@sleep2agi/commhub-server 0.9.0-preview.156 → 0.9.0-preview.158

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.156",
+  "version": "0.9.0-preview.158",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/api-nodes-shape.test.ts

@@ -36,10 +36,25 @@ afterAll(() => {
 // the dashboard / external clients see.
 function mapRow(r: Record<string, unknown>): Record<string, unknown> {
   let role: string | null = null;
+  // #2293 —— 与 handler 同一套读法：快照可能是文本或对象；解析失败/形状不对 = 这一格没有。
+  let opencodeCatalog: string[] | null = null;
+  let opencodeGeneration: "v1" | "v2" | null = null;
+  let opencodeMode: string | null = null;
+  let opencodeServer: string | null = null;
   const snap = r.config_snapshot;
   if (snap) {
-    try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
-    catch { /* malformed */ }
+    let parsed: any = null;
+    try { parsed = typeof snap === "string" ? JSON.parse(snap) : snap; }
+    catch { parsed = null; }
+    role = parsed?.role ?? null;
+    const raw = parsed?.opencode_catalog;
+    if (Array.isArray(raw) && raw.every((m: unknown) => typeof m === "string" && m.length <= 400)) {
+      opencodeCatalog = raw.slice(0, 400);
+    }
+    const flags = parsed?.flags;
+    if (flags?.opencodeGeneration === "v1" || flags?.opencodeGeneration === "v2") opencodeGeneration = flags.opencodeGeneration;
+    if (typeof flags?.opencodeMode === "string" && flags.opencodeMode.length <= 32) opencodeMode = flags.opencodeMode;
+    if (typeof parsed?.opencode_server === "string" && parsed.opencode_server.length <= 200) opencodeServer = parsed.opencode_server;
   }
   const { config_snapshot, ...rest } = r;
   return {
@@ -47,6 +62,10 @@ function mapRow(r: Record<string, unknown>): Record<string, unknown> {
     tags: parseStoredTags(r.tags),
     attrs_revision: Number(r.attrs_revision ?? 0),
     role,
+    opencode_catalog: opencodeCatalog,
+    opencode_generation: opencodeGeneration,
+    opencode_mode: opencodeMode,
+    opencode_server: opencodeServer,
   };
 }
 
@@ -83,7 +102,7 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     // Expected fields present (13 = 12 contract + new role)
     for (const k of ["node_id", "node_name", "alias", "runtime", "model",
                      "config_path", "channels", "server", "hostname",
-                     "network_id", "created_at", "updated_at", "role"]) {
+                     "network_id", "created_at", "updated_at", "role", "opencode_catalog"]) {
       expect(row).toHaveProperty(k);
     }
     // Internal fields NOT present
@@ -100,7 +119,8 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(Object.keys(row).sort()).toEqual([
       "alias", "attrs_revision", "channels", "config_path", "created_at",
       "display_name", "hostname", "model", "network_id", "node_id",
-      "node_name", "role", "runtime", "server", "tags", "team",
+      "node_name", "opencode_catalog", "opencode_generation", "opencode_mode",
+      "opencode_server", "role", "runtime", "server", "tags", "team",
       "updated_at",
     ]);
   });
@@ -186,3 +206,74 @@ describe("RFC-024 regression — GET /api/nodes response shape (no SELECT *)", (
     expect(cfgRow?.config_snapshot).toContain("claude-opus");
   });
 });
+
+// #2293（admin 2026-10-25）—— 节点自报的模型清单必须能到 /api/nodes：
+// 「没有 daemon 绑定」的节点，客户端就是靠这一格给建议列表（否则只能手填）。
+describe("#2293 opencode_catalog projection", () => {
+  const insert = (snapshot: unknown) => db.run(
+    `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+     VALUES (?1, ?2, ?3, ?4, ?5)`,
+    [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, typeof snapshot === "string" ? snapshot : JSON.stringify(snapshot)],
+  );
+  const read = () => mapRow(db.get<Record<string, unknown>>(
+    `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+    TEST_NODE,
+  )!);
+
+  test("valid list reaches the row, order kept", () => {
+    insert({ opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"] });
+    expect(read().opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+  });
+
+  test("absent / malformed / wrong shape → null, row still served", () => {
+    insert({ model: "x" });
+    expect(read().opencode_catalog).toBeNull();
+    insert("not-json{");
+    expect(read().opencode_catalog).toBeNull();
+    // 混了非字符串 → 整格作废（不猜、不部分展示）
+    insert({ opencode_catalog: ["a/b", 7] });
+    expect(read().opencode_catalog).toBeNull();
+    // 空列表是合法但无意义 → 照原样给出（客户端自己判断要不要建列表）
+    insert({ opencode_catalog: [] });
+    expect(read().opencode_catalog).toEqual([]);
+  });
+});
+
+// #2293（PR #1092 在真机上拿不到值的原因）—— /api/nodes 不带整个 config_snapshot，
+// 但「Runtime · V2」「OpenCode Server」两行只要三个标量：代际、模式、loopback 端点。
+describe("#2293 opencode_* scalars", () => {
+  test("generation / mode / server come from the snapshot, nothing else leaks", () => {
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, ?5)`,
+      [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, JSON.stringify({
+        flags: { opencodeGeneration: "v2", opencodeMode: "copresence", secretOther: "must-not-leak" },
+        opencode_server: "http://127.0.0.1:4096",
+      })],
+    );
+    const row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+  });
+
+  test("unknown generation / absent fields → null (old nodes keep rendering)", () => {
+    db.run(
+      `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, config_snapshot)
+       VALUES (?1, ?2, ?3, ?4, ?5)`,
+      [TEST_NODE, "test-shape", "test-shape", TEST_NETWORK, JSON.stringify({ flags: { opencodeGeneration: "v9" } })],
+    );
+    const row = mapRow(db.get<Record<string, unknown>>(
+      `SELECT node_id, node_name, alias, network_id, config_snapshot FROM nodes WHERE node_id = ?1`,
+      TEST_NODE,
+    )!);
+    expect(row.opencode_generation).toBeNull();
+    expect(row.opencode_mode).toBeNull();
+    expect(row.opencode_server).toBeNull();
+  });
+});

