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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.154",
+  "version": "0.9.0-preview.156",
   "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/project-viewer-can-http.test.ts

@@ -91,7 +91,9 @@ describe("GET /api/requirements/projects 的 viewer_can.edit", () => {
 
   test("只加字段:其余键与之前逐字相同", async () => {
     const row = (await projects("alice"))["pvc-P2"];
-    expect(Object.keys(row).sort()).toEqual(["archived", "color", "createdAt", "id", "name", "sort", "viewer_can"]);
+    // parentId 是 2026-10-24 加的「子项目」字段（admin：管理项目里看不到层级）；
+    // 它同样是加法式的：这里钉的是「已知键一个不多一个不少」，新键必须显式加进这个清单。
+    expect(Object.keys(row).sort()).toEqual(["archived", "color", "createdAt", "id", "name", "parentId", "sort", "viewer_can"]);
     expect(Object.keys(row.viewer_can)).toEqual(["edit"]);
   });
 

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

@@ -264,3 +264,120 @@ 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);
+  });
+});

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-errors.ts

@@ -40,6 +40,13 @@ const ENTRIES: Record<string, Entry> = {
   tag_parent_not_found: { field: 'parent_id', message: 'No tag named that in this network.', hint: 'Create the parent first (parent_id: null), or read GET /api/requirements/tags → nodes for the names that exist.' },
   invalid_tag_parent_id: { field: 'parent_id', message: 'parent_id must be a tag name in this network, or null for the root.', hint: 'Tag names are 1–20 characters; read GET /api/requirements/tags → nodes for the names that exist.' },
   tag_parent_cycle: { field: 'parent_id', message: 'A tag cannot be its own parent.', hint: 'Pass a different parent, or null for the root.' },
+  // 子项目（admin 2026-10-24）：项目也能成层级，错误码与标签那几条**分开**，文案指向 proj_… 而不是标签名。
+  invalid_project_parent: { field: 'parent_id', message: 'parent_id must be a project id (proj_…) or null for a top-level project.', hint: 'Call projects_list to get project ids.' },
+  project_parent_not_found: { field: 'parent_id', message: 'No project with that id in this network (or it was deleted).', hint: 'Call projects_list to get the ids that exist.' },
+  project_parent_archived: { field: 'parent_id', message: 'That parent project is archived, so it cannot take children.', hint: 'Unarchive it first, or pick an active project.' },
+  project_parent_cycle: { field: 'parent_id', message: 'That parent would make the project its own ancestor.', hint: 'Pick a project that is not this one or one of its children.' },
+  project_parent_too_deep: { field: 'parent_id', message: 'Projects nest at most 3 levels (a top-level project counts as level 1).', hint: 'Attach it to a higher-level project.' },
+  project_has_children: { message: 'This project still has sub-projects, so it cannot be deleted.', hint: 'Move or delete the sub-projects first (a parent is never silently orphaned).' },
   tag_depth_exceeded: { field: 'parent_id', message: 'Tags nest at most 4 levels (the root counts as level 1).', hint: 'Attach the tag to a higher-level tag.' },
   invalid_tag: { field: 'name', message: 'Tag names are 1–20 characters after trimming, with no control characters.', hint: 'Shorten the name, or remove line breaks.' },
   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.' },

package/src/requirements-migrate.ts

@@ -41,6 +41,9 @@ export function ensureRequirementProjects(database: DbAdapter): void {
     );
     CREATE INDEX IF NOT EXISTS idx_requirement_projects_network ON requirement_projects(network_id, sort);
   `);
+  // 子项目（admin 2026-10-24：管理项目里没有层级）。加法式列，老库用 ALTER 补；重复执行无副作用。
+  // NULL = 顶层项目，所以现有行不需要回填。
+  try { database.exec("ALTER TABLE requirement_projects ADD COLUMN parent_id TEXT"); } catch {}
 }
 
 /**

package/src/requirements-projects-parent-http.test.ts

@@ -0,0 +1,123 @@
+// 子项目（admin 2026-10-24：管理项目里只能平铺，看不到层级）。
+//
+// 本文件钉住四件事，任何一条错都会让「项目」这个词变得不可信：
+//   1. 建/搬家都能指定 parent_id，GET 列表能读回；
+//   2. 深度上限 3 层（顶层=1），超了拒绝而不是悄悄截断；
+//   3. 环（把自己挂到自己的后代下面 / 挂到自己身上）必须拒绝；
+//   4. 有子项目的项目不能直接删（不偷偷把子项目变孤儿或改写它们的层级）。
+// 另外：父项目必须同网络、未归档。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
+import { register } from "./auth.js";
+import { bootServer } from "./server.js";
+
+let BASE = "";
+let server: any = null;
+let token = "";
+let NET = "";
+
+async function send(method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+
+const P = (path: string) => `${path}${path.includes("?") ? "&" : "?"}network_id=${NET}`;
+const mk = (name: string, parent_id?: string | null) =>
+  send("POST", P("/api/requirements/projects"), parent_id === undefined ? { name } : { name, parent_id });
+
+beforeAll(async () => {
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const a = register(`projparent_${suffix}`, "ProjParentPw123!", undefined, "pp");
+  expect(a.ok).toBe(true);
+  token = a.token!;
+  NET = a.network_id!;
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => { try { server?.stop?.(true); } catch {} });
+
+describe("sub-projects (parent_id)", () => {
+  test("create a child and read the hierarchy back", async () => {
+    const parent = await mk("父项目");
+    expect(parent.status).toBe(201);
+    const parentId = parent.body.project.id;
+    expect(parent.body.project.parentId).toBeNull();
+
+    const child = await mk("子项目", parentId);
+    expect(child.status).toBe(201);
+    expect(child.body.project.parentId).toBe(parentId);
+
+    const list = await send("GET", P("/api/requirements/projects"));
+    expect(list.status).toBe(200);
+    const rows = list.body.projects as any[];
+    expect(rows.find((r) => r.name === "子项目")!.parentId).toBe(parentId);
+    expect(rows.find((r) => r.name === "父项目")!.parentId).toBeNull();
+  });
+
+  test("a project can be moved under another one, and back to the top", async () => {
+    const a = await mk("可搬 A");
+    const b = await mk("可搬 B");
+    const moved = await send("PATCH", P(`/api/requirements/projects/${b.body.project.id}`), { parent_id: a.body.project.id });
+    expect(moved.status).toBe(200);
+    expect(moved.body.project.parentId).toBe(a.body.project.id);
+
+    const back = await send("PATCH", P(`/api/requirements/projects/${b.body.project.id}`), { parent_id: null });
+    expect(back.status).toBe(200);
+    expect(back.body.project.parentId).toBeNull();
+  });
+
+  test("depth is capped at 3 (top level counts as 1)", async () => {
+    const l1 = await mk("深 1");
+    const l2 = await mk("深 2", l1.body.project.id);
+    const l3 = await mk("深 3", l2.body.project.id);
+    expect(l3.status).toBe(201);
+    const l4 = await mk("深 4", l3.body.project.id);
+    expect(l4.status).toBe(400);
+    expect(l4.body.error).toBe("project_parent_too_deep");
+  });
+
+  test("a cycle is refused (self, and a descendant)", async () => {
+    const a = await mk("环 A");
+    const b = await mk("环 B", a.body.project.id);
+    const self = await send("PATCH", P(`/api/requirements/projects/${a.body.project.id}`), { parent_id: a.body.project.id });
+    expect(self.status).toBe(400);
+    expect(self.body.error).toBe("project_parent_cycle");
+
+    // 把 A 挂到它自己的子项目 B 下面 = 环
+    const loop = await send("PATCH", P(`/api/requirements/projects/${a.body.project.id}`), { parent_id: b.body.project.id });
+    expect(loop.status).toBe(400);
+    expect(loop.body.error).toBe("project_parent_cycle");
+  });
+
+  test("a parent that does not exist, is archived, or lives in another network is refused", async () => {
+    const missing = await mk("缺父", "proj_does_not_exist");
+    expect(missing.status).toBe(404);
+    expect(missing.body.error).toBe("project_parent_not_found");
+
+    const parent = await mk("会归档的父");
+    await send("PATCH", P(`/api/requirements/projects/${parent.body.project.id}`), { archived: true });
+    const archived = await mk("挂到归档父", parent.body.project.id);
+    expect(archived.status).toBe(400);
+    expect(archived.body.error).toBe("project_parent_archived");
+  });
+
+  test("a project with children cannot be deleted (children are not silently orphaned)", async () => {
+    const parent = await mk("有孩子的父");
+    const child = await mk("孩子", parent.body.project.id);
+    const del = await send("DELETE", P(`/api/requirements/projects/${parent.body.project.id}`));
+    expect(del.status).toBe(409);
+    expect(del.body.error).toBe("project_has_children");
+
+    // 先删孩子，父就能删
+    expect((await send("DELETE", P(`/api/requirements/projects/${child.body.project.id}`))).status).toBe(200);
+    expect((await send("DELETE", P(`/api/requirements/projects/${parent.body.project.id}`))).status).toBe(200);
+  });
+});

package/src/requirements-status-participants-http.test.ts

@@ -213,8 +213,8 @@ describe("tool descriptions", () => {
     // #478:节点令牌的 tools/list 里本来就没有 projects_create / projects_update(调了也是 403),那两条的说明从人的列表里读。
     expect(byName.has("projects_create")).toBe(false);
     const human = new Map(((await rpc(U.member.token, "tools/list", {})).result.tools as any[]).map(t => [t.name, t]));
-    expect(byName.get("projects_list").description).toMatch(/node \(Agent\) tokens can only read projects/i);
-    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    expect(byName.get("projects_list").description).toMatch(/node (?:\(Agent\) )?tokens can only read projects/i);
+    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node (?:\(Agent\) )?tokens can only read projects/i);
     const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
     expect(denied.status).toBe(403);
     expect(denied.error).toBe("user_token_required");

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";
@@ -348,11 +348,13 @@ function storedChecklist(raw: string | null): ChecklistItem[] {
 // ── 项目 ──
 // 按网络隔离;名字 1–40 字,同一网络里未归档的项目不重名;颜色 #RRGGBB;sort 越小越靠前。
 // 删除 = 删项目行 + 把引用它的卡片 project_id 置空(卡片本身不动);归档 = 保留引用,只是不能再被选。
-type ProjectRow = { project_id: string; network_id: string; name: string; color: string; sort: number; archived: number; created_at: string };
+type ProjectRow = { project_id: string; network_id: string; name: string; color: string; sort: number; archived: number; created_at: string; parent_id: string | null };
 const PROJECT_COLOR = /^#[0-9a-fA-F]{6}$/;
 const PROJECT_PALETTE = ["#2563eb", "#16a34a", "#d97706", "#dc2626", "#7c3aed", "#0891b2", "#db2777", "#4b5563"];
-const PROJECT_SELECT = "project_id, network_id, name, color, sort, archived, created_at";
-const projectPublic = (row: ProjectRow) => ({ id: row.project_id, name: row.name, color: row.color, sort: row.sort, archived: !!row.archived, createdAt: row.created_at });
+const PROJECT_SELECT = "project_id, network_id, name, color, sort, archived, created_at, parent_id";
+/** 子项目最多 3 层（顶层=1）。再深的话「项目」这个词就没有意义了，也没人能在选择器里点对。 */
+const PROJECT_MAX_DEPTH = 3;
+const projectPublic = (row: ProjectRow) => ({ id: row.project_id, name: row.name, color: row.color, sort: row.sort, archived: !!row.archived, createdAt: row.created_at, parentId: row.parent_id ?? null });
 const projectName = (raw: unknown): string | null => {
   if (typeof raw !== "string") return null;
   const name = raw.replace(/[\r\n\t]+/g, " ").trim();
@@ -361,6 +363,50 @@ const projectName = (raw: unknown): string | null => {
 function projectNameTaken(networkId: string, name: string, except?: string): boolean {
   return !!db.get("SELECT 1 FROM requirement_projects WHERE network_id = ?1 AND name = ?2 AND archived = 0 AND project_id != ?3", networkId, name, except ?? "");
 }
+/** 这个项目往上数有几层（自己算第一层）。用于深度上限与环路判断。 */
+function projectDepth(projectId: string): number {
+  let depth = 0;
+  let cur: string | null = projectId;
+  const seen = new Set<string>();
+  while (cur && depth < 64) {
+    if (seen.has(cur)) return Number.POSITIVE_INFINITY;  // 循环：当成超深，调用方会拒绝
+    seen.add(cur);
+    depth++;
+    const row: { parent_id: string | null } | null = db.get("SELECT parent_id FROM requirement_projects WHERE project_id = ?1", cur);
+    cur = row?.parent_id ?? null;
+  }
+  return depth;
+}
+
+/**
+ * 校验 parent_id（新项目或搬家时）。返回 { parent } 或错误码。
+ * 规则：同一网络、存在、未归档、不是自己或自己的后代、加进来后不超过 PROJECT_MAX_DEPTH。
+ */
+function validateProjectParent(
+  networkId: string, parentId: string, selfId: string | null,
+): { ok: true; parent: ProjectRow } | { ok: false; error: string } {
+  const parent = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, parentId);
+  if (!parent || parent.network_id !== networkId) return { ok: false, error: "project_parent_not_found" };
+  if (parent.archived) return { ok: false, error: "project_parent_archived" };
+  if (selfId) {
+    if (parent.project_id === selfId) return { ok: false, error: "project_parent_cycle" };
+    // 把 A 挂到 A 的后代下面 = 环。沿 parent 链往上走，遇到自己就拒绝。
+    let cur: string | null = parent.parent_id ?? null;
+    const seen = new Set<string>();
+    while (cur && !seen.has(cur)) {
+      if (cur === selfId) return { ok: false, error: "project_parent_cycle" };
+      seen.add(cur);
+      cur = db.get<{ parent_id: string | null }>("SELECT parent_id FROM requirement_projects WHERE project_id = ?1", cur)?.parent_id ?? null;
+    }
+    if (projectDepth(selfId) + projectDepth(parent.project_id) > PROJECT_MAX_DEPTH) {
+      return { ok: false, error: "project_parent_too_deep" };
+    }
+  } else if (projectDepth(parent.project_id) + 1 > PROJECT_MAX_DEPTH) {
+    return { ok: false, error: "project_parent_too_deep" };
+  }
+  return { ok: true, parent };
+}
+
 /** 卡片上的 project_id:null 清空;字符串必须是同一网络、未归档的项目。 */
 function projectRef(value: unknown, networkId: string): string | null {
   if (value === null) return null;
@@ -405,13 +451,24 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
     const sort = body.sort === undefined ? count : body.sort;
     if (!Number.isInteger(sort)) return jsonError("invalid_project_sort", 400);
     const id = `proj_${crypto.randomUUID()}`;
-    db.run(`INSERT INTO requirement_projects (${PROJECT_SELECT}) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6)`, [id, networkId, name, color, sort, new Date().toISOString()]);
+    // 子项目：parent_id 可选；null/缺省 = 顶层。
+    let parentId: string | null = null;
+    if (body.parent_id !== undefined && body.parent_id !== null && body.parent_id !== "") {
+      if (typeof body.parent_id !== "string") return jsonError("invalid_project_parent", 400);
+      const check = validateProjectParent(networkId, body.parent_id, null);
+      if (!check.ok) return jsonError(check.error, check.error === "project_parent_not_found" ? 404 : 400);
+      parentId = check.parent.project_id;
+    }
+    db.run(`INSERT INTO requirement_projects (${PROJECT_SELECT}) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6, ?7)`, [id, networkId, name, color, sort, new Date().toISOString(), parentId]);
     return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, id)!) }, { status: 201 });
   }
   if (!one) return jsonError("not_found", 404);
   const current = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, decodeURIComponent(one[1]));
   if (!current || current.network_id !== networkId) return jsonError("project_not_found", 404);
   if (req.method === "DELETE") {
+    // 子项目不能凭空变孤儿：先搬走或删掉它们（明确拒绝，不偷偷改层级）。
+    const kids = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_projects WHERE parent_id = ?1", current.project_id)?.n ?? 0;
+    if (kids > 0) return jsonError("project_has_children", 409);
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
     // updated_at 跟着动:按 updated_since 增量同步的客户端要看得见「项目被清空」这一改动。
     // 每张被清空项目的卡记一条「项目 X → 无」(与清空同一个事务)。
@@ -445,8 +502,20 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
     if (typeof body.archived !== "boolean") return jsonError("invalid_project_archived", 400);
     archived = body.archived ? 1 : 0;
   }
+  let parentId: string | null = current.parent_id ?? null;
+  if ("parent_id" in body) {
+    if (body.parent_id === null || body.parent_id === "") {
+      parentId = null;                                    // 变成顶层
+    } else if (typeof body.parent_id !== "string") {
+      return jsonError("invalid_project_parent", 400);
+    } else {
+      const check = validateProjectParent(networkId, body.parent_id, current.project_id);
+      if (!check.ok) return jsonError(check.error, check.error === "project_parent_not_found" ? 404 : 400);
+      parentId = check.parent.project_id;
+    }
+  }
   if (!archived && projectNameTaken(networkId, name, current.project_id)) return jsonError("project_name_taken", 409);
-  db.run("UPDATE requirement_projects SET name = ?1, color = ?2, sort = ?3, archived = ?4 WHERE project_id = ?5", [name, color, sort, archived, current.project_id]);
+  db.run("UPDATE requirement_projects SET name = ?1, color = ?2, sort = ?3, archived = ?4, parent_id = ?6 WHERE project_id = ?5", [name, color, sort, archived, current.project_id, parentId]);
   return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, current.project_id)!) });
 }
 
@@ -478,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);
@@ -498,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);
@@ -521,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/tools.ts

@@ -4104,7 +4104,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "tail_node_logs",
-    "Ask a node for the tail of its own agent-node run log (read-only, redacted on the node before it leaves). No path argument: the node reads only its own log directory. User logins only; the node's owner or a network owner/admin. Poll get_rules_file_result — content is JSON {files, lines:[{ts, level, text, key}], truncated, matched, now_ts}; it is handed out once and then purged.",
+    "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.",
     {
       ...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)."),
@@ -6916,7 +6916,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "projects_list",
-    "List requirement projects in your network (id, name, color, sort, archived). Node (Agent) tokens can only read projects; creating / changing them (projects_create / projects_update) needs a person's token.",
+    "List requirement projects (id, name, color, sort, archived, parentId). node tokens can only read projects; creating / changing needs a person's token (projects_create / projects_update).",
     { network_id: z.string().max(200).optional() },
     async ({ network_id }) => requirementsCall("GET", "/api/requirements/projects", network_id),
   );
@@ -6926,19 +6926,20 @@ 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 in your network (same as 管理项目 → 新建 in the app). name 1–40 characters, unique in the network; color #RRGGBB (default: next palette colour); sort integer. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
+    "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.",
     {
       network_id: z.string().max(200).optional(),
       name: z.string().min(1).max(40),
       color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
       sort: z.number().int().optional(),
+      parent_id: z.string().max(200).nullable().optional(),
     },
-    async (args) => requirementsCall("POST", "/api/requirements/projects", args.network_id, pick(args, ["name", "color", "sort"])),
+    async (args) => requirementsCall("POST", "/api/requirements/projects", args.network_id, pick(args, ["name", "color", "sort", "parent_id"])),
   );
 
   server.tool(
     "projects_update",
-    "Rename, recolour, reorder, archive or unarchive a requirement project (same as 管理项目 in the app). Only the fields you pass change. archived=true hides it from pickers (its tasks keep project_id); archived=false brings it back. Returns { project }. Needs a person's token: node (Agent) tokens can only read projects (403 user_token_required). Also refused (403) for task-scoped members and read-only roles.",
+    "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.",
     {
       network_id: z.string().max(200).optional(),
       id: z.string().min(1).max(200).describe("project id (proj_…), from projects_list"),
@@ -6946,8 +6947,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       color: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional(),
       sort: z.number().int().optional(),
       archived: z.boolean().optional(),
+      parent_id: z.string().max(200).nullable().optional(),
     },
-    async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived"])),
+    async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived", "parent_id"])),
   );
 
   // #476 —— 不带 requirement_id 的全网动态默认 50 条(REST 默认 200 不变,App 走 REST);严格参数同 #471。