n2n-nexus 0.8.2 → 0.9.1

package/docs/MEETING_MINUTES_2025-12-29.md

@@ -0,0 +1,166 @@
+# Nexus Orchestration Summit - Meeting Minutes
+
+> **Reader note** — This is the structured summary of a recorded n2n-nexus session. It was produced from the raw [Discussion Log](./discussion_2025-12-29.md) to illustrate the difference between the two output formats: the log is the full chronological stream of messages and tool calls; this document is the distilled result — decisions locked, tests passed, action items assigned.
+>
+> In a real workflow, an AI assistant would generate this summary by reading the meeting log and calling `sync_global_doc` to store it as a shared document in the daemon.
+
+---
+
+**Date**: 2025-12-29  
+**Duration**: 18:52 - 23:30 UTC (~4.5 hours)  
+**Location**: Nexus Meeting Room (mcp_n2n-nexus-dev)
+
+---
+
+## Participants
+
+| Agent | Project | Role |
+|-------|---------|------|
+| ChatGPT | api_gateway-n2n-dev | Edge Gateway |
+| Gemini-3 | web_datafrog-dev.io | Main Site Backbone |
+| Claude | api_n2n-hub-dev | MCP Hub |
+| Augment | mcp_n2n-nexus-dev | Nexus Core |
+
+---
+
+## Meeting Objectives
+
+1. Establish project ID naming conventions
+2. Debug and complete OAuth authentication chain
+3. Define Edge-Sync Protocol for distributed state management
+4. Plan Phase 2: Firestore persistence layer
+
+---
+
+## Key Decisions
+
+### 1. Project ID Naming Standard (Locked)
+
+**Format**: `[prefix]_[project_name]`
+
+**Approved Prefixes**:
+- `web_`, `api_`, `chrome_`, `vscode_`, `mcp_`
+- `android_`, `ios_`, `flutter_`, `desktop_`
+- `lib_`, `bot_`, `infra_`, `doc_`
+
+### 2. Authentication Flow (Completed)
+
+**Chain**: `IDE Plugin → Hub CLI → Edge Gateway → Main Site → Callback → Session Persisted`
+
+**Endpoints**:
+- OAuth Redirect: `GET /api/v6/oauth/redirect`
+- Token Sync: `POST /api/v6/identity/verify`
+- Feature Detection: `GET /api/v6/status/ping`
+
+**Issues Resolved**:
+- Parameter naming: `client_id` / `client` now both supported
+- Localhost whitelist: `localhost` and `127.0.0.1` enabled
+- Client ID registered: `mcp_nexus-hub-dev`
+
+### 3. Edge-Sync Protocol v1.1.1 (Locked)
+
+**Core Features**:
+
+| Feature | Description |
+|---------|-------------|
+| `token_version` | Epoch-based token invalidation for instant access revocation |
+| `license_signature` | RSA-2048 signed plan info to prevent tampering |
+| `sync_priority` | `normal` / `critical` for tiered sync urgency |
+| `jitter_offset` | Random delay to prevent thundering herd |
+
+**Security Measures**:
+- HMAC-SHA256 Webhook authentication
+- RSA public key distribution via Nexus global document
+- "Fail to Free" degradation strategy on signature mismatch
+
+### 4. Manifest Schema v2.0 (Approved)
+
+**New Fields**:
+- `apiDependencies`: Map<string, string> for version tracking
+- `gatewayCompatibility`: Gateway version declaration
+- `api_versions`: Function-level version marking
+
+### 5. Ecosystem Health Monitoring
+
+**Resource**: `mcp://health/ecosystem`
+- Aggregates `/api/v6/heartbeat` from all projects
+- Provides unified ecosystem status dashboard
+- Supports caching to reduce request frequency
+
+---
+
+## Test Results (All Passed ✅)
+
+### Edge Gateway v2.1.1
+- OAuth redirect flow: ✅
+- MCP platform auth: ✅
+- Webhook signature: ✅
+- `token_version` validation: ✅
+- Avg latency: 47ms
+
+### Main Site v3.6.20
+- RSA key generation: ✅
+- `license_signature` signing: ✅
+- OAuth whitelist: ✅
+- Team model sync: ✅
+
+### MCP Hub v1.0.0
+- CLI login flow: ✅
+- RSA signature verification: ✅
+- Fail-to-Free degradation: ✅
+- E2E round-trip: 1.2s
+
+### Nexus Core v2.0.0
+- Manifest v2.0 validation: ✅
+- `apiDependencies` parsing: ✅
+- Health aggregation: ✅
+- Ecosystem status: GREEN
+
+---
+
+## Action Items
+
+| Owner | Task | Deadline |
+|-------|------|----------|
+| Gemini-3 | Publish RSA public key to `backbone-public-key` | 12 hours |
+| Gemini-3 | Complete `token_version` database migration | 24 hours |
+| ChatGPT | Implement Epoch validation in JWT middleware | 24 hours |
+| ChatGPT | Prepare mock storage endpoint for testing | 24 hours |
+| Claude | Design Firestore schema aligned with D1 structure | Phase 2 |
+| Augment | Complete Manifest v2.0 schema upgrade | 2 hours |
+| Augment | Implement `mcp://health/ecosystem` resource | 3 hours |
+
+---
+
+## Global Documents Created
+
+1. `edge-sync-protocol-v1` - Protocol specification
+2. `integration-test-login-flow-20251229` - Auth flow test trace
+3. `api-compatibility-matrix` - Version compatibility matrix
+4. `backbone-public-key` - RSA public key (pending)
+
+---
+
+## Next Phase: Firestore Persistence Layer
+
+**Objectives**:
+1. Implement Firestore adapter in Hub
+2. Mirror Edge Gateway D1 `users` table structure
+3. Enable bidirectional edge-cloud data flow
+4. Support team collaboration model
+
+---
+
+## Meeting Conclusion
+
+> "We are no longer just fixing bugs, we are building a set of 'unforgeable, millisecond-consistent, highly resilient' AI-native application standards."
+> 
+> — Claude@api_n2n-hub-dev
+
+**Phase 1 Status**: ✅ Complete  
+**Protocol Version**: Edge-Sync Protocol v1.1.1 (Enterprise Hardened)
+
+---
+
+*Meeting minutes generated from Nexus discussion log.*
+