package/src/node-attrs.test.ts

@@ -215,3 +215,44 @@ describe("node display attrs — auth + scope", () => {
     expect(r.status).toBe(404);
   });
 });
+
+// #2293（admin 2026-10-25）—— 走**真正**的 HTTP，不镜像 handler：
+// 客户端「Runtime · V2」「OpenCode Server」和「模型可选列表」要的三样东西
+// （代际 / 模式 / loopback 端点）与「这台机器上报的模型 id 清单」都在 /api/nodes 上，
+// 而整个 config_snapshot 仍然不外泄（终端 #312 的约定）。
+describe("#2293 opencode bits on GET /api/nodes (real HTTP)", () => {
+  const OC_NODE = "node_attrs_opencode";
+  const OC_ALIAS = "attrs-opencode-node";
+
+  test("generation / mode / server / catalog are projected; config_snapshot is not", async () => {
+    db.run(`DELETE FROM nodes WHERE node_id = ?1`, [OC_NODE]);
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, runtime, model, network_id, config_snapshot)
+       VALUES (?1, 'attrs-oc', ?2, 'opencode-sdk', 'deepseek/deepseek-flash', ?3, ?4)`,
+      [OC_NODE, OC_ALIAS, NET, JSON.stringify({
+        model: "deepseek/deepseek-flash",
+        flags: { opencodeGeneration: "v2", opencodeMode: "copresence", daemonSideSecret: "must-not-leak" },
+        opencode_server: "http://127.0.0.1:4096",
+        opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"],
+      })],
+    );
+    const row = (await listNodes()).find((r) => r.node_id === OC_NODE)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    expect(row.opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+    // 整个快照仍然不出现，且 flags 里的其它键不外泄。
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+    db.run(`DELETE FROM nodes WHERE node_id = ?1`, [OC_NODE]);
+  });
+
+  test("a node that never reported them reads as null / [] (old node, no invented values)", async () => {
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(row.opencode_generation ?? null).toBeNull();
+    expect(row.opencode_mode ?? null).toBeNull();
+    expect(row.opencode_server ?? null).toBeNull();
+    expect(row.opencode_catalog ?? null).toBeNull();
+  });
+});

package/src/node-permissions.ts

@@ -259,6 +259,7 @@ export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
   request_adopt_node: "human_only", unadopt_node: "human_only",
   get_adopt_request: "always", ack_adopt_request: "always",
   send_desktop_message: "always", // 发给人的私信,不是派活
+  requirement_tags: "requirements",
   // 读
   get_all_status: "read", get_session_status: "read", get_task: "read", list_tasks: "read", get_completions: "read", org_whoami: "read",
   list_skills: "read", get_skill: "read", list_host_supervisors: "read", list_network_secrets: "read", list_providers: "read",

package/src/opencode-catalog-report-http.test.ts

@@ -0,0 +1,139 @@
+// #2293（admin 2026-10-25）—— 从**节点的真实上报**一路走到 `/api/nodes` 的投影。
+//
+// 为什么这条要单独写：`api-nodes-shape.test.ts` 是**镜像 handler** 的（文件里自己声明会漂），
+// `node-attrs.test.ts` 是直接往库里塞一行快照。两者都没有走 `report_status` 的 zod schema ——
+// 而 schema 恰恰是「节点发了、Hub 上却什么都没有」最容易出事的地方（#1545：往非 strict 对象里
+// 加键会被静默丢弃）。这里用真 node 令牌 + 真 MCP `tools/call` + 真 `GET /api/nodes`。
+//
+// 断言三件事：
+//   1. `opencode_catalog` / `opencode_server` / flags 里的代际·模式，经 schema 后**落到库里**；
+//   2. `/api/nodes` 把它们投影出来，且**整个 config_snapshot 不外泄**；
+//   3. 形状不对（嵌对象、混非字符串）时**心跳照收**，只是这一格没有 —— 不许拒整份上报。
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-catalog-report-"));
+process.env.COMMHUB_DB ||= join(DIR, "commhub.db");
+
+const stamp = `${process.pid}_${Date.now()}`;
+const NET_ALIAS = `catalog-${stamp}`;
+let hub: any;
+let base = "";
+let adminToken = "";
+let nodeToken = "";
+let networkId = "";
+let nodeId = "";
+
+async function send(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(`${base}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await r.text();
+  let json: any = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* MCP may answer as SSE */ }
+  return { status: r.status, body: json, text };
+}
+
+/** 真 MCP `tools/call report_status`，和 agent-node 心跳走同一条入参路径。 */
+async function reportStatus(snapshot: Record<string, unknown>) {
+  const r = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${nodeToken}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({
+      jsonrpc: "2.0", id: 1, method: "tools/call",
+      params: {
+        name: "report_status",
+        arguments: {
+          resume_id: `r_catalog_${stamp}`, alias: NET_ALIAS, status: "idle", node_id: nodeId,
+          runtime: "opencode-sdk",
+          config_snapshot: { model: "deepseek/deepseek-flash", ...snapshot },
+        },
+      },
+    }),
+  });
+  await r.text();
+  return r.status;
+}
+
+async function listNodes() {
+  const r = await send(adminToken, "GET", `/api/nodes?network_id=${networkId}`);
+  expect(r.status).toBe(200);
+  return (r.body?.nodes ?? []) as Array<Record<string, unknown>>;
+}
+
+beforeAll(async () => {
+  const admin = register(`catalog_admin_${stamp}`, "CatalogAdmin123!", undefined, "Catalog Admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  networkId = admin.network_id!;
+  const ownerId = admin.user!.user_id;
+  nodeId = `n_catalog_${stamp}`;
+  const minted = createNetworkTokenForNode(ownerId, networkId, NET_ALIAS, nodeId);
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch { /* already down */ }
+  try { rmSync(DIR, { recursive: true, force: true }); } catch { /* best effort */ }
+});
+
+describe("#2293 node-reported OpenCode catalog reaches GET /api/nodes", () => {
+  test("a real report_status lands the catalog and the scalars on the node row", async () => {
+    expect(await reportStatus({
+      flags: { opencodeGeneration: "v2", opencodeMode: "copresence", daemonSideSecret: "must-not-leak" },
+      opencode_catalog: ["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"],
+      opencode_server: "http://127.0.0.1:4096",
+    })).toBe(200);
+
+    const stored = db.get<{ config_snapshot: string }>("SELECT config_snapshot FROM nodes WHERE node_id = ?1", nodeId)!;
+    expect(JSON.parse(stored.config_snapshot).opencode_catalog).toEqual([
+      "deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free",
+    ]);
+
+    const row = (await listNodes()).find(r => r.node_id === nodeId)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_catalog).toEqual(["deepseek/deepseek-flash", "opencode/mimo-v2.6-flash-free"]);
+    expect(row.opencode_generation).toBe("v2");
+    expect(row.opencode_mode).toBe("copresence");
+    expect(row.opencode_server).toBe("http://127.0.0.1:4096");
+    // 整个快照仍然不出现在这一行里；flags 中的其它键也不外泄。
+    expect(row).not.toHaveProperty("config_snapshot");
+    expect(JSON.stringify(row)).not.toContain("must-not-leak");
+  });
+
+  test("a malformed catalog drops that field only — the heartbeat is still accepted", async () => {
+    expect(await reportStatus({
+      flags: { opencodeGeneration: "v2" },
+      // 嵌对象 + 混入数字：形状不对，schema 的 `.catch(undefined)` 应当只丢这一格。
+      opencode_catalog: { models: ["deepseek/deepseek-flash"] },
+      opencode_server: 12345,
+    })).toBe(200);
+
+    const row = (await listNodes()).find(r => r.node_id === nodeId)!;
+    expect(row).toBeDefined();
+    expect(row.opencode_catalog).toBeNull();
+    expect(row.opencode_server).toBeNull();
+    // 代际这一格仍然照常投影（没被同一条错误连带丢掉）。
+    expect(row.opencode_generation).toBe("v2");
+  });
+
+  test("a node that never reported the fields reads as null on every one of them", async () => {
+    const other = (await listNodes()).find(r => r.node_id !== nodeId);
+    if (!other) return; // 该网络里只有一个节点时无需断言（不是失败）
+    expect(other.opencode_catalog ?? null).toBeNull();
+    expect(other.opencode_generation ?? null).toBeNull();
+    expect(other.opencode_mode ?? null).toBeNull();
+    expect(other.opencode_server ?? null).toBeNull();
+  });
+});

