termdock 1.4.242 → 1.4.244

package/dist/server/agent/collaborationCli.js

@@ -2,76 +2,85 @@ import fs from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { COLLAB_LIMITS, CollaborationError, canonicalShortId } from './collaborationProtocol.js';
 export const COLLAB_HELP = `td collab — durable messages; no agent-specific hooks required
-  (except --session, wherever an id is taken, the short id shown in deliveries and --text
-   output works too; a shorter unique prefix down to 4 characters also resolves —
-   an ambiguous prefix is refused, so use more characters or the full id)
+  我想…
+    回复刚收到的消息 → 用投递「来自」行里的 id: td collab reply <id> "内容" --text
+    看有谁、我在哪些组 → td collab status --text
+    主动找人 → td collab send <成员id> "消息内容" --text
+    看对方在干什么 → td collab capture <成员id> --text（只读巡屏，不发送按键）
+    取大消息全文 → td collab message get <id> --text
+    改我的显示名 → td collab rename <我的id> <新名字>
+    设角色定位 → td collab role set <组id> <成员id> <定位>
+    查/改群规 → td collab rules get|set <组id>
+    消息发出去没动静 → td collab message get <id>（投递状态与重试原因）
+  Output: --json (default) | --jsonl | --text (human-readable lines; prefer it
+    when reading results yourself. Commands without a dedicated --text form
+    still print JSON)
   Source identity (all collab commands): --session <full-Termdock-session-id>
     or TERMDOCK_COLLAB_SESSION_ID. CLI option wins; explicit identity bypasses
     environment/tmux detection. Use your own full member ID from status output,
     not a tmux name, backend ID or Claude session ID. Unknown IDs are refused.
-    This selects a source in the trusted local-user context; it is not proof
-    of identity or isolation between processes running as the same OS user.
     Example: td collab --session <your-full-session-id> status
-    Rebind identity and location separately:
-      td collab --session <your-full-session-id> rebind --pane %3
-    Without explicit identity, the backend environment / tmux pane is detected.
+  Ids: wherever an id is taken, the short id shown in deliveries and --text
+    output works too; a shorter unique prefix down to 4 characters also
+    resolves — an ambiguous prefix is refused, so use more characters.
   Scheduled self-reminders: td automation create --name 'Review progress' --every 30 --self --prompt 'Review group progress and continue'
   Scheduling help: td automation --help
-  status | capabilities
-  transport list (server-owned remote session directory)
-  transport invite --origin https://this-service:9834
-    Create a 10-minute invitation granting collaboration directory/group access.
-    Transfer its JSON privately to the other machine; no browser is required.
-  transport accept --origin https://this-service:9834 --file invitation.json
-    Pair both services once; subsequent discovery, groups and delivery are automatic.
-  group save --file group.json
-    JSON: {name, sessionIds, id?, expectedUpdatedAt?}; same service API as the UI.
-  transport info
-    Print this service's public identity and CA fingerprint (no private keys).
-  transport register <group-id> --file <nodes.json>
-    One-time server peer registration; nodes.json is an array of public
-    {serviceId, origin, caFingerprint256?} entries, including this service.
-    Obtain pins from each administrator's transport info over a trusted channel.
-    Registered servers deliver without an open browser or Desktop client.
-  rebind [--pane %3] (explicitly bind this peer to its current Agent; resumes queued delivery)
-  send <session-id> <message> | reply <message-id> <message> | handoff <session-id> <message>
-    (send fan-out: comma-separated same-group ids, e.g. send a,b "任务"; every
-    recipient sees it as 群发 with the sibling list; waiting options apply to
-    single-recipient sends only)
-    --group <id> --thread <id> --idempotency-key <key>
-    --file <path> | --stdin (instead of inline body; -- ends option parsing)
-    --wait-until queued|delivered --timeout 30s
-    --expect-reply ack|result|any
-    --response-kind ack|progress|result --metadata '<JSON object>'
-    --expires-at <ISO timestamp or epoch milliseconds>
-    reply: --task-envelope '<JSON: task_id,status,progress?,evidence?,blocker?>'
+
+── 常用 ──
+  status (who is in my groups, their names, roles, observed activity)
+  send <session-id> <message> (deliver to one member; comma-separated same-group
+    ids fan out, e.g. send a,b "任务" — recipients see it as 群发)
+  reply <message-id> <message> (answer a message you received; one-to-one)
+  handoff <session-id> <message> (like send, framed as a task hand-off)
+    shared options: --group <id> --thread <id> --idempotency-key <key>
+      --file <path> | --stdin (instead of inline body; -- ends option parsing)
+      --wait-until queued|delivered --timeout 30s --expect-reply ack|result|any
+      --response-kind ack|progress|result --metadata '<JSON object>'
+      --expires-at <ISO timestamp or epoch milliseconds>
+    reply also: --task-envelope '<JSON: task_id,status,progress?,evidence?,blocker?>'
       (status reporting happens only via reply; send/handoff dispatch carries no task state)
-  message get <message-id> [--receipt-only] [--raw]
+  message get <id> [--receipt-only] [--raw] [--no-rules] [--text]
+    (delivery status, retries and the full body of large messages)
   message confirm-shell <message-id> (sender confirms delivery into a shell; continues the same message)
   message watch <message-id> [--wait-until delivered] [--timeout 30s]
-  inbox [--since <ISO or epoch-ms>] [--after-id <id>]
-    [--cursor <token>] [--consumer <name>] [--limit 1..200]
-    [--from <id>] [--group <id>] [--thread <id>] [--kind <kind>]
-    [--response-kind ack|progress|result] [--follow] [--timeout 30s]
-  cursor commit <token> --consumer <name> (commit after processing the page)
+  capture <session-id> [--lines 1..10000] [--raw] [--text]
+    (查看伙伴正在做什么：读取同组、本机 tmux 成员的当前屏幕，不发送按键、不打断对方。
+    不是完整聊天历史或完成凭证；用 status --text 查成员 ID；不支持远端成员，远端请 send 询问进展。)
+── 群与规则 ──
+  group save --file group.json
+    JSON: {name, sessionIds, id?, expectedUpdatedAt?}; same service API as the UI.
   add|remove <group-id> <session-id>
   spawn <group-id> <agent-slug> [--name <name>] [--cwd <path>] [--task <text>]
-  rules get <group-id> [--text]
-  rules set <group-id> <text> | --file <path> | --stdin [--if-version <version>]
-  rules clear <group-id> [--if-version <version>]
-    Shared group guidance, up to 8192 UTF-8 bytes; message envelopes retain its version.
-  traits list|set|unset (alias of role; long-lived capabilities/preferences)
-  role list <group-id>
-  role set <group-id> <session-id> <role…> (trailing words join as the role)
-  role unset <group-id> <session-id>
-    (roles are shared within the group; members set each other's, your own
-    rides the delivery shell header)
+  rules get <group-id> [--text] | rules set <group-id> <text> | --file <path> | --stdin [--if-version <version>]
+    | rules clear <group-id> [--if-version <version>]
+    (shared group guidance, up to 8192 UTF-8 bytes; message envelopes retain
+    its version. if-version rejects concurrent overwrites with GROUP_CHANGED)
   rename <session-id> <name…> (rename a member of any shared group;
     trailing words join as the new name; roster and shells show it at once)
-  capture <session-id> [--lines 1..10000] [--raw] [--text]
-    (查看伙伴正在做什么：读取同组、本机 tmux 成员的当前屏幕，不发送按键、不打断对方。
-    需要了解进展、排查卡住或决定是否跟进时先 capture；不是完整聊天历史或完成凭证。
-    用 status --text 查成员 ID；不支持远端成员，远端请 send 询问进展。)
+  role list <group-id> | role set <group-id> <session-id> <role…> | role unset <group-id> <session-id>
+    (roles are shared within the group; members set each other's, your own
+    rides the delivery shell header. traits is an alias of role)
+── 收件箱与游标 ──
+  inbox [--since <ISO or epoch-ms>] [--after-id <id>] [--cursor <token>]
+    [--consumer <name>] [--limit 1..200] [--from <id>] [--group <id>]
+    [--thread <id>] [--kind <kind>] [--response-kind ack|progress|result]
+    [--follow] [--timeout 30s]
+    (defaults to newest 50; cursor/consumer mode reads oldest unseen first.
+    Reading never advances a consumer. Read receipts are not supported)
+  cursor commit <token> --consumer <name> (commit after processing the page)
+── 传输与运维 ──
+  transport list (server-owned remote session directory) | transport info (this service's public identity and CA fingerprint, no private keys)
+  transport invite --origin https://this-service:9834
+    (create a 10-minute invitation granting collaboration directory/group
+    access; transfer its JSON privately — no browser required)
+  transport accept --origin https://this-service:9834 --file invitation.json
+    (pair both services once; discovery, groups and delivery become automatic)
+  transport register <group-id> --file <nodes.json>
+    (one-time server peer registration; nodes.json is an array of public
+    {serviceId, origin, caFingerprint256?} entries, including this service.
+    Obtain pins from each administrator's transport info over a trusted
+    channel. Registered servers deliver without an open browser or Desktop client)
+  rebind [--pane %3] (explicitly bind this peer to its current Agent; resumes queued delivery)
   drive <session-id> approve|enter|escape|space|left|right|up|down|capture
   drive <session-id> run <command…>
     (drive the terminal of a member session you share a group with — terminal
@@ -79,30 +88,30 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
     dialog and refuses unless one is actually showing; named keys inject one
     key; capture reads the current screen back; run submits one line and
     returns the screen. Works on plain shell members too (no agent needed) for
-    run/capture; key actions (approve/enter/…) require an agent pane, and are
-    refused while the user has the pane scrolled into copy-mode. Cannot target
-    your own session. Treat every drive as strong control: the member's shell
-    executes what you send.)
+    run/capture; key actions require an agent pane and are refused while the
+    user has the pane scrolled into copy-mode. Cannot target your own session.
+    Treat every drive as strong control: the member's shell executes what you send)
   cleanup <session-id>… 移除协作会话并终止其 tmux/进程（仅限与你同组的会话；
     不能清理当前会话自身，也不能通过清理解散你所在的组）
     风险操作：默认只打印清理计划并拒绝执行（exit 1）——这是不可恢复的删除。
     必须先向用户（人类）说明将清理的会话与影响并获得其明确同意，
     才能以 --confirm 重跑执行；每次执行都需要当场的人类授权。
-  --json (default) | --jsonl | --text
+  help (this text; when a managed session is available it also lists the
+    groups you are in with every member's id, name and role)
 Exit codes: 0 requested condition met; 1 invalid request/network error;
 cleanup without --confirm prints the plan and refuses (also 1);
 2 wait timeout (message may still deliver); 3 failed/expired.
 Message limit: ${COLLAB_LIMITS.message_bytes} UTF-8 bytes; metadata: ${COLLAB_LIMITS.metadata_bytes} bytes.
 Idempotency retention: 7 days. Terminal delivery, ACK and result never imply each other.
-Inbox defaults to newest 50; cursor/consumer mode reads oldest unseen first.
-Reading never advances a consumer. Read receipts are not supported.`;
+Delivery semantics: delivered = written to the terminal — never proof of
+reading or task completion; a timeout stops waiting, it does not cancel delivery.`;
 /** One roster row: prefer the member's human name, keep the full session id
  * reachable for role set/unset targeting, mark unset members explicitly. */
 function roleLine(member, role) {
     const label = member.name ? `${member.name} (${member.sessionId})` : member.sessionId;
     return role ? `- ${label}：${role}` : `- ${label}（未设置）`;
 }
-const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'follow', 'stdin', 'receipt-only', 'confirm', 'raw', 'help']);
+const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'follow', 'stdin', 'receipt-only', 'confirm', 'raw', 'help', 'no-rules']);
 const VALUE_OPTIONS = new Set(['session', 'group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task', 'pane', 'lines', 'if-version', 'origin']);
 export function parseCollaborationCommand(argv) {
     const options = {};
@@ -271,7 +280,7 @@ export function parseCollaborationCommand(argv) {
         handoff: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at'],
         reply: ['idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
         inbox: ['raw', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind', 'follow', 'timeout'],
-        message: ['raw', 'receipt-only', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
+        message: ['raw', 'receipt-only', 'no-rules', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
         add: [], remove: [], spawn: ['name', 'cwd', 'task'], role: [], rename: [], cleanup: ['confirm'], drive: ['lines', 'raw'],
     };
     for (const option of byAction[action])
@@ -329,8 +338,10 @@ export async function executeCollaborationCommand(command, context, io) {
                     io.write(message.content);
                 }
             else if (value.message) {
-                if (value.message.instructions?.text)
-                    io.write(`协作约定（版本 ${value.message.instructions.version}）：\n${value.message.instructions.text}`);
+                // One line instead of the full rules text — the CLI is stateless so it
+                // cannot diff versions across calls; --no-rules silences it entirely.
+                if (!o['no-rules'] && value.message.instructions?.text)
+                    io.write(`消息附群规版本 ${value.message.instructions.version}；td collab rules get <组id> --text 查看全文`);
                 io.write(`[${value.status}] ${canonicalShortId(String(value.message_id ?? ''))}\n${value.message.content}`);
             }
             else if (value.message_id) {
@@ -340,8 +351,12 @@ export async function executeCollaborationCommand(command, context, io) {
                 if (value.code === 'WAIT_TIMEOUT' && value.stage_reached && value.expect_reply) {
                     io.write(`\n投递已完成；等待${value.expect_reply === 'result' ? '结果' : '回复'}超时（expect-reply=${value.expect_reply}）`);
                 }
+                // The screen rides the receipt as the delivery credential: the service
+                // observes terminal writes, never reading, so this capture is the only
+                // evidence the message actually landed. Kept visible in --text, but
+                // fenced and labelled so it cannot be mistaken for delivery state.
                 if (value.snapshot)
-                    io.write(`\n${value.snapshot}`);
+                    io.write(`\n对方终端当前屏幕（凭证：确认你的消息已写入；不代表已读或任务完成）：\n───\n${value.snapshot}\n───`);
             }
             else
                 io.write(JSON.stringify(value, null, 2));
@@ -382,7 +397,12 @@ export async function executeCollaborationCommand(command, context, io) {
         if (command.action === 'group') {
             if (fs.statSync(String(o.file)).size > 64 * 1024)
                 throw new Error('Group input exceeds 64 KiB');
-            output(await request('POST', '/group', { input: JSON.parse(fs.readFileSync(String(o.file), 'utf8')) }));
+            const saved = await request('POST', '/group', { input: JSON.parse(fs.readFileSync(String(o.file), 'utf8')) });
+            if (o.text && saved.group) {
+                io.write(`已保存协作组「${saved.group.name ?? saved.group.id ?? ''}」（${saved.group.sessionIds?.length ?? 0} 个成员，updatedAt=${saved.group.updatedAt ?? '未知'}）`);
+            }
+            else
+                output(saved);
             return 0;
         }
         if (command.action === 'transport') {
@@ -420,6 +440,7 @@ export async function executeCollaborationCommand(command, context, io) {
                         for (const id of group.sessionIds)
                             io.write(roleLine({ sessionId: id, name: members.get(id) ?? null }, group.roles?.[id]));
                     }
+                    io.write('给成员发消息: td collab send <成员id> "消息内容" --text（成员 id 见上表）');
                 }
             }
             catch { /* help stays available without a server or session */ }
@@ -427,31 +448,41 @@ export async function executeCollaborationCommand(command, context, io) {
         }
         if (command.action === 'capabilities' || command.action === 'status') {
             const result = await request('GET', command.action === 'status' ? '/peers' : '/capabilities');
-            output(result);
             if (command.action === 'status' && o.text) {
-                for (const group of result.groups ?? []) {
-                    io.write(`组「${group.name}」成员定位：`);
-                    for (const id of group.sessionIds ?? []) {
-                        const member = [...(result.peers ?? []), result.source].find(item => item?.sessionId === id);
-                        io.write(roleLine({ sessionId: id, name: member?.name }, group.roles?.[id]));
+                // Human-readable status: no JSON dump, one line per fact.
+                const source = result.source;
+                if (source?.sessionId)
+                    io.write(`我:${source.name ?? ''}（${source.sessionId}）`);
+                for (const peer of result.peers ?? []) {
+                    const facts = peer;
+                    const line = `- ${facts.name || facts.sessionId}（${facts.sessionId}）${facts.status ? ` · ${facts.status}` : ''}`;
+                    io.write(line);
+                    if (facts.last_terminal_output_at && facts.activity_observed_at) {
+                        io.write(`  观测时距终端输出 ${facts.output_idle_seconds ?? Math.max(0, Math.floor((facts.activity_observed_at - facts.last_terminal_output_at) / 1000))} 秒（不代表任务进度）`);
                     }
                 }
-                for (const peer of result.peers ?? [])
-                    if (peer.last_terminal_output_at && peer.activity_observed_at) {
-                        io.write(`${peer.name || peer.sessionId}：观测时距终端输出 ${peer.output_idle_seconds ?? Math.max(0, Math.floor((peer.activity_observed_at - peer.last_terminal_output_at) / 1000))} 秒（不代表任务进度）`);
+                for (const group of result.groups ?? []) {
+                    const view = group;
+                    io.write(`组「${view.name}」成员定位：`);
+                    const peersAndSource = [...(result.peers ?? []), result.source];
+                    for (const id of view.sessionIds ?? []) {
+                        const member = peersAndSource.find(item => item?.sessionId === id);
+                        io.write(roleLine({ sessionId: id, name: member?.name }, view.roles?.[id]));
                     }
-            }
-            if (command.action === 'status' && o.text && Array.isArray(result.peers) && result.peers.length) {
+                }
                 io.write('查看伙伴当前屏幕（只读，仅本机 tmux）：');
-                for (const peer of result.peers) {
+                for (const peer of result.peers ?? []) {
                     const id = peer.sessionId;
-                    if (typeof id !== 'string' || id === result.source?.sessionId)
+                    const name = peer.name;
+                    if (typeof id !== 'string' || id === source?.sessionId)
                         continue;
-                    io.write(`- ${peer.name || id}：${id.startsWith('remote:')
+                    io.write(`- ${name || id}：${id.startsWith('remote:')
                         ? `远端成员，请用 td collab send ${id} "当前进展？" --text`
                         : `td collab capture ${id} --text`}`);
                 }
