MindOS 项目说明书 - Doramagic.ai

Doramagic 项目包 · 项目说明书

MindOS 项目

MindOS 是一个 Human-AI 协同思维系统，由人类负责思考、agent 负责执行；它可以在全局范围内把你的思维同步给所有 agent，过程透明、可控，并能与你共同进化、共生发展。

系统总览与 Monorepo 架构

MindOS 是一个面向「人 + Agent 协同进化」的个人操作系统，整体采用 pnpm + Turborepo 的多包 Monorepo 结构组织代码，运行时通过 npm 包 @geminilight/mindos 进行统一发布与 CLI 暴露。仓库根目录仅作为「私有 monorepo orchestrator」，真正的产品代码全部下沉到 packages/ 子目录下。

章节 相关页面

继续阅读本节完整说明和来源证据。

一、仓库根目录布局

仓库遵循 OpenCode 风格的工作空间扁平化设计：

/
├── 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。

二、核心包结构与职责

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、packages/web/README.md。

三、用户数据与运行时分层

源代码仓库与用户私有数据严格隔离：

graph TD
    A["packages/mindos<br/>@geminilight/mindos"] --> B["CLI 入口<br/>bin/cli.js"]
    A --> C["协议层<br/>ACP / MCP"]
    A --> D["知识层 + 检索适配器<br/>packages/retrieval"]
    B --> E["~/.mindos/<br/>config.json"]
    B --> F["~/.mindos/mind/<br/>私有知识库"]
    A -.打包.-> G["_standalone/<br/>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、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、templates/README.md。

五、社区高频问题与架构影响

全局安装路径与脚本缺失：#35 与 #34 暴露了「发布包不再携带 scripts/setup.js」的回归风险——CLI 必须通过 packages/mindos/bin/cli.js 内的等价路径完成 onboard，避免依赖仓库内脚本。
核心更新器只下载源码 zip：#36 反映 Desktop updater 抓取的版本缺少 server.js 与 mcp/dist，提示发布产物必须内嵌运行时 artifact，而非源码包。
协议层升级回归：#40 的 o.newSession is not a function 与 #22 中 clean-env.js 的块注释语法错误，共同说明协议运行时（ACP/MCP）内化进 packages/mindos/src/protocols/* 后，必须保证 dist/protocols/* 与运行时代码同步构建。
浏览器扩展加载失败：#41 提示 manifest 引用的资源必须在仓库中真实存在，建议 CI 增加静态校验。
官网域名错配：#43 表明 Help → MindOS 文档 菜单仍指向被 GoDaddy 托管的 mindos.app，应统一为 https://mindos.you/。

核心 CLI 包 mindos 与 Onboarding 流程

mindos 是 MindOS 仓库在 v1 重构后引入的"OpenCode 风格"主发布包，包名为 @geminilight/mindos。它是 CLI 内核边界和运行时门面（runtime facade），将原本散落在仓库根目录的 app/、mcp/、bin/ 等源码根统一收纳到 packages/mindos/ 之下，由 Web、CLI、Desktop、Mobile ...

章节 相关页面

继续阅读本节完整说明和来源证据。

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。其工作流可概括为四步：

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 流程在社区中暴露出过若干真实失败模式，运维时建议留意：

全局安装后 scripts/setup.js 缺失（issue #35）。通过 npm 全局安装后执行 mindos onboard 会抛出 MODULE_NOT_FOUND，原因是 CLI 试图加载仓库根的 scripts/setup.js，而该文件未被打入 tarball。资料来源：issue #35
Onboarding 过程中 MCP 构建报错（issue #34）。日志显示向导会进入 "Installing MCP build dependencies..." 并执行 Rebuilding MCP bundle，若该步骤失败，向导会回退到 setupPending=true 状态要求重试。资料来源：issue #34
**bin/lib/clean-env.js 块注释中含 */ 导致 SyntaxError**（issue #22）。在 macOS 通过 npm 全局安装后触发，CLI 启动即崩溃，根因是 JavaScript 块注释内嵌套了闭合标记。
升级后运行时接口不匹配（issue #40）。core 升至 1.0.15、desktop 升至 v0.3.20 后出现 o.newSession is not a function，表明 CLI 与 core runtime 的协议接口版本需要严格对齐。
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

Agent 协议集成: MCP、ACP、A2A 与 Runtime

MindOS 的 Agent 协议集成层是连接外部 Agent runtime（Codex、Claude Code、ClineCore、Hermes、Cursor 等）与本地知识库的"桥接面"。它在架构上明确区分三层：Assistant / subagent profile / mode / rule 是配置层；Agent runtime / harness 是执行层；Ru...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 3.1 协议定位

继续阅读本节完整说明和来源证据。

章节 3.2 事件流与权限桥接

继续阅读本节完整说明和来源证据。

章节 3.3 Runtime 适配器与 Profile 分离

继续阅读本节完整说明和来源证据。

一、概述与设计目标

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

graph LR
    U[用户知识库<br/>~/.mindos/mind] --> S[MCP Server<br/>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/<id>/ 这种本地 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

知识库、检索、前端渲染与多端发布

本页聚焦 MindOS 在「知识管理 → 检索召回 → 前端渲染 → 多端发布」这一整条用户可见链路上的实现方式与协作关系，涵盖知识库目录约定、检索栈、前端 Web 视图与浏览器扩展、Web Clipper / Desktop 等多端入口。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1.1 一级空间划分

继续阅读本节完整说明和来源证据。

章节 1.2 Mind Spaces 轻量模板

继续阅读本节完整说明和来源证据。

章节 1.3 模板拷贝与初始化

继续阅读本节完整说明和来源证据。

一、知识库结构与模板

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、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、issues/28。

四、多端发布：Web Clipper 与 Desktop

4.1 Web Clipper（浏览器扩展）

packages/browser-extension/ 提供开箱即用的「无构建加载」扩展：

打开 chrome://extensions，开启开发者模式，选择 Load unpacked → extension/ 目录资料来源：packages/browser-extension/README.md:18-24。
首次使用时填入 MindOS URL（默认 http://localhost:3456）与 MCP 设置中的 Auth Token 完成 Connect 资料来源：packages/browser-extension/README.md:30-36。
点击图标、右键 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。

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、issues/35、issues/34。

4.3 端到端协作示意

graph LR
    User["👤 用户"]
    Clip["🌐 Web Clipper<br/>(浏览器扩展)"]
    Web["🖥 packages/web<br/>(本地 Web 前端)"]
    Mind["📚 ~/.mindos/mind<br/>(Markdown 知识库)"]
    Ret["🔍 packages/retrieval<br/>(可选检索栈)"]
    Agent["🤖 Agent / MCP"]
    Desk["💻 Desktop<br/>(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。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：超多文件处理时频繁提示：Stream Error: Cannot continue from message role: assistant

可能影响授权、密钥配置或安全边界。

medium 来源证据：Core updater downloads v1.0.2 source zip without runtime artifacts

可能增加新用户试用和生产接入成本。

medium 来源证据：`mindos onboard` fails with MODULE_NOT_FOUND: missing scripts/setup.js

可能增加新用户试用和生产接入成本。

medium 来源证据：mindos onboard后报错

可能增加新用户试用和生产接入成本。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

MindOS 项目

系统总览与 Monorepo 架构

一、仓库根目录布局

二、核心包结构与职责

三、用户数据与运行时分层

四、生态插件与模板

五、社区高频问题与架构影响

See Also

核心 CLI 包 mindos 与 Onboarding 流程

1. 概述与定位

2. 包结构与发布边界

3. Onboarding 流程

4. 已知失败模式与社区反馈

5. 与上层产品的协作边界

See Also

Agent 协议集成: MCP、ACP、A2A 与 Runtime

一、概述与设计目标

二、MCP Server 与知识库暴露

三、ACP / A2A 与 Agent Runtime

3.1 协议定位

3.2 事件流与权限桥接

3.3 Runtime 适配器与 Profile 分离

四、模板、SOP 与 Agent-Ready 文档

五、已知限制与社区反馈

六、与外部生态的边界

See Also

知识库、检索、前端渲染与多端发布

一、知识库结构与模板

1.1 一级空间划分

1.2 Mind Spaces 轻量模板

1.3 模板拷贝与初始化

二、检索栈（Retrieval Stack）

三、前端 Web 渲染

四、多端发布：Web Clipper 与 Desktop

4.1 Web Clipper（浏览器扩展）

4.2 Desktop 与 Runtime

4.3 端到端协作示意

五、面向 Agent 的可执行知识

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

1. 安全/权限坑 · 来源证据：超多文件处理时频繁提示：Stream Error: Cannot continue from message role: assistant

2. 安装坑 · 来源证据：Core updater downloads v1.0.2 source zip without runtime artifacts

3. 安装坑 · 来源证据：`mindos onboard` fails with MODULE_NOT_FOUND: missing scripts/setup.js

4. 安装坑 · 来源证据：mindos onboard后报错

5. 配置坑 · 可能修改宿主 AI 配置

6. 能力坑 · 能力判断依赖假设

7. 运行坑 · 来源证据：向量搜索功能无法保存

8. 运行坑 · 来源证据：期待能开启子agent。大量文件时，处理起来太慢了，并且一直超时，不能脱离人自动操作。

9. 维护坑 · 维护活跃度未知

11. 安全/权限坑 · 存在评分风险

12. 维护坑 · issue/PR 响应质量未知

13. 维护坑 · 发布节奏不明确