package/src/requirement-tag-ops-http.test.ts

@@ -381,3 +381,45 @@ describe("改父级 reparent —— 被拒绝时不留副作用", () => {
     expect(after?.registered ?? false).toBe(false);
   });
 });
+
+// ── MCP 面（#2204 缺口 2）──
+// 一个工具(action 分派)而不是 list + op 两个:tools/list 字节预算是硬约束,见 tools.ts 的注释。
+describe("requirement_tags (MCP)", () => {
+  async function mcp(token: string, name: string, args: Record<string, unknown>) {
+    const r = await fetch(`${BASE}/mcp`, { method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }) });
+    const raw = await r.text(), line = raw.split("\n").find(x => x.startsWith("data: "));
+    const envelope = JSON.parse(line ? line.slice(6) : raw);
+    try { return JSON.parse(envelope.result.content[0].text); } catch { return { mcpError: envelope.error ?? envelope.result }; }
+  }
+  const nodes = async (token: string) => (await send(token, "GET", `/api/requirements/tags?network_id=${NET}`)).body.nodes as Array<{ name: string; parent_id: string | null; depth: number; registered: boolean }>;
+
+  test("action=list 返回标签树(含 parent/depth/registered);action=reparent 走同一条 REST 语义", async () => {
+    expect((await send(admin.token, "POST", `/api/requirements/tags/create?network_id=${NET}`, { name: "MCP父", parent_id: null })).status).toBe(201);
+    expect((await send(admin.token, "POST", `/api/requirements/tags/create?network_id=${NET}`, { name: "MCP子", parent_id: null })).status).toBe(201);
+
+    const listed = await mcp(admin.token, "requirement_tags", { action: "list" });
+    const rows = listed.nodes as Array<{ name: string; parent_id: string | null; depth: number; registered: boolean }>;
+    expect(rows.find(node => node.name === "MCP父")).toMatchObject({ parent_id: null, depth: 1, registered: true });
+    expect(rows.find(node => node.name === "MCP子")).toMatchObject({ parent_id: null, depth: 1 });
+
+    const moved = await mcp(admin.token, "requirement_tags", { action: "reparent", tag: "MCP子", parent: "MCP父" });
+    expect(moved).toMatchObject({ ok: true, op: "reparent", affected: 0, reparented: 1 });
+    expect((await nodes(admin.token)).find(node => node.name === "MCP子")).toMatchObject({ parent_id: "MCP父", depth: 2 });
+
+    // 与 REST 同一套错误码:不传 parent 键 ≠ 升到顶层
+    const missing = await mcp(admin.token, "requirement_tags", { action: "reparent", tag: "MCP子" });
+    expect(missing.error).toBe("invalid_tag_parent_id");
+    expect((await nodes(admin.token)).find(node => node.name === "MCP子")).toMatchObject({ parent_id: "MCP父" });
+  });
+
+  test("节点令牌:能 list,但写操作被拒(403 permission_denied),树不变", async () => {
+    const listed = await mcp(nodeToken, "requirement_tags", { action: "list" });
+    expect(Array.isArray(listed.nodes)).toBe(true);
+    const write = await mcp(nodeToken, "requirement_tags", { action: "reparent", tag: "MCP子", parent: null });
+    expect(write.status).toBe(403);
+    // 写操作先过「要人的令牌」这道闸(tags_write),再到 owner/admin 判定;节点令牌停在前一道。
+    expect(["user_token_required", "permission_denied"]).toContain(write.error);
+    expect((await nodes(admin.token)).find(node => node.name === "MCP子")).toMatchObject({ parent_id: "MCP父" });
+  });
+});

