termdock 1.4.190 → 1.4.192

package/dist/server/agent/collaborationCli.js

@@ -5,13 +5,17 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
   status | capabilities
   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|read --timeout 30s
     --expect-reply ack|result|any
     --response-kind ack|progress|result --metadata '<JSON object>'
-    --task-envelope '<JSON: task_id,status,progress?,evidence?,blocker?>'
     --expires-at <ISO timestamp or epoch milliseconds>
+    reply: --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]
   message read <message-id> (explicit consumption; not application ACK)
   message watch <message-id> [--wait-until delivered|read] [--timeout 30s]
@@ -22,14 +26,41 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
   cursor commit <token> --consumer <name> (commit after processing the page)
   add|remove <group-id> <session-id>
   spawn <group-id> <agent-slug> [--name <name>] [--cwd <path>] [--task <text>]
+  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)
+  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)
+  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
+    operations are shell operations: approve dismisses an interactive approval
+    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. 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
 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. read/ACK/result never imply each other.
 Inbox defaults to unread first, newest 50; cursor/consumer mode reads oldest unseen first.
 Reading never advances a consumer or marks messages read automatically.`;
-const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'unread', 'follow', 'stdin', 'receipt-only', 'help']);
+/** 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', 'unread', 'follow', 'stdin', 'receipt-only', 'confirm', 'help']);
 const VALUE_OPTIONS = new Set(['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']);
 export function parseCollaborationCommand(argv) {
     const options = {};
@@ -61,7 +92,7 @@ export function parseCollaborationCommand(argv) {
             positional.push(value);
     }
     const action = (options.help ? 'help' : positional.shift() ?? 'status');
-    if (!['status', 'inbox', 'send', 'handoff', 'reply', 'add', 'remove', 'spawn', 'message', 'cursor', 'rebind', 'capabilities', 'help'].includes(action))
+    if (!['status', 'inbox', 'send', 'handoff', 'reply', 'add', 'remove', 'spawn', 'message', 'cursor', 'rebind', 'role', 'rename', 'cleanup', 'drive', 'capabilities', 'help'].includes(action))
         throw new Error('Unknown collaboration command; see td collab --help');
     if (options.pane && !/^%\d+$/.test(String(options.pane)))
         throw new Error('pane must be a tmux pane id such as %3');
@@ -106,17 +137,63 @@ export function parseCollaborationCommand(argv) {
         command.cwd = options.cwd;
         command.task = options.task;
     }
+    else if (action === 'role') {
+        command.operation = positional.shift();
+        command.groupId = positional.shift();
+        if (command.operation === 'list') {
+            if (!command.groupId || positional.length)
+                throw new Error('Usage: td collab role list <group-id>');
+        }
+        else if (command.operation === 'set') {
+            command.sessionId = positional.shift();
+            command.role = positional.join(' ');
+            if (!command.groupId || !command.sessionId || !command.role?.trim())
+                throw new Error('Usage: td collab role set <group-id> <session-id> <role…>');
+        }
+        else if (command.operation === 'unset') {
+            command.sessionId = positional.shift();
+            if (!command.groupId || !command.sessionId || positional.length)
+                throw new Error('Usage: td collab role unset <group-id> <session-id>');
+        }
+        else
+            throw new Error('Usage: td collab role list|set|unset (see td collab --help)');
+    }
+    else if (action === 'rename') {
+        command.sessionId = positional.shift();
+        command.name = positional.join(' ');
+        if (!command.sessionId || !command.name?.trim())
+            throw new Error('Usage: td collab rename <session-id> <name…>');
+    }
+    else if (action === 'cleanup') {
+        command.sessionIds = [...positional];
+        if (command.sessionIds.length === 0)
+            throw new Error('Usage: td collab cleanup <session-id> [<session-id>…]');
+    }
+    else if (action === 'drive') {
+        command.sessionId = positional.shift();
+        command.operation = positional.shift();
+        if (!command.sessionId || !command.operation)
+            throw new Error('Usage: td collab drive <session-id> approve|enter|escape|space|left|right|up|down|capture|run <command…>');
+        if (command.operation === 'run') {
+            command.message = positional.join(' ');
+            if (!command.message?.trim())
+                throw new Error('Usage: td collab drive <session-id> run <command…>');
+        }
+        else if (positional.length || !['approve', 'enter', 'escape', 'space', 'left', 'right', 'up', 'down', 'capture'].includes(command.operation)) {
+            throw new Error(`Unknown drive action ${command.operation ?? ''}; use approve|enter|escape|space|left|right|up|down|capture|run`);
+        }
+    }
     else if (positional.length && action !== 'help')
         throw new Error(`Unexpected arguments for ${action}`);
     const allowed = new Set(['json', 'jsonl', 'text', 'help']);
     const byAction = {
         status: [], capabilities: [], rebind: ['pane'], help: [...BOOLEAN_OPTIONS, ...VALUE_OPTIONS],
-        send: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'kind'],
-        handoff: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
+        send: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at', 'kind'],
+        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: ['unread', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind', 'follow', 'timeout'],
         message: ['receipt-only', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
-        add: [], remove: [], spawn: ['name', 'cwd', 'task'],
+        add: [], remove: [], spawn: ['name', 'cwd', 'task'], role: [], rename: [], cleanup: ['confirm'], drive: [],
     };
     for (const option of byAction[action])
         allowed.add(option);
@@ -160,12 +237,28 @@ export async function executeCollaborationCommand(command, context, io) {
     const output = (value) => {
         if (o.text) {
             if (Array.isArray(value.messages))
-                for (const message of value.messages)
-                    io.write(`[${message.responseKind ?? message.kind}] ${message.id} from ${message.fromSessionId ?? 'user'}\n${message.content}`);
+                for (const message of value.messages) {
+                    const fanIds = Array.isArray(message.fanOutIds) ? message.fanOutIds : [];
+                    const names = value.names ?? {};
+                    io.write(`[${message.responseKind ?? message.kind}] ${message.id} from ${message.fromSessionId ?? 'user'}${fanIds.length ? ' · 群发' : ''}`);
+                    // A fan-out dispatch names its sibling recipients so a broadcast is
+                    // never read as a one-to-one assignment; unknown ids stay raw.
+                    if (fanIds.length)
+                        io.write(`同时发给了:${fanIds.map((id) => names[id] ?? id).join('、')}`);
+                    io.write(message.content);
+                }
             else if (value.message)
                 io.write(`[${value.status}] ${value.message_id}\n${value.message.content}`);
-            else if (value.message_id)
+            else if (value.message_id) {
                 io.write(`${value.status} ${value.message_id} thread=${value.thread_id}${value.code ? ` ${value.code}` : ''}${value.failure_reason ? ` ${value.failure_reason}` : ''}`);
+                // A timeout after the wait stage itself was reached means delivery
+                // (or reading) completed — only the expected reply/result is late.
+                if (value.code === 'WAIT_TIMEOUT' && value.stage_reached && value.expect_reply) {
+                    io.write(`\n投递已完成；等待${value.expect_reply === 'result' ? '结果' : '回复'}超时（expect-reply=${value.expect_reply}）`);
+                }
+                if (value.snapshot)
+                    io.write(`\n${value.snapshot}`);
+            }
             else
                 io.write(JSON.stringify(value, null, 2));
             if (value.next_cursor)
@@ -184,6 +277,24 @@ export async function executeCollaborationCommand(command, context, io) {
     try {
         if (command.action === 'help') {
             io.write(COLLAB_HELP);
+            // Append the caller's own groups with every member role — help doubles
+            // as the newcomer's one-shot introduction to the current roster. The
+            // snapshot requires a managed session, so it degrades to bare help
+            // outside one (a plain CLI read still prints the full surface).
+            try {
+                const mine = await request('GET', '/role');
+                const groups = mine.groups ?? [];
+                if (groups.length) {
+                    io.write('\n本会话所在协作组的成员定位：');
+                    for (const group of groups) {
+                        io.write(`组「${group.name ?? ''}」(${group.sessionIds.length} 个成员)`);
+                        const members = new Map((group.members ?? []).map((member) => [member.sessionId, member.name ?? null]));
+                        for (const id of group.sessionIds)
+                            io.write(roleLine({ sessionId: id, name: members.get(id) ?? null }, group.roles?.[id]));
+                    }
+                }
+            }
+            catch { /* help stays available without a server or session */ }
             return 0;
         }
         if (command.action === 'capabilities' || command.action === 'status') {
@@ -252,13 +363,114 @@ export async function executeCollaborationCommand(command, context, io) {
             idempotencyKey = String(o['idempotency-key'] ?? randomUUID());
             const extras = { group_id: o.group, thread_id: o.thread, idempotency_key: idempotencyKey, response_kind: o['response-kind'],
                 metadata: o.metadata ? JSON.parse(String(o.metadata)) : undefined, task: o['task-envelope'] ? JSON.parse(String(o['task-envelope'])) : undefined, expires_at: expiresAt };
+            // A comma-separated target list fans one dispatch out to several
+            // recipients of a shared group; every edge carries the sibling list so
+            // recipients see the 群发 framing. Reply stays one-to-one by nature.
+            const targets = command.target.split(',').map((id) => id.trim()).filter(Boolean);
+            const fanOut = command.action !== 'reply' && targets.length > 1;
+            if (command.action !== 'reply' && !targets.length)
+                throw new Error(`${command.action} requires a target session id`);
+            if (fanOut && (o['wait-until'] || o['expect-reply']))
+                throw new Error('--wait-until/--expect-reply need a single recipient; fan-out confirms queued delivery only');
             deadline = now() + duration(String(o.timeout ?? '30s'));
             receipt = await request('POST', command.action === 'reply' ? '/reply' : '/send', command.action === 'reply'
-                ? { ...extras, messageId: command.target, content } : { ...extras, targetSessionId: command.target, message: content, kind: command.action === 'handoff' ? 'handoff' : o.kind ?? 'message' });
+                ? { ...extras, messageId: command.target, content }
+                : { ...extras, ...(fanOut ? { toSessionIds: targets } : { targetSessionId: targets[0] }), message: content, kind: command.action === 'handoff' ? 'handoff' : o.kind ?? 'message' });
             // CLI receipts stay small even when the message is a large evidence package.
             delete receipt.messages;
             receipt.idempotency_key = idempotencyKey;
         }
+        else if (command.action === 'role') {
+            if (command.operation === 'list') {
+                const body = await request('GET', `/role?group=${encodeURIComponent(command.groupId)}`);
+                if (o.text) {
+                    const group = body.group;
+                    io.write(`定位表（${group.name ? `组「${group.name}」· ` : ''}${group.sessionIds.length} 个成员）：`);
+                    const members = new Map((group.members ?? []).map((member) => [member.sessionId, member.name ?? null]));
+                    for (const id of group.sessionIds)
+                        io.write(roleLine({ sessionId: id, name: members.get(id) ?? null }, group.roles?.[id]));
+                }
+                else
+                    output(body);
+                return 0;
+            }
+            const body = await request('POST', '/role', { group_id: command.groupId, session_id: command.sessionId,
+                role: command.operation === 'unset' ? null : command.role });
+            if (o.text) {
+                io.write(command.operation === 'set'
+                    ? `定位已设置：${command.sessionId} = ${body.group.roles?.[command.sessionId] ?? ''}`
+                    : `定位已清除：${command.sessionId}`);
+            }
+            else
+                output(body);
+            return 0;
+        }
+        else if (command.action === 'rename') {
+            const body = await request('POST', '/name', { session_id: command.sessionId, name: command.name });
+            if (o.text)
+                io.write(`已改名：${command.sessionId} = ${body.name ?? command.name}`);
+            else
+                output(body);
+            return 0;
+        }
+        else if (command.action === 'drive') {
+            const body = await request('POST', '/drive', { session: command.sessionId, action: command.operation, text: command.message });
+            const result = body;
+            if (o.text) {
+                if (command.operation === 'run') {
+                    io.write(`已向 ${command.sessionId} 发送一行并提交：${command.message}`);
+                    if (result.snapshot)
+                        io.write(`--- ${command.sessionId} 当前屏幕 ---\n${result.snapshot}`);
+                }
+                else if (command.operation === 'capture') {
+                    if (result.snapshot)
+                        io.write(result.snapshot);
+                    else
+                        io.write('（无快照）');
+                }
+                else if (command.operation === 'approve') {
+                    io.write(result.approved ? `已批准 ${command.sessionId} 的审批对话框` : '目标面板当前没有显示审批对话框；未发送任何按键');
+                }
+                else
+                    io.write(`已向 ${command.sessionId} 发送 ${command.operation}`);
+            }
+            else
+                output(body);
+            return 0;
+        }
+        else if (command.action === 'cleanup') {
+            const plan = await request('POST', '/cleanup', { sessionIds: command.sessionIds, confirmed: Boolean(o.confirm) });
+            const targets = (plan.plan?.targets ?? []);
+            const groups = (plan.plan?.groups ?? []);
+            if (plan.ok !== true) {
+                if (o.text) {
+                    io.write('清理计划（未执行 —— 需要人类授权）');
+                    for (const target of targets)
+                        io.write(`- ${target.name ?? target.sessionId}（${target.sessionId}）${target.mode === 'tmux' && target.tmuxSessionName ? ` · tmux ${target.tmuxSessionName}` : target.mode ? ` · ${target.mode}` : ''}`);
+                    if (groups.length) {
+                        io.write('协作组影响：');
+                        for (const group of groups)
+                            io.write(group.dissolves
+                                ? `- 组「${group.name ?? group.id}」将被解散（组内消息一并清除）`
+                                : `- 组「${group.name ?? group.id}」：${group.sizeBefore} 个成员 → ${group.sizeAfter} 个成员`);
+                    }
+                    io.write('⚠ 这是不可恢复的风险操作：将移除上述会话记录并终止其 tmux/进程。');
+                    io.write('执行前必须先向用户（人类）说明以上内容并获得明确同意，再以 --confirm 重跑本命令；每次执行都需要当场的人类授权。');
+                }
+                else
+                    output(plan);
+                return 1;
+            }
+            const removed = (plan.removed ?? []);
+            if (o.text) {
+                io.write(`已清理 ${removed.length} 个会话：`);
+                for (const entry of removed)
+                    io.write(`- ${entry.name ?? entry.sessionId}（${entry.sessionId}）：${entry.tmuxSessionName ? (entry.alreadyGone ? 'tmux 已不存在，记录已移除' : `tmux ${entry.tmuxSessionName} 已终止`) : entry.killed ? '进程已终止，记录已移除' : '记录已移除'}`);
+            }
+            else
+                output(plan);
+            return 0;
+        }
         else {
             const body = command.action === 'spawn' ? { groupId: command.groupId, agentSlug: command.agentSlug, name: command.name, cwd: command.cwd, task: command.task }
                 : { groupId: command.groupId, targetSessionId: command.sessionId, action: command.action };
@@ -284,7 +496,8 @@ export async function executeCollaborationCommand(command, context, io) {
                 }
             }
             if (now() >= deadline) {
-                output({ ...receipt, ok: false, code: 'WAIT_TIMEOUT', wait_until: stage, expect_reply: o['expect-reply'] ?? null, delivery_continues: true });
+                output({ ...receipt, ok: false, code: 'WAIT_TIMEOUT', wait_until: stage, stage_reached: waitSatisfied(receipt, stage, undefined),
+                    expect_reply: o['expect-reply'] ?? null, delivery_continues: true });
                 return 2;
             }
             await sleep(Math.min(500, deadline - now()));

package/dist/server/agent/collaborationDeliveryWorker.js

@@ -4,6 +4,14 @@ export class CollaborationDeliveryWorker {
     states = new Map();
     failures = new Map();
     submitted = new Set();
+    /** Sessions whose latest delivery was confirmed rendered in this process,
+     *  mapped to the timestamp until which confirmations are skipped. A recent
+     *  confirmed delivery means the agent is actively consuming input, so
+     *  follow-up messages settle immediately; once the cooldown lapses the
+     *  agent's state is unknown again (it may be mid-turn, or finishing one)
+     *  and the gate re-engages. Settled-but-unconfirmed deliveries never grant
+     *  cooldown — that would re-open the turn-handover hole the gate closes. */
+    confirmedUntil = new Map();
     timer = null;
     ticking = null;
     constructor(options) {
@@ -111,10 +119,33 @@ export class CollaborationDeliveryWorker {
             return;
         }
         const message = pending[0];
+        const attempts = store.diagnostic(message.id)?.attempt_count ?? 0;
+        // Confirm gate: the route becoming ready only proves the agent process is
+        // up, not that its TUI is consuming — a write landing while the agent
+        // finishes another turn can sit unsubmitted in its input box. When the
+        // route can read terminal history, hold deliveries outside the session's
+        // confirm cooldown until our message appears in the history (the agent
+        // rendered it). Unconfirmed writes are re-attempted up to the configured
+        // bound; at-least-once transport is preserved throughout.
+        const confirmMs = this.options.firstDeliveryConfirmMs ?? 1_500;
+        const gateActive = Boolean(route.confirm) && confirmMs > 0
+            && Date.now() >= (this.confirmedUntil.get(id) ?? 0)
+            && attempts + 1 < (this.options.maxUnconfirmedWrites ?? 3);
+        // Differential baseline for stuck-paste recovery: captured before the
+        // write so a later screen diff can tell our paste apart from stale ones.
+        let baseline = '';
+        if (gateActive && route.recoverStuck && !this.submitted.has(message.id) && route.capture) {
+            try {
+                baseline = (await route.capture()) ?? '';
+            }
+            catch {
+                baseline = '';
+            }
+        }
         if (!this.submitted.has(message.id)) {
             store.recordTransport(message.id, {
                 relay_online: null, peer_reachable: true,
-                attempt_count: (store.diagnostic(message.id)?.attempt_count ?? 0) + 1,
+                attempt_count: attempts + 1,
                 next_retry_at: Date.now() + 2_000, last_error: 'DELIVERY_IN_PROGRESS', checked_at: Date.now(),
             });
             try {
@@ -125,11 +156,73 @@ export class CollaborationDeliveryWorker {
                 return;
             }
             this.submitted.add(message.id);
+            // Capture the recipient terminal before marking delivered, so a sender
+            // waiting on delivered always finds the snapshot present. The capture is
+            // strictly best-effort: a failure must never block delivery completion.
+            if (route.capture) {
+                try {
+                    const snapshot = await route.capture();
+                    if (snapshot)
+                        store.setSnapshot(message.id, snapshot);
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        if (gateActive) {
+            if (!(await this.confirmConsumed(pending, route, confirmMs, baseline))) {
+                this.submitted.delete(message.id);
+                store.recordTransport(message.id, {
+                    relay_online: null, peer_reachable: true,
+                    attempt_count: attempts + 1,
+                    next_retry_at: Date.now() + 4_000, last_error: 'AGENT_CONSUME_UNCONFIRMED', checked_at: Date.now(),
+                });
+                this.failures.delete(id);
+                return;
+            }
+            // Confirmed rendered: refresh the exemption window so follow-ups in the
+            // agent's active turn settle immediately.
+            this.confirmedUntil.set(id, Date.now() + (this.options.confirmCooldownMs ?? 30_000));
         }
         // If persistence fails after writing, the in-process guard avoids a
         // second write on retry. Across a crash, transport is at-least-once.
         this.complete(id, message);
     }
+    /** Wait out the confirm window, then look for the written messages in the
+     *  recipient's terminal history. A message found there was rendered by the
+     *  agent and counts as consumed. While the agent is blocked on an approval
+     *  dialog (its Bash call needs permission) dismiss it once per cycle, and
+     *  on the first cycle submit a paste that arrived during turn handover and
+     *  is still sitting unsubmitted (differential baseline evidence only, at
+     *  most once per delivery). Each recovery sends Enter on evidence, never
+     *  blind. */
+    async confirmConsumed(messages, route, delayMs, baseline) {
+        let recovered = false;
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            await new Promise((resolve) => setTimeout(resolve, attempt === 0 ? delayMs : Math.min(1_200, delayMs)));
+            let content = null;
+            try {
+                content = await route.confirm();
+            }
+            catch {
+                content = null;
+            }
+            if (content && messages.some((message) => content.includes(message.id)))
+                return true;
+            if (!recovered && route.recoverStuck && baseline) {
+                try {
+                    recovered = await route.recoverStuck(baseline);
+                }
+                catch { /* a failed submit must not settle delivery */ }
+            }
+            if (content && route.approve) {
+                try {
+                    await route.approve();
+                }
+                catch { /* a failed dismiss must not settle delivery */ }
+            }
+        }
+        return false;
+    }
     complete(id, message) {
         const { store } = this.options;
         store.markDelivered([message.id]);

package/dist/server/agent/collaborationGroupRoutes.js

@@ -1,5 +1,6 @@
 import { Router } from 'express';
 import { CollaborationError } from './collaborationProtocol.js';
+import { COLLAB_NAME_FORBIDDEN } from './collaborationPrompt.js';
 /** The current service owns group membership, including retained offline members. */
 export function collaborationGroupRoutes(options) {
     const router = Router();
@@ -15,6 +16,9 @@ export function collaborationGroupRoutes(options) {
                 || sessionIds.some((value) => typeof value !== 'string' || !value.trim())) {
                 throw new CollaborationError('INVALID_GROUP', '名称和成员列表无效', 400);
             }
+            if (COLLAB_NAME_FORBIDDEN.test(name.trim())) {
+                throw new CollaborationError('INVALID_GROUP', '名称不能包含「【】」、间隔号「·」、换行或控制字符', 400);
+            }
             const existing = id ? options.store.getGroup(id) : null;
             if (id && (!existing || existing.deleted))
                 throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
@@ -52,6 +56,27 @@ export function collaborationGroupRoutes(options) {
                 error: error instanceof Error ? error.message : '成员移动失败' });
         }
     });
+    router.post('/collaboration-groups/:groupId/role', (req, res) => {
+        try {
+            const existing = options.store.getGroup(req.params.groupId);
+            if (!existing || existing.deleted)
+                throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
+            const { sessionId, role } = req.body ?? {};
+            if (typeof sessionId !== 'string' || !existing.sessionIds.includes(sessionId)) {
+                throw new CollaborationError('NOT_A_MEMBER', '该会话不在协作组中，无法设置定位', 400);
+            }
+            if (role === undefined || (role !== null && typeof role !== 'string')) {
+                throw new CollaborationError('INVALID_ROLE', '定位必须是文本；清除请传 null', 400);
+            }
+            const updated = options.store.setRole({ groupId: existing.id, sessionId, role: role });
+            res.json({ group: { ...updated, roles: updated.roles ?? {} } });
+        }
+        catch (error) {
+            res.status(error instanceof CollaborationError ? error.httpStatus : 400)
+                .json({ code: error instanceof CollaborationError ? error.code : 'GROUP_ROLE_FAILED',
+                error: error instanceof Error ? error.message : '定位设置失败' });
+        }
+    });
     router.post('/collaboration-groups/:groupId/promote', (req, res) => {
         try {
             const { group, expectedUpdatedAt } = req.body ?? {};

package/dist/server/agent/collaborationPrompt.js

@@ -1,54 +1,117 @@
-const MESSAGE_LABELS = {
-    message: '消息',
-    ask: '问题',
-    reply: '回复',
-    task: '任务',
-    handoff: '交接',
-    done: '完成',
-};
+import { sanitizeCollaborationRole } from './collaborationStore.js';
+const SHELL_RULE = '─'.repeat(30);
+/** 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 = 8_192;
+/**
+ * Characters that would corrupt the delivery shell header `「X」群(N 个成员)`
+ * and the per-message `来自:X · kind` line: the quote brackets and the middle
+ * dot, which the render layer uses as structure, plus control sequences
+ * (C0 controls + DEL) that could inject terminal output. Legacy and federated
+ * names may carry them, so the render layer neutralizes them defensively;
+ * user-entered names are rejected at creation instead.
+ */
+export const COLLAB_NAME_FORBIDDEN = /[【】「」·\x00-\x1f\x7f]/;
+/** Render-safe name for shell header / per-message source lines: reserved
+ * bracket and delimiter characters become spaces (they would otherwise split
+ * the `「X」群` and `来自:X · kind` lines), control characters are
+ * neutralized, whitespace collapses, and the display length is capped. */
+export function sanitizeCollaborationName(name, max = 40) {
+    const cleaned = name
+        .replace(/[【】「」]/g, ' ')
+        .replace(/·/g, ' ')
+        .replace(/[\x00-\x1f\x7f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+}
+/** A single delivered message: `来自:X · kind` over a fenced body, with the
+ * reply route for agent-sourced messages 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) {
+    const lines = [`来自:${source} · ${message.kind}${fannedNames.length ? ' · 群发' : ''}`];
+    if (fannedNames.length)
+        lines.push(`同时发给了:${fannedNames.join('、')}`);
+    lines.push('', fence, message.content, fence);
+    if (message.task)
+        lines.push('', `任务上报:${JSON.stringify(message.task)}`);
+    if (message.fromSessionId)
+        lines.push('', `回复:td collab reply ${message.id} "回复内容" --text`);
+    return lines.join('\n');
+}
 export function formatCollaborationDelivery(input) {
     const groupsById = new Map(input.groups.map((group) => [group.id, group]));
     const sessionsById = new Map(input.sessions.map((session) => [session.sessionId, session]));
-    const messageBlocks = input.messages.map((message) => {
+    const blocks = [];
+    for (const message of input.messages) {
         const sourceSession = message.fromSessionId ? sessionsById.get(message.fromSessionId) : null;
         const source = message.fromSessionId
-            ? sourceSession?.name ?? message.fromSessionId
+            ? sanitizeCollaborationName(sourceSession?.name ?? message.fromSessionId)
             : '用户';
-        const group = groupsById.get(message.groupId)?.name ?? '协作组';
-        const body = Buffer.byteLength(message.content) > 8_192
-            ? `大消息已完整保存（${Buffer.byteLength(message.content)} 字节）。使用 td collab message get ${message.id} --json 获取正文；不要把这条提示当作任务正文。`
+        const bytes = Buffer.byteLength(message.content);
+        const body = bytes > MAX_INLINE_BODY_BYTES
+            ? `大消息已完整保存（${bytes} 字节）。使用 td collab message get ${message.id} --json 获取正文；不要把这条提示当作消息正文。`
             : message.content;
         const fence = '`'.repeat(Math.max(3, ...Array.from(body.matchAll(/`+/g), (match) => match[0].length + 1)));
