@sleep2agi/commhub-server 0.9.0-preview.88 → 0.9.0-preview.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.88",
+  "version": "0.9.0-preview.90",
   "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/agent-access.ts

@@ -480,4 +480,8 @@ export const RESTRICTED_MEMBER_TOOLS: ReadonlySet<string> = new Set([
   "projects_create",
   "projects_update",
   "requirements_events",
+  // #474:评论走同一个 REST 处理 —— 看不见的任务 404、只读角色 403;受限成员的评论和他的其他任务写一样按可见性准入。
+  "requirements_comment",
+  // #473:通讯录同 /api/requirements/people 的可见范围 —— 受限成员看不见的 Agent 不出现(hiddenNodeFilter)。
+  "requirements_people",
 ]);

package/src/requirement-events.ts

@@ -56,11 +56,12 @@ export type EventCard = {
   archived: number | null;
 };
 
-export type EventKind = "created" | "changed" | "deleted";
+export type EventKind = "created" | "changed" | "deleted" | "comment";
 /**
  * field(kind = changed):column / title / priority / due / start / assignee / owner / agent_owner / participants /
  * tags / checklist_item(勾选或取消一项:{id,text,done})/ checklist(增删改条目:{total,done})/
  * description(只记字数,不存正文)/ project / parent / archived。
+ * kind = comment(#474):field 为 null,new = { text }(评论正文,≤ 4000 字),只追加,不对应任何字段的改动。
  */
 export type EventDraft = { kind: EventKind; field: string | null; old: unknown; new: unknown };
 

package/src/requirements-comment-http.test.ts

