@sleep2agi/commhub-server 0.9.0-preview.64 → 0.9.0-preview.66

package/src/requirements-migrate.ts

@@ -0,0 +1,44 @@
+// 需求卡的启动迁移。requirements.ts 载入时调用一次(列由 db.ts 的加列循环加上)。
+import type { DbAdapter } from "./db-adapter";
+
+/**
+ * 负责人 = 人类(owner, kind user);负责 Agent = 节点(agent_owner, kind node)。
+ * 之前 owner 可以是节点:这些卡把节点挪到 agent_owner、owner 置空。只动 agent_owner 还空着的行,
+ * 所以重复执行不会再改任何东西;不删行,不碰别的列。在 JS 里判 kind(不依赖 SQLite 的 json_extract)。
+ */
+export function migrateRequirementAgentOwners(database: DbAdapter): { moved: number } {
+  const rows = database.all<{ requirement_id: string; owner_json: string | null }>(
+    "SELECT requirement_id, owner_json FROM requirements WHERE owner_json IS NOT NULL AND agent_owner_json IS NULL",
+  );
+  let moved = 0;
+  for (const row of rows) {
+    let owner: { kind?: unknown; id?: unknown } | null = null;
+    try { owner = JSON.parse(row.owner_json || "null"); } catch { continue; }
+    if (!owner || owner.kind !== "node" || typeof owner.id !== "string" || !owner.id) continue;
+    database.run(
+      "UPDATE requirements SET agent_owner_json = ?1, owner_json = NULL WHERE requirement_id = ?2 AND agent_owner_json IS NULL",
+      [JSON.stringify({ kind: "node", id: owner.id }), row.requirement_id],
+    );
+    moved += 1;
+  }
+  return { moved };
+}
+
+/**
+ * 项目表(需求卡的「项目」)。只建表、建索引,不塞任何项目 —— 军团项目 / TMAI 由 owner 在界面里建。
+ * CREATE ... IF NOT EXISTS:重复执行无副作用。放在这里而不是 db.ts,db.ts 的行号被文档钉着。
+ */
+export function ensureRequirementProjects(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS requirement_projects (
+      project_id  TEXT PRIMARY KEY,
+      network_id  TEXT NOT NULL,
+      name        TEXT NOT NULL,
+      color       TEXT NOT NULL,
+      sort        INTEGER NOT NULL DEFAULT 0,
+      archived    INTEGER NOT NULL DEFAULT 0,
+      created_at  TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_requirement_projects_network ON requirement_projects(network_id, sort);
+  `);
+}

package/src/requirements-upgrade-e2e.test.ts

@@ -0,0 +1,126 @@
+// 负责人 / 负责 Agent 拆分:一次性 Hub 进程的升级端到端。
+// 真起两次 `bun run src/index.ts`(HOME=临时目录、随机端口、绝不是 9200、独立库):
+//   第一次:注册、建节点、建一张「旧式」卡(owner 是节点 —— 用 SQL 写进去,因为新 Hub 已不接受);
+//          再把 agent_owner_json 列删掉,库回到 #2065 时代的样子。
+//   第二次:同一个库启动 = 升级。启动迁移把节点挪到 agent_owner,HTTP 读回;然后走一遍新规则。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+
+const home = mkdtempSync(join(tmpdir(), "anet-req-agent-owner-e2e-"));
+const dbFile = join(home, "hub.db");
+const port = 20000 + Math.floor(Math.random() * 20000);
+if (port === 9200) throw new Error("9200 is the production hub port");
+const base = `http://127.0.0.1:${port}`;
+const serverDir = resolve(import.meta.dir, "..");
+let proc: ChildProcess | null = null;
+
+async function startHub() {
+  proc = spawn("bun", ["run", "src/index.ts"], {
+    cwd: serverDir,
+    env: { PATH: process.env.PATH || "", HOME: home, COMMHUB_DB: dbFile, COMMHUB_SERVER: "1", PORT: String(port), HOST: "127.0.0.1" },
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  let err = "";
+  proc.stderr?.on("data", d => { err += String(d); });
+  for (let i = 0; i < 100; i++) {
+    try { if ((await fetch(`${base}/health`)).ok) return; } catch {}
+    await new Promise(r => setTimeout(r, 150));
+  }
+  throw new Error(`hub did not start on ${port}: ${err.slice(-600)}`);
+}
+async function stopHub() {
+  if (!proc) return;
+  const p = proc;
+  proc = null;
+  await new Promise<void>(res => { p.once("exit", () => res()); p.kill("SIGTERM"); setTimeout(() => { p.kill("SIGKILL"); res(); }, 5000); });
+}
+afterAll(async () => { await stopHub(); try { rmSync(home, { recursive: true, force: true }); } catch {} });
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+test("an upgraded hub moves node owners to agent_owner and then enforces human owner / agent executor", async () => {
+  await startHub();
+  const reg = await (await fetch(`${base}/api/auth/register`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ username: "e2e_owner", password: "E2eOwner123!pass" }) })).json() as any;
+  expect(reg.ok).toBe(true);
+  const token = reg.token as string, net = reg.network_id as string, uid = reg.user.user_id as string;
+  const human = { kind: "user", id: uid }, agent = { kind: "node", id: "node_e2e_exec" };
+  {
+    const db = new Database(dbFile);
+    db.run("INSERT INTO nodes (node_id,node_name,alias,network_id) VALUES (?1,'e2e-exec','e2e-exec',?2)", [agent.id, net]);
+    db.close();
+  }
+  const card = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "旧式卡", network_id: net, participants: [human] }) });
+  expect(card.status).toBe(201);
+  const keep = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "人类负责人卡", network_id: net, owner: human }) });
+  expect(keep.status).toBe(201);
+  await stopHub();
+  {
+    // 退回旧库:节点当负责人,且没有 agent_owner_json 列
+    const db = new Database(dbFile);
+    db.run("UPDATE requirements SET owner_json = ?1 WHERE requirement_id = ?2", [JSON.stringify(agent), card.body.requirement.id]);
+    db.exec("ALTER TABLE requirements DROP COLUMN agent_owner_json");
+    const cols = (db.query("PRAGMA table_info(requirements)").all() as { name: string }[]).map(c => c.name);
+    expect(cols.includes("agent_owner_json")).toBe(false);
+    db.close();
+  }
+  await startHub();
+  const listed = await api(token, `/api/requirements?network_id=${net}`);
+  expect(listed.status).toBe(200);
+  expect(listed.body.requirements.length).toBe(2);
+  const upgraded = listed.body.requirements.find((r: any) => r.id === card.body.requirement.id);
+  expect(upgraded.owner).toBeNull();
+  expect(upgraded.agent_owner).toEqual(agent);
+  expect(upgraded.participants).toEqual([human]);
+  expect(upgraded.name).toBe("旧式卡");
+  const untouched = listed.body.requirements.find((r: any) => r.id === keep.body.requirement.id);
+  expect(untouched.owner).toEqual(human);
+  expect(untouched.agent_owner).toBeNull();
+
+  const path = `/api/requirements/${upgraded.id}?network_id=${net}`;
+  const both = await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: human }) });
+  expect(both.status).toBe(200);
+  expect(both.body.requirement.owner).toEqual(human);
+  expect(both.body.requirement.agent_owner).toEqual(agent);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: agent }) })).body.error).toBe("owner_must_be_human");
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ agent_owner: human }) })).body.error).toBe("agent_owner_must_be_agent");
+
+  // 预计完成:旧卡的全天值(升级前写的)原样读回;改成带时刻的,存 UTC
+  const dated = await api(token, path, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01" }) });
+  expect(dated.body.requirement.due).toBe("2026-10-01");
+  // 描述 / 子任务:升级后的旧卡可写,单项勾选只动那一项
+  expect(upgraded.description).toBe("");
+  expect(upgraded.checklist).toEqual([]);
+  const withList = await api(token, path, { method: "PATCH", body: JSON.stringify({ description: "# 验收\n- 能用", checklist: [{ id: "one", text: "第一步" }, { id: "two", text: "第二步" }] }) });
+  expect(withList.status).toBe(200);
+  const ticked = await api(token, `/api/requirements/${upgraded.id}/checklist/two?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+  expect(ticked.body.requirement.checklist).toEqual([{ id: "one", text: "第一步", done: false }, { id: "two", text: "第二步", done: true }]);
+
+  // 项目:升级后没有任何项目(不预置),建一个、给旧卡挂上
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects).toEqual([]);
+  const proj = await api(token, `/api/requirements/projects?network_id=${net}`, { method: "POST", body: JSON.stringify({ name: "军团项目" }) });
+  expect(proj.status).toBe(201);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ project_id: proj.body.project.id }) })).body.requirement.project_id).toBe(proj.body.project.id);
+
+  // 第三次启动(同一个库):迁移不再改任何东西
+  await stopHub();
+  await startHub();
+  const again = (await api(token, `/api/requirements?network_id=${net}`)).body.requirements;
+  expect(again.length).toBe(2);
+  const same = again.find((r: any) => r.id === upgraded.id);
+  expect(same.owner).toEqual(human);
+  expect(same.agent_owner).toEqual(agent);
+  expect(same.description).toBe("# 验收\n- 能用");
+  expect(same.checklist.map((i: any) => i.done)).toEqual([false, true]);
+  expect(same.project_id).toBe(proj.body.project.id);
+  expect(same.due).toBe("2026-10-01");
+  const timed = await api(token, `/api/requirements/${upgraded.id}?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01T18:30:45+08:00" }) });
+  expect(timed.body.requirement.due).toBe("2026-10-01T10:30:45Z");
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects.map((p: any) => p.name)).toEqual(["军团项目"]);
+}, 60_000);

