@sleep2agi/commhub-server 0.9.0-preview.79 → 0.9.0-preview.80

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.79",
+  "version": "0.9.0-preview.80",
   "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/human-dm.ts

@@ -78,13 +78,7 @@ export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
   const metaJson = attachments.attachments.length ? JSON.stringify({ attachments: attachments.attachments }) : null;
 
   db.transaction(() => {
-    db.run(
-      // created_at 带毫秒:同一秒里一来一回的两条私信要能排出先后(秒级的 datetime('now') 排不出)。
-      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, sender_user_id, created_at)
-       VALUES (?1, ?2, ?3, ?4, ?5, NULL, ?6, 'info', ?7, ?8, strftime('%Y-%m-%d %H:%M:%f', 'now'))
-       ON CONFLICT(message_id) DO NOTHING`,
-      [messageId, networkId, target.user_id, sender.username, HUMAN_DM_KIND, text, metaJson, sender.userId],
-    );
+    insertDmRow({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
     db.run(
       `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
        VALUES (?1, ?2, 'human_dm_sent', 'user', ?3, ?4, ?5)`,
@@ -97,20 +91,65 @@ export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
     messageId,
   )!;
   // 推送在提交之后(与 send_desktop_message 同一条规矩:回滚的消息不能先被看见)。
-  const delivered = hasUserSubscribers(networkId, target.user_id);
-  pushUserEvent(networkId, target.user_id, {
+  const delivered = pushDmEvent({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
+  return { ok: true, message: redactMessageRow(row), delivered };
+}
+
+type DmRow = { messageId: string; networkId: string; targetUserId: string; sender: { userId: string; username: string }; title: string | null; text: string; metaJson: string | null };
+
+function insertDmRow(m: DmRow): void {
+  db.run(
+    // created_at 带毫秒:同一秒里一来一回的两条私信要能排出先后(秒级的 datetime('now') 排不出)。
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, sender_user_id, created_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'info', ?8, ?9, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+     ON CONFLICT(message_id) DO NOTHING`,
+    [m.messageId, m.networkId, m.targetUserId, m.sender.username, HUMAN_DM_KIND, m.title, m.text, m.metaJson, m.sender.userId],
+  );
+}
+
+/** 推 desktop_message 到收件人的 /events/users/me。返回推送时他有没有在线的订阅。 */
+function pushDmEvent(m: DmRow): boolean {
+  const delivered = hasUserSubscribers(m.networkId, m.targetUserId);
+  pushUserEvent(m.networkId, m.targetUserId, {
     type: "desktop_message",
-    message_id: messageId,
+    message_id: m.messageId,
     kind: HUMAN_DM_KIND,
-    from: sender.username,
-    from_user_id: sender.userId,
-    title: null,
-    message: text,
+    from: m.sender.username,
+    from_user_id: m.sender.userId,
+    title: m.title,
+    message: m.text,
     severity: "info",
     created_at: new Date().toISOString(),
-    ...(metaJson ? { meta: JSON.parse(metaJson) } : {}),
+    ...(m.metaJson ? { meta: JSON.parse(m.metaJson) } : {}),
   });
-  return { ok: true, message: redactMessageRow(row), delivered };
+  return delivered;
+}
+
+/**
+ * Hub 代某人发的一条私信(参与人改了任务的通知,见 requirement-notify.ts):与人发的私信同一张表、同一条推送,
+ * 所以 App 按私信展示(顶部提示 + 人员列表未读 + 与他的会话里能看到),不用新渠道。
+ * 不校验正文 / 附件(调用方生成),也不记 human_dm_sent 审计(这不是他亲手发的)。
+ * 收件人或发信人已不在网络里 → 不发。返回 false = 没发。
+ */
+export function sendNoticeDm(m: DmRow): boolean {
+  if (m.targetUserId === m.sender.userId) return false;
+  if (!getUserNetworkRole(m.sender.userId, m.networkId) || !getUserNetworkRole(m.targetUserId, m.networkId)) return false;
+  insertDmRow(m);
+  pushDmEvent(m);
+  return true;
+}
+
+/**
+ * 把一条还没读的通知私信改写成合并后的正文(同一段时间里的连续改动并成一条)。
+ * 收件人已经读过(acked)或那行没了 → false,调用方另发一条新的。
+ * 只改库、再推一次同一个 message_id:App 按 message_id 去重,不会第二次弹;会话列表下次拉到的是新正文。
+ */
+export function rewriteUnreadNoticeDm(m: DmRow): boolean {
+  const row = db.get<{ acked: number | boolean | null }>("SELECT acked FROM user_inbox WHERE message_id = ?1 AND user_id = ?2", m.messageId, m.targetUserId);
+  if (!row || row.acked) return false;
+  db.run("UPDATE user_inbox SET content = ?1, meta_json = ?2 WHERE message_id = ?3 AND user_id = ?4", [m.text, m.metaJson, m.messageId, m.targetUserId]);
+  pushDmEvent(m);
+  return true;
 }
 
 /** 带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。返回它的索引条目,不属于 → null。 */

package/src/requirement-notify.ts

