> **读者**：在用户本机通过 **ZeroNews MCP** 安装/配置 ZeroNews 的 **AI Agent**（Cursor、Claude Code、Codex、DeepSeek Harness、WorkBuddy 等）。  
> **Markdown raw**：`/raw/ai/zeronews-mcp-setup.md`  
> **人类**：[ZeroNews MCP](/ai/zeronews-mcp)

Docker / 容器内客户端不在范围。**MUST NOT** 编辑本文件打勾。

# ZeroNews 指引描述

本指引指导 **AI Agent** 完全按照此文档的工作流程，务必完全理解 **Agent 约束** 后，完成 **接入 ZeroNews MCP**，再用 **MCP 工具** 安装 **ZeroNews 客户端**、**浏览器 login** 绑机，将本地 **HTTP/TCP** 服务映射到公网。

## 主路径 {#主路径}

用户意图 **安装客户端并代理/映射本地服务**（或一句话含装+穿透）时，**必须**按顺序完成：

| 序 | STEP（对话汇报名） | 概要 |
|----|-------------------|------|
| 1 | **检查宿主机环境** | 宿主、OS、`node -v` ≥ 20、`npx`（Win：`npx.cmd`） |
| 2 | **接入 ZeroNews MCP** | 按 [宿主适配](#宿主适配) 写入配置（**npx `zeronews-mcp@latest`**）；**A5** 等到 `client_status` + `install_client` 出现 |
| 3 | **安装 ZeroNews 客户端** | MCP **`client_status`** → 缺则 **`install_client`**；未登录则 **`login`** + 轮询至 `logged_in` |
| 4 | **添加隧道** | 已登录且客户端可用 → **`list_local_listeners`** / **`expose_local_service`** / **`add_tunnel`** 等 |

**FAST：** 工具列表已有 `client_status` 与 `install_client`（且 MCP 已连接，见适配表「FAST 额外」）→ **跳过 Step 2 的写配置**，从 **Step 3** 起；**仍须** Step 1 的 Node ≥ 20。

| 意图 | 结束 STEP |
|------|-----------|
| 只接 MCP / 只要配置文件 | **接入 ZeroNews MCP**（A5；勿 `install_client`） |
| 只装客户端 | **安装 ZeroNews 客户端**（不必登录） |
| 登录/绑机 | **安装 ZeroNews 客户端**（`logged_in`） |
| 映射 / Webhook / 分享 / 域名 | **添加隧道** |
| 其它 | 复述意图，勿默认映射 |

## Agent 约束

1. **先做事，后解释** — 在本机连续写配置、调 MCP，不要先写长文，不要跳步、改顺序。
2. **禁止 Skills 旁路** — 本路径用 **MCP 工具** 装客户端/登录/映射；**不要**用 `zeronews-skills` / Shell `curl` 代装（Skills 路径见 [Skills Agent 规程](/raw/ai/zeronews-skills-setup.md)）。
3. **所有操作在用户电脑上执行** — Shell、MCP、浏览器登录均在用户机器；每条 Shell **须**剥离沙箱（见 Step 1）；**禁止** Cloud Agent / 沙箱结果当成功。
4. **先 MCP，后客户端** — **A5 未出现** `client_status` 与 `install_client` **之前**，**禁止** `install_client` / `login` / 映射工具；A 阶段 **禁止** Shell 探测或安装客户端。
5. **只用 MCP `login` 绑机** — **不要**向用户要 Token，**禁止** `authtoken`、Skills 里的 authtoken 流程。
6. **已登录勿重复 `login`** — `client_status` 已 `logged_in` 时不要再 `login`。
7. **未登录不能加隧道** — 未 `logged_in` **不要** `list_local_listeners`、**不要** `expose_local_service` / `add_tunnel`。
8. **端口别猜** — 用户未给唯一端口 → `list_local_listeners` 后请用户 **选一项**；**禁止**默认 3000/8080、**禁止**列表第一项。
9. **默认别多问** — 非必要不问「是否继续」、安装目录、workdir（用 [标准 env](#标准-env)）；写配置路径按 [宿主适配](#宿主适配) 与现场 merge。
10. **必须按指引顺序操作** — 须对齐 [主路径](#主路径) 意图表；**禁止**跨宿主写 MCP、默认死写 Cursor 路径。
11. **输出 STEP 名称** — 执行每一步时 **必须**输出当前 STEP（主路径表中文名）。
12. **做完 Step 4 再总结** — 回报 client_id、公网地址、本地端口、endpoint；没到终点勿宣称已装好/已映射。
13. **命令前自检** — Shell 前若 `$NODE_OPTIONS` 含 `node-language-shim` 等沙箱痕迹，**须**用剥离前缀（与 Step 1 示例一致）。

### 可问用户

宿主/OS/任务目录不定；意图为「其它」；Step 4 多个监听端口需 **选一项**；`reset` / 破坏性删除须确认；浏览器里点「确认登录」；MCP 配置路径现场与适配表冲突且无法判定。

---

# step 1: 检查宿主机环境

- 定 **宿主**（Cursor / Claude Code / Codex / WorkBuddy / Harness 等）与 **OS**（`uname -sm` 等）。
- **`node -v` ≥ 20**；确认 **`npx`**（Windows：**`npx.cmd`**）。无 `npx` → 引导安装后继续。
- 打开 [宿主适配](#宿主适配) **只读当前宿主行**（Harness / WorkBuddy 另读文末短节）。
- **通过后仅可进 Step 2**（或 FAST 且工具已在 → Step 3）。
- **禁止**本步 `install_client`、Shell 装客户端、`login`、列端口、写 Skills。

**Shell 自检（需要时）：**

```bash
env -u NODE_OPTIONS -u PYTHONPATH -u CODEBUDDY_BROKERED_FS_HOOK_ENABLED -u TOYBOX_SANDBOX_SOCK node -v
env -u NODE_OPTIONS -u PYTHONPATH -u CODEBUDDY_BROKERED_FS_HOOK_ENABLED -u TOYBOX_SANDBOX_SOCK command -v npx
```

Node 过低 → [附录](#附录)。

---

# step 2: 接入 ZeroNews MCP

**FAST：** 已见 `client_status` 与 `install_client`（调用名见适配表）且 MCP server 已连接 → **勿重写配置**，进 Step 3。

1. **A4 — 写配置：** 按 [MCP 合并规则](#mcp-合并规则) 与 [宿主适配](#宿主适配) **merge**，**只改 `zeronews` 条目**；`command`＝`npx`（Win：`npx.cmd`），`args`＝`["-y","zeronews-mcp@latest"]`；[标准 env](#标准-env)；禁止 Token。模板见 [JSON](#json-模板) / [Codex TOML](#codex-toml)。
2. **方式（写入内容）：** MCP 通过 **`npx -y zeronews-mcp@latest`** 拉起（写在配置 `args` 中，**不是** Skills 的 `skills add`）。
3. **A5 — 等生效：** 保存后等待 / Reload / 重启（见适配表「A5/生效」）。**验收：** 工具列表出现 **`client_status`** 与 **`install_client`**（Harness 等可能为 `mcp__zeronews__*`）。
4. **A5 未过 → 禁止 Step 3。** 仍无 → 适配表「A5 降级」→ [附录](#附录)。

用户 **只要配置文件** → 本步结束并说明 **MCP 未登录/未装客户端**。

---

# step 3: 安装 ZeroNews 客户端

**门禁：** Step 2（或 FAST）MCP 已生效。

1. 调用 **`client_status`**（逻辑名；实际名见 [宿主适配](#宿主适配)）。
2. 未安装 → **`install_client`**（`download_install: true`，不传 workdir/executable）。MCP 触发的下载域含 `testenv` / `localhost` / `127.0.0.1` 且用户未要求测试 → **停**。
3. 路径与 `ZERONEWS_*` env 不一致 → **仅**改当前宿主配置文件中的 env 与 `ZERONEWS_MCP_CONFIG_REV`（+1），等工具重现后再 `client_status`（**禁止**借机 Shell 安装）。
4. 需登录且未 `logged_in` → **`login`**，随后 **每 3s** 轮询 **`client_status`**，最多 **20** 次：`logged_in` → 完成；`login_pending` → 继续；`denied` / `expired` / `quota_exceeded` / `failed` / `login_error` → 停。
5. **`upgrade_available`**：有意图登录/已登录且存在 `upgrade_client` 可升级；**禁止**仅为升级去 `login`。

**本步结束条件：** 用户意图仅需装客户端 → 已安装即可停；需映射 → **`logged_in`** 且客户端路径与 env 一致。达到后 **不要**重复 `login`，进 Step 4。

**仅装客户端、不映射** → 本步结束即 DONE（可口述 `client_status` 摘要）。

---

# step 4: 添加隧道

**门禁：** **`logged_in`** 且客户端可用（必要时 `service_status` / `start` / `client_reload`，见 [工具](#工具)）。

- 用户 **已给唯一端口** → **`expose_local_service`**（仅该 port）。
- **未给端口** → **`list_local_listeners`** → 用户 **选一项** → **`expose_local_service`**（**禁止**猜端口）。
- Webhook / 文件分享 / 指定隧道类型 → **`add_tunnel`**；域名 → **`add_domain`**。
- 默认 Web 常用 `https`；TCP/TLS 按用户语义。

成功后回报公网 URL / endpoint、本地端口、client_id。

---

## MCP 合并规则 {#mcp-合并规则}

**层级：** 有项目且宿主支持项目级 → **只写项目级**；无项目 → 用户/应用级。两处都有 `zeronews` → 留本次写入层，删另一层。A5 降级见适配表。

**定位：** ① 宿主官方 MCP 入口 → ② 本层 **merge** 只改 `zeronews` → ③ 与适配「配置路径」冲突以现场为准 → ④ 仍不定则 [可问用户](#可问用户)。

**字段：** `ZERONEWS_MCP_CONFIG_REV` 无则 `"1"`，改 env 则 +1。写文件成功 ≠ MCP 生效。

## 标准 env {#标准-env}

| OS | ZERONEWS_EXECUTABLE | ZERONEWS_WORKDIR |
|----|---------------------|------------------|
| darwin | `/Applications/zeronews/zeronews` | `/Applications/zeronews` |
| linux | `/usr/bin/zeronews` | `/etc/zeronews` |
| win32 | `C:/Program Files/zeronews/zeronews.exe` | `C:/Program Files/zeronews` |

JSON 中 Windows 路径用正斜杠。Linux 上 binary 与 workdir **不同目录**。路径校正 **仅在 Step 3** 之后、通过改 MCP env + REV。

## 工具 {#工具}

**仅 Step 2 验收后使用。** 下表为逻辑名；**调用名**见 [宿主适配](#宿主适配)。

| 意图 | 逻辑工具 |
|------|----------|
| 探活 | `client_status` |
| 安装 | `install_client` |
| 登录 | `login` |
| 有端口 | `expose_local_service` |
| 无端口 | `list_local_listeners` → 用户选 → `expose_local_service` |
| Webhook/分享 | `add_tunnel` |
| 域名 | `add_domain` |
| 升级 | `upgrade_client`（按 Step 3 规则） |

**禁止** Shell `zeronews upgrade` 代替 MCP。

## 宿主适配 {#宿主适配}

**Step 1 之后、Step 2 写入前必读当前宿主行。**

| 宿主 | 配置路径（项目 / 用户） | 格式 | 工具调用名 | A5/生效 | FAST 额外 | A5 降级 |
|------|-------------------------|------|------------|---------|-----------|---------|
| Cursor | `.cursor/mcp.json` / `~/.cursor/mcp.json` | JSON | 原名 | 等待 / Reload | — | 项目 → 用户，删未生效层 |
| Claude Code | `.mcp.json` / `~/.claude.json` | JSON | 原名 | 等待 / Reload | — | 同上 |
| Claude Desktop | 应用 MCP 配置 | JSON | 原名 | 重启应用 | — | Reload 后仍无 → 附录 |
| Codex | `.codex/config.toml` / `~/.codex/config.toml` | TOML | 原名 | Reload / 新会话 | — | 项目 → 用户 |
| WorkBuddy | `<任务>/.workbuddy/mcp.json` / `~/.workbuddy/mcp.json` | JSON | `mcp__zeronews__{tool}` | Reload / 新会话 | **须 trust `zeronews`** | 项目 → `~/.workbuddy/…` |
| Harness | 工作区 `.dsh/mcp.json` | JSON | `mcp__zeronews__{tool}` | desktop 全量重启 | — | 勿跨宿主 |

「原名」＝`client_status`、`install_client` 等与上表逻辑工具同名。

### JSON 宿主共用模板 {#json-模板}

`{NPX}`：Unix `npx`，Win `npx.cmd`；`{EXECUTABLE}` / `{WORKDIR}` 来自 [标准 env](#标准-env)；`{REV}` 见合并规则。

```json
{
  "mcpServers": {
    "zeronews": {
      "command": "{NPX}",
      "args": ["-y", "zeronews-mcp@latest"],
      "env": {
        "ZERONEWS_EXECUTABLE": "{EXECUTABLE}",
        "ZERONEWS_WORKDIR": "{WORKDIR}",
        "ZERONEWS_MCP_CONFIG_REV": "{REV}"
      }
    }
  }
}
```

### Codex {#codex-toml}

```toml
[mcp_servers.zeronews]
command = "{NPX}"
args = ["-y", "zeronews-mcp@latest"]
[mcp_servers.zeronews.env]
ZERONEWS_EXECUTABLE = "{EXECUTABLE}"
ZERONEWS_WORKDIR = "{WORKDIR}"
ZERONEWS_MCP_CONFIG_REV = "{REV}"
```

### WorkBuddy {#附录workbuddy}

路径须 **`.workbuddy/mcp.json`**。保存后用户须在连接器 **信任/启用** `zeronews`；Agent 不能代点 UI。npm 不可达可 `NPM_CONFIG_REGISTRY`（+REV）。勿用 zip 代替 npx。

### DeepSeek Harness {#附录deepseek-harness}

**A4 前：** `dsh plugin --profile <p> add dsh-workspace-mcp`。 **A4：** 只写 **`.dsh/mcp.json`**。**A5：** desktop **完整重启**后再开会话。

## 附录 {#附录}

**无 MCP / Node < 20：** 停；勿 Shell+`authtoken` 冒充。请换 Skills 路径 → [Skills Agent 规程](/raw/ai/zeronews-skills-setup.md)。

**Docker / 容器内客户端：** 停。

**人类分步说明：** → [ZeroNews MCP](/ai/zeronews-mcp)。

**可选 env：** `ZERONEWS_LOCAL_API_BEARER`、`ZERONEWS_EXCLUDE_LISTENER_PORTS`、`ZERONEWS_DOWNLOAD_BASE`、`NPM_CONFIG_REGISTRY`（改则 +REV）。