MindOS：你的AI第二大脑知识库

MindOS 完整知识总结与使用教程

"人类在此思考，Agent 依此行动。"

项目地址：https://github.com/GeminiLight/MindOS

项目概览
核心理念与设计哲学
系统架构
功能特性详解
安装与初始化
配置参考
[CLI 命令完整参考](#CLI 命令完整参考)
[连接 AI Agent（MCP + Skills）](#连接 AI Agent（MCP + Skills）)
[Web UI 使用指南](#Web UI 使用指南)
知识库结构与模板
[Git 同步配置](#Git 同步配置)
安全机制
常见问题与排错
即将到来的功能
社区与贡献

一、项目概览

MindOS 是一个本地优先的人机共享知识库 ，定位为人类与 AI Agent 之间的"第二大脑"。它不是单纯的笔记工具，也不是孤立的 AI 聊天工具，而是将人类思考、AI 执行、经验沉淀三者有机融合的系统。

核心定位

维度	描述
对人类	一个可以浏览、编辑、搜索的本地知识库 GUI
对 Agent	通过 MCP 协议直连的上下文提供者与指令执行中枢
对系统	人机协作的持续进化飞轮------思考沉淀为知识，知识驱动行动，行动反哺知识

技术栈简介

前端：Next.js 16（Web UI + 桌面客户端）
MCP Server：stdio + 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 Skills（mindos、mindos-zh）--- Agent 工作流指南
├── templates/              # 预设模板（en/、zh/、empty/）--- onboard 时复制到知识库目录
├── bin/                    # CLI（mindos 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 API	`3456`	浏览器访问入口，提供 REST API
MCP Server	`8781`	Agent 连接入口，支持 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 Inspector	Agent 操作审计面板

4.2 Agent 侧功能

MCP Server + Skills

stdio + 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 等目录骨架
快速冷启动个人 Context

4.3 基础设施功能

安全防线

Bearer Token 认证（保护 /api/* 和 /mcp）
路径沙箱（防止越权访问）
INSTRUCTION.md 写保护
原子写入（防止文件损坏）

知识图谱

动态解析并可视化文件间的引用与依赖关系

反向链接视图

展示所有引用当前文件的反向链接
帮助理解笔记在知识网络中的位置

Agent 审计面板

将 Agent 操作日志渲染为可筛选的时间线
审查每次工具调用的详细信息

Git 时光机

Git 自动同步（commit / push / pull）
记录人类与 Agent 的每次编辑历史
支持一键回滚和跨设备同步

桌面客户端

原生 macOS / Windows / Linux 应用
系统托盘驻留、开机自启、本地进程管理

五、安装与初始化

5.1 方式一：Agent 一键安装（最简单）

将以下指令粘贴到任意支持 MCP 的 Agent（Claude Code、Cursor 等），自动完成全部安装：

复制代码

帮我从 https://github.com/GeminiLight/MindOS 安装 MindOS，包含 MCP 和 Skills，使用中文模板。

5.2 方式二：桌面客户端（图形界面）

从官网 https://tianfuwang.tech/MindOS/#quickstart 或 GitHub Releases 下载对应平台安装包，双击安装，无需终端操作。

5.3 方式三：npm 全局安装

bash 复制代码

npm install -g @geminilight/mindos@latest

5.4 方式四：克隆源码

bash 复制代码

git clone https://github.com/GeminiLight/MindOS
cd MindOS
npm install
npm link   # 将 mindos 命令注册为全局命令

5.5 交互式初始化

bash 复制代码

mindos onboard

配置向导会引导你完成以下选项配置（所有选项都有合理默认值）：

知识库路径 ：本地存储位置，默认 ~/MindOS
模板选择：中文 / 英文 / 空白
端口设置：Web UI 端口（默认 3456）、MCP 端口（默认 8781）
认证配置：Bearer Token、Web 登录密码
AI 服务商：Anthropic（Claude）或 OpenAI（及兼容 API）
启动模式：前台 / 后台守护进程

配置自动保存到 ~/.mindos/config.json。选择"后台服务"模式可开机自启。

5.6 启动服务

bash 复制代码

mindos start        # 前台启动
mindos start --daemon  # 后台守护进程启动（推荐）
mindos open         # 在浏览器中打开 Web UI

5.7 注入个人心智（初次使用推荐）

打开 MindOS GUI 中的内置 Agent 对话面板
上传你的简历或任意个人/项目资料
发送指令：

帮我把这些信息同步到我的 MindOS 知识库。

更多实用指令示例：

复制代码

这是我的简历，读一下，把我的信息整理到 MindOS 里。
帮我把这次对话的经验沉淀到 MindOS，形成一个可复用的工作流。
帮我执行 MindOS 里的 XXX 工作流。

六、配置参考

配置文件路径：~/.mindos/config.json，由 mindos onboard 自动生成。

6.1 完整配置示例

json 复制代码

{
  "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`	必填	知识库根目录的绝对路径
`port`	`3456`	可选	Web 服务端口
`mcpPort`	`8781`	可选	MCP 服务端口
`authToken`	---	可选	保护 App `/api/*` 和 MCP `/mcp` 的 Bearer Token 认证（暴露到网络时建议设置）
`webPassword`	---	可选	Web UI 登录密码保护，与 `authToken` 相互独立
`startMode`	`start`	可选	`daemon`（后台+开机自启）、`start`（前台）、`dev`（开发模式）
`ai.provider`	`anthropic`	可选	当前使用的 AI 服务商：`anthropic` 或 `openai`
`ai.providers.anthropic.apiKey`	---	可选	Anthropic API Key
`ai.providers.anthropic.model`	`claude-sonnet-4-6`	可选	Anthropic 模型 ID
`ai.providers.openai.apiKey`	---	可选	OpenAI API Key
`ai.providers.openai.model`	`gpt-4o`	可选	OpenAI 模型 ID
`ai.providers.openai.baseUrl`	---	可选	自定义接口地址（用于代理或兼容 API）
`sync.enabled`	`false`	可选	启用/禁用 Git 自动同步
`sync.provider`	`git`	可选	同步方式（目前仅支持 `git`）
`sync.remote`	`origin`	可选	Git 远程仓库名
`sync.branch`	`main`	可选	同步分支
`sync.autoCommitInterval`	`30`	可选	文件变更后自动 commit+push 的延迟秒数
`sync.autoPullInterval`	`300`	可选	自动从远程 pull 的间隔秒数

6.3 配置管理命令

bash 复制代码

mindos config show              # 查看当前配置（API Key 脱敏显示）
mindos config validate          # 验证配置文件是否合法
mindos config set port 4000     # 更新单个字段，无需手动编辑文件

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（更快的 HMR）
`mindos open`	在默认浏览器中打开 Web UI
`mindos stop`	停止正在运行的 MindOS 进程
`mindos restart`	停止后重新启动
`mindos build`	手动构建生产版本
`mindos status`	查看服务状态概览（支持 `--json`）

7.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 Agent
`mindos agent info <name>`	查看 Agent 详情和 MCP 配置
`mindos api <METHOD> <path>`	API 透传（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 + pull）
`mindos sync on`	启用自动同步
`mindos sync off`	禁用自动同步
`mindos sync conflicts`	列出未解决的冲突文件

7.5 后台服务（Gateway）

命令	说明
`mindos gateway install`	安装后台服务（Linux 用 systemd，macOS 用 LaunchAgent）
`mindos 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 Agent（MCP + Skills）

8.1 支持的 Agent 列表

Agent	MCP	Skills	MCP 配置文件路径
Claude Code	✅	✅	`~/.claude.json`（全局）或 `.mcp.json`（项目级）
Cursor	✅	✅	`~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目级）
Gemini CLI	✅	✅	`~/.gemini/settings.json` 或 `.gemini/settings.json`
GitHub Copilot	✅	✅	`.vscode/mcp.json` 或 VS Code `settings.json`
Windsurf	✅	✅	`~/.codeium/windsurf/mcp_config.json`
Cline	✅	✅	macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
Trae	✅	✅	`~/.trae/mcp.json` 或 `.trae/mcp.json`
Codex	✅	✅	`~/.codex/config.toml`（TOML 格式）
OpenClaw	✅	✅	`~/.openclaw/openclaw.json`
CodeBuddy	✅	✅	`~/.codebuddy/mcp.json`
Qoder	✅	✅	`~/.qoder.json`
Roo Code	✅	✅	macOS: `~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json`
Kimi Code	✅	✅	`~/.kimi/mcp.json` 或 `.kimi/mcp.json`
Qwen Code	✅	✅	`~/.qwen/settings.json` 或 `.qwen/settings.json`
Augment	✅	✅	`~/.augment/settings.json`
VS Code	✅	✅	`.vscode/mcp.json` 或 VS Code `settings.json`

8.2 MCP 安装方式

方式一：自动安装（推荐）

bash 复制代码

mindos mcp install

交互式引导选择：agent 类型 → scope（全局/项目级）→ transport（stdio/http）→ token

方式二：一键全局安装

bash 复制代码

mindos mcp install -g -y

方式三：远程服务器安装

bash 复制代码

mindos mcp install --transport http --url http://<服务器IP>:8781/mcp --token your-token -g

方式四：手动配置 JSON

本机 stdio 传输（无需启动独立服务进程）：

json 复制代码

{
  "mcpServers": {
    "mindos": {
      "type": "stdio",
      "command": "mindos",
      "args": ["mcp"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

本机 HTTP 传输：

json 复制代码

{
  "mcpServers": {
    "mindos": {
      "url": "http://localhost:8781/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

远程服务器：

json 复制代码

{
  "mcpServers": {
    "mindos": {
      "url": "http://<服务器IP>:8781/mcp",
      "headers": { "Authorization": "Bearer your-token" }
    }
  }
}

8.3 Skills 安装

Skills 是为 Agent 提供工作流能力的指导文档，根据语言偏好选择：

bash 复制代码

# 中文 Skills
npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y

# 英文 Skills
npx skills add https://github.com/GeminiLight/MindOS --skill mindos -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 UI（mindos 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 执行。

推荐写法示例：

markdown 复制代码

# 代码审查工作流

## 步骤
1. 读取 PR 描述和改动文件
2. 检查代码风格是否符合 Configurations/code-style.md
3. 验证测试覆盖率 ≥ 80%
4. 生成审查意见，格式参考 Templates/code-review-template.md
5. 将审查结论写入 Projects/{{项目名}}/reviews/ 目录

## 偏好
- 优先关注安全漏洞和性能问题
- 使用中文写审查意见
- 避免个人风格批评，聚焦于代码质量

Agent 看到这份笔记后，可以直接将其作为执行指令，完成完整的代码审查流程。

十一、Git 同步配置

11.1 初始化 Git 同步

bash 复制代码

# 交互式配置
mindos sync init

# 配置完成后启用
mindos sync on

11.2 手动同步操作

bash 复制代码

mindos sync now          # 立即执行 commit + push + pull
mindos sync status       # 查看同步状态
mindos sync conflicts    # 查看冲突文件

11.3 同步配置说明

在 ~/.mindos/config.json 的 sync 字段中：

autoCommitInterval: 30：文件保存 30 秒后自动 commit 并 push（避免过于频繁）
autoPullInterval: 300：每 5 分钟自动 pull 一次远程更新
可配合 GitHub / Gitee / 自建 Git 服务使用，实现多设备同步

11.4 时光机：回滚操作

所有编辑（包括 Agent 的写入）都会被 Git 记录。如果 Agent 写入了错误内容：

bash 复制代码

# 查看历史
cd ~/MindOS && git log --oneline

# 回滚到某个提交
git revert <commit-hash>
# 或
git reset --hard <commit-hash>

十二、安全机制

12.1 双层认证

认证类型	配置字段	作用对象	适用场景
Bearer Token	`authToken`	保护 `/api/*` 和 MCP `/mcp`	Agent 访问、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（不是刷新，是彻底关闭再打开）。

Q2：macOS 下 `mindos` 命令找不到

现象：GUI 类 Agent（Cursor、Windsurf）使用 stdio 传输时报错，找不到 mindos 命令。

原因：GUI 应用可能不继承 shell 的 PATH 环境变量。

解决：

bash 复制代码

# 找到 mindos 的完整路径
which mindos
# 输出示例：/opt/homebrew/bin/mindos

# 在 MCP 配置中使用完整路径
{
  "command": "/opt/homebrew/bin/mindos",
  "args": ["mcp"],
  "env": { "MCP_TRANSPORT": "stdio" }
}

Q3：Windows 下命令启动失败

原因：Windows 上 mindos（通过 npm 安装）是 .cmd 脚本，部分 Agent 无法直接执行。

解决：用 cmd 包装一层：

json 复制代码

{
  "mcpServers": {
    "mindos": {
      "command": "cmd",
      "args": ["/c", "mindos", "mcp"],
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Q4：Cursor 中 MindOS Tools 被静默丢弃

原因：Cursor 所有 MCP Server 合计最多约 40 个 Tool。安装了太多 MCP Server 时，工具会被静默丢弃。

解决：在 Cursor MCP 设置中禁用不常用的 MCP Server，释放 Tool 名额。

Q5：服务启动失败，端口被占用

bash 复制代码

# 检查端口占用
lsof -i :3456
lsof -i :8781

# 停止 MindOS
mindos stop

# 或修改端口
mindos config set port 3457
mindos config set mcpPort 8782
mindos restart

Q6：如何升级 MindOS

bash 复制代码

mindos update

或手动升级：

bash 复制代码

npm install -g @geminilight/mindos@latest
mindos restart

Q7：运行健康检查

bash 复制代码

mindos doctor

该命令会检查：配置文件完整性、端口可用性、构建产物是否存在、daemon 服务状态等，并给出修复建议。

十四、即将到来的功能

功能	描述
RAG 深度集成	基于知识库内容的检索增强生成，让 AI 回答更精准、更有上下文
ACP / A2A Phase 2	深度多 Agent 协作，支持任务委派、共享上下文、工作流链式执行
经验编译器	从 Agent 交互中自动提取纠正和偏好，沉淀为可复用的 Skills/SOP
知识库健康度仪表盘	可视化认知复利指标------已积累规则数、Agent 复用次数、知识新鲜度

十五、社区与贡献

微信社区

扫码加入微信内测群（抢先体验、反馈建议、交流 AI 工作流），或添加微信 wtfly2018 邀请入群。

参与贡献

bash 复制代码

git clone https://github.com/GeminiLight/MindOS
cd MindOS
npm install
npm run dev     # 启动开发模式

欢迎提交 Issue 和 Pull Request。

致谢

本项目已在 LINUX DO 社区发布，感谢社区的支持与反馈。

附录：快速参考卡

最常用命令

bash 复制代码

mindos onboard           # 首次初始化
mindos start --daemon    # 后台启动
mindos open              # 打开 Web UI
mindos mcp install -g -y # 一键安装 MCP（所有 Agent）
mindos status            # 查看运行状态
mindos doctor            # 健康检查
mindos update            # 更新版本
mindos stop              # 停止服务

最实用的 Agent 指令模板

复制代码

# 导入个人信息
这是我的简历，读一下，把我的信息整理到 MindOS 里。

# 沉淀经验
帮我把这次对话的经验沉淀到 MindOS，形成一个可复用的工作流。

# 执行工作流
帮我执行 MindOS 里的 [工作流名称] 工作流。

# 同步项目信息
帮我把 [项目名] 的背景和技术选型信息整理到 MindOS 的 Projects 目录。

快捷键速查

`⌘K`	全局搜索	`⌘/`	AI 助手	`E`	编辑	`⌘S`	保存	`Esc`	关闭

MindOS：你的AI第二大脑知识库

MindOS 完整知识总结与使用教程

目录

一、项目概览

核心定位

技术栈简介

二、核心理念与设计哲学

2.1 三大核心原则

2.2 底层原则

2.3 双向进化飞轮

三、系统架构

3.1 目录结构

3.2 服务端口

四、功能特性详解

4.1 人类侧功能

4.2 Agent 侧功能

4.3 基础设施功能

五、安装与初始化

5.1 方式一：Agent 一键安装（最简单）

5.2 方式二：桌面客户端（图形界面）

5.3 方式三：npm 全局安装

5.4 方式四：克隆源码

5.5 交互式初始化

5.6 启动服务

5.7 注入个人心智（初次使用推荐）

六、配置参考

6.1 完整配置示例

6.2 字段说明

6.3 配置管理命令

6.4 重要说明

七、CLI 命令完整参考

7.1 核心命令

7.2 知识库操作

7.3 MCP 管理

7.4 Git 同步

7.5 后台服务（Gateway）

7.6 运维与调试

八、连接 AI Agent（MCP + Skills）

8.1 支持的 Agent 列表

8.2 MCP 安装方式

8.3 Skills 安装

九、Web UI 使用指南

9.1 常用快捷键

9.2 主要功能区域

9.3 典型使用流程

十、知识库结构与模板

10.1 中文模板目录结构（默认）

10.2 INSTRUCTION.md 的作用

10.3 笔记即指令的最佳实践

十一、Git 同步配置

11.1 初始化 Git 同步

11.2 手动同步操作

11.3 同步配置说明

11.4 时光机：回滚操作

十二、安全机制

12.1 双层认证

12.2 路径沙箱

12.3 INSTRUCTION.md 写保护

12.4 原子写入

12.5 暴露到公网时的安全建议

十三、常见问题与排错

Q1：安装后 Tools 不出现

Q2：macOS 下 mindos 命令找不到

Q3：Windows 下命令启动失败

Q4：Cursor 中 MindOS Tools 被静默丢弃

Q5：服务启动失败，端口被占用

Q6：如何升级 MindOS

Q7：运行健康检查

十四、即将到来的功能

十五、社区与贡献

微信社区

参与贡献

致谢

附录：快速参考卡

最常用命令

最实用的 Agent 指令模板

快捷键速查

Q2：macOS 下 `mindos` 命令找不到