@sleep2agi/commhub-server 0.9.0-preview.67 → 0.9.0-preview.68

package/src/requirements-http.test.ts

@@ -55,6 +55,84 @@ afterAll(() => {
 describe("requirements stay on the hub", () => {
   let id = "";
 
+  test("name limit is consistent across create, PATCH and both upsert paths", async () => {
+    const send = (path: string, method: string, body: unknown) => api(ownerToken, path, { method, body: JSON.stringify(body) });
+    const ref = 'github:test/name-limit#1';
+    const created = await send('/api/requirements/upsert', 'POST', { name: '字'.repeat(80), external_ref: ref });
+    expect(created.status).toBe(201);
+    const path = `/api/requirements/${created.body.requirement.id}`;
+    for (const name of ['a'.repeat(150), '字'.repeat(81), '   ', null, 12]) {
+      for (const [url, method, extra] of [
+        ['/api/requirements', 'POST', {}],
+        [path, 'PATCH', {}],
+        ['/api/requirements/upsert', 'POST', { external_ref: ref }],
+        ['/api/requirements/upsert', 'POST', { external_ref: 'github:test/name-limit#2' }],
+      ] as const) {
+        const result = await send(url, method, { ...extra, name });
+        expect(result.status).toBe(400);
+        expect(result.body.error).toBe('invalid_name');
+      }
+    }
+    expect((await api(ownerToken, path)).body.requirement.name).toBe('字'.repeat(80));
+    const boundary = await send(path, 'PATCH', { name: `  ${'界'.repeat(80)}  ` });
+    expect(boundary.status).toBe(200);
+    expect(boundary.body.requirement.name).toBe('界'.repeat(80));
+    expect((await send(path, 'PATCH', { priority: 'high' })).body.requirement.name).toBe('界'.repeat(80));
+    await api(ownerToken, path, { method: 'DELETE' });
+  });
+
+  test("archived=true returns only archived tasks and default excludes them", async () => {
+    const create = async (token: string, name: string) => api(token, '/api/requirements', { method: 'POST', body: JSON.stringify({ name }) });
+    const active = (await create(ownerToken, 'archive-filter-active')).body.requirement.id;
+    const archived = (await create(ownerToken, 'archive-filter-archived')).body.requirement.id;
+    const foreign = (await create(otherToken, 'archive-filter-foreign')).body.requirement.id;
+    for (const [token, taskId] of [[ownerToken, archived], [otherToken, foreign]]) {
+      expect((await api(token, `/api/requirements/${taskId}`, { method: 'PATCH', body: JSON.stringify({ archived: true }) })).status).toBe(200);
+    }
+    const ids = async (query: string) => {
+      const result = await api(ownerToken, `/api/requirements${query}${query ? '&' : '?'}network_id=${ownerNetwork}`);
+      expect(result.status).toBe(200);
+      return result.body.requirements.map((task: any) => task.id);
+    };
+    expect(await ids('?archived=true')).toEqual([archived]);
+    expect(await ids('?archived=true&include_archived=1')).toEqual([archived]);
+    const defaults = await ids('');
+    expect(defaults).toContain(active);
+    expect(defaults).not.toContain(archived);
+    expect(defaults).not.toContain(foreign);
+    expect(await ids('?archived=false')).toEqual(defaults);
+    const all = await ids('?include_archived=1');
+    expect(all).toContain(active);
+    expect(all).toContain(archived);
+    expect(all).not.toContain(foreign);
+    for (const [token, taskId] of [[ownerToken, active], [ownerToken, archived], [otherToken, foreign]]) {
+      await api(token, `/api/requirements/${taskId}`, { method: 'DELETE' });
+    }
+  });
+
+  test("tags validate, aggregate within network, and survive old PATCH shapes", async () => {
+    const created = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: 'tagged task', tags: [' UI ', 'UI', '交付'] }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.tags).toEqual(['UI', '交付']);
+    const path = `/api/requirements/${created.body.requirement.id}`;
+    const old = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ column: 'doing', name: 'old app edit' }) });
+    expect(old.status).toBe(200);
+    expect(old.body.requirement.tags).toEqual(['UI', '交付']);
+    for (const tags of [null, 'UI', [12], [''], ['a'.repeat(21)], Array.from({ length: 11 }, (_, i) => `t${i}`)]) {
+      const invalid = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ tags }) });
+      expect(invalid.status).toBe(400);
+      expect(invalid.body.error).toBe('invalid_tags');
+    }
+    const own = await api(ownerToken, '/api/requirements/tags');
+    expect(own.body.tags).toEqual(['UI', '交付']);
+    expect((await api(otherToken, '/api/requirements/tags')).body.tags).toEqual([]);
+    expect((await api(nodeToken, '/api/requirements/tags')).body.tags).toEqual(['UI', '交付']);
+    expect((await api(viewerToken, `${path}?network_id=${ownerNetwork}`, { method: 'PATCH', body: JSON.stringify({ tags: [] }) })).status).toBe(403);
+    const cleared = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ tags: [] }) });
+    expect(cleared.body.requirement.tags).toEqual([]);
+    expect((await api(ownerToken, '/api/requirements/tags')).body.tags).toEqual([]);
+  });
+
   test("typed assignments validate network membership, preserve kinds and clear explicitly", async () => {
     const { db } = await import('./db.js');
     const ownerId = db.get<{ owner_id: string }>('SELECT owner_id FROM networks WHERE network_id=?1', ownerNetwork)!.owner_id;
@@ -294,7 +372,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-mcp.test.ts

@@ -70,9 +70,12 @@ describe("requirements MCP tools", () => {
       const first = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, external_url: "https://github.com/acme/widgets/issues/42", name: "修复登录", description: "issue 正文", checklist: [{ id: "c1", text: "复现" }, { id: "c2", text: "修" }] });
       expect(first.ok).toBe(true);
       expect(first.created).toBe(true);
+      const tagged = await s.call("requirements_update", { id: first.requirement.id, tags: ["release"] });
+      expect(tagged.requirement.tags).toEqual(["release"]);
       expect(first.requirement.created_by).toEqual({ kind: "node", id: "node_gh_sync" });
       const again = await s.call("requirements_upsert_by_external_ref", { external_ref: ref, name: "修复登录(改了标题)" });
       expect(again.created).toBe(false);
+      expect(again.requirement.tags).toEqual(["release"]);
       expect(again.requirement.id).toBe(first.requirement.id);
       const listed = await s.call("requirements_list", { external_ref: ref });
       expect(listed.requirements.length).toBe(1);

package/src/requirements.ts

@@ -1,7 +1,9 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { db } from "./db.js";
-import { addNetworkScope, canRestWriteNetwork, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+import { normalizeTags, storedTags } from "./requirement-tags.js";
+import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
+import { isAgentRestricted, visibleAgents } from "./agent-access.js";
 import { ensureRequirementIndexes, ensureRequirementProjects, migrateRequirementAgentOwners } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
@@ -50,6 +52,7 @@ type Row = {
   due_on: string | null;
   assignee: string | null;
   issues_json: string | null;
+  tags_json: string | null;
   created_at: string;
 };
 
@@ -284,6 +287,7 @@ function toPublic(row: Row) {
     createdAt: row.created_at,
     updatedAt: row.updated_at || row.created_at,
     issues: storedIssues(row.issues_json),
+    tags: storedTags(row.tags_json),
     // 同步用的外部引用(如 github:owner/repo#123)和链接;归档的卡默认不在列表里(include_archived=1 才有)。
     external_ref: row.external_ref || null,
     external_url: row.external_url || null,
@@ -312,22 +316,55 @@ function writeNetwork(body: Record<string, unknown>, ctx: RequirementsRequestCon
 function canWrite(ctx: RequirementsRequestContext, networkId: string | null): boolean {
   // 节点令牌只能写它绑定的那个网络(scope 已强制;这里再核一次,防止别的入口绕过 scope)。
   if (ctx.isNodeToken && (!ctx.auth?.networkId || ctx.auth.networkId !== networkId)) return false;
-  return canRestWriteNetwork(ctx.auth, networkId, ctx.isAdmin);
+  if (ctx.isNodeToken) return canRestWriteNetwork(ctx.auth, networkId, ctx.isAdmin);
+  // 需求看板是人类协作面:受限成员(只看授权 Agent 的成员)照样能读写卡片,
+  // 只是卡片上没授权给他的 Agent 引用会被隐去、也不能被他指派(见 hiddenNodeFilter)。
+  return canRestWriteNetworkAsHuman(ctx.auth, networkId, ctx.isAdmin);
+}
+
+// ── 多用户 Agent 权限 ──
+// 受限成员看需求卡时:agent_owner / 参与人 / created_by / updated_by 里没授权给他的节点一律隐去;
+// 他写卡时也不能引用这些节点。返回 null = 这个调用者在这个网络里不受限。
+type HiddenNode = ((nodeId: string) => boolean) | null;
+function hiddenNodeFilter(ctx: RequirementsRequestContext, networkId: string): HiddenNode {
+  if (!ctx.auth || ctx.isNodeToken || ctx.isAdmin) return null;
+  if (!isAgentRestricted(ctx.auth.userId, networkId)) return null;
+  const visible = new Set(visibleAgents(ctx.auth.userId, networkId).nodeIds);
+  return (nodeId: string) => !visible.has(nodeId);
+}
+function isHiddenRef(ref: unknown, hidden: HiddenNode): boolean {
+  if (!hidden || !ref || typeof ref !== "object") return false;
+  const r = ref as { kind?: unknown; id?: unknown };
+  return r.kind === "node" && typeof r.id === "string" && hidden(r.id);
+}
+function toPublicFor(ctx: RequirementsRequestContext, row: Row) {
+  const pub = toPublic(row);
+  const hidden = hiddenNodeFilter(ctx, row.network_id);
+  if (!hidden) return pub;
+  return {
+    ...pub,
+    owner: isHiddenRef(pub.owner, hidden) ? null : pub.owner,
+    agent_owner: isHiddenRef(pub.agent_owner, hidden) ? null : pub.agent_owner,
+    participants: Array.isArray(pub.participants) ? pub.participants.filter((ref: unknown) => !isHiddenRef(ref, hidden)) : pub.participants,
+    created_by: isHiddenRef(pub.created_by, hidden) ? null : pub.created_by,
+    updated_by: isHiddenRef(pub.updated_by, hidden) ? null : pub.updated_by,
+  };
 }
 
-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, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, " +
+const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0) AS children_total, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0 AND c.column_name = 'done') AS children_done";
 
 type PersonRef = { kind: 'user' | 'node'; id: string };
-function personRef(value: unknown, networkId: string): PersonRef {
+function personRef(value: unknown, networkId: string, hidden: HiddenNode = null): PersonRef {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid_person');
   const row = value as Record<string, unknown>;
   if ((row.kind !== 'user' && row.kind !== 'node') || typeof row.id !== 'string' || !row.id.trim()) throw new Error('invalid_person');
   const exists = row.kind === 'user'
     ? db.get("SELECT 1 FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 AND m.user_id=?2", networkId, row.id)
     : db.get("SELECT 1 FROM nodes WHERE network_id=?1 AND node_id=?2", networkId, row.id);
-  if (!exists) throw new Error('person_not_in_network');
+  // 没授权的节点与不存在的节点同一个错误,不给受限成员留 node_id 探测差异。
+  if (!exists || (row.kind === 'node' && hidden?.(row.id as string))) throw new Error('person_not_in_network');
   return { kind: row.kind, id: row.id };
 }
 
@@ -336,12 +373,14 @@ function personRef(value: unknown, networkId: string): PersonRef {
 // 旧客户端兼容(App ≤ 0.2.142 只有一个「负责人」,可以选节点):请求里 owner 是节点、又**没带** agent_owner
 // → 当成设置负责 Agent,负责人清空,照常 200,并回 owner_coerced_to_agent_owner: true。
 // 带了 agent_owner 的就是新客户端,保持严格:owner 是节点 → 400 owner_must_be_human。
-function assignments(body: Record<string, unknown>, networkId: string, current?: Row) {
+function assignments(body: Record<string, unknown>, networkId: string, current?: Row, hidden: HiddenNode = null) {
   let owner = current?.owner_json ? JSON.parse(current.owner_json) : null;
   let agentOwner = current?.agent_owner_json ? JSON.parse(current.agent_owner_json) : null;
   let coerced: PersonRef | null = null;
+  // 受限成员看不见的负责 Agent,他也不能换掉或清空(他读到的是 null,写回 null 不该抹掉别人的指派)。
+  const agentOwnerLocked = isHiddenRef(agentOwner, hidden);
   if ('owner' in body) {
-    owner = body.owner === null ? null : personRef(body.owner, networkId);
+    owner = body.owner === null ? null : personRef(body.owner, networkId, hidden);
     if (owner && owner.kind !== 'user') {
       if ('agent_owner' in body) throw new Error('owner_must_be_human');
       coerced = owner;
@@ -349,15 +388,19 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
       owner = null;
     }
   }
+  if (coerced && agentOwnerLocked) throw new Error('agent_owner_not_granted');
   if ('agent_owner' in body) {
-    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId);
+    if (agentOwnerLocked) throw new Error('agent_owner_not_granted');
+    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId, hidden);
     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()];
+    const refs = body.participants.map(value => personRef(value, networkId, hidden));
+    // 参与人是整体替换:把受限成员看不见的那些节点原样留下,别让他「保存」时静默删掉。
+    const keptHidden = hidden ? participants.filter((ref: unknown) => isHiddenRef(ref, hidden)) : [];
+    participants = [...new Map([...keptHidden, ...refs].map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref])).values()];
   }
   return {
     coerced,
@@ -382,7 +425,7 @@ function operationOf(req: Request, url: URL): string {
   return "create";
 }
 
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements"] as const;
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -495,6 +538,8 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   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 tags = body.tags === undefined ? [] : normalizeTags(body.tags);
+  if (tags === null) return jsonError("invalid_tags", 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);
@@ -520,19 +565,19 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   }
   if (clientId) {
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
-    if (existing) return Response.json({ ok: true, requirement: toPublic(existing) });
+    if (existing) return Response.json({ ok: true, requirement: toPublicFor(ctx, existing) });
   }
   const id = `req_${crypto.randomUUID()}`;
   const createdAt = new Date().toISOString();
   let people;
-  try { people = assignments(body, networkId); } catch (e) { return jsonError((e as Error).message, 400); }
+  try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
   const actor = JSON.stringify(actorOf(ctx));
   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, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21)`,
-      [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, ref, extUrl, actor, parentId],
+       (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, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22)`,
+      [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, ref, extUrl, actor, parentId, JSON.stringify(tags)],
     );
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
@@ -543,14 +588,14 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
     if (!clientId) return jsonError("insert_failed", 500);
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
     if (!existing) return jsonError("insert_failed", 500);
