n2n-nexus 0.9.2 → 0.9.4

package/docs/CONTRIBUTING_zh.md

@@ -0,0 +1,51 @@
+# 参与贡献
+
+[English version](../CONTRIBUTING.md)
+
+感谢你帮助改进 n2n-nexus。
+
+## 开发环境
+
+使用 Node.js 24（与 CI 和 lint 工具链一致），host 使用 `go.mod` 中指定的 Go 版本（`npm test` 也会构建 Go 测试 host）。发布的客户端要求 Node.js 22.14+（22.x 系列）或 Node.js 23.6+。
+
+```bash
+npm install
+npm run build
+npm test
+go vet ./...
+go test ./host/...
+npm run host:build-test && npm run test:conformance
+```
+
+pre-commit 运行 lint。pre-push 通过 lefthook 运行 `go vet`、`go test ./host/...`、构建、`npm test`、测试 host 构建和一致性测试。
+
+完整的本地运行：
+
+```bash
+# 启动一个 host
+go run ./host/cmd/n2n-nexus-host serve --root /tmp/nexus-test --port 5799
+
+# 启动 MCP 适配器（另开一个终端）
+NEXUS_ENDPOINT=http://127.0.0.1:5799 node build/index.js mcp
+```
+
+## Pull Request 规范
+
+- 改动保持集中，便于评审。
+- 行为改动要新增或更新测试：Go 测试放在 host 代码旁边，客户端能通过 HTTP 观察到的行为在 `tests/conformance/` 里写一致性测试，客户端测试放在 `tests/`。
+- 修改 HTTP API、数据库 schema 或 `contract/` 中的协议之前，先更新 `docs/ARCHITECTURE.md`。
+- AI 助手能看到的工具行为发生变化时，更新 `docs/ASSISTANT_GUIDE.md` 和 `docs/ASSISTANT_GUIDE_zh.md`。
+- 提交 PR 前运行 `npm run build && npm test`、`go test ./host/...` 和 `npm run test:conformance`。
+
+## 提交规范
+
+- 不要提交 host 数据目录、`tests/tmp/`、`host/bin/` 或生成的 `node_modules/`。
+- 在 PR 描述中说明用户可见的行为变化。
+
+## 架构说明
+
+系统设计见 `docs/ARCHITECTURE.md`，host 的构建和发布见 `host/README.md`。
+
+## 更新日志
+
+用户可见的变更应记录在 `CHANGELOG.md` 中。

package/docs/INSTALL.md