package/src/scheduled-requirement-wake-http.test.ts

@@ -268,6 +268,12 @@ describe("#1279 authoritative scoped requirement-event wake over HTTP/MCP", () =
       expect({exit:code,stderr:w.stderr().trim().slice(0,800)}).toEqual({exit:0,stderr:""});
       results.push(JSON.parse(output.trim().split("\n").at(-1)!).wake);}
     expect(results.sort()).toEqual([false,true]);expect(state(scheduleId).revision).toBe(before.revision+1);expect(poll(scheduleId)).toBe(false);
-  });
+  // #2198:显式预算。这条用例要起 2 个 Node 子进程、各自打开同一个磁盘 SQLite,
+  // 再用 /tmp 上的 gate 文件对齐起跑。默认 5s 在机器繁忙时会被打满,而**超时与断言
+  // 失败在报告里长得一样**(都只是一行 (fail)):实测 8 路并发 + 3× CPU 超订时,
+  // 11 轮里有 2 轮红,但每次红的都是 `timed out after 5000ms`,而 trues 恒为 1、
+  // revision 恒只 +1 —— 语义一直是对的,是预算不够。
+  // 这里只放宽**时间**,不放宽任何断言(仍然 [false,true]、仍然 revision+1、仍然 poll false)。
+  }, 30_000);
 
 });

package/src/server.ts

@@ -5250,10 +5250,31 @@ return Bun.serve({
       const management = lifecycleUser ? lifecycleProjections(restScope) : null;
       const rows = rawRows.map(r => {
         let role: string | null = null;
+        // #2293（admin 2026-10-25）—— 节点自报的 OpenCode V2 模型 id 清单（`provider/model` 字符串数组）。
+        // 客户端在**没有 daemon 绑定**时用它当建议列表。读法同 role：快照可能是文本或对象；
+        // 解析失败/形状不对 = 这一格没有（null），不影响整行。
+        let opencodeCatalog: string[] | null = null;
+        let opencodeGeneration: "v1" | "v2" | null = null;
+        let opencodeMode: string | null = null;
+        let opencodeServer: string | null = null;
         const snap = r.config_snapshot;
         if (snap) {
-          try { role = (typeof snap === "string" ? JSON.parse(snap) : snap)?.role ?? null; }
-          catch { /* malformed snapshot — leave role null */ }
+          let parsed: any = null;
+          try { parsed = typeof snap === "string" ? JSON.parse(snap) : snap; }
+          catch { parsed = null; }
+          role = parsed?.role ?? null;
+          const raw = parsed?.opencode_catalog;
+          if (Array.isArray(raw) && raw.every((m: unknown) => typeof m === "string" && m.length <= 400)) {
+            opencodeCatalog = raw.slice(0, 400);
+          }
+          // #2293 —— 客户端「Runtime · V2」和「OpenCode Server」两行要的正是快照里这三格标量。
+          // PR #1092 之前从 `node.config_snapshot` 读，但这个端点**刻意不带整个快照**
+          // （见上方 #312 注释）⇒ 真机上两行是空的/整行不出现。这里只放三个标量出来，
+          // 仍不暴露 flags 里的其它内容，更不暴露任何凭据。
+          const flags = parsed?.flags;
+          if (flags?.opencodeGeneration === "v1" || flags?.opencodeGeneration === "v2") opencodeGeneration = flags.opencodeGeneration;
+          if (typeof flags?.opencodeMode === "string" && flags.opencodeMode.length <= 32) opencodeMode = flags.opencodeMode;
+          if (typeof parsed?.opencode_server === "string" && parsed.opencode_server.length <= 200) opencodeServer = parsed.opencode_server;
         }
         const { config_snapshot, owner_user_id, ...rest } = r;
         // `tags` is stored as JSON text; hand the dashboard a real array so
@@ -5269,6 +5290,10 @@ return Bun.serve({
           tags: parseStoredTags(r.tags),
           attrs_revision: Number(r.attrs_revision ?? 0),
           role,
+          opencode_catalog: opencodeCatalog,
+          opencode_generation: opencodeGeneration,
+          opencode_mode: opencodeMode,
+          opencode_server: opencodeServer,
           lifecycle_controllable,
           lifecycle_daemon_node_id: controllable.get(r.node_id) ?? null,
           ...(management ? (management.get(r.node_id) ?? { managed: "none", adoption: null }) : {}),

package/src/tool-audience-http.test.ts

@@ -211,6 +211,12 @@ describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
   // assign_agent 合并成一个，尽量小）。实测 node 64,112 B / user 60,117 B，比原上限
   // 分别高 412 / 279 B —— 这是有意的功能增长（组织架构可由 Agent 直接调），不是文案偷偷变长。
   // 留约 400 B 余量；再要加工具时请先合并动作或砍描述，别连续抬上限。
+  // #2204（2026-10-25）：标签管理给 MCP。为了**不抬上限**，做了两件事：
+  //   ① 合并成一个工具 `requirement_tags`（action 分派 list/rename/merge/delete/color/reparent），
+  //      而不是 list + op 两个（照 #1894 `departments` 的先例）；
+  //   ② 砍掉一批冗长描述里重复的解释性从句（每条约 20–100 B，信息点全部保留）。
+  // 实测（含新工具）：all 97 / 86,020 B；node 64 / 64,464 B；user 64 / 59,680 B —— 三个上限**一个都没动**。
+  // 下次再加工具，请先合并动作或砍描述，不要直接改这三个数。
   const CEILINGS = { node: 64_500, user: 60_500, all: 86_500 } as const;
   test("node / user / all", async () => {
     const node = await listTools(T.node_normal);

package/src/tool-audience.ts

@@ -43,7 +43,7 @@ export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
   get_probe_request: "protocol", ack_probe_request: "protocol",
   get_opencode_catalog_request: "protocol", ack_opencode_catalog: "protocol",
   // ── 人:节点令牌一律 user_token_required(项目管理)/ node_token_cannot_browse_files / node_token_cannot_read_logs ──
-  projects_create: "user", projects_update: "user",
+  projects_create: "user", projects_update: "user", requirement_tags: "both",
   read_opencode_catalog: "user", get_opencode_catalog: "user",
   list_node_files: "user", read_node_file: "user", tail_node_logs: "user",
   // ── 两边都能调 ──

package/src/tools.ts

@@ -921,7 +921,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           revision: z.number().int().min(0).optional(),
         }).strict()).max(64),
         error: z.enum(["invalid_manifest", "unsafe_manifest", "read_failed"]).optional(),
-      }).strict().optional().describe("Bounded node-reported external schedule snapshot; never includes host paths or commands"),
+      }).strict().optional().describe("Node-reported schedules; never includes host paths or commands"),
       // RFC-024 B6 — masked snapshot of the node's effective config
       // (model + 6 dashboard-editable flags). Secrets ARE NOT in this
       // shape (env._envRef stays on host); the dashboard reads this
@@ -934,6 +934,16 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         model: z.string().max(200).optional().nullable(),
         flags: z.record(z.string(), z.unknown()).optional(),
         config_revision: z.number().int().min(0).optional(),
+        // #2293（admin 2026-10-25）—— 节点自己上报的 OpenCode V2 模型 id 清单
+        // （`provider/model`）。没有 daemon 绑定的节点靠这一格给客户端可选列表，
+        // 否则 admin 只能手填。只收 id：名字/设置/headers 可能带凭据，一律不收。
+        // 排成**一个字符串数组**而不是对象，是为了不抬 tools/list 的字节上限
+        // （约定见 tool-audience-http.test.ts：加字段先砍描述或合并，别改那三个数）。
+        // `.catch(undefined)`：形状不对只丢这一格，绝不拒掉整份心跳。
+        opencode_catalog: z.array(z.string()).max(400).optional().catch(undefined),
+        // #2293 —— 这台机器上 OpenCode serve 的 loopback 端点（`http://127.0.0.1:PORT`）。
+        // 客户端「OpenCode Server」行此前只能写「端口未上报」。只收 loopback URL，不收密码。
+        opencode_server: z.string().max(200).optional().catch(undefined),
         config_update_capable: z.boolean().optional(),
         peer_reply_inbox_capable: z.literal(true).optional(),
         side_thread_capability: z.object({
@@ -1993,7 +2003,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "send_task",
-    "Dispatch a task to a session's inbox (by alias). The reply carries queue_ahead (open tasks already on the target), target_busy, est_wait_minutes (rough, null = no history) and, when the queue is long, a warning: queued, never refused — consider an idle node.",
+    "Dispatch a task to a session's inbox (by alias). The reply carries queue_ahead, target_busy, est_wait_minutes (null = no history) and, when the queue is long, a warning. Always queued, never refused.",
     {
       alias: z.string().min(1).max(200).describe("Target session alias"),
       task: z.string().min(1).max(TASK_CONTENT_MAX).describe("Task content"),
@@ -2002,8 +2012,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       from_session: z.string().max(200).optional(),
       ttl_seconds: z.number().min(1).max(86400).optional().describe("Task TTL in seconds (default: 3600)"),
       network_id: z.string().max(200).optional().describe("Network scope"),
-      parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. When the child task replies the hub will auto-chain the answer to the parent task's originator, so the user sees the final result even if the intermediate session ends."),
-      meta: z.any().optional().describe("Optional structured task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
+      parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. The child's reply is auto-chained to the parent's originator, so the user sees the result even if the intermediate session ends."),
+      meta: z.any().optional().describe("Optional task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
       force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
     },
     async ({ alias, task, priority, context, from_session: _fromIn, ttl_seconds, network_id: netId, parent_task_id: parentIn, meta, force }) => {
@@ -2367,7 +2377,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // it always sent alias=undefined → -32602 "expected string, received
       // undefined at alias". The target was already knowable from the task,
       // so requiring the caller to pass it was a redundant-param trap.
-      alias: z.string().min(1).max(200).optional().describe("Target session alias — optional; derived from in_reply_to's task sender when omitted"),
+      alias: z.string().min(1).max(200).optional().describe("Target alias — optional; defaults to in_reply_to's sender"),
       text: z.string().min(1).max(10000).describe("Reply content"),
       in_reply_to: z.string().max(200).optional().describe("Original task/message ID"),
       status: z.enum(["replied", "failed", "cancelled"]).optional().default("replied").describe("Task outcome"),
@@ -2378,7 +2388,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // `attachments` before this schema entry existed would see `ok:true`
       // and never learn the attachments were dropped. Validated by
       // validateAttachments (uploads.ts) — the same helper the REST path uses.
-      attachments: z.any().optional().describe("Attachments, like send_task's meta.attachments: [{type:'file', file_id, name?, mime?, size?}]."),
+      attachments: z.any().optional().describe("Attachments, like send_task's: [{type:'file', file_id, name?, mime?, size?}]."),
       // #507 — optional structured metadata (parity with send_task L837). If
       // both `attachments` (top-level) and `meta.attachments` are supplied,
       // top-level wins (same rule as REST /api/task L2101).
@@ -2844,7 +2854,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   );
   server.tool(
     "send_peer_reply",
-    "Atomically finalize one node-owned task and enqueue one no-response result when the exact recipient advertises peer_reply_inbox_capable. Stored capability survives transient SSE disconnects; legacy peers return peer_reply_unsupported with zero writes.",
+    "Atomically finalize one node-owned task and enqueue one no-response result when the recipient advertises peer_reply_inbox_capable. Stored capability mismatch -> refused, not silently degraded.",
     replyToolSchema,
     (args) => handleReply(args, true),
   );
@@ -3465,7 +3475,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "update_node_config",
-    "Set the desired per-node config (model + flags) and push a doorbell to the node. The node pulls + validates + applies (hot or restart per field tier). RFC-024.",
+    "Set the per-node config (model + flags) and push a doorbell; the node pulls, validates and applies (hot or restart per field). RFC-024.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       base_revision: z.number().int().min(0).describe("Current revision per the dashboard's last GET — 409 if hub's current revision differs."),
@@ -4034,7 +4044,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "read_node_rules_file",
-    "Ask a node to send back its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) from its working directory. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
+    "Ask a node to send back its rules file (CLAUDE.md for claude, else AGENTS.md) from its work dir. No path argument. Poll get_rules_file_result with the returned request_id. app#225.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
@@ -4045,7 +4055,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "write_node_rules_file",
-    "Ask a node to overwrite its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) in its working directory with `content`. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
+    "Ask a node to write a managed block into its rules file (CLAUDE.md / AGENTS.md). Poll get_rules_file_result. User logins only (node owner or network owner/admin).",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
@@ -4057,7 +4067,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "list_node_skills",
-    "Ask a node to list the skills its runtime loads (name, scope project|user|system, display path, frontmatter description; team skills also include origin \"team\"). Read-only; no path argument. Poll get_rules_file_result — content is JSON {skills:[…], roots, warnings}.",
+    "Ask a node for the skills its runtime loads (name, scope project|user|system, display path, description; team skills add origin \"team\"). No path. Poll get_rules_file_result: {skills:[...], roots, warnings}.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
@@ -4068,7 +4078,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "read_node_skill",
-    "Ask a node for one skill's SKILL.md by name. Read-only; the node resolves the name under its own runtime's skills roots — no path argument. Poll get_rules_file_result — content is JSON {name, scope, path_rel, description, content, origin?}. origin is \"team\" only for a team skill.",
+    "One skill's SKILL.md by name; the node resolves it under its own skills roots (no path). Poll get_rules_file_result: {name, scope, path_rel, description, content, origin?}; origin=\"team\" only for a team skill.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
@@ -4080,7 +4090,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "list_node_files",
-    "Ask a node to list one directory level of its work dir (project folder view, read-only). `path` is relative to the work dir (default: the root); absolute paths and .. are refused. Poll get_rules_file_result — content is JSON {path, entries:[{name,type,size?,mtime?,hidden_reason?,no_descend?}], truncated, total}. User logins only.",
+    "List one level of the node's work dir (read-only). `path` relative (default root); absolute and .. refused. Poll get_rules_file_result: {path, entries:[{name,type,size?,mtime?,hidden_reason?,no_descend?}], truncated, total}. User logins only.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
@@ -4092,7 +4102,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "read_node_file",
-    "Ask a node for one text file under its work dir (project folder view, read-only, 256 KiB cap; binary / too large → size only; secret-looking files → name only). `path` is relative to the work dir. Poll get_rules_file_result — content is JSON {path, name, kind, size?, mtime?, content?, hidden_reason?}. User logins only.",
+    "One text file under the node's work dir (read-only, 256 KiB cap; binary / too large -> size only; secret-looking -> name only). `path` relative. Poll get_rules_file_result: {path, name, kind, size?, mtime?, content?, hidden_reason?}. User logins only.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
@@ -4104,14 +4114,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "tail_node_logs",
-    "Tail of a node's own agent-node run log (read-only, redacted on the node). No path argument: it reads only its own log directory. User logins only (node owner or network owner/admin). Poll get_rules_file_result; JSON {files, lines, truncated, matched}; handed out once, then purged.",
+    "Tail of the node's own run log (read-only, redacted on the node). No path argument. User logins only (node owner or network owner/admin). Poll get_rules_file_result: {files, lines, truncated, matched}; handed out once, then purged.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting logs_capable)."),
       lines: z.number().int().min(1).max(LOGS_MAX_LINES).optional().describe("How many of the newest matching lines (default 500, max 2000)."),
       level: z.enum(["info", "warn", "error"]).optional().describe("Only lines of exactly this level."),
       grep: z.string().min(1).max(LOGS_GREP_MAX).optional().describe("Case-insensitive substring, matched after redaction."),
-      since_ts: z.number().int().min(0).optional().describe("Only lines at or after this epoch-ms timestamp (follow mode; the client de-duplicates by line key)."),
+      since_ts: z.number().int().min(0).optional().describe("Only lines at/after this epoch-ms timestamp (follow mode; client de-dupes by line key)."),
       network_id: z.string().max(200).optional(),
     },
     async ({ node_id, child_node_id, alias, lines, level, grep, since_ts, network_id }) =>
@@ -4217,7 +4227,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "get_rules_file_result",
-    "Poll the outcome of a read_node_rules_file / write_node_rules_file request. Returns status pending|in_progress|done|failed|timeout, the file name the node used, and (for reads) the content. app#225.",
+    "Poll a read_node_rules_file / write_node_rules_file / node-file / node-log request. Returns status pending|in_progress|done|failed|timeout plus the file name and (reads) content. app#225.",
     { request_id: z.string().min(1).max(200), network_id: z.string().max(200).optional() },
     async ({ request_id: requestId, network_id: clientNetId }) => {
       const effectiveNetId = getNetworkId(clientNetId);
@@ -4298,7 +4308,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "restart_node",
-    "Trigger a node restart without changing config. RFC-024 Vincent 2026-06-28 increment. Network-scoped (SEC-1); member+ role suffices (lifecycle ops are not privilege elevation).",
+    "Restart a node without changing config (RFC-024). Network-scoped (SEC-1); member+ suffices — not privilege elevation.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       network_id: z.string().max(200).optional(),
@@ -4930,7 +4940,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // the policy and the runtime's session capability (see clone-node.ts).
   server.tool(
     "clone_node",
-    "Clone a daemon child into a new node on the same daemon. New name and new token. copy_session defaults to true. workdir_policy new_empty (default) or share_source. Hub #938.",
+    "Clone a daemon child into a new node on the same daemon: new name + token. copy_session defaults true; workdir_policy new_empty (default) or share_source. Hub #938.",
     {
       source_node_id: z.string().min(1).max(200),
       name: z.string().min(1).max(256),
@@ -5720,7 +5730,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "delete_node",
-    "Stop child + revoke ntok + delete hub row + (default) backup config to ~/.anet/deleted/<ts>-<alias>/ for 30d. confirm_alias must equal the node's alias. daemon_node_id is auto-resolved when omitted. RFC-027 §2.2.",
+    "Stop child + revoke token + delete hub row + (default) back up config to ~/.anet/deleted/<ts>-<alias>/ for 30d. confirm_alias must match. daemon_node_id auto-resolved. RFC-027 §2.2.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
@@ -6218,7 +6228,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // §2.3.4 — upsert_network_secret (OWNER-ONLY; vault write).
   server.tool(
     "upsert_network_secret",
-    "Write or replace a secret value in the network's vault (AES-GCM encrypted at rest). OWNER-only. RFC-028.",
+    "Create or replace one vault secret by key (value never read back). RFC-028.",
     {
       key: z.string().min(1).max(64).regex(/^[A-Z][A-Z0-9_]{0,63}$/),
       value: z.string().min(1).max(16 * 1024),
@@ -6776,7 +6786,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     name: z.string().min(1).max(80).optional(),
     priority: z.enum(["high", "normal", "low", "lowest"]).optional().describe("high = P0 最高, normal = P1 普通, low = P2 低, lowest = P3 极低"),
     column: z.enum(["pool", "doing", "done", "abandoned"]).optional(),
-    due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (stored as UTC seconds); \"\" clears"),
+    due: z.string().max(40).optional().describe("YYYY-MM-DD (all day) or ISO 8601 (stored as UTC seconds); \"\" clears"),
     start: z.string().max(40).optional().describe("start date (Gantt): same shapes as due; \"\" clears"),
     description: z.string().max(20_000).optional().describe("markdown"),
     checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
@@ -6888,14 +6898,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_create",
-    "Create a requirement task. name is required. column (or its alias status) = pool / doing / done / abandoned. A duplicate external_ref in the network returns 409 external_ref_exists with existing_id — use requirements_upsert_by_external_ref for syncing.",
+    "Create a task; name required. column (alias status) = pool/doing/done/abandoned. Duplicate external_ref -> 409 external_ref_exists with existing_id; use requirements_upsert_by_external_ref to sync.",
     { network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, name: z.string().min(1).max(80), external_ref: z.string().max(200).optional() },
     async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements", args.network_id, pick(a, REQ_WRITE_KEYS))),
   );
 
   server.tool(
     "requirements_update",
-    "Patch a requirement task (id or \"#N\"); omitted fields keep their value. column (or its alias status) moves it between pool / doing / done / abandoned. participants REPLACES the whole list; to add or remove people without dropping the others use participants_add / participants_remove. archived=true hides it from the default list (agents cannot delete).",
+    "Patch a task (id or \"#N\"); omitted fields keep their value. column (alias status) = pool/doing/done/abandoned. participants REPLACES the whole list (use participants_add / _remove to keep others). archived=true hides it; agents cannot delete.",
     { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, status: reqStatus, participants_add: reqPeopleDelta("add"), participants_remove: reqPeopleDelta("remove"), external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
     async (args) => withColumn(args, a => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(a, [...REQ_WRITE_KEYS, "participants_add", "participants_remove"]))),
   );
@@ -6909,7 +6919,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_upsert_by_external_ref",
-    "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or, if it already exists in the network, patch it (omitted fields — including column / status — are kept). Returns { requirement, created }.",
+    "Idempotent sync: create the task for external_ref (e.g. github:owner/repo#123) or update the one already bound to it. Returns { requirement, created }.",
     { network_id: z.string().max(200).optional(), external_ref: z.string().min(1).max(200), ...reqFields, status: reqStatus, archived: z.boolean().optional() },
     async (args) => withColumn(args, a => requirementsCall("POST", "/api/requirements/upsert", args.network_id, pick(a, REQ_WRITE_KEYS))),
   );
@@ -6926,7 +6936,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // write access and is refused to 「仅相关任务」(task-scoped) members; events use the task list's visibility.
   server.tool(
     "projects_create",
-    "Create a requirement project (管理项目 → 新建). name 1–40, unique; color #RRGGBB; sort int; parent_id optional (≤3 levels). Returns { project }. node tokens can only read projects (403 user_token_required); task-scoped / read-only members are refused.",
+    "Create a project (管理项目 → 新建). name 1-40, unique; color #RRGGBB; sort int; parent_id optional (<=3 levels). Returns { project }; node tokens can only read projects.",
     {
       network_id: z.string().max(200).optional(),
       name: z.string().min(1).max(40),
@@ -6939,7 +6949,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "projects_update",
-    "Rename, recolour, reorder, archive/unarchive, or move a project under another (parent_id; null = top level, cycles / depth>3 refused). Only the fields you pass change; archived hides it from pickers. Returns { project }. node tokens can only read projects (403); task-scoped / read-only members refused.",
+    "Rename, recolour, reorder, archive, or move a project under another (parent_id; null = top level; cycles / depth>3 refused). Only fields you pass change; node tokens can only read projects.",
     {
       network_id: z.string().max(200).optional(),
       id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
@@ -6952,6 +6962,33 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived", "parent_id"])),
   );
 
+  // #2204 —— 标签管理给 MCP:REST 早就有 rename/merge/delete/color/reparent,但只有人用的 HTTP,
+  // MCP 侧既读不到标签树、也改不了父级。做成**一个**工具(action 分派)而不是 list + op 两个:
+  // tools/list 字节预算是硬约束(all 86,500 / node 64,500 / user 60,500),两个工具会撑破预算,
+  // 而"抬预算"是仓里明令禁止的做法(见 tool-audience-http.test.ts 注释与 #1894 先例)。
+  server.tool(
+    "requirement_tags",
+    "Tags of this network. action=list → name, parent_id (null=root), depth, colour, usage, can_manage. Writes (owner/admin; node tokens 403): rename|merge|delete|color|reparent. reparent moves only the tree edge (cycle / depth>4 refused).",
+    {
+      network_id: z.string().max(200).optional(),
+      action: z.enum(["list", "rename", "merge", "delete", "color", "reparent"]),
+      tag: z.string().min(1).max(20).optional(),
+      from: z.union([z.string().min(1).max(20), z.array(z.string().min(1).max(20)).min(1).max(50)]).optional(),
+      to: z.string().min(1).max(20).optional(),
+      parent: z.string().min(1).max(20).nullable().optional(),
+      color: z.string().regex(/^#[0-9a-fA-F]{6}$/).nullable().optional(),
+    },
+    async (args) => {
+      if (args.action === "list") return requirementsCall("GET", "/api/requirements/tags", args.network_id);
+      const body: Record<string, unknown> = { op: args.action };
+      if (args.action === "rename" || args.action === "merge") { body.from = args.from; body.to = args.to; }
+      else if (args.action === "delete") body.tag = args.tag;
+      else if (args.action === "color") { body.tag = args.tag; body.color = args.color === undefined ? null : args.color; }
+      else { body.tag = args.tag; if ("parent" in args) body.parent = args.parent; }
+      return requirementsCall("POST", "/api/requirements/tags/ops", args.network_id, body);
+    },
+  );
+
   // #476 —— 不带 requirement_id 的全网动态默认 50 条(REST 默认 200 不变,App 走 REST);严格参数同 #471。
   const REQ_EVENTS_NETWORK_DEFAULT_LIMIT = 50;
   const reqEventsShape = {
@@ -6995,7 +7032,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // 两次调用,并发时覆盖别人刚写的描述。这条只追加,进「动态」(requirements_events kind=comment),不改任务本身。
   server.tool(
     "requirements_comment",
-    "Add a comment / progress note to a task (append-only; never rewrites the description). It shows in the task's activity timeline (the app's 动态, requirements_events kind=comment, text in new.text) under your name. text: markdown, 1–4000 characters. Anyone who can see the task and can write in the network (not read-only) may comment. Returns { event }.",
+    "Append a comment / progress note to a task (**append-only**; never rewrites the description). Shows in requirements_events (kind=comment, text in new.text). text: markdown 1-4000. Anyone who can see the task and write in the network may comment. Returns { event }.",
     {
       id: z.string().min(1).max(200).describe(REQ_ID_DESC),
       text: z.string().min(1).max(4000).describe("the comment (markdown), 1–4000 characters"),