企业官网建设流程全解析

一句话理解 MindOS：本地知识工作台 + Agent 共享大脑

如果你装过 Claude Code、Cursor、Gemini CLI，大概率遇到过同一个痛点：换个工具，上下文就清零；知识散落在聊天记录里，Agent 的推理过程像黑盒，出了问题无从查起。

MindOS就是为了解决这个问题而生的Human-AI 协作心智系统（Human-AI Collaborative Mind System）：你的知识库是一堆本地纯文本（Markdown + CSV），人类在这里思考、审阅，各个 Agent 通过 MCP 协议读取共享上下文、执行任务，再把经验沉淀回知识库。它的核心承诺可以概括成三个词：全局同步（Global Sync）、透明可控（Transparent & Controllable）、共生进化（Symbiotic Evolution）。

本文将从架构视角拆解两件事：

1. OpenCode 式产品主包——packages/mindos如何把 CLI、Server、协议、Agent 运行时收敛成一个单一 runtime；
2. 78 条 API 路由——Web 端这套路由体系如何撑起一个"本地知识工作台"，以及它是怎么一步步瘦身的。

不需要任何源码基础，跟着读就能建立完整的心智模型。

鸟瞰图：谁和谁在对话？

MindOS 的整体结构非常清晰，记住三层就够：

外部 Agent（Claude Code、Cursor、Codex 等）不直接碰文件系统，而是走MCP 协议（stdio 或 Streamable HTTP + Bearer Token）进入产品运行时。这样设计的好处是：所有读写都经过同一套路径沙箱、权限决策和审计日志，Agent 做了什么、改了什么，人类随时可查。

官方文档把整套系统架构讲得很细，建议收藏：wiki/20-system-architecture.md；面向用户的安装与配置说明在 docs/zh/（中文）与 docs/en/。

什么是"OpenCode 式产品主包"？

先说结论：packages/mindos是 MindOS 的"产品主包"，它的设计参考了 OpenCode 的组织方式——把产品真正的所有物（product kernel）收进一个可独立发布的 npm 包里，其余一切（Web、桌面、移动端、扩展）都只是客户端和适配器。

这个包的名字是@geminilight/mindos，你npm install -g装到的就是它。它对外暴露了一组语义化子路径导出（subpath exports），每个子路径对应一块能力：

• ./foundation：配置、日志、权限、安全、插件安装等最底层的共享原语
• ./knowledge：存储、空间、知识图谱、Git 同步、知识库操作内核
• ./retrieval：检索契约、分块策略、索引/向量抽象
• ./server：API 路由契约与 Hono HTTP 应用
• ./protocols：MCP / ACP / A2A 协议实现
• ./agent、./client、./client-types、./plugin、./tool、./session：Agent 运行时与客户端契约

想亲手看它长什么样：packages/mindos/package.json 里的exports字段就是全部公开能力地图；包内分层规则由 packages/mindos/src/layering.test.ts 静态扫描强制执行。

依赖单向流动：foundation ← knowledge ← agent ← server

主包内部还有一条铁律：依赖只能单向流动。分层从低到高依次是foundation → knowledge → agent → server，协议层（protocols）是低层 domain，任何一层都不能反向 import 更上层的模块。这不是靠代码评审维持的口头约定，而是由layering.test.ts的自动检查守住——一旦有人写了反向依赖，CI 直接红灯。

为什么重要？因为 MindOS 同时跑着Web 服务器、独立 Product Server、CLI、桌面壳四种宿主。分层清晰意味着同一份knowledge代码在四种宿主里行为一致，不会出现"Web 一套写入逻辑、CLI 又一套"的分裂。历史上 Web 侧确实曾有本地operation-kernel.ts，后来被删除，统一改走@geminilight/mindos/server的 facade（见 packages/web/app/api/file/route.ts）。

发布边界：一个 shim，八种平台包

packages/mindos/package.json是真正的发布单元：bin.mindos指向一个极薄的bin/mindos-shim.cjs，它负责解析当前平台并执行对应的平台 runtime 包（@geminilight/mindos-darwin-arm64、-linux-x64、-windows-x64等 8 个 optionalDependencies）。npm 主包本体只保留 shim + 公共 JS 导出，完整 CLI 和预构建的 Web 运行时（_standalone/）由平台包承载。

这套发布契约由 tests/runtime-product-kernel-contract.test.ts 和 tests/platform-runtime-package-contract.test.ts 锁定。对用户的直接收益是：一条npm install -g @geminilight/mindos@latest，跨平台拿到开箱即用的 CLI + 本地 Web 工作台，不用自己折腾 Node 环境。

78 条 API 路由：本地知识工作台的"接口契约"

打开 wiki/20-system-architecture.md，会看到一句话："API Routes (总 78，已迁移 thin-adapter 65)"。这就是本文标题里"78 条 API 路由"的出处——Web 端最初盘点出 78 个 API 端点，其中 65 个已经迁移成"thin adapter（薄适配器）"模式。