-    return Response.json({ ok: true, requirement: toPublic(existing) });
+    return Response.json({ ok: true, requirement: toPublicFor(ctx, existing) });
   }
   const created = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, id)!;
-  return Response.json(withLegacyOwner(toPublic(created), people.coerced), { status: 201 });
+  return Response.json(withLegacyOwner(toPublicFor(ctx, created), people.coerced), { status: 201 });
 }
 
 // ── 修改(省略的字段保留原值) ──
-const PATCH_FIELDS = ["column", "issues", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id"];
+const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id"];
 function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Record<string, unknown>): Response {
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
@@ -558,6 +603,8 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   if (has("column") && !COLUMNS.has(String(body.column))) return jsonError("invalid_column", 400);
   const issues = has("issues") ? normalizeIssues(body.issues) : null;
   if (has("issues") && issues === null) return jsonError("invalid_issues", 400);
+  const tags = has("tags") ? normalizeTags(body.tags) : null;
+  if (has("tags") && tags === null) return jsonError("invalid_tags", 400);
   const description = has("description") ? normalizeDescription(body.description) : null;
   if (has("description") && description === null) return jsonError("invalid_description", 400);
   const checklist = has("checklist") ? normalizeChecklist(body.checklist) : null;
@@ -585,7 +632,7 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     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); }
+  try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id)); } catch (e) { return jsonError((e as Error).message, 400); }
   let projectId = row.project_id;
   if (has("project_id")) {
     try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return jsonError((e as Error).message, 400); }