package/src/requirements-upgrade-migration.test.ts

@@ -0,0 +1,76 @@
+// 负责人 / 负责 Agent 拆分的启动迁移:旧库里 owner 是节点的卡,节点挪到 agent_owner、owner 置空。
+// 用 #2065 时代的表结构(没有 agent_owner_json 列)先建库、塞行,再 import db.ts + requirements.ts(真实启动路径)。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-req-agent-owner-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`CREATE TABLE requirements (
+  requirement_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, title TEXT NOT NULL,
+  column_name TEXT NOT NULL DEFAULT 'pool', priority TEXT NOT NULL DEFAULT 'normal', due_on TEXT, assignee TEXT,
+  client_id TEXT, issues_json TEXT, created_by TEXT,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+  owner_json TEXT, participants_json TEXT NOT NULL DEFAULT '[]')`);
+const rows: [string, string | null, string][] = [
+  ["r_node_owner", JSON.stringify({ kind: "node", id: "node_x" }), JSON.stringify([{ kind: "user", id: "u1" }])],
+  ["r_user_owner", JSON.stringify({ kind: "user", id: "u1" }), "[]"],
+  ["r_no_owner", null, "[]"],
+  ["r_bad_json", "{not json", "[]"],
+  ["r_node_no_id", JSON.stringify({ kind: "node" }), "[]"],
+  ["r_node_owner_2", JSON.stringify({ kind: "node", id: "node_y" }), "[]"],
+];
+for (const [id, owner, participants] of rows) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, due_on, assignee, owner_json, participants_json) VALUES (?1, 'net', ?2, '2026-10-01', 'legacy', ?3, ?4)", [id, `卡 ${id}`, owner, participants]);
+}
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+const snapshot = (db: any) => db.all("SELECT requirement_id, network_id, title, due_on, assignee, participants_json, owner_json, agent_owner_json, project_id FROM requirements ORDER BY requirement_id") as any[];
+
+test("startup migration moves node owners to agent_owner, keeps every row, and is idempotent", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js"); // 真实启动路径:server.ts 载入 requirements.ts 时迁移
+  const { migrateRequirementAgentOwners } = await import("./requirements-migrate.js");
+  const after = snapshot(db);
+  expect(after.length).toBe(rows.length);
+  const by = Object.fromEntries(after.map(r => [r.requirement_id, r]));
+  expect(by.r_node_owner.owner_json).toBeNull();
+  expect(JSON.parse(by.r_node_owner.agent_owner_json)).toEqual({ kind: "node", id: "node_x" });
+  expect(by.r_node_owner.participants_json).toBe(JSON.stringify([{ kind: "user", id: "u1" }]));
+  expect(JSON.parse(by.r_node_owner_2.agent_owner_json)).toEqual({ kind: "node", id: "node_y" });
+  expect(JSON.parse(by.r_user_owner.owner_json)).toEqual({ kind: "user", id: "u1" });
+  expect(by.r_user_owner.agent_owner_json).toBeNull();
+  expect(by.r_no_owner.owner_json).toBeNull();
+  // 读不懂的旧值原样留着,不猜、不删
+  expect(by.r_bad_json.owner_json).toBe("{not json");
+  expect(by.r_node_no_id.owner_json).toBe(JSON.stringify({ kind: "node" }));
+  for (const r of after) {
+    expect(r.title).toBe(`卡 ${r.requirement_id}`);
+    expect(r.network_id).toBe("net");
+    expect(r.due_on).toBe("2026-10-01");
+    expect(r.assignee).toBe("legacy");
+  }
+  // 加列只加不改:旧行的描述 / 子任务是空
+  const cols = (db.all("PRAGMA table_info(requirements)") as { name: string }[]).map(c => c.name);
+  expect(cols.includes("description") && cols.includes("checklist_json") && cols.includes("agent_owner_json")).toBe(true);
+  const extra = db.all("SELECT description, checklist_json FROM requirements") as any[];
+  expect(extra.every(r => r.description === null && r.checklist_json === null)).toBe(true);
+  // 项目表:建了、是空的(不预置),重复执行不报错;卡片的 project_id 列只加不改
+  expect(cols.includes("project_id")).toBe(true);
+  expect((db.all("SELECT project_id FROM requirements WHERE project_id IS NOT NULL") as any[]).length).toBe(0);
+  expect((db.get("SELECT COUNT(*) AS n FROM requirement_projects") as any).n).toBe(0);
+  const { ensureRequirementProjects } = await import("./requirements-migrate.js");
+  ensureRequirementProjects(db);
+  ensureRequirementProjects(db);
+  expect((db.get("SELECT COUNT(*) AS n FROM requirement_projects") as any).n).toBe(0);
+  // 再跑一次(= 下次启动):什么都不动
+  expect(migrateRequirementAgentOwners(db).moved).toBe(0);
+  expect(snapshot(db)).toEqual(after);
+});

package/src/requirements.ts

@@ -2,6 +2,12 @@
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { db } from "./db.js";
 import { addNetworkScope, canRestWriteNetwork, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+import { ensureRequirementProjects, migrateRequirementAgentOwners } from "./requirements-migrate.js";
+
+// 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
+// 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
+migrateRequirementAgentOwners(db);
+ensureRequirementProjects(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string } | null;
 
@@ -20,6 +26,10 @@ const DUE = /^\d{4}-\d{2}-\d{2}$/;
 
 type Row = {
   owner_json: string | null;
+  agent_owner_json: string | null;
+  description: string | null;
+  checklist_json: string | null;
+  project_id: string | null;
   participants_json: string;
   requirement_id: string;
   network_id: string;
@@ -43,6 +53,26 @@ function dueOk(due: string): boolean {
   return dt.getUTCFullYear() === y && dt.getUTCMonth() === m - 1 && dt.getUTCDate() === d;
 }
 
+// 预计完成:两种形状都收。
+//   YYYY-MM-DD                      全天(旧值原样保存、原样返回;客户端按查看者本地时区的那一天理解)
+//   YYYY-MM-DDTHH:MM[:SS][.fff](Z|±HH:MM)  精确到秒的时刻 → 统一存成 UTC「YYYY-MM-DDTHH:MM:SSZ」
+// 不带时区的时刻拒收(无法知道是谁的本地时间)。返回 null = 不合法。
+const DUE_DATETIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:\.\d{1,9})?(Z|[+-](\d{2}):(\d{2}))$/;
+export function normalizeDue(raw: string): string | null {
+  const due = raw.trim();
+  if (!due) return "";
+  if (dueOk(due)) return due;
+  const m = DUE_DATETIME.exec(due);
+  if (!m) return null;
+  if (!dueOk(`${m[1]}-${m[2]}-${m[3]}`)) return null;
+  const [hh, mm, ss] = [Number(m[4]), Number(m[5]), Number(m[6] ?? 0)];
+  if (hh > 23 || mm > 59 || ss > 59) return null;
+  if (m[7] !== "Z" && (Number(m[8]) > 14 || Number(m[9]) > 59)) return null;
+  const ms = Date.parse(due);
+  if (!Number.isFinite(ms)) return null;
+  return new Date(Math.floor(ms / 1000) * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+
 const REPO = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const ISSUE_URL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)\/issues\/(\d+)\/?$/;
 
@@ -96,9 +126,143 @@ function storedIssues(raw: string | null) {
   }
 }
 
+// ── 描述 / 子任务 ──
+// 描述是 markdown 原文,整段替换。子任务是有序数组 [{id,text,done}]:PATCH 整个替换(排序、增删都走这里),
+// 单项勾选走 PATCH /api/requirements/{id}/checklist/{itemId} {done} —— 只改那一项,app 和 Agent 同时操作
+// 不会互相盖掉对方的整张清单。done 是显式值(不是「取反」),重复请求结果一样。
+export const DESCRIPTION_MAX = 20_000;
+export const CHECKLIST_MAX_ITEMS = 100;
+export const CHECKLIST_TEXT_MAX = 500;
+const CHECKLIST_ID = /^[A-Za-z0-9_-]{1,40}$/;
+type ChecklistItem = { id: string; text: string; done: boolean };
+
+function normalizeDescription(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const text = raw.replace(/\r\n?/g, "\n");
+  return text.length > DESCRIPTION_MAX ? null : text;
+}
+
+/** 输入的 id 保留(客户端要靠它对上勾选);缺 id 的由 Hub 生成。重复 id、空文字、超长 → null(整体拒绝)。 */
+function normalizeChecklist(raw: unknown): ChecklistItem[] | null {
+  if (!Array.isArray(raw) || raw.length > CHECKLIST_MAX_ITEMS) return null;
+  const seen = new Set<string>();
+  const out: ChecklistItem[] = [];
+  for (const value of raw) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+    const item = value as Record<string, unknown>;
+    const id = item.id === undefined ? `ck_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}` : item.id;
+    if (typeof id !== "string" || !CHECKLIST_ID.test(id) || seen.has(id)) return null;
+    const text = typeof item.text === "string" ? item.text.replace(/[\r\n]+/g, " ").trim() : "";
+    if (!text || text.length > CHECKLIST_TEXT_MAX) return null;
+    if (item.done !== undefined && typeof item.done !== "boolean") return null;
+    seen.add(id);
+    out.push({ id, text, done: item.done === true });
+  }
+  return out;
+}
+
+function storedChecklist(raw: string | null): ChecklistItem[] {
+  if (!raw) return [];
+  try { return normalizeChecklist(JSON.parse(raw)) ?? []; } catch { return []; }
+}
+
+// ── 项目 ──
+// 按网络隔离;名字 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 };
+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 projectName = (raw: unknown): string | null => {
+  if (typeof raw !== "string") return null;
+  const name = raw.replace(/[\r\n\t]+/g, " ").trim();
+  return name && name.length <= 40 ? name : 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 ?? "");
+}
+/** 卡片上的 project_id:null 清空;字符串必须是同一网络、未归档的项目。 */
+function projectRef(value: unknown, networkId: string): string | null {
+  if (value === null) return null;
+  if (typeof value !== "string" || !value) throw new Error("invalid_project");
+  const row = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, value);
+  if (!row || row.network_id !== networkId) throw new Error("project_not_in_network");
+  if (row.archived) throw new Error("project_archived");
+  return row.project_id;
+}
+
+async function handleProjects(ctx: RequirementsRequestContext): Promise<Response> {
+  const { req, url } = ctx;
+  const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+  if (!networkId) return jsonError("network_id_required", 400);
+  const one = url.pathname.match(/^\/api\/requirements\/projects\/([^/]+)$/);
+  if (url.pathname === "/api/requirements/projects" && req.method === "GET") {
+    const rows = db.all<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE network_id = ?1 ORDER BY sort, created_at`, networkId);
+    return Response.json({ ok: true, projects: rows.map(projectPublic) });
+  }
+  if (!canWrite(ctx, networkId)) return jsonError("permission_denied", 403);
+  let body: Record<string, unknown> = {};
+  if (req.method === "POST" || req.method === "PATCH") {
+    try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
+  }
+  if (url.pathname === "/api/requirements/projects" && req.method === "POST") {
+    const name = projectName(body.name);
+    if (!name) return jsonError("invalid_project_name", 400);
+    if (projectNameTaken(networkId, name)) return jsonError("project_name_taken", 409);
+    const count = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_projects WHERE network_id = ?1", networkId)?.n ?? 0;
+    if (count >= 200) return jsonError("too_many_projects", 400);
+    const color = body.color === undefined ? PROJECT_PALETTE[count % PROJECT_PALETTE.length] : body.color;
+    if (typeof color !== "string" || !PROJECT_COLOR.test(color)) return jsonError("invalid_project_color", 400);
+    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()]);
+    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") {
+    // 先把卡片上的引用置空,再删项目:卡片一张不少。
+    db.run("UPDATE requirements SET project_id = NULL WHERE project_id = ?1", [current.project_id]);
+    db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    return Response.json({ ok: true });
+  }
+  if (req.method !== "PATCH") return jsonError("not_found", 404);
+  let { name, color, sort, archived } = current;
+  if ("name" in body) {
+    const next = projectName(body.name);
+    if (!next) return jsonError("invalid_project_name", 400);
+    name = next;
+  }
+  if ("color" in body) {
+    if (typeof body.color !== "string" || !PROJECT_COLOR.test(body.color)) return jsonError("invalid_project_color", 400);
+    color = body.color;
+  }
+  if ("sort" in body) {
+    if (!Number.isInteger(body.sort)) return jsonError("invalid_project_sort", 400);
+    sort = body.sort as number;
+  }
+  if ("archived" in body) {
+    if (typeof body.archived !== "boolean") return jsonError("invalid_project_archived", 400);
+    archived = body.archived ? 1 : 0;
+  }
+  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]);
+  return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, current.project_id)!) });
+}
+
 function toPublic(row: Row) {
   return {
     owner: row.owner_json ? JSON.parse(row.owner_json) : null,
+    // 负责 Agent(执行者)。字段总在:客户端靠它判断这个 Hub 分不分「负责人 / 负责 Agent」。
+    agent_owner: row.agent_owner_json ? JSON.parse(row.agent_owner_json) : null,
+    // 描述(markdown)与子任务。字段总在:客户端靠它判断这个 Hub 支不支持。
+    description: row.description || "",
+    checklist: storedChecklist(row.checklist_json),
+    // 项目(可空)。字段总在:客户端靠它判断这个 Hub 有没有项目。项目被删 → 置空;被归档 → 引用保留。
+    project_id: row.project_id || null,
     participants: JSON.parse(row.participants_json || '[]'),
     id: row.requirement_id,
     name: row.title,
@@ -127,7 +291,7 @@ function canWrite(ctx: RequirementsRequestContext, networkId: string | null): bo
   return !ctx.isNodeToken && canRestWriteNetwork(ctx.auth, networkId, ctx.isAdmin);
 }
 
-const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, created_at, owner_json, participants_json";
+const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id";
 
 type PersonRef = { kind: 'user' | 'node'; id: string };
 function personRef(value: unknown, networkId: string): PersonRef {
@@ -141,21 +305,52 @@ function personRef(value: unknown, networkId: string): PersonRef {
   return { kind: row.kind, id: row.id };
 }
 
+// 负责人只能是人类,负责 Agent 只能是节点;参与人两种都行。库里旧的节点负责人照样读出来(启动迁移会挪走),
+// 只有这次请求显式写了 owner / agent_owner 才校验种类。
 function assignments(body: Record<string, unknown>, networkId: string, current?: Row) {
-  const owner = 'owner' in body ? body.owner === null ? null : personRef(body.owner, networkId) : current?.owner_json ? JSON.parse(current.owner_json) : null;
+  let owner = current?.owner_json ? JSON.parse(current.owner_json) : null;
+  if ('owner' in body) {
+    owner = body.owner === null ? null : personRef(body.owner, networkId);
+    if (owner && owner.kind !== 'user') throw new Error('owner_must_be_human');
+  }
+  let agentOwner = current?.agent_owner_json ? JSON.parse(current.agent_owner_json) : null;
+  if ('agent_owner' in body) {
+    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId);
+    if (agentOwner && agentOwner.kind !== 'node') throw new Error('agent_owner_must_be_agent');
+  }
   let participants = current ? JSON.parse(current.participants_json || '[]') : [];
   if ('participants' in body) {
     if (!Array.isArray(body.participants) || body.participants.length > 100) throw new Error('invalid_participants');
     const refs = body.participants.map(value => personRef(value, networkId));
     participants = [...new Map(refs.map(ref => [`${ref.kind}:${ref.id}`, ref])).values()];
   }
-  return { ownerJson: owner === null ? null : JSON.stringify(owner), participantsJson: JSON.stringify(participants) };
+  return {
+    ownerJson: owner === null ? null : JSON.stringify(owner),
+    agentOwnerJson: agentOwner === null ? null : JSON.stringify(agentOwner),
+    participantsJson: JSON.stringify(participants),
+  };
+}
+
+/** 节点令牌可用的操作。空 = 与之前一样全部拒绝(本 PR 不放宽)。候选:'read' | 'patch' | 'checklist_item'。 */
+const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>();
+function operationOf(req: Request, url: URL): string {
+  if (req.method === "GET") return "read";
+  if (/^\/api\/requirements\/projects(\/|$)/.test(url.pathname)) return "projects";
+  if (/^\/api\/requirements\/[^/]+\/checklist\/[^/]+$/.test(url.pathname)) return "checklist_item";
+  if (req.method === "PATCH") return "patch";
+  return "create";
 }
 
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime"] as const;
+
 export async function handleRequirementsRequest(ctx: RequirementsRequestContext): Promise<Response | null> {
   const { req, url } = ctx;
   if (url.pathname !== "/api/requirements" && !url.pathname.startsWith("/api/requirements/")) return null;
-  if (ctx.isNodeToken) return jsonError("user_token_required", 403);
+  // 节点令牌(Agent)现在一律拒绝。以后要让 Agent 读写描述、勾子任务,把对应操作加进
+  // NODE_TOKEN_OPERATIONS(并给 canWrite 加上节点所属网络的判断)即可 —— 路由和请求体不用改。
+  if (ctx.isNodeToken && !NODE_TOKEN_OPERATIONS.has(operationOf(req, url))) return jsonError("user_token_required", 403);
+
+  if (url.pathname === "/api/requirements/projects" || url.pathname.startsWith("/api/requirements/projects/")) return handleProjects(ctx);
 
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
@@ -175,7 +370,8 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     sql = addNetworkScope(sql, params, ctx.scope);
     sql += " ORDER BY created_at DESC LIMIT 500";
     const rows = db.all<Row>(sql, ...params).map(toPublic);
-    return Response.json({ ok: true, requirements: rows });
+    // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
+    return Response.json({ ok: true, requirements: rows, capabilities: REQUIREMENT_CAPABILITIES });
   }
 
   if (url.pathname === "/api/requirements" && req.method === "POST") {
@@ -188,14 +384,22 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     if (!name || name.length > 80) return jsonError("invalid_name", 400);
     const priority = typeof body.priority === "string" ? body.priority : "normal";
     if (!PRIORITIES.has(priority)) return jsonError("invalid_priority", 400);
-    const due = typeof body.due === "string" ? body.due.trim() : "";
-    if (due && !dueOk(due)) return jsonError("invalid_due", 400);
+    const due = typeof body.due === "string" ? normalizeDue(body.due) : "";
+    if (due === null) return jsonError("invalid_due", 400);
     const assignee = typeof body.assignee === "string" ? body.assignee.trim().slice(0, 80) : "";
     const clientId = typeof body.client_id === "string" ? body.client_id.trim() : "";
     if (clientId && !/^[A-Za-z0-9._-]{1,80}$/.test(clientId)) return jsonError("invalid_client_id", 400);
     const column = typeof body.column === "string" && COLUMNS.has(body.column) ? body.column : "pool";
     const issues = body.issues === undefined ? [] : normalizeIssues(body.issues);
     if (issues === null) return jsonError("invalid_issues", 400);
+    const description = body.description === undefined ? "" : normalizeDescription(body.description);
+    if (description === null) return jsonError("invalid_description", 400);
+    const checklist = body.checklist === undefined ? [] : normalizeChecklist(body.checklist);
+    if (checklist === null) return jsonError("invalid_checklist", 400);
+    let projectId: string | null = null;
+    if (body.project_id !== undefined) {
+      try { projectId = projectRef(body.project_id, networkId); } catch (e) { return jsonError((e as Error).message, 400); }
+    }
     if (clientId) {
       const existing = db.get<Row>(
         `SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`,
@@ -210,9 +414,9 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     try {
       db.run(
         `INSERT INTO requirements
-         (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json)
-         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13)`,
-        [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson],
+         (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17)`,
+        [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId],
       );
     } catch {
       if (!clientId) return jsonError("insert_failed", 500);
@@ -227,6 +431,29 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     return Response.json({ ok: true, requirement: toPublic(created) }, { status: 201 });
   }
 
+  const itemMatch = url.pathname.match(/^\/api\/requirements\/([^/]+)\/checklist\/([^/]+)$/);
+  if (itemMatch) {
+    if (req.method !== "PATCH") return jsonError("not_found", 404);
+    let body: Record<string, unknown>;
+    try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
+    if (typeof body.done !== "boolean") return jsonError("invalid_done", 400);
+    const params: unknown[] = [decodeURIComponent(itemMatch[1])];
+    let sql = `SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`;
+    sql = addNetworkScope(sql, params, ctx.scope);
+    const row = db.get<Row>(sql, ...params);
+    if (!row) return jsonError("requirement_not_found", 404);
+    if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
+    const items = storedChecklist(row.checklist_json);
+    const itemId = decodeURIComponent(itemMatch[2]);
+    const item = items.find(entry => entry.id === itemId);
+    if (!item) return jsonError("checklist_item_not_found", 404);
+    item.done = body.done;
+    db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2 WHERE requirement_id = ?3", [JSON.stringify(items), new Date().toISOString(), row.requirement_id]);
+    const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
+    return Response.json({ ok: true, requirement: toPublic(updated) });
+  }
+
   const match = url.pathname.match(/^\/api\/requirements\/([^/]+)$/);
   if (!match || req.method !== "PATCH") return jsonError("not_found", 404);
   const id = decodeURIComponent(match[1]);
@@ -234,7 +461,18 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
   const hasColumn = 'column' in body;
   const hasIssues = Object.prototype.hasOwnProperty.call(body, "issues");
-  if (!hasColumn && !hasIssues && !('owner' in body) && !('participants' in body)) return jsonError('empty_patch', 400);
+  const hasName = 'name' in body;
+  const hasPriority = 'priority' in body;
+  const hasDue = 'due' in body;
+  const hasAssignee = 'assignee' in body;
+  const hasDescription = 'description' in body;
+  const hasChecklist = 'checklist' in body;
+  const hasProject = 'project_id' in body;
+  if (!hasColumn && !hasIssues && !hasName && !hasPriority && !hasDue && !hasAssignee && !('owner' in body) && !('agent_owner' in body) && !('participants' in body) && !hasDescription && !hasChecklist && !hasProject) return jsonError('empty_patch', 400);
+  const description = hasDescription ? normalizeDescription(body.description) : null;
+  if (hasDescription && description === null) return jsonError("invalid_description", 400);
+  const checklist = hasChecklist ? normalizeChecklist(body.checklist) : null;
+  if (hasChecklist && checklist === null) return jsonError("invalid_checklist", 400);
   if (hasColumn && !COLUMNS.has(String(body.column))) return jsonError("invalid_column", 400);
   const issues = hasIssues ? normalizeIssues(body.issues) : null;
   if (hasIssues && issues === null) return jsonError("invalid_issues", 400);
@@ -244,12 +482,39 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   const row = db.get<Row>(sql, ...params);
   if (!row) return jsonError("requirement_not_found", 404);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+  let name = row.title;
+  if (hasName) {
+    name = typeof body.name === "string" ? body.name.trim() : "";
+    if (!name || name.length > 80) return jsonError("invalid_name", 400);
+  }
+  let priority = row.priority;
+  if (hasPriority) {
+    if (typeof body.priority !== "string" || !PRIORITIES.has(body.priority)) return jsonError("invalid_priority", 400);
+    priority = body.priority;
+  }
+  let due = row.due_on || "";
+  if (hasDue) {
+    if (typeof body.due !== "string") return jsonError("invalid_due", 400);
+    const next = normalizeDue(body.due);
+    if (next === null) return jsonError("invalid_due", 400);
+    due = next;
+  }
+  let assignee = row.assignee || "";
+  if (hasAssignee) {
+    if (typeof body.assignee !== "string") return jsonError("invalid_assignee", 400);
+    assignee = body.assignee.trim().slice(0, 80);
+  }
   let people;
   try { people = assignments(body, row.network_id, row); } catch (e) { return jsonError((e as Error).message, 400); }
+  let projectId = row.project_id;
+  if (hasProject) {
+    try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return jsonError((e as Error).message, 400); }
+  }
   const updatedAt = new Date().toISOString();
   db.run(
-    "UPDATE requirements SET column_name = ?1, updated_at = ?2, owner_json = ?4, participants_json = ?5, issues_json = ?6 WHERE requirement_id = ?3",
-    [hasColumn ? body.column : row.column_name, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, hasIssues ? JSON.stringify(issues) : row.issues_json],
+    "UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6, agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14 WHERE requirement_id = ?3",
+    [hasColumn ? body.column : row.column_name, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, hasIssues ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
+      hasDescription ? (description || null) : row.description, hasChecklist ? JSON.stringify(checklist) : row.checklist_json, projectId],
   );
   const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
   return Response.json({ ok: true, requirement: toPublic(updated) });