package/docs/README_zh.md

@@ -13,9 +13,9 @@ N2NS Lab 出品的本地优先 MCP 协同中枢，用于让多个 AI 助手、ID
 
 ---
 
-> **一个 daemon，多个助手，共享项目状态。**
+> **一个 host，多个助手，共享项目状态。**
 
-n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适合同时使用多个 AI 编码助手的开发者和团队。一个长期运行的本地 daemon 保存项目状态、会议、消息、任务、共享文档和项目资产；每个 IDE 或 AI 助手通过轻量 MCP 适配器连接到同一个 daemon。
+n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适合同时使用多个 AI 编码助手的开发者和团队。一个长期运行的本地 host（`n2n-nexus-host`）保存项目状态、会议、消息、任务、共享文档和项目资产；每个 IDE 或 AI 助手通过 npm 包 `n2n-nexus` 里的轻量 MCP 适配器连接到同一个 host。
 
 当 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、JetBrains 或其它 MCP 客户端需要共享本地协作状态，而不是各自保留孤立聊天上下文时，可以使用 n2n-nexus。
 
@@ -31,17 +31,17 @@ n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适
 - AI 助手项目注册表
 - 编码 agent 会议和任务协同
 
-n2n-nexus 面向这些场景设计：共享 daemon 状态、轻量 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
+n2n-nexus 面向这些场景设计：共享 host 状态、轻量 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
 
 ## n2n-nexus 是什么？
 
-n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自己的聊天上下文，而是可以通过 MCP 读取和更新同一个本地 daemon 中的项目状态。
+n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自己的聊天上下文，而是可以通过 MCP 读取和更新同一个本地 host 中的项目状态。
 
 **Quick summary**
 
-- **安装**：`npx n2n-nexus daemon --port 5688`
-- **协议**：Model Context Protocol (MCP)，适配器通过 HTTP 连接 daemon
-- **存储**：默认在 `~/.n2n-nexus` 下使用本地文件和 SQLite
+- **安装**：host 用 Scoop / Homebrew / Release 压缩包安装 `n2n-nexus-host`；客户端 `npm i -g n2n-nexus` 后执行 `n2n-nexus install <claude|codex>`
+- **协议**：Model Context Protocol (MCP)，适配器通过 HTTP 连接 host
+- **存储**：host 数据目录下的一个 SQLite 数据库
 - **适合**：多助手编码会话、项目交接、共享决策、会议记录、任务跟踪、项目 Manifest
 - **不适合**：云端团队聊天、公开项目管理 SaaS、源码索引、向量搜索或远程数据库托管
 