@@ -0,0 +1,165 @@
+// #474(MCP 任务生命周期测试报告问题 5)—— 评论 / 进展:只追加,进「动态」(requirement_events kind=comment),
+// 不改任务本身。钉住:
+//   - Agent(节点令牌)经 MCP、人经 REST 都能评论,署名是调用者;description / updated_at 一个字节都不动;
+//   - requirements_events 里是 kind=comment、new.text 全文,单任务的动态体积可控;
+//   - 看不见这张卡的人评论 = 404(和读一样),只读角色 = 403,空 / 超长 = 400 + 提示;
+//   - 只追加:没有改 / 删评论的路由。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { COMMENT_MAX_CHARS } from "./requirements.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-comment-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqCommentPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+let card = { id: "", seq: 0 };
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json, bytes: text.length };
+}
+async function rpc(token: string, name: string, args: Record<string, unknown>): Promise<{ data: any; raw: any; bytes: number }> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = out.result?.content?.[0]?.text ?? "";
+  let data: any = null;
+  try { data = JSON.parse(text); } catch { data = text; }
+  return { data, raw: out, bytes: text.length };
+}
+const mcp = async (token: string, name: string, args: Record<string, unknown>) => (await rpc(token, name, args)).data;
+const cardRow = (id: string) => db.get<{ description: string | null; updated_at: string | null; updated_by_json: string | null }>("SELECT description, updated_at, updated_by_json FROM requirements WHERE requirement_id = ?1", id)!;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`cmt_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.id]);
+  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}`;
+  const mk = async (username: string, role: string) => {
+    expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role })).status).toBe(200);
+    const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  const stamp = Date.now();
+  U.member = await mk(`cmt_member_${stamp}`, "member");
+  U.viewer = await mk(`cmt_viewer_${stamp}`, "viewer");
+  U.scoped = await mk(`cmt_scoped_${stamp}`, "member");
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.scoped.id}/task-grants`, { task_access: "scoped", project_grants: [] })).status).toBe(200);
+  U.nodeA = { token: createNetworkTokenForNode(U.owner.id, NET, "示例-甲", "node_cmt_a").token!, id: "node_cmt_a" };
+  const created = (await mcp(U.nodeA.token, "requirements_create", { name: "示例任务:评论", description: "## 背景\n原文。" })).requirement;
+  card = { id: created.id, seq: created.seq };
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirements_comment", () => {
+  test("an Agent comments over MCP (#N): one comment event, attributed to the node; the task itself is untouched", async () => {
+    const before = cardRow(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: `#${card.seq}`, text: "进展:示例草稿已写完,等人看。" });
+    expect(r.ok).toBe(true);
+    expect(r.event.kind).toBe("comment");
+    expect(r.event.field).toBeNull();
+    expect(r.event.new).toEqual({ text: "进展:示例草稿已写完,等人看。" });
+    expect(r.event.actor).toEqual({ kind: "node", id: "node_cmt_a" });
+    expect(r.event.requirement_id).toBe(card.id);
+    const after = cardRow(card.id);
+    expect(after).toEqual(before); // description, updated_at, updated_by all unchanged
+  });
+
+  test("a person comments over REST; both show in requirements_events with the full text, newest first", async () => {
+    const r = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "  好的,我下午看。  " });
+    expect(r.status).toBe(201);
+    expect(r.body.event.new.text).toBe("好的,我下午看。"); // trimmed
+    expect(r.body.event.actor).toEqual({ kind: "user", id: U.member.id });
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: `#${card.seq}` });
+    const comments = ev.data.events.filter((e: any) => e.kind === "comment");
+    expect(comments.map((e: any) => e.new.text)).toEqual(["好的,我下午看。", "进展:示例草稿已写完,等人看。"]);
+    expect(ev.data.events.at(-1).kind).toBe("created");
+  });
+
+  test("full text up to the cap, and the timeline stays small", async () => {
+    const long = "长".repeat(COMMENT_MAX_CHARS);
+    const r = await mcp(U.nodeA.token, "requirements_comment", { id: card.id, text: long });
+    expect(r.ok).toBe(true);
+    expect(r.event.new.text.length).toBe(COMMENT_MAX_CHARS);
+    const ev = await rpc(U.nodeA.token, "requirements_events", { requirement_id: card.id });
+    // 1 created + 3 comments (one of them 4000 chars): well under 20 KB.
+    expect(ev.bytes).toBeLessThan(20_000);
+    expect(ev.data.events.some((e: any) => e.kind === "comment" && e.new.text === long)).toBe(true);
+  });
+
+  test("bad input: empty → invalid_comment, over the cap → comment_too_long (REST), MCP schema → -32602; both with hints", async () => {
+    const empty = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "   " });
+    expect(empty.status).toBe(400);
+    expect(empty.body.error).toBe("invalid_comment");
+    expect(empty.body.field).toBe("text");
+    const tooLong = await rest(U.member.token, "POST", `/api/requirements/${card.id}/comments`, { text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(tooLong.status).toBe(400);
+    expect(tooLong.body.error).toBe("comment_too_long");
+    expect(tooLong.body.hint).toContain("Split");
+    const viaMcp = await rpc(U.nodeA.token, "requirements_comment", { id: card.id, text: "x".repeat(COMMENT_MAX_CHARS + 1) });
+    expect(String(viaMcp.raw.error?.code ?? viaMcp.raw.result?.content?.[0]?.text)).toMatch(/-32602|too big|Too big/i);
+  });
+
+  test("permissions: a non-reader gets 404 (like reading), a read-only role 403; neither writes anything", async () => {
+    const count = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND kind = 'comment'", card.id)!.n;
+    const n = count();
+    // scoped member with no grant cannot see the task → cannot read it → cannot comment on it.
+    expect((await rest(U.scoped.token, "GET", `/api/requirements/${card.id}`)).status).toBe(404);
+    const scoped = await rest(U.scoped.token, "POST", `/api/requirements/${card.id}/comments`, { text: "看不见也想评论" });
+    expect(scoped.status).toBe(404);
+    expect(scoped.body.error).toBe("requirement_not_found");
+    const viewer = await rest(U.viewer.token, "POST", `/api/requirements/${card.id}/comments`, { text: "只读角色" });
+    expect(viewer.status).toBe(403);
+    expect(viewer.body.error).toBe("permission_denied");
+    expect(count()).toBe(n);
+    // …and the scoped member does not see the comments in the network timeline either.
+    const ev = await rest(U.scoped.token, "GET", `/api/requirements/events?network_id=${NET}`);
+    expect((ev.body.events ?? []).some((e: any) => e.requirement_id === card.id)).toBe(false);
+  });
+
+  test("append-only: no route edits or deletes a comment; unknown task → requirement_not_found with a hint", async () => {
+    expect((await rest(U.owner.token, "PATCH", `/api/requirements/${card.id}/comments`, { text: "改" })).status).toBe(404);
+    expect((await rest(U.owner.token, "DELETE", `/api/requirements/${card.id}/comments`)).status).toBe(404);
+    const missing = await mcp(U.nodeA.token, "requirements_comment", { id: "#9999", text: "没有这张卡" });
+    expect(missing.error).toBe("requirement_not_found");
+    expect(missing.hint).toContain("requirements_list");
+  });
+
+  test("discoverable: tools/list carries requirements_comment, and requirements_events mentions comments", async () => {
+    const res = await fetch(`${BASE}/mcp`, {
+      method: "POST",
+      headers: { Authorization: `Bearer ${U.nodeA.token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/list" }),
+    });
+    const raw = await res.text();
+    const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+    const tools = (lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw)).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    expect(String(byName.get("requirements_comment")?.description)).toContain("append-only");
+    expect(String(byName.get("requirements_events")?.description)).toContain("kind=comment");
+  });
+});

package/src/requirements-errors-mcp-http.test.ts

@@ -0,0 +1,164 @@
+// #472(MCP 任务生命周期测试报告问题 4)—— 任务 / 项目接口的错误带上 field / message / hint,`error` 原样。
+// 每条提示一个测试(经 MCP,以 Agent / 人的身份),外加一道取集门:requirements.ts 里返回 / 抛出的每个错误码都在
+// requirements-errors.ts 的登记表里,新加的错误码没登记 ⇒ 红。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { __documentedErrorCodes, errorBody } from "./requirements-errors.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-errors-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqErrorsPassw0rd!xyz";
+let NET = "", ownerToken = "", ownerId = "", nodeToken = "", memberToken = "", cardId = "";
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(out.result.content[0].text);
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`reqerr_owner_${Date.now()}`, PW, undefined, "Owner");
+  ownerToken = a.token!; ownerId = a.user!.user_id; NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [ownerId]);
+  nodeToken = createNetworkTokenForNode(ownerId, NET, "示例-甲", "node_reqerr_a").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}`;
+  const username = `reqerr_member_${Date.now()}`;
+  expect((await rest(ownerToken, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+  memberToken = (await rest("", "POST", "/api/auth/login", { username, password: PW })).body.token;
+  cardId = (await mcp(nodeToken, "requirements_create", { name: "错误提示测试" })).requirement.id;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("each hint, over MCP", () => {
+  test("invalid_due: field due, the accepted formats", async () => {
+    for (const due of ["下周五", "2026/10/10"]) {
+      const r = await mcp(nodeToken, "requirements_update", { id: cardId, due });
+      expect(r.error).toBe("invalid_due");
+      expect(r.status).toBe(400);
+      expect(r.field).toBe("due");
+      expect(r.hint).toContain("YYYY-MM-DD");
+      expect(r.hint).toContain("ISO 8601");
+    }
+    expect((await mcp(nodeToken, "requirements_update", { id: cardId, start: "明天" })).field).toBe("start");
+  });
+
+  test("person_not_in_network: names the field, explains node_id vs user_id and where to find them", async () => {
+    const byAlias = await mcp(nodeToken, "requirements_update", { id: cardId, agent_owner: { kind: "node", id: "示例-甲" } });
+    expect(byAlias.error).toBe("person_not_in_network");
+    expect(byAlias.field).toBe("agent_owner");
+    // #473:人员字段也收名字 —— 提示改为指向 requirements_people,并说明 alias / username 的写法。
+    expect(byAlias.hint).toContain("requirements_people");
+    expect(byAlias.hint).toContain("{kind:'node', alias}");
+    expect((await mcp(nodeToken, "requirements_update", { id: cardId, owner: { kind: "user", id: "u_nobody" } })).field).toBe("owner");
+    expect((await mcp(nodeToken, "requirements_update", { id: cardId, participants: [{ kind: "node", id: "node_reqerr_a" }, { kind: "user", id: "u_nobody" }] })).field).toBe("participants");
+  });
+
+  test("project_not_in_network: a name is recognised as a name; both point to projects_list", async () => {
+    const byName = await mcp(nodeToken, "requirements_update", { id: cardId, project_id: "示例项目" });
+    expect(byName.error).toBe("project_not_in_network");
+    expect(byName.field).toBe("project_id");
+    expect(byName.message).toContain("looks like a project name");
+    expect(byName.hint).toContain("projects_list");
+    const byId = await mcp(nodeToken, "requirements_update", { id: cardId, project_id: "proj_missing" });
+    expect(byId.error).toBe("project_not_in_network");
+    expect(byId.message).not.toContain("project name");
+    expect(byId.hint).toContain("projects_list");
+  });
+
+  test("empty_patch: lists the writable fields; sending status says to use column", async () => {
+    // The MCP tool schema strips keys it does not know, so `status` arrives as nothing; REST sees the raw body.
+    const viaRest = await rest(nodeToken, "PATCH", `/api/requirements/${cardId}`, { status: "doing" });
+    expect(viaRest.status).toBe(400);
+    expect(viaRest.body.error).toBe("empty_patch");
+    expect(viaRest.body.hint).toContain("use column");
+    expect(viaRest.body.hint).toContain("Writable fields: column");
+    expect(viaRest.body.message).toContain("status");
+    const viaMcp = await mcp(nodeToken, "requirements_update", { id: cardId });
+    expect(viaMcp.error).toBe("empty_patch");
+    expect(viaMcp.hint).toContain("Writable fields:");
+    expect(viaMcp.hint).not.toContain("use column");
+  });
+
+  test("user_token_required: says projects are managed by people and what to do instead", async () => {
+    const r = await mcp(nodeToken, "projects_create", { name: "节点建项目" });
+    expect(r.error).toBe("user_token_required");
+    expect(r.status).toBe(403);
+    expect(r.message).toContain("node token");
+    expect(r.hint).toContain("projects_list");
+  });
+
+  test("network_id_required: field network_id and how to fix it", async () => {
+    const r = await mcp(memberToken, "projects_create", { name: "成员建项目" });
+    expect(r.error).toBe("network_id_required");
+    expect(r.field).toBe("network_id");
+    expect(r.hint).toContain("network_id");
+  });
+
+  test("swept codes carry hints too: checklist_item_not_found, external_ref_exists (existing_id kept), owner_must_be_human, parent_cycle", async () => {
+    const ck = await mcp(nodeToken, "requirements_checklist_toggle", { id: cardId, item_id: "nope", done: true });
+    expect(ck.error).toBe("checklist_item_not_found");
+    expect(ck.hint).toContain("requirements_get");
+    await mcp(nodeToken, "requirements_create", { name: "外部", external_ref: "github:example/repo#472" });
+    const dup = await mcp(nodeToken, "requirements_create", { name: "外部又一次", external_ref: "github:example/repo#472" });
+    expect(dup.error).toBe("external_ref_exists");
+    expect(typeof dup.existing_id).toBe("string");
+    expect(dup.hint).toContain("requirements_upsert_by_external_ref");
+    const own = await mcp(nodeToken, "requirements_update", { id: cardId, owner: { kind: "node", id: "node_reqerr_a" } });
+    expect(own.error).toBe("owner_must_be_human");
+    expect(own.hint).toContain("agent_owner");
+    const cyc = await mcp(nodeToken, "requirements_update", { id: cardId, parent_id: cardId });
+    expect(cyc.error).toBe("parent_cycle");
+    expect(cyc.field).toBe("parent_id");
+  });
+});
+
+describe("compatibility", () => {
+  test("REST keeps the exact error strings the app matches on; the new keys are additive", async () => {
+    const r = await rest(ownerToken, "PATCH", `/api/requirements/${cardId}`, { due: "下周五" });
+    expect(r.status).toBe(400);
+    expect(r.body.ok).toBe(false);
+    expect(r.body.error).toBe("invalid_due");
+    expect(Object.keys(r.body).sort()).toEqual(["error", "field", "hint", "message", "ok"]);
+    // A code without an entry is exactly the old shape.
+    expect(errorBody("some_future_code")).toEqual({ ok: false, error: "some_future_code" });
+  });
+
+  test("every error code requirements.ts returns or throws has an entry (a new code must be documented)", () => {
+    const src = readFileSync(join(import.meta.dir, "requirements.ts"), "utf8");
+    const codes = new Set<string>();
+    for (const m of src.matchAll(/jsonError\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/(?:new (?:Error|RequirementFieldError))\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/errorBody\(\s*["']([a-z_]+)["']/g)) codes.add(m[1]);
+    for (const m of src.matchAll(/return\s+["'](parent_[a-z_]+)["']/g)) codes.add(m[1]);
+    expect(codes.size).toBeGreaterThan(40); // the scan really found the codes (not an empty pass)
+    const documented = new Set(__documentedErrorCodes());
+    expect([...codes].filter(c => !documented.has(c)).sort()).toEqual([]);
+  });
+});

package/src/requirements-errors.ts

@@ -0,0 +1,138 @@
+// #472(MCP 任务生命周期测试报告问题 4)—— 任务 / 项目接口的错误不再只有一个代码。
+//
+// 以前回 `{ ok:false, error:"invalid_due" }`:app 按代码自己出文案,能用;但 MCP 上的 Agent 拿到的就只有这个词,
+// 不知道哪个字段错了、正确的格式是什么、下一步该调哪个工具。这里给每个代码配上:
+//   field   —— 出错的字段(有的话),
+//   message —— 一句英文说明(MCP 工具描述都是英文,读的是 LLM;app 不显示它),
+//   hint    —— 怎么改 / 下一步调什么。
+// 🔴 `error` 字符串原样不变:app、测试、脚本都按它匹配。新增的三个键旧客户端不认识,直接忽略。
+// 只有一个出口:requirements.ts 的 jsonError() 和抛错转换都走 errorBody(),不在调用点各写各的。
+
+export type ErrorContext = {
+  /** 出错的字段(调用点知道时传;不传就用登记表里的默认字段)。 */
+  field?: string;
+  /** 请求里实际带了哪些键(empty_patch 用来指出「你传了 status,该用 column」)。 */
+  sent?: readonly string[];
+  /** 可写字段(empty_patch 列出来)。 */
+  writable?: readonly string[];
+  /** 出错的那个值(project_not_in_network 用来判断是不是传了项目名)。 */
+  value?: unknown;
+};
+
+type Detail = { field?: string; message: string; hint?: string };
+type Entry = Detail | ((ctx: ErrorContext) => Detail);
+
+const DUE_FORMATS = 'YYYY-MM-DD (all day) or ISO 8601 with Z / ±HH:MM (e.g. 2026-10-10T18:00:00+08:00); "" clears it';
+// #473 —— 人员字段也收名字({kind:'user', username} / {kind:'node', alias}),只在任务所在的网络里解析;查人用 requirements_people。
+const PERSON_IDS = "Look people up with requirements_people (q= filters by name): it returns each member's user_id and username and the node_id and alias of their Agents. Pass {kind:'user', id} or {kind:'user', username}, {kind:'node', id} or {kind:'node', alias}; names resolve only in the task's own network.";
+
+const ENTRIES: Record<string, Entry> = {
+  // ── 定位 / 范围 ──
+  network_id_required: { field: 'network_id', message: 'This token can see more than one network (or is not bound to one), so the network must be named.', hint: 'Pass network_id (the network the task or project belongs to).' },
+  ambiguous_seq: { field: 'id', message: 'That #N exists in more than one network you can see.', hint: 'Pass network_id, or use the req_… id.' },
+  requirement_not_found: { field: 'id', message: 'No task with that id or #N in this network (or you cannot see it).', hint: 'Find it with requirements_list (q= searches titles; include_archived=true also lists archived tasks).' },
+  not_found: { message: 'No such task, project or route.', hint: 'Check the id; requirements_list / projects_list return the ids you can use.' },
+  project_not_found: { field: 'id', message: 'No project with that id in this network.', hint: 'Call projects_list to get project ids (proj_…).' },
+  tag_not_found: { field: 'tag', message: 'No task in this network carries that tag.', hint: 'Tags are free text on tasks; list the ones in use from requirements_list (view=summary shows each task’s tags).' },
+  checklist_item_not_found: { field: 'item_id', message: 'This task has no checklist item with that id.', hint: 'Item ids (ck_…) are in requirements_get → checklist[].id.' },
+  // ── 权限 ──
+  user_token_required: { message: 'This operation is for people only: a node token can read projects and read / create / update tasks, but cannot manage projects or delete tasks.', hint: 'Use an existing project (projects_list), or ask a person to create / change the project in the app (任务 → 管理项目).' },
+  permission_denied: { message: 'Your role in this network cannot do this (read-only, or task-scoped to other projects).', hint: 'Ask a network admin for write access, or work on tasks you can see.' },
+  upsert_not_allowed: { message: 'Task-scoped members cannot upsert by external_ref.', hint: 'Use requirements_create / requirements_update on tasks you can see.' },
+  external_ref_not_allowed: { field: 'external_ref', message: 'Task-scoped members cannot set external_ref.', hint: 'Leave external_ref out.' },
+  // ── 人员 ──
+  invalid_person: (ctx) => ({ field: ctx.field ?? 'owner', message: 'A person must be an object {kind:"user", id | username} or {kind:"node", id | alias}.', hint: PERSON_IDS }),
+  person_not_in_network: (ctx) => ({ field: ctx.field ?? 'owner', message: `${ctx.field ?? 'owner'} names nobody in this network (unknown id / username / alias, wrong kind, or a node you cannot see).`, hint: PERSON_IDS }),
+  person_ambiguous: (ctx) => ({ field: ctx.field ?? 'agent_owner', message: 'More than one Agent in this network has that alias.', hint: 'Call requirements_people (q=<alias>) and pass the node_id instead.' }),
+  owner_must_be_human: { field: 'owner', message: 'owner (负责人) must be a person.', hint: "Use owner: {kind:'user', id}. To assign a node / Agent, use agent_owner: {kind:'node', id}." },
+  agent_owner_must_be_agent: { field: 'agent_owner', message: 'agent_owner (负责 Agent) must be a node.', hint: "Use agent_owner: {kind:'node', id}. To assign a person, use owner: {kind:'user', id}." },
+  agent_owner_not_granted: { field: 'agent_owner', message: 'The current responsible Agent is one you are not granted, so you cannot replace or clear it.', hint: 'Leave agent_owner out of the patch.' },
+  invalid_participants: { field: 'participants', message: 'participants must be an array of up to 100 persons {kind, id}; it replaces the whole list.', hint: 'Send the full list you want (read it first with requirements_get).' },
+  invalid_participants_delta: { field: 'participants_add', message: 'participants_add / participants_remove must each be an array of up to 100 persons ({kind, id}, {kind:"user", username} or {kind:"node", alias}).', hint: PERSON_IDS },
+  participants_conflict: { field: 'participants', message: 'participants (replace the whole list) cannot be combined with participants_add / participants_remove.', hint: 'Use participants_add / participants_remove to change a few people, or participants alone to replace the list.' },
+  participants_add_remove_overlap: { field: 'participants_remove', message: 'The same person is in both participants_add and participants_remove.', hint: 'Send each person in only one of the two lists.' },
+  too_many_participants: { field: 'participants_add', message: 'A task can have at most 100 participants.', hint: 'Remove some with participants_remove first.' },
+  status_conflicts_with_column: { field: 'status', message: 'status is an alias of column, and the two values sent differ.', hint: 'Send only one of them (pool, doing or done).' },
+  invalid_assignee: { field: 'assignee', message: 'assignee must be a string (legacy free-text field).', hint: 'Prefer owner / agent_owner.' },
+  // ── 项目 ──
+  invalid_project: { field: 'project_id', message: 'project_id must be a project id string or null.', hint: 'Call projects_list to get project ids (proj_…); null removes the task from its project.' },
+  project_not_in_network: (ctx) => {
+    const looksLikeName = typeof ctx.value === 'string' && !/^proj_/.test(ctx.value);
+    return {
+      field: ctx.field ?? 'project_id',
+      message: looksLikeName ? `"${String(ctx.value).slice(0, 40)}" is not a project id — it looks like a project name.` : 'No project with that id in this network.',
+      hint: 'Call projects_list and pass the project’s id (proj_…), not its name.',
+    };
+  },
+  project_archived: { field: 'project_id', message: 'That project is archived.', hint: 'Pick an active project from projects_list, or ask a person to unarchive it.' },
+  project_name_taken: { field: 'name', message: 'A project with that name already exists in this network.', hint: 'Use the existing one (projects_list) or choose another name.' },
+  invalid_project_name: { field: 'name', message: 'Project name must be 1–40 characters.' },
+  invalid_project_color: { field: 'color', message: 'color must be #RRGGBB.' },
+  invalid_project_sort: { field: 'sort', message: 'sort must be an integer.' },
+  invalid_project_archived: { field: 'archived', message: 'archived must be true or false.' },
+  too_many_projects: { message: 'This network has reached the project limit (200).', hint: 'Reuse an existing project (projects_list).' },
+  // ── 任务字段 ──
+  empty_patch: (ctx) => {
+    const sent = ctx.sent ?? [];
+    const writable = ctx.writable?.length ? ctx.writable.join(', ') : 'name, column, priority, due, start, description, checklist, tags, owner, agent_owner, participants, project_id, parent_id, external_ref, external_url, archived';
+    const statusHint = sent.includes('status') ? 'To move a task between pool / doing / done, use column (status is the name of the list filter). ' : '';
+    return { message: sent.length ? `None of the keys sent (${sent.join(', ')}) is a writable field.` : 'The patch changes nothing.', hint: `${statusHint}Writable fields: ${writable}.` };
+  },
+  invalid_json: { message: 'The request body must be a JSON object.' },
+  invalid_name: { field: 'name', message: 'name must be 1–80 characters.' },
+  invalid_description: { field: 'description', message: 'description must be a string (markdown) of at most 20 000 characters.' },
+  invalid_column: { field: 'column', message: 'column must be pool, doing or done.' },
+  invalid_status: { field: 'status', message: 'status (list filter) must be pool, doing or done.' },
+  invalid_priority: { field: 'priority', message: 'priority must be high (P0), normal (P1), low (P2) or lowest (P3).' },
+  invalid_due: { field: 'due', message: 'due is not a date this hub understands.', hint: `Use ${DUE_FORMATS}.` },
+  invalid_start: { field: 'start', message: 'start is not a date this hub understands.', hint: `Use ${DUE_FORMATS}.` },
+  invalid_tags: { field: 'tags', message: 'tags must be an array of at most 10 strings, each 1–20 characters.', hint: 'Omit tags to keep them, [] to clear.' },
+  invalid_checklist: { field: 'checklist', message: 'checklist must be an array of up to 100 items {text (1–500 chars), done?, id?}; it replaces the whole list.', hint: 'To tick one item use requirements_checklist_toggle (item ids from requirements_get).' },
+  invalid_done: { field: 'done', message: 'done must be true or false.' },
+  invalid_parent_id: { field: 'parent_id', message: 'parent_id must be a task id in this network (or null to detach).', hint: 'Get the parent’s req_… id from requirements_list / requirements_get.' },
+  parent_cycle: { field: 'parent_id', message: 'That parent would make the task its own ancestor.', hint: 'Pick a parent that is not this task or one of its children.' },
+  parent_too_deep: { field: 'parent_id', message: 'Tasks nest at most 5 levels.', hint: 'Attach it to a higher-level task.' },
+  parent_not_found: { field: 'parent_id', message: 'No task with that parent_id in this network (or you cannot see it).', hint: 'Get the parent’s req_… id from requirements_list / requirements_get.' },
+  invalid_external_ref: { field: 'external_ref', message: 'external_ref must start with a letter or digit and use only letters, digits and _ . : / # @ + - (≤ 200 characters).', hint: 'e.g. github:owner/repo#123' },
+  external_ref_required: { field: 'external_ref', message: 'external_ref is required for upsert.' },
+  external_ref_exists: { field: 'external_ref', message: 'A task with that external_ref already exists in this network (existing_id).', hint: 'Use requirements_upsert_by_external_ref to sync, or requirements_update on existing_id.' },
+  invalid_external_url: { field: 'external_url', message: 'external_url must be an http(s) URL of at most 500 characters, or null.' },
+  invalid_issues: { field: 'issues', message: 'issues must be an array of issue references.' },
+  invalid_archived: { field: 'archived', message: 'archived must be true or false.' },
+  invalid_seq: { field: 'seq', message: 'seq must be a positive integer (the #N shown for a task).' },
+  invalid_client_id: { field: 'client_id', message: 'client_id must be 1–80 characters of letters, digits, ., _ or -.' },
+  client_id_taken: { field: 'client_id', message: 'That client_id was already used for another task.', hint: 'Generate a new client_id for each new task.' },
+  // ── 列表 / 事件 ──
+  invalid_view: { field: 'view', message: 'view must be full or summary.' },
+  invalid_limit: { field: 'limit', message: 'limit is out of range.' },
+  invalid_cursor: { field: 'cursor', message: 'cursor is not one this hub issued.', hint: 'Pass next_cursor from the previous page unchanged, or start again without cursor.' },
+  invalid_updated_since: { field: 'updated_since', message: 'updated_since must be an ISO 8601 time.', hint: 'Use server_time from the previous changes=true response.' },
+  updated_since_required: { field: 'updated_since', message: 'changes=true needs updated_since.', hint: 'Pass updated_since (ISO time; server_time from the last call).' },
+  invalid_since: { field: 'since', message: 'since must be an ISO 8601 time.', hint: 'Use server_time from the previous requirements_events response.' },
+  invalid_comment: { field: 'text', message: 'A comment needs non-empty text.', hint: 'Pass text (markdown), e.g. a progress note or a conclusion.' },
+  comment_too_long: { field: 'text', message: 'A comment can be at most 4000 characters.', hint: 'Split it into several comments, or put the long part in the description.' },
+  insert_failed: { message: 'The hub could not save the task.', hint: 'Retry once; if it fails again, report it.' },
+};
+
+/** 错误响应体:`error` 原样,补上 field / message / hint(登记表里没有的代码就只有 error,和以前一样)。 */
+export function errorBody(error: string, ctx: ErrorContext = {}): { ok: false; error: string; field?: string; message?: string; hint?: string } {
+  const entry = ENTRIES[error];
+  if (!entry) return { ok: false, error };
+  const d = typeof entry === 'function' ? entry(ctx) : entry;
+  const field = ctx.field ?? d.field;
+  return { ok: false, error, ...(field ? { field } : {}), message: d.message, ...(d.hint ? { hint: d.hint } : {}) };
+}
+
+/** 带字段的抛错:assignments / projectRef 里抛,调用点的 catch 用 errorFrom() 转成响应。 */
+export class RequirementFieldError extends Error {
+  constructor(code: string, readonly field?: string, readonly value?: unknown) { super(code); }
+}
+
+export function errorFrom(e: unknown, status = 400): Response {
+  const code = (e as Error)?.message ?? 'invalid_json';
+  const fe = e instanceof RequirementFieldError ? e : null;
+  return Response.json(errorBody(code, { field: fe?.field, value: fe?.value }), { status });
+}
+
+/** Test-only: every code with an entry. */
+export const __documentedErrorCodes = (): string[] => Object.keys(ENTRIES);