+                return 0;
             }
+            output(result);
             return 0;
         }
         if (command.action === 'rebind') {
@@ -551,7 +582,7 @@ export async function executeCollaborationCommand(command, context, io) {
                 role: command.operation === 'unset' ? null : command.role });
             if (o.text) {
                 io.write(command.operation === 'set'
-                    ? `定位已设置：${command.sessionId} = ${body.group.roles?.[command.sessionId] ?? ''}`
+                    ? `定位已设置：${command.sessionId} = ${body.group.roles?.[command.sessionId] ?? ''}\n（改成员显示名: td collab rename ${command.sessionId} <新名字>）`
                     : `定位已清除：${command.sessionId}`);
             }
             else
@@ -666,8 +697,16 @@ export async function executeCollaborationCommand(command, context, io) {
             output({ ...receipt, ok: false, code: 'WAIT_TIMEOUT', delivery_continues: true, last_error: error instanceof Error ? error.message : String(error) });
             return 2;
         }
-        output({ ...(receipt ?? {}), ok: false, code: error instanceof CollaborationError ? error.code : 'COLLABORATION_ERROR',
-            error: error instanceof Error ? error.message : String(error), ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}), ...(receipt ? { delivery_continues: true } : {}) });
+        const code = error instanceof CollaborationError ? error.code : 'COLLABORATION_ERROR';
+        const message = error instanceof Error ? error.message : String(error);
+        if (o.text) {
+            // Single-line errors in text mode; the enqueued-message hint keeps a
+            // mid-wait failure from reading as a lost message.
+            io.write(`${code}: ${message}${receipt?.message_id ? `（消息 ${canonicalShortId(String(receipt.message_id))} 已入队，投递继续）` : ''}`);
+            return 1;
+        }
+        output({ ...(receipt ?? {}), ok: false, code,
+            error: message, ...(idempotencyKey ? { idempotency_key: idempotencyKey } : {}), ...(receipt ? { delivery_continues: true } : {}) });
         return 1;
     }
 }