@@ -624,13 +671,13 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   const updatedAt = new Date().toISOString();
   db.run(
     `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, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19
+       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20
      WHERE requirement_id = ?3`,
     [has("column") ? body.column : row.column_name, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
-      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, JSON.stringify(actorOf(ctx)), parentId],
+      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, JSON.stringify(actorOf(ctx)), parentId, has("tags") ? JSON.stringify(tags) : row.tags_json],
   );
   const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
-  return Response.json(withLegacyOwner(toPublic(updated), people.coerced));
+  return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
 }
 
 /**
@@ -646,12 +693,12 @@ function withLegacyOwner(requirement: ReturnType<typeof toPublic>, coerced: Pers
 function scopedRow(ctx: RequirementsRequestContext, id: string): Row | undefined {
   const params: unknown[] = [id];
   let sql = `SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`;
-  sql = addNetworkScope(sql, params, ctx.scope);
+  sql = addHumanNetworkScope(sql, params, ctx.scope);
   return db.get<Row>(sql, ...params) ?? undefined;
 }
 
 /** GET 的筛选(同步方 / MCP 用):status、project_id、owner / agent_owner(kind:id)、updated_since、external_ref、parent_id / top_level、include_archived。 */
-function listFilters(url: URL, sql: string, params: unknown[]): string | Response {
+function listFilters(url: URL, sql: string, params: unknown[], ctx?: RequirementsRequestContext): string | Response {
   const q = url.searchParams;
   const status = q.get("status");
   if (status !== null) {
@@ -666,6 +713,8 @@ function listFilters(url: URL, sql: string, params: unknown[]): string | Respons
     if (v === "none") { sql += ` AND ${column} IS NULL`; continue; }
     const m = /^(user|node):(.+)$/.exec(v);
     if (!m) return jsonError(`invalid_${param}`, 400);
+    // 受限成员按一个没授权给他的节点筛选:与「没有这样的卡」同一结果(否则是「谁负责这张卡」的探测器)。
+    if (m[1] === "node" && ctx && hiddenFilterForScope(ctx, m[2])) { sql += " AND 1=0"; continue; }
     sql += ` AND ${column} = ?${params.push(JSON.stringify({ kind: m[1], id: m[2] }))}`;
   }
   const since = q.get("updated_since");
@@ -679,10 +728,22 @@ function listFilters(url: URL, sql: string, params: unknown[]): string | Respons
   const parent = q.get("parent_id");
   if (parent !== null) sql += parent === "none" ? " AND parent_id IS NULL" : ` AND parent_id = ?${params.push(parent)}`;
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
-  if (q.get("include_archived") !== "1") sql += " AND COALESCE(archived, 0) = 0";
+  // Explicit archived-only wins over the legacy include-all switch.
+  if (q.get("archived") === "true") sql += " AND COALESCE(archived, 0) = 1";
+  else if (q.get("include_archived") !== "1") sql += " AND COALESCE(archived, 0) = 0";
   return sql;
 }
 
+/** 这个节点对调用者在他作用域内的某个受限网络里是否隐藏。 */
+function hiddenFilterForScope(ctx: RequirementsRequestContext, nodeId: string): boolean {
+  const restricted = ctx.scope.agentRestriction?.networkIds ?? [];
+  for (const networkId of restricted) {
+    const hidden = hiddenNodeFilter(ctx, networkId);
+    if (hidden?.(nodeId)) return true;
+  }
+  return false;
+}
+
 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;
@@ -692,25 +753,34 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
 
   if (url.pathname === "/api/requirements/projects" || url.pathname.startsWith("/api/requirements/projects/")) return handleProjects(ctx);
 
+  if (url.pathname === "/api/requirements/tags" && req.method === "GET") {
+    const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+    if (!networkId) return jsonError("network_id_required", 400);
+    const rows = db.all<{ tags_json: string | null }>("SELECT tags_json FROM requirements WHERE network_id=?1", networkId);
+    const tags = [...new Set(rows.flatMap(row => storedTags(row.tags_json)))].sort();
+    return Response.json({ ok: true, networkId, tags });
+  }
+
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError('network_id_required', 400);
     const users = db.all<{ id: string; name: string }>(
       "SELECT u.user_id AS id, COALESCE(NULLIF(u.display_name,''), u.username) AS name FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 ORDER BY name, id", networkId,
     );
+    const hidden = hiddenNodeFilter(ctx, networkId);
     const nodes = db.all<{ id: string; name: string }>(
       "SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name FROM nodes WHERE network_id=?1 ORDER BY name, id", networkId,
-    );
+    ).filter(row => !hidden?.(row.id));
     return Response.json({ ok: true, people: [...users.map(row => ({ ...row, kind: 'user', networkId })), ...nodes.map(row => ({ ...row, kind: 'node', networkId }))] });
   }
 
   if (url.pathname === "/api/requirements" && req.method === "GET") {
     const params: unknown[] = [];
     let sql = `SELECT ${SELECT} FROM requirements WHERE 1=1`;
-    sql = addNetworkScope(sql, params, ctx.scope);
-    const filtered = listFilters(url, sql, params);
+    sql = addHumanNetworkScope(sql, params, ctx.scope);
+    const filtered = listFilters(url, sql, params, ctx);
     if (typeof filtered !== "string") return filtered;
-    const rows = db.all<Row>(`${filtered} ORDER BY created_at DESC LIMIT 500`, ...params).map(toPublic);
+    const rows = db.all<Row>(`${filtered} ORDER BY created_at DESC LIMIT 500`, ...params).map(row => toPublicFor(ctx, row));
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
     return Response.json({ ok: true, requirements: rows, capabilities: REQUIREMENT_CAPABILITIES });
   }