@@ -0,0 +1,146 @@
+# n2n-nexus installation guide
+
+[中文版](INSTALL_zh.md)
+
+This guide installs n2n-nexus so that your AI coding sessions (Claude Code and Codex) can share projects and documents and message each other. Once it is installed, the [User guide](USER_GUIDE.md) covers using it.
+
+## What you install
+
+| Part | What it is | Where |
+|---|---|---|
+| `n2n-nexus-host` | The host: one program that keeps all shared data and passes messages between sessions. Run it on one machine. | Windows, macOS or Linux |
+| `n2n-nexus` (npm) | The client: the MCP server your AI clients start, plus the hooks that tell the host which conversation is which. | Every machine with Claude Code or Codex |
+
+## 1. Install the host
+
+| Platform | Install |
+|---|---|
+| Windows (Scoop) | `scoop bucket add n2ns https://github.com/n2ns/scoop-bucket`, then `scoop install n2ns/n2n-nexus-host` |
+| Windows (winget) | coming soon |
+| macOS (Homebrew) | `brew install n2ns/tap/n2n-nexus-host` |
+| Linux | download `n2n-nexus-host_<version>_linux_<amd64\|arm64>.tar.gz` from [Releases](https://github.com/n2ns/n2n-nexus/releases), extract it and put `n2n-nexus-host` on your `PATH` |
+
+[Releases](https://github.com/n2ns/n2n-nexus/releases) (tags `host-v<version>`) has the archives for every platform: `n2n-nexus-host_<version>_<os>_<arch>.zip` for Windows and `.tar.gz` for macOS and Linux, amd64 and arm64. Verify a download against the release's `SHA256SUMS` and its build provenance:
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+gh attestation verify n2n-nexus-host_<version>_<os>_<arch>.tar.gz --repo n2ns/n2n-nexus
+```
+
+Good to know:
+
+- The binaries are not code-signed yet. On Windows, the first start of `n2n-nexus-host.exe` or `n2n-nexus-host-tray.exe` may show a SmartScreen warning: click **More info → Run anyway**. Homebrew builds the host from source on your Mac, so there is no Gatekeeper prompt.
+- On Windows the package has two programs: `n2n-nexus-host.exe` for commands, and `n2n-nexus-host-tray.exe`, the tray, which opens no console window. `n2n-nexus-host` without arguments starts the tray program and returns.
+
+## 2. Start the host
+
+Start it in one of two ways:
+
+- **Tray app**: run `n2n-nexus-host` without arguments. The first time the tray runs it turns **Start at login** on; after that it stays as you set it. What the tray menu does: [User guide](USER_GUIDE.md#1-the-tray).
+- **Background service** (starts at boot, no login needed, no tray): `n2n-nexus-host service install` from an elevated terminal (Windows) or with `sudo` (macOS, Linux). The service runs as the user who installed it. Quit the tray first: `service install` refuses while the tray runs the host. While the service runs, a tray started later only controls it.
+
+On Linux the tray needs a desktop with StatusNotifierItem (AppIndicator) support; on a server, use `service install`. Where the service and the start-at-login entry are registered on each OS: [Architecture](ARCHITECTURE.md#tray-and-service-per-os).
+
+## 3. Install the client for Claude Code and Codex
+
+Requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
+
+```bash
+npm i -g n2n-nexus@latest
+n2n-nexus install claude     # ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR) + claude mcp add --scope user
+n2n-nexus install codex      # ~/.codex/hooks.json (or $CODEX_HOME) + codex mcp add
+n2n-nexus doctor             # checks everything, including that the host answers
+```
+
+`install` writes the hooks and the MCP server into the client's user configuration. Start a **new** conversation afterwards: running conversations do not load the new MCP server.
+
+The MCP server updates itself: it runs `n2n-nexus@latest` through npm's npx, so every new conversation asks npm for the latest version and starts it (a new release is downloaded once, then started from npm's cache). The hooks run the globally installed package, which you update yourself (step 8).
+
+- Pass `--endpoint <url>` to both commands when the host is not at `http://127.0.0.1:5688`, or `--endpoint discover` to find a host on the LAN (step 6).
+- On Windows, run `npm i -g` and `install` from a regular terminal, not from the terminal of a packaged app such as Codex: that terminal installs into the app's private copy of `%APPDATA%`, which hides the global install from the app.
+- The hooks and the MCP server command use an absolute Node path, because GUI clients started from the Dock (such as Claude Desktop) do not read your shell's `PATH`. The MCP server command is `"<node>" "<npx>" -y n2n-nexus@latest mcp`, with npm's npx found next to that Node (or next to the Node a version manager's shim runs); it also sets `PATH` to a folder whose `node` is that Node, followed by the system folders (`/usr/bin` and `/bin`; on Windows `System32` and the Windows folder), so the package npx starts finds Node. By default `install` writes the `node` found on `PATH` when it is the same file as the Node running `install` (for example `/usr/local/bin/node`, `/opt/homebrew/bin/node`, `~/.local/bin/node` or a version manager's stable entry point), and otherwise the real path of the running Node. `install` prints the path it wrote as `Node: <path>`.
+- macOS with the Claude desktop app: `n2n-nexus install claude` is all the app's Code tab needs; it reads the same `~/.claude.json` and hooks as the `claude` CLI. Do not also add n2n-nexus to the app's `claude_desktop_config.json`: the app then bridges that server into every Code tab in place of the one Claude Code starts, and the bridge drops the conversation identity, so direct messages fail with "This call carries no agent session". If the entry is there, remove it, restart the desktop app and start a new Code tab conversation ([User guide, section 2](USER_GUIDE.md#2-claude-desktop-app)).
+- Pass `--node <path>` to choose the Node path yourself. It must exist, be executable and satisfy the `engines` range in package.json (`^22.14.0 || >=23.6.0`); otherwise `install` exits with code 1 and writes nothing.
+- After upgrading Node: if `install` warned that the Node path contains a version directory (Homebrew `Cellar`, nvm, fnm, Volta, asdf, `node-v<version>`), run `n2n-nexus install <claude|codex>` again after each upgrade, or pass `--node` with a stable path.
+- Supported on Linux, WSL and macOS; Codex hooks also support Windows PowerShell.
+
+## 4. Turn on the Codex hooks (one-time, required)
+
+Codex does not run hooks that someone else wrote until you have reviewed and trusted them. Without this step Codex conversations still get the shared tools, but they cannot send or receive direct messages, and the host never sees them come online.
+
+1. Open the Codex CLI in a terminal: `codex`.
+2. Type `/hooks`.
+3. Review the n2n-nexus entries (SessionStart, SessionEnd, UserPromptSubmit, PostToolUse and two Stop hooks; their commands run `n2n-nexus … hook codex`) and trust them.
+4. Start a new Codex conversation.
+
+Good to know:
+
+- Codex stores the trust per hook, with a hash of its command, in `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`). The CLI and the Codex app share it, so trusting once in the CLI is enough for the app too. The Codex app has no `/hooks` screen of its own: use the CLI as above.
+- A changed command needs trusting again. That happens when you run `n2n-nexus install codex` again with a different `--endpoint` or `--node`, or after your Node.js moved to another path. Upgrading the npm package alone does not change the commands.
+- Hooks are on by default in current Codex versions. If a policy or your own `config.toml` sets `[features] hooks = false`, they do not run at all.
+- When hooks need review, Codex warns at startup and points you to `/hooks`.
+
+Official documentation: [Codex hooks](https://learn.chatgpt.com/docs/hooks).
+
+Claude Code needs no such step: it runs the hooks in `settings.json` as soon as `install claude` has written them.
+
+## 5. Other MCP clients
+
+Other MCP clients can use every tool except direct messages:
+
+```json
+{
+  "mcpServers": {
+    "n2n-nexus": {
+      "command": "npx",
+      "args": ["-y", "n2n-nexus", "mcp"],
+      "env": {
+        "NEXUS_ENDPOINT": "http://127.0.0.1:5688"
+      }
+    }
+  }
+}
+```
+
+The adapter can start before the host. It loads the host's tool list once the host becomes reachable. The adapter and the hooks never start a host themselves: when none answers, tool calls fail with a message saying how to start it (or, for a remote endpoint, that it must be started on that machine), and the hooks skip silently. A call the host does not answer in time fails on its own; the host may still complete it.
+
+## 6. Several machines and environments
+
+By default the host listens on `127.0.0.1` only. To make it the host for other machines on a trusted network:
+
+1. On the host machine, turn LAN access on:
+   - Tray: check **Allow LAN access**. The tray writes `"host": "0.0.0.0"` to `settings.json` and restarts the host. On Windows it adds inbound firewall rules for the TCP port and the UDP discovery port (5688 and 5688 by default) after a UAC prompt; on macOS and Linux it tells you which ports to allow in your firewall.
+   - Service: `n2n-nexus-host service install --host 0.0.0.0` writes the address to `settings.json`; allow TCP 5688 and UDP 5688 in the firewall yourself.
+2. On the other machines, install the client with `--endpoint discover` (for example `n2n-nexus install claude --endpoint discover`), or with the host's address.
+
+With `discover`, the adapter and the hooks broadcast a query on UDP `NEXUS_DISCOVERY_PORT` and use the first host that answers; the result is cached in `~/.n2n-nexus/discovered-endpoint` and looked up again when that host cannot be reached. A host answers only when it listens on a non-loopback address (LAN access on), so allow UDP and TCP 5688 through its firewall for the trusted network. When none answers, the client uses `http://127.0.0.1:5688` (a host on this machine) and looks again after a minute.
+
+| Scenario | `--endpoint` / `NEXUS_ENDPOINT` |
+| --- | --- |
+| Same machine | `http://127.0.0.1:5688` |
+| WSL IDE to Windows host | `http://host.docker.internal:5688` |
+| Windows IDE to WSL host | `http://<WSL-IP>:5688` |
+| Remote machine | `http://<Server-IP>:5688` |
+| Find a host on the LAN | `discover` |
+
+On macOS the first connection may trigger a **Local Network** permission prompt for the app that runs the client (Claude, Terminal, VS Code). Allow it; otherwise the client cannot reach the host (**System Settings → Privacy & Security → Local Network**).
+
+## 7. Check the installation
+
+`n2n-nexus doctor [claude|codex]` checks that the Node path and the entry script in the installed hook commands, and the Node path and npx in the MCP command, still exist and run, and that the host they talk to answers with the client's contract version; it exits with code 1 when a check fails.
+
+## 8. Upgrading
+
+- Client: the MCP server needs nothing: each new conversation starts the latest version (a running conversation keeps the one it started with). For the hooks, run `npm i -g n2n-nexus@latest`; they use the new version at once.
+- Host: upgrade with the package manager you installed it with (`scoop update n2n-nexus-host`, `brew upgrade n2n-nexus-host`), or replace the program, then restart it (tray: **Restart**; service: run `n2n-nexus-host service install` again from an administrator terminal).
+
+## 9. Uninstalling
+
+`n2n-nexus uninstall <claude|codex>` removes the hooks and the MCP server that `install` added and leaves the rest of the configuration alone.
+
+```bash
+n2n-nexus uninstall claude
+n2n-nexus uninstall codex
+n2n-nexus-host service uninstall     # if you installed the service (administrator / sudo)
+n2n-nexus-host autostart off         # if the tray starts at login
+```

package/docs/INSTALL_zh.md

@@ -0,0 +1,146 @@
+# n2n-nexus 安装手册
+
+[English version](INSTALL.md)
+
+本手册介绍如何安装 n2n-nexus，让你的 AI 编程会话（Claude Code 和 Codex）共享项目和文档、互相发消息。装好以后怎么用，见[使用手册](USER_GUIDE_zh.md)。
+
+## 要安装什么
+
+| 组件 | 是什么 | 装在哪 |
+|---|---|---|
+| `n2n-nexus-host` | host：保存所有共享数据、在会话之间传递消息的程序。只需在一台机器上运行。 | Windows、macOS 或 Linux |
+| `n2n-nexus`（npm） | 客户端：AI 客户端启动的 MCP 服务器，以及告诉 host"这是哪个对话"的 hooks。 | 每台装了 Claude Code 或 Codex 的机器 |
+
+## 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。用 Release 里的 `SHA256SUMS` 和构建证明校验下载的文件：
+
+```bash
+sha256sum -c SHA256SUMS --ignore-missing
+gh attestation verify n2n-nexus-host_<版本>_<os>_<arch>.tar.gz --repo n2ns/n2n-nexus
+```
+
+需要知道的：
+
+- 程序暂未做代码签名。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` 会启动托盘程序后立即返回。
+
+## 2. 启动 host
+
+用下面两种方式之一启动：
+
+- **托盘程序**：不带参数运行 `n2n-nexus-host`。托盘第一次运行时会自动打开 **登录后自启**，之后保持你的设置。托盘菜单的用法见[使用手册](USER_GUIDE_zh.md#1-托盘)。
+- **后台服务**（开机即启动，不用登录，不带托盘）：在管理员终端（Windows）或用 `sudo`（macOS、Linux）执行 `n2n-nexus-host service install`。服务以安装它的用户身份运行。先退出托盘：托盘正在运行 host 时 `service install` 会拒绝执行。服务在运行时，之后启动的托盘只做控制界面。
+
+Linux 上的托盘需要桌面环境支持 StatusNotifierItem（AppIndicator）；没有桌面的服务器请用 `service install`。各系统上服务和登录后自启注册在哪里，见[架构说明](ARCHITECTURE_zh.md#各平台的托盘与服务)。
+
+## 3. 为 Claude Code 和 Codex 安装客户端
+
+运行环境要求 Node.js 22.x 中的 22.14.0 或更高版本，或 Node.js 23.6.0 及以上版本。
+
+```bash
+npm i -g n2n-nexus@latest
+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 服务写进客户端的用户级配置。装完后要**新开**对话：正在进行的对话不会加载新的 MCP 服务器。
+
+MCP 服务器会自己更新：它通过 npm 的 npx 运行 `n2n-nexus@latest`，所以每次新开对话都会向 npm 查询最新版本并启动它（新版本只下载一次，之后从 npm 缓存启动）。hooks 用的是全局安装的包，需要你自己升级（第 8 步）。
+
+- host 不在 `http://127.0.0.1:5688` 时，两条命令都加上 `--endpoint <url>`；要在局域网里自动查找 host，就用 `--endpoint discover`（第 6 步）。
+- 在 Windows 上，`npm i -g` 和 `install` 要在普通终端里执行，不要在 Codex 这类打包应用自带的终端里执行：那里会装进该应用私有的 `%APPDATA%` 副本，并让应用看不到全局安装。
+- hooks 和 MCP 服务的命令里写的是 Node 的绝对路径，因为从 Dock 启动的 GUI 客户端（如 Claude 桌面版）不读取 shell 的 `PATH`。MCP 服务的命令是 `"<node>" "<npx>" -y n2n-nexus@latest mcp`，npx 取这个 Node 旁边的 npm 自带的那个（版本管理工具的 shim 则取它实际运行的 Node 旁边的）；同时把 `PATH` 设为一个其中 `node` 就是这个 Node 的目录，后面跟系统目录（`/usr/bin` 和 `/bin`；Windows 上是 `System32` 和 Windows 目录），让 npx 启动的包能找到 Node。默认情况下，`PATH` 上的 `node` 与运行 `install` 的 Node 是同一个文件时，`install` 写入 `PATH` 上的路径（例如 `/usr/local/bin/node`、`/opt/homebrew/bin/node`、`~/.local/bin/node` 或版本管理工具的稳定入口），否则写入当前运行的 Node 的真实路径。`install` 会打印一行 `Node: <path>` 显示实际写入的路径。
+- macOS 上用 Claude 桌面版：Code 标签页只需要 `n2n-nexus install claude`，它和 `claude` 命令行读同一份 `~/.claude.json` 和 hooks。不要再把 n2n-nexus 加进桌面版的 `claude_desktop_config.json`：桌面版会把那个服务器桥接进每个 Code 标签页、顶替 Claude Code 自己启动的那份，桥接会丢掉对话身份，直接消息全部报 "This call carries no agent session"。如果已经加了，删掉这一项、重启桌面版、再新开 Code 标签页对话（[用户手册第 2 节](USER_GUIDE_zh.md#2-claude-桌面版)）。
+- 用 `--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` 指定稳定路径。
+- 支持 Linux、WSL 和 macOS；Codex hooks 也支持 Windows PowerShell。
+
+## 4. 启用 Codex 的 hooks（只需一次，必须做）
+
+Codex 不会运行别人写的 hooks，除非你审阅并信任了它们。不做这一步，Codex 对话仍能用共享工具，但收发不了直接消息，host 也看不到它们上线。
+
+1. 在终端里打开 Codex 命令行：`codex`。
+2. 输入 `/hooks`。
+3. 审阅 n2n-nexus 的几条 hook（SessionStart、SessionEnd、UserPromptSubmit、PostToolUse 和两条 Stop，命令都是 `n2n-nexus … hook codex`），然后信任它们。
+4. 新开一个 Codex 对话。
+
+需要知道的：
+
+- Codex 按每条 hook 记录信任，连同它命令的哈希，存在 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）里。命令行和 Codex 桌面应用共用这份记录，所以在命令行里信任一次，桌面应用也生效。Codex 桌面应用没有自己的 `/hooks` 界面，请按上面的步骤用命令行。
+- 命令变了就要重新信任。比如用不同的 `--endpoint` 或 `--node` 重新运行 `n2n-nexus install codex`，或者 Node.js 换了路径之后。只升级 npm 包不会改变命令。
+- 当前版本的 Codex 默认开启 hooks。如果管理策略或你自己的 `config.toml` 里设置了 `[features] hooks = false`，hooks 就完全不会运行。
+- 有 hooks 需要审阅时，Codex 启动时会给出提示，指向 `/hooks`。
+
+官方文档：[Codex hooks](https://learn.chatgpt.com/docs/hooks)。
+
+Claude Code 不需要这一步：`install claude` 写入 `settings.json` 后，hooks 立即生效。
+
+## 5. 其他 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 可能仍会执行完。
+
+## 6. 多台机器和多个环境
+
+host 默认只监听 `127.0.0.1`。要让它成为可信网络里其他机器的 host：
+
+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 需要自己放行。
+2. 在其他机器上用 `--endpoint discover` 安装客户端（例如 `n2n-nexus install claude --endpoint discover`），或者直接写 host 的地址。
+
+设为 `discover` 时，适配器和 hooks 在 UDP `NEXUS_DISCOVERY_PORT` 上广播查询，使用第一个应答的 host；结果缓存在 `~/.n2n-nexus/discovered-endpoint`，连不上该 host 时重新查找。只有监听非回环地址（开启了局域网访问）的 host 才应答，所以要在它的防火墙上对可信网络放行 UDP 和 TCP 5688。没有应答时，客户端使用 `http://127.0.0.1:5688`（本机的 host），一分钟后再查找。
+
+| 场景 | `--endpoint` / `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` |
+
+macOS 上第一次连接时，系统可能会为运行客户端的应用（Claude、终端、VS Code）弹出**本地网络**权限提示。请允许；否则客户端连不上 host（**系统设置 → 隐私与安全性 → 本地网络**）。
+
+## 7. 检查安装
+
+`n2n-nexus doctor [claude|codex]` 检查已安装的 hook 命令里的 Node 路径与入口脚本、MCP 命令里的 Node 路径与 npx 是否仍然存在、能否运行，以及它们连接的 host 是否应答、协议版本是否与客户端一致，有检查失败时以退出码 1 退出。
+
+## 8. 升级
+
+- 客户端：MCP 服务器不用管，每次新开对话都会启动最新版本（正在进行的对话保持它启动时的版本）。hooks 需要运行 `npm i -g n2n-nexus@latest`，之后立即用上新版本。
+- host：用当初安装它的包管理器升级（`scoop update n2n-nexus-host`、`brew upgrade n2n-nexus-host`），或直接替换程序，然后重启（托盘：**重启**；服务：在管理员终端里再运行一次 `n2n-nexus-host service install`）。
+
+## 9. 卸载
+
+`n2n-nexus uninstall <claude|codex>` 删除 `install` 写入的 hooks 和 MCP 服务，配置里的其他内容不动。
+
+```bash
+n2n-nexus uninstall claude
+n2n-nexus uninstall codex
+n2n-nexus-host service uninstall     # 如果装了服务（管理员终端 / sudo）
+n2n-nexus-host autostart off         # 如果托盘设置了登录后自启
+```