package/dist/server/agent/collaborationGroupRoutes.js

@@ -10,7 +10,17 @@ export function collaborationGroupRoutes(options) {
     });
     router.post('/collaboration-groups', async (req, res) => {
         try {
-            const { id, name, sessionIds, expectedUpdatedAt } = req.body ?? {};
+            const body = req.body ?? {};
+            const { id, name, sessionIds, expectedUpdatedAt } = body;
+            // Unknown fields used to be dropped silently while the save still
+            // returned ok — a caller submitting `members` to rename someone got a
+            // success and no rename. Reject them and route the common case (member
+            // renames) to the command that actually does it.
+            const unknownKeys = Object.keys(body).filter((key) => !['id', 'name', 'sessionIds', 'expectedUpdatedAt'].includes(key));
+            if (unknownKeys.length) {
+                const hint = unknownKeys.includes('members') ? '；要改成员显示名请用 td collab rename <session-id> <新名字>' : '';
+                throw new CollaborationError('INVALID_GROUP', `含未知字段 ${unknownKeys.join('、')}（合法字段：name, sessionIds, id, expectedUpdatedAt）${hint}`, 400);
+            }
             if ((id !== undefined && (typeof id !== 'string' || !id))
                 || typeof name !== 'string' || !name.trim() || !Array.isArray(sessionIds)
                 || sessionIds.some((value) => typeof value !== 'string' || !value.trim())) {
@@ -23,7 +33,7 @@ export function collaborationGroupRoutes(options) {
             if (id && (!existing || existing.deleted))
                 throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
             if (expectedUpdatedAt !== undefined && (!Number.isFinite(expectedUpdatedAt) || expectedUpdatedAt !== existing?.updatedAt)) {
-                throw new CollaborationError('GROUP_CHANGED', '协作组已被修改，请重新打开成员管理后再保存', 409);
+                throw new CollaborationError('GROUP_CHANGED', `协作组已被修改（当前 updatedAt=${existing?.updatedAt}）。请先确认最新成员列表，再以 expectedUpdatedAt=${existing?.updatedAt} 重新提交`, 409, { currentUpdatedAt: existing?.updatedAt });
             }
             const ids = [...new Set(sessionIds)];
             if (ids.length < 2)
@@ -41,6 +51,7 @@ export function collaborationGroupRoutes(options) {
         catch (error) {
             res.status(error instanceof CollaborationError ? error.httpStatus : 500)
                 .json({ code: error instanceof CollaborationError ? error.code : 'GROUP_SAVE_FAILED',
+                ...(error instanceof CollaborationError && error.details ? error.details : {}),
                 error: error instanceof Error ? error.message : '协作组保存失败' });
         }
     });
@@ -57,6 +68,7 @@ export function collaborationGroupRoutes(options) {
         catch (error) {
             res.status(error instanceof CollaborationError ? error.httpStatus : 500)
                 .json({ code: error instanceof CollaborationError ? error.code : 'GROUP_MOVE_FAILED',
+                ...(error instanceof CollaborationError && error.details ? error.details : {}),
                 error: error instanceof Error ? error.message : '成员移动失败' });
         }
     });
@@ -97,13 +109,15 @@ export function collaborationGroupRoutes(options) {
         catch (error) {
             res.status(error instanceof CollaborationError ? error.httpStatus : 400)
                 .json({ code: error instanceof CollaborationError ? error.code : 'GROUP_PROMOTION_FAILED',
+                ...(error instanceof CollaborationError && error.details ? error.details : {}),
                 error: error instanceof Error ? error.message : '跨服务组转换失败' });
         }
     });
     router.delete('/collaboration-groups/:groupId', (req, res) => {
         const existing = options.store.getGroup(req.params.groupId);
         if (req.query.expectedUpdatedAt !== undefined && Number(req.query.expectedUpdatedAt) !== existing?.updatedAt) {
-            return res.status(409).json({ code: 'GROUP_CHANGED', error: '协作组已变化，请刷新后重新操作' });
+            return res.status(409).json({ code: 'GROUP_CHANGED', currentUpdatedAt: existing?.updatedAt,
+                error: `协作组已变化（当前 updatedAt=${existing?.updatedAt}），请刷新后重新操作` });
         }
         if (!options.store.remove(req.params.groupId))
             return res.status(404).json({ error: '协作组不存在' });

package/dist/server/agent/collaborationPrompt.js

@@ -1,6 +1,6 @@
 import { canonicalShortId } from './collaborationProtocol.js';
 import { sanitizeCollaborationRole } from './collaborationStore.js';
-const SHELL_RULE = '─'.repeat(30);
+const SHELL_RULE = '─'.repeat(3);
 /** Body larger than this (in UTF-8 bytes) is replaced by a retrieval pointer
  * instead of being injected into the terminal verbatim. */
 const MAX_INLINE_BODY_BYTES = 4_096;
@@ -61,41 +61,22 @@ export function collaborationMessageAnchorTokens(messages) {
         return [message.id, counts.get(short) === 1 ? short : message.id];
     }));
 }
-/** The one line of a delivered block that carries the message's id, chosen by
- *  what the recipient can actually do with it: an agent-sourced message gets the
- *  reply command, a user message gets the read-back command (`td collab reply`
- *  refuses user messages — NO_REPLY_TARGET — so naming it there would be a dead
- *  command). Both routes accept the short form (the CLI resolves id prefixes),
- *  so whichever token collaborationMessageAnchorTokens picks for this delivery is what
- *  the recipient can paste back. Every message must carry its token regardless
- *  of source: the invariant is pinned by the "carries its id" test in
- *  collaborationPrompt.test.ts. */
-export function collaborationMessageAnchorLine(message, token = canonicalShortId(message.id)) {
-    return message.fromSessionId
-        ? `回复:td collab reply ${token} "内容" --text`
-        : `详情:td collab message get ${token} --json`;
-}
-/** A single delivered message: `来自:X · kind` over a fenced body, with the
- * anchor line (reply route / read-back route) kept outside the fence. A fan-out
- * dispatch (message.fanOutIds present) is flagged `· 群发` and names the
- * sibling recipients on their own line, so a broadcast is never mistaken for
- * a one-to-one assignment — raw ids fall back to the sanitized id itself. */
-function formatCollaborationMessage(message, source, fannedNames, fence, token, now) {
-    const lines = [`来自:${source}${message.kind === 'message' ? '' : ` · ${message.kind}`}${fannedNames.length ? ' · 群发' : ''}`];
+/** A single delivered message: `来自:X · kind · id` over a fenced body. The
+ *  message id rides the source line — it is the one place a recipient can
+ *  look up how to reply (`td collab --help`, always present below) without a
+ *  per-message command template. A fan-out dispatch (message.fanOutIds
+ *  present) is flagged `· 群发` and names the sibling recipients on their own
+ *  line, so a broadcast is never mistaken for a one-to-one assignment — raw
+ *  ids fall back to the sanitized id itself. The id must stay in every block:
+ *  the delivery-confirm gate searches the terminal text for this exact token. */
+function formatCollaborationMessage(message, source, fannedNames, fence, token) {
+    const kindSuffix = message.kind === 'message' ? '' : ` · ${message.kind}`;
+    const lines = [`来自:${source}${kindSuffix}${fannedNames.length ? ' · 群发' : ''} · ${token}`];
     if (fannedNames.length)
         lines.push(`同时发给了:${fannedNames.join('、')}`);
-    const rules = message.instructions;
-    if (rules?.text) {
-        const age = collaborationRulesAge(rules.updatedAt, now);
-        const inline = Array.from(rules.text).length <= 200 && rules.text.split(/\r\n?|\n/).length <= 4;
-        lines.push(inline
-            ? `群规[${age}]:${rules.text}`
-            : `查看群规[${age}]:td collab rules get ${message.groupId} --text`);
-    }
     lines.push('', fence, message.content, fence);
     if (message.task)
         lines.push('', `任务上报:${JSON.stringify(message.task)}`);
-    lines.push('', collaborationMessageAnchorLine(message, token));
     return lines.join('\n');
 }
 export function formatCollaborationDelivery(input) {
@@ -117,10 +98,7 @@ export function formatCollaborationDelivery(input) {
         const fence = '`'.repeat(Math.max(3, ...Array.from(body.matchAll(/`+/g), (match) => match[0].length + 1)));
         const fannedNames = (message.fanOutIds ?? [])
             .map((sessionId) => sanitizeCollaborationName(sessionsById.get(sessionId)?.name ?? sessionId));
-        // Show current guidance alongside the command that retrieves current rules.
-        // The stored message snapshot remains available through message get.
-        const instructions = groupsById.get(message.groupId)?.instructions ?? message.instructions;
-        blocks.push(formatCollaborationMessage({ ...message, content: body, instructions }, source, fannedNames, fence, token, now));
+        blocks.push(formatCollaborationMessage({ ...message, content: body }, source, fannedNames, fence, token));
     }
     // The shell header names the group only when every block belongs to one;
     // a mixed batch drops the header entirely (no single-group claim to make).
@@ -128,53 +106,66 @@ export function formatCollaborationDelivery(input) {
     const groupIds = [...new Set(input.messages.map((message) => message.groupId))];
     const singleGroup = groupIds.length === 1 ? groupsById.get(groupIds[0]) : null;
     const shellHeader = singleGroup
-        ? `「${sanitizeCollaborationName(singleGroup.name ?? '协作组')}」群 · ${singleGroup.sessionIds.length} 人`
+        ? `「${sanitizeCollaborationName(singleGroup.name ?? '协作组')}」td群 · ${singleGroup.sessionIds.length} 人`
         : '';
+    // One-time education block: static guidance that only rides the first
+    // delivery (and again whenever the roster or the group rules change).
+    // Current group guidance is preferred over the message's stored snapshot —
+    // the snapshot stays reachable through message get.
+    const educated = input.showRoutingHelp !== false;
+    const education = [];
+    if (educated) {
+        const rules = singleGroup?.instructions ?? input.messages.find((message) => message.instructions)?.instructions;
+        if (rules?.text) {
+            const age = collaborationRulesAge(rules.updatedAt, now);
+            const inline = Array.from(rules.text).length <= 200 && rules.text.split(/\r\n?|\n/).length <= 4;
+            education.push(inline
+                ? `群规[${age}]:${rules.text}`
+                : `查看群规[${age}]:td collab rules get ${singleGroup?.id ?? input.messages[0].groupId} --text`);
+        }
+        const peerIds = Array.from(new Set(input.groups.flatMap((group) => group.sessionIds)))
+            .filter((sessionId) => sessionId !== input.targetSessionId);
+        // Keep routing IDs once, only for peers who are not already directly replyable.
+        const sourceIds = new Set(input.messages.map((message) => message.fromSessionId));
+        const peers = peerIds.filter((id) => !sourceIds.has(id)).map((sessionId) => {
+            const session = sessionsById.get(sessionId);
+            return `- ${session ? sanitizeCollaborationName(session.name) : '离线会话'}：\`td collab send ${sessionId} "消息内容" --text\``;
+        });
+        if (peers.length)
+            education.push('联系其他成员：', ...peers);
+        const captureHelp = '查看屏幕：`td collab capture <会话ID> --text`（只读，不打断对方；仅同组本机 tmux，远端用 send 询问）。ID：`td collab status --text`。快照不代表完成，勿循环轮询。';
+        education.push(captureHelp);
+        if (peerIds.some((id) => id.startsWith('remote:'))) {
+            education.push('跨服务通信使用 td collab；已登记节点由服务后台直接投递，使用 message get 查看送达回执与重试原因。');
+        }
+    }
+    // Dynamic notices report current conditions and are never gated:
+    // an unreachable peer changes what a reply can actually do, every delivery.
     const peerIds = Array.from(new Set(input.groups.flatMap((group) => group.sessionIds)))
         .filter((sessionId) => sessionId !== input.targetSessionId);
-    // Keep routing IDs once, only for peers who are not already directly replyable.
-    const sourceIds = new Set(input.messages.map((message) => message.fromSessionId));
-    const peers = peerIds.filter((id) => !sourceIds.has(id)).map((sessionId) => {
-        const session = sessionsById.get(sessionId);
-        return `- ${session ? sanitizeCollaborationName(session.name) : '离线会话'}：\`td collab send ${sessionId} "消息内容" --text\``;
-    });
     const unreachable = peerIds.filter((id) => sessionsById.get(id)?.status === 'service-unreachable');
-    // Static command help is shown once per roster; delivery conditions remain visible.
-    const routingHelp = input.showRoutingHelp === false ? [] : (peers.length ? ['联系其他成员：', ...peers] : []);
-    const dynamicNotices = [
-        ...(peerIds.some((id) => id.startsWith('remote:'))
-            ? ['跨服务通信使用 td collab；已登记节点由服务后台直接投递，使用 message get 查看送达回执与重试原因。'] : []),
-        ...unreachable.map((id) => {
-            const session = sessionsById.get(id);
-            return `注意：${session ? sanitizeCollaborationName(session.name) : id} 服务不可达，消息无法送达；仅可排队等待重连。`;
-        }),
-    ];
-    const captureHelp = '查看屏幕：`td collab capture <会话ID> --text`（只读，不打断对方；仅同组本机 tmux，远端用 send 询问）。ID：`td collab status --text`。快照不代表完成，勿循环轮询。';
-    const notes = [...routingHelp, ...dynamicNotices,
-        ...(input.showRoutingHelp === false ? [] : [captureHelp]), '帮助:td collab --help'];
-    // Notes (education + dynamic notices) live inside the shell, after the last
-    // message, so the closing rule still marks the end of the delivered block.
+    const dynamicNotices = unreachable.map((id) => {
+        const session = sessionsById.get(id);
+        return `注意：${session ? sanitizeCollaborationName(session.name) : id} 服务不可达，消息无法送达；仅可排队等待重连。`;
+    });
+    const notes = [...education, ...dynamicNotices, '帮助:td collab --help'];
     if (!blocks.length)
         return notes.join('\n');
-    // Self-identity rides the shell under the header so the recipient always
-    // knows the name peers see (a rename lands on the next delivery — no
-    // separate notification needed) and, in a single-group delivery, its role.
-    // The name needs no group claim and survives mixed batches; the role (定位)
-    // only rides when the batch maps to exactly one group.
+    // Recipient identity rides the shell under the header so the recipient
+    // always knows the name peers see (a rename lands on the next delivery — no
+    // separate notification needed) and, in a single-group delivery, its role
+    // (定位). The name needs no group claim and survives mixed batches; the
+    // role only rides when the batch maps to exactly one group.
     const ownName = sanitizeCollaborationName(sessionsById.get(input.targetSessionId)?.name ?? '');
     const ownRole = singleGroup
         ? sanitizeCollaborationRole(singleGroup.roles?.[input.targetSessionId] ?? '')
         : '';
-    const lines = [SHELL_RULE];
-    if (shellHeader)
-        lines.push(shellHeader);
-    if (ownName)
-        lines.push(`你:${ownName}`);
-    if (ownRole)
-        lines.push(`你的定位:${ownRole}`);
-    // No blank line between the identity block and the first message, nor
-    // between the last message and the notes: the shell reads as one compact
-    // block, and only message-to-message boundaries keep a blank line.
+    const contextLines = [shellHeader, ownName ? `收件人:${ownName}${ownRole ? ` · 定位:${ownRole}` : ''}` : ''].filter(Boolean);
+    const lines = [SHELL_RULE, ...contextLines];
+    // A blank line separates the who/where context block from the message
+    // stream: the shell reads as context, then one compact block per message.
+    if (contextLines.length)
+        lines.push('');
     lines.push(blocks.join('\n\n'), ...notes, SHELL_RULE);
     return lines.join('\n');
 }

package/dist/server/agent/collaborationProtocol.js

@@ -13,10 +13,15 @@ export const COLLAB_LIMITS = {
 export class CollaborationError extends Error {
     code;
     httpStatus;
-    constructor(code, message, httpStatus = 400) {
+    details;
+    /** Structured fields merged into the JSON error body (e.g. the group's
+     *  current updatedAt on GROUP_CHANGED) so callers can retry programmatically
+     *  without scraping the sentence. */
+    constructor(code, message, httpStatus = 400, details) {
         super(message);
         this.code = code;
         this.httpStatus = httpStatus;
+        this.details = details;
     }
 }
 /** A delivered terminal shows a short id, because a 36-character one wraps in

package/dist/server/agent/collaborationService.js

@@ -274,7 +274,7 @@ export class CollaborationService {
         if (input.id && (!existing || existing.deleted))
             throw new Error('GROUP_NOT_FOUND');
         if (existing && input.expectedUpdatedAt !== existing.updatedAt)
-            throw new CollaborationError('GROUP_CHANGED', '协作组已变化，请刷新后重试', 409);
+            throw new CollaborationError('GROUP_CHANGED', `协作组已变化（当前 updatedAt=${existing.updatedAt}），请刷新后重试`, 409, { currentUpdatedAt: existing.updatedAt });
         if (typeof input.name !== 'string' || !input.name.trim() || COLLAB_NAME_FORBIDDEN.test(input.name) || !Array.isArray(input.sessionIds) || input.sessionIds.some(id => typeof id !== 'string') || new Set(input.sessionIds).size < 2)
             throw new Error('INVALID_GROUP');
         if (!input.sessionIds.some(id => address(id)) && !existing?.federated) {

package/dist/server/agent/collaborationStore.js

@@ -182,7 +182,7 @@ export class CollaborationStore {
             throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
         if (source.id === target.id || !source.sessionIds.includes(input.sessionId)
             || source.updatedAt !== input.expectedSourceUpdatedAt || target.updatedAt !== input.expectedTargetUpdatedAt) {
-            throw new CollaborationError('GROUP_CHANGED', '协作组已变化，请刷新后重新移动成员', 409);
+            throw new CollaborationError('GROUP_CHANGED', `协作组已变化（当前 updatedAt：源组=${source.updatedAt}，目标组=${target.updatedAt}），请刷新后重新移动成员`, 409, { currentSourceUpdatedAt: source.updatedAt, currentTargetUpdatedAt: target.updatedAt });
         }
         const sourceIds = source.sessionIds.filter((id) => id !== input.sessionId);
         const dissolved = sourceIds.length < 2;
@@ -448,7 +448,7 @@ export class CollaborationStore {
         if (!existing || existing.deleted)
             throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
         if (existing.federated || existing.updatedAt !== expectedUpdatedAt || this.getGroup(group.id)) {
-            throw new CollaborationError('GROUP_CHANGED', '协作组已被修改，请重新打开成员管理后再保存', 409);
+            throw new CollaborationError('GROUP_CHANGED', `协作组已被修改（当前 updatedAt=${existing.updatedAt}），请刷新后再保存`, 409, { currentUpdatedAt: existing.updatedAt });
         }
         const promoted = { ...group, createdAt: existing.createdAt, updatedAt: Math.max(Date.now(), existing.updatedAt + 1, group.updatedAt) };
         const idempotency = { ...this.document.idempotency };