-        const plainBody = input.messages.length === 1 && !/[\r\n`]/.test(body) && body.length <= 240;
-        return [
-            `【${group} · ${source}${['task', 'handoff', 'done'].includes(message.kind) ? ` · ${MESSAGE_LABELS[message.kind]}` : ''}】`,
-            ...(plainBody ? [body] : [fence, body, fence]),
-            ...(message.task ? [`任务上报：${JSON.stringify(message.task)}`] : []),
-            message.fromSessionId
-                ? `回复：\`td collab reply ${message.id} "回复内容" --text\``
-                : '用户消息：直接在当前会话处理，无需回复收件箱。',
-        ].join('\n');
-    });
+        const fannedNames = (message.fanOutIds ?? [])
+            .map((sessionId) => sanitizeCollaborationName(sessionsById.get(sessionId)?.name ?? sessionId));
+        blocks.push(formatCollaborationMessage({ ...message, content: body }, source, fannedNames, fence));
+    }
+    // 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).
+    // The member count rides along as the at-a-glance size of that group.
+    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} 个成员)`
+        : '';
     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?.name ?? '离线会话'}：\`td collab send ${sessionId} "消息内容" --text\``;
+        return `- ${session ? sanitizeCollaborationName(session.name) : '离线会话'}：\`td collab send ${sessionId} "消息内容" --text\``;
     });
     const unreachable = peerIds.filter((id) => sessionsById.get(id)?.status === 'service-unreachable');
