@geminilight/mindos 0.5.44 → 0.5.45

package/README.md

@@ -15,6 +15,8 @@
 <p align="center">
   <a href="https://tianfuwang.tech/MindOS"><img src="https://img.shields.io/badge/Website-MindOS-0ea5e9.svg?style=for-the-badge" alt="Website"></a>
   <a href="https://www.npmjs.com/package/@geminilight/mindos"><img src="https://img.shields.io/npm/v/@geminilight/mindos.svg?style=for-the-badge&color=f59e0b" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@geminilight/mindos"><img src="https://img.shields.io/npm/dw/@geminilight/mindos.svg?style=for-the-badge&color=10b981" alt="npm downloads"></a>
+  <a href="https://github.com/GeminiLight/MindOS/stargazers"><img src="https://img.shields.io/github/stars/GeminiLight/MindOS.svg?style=for-the-badge&color=f59e0b" alt="GitHub Stars"></a>
   <a href="#wechat"><img src="https://img.shields.io/badge/WeChat-Group-07C160.svg?style=for-the-badge&logo=wechat&logoColor=white" alt="WeChat"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-6366f1.svg?style=for-the-badge" alt="MIT License"></a>
 </p>
@@ -84,14 +86,15 @@ All that experience from your conversations — gone the moment you close the wi
 
 - **Security**: Bearer Token auth, path sandboxing, INSTRUCTION.md write-protection, atomic writes.
 - **Knowledge Graph**: dynamically parses and visualizes inter-file references and dependencies.
+- **Backlinks View**: displays all files that reference the current file, helping you understand how a note fits into the knowledge network.
 - **Git Time Machine**: Git auto-sync (commit/push/pull), records every edit by both humans and Agents. One-click rollback, cross-device sync.
+- **Desktop App**: native macOS/Windows/Linux app with system tray, auto-start, and local process management.
 
 <details>
 <summary><strong>Coming Soon</strong></summary>
 
 - [ ] ACP (Agent Communication Protocol): connect external Agents (e.g., Claude Code, Cursor) and turn the knowledge base into a multi-Agent collaboration hub
 - [ ] Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses
-- [ ] Backlinks View: display all files that reference the current file, helping you understand how a note fits into the knowledge network
 - [ ] Agent Inspector: render Agent operation logs as a filterable timeline to audit every tool call in detail
 
 </details>
@@ -131,84 +134,10 @@ npm link   # registers the `mindos` command globally
 mindos onboard
 ```
 
-The setup wizard will guide you through:
-1. Knowledge base path → default `~/MindOS`
-2. Choose template (en / zh / empty / custom)
-3. Ports (Web UI + MCP)
-4. Auth token (auto-generated or passphrase-seeded)
-5. Web UI password (optional)
-6. AI Provider (Anthropic / OpenAI) + API Key — or **skip** to configure later via `mindos config set`
-7. Start mode — **Background service** (recommended, auto-starts on boot) or Foreground
-
-Config is saved to `~/.mindos/config.json` automatically.
-
-<!-- For Agents: Before running setup, if the user has not provided LLM configuration, ask them:
-1. AI Provider — `anthropic` or `openai` (compatible)?
-2. API Key — the key for the chosen provider
-3. Custom Base URL? — only needed for proxies or OpenAI-compatible endpoints; skip if using official API
-4. Model ID — or use the default
-Or skip the wizard and edit `~/.mindos/config.json` manually (see Config Reference below).
--->
-
-<details>
-<summary>Config Reference (~/.mindos/config.json)</summary>
-
-```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-5.4", "baseUrl": "" }
-    }
-  },
-  "sync": {
-    "enabled": true,
-    "provider": "git",
-    "remote": "origin",
-    "branch": "main",
-    "autoCommitInterval": 30,
-    "autoPullInterval": 300
-  }
-}
-```
-
-| Field | Default | Description |
-| :--- | :--- | :--- |
-| `mindRoot` | `~/MindOS` | **Required**. Absolute path to the knowledge base root. |
-| `port` | `3456` | Optional. Web app port. |
-| `mcpPort` | `8781` | Optional. MCP server port. |
-| `authToken` | — | Optional. Protects App `/api/*` and MCP `/mcp` with bearer token auth. For Agent / MCP clients. Recommended when exposed to a network. |
-| `webPassword` | — | Optional. Protects the web UI with a login page. For browser access. Independent from `authToken`. |
-| `startMode` | `start` | Start mode: `daemon` (background service, auto-starts on boot), `start` (foreground), or `dev`. |
-| `ai.provider` | `anthropic` | Active provider: `anthropic` or `openai`. |
-| `ai.providers.anthropic.apiKey` | — | Anthropic API key. |
-| `ai.providers.anthropic.model` | `claude-sonnet-4-6` | Anthropic model ID. |
-| `ai.providers.openai.apiKey` | — | OpenAI API key. |
-| `ai.providers.openai.model` | `gpt-5.4` | OpenAI model ID. |
-| `ai.providers.openai.baseUrl` | — | Optional. Custom endpoint for proxy or OpenAI-compatible APIs. |
-| `sync.enabled` | `false` | Enable/disable automatic Git sync. |
-| `sync.provider` | `git` | Sync provider (currently only `git`). |
-| `sync.remote` | `origin` | Git remote name. |
-| `sync.branch` | `main` | Git branch to sync. |
-| `sync.autoCommitInterval` | `30` | Seconds after file change to auto-commit+push. |
-| `sync.autoPullInterval` | `300` | Seconds between auto-pull from remote. |
-
-Multiple providers can be configured simultaneously — switch between them by changing `ai.provider`. Shell env vars (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) take precedence over config file values.
-
-</details>
-
-> [!NOTE]
-> If you want the MindOS GUI to be reachable from other devices, make sure the port is open in firewall/security-group settings and bound to an accessible host/network interface.
+The setup wizard guides you through knowledge base path, template, ports, auth, AI provider, and start mode — all with sensible defaults. Config is saved to `~/.mindos/config.json`. See **[docs/en/configuration.md](docs/en/configuration.md)** for all fields.
 
 > [!TIP]
-> If you chose "Background service" during onboard, MindOS is installed as a background OS service and starts automatically — no need to run `mindos start` manually. Run `mindos update` to upgrade to the latest version.
+> Choose "Background service" during onboard for auto-start on boot. Run `mindos update` anytime to upgrade.
 
 Open the Web UI in your browser:
 
@@ -228,124 +157,24 @@ mindos open
 
 ### 4. Make Any Agent Ready (MCP + Skills)
 
-#### 4.1 Configure MindOS MCP
-
-<!-- For Agents: Register MindOS MCP as global (user-level) config by default, so all projects share the same knowledge base. -->
-
-Run one command to auto-install MCP config into your Agent:
+**MCP** (connection) — one command to auto-install:
 
 ```bash
-mindos mcp install
+mindos mcp install        # interactive
+mindos mcp install -g -y  # one-shot, global scope
 ```
 
-Supports Claude Code, Cursor, Windsurf, Cline, Trae, Gemini CLI, and more — interactively guides you through agent, scope, transport, and token.
-
-**Local (Agent and MindOS on the same machine)**
-
-Use `stdio` transport — no server process needed, most reliable:
+**Skills** (workflow) — install one based on your language:
 
 ```bash
-# Interactive
-mindos mcp install
-
-# One-shot, global scope (shared across all projects)
-mindos mcp install -g -y
-```
-
-**Remote (Agent on a different machine)**
-
-Use `http` transport — MindOS must be running (`mindos start`) on the remote machine:
-
-```bash
-mindos mcp install--transport http --url http://<server-ip>:8781/mcp --token your-token -g
-```
-
-> [!NOTE]
-> For remote access, ensure port `8781` is open in your firewall/security-group.
-
-> Add `-g` to install globally — MCP config is shared across all projects instead of the current directory only.
-
-> The MCP port defaults to `8781`. To use a different port, run `mindos onboard` and set `mcpPort`.
-
-<details>
-<summary>Manual config (JSON snippets)</summary>
-
-**Local via stdio** (no server process needed):
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "type": "stdio",
-      "command": "mindos",
-      "args": ["mcp"],
-      "env": { "MCP_TRANSPORT": "stdio" }
-    }
-  }
-}
-```
-
-**Local via URL:**
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "url": "http://localhost:8781/mcp",
-      "headers": { "Authorization": "Bearer your-token" }
-    }
-  }
-}
-```
-
-**Remote:**
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "url": "http://<server-ip>:8781/mcp",
-      "headers": { "Authorization": "Bearer your-token" }
-    }
-  }
-}
+npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y      # English
+npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y   # Chinese
 ```
 
-Each Agent stores config in a different file — see the **MCP Config Path** column in the [Supported Agents](#-supported-agents) table for exact paths.
-
-</details>
-
-#### 4.2 Install MindOS Skills
-
-| Skill | Description |
-|-------|-------------|
-| `mindos` | Knowledge base operation guide (English) — read/write notes, search, manage SOPs, maintain Profiles |
-| `mindos-zh` | Knowledge base operation guide (Chinese) — same capabilities, Chinese interface |
-
-Install one skill only (choose based on your preferred language):
-
-```bash
-# English
-npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y
-
-# Chinese (optional)
-npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y
-```
-
-MCP = connection capability, Skills = workflow capability. Enabling both gives the complete MindOS agent experience.
-
-#### 4.3 Common Pitfalls
-
-- Only MCP, no Skills: tools are callable, but best-practice workflows are missing.
-- Only Skills, no MCP: workflow guidance exists, but the Agent cannot operate your local knowledge base.
-- `MIND_ROOT` is not an absolute path: MCP tool calls will fail.
-- No `authToken` set: your API and MCP server are exposed on the network without protection.
-- No `webPassword` set: anyone who can reach your server can access the web UI.
+> For remote access, manual JSON config, and common pitfalls, see **[docs/en/supported-agents.md](docs/en/supported-agents.md)**.
 
 ## ⚙️ How It Works
 
-A fleeting idea becomes shared intelligence through three interlocking loops:
-
 ```mermaid
 graph LR
     H["👤 Human<br/><sub>thinks · reviews · evolves</sub>"]
@@ -367,42 +196,30 @@ graph LR
 
 > **Both sides evolve.** Humans gain new insights from accumulated knowledge; Agents extract SOPs and get smarter. MindOS sits at the center — the shared second brain that grows with every interaction.
 
-**Collaboration Loop (Human + Multi-Agent)**
-
-1. Human reviews and updates notes/SOPs in the MindOS GUI (single source of truth).
-2. Other Agent clients (OpenClaw, Claude Code, Cursor, etc.) connect through MCP and read the same memory/context.
-3. With Skills enabled, those Agents execute workflows and SOP tasks in a guided way.
-4. Execution results are written back to MindOS so humans can audit and refine continuously.
-
-**Who is this for?**
-
-- **Independent Developer** — Store personal SOPs, tech stack preferences, and project context in MindOS. Any Agent instantly inherits your work habits.
-- **Knowledge Worker** — Manage research materials with bi-directional links. Your AI assistant answers questions grounded in your full context, not generic knowledge.
-- **Team Collaboration** — Share a MindOS knowledge base across team members as a single source of truth. Humans and Agents read from the same playbook, keeping everyone aligned.
-- **Automated Agent Operations** — Write standard workflows as Agent-Ready documents. Agents execute directly, humans audit the results.
-
 ---
 
 ## 🤝 Supported Agents
 
-| Agent | MCP | Skills | MCP Config Path |
-|:------|:---:|:------:|:----------------|
-| MindOS Agent | ✅ | ✅ | Built-in (no config needed) |
-| OpenClaw | ✅ | ✅ | `~/.openclaw/openclaw.json` or `~/.openclaw/mcp.json` |
-| Claude Desktop | ✅ | ✅ | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Code | ✅ | ✅ | `~/.claude.json` (global) or `.mcp.json` (project) |
-| CodeBuddy | ✅ | ✅ | `~/.claude-internal/.claude.json` (global) |
-| Cursor | ✅ | ✅ | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |
-| Windsurf | ✅ | ✅ | `~/.codeium/windsurf/mcp_config.json` |
-| Cline | ✅ | ✅ | macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`; Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
-| Trae | ✅ | ✅ | `~/.trae/mcp.json` (global) or `.trae/mcp.json` (project) |
-| Gemini CLI | ✅ | ✅ | `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project) |
-| GitHub Copilot | ✅ | ✅ | `.vscode/mcp.json` (project) or VS Code User `settings.json` (global) |
-| iFlow | ✅ | ✅ | iFlow platform MCP configuration panel |
+> Full list with MCP config paths and manual setup: **[docs/en/supported-agents.md](docs/en/supported-agents.md)**
+
+| Agent | MCP | Skills |
+|:------|:---:|:------:|
+| MindOS Agent | ✅ | ✅ |
+| OpenClaw | ✅ | ✅ |
+| Claude Desktop / Code | ✅ | ✅ |
+| CodeBuddy | ✅ | ✅ |
+| Cursor | ✅ | ✅ |
+| Windsurf | ✅ | ✅ |
+| Cline | ✅ | ✅ |
+| Trae | ✅ | ✅ |
+| Gemini CLI | ✅ | ✅ |
+| GitHub Copilot | ✅ | ✅ |
+| iFlow | ✅ | ✅ |
 
 ---
 
-## 📁 Project Structure
+<details>
+<summary><strong>📁 Project Structure</strong></summary>
 
 ```bash
 MindOS/
@@ -420,56 +237,24 @@ MindOS/
 └── mind/             # Your private knowledge base (default: ~/MindOS/mind, customizable on onboard)
 ```
 
----
+</details>
 
 ## ⌨️ CLI Commands
 
+> Full command reference: **[docs/en/cli-commands.md](docs/en/cli-commands.md)**
+
 | Command | Description |
 | :--- | :--- |
 | `mindos onboard` | Interactive setup (config, template, start mode) |
-| `mindos start` | Start app + MCP server (foreground, production mode) |
-| `mindos start --daemon` | Install + start as a background OS service (survives terminal close, auto-restarts on crash) |
-| `mindos dev` | Start app + MCP server (dev mode, hot reload) |
-| `mindos dev --turbopack` | Dev mode with Turbopack (faster HMR) |
-| `mindos open` | Open the Web UI in the default browser |
-| `mindos stop` | Stop running MindOS processes |
-| `mindos restart` | Stop then start again |
-| `mindos build` | Manually build for production |
-| `mindos mcp` | Start MCP server only |
-| `mindos token` | Show auth token and per-agent MCP config snippets |
-| `mindos sync` | Show sync status (alias for `sync status`) |
-| `mindos sync init` | Interactive setup for Git remote sync |
-| `mindos sync status` | Show sync status: last sync, unpushed commits, conflicts |
-| `mindos sync now` | Manually trigger a full sync (commit + push + pull) |
-| `mindos sync on` | Enable automatic sync |
-| `mindos sync off` | Disable automatic sync |
-| `mindos sync conflicts` | List unresolved conflict files |
-| `mindos gateway install` | Install background service (systemd on Linux, LaunchAgent on macOS) |
-| `mindos gateway uninstall` | Remove background service |
-| `mindos gateway start` | Start the background service |
-| `mindos gateway stop` | Stop the background service |
-| `mindos gateway status` | Show background service status |
-| `mindos gateway logs` | Tail background service logs |
-| `mindos doctor` | Health check (config, ports, build, daemon status) |
-| `mindos update` | Update MindOS to the latest version |
-| `mindos uninstall` | Fully uninstall MindOS (stop, remove daemon, npm uninstall) |
-| `mindos logs` | Tail service logs (`~/.mindos/mindos.log`) |
-| `mindos config show` | Print current config (API keys masked) |
-| `mindos config validate` | Validate config file |
-| `mindos config set <key> <val>` | Update a single config field |
-| `mindos` | Start using the mode saved in `~/.mindos/config.json` |
-
----
-
-## ⌨️ Keyboard Shortcuts
-
-| Shortcut | Function |
-| :--- | :--- |
-| `⌘ + K` | Global Search |
-| `⌘ + /` | Call AI Assistant / Sidebar |
-| `E` | Press `E` in View mode to quickly enter Edit mode |
-| `⌘ + S` | Save current edit |
-| `Esc` | Cancel edit / Close dialog |
+| `mindos start` | Start app + MCP server (foreground) |
+| `mindos start --daemon` | Start as background OS service |
+| `mindos open` | Open Web UI in browser |
+| `mindos mcp install` | Auto-install MCP config into your Agent |
+| `mindos sync init` | Setup Git remote sync |
+| `mindos update` | Update to latest version |
+| `mindos doctor` | Health check |
+
+**Keyboard shortcuts:** `⌘K` Search · `⌘/` AI Assistant · `E` Edit · `⌘S` Save · `Esc` Close
 
 ---
 

package/README_zh.md

@@ -15,6 +15,8 @@
 <p align="center">
   <a href="https://tianfuwang.tech/MindOS"><img src="https://img.shields.io/badge/Website-MindOS-0ea5e9.svg?style=for-the-badge" alt="Website"></a>
   <a href="https://www.npmjs.com/package/@geminilight/mindos"><img src="https://img.shields.io/npm/v/@geminilight/mindos.svg?style=for-the-badge&color=f59e0b" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/@geminilight/mindos"><img src="https://img.shields.io/npm/dw/@geminilight/mindos.svg?style=for-the-badge&color=10b981" alt="npm downloads"></a>
+  <a href="https://github.com/GeminiLight/MindOS/stargazers"><img src="https://img.shields.io/github/stars/GeminiLight/MindOS.svg?style=for-the-badge&color=f59e0b" alt="GitHub Stars"></a>
   <a href="#wechat"><img src="https://img.shields.io/badge/WeChat-群聊-07C160.svg?style=for-the-badge&logo=wechat&logoColor=white" alt="WeChat"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-6366f1.svg?style=for-the-badge" alt="MIT License"></a>
 </p>
@@ -84,14 +86,15 @@ Agent 记了什么、记对没有，用户无从知晓。**MindOS 将每次读
 
 - **安全防线**：Bearer Token 认证、路径沙箱、INSTRUCTION.md 写保护、原子写入。
 - **知识图谱**：动态解析并可视化文件间的引用与依赖关系。
+- **反向链接视图**：展示所有引用当前文件的反向链接，理解笔记在知识网络中的位置。
 - **Git 时光机**：Git 自动同步（commit/push/pull），记录人类与 Agent 的每次编辑历史，一键回滚，跨设备同步。
+- **桌面客户端**：原生 macOS/Windows/Linux 应用，系统托盘、开机自启、本地进程管理。
 
 <details>
 <summary><strong>即将到来</strong></summary>
 
 - [ ] ACP（Agent Communication Protocol）：连接外部 Agent（如 Claude Code、Cursor），让知识库成为多 Agent 协作的中枢
 - [ ] RAG 深度集成：基于知识库内容的检索增强生成，让 AI 回答更精准、更有上下文
-- [ ] 反向链接视图（Backlinks）：展示所有引用当前文件的反向链接，理解笔记在知识网络中的位置
 - [ ] Agent 审计面板（Agent Inspector）：将 Agent 操作日志渲染为可筛选的时间线，审查每次工具调用的详情
 
 </details>
@@ -128,89 +131,13 @@ npm link   # 将 mindos 命令注册为全局命令
 ### 2. 交互式配置
 
 ```bash
-mindos onboard --install-daemon
+mindos onboard
 ```
 
-> `--install-daemon`：配置完成后，自动将 MindOS 安装为后台 OS 服务（关闭终端仍运行，崩溃自动重启）。
-
-配置向导将引导你完成：
-1. 知识库路径 → 默认 `~/MindOS`
-2. 选择模板（en / zh / empty / custom）
-3. 端口配置（Web UI + MCP）
-4. Auth token（自动生成或口令派生）
-5. Web UI 访问密码（可选）
-6. 配置 AI Provider（Anthropic / OpenAI）+ API Key — 或选择 **skip**，稍后通过 `mindos config set` 补填
-7. 启动模式 — **后台服务**（推荐，开机自启）或前台运行
-
-配置自动保存到 `~/.mindos/config.json`。
-
-<!-- For Agents: 运行 onboard 前，如果用户未提供 LLM 配置，请询问：
-1. AI Provider — `anthropic` 还是 `openai`（兼容）？
-2. API Key — 对应 Provider 的密钥
-3. 自定义 Base URL？— 仅代理或 OpenAI 兼容端点需要；使用官方 API 则跳过
-4. Model ID — 或使用默认值
-或跳过向导，手动编辑 `~/.mindos/config.json`（参考下方配置参考）。
--->
-
-<details>
-<summary>配置参考（~/.mindos/config.json）</summary>
-
-```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-5.4", "baseUrl": "" }
-    }
-  },
-  "sync": {
-    "enabled": true,
-    "provider": "git",
-    "remote": "origin",
-    "branch": "main",
-    "autoCommitInterval": 30,
-    "autoPullInterval": 300
-  }
-}
-```
-
-| 字段 | 默认值 | 说明 |
-| :--- | :--- | :--- |
-| `mindRoot` | `~/MindOS` | **必填**。知识库根目录的绝对路径 |
-| `port` | `3456` | 可选。Web 服务端口 |
-| `mcpPort` | `8781` | 可选。MCP 服务端口 |
-| `authToken` | — | 可选。保护 App `/api/*` 和 MCP `/mcp` 的 Bearer Token 认证。供 Agent / MCP 客户端使用，暴露到网络时建议设置 |
-| `webPassword` | — | 可选。为 Web UI 添加登录密码保护。供浏览器访问，与 `authToken` 相互独立 |
-| `startMode` | `start` | 启动模式：`daemon`（后台服务，开机自启）、`start`（前台）或 `dev` |
-| `ai.provider` | `anthropic` | 当前使用的 provider：`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-5.4` | OpenAI 模型 ID |
-| `ai.providers.openai.baseUrl` | — | 可选。用于代理或 OpenAI 兼容 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 的间隔秒数 |
-
-多个 provider 可以同时配置，切换时只需修改 `ai.provider` 字段，无需重新填写 API Key。Shell 环境变量（`ANTHROPIC_API_KEY`、`OPENAI_API_KEY` 等）优先级高于配置文件。
-
-</details>
-
-> [!NOTE]
-> 如果你希望其他设备也能访问 MindOS GUI，请确保端口已在防火墙/安全组中放行，并绑定到可访问的主机地址/网卡。
+配置向导会引导你完成知识库路径、模板、端口、认证、AI 服务商、启动模式等配置——所有选项都有合理默认值。配置自动保存到 `~/.mindos/config.json`。完整字段说明见 **[docs/zh/configuration.md](docs/zh/configuration.md)**。
 
 > [!TIP]
-> 使用 `--install-daemon` 时，MindOS 会作为后台 OS 服务安装并自动启动，无需手动执行 `mindos start`。如果跳过了该参数，运行 `mindos start` 手动启动，或运行 `mindos update` 升级到最新版本。
+> 选择"后台服务"模式可开机自启。随时运行 `mindos update` 升级到最新版本。
 
 在浏览器中打开 Web UI：
 
@@ -230,124 +157,24 @@ mindos open
 
 ### 4. 让任意 Agent 可用（MCP + Skills）
 
-#### 4.1 配置 MindOS MCP
-
-<!-- For Agents: MindOS MCP 默认注册为全局（user-level）配置，使所有项目共享同一知识库。-->
-
-一条命令自动将 MCP 配置写入 Agent：
-
-```bash
-mindos mcp install
-```
-
-支持 Claude Code、Cursor、Windsurf、Cline、Trae、Gemini CLI 等主流 Agent，交互式引导完成 agent、scope、transport 和 token 的配置。
-
-**本机访问（Agent 和 MindOS 在同一台机器）**
-
-使用 `stdio` transport — 无需启动服务进程，最稳定：
-
-```bash
-# 交互式
-mindos mcp install
-
-# 一键安装，全局（所有项目共享）
-mindos mcp install -g -y
-```
-
-**远程访问（Agent 在另一台机器）**
-
-使用 `http` transport — 远程机器上需先运行 `mindos start`：
+**MCP**（连接能力）— 一条命令自动安装：
 
 ```bash
-mindos mcp install --transport http --url http://<服务器IP>:8781/mcp --token your-token -g
-```
-
-> [!NOTE]
-> 远程访问时，请确保端口 `8781` 已在防火墙/安全组中放行。
-
-> 加 `-g` 表示全局安装 — MCP 配置写入用户级配置文件，所有项目共享，而非仅当前目录。
-
-> MCP 端口默认为 `8781`。如需修改，运行 `mindos onboard` 设置 `mcpPort`。
-
-<details>
-<summary>手动配置（JSON 片段）</summary>
-
-**本机 stdio**（无需启动服务进程）：
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "type": "stdio",
-      "command": "mindos",
-      "args": ["mcp"],
-      "env": { "MCP_TRANSPORT": "stdio" }
-    }
-  }
-}
-```
-
-**本机 URL：**
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "url": "http://localhost:8781/mcp",
-      "headers": { "Authorization": "Bearer your-token" }
-    }
-  }
-}
+mindos mcp install        # 交互式
+mindos mcp install -g -y  # 一键全局安装
 ```
 
-**远程：**
-
-```json
-{
-  "mcpServers": {
-    "mindos": {
-      "url": "http://<服务器IP>:8781/mcp",
-      "headers": { "Authorization": "Bearer your-token" }
-    }
-  }
-}
-```
-
-各 Agent 的配置文件路径不同，详见下方 [支持的 Agent](#-支持的-agent) 表格中的 **MCP 配置文件路径** 列。
-
-</details>
-
-#### 4.2 安装 MindOS Skills
-
-| Skill | 说明 |
-|-------|------|
-| `mindos` | 知识库操作指南（英文）— 读写笔记、搜索、管理 SOP、维护 Profile |
-| `mindos-zh` | 知识库操作指南（中文）— 相同能力，中文交互 |
-
-根据你的语言偏好选择其一安装即可：
+**Skills**（工作流能力）— 根据语言偏好选择其一：
 
 ```bash
-# 英文
-npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y
-
-# 中文（可选）
-npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y
+npx skills add https://github.com/GeminiLight/MindOS --skill mindos -g -y      # 英文
+npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y   # 中文
 ```
 
-MCP = 连接能力，Skills = 工作流能力；两者都开启后体验完整。
-
-#### 4.3 常见误区
-
-- 只配 MCP，不装 Skills：能调用工具，但缺少最佳实践指引。
-- 只装 Skills，不配 MCP：有流程提示，但无法操作本地知识库。
-- `MIND_ROOT` 不是绝对路径：MCP 工具调用会失败。
-- 未设置 `authToken`：API 和 MCP 服务暴露在网络上，存在安全风险。
-- 未设置 `webPassword`：任何能访问服务器的人都可以打开 Web UI。
+> 远程配置、手动 JSON 片段、常见误区等详见 **[docs/zh/supported-agents.md](docs/zh/supported-agents.md)**。
 
 ## ⚙️ 运作机制
 
-一个零散想法如何变成所有 Agent 共享的智慧——三个联动飞轮：
-
 ```mermaid
 graph LR
     H["👤 人类<br/><sub>思考 · 审查 · 进化</sub>"]
@@ -369,42 +196,30 @@ graph LR
 
 > **双向进化。** 人类从积累的知识中获得新洞察；Agent 提炼 SOP 变得更强。MindOS 居中——随每次交互持续成长的共享第二大脑。
 
-**协作闭环（人类 + 多 Agent）**
-
-1. 人类在 MindOS GUI 中审阅并更新笔记/SOP（单一事实来源）。
-2. 其他 Agent 客户端（OpenClaw、Claude Code、Cursor 等）通过 MCP 读取同一份记忆与上下文。
-3. 启用 Skills 后，Agent 按工作流指引执行任务与 SOP。
-4. 执行结果回写到 MindOS，供人类持续审查与迭代。
-
-**适用人群：**
-
-- **AI 独立开发者** — 将个人 SOP、技术栈偏好、项目上下文存入 MindOS，任何 Agent 即插即用你的工作习惯。
-- **知识工作者** — 用双链笔记管理研究资料，AI 助手基于你的完整上下文回答问题，而非泛泛而谈。
-- **团队协作** — 团队成员共享同一个 MindOS 知识库作为 Single Source of Truth，人与 Agent 读同一份剧本，保持对齐。
-- **Agent 自动运维** — 将标准流程写成笔记即指令的文档，Agent 直接执行，人类审计结果。
-
 ---
 
 ## 🤝 支持的 Agent
 
-| Agent | MCP | Skills | MCP 配置文件路径 |
-|:------|:---:|:------:|:-----------------|
-| MindOS Agent | ✅ | ✅ | 内置（无需配置） |
-| OpenClaw | ✅ | ✅ | `~/.openclaw/openclaw.json` 或 `~/.openclaw/mcp.json` |
-| Claude Desktop | ✅ | ✅ | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` |
-| Claude Code | ✅ | ✅ | `~/.claude.json`（全局）或 `.mcp.json`（项目级） |
-| CodeBuddy | ✅ | ✅ | `~/.claude-internal/.claude.json`（全局） |
-| Cursor | ✅ | ✅ | `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（项目级） |
-| Windsurf | ✅ | ✅ | `~/.codeium/windsurf/mcp_config.json` |
-| Cline | ✅ | ✅ | macOS: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`；Linux: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` |
-| Trae | ✅ | ✅ | `~/.trae/mcp.json`（全局）或 `.trae/mcp.json`（项目级） |
-| Gemini CLI | ✅ | ✅ | `~/.gemini/settings.json`（全局）或 `.gemini/settings.json`（项目级） |
-| GitHub Copilot | ✅ | ✅ | `.vscode/mcp.json`（项目级）或 VS Code 用户 `settings.json`（全局） |
-| iFlow | ✅ | ✅ | iFlow 平台 MCP 配置面板 |
+> 完整列表及 MCP 配置路径、手动配置方法：**[docs/zh/supported-agents.md](docs/zh/supported-agents.md)**
+
+| Agent | MCP | Skills |
+|:------|:---:|:------:|
+| MindOS Agent | ✅ | ✅ |
+| OpenClaw | ✅ | ✅ |
+| Claude Desktop / Code | ✅ | ✅ |
+| CodeBuddy | ✅ | ✅ |
+| Cursor | ✅ | ✅ |
+| Windsurf | ✅ | ✅ |
+| Cline | ✅ | ✅ |
+| Trae | ✅ | ✅ |
+| Gemini CLI | ✅ | ✅ |
+| GitHub Copilot | ✅ | ✅ |
+| iFlow | ✅ | ✅ |
 
 ---
 
-## 📁 项目架构
+<details>
+<summary><strong>📁 项目架构</strong></summary>
 
 ```bash
 MindOS/
@@ -422,57 +237,24 @@ MindOS/
 └── my-mind/          # 你的私有知识库（默认路径，onboard 时可自定义）
 ```
 
----
+</details>
 
 ## ⌨️ CLI 命令
 
+> 完整命令参考：**[docs/zh/cli-commands.md](docs/zh/cli-commands.md)**
+
 | 命令 | 说明 |
 | :--- | :--- |
 | `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 mcp` | 仅启动 MCP 服务 |
-| `mindos token` | 查看当前 Auth token 及 MCP 配置片段 |
-| `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` | 列出未解决的冲突文件 |
-| `mindos gateway install` | 安装后台服务（Linux 用 systemd，macOS 用 LaunchAgent） |
-| `mindos gateway uninstall` | 卸载后台服务 |
-| `mindos gateway start` | 启动后台服务 |
-| `mindos gateway stop` | 停止后台服务 |
-| `mindos gateway status` | 查看后台服务状态 |
-| `mindos gateway logs` | 实时查看服务日志 |
-| `mindos doctor` | 健康检查（配置、端口、构建、daemon 状态） |
-| `mindos update` | 更新 MindOS 到最新版本 |
-| `mindos uninstall` | 完整卸载 MindOS（停止进程、移除 daemon、npm 卸载） |
-| `mindos logs` | 实时查看服务日志（`~/.mindos/mindos.log`） |
-| `mindos config show` | 查看当前配置（API Key 脱敏显示） |
-| `mindos config validate` | 验证配置文件 |
-| `mindos config set <key> <val>` | 更新单个配置字段 |
-| `mindos` | 使用 `~/.mindos/config.json` 中保存的模式启动 |
-
----
-
-## ⌨️ 快捷键指南
-
-| 快捷键 | 功能 |
-| :--- | :--- |
-| `⌘ + K` | 全局搜索知识库 |
-| `⌘ + /` | 唤起 AI 问答 / 侧边栏 |
-| `E` | 在阅读界面按 `E` 快速进入编辑模式 |
-| `⌘ + S` | 保存当前编辑 |
-| `Esc` | 取消编辑 / 关闭弹窗 |
+| `mindos start` | 前台启动 app + MCP 服务 |
+| `mindos start --daemon` | 以后台 OS 服务方式启动 |
+| `mindos open` | 在浏览器中打开 Web UI |
+| `mindos mcp install` | 自动将 MCP 配置写入 Agent |
+| `mindos sync init` | 配置 Git 远程同步 |
+| `mindos update` | 更新到最新版本 |
+| `mindos doctor` | 健康检查 |
+
+**快捷键：** `⌘K` 搜索 · `⌘/` AI 助手 · `E` 编辑 · `⌘S` 保存 · `Esc` 关闭
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.5.44",
+  "version": "0.5.45",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",