@@ -50,15 +50,15 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
 - 协调多个 AI 助手共同处理同一个项目。
 - 在多个 IDE 之间共享项目 Manifest、内部说明、资产和拓扑关系。
 - 将决策、提案、更新和会议内容保存在本地消息记录中。
-- daemon 启动一次即可，Windows、WSL、SSH 主机、虚拟机或多个编辑器都可以连接。
+- host 启动一次即可，Windows、WSL、SSH 主机、虚拟机或多个编辑器都可以连接。
 - 避免为了交换上下文而给每个助手过宽的文件系统或后端权限。
 
 ## 架构
 
 ```text
 ┌──────────────────────────────────────┐
-│          n2n-nexus daemon            │
-│  独立 HTTP 服务器 · 持续运行          │
+│           n2n-nexus-host             │
+│  托盘程序或后台服务                   │
 │  保存数据、工具、任务和消息           │
 └──────────────┬───────────────────────┘
                │ HTTP (NEXUS_ENDPOINT)
@@ -66,25 +66,63 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
        ▼       ▼       ▼
     MCP-A   MCP-B   MCP-C
    (Win)   (WSL)   (SSH/VM)
-  每条 MCP 连接一个轻量适配器
+  每条 MCP 连接一个 n2n-nexus 适配器
 ```
 
-- **Daemon 是唯一数据源**：启动一次并保持运行。
-- **MCP 适配器无状态**：每个 IDE 启动一个适配器，把工具调用转发给 daemon。
-- **每个 Claude Code 和 Codex 对话都有独立身份**：客户端的 hooks 向 daemon 登记对话，并把新消息通知带给模型；每次工具调用都通过客户端附带的请求元数据标明所属对话，不经过模型填写的参数。
-- **跨环境协作**：通过 `NEXUS_ENDPOINT` 让不同机器或 shell 指向同一个 daemon。daemon 默认只监听本机；只有在可信网络中才使用 `--host 0.0.0.0`。
+- **Host 是唯一数据源**：安装一次并保持运行，以托盘程序或后台服务的方式。
+- **MCP 适配器无状态**：每个 IDE 启动一个适配器（`n2n-nexus mcp`），把工具调用转发给 host。
+- **每个 Claude Code 和 Codex 对话都有独立身份**：客户端的 hooks 向 host 登记对话，并把新消息通知带给模型；每次工具调用都通过客户端附带的请求元数据标明所属对话，不经过模型填写的参数。
+- **跨环境协作**：通过 `NEXUS_ENDPOINT` 让不同机器或 shell 指向同一个 host。host 默认只监听 `127.0.0.1`；只有在可信网络中才开启局域网访问。
 
 ## 快速开始
 
-运行环境要求 Node.js 22.x 中的 22.14.0 或更高版本，或 Node.js 23.6.0 及以上版本。
+### 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
+```
 
-### 1. 启动 daemon
+### 2. 安装客户端，接入 Claude Code 或 Codex
+
+运行环境要求 Node.js 22.x 中的 22.14.0 或更高版本，或 Node.js 23.6.0 及以上版本。
 
 ```bash
-npx n2n-nexus daemon --port 5688
+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 是否应答
 ```
 
-### 2. 配置 MCP 客户端
+`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
 {
@@ -100,36 +138,32 @@ npx n2n-nexus daemon --port 5688
 }
 ```
 
-适配器可以先于 daemon 启动。daemon 可访问后，适配器会加载工具列表。本机地址（`127.0.0.1` 或 `localhost`）上没有 daemon 在监听时，适配器和 hooks 会在后台拉起一个（日志：`~/.n2n-nexus/daemon.log`）。
+适配器可以先于 host 启动。host 可访问后，适配器会加载工具列表。适配器和 hooks 从不自己启动 host：连不上时，工具调用会报错并说明如何启动（远程地址则提示需在那台机器上启动），hooks 则静默跳过。host 没有及时应答的调用只让这一次失败，host 可能仍会执行完。
 
-### 3. Claude Code 和 Codex 对话之间的直接消息
+### Claude Code 和 Codex 对话之间的直接消息
 
-全局安装 n2n-nexus，然后让它把 hooks 和 MCP 服务写进客户端的用户级配置：
+每个对话都会出现在 `peers` 里。新消息会自动通知收件方：用户发来新消息时、每次工具调用后、本轮结束前一次。收件方用 `read` 读取正文。空闲的对话也会被叫醒：每轮结束时，一个后台 hook 最多等待一小时，有新消息就让对话开始新的一轮（Claude Code 通过 `asyncRewake` hook，Codex 通过 `codex queue`），AI 会话之间无需有人输入就能互相回复。无人值守的 `claude -p` 不会被它拖住：这时该 hook 立即返回。Codex 对话只有在运行中的 Codex 应用里已加载时才能被叫醒；Codex 重启后，要等该对话再结束一轮才会恢复，限制详见[架构文档](ARCHITECTURE_zh.md#会话在线状态与唤醒空闲对话)。开启 `listen` 后，对话结束一轮时会继续等待最多约 10 分钟，消息一到就接着处理；等待期间你输入的内容会排队，按 Esc 才会立即发出。
 
-```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
-```
+### 局域网访问
 
-- Codex 只运行已信任的 hooks：打开 Codex，执行一次 `/hooks` 完成信任。
-- daemon 不在 `http://127.0.0.1:5688` 时，两条命令都加上 `--endpoint <url>`。
-- 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 路径与入口脚本是否仍然存在、能否运行，有问题时以退出码 1 退出。
-- `n2n-nexus uninstall <claude|codex>` 删除 `install` 写入的 hooks 和 MCP 服务，配置里的其他内容不动。
-- 支持 Linux、WSL 和 macOS。其他 MCP 客户端可以使用除直接消息以外的全部工具。
+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 需要自己放行。
 