@@ -0,0 +1,134 @@
+// 参与人改了任务 → 通知相关的人(Vincent 2026-10-01「参与人可以改，但是改了之后需要有个通知」)。
+//
+// 谁触发:操作者是人,且是这张卡的参与人、不是负责人(权限上参与人只能改状态和检查项,见 task-access.ts
+// PARTICIPANT_EDIT_FIELDS;老成员 task_access='all' 的参与人改了也一样通知)。只说状态和检查项的变化,别的字段不进正文。
+// 通知谁:负责人、创建者、其他参与人 —— 只要人类、去重、不含操作者本人。
+// 怎么送:复用人与人私信(human-dm.ts,user_inbox kind=human_dm + /events/users/me 的 desktop_message),
+//   发信人 = 操作者。App 已有的展示:顶部提示 + 人员列表未读 + 与他的私信会话。不新增渠道。
+// 合并:同一 (收件人, 操作者, 卡) 在 COALESCE_WINDOW_MS 内的连续改动并进同一条还没读的私信(改写正文,不再弹)。
+
+import { db, uuidv4 } from "./db.js";
+import { isParticipant } from "./task-access.js";
+import { rewriteUnreadNoticeDm, sendNoticeDm } from "./human-dm.js";
+
+export const COALESCE_WINDOW_MS = 60_000;
+const COLUMN_LABEL: Record<string, string> = { pool: "需求池", doing: "进行中", done: "完成" };
+const MAX_LINES = 20;
+const MAX_ITEM_CHARS = 40;
+
+export type NoticeCard = {
+  requirement_id: string;
+  network_id: string;
+  seq: number | null;
+  title: string;
+  column_name: string;
+  checklist_json: string | null;
+  owner_json: string | null;
+  participants_json: string | null;
+  created_by: string | null;
+  created_by_json: string | null;
+};
+
+type Item = { id: string; text: string; done: boolean };
+const items = (raw: string | null): Item[] => {
+  try {
+    const list = raw ? JSON.parse(raw) : [];
+    return Array.isArray(list) ? list.filter((x) => x && typeof x.id === "string").map((x) => ({ id: x.id, text: String(x.text ?? ""), done: x.done === true })) : [];
+  } catch { return []; }
+};
+const clip = (s: string) => { const c = Array.from(s); return c.length > MAX_ITEM_CHARS ? c.slice(0, MAX_ITEM_CHARS).join("") + "…" : s; };
+const parse = (raw: string | null) => { try { return raw ? JSON.parse(raw) : null; } catch { return null; } };
+const userIdOf = (ref: unknown): string | null => {
+  const r = ref as { kind?: unknown; id?: unknown } | null;
+  return r && r.kind === "user" && typeof r.id === "string" ? r.id : null;
+};
+
+/**
+ * 这次改动里要说的那几件事,按「对象」做键:同一个对象后一次覆盖前一次(先勾再取消 = 只剩「取消勾选」)。
+ * 键:column / ck:<id>。值:一句短话(不带主语和卡名)。
+ */
+export function describeChanges(before: Pick<NoticeCard, "column_name" | "checklist_json">, after: Pick<NoticeCard, "column_name" | "checklist_json">): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  if (before.column_name !== after.column_name) out.push(["column", `改为 ${COLUMN_LABEL[after.column_name] ?? after.column_name}`]);
+  const a = items(before.checklist_json), b = items(after.checklist_json);
+  const was = new Map(a.map((x) => [x.id, x]));
+  const now = new Map(b.map((x) => [x.id, x]));
+  for (const x of b) {
+    const old = was.get(x.id);
+    if (!old) { out.push([`ck:${x.id}`, `添加了检查项「${clip(x.text)}」`]); continue; }
+    if (old.text !== x.text) out.push([`ck:${x.id}`, `把检查项「${clip(old.text)}」改为「${clip(x.text)}」`]);
+    else if (old.done !== x.done) out.push([`ck:${x.id}`, `${x.done ? "勾选了" : "取消勾选了"}检查项「${clip(x.text)}」`]);
+  }
+  for (const x of a) if (!now.has(x.id)) out.push([`ck:${x.id}`, `删除了检查项「${clip(x.text)}」`]);
+  return out;
+}
+
+/** 收件人:负责人、创建者、其他参与人(只要人,去重,去掉操作者)。 */
+export function noticeRecipients(card: NoticeCard, actorUserId: string): string[] {
+  const ids = new Set<string>();
+  const owner = userIdOf(parse(card.owner_json));
+  if (owner) ids.add(owner);
+  const creator = userIdOf(parse(card.created_by_json)) ?? (!card.created_by_json && card.created_by ? card.created_by : null);
+  if (creator) ids.add(creator);
+  const participants = parse(card.participants_json);
+  if (Array.isArray(participants)) for (const p of participants) { const id = userIdOf(p); if (id) ids.add(id); }
+  ids.delete(actorUserId);
+
+  return [...ids];
+}
+
+export function noticeText(actorName: string, title: string, lines: readonly string[]): string {
+  if (lines.length === 1) {
+    const line = lines[0];
+    return line.startsWith("改为 ") ? `${actorName} 把「${title}」${line}` : `${actorName} 在「${title}」${line}`;
+  }
+  const shown = lines.slice(-MAX_LINES);
+  const more = lines.length > shown.length ? `\n…另有 ${lines.length - shown.length} 项` : "";
+  return `${actorName} 更新了「${title}」:\n${shown.map((l) => `· ${l}`).join("\n")}${more}`;
+}
+
+type Pending = { messageId: string; startedAt: number; changes: Map<string, string> };
+const pending = new Map<string, Pending>();
+
+export function __resetRequirementNoticesForTest(): void { pending.clear(); }
+
+/**
+ * 参与人(非负责人)改完一张卡之后调用(事务提交之后)。before / after = 改前改后的行。
+ * 不是参与人、或者状态和检查项都没变 → 什么都不发。返回这次通知到的收件人(测试用)。
+ */
+export function notifyParticipantChange(input: { before: NoticeCard; after: NoticeCard; actorUserId: string; now?: number }): string[] {
+  const { before, after, actorUserId } = input;
+  if (!isParticipant(before, actorUserId)) return [];
+  if (userIdOf(parse(before.owner_json)) === actorUserId) return [];
+
+  const changes = describeChanges(before, after);
+  if (!changes.length) return [];
+  const now = input.now ?? Date.now();
+  // 用户名从库里取:MCP 入口的 auth.username 是空串。
+  const user = db.get<{ username: string; display_name: string | null }>("SELECT username, display_name FROM users WHERE user_id = ?1", actorUserId);
+  if (!user) return [];
+  const actorName = user.display_name?.trim() || user.username;
+  const sender = { userId: actorUserId, username: user.username };
+  const sent: string[] = [];
+  for (const target of noticeRecipients(after, actorUserId)) {
+    const key = `${target}\u0000${actorUserId}\u0000${after.requirement_id}`;
+    const prev = pending.get(key);
+    const live = prev && now - prev.startedAt < COALESCE_WINDOW_MS ? prev : null;
+    const merged = new Map(live?.changes ?? []);
+    for (const [k, line] of changes) { merged.delete(k); merged.set(k, line); }
+    const meta = JSON.stringify({ task_notice: { requirement_id: after.requirement_id, seq: after.seq ?? null, network_id: after.network_id } });
+    const base = { networkId: after.network_id, targetUserId: target, sender, title: "任务更新", metaJson: meta };
+    if (live && rewriteUnreadNoticeDm({ ...base, messageId: live.messageId, text: noticeText(actorName, after.title, [...merged.values()]) })) {
+      live.changes = merged;
+      sent.push(target);
+      continue;
+    }
+    const messageId = `dm_task_${uuidv4()}`;
+    const fresh = new Map(changes);
+    if (!sendNoticeDm({ ...base, messageId, text: noticeText(actorName, after.title, [...fresh.values()]) })) continue;
+    pending.set(key, { messageId, startedAt: now, changes: fresh });
+    sent.push(target);
+  }
+  if (pending.size > 5_000) for (const [k, p] of pending) if (now - p.startedAt >= COALESCE_WINDOW_MS) pending.delete(k);
+  return sent;
+}