@@ -739,7 +809,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
       return Response.json({ ...data, created: true }, { status: 201 });
     }
     const { external_ref: _ref, network_id: _net, client_id: _client, ...patch } = body;
-    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) return Response.json({ ok: true, requirement: toPublic(existing), created: false });
+    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) return Response.json({ ok: true, requirement: toPublicFor(ctx, existing), created: false });
     const res = patchRequirement(ctx, existing, patch);
     if (res.status !== 200) return res;
     const data = await res.json() as Record<string, unknown>;
@@ -763,7 +833,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     item.done = body.done;
     db.run("UPDATE requirements SET checklist_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(items), new Date().toISOString(), JSON.stringify(actorOf(ctx)), 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) });
+    return Response.json({ ok: true, requirement: toPublicFor(ctx, updated) });
   }
 
   const match = url.pathname.match(/^\/api\/requirements\/([^/]+)$/);
@@ -771,7 +841,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   const id = decodeURIComponent(match[1]);
   if (req.method === "GET") {
     const row = scopedRow(ctx, id);
-    return row ? Response.json({ ok: true, requirement: toPublic(row) }) : jsonError("requirement_not_found", 404);
+    return row ? Response.json({ ok: true, requirement: toPublicFor(ctx, row) }) : jsonError("requirement_not_found", 404);
   }
   if (req.method === "DELETE") {
     // 删除只给人(节点令牌在入口已被拒):Agent 用 archived 归档。

package/src/rest-explicit-columns-http.test.ts

@@ -31,7 +31,7 @@ const GOLDEN_RESPONSE_KEYS = {
   //    —— 理由见本文件顶部：从投影推导会让被删掉的列同时从响应和期望里消失，产生假绿。
   authMeNetwork: [
     "network_id", "network_name", "owner_id", "description", "settings",
-    "created_at", "updated_at", "visibility", "max_members", "member_role",
+    "created_at", "updated_at", "visibility", "max_members", "member_role", "agent_access",
   ],
   networkDetail: [
     "network_id", "network_name", "owner_id", "description", "settings",

package/src/restricted-files.ts

@@ -0,0 +1,73 @@
+// 多用户 Agent 权限 —— 受限成员与上传文件。
+// 文件按网络归属;受限成员(只看授权 Agent 的成员)在受限网络里不能凭 file_id 读网络里任意文件,
+// 也不能把自己看不见的 file_id 塞进发给授权 Agent 的任务(那等于借 Agent 的网络令牌去读)。
+import { existsSync, readFileSync } from "fs";
+import { db } from "./db.js";
+import { addOwnTrafficScope, type RestNetworkScope } from "./network-scope.js";
+import { FILE_ID_REGEX, indexEntryPath, validateIndexEntry } from "./uploads.js";
+
+/**
+ * 受限成员能不能看见这个文件:只认**对方(授权 Agent / 给他发私信的人)放进来**的附件 ——
+ *   user_inbox 里发给自己的私信附件;
+ *   授权 Agent 发给自己的任务 / inbox 行的 attachments;
+ *   自己发给授权 Agent 的任务上,Agent 回复写进的 reply_attachments。
+ * 自己随任务带出去的 attachments **不算**:否则把任意 file_id 塞进自己的任务就能「解锁」别人的文件。
+ */
+export function restrictedMemberSeesFile(userId: string, username: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const listed = (metaJson: string | null | undefined, key: "attachments" | "reply_attachments"): boolean => {
+    if (!metaJson) return false;
+    try {
+      const list = JSON.parse(metaJson)?.[key];
+      return Array.isArray(list) && list.some((a: any) => a && typeof a === "object" && a.file_id === fileId);
+    } catch { return false; }
+  };
+  // LIKE 只做预筛(file_id 只含 [A-Za-z0-9_-],`_` 转义后逐字匹配),真正的判定在 listed() 里按键解析。
+  const needle = `%"${fileId.replace(/_/g, "\\_")}"%`;
+  for (const row of db.all<{ meta_json: string | null }>(
+    "SELECT meta_json FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND meta_json LIKE ?3 ESCAPE '\\' LIMIT 50",
+    userId, networkId, needle,
+  )) {
+    if (listed(row.meta_json, "attachments")) return true;
+  }
+  const scope: RestNetworkScope = { networkId, networkIds: null, agentRestriction: { userId, username, networkIds: [networkId] } };
+  const taskParams: unknown[] = [needle];
+  const taskSql = addOwnTrafficScope("SELECT from_name, to_name, meta_json FROM tasks WHERE meta_json LIKE ?1 ESCAPE '\\'", taskParams, scope, { from: "from_name", to: "to_name", fromNodeId: "from_node_id", toNodeId: "to_node_id" });
+  for (const row of db.all<{ from_name: string; to_name: string; meta_json: string | null }>(taskSql + " LIMIT 50", ...taskParams)) {
+    if (row.to_name === username && listed(row.meta_json, "attachments")) return true;
+    if (row.from_name === username && listed(row.meta_json, "reply_attachments")) return true;
+  }
+  const inboxParams: unknown[] = [needle];
+  const inboxSql = addOwnTrafficScope("SELECT session_name, meta_json FROM inbox WHERE meta_json LIKE ?1 ESCAPE '\\'", inboxParams, scope, { from: "from_session", to: "session_name" });
+  for (const row of db.all<{ session_name: string; meta_json: string | null }>(inboxSql + " LIMIT 50", ...inboxParams)) {
+    if (row.session_name === username && listed(row.meta_json, "attachments")) return true;
+  }
+  return false;
+}
+
+/** 受限成员能不能用这个文件(下载 / 当附件转给 Agent):自己传的,或 restrictedMemberSeesFile。 */
+export function restrictedMemberCanUseFile(userId: string, username: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const path = indexEntryPath(fileId);
+  if (!path || !existsSync(path)) return false;
+  let entry: any;
+  try { entry = JSON.parse(readFileSync(path, "utf8")); } catch { return false; }
+  if (!validateIndexEntry(entry) || entry.file_id !== fileId) return false;
+  if (entry.network_id !== networkId) return false;
+  if (entry.owner_id === userId) return true;
+  return restrictedMemberSeesFile(userId, username, networkId, fileId);
+}
+
+/**
+ * 受限成员发给 Agent 的任务 / 消息里的附件:每个 file_id 都必须是他自己能用的文件。
+ * 返回第一个不合格的 file_id(调用方回 403),全部合格返回 null。
+ */
+export function restrictedMemberAttachmentsDenied(userId: string, username: string, networkId: string, raw: unknown): string | null {
+  if (!Array.isArray(raw)) return null;
+  for (const item of raw) {
+    const fileId = item && typeof item === "object" ? (item as { file_id?: unknown }).file_id : undefined;
+    if (fileId === undefined) continue;
+    if (typeof fileId !== "string" || !restrictedMemberCanUseFile(userId, username, networkId, fileId)) return String(fileId);
+  }
+  return null;
+}

package/src/scheduled-tasks-http.test.ts

@@ -41,7 +41,8 @@ beforeAll(async () => {
   expect(viewer.ok).toBe(true);
   viewerToken = viewer.token!;
   const viewerId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", viewer.user!.username)!.user_id;
-  addNetworkMember(networkId, viewerId, "viewer", ownerId);
+  // 多用户 Agent 权限:新成员默认只看授权 Agent;本测试测的是「完全信任的成员」旧语义,显式 agent_access=all。
+  addNetworkMember(networkId, viewerId, "viewer", ownerId, { agentAccess: "all" });
   const ntok = createNetworkTokenForNode(ownerId, networkId, "scheduler-node");
   expect(ntok.ok).toBe(true);
   nodeToken = ntok.token!;

package/src/scheduled-tasks.ts

@@ -1,6 +1,7 @@
 import { db, logTaskEvent } from "./db.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { addNetworkScope, canRestWriteNetwork, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
+import { canMessageAgent } from "./agent-access.js";
 import { hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
 
@@ -266,6 +267,17 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
       if (advanceSchedule) advance(row, scheduledFor, advanceAfter);
       return;
     }
+    // 多用户 Agent 权限:排程是「建它的人」的委托。建的人后来被设成受限成员、而且没被授权
+    // 给目标 Agent 发任务时,不再代他派发(否则受限前建的排程会永远绕过授权)。
+    if (row.created_by && !canMessageAgent(row.created_by, row.network_id, { alias: node.alias, nodeId: node.node_id })) {
+      finalStatus = "failed";
+      db.run(
+        "UPDATE scheduled_task_runs SET status = 'failed', error_code = 'creator_access_revoked', error_message = 'The schedule creator is no longer allowed to message this agent', completed_at = datetime('now') WHERE run_id = ?1",
+        [runId],
+      );
+      if (advanceSchedule) advance(row, scheduledFor, advanceAfter);
+      return;
+    }
     const lifecycle = assertNodeActive(node.alias, row.network_id);
     if (!lifecycle.ok) {
       finalStatus = "failed";