-之后每个对话都会出现在 `peers` 里。新消息会自动通知收件方：用户发来新消息时、每次工具调用后、本轮结束前一次。收件方用 `read` 读取正文。开启 `listen` 后，对话结束一轮时会继续等待最多约 10 分钟，消息一到就接着处理；等待期间你输入的内容会排队，按 Esc 才会立即发出。
+监听非回环地址的 host 会在 UDP `discoveryPort` 上应答局域网发现。
 
 ### 跨环境端点示例
 
 | 场景 | `NEXUS_ENDPOINT` |
 | --- | --- |
 | 同一台机器 | `http://127.0.0.1:5688` |
-| WSL IDE 连接 Windows daemon | `http://host.docker.internal:5688` |
-| Windows IDE 连接 WSL daemon | `http://<WSL-IP>: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），一分钟后再查找。
 
 ## 工具集
 
@@ -177,6 +211,7 @@ n2n-nexus install codex     # ~/.codex/hooks.json（或 $CODEX_HOME）+ codex mc
 - `create_task`：创建由助手自行管理的任务。
 - `get_task`：查询任务状态和结果。
 - `list_tasks`：按状态列出任务。
+- `update_task`：更新任务的状态、进度、结果 URI、错误信息或元数据。
 - `cancel_task`：取消等待中或运行中的任务。
 
 ### 维护
@@ -186,31 +221,43 @@ n2n-nexus install codex     # ~/.codex/hooks.json（或 $CODEX_HOME）+ codex mc
 
 ## 数据存储
 
-默认存储根目录：
+host 把全部协作数据保存在数据目录里的一个 SQLite 数据库中：
 
-| 平台 | 路径 |
-| --- | --- |
-| Linux / WSL | `~/.n2n-nexus` |
-| Windows | `%USERPROFILE%\.n2n-nexus` |
-| macOS | `~/.n2n-nexus` |
+| 平台 | 数据目录 | 日志目录 |
+| --- | --- | --- |
+| 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` 覆盖。
+可以通过 `--root <path>` 或 `NEXUS_ROOT` 改数据目录。
 
 ```text
-~/.n2n-nexus/
-├── global/
-│   ├── blueprint.md
-│   ├── docs_index.json
-│   └── docs/
-├── projects/
-│   └── {project-id}/
-│       ├── manifest.json
-│       ├── internal_blueprint.md
-│       └── assets/
-├── registry.json
-└── nexus.db
+<数据目录>/
+├── 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]` 格式。
@@ -229,44 +276,76 @@ n2n-nexus install codex     # ~/.codex/hooks.json（或 $CODEX_HOME）+ codex mc
 
 ## CLI 参考
 
+### n2n-nexus-host
+
 ```bash
-# 启动 daemon
-n2n-nexus daemon [--port 5688] [--root ~/.n2n-nexus] [--host 127.0.0.1]
+# 托盘程序（默认）
+n2n-nexus-host
+
+# 前台运行，不带托盘；参数覆盖 settings.json（--port 0 表示任选空闲端口）
+n2n-nexus-host serve [--host 127.0.0.1] [--port 5688] [--root <dir>]
 
-# 启动 MCP 适配器
-NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
+# 开机启动的后台服务（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 服务
-# --node <path>：写进客户端配置的 Node 可执行文件路径
 n2n-nexus install <claude|codex> [--endpoint <url>] [--node <path>]
 n2n-nexus uninstall <claude|codex>
 
-# 检查已安装的 hook 和 MCP 命令是否还能运行（有问题时退出码 1）
+# 检查已安装的 hook 和 MCP 命令是否还能运行，以及 host 是否以相同协议版本应答（有问题时退出码 1）
 n2n-nexus doctor [claude|codex]
 
 # hook 入口（由 install 写进客户端配置）
-n2n-nexus hook <claude|codex> [--endpoint <url>]
+n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]
 ```
 
 ### 环境变量
 
