MindOS 完整知识总结与使用教程“人类在此思考Agent 依此行动。”项目地址https://github.com/GeminiLight/MindOS目录项目概览核心理念与设计哲学系统架构功能特性详解安装与初始化配置参考CLI 命令完整参考连接 AI AgentMCP SkillsWeb UI 使用指南知识库结构与模板Git 同步配置安全机制常见问题与排错即将到来的功能社区与贡献一、项目概览MindOS 是一个本地优先的人机共享知识库定位为人类与 AI Agent 之间的第二大脑。它不是单纯的笔记工具也不是孤立的 AI 聊天工具而是将人类思考、AI 执行、经验沉淀三者有机融合的系统。核心定位维度描述对人类一个可以浏览、编辑、搜索的本地知识库 GUI对 Agent通过 MCP 协议直连的上下文提供者与指令执行中枢对系统人机协作的持续进化飞轮——思考沉淀为知识知识驱动行动行动反哺知识技术栈简介前端Next.js 16Web UI 桌面客户端MCP Serverstdio HTTP 双传输适配器数据存储本地纯文本Markdown 文件默认路径~/MindOS配置存储~/.mindos/config.json桌面端原生 macOS / Windows / Linux 应用二、核心理念与设计哲学2.1 三大核心原则① 全局同步 — 打破记忆割裂传统 AI 工具存在严重的上下文割裂问题每次切换 Cursor、Claude Code、Copilot 时AI 不知道你的项目背景、工作偏好和历史决策。MindOS 内置 MCP Server所有支持 MCP 协议的 Agent 可零配置直连同一个知识库。项目记忆与 SOP 只需记录一次全局赋能所有 AI 工具。② 透明可控 — 消除记忆黑箱大多数 AI 记忆系统将记忆锁在黑箱中用户无法审查 Agent 的推理依据错误难以纠正幻觉不断累积。MindOS 将每次检索与执行沉淀为本地纯文本提供完整的审查干预界面人类拥有绝对的心智纠偏权可随时校准 Agent 行为。③ 共生演进 — 经验回流为指令新对话每次都从零开始偏好需要反复表达思考无法积累为 AI 的能力。MindOS 将每次思考自动沉淀为知识库条目在交互中厘清想法与标准下次对话更默契认知随每次沉淀变得锐利。2.2 底层原则默认本地优先全部数据以本地纯文本保存兼顾隐私、主权与性能。你的数据永远在自己的机器上不依赖任何云服务。2.3 双向进化飞轮人类思考 · 审查 · 进化 ↓ 想法 反馈 MindOS共享知识库 ↑ 上下文 洞察 ↓ 指令 上下文 Agent执行 · 复盘 · 提炼 SOP ↓ 结果 SOP MindOS ↓ via MCP 所有 Agent人类从积累的知识中获得新洞察Agent 提炼 SOP 变得更强MindOS 居中——随每次交互持续成长的共享第二大脑。三、系统架构3.1 目录结构MindOS/ # 项目根目录 ├── app/ # Next.js 16 前端 — 浏览、编辑、与 AI 交互 ├── mcp/ # MCP Server — HTTP 适配器将工具映射到 App API ├── skills/ # MindOS Skillsmindos、mindos-zh— Agent 工作流指南 ├── templates/ # 预设模板en/、zh/、empty/— onboard 时复制到知识库目录 ├── bin/ # CLImindos start、mindos file、mindos ask 等 ├── scripts/ # 配置向导与辅助脚本 └── README.md ~/.mindos/ # 用户数据目录项目外不纳入版本控制 ├── config.json # 所有配置AI 密钥、端口、Auth token、同步设置 ├── sync-state.json # 同步状态最后同步时间、冲突文件 ├── mindos.log # 服务运行日志 └── mind/ # 你的私有知识库默认路径onboard 时可自定义3.2 服务端口服务默认端口说明Web UI / App API3456浏览器访问入口提供 REST APIMCP Server8781Agent 连接入口支持 stdio 和 HTTP四、功能特性详解4.1 人类侧功能GUI 工作台浏览、编辑、搜索笔记的统一界面统一搜索 AI 入口⌘K搜索 /⌘/AI 助手专为人机共创设计的交互体验内置 Agent 助手在知识库上下文中直接对话编辑内容无缝沉淀为可管理的知识条目一键导入拖拽文件即可导入PDF、Word、文本等Inline AI Organize 自动分析、分类、写入知识库支持进度追踪和撤销操作新手引导Onboarding首次使用的分步引导体验帮助新用户快速搭建知识库并连接第一个 Agent插件扩展内置渲染器插件功能TODO Board任务看板视图CSV Views表格数据可视化Wiki Graph知识图谱可视化Timeline时间线视图Workflow Editor可视化工作流编辑器Agent InspectorAgent 操作审计面板4.2 Agent 侧功能MCP Server Skillsstdio HTTP 双传输协议全阵容 Agent 兼容支持 Claude Code、Cursor、Gemini CLI、GitHub Copilot 等主流工具零配置接入一行命令自动安装ACP / A2A 协议Agent 间通信Phase 1 已上线Agent Card 发现 JSON-RPC 消息通信支持 Agent 发现、任务委派与编排Workflow 编排基于 YAML 的可视化工作流编辑器步骤执行引擎定义、编辑、运行多步 Agent 工作流笔记即指令日常笔记天然就是 Agent 可直接执行的高质量指令结构化模板预置 Profile、Workflows、Configurations 等目录骨架快速冷启动个人 Context4.3 基础设施功能安全防线Bearer Token 认证保护/api/*和/mcp路径沙箱防止越权访问INSTRUCTION.md写保护原子写入防止文件损坏知识图谱动态解析并可视化文件间的引用与依赖关系反向链接视图展示所有引用当前文件的反向链接帮助理解笔记在知识网络中的位置Agent 审计面板将 Agent 操作日志渲染为可筛选的时间线审查每次工具调用的详细信息Git 时光机Git 自动同步commit / push / pull记录人类与 Agent 的每次编辑历史支持一键回滚和跨设备同步桌面客户端原生 macOS / Windows / Linux 应用系统托盘驻留、开机自启、本地进程管理五、安装与初始化5.1 方式一Agent 一键安装最简单将以下指令粘贴到任意支持 MCP 的 AgentClaude Code、Cursor 等自动完成全部安装帮我从 https://github.com/GeminiLight/MindOS 安装 MindOS包含 MCP 和 Skills使用中文模板。5.2 方式二桌面客户端图形界面从官网 https://tianfuwang.tech/MindOS/#quickstart 或 GitHub Releases 下载对应平台安装包双击安装无需终端操作。5.3 方式三npm 全局安装npminstall-ggeminilight/mindoslatest5.4 方式四克隆源码gitclone https://github.com/GeminiLight/MindOScdMindOSnpminstallnpmlink# 将 mindos 命令注册为全局命令5.5 交互式初始化mindos onboard配置向导会引导你完成以下选项配置所有选项都有合理默认值知识库路径本地存储位置默认~/MindOS模板选择中文 / 英文 / 空白端口设置Web UI 端口默认 3456、MCP 端口默认 8781认证配置Bearer Token、Web 登录密码AI 服务商AnthropicClaude或 OpenAI及兼容 API启动模式前台 / 后台守护进程配置自动保存到~/.mindos/config.json。选择后台服务模式可开机自启。5.6 启动服务mindos start# 前台启动mindos start--daemon# 后台守护进程启动推荐mindosopen# 在浏览器中打开 Web UI5.7 注入个人心智初次使用推荐打开 MindOS GUI 中的内置 Agent 对话面板上传你的简历或任意个人/项目资料发送指令帮我把这些信息同步到我的 MindOS 知识库。更多实用指令示例这是我的简历读一下把我的信息整理到 MindOS 里。 帮我把这次对话的经验沉淀到 MindOS形成一个可复用的工作流。 帮我执行 MindOS 里的 XXX 工作流。六、配置参考配置文件路径~/.mindos/config.json由mindos onboard自动生成。6.1 完整配置示例{mindRoot:~/MindOS,port:3456,mcpPort:8781,authToken:,webPassword:,startMode:daemon,ai:{provider:anthropic,providers:{anthropic:{apiKey:sk-ant-...,model:claude-sonnet-4-6},openai:{apiKey:sk-...,model:gpt-4o,baseUrl:}}},sync:{enabled:true,provider:git,remote:origin,branch:main,autoCommitInterval:30,autoPullInterval:300}}6.2 字段说明字段默认值是否必填说明mindRoot~/MindOS必填知识库根目录的绝对路径port3456可选Web 服务端口mcpPort8781可选MCP 服务端口authToken—可选保护 App/api/*和 MCP/mcp的 Bearer Token 认证暴露到网络时建议设置webPassword—可选Web UI 登录密码保护与authToken相互独立startModestart可选daemon后台开机自启、start前台、dev开发模式ai.provideranthropic可选当前使用的 AI 服务商anthropic或openaiai.providers.anthropic.apiKey—可选Anthropic API Keyai.providers.anthropic.modelclaude-sonnet-4-6可选Anthropic 模型 IDai.providers.openai.apiKey—可选OpenAI API Keyai.providers.openai.modelgpt-4o可选OpenAI 模型 IDai.providers.openai.baseUrl—可选自定义接口地址用于代理或兼容 APIsync.enabledfalse可选启用/禁用 Git 自动同步sync.providergit可选同步方式目前仅支持gitsync.remoteorigin可选Git 远程仓库名sync.branchmain可选同步分支sync.autoCommitInterval30可选文件变更后自动 commitpush 的延迟秒数sync.autoPullInterval300可选自动从远程 pull 的间隔秒数6.3 配置管理命令mindos config show# 查看当前配置API Key 脱敏显示mindos config validate# 验证配置文件是否合法mindos configsetport4000# 更新单个字段无需手动编辑文件6.4 重要说明多个 AI provider 可以同时配置切换时只需修改ai.provider字段Shell 环境变量ANTHROPIC_API_KEY、OPENAI_API_KEY优先级高于配置文件运行mindos config set key val可更新单个字段无需手动编辑文件七、CLI 命令完整参考7.1 核心命令命令说明mindos使用~/.mindos/config.json中保存的模式启动mindos onboard交互式初始化生成配置、选择模板mindos onboard --install-daemon初始化 安装并启动后台服务mindos start前台启动 app MCP 服务生产模式mindos start --daemon安装并以后台 OS 服务方式启动关闭终端仍运行崩溃自动重启mindos dev启动 app MCP 服务开发模式热更新mindos dev --turbopack开发模式 Turbopack更快的 HMRmindos open在默认浏览器中打开 Web UImindos stop停止正在运行的 MindOS 进程mindos restart停止后重新启动mindos build手动构建生产版本mindos status查看服务状态概览支持--json7.2 知识库操作命令说明mindos file list列出知识库中所有文件mindos file read path读取文件内容mindos file create path创建新文件mindos file delete path删除文件mindos file search query按文件名搜索mindos space list列出所有空间mindos space create name创建新空间mindos space info name查看空间详情mindos search query通过 API 搜索知识库内容mindos ask question基于知识库向 AI 提问mindos agent list列出已检测到的 AI Agentmindos agent info name查看 Agent 详情和 MCP 配置mindos api METHOD pathAPI 透传GET/POST/PUT/DELETE开发者/Agent 用所有知识库命令均支持--json标志供 AI Agent 程序化调用。7.3 MCP 管理命令说明mindos mcp仅启动 MCP 服务mindos mcp install自动将 MCP 配置写入 Agent交互式mindos mcp install -g -y一键全局安装无需交互确认mindos token查看当前 Auth token 及 MCP 配置片段7.4 Git 同步命令说明mindos sync查看同步状态sync status的别名mindos sync init交互式配置 Git 远程同步mindos sync status查看同步状态最后同步时间、未推送提交、冲突mindos sync now手动触发完整同步commit push pullmindos sync on启用自动同步mindos sync off禁用自动同步mindos sync conflicts列出未解决的冲突文件7.5 后台服务Gateway命令说明mindos gateway install安装后台服务Linux 用 systemdmacOS 用 LaunchAgentmindos gateway uninstall卸载后台服务mindos gateway start启动后台服务mindos gateway stop停止后台服务mindos gateway status查看后台服务状态mindos gateway logs实时查看服务日志7.6 运维与调试命令说明mindos doctor健康检查配置、端口、构建、daemon 状态mindos update更新 MindOS 到最新版本mindos uninstall完整卸载停止进程、移除 daemon、npm 卸载mindos logs实时查看服务日志~/.mindos/mindos.log八、连接 AI AgentMCP Skills8.1 支持的 Agent 列表AgentMCPSkillsMCP 配置文件路径Claude Code✅✅~/.claude.json全局或.mcp.json项目级Cursor✅✅~/.cursor/mcp.json全局或.cursor/mcp.json项目级Gemini CLI✅✅~/.gemini/settings.json或.gemini/settings.jsonGitHub Copilot✅✅.vscode/mcp.json或 VS Codesettings.jsonWindsurf✅✅~/.codeium/windsurf/mcp_config.jsonCline✅✅macOS:~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.jsonTrae✅✅~/.trae/mcp.json或.trae/mcp.jsonCodex✅✅~/.codex/config.tomlTOML 格式OpenClaw✅✅~/.openclaw/openclaw.jsonCodeBuddy✅✅~/.codebuddy/mcp.jsonQoder✅✅~/.qoder.jsonRoo Code✅✅macOS:~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.jsonKimi Code✅✅~/.kimi/mcp.json或.kimi/mcp.jsonQwen Code✅✅~/.qwen/settings.json或.qwen/settings.jsonAugment✅✅~/.augment/settings.jsonVS Code✅✅.vscode/mcp.json或 VS Codesettings.json8.2 MCP 安装方式方式一自动安装推荐mindos mcpinstall交互式引导选择agent 类型 → scope全局/项目级→ transportstdio/http→ token方式二一键全局安装mindos mcpinstall-g-y方式三远程服务器安装mindos mcpinstall--transporthttp--urlhttp://服务器IP:8781/mcp--tokenyour-token-g方式四手动配置 JSON本机 stdio 传输无需启动独立服务进程{mcpServers:{mindos:{type:stdio,command:mindos,args:[mcp],env:{MCP_TRANSPORT:stdio}}}}本机 HTTP 传输{mcpServers:{mindos:{url:http://localhost:8781/mcp,headers:{Authorization:Bearer your-token}}}}远程服务器{mcpServers:{mindos:{url:http://服务器IP:8781/mcp,headers:{Authorization:Bearer your-token}}}}8.3 Skills 安装Skills 是为 Agent 提供工作流能力的指导文档根据语言偏好选择# 中文 Skillsnpx skillsaddhttps://github.com/GeminiLight/MindOS--skillmindos-zh-g-y# 英文 Skillsnpx skillsaddhttps://github.com/GeminiLight/MindOS--skillmindos-g-y九、Web UI 使用指南9.1 常用快捷键快捷键功能⌘K全局搜索⌘/打开 AI 助手对话E编辑当前文件⌘S保存当前编辑Esc关闭对话框/面板9.2 主要功能区域首页 — 知识库概览显示所有空间Space和文件列表快速访问最近编辑的文件统计知识库整体信息AI 对话面板⌘/在知识库上下文中与 AI 对话AI 可直接读取、写入知识库中的文件支持上传文件让 AI 分析并整理Agent 工作台管理所有已连接的 AI Agent查看 Agent 的连接状态和 MCP 配置监控 Agent 的操作历史Echo复盘与认知沉淀对话后复盘界面将有价值的交互内容提炼为可复用的知识9.3 典型使用流程1. 打开 MindOS Web UImindos open 2. 上传资料 → AI 自动整理到知识库 3. 在 Cursor/Claude Code 等工具中编写代码 4. Agent 通过 MCP 自动读取知识库中的上下文 5. 完成任务后让 Agent 将经验沉淀回知识库 6. 下次同类任务Agent 直接复用 SOP十、知识库结构与模板10.1 中文模板目录结构默认~/MindOS/或你自定义的 mindRoot ├── INSTRUCTION.md # 给 Agent 的全局指令写保护谨慎修改 ├── Profile/ # 个人/团队信息 │ ├── About.md # 基本信息、背景 │ ├── Skills.md # 技能与专长 │ └── Preferences.md # 工作偏好与习惯 ├── Workflows/ # 可执行的工作流 SOP │ ├── coding-workflow.md # 编程工作流 │ └── research-workflow.md # 研究工作流 ├── Configurations/ # 项目与工具配置 │ └── dev-environment.md # 开发环境配置 ├── Projects/ # 项目相关知识 └── Notes/ # 日常笔记与想法10.2 INSTRUCTION.md 的作用INSTRUCTION.md是整个知识库的总纲相当于给所有 Agent 的系统提示词。它被 MCP Server 自动注入到每次 Agent 的上下文中告知 Agent如何理解和使用这个知识库知识库的组织结构写入内容时需遵守的规范全局偏好与约束⚠️INSTRUCTION.md受写保护Agent 默认不能修改它只有人类可以编辑。10.3 笔记即指令的最佳实践MindOS 的核心理念之一是笔记即指令——用自然语言记录的 SOP 可以直接被 Agent 执行。推荐写法示例# 代码审查工作流 ## 步骤 1. 读取 PR 描述和改动文件 2. 检查代码风格是否符合 Configurations/code-style.md 3. 验证测试覆盖率 ≥ 80% 4. 生成审查意见格式参考 Templates/code-review-template.md 5. 将审查结论写入 Projects/{{项目名}}/reviews/ 目录 ## 偏好 - 优先关注安全漏洞和性能问题 - 使用中文写审查意见 - 避免个人风格批评聚焦于代码质量Agent 看到这份笔记后可以直接将其作为执行指令完成完整的代码审查流程。十一、Git 同步配置11.1 初始化 Git 同步# 交互式配置mindossyncinit# 配置完成后启用mindossyncon11.2 手动同步操作mindossyncnow# 立即执行 commit push pullmindossyncstatus# 查看同步状态mindossyncconflicts# 查看冲突文件11.3 同步配置说明在~/.mindos/config.json的sync字段中autoCommitInterval: 30文件保存 30 秒后自动 commit 并 push避免过于频繁autoPullInterval: 300每 5 分钟自动 pull 一次远程更新可配合 GitHub / Gitee / 自建 Git 服务使用实现多设备同步11.4 时光机回滚操作所有编辑包括 Agent 的写入都会被 Git 记录。如果 Agent 写入了错误内容# 查看历史cd~/MindOSgitlog--oneline# 回滚到某个提交gitrevertcommit-hash# 或gitreset--hardcommit-hash十二、安全机制12.1 双层认证认证类型配置字段作用对象适用场景Bearer TokenauthToken保护/api/*和 MCP/mcpAgent 访问、API 调用Web 密码webPassword保护 Web UI 登录浏览器访问两者相互独立可以单独启用。12.2 路径沙箱MCP Server 的所有文件操作被限制在mindRoot目录内防止 Agent 越权访问系统文件。12.3 INSTRUCTION.md 写保护INSTRUCTION.md是全局指令文件被系统级写保护Agent 无法修改它。这确保了 Agent 行为规范的稳定性防止 AI 自我修改控制指令。12.4 原子写入所有文件写入操作使用原子写入策略先写临时文件再原子替换防止因意外中断导致文件损坏。12.5 暴露到公网时的安全建议如果你将 MindOS 部署到公网服务器必须设置authToken用于 Agent/API 访问建议设置webPassword用于 Web UI 访问建议使用反向代理Nginx/Caddy添加 HTTPS考虑使用防火墙限制访问 IP十三、常见问题与排错Q1安装后 Tools 不出现现象运行mindos mcp install后在 Cursor/Windsurf/Trae/Cline 中找不到 MindOS 的工具。原因这些 Agent 不会热加载 MCP 配置。解决完全退出并重启该 Agent不是刷新是彻底关闭再打开。Q2macOS 下mindos命令找不到现象GUI 类 AgentCursor、Windsurf使用 stdio 传输时报错找不到mindos命令。原因GUI 应用可能不继承 shell 的 PATH 环境变量。解决# 找到 mindos 的完整路径whichmindos# 输出示例/opt/homebrew/bin/mindos# 在 MCP 配置中使用完整路径{command:/opt/homebrew/bin/mindos,args:[mcp],env:{MCP_TRANSPORT:stdio}}Q3Windows 下命令启动失败原因Windows 上mindos通过 npm 安装是.cmd脚本部分 Agent 无法直接执行。解决用cmd包装一层{mcpServers:{mindos:{command:cmd,args:[/c,mindos,mcp],env:{MCP_TRANSPORT:stdio}}}}Q4Cursor 中 MindOS Tools 被静默丢弃原因Cursor 所有 MCP Server 合计最多约 40 个 Tool。安装了太多 MCP Server 时工具会被静默丢弃。解决在 Cursor MCP 设置中禁用不常用的 MCP Server释放 Tool 名额。Q5服务启动失败端口被占用# 检查端口占用lsof-i:3456lsof-i:8781# 停止 MindOSmindos stop# 或修改端口mindos configsetport3457mindos configsetmcpPort8782mindos restartQ6如何升级 MindOSmindos update或手动升级npminstall-ggeminilight/mindoslatest mindos restartQ7运行健康检查mindos doctor该命令会检查配置文件完整性、端口可用性、构建产物是否存在、daemon 服务状态等并给出修复建议。十四、即将到来的功能功能描述RAG 深度集成基于知识库内容的检索增强生成让 AI 回答更精准、更有上下文ACP / A2A Phase 2深度多 Agent 协作支持任务委派、共享上下文、工作流链式执行经验编译器从 Agent 交互中自动提取纠正和偏好沉淀为可复用的 Skills/SOP知识库健康度仪表盘可视化认知复利指标——已积累规则数、Agent 复用次数、知识新鲜度十五、社区与贡献微信社区扫码加入微信内测群抢先体验、反馈建议、交流 AI 工作流或添加微信wtfly2018邀请入群。参与贡献gitclone https://github.com/GeminiLight/MindOScdMindOSnpminstallnpmrun dev# 启动开发模式欢迎提交 Issue 和 Pull Request。致谢本项目已在 LINUX DO 社区 发布感谢社区的支持与反馈。附录快速参考卡最常用命令mindos onboard# 首次初始化mindos start--daemon# 后台启动mindosopen# 打开 Web UImindos mcpinstall-g-y# 一键安装 MCP所有 Agentmindos status# 查看运行状态mindos doctor# 健康检查mindos update# 更新版本mindos stop# 停止服务最实用的 Agent 指令模板# 导入个人信息 这是我的简历读一下把我的信息整理到 MindOS 里。 # 沉淀经验 帮我把这次对话的经验沉淀到 MindOS形成一个可复用的工作流。 # 执行工作流 帮我执行 MindOS 里的 [工作流名称] 工作流。 # 同步项目信息 帮我把 [项目名] 的背景和技术选型信息整理到 MindOS 的 Projects 目录。快捷键速查⌘K全局搜索⌘/AI 助手E编辑⌘S保存Esc关闭