-    const instructions = [
-        ...(peers.length ? ['联系其他成员：', ...peers] : []),
-        '更多操作：`td collab --help`。',
+    // Education (peer roster examples) decays once the session knows the group;
+    // the `--help` pointer stays permanently as the one-line entrance to the
+    // full command surface — everything else can be looked up from there.
+    const routingHelp = input.showRoutingHelp === false ? [] : (peers.length ? ['联系其他成员：', ...peers] : []);
+    const dynamicNotices = [
         ...(peerIds.some((id) => id.startsWith('remote:'))
             ? ['跨服务通信使用 td collab；转发客户端须保持运行，网页或 PWA 暂停后需返回前台继续转发。'] : []),
-        ...unreachable.map((id) => `注意：${sessionsById.get(id)?.name ?? id} 服务不可达，消息无法送达；仅可排队等待重连。`),
+        ...unreachable.map((id) => {
+            const session = sessionsById.get(id);
+            return `注意：${session ? sanitizeCollaborationName(session.name) : id} 服务不可达，消息无法送达；仅可排队等待重连。`;
+        }),
     ];
-    return [
-        ...(input.messages.length > 1 ? [`[Termdock 协作 · ${input.messages.length} 条]`, ''] : []),
-        messageBlocks.join('\n\n'),
-        '',
-        ...instructions,
-    ].join('\n');
+    const notes = [...routingHelp, ...dynamicNotices, '更多操作：`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.
+    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.
+    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.
+    lines.push(blocks.join('\n\n'), ...notes, SHELL_RULE);
+    return lines.join('\n');
 }