package/src/requirement-participant-notify-http.test.ts

@@ -0,0 +1,309 @@
+// 参与人可以改任务的状态和检查项,改了通知相关的人(Vincent 2026-10-01)—— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// 网络 NET(owner = boss)。成员:
+//   owen —— 卡的负责人;cara —— 建卡的人(task_access='all');
+//   pat  —— 参与人,scoped(只看相关任务);pia —— 另一个参与人(all);
+//   sam  —— scoped,与卡无关(看不见)。
+// 正向:pat 改状态 / 勾检查项 / 改检查项列表 → 200;owen、cara、pia 各收到一条私信(发信人 pat),pat 自己没有;
+//       60 s 内连续改动并成一条(未读时改写正文);读过之后再改 → 新的一条;MCP 与 REST 一致。
+// 反向:pat 改标题 / 描述 / 负责人 / 参与人 / 项目 / 优先级 / 日期 / 标签 → 403 task_read_only + field,卡不变、不通知;
+//       负责人自己改不通知;sam 照旧看不见(与不存在的卡逐字节相同)。
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-part-notify-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+process.env.HOST = "127.0.0.1";
+const PW = "PartNotifyPassw0rd!x";
+
+type U = { token: string; id: string; username: string };
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let PROJ = "";
+let db: any;
+let notify: typeof import("./requirement-notify.js");
+let boss: U, owen: U, cara: U, pat: U, pia: U, sam: U;
+
+type R = { status: number; body: any; text: string };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { 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, text };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const payload = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(payload.result.content[0].text);
+}
+const userRef = (id: string) => ({ kind: "user", id });
+
+/** 某张卡发出的通知私信:按收件人分组(只看这张卡的,meta.task_notice.requirement_id)。 */
+function notices(reqId: string): Record<string, Array<{ message_id: string; content: string; sender_user_id: string; acked: number; from_session: string }>> {
+  const rows = db.all(
+    "SELECT message_id, user_id, sender_user_id, from_session, content, acked, meta_json FROM user_inbox WHERE network_id = ?1 AND kind = 'human_dm' ORDER BY created_at, message_id",
+    NET,
+  ) as any[];
+  const out: Record<string, any[]> = {};
+  for (const r of rows) {
+    let meta: any = null;
+    try { meta = JSON.parse(r.meta_json); } catch {}
+    if (meta?.task_notice?.requirement_id !== reqId) continue;
+    (out[r.user_id] ||= []).push({ message_id: r.message_id, content: r.content, sender_user_id: r.sender_user_id, acked: Number(r.acked), from_session: r.from_session });
+  }
+  return out;
+}
+
+async function card(name: string, extra: Record<string, unknown> = {}) {
+  const r = await send(cara.token, "POST", "/api/requirements", {
+    network_id: NET, name, owner: userRef(owen.id), participants: [userRef(pat.id), userRef(pia.id)],
+    checklist: [{ id: "i1", text: "写测试", done: false }, { id: "i2", text: "发版", done: false }], ...extra,
+  });
+  expect(r.status).toBe(201);
+  return r.body.requirement.id as string;
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { addNetworkMember, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const mk = (name: string, display?: string): U => {
+    const r = register(`pn_${name}_${stamp}`, PW, undefined, display);
+    expect(r.ok).toBe(true);
+    return { token: r.token!, id: r.user!.user_id, username: r.user!.username };
+  };
+  const b = register(`pn_boss_${stamp}`, PW);
+  expect(b.ok).toBe(true);
+  boss = { token: b.token!, id: b.user!.user_id, username: b.user!.username };
+  NET = b.network_id!;
+  owen = mk("owen"); cara = mk("cara"); pat = mk("pat", "参与人甲"); pia = mk("pia"); sam = mk("sam");
+  addNetworkMember(NET, owen.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, cara.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, pat.id, "member", boss.id, { taskAccess: "scoped" });
+  addNetworkMember(NET, pia.id, "member", boss.id, { taskAccess: "all" });
+  addNetworkMember(NET, sam.id, "member", boss.id, { taskAccess: "scoped" });
+  notify = await import("./requirement-notify.js");
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  // register() 给每人建了自己的网络:后面的请求一律带 network_id。
+  const p = await send(boss.token, "POST", "/api/requirements/projects", { network_id: NET, name: "pn-proj" });
+  expect(p.status).toBe(201);
+  PROJ = p.body.project.id;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("参与人能改的", () => {
+  test("改状态:200,负责人 / 创建者 / 其他参与人各一条,操作者自己没有", async () => {
+    const id = await card("pn-状态");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" });
+    expect(r.status).toBe(200);
+    expect(r.body.requirement.column).toBe("doing");
+    const n = notices(id);
+    expect(Object.keys(n).sort()).toEqual([owen.id, cara.id, pia.id].sort());
+    for (const uid of [owen.id, cara.id, pia.id]) {
+      expect(n[uid].length).toBe(1);
+      expect(n[uid][0].sender_user_id).toBe(pat.id);
+      expect(n[uid][0].from_session).toBe(pat.username);
+      expect(n[uid][0].content).toBe("参与人甲 把「pn-状态」改为 进行中");
+    }
+    expect(n[pat.id]).toBeUndefined();
+  });
+
+  test("勾检查项(单条接口):200 并通知", async () => {
+    const id = await card("pn-勾选");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true });
+    expect(r.status).toBe(200);
+    expect(r.body.requirement.checklist.find((x: any) => x.id === "i1").done).toBe(true);
+    expect(notices(id)[owen.id].map(x => x.content)).toEqual(["参与人甲 在「pn-勾选」勾选了检查项「写测试」"]);
+  });
+
+  test("整表改检查项(增 / 删 / 改字)+ 状态:一次 PATCH 一条通知,逐项列出", async () => {
+    const id = await card("pn-整表");
+    const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, {
+      column: "done", checklist: [{ id: "i1", text: "写更多测试", done: false }, { id: "i3", text: "回归", done: false }],
+    });
+    expect(r.status).toBe(200);
+    const n = notices(id)[cara.id];
+    expect(n.length).toBe(1);
+    expect(n[0].content).toBe("参与人甲 更新了「pn-整表」:\n· 改为 完成\n· 把检查项「写测试」改为「写更多测试」\n· 添加了检查项「回归」\n· 删除了检查项「发版」");
+  });
+
+  test("60 s 内连续勾选并成一条(未读时改写正文);同一项先勾再取消只留最后一次", async () => {
+    const id = await card("pn-合并");
+    for (const [item, done] of [["i1", true], ["i2", true], ["i1", false]] as const) {
+      expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/${item}?network_id=${NET}`, { done })).status).toBe(200);
+    }
+    const n = notices(id);
+    for (const uid of [owen.id, cara.id, pia.id]) {
+      expect(n[uid].length).toBe(1);
+      expect(n[uid][0].content).toBe("参与人甲 更新了「pn-合并」:\n· 勾选了检查项「发版」\n· 取消勾选了检查项「写测试」");
+    }
+  });
+
+  test("收件人读过之后再改 → 另发一条;别人那条仍在合并", async () => {
+    const id = await card("pn-已读");
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
+    db.run("UPDATE user_inbox SET acked = 1 WHERE user_id = ?1 AND message_id = ?2", [owen.id, notices(id)[owen.id][0].message_id]);
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}/checklist/i2?network_id=${NET}`, { done: true })).status).toBe(200);
+    const n = notices(id);
+    expect(n[owen.id].length).toBe(2);
+    expect(n[owen.id][1].content).toBe("参与人甲 在「pn-已读」勾选了检查项「发版」");
+    expect(n[cara.id].length).toBe(1);
+  });
+
+  test("过了合并窗口 → 另发一条", async () => {
+    const id = await card("pn-窗口");
+    const row = (col: string, ck: boolean) => ({
+      requirement_id: id, network_id: NET, seq: null, title: "pn-窗口", column_name: col,
+      checklist_json: JSON.stringify([{ id: "i1", text: "写测试", done: ck }]),
+      owner_json: JSON.stringify(userRef(owen.id)), participants_json: JSON.stringify([userRef(pat.id)]),
+      created_by: null, created_by_json: JSON.stringify(userRef(cara.id)),
+    });
+    const t0 = Date.now();
+    expect(notify.notifyParticipantChange({ before: row("pool", false), after: row("pool", true), actorUserId: pat.id, now: t0 }).sort()).toEqual([owen.id, cara.id].sort());
+    notify.notifyParticipantChange({ before: row("pool", true), after: row("doing", true), actorUserId: pat.id, now: t0 + notify.COALESCE_WINDOW_MS - 1 });
+    expect(notices(id)[owen.id].length).toBe(1);
+    notify.notifyParticipantChange({ before: row("doing", true), after: row("done", true), actorUserId: pat.id, now: t0 + notify.COALESCE_WINDOW_MS + 1 });
+    expect(notices(id)[owen.id].length).toBe(2);
+  });
+
+  test("推送:收件人的用户流收到 desktop_message(kind=human_dm,发信人 = 参与人)", async () => {
+    const id = await card("pn-推送");
+    const ctrl = new AbortController();
+    const res = await fetch(`${BASE}/events/users/me?network_id=${NET}`, { headers: { Authorization: `Bearer ${owen.token}` }, signal: ctrl.signal });
+    expect(res.status).toBe(200);
+    const events: any[] = [];
+    const reader = res.body!.getReader();
+    const dec = new TextDecoder();
+    let buf = "";
+    void (async () => {
+      try {
+        for (;;) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buf += dec.decode(value);
+          let i: number;
+          while ((i = buf.indexOf("\n\n")) >= 0) {
+            const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+            for (const line of frame.split("\n")) if (line.startsWith("data: ")) { try { events.push(JSON.parse(line.slice(6))); } catch {} }
+          }
+        }
+      } catch {}
+    })();
+    const until = async (cond: () => boolean) => { for (let k = 0; k < 150 && !cond(); k++) await new Promise(r => setTimeout(r, 20)); };
+    await until(() => events.some(e => e.type === "connected"));
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    await until(() => events.some(e => e.type === "desktop_message"));
+    ctrl.abort();
+    const ev = events.find(e => e.type === "desktop_message");
+    expect(ev).toMatchObject({ kind: "human_dm", from: pat.username, from_user_id: pat.id, title: "任务更新", message: "参与人甲 把「pn-推送」改为 进行中" });
+    expect(ev.meta.task_notice.requirement_id).toBe(id);
+  });
+
+  test("MCP 与 REST 一致:requirements_update 改状态能过并通知,改标题被拒", async () => {
+    const id = await card("pn-mcp");
+    const ok = await mcp(pat.token, "requirements_update", { id, network_id: NET, column: "doing" });
+    expect(ok.ok).toBe(true);
+    expect(notices(id)[owen.id][0].content).toBe("参与人甲 把「pn-mcp」改为 进行中");
+    expect(notices(id)[owen.id][0].from_session).toBe(pat.username);
+    const no = await mcp(pat.token, "requirements_update", { id, network_id: NET, name: "改名" });
+    expect(no).toMatchObject({ ok: false, error: "task_read_only", field: "name", status: 403 });
+    const tog = await mcp(pat.token, "requirements_checklist_toggle", { id, network_id: NET, item_id: "i2", done: true });
+    expect(tog.ok).toBe(true);
+  });
+
+  test("viewer_can:参与人带 edit_fields;负责人不带", async () => {
+    const id = await card("pn-权限");
+    const mine = await send(pat.token, "GET", `/api/requirements/${id}?network_id=${NET}`);
+    expect(mine.body.requirement.viewer_can).toEqual({ edit: false, delete: false, edit_fields: ["column", "checklist"] });
+  });
+});
+
+describe("参与人不能改的", () => {
+  test("标题 / 描述 / 负责人 / 负责 Agent / 参与人 / 项目 / 优先级 / 日期 / 标签:403 task_read_only + field;卡不变、不通知", async () => {
+    const id = await card("pn-拒绝");
+    const before = (await send(cara.token, "GET", `/api/requirements/${id}?network_id=${NET}`)).body.requirement;
+    const cases: Array<[string, unknown]> = [
+      ["name", "改名"], ["description", "x"], ["owner", userRef(pat.id)], ["agent_owner", null], ["participants", [userRef(pat.id)]],
+      ["project_id", PROJ], ["priority", "high"], ["due", "2026-12-31"], ["start", "2026-12-01"], ["tags", ["t"]], ["archived", true], ["parent_id", null],
+    ];
+    for (const [field, value] of cases) {
+      const r = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { [field]: value });
+      expect(r.status).toBe(403);
+      expect(r.body.ok).toBe(false);
+      expect(r.body.error).toBe("task_read_only");
+      expect(r.body.field).toBe(field);
+      expect(typeof r.body.message).toBe("string");
+    }
+    // 混着能改的字段一起发:整条拒绝,状态也不动。
+    const mixed = await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing", name: "改名" });
+    expect(mixed.status).toBe(403);
+    expect(mixed.body.field).toBe("name");
+    const after = (await send(cara.token, "GET", `/api/requirements/${id}?network_id=${NET}`)).body.requirement;
+    expect(after).toEqual(before);
+    expect(notices(id)).toEqual({});
+  });
+
+  test("负责人 / 创建者自己改:不通知;删除仍不行", async () => {
+    const id = await card("pn-负责人");
+    expect((await send(owen.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect((await send(cara.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
+    expect(notices(id)).toEqual({});
+    expect((await send(pat.token, "DELETE", `/api/requirements/${id}?network_id=${NET}`)).status).toBe(403);
+  });
+
+  test("负责人同时是参与人:改了也不通知", async () => {
+    const id = await card("pn-兼任", { owner: userRef(pat.id), participants: [userRef(pat.id), userRef(pia.id)] });
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect(notices(id)).toEqual({});
+  });
+
+  test("只看相关任务的无关成员:看不见、改不了(与不存在的卡逐字节相同),也收不到通知", async () => {
+    const id = await card("pn-无关");
+    const list = await send(sam.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect((list.body.requirements as any[]).some(x => x.id === id)).toBe(false);
+    const hidden = await send(sam.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" });
+    const ghost = await send(sam.token, "PATCH", `/api/requirements/req_does_not_exist?network_id=${NET}`, { column: "doing" });
+    expect(hidden.status).toBe(404);
+    expect(hidden.text).toBe(ghost.text);
+    const hiddenCk = await send(sam.token, "PATCH", `/api/requirements/${id}/checklist/i1?network_id=${NET}`, { done: true });
+    expect(hiddenCk.status).toBe(404);
+    expect((await send(pat.token, "PATCH", `/api/requirements/${id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
+    expect(notices(id)[sam.id]).toBeUndefined();
+  });
+});
+
+describe("收件人(纯函数)", () => {
+  test("只要人、去重、去掉操作者;旧卡没有 created_by_json 时用 created_by", () => {
+    const base = {
+      requirement_id: "r", network_id: NET, seq: 1, title: "t", column_name: "pool", checklist_json: null,
+      owner_json: JSON.stringify(userRef("u-owner")),
+      participants_json: JSON.stringify([userRef("u-actor"), userRef("u-owner"), { kind: "node", id: "n-1" }, userRef("u-other")]),
+      created_by: null, created_by_json: JSON.stringify({ kind: "node", id: "n-2" }),
+    };
+    expect(notify.noticeRecipients(base, "u-actor").sort()).toEqual(["u-other", "u-owner"]);
+    expect(notify.noticeRecipients({ ...base, created_by_json: null, created_by: "u-legacy" }, "u-actor").sort()).toEqual(["u-legacy", "u-other", "u-owner"]);
+  });
+});

package/src/requirements.ts

@@ -9,9 +9,10 @@ import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-s
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
 import {
-  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
-  isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
+  isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
+import { notifyParticipantChange } from "./requirement-notify.js";
 import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
@@ -87,12 +88,31 @@ function taskCaller(ctx: RequirementsRequestContext): TaskCaller {
   if (!ctx.auth || ctx.isNodeToken || ctx.isAdmin) return null;
   return { userId: ctx.auth.userId };
 }
-/** 看得见但没权限写:403,并按 (用户, 卡) 每小时最多记一条审计。 */
-function taskDenied(ctx: RequirementsRequestContext, row: Row, error: "task_read_only" | "task_delete_denied"): Response {
+/**
+ * 看得见但没权限写:403,并按 (用户, 卡) 每小时最多记一条审计。
+ * field:参与人改了参与人不能改的字段 —— 错误码不变(旧 App 照旧认 task_read_only),多带 field + 一句中文 message。
+ */
+function taskDenied(ctx: RequirementsRequestContext, row: Row, error: "task_read_only" | "task_delete_denied", field?: string): Response {
   if (ctx.auth && shouldAuditDenied(ctx.auth.userId, row.requirement_id)) {
-    logAudit(ctx.auth.userId, ctx.auth.username || null, "task_access_denied", "requirement", row.requirement_id, JSON.stringify({ error }), undefined, row.network_id);
+    logAudit(ctx.auth.userId, ctx.auth.username || null, "task_access_denied", "requirement", row.requirement_id, JSON.stringify(field ? { error, field } : { error }), undefined, row.network_id);
+  }
+  if (!field) return jsonError(error, 403);
+  return Response.json({ ok: false, error, field, message: `参与人只能修改状态和检查项,不能修改「${FIELD_LABEL[field] ?? field}」` }, { status: 403 });
+}
+const FIELD_LABEL: Record<string, string> = {
+  name: "标题", description: "描述", owner: "负责人", agent_owner: "负责 Agent", participants: "参与人", project_id: "项目",
+  priority: "优先级", due: "预计完成", start: "开始时间", tags: "标签", issues: "关联 issue", assignee: "执行人",
+  external_ref: "外部引用", external_url: "外部链接", archived: "归档", parent_id: "父任务",
+};
+/** 参与人改完(事务提交后)发通知;操作者不是参与人 / 状态和检查项没变 → 不发。只对人(用户令牌)。 */
+function notifyIfParticipant(ctx: RequirementsRequestContext, before: Row, after: Row): void {
+  if (!ctx.auth || ctx.isNodeToken) return;
+  try {
+    notifyParticipantChange({ before, after, actorUserId: ctx.auth.userId });
+  } catch (e) {
+    // 通知失败不影响这次改动(已经提交)。
+    console.error(`[requirements] participant notice failed: ${(e as Error).message}`);
   }
-  return jsonError(error, 403);
 }
 /** 父卡对调用者不可见 = 与不存在同一个错误(不给 scoped 成员留卡片存在性探测)。 */
 function parentHidden(ctx: RequirementsRequestContext, parentId: string): boolean {
@@ -785,7 +805,12 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
   const caller = taskCaller(ctx);
-  if (!canEditTask(caller, row)) return taskDenied(ctx, row, "task_read_only");
+  if (!canEditTask(caller, row)) {
+    // 参与人:只放状态和检查项;别的字段点名拒绝。不是参与人 → 与今天一样。
+    if (!canParticipantEditTask(caller, row)) return taskDenied(ctx, row, "task_read_only");
+    const other = PATCH_FIELDS.find(k => has(k) && !PARTICIPANT_EDIT_FIELDS.includes(k));
+    if (other) return taskDenied(ctx, row, "task_read_only", other);
+  }
   // scoped 成员不能写 external_ref:唯一索引冲突会泄露别的卡用了这个 ref。
   if (has("external_ref") && caller && isTaskScoped(caller.userId, row.network_id)) return jsonError("external_ref_not_allowed", 403);
   if (has("column") && !COLUMNS.has(String(body.column))) return jsonError("invalid_column", 400);
@@ -887,6 +912,7 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     recordRequirementEvents(db, after, actor, diffRequirement(row, after), updatedAt);
     return after;
   });
+  notifyIfParticipant(ctx, row, updated);
   return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
 }
 
@@ -1357,7 +1383,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
-    if (!canEditTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_read_only");
+    if (!canEditTask(taskCaller(ctx), row) && !canParticipantEditTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_read_only");
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
     const itemId = decodeURIComponent(itemMatch[2]);
@@ -1373,6 +1399,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
       if (was !== item.done) recordRequirementEvents(db, row, actor, [{ kind: "changed", field: "checklist_item", old: { ...item, done: was }, new: { ...item } }], at);
       return db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
     });
+    notifyIfParticipant(ctx, row, updated);
     return Response.json({ ok: true, requirement: toPublicFor(ctx, updated) });
   }
 

package/src/task-access-http.test.ts

@@ -192,7 +192,8 @@ describe("可见性", () => {
     const r = await get(alice.token, `/api/requirements?network_id=${NET}`);
     const by = (n: string) => (r.body.requirements as any[]).find(x => x.name === n)?.viewer_can;
     expect(by("ta-own")).toEqual({ edit: true, delete: true });
-    expect(by("ta-part")).toEqual({ edit: false, delete: false });
+    // 参与人:整卡只读,但状态和检查项能改(edit_fields;旧 App 不认这个键,照旧画只读)。
+    expect(by("ta-part")).toEqual({ edit: false, delete: false, edit_fields: ["column", "checklist"] });
     expect(by("ta-p1")).toEqual({ edit: false, delete: false });
     expect(by("ta-p2")).toEqual({ edit: true, delete: false });
     expect((await get(vic.token, `/api/requirements/${C["ta-p3"].id}?network_id=${NET}`)).body.requirement.viewer_can).toEqual({ edit: false, delete: false });
@@ -235,25 +236,28 @@ describe("可见性", () => {
 });
 
 describe("写入", () => {
-  test("能改:负责的、可改项目里的;只读:参与的、只看项目里的(403 task_read_only);看不见的与不存在的同一个 404", async () => {
+  test("能改:负责的、可改项目里的;只读:只看项目里的(403 task_read_only);参与的只能改状态 / 检查项;看不见的与不存在的同一个 404", async () => {
     expect((await send(alice.token, "PATCH", `/api/requirements/${C["ta-own"].id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
     expect((await send(alice.token, "PATCH", `/api/requirements/${C["ta-p2"].id}?network_id=${NET}`, { column: "doing" })).status).toBe(200);
-    for (const n of ["ta-part", "ta-p1"]) {
-      const r = await send(alice.token, "PATCH", `/api/requirements/${C[n].id}?network_id=${NET}`, { column: "doing" });
-      expect(r.status).toBe(403);
-      expect(r.body.error).toBe("task_read_only");
-    }
+    const p1 = await send(alice.token, "PATCH", `/api/requirements/${C["ta-p1"].id}?network_id=${NET}`, { column: "doing" });
+    expect(p1.status).toBe(403);
+    expect(p1.body).toEqual({ ok: false, error: "task_read_only" });
+    const part = await send(alice.token, "PATCH", `/api/requirements/${C["ta-part"].id}?network_id=${NET}`, { name: "renamed" });
+    expect(part.status).toBe(403);
+    expect(part.body.error).toBe("task_read_only");
+    expect(part.body.field).toBe("name");
     const hidden = await send(alice.token, "PATCH", `/api/requirements/${C["ta-other"].id}?network_id=${NET}`, { column: "doing" });
     const ghost = await send(alice.token, "PATCH", `/api/requirements/req_does_not_exist?network_id=${NET}`, { column: "doing" });
     expect(hidden.status).toBe(404);
     expect(hidden.text).toBe(ghost.text);
   });
 
-  test("勾子任务:负责的能勾,参与的 403,看不见的 404", async () => {
+  test("勾子任务:负责的能勾,参与的能勾,只看项目的 403,看不见的 404", async () => {
     expect((await send(alice.token, "PATCH", `/api/requirements/${C["ta-own"].id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
-    const part = await send(alice.token, "PATCH", `/api/requirements/${C["ta-part"].id}/checklist/i1?network_id=${NET}`, { done: true });
-    expect(part.status).toBe(403);
-    expect(part.body.error).toBe("task_read_only");
+    expect((await send(alice.token, "PATCH", `/api/requirements/${C["ta-part"].id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(200);
+    const ro = await send(alice.token, "PATCH", `/api/requirements/${C["ta-p1"].id}/checklist/i1?network_id=${NET}`, { done: true });
+    expect(ro.status).toBe(403);
+    expect(ro.body.error).toBe("task_read_only");
     expect((await send(alice.token, "PATCH", `/api/requirements/${C["ta-other"].id}/checklist/i1?network_id=${NET}`, { done: true })).status).toBe(404);
   });
 

package/src/task-access.ts

@@ -133,6 +133,26 @@ export function canEditTask(caller: TaskCaller, row: CardRow): boolean {
   return projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true;
 }
 
+/**
+ * 参与人能改的字段(Vincent 2026-10-01「参与人可以改，但是改了之后需要有个通知」):状态(列)和检查项。
+ * 只对 canEditTask 为 false 的 scoped 参与人生效;标题 / 描述 / 负责人 / 参与人 / 项目 / 优先级 / 日期 / 标签等仍只给
+ * 负责人 / 创建者 / 可改项目授权。
+ */
+export const PARTICIPANT_EDIT_FIELDS: readonly string[] = ["column", "checklist"];
+
+/** 这个调用者是不是「只能以参与人身份改」这张卡(canEditTask 为 false、但他是卡上的参与人)。viewer 不算。 */
+export function canParticipantEditTask(caller: TaskCaller, row: CardRow): boolean {
+  if (!caller) return false;
+  const m = memberRow(caller.userId, row.network_id);
+  if (!scopedRow(m) || m?.member_role === "viewer") return false;
+  return participates(row, caller.userId);
+}
+
+/** 卡上有没有这个用户当参与人(不看权限模式;通知用)。 */
+export function isParticipant(row: Pick<CardRow, "participants_json">, userId: string): boolean {
+  return refIs(row.participants_json, userId);
+}
+
 /** 能删这张卡吗。scoped 成员只能删负责人是自己或自己建的。 */
 export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
   if (!caller) return true;
@@ -146,7 +166,8 @@ export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
  * 给客户端画「只读 / 不能删」用的每卡权限。只对 scoped 调用者返回(其余 null = 与今天一样全能)。
  * 一个请求里按网络缓存成员行与项目授权,列表 500 张卡不会变成 500 × 3 次查询。
  */
-export type TaskPermissions = { edit: boolean; delete: boolean };
+// edit_fields:只在 edit=false、但调用者是这张卡的参与人时出现 —— 他能改的就是这几个字段(旧 App 不认这个键,照旧画只读)。
+export type TaskPermissions = { edit: boolean; delete: boolean; edit_fields?: readonly string[] };
 export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => TaskPermissions | null {
   if (!caller) return () => null;
   const cache = new Map<string, { scoped: boolean; viewer: boolean; grants: Map<string, boolean> }>();
@@ -165,7 +186,9 @@ export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => T
     if (!c.scoped) return null;
     if (c.viewer) return { edit: false, delete: false };
     const mine = ownsCard(row, caller.userId) || createdCard(row, caller.userId);
-    return { edit: mine || (row.project_id ? c.grants.get(row.project_id) === true : false), delete: mine };
+    const edit = mine || (row.project_id ? c.grants.get(row.project_id) === true : false);
+    if (!edit && participates(row, caller.userId)) return { edit, delete: mine, edit_fields: PARTICIPANT_EDIT_FIELDS };
+    return { edit, delete: mine };
   };
 }