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

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

1. 项目概览
2. 核心理念与设计哲学
3. 系统架构
4. 功能特性详解
5. 安装与初始化
6. 配置参考
7. CLI 命令完整参考
8. 连接 AI Agent（MCP + Skills）
9. Web UI 使用指南
10. 知识库结构与模板
11. Git 同步配置
12. 安全机制
13. 常见问题与排错
14. 即将到来的功能
15. 社区与贡献

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

核心定位

技术栈简介

• 前端：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 服务端口

4.1 人类侧功能

GUI 工作台

• 浏览、编辑、搜索笔记的统一界面
• 统一搜索 + AI 入口（⌘K 搜索 / ⌘/ AI 助手）
• 专为人机共创设计的交互体验

内置 Agent 助手

• 在知识库上下文中直接对话
• 编辑内容无缝沉淀为可管理的知识条目

一键导入

• 拖拽文件即可导入（PDF、Word、文本等）
• Inline AI Organize 自动分析、分类、写入知识库
• 支持进度追踪和撤销操作

新手引导（Onboarding）

• 首次使用的分步引导体验
• 帮助新用户快速搭建知识库并连接第一个 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 全局安装

npm install -g @geminilight/mindos@latest

5.4 方式四：克隆源码

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

5.5 交互式初始化

mindos onboard

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

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

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

5.6 启动服务

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

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

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

   帮我把这些信息同步到我的 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 字段说明

6.3 配置管理命令

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 可更新单个字段，无需手动编辑文件

7.1 核心命令

7.2 知识库操作

所有知识库命令均支持 --json 标志，供 AI Agent 程序化调用。

7.3 MCP 管理

7.4 Git 同步

7.5 后台服务（Gateway）

7.6 运维与调试

8.1 支持的 Agent 列表

8.2 MCP 安装方式

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

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

方式二：一键全局安装

 
          
    
            
 
             
mindos mcp install -g -y
 
            
 
方式三：远程服务器安装
 
          
    
            
 
             
mindos mcp install --transport http --url http:// 
                <服务器ip>
                  :8781/mcp --token your-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 提供工作流能力的指导文档，根据语言偏好选择：

 
          
    
            
 
             
# 中文 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
 
            

9.1 常用快捷键

9.2 主要功能区域

首页 --- 知识库概览

• 显示所有空间（Space）和文件列表
• 快速访问最近编辑的文件
• 统计知识库整体信息

AI 对话面板（⌘/）

• 在知识库上下文中与 AI 对话
• AI 可直接读取、写入知识库中的文件
• 支持上传文件让 AI 分析并整理

Agent 工作台

• 管理所有已连接的 AI Agent
• 查看 Agent 的连接状态和 MCP 配置
• 监控 Agent 的操作历史

Echo（复盘与认知沉淀）

• 对话后复盘界面
• 将有价值的交互内容提炼为可复用的知识

9.3 典型使用流程

 
          
    
            
 
             
1. 打开 MindOS Web UI（mindos open） 
 
             
 
              
上传资料 → AI 自动整理到知识库
 
              
在 Cursor/Claude Code 等工具中编写代码
 
              
Agent 通过 MCP 自动读取知识库中的上下文
 
              
完成任务后，让 Agent 将经验沉淀回知识库
 
              
下次同类任务，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 执行。

推荐写法示例：

 
           
    
             
 
              
# 代码审查工作流 
 
              
步骤
 
              
 
               
读取 PR 描述和改动文件
 
               
检查代码风格是否符合 Configurations/code-style.md
 
               
验证测试覆盖率 ≥ 80%
 
               
生成审查意见，格式参考 Templates/code-review-template.md
 
               
将审查结论写入 Projects/{{项目名}}/reviews/ 目录
 
              
 
              
偏好
 
              
 
               
优先关注安全漏洞和性能问题
 
               
使用中文写审查意见
 
               
避免个人风格批评，聚焦于代码质量
 
              
 
             

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

11.1 初始化 Git 同步

 
            
    
              
 
               
# 交互式配置 
 
               
mindos sync init
 
               
配置完成后启用
 
               
mindos sync on
 
              

 
11.2 手动同步操作
 
            
    
              
 
               
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 写入了错误内容：

 
            
    
              
 
               
# 查看历史 
 
               
cd ~/MindOS && git log –oneline
 
               
回滚到某个提交
 
               
git revert 
                
 
               
或
 
               
git reset –hard 
                 
                  
                
 
              

12.1 双层认证

两者相互独立，可以单独启用。

12.2 路径沙箱

MCP Server 的所有文件操作被限制在 mindRoot 目录内，防止 Agent 越权访问系统文件。

12.3 INSTRUCTION.md 写保护

INSTRUCTION.md 是全局指令文件，被系统级写保护，Agent 无法修改它。这确保了 Agent 行为规范的稳定性，防止 AI 自我修改控制指令。

12.4 原子写入

所有文件写入操作使用原子写入策略（先写临时文件，再原子替换），防止因意外中断导致文件损坏。

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

如果你将 MindOS 部署到公网服务器：

1. 必须设置 authToken（用于 Agent/API 访问）
2. 建议设置 webPassword（用于 Web UI 访问）
3. 建议使用反向代理（Nginx/Caddy）添加 HTTPS
4. 考虑使用防火墙限制访问 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 环境变量。

解决：

# 找到 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 包装一层：

{ "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：服务启动失败，端口被占用

 
                 
    
                   
 
                    
# 检查端口占用 
 
                    
lsof -i :3456 lsof -i :8781
 
                    
停止 MindOS
 
                    
mindos stop
 
                    
或修改端口
 
                    
mindos config set port 3457 mindos config set mcpPort 8782 mindos restart
 
                   

Q6：如何升级 MindOS

 
                 
    
                   
 
                    
mindos update
 
                   
 
或手动升级：
 
                 
    
                   
 
                    
npm install -g @geminilight/mindos@latest 
 
                    
mindos restart
 
                   

Q7：运行健康检查

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

微信社区

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

参与贡献

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

 
欢迎提交 Issue 和 Pull Request。
 

致谢

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

最常用命令

 
                    
    
                      
 
                       
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 目录。
 
                      

 
快捷键速查