Development and Architecture

Development and Architecture / 开发与架构

← Wiki home / 手册首页 · English · 中文 · Repository / 仓库

Audience / 适用对象： contributors who need repository orientation, local commands, packaging entry points, or the boundaries that protect source data and the interactive UI.
需要了解仓库结构、本地命令、打包入口，以及来源数据和交互式界面保护边界的贡献者。

English

Repository orientation

• omniclip_rag/ — application code, services, storage, retrieval, Runtime management, and UI
• tests/ — unit and integration-focused tests
• scripts/ — local launch, build, and maintenance entry points
• runtime_support/ — manifest and installer-side Runtime support
• pyinstaller_hooks/ — packaged-build hooks
• resources/ and icon/ — application assets
• examples/mcp/ — client configuration examples
• docs/ — GitHub Pages website
• releases/ — versioned release notes and release-facing metadata

Common commands

# Desktop GUI
.\scripts\run_gui.ps1

# CLI
.\scripts\run.ps1 status
.\scripts\run.ps1 query "your question"

# Tests
pytest -q

# Build packaged Windows artifacts
.\scripts\build_exe.ps1

# MCP self-check
python launcher_mcp.py --mcp-selfcheck

Architectural boundaries

• Source notes and documents are external read-only inputs during normal indexing.
• App-owned state belongs under the active data root, not inside source directories or the EXE tree.
• Markdown, PDF, and Tika use separate index/state boundaries.
• The desktop app, CLI, and MCP shell share retrieval services rather than maintaining separate backends.
• Heavy native ML work is isolated from the interactive Qt process where failure or teardown could otherwise terminate the UI.
• MCP request handling reserves stdout for protocol traffic.

References

• Architecture
• Runtime setup
• MCP setup
• Storage precheck
• Third-party notices
• Changelog

Internal implementation plans remain in the repository for engineering history, but they are not the primary user manual and may describe superseded intermediate designs.

中文

仓库结构

• omniclip_rag/：应用代码、服务、存储、检索、Runtime 管理和 UI
• tests/：单元测试与集成测试
• scripts/：本地启动、构建和维护入口
• runtime_support/：Runtime 清单和安装支持
• pyinstaller_hooks/：发布包构建钩子
• resources/ 与 icon/：应用资源
• examples/mcp/：客户端配置示例
• docs/：GitHub Pages 网站
• releases/：版本化发布说明和发布元数据

常用命令

# 桌面 GUI
.\scripts\run_gui.ps1

# CLI
.\scripts\run.ps1 status
.\scripts\run.ps1 query "你的问题"

# 测试
pytest -q

# 构建 Windows 发布物
.\scripts\build_exe.ps1

# MCP 自检
python launcher_mcp.py --mcp-selfcheck

架构边界

• 正常建库时，原始笔记和文档是外部只读输入。
• 软件拥有的状态应位于当前数据目录，不应写入来源目录或 EXE 目录。
• Markdown、PDF 和 Tika 保持独立索引与状态边界。
• 桌面版、CLI 和 MCP 复用检索服务，不维护互相漂移的独立后端。
• 可能因原生 ML 故障或退出清理拖垮界面的重型工作，应尽量与交互式 Qt 进程隔离。
• MCP 请求处理必须把 stdout 保留给协议流量。

参考文档

• 架构说明
• Runtime 说明
• MCP 说明
• 存储预检
• 第三方许可与声明
• 更新日志

仓库中的内部实施计划用于保留工程历史，不再作为主要用户手册；部分计划可能描述已经被后续版本替代的中间设计。

---

User manual / 用户手册： ← Wiki home / 返回手册首页