这 78 条路由大致覆盖六类场景：

关键设计：thin adapter，一行委托

"已迁移 thin-adapter 65"是理解这套架构的钥匙。以文件路由为例，Web 侧的route.ts不再自己写业务逻辑，而是一行delegateToMindos(method, path)，请求经过 Next 鉴权后，全部交给产品主包里那张统一的路由表（MindosRouteDefinition[]，按 files / search / knowledge / agent / mcp / skills / system 等领域分文件导出）。

好处有三：

1. 单一事实来源：body 限额、错误映射、内容变更日志、ETag/304 缓存，全部收敛在路由表里，Web 侧不再散落复制粘贴；
2. CLI / MCP / Web 复用同一实现：MCP 工具调用和 Web 页面按钮背后走的是同一套knowledge-ops内核，权限和写规则不会分裂；
3. 契约测试兜底：tests/web-api-route-ownership-contract.test.ts 会校验每个 Next API 路由都被注册表恰好分类一次、product-owned 路由不允许在 Web 侧直接 import handler、委托方法集与MINDOS_SERVER_ROUTES完全一致。契约一旦漂移，测试立刻失败。

随着路由持续扩展，当前委托给产品路由表（mindos-appadapter）的数量已从早期的 65 增长到109 条——你可以把它理解为"78 条路由基线 + 持续下沉的新路由"。这也是为什么看文档时要区分"历史盘点数字"和"当前契约数字"。

瘦身实录：从 1524 行到 1050 行

架构演进不是口号，数字能说明问题。2026-04-10 的一轮职责分离重构中：

• app/api/ask/route.ts：1,524 行 →1,050 行（-31%），拆出lib/sse/events.ts、lib/agent/skill-resolver.ts等 7 个业务模块
• app/api/file/route.ts：451 行 →159 行（-65%），业务全部下沉到产品主包

超大组件同样在拆：TodoRenderer从 889 行降到 137 行（-85%），AgentDetailContent从 1,188 行降到 741 行并拆出 6 个子组件。明细见 wiki/20-system-architecture.md。

数据底座：Markdown 是真相，SQLite 只是加速

很多人担心"本地工作台"是不是要拖一个重量级数据库。MindOS 的答案是：知识内容永远是本地纯文本（Markdown + CSV + Git），数据库只用来存"派生状态"——那些删了可以随时重建的高频查询数据。

具体用 Node 内建的node:sqlite（WAL 模式），零新增依赖：

• 变更日志：.mindos/db/change_log_1.sqlite，每次文件改动留痕，保留最新 500 条
• Agent run ledger：.mindos/db/agent_runs_1.sqlite，Agent 每一步工具调用、权限事件都在此落账
• pending prompts：跨进程的权限确认镜像，保证"在 Web 上点的确认，能即时传回正在跑 Agent 的 CLI 进程"

配合文件树缓存（server/tree-cache.ts，500ms 批处理 fs.watch 事件）和BM25 搜索索引（中文分词 + 增量重建），整个工作台做到"改文件 → SSE 事件 → UI 秒级刷新"的全链路响应。旧格式的 JSONL 台账在首次打开时自动迁移改名，升级无感。

新手落地：三步跑起来

# 1. 全局安装（自带 CLI + 本地 Web 运行时） npm install -g @geminilight/mindos@latest # 2. 交互式初始化：知识库路径、模板、端口、AI 供应商，全有默认值 mindos onboard # 3. 打开 Web 工作台 mindos open

之后给任意 Agent 装上共享大脑，一条命令完成 MCP + Skills 安装：

mindos mcp install -g -y # 全局、免交互 mindos doctor agents # 验证各 Agent 真实就绪状态

配置文件落在~/.mindos/config.json，全部字段说明见 docs/zh/configuration.md；支持哪些 Agent、各自的 MCP 配置路径与排障技巧，看 docs/zh/supported-agents.md。

总结：为什么这套架构值得你深潜

回到开头的问题——为什么 MindOS 值得花时间理解它的架构？因为它的每一个设计决策都在回答"人机协作"的三个基本焦虑：

而支撑这一切的，正是两个"骨架"：OpenCode 式产品主包保证能力收敛、跨宿主一致；78 条（且持续增长中的）API 路由 + thin adapter 契约保证 Web 端轻、逻辑不分裂、演进有测试兜底。理解了这两点，你就拥有了阅读 MindOS 全部源码的地图。

延伸阅读：wiki/20-system-architecture.md（系统架构全文）、wiki/21-design-principle.md（设计原则）、wiki/25-agent-architecture.md（Agent 架构）、wiki/30-api-reference.md（API 参考）、wiki/80-known-pitfalls.md（已知坑位清单）。