# https://github.com/GeminiLight/MindOS 项目说明书 生成时间：2026-06-24 19:09:16 UTC ## 目录 - [系统总览与 Monorepo 架构](#page-1) - [核心 CLI 包 mindos 与 Onboarding 流程](#page-2) - [Agent 协议集成: MCP、ACP、A2A 与 Runtime](#page-3) - [知识库、检索、前端渲染与多端发布](#page-4) ## 系统总览与 Monorepo 架构 ### 相关页面 相关主题：[核心 CLI 包 mindos 与 Onboarding 流程](#page-2), [Agent 协议集成: MCP、ACP、A2A 与 Runtime](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) - [package.json](https://github.com/GeminiLight/MindOS/blob/main/package.json) - [pnpm-workspace.yaml](https://github.com/GeminiLight/MindOS/blob/main/pnpm-workspace.yaml) - [turbo.json](https://github.com/GeminiLight/MindOS/blob/main/turbo.json) - [templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md) - [packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md) - [packages/browser-extension/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/README.md) - [wiki/plugins/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/plugins/README.md)
# 系统总览与 Monorepo 架构 MindOS 是一个面向「人 + Agent 协同进化」的个人操作系统，整体采用 **pnpm + Turborepo** 的多包 Monorepo 结构组织代码，运行时通过 npm 包 `@geminilight/mindos` 进行统一发布与 CLI 暴露。仓库根目录仅作为「私有 monorepo orchestrator」，真正的产品代码全部下沉到 `packages/` 子目录下。 ## 一、仓库根目录布局 仓库遵循 OpenCode 风格的工作空间扁平化设计： ```text / ├── packages/ # 所有源码工作区（web / desktop / mobile / mindos / retrieval） ├── skills/ # MindOS Skills（mindos、mindos-zh） ├── templates/ # 知识库预设模板（en / zh / empty） ├── scripts/ # 安装与初始化脚本 ├── README.md # 项目主文档 └── package.json # 工作空间配置与脚本入口 ``` 自 v1 起，顶层 `app/`、`apps/`、`mcp/`、`desktop/`、`mobile/`、`browser-extension/`、`desktop-tauri/` 以及根级 `bin/` 已不再是源码根目录，它们要么下沉到 `packages/`，要么从发布包中剔除，从而让根目录保持「薄编排器」的角色。资料来源：[README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md)。 ## 二、核心包结构与职责 `packages/` 是 MindOS 的真正产品核心，各子包按照「运行时形态」划分边界： | 包名 | 形态 | 主要职责 | |------|------|----------| | `packages/mindos` | 已发布 npm 包 `@geminilight/mindos` | 运行时外观（runtime facade）、CLI 内核、协议层（ACP/MCP）、基础与知识层 | | `packages/web` | Web 源码树 | 唯一 Web 源，不打入 npm tarball，独立构建为 `_standalone/` | | `packages/desktop` | 桌面端 | macOS / Windows / Linux 原生应用，含系统托盘与自动启动 | | `packages/mobile` | 移动端 | 响应式前端入口，适配顶栏与抽屉式侧栏 | | `packages/retrieval/*` | 可选检索栈 | search、vector、indexer、API；按需启用 | CLI 入口约定为 `packages/mindos/bin/cli.js`，本地仓库与 npm 安装用户都通过这一统一入口触发 `mindos onboard`、`mindos config` 等命令。资料来源：[README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md)、[packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md)。 ## 三、用户数据与运行时分层 源代码仓库与用户私有数据严格隔离： ```mermaid graph TD A["packages/mindos
@geminilight/mindos"] --> B["CLI 入口
bin/cli.js"] A --> C["协议层
ACP / MCP"] A --> D["知识层 + 检索适配器
packages/retrieval"] B --> E["~/.mindos/
config.json"] B --> F["~/.mindos/mind/
私有知识库"] A -.打包.-> G["_standalone/
Web 运行时"] H["packages/web"] -.构建.-> G I["packages/desktop"] -.内置.-> A I -.内置.-> G ``` 用户数据落在仓库之外： - `~/.mindos/config.json`：集中保存 AI 密钥、端口、Auth Token、同步设置。 - `~/.mindos/sync-state.json`：记录上次同步时间与冲突状态。 - `~/.mindos/mind/`：默认知识库根目录，`mindos onboard` 时可自定义。 这种「代码即包、配置即文件」的拆分保证了发布包体积可控，也避免个人笔记误入版本控制。资料来源：[README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md)、[templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md)。 ## 四、生态插件与模板 - **Skills**：`skills/mindos` 与 `skills/mindos-zh` 是面向 Agent 的工作流指南，告诉 Agent 如何在 MindOS 内执行典型 SOP。 - **Templates**：`templates/en/`、`templates/zh/`、`templates/empty/` 为知识库提供开箱即用的目录骨架（👤 Profile / 📝 Notes / 🔄 Workflows / 🚀 Projects / 📚 Resources 等），由 `mindos onboard` 自动复制到用户目录。 - **Plugins**：内置渲染器涵盖 TODO Board、CSV Views、Wiki Graph、Timeline、Workflow Editor、Agent Inspector 等；计划中的转换器插件（MarkItDown、Readwise、Notion、Obsidian、Browser Clipper、Voice Memo）位于 `wiki/plugins/README.md` 中维护。 资料来源：[wiki/plugins/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/plugins/README.md)、[templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md)。 ## 五、社区高频问题与架构影响 - **全局安装路径与脚本缺失**：[#35](https://github.com/GeminiLight/MindOS/issues/35) 与 [#34](https://github.com/GeminiLight/MindOS/issues/34) 暴露了「发布包不再携带 `scripts/setup.js`」的回归风险——CLI 必须通过 `packages/mindos/bin/cli.js` 内的等价路径完成 onboard，避免依赖仓库内脚本。 - **核心更新器只下载源码 zip**：[#36](https://github.com/GeminiLight/MindOS/issues/36) 反映 Desktop updater 抓取的版本缺少 `server.js` 与 `mcp/dist`，提示发布产物必须内嵌运行时 artifact，而非源码包。 - **协议层升级回归**：[#40](https://github.com/GeminiLight/MindOS/issues/40) 的 `o.newSession is not a function` 与 [#22](https://github.com/GeminiLight/MindOS/issues/22) 中 `clean-env.js` 的块注释语法错误，共同说明协议运行时（ACP/MCP）内化进 `packages/mindos/src/protocols/*` 后，必须保证 `dist/protocols/*` 与运行时代码同步构建。 - **浏览器扩展加载失败**：[#41](https://github.com/GeminiLight/MindOS/issues/41) 提示 manifest 引用的资源必须在仓库中真实存在，建议 CI 增加静态校验。 - **官网域名错配**：[#43](https://github.com/GeminiLight/MindOS/issues/43) 表明 `Help → MindOS 文档` 菜单仍指向被 GoDaddy 托管的 `mindos.app`，应统一为 `https://mindos.you/`。 ## See Also - [Web 运行时与编辑体验](packages-web-runtime.md) - [CLI 与 `mindos onboard` 命令](cli-onboard.md) - [协议层：MCP 与 ACP](protocols-mcp-acp.md) - [知识库模板与目录约定](kb-templates.md) - [桌面端核心更新器](desktop-core-updater.md) --- ## 核心 CLI 包 mindos 与 Onboarding 流程 ### 相关页面 相关主题：[系统总览与 Monorepo 架构](#page-1), [Agent 协议集成: MCP、ACP、A2A 与 Runtime](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [packages/mindos/bin/cli.js](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/bin/cli.js) - [packages/mindos/package.json](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/package.json) - [packages/mindos/bin/commands/onboard.js](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/bin/commands/onboard.js) - [packages/mindos/bin/commands/start.js](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/bin/commands/start.js) - [packages/mindos/bin/commands/stop.js](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/bin/commands/stop.js) - [packages/mindos/bin/commands/mcp-cmd.js](https://github.com/GeminiLight/MindOS/blob/main/packages/mindos/bin/commands/mcp-cmd.js) - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) - [templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md)
# 核心 CLI 包 mindos 与 Onboarding 流程 ## 1. 概述与定位 `mindos` 是 MindOS 仓库在 v1 重构后引入的"OpenCode 风格"主发布包，包名为 `@geminilight/mindos`。它是 CLI 内核边界和运行时门面（runtime facade），将原本散落在仓库根目录的 `app/`、`mcp/`、`bin/` 等源码根统一收纳到 `packages/mindos/` 之下，由 Web、CLI、Desktop、Mobile 适配层围绕它构建。仓库 README 明确指出：`packages/mindos` 的 repo 内 CLI 入口为 `packages/mindos/bin/cli.js`，npm 用户安装后获得的包级入口同样是 `bin/cli.js`，而预构建的本地 Web 运行时被打包为 `_standalone/` 随 npm tarball 一起发布。资料来源：[README.md:9-12]() CLI 的核心职责包括：驱动首次安装的 Onboarding 向导、启动/停止本地运行时进程、管理 MCP 服务、以及暴露后续的 `config`、`gateway`、`clean-env` 等子命令。所有用户态配置（AI Key、端口、Auth Token、同步设置）均落在用户目录下的 `~/.mindos/config.json`，知识库默认位于 `~/.mindos/mind/`，这两个路径都属于仓仓库之外的私有数据，不会进入版本管理。资料来源：[README.md:5-13]() ## 2. 包结构与发布边界 `packages/mindos/` 的目录遵循"运行时门面 + 协议 + 基础设施"的分层思路： | 子目录 | 角色 | 说明 | |---|---|---| | `bin/cli.js` | CLI 入口 | 命令解析与子命令分发 | | `bin/commands/` | 子命令实现 | `onboard`、`start`、`stop`、`mcp-cmd` 等 | | `src/protocols/*` | 协议运行时 | ACP、MCP 源码内化进包内 | | `dist/protocols/*` | 打包产物 | 随 npm 发布，无需外部嵌套包 | | `_standalone/` | 预构建 Web | npm 用户开箱即用的本地运行时 | 仓库 README 强调"protocol runtimes internalized"——ACP 与 MCP 的源现在都在 `packages/mindos/src/protocols/*` 下，发布包自带 `dist/protocols/*` bundle，取代了原先相互嵌套的协议子包。资料来源：[README.md:1-4]()。同时 `packages/web` 是仓库内唯一的 Web 源码树，但它不会进入 npm tarball，意味着通过 `npm install -g @geminilight/mindos` 获取的用户不会拿到 Web 源码，只会拿到 `_standalone/` 中的预构建产物。 ## 3. Onboarding 流程 Onboarding 是用户首次接触 MindOS 的必经路径，对应 CLI 命令 `mindos onboard`。其工作流可概括为四步： ```mermaid flowchart LR A[用户执行 mindos onboard] --> B{检测 ~/.mindos/config.json} B -- 不存在或 setupPending=true --> C[交互式设置向导] C --> D[写入 config.json + 生成 auth token] D --> E[从 templates/ 拷贝预设到 mind 根目录] E --> F[按需构建 MCP bundle] F --> G[标记 setupPending=false] B -- 已配置 --> G ``` 设计细节层面，`templates/README.md` 给出了三种初始化方式：(a) 推荐使用 `mindos onboard` 自动跑设置向导；(b) 手动 `cp -r templates/en ~/MindOS` 然后在 `config.json` 设置 `mindRoot`；(c) 直接复制 `templates/zh` 中文预设。预设中包含了 `👤 Profile`、`📝 Notes`、`🔄 Workflows`、`🚀 Projects`、`📚 Resources` 等标准目录，并附带 `README.md` 和 `INSTRUCTION.md`，Agent 可据此预测文件位置。资料来源：[templates/README.md:7-22]()、[`templates/en/🚀 Projects/README.md:1-15`]() 设置向导写入的 `config.json` 还会包含 `setupPending` 标志位。若 CLI 检测到该标志位仍为 `true`，再次启动时会显式提示 "⚠ Setup was not completed. Run mindos onboard to finish..."，并提供 `mindos config set setupPending false` 一键跳过的逃生口。资料来源：[README.md:11-13]() ## 4. 已知失败模式与社区反馈 Onboarding 流程在社区中暴露出过若干真实失败模式，运维时建议留意： 1. **全局安装后 `scripts/setup.js` 缺失**（issue #35）。通过 npm 全局安装后执行 `mindos onboard` 会抛出 `MODULE_NOT_FOUND`，原因是 CLI 试图加载仓库根的 `scripts/setup.js`，而该文件未被打入 tarball。资料来源：[issue #35](https://github.com/GeminiLight/MindOS/issues/35) 2. **Onboarding 过程中 MCP 构建报错**（issue #34）。日志显示向导会进入 "Installing MCP build dependencies..." 并执行 `Rebuilding MCP bundle`，若该步骤失败，向导会回退到 `setupPending=true` 状态要求重试。资料来源：[issue #34](https://github.com/GeminiLight/MindOS/issues/34) 3. **`bin/lib/clean-env.js` 块注释中含 `*/` 导致 SyntaxError**（issue #22）。在 macOS 通过 npm 全局安装后触发，CLI 启动即崩溃，根因是 JavaScript 块注释内嵌套了闭合标记。 4. **升级后运行时接口不匹配**（issue #40）。core 升至 1.0.15、desktop 升至 v0.3.20 后出现 `o.newSession is not a function`，表明 CLI 与 core runtime 的协议接口版本需要严格对齐。 5. **Core Updater 下载到源码 zip 而非运行时产物**（issue #36）。Desktop 触发 core 更新时下载的是源码包，缺少 `server.js` 与 `mcp/dist`，提示 `Downloaded runtime is incomplete`。 对于上述问题，社区默认的恢复路径是先 `mindos config set setupPending false` 跳过未完成的引导，再按需重新执行 `mindos onboard`，必要时手动校验 `templates/` 模板与 `~/.mindos/config.json` 中的 `mindRoot` 路径一致性。资料来源：[README.md:11-13]()、[`templates/README.md:9-16`]() ## 5. 与上层产品的协作边界 `mindos` 包仅负责"内核 + 协议 + CLI"这一层。Web 端由 `packages/web` 在本地开发时提供，发布版则使用预构建的 `_standalone/`；桌面端通过 Desktop 应用调用 CLI 的 `start`/`stop` 子命令来拉起或终止后台运行时；Mobile 端同样以 CLI 作为事实后端。设计这种"内核-适配层"分离后，任何核心能力（如 MCP 协议、配置结构、模板目录）都只需在 `packages/mindos/` 内演进，Web/Desktop/Mobile 仅做呈现层适配。资料来源：[README.md:1-13]() ## See Also - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) - [templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md) - [packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md) - [packages/browser-extension/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/README.md) - [wiki/refs/coding-agent-harness-research/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/refs/coding-agent-harness-research/README.md) --- ## Agent 协议集成: MCP、ACP、A2A 与 Runtime ### 相关页面 相关主题：[系统总览与 Monorepo 架构](#page-1), [核心 CLI 包 mindos 与 Onboarding 流程](#page-2), [知识库、检索、前端渲染与多端发布](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) - [wiki/refs/coding-agent-harness-research/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/refs/coding-agent-harness-research/README.md) - [packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md) - [packages/browser-extension/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/README.md) - [packages/browser-extension/src/lib/markdown.ts](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/src/lib/markdown.ts) - [templates/en/📝 Notes/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/en/📝 Notes/README.md) - [templates/en/🚀 Projects/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/en/🚀 Projects/README.md) - [templates/en/🔄 Workflows/Information/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/en/🔄 Workflows/Information/README.md)
# Agent 协议集成: MCP、ACP、A2A 与 Runtime ## 一、概述与设计目标 MindOS 的 Agent 协议集成层是连接外部 Agent runtime（Codex、Claude Code、ClineCore、Hermes、Cursor 等）与本地知识库的"桥接面"。它在架构上明确区分三层：Assistant / subagent profile / mode / rule 是**配置层**；Agent runtime / harness 是**执行层**；Run / session / task 是**实例层**。资料来源：[wiki/refs/coding-agent-harness-research/README.md:5-30]() 整个协议栈由三类核心协议构成： - **MCP（Model Context Protocol）**：用于把 MindOS 知识库以工具与资源形式暴露给 Agent，让任何兼容 MCP 的 Agent（Claude Code、Cursor、Gemini CLI 等）"零配置"接入。 - **ACP（Agent Communication Protocol）**：智能体通信协议，负责本地与远程 Agent runtime 的发现、注册与会话管理。 - **A2A（Agent-to-Agent）**：在多 Agent 场景下进行任务委派、共享上下文与流程编排。 当前已上线（Phase 1）的能力包括 MCP Server 双传输（stdio + HTTP）、ACP Agent Card 发现 + JSON-RPC 消息传递；Phase 2 将带来更深度的多 Agent 协作与工作流串联。资料来源：[README.md:14-22]() ## 二、MCP Server 与知识库暴露 MCP 层是 Agent 集成中最成熟的部分。它通过 Bearer Token 鉴权、路径沙箱、`INSTRUCTION.md` 写保护与原子写入等机制保障知识库安全。资料来源：[README.md:36-44]() ```mermaid graph LR U[用户知识库
~/.mindos/mind] --> S[MCP Server
stdio + HTTP] S -- "tools/resources" --> A1[Claude Code] S -- "tools/resources" --> A2[Cursor] S -- "tools/resources" --> A3[Gemini CLI] S -- "tools/resources" --> A4[自定义 Agent] ``` **关键配置项**（节选自 `packages/web`）： | 变量 | 默认值 | 说明 | |---|---|---| | `MIND_ROOT` | `./my-mind` | 知识库根目录 | | `MINDOS_WEB_PORT` | `3456` | Web / MCP 端口 | | `AI_PROVIDER` | `anthropic` | `anthropic` 或 `openai` | | `ANTHROPIC_API_KEY` | — | 使用 Anthropic 时必填 | | `ANTHROPIC_MODEL` | `claude-sonnet-4-*` | 默认模型 | 资料来源：[packages/web/README.md:22-35]() 浏览器扩展通过同一 Bearer Token 与本地 MCP 端点（默认 `http://localhost:3456`）对接，将任意网页或 AI 对话一键剪藏为 Markdown 并写入 Inbox。资料来源：[packages/browser-extension/README.md:16-30]() ## 三、ACP / A2A 与 Agent Runtime ### 3.1 协议定位 MindOS 把 Coding Agent 视为**独立的 runtime 实体**，而非普通的模型 Provider。每个 runtime 自身拥有 auth、model、session、tools、permissions 与 event stream。MindOS 在其中的角色是 **UI / context / permission bridge**。资料来源：[wiki/refs/coding-agent-harness-research/README.md:1-10]() ### 3.2 事件流与权限桥接 行业共识是事件流必须结构化，单存最终文本无法表达真实 coding work。典型事件应包含：计划 / reasoning 摘要、shell command start/output/end、file edit / diff、MCP tool call、permission request、clarification、error / retry / rate limit、checkpoint / rollback、PR / handoff。MindOS 的 Agent Inspector 即把上述操作日志渲染为可过滤的时间线，便于逐条审计。资料来源：[README.md:36-44]() [wiki/refs/coding-agent-harness-research/README.md:30-50]() 权限模型上，MindOS 采用"ask/allow/deny、auto-approve、sandbox policy"组合，应**桥接而非绕过**原生 runtime 的权限系统。 ### 3.3 Runtime 适配器与 Profile 分离 Assistant 存放于 `.mindos/assistants//` 这种本地 profile；Codex、Claude、Cline、Hermes 等以 runtime adapter 形式接入；用户一次请求会派生出 run / session / task 实例。这种"profile ↔ runtime ↔ instance"三层切分是当前架构的关键判断之一。资料来源：[wiki/refs/coding-agent-harness-research/README.md:15-25]() ## 四、模板、SOP 与 Agent-Ready 文档 MindOS 通过结构化模板把日常笔记转化为 Agent 可直接执行的高质量指令，无需格式转换即可分派。模板覆盖以下空间： - **👤 Profile**：个人信息与画像 - **📝 Notes**：含 `Inbox/`、`Drafts/`、`Waiting/`、`Meetings/`、`Ideas/` 子目录，用于快速捕获 - **🔄 Workflows**：以 `Information/` 等 SOP 文件夹沉淀检索、提取、同步流程 - **🚀 Projects**：下含 `Products/`、`Research/`、`Archived/`，对应项目级文档 - **📚 Resources**：参考资料与素材 资料来源：[templates/en/📝 Notes/README.md:3-12]() [templates/en/🚀 Projects/README.md:3-10]() [templates/en/🔄 Workflows/Information/README.md:3-9]() ## 五、已知限制与社区反馈 下列问题在社区中被频繁提及，建议在生产化部署前评估： | 问题 | 影响 | 进展 | |---|---|---| | **#33 本地 CLI acp 无法使用** | Codex / Claude / Kimi CLI 接入失败 | 已开放（open） | | **#45 子 Agent 不可用** | 批量大文件处理超时、无法脱离人工 | 当前 runtime 没有子 Agent，所有工作只能在主线程完成 | | **#46 上下文溢出** | `Stream Error: Cannot continue from message role: assistant` | 上下文管理尚不透明，需新开会话或加强压缩 | | **#47 模型全局切换** | 多会话无法各自选择模型 | 官方称"已修复"，待版本验证 | | **#44 批量上传上限** | 24 个以上提示"保存文件失败" | 通过设置可调大默认 size | | **#30 PDF / DOCX 导入** | 桌面版仅支持 Markdown | 已宣称在最新版本支持 | | **#40 升级后断连** | `o.newSession is not a function` | 已修复，需更新 runtime | | **#22 clean-env.js 语法错误** | 全局安装后 CLI SyntaxError | 块注释内 `*/` 导致 | 资料来源：[README.md:18-22]() [wiki/refs/coding-agent-harness-research/README.md:50-70]() ## 六、与外部生态的边界 MindOS 在 v1 中对仓库目录进行了重构：`app/`、`apps/`、`mcp/`、`desktop/`、`mobile/`、`browser-extension/`、`desktop-tauri/` 与根目录 `bin/` 不再是源码根；`packages/mindos` 成为 `@geminilight/mindos` 风格的发布包，其 CLI 入口为 `packages/mindos/bin/cli.js`，预构建 Web runtime 发布为 `_standalone/`；`packages/web` 是唯一的 Web 源码树，不会进入 npm tarball。资料来源：[README.md:30-50]() ## See Also - [wiki/refs/coding-agent-harness-research](./coding-agent-harness-research.md) - [README.md · 顶层产品介绍](../README.md) - [packages/web/README.md · Web 运行时](../packages/web/README.md) - [packages/browser-extension/README.md · 浏览器剪藏扩展](../packages/browser-extension/README.md) --- ## 知识库、检索、前端渲染与多端发布 ### 相关页面 相关主题：[系统总览与 Monorepo 架构](#page-1), [Agent 协议集成: MCP、ACP、A2A 与 Runtime](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) - [packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md) - [packages/browser-extension/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/README.md) - [packages/browser-extension/src/lib/markdown.ts](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/src/lib/markdown.ts) - [templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md) - [templates/en/📝 Notes/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/en/📝 Notes/README.md) - [templates/en/🚀 Projects/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/en/🚀 Projects/README.md) - [templates/mind-spaces/product/en/Product/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/mind-spaces/product/en/Product/README.md) - [wiki/plugins/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/plugins/README.md) - [skills/mindos-zh/references/README.md](https://github.com/GeminiLight/MindOS/blob/main/skills/mindos-zh/references/README.md)
# 知识库、检索、前端渲染与多端发布 本页聚焦 MindOS 在「**知识管理 → 检索召回 → 前端渲染 → 多端发布**」这一整条用户可见链路上的实现方式与协作关系，涵盖知识库目录约定、检索栈、前端 Web 视图与浏览器扩展、Web Clipper / Desktop 等多端入口。 ## 一、知识库结构与模板 MindOS 的知识库是一组本地 Markdown 文件，目录结构由 `templates/` 下的预设模板在 `mindos onboard` 时自动复制生成，模板分为英文 (`templates/en/`) 与中文 (`templates/zh/`) 两套。 ### 1.1 一级空间划分 英文预设包含四个顶层空间： - **👤 Profile**：个人画像与基础信息。 - **📝 Notes**：快速捕获区，内含 `Inbox / Drafts / Waiting / Meetings / Ideas` 五个子目录 资料来源：[templates/en/📝 Notes/README.md:5-13]()。 - **🔄 Workflows**：SOP 流程库，例如 `Information/` 收集流程目录 资料来源：[templates/en/🔄 Workflows/Information/README.md:3-7]()。 - **🚀 Projects**：项目工作区，下分 `Products / Research / Archived` 资料来源：[templates/en/🚀 Projects/README.md:3-12]()。 中文预设使用语义同构的 `👤 画像 / 📝 笔记 / 🔄 流程 / 🚀 项目` 命名，例如「信息」目录明确说明存放检索、摘录、归档、同步 SOP 资料来源：[templates/zh/🔄 流程/信息/README.md:9-12]()。 ### 1.2 Mind Spaces 轻量模板 除完整预设外，`templates/mind-spaces/` 提供按「场景」拆分的小模板，如 `Creation / Product / Social`，每个场景下的 README 都给出"推荐的初始笔记列表"，例如 Product 模板建议先建立产品原则、用户细分、Feature Spec 与发布记录 资料来源：[templates/mind-spaces/product/en/Product/README.md:7-12]()。这一层用于让用户从更细粒度的 Space 起步，再按需扩展到完整预设。 ### 1.3 模板拷贝与初始化 `mindos onboard` 是模板初始化的官方入口；如果想手动覆盖，也可以直接复制 `templates/en` 到 `~/MindOS` 并在 `~/.mindos/config.json` 中配置 `mindRoot` 资料来源：[templates/README.md:11-22]()。 ## 二、检索栈（Retrieval Stack） 可选检索栈位于 `packages/retrieval/`，按 README 中的仓库树说明包含 `search / vector / indexer / api` 四个子模块 资料来源：[README.md:144-152]()。该栈是「Deep RAG」路线的前置，README 中明确将其列为待深化能力： > Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses 资料来源：[README.md:48-50]()。 社区反馈显示，对 300+ Markdown 文档的批量上传，MindOS 当前依赖磁盘存储与原子写入，开发者正在调整默认 `size` 并提供设置项以避免"保存文件失败"误报；同时 #46 指出上下文管理不透明、批量大文件处理易触发 `Stream Error`，验证了检索栈与上下文压缩逻辑尚未完全独立 资料来源：[issues/44](https://github.com/GeminiLight/MindOS/issues/44)、[issues/46](https://github.com/GeminiLight/MindOS/issues/46)。 ## 三、前端 Web 渲染 唯一的前端源码树是 `packages/web/`，README 列举的能力覆盖编辑器、搜索、AI 助手与可视化： - `⌘S` 保存 / `Esc` 取消、`⌘K` 全局搜索（基于 Fuse.js 模糊匹配 + 摘要预览）、悬浮 TOC、AI Agent `⌘/` 入口、`@` 文件引用、本地 PDF 上传 资料来源：[packages/web/README.md:25-35]()。 - 知识图谱（Knowledge Graph）动态解析文件间引用并可视化；Backlinks 视图列出引用当前页的全部文件 资料来源：[README.md:62-65]()。 - 插件渲染器系统以 `BACKLINKS.md` 等命名约定分发，例如 `*TODO*.md` 走 TODO 板，`*BACKLINKS*.md` 走引用分析 资料来源：[wiki/plugins/README.md:9-17]()。 - 环境变量 `MIND_ROOT / MINDOS_WEB_PORT / AI_PROVIDER / ANTHROPIC_API_KEY / ANTHROPIC_MODEL` 决定了知识根目录与 LLM 后端 资料来源：[packages/web/README.md:45-53]()。 社区反馈中的「流式输出无法停在某一行」（#32）已在新版本修复，「停止对话后旧 prompt 仍被读取」（#28）也在下一版撤回 prompt 至输入框，说明前端交互层在持续打磨 资料来源：[issues/32](https://github.com/GeminiLight/MindOS/issues/32)、[issues/28](https://github.com/GeminiLight/MindOS/issues/28)。 ## 四、多端发布：Web Clipper 与 Desktop ### 4.1 Web Clipper（浏览器扩展） `packages/browser-extension/` 提供开箱即用的「无构建加载」扩展： 1. 打开 `chrome://extensions`，开启开发者模式，选择 `Load unpacked` → `extension/` 目录 资料来源：[packages/browser-extension/README.md:18-24]()。 2. 首次使用时填入 MindOS URL（默认 `http://localhost:3456`）与 MCP 设置中的 Auth Token 完成 Connect 资料来源：[packages/browser-extension/README.md:30-36]()。 3. 点击图标、右键 `Save to MindOS`，或使用 `Ctrl/Cmd + Shift + M` 快捷键剪藏网页/AI 对话 资料来源：[packages/browser-extension/README.md:39-44]()。 剪藏链路中 Markdown 转换由 `src/lib/markdown.ts` 负责：`sanitizeFileName()` 清洗非法文件系统字符并限制长度 120，frontmatter 生成器对 YAML 保留字与特殊起始字符进行加引号处理，确保 frontmatter 在不同解析器下都能正确还原 资料来源：[packages/browser-extension/src/lib/markdown.ts:5-13]() 与 [packages/browser-extension/src/lib/markdown.ts:16-38]()。 社区反馈指出 `extension/icons/` 只提供 `.svg` 但 `manifest.json` 引用 `.png`，导致 #41 加载失败，需手动将 manifest 中的 `.png` 改为 `.svg` 资料来源：[issues/41](https://github.com/GeminiLight/MindOS/issues/41)。 ### 4.2 Desktop 与 Runtime README 将 Desktop 描述为提供「系统托盘、开机自启与本地进程管理」的原生应用 资料来源：[README.md:68-69]()。v1 重构后，`packages/mindos` 成为对外发布的 product package，Web 前端以 `_standalone/` 预构建形式随 npm 包分发，`packages/web` 不再进入 npm tarball；运行时更新通过 Desktop 内置的 Core Updater 拉取 资料来源：[README.md:155-164]()。 社区反馈中，#36 报告 Core Updater 下载 v1.0.2 时缺少 `server.js` 或 `mcp/dist` 导致 "Downloaded runtime is incomplete"，#35 / #34 反映全局安装后 `mindos onboard` 因 `scripts/setup.js` 缺失而 MODULE_NOT_FOUND，这些都集中在 CLI / Runtime / Updater 边界，是多端发布链路中需要持续加固的位置 资料来源：[issues/36](https://github.com/GeminiLight/MindOS/issues/36)、[issues/35](https://github.com/GeminiLight/MindOS/issues/35)、[issues/34](https://github.com/GeminiLight/MindOS/issues/34)。 ### 4.3 端到端协作示意 ```mermaid graph LR User["👤 用户"] Clip["🌐 Web Clipper
(浏览器扩展)"] Web["🖥 packages/web
(本地 Web 前端)"] Mind["📚 ~/.mindos/mind
(Markdown 知识库)"] Ret["🔍 packages/retrieval
(可选检索栈)"] Agent["🤖 Agent / MCP"] Desk["💻 Desktop
(system tray / updater)"] User --> Clip Clip -- "save MD" --> Mind User --> Web Web <-- "read/write MD" --> Mind Mind --> Ret Ret --> Agent Desk --> Web Desk --> Agent ``` ## 五、面向 Agent 的可执行知识 知识库不仅是给人读的，也是给 Agent 执行的入口。`skills/mindos-zh/references/` 通过 SKILL.md + 补充长文的方式，把"写入 / SOP / 结构变更"等操作流程固化为可被模型加载的参考，包括 `write-supplement.md / post-task-hooks.md / sop-template.md / preference-capture.md` 四份文档，按需加载 资料来源：[skills/mindos-zh/references/README.md:5-12]()。 ## See Also - [README.md](https://github.com/GeminiLight/MindOS/blob/main/README.md) — 项目总览与 Roadmap - [packages/web/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/web/README.md) — Web 前端详细能力 - [packages/browser-extension/README.md](https://github.com/GeminiLight/MindOS/blob/main/packages/browser-extension/README.md) — Web Clipper 安装与使用 - [templates/README.md](https://github.com/GeminiLight/MindOS/blob/main/templates/README.md) — 预设模板初始化 - [wiki/plugins/README.md](https://github.com/GeminiLight/MindOS/blob/main/wiki/plugins/README.md) — 转换器与渲染器插件矩阵 --- --- ## Doramagic 踩坑日志 项目：GeminiLight/MindOS 摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：超多文件处理时频繁提示：Stream Error: Cannot continue from message role: assistant。 ## 1. 安全/权限坑 · 来源证据：超多文件处理时频繁提示：Stream Error: Cannot continue from message role: assistant - 严重度：high - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：超多文件处理时频繁提示：Stream Error: Cannot continue from message role: assistant - 对用户的影响：可能影响授权、密钥配置或安全边界。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/46 | 来源类型 github_issue 暴露的待验证使用条件。 ## 2. 安装坑 · 来源证据：Core updater downloads v1.0.2 source zip without runtime artifacts - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Core updater downloads v1.0.2 source zip without runtime artifacts - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/36 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。 ## 3. 安装坑 · 来源证据：`mindos onboard` fails with MODULE_NOT_FOUND: missing scripts/setup.js - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`mindos onboard` fails with MODULE_NOT_FOUND: missing scripts/setup.js - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/35 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 4. 安装坑 · 来源证据：mindos onboard后报错 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：mindos onboard后报错 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/34 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 ## 5. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/GeminiLight/MindOS | host_targets=mcp_host, claude_code, claude, cursor ## 6. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/GeminiLight/MindOS | README/documentation is current enough for a first validation pass. ## 7. 运行坑 · 来源证据：向量搜索功能无法保存 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：向量搜索功能无法保存 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/31 | 来源类型 github_issue 暴露的待验证使用条件。 ## 8. 运行坑 · 来源证据：期待能开启子agent。大量文件时，处理起来太慢了，并且一直超时，不能脱离人自动操作。 - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：期待能开启子agent。大量文件时，处理起来太慢了，并且一直超时，不能脱离人自动操作。 - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/GeminiLight/MindOS/issues/45 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/GeminiLight/MindOS | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/GeminiLight/MindOS | no_demo; severity=medium ## 11. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/GeminiLight/MindOS | no_demo; severity=medium ## 12. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/GeminiLight/MindOS | issue_or_pr_quality=unknown ## 13. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/GeminiLight/MindOS | release_recency=unknown