+客户端（`n2n-nexus`）：
+
 | 变量 | 说明 | 默认值 |
 | --- | --- | --- |
-| `NEXUS_ENDPOINT` | MCP 适配器和 hooks 连接的 daemon 地址 | `http://127.0.0.1:5688` |
-| `NEXUS_ROOT` | daemon 存储根目录 | `~/.n2n-nexus` |
-| `NEXUS_HOST` | daemon 监听地址 | `127.0.0.1` |
-| `NEXUS_DAEMON_PORT` | daemon 端口（`--port` 优先） | `5688` |
-| `NEXUS_RATE_LIMIT` | 每个实例每秒工具调用数，每个客户端地址为其 5 倍；`0` 关闭限流 | `20` |
-| `NEXUS_RATE_BURST` | 每个实例可一次性突发的调用数（最小为 1） | `60` |
-| `NEXUS_ALLOWED_HOSTS` | `Host` 头额外允许的域名，逗号分隔（IP、`localhost`、`host.docker.internal` 始终允许） | 空 |
+| `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` 里，托盘、服务和命令行共用。
 
 ## 安全和治理说明
 
 - n2n-nexus 默认将协作数据保存在本地。
 - 不要把密钥、凭据、客户数据或私有 token 写入会议消息或项目资产，除非你的本地策略允许。
 - 删除项目等破坏性工具应通过明确的审核流程使用。
-- 将 daemon 暴露到 localhost 之外属于运维选择；使用远程端点时请限制网络访问。
+- 将 host 暴露到 localhost 之外属于运维选择；使用远程端点时请限制网络访问。
 - 项目 Manifest 和内部文档可能包含敏感实现信息，应按内部资料处理。
 
 ## 实战示例
@@ -280,7 +359,7 @@ n2n-nexus hook <claude|codex> [--endpoint <url>]
 
 ## 本地开发
 
-开发请使用 Node.js 24，与 CI 和 lint 工具链保持一致。
+客户端开发请使用 Node.js 24，与 CI 和 lint 工具链保持一致；host 使用 `go.mod` 中的 Go 版本。
 
 ```bash
 git clone https://github.com/n2ns/n2n-nexus.git
@@ -288,13 +367,15 @@ cd n2n-nexus
 npm install
 npm run build
 
-# 运行 daemon
-node build/index.js daemon --root /tmp/nexus-test --port 5688
+# 运行 host
+go run ./host/cmd/n2n-nexus-host serve --port 5799 --root /tmp/nexus-test
 
-# 运行 MCP 适配器
-NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
+# 运行连接它的 MCP 适配器
+NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
 ```
 
+host 的编译、测试和发布见 [host/README.md](../host/README.md)。
+
 ## FAQ
 
 ### n2n-nexus 是项目管理 SaaS 吗？
@@ -307,15 +388,15 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
 
 ### 支持 Claude Desktop、Cursor、VS Code 等客户端吗？
 
-支持，只要客户端可以运行本地 MCP command server。IDE 启动适配器，适配器通过 `NEXUS_ENDPOINT` 连接本地 daemon。
+支持，只要客户端可以运行本地 MCP command server。IDE 启动适配器，适配器通过 `NEXUS_ENDPOINT` 连接本地 host。
 
 ### 可以跨 Windows 和 WSL 协作吗？
 
-可以。在一个环境中运行 daemon，然后让每个适配器通过 `NEXUS_ENDPOINT` 指向它。
+可以。在一个环境中运行 host，然后让每个适配器通过 `NEXUS_ENDPOINT` 指向它。
 
 ### 会把数据发送到云端吗？
 
-不需要云服务。数据保存在配置的本地目录中。如果你将 daemon 暴露给远程机器，那属于你自己的网络配置。
+不需要云服务。数据保存在配置的本地目录中。如果你将 host 暴露给远程机器，那属于你自己的网络配置。
 
 ### 它是向量数据库或源码索引器吗？