@sleep2agi/commhub-server 0.9.0-preview.155 → 0.9.0-preview.157

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.155",
+  "version": "0.9.0-preview.157",
   "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/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/requirement-tag-ops-http.test.ts

@@ -264,3 +264,162 @@ describe("改名 / 合并 / 删除 / 颜色", () => {
     expect(cardTags("net2")).toEqual(["UI", "交互"]);
   });
 });
+
+// ── 改父级(reparent) ──
+// 客户端(0.297+)的「管理标签」里要能改父级;Hub 侧此前只缺这一个 op。
+// 这里只验树:reparent 不给标签改名、不动任何卡片的 tags 数组。
+describe("改父级 reparent", () => {
+  const createTag = (token: string, name: string, parent: string | null = null) =>
+    send(token, "POST", `/api/requirements/tags/create?network_id=${NET}`, { name, parent_id: parent });
+  const nodesOf = 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 }>;
+  const nodeOf = async (token: string, name: string) => (await nodesOf(token)).find(node => node.name === name)!;
+
+  test("搬到另一个标签下面,再搬回顶层:父与深度都跟着变,卡片一张都不动", async () => {
+    expect((await createTag(admin.token, "RP根")).status).toBe(201);
+    expect((await createTag(admin.token, "RP枝")).status).toBe(201);
+    expect((await createTag(admin.token, "RP叶", "RP枝")).status).toBe(201);
+    const before = db.get("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET).n;
+
+    const moved = await op(admin.token, { op: "reparent", tag: "RP叶", parent: "RP根" });
+    expect(moved.status).toBe(200);
+    expect(moved.body).toMatchObject({ ok: true, op: "reparent", affected: 0, reparented: 1 });
+    expect(await nodeOf(admin.token, "RP叶")).toMatchObject({ parent_id: "RP根", depth: 2 });
+    // 原来是 RP枝 的子孙,搬走之后 RP枝 下面没有它了
+    expect((await nodesOf(admin.token)).filter(node => node.parent_id === "RP枝")).toEqual([]);
+
+    const back = await op(admin.token, { op: "reparent", tag: "RP叶", parent: null });
+    expect(back.status).toBe(200);
+    expect(await nodeOf(admin.token, "RP叶")).toMatchObject({ parent_id: null, depth: 1 });
+    // 只动树:卡片数与卡的标签都没变
+    expect(db.get("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET).n).toBe(before);
+  });
+
+  test("父是自己的子孙 = 环,拒绝(400 tag_parent_cycle),树一个字都不改", async () => {
+    expect((await createTag(admin.token, "RP环甲")).status).toBe(201);
+    expect((await createTag(admin.token, "RP环乙", "RP环甲")).status).toBe(201);
+    const r = await op(admin.token, { op: "reparent", tag: "RP环甲", parent: "RP环乙" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("tag_parent_cycle");
+    expect(await nodeOf(admin.token, "RP环甲")).toMatchObject({ parent_id: null });
+  });
+
+  test("自己当自己的父:解析阶段就拒(400 tag_parent_cycle)", async () => {
+    const r = await op(admin.token, { op: "reparent", tag: "RP根", parent: "RP根" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("tag_parent_cycle");
+  });
+
+  test("连子树一起搬:新父深度 + 子树高度 > 4 就拒(400 tag_depth_exceeded)", async () => {
+    expect((await createTag(admin.token, "RPD1")).status).toBe(201);
+    expect((await createTag(admin.token, "RPD2", "RPD1")).status).toBe(201);
+    expect((await createTag(admin.token, "RPD3", "RPD2")).status).toBe(201);     // 3 层:1>2>3
+    expect((await createTag(admin.token, "RPX")).status).toBe(201);
+    expect((await createTag(admin.token, "RPY", "RPX")).status).toBe(201);       // 2 层子树
+    // 把 2 层的 RPX(含 RPY)挂到第 3 层下面 → 最深 5 层 > 4
+    const r = await op(admin.token, { op: "reparent", tag: "RPX", parent: "RPD3" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("tag_depth_exceeded");
+    expect(await nodeOf(admin.token, "RPX")).toMatchObject({ parent_id: null });
+    // 只搬叶子(高度 1)就正好 4 层,允许
+    const ok = await op(admin.token, { op: "reparent", tag: "RPY", parent: "RPD3" });
+    expect(ok.status).toBe(200);
+    expect(await nodeOf(admin.token, "RPY")).toMatchObject({ parent_id: "RPD3", depth: 4 });
+  });
+
+  test("父不存在 = 404,不静默升到根", async () => {
+    const r = await op(admin.token, { op: "reparent", tag: "RP根", parent: "不存在的父" });
+    expect(r.status).toBe(404);
+    expect(r.body.error).toBe("tag_parent_not_found");
+    expect(await nodeOf(admin.token, "RP根")).toMatchObject({ parent_id: null });
+  });
+
+  test("缺 parent 键 = 400(不能用「没传」把标签静默升到根);parent 为空串 = 顶层", async () => {
+    const missing = await op(admin.token, { op: "reparent", tag: "RP根" });
+    expect(missing.status).toBe(400);
+    expect(missing.body.error).toBe("invalid_tag_parent_id");
+    expect(await nodeOf(admin.token, "RP根")).toMatchObject({ parent_id: null });
+
+    expect((await op(admin.token, { op: "reparent", tag: "RP根", parent: "RPD1" })).status).toBe(200);
+    const root = await op(admin.token, { op: "reparent", tag: "RP根", parent: "" });
+    expect(root.status).toBe(200);
+    expect(await nodeOf(admin.token, "RP根")).toMatchObject({ parent_id: null });
+  });
+
+  test("只在卡片上出现过的老标签也能改父级:先登记成节点,再挂到父下面", async () => {
+    const inUse = (await nodesOf(admin.token)).find(node => node.registered === false);
+    if (!inUse) return;                       // 该网络里没有"未登记但在用"的标签时,这条不适用
+    const r = await op(admin.token, { op: "reparent", tag: inUse.name, parent: "RPD1" });
+    expect(r.status).toBe(200);
+    const after = await nodeOf(admin.token, inUse.name);
+    expect(after).toMatchObject({ parent_id: "RPD1", depth: 2, registered: true });
+    // 卡片上的标签字符串不变(改父级不是改名)
+    const stillUsed = db.all<{ tags_json: string }>("SELECT tags_json FROM requirements WHERE network_id = ?1 AND tags_json LIKE ?2", NET, `%${inUse.name}%`);
+    expect(stillUsed.length).toBeGreaterThan(0);
+  });
+
+  test("reparent 走同一把标签管理锁:节点令牌与 viewer 都拒(403),树不变", async () => {
+    const byNode = await op(nodeToken, { op: "reparent", tag: "RP根", parent: "RPD1" });
+    expect(byNode.status).toBe(403);
+    const byViewer = await op(vic.token, { op: "reparent", tag: "RP根", parent: "RPD1" });
+    expect(byViewer.status).toBe(403);
+    expect(await nodeOf(admin.token, "RP根")).toMatchObject({ parent_id: null });
+  });
+});
+
+describe("改父级 reparent —— 被拒绝时不留副作用", () => {
+  const nodes = async () => (await send(admin.token, "GET", `/api/requirements/tags?network_id=${NET}`)).body.nodes as Array<{ name: string; parent_id: string | null; registered: boolean }>;
+  test("只在卡片上用过的标签,reparent 到不存在的父:404 且**不会**被登记进树", async () => {
+    const before = (await nodes()).filter(node => !node.registered).map(node => node.name);
+    if (!before.length) return;                 // 该网络里没有"未登记但在用"的标签时,这条不适用
+    const name = before[0];
+    const r = await op(admin.token, { op: "reparent", tag: name, parent: "根本没有这个父" });
+    expect(r.status).toBe(404);
+    expect(r.body.error).toBe("tag_parent_not_found");
+    // 关键:事务返回错误码是**提交**语义,若先 INSERT 登记再报错,这里就会看到 registered=true
+    const after = (await nodes()).find(node => node.name === name);
+    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/requirement-tag-tree.ts

@@ -95,3 +95,33 @@ export function buildTagNodes(registered: TagNodeRow[], inUse: string[]): TagNod
   }
   return nodes.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
+
+/**
+ * name 这棵子树有几层(叶子 = 1)。改父级时用它算「搬过去之后最深到几层」:
+ * 只检查新父的深度是不够的 —— 一个 3 层的子树挂到第 3 层下,最深会到 5 层。
+ * 历史脏数据里有环时用 visited 兜住,不要为脏数据死循环。
+ */
+export function tagSubtreeHeight(name: string, parentOf: Map<string, string | null>): number {
+  const childrenOf = new Map<string, string[]>();
+  for (const [child, parent] of parentOf) {
+    if (!parent) continue;
+    const list = childrenOf.get(parent);
+    if (list) list.push(child); else childrenOf.set(parent, [child]);
+  }
+  let height = 1;
+  let frontier = [name];
+  const seen = new Set<string>([name]);
+  for (;;) {
+    const next: string[] = [];
+    for (const node of frontier) {
+      for (const child of childrenOf.get(node) ?? []) {
+        if (seen.has(child)) continue;
+        seen.add(child);
+        next.push(child);
+      }
+    }
+    if (!next.length) return height;
+    height++;
+    frontier = next;
+  }
+}

package/src/requirement-tags.ts

@@ -23,7 +23,9 @@ export type TagOp =
   | { op: "rename"; from: string; to: string }
   | { op: "merge"; from: string[]; to: string }
   | { op: "delete"; tag: string }
-  | { op: "color"; tag: string; color: string | null };
+  | { op: "color"; tag: string; color: string | null }
+  // 改父级(标签树自己的层级,与卡片无关):parent=null = 升为顶层。
+  | { op: "reparent"; tag: string; parent: string | null };
 
 /** 单个标签名,规则同 normalizeTags。不合法 = null。 */
 export function tagName(value: unknown): string | null {
@@ -66,6 +68,17 @@ export function parseTagOp(body: Record<string, unknown>): TagOp | { error: stri
       if (body.color !== null && (typeof body.color !== "string" || !TAG_COLOR.test(body.color))) return { error: "invalid_tag_color" };
       return { op: "color", tag, color: body.color === null ? null : (body.color as string).toLowerCase() };
     }
+    case "reparent": {
+      const tag = tagName(body.tag);
+      if (!tag) return { error: "invalid_tag" };
+      // 与 create 同一套读法:缺省 key 算错(不能靠"没传"把标签静默升到根),显式 null = 根。
+      if (!("parent" in body)) return { error: "invalid_tag_parent_id" };
+      if (body.parent === null || body.parent === "") return { op: "reparent", tag, parent: null };
+      const parent = tagName(body.parent);
+      if (!parent) return { error: "invalid_tag_parent_id" };
+      if (parent === tag) return { error: "tag_parent_cycle" };
+      return { op: "reparent", tag, parent };
+    }
     default:
       return { error: "invalid_tag_op" };
   }

package/src/requirements.ts

@@ -8,7 +8,7 @@ import { db, logAudit } from "./db.js";
 import { resolveNodeCaller } from "./create-node.js";
 import { markGzipReusable } from "./http-gzip.js";
 import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from "./requirement-tags.js";
-import { buildTagNodes, MAX_TAG_DEPTH, parseCreateTag, TAG_TREE_CAPABILITY, tagDepth, type TagNodeRow } from "./requirement-tag-tree.js";
+import { buildTagNodes, isDescendant, MAX_TAG_DEPTH, parseCreateTag, TAG_TREE_CAPABILITY, tagDepth, tagSubtreeHeight, type TagNodeRow } from "./requirement-tag-tree.js";
 import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-stats.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
@@ -547,13 +547,37 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
     const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
     // 「存在」= 有卡片在用 / 有颜色行 / 是登记过的树节点。最后一种让 0 任务的标签也能改名、合并、删除、上色。
     const nodeExists = (name: string) => !!db.get<{ x: number }>("SELECT 1 AS x FROM network_tag_nodes WHERE network_id = ?1 AND name = ?2", networkId, name);
-    const known = cards.some(card => storedTags(card.tags_json).some(tag => sources.includes(tag))) || sources.some(tag => colorOf(tag) !== null || nodeExists(tag));
+    // 「存在」的三种形态(卡片在用 / 有颜色行 / 登记过的树节点),reparent 判父存在时用的是同一个口径。
+    const tagExists = (name: string) => cards.some(card => storedTags(card.tags_json).includes(name)) || colorOf(name) !== null || nodeExists(name);
+    const known = sources.some(tagExists);
     if (!known) return null;
     if (op.op === "color") {
       if (op.color === null) db.run("DELETE FROM network_tags WHERE network_id = ?1 AND name = ?2", [networkId, op.tag]);
       else db.run("INSERT INTO network_tags (network_id, name, color, updated_at) VALUES (?1, ?2, ?3, ?4) ON CONFLICT (network_id, name) DO UPDATE SET color = excluded.color, updated_at = excluded.updated_at", [networkId, op.tag, op.color, now]);
       return { affected: 0 };
     }
+    // 改父级:只动标签树,不动任何卡片(标签仍然是卡片 tags_json 里的字符串)。
+    // 三条规则都明确拒绝而不是静默纠正:父必须存在、不许成环、搬完最深不超过 MAX_TAG_DEPTH。
+    if (op.op === "reparent") {
+      const nodes = db.all<TagNodeRow>("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1", networkId);
+      const parentOf = new Map(nodes.map(row => [row.name, row.parent_name ?? null]));
+      // 只在卡片上出现过的老标签没有行可改,要登记成顶层节点(这不是把它降级,它本来就没有父)。
+      // ⚠ 先**在虚拟树上**判环与深度,判过了再写:事务返回 {error} 是提交而不是回滚,
+      //   如果先 INSERT 登记再返回错误,调用方看到的是"被拒绝了",库里却多了一行 —— 树被静默改过。
+      const virtual = new Map(parentOf);
+      if (!virtual.has(op.tag)) virtual.set(op.tag, null);
+      if (op.parent) {
+        if (!tagExists(op.parent)) return { error: "tag_parent_not_found" };
+        if (!virtual.has(op.parent)) virtual.set(op.parent, null);
+        // 环:父是自己(parse 已挡)或自己的子孙(这里挡)。深度:新父的深度 + 自己这棵子树的高度。
+        if (isDescendant(op.parent, op.tag, virtual)) return { error: "tag_parent_cycle" };
+        if (tagDepth(op.parent, virtual) + tagSubtreeHeight(op.tag, virtual) > MAX_TAG_DEPTH) return { error: "tag_depth_exceeded" };
+      }
+      if (!parentOf.has(op.tag)) db.run("INSERT INTO network_tag_nodes (network_id, name, parent_name, created_at, updated_at, created_by_json) VALUES (?1, ?2, NULL, ?3, ?3, ?4)", [networkId, op.tag, now, actor]);
+      if (op.parent && !parentOf.has(op.parent)) db.run("INSERT INTO network_tag_nodes (network_id, name, parent_name, created_at, updated_at, created_by_json) VALUES (?1, ?2, NULL, ?3, ?3, ?4)", [networkId, op.parent, now, actor]);
+      db.run("UPDATE network_tag_nodes SET parent_name = ?1, updated_at = ?2 WHERE network_id = ?3 AND name = ?4", [op.parent, now, networkId, op.tag]);
+      return { affected: 0, reparented: 1 };
+    }
     let affected = 0;
     for (const card of cards) {
       const next = applyTagOp(storedTags(card.tags_json), op);
@@ -567,13 +591,14 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
     return { affected, reparented };
   });
   if (!result) return jsonError("tag_not_found", 404);
+  if ("error" in result) return jsonError(result.error, result.error === "tag_parent_not_found" ? 404 : 400);
   if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, `requirement_tag_${op.op}`, "requirement_tag", op.op === "rename" || op.op === "merge" ? op.to : op.tag, JSON.stringify({ ...op, affected: result.affected }).slice(0, 1000), undefined, networkId);
   return Response.json({ ok: true, op: op.op, affected: result.affected, reparented: result.reparented });
 }
 
 /** 改名 / 合并:目标没有颜色就继承第一个有颜色的来源;来源的颜色行删掉。删除:删颜色行。 */
 function moveTagColors(networkId: string, op: TagOp, colorOf: (name: string) => string | null, now: string): void {
-  if (op.op === "color") return;
+  if (op.op === "color" || op.op === "reparent") return;
   const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
   if (op.op !== "delete" && colorOf(op.to) === null) {
     const inherited = sources.map(colorOf).find(color => color !== null);
@@ -590,7 +615,7 @@ function moveTagColors(networkId: string, op: TagOp, colorOf: (name: string) =>
  * 返回被改挂的节点数(客户端能报「N 个子标签已上移」)。
  */
 function maintainTagTree(networkId: string, op: TagOp, now: string): number {
-  if (op.op === "color") return 0;
+  if (op.op === "color" || op.op === "reparent") return 0;
   const rows = db.all<TagNodeRow>("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1", networkId);
   if (!rows.length) return 0;
   const parentOf = new Map(rows.map(row => [row.name, row.parent_name ?? 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

@@ -1993,7 +1993,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"),
@@ -2844,7 +2844,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 +3465,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 +4034,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 +4045,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 +4057,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 +4068,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 +4080,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 +4092,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,7 +4104,7 @@ 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)."),
@@ -4217,7 +4217,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 +4298,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 +4930,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 +5720,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 +6218,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),
@@ -6888,14 +6888,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 +6909,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 +6926,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 +6939,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 +6952,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 +7022,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"),