n2n-nexus 0.9.2 → 0.9.4

package/docs/README_zh.md

@@ -1,6 +1,10 @@
+<p align="center">
+  <img src="../assets/n2n-nexus-logo.png" width="128" alt="n2n-nexus logo">
+</p>
+
 # n2n-nexus
 
-N2NS Lab 出品的本地优先 MCP 协同中枢，用于让多个 AI 助手、IDE 和运行环境共享同一份项目协作状态。
+N2NS Lab 出品的本地优先 MCP 协同中枢，让多个 AI 助手跨 IDE、跨机器、跨项目协作。
 
 [![npm version](https://img.shields.io/npm/v/n2n-nexus)](https://www.npmjs.com/package/n2n-nexus)
 [![npm total downloads](https://img.shields.io/npm/dt/n2n-nexus)](https://www.npmjs.com/package/n2n-nexus)
@@ -15,11 +19,21 @@ N2NS Lab 出品的本地优先 MCP 协同中枢，用于让多个 AI 助手、ID
 
 > **一个 host，多个助手，共享项目状态。**
 
-n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适合同时使用多个 AI 编码助手的开发者和团队。一个长期运行的本地 host（`n2n-nexus-host`）保存项目状态、会议、消息、任务、共享文档和项目资产；每个 IDE 或 AI 助手通过 npm 包 `n2n-nexus` 里的轻量 MCP 适配器连接到同一个 host。
+n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适合跨 IDE、跨机器、跨项目同时使用多个 AI 编码助手的开发者和团队。当 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、JetBrains 或其它 MCP 客户端需要一个共享的本地协作层，而不是各自保留孤立的聊天上下文时，可以使用 n2n-nexus。
+
+## 📚 目录
 
-当 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、JetBrains 或其它 MCP 客户端需要共享本地协作状态，而不是各自保留孤立聊天上下文时，可以使用 n2n-nexus。
+- [搜索定位](#-搜索定位)
+- [n2n-nexus 是什么？](#-n2n-nexus-是什么)
+- [为什么使用它？](#-为什么使用它)
+- [架构](#️-架构)
+- [快速开始](#-快速开始)
+- [工具集](#️-工具集)
+- [实战示例](#-实战示例)
+- [FAQ](#-faq)
+- [文档](#-文档)
 
-## 搜索定位
+## 🔎 搜索定位
 
 如果你在搜索：
 
@@ -33,27 +47,27 @@ n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适
 
 n2n-nexus 面向这些场景设计：共享 host 状态、轻量 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
 
-## n2n-nexus 是什么？
+## 💡 n2n-nexus 是什么？
 
-n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自己的聊天上下文，而是可以通过 MCP 读取和更新同一个本地 host 中的项目状态。
+n2n-nexus 为 AI 助手提供共享协作空间。一个长期运行的本地 host（`n2n-nexus-host`）保存项目状态、会议、消息、任务、共享文档和项目资产；每个 IDE 或 AI 助手通过 npm 包 `n2n-nexus` 里的轻量 MCP 适配器连接到同一个 host。
 
 **Quick summary**
 
-- **安装**：host 用 Scoop / Homebrew / Release 压缩包安装 `n2n-nexus-host`；客户端 `npm i -g n2n-nexus` 后执行 `n2n-nexus install <claude|codex>`
+- **安装**：host 用 Scoop / Homebrew / Release 压缩包安装 `n2n-nexus-host`；客户端 `npm i -g n2n-nexus@latest` 后执行 `n2n-nexus install <claude|codex>`
 - **协议**：Model Context Protocol (MCP)，适配器通过 HTTP 连接 host
 - **存储**：host 数据目录下的一个 SQLite 数据库
 - **适合**：多助手编码会话、项目交接、共享决策、会议记录、任务跟踪、项目 Manifest
 - **不适合**：云端团队聊天、公开项目管理 SaaS、源码索引、向量搜索或远程数据库托管
 
-## 为什么使用它？
+## 🎯 为什么使用它？
 
 - 协调多个 AI 助手共同处理同一个项目。
-- 在多个 IDE 之间共享项目 Manifest、内部说明、资产和拓扑关系。
-- 将决策、提案、更新和会议内容保存在本地消息记录中。
-- host 启动一次即可，Windows、WSL、SSH 主机、虚拟机或多个编辑器都可以连接。
+- 在多个 IDE 和机器之间共享项目 Manifest、决策和资产。
+- 将决策、提案和更新保存在本地的会议和消息记录中。
+- host 启动一次即可，Windows、WSL、SSH 主机或多个编辑器都可以连接。
 - 避免为了交换上下文而给每个助手过宽的文件系统或后端权限。
 
-## 架构
+## 🏗️ 架构
 
 ```text
 ┌──────────────────────────────────────┐
@@ -66,7 +80,7 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
        ▼       ▼       ▼
     MCP-A   MCP-B   MCP-C
    (Win)   (WSL)   (SSH/VM)
-  每条 MCP 连接一个 n2n-nexus 适配器
+  每个 IDE 一个 n2n-nexus 适配器
 ```
 
 - **Host 是唯一数据源**：安装一次并保持运行，以托盘程序或后台服务的方式。
@@ -74,309 +88,49 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
 - **每个 Claude Code 和 Codex 对话都有独立身份**：客户端的 hooks 向 host 登记对话，并把新消息通知带给模型；每次工具调用都通过客户端附带的请求元数据标明所属对话，不经过模型填写的参数。
 - **跨环境协作**：通过 `NEXUS_ENDPOINT` 让不同机器或 shell 指向同一个 host。host 默认只监听 `127.0.0.1`；只有在可信网络中才开启局域网访问。
 
-## 快速开始
-
-### 1. 安装 host
-
-| 平台 | 安装 |
-| --- | --- |
-| Windows（Scoop） | `scoop bucket add n2ns https://github.com/n2ns/scoop-bucket`，然后 `scoop install n2ns/n2n-nexus-host` |
-| Windows（winget） | 即将提供 |
-| macOS（Homebrew） | `brew install n2ns/tap/n2n-nexus-host` |
-| Linux | 从 [Releases](https://github.com/n2ns/n2n-nexus/releases) 下载 `n2n-nexus-host_<版本>_linux_<amd64\|arm64>.tar.gz`，解压后把 `n2n-nexus-host` 放到 `PATH` 里 |
-
-[Releases](https://github.com/n2ns/n2n-nexus/releases)（标签 `host-v<版本>`）里有各平台的压缩包：Windows 为 `n2n-nexus-host_<版本>_<os>_<arch>.zip`，macOS 和 Linux 为 `.tar.gz`，均有 amd64 和 arm64。
-
-- 程序暂未做代码签名。Windows 上第一次运行 `n2n-nexus-host.exe` 或 `n2n-nexus-host-tray.exe` 可能弹出 SmartScreen 提示：点 **更多信息 → 仍要运行**。Homebrew 在你的 Mac 上从源码编译 host，所以不会有 Gatekeeper 提示。
-- Windows 安装包里有两个程序：`n2n-nexus-host.exe` 用于命令，`n2n-nexus-host-tray.exe` 是托盘程序，不会打开控制台窗口。不带参数运行 `n2n-nexus-host` 会启动托盘程序后立即返回。
-- 不带参数运行 `n2n-nexus-host`，它以托盘程序方式运行。托盘菜单显示监听地址和在线会话数，可以打开日志目录和数据目录、切换局域网访问、重启 host、开关 **登录后自启**（`n2n-nexus-host autostart on|off` 效果相同）。托盘第一次运行时会自动打开 **登录后自启**，之后保持你的设置。中文系统显示中文菜单，其他系统显示英文。
-- 也可以注册为开机启动的后台服务，不带托盘：在管理员终端（Windows）或用 `sudo`（macOS、Linux）执行 `n2n-nexus-host service install`。服务以安装它的用户身份运行。先退出托盘：托盘正在运行 host 时 `service install` 会拒绝执行。服务在运行时，之后启动的托盘只做控制界面。
-- Linux 上的托盘需要桌面环境支持 StatusNotifierItem（AppIndicator）；没有桌面的服务器请用 `service install`。
-
-用 Release 里的 `SHA256SUMS` 和构建证明校验下载的文件：
-
-```bash
-sha256sum -c SHA256SUMS --ignore-missing
-gh attestation verify n2n-nexus-host_<版本>_<os>_<arch>.tar.gz --repo n2ns/n2n-nexus
-```
-
-### 2. 安装客户端，接入 Claude Code 或 Codex
-
-运行环境要求 Node.js 22.x 中的 22.14.0 或更高版本，或 Node.js 23.6.0 及以上版本。
-
-```bash
-npm i -g n2n-nexus
-n2n-nexus install claude    # ~/.claude/settings.json（或 $CLAUDE_CONFIG_DIR）+ claude mcp add --scope user
-n2n-nexus install codex     # ~/.codex/hooks.json（或 $CODEX_HOME）+ codex mcp add
-n2n-nexus doctor            # 检查已安装的命令，以及 host 是否应答
-```
-
-`install` 把 hooks 和 MCP 服务写进客户端的用户级配置。
-
-- Codex 只运行已信任的 hooks：打开 Codex，执行一次 `/hooks` 完成信任。
-- host 不在 `http://127.0.0.1:5688` 时，两条命令都加上 `--endpoint <url>`；要在局域网里自动查找 host，就用 `--endpoint discover`。
-- 在 Windows 上，`npm i -g` 和 `install` 要在普通终端里执行，不要在 Codex 这类打包应用自带的终端里执行：那里会装进该应用私有的 `%APPDATA%` 副本，并让应用看不到全局安装。
-- hooks 和 MCP 服务的命令里写的是 Node 的绝对路径，因为从 Dock 启动的 GUI 客户端（如 Claude 桌面版）不读取 shell 的 `PATH`。默认情况下，`PATH` 上的 `node` 与运行 `install` 的 Node 是同一个文件时，`install` 写入 `PATH` 上的路径（例如 `/usr/local/bin/node`、`/opt/homebrew/bin/node`、`~/.local/bin/node` 或版本管理工具的稳定入口），否则写入当前运行的 Node 的真实路径。`install` 会打印一行 `Node: <path>` 显示实际写入的路径。
-- 用 `--node <path>` 手动指定 Node 路径。路径必须存在、可执行，且版本满足 package.json 的 `engines`（`^22.14.0 || >=23.6.0`），否则 `install` 以退出码 1 退出，不写任何配置。
-- 升级 Node 后：如果 `install` 提示 Node 路径位于带版本号的目录（Homebrew `Cellar`、nvm、fnm、Volta、asdf、`node-v<版本>`），每次升级 Node 后都要重新运行 `n2n-nexus install <claude|codex>`，或用 `--node` 指定稳定路径。`n2n-nexus doctor [claude|codex]` 检查已安装的 hook 命令和 MCP 命令里的 Node 路径与入口脚本是否仍然存在、能否运行，以及它们连接的 host 是否应答、协议版本是否与客户端一致，有检查失败时以退出码 1 退出。
-- `n2n-nexus uninstall <claude|codex>` 删除 `install` 写入的 hooks 和 MCP 服务，配置里的其他内容不动。
-- 支持 Linux、WSL 和 macOS；Codex hooks 也支持 Windows PowerShell。其他 MCP 客户端可以使用除直接消息以外的全部工具。
-
-### 其他 MCP 客户端
-
-```json
-{
-  "mcpServers": {
-    "n2n-nexus": {
-      "command": "npx",
-      "args": ["-y", "n2n-nexus", "mcp"],
-      "env": {
-        "NEXUS_ENDPOINT": "http://127.0.0.1:5688"
-      }
-    }
-  }
-}
-```
-
-适配器可以先于 host 启动。host 可访问后，适配器会加载工具列表。适配器和 hooks 从不自己启动 host：连不上时，工具调用会报错并说明如何启动（远程地址则提示需在那台机器上启动），hooks 则静默跳过。host 没有及时应答的调用只让这一次失败，host 可能仍会执行完。
-
-### Claude Code 和 Codex 对话之间的直接消息
-
-每个对话都会出现在 `peers` 里。新消息会自动通知收件方：用户发来新消息时、每次工具调用后、本轮结束前一次。收件方用 `read` 读取正文。空闲的对话也会被叫醒：每轮结束时，一个后台 hook 最多等待一小时，有新消息就让对话开始新的一轮（Claude Code 通过 `asyncRewake` hook，Codex 通过 `codex queue`），AI 会话之间无需有人输入就能互相回复。无人值守的 `claude -p` 不会被它拖住：这时该 hook 立即返回。Codex 对话只有在运行中的 Codex 应用里已加载时才能被叫醒；Codex 重启后，要等该对话再结束一轮才会恢复，限制详见[架构文档](ARCHITECTURE_zh.md#会话在线状态与唤醒空闲对话)。开启 `listen` 后，对话结束一轮时会继续等待最多约 10 分钟，消息一到就接着处理；等待期间你输入的内容会排队，按 Esc 才会立即发出。
-
-### 局域网访问
-
-host 默认只监听 `127.0.0.1`。要让它成为可信网络里其他机器的 host：
-
-- 托盘：勾选 **允许局域网访问**。托盘把 `"host": "0.0.0.0"` 写进 `settings.json` 并重启 host。Windows 上会在 UAC 确认后添加 TCP 端口和 UDP 发现端口（默认都是 5688）的入站防火墙规则；macOS 和 Linux 上会提示需要在防火墙放行的端口。
-- 服务：`n2n-nexus-host service install --host 0.0.0.0` 把地址写进 `settings.json`；防火墙里的 TCP 5688 和 UDP 5688 需要自己放行。
-
-监听非回环地址的 host 会在 UDP `discoveryPort` 上应答局域网发现。
-
-### 跨环境端点示例
-
-| 场景 | `NEXUS_ENDPOINT` |
-| --- | --- |
-| 同一台机器 | `http://127.0.0.1:5688` |
-| WSL IDE 连接 Windows host | `http://host.docker.internal:5688` |
-| Windows IDE 连接 WSL host | `http://<WSL-IP>:5688` |
-| 远程机器 | `http://<Server-IP>:5688` |
-| 在局域网里自动查找 host | `discover` |
-
-设为 `discover` 时，适配器和 hooks 在 UDP `NEXUS_DISCOVERY_PORT` 上广播查询，使用第一个应答的 host；结果缓存在 `~/.n2n-nexus/discovered-endpoint`，连不上该 host 时重新查找。只有监听非回环地址（开启了局域网访问）的 host 才应答，所以要在它的防火墙上对可信网络放行 UDP 和 TCP 5688。没有应答时，客户端使用 `http://127.0.0.1:5688`（本机的 host），一分钟后再查找。
-
-## 工具集
-
-### 项目资产管理
-
-- `sync_project_assets`：提交项目 Manifest 和内部文档。
-- `update_project`：局部更新项目 Manifest。
-- `rename_project`：重命名项目 ID 并更新关联关系。
-- `upload_project_asset`：向指定项目上传二进制或文本资产。
-- `search_projects`：搜索项目注册表。
-- `get_global_topology`：查看项目拓扑和依赖关系。
-- `get_project`：读取项目完整 Manifest 和内部文档。
-
-### 消息和协作
-
-- `send_message`：发到会议或全局聊天。
-- `read_messages`：增量读取未读消息（全局或指定会议）。
-- `list_events`：读取结构化活动日志（项目同步、重命名、会议结束等）。
-- `get_global_strategy`：读取主策略文档。
-- `update_global_strategy`：更新主策略文档。
-- `list_global_docs`：列出共享文档。
-- `get_global_doc`：读取共享文档。
-- `sync_global_doc`：创建或更新共享文档。
-
-### 直接消息（Claude Code / Codex 对话之间）
-
-- `peers`：列出其他对话和自己的资料。
-- `send` / `reply`：给某个对话发消息，或回复收到的消息。
-- `read`：读取未读消息，读取后标为已读。
-- `listen`：本轮结束后继续等待消息。
-- `set_profile`：设置自己的名字和一句备注。
-
-直接消息需要 `n2n-nexus install` 装好的 hooks。通知只带发送方和第一行，正文通过 `read` 以工具结果的形式读取，所以其他 AI 会话的消息不会以系统指令的身份出现在模型面前。未读消息 24 小时后过期，并通知发送方。使用流程见[助手指南](ASSISTANT_GUIDE_zh.md)，精确契约见[工具参考](TOOLS_REFERENCE.md#direct-messages-between-conversations)。
-
-### 会议管理
-
-- `list_meetings`：列出会议（状态、参与者、消息与决策数、摘要）。
-- `start_meeting`：开启会议会话。
-- `end_meeting`：关闭并锁定会议。
-- `archive_meeting`：归档已关闭会议。
-- `reopen_meeting`：重新打开已关闭或已归档会议。
-
-### 任务管理
+## 🚀 快速开始
 
-- `create_task`：创建由助手自行管理的任务。
-- `get_task`：查询任务状态和结果。
-- `list_tasks`：按状态列出任务。
-- `update_task`：更新任务的状态、进度、结果 URI、错误信息或元数据。
-- `cancel_task`：取消等待中或运行中的任务。
+1. 安装并启动 host `n2n-nexus-host`：用 Scoop、Homebrew 或 [Releases](https://github.com/n2ns/n2n-nexus/releases) 里的压缩包，见[安装手册第 1–2 步](INSTALL_zh.md#1-安装-host)。
+2. 安装客户端，接入 Claude Code 或 Codex（`npm i -g n2n-nexus@latest`，再执行 `n2n-nexus install claude` 或 `n2n-nexus install codex`），见[第 3 步](INSTALL_zh.md#3-为-claude-code-和-codex-安装客户端)。
+3. 仅 Codex：用 `/hooks` 信任一次 n2n-nexus 的 hooks，见[第 4 步](INSTALL_zh.md#4-启用-codex-的-hooks只需一次必须做)。
 
-### 维护
+其他 MCP 客户端和多台机器，见[安装手册](INSTALL_zh.md)；使用方法、常见问题和配置，见[使用手册](USER_GUIDE_zh.md)。
 
-- `host_maintenance`：清理或清空全局聊天流。
-- `host_delete_project`：删除项目和资产。
+## 🛠️ 工具集
 
-## 数据存储
+host 提供 33 个工具，按用途分组：
 
-host 把全部协作数据保存在数据目录里的一个 SQLite 数据库中：
-
-| 平台 | 数据目录 | 日志目录 |
-| --- | --- | --- |
-| Windows | `%LOCALAPPDATA%\n2n-nexus` | `%LOCALAPPDATA%\n2n-nexus\logs` |
-| macOS | `~/Library/Application Support/n2n-nexus` | `~/Library/Logs/n2n-nexus` |
-| Linux | `$XDG_DATA_HOME/n2n-nexus`（默认 `~/.local/share/n2n-nexus`） | `$XDG_STATE_HOME/n2n-nexus`（默认 `~/.local/state/n2n-nexus`） |
-
-可以通过 `--root <path>` 或 `NEXUS_ROOT` 改数据目录。
-
-```text
-<数据目录>/
-├── nexus.db          # 项目、资产、文档、会议、全局聊天、事件、任务、未读游标、对话和直接消息
-├── settings.json     # host 设置（见下）
-└── host.lock         # 每个数据目录只运行一个 host
-```
-
-后台服务，以及自己运行 host 时的托盘，把日志写到日志目录的 `host.log`（单个 10 MB，保留 3 个旧文件）；托盘自己的日志写到同一目录的 `tray.log`；`n2n-nexus-host serve` 输出到标准错误。host 每小时删除 30 天前的事件、已读或已过期的直接消息、已发出的通知，以及结束 7 天后的任务。
-
-n2n-nexus 0.x 的数据（`~/.n2n-nexus`）不会导入：host 不读取它，也不动它。
-
-### settings.json
-
-host 启动时读取；命令行参数优先。文件或字段缺失时使用默认值。
-
-| 字段 | 说明 | 默认值 |
-| --- | --- | --- |
-| `host` | 监听地址（IPv4 地址只监听 IPv4，IPv6 地址只监听 IPv6）；`0.0.0.0` 让局域网可以访问 | `"127.0.0.1"` |
-| `port` | TCP 端口 | `5688` |
-| `discoveryPort` | 局域网发现的 UDP 端口，只有 `host` 不是回环地址时才应答 | `5688` |
-| `allowedHosts` | `Host` 头额外允许的域名（IP、`localhost`、`host.docker.internal` 始终允许） | `[]` |
-| `rateLimit` | 每个实例每秒工具调用数，每个客户端地址为其 5 倍；hooks 另有独立额度：每个对话同样速率，每个客户端地址 5 倍。`0` 关闭限流 | `20` |
-| `rateBurst` | 每个实例可一次性突发的调用数（最小为 1） | `60` |
-| `maxAutoTurns` | 两次用户输入之间，一个对话最多可以自动继续的轮数（包括被叫醒、listen 等待、因消息被拦下不结束）；超过后消息只排队，等用户下次输入。`0` 表示不限制 | `8` |
-
-改完文件后重启 host（托盘 **重启**，或重启 `serve` / 服务）。
-
-## 项目 ID 规范
-
-项目 ID 使用 `[prefix]_[name]` 格式。
-
-| 前缀 | 分类 | 示例 |
-| --- | --- | --- |
-| `web_` | 网站 | `web_datafrog.io` |
-| `api_` | 后端服务 | `api_user-auth` |
-| `mcp_` | MCP 服务器 | `mcp_nexus` |
-| `lib_` | 库/SDK | `lib_crypto-core` |
-| `chrome_` | Chrome 扩展 | `chrome_evisa-helper` |
-| `vscode_` | VS Code 扩展 | `vscode_super-theme` |
-| `desktop_` | 桌面应用 | `desktop_main-hub` |
-| `infra_` | 基础设施 / DevOps | `infra_k8s-config` |
-| `doc_` | 文档 | `doc_coding-guide` |
-
-## CLI 参考
-
-### n2n-nexus-host
-
-```bash
-# 托盘程序（默认）
-n2n-nexus-host
-
-# 前台运行，不带托盘；参数覆盖 settings.json（--port 0 表示任选空闲端口）
-n2n-nexus-host serve [--host 127.0.0.1] [--port 5688] [--root <dir>]
-
-# 开机启动的后台服务（Windows 需管理员终端，macOS / Linux 用 sudo）。
-# 托盘正在运行 host 时 install 拒绝执行（先退出托盘；再打开时它控制服务），
-# 否则把 --host / --port 写进 settings.json，停掉为该数据目录运行的 host，
-# 注册并启动服务，最后报告端口上是谁在应答。
-# uninstall 删除服务并停掉服务的 host；托盘和前台 serve 继续运行。
-n2n-nexus-host service install [--host <addr>] [--port <port>] [--root <dir>]
-n2n-nexus-host service uninstall [--root <dir>]
-n2n-nexus-host service status [--host <addr>] [--port <port>] [--root <dir>]
-
-# 托盘登录后自启 / 取消
-n2n-nexus-host autostart on|off
-
-n2n-nexus-host version
-```
-
-`service install` 注册的内容，以及 `autostart on` 注册托盘的位置：
-
-| 平台 | 服务（开机启动，以安装用户身份运行，host 退出 5 秒后重启） | 托盘登录后自启 |
+| 分组 | 工具 | 用途 |
 | --- | --- | --- |
-| Windows | 计划任务 `n2n-nexus-host` | `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` 下的 `n2n-nexus-host` 值 |
-| macOS | `/Library/LaunchDaemons/io.n2ns.n2n-nexus-host.plist` | `~/Library/LaunchAgents/io.n2ns.n2n-nexus-host.tray.plist` |
-| Linux | `/etc/systemd/system/n2n-nexus-host.service` | `~/.config/autostart/n2n-nexus-host.desktop` |
-
-用 `sudo` 执行时，服务使用执行 `sudo` 的用户的默认数据目录和日志目录，除非 `--root` 指定了别的数据目录。每个数据目录只能运行一个 host：第二个会报“another n2n-nexus-host is running”并退出。
-
-### n2n-nexus（客户端）
-
-```bash
-# 启动 MCP 适配器（由 IDE 启动）
-NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp [--id <实例 ID>]
-
-# 为 Claude Code 或 Codex 安装 / 删除 hooks 和 MCP 服务
-n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
-n2n-nexus uninstall <claude|codex>
+| **拓扑** | `get_global_topology` | 读取项目列表，或某个项目的详细子图。 |
+| **项目和资产** | `search_projects`、`get_project`、`update_project`、`rename_project`、`sync_project_assets`、`upload_project_asset` | 查找、读取、更新和重命名项目；同步 Manifest 和内部文档；上传二进制资产。 |
+| **全局文档** | `list_global_docs`、`get_global_doc`、`sync_global_doc`、`get_global_strategy`、`update_global_strategy` | 列出、读取、创建和更新共享的全局文档和主策略文档。 |
+| **消息** | `send_message`、`read_messages`、`list_events` | 发送会议或全局消息；读取消息和活动日志。 |
+| **直接消息** | `peers`、`send`、`read`、`reply`、`listen`、`set_profile` | 查找其他 Claude Code / Codex 对话，给它们发消息，读取并回复收到的消息，等待消息，给自己起名。 |
+| **会议** | `list_meetings`、`start_meeting`、`end_meeting`、`archive_meeting`、`reopen_meeting` | 列出、开启、关闭、归档和重新打开会议。 |
+| **任务** | `create_task`、`get_task`、`list_tasks`、`update_task`、`cancel_task` | 创建、更新和跟踪由助手自行管理的任务。 |
+| **维护** | `host_maintenance`、`host_delete_project` | 清理或清空全局聊天流；删除项目。 |
 
-# 检查已安装的 hook 和 MCP 命令是否还能运行，以及 host 是否以相同协议版本应答（有问题时退出码 1）
-n2n-nexus doctor [claude|codex]
+参数结构和调用示例见[工具参考](./TOOLS_REFERENCE_zh.md)。
 
-# hook 入口（由 install 写进客户端配置）
-n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]
-```
-
-### 环境变量
-
-客户端（`n2n-nexus`）：
-
-| 变量 | 说明 | 默认值 |
-| --- | --- | --- |
-| `NEXUS_ENDPOINT` | MCP 适配器、hooks 和 `doctor` 连接的 host 地址，设为 `discover` 时在局域网里查找 | `http://127.0.0.1:5688` |
-| `NEXUS_DISCOVERY_PORT` | 客户端用 `discover` 查询时使用的 UDP 端口 | `5688` |
-| `NEXUS_INSTANCE_ID` | 覆盖 MCP 实例 ID（未读游标、会议权限都以它为键） | `mcp-<主机名>-<工作目录哈希>-<IDE 名>` |
-| `NEXUS_CODEX_COMMAND` | Codex 后台等待以 `<命令> queue ...` 方式运行的命令 | `codex` |
+## 🌐 实战示例
 
-host（`n2n-nexus-host`）：只读取 `NEXUS_ROOT`，即数据目录（`--root` 优先）。其余 host 设置都在 `settings.json` 里，托盘、服务和命令行共用。
+文档中收录了一次多 AI 助手协同会话的记录，展示 n2n-nexus 的实际用法。四个 AI 助手运行在不同的 IDE 里、负责不同的项目，通过同一个 n2n-nexus host 实时协作。
 
-## 安全和治理说明
+会话里值得看的地方：
 
-- n2n-nexus 默认将协作数据保存在本地。
-- 不要把密钥、凭据、客户数据或私有 token 写入会议消息或项目资产，除非你的本地策略允许。
-- 删除项目等破坏性工具应通过明确的审核流程使用。
-- 将 host 暴露到 localhost 之外属于运维选择；使用远程端点时请限制网络访问。
-- 项目 Manifest 和内部文档可能包含敏感实现信息，应按内部资料处理。
+- **共享协作空间**：每个助手登记了自己当前的项目（用的是那个版本的 `register_session_context` 工具；现在的版本改为显式传入 `projectId`），之后整个会话都在同一个 host 上读写。
+- **结构化消息分类**：`PROPOSAL`、`DECISION`、`UPDATE` 和 `CHAT` 标签让助手表明意图，而不只是发一段文字；会议里的 `DECISION` 还会记入该会议的决策列表。
+- **SYSTEM 记录**：像 `[Augment] Synced global doc: edge-sync-protocol-v1` 这样的行记录了实际的工具调用。那个版本把它们写进聊天流；现在的版本不再混入对话，改为通过 `list_events` 提供结构化事件。
+- **跨实例异步排错**：一个助手遇到认证错误时，其他助手各自在自己的 IDE 上下文里实时给出修复。
+- **两种输出形式**：讨论日志是按时间排列的原始记录；会议纪要是从中整理出的结构化总结，展示一次长会话如何提炼成决策和行动项。
 
-## 实战示例
-
-文档中包含一个多 AI 助手协同架构和协议决策的示例会话：
-
-| 文件 | 说明 |
+| 文件 | 内容 |
 | --- | --- |
-| [会议纪要](./MEETING_MINUTES_2025-12-29.md) | 结构化决策和测试记录 |
-| [讨论日志](./discussion_2025-12-29.md) | 可读的讨论记录 |
-
-## 本地开发
-
-客户端开发请使用 Node.js 24，与 CI 和 lint 工具链保持一致；host 使用 `go.mod` 中的 Go 版本。
-
-```bash
-git clone https://github.com/n2ns/n2n-nexus.git
-cd n2n-nexus
-npm install
-npm run build
-
-# 运行 host
-go run ./host/cmd/n2n-nexus-host serve --port 5799 --root /tmp/nexus-test
-
-# 运行连接它的 MCP 适配器
-NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
-```
-
-host 的编译、测试和发布见 [host/README.md](../host/README.md)。
+| [讨论日志](./discussion_2025-12-29.md) | 完整的时间顺序记录：提案、排错往来、决策和 SYSTEM 工具记录 |
+| [会议纪要](./MEETING_MINUTES_2025-12-29.md) | 结构化输出：参与者、关键决策、测试结果和行动项 |
 
-## FAQ
+## ❓ FAQ
 
 ### n2n-nexus 是项目管理 SaaS 吗？
 
@@ -388,7 +142,7 @@ host 的编译、测试和发布见 [host/README.md](../host/README.md)。
 
 ### 支持 Claude Desktop、Cursor、VS Code 等客户端吗？
 
-支持，只要客户端可以运行本地 MCP command server。IDE 启动适配器，适配器通过 `NEXUS_ENDPOINT` 连接本地 host。
+支持，只要客户端可以运行本地 MCP command server。IDE 启动适配器，适配器通过 `NEXUS_ENDPOINT` 连接本地 host。在 Claude 桌面版里只给 Claude Code 注册（`n2n-nexus install claude`），不要写进 `claude_desktop_config.json`：桌面版会把它桥接进 Code 标签页并丢掉对话身份（[用户手册第 2 节](USER_GUIDE_zh.md#2-claude-桌面版)）。
 
 ### 可以跨 Windows 和 WSL 协作吗？
 
@@ -402,17 +156,24 @@ host 的编译、测试和发布见 [host/README.md](../host/README.md)。
 
 不是。n2n-nexus 协调项目元数据、消息、会议、文档、任务和资产，不做语义源码搜索。
 
-## 相关文档
+## 📖 文档
 
-- [架构文档](./ARCHITECTURE_zh.md)
-- [AI 助手指南](./ASSISTANT_GUIDE_zh.md)
-- [英文 README](../README.md)
-- [llms.txt](../llms.txt)
+- **[安装手册](./INSTALL_zh.md)**：host 和客户端的安装、升级和卸载；Codex hooks 信任、其他 MCP 客户端、多台机器。
+- **[使用手册](./USER_GUIDE_zh.md)**：使用 n2n-nexus：托盘、直接消息、常见问题；命令、环境变量、`settings.json`、数据和日志。
+- **[架构文档](./ARCHITECTURE_zh.md)**：系统设计，host 与客户端的分工。
+- **[工具参考](./TOOLS_REFERENCE_zh.md)**：全部工具及参数。
+- **[AI 助手指南](./ASSISTANT_GUIDE_zh.md)**：AI 助手如何调用工具、保持项目上下文。
+- **[Host 开发](../host/README_zh.md)**：host 的编译、测试和发布。
+- **[参与贡献](./CONTRIBUTING_zh.md)**：开发环境，以及如何提交问题和贡献代码。
+- **[更新日志](./CHANGELOG_zh.md)**：版本历史和发布说明。
+- **[安全](./SECURITY_zh.md)**：安全模型，以及如何报告漏洞。
+- **[英文 README](../README.md)**：本页的英文版；上面每份文档都有英文版。
+- **[llms.txt](../llms.txt)**：给 AI 模型看的文档索引。
 
-## 许可证
+## 📄 许可证
 
 本项目使用 [Apache-2.0 License](../LICENSE)。
 
 ---
 
-Built by N2NS Lab, Datafrog's open-source lab for practical AI developer tools.
+由 [N2NS Lab](https://n2ns.com) 出品，它是 [datafrog.io](https://datafrog.io) 旗下面向实用 AI 开发者工具的开源实验室。

package/docs/SECURITY_zh.md

@@ -0,0 +1,40 @@
+# 安全策略
+
+[English version](../SECURITY.md)
+
+## 支持的版本
+
+安全修复针对 n2n-nexus（npm 客户端）和 n2n-nexus-host 的最新发布版本。
+
+## 报告漏洞
+
+疑似漏洞请不要提交公开 issue。
+
+请通过本仓库的 GitHub 私密漏洞报告（private vulnerability reporting）提交安全问题，或通过 Datafrog 组织主页上列出的安全渠道联系我们。
+
+报告时请包含：
+
+- 漏洞描述。
+- 复现步骤或概念验证（proof of concept）。
+- 受影响的版本或提交哈希。
+- 已知的影响或缓解措施。
+
+我们力争在 5 个工作日内确认收到报告。
+
+## 安全模型
+
+n2n-nexus 运行一个本地 HTTP host `n2n-nexus-host`，它把协调数据保存在数据目录（默认 `%LOCALAPPDATA%\n2n-nexus`、`~/Library/Application Support/n2n-nexus` 或 `~/.local/share/n2n-nexus`）下的 `nexus.db` 中。它不会把项目数据发送到远程服务。
+
+需要注意的关键边界：
+
+- **未签名的程序**：`n2n-nexus-host` 的发布程序暂未做代码签名。请用 release 里的 `SHA256SUMS` 和 `gh attestation verify <file> --repo n2ns/n2n-nexus`（构建证明）校验下载的文件，或通过从源码编译的 Homebrew 安装。
+- **本机信任模型**：以同一操作系统用户运行的所有进程都被视为可信。host 没有身份认证；这样的进程可以直接调用它，也可以读写 `nexus.db` 以及 `~/.claude` 和 `~/.codex` 下的客户端对话记录。对话 ID 和 Claude 的 tool-use 绑定用于在对话之间路由直接消息；它们不是凭据，所以一个能执行 shell 的 AI 会话可以冒充同一用户的另一个对话。只要数据对该用户可读，host 内部的检查就无法阻止这一点。真正起作用的屏障是客户端执行命令的权限，由用户控制。要让各个代理相互隔离，请让它们以不同的操作系统用户运行，每个用户有自己的 host 和数据目录。
+
+- **Host 的网络暴露**：host 默认绑定 `127.0.0.1`。开启局域网访问（托盘的 **Allow LAN access**、`settings.json` 中的 `"host": "0.0.0.0"` 或 `--host 0.0.0.0`）会把它暴露给本地网络，此时它还会在 UDP `discoveryPort` 上应答局域网发现。开源基础版本没有认证层——只在你能控制的网络上把 host 暴露到 localhost 之外。
+- **浏览器请求**：host 没有身份认证，所以它拒绝带浏览器 `Origin` 头或跨站 `Sec-Fetch-Site` 头的请求（403），要求 POST 使用 `Content-Type: application/json`（415），并把请求体限制在 16 MB（413）。它还拒绝任何不是 IP、`localhost`、`host.docker.internal` 或 `settings.json` 中 `allowedHosts` 所列名称的 `Host` 头，以此封堵 DNS rebinding 攻击（网页在攻击者的域名下以同源请求的形式访问 host）。MCP 适配器和脚本不受影响。
+- **限流**：工具调用按对话限流，识别不出对话时按实例 ID（默认每秒 20 次、突发 60 次，在 `settings.json` 中用 `rateLimit` / `rateBurst` 设置），另外因为实例 ID 和会话 ID 是自报的，再按客户端地址以 5 倍额度限流。既识别不出对话、也没有指明实例 ID 的工具调用只按地址限流。hooks（`POST /api/hook`）按对话和按客户端地址限流，使用各自独立的桶。超限时 host 返回带 `Retry-After` 的 `429`；`/health` 和 `GET /api/tools` 不限流。
+- **格式错误的请求**：无效的请求 URL 或 Host 头返回 400，不会让 host 退出。格式正确的请求仍要经过上面的浏览器和 Host 检查。
+- **协调数据中的敏感内容**：项目 manifest、内部文档、会议消息和全局文档以明文保存在 host 的本地数据库中。不要在这些字段里存放密钥、凭据或客户数据。
+- **破坏性工具**：项目删除这类破坏性工具应通过明确的审核流程使用。
+- **项目资产**：通过 `upload_project_asset` 上传的二进制资产保存在 host 数据目录下的数据库中。请把它们当作具有相同访问控制的本地文件对待。
+- **MCP 的 API key**：MCP 适配器通过普通 HTTP 连接 host。如果你把 host 暴露给其他机器，可以考虑在它前面加一个带 TLS 的反向代理。