Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
feat(telegram): 官方 bot 进度、终稿、交互卡与命令菜单改由客户端经 msg.op 发布 (#5550)
Dash10b0f3e01a40
diff --git a/AGENTS.md b/AGENTS.mdindex d1b376f9c9..aa465ecbd4 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -88,6 +88,9 @@的术语照用,不自造译法;表里没有或拿不准的,在 `i18n/glossary.json` 加`status: "proposed"` 条目再讨论。门禁为 `pnpm check:i18n-glossary`,规则见`docs/dev-rules/engineering-conventions.md` §5.1。+- 修改个人 IM 渠道(`apps/desktop/src/main/im/**`)或官方 hook(`hook-control/**`)的+ 找/建任务、命令、排队与插话、输入拼装、事件观察、交互、收尾或停止逻辑前,必须先读+ `docs/dev-rules/im-turn-flow.md`(入口账本、状态清单、不变量与迁移批次)。- 新增或修改**任一 Telegram bot 的用户可见行为**(命令、消息呈现、收口策略、群行为、权限口径、附件与表情)前,必须先读能力台账 `docs/product-rules/telegram-bot-parity.md`:两个 bot 是两套架构,差异可以有但必须登记在表里;表里标「有意不同」的行**不要去diff --git a/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts b/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.tsindex 98d5cd8214..d67f944103 100644--- a/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts+++ b/apps/desktop/src/main/hook-control/__tests__/dispatcher.test.ts@@ -14,6 +14,10 @@ import { setMainLocale } from '../../i18n';import {HOOK_FEATURE_MESSAGE_OPS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,HOOK_FEATURE_TURN_DELIVERY,HOOK_FEATURE_TURN_REOPEN,type HookMessage,@@ -4846,3 +4850,570 @@ describe('官方 bot ack 表情(msg.op)', () => {expect(next.sent.filter((m) => m.type === 'msg.op')).toHaveLength(0);});});++describe('官方 Telegram 进度消息由客户端渲染(telegram-progress-ops-v1)', () => {+ const PROGRESS_FEATURES = [HOOK_FEATURE_MESSAGE_OPS, HOOK_FEATURE_TELEGRAM_PROGRESS_OPS];+ const progressOps = (sent: readonly HookMessage[]) =>+ sent.filter(+ (m): m is Extract<HookMessage, { type: 'msg.op' }> =>+ m.type === 'msg.op' && m.payload.purpose === 'turn-progress',+ );++ it('未协商: 只发 turn.progress, 一帧进度 msg.op 都没有(行为与旧版相同)', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = collector();+ d.onConnected('conn-1', c.send, [HOOK_FEATURE_MESSAGE_OPS]);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.calls[0].onProgress!('**工作中**');+ await vi.advanceTimersByTimeAsync(5_000);+ expect(c.ofType('turn.progress')).toHaveLength(1);+ expect(progressOps(c.sent)).toHaveLength(0);+ fr.finish();+ await tick();+ } finally {+ vi.useRealTimers();+ }+ });++ it('协商后: turn.progress 照发(续 lease), 进度消息首帧 send、后续 edit, done 冲刷排在 turn.end 之前', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = collector();+ d.onConnected('conn-1', c.send, PROGRESS_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ const onProgress = fr.calls[0].onProgress!;++ onProgress('**工作中**');+ expect(c.ofType('turn.progress')).toHaveLength(1);+ await vi.advanceTimersByTimeAsync(1_500);+ const [first] = progressOps(c.sent);+ expect(first.payload).toMatchObject({+ requestId: 'req-1',+ scope: { externalKey: 'telegram:group:bot:-100200:user-7:g1' },+ action: { kind: 'send', tier: 'html', text: '<b>工作中</b>' },+ });+ d.onMessageOpResult({ opId: first.payload.opId, ok: true, messageId: '700' });+ await tick();++ // 最后一帧还在 1.5s 尾沿窗口里就收口: 终稿栅栏同步冲刷, wire 上先于 turn.end。+ onProgress('**工作中**\n\n最后一帧');+ fr.finish();+ await tick();+ const lastEdit = c.sent.findIndex(+ (m) => m.type === 'msg.op' && m.payload.purpose === 'turn-progress' && m.payload.action.kind === 'edit',+ );+ const end = c.sent.findIndex((m) => m.type === 'turn.end');+ expect(lastEdit).toBeGreaterThan(-1);+ expect(lastEdit).toBeLessThan(end);+ expect((c.sent[lastEdit] as Extract<HookMessage, { type: 'msg.op' }>).payload.action).toMatchObject({+ kind: 'edit',+ messageId: '700',+ });++ // 收口后迟到的进度帧 / 节流定时器不再产出任何进度 op。+ const count = progressOps(c.sent).length;+ onProgress('迟到');+ await vi.advanceTimersByTimeAsync(5_000);+ expect(progressOps(c.sent)).toHaveLength(count);+ } finally {+ vi.useRealTimers();+ }+ });++ it('跨轮不串消息: 下一轮从新的 send 开始, opId 按各自 requestId 派生', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = collector();+ d.onConnected('conn-1', c.send, PROGRESS_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch({ requestId: 'r-a' }), c.send);+ await tick();+ fr.calls[0].onProgress!('第一轮');+ await vi.advanceTimersByTimeAsync(1_500);+ const a = progressOps(c.sent)[0];+ d.onMessageOpResult({ opId: a.payload.opId, ok: true, messageId: '1' });+ fr.finish();+ await tick();++ d.handleDispatch('conn-1', telegramDispatch({ requestId: 'r-b' }), c.send);+ await tick();+ fr.calls[1].onProgress!('第二轮');+ await vi.advanceTimersByTimeAsync(1_500);+ const b = progressOps(c.sent).filter((m) => m.payload.requestId === 'r-b');+ expect(b).toHaveLength(1);+ expect(b[0].payload.action.kind).toBe('send');+ expect(b[0].payload.opId.startsWith('r-b:')).toBe(true);+ // 上一轮的迟到回执不会被这一轮认领。+ d.onMessageOpResult({ opId: a.payload.opId, ok: true, messageId: '1' });+ fr.calls[1].onProgress!('第二轮继续');+ await vi.advanceTimersByTimeAsync(1_500);+ expect(progressOps(c.sent).filter((m) => m.payload.requestId === 'r-b')).toHaveLength(1);+ fr.finish();+ await tick();+ } finally {+ vi.useRealTimers();+ }+ });++ it('Slack 任务即使连接宣告了能力也不走进度 op', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = collector();+ d.onConnected('conn-1', c.send, PROGRESS_FEATURES);+ d.handleDispatch('conn-1', dispatch(), c.send);+ await tick();+ fr.calls[0].onProgress!('slack 进度');+ await vi.advanceTimersByTimeAsync(5_000);+ expect(progressOps(c.sent)).toHaveLength(0);+ fr.finish();+ await tick();+ } finally {+ vi.useRealTimers();+ }+ });+});++describe('官方 Telegram 终稿 / 交互卡 / 命令菜单由客户端发布', () => {+ type OpMessage = Extract<HookMessage, { type: 'msg.op' }>;+ const ALL_FEATURES = [+ HOOK_FEATURE_MESSAGE_OPS,+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ ];+ const ops = (sent: readonly HookMessage[], purpose?: string) =>+ sent.filter((m): m is OpMessage => m.type === 'msg.op' && (purpose === undefined || m.payload.purpose === purpose));++ /**+ * 带自动回执的连接: 每发一帧 msg.op 就在下一个微任务里按 responder 回执(模拟服务端)。+ * responder 返回 null = 不回执。onSend 在帧交出时同步回调(用来抓"那一刻"的账本)。+ */+ function respondingCollector(+ d: ReturnType<typeof makeDispatcher>['d'],+ responder: (payload: OpMessage['payload']) => Record<string, unknown> | null,+ onSend?: (m: HookMessage) => void,+ ) {+ const c = collector();+ let id = 500;+ const send = (m: HookMessage): boolean => {+ const ok = c.send(m);+ onSend?.(m);+ if (ok && m.type === 'msg.op') {+ const result = responder(m.payload);+ if (result) {+ queueMicrotask(() =>+ d.onMessageOpResult({ opId: m.payload.opId, ok: true, messageId: String(id++), ...result } as never),+ );+ }+ }+ return ok;+ };+ return { ...c, send };+ }++ it('协商终稿: 先写持久出箱、再经 msg.op 发布, 最后 turn.end 带 clientFinal.complete', async () => {+ const ledger = memoryTerminalLedger();+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner, terminalLedger: ledger });+ let ledgerAtFirstFinal: HookTerminalRecord | null | undefined;+ const c = respondingCollector(+ d,+ (p) => (p.action.kind === 'send' && p.action.tier === 'rich' ? { ok: false, channelErrorCode: 400, error: 'rich' } : {}),+ (m) => {+ if (m.type === 'msg.op' && m.payload.purpose === 'turn-final' && ledgerAtFirstFinal === undefined) {+ ledgerAtFirstFinal = ledger.get('conn-1', 'req-1');+ }+ },+ );+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({ finalText: '**答案**' });+ await tick(40);++ // 发布前出箱里已经有一份「交回服务端」版本的 turn.end(不带 clientFinal)。+ expect(ledgerAtFirstFinal?.delivery).toBe('pending');+ expect(ledgerAtFirstFinal?.turnEnd?.clientFinal).toBeUndefined();+ const finals = ops(c.sent, 'turn-final');+ expect(finals.map((m) => m.payload.action.kind)).toEqual(['send', 'send']);+ const endIndex = c.sent.findIndex((m) => m.type === 'turn.end');+ expect(endIndex).toBeGreaterThan(c.sent.indexOf(finals[finals.length - 1]));+ const end = c.last('turn.end')!.payload;+ expect(end.clientFinal).toEqual({ complete: true });+ expect(ledger.get('conn-1', 'req-1')?.turnEnd?.clientFinal).toEqual({ complete: true });+ });++ it('客户端终稿没有完整确认 → turn.end 带 clientFinal.complete=false(服务端照旧发布)', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = respondingCollector(d, (p) => (p.purpose === 'turn-final' ? null : {}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({ finalText: '答案' });+ await vi.advanceTimersByTimeAsync(3 * 31_000) // 首发 + 2 次原样重发各等满回执超时;+ await tick(20);+ const end = c.last('turn.end')!.payload;+ expect(end.clientFinal).toEqual({ complete: false });+ } finally {+ vi.useRealTimers();+ }+ });++ it('持久出箱写不进兜底帧: 不走客户端终稿, turn.end 交给服务端照旧发布', async () => {+ const ledger = memoryTerminalLedger();+ const set = ledger.set.bind(ledger);+ // 发布前那次 pending 写入失败(磁盘满 / 锁冲突), 之后的写入照常。+ let failNext = true;+ ledger.set = (record) => {+ if (failNext && record.delivery === 'pending') {+ failNext = false;+ return false;+ }+ return set(record);+ };+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner, terminalLedger: ledger });+ const c = respondingCollector(d, () => ({}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({ finalText: '答案' });+ await tick(20);+ expect(ops(c.sent, 'turn-final')).toHaveLength(0);+ const end = c.last('turn.end')!.payload;+ expect(end.clientFinal).toBeUndefined();+ expect(end.finalText).toBe('答案');+ });++ it('带附件的成功轮次不走客户端终稿: 不发 turn-final, turn.end 原样带附件交给服务端', async () => {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = respondingCollector(d, () => ({}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({+ finalText: '答案',+ attachments: [{ name: 'a.png', mimeType: 'image/png', dataBase64: 'AAAA' }],+ });+ await tick(20);+ expect(ops(c.sent, 'turn-final')).toHaveLength(0);+ const end = c.last('turn.end')!.payload;+ expect(end.clientFinal).toBeUndefined();+ expect(end.attachments).toHaveLength(1);+ });++ it('发布客户端终稿期间重连: 不重放出箱里的兜底 turn.end, 发布结束后才发正式帧', async () => {+ vi.useFakeTimers();+ try {+ const ledger = memoryTerminalLedger();+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner, terminalLedger: ledger });+ const c = respondingCollector(d, (p) => (p.purpose === 'turn-final' ? null : {}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({ finalText: '答案' });+ await tick(20);+ expect(ops(c.sent, 'turn-final').length).toBeGreaterThan(0);+ expect(ledger.get('conn-1', 'req-1')?.delivery).toBe('pending');++ const reconnected = respondingCollector(d, (p) => (p.purpose === 'turn-final' ? null : {}));+ d.onConnected('conn-1', reconnected.send, ALL_FEATURES);+ await tick(20);+ expect(reconnected.sent.filter((m) => m.type === 'turn.end')).toHaveLength(0);++ await vi.advanceTimersByTimeAsync(3 * 31_000) // 首发 + 2 次原样重发各等满回执超时;+ await tick(20);+ const ends = reconnected.sent.filter((m) => m.type === 'turn.end');+ expect(ends).toHaveLength(1);+ expect((ends[0] as Extract<HookMessage, { type: 'turn.end' }>).payload.clientFinal).toEqual({+ complete: false,+ });+ } finally {+ vi.useRealTimers();+ }+ });++ it('失败 / NO_REPLY / 未协商终稿能力: 不发 turn-final, turn.end 不带 clientFinal(行为与旧版相同)', async () => {+ for (const [features, outcome] of [+ [ALL_FEATURES, { status: 'error' as const, finalText: '', errorMessage: 'boom' }],+ [ALL_FEATURES, { finalText: 'NO_REPLY' }],+ [[HOOK_FEATURE_MESSAGE_OPS, HOOK_FEATURE_TELEGRAM_PROGRESS_OPS], { finalText: '答案' }],+ ] as const) {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = respondingCollector(d, () => ({}));+ d.onConnected('conn-1', c.send, [...features]);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish(outcome);+ await tick(20);+ expect(ops(c.sent, 'turn-final')).toHaveLength(0);+ expect(c.last('turn.end')!.payload.clientFinal).toBeUndefined();+ }+ });++ it('协商卡片: 用个人 bot 同一渲染经 msg.op 发卡(短按钮成对), 收口编辑清键盘并先于 turn.end; 不发 interaction.request', async () => {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = respondingCollector(d, () => ({}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ const req = fr.calls[0];+ req.onInteraction!({+ interactionId: 'i-1',+ kind: 'permission',+ title: '🔐 权限请求: Bash',+ body: '工具: `Bash`',+ buttons: [+ { id: 'perm:allow', label: '允许一次', style: 'primary' },+ { id: 'perm:always', label: '本任务总是允许', style: 'default' },+ { id: 'perm:deny', label: '拒绝', style: 'danger' },+ ],+ });+ await tick();+ const [open] = ops(c.sent, 'interaction-card');+ expect(open.payload).toMatchObject({ interactionId: 'i-1', requestId: 'req-1' });+ expect(open.payload.action).toMatchObject({+ kind: 'send',+ tier: 'html',+ text: '<b>🔐 权限请求: Bash</b>\n\n工具: <code>Bash</code>',+ // 与个人 bot 同一排布: label ≤12 字的两两并排。+ buttons: [+ [+ { token: 'perm:allow', label: '允许一次' },+ { token: 'perm:always', label: '本任务总是允许' },+ ],+ [{ token: 'perm:deny', label: '拒绝' }],+ ],+ });+ expect(c.ofType('interaction.request')).toHaveLength(0);++ req.onInteractionCancel!('i-1', '等待授权超时, 已拒绝该权限请求');+ fr.finish();+ await tick(30);+ const close = ops(c.sent, 'interaction-card').find((m) => m.payload.interactionClosed === true)!;+ expect(close.payload.action).toMatchObject({ kind: 'edit', buttons: [] });+ expect(c.sent.indexOf(close)).toBeLessThan(c.sent.findIndex((m) => m.type === 'turn.end'));+ expect(c.ofType('interaction.cancel')).toHaveLength(0);+ });++ it('发布客户端终稿期间服务端重投同一 task.dispatch: 只回放 ack, 不发兜底 turn.end', async () => {+ vi.useFakeTimers();+ try {+ const ledger = memoryTerminalLedger();+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner, terminalLedger: ledger });+ const c = respondingCollector(d, (p) => (p.purpose === 'turn-final' ? null : {}));+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.finish({ finalText: '答案' });+ await tick(20);+ expect(ledger.get('conn-1', 'req-1')?.delivery).toBe('pending');+ const acksBefore = c.ofType('task.ack').length;++ // 服务端没收到最初的 ack, 重投同一个 requestId。+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick(20);+ expect(c.ofType('task.ack').length).toBe(acksBefore + 1);+ expect(c.ofType('turn.end')).toHaveLength(0);+ expect(fr.calls).toHaveLength(1);++ await vi.advanceTimersByTimeAsync(3 * 31_000);+ await tick(20);+ const ends = c.ofType('turn.end');+ expect(ends).toHaveLength(1);+ expect(ends[0].payload.clientFinal).toEqual({ complete: false });+ } finally {+ vi.useRealTimers();+ }+ });++ it('终稿已发、卡片还在 drain 时重连: 仍不重放兜底帧, 正式 turn.end 带 clientFinal.complete', async () => {+ vi.useFakeTimers();+ try {+ const ledger = memoryTerminalLedger();+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner, terminalLedger: ledger });+ // 卡片收口编辑不回执 → drain 要等满上限; 终稿段正常确认。+ const responder = (p: OpMessage['payload']) =>+ p.purpose === 'interaction-card' && p.interactionClosed ? null : {};+ const c = respondingCollector(d, responder);+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ const req = fr.calls[0];+ req.onInteraction!({+ interactionId: 'i-1',+ kind: 'permission',+ title: '🔐 权限请求: Bash',+ body: '工具: `Bash`',+ buttons: [{ id: 'perm:allow', label: '允许一次', style: 'primary' }],+ });+ await tick();+ req.onInteractionCancel!('i-1', '已处理');+ fr.finish({ finalText: '答案' });+ await tick(20);+ expect(ops(c.sent, 'turn-final').length).toBeGreaterThan(0);+ expect(c.ofType('turn.end')).toHaveLength(0);++ const reconnected = respondingCollector(d, responder);+ d.onConnected('conn-1', reconnected.send, ALL_FEATURES);+ await tick(20);+ expect(reconnected.ofType('turn.end')).toHaveLength(0);++ await vi.advanceTimersByTimeAsync(6_000);+ await tick(20);+ const ends = reconnected.ofType('turn.end');+ expect(ends).toHaveLength(1);+ expect(ends[0].payload.clientFinal).toEqual({ complete: true });+ } finally {+ vi.useRealTimers();+ }+ });++ it('drain 超时后仍在途的卡片操作: 换账号重连后不经新账号的同名连接发出', async () => {+ vi.useFakeTimers();+ try {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ // 发卡撞 429, 要退避 20s: 这一轮收口时 drain(5s)等不到它。+ const c = respondingCollector(d, (p) =>+ p.purpose === 'interaction-card'+ ? { ok: false, channelErrorCode: 429, retryAfterMs: 20_000, error: 'Too Many Requests' }+ : {},+ );+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ fr.calls[0].onInteraction!({+ interactionId: 'i-1',+ kind: 'permission',+ title: '🔐 权限请求: Bash',+ body: '工具: `Bash`',+ buttons: [{ id: 'perm:allow', label: '允许一次', style: 'primary' }],+ });+ await tick();+ expect(ops(c.sent, 'interaction-card')).toHaveLength(1);+ fr.finish();+ await vi.advanceTimersByTimeAsync(6_000);+ await tick(20);+ expect(c.ofType('turn.end')).toHaveLength(1);++ await d.deactivateAccount();+ d.activateAccount();+ const next = respondingCollector(d, () => ({}));+ d.onConnected('conn-1', next.send, ALL_FEATURES);+ await vi.advanceTimersByTimeAsync(20_000);+ await tick(20);+ expect(ops(next.sent, 'interaction-card')).toHaveLength(0);+ expect(next.ofType('interaction.request')).toHaveLength(0);+ } finally {+ vi.useRealTimers();+ }+ });++ it('卡片 op 被明确拒绝 → 回落 interaction.request, 收口也走 interaction.cancel', async () => {+ const fr = fakeRunner();+ const { d } = makeDispatcher({ runner: fr.runner });+ const c = respondingCollector(d, (p) =>+ p.purpose === 'interaction-card' ? { ok: false, channelErrorCode: 400, error: "can't parse entities" } : {},+ );+ d.onConnected('conn-1', c.send, ALL_FEATURES);+ d.handleDispatch('conn-1', telegramDispatch(), c.send);+ await tick();+ const req = fr.calls[0];+ req.onInteraction!({ interactionId: 'i-2', kind: 'ask_user_question', title: '❓ 选哪个', body: 'x', buttons: [] });+ await tick(20);+ expect(c.ofType('interaction.request')).toHaveLength(1);+ req.onInteractionCancel!('i-2', '超时');+ await tick(20);+ expect(c.ofType('interaction.cancel')).toHaveLength(1);+ fr.finish();+ await tick(20);+ });++ it('命令菜单: 握手宣告 telegram-commands-v1 才下发 provider.commands.set', () => {+ const menus = [{ languageCode: null, commands: [{ command: 'new', description: 'New task' }] }];+ const fr = fakeRunner();+ const d = createHookDispatcher({+ getConnection: () => CONFIG,+ bindings: memoryBindings(),+ runner: fr.runner,+ telegramCommandMenus: () => menus,+ log: noopLog,+ });+ const without = collector();+ d.onConnected('conn-1', without.send, [HOOK_FEATURE_MESSAGE_OPS]);+ expect(without.ofType('provider.commands.set')).toHaveLength(0);+ const withMenu = collector();+ d.onConnected('conn-1', withMenu.send, [HOOK_FEATURE_TELEGRAM_COMMANDS]);+ expect(withMenu.last('provider.commands.set')?.payload).toEqual({ provider: 'telegram', menus });+ });+});++describe('渠道 /stop 走统一明确停止', () => {+ it('task.cancel 调 stopSessionExplicitly(与桌面 Stop 同一套清理), 不再直接 abort', async () => {+ const fr = fakeRunner();+ const abortSession = vi.fn(async () => undefined);+ const stopSessionExplicitly = vi.fn(async () => undefined);+ const d = createHookDispatcher({+ getConnection: () => CONFIG,+ bindings: memoryBindings(),+ runner: fr.runner,+ abortSession,+ stopSessionExplicitly,+ log: noopLog,+ });+ const c = collector();+ d.handleDispatch('conn-1', dispatch(), c.send);+ await tick();+ const sessionId = fr.calls[0].sessionId;+ d.cancel('conn-1', 'req-1');+ expect(stopSessionExplicitly).toHaveBeenCalledWith(sessionId);+ expect(abortSession).not.toHaveBeenCalled();+ fr.finish({ status: 'error', finalText: '', errorMessage: 'aborted' });+ await tick();+ expect(c.last('turn.end')?.payload.status).toBe('cancelled');+ });++ it('账号边界的中止不是用户喊停: 仍走 abortSession(不暂停 Goal)', async () => {+ const fr = fakeRunner();+ const abortSession = vi.fn(async () => undefined);+ const stopSessionExplicitly = vi.fn(async () => undefined);+ const d = createHookDispatcher({+ getConnection: () => CONFIG,+ bindings: memoryBindings(),+ runner: fr.runner,+ abortSession,+ stopSessionExplicitly,+ log: noopLog,+ });+ const c = collector();+ d.handleDispatch('conn-1', dispatch(), c.send);+ await tick();+ const deactivated = d.deactivateAccount();+ await tick();+ expect(abortSession).toHaveBeenCalledWith(fr.calls[0].sessionId);+ expect(stopSessionExplicitly).not.toHaveBeenCalled();+ fr.finish();+ await deactivated;+ });+});diff --git a/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts b/apps/desktop/src/main/hook-control/__tests__/session-runner.test.tsindex f8a219f41b..e45a3bf5ee 100644--- a/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts+++ b/apps/desktop/src/main/hook-control/__tests__/session-runner.test.ts@@ -87,6 +87,30 @@ const h = vi.hoisted(() => {};});+// 账号快照: 同一引用 = 账号没变(新任务从入口起按它复核账号代次)。测试可换引用模拟换账号。+const dbAccount = vi.hoisted(() => ({ current: {} as object }));+vi.mock('../../localDb/client/current', async (importOriginal) => ({+ ...(await importOriginal<typeof import('../../localDb/client/current')>()),+ getCurrentDbClientSnapshot: () => dbAccount.current,+}));++// 新任务经公共入口 openSession(模型准入)—— 准入本身由 sessionOpening 的测试覆盖, 这里+// 只把准入前的路由原样透传给建行回调。+vi.mock('../../localDb/sessionOpening.js', () => ({+ openSession: vi.fn(+ async (+ input: { body: Record<string, unknown> },+ commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>,+ ) => {+ const row = {+ ...input.body,+ providerId: input.body.providerId ?? null,+ fastMode: !!input.body.fastMode,+ };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ },+ ),+}));vi.mock('electron', () => ({BrowserWindow: { getAllWindows: () => [] },}));@@ -603,6 +627,50 @@ describe('hook session-runner 的 userSendAt 时序(未分类误判回归)', ()expect(h.touchUserSendInDb).toHaveBeenCalledTimes(1);});+ it('createOnly 建行后换了账号: 报失败, 不把补写落进新账号的库、不广播', async () => {+ h.createSessionRow.mockImplementationOnce(async () => {+ dbAccount.current = {};+ });+ const runner = createMakerHookSessionRunner({ log });++ const outcome = await runner.run(baseReq({ createOnly: true }));++ expect(outcome.status).toBe('error');+ expect(h.touchUserSendInDb).not.toHaveBeenCalled();+ expect(h.calls).not.toContain('created:sess-new');+ });++ it('新任务经 openSession 准入: 首条消息与 /new 都用准入后的路由建任务', async () => {+ const { openSession } = await import('../../localDb/sessionOpening.js');+ const admit = async (input: { body: Record<string, unknown> }, commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>) => {+ const row = { ...input.body, model: 'admitted-model', providerId: 'admitted-provider', fastMode: false };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ };+ vi.mocked(openSession).mockImplementationOnce(admit as never).mockImplementationOnce(admit as never);+ const runner = createMakerHookSessionRunner({ log });++ await runner.run(baseReq({}));+ expect(vi.mocked(openSession).mock.calls.at(-1)?.[0]).toMatchObject({ id: 'sess-new', body: { model: 'test-model' } });+ // 账号代次在读配置之前捕获, 一路带进准入(openSession 前后与写库前都复核)。+ expect(vi.mocked(openSession).mock.calls.at(-1)?.[0]).toMatchObject({ assertCurrent: expect.any(Function) });+ expect(fakeMaker.createSession).toHaveBeenCalledWith(+ expect.objectContaining({ id: 'sess-new', model: 'admitted-model', providerId: 'admitted-provider' }),+ );++ await runner.run(baseReq({ createOnly: true }));+ expect(h.createSessionRow).toHaveBeenCalledWith(+ expect.objectContaining({ id: 'sess-new', model: 'admitted-model' }),+ );+ });++ it('复用既有任务不经过准入(冷 resume 按库里的路由)', async () => {+ const { openSession } = await import('../../localDb/sessionOpening.js');+ vi.mocked(openSession).mockClear();+ const runner = createMakerHookSessionRunner({ log });+ await runner.run(baseReq({ isNew: false }));+ expect(openSession).not.toHaveBeenCalled();+ });+it('createOnly keeps the durable task when userSendAt enrichment fails', async () => {h.touchUserSendInDb.mockRejectedValueOnce(new Error('db busy'));const runner = createMakerHookSessionRunner({ log });@@ -830,6 +898,21 @@ describe('hook session-runner 的 userSendAt 时序(未分类误判回归)', ()expect(createCalls[0][1].content).toBe('hello');});+ it('普通新任务补写期间换了账号: 不再补写、不广播, 并在发送前终止这次派发', async () => {+ h.touchUserSendInDb.mockImplementationOnce(async () => {+ dbAccount.current = {};+ });+ const runner = createMakerHookSessionRunner({ log });+ const outcome = await runner.run(+ baseReq({ source: { im: 'telegram', channelName: 'Release topic', userText: 'hello' } }),+ );+ expect(outcome.status).toBe('error');+ expect(h.setSessionSourceInDb).not.toHaveBeenCalled();+ expect(h.calls).not.toContain('created:sess-new');+ const session = await fakeMaker.createSession.mock.results[0].value;+ expect(session.send).not.toHaveBeenCalled();+ });+it('官方 Telegram 新会话保留 provider 标记并把包命令留给 Desktop 确认', async () => {const runner = createMakerHookSessionRunner({ log });const outcome = await runner.run(diff --git a/apps/desktop/src/main/hook-control/__tests__/telegramTurnCarrier.test.ts b/apps/desktop/src/main/hook-control/__tests__/telegramTurnCarrier.test.tsnew file mode 100644index 0000000000..27601fa6da--- /dev/null+++ b/apps/desktop/src/main/hook-control/__tests__/telegramTurnCarrier.test.ts@@ -0,0 +1,546 @@+/**+ * 官方 Telegram 进度载体: msg.op 版 TelegramProgressDeps + 个人 bot 同一生命周期。+ * 覆盖: 首帧 send / 后续 edit、HTML 被拒回落 plain、not modified 视为成功、429 按+ * retryAfterMs 退避并合并到最新帧、回执未知时 send 原 opId 重发、服务端声明本轮+ * 进度不归客户端时停手、finish 的同步冲刷。+ */++import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import {+ MESSAGE_OP_ERROR_OUTCOME_UNKNOWN,+ MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,+ MESSAGE_OP_ERROR_RATE_LIMITED,+ type HookMessage,+ type HookMessageOpMessage,+ type MessageOpResultPayload,+} from '@cindy/slack-hook-protocol';++import { createMsgOpResultRouter, isTelegramTurnOpId } from '../telegramMsgOp';+import {+ createOfficialTelegramTurnCarrier,+ isClientFinalEligible,+ TELEGRAM_DM_COMPLETION_EFFECT_ID,+} from '../telegramTurnCarrier';++const THROTTLE_MS = 1500;+const log = { info: vi.fn(), warn: vi.fn() };++function harness(+ opts: { requestId?: string; resultTimeoutMs?: number; directMessage?: boolean } = {},+) {+ const router = createMsgOpResultRouter();+ const sent: HookMessageOpMessage[] = [];+ let online = true;+ const send = (m: HookMessage): boolean => {+ if (!online) return false;+ sent.push(m as HookMessageOpMessage);+ return true;+ };+ const carrier = createOfficialTelegramTurnCarrier({+ connectionId: 'conn-1',+ requestId: opts.requestId ?? 'req-1',+ externalKey: 'telegram:group:bot:-100:u:g1',+ directMessage: opts.directMessage ?? false,+ getSend: () => (online ? send : undefined),+ router,+ log,+ ...(opts.resultTimeoutMs !== undefined ? { resultTimeoutMs: opts.resultTimeoutMs } : {}),+ });+ const last = (): HookMessageOpMessage => sent[sent.length - 1]!;+ const reply = (result: Partial<MessageOpResultPayload> & { ok: boolean }): void => {+ router.settle({ opId: last().payload.opId, ...result });+ };+ return {+ router,+ carrier,+ sent,+ last,+ reply,+ setOnline: (v: boolean) => {+ online = v;+ },+ };+}++async function flushMicrotasks(): Promise<void> {+ for (let i = 0; i < 20; i++) await Promise.resolve();+}++async function advance(ms: number): Promise<void> {+ await vi.advanceTimersByTimeAsync(ms);+ await flushMicrotasks();+}++beforeEach(() => {+ vi.useFakeTimers();+ log.info.mockClear();+ log.warn.mockClear();+});+afterEach(() => {+ vi.useRealTimers();+});++describe('官方 Telegram 进度载体(msg.op)', () => {+ it('首帧 send(HTML, purpose=turn-progress), 后续 edit 同一条消息', async () => {+ const h = harness();+ h.carrier.update('**工作中**');+ // 与个人 bot 同一尾沿节流: 窗口结束前不出站。+ expect(h.sent).toHaveLength(0);+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(1);+ expect(h.last().payload).toMatchObject({+ requestId: 'req-1',+ purpose: 'turn-progress',+ scope: { externalKey: 'telegram:group:bot:-100:u:g1' },+ action: { kind: 'send', tier: 'html', text: '<b>工作中</b>' },+ });+ expect(isTelegramTurnOpId(h.last().payload.opId)).toBe(true);+ h.reply({ ok: true, messageId: '901' });+ await flushMicrotasks();++ h.carrier.update('**工作中**\n\n第二步');+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(2);+ expect(h.last().payload.action).toMatchObject({ kind: 'edit', messageId: '901', tier: 'html' });+ h.reply({ ok: true });+ await flushMicrotasks();+ });++ it('HTML 被拒(channelErrorCode=400) → 同一帧以 plain 原 markdown 重发, 换新 opId', async () => {+ const h = harness();+ h.carrier.update('坏 <标签');+ await advance(THROTTLE_MS);+ const htmlOp = h.last().payload;+ h.reply({ ok: false, channelErrorCode: 400, error: "Bad Request: can't parse entities" });+ await flushMicrotasks();+ expect(h.sent).toHaveLength(2);+ const plainOp = h.last().payload;+ expect(plainOp.action).toMatchObject({ kind: 'send', tier: 'plain', text: '坏 <标签' });+ expect(plainOp.opId).not.toBe(htmlOp.opId);+ h.reply({ ok: true, messageId: '7' });+ await flushMicrotasks();++ // edit 的 400 回落剥标签纯文本(与个人 editHtml 同一判据)。+ h.carrier.update('**粗体** 后续');+ await advance(THROTTLE_MS);+ h.reply({ ok: false, channelErrorCode: 400, error: "Bad Request: can't parse entities" });+ await flushMicrotasks();+ expect(h.last().payload.action).toMatchObject({+ kind: 'edit',+ messageId: '7',+ tier: 'plain',+ text: '粗体 后续',+ });+ });++ it('message is not modified 视为成功: 不回落、不重试', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.reply({ ok: true, messageId: '1' });+ await flushMicrotasks();+ h.carrier.update('B');+ await advance(THROTTLE_MS);+ h.reply({+ ok: false,+ channelErrorCode: 400,+ error: 'Bad Request: message is not modified: specified new message content is the same',+ });+ await flushMicrotasks();+ expect(h.sent).toHaveLength(2);+ // 同一帧不会再发(已视为显示成功)。+ await advance(THROTTLE_MS * 3);+ expect(h.sent).toHaveLength(2);+ });++ it('429 按 retryAfterMs 退避, 期间的新帧合并, 窗口后只发最新一帧', async () => {+ const h = harness();+ h.carrier.update('第 1 帧');+ await advance(THROTTLE_MS);+ h.reply({ ok: true, messageId: '1' });+ await flushMicrotasks();++ h.carrier.update('第 2 帧');+ await advance(THROTTLE_MS);+ const limited = h.last().payload;+ h.reply({ ok: false, channelErrorCode: 429, retryAfterMs: 10_000, error: 'Too Many Requests' });+ await flushMicrotasks();+ // 退避期间新帧只进缓冲, 不出站。+ h.carrier.update('第 3 帧');+ await advance(THROTTLE_MS);+ h.carrier.update('第 4 帧');+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(2);++ // retry_after 到点: 在途那次按 429 规则重试一次(新 opId), 之后合并发最新帧。+ await advance(10_000);+ expect(h.sent).toHaveLength(3);+ expect(h.last().payload.opId).not.toBe(limited.opId);+ h.reply({ ok: true });+ await flushMicrotasks();+ await advance(THROTTLE_MS);+ const texts = h.sent.map((m) => (m.payload.action as { text?: string }).text);+ expect(texts[texts.length - 1]).toBe('第 4 帧');+ expect(texts).not.toContain('第 3 帧');+ });++ it('回执未知(超时)时首帧 send 原样重发(同 opId 同正文), 对账成功后补 edit 到最新帧', async () => {+ const h = harness({ resultTimeoutMs: 5_000 });+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ const first = h.last().payload;+ await advance(5_000);+ h.carrier.update('A 继续');+ await advance(THROTTLE_MS);+ // 服务端按 opId + 内容指纹去重: 换正文会撞 IDEMPOTENCY_CONFLICT, 所以原样重发。+ expect(h.last().payload).toEqual(first);+ h.reply({ ok: true, messageId: '42' });+ await flushMicrotasks();+ expect(h.last().payload.action).toMatchObject({+ kind: 'edit',+ messageId: '42',+ text: 'A 继续',+ });+ });++ it('OUTCOME_UNKNOWN 与超时同处理: 不换 opId', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ const first = h.last().payload;+ h.reply({ ok: false, errorCode: MESSAGE_OP_ERROR_OUTCOME_UNKNOWN });+ await flushMicrotasks();+ h.carrier.update('B');+ await advance(THROTTLE_MS);+ expect(h.last().payload).toEqual(first);+ });++ it('服务端限速拒收(RATE_LIMITED + retryAfterMs)按 429 退避', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.reply({ ok: false, errorCode: MESSAGE_OP_ERROR_RATE_LIMITED, retryAfterMs: 4_000 });+ await flushMicrotasks();+ await advance(3_000);+ expect(h.sent).toHaveLength(1);+ await advance(1_000);+ expect(h.sent).toHaveLength(2);+ expect(h.last().payload.opId).toBe('req-1:progress:send:1');+ });++ it('发不出去(离线)不占在途槽, 恢复后以原 send opId 重试', async () => {+ const h = harness();+ h.setOnline(false);+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(0);+ h.setOnline(true);+ h.carrier.update('A 继续');+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(1);+ expect(h.last().payload.opId).toBe('req-1:progress:send:0');+ });++ it('明确失败后 send 换号, 不拿回同一份失败', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.reply({ ok: false, error: 'boom' });+ await flushMicrotasks();+ h.carrier.update('B');+ await advance(THROTTLE_MS);+ expect(h.last().payload.opId).toBe('req-1:progress:send:1');+ });++ it('服务端回 PROGRESS_UNAVAILABLE(私聊草稿 / 已收口) → 本轮不再发任何进度 op', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.reply({ ok: false, errorCode: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE });+ await flushMicrotasks();+ h.carrier.update('B');+ await advance(THROTTLE_MS * 3);+ expect(h.sent).toHaveLength(1);+ });++ it('NO_REPLY 哨兵(及其流式前缀)不落地 —— 与个人 driver 同一判据', async () => {+ const h = harness();+ h.carrier.update('NO_');+ await advance(THROTTLE_MS);+ h.carrier.update('NO_REPLY');+ await advance(THROTTLE_MS);+ expect(h.sent).toHaveLength(0);+ });++ it('finish: 管道空闲时同步交出最新帧(先于随后的 turn.end), 之后永不出站', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.reply({ ok: true, messageId: '1' });+ await flushMicrotasks();+ h.carrier.update('最后一帧');+ // 尾沿窗口还没到 —— finish 必须同步冲刷, 不能等定时器。+ h.carrier.finish();+ expect(h.sent).toHaveLength(2);+ expect(h.last().payload.action).toMatchObject({ kind: 'edit', text: '最后一帧' });+ h.carrier.update('迟到');+ await advance(THROTTLE_MS * 3);+ expect(h.sent).toHaveLength(2);+ });++ it('close 不冲刷; 关闭后迟到的 400 也不再回落', async () => {+ const h = harness();+ h.carrier.update('A');+ await advance(THROTTLE_MS);+ h.carrier.close();+ h.reply({ ok: false, channelErrorCode: 400, error: "can't parse entities" });+ await flushMicrotasks();+ expect(h.sent).toHaveLength(1);+ });++ it('不同轮次的 opId 互不相同(按 requestId 派生), 回执不串轮', async () => {+ const a = harness({ requestId: 'req-a' });+ const b = harness({ requestId: 'req-b' });+ a.carrier.update('A');+ b.carrier.update('B');+ await advance(THROTTLE_MS);+ expect(a.last().payload.opId).not.toBe(b.last().payload.opId);+ // b 的回执投到 a 的路由器上: a 不认, 仍在等自己的。+ expect(a.router.settle({ opId: b.last().payload.opId, ok: true, messageId: '2' })).toBe(false);+ });+});++describe('createMsgOpResultRouter', () => {+ it('发送失败 / 断线 / 超时都以 null 收口, 不悬挂', async () => {+ const router = createMsgOpResultRouter();+ const msg = {} as HookMessage;+ await expect(router.request('c', () => false, msg, 'op-a')).resolves.toBeNull();++ const pending = router.request('c', () => true, msg, 'op-b');+ router.failConnection('c');+ await expect(pending).resolves.toBeNull();++ const timed = router.request('c', () => true, msg, 'op-c', 1_000);+ await vi.advanceTimersByTimeAsync(1_000);+ await expect(timed).resolves.toBeNull();++ const ok = router.request('c', () => true, msg, 'op-d');+ expect(router.settle({ opId: 'op-d', ok: true })).toBe(true);+ await expect(ok).resolves.toEqual({ opId: 'op-d', ok: true });+ expect(router.settle({ opId: 'op-d', ok: true })).toBe(false);+ });+});++/**+ * 终稿用自动应答: 每发一帧就按 responder 的决定回执(在下一个微任务里, 模拟服务端异步)。+ * responder 返回 null = 不回执(回执未知, 靠超时收口)。+ */+function autoHarness(+ responder: (payload: HookMessageOpMessage['payload']) => Partial<MessageOpResultPayload> | null,+ opts: { directMessage?: boolean; resultTimeoutMs?: number } = {},+) {+ const router = createMsgOpResultRouter();+ const sent: HookMessageOpMessage[] = [];+ const carrier = createOfficialTelegramTurnCarrier({+ connectionId: 'conn-1',+ requestId: 'req-1',+ externalKey: 'telegram:dm:bot:42',+ directMessage: opts.directMessage ?? false,+ getSend: () => (m: HookMessage) => {+ const op = m as HookMessageOpMessage;+ sent.push(op);+ const result = responder(op.payload);+ if (result)+ queueMicrotask(() => router.settle({ opId: op.payload.opId, ok: true, ...result }));+ return true;+ },+ router,+ log,+ resultTimeoutMs: opts.resultTimeoutMs ?? 1_000,+ });+ return { carrier, sent };+}++let nextId = 100;+const okWithId = () => ({ ok: true, messageId: String(nextId++) });++describe('官方 Telegram 终稿由客户端发布(turn-final)', () => {+ it('有过程载体: Rich 新发终稿首段(私聊挂完成特效), 落地后删掉过程消息, 完整确认', async () => {+ const h = autoHarness(() => okWithId(), { directMessage: true });+ h.carrier.update('**工作中**');+ await advance(THROTTLE_MS);+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '**答案**' });+ await advance(0);+ await expect(done).resolves.toBe(true);+ const kinds = h.sent.map((m) => [+ m.payload.purpose,+ m.payload.action.kind,+ m.payload.finalPart,+ ]);+ expect(kinds).toEqual([+ ['turn-progress', 'send', undefined],+ ['turn-final', 'send', 0],+ ['turn-progress', 'delete', undefined],+ ]);+ expect(h.sent[1].payload.action).toMatchObject({+ tier: 'rich',+ text: '**答案**',+ effectId: TELEGRAM_DM_COMPLETION_EFFECT_ID,+ });+ });++ it('Rich 被拒(400) → 同一段 HTML 新发(换 opId); 群里不挂特效', async () => {+ const h = autoHarness((p) =>+ p.action.kind === 'send' && p.action.tier === 'rich'+ ? { ok: false, channelErrorCode: 400, error: 'Bad Request: rich message unsupported' }+ : okWithId(),+ );+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '**答案**' });+ await advance(0);+ await expect(done).resolves.toBe(true);+ const finals = h.sent.filter((m) => m.payload.purpose === 'turn-final');+ expect(finals.map((m) => (m.payload.action as { tier?: string }).tier)).toEqual([+ 'rich',+ 'html',+ ]);+ expect(finals[0].payload.opId).not.toBe(finals[1].payload.opId);+ expect(finals[1].payload.action).toMatchObject({ text: '<b>答案</b>' });+ expect((finals[1].payload.action as { effectId?: string }).effectId).toBeUndefined();+ });++ it.each([+ [403, 'Forbidden'],+ [429, 'Too Many Requests'],+ ])('Rich 收到其它确定 4xx(%i) → 同样回落 HTML, 不交回服务端', async (code, error) => {+ const h = autoHarness((p) =>+ p.action.kind === 'send' && p.action.tier === 'rich'+ ? { ok: false, channelErrorCode: code, error }+ : okWithId(),+ );+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(THROTTLE_MS * 10);+ await expect(done).resolves.toBe(true);+ const tiers = h.sent+ .filter((m) => m.payload.purpose === 'turn-final')+ .map((m) => (m.payload.action as { tier?: string }).tier);+ expect(tiers.at(-1)).toBe('html');+ });++ it('Rich 遇服务端自判拒绝码(无渠道错误码) → 不回落, 交回服务端', async () => {+ const h = autoHarness((p) =>+ p.purpose === 'turn-final' ? { ok: false, errorCode: 'PERSIST_FAILED' } : okWithId(),+ );+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(0);+ await expect(done).resolves.toBe(false);+ expect(h.sent.filter((m) => m.payload.purpose === 'turn-final')).toHaveLength(1);+ });++ it('长正文按个人 bot 同一分段逐段发布, finalPart 递增', async () => {+ const h = autoHarness((p) =>+ p.action.kind === 'send' && p.action.tier === 'rich'+ ? { ok: false, channelErrorCode: 404, error: 'Not Found' }+ : okWithId(),+ );+ const longText = Array.from({ length: 4 }, (_, i) => `段落 ${i} ${'字'.repeat(2000)}`).join(+ '\n\n',+ );+ const done = h.carrier.publishFinal({ status: 'ok', finalText: longText });+ await advance(0);+ await expect(done).resolves.toBe(true);+ const finals = h.sent.filter(+ (m) =>+ m.payload.purpose === 'turn-final' &&+ !(m.payload.action.kind === 'send' && m.payload.action.tier === 'rich'),+ );+ const parts = finals.map((m) => m.payload.finalPart);+ expect(parts).toEqual([...parts].sort((a, b) => a! - b!));+ expect(new Set(parts).size).toBe(parts.length);+ expect(finals.filter((m) => m.payload.action.kind === 'send').length).toBeGreaterThan(1);+ });++ it('终稿回执一直未知 → 同 opId 同正文有界重发对账, 仍未知才不确认(交回服务端)', async () => {+ const h = autoHarness((p) => (p.purpose === 'turn-final' ? null : okWithId()));+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(5_000);+ await expect(done).resolves.toBe(false);+ const finals = h.sent.filter((m) => m.payload.purpose === 'turn-final');+ // 首发 + 2 次原样重发; 不换 opId、不回落 HTML(没有应答就不能判定 Rich 没落地)。+ expect(finals).toHaveLength(3);+ expect(finals[1].payload).toEqual(finals[0].payload);+ expect(finals[2].payload).toEqual(finals[0].payload);+ });++ it('终稿回执未知、重发时服务端回显原结果 → 对上账, 照常确认', async () => {+ let seen = 0;+ const h = autoHarness((p) => {+ if (p.purpose !== 'turn-final') return okWithId();+ seen += 1;+ return seen === 1 ? { ok: false, errorCode: MESSAGE_OP_ERROR_OUTCOME_UNKNOWN } : okWithId();+ });+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(0);+ await expect(done).resolves.toBe(true);+ const finals = h.sent.filter((m) => m.payload.purpose === 'turn-final');+ expect(finals).toHaveLength(2);+ expect(finals[1].payload.opId).toBe(finals[0].payload.opId);+ });++ it('TURN_UNAVAILABLE → 不确认, 之后不再出站', async () => {+ const h = autoHarness(() => ({ ok: false, errorCode: 'TURN_UNAVAILABLE' }));+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(0);+ await expect(done).resolves.toBe(false);+ const count = h.sent.length;+ h.carrier.update('迟到');+ await advance(THROTTLE_MS * 2);+ expect(h.sent).toHaveLength(count);+ });++ it('私聊草稿模式: 进度与终稿都被收回 → 只试一次终稿 op, 不回落纯文本, 交回服务端', async () => {+ const h = autoHarness((p) =>+ p.purpose === 'turn-progress'+ ? { ok: false, errorCode: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE }+ : { ok: false, errorCode: 'TURN_UNAVAILABLE' },+ );+ h.carrier.update('工作中');+ await advance(THROTTLE_MS);+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(0);+ await expect(done).resolves.toBe(false);+ expect(h.sent.filter((m) => m.payload.purpose === 'turn-final')).toHaveLength(1);+ });++ it('进度被服务端收回后, 终稿是否可发由终稿 op 自己的回执决定(本端不预判)', async () => {+ const h = autoHarness((p) =>+ p.purpose === 'turn-progress'+ ? { ok: false, errorCode: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE }+ : okWithId(),+ );+ h.carrier.update('工作中');+ await advance(THROTTLE_MS);+ const done = h.carrier.publishFinal({ status: 'ok', finalText: '答案' });+ await advance(0);+ await expect(done).resolves.toBe(true);+ expect(h.sent.filter((m) => m.payload.purpose === 'turn-final')).toHaveLength(1);+ });+});++describe('isClientFinalEligible', () => {+ it('只覆盖成功、非空、非 NO_REPLY、不带附件的轮次', () => {+ expect(isClientFinalEligible({ status: 'ok', finalText: '答案' })).toBe(true);+ expect(isClientFinalEligible({ status: 'error', finalText: '答案' })).toBe(false);+ expect(isClientFinalEligible({ status: 'cancelled', finalText: '答案' })).toBe(false);+ expect(isClientFinalEligible({ status: 'ok', finalText: ' ' })).toBe(false);+ expect(isClientFinalEligible({ status: 'ok', finalText: ' NO_REPLY ' })).toBe(false);+ // 带附件整轮交回服务端: 持久兜底只存文本, 本端上传中途退出会丢附件。+ expect(+ isClientFinalEligible({+ status: 'ok',+ finalText: '答案',+ attachments: [{ name: 'a.png', mimeType: 'image/png', dataBase64: 'AA' }],+ }),+ ).toBe(false);+ expect(isClientFinalEligible({ status: 'ok', finalText: '答案', attachments: [] })).toBe(true);+ });+});diff --git a/apps/desktop/src/main/hook-control/dispatcher.ts b/apps/desktop/src/main/hook-control/dispatcher.tsindex e22a2318a1..d623aecf63 100644--- a/apps/desktop/src/main/hook-control/dispatcher.ts+++ b/apps/desktop/src/main/hook-control/dispatcher.ts@@ -47,6 +47,10 @@ import {makeTurnEnd,makeTurnProgress,makeTurnReopen,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,HOOK_FEATURE_TURN_DELIVERY,HOOK_FEATURE_TURN_REOPEN,type HookMessage,@@ -60,7 +64,10 @@ import {type TaskSource,type QueryRequestPayload,type TurnDeliveryPayload,+ type TurnEndClientFinal,type TurnEndPayload,+ type TelegramCommandMenu,+ makeProviderCommandsSet,} from '@cindy/slack-hook-protocol';import { createTelegramMessageLifecycle, type TelegramMessageLifecycle } from '@cindy/im';@@ -70,6 +77,18 @@ import type { GroupHistoryAccessScope } from '../im/shared/groupHistoryAccess.jsimport { groupHistoryAccessForExternalKey } from './groupHistoryScope.js';import { isPathWithin } from './paths.js';import { createAckReactions, type AckReactionTask } from './ackReactions.js';+import { createMsgOpResultRouter, isTelegramTurnOpId } from './telegramMsgOp.js';+import {+ createOfficialTelegramTurnCarrier,+ isClientFinalEligible,+ type ClientFinalInput,+ type OfficialTelegramTurnCarrier,+} from './telegramTurnCarrier.js';+import {+ createOfficialTelegramCardPublisher,+ type OfficialTelegramCardPublisher,+ type OfficialTelegramCardPublisherDeps,+} from './telegramCardOps.js';import type { HookConnectionConfig } from './store.js';import type { HookBindingStore } from './bindings.js';import { terminalDeliveryExpired } from './requestLedger.js';@@ -297,6 +316,13 @@ export interface HookDispatcherDeps {* maker.getSession(id)?.abort())。未注入时 cancel 只能收口排队中的任务。*/abortSession?: (sessionId: string) => Promise<void>;+ /**+ * 可选: 用户明确喊停(task.cancel)时的统一停止 —— 与桌面 Stop 同一套清理(撤自动续跑、+ * 取消恢复、暂停 Goal、停输入队列并中止当前一轮; 生产为 maker-ipc 的+ * stopSessionTurnExplicitly)。未注入时回落 abortSession。账号边界的中止不是用户+ * 喊停, 仍走 abortSession(不暂停 Goal)。+ */+ stopSessionExplicitly?: (sessionId: string) => Promise<void>;/*** 可选: 把 session 行置为 archived(session.archive 用; 生产为* patchSessionMetaInDb, 自带 sidebar 广播)。未注入时 archive 只清绑定。@@ -346,6 +372,11 @@ export interface HookDispatcherDeps {* eager behavior unless they opt out explicitly.*/accountInitiallyActive?: boolean;+ /**+ * 官方 Telegram 命令菜单(telegram-commands-v1): 以 desktop 命令注册表为准, 每次握手+ * 宣告该能力后经 provider.commands.set 下发。省略 = 不下发(服务端照旧用自己的)。+ */+ telegramCommandMenus?: () => TelegramCommandMenu[];log: { info(msg: string): void; warn(msg: string): void };}@@ -655,6 +686,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {buildContextPrefix,dialogue,abortSession,+ stopSessionExplicitly,archiveSessionRow,resolveInteraction,subscribeUiContinuation,@@ -662,6 +694,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {subscribeUiTurnDispatching,subscribeUiTurnUndispatched,accountInitiallyActive,+ telegramCommandMenus,log,} = deps;@@ -816,6 +849,16 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {>();/** 已请求取消的 connectionId + requestId(execute 收口时据此把结果改写为 cancelled)。 */const cancelRequested = new Set<string>();+ /**+ * 正在由本端发布客户端终稿的 connectionId + requestId。发布前写下的出箱兜底帧+ * (不带 clientFinal)只为崩溃重启准备: 本进程还在发布时重连, 不能拿它抢先重放,+ * 否则服务端提前接管、删掉刚落地的终稿段再自己发一遍。屏障一直保持到正式 turn.end+ * 进入发送 / 缓冲路径(终稿之后还要等卡片 drain)。+ */+ const publishingClientFinals = new Set<string>();+ /** 出箱里这条兜底帧此刻是否不能重放(本进程仍在发布它对应的客户端终稿)。重连扫描与 task.dispatch 重投共用。 */+ const isPublishingClientFinal = (connectionId: string, requestId: string): boolean =>+ publishingClientFinals.has(ackKey(connectionId, requestId));/** 每连接最近一次 welcome 宣告的能力集(turn.reopen 的 feature gate)。 */const serverFeatures = new Map<string, readonly string[]>();// 官方 bot 的 ack 表情(👀 → 👍/👎) —— 个人 bot 早有, 官方侧靠 msg.op 补上。@@ -828,6 +871,180 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {emojiReactions: () => emojiReactionsMode,log,});+ /** 本端驱动的 Telegram msg.op(进度 / 终稿 / 卡片)的请求/回执配对(所有轮次共用)。 */+ const telegramOpRouter = createMsgOpResultRouter();+ /** 仍在驱动消息的轮次载体与卡片发布器(账号切换 / dispose 时统一停下)。 */+ const activeTurnCarriers = new Set<OfficialTelegramTurnCarrier>();+ const activeCardPublishers = new Set<OfficialTelegramCardPublisher>();+ const closeTelegramTurnOps = (): void => {+ for (const carrier of [...activeTurnCarriers]) carrier.close();+ activeTurnCarriers.clear();+ for (const publisher of [...activeCardPublishers]) publisher.dispose();+ activeCardPublishers.clear();+ telegramOpRouter.failAll();+ };+ /** 该连接最近一次 welcome 是否同时宣告了 msg-op-v1 与 feature; 能力快照缺席(离线)= undefined。 */+ const telegramOpsNegotiated = (connectionId: string, feature: string): boolean | undefined => {+ const features = serverFeatures.get(connectionId);+ if (features === undefined) return undefined;+ return features.includes(HOOK_FEATURE_MESSAGE_OPS) && features.includes(feature);+ };++ /**+ * 一轮官方 Telegram 的消息载体(只在 telegram 任务上建): 进度消息与成功终稿。+ *+ * 进度: 双方都宣告 telegram-progress-ops-v1 时, 首帧起由本端渲染并经 msg.op 驱动+ * (个人 bot 同一个 handle, 见 telegramTurnCarrier.ts); 否则什么都不做, 服务端照旧+ * 渲染 turn.progress。turn.progress 由调用方**照发**(lease)。协商按帧现查: 断线期间+ * 能力快照缺席只跳过这一帧; 新 welcome 明确不再宣告(滚动发布落到旧节点)时本轮停止 ——+ * 旧节点会自己渲染 turn.progress。+ *+ * 终稿: 宣告 telegram-final-ops-v1 且这一轮可由本端发布(isClientFinalEligible)时,+ * 用同一个 handle 的 finalize 发布, 返回 turn.end 要带的 clientFinal; 否则冲刷最后+ * 一帧进度后停下, 返回 null(服务端照旧发布)。+ */+ function telegramTurnCarrier(+ connectionId: string,+ requestId: string,+ externalKey: string,+ accountGeneration: number,+ ): {+ update(markdown: string): void;+ /** 不由本端发布终稿时的收口: 冲刷最后一帧进度后停下(wire 上先于 turn.end)。 */+ finish(): void;+ /**+ * 由本端发布成功终稿; 不发布(未协商 / 不适用)时等同 finish() 并返回 null。+ * `beforePublish` 在真正发出第一条终稿 op 之前同步调用(调用方在此把 turn.end+ * 写进持久出箱, 保证发布中途崩溃时服务端仍能按出箱重放兜底); 它返回 false(兜底+ * 没写进去)时同样不发布, 交回服务端。+ */+ publishFinal(+ input: ClientFinalInput,+ beforePublish?: () => boolean,+ ): Promise<TurnEndClientFinal | null>;+ close(): void;+ } {+ let carrier: OfficialTelegramTurnCarrier | null = null;+ let progressLost = false;+ let stopped = false;+ const ensureCarrier = (): OfficialTelegramTurnCarrier => {+ if (!carrier) {+ carrier = createOfficialTelegramTurnCarrier({+ connectionId,+ requestId,+ externalKey,+ directMessage: deriveLaneKind(externalKey) === 'dm',+ getSend: () => sendForGeneration(connectionId, accountGeneration),+ router: telegramOpRouter,+ log,+ });+ activeTurnCarriers.add(carrier);+ }+ return carrier;+ };+ const stop = (): void => {+ stopped = true;+ if (carrier) activeTurnCarriers.delete(carrier);+ };+ return {+ update(markdown) {+ if (stopped || progressLost) return;+ const negotiated = telegramOpsNegotiated(connectionId, HOOK_FEATURE_TELEGRAM_PROGRESS_OPS);+ if (negotiated === undefined) return;+ if (!negotiated) {+ // 已经由本端建过进度消息: 新节点不认这份能力, 本轮进度到此为止(旧节点自己渲染)。+ if (carrier) progressLost = true;+ return;+ }+ ensureCarrier().update(markdown);+ },+ finish() {+ carrier?.finish();+ stop();+ },+ async publishFinal(input, beforePublish) {+ if (stopped) return null;+ const negotiated =+ telegramOpsNegotiated(connectionId, HOOK_FEATURE_TELEGRAM_FINAL_OPS) === true;+ if (!negotiated || !isClientFinalEligible(input)) {+ carrier?.finish();+ stop();+ return null;+ }+ const target = ensureCarrier();+ if (beforePublish && !beforePublish()) {+ target.finish();+ stop();+ return null;+ }+ try {+ return { complete: await target.publishFinal(input) };+ } finally {+ stop();+ }+ },+ close() {+ carrier?.close();+ stop();+ },+ };+ }++ /**+ * 一轮官方 Telegram 的交互卡出口: 双方宣告 telegram-card-ops-v1 时由本端渲染并经+ * msg.op 发布(见 telegramCardOps.ts), 否则走 interaction.request / cancel 旧路径。+ * 每张卡在打开那一刻定路径, 收口跟着它走, 两条路径不混用。+ */+ function telegramCardPublisher(+ connectionId: string,+ requestId: string,+ externalKey: string,+ accountGeneration: number,+ legacy: OfficialTelegramCardPublisherDeps['legacy'],+ ): OfficialTelegramCardPublisherDeps['legacy'] & {+ /** 等在途的发卡 / 收口编辑结束(有界), 然后不再纳入账号切换的统一停止 —— 这一轮已收口。 */+ drain(): Promise<void>;+ } {+ let publisher: OfficialTelegramCardPublisher | null = null;+ const clientCards = new Set<string>();+ return {+ open(card) {+ if (telegramOpsNegotiated(connectionId, HOOK_FEATURE_TELEGRAM_CARD_OPS) !== true) {+ legacy.open(card);+ return;+ }+ if (!publisher) {+ publisher = createOfficialTelegramCardPublisher({+ connectionId,+ requestId,+ externalKey,+ getSend: () => sendForGeneration(connectionId, accountGeneration),+ router: telegramOpRouter,+ legacy,+ log,+ });+ activeCardPublishers.add(publisher);+ }+ clientCards.add(card.interactionId);+ publisher.open(card);+ },+ close(interactionId, reason) {+ if (publisher && clientCards.delete(interactionId)) {+ publisher.close(interactionId, reason);+ return;+ }+ legacy.close(interactionId, reason);+ },+ async drain() {+ if (!publisher) return;+ await publisher.drain();+ // 这一轮已收口: 从账号切换的统一停止集合里摘掉, 免得每轮一个、只增不减。+ // 迟到的收口编辑(如共享权限在桌面端被决定)与 drain 超时后仍在途的操作仍可经+ // 闭包里的 publisher 发出, 但发送器绑定本轮账号代次: 换账号后视同离线。+ activeCardPublishers.delete(publisher);+ },+ };+ }/*** 以失败收口、**还等着被续跑**的任务, 按 sessionId 记账(见协议阶段 18)。*@@ -974,6 +1191,18 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {return accountActive && generation === accountGeneration;}+ /**+ * 一轮的出站发送器: 只在这一轮所属的账号代次仍是当前代次时给出连接, 否则视同离线。+ * 换账号后同名 connectionId 可能已是新账号的连接 —— 迟到的卡片收口、drain 超时后仍在+ * 途的操作、429 退避后的重试都不能借它发出旧账号的内容。+ */+ function sendForGeneration(+ connectionId: string,+ generation: number,+ ): ((m: HookMessage) => boolean) | undefined {+ return isCurrentGeneration(generation) ? sendFns.get(connectionId) : undefined;+ }+function ackKey(connectionId: string, requestId: string): string {return `${connectionId} ${requestId}`;}@@ -1294,6 +1523,16 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {requestId,entry.source,);+ // 续跑轮同样由本端驱动进度消息(新建一条, 不改写被续的旧终稿 —— 那条由服务端+ // 在终稿时原位修正, 本轮进度消息随后由服务端清理)。+ const turnCarrier = messageLifecycle+ ? telegramTurnCarrier(+ entry.connectionId,+ requestId,+ entry.externalKey,+ entry.accountGeneration,+ )+ : null;let claimed = false;// runner 可能在 watch() 里**同步**收口(会话已不在进程里就直接 onAbandon),// 那时 cancelWatch 还没赋值 —— 用这个标记决定要不要登记, 不去碰它。@@ -1335,6 +1574,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {const cleanup = (): void => {runningByRequest.delete(requestKey);cancelRequested.delete(requestKey);+ turnCarrier?.close();detach();};const cancelWatch = watch({@@ -1381,12 +1621,17 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {if (messageLifecycle && !messageLifecycle.acceptProgress()) return;const send = sendFns.get(entry.connectionId);if (send) send(makeTurnProgress({ requestId, text }));+ turnCarrier?.update(text);},// 停止观察即摘账 —— 成功收口还要异步收集附件, 那段时间它不该再被算作"在观察的// 那一轮"(否则排在后面的桌面消息一 dispatch 就被误判成顶替)。发帧的闭包照旧存活。onSettling: detach,onEnd: (outcome) => {const wasCancelled = cancelRequested.has(requestKey);+ // 终稿栅栏前冲刷最新进度帧(wire 上排在 turn.end 之前); 撤销 / 换账号则不冲刷。+ if (!revoked && claimed && isCurrentGeneration(entry.accountGeneration)) {+ turnCarrier?.finish();+ }cleanup();if (revoked || !claimed || !isCurrentGeneration(entry.accountGeneration)) return;const status: 'ok' | 'error' | 'cancelled' = wasCancelled ? 'cancelled' : outcome.status;@@ -1472,7 +1717,10 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {isClaimed: () => claimed,cancel: (silent: boolean, noRemember: boolean) => {// revoked 是"连迟到的帧都别发"的开关 —— 只有连接已断时才该置位。- if (silent) revoked = true;+ if (silent) {+ revoked = true;+ turnCarrier?.close();+ }if (noRemember) denyRemember = true;cancelWatch();},@@ -1502,17 +1750,50 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {task.requestId,task.run.source,);+ const turnCarrier = messageLifecycle+ ? telegramTurnCarrier(+ task.connectionId,+ task.requestId,+ task.externalKey,+ task.accountGeneration,+ )+ : null;// 进度快照直发不缓存: 断线期间的中间帧没有补发价值(turn.end 会带最终- // 结果), 发送失败静默丢弃即可+ // 结果), 发送失败静默丢弃即可。协商了客户端进度时 turn.progress 仍照发+ // (服务端靠它续 lease), 进度消息本身由 turnCarrier 经 msg.op 驱动。const onProgress = (text: string): void => {if (!isCurrentGeneration(task.accountGeneration)) return;if (messageLifecycle && !messageLifecycle.acceptProgress()) return;const send = sendFns.get(task.connectionId);if (send) send(makeTurnProgress({ requestId: task.requestId, text }));+ turnCarrier?.update(text);};// 交互卡同样直发不缓存: 连接不在线时用户本来就看不到卡, runner 侧的// 交互超时会按安全默认自决, 任务不会卡死+ const legacyCards: OfficialTelegramCardPublisherDeps['legacy'] = {+ open(card) {+ const send = sendForGeneration(task.connectionId, task.accountGeneration);+ if (send) send(makeInteractionRequest({ requestId: task.requestId, ...card }));+ },+ close(interactionId, reason) {+ const send = sendForGeneration(task.connectionId, task.accountGeneration);+ if (send) {+ send(makeInteractionCancel({ requestId: task.requestId, interactionId, reason }));+ }+ },+ };+ // 官方 Telegram 协商了 telegram-card-ops-v1 时卡片由本端渲染发布, 否则(含 Slack /+ // X)走 interaction.request / cancel 旧路径。+ const cards = messageLifecycle+ ? telegramCardPublisher(+ task.connectionId,+ task.requestId,+ task.externalKey,+ task.accountGeneration,+ legacyCards,+ )+ : null;const onInteraction = (card: {interactionId: string;kind: string;@@ -1521,13 +1802,11 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {buttons: InteractionButton[];}): void => {if (!isCurrentGeneration(task.accountGeneration)) return;- const send = sendFns.get(task.connectionId);- if (send) send(makeInteractionRequest({ requestId: task.requestId, ...card }));+ (cards ?? legacyCards).open(card);};const onInteractionCancel = (interactionId: string, reason: string): void => {if (!isCurrentGeneration(task.accountGeneration)) return;- const send = sendFns.get(task.connectionId);- if (send) send(makeInteractionCancel({ requestId: task.requestId, interactionId, reason }));+ (cards ?? legacyCards).close(interactionId, reason);};let outcome: HookRunOutcome;@@ -1618,6 +1897,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {runningByRequest.delete(requestKey);pendingGroupAdmissions.delete(requestKey);if (!isCurrentGeneration(task.accountGeneration)) {+ turnCarrier?.close();cancelRequested.delete(requestKey);running.delete(sessionId);return;@@ -1628,7 +1908,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {const status: 'ok' | 'error' | 'cancelled' = wasCancelled ? 'cancelled' : outcome.status;// 协议约束: error 必须带非空 errorMessage, ok / cancelled 必须为 nullconst isError = status === 'error';- const turnEnd: TurnEndPayload = {+ let turnEnd: TurnEndPayload = {requestId: task.requestId,externalKey: task.externalKey,sessionId,@@ -1644,15 +1924,56 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {// outbox path. A late progress callback from the observer must never write// over the answer after this point.const finalIntent = messageLifecycle?.beginFinal() ?? null;+ const terminalRecord = {+ connectionId: task.connectionId,+ requestId: task.requestId,+ ack: task.ack,+ };+ let persistedBeforePublish = false;+ const publishingKey = ackKey(task.connectionId, task.requestId);+ if (turnCarrier) {+ // 官方 Telegram: 协商了客户端终稿且这一轮适用时, 用个人 bot 同一套收口经 msg.op+ // 发布; 否则冲刷最后一帧进度(wire 上先于 turn.end)后停下, 由服务端照旧发布。+ // 发布前先把不带 clientFinal 的 turn.end 写进持久出箱: 中途崩溃时重启重放的是+ // 「交回服务端」那一版, 服务端删掉已落地的客户端终稿段并自己发布, 终稿必达不降级。+ const clientFinal = await turnCarrier.publishFinal(+ { status, finalText: turnEnd.finalText, attachments: turnEnd.attachments },+ () => {+ persistedBeforePublish = persistTerminal({+ ...terminalRecord,+ turnEnd: durableTurnEnd(turnEnd),+ delivery: 'pending',+ });+ // 兜底写不进出箱就不走本端发布: 发布中途退出时服务端将收不到任何收口。没配+ // 出箱(测试)时与旧路径一样本就没有持久兜底, 照常发布。+ const durable = persistedBeforePublish || !terminalLedger;+ if (durable) publishingClientFinals.add(publishingKey);+ return durable;+ },+ );+ // 带附件的轮次不走本端发布(isClientFinalEligible), 这里的 turnEnd 不含附件。+ if (clientFinal) turnEnd = { ...turnEnd, clientFinal };+ }+ // 收口编辑先于 turn.end 到达服务端(否则服务端的收口清扫会先把卡片当成未收口)。+ await cards?.drain();+ if (!isCurrentGeneration(task.accountGeneration)) {+ // 发布期间换了账号: 与上面的早退同一语义(不再以旧账号回推), 发布前写下的出箱条目+ // 一并作废, 免得换回该账号时被重放。+ if (persistedBeforePublish) markTerminalSent(task.connectionId, task.requestId);+ publishingClientFinals.delete(publishingKey);+ running.delete(sessionId);+ return;+ }// Protocol idempotency replays only the original ACK. The terminal record// is written as a pending outbox entry before sending; an offline frame// stays buffered in memory until onConnected flushes the full payload.sendOrBuffer(task.connectionId, makeTurnEnd(turnEnd), {- connectionId: task.connectionId,- requestId: task.requestId,- ack: task.ack,+ ...terminalRecord,turnEnd: durableTurnEnd(turnEnd),});+ // 屏障撤在正式帧进入发送 / 缓冲路径之后: 终稿发完到这里还隔着卡片 drain(最长数秒),+ // 这段时间重连仍不能拿出箱里的兜底帧抢先重放。+ publishingClientFinals.delete(publishingKey);if (messageLifecycle && finalIntent) {messageLifecycle.markFinalSent(finalIntent);if (messageLifecycle.beginCleanup()) messageLifecycle.finishCleanup();@@ -2232,6 +2553,10 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {cacheAck(connectionId, terminalReplay.ack);const ackDelivered = send(makeTaskAck(terminalReplay.ack));if (!terminalReplay.turnEnd) return;+ // 本进程仍在发布这一轮的客户端终稿: 出箱里的是不带 clientFinal 的兜底帧, 重放会让+ // 服务端提前接管。只回放 ack, 正式 turn.end 发布结束后由正常路径发出(重启后集合为空,+ // 兜底照常重放)。+ if (isPublishingClientFinal(connectionId, payload.requestId)) return;// 投递时效在这里也生效, 规则统一: **过线的终稿一律不再发出**, 包括 server// 显式重投这一支。ack 已经回放了 —— server 由此知道这个 requestId 我们受理并// 处理过, 不会再叫一次 Agent; 缺的只是一份它自己也已经放弃发布的终稿(服务端@@ -2460,6 +2785,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {accountActive = false;accountGeneration += 1;clearRecoveryDeliveries();+ closeTelegramTurnOps();if (accountDeactivation !== null) {await accountDeactivation;return;@@ -2755,11 +3081,14 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {if (runningEntry !== undefined && runningEntry.connectionId === connectionId) {const sessionId = runningEntry.sessionId;cancelRequested.add(requestKey);- log.info(`hook task ${requestId} cancel requested (aborting session ${sessionId})`);- if (abortSession) {- void abortSession(sessionId).catch((err) => {+ log.info(`hook task ${requestId} cancel requested (stopping session ${sessionId})`);+ // 渠道里的 /stop 是用户明确喊停: 与桌面 Stop 同一套清理, 不只是 abort ——+ // 否则已排期的自动续跑会在喊停后原地复活, 进行中的 Goal 也会接着跑。+ const stop = stopSessionExplicitly ?? abortSession;+ if (stop) {+ void stop(sessionId).catch((err) => {log.warn(- `abortSession failed for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`,+ `hook stop failed for ${sessionId}: ${err instanceof Error ? err.message : String(err)}`,);});}@@ -2770,6 +3099,8 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {},onDisconnected(connectionId) {sendFns.delete(connectionId);+ // 在等的进度回执不会再来: 立刻按"回执未知"收口(send 下一窗口原 opId 重发)。+ telegramOpRouter.failConnection(connectionId);for (const pending of pendingDeliveryTurnEnds.values()) {if (pending.connectionId !== connectionId || pending.timer === null) continue;clearTimeout(pending.timer);@@ -2793,6 +3124,7 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {},dispose() {clearRecoveryDeliveries();+ closeTelegramTurnOps();unsubscribeUiContinuation?.();unsubscribeUiIntervention?.();unsubscribeUiTurnDispatching?.();@@ -2810,6 +3142,9 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {for (const key of [...pendingDeliveryTurnEnds.keys()]) clearPendingDelivery(key);},onMessageOpResult(payload: MessageOpResultPayload) {+ // 进度操作的回执(含等待方已超时让位后的迟到回执)只归进度载体, 不落到+ // 表情的失败日志里。+ if (telegramOpRouter.settle(payload) || isTelegramTurnOpId(payload.opId)) return;recoveryDeliveries.get(payload.opId)?.(payload.ok);// 带上按连接取发送函数的钩子: 群限制了可用表情时要用基础款回落一次,// 而该发到哪条连接由 ackReactions 自己记的 task 决定。@@ -2827,6 +3162,17 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {// 老实例不宣告 turn.reopen 时必须立刻停用回流, 不能拿上一次的快照发帧。serverFeatures.set(connectionId, features ? [...features] : []);sendFns.set(connectionId, send);+ // 官方 Telegram 命令菜单以本端注册表为准: 每次握手都重发一次(服务端只存内存,+ // 重启后到本端重连前用它自己的默认菜单), 文案跟着桌面端版本走。+ if (telegramCommandMenus && features?.includes(HOOK_FEATURE_TELEGRAM_COMMANDS)) {+ try {+ send(makeProviderCommandsSet({ provider: 'telegram', menus: telegramCommandMenus() }));+ } catch (err) {+ log.warn(+ `telegram command menu not sent: ${err instanceof Error ? err.message : String(err)}`,+ );+ }+ }// 断线时没送出去的终态表情在这里补 —— 否则那条消息永远挂着 👀。// opId 由 requestId 派生, 服务端按它去重, 补发不会打出第二个。ackReactions.onReconnected(connectionId, send);@@ -2910,6 +3256,8 @@ export function createHookDispatcher(deps: HookDispatcherDeps): HookDispatcher {// durable frame during the same reconnect attempt.if (flushedRequestIds.has(pending.requestId)) continue;if (!pending.turnEnd) continue;+ // 本进程正在发布客户端终稿: 兜底帧留给崩溃重启, 发布结束后由正常路径发送。+ if (isPublishingClientFinal(connectionId, pending.requestId)) continue;if (deliveryAck) {// 已在 ACK 缓冲中的条目由本函数开头的循环重放, 不再用文本帧重复补发。if (pendingDeliveryTurnEnds.has(ackKey(connectionId, pending.requestId))) continue;diff --git a/apps/desktop/src/main/hook-control/ipc.ts b/apps/desktop/src/main/hook-control/ipc.tsindex 1ade4c64ec..e66248fcd9 100644--- a/apps/desktop/src/main/hook-control/ipc.ts+++ b/apps/desktop/src/main/hook-control/ipc.ts@@ -21,6 +21,9 @@ import { isModelVisible, visibleModelUnion } from '@cindy/model-providers';import { BRAND_NAME } from '@cindy/maker-shared/branding';import { createLogger } from '../logger.js';+import { t } from '../i18n.js';+import { buildOfficialBotCommandMenus } from '../im/shared/botCommands.js';+import { stopSessionTurnExplicitly } from '../maker-ipc/register.js';import { getMaker, restartCodexAfterAuthModeChange } from '../maker-host/index.js';import { shutdownCodexEnvironment } from '../mcp-integrations/codexEnvironment.js';import { getDesktopProviderService } from '../maker-host/createDesktopProviderService.js';@@ -536,6 +539,9 @@ function ensureInstances(): { store: SlackHookStore; manager: HookControlManager}await session.abort();},+ // 渠道 /stop(task.cancel): 与桌面 Stop 同一套清理(撤续跑 / 取消恢复 / 暂停 Goal /+ // 停输入队列并中止当前一轮), 见 docs/dev-rules/im-turn-flow.md 不变量 9。+ stopSessionExplicitly: (sessionId) => stopSessionTurnExplicitly(sessionId),// session.archive 的归档出口: 与 device-link 远程归档同一条// patchSessionMetaInDb 路径(落库 + sessions:patched 广播, sidebar 即时移出)archiveSessionRow: async (sessionId) => {@@ -550,6 +556,9 @@ function ensureInstances(): { store: SlackHookStore; manager: HookControlManagersubscribeUiTurnDispatching: onUiTurnDispatching,subscribeUiTurnUndispatched: onUiTurnUndispatched,accountInitiallyActive: false,+ // 官方 Telegram 命令菜单以 desktop 注册表为准(telegram-commands-v1), 按 Telegram+ // 用户语言各渲染一份。+ telegramCommandMenus: () => buildOfficialBotCommandMenus((key, locale) => t(key, locale)),log,});manager = createHookControlManager({diff --git a/apps/desktop/src/main/hook-control/manager.ts b/apps/desktop/src/main/hook-control/manager.tsindex 956c6e5bd0..4bf493c798 100644--- a/apps/desktop/src/main/hook-control/manager.ts+++ b/apps/desktop/src/main/hook-control/manager.ts@@ -31,6 +31,10 @@ import {HOOK_FEATURE_SESSION_PICKER,HOOK_FEATURE_SESSION_NEW,HOOK_FEATURE_SLACK_TOOLS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,HOOK_FEATURE_TURN_DELIVERY,makeBindRevoke,makeBindStart,@@ -694,6 +698,13 @@ export function createHookControlManager(deps: HookControlManagerDeps): HookCont// 只给 Telegram 声明: msg.op 目前只有 Telegram 的执行器, X 的渲染路径// 不接入(#1855 的红线之一)。HOOK_FEATURE_MESSAGE_OPS,+ // 进度消息、成功终稿、交互卡由客户端渲染并经 msg.op 发布, 命令菜单以客户端注册表+ // 为准(dispatcher 的 telegramTurnCarrier / telegramCardOps / provider.commands.set)。+ // 每项都要服务端同时宣告才启用; 否则那一项继续由服务端渲染。+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,HOOK_FEATURE_SESSION_NEW,],isEnabled: () => store.get().telegramEnabled,diff --git a/apps/desktop/src/main/hook-control/session-runner.ts b/apps/desktop/src/main/hook-control/session-runner.tsindex 4adeb3202a..5881ab60bc 100644--- a/apps/desktop/src/main/hook-control/session-runner.ts+++ b/apps/desktop/src/main/hook-control/session-runner.ts@@ -110,6 +110,11 @@ import { beginHeadlessGhostSetupTurn } from '../mcp-integrations/ghostSetupInterimport { observeHookTurn, type HookTurnObserver } from './turnObserver.js';import { bindRuntimeRecoveryNotice } from '../im/shared/runtimeRecoveryNotice.js';import { beginGroupHistoryAccess } from '../im/shared/groupHistoryAccess.js';+import {+ captureChannelAccount,+ openChannelSession,+ type ChannelSessionRoute,+} from '../im/shared/openChannelSession.js';import { describeInteractionSource } from '../im/shared/interactionSource';import { groupLaneOf } from './groupWindow';@@ -504,6 +509,18 @@ export function createMakerHookSessionRunner(deps: {async run(req) {const startedAt = Date.now();const maker = getMaker();+ // 新任务的账号代次从读取偏好 / 默认配置之前算起(与个人 IM 同一判据): 中途换账号时+ // 不拿旧账号读到的配置去新账号的库里建任务。+ const assertAccount = req.isNew ? captureChannelAccount() : undefined;+ /** 新任务建行后的补写(来源、发送时间、worktree)同样只写入口账号的库。 */+ const accountStillCurrent = (): boolean => {+ try {+ assertAccount?.();+ return true;+ } catch {+ return false;+ }+ };// 新建: 按「偏好 > 草稿默认」合成; 复用/接管: session meta 权威, 下方覆盖const resolved = req.isNew@@ -656,6 +673,21 @@ export function createMakerHookSessionRunner(deps: {: {}),resumeSessionId,};+ // 新任务经公共入口 openSession(与桌面新建任务同一套模型准入 / Git 初始化 / 账号代次+ // 校验, docs/dev-rules/im-turn-flow.md 批次 2); 建行本身仍是下面各自既有的路径。+ // 准入可能规范化来源 / 推理强度, 新任务用准入后的路由。复用 / 接管不经过这里。+ const newSessionRoute: ChannelSessionRoute = {+ agentKind: effectiveAgentKind,+ model: effectiveModel,+ providerId,+ ...(effort !== undefined ? { effort } : {}),+ permissionMode,+ workingDir,+ ...(req.workspaceKind !== undefined ? { workspaceKind: req.workspaceKind } : {}),+ ...(req.title ? { title: req.title } : {}),+ };+ /** 这一轮会话实际使用的来源(新任务取准入后的值)。 */+ let sessionProviderId = providerId;if (req.createOnly) {if (!req.isNew) return fail('create-only requires a new task');try {@@ -664,30 +696,47 @@ export function createMakerHookSessionRunner(deps: {// into a slow websocket RPC and can leave server/client state split// if the response times out. The first real message cold-opens this// same row through the ordinary reuse path.- await desktopSessionStorage.create({- id: req.sessionId,- agentKind: effectiveAgentKind,- workDir: workingDir,- title: req.title ?? 'New task',- model: effectiveModel,- ...(req.workspaceKind !== undefined ? { workspaceKind: req.workspaceKind } : {}),- ...(effort !== undefined ? { effort } : {}),- permissionMode,- });- if (providerId) {- setSessionProvider(req.sessionId, providerId);- await setSessionProviderIdInDb(req.sessionId, providerId);+ const admittedProviderId = await openChannelSession(+ req.sessionId,+ newSessionRoute,+ async (admitted) => {+ await desktopSessionStorage.create({+ id: req.sessionId,+ agentKind: effectiveAgentKind,+ workDir: workingDir,+ title: req.title ?? 'New task',+ model: admitted.model,+ ...(req.workspaceKind !== undefined ? { workspaceKind: req.workspaceKind } : {}),+ ...(admitted.effort !== undefined ? { effort: admitted.effort } : {}),+ permissionMode,+ });+ return admitted.providerId;+ },+ assertAccount,+ );+ // 建行之后的补写同样按入口账号复核: 中途换了账号就报失败, 不把补写落进新账号的库,+ // 也不向服务端谎报创建成功。+ if (admittedProviderId) {+ assertAccount?.();+ setSessionProvider(req.sessionId, admittedProviderId);+ await setSessionProviderIdInDb(req.sessionId, admittedProviderId);}if (req.source?.im === 'telegram' || req.source?.im === 'x') {+ assertAccount?.();await setSessionSourceInDb(req.sessionId, req.source.im);}+ assertAccount?.();await touchUserSendInDb(req.sessionId).catch((err) => {log.warn(`hook create-only touchUserSend failed: ${err instanceof Error ? err.message : String(err)}`,);});const wtMeta = worktreeStore.get(req.sessionId);- if (wtMeta) await setWorktreePathInDb(req.sessionId, wtMeta.path);+ if (wtMeta) {+ assertAccount?.();+ await setWorktreePathInDb(req.sessionId, wtMeta.path);+ }+ assertAccount?.();broadcastSessionCreated(req.sessionId);return {status: 'ok',@@ -704,7 +753,17 @@ export function createMakerHookSessionRunner(deps: {}try {await prepareUnhealthySessionForSend(req.sessionId);- session = await maker.createSession(createOpts);+ session = req.isNew+ ? await openChannelSession(req.sessionId, newSessionRoute, (admitted) => {+ sessionProviderId = admitted.providerId;+ return maker.createSession({+ ...createOpts,+ model: admitted.model,+ ...(admitted.providerId !== null ? { providerId: admitted.providerId } : {}),+ ...(admitted.effort !== undefined ? { effort: admitted.effort } : {}),+ });+ }, assertAccount)+ : await maker.createSession(createOpts);} catch (err) {// session 未建成: 若有预建 worktree 则回收(同 maker-ipc/register.ts// 的 shouldRecycleHandoffWorktreeOnFailure 判据), 防孤儿泄漏@@ -751,7 +810,9 @@ export function createMakerHookSessionRunner(deps: {// 新建显式 set(与 scheduler 4.4.2 的显式 providerId 分支同款); 复用走// hydrate —— 仅内存无条目时写入, 不覆盖运行中会话刚在聊天里切的更新值。if (req.isNew) {- if (providerId) setSessionProvider(session.id, providerId);+ if (sessionProviderId && accountStillCurrent()) {+ setSessionProvider(session.id, sessionProviderId);+ }} else {hydrateSessionProvider(session.id, rowProviderId);}@@ -865,7 +926,8 @@ export function createMakerHookSessionRunner(deps: {pendingInteractionNotices.clear();};// 新建会话广播 -> 侧边栏实时出现(复用/接管的会话本来就在列表里, 不用发)- if (req.isNew) {+ // 换了账号就不再补写(会落进新账号的库); 这一轮的出站本就按账号代次作废。+ if (req.isNew && accountStillCurrent()) {// hook 会话由用户消息(Slack / Telegram DM、群组或 topic)触发创建,// 与 IM 同语义(53b999601):// 广播前先落 userSendAt, 否则 renderer 重拉到 userSendAt=null && 0 消息的行@@ -879,18 +941,19 @@ export function createMakerHookSessionRunner(deps: {// 来源落库也在广播前: DesktopSessionStorage.create 不写 provider_id,// 不补的话 renderer 重拉 / 冷 resume 的 hydrate funnel 读到的来源恒空// (issue #854)。失败仅 warn(helper 内部吞错), 运行时路由不受影响。- if (providerId) {- await setSessionProviderIdInDb(session.id, providerId);+ // 每个 await 之后都可能换了账号: 每次补写与广播前就地复核, 账号变了就停下。+ if (sessionProviderId && accountStillCurrent()) {+ await setSessionProviderIdInDb(session.id, sessionProviderId);}- if (req.source?.im === 'telegram' || req.source?.im === 'x') {+ if ((req.source?.im === 'telegram' || req.source?.im === 'x') && accountStillCurrent()) {await setSessionSourceInDb(session.id, req.source.im);}- broadcastSessionCreated(session.id);+ if (accountStillCurrent()) broadcastSessionCreated(session.id);}// worktree 场景补写 sessions.worktree_path(同 send_to_session 做法):// prepareHandoffWorktree 时 session 行不存在, worktreeStore.set 的 DB// 同步落空; session 行建好后补一次, 失败非致命(store 是 source of truth)。- if (req.isNew) {+ if (req.isNew && accountStillCurrent()) {const wtMeta = worktreeStore.get(session.id);if (wtMeta) {void setWorktreePathInDb(session.id, wtMeta.path);@@ -1176,6 +1239,10 @@ export function createMakerHookSessionRunner(deps: {? (prependNoteToWireUserMessage(withPlanReconcile, goalInactiveNote) as UserMessage): withPlanReconcile;const trustedChannelOrigin = mainOwnedChannelOrigin(req.source?.im);+ // 新任务从入口起绑定账号: 建行后的补写、附件与上下文准备期间换了账号, 就终止这次+ // 派发(下面的 catch 统一收尾并回失败), 不让迟到的 send 在 teardown 之后重新启动+ // 旧账号的请求。+ assertAccount?.();const sendResult = await session.send(outgoingMessage, {origin,planMode: false,diff --git a/apps/desktop/src/main/hook-control/telegramCardOps.ts b/apps/desktop/src/main/hook-control/telegramCardOps.tsnew file mode 100644index 0000000000..a68f3a5c57--- /dev/null+++ b/apps/desktop/src/main/hook-control/telegramCardOps.ts@@ -0,0 +1,235 @@+/**+ * hook-control/telegramCardOps.ts+ * ---------------------------------------------------------------------------+ * 官方 Telegram 一轮里的**执行中交互卡**(ask / plan / 权限): 双方协商+ * `telegram-card-ops-v1` 后由本端用与个人 bot 同一份卡片渲染(@cindy/im+ * `layoutTelegramCard`: 粗体标题 + markdown 正文 → HTML、正文上限、短按钮成对排布)+ * 经 msg.op(`purpose: 'interaction-card'`)发布与收口。+ *+ * 分工: 卡片的**语义**(选项、按钮文案、决策映射、超时默认)仍在 `interactions.ts`,+ * 不因载体改变; 本模块只负责把那张卡渲染成 Telegram 形态并驱动发布 / 收口。按钮回调+ * 仍由服务端收入站(它铸 callback_data、记 buttonId 映射), 照旧回 interaction.decision;+ * 群里的卡改投 owner 私聊也仍由服务端按现行规则决定。+ *+ * 回落: 卡片 op 拿到明确失败(含 HTML 被拒)时改发旧的 interaction.request, 交服务端+ * 渲染 —— 卡片是这一轮能否继续的关键路径, 不能因为新载体失败就让用户看不到。之后同一张+ * 卡的收口也走旧路径(interaction.cancel), 两条路径不混用。+ */++import {+ makeMessageOp,+ type InteractionButton,+ type MessageOpAction,+} from '@cindy/slack-hook-protocol';+import { callWithTelegramRateLimitRetry, layoutTelegramCard } from '@cindy/im';++import {+ abortableSleep,+ isMsgOpOutcomeUnknown,+ MSG_OP_UNKNOWN_REPLAYS,+ msgOpErrorFromResult,+ TELEGRAM_OP_MARKER,+ TelegramMsgOpError,+ type MsgOpResultRouter,+ type MsgOpSendFn,+} from './telegramMsgOp.js';++/** 一张执行中交互卡(与 interaction.request 同一份内容)。 */+export interface OfficialInteractionCard {+ interactionId: string;+ kind: string;+ title: string;+ body: string;+ buttons: InteractionButton[];+}++type CardState = { mode: 'client'; messageId: string } | { mode: 'legacy' } | { mode: 'lost' };++export interface OfficialTelegramCardPublisherDeps {+ connectionId: string;+ requestId: string;+ externalKey: string;+ getSend: () => MsgOpSendFn | undefined;+ router: MsgOpResultRouter;+ /** 旧路径: interaction.request / interaction.cancel(服务端渲染)。 */+ legacy: {+ open(card: OfficialInteractionCard): void;+ close(interactionId: string, reason: string): void;+ };+ log: { info(msg: string): void; warn(msg: string): void };+ resultTimeoutMs?: number;+}++export interface OfficialTelegramCardPublisher {+ open(card: OfficialInteractionCard): void;+ /** 卡片已决 / 超时 / 撤销: 把正文改成收口说明并清键盘。 */+ close(interactionId: string, reason: string): void;+ /**+ * 等在途的发卡 / 收口编辑结束(有界)。dispatcher 在发 turn.end 之前调用: 收口编辑要+ * 先于 turn.end 到达服务端, 否则服务端的收口清扫会先把卡片当成未收口处理。+ */+ drain(timeoutMs?: number): Promise<void>;+ /** 换账号 / dispose: 停止一切出站(在途发布照常收口但不再发后续 op)。 */+ dispose(): void;+}++/** drain 的默认上限: 只为等已交出的编辑拿回执, 不为它无限推迟 turn.end。 */+const CARD_DRAIN_TIMEOUT_MS = 5_000;++export function createOfficialTelegramCardPublisher(+ deps: OfficialTelegramCardPublisherDeps,+): OfficialTelegramCardPublisher {+ const { connectionId, requestId, externalKey, router, log } = deps;+ const cards = new Map<string, Promise<CardState>>();+ /** 在途的发卡与收口编辑(drain 等它们)。 */+ const inflight = new Set<Promise<unknown>>();+ const track = <T>(promise: Promise<T>): Promise<T> => {+ inflight.add(promise);+ void promise.finally(() => inflight.delete(promise)).catch(() => undefined);+ return promise;+ };+ const abort = new AbortController();+ const sleep = abortableSleep(abort.signal);+ const isLive = (): boolean => !abort.signal.aborted;++ async function perform(+ interactionId: string,+ opIdBase: string,+ action: MessageOpAction,+ interactionClosed: boolean,+ ): Promise<string | null> {+ let attempt = 0;+ let replays = 0;+ const once = async (): Promise<string | null> => {+ if (!isLive()) throw new TelegramMsgOpError('telegram card publisher is disposed');+ const send = deps.getSend();+ if (!send) throw new TelegramMsgOpError('telegram card publisher is offline');+ const opId = `${opIdBase}:${attempt}`;+ const result = await router.request(+ connectionId,+ send,+ makeMessageOp({+ opId,+ requestId,+ scope: { externalKey },+ purpose: 'interaction-card',+ interactionId,+ ...(interactionClosed ? { interactionClosed: true } : {}),+ action,+ }),+ opId,+ deps.resultTimeoutMs,+ );+ if (isMsgOpOutcomeUnknown(result)) {+ throw new TelegramMsgOpError(`telegram msg.op ${opId} outcome unknown`);+ }+ if (result!.ok) return result!.messageId ?? result!.messageIds?.[0] ?? null;+ attempt += 1;+ throw msgOpErrorFromResult(result!);+ };+ for (;;) {+ try {+ return await callWithTelegramRateLimitRetry(once, { sleep, isLive });+ } catch (err) {+ const unknown =+ err instanceof TelegramMsgOpError && err.errorCode === undefined && !err.serverCode;+ if (unknown && isLive() && replays < MSG_OP_UNKNOWN_REPLAYS) {+ replays += 1;+ continue;+ }+ throw err;+ }+ }+ }++ async function publish(card: OfficialInteractionCard): Promise<CardState> {+ const { html, rows } = layoutTelegramCard({+ title: card.title,+ body: card.body,+ buttons: card.buttons,+ });+ try {+ const messageId = await perform(+ card.interactionId,+ `${requestId}${TELEGRAM_OP_MARKER.card}${card.interactionId}:open`,+ {+ kind: 'send',+ text: html,+ tier: 'html',+ buttons: rows.map((row) =>+ row.map(({ button, text }) => ({ token: button.id, label: text })),+ ),+ },+ false,+ );+ if (messageId !== null) return { mode: 'client', messageId };+ log.warn(+ `telegram card ${card.interactionId} published without a messageId; it cannot be closed`,+ );+ return { mode: 'lost' };+ } catch (err) {+ const unknown =+ err instanceof TelegramMsgOpError && err.errorCode === undefined && !err.serverCode;+ if (unknown || !isLive()) {+ // 不知道它落没落地: 再走旧路径可能出现两张卡, 宁可只留这一张(30 分钟超时照常收口)。+ log.warn(`telegram card ${card.interactionId} outcome unknown; not falling back`);+ return { mode: 'lost' };+ }+ log.info(+ `telegram card ${card.interactionId} rejected (${err instanceof Error ? err.message : String(err)}); falling back to interaction.request`,+ );+ deps.legacy.open(card);+ return { mode: 'legacy' };+ }+ }++ return {+ open(card) {+ if (!isLive() || cards.has(card.interactionId)) return;+ cards.set(card.interactionId, track(publish(card)));+ },+ close(interactionId, reason) {+ const pending = cards.get(interactionId);+ if (!pending) return;+ cards.delete(interactionId);+ void track(+ pending.then(async (state) => {+ if (state.mode === 'legacy') {+ deps.legacy.close(interactionId, reason);+ return;+ }+ if (state.mode !== 'client' || !isLive()) return;+ const { html } = layoutTelegramCard({ body: reason, buttons: [] });+ try {+ await perform(+ interactionId,+ `${requestId}${TELEGRAM_OP_MARKER.card}${interactionId}:close`,+ { kind: 'edit', messageId: state.messageId, text: html, tier: 'html', buttons: [] },+ true,+ );+ } catch (err) {+ log.warn(+ `telegram card ${interactionId} close failed: ${err instanceof Error ? err.message : String(err)}`,+ );+ }+ }),+ );+ },+ async drain(timeoutMs = CARD_DRAIN_TIMEOUT_MS) {+ if (inflight.size === 0) return;+ let timer: ReturnType<typeof setTimeout> | undefined;+ await Promise.race([+ Promise.allSettled([...inflight]),+ new Promise<void>((resolve) => {+ timer = setTimeout(resolve, timeoutMs);+ timer.unref?.();+ }),+ ]);+ if (timer !== undefined) clearTimeout(timer);+ },+ dispose() {+ abort.abort();+ cards.clear();+ },+ };+}diff --git a/apps/desktop/src/main/hook-control/telegramMsgOp.ts b/apps/desktop/src/main/hook-control/telegramMsgOp.tsnew file mode 100644index 0000000000..1fc321b631--- /dev/null+++ b/apps/desktop/src/main/hook-control/telegramMsgOp.ts@@ -0,0 +1,189 @@+/**+ * hook-control/telegramMsgOp.ts+ * ---------------------------------------------------------------------------+ * 官方 Telegram 由本端驱动的 msg.op(进度 / 终稿 / 交互卡)共用的传输小件:+ * - 请求/回执配对(MsgOpResultRouter): 回执按 opId 路由回等待方, 发不出去 /+ * 超时 / 断线都以 null(回执未知)收口, 绝不悬挂;+ * - 失败映射(TelegramMsgOpError): 把 msg.op.result 映射成与 Bot API+ * `TelegramApiError` 同形的错误, 让 @cindy/im `outboundPolicy` 的判据+ * (HTML 400 回落 / not modified / 429 退避)对两个 bot 原样生效;+ * - opId 命名: 由 requestId 派生, 带用途标记, dispatcher 据此把回执只路由给+ * 这些模块(不落到 ack 表情的失败日志里)。+ *+ * 不持有任何一轮的状态 —— 每轮的状态在 telegramTurnCarrier / telegramCardOps 里。+ */++import {+ MESSAGE_OP_ERROR_BINDING_REVOKED,+ MESSAGE_OP_ERROR_MESSAGE_NOT_OWNED,+ MESSAGE_OP_ERROR_OUTCOME_UNKNOWN,+ MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,+ MESSAGE_OP_ERROR_RATE_LIMITED,+ MESSAGE_OP_ERROR_TURN_UNAVAILABLE,+ MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS,+ type HookMessage,+ type MessageOpResultPayload,+} from '@cindy/slack-hook-protocol';++/** 等 msg.op.result 的时限; 过时按"回执未知"处理。 */+export const TELEGRAM_MSG_OP_RESULT_TIMEOUT_MS = 30_000;++/** 本端派生的 opId 用途标记: `<requestId>:<marker>...`。 */+export const TELEGRAM_OP_MARKER = {+ progress: ':progress:',+ final: ':final:',+ card: ':card:',+} as const;++/** 这条回执属于本端驱动的某一轮 msg.op(进度 / 终稿 / 卡片)吗。 */+export function isTelegramTurnOpId(opId: string): boolean {+ return Object.values(TELEGRAM_OP_MARKER).some((marker) => opId.includes(marker));+}++export type MsgOpSendFn = (m: HookMessage) => boolean;++/**+ * msg.op 请求/回执配对。dispatcher 持有一份, 所有轮次共用。+ */+export interface MsgOpResultRouter {+ request(+ connectionId: string,+ send: MsgOpSendFn,+ message: HookMessage,+ opId: string,+ timeoutMs?: number,+ ): Promise<MessageOpResultPayload | null>;+ /** 回执入口; 有人在等这个 opId 返回 true。 */+ settle(payload: MessageOpResultPayload): boolean;+ /** 连接断开: 该连接上在等的回执不会再来。 */+ failConnection(connectionId: string): void;+ /** 账号切换 / dispose。 */+ failAll(): void;+}++export function createMsgOpResultRouter(): MsgOpResultRouter {+ const waiters = new Map<+ string,+ { connectionId: string; settle: (r: MessageOpResultPayload | null) => void }+ >();+ return {+ request(connectionId, send, message, opId, timeoutMs = TELEGRAM_MSG_OP_RESULT_TIMEOUT_MS) {+ return new Promise((resolve) => {+ // 同一 opId 的旧等待方(幂等重发)以"未知"让位: 回执只会来一次, 归最新的等待方。+ waiters.get(opId)?.settle(null);+ const timer = setTimeout(() => settle(null), timeoutMs);+ timer.unref?.();+ const settle = (result: MessageOpResultPayload | null): void => {+ clearTimeout(timer);+ if (waiters.get(opId)?.settle === settle) waiters.delete(opId);+ resolve(result);+ };+ waiters.set(opId, { connectionId, settle });+ let transmitted = false;+ try {+ transmitted = send(message);+ } catch {+ transmitted = false;+ }+ if (!transmitted) settle(null);+ });+ },+ settle(payload) {+ const waiter = waiters.get(payload.opId);+ if (!waiter) return false;+ waiter.settle(payload);+ return true;+ },+ failConnection(connectionId) {+ for (const waiter of [...waiters.values()]) {+ if (waiter.connectionId === connectionId) waiter.settle(null);+ }+ },+ failAll() {+ for (const waiter of [...waiters.values()]) waiter.settle(null);+ },+ };+}++/**+ * msg.op 失败, 与 Bot API `TelegramApiError` 同形: `errorCode` = Telegram 原生+ * error_code(服务端透传), `message` 含 Telegram 原文。回执未知时**不带** errorCode+ * —— 那时不能判断 Telegram 是否已接收, 任何回落都不该触发。+ */+export class TelegramMsgOpError extends Error {+ readonly name = 'TelegramMsgOpError';+ constructor(+ message: string,+ readonly errorCode?: number,+ readonly retryAfterSec?: number,+ /** 服务端自己判定的结构化拒绝码(未调 Bot API)。 */+ readonly serverCode?: string,+ ) {+ super(message);+ }+}++/**+ * 回执未知时同 opId、同内容最多原样重发几次(卡片与终稿段共用)。服务端拿到过 Telegram+ * 应答的, 重发只回显原结果(对上账、不重复); 服务端也没应答的, 每个 opId 只重新执行一次,+ * 之后回显缓存的 OUTCOME_UNKNOWN。仍未知就按各自路径放弃。+ */+export const MSG_OP_UNKNOWN_REPLAYS = 2;++/** 回执未知: 没收到 / 超时 / 断线, 或服务端明说调用结果未知。 */+export function isMsgOpOutcomeUnknown(result: MessageOpResultPayload | null): boolean {+ return result === null || result.errorCode === MESSAGE_OP_ERROR_OUTCOME_UNKNOWN;+}++/**+ * 服务端拒绝码里"本轮这类 op 别再发了"的那几种: 不归本端承载 / 契约错误 / 消息不归属 /+ * 绑定已撤。其余明确失败(IDEMPOTENCY_CONFLICT / CAPACITY_REACHED / PERSIST_FAILED /+ * 不认识的码)只让这一次失败。+ */+const STOP_CODES: ReadonlySet<string> = new Set([+ MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,+ MESSAGE_OP_ERROR_TURN_UNAVAILABLE,+ MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS,+ MESSAGE_OP_ERROR_MESSAGE_NOT_OWNED,+ MESSAGE_OP_ERROR_BINDING_REVOKED,+]);++export function isMsgOpStopCode(result: MessageOpResultPayload): boolean {+ return typeof result.errorCode === 'string' && STOP_CODES.has(result.errorCode);+}++/** 失败回执 → 同形错误。服务端限速队列的拒收(RATE_LIMITED + retryAfterMs)与渠道 429 同一处理。 */+export function msgOpErrorFromResult(result: MessageOpResultPayload): TelegramMsgOpError {+ const rateLimited =+ result.errorCode === MESSAGE_OP_ERROR_RATE_LIMITED || typeof result.retryAfterMs === 'number';+ const errorCode =+ typeof result.channelErrorCode === 'number'+ ? result.channelErrorCode+ : rateLimited+ ? 429+ : undefined;+ const retryAfterSec =+ typeof result.retryAfterMs === 'number' ? result.retryAfterMs / 1000 : undefined;+ return new TelegramMsgOpError(+ `telegram msg.op ${result.opId} failed: ${errorCode ?? ''} ${result.error ?? result.errorCode ?? 'unknown'}`.trim(),+ errorCode,+ retryAfterSec,+ result.errorCode ?? undefined,+ );+}++/** 绑定在一个 AbortSignal 上的 sleep: abort 时提前 resolve(调用方醒来后自行复核)。 */+export function abortableSleep(signal: AbortSignal): (ms: number) => Promise<void> {+ return (ms) =>+ new Promise((resolve) => {+ if (signal.aborted) return resolve();+ const timer = setTimeout(done, ms);+ timer.unref?.();+ function done(): void {+ signal.removeEventListener('abort', done);+ clearTimeout(timer);+ resolve();+ }+ signal.addEventListener('abort', done, { once: true });+ });+}diff --git a/apps/desktop/src/main/hook-control/telegramTurnCarrier.ts b/apps/desktop/src/main/hook-control/telegramTurnCarrier.tsnew file mode 100644index 0000000000..cf4a7a44fc--- /dev/null+++ b/apps/desktop/src/main/hook-control/telegramTurnCarrier.ts@@ -0,0 +1,371 @@+/**+ * hook-control/telegramTurnCarrier.ts+ * ---------------------------------------------------------------------------+ * 官方 Telegram 一轮的**消息载体**: 进度消息(`telegram-progress-ops-v1`)与成功+ * 终稿(`telegram-final-ops-v1`)由本端渲染、经 msg.op 驱动, 服务端只执行(lane 授权、+ * 全局限速、调 Bot API、登记 route)。+ *+ * **不另写一套逻辑**: 生命周期(惰性占位、1.5s 尾沿节流、首帧 send 后续 edit、单帧+ * 上限、NO_REPLY 不落地、失败等下一窗口)与终稿收口(Rich → HTML → 纯文本、分段、+ * 落地后删过程载体)直接复用个人 bot 的同一个 handle(@cindy/im+ * `startTelegramTurnCarrier`); 渲染用同一个 `markdownToTelegramHtml`; HTML 被拒回落、+ * not modified、429 退避用同一组 `outboundPolicy` 判据。本模块只把+ * `TelegramStreamingDeps` 落到 msg.op 上:+ * - 过程帧 send / edit / delete → `purpose: 'turn-progress'`(首帧 silent, 与服务端+ * 旧进度消息一致);+ * - 终稿段 / Rich 终稿 → `purpose: 'turn-final'` + `finalPart`; 私聊首段挂完成特效。+ * 带附件的轮次不由本端发布(见 isClientFinalEligible)。+ * 投递位置(topic、回复引用、owner 私聊改投)仍由服务端按这一轮的策略决定。+ *+ * 幂等: 过程帧首个 send 的 opId 只在拿到定案回执后换号, 回执未知时**原样**重发+ * (服务端按 opId + 内容指纹去重), 对账成功后补一次 edit 到最新帧。终稿段回执未知时+ * 同 opId 同正文有界重发对账(MSG_OP_UNKNOWN_REPLAYS), 仍没有完整确认就以+ * `clientFinal.complete=false` 交回服务端, 服务端删掉已落地的客户端终稿段并照旧自己+ * 发布(见协议 HOOK_FEATURE_TELEGRAM_FINAL_OPS)。+ */++import {+ makeMessageOp,+ MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,+ type MessageOpAction,+ type MessageOpPurpose,+ type MessageOpResultPayload,+ type TaskAttachment,+} from '@cindy/slack-hook-protocol';+import {+ callWithTelegramRateLimitRetry,+ chunkTelegramSource,+ editTelegramHtmlWithFallback,+ markdownToTelegramHtml,+ sendTelegramHtmlWithFallback,+ startTelegramTurnCarrier,+ type TelegramStreamingDeps,+} from '@cindy/im';++import {+ abortableSleep,+ isMsgOpOutcomeUnknown,+ MSG_OP_UNKNOWN_REPLAYS,+ isMsgOpStopCode,+ msgOpErrorFromResult,+ TELEGRAM_OP_MARKER,+ TelegramMsgOpError,+ type MsgOpResultRouter,+ type MsgOpSendFn,+} from './telegramMsgOp.js';++/** 私聊成功终稿首段的完成特效(Telegram message_effect_id), 与服务端现行取值一致。 */+export const TELEGRAM_DM_COMPLETION_EFFECT_ID = '5107584321108051014';++const NO_REPLY = 'NO_REPLY';++/** Telegram 完整应答后的 4xx(渠道错误码; 服务端自判的 RATE_LIMITED 也映射为 429)。 */+function isTelegramClientError(err: unknown): boolean {+ if (!(err instanceof TelegramMsgOpError)) return false;+ const code = err.errorCode;+ return typeof code === 'number' && code >= 400 && code < 500;+}++export interface ClientFinalInput {+ status: 'ok' | 'error' | 'cancelled';+ finalText: string;+ attachments?: readonly TaskAttachment[];+}++/**+ * 这一轮的终稿能不能由本端发布。只覆盖普通成功、不带附件的轮次; 失败 / 取消 / 空正文 /+ * NO_REPLY(ambient 判定在服务端)/ 带附件都交回服务端按 turn.end 照旧处理。+ *+ * 带附件不由本端发布: 持久出箱只存终态文本(附件字节不进 JSON 持久化), 本端逐段上传+ * 附件期间退出 / 崩溃时, 重启重放的兜底帧没有附件, 服务端接管后附件就丢了。整轮随+ * turn.end 交给服务端, 附件与旧路径一样由服务端承载。+ */+export function isClientFinalEligible(input: ClientFinalInput): boolean {+ if (input.status !== 'ok') return false;+ if ((input.attachments?.length ?? 0) > 0) return false;+ const text = input.finalText.trim();+ return text !== '' && text !== NO_REPLY;+}++export interface OfficialTelegramTurnCarrierDeps {+ connectionId: string;+ requestId: string;+ externalKey: string;+ /** 私聊 lane(终稿首段挂完成特效)。 */+ directMessage: boolean;+ /** 该连接**当前**的发送函数; 断线时 undefined。每次出站现取, 不缓存旧 socket。 */+ getSend: () => MsgOpSendFn | undefined;+ router: MsgOpResultRouter;+ log: { info(msg: string): void; warn(msg: string): void };+ resultTimeoutMs?: number;+}++export interface OfficialTelegramTurnCarrier {+ /** 交一帧最新快照(markdown), 按个人 bot 同一节流出站。 */+ update(markdown: string): void;+ /**+ * 不由本端发布终稿时的收口: 立即冲刷最新帧后永久停止。冲刷在同步阶段就把 msg.op+ * 交给连接(管道空闲时), 所以它在 wire 上排在随后的 turn.end 之前; 管道正忙则这一帧+ * 放弃 —— 终稿随后由服务端发布, 不为一帧过程态推迟 turn.end。+ */+ finish(): void;+ /**+ * 由本端发布成功终稿(调用方先确认 isClientFinalEligible 与能力协商)。+ * 返回 true = 全部终稿段都拿到成功回执(turn.end 带 clientFinal.complete=true);+ * false = 没有完整确认, 交回服务端。之后载体永久停止。+ */+ publishFinal(input: ClientFinalInput): Promise<boolean>;+ /** 撤销 / 断线隔离 / 换账号: 永久停止, 不冲刷。幂等。 */+ close(): void;+}++/** 一轮的官方消息载体: msg.op 版 TelegramStreamingDeps + 个人 bot 同一个 handle。 */+export function createOfficialTelegramTurnCarrier(+ deps: OfficialTelegramTurnCarrierDeps,+): OfficialTelegramTurnCarrier {+ const { connectionId, requestId, externalKey, router, log } = deps;+ let closed = false;+ /**+ * 服务端说这一轮的**进度**不归本端(私聊草稿模式由服务端按 turn.progress 出草稿)。+ * 只停进度 op; 终稿仍可由本端发布(那时没有过程载体, finalize 直接新发)。+ */+ let progressStopped = false;+ /** 这一轮整体不归本端(已收口 / 不属于该设备 / 契约错误 / 回执违约) —— 不再出站。 */+ let turnStopped = false;+ let progressSendSeq = 0;+ let progressEditSeq = 0;+ let progressDeleteSeq = 0;+ /** 每个终稿段的 opId 序号: 只在拿到明确失败(含 429 / HTML 400 回落)后换号。 */+ const finalAttempt = new Map<number, number>();+ const abort = new AbortController();+ const sleep = abortableSleep(abort.signal);+ const isLive = (): boolean => !closed && !turnStopped;+ const isProgressLive = (): boolean => isLive() && !progressStopped;++ /**+ * 回执未知的过程帧首个 send。服务端按 opId + 内容指纹去重, 所以下一次 send 必须+ * **原样**重发它(同 opId 同正文)对账, 不能沿用 opId 换正文(IDEMPOTENCY_CONFLICT),+ * 也不能换 opId(可能多建一条)。+ */+ let unresolvedProgressSend: { opId: string; action: MessageOpAction } | null = null;+ /** 最近一次过程帧 send 是在原样重发更早的帧(显示的不是本次要发的内容)。 */+ let lastProgressSendReplayed = false;++ async function request(+ opId: string,+ purpose: MessageOpPurpose,+ action: MessageOpAction,+ finalPart?: number,+ ): Promise<MessageOpResultPayload | null> {+ if (purpose === 'turn-progress' ? !isProgressLive() : !isLive()) {+ throw new TelegramMsgOpError('telegram turn carrier is closed');+ }+ const send = deps.getSend();+ if (!send) throw new TelegramMsgOpError('telegram turn carrier is offline');+ return router.request(+ connectionId,+ send,+ makeMessageOp({+ opId,+ requestId,+ scope: { externalKey },+ purpose,+ ...(finalPart !== undefined ? { finalPart } : {}),+ action,+ }),+ opId,+ deps.resultTimeoutMs,+ );+ }++ /** 定案的失败回执: 停手码让本轮停止出站, 其余映射成同形错误抛给 outboundPolicy。 */+ function failed(result: MessageOpResultPayload): TelegramMsgOpError {+ if (result.errorCode === MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE) {+ progressStopped = true;+ log.info(+ `telegram progress ops unavailable for ${requestId}; leaving progress to the server`,+ );+ } else if (isMsgOpStopCode(result)) {+ turnStopped = true;+ log.info(+ `telegram turn ops stopped for ${requestId} (${result.errorCode}); leaving the rest to the server`,+ );+ }+ return msgOpErrorFromResult(result);+ }++ async function progressOp(requested: MessageOpAction): Promise<MessageOpResultPayload> {+ let opId: string;+ let action = requested;+ if (requested.kind === 'send') {+ if (unresolvedProgressSend !== null) {+ ({ opId, action } = unresolvedProgressSend);+ lastProgressSendReplayed = action.kind === 'send' && action.text !== requested.text;+ } else {+ opId = `${requestId}${TELEGRAM_OP_MARKER.progress}send:${progressSendSeq}`;+ unresolvedProgressSend = { opId, action };+ lastProgressSendReplayed = false;+ }+ } else if (requested.kind === 'edit') {+ opId = `${requestId}${TELEGRAM_OP_MARKER.progress}edit:${++progressEditSeq}`;+ } else {+ opId = `${requestId}${TELEGRAM_OP_MARKER.progress}delete:${++progressDeleteSeq}`;+ }+ const result = await request(opId, 'turn-progress', action);+ // 回执未知: send 保持 unresolvedProgressSend, 下一窗口原样重发对账。+ if (isMsgOpOutcomeUnknown(result)) {+ throw new TelegramMsgOpError(`telegram msg.op ${opId} outcome unknown`);+ }+ const settled = result!;+ if (action.kind === 'send') {+ unresolvedProgressSend = null;+ if (!settled.ok) progressSendSeq += 1;+ }+ if (settled.ok) return settled;+ throw failed(settled);+ }++ /**+ * 终稿段: 回执未知时先同 opId 同正文有界重发对账(服务端有应答就回显原结果, 不会多出一份+ * 答案), 仍未知才交回服务端; 明确失败换号以便回落重发。+ */+ async function finalOp(part: number, action: MessageOpAction): Promise<MessageOpResultPayload> {+ const attempt = finalAttempt.get(part) ?? 0;+ const opId = `${requestId}${TELEGRAM_OP_MARKER.final}${part}:${attempt}`;+ let result = await request(opId, 'turn-final', action, part);+ for (+ let replay = 0;+ isMsgOpOutcomeUnknown(result) && replay < MSG_OP_UNKNOWN_REPLAYS && isLive();+ replay += 1+ ) {+ result = await request(opId, 'turn-final', action, part);+ }+ if (isMsgOpOutcomeUnknown(result)) {+ throw new TelegramMsgOpError(`telegram msg.op ${opId} outcome unknown`);+ }+ const settled = result!;+ if (settled.ok) return settled;+ finalAttempt.set(part, attempt + 1);+ throw failed(settled);+ }++ const messageIdOf = (result: MessageOpResultPayload, what: string): string => {+ const id = result.messageId ?? result.messageIds?.[0] ?? null;+ if (id !== null) return id;+ // 违约回执: 没有 messageId 就无法 edit / 删除, 再发只会多建消息。本轮停手。+ turnStopped = true;+ log.warn(`telegram ${what} for ${requestId} succeeded without a messageId; stopping`);+ throw new TelegramMsgOpError(`telegram ${what} returned no messageId`);+ };++ const effectFor = (part: number): { effectId?: string } =>+ part === 0 && deps.directMessage ? { effectId: TELEGRAM_DM_COMPLETION_EFFECT_ID } : {};++ const retry = <T>(call: () => Promise<T>, live: () => boolean = isLive): Promise<T> =>+ callWithTelegramRateLimitRetry(call, { sleep, isLive: live });++ const streamingDeps: TelegramStreamingDeps = {+ async send(markdown) {+ const { html } = markdownToTelegramHtml(markdown);+ const result = await sendTelegramHtmlWithFallback(html, markdown, (text, parseHtml) =>+ retry(+ () =>+ progressOp({ kind: 'send', text, tier: parseHtml ? 'html' : 'plain', silent: true }),+ isProgressLive,+ ),+ );+ const messageId = messageIdOf(result, 'progress send');+ // 对账拿回的是更早那一帧: 尽力补一次 edit 到本帧, 失败交给下一窗口。+ if (lastProgressSendReplayed) {+ lastProgressSendReplayed = false;+ await streamingDeps.edit(messageId, markdown).catch(() => undefined);+ }+ return messageId;+ },+ async edit(messageId, markdown) {+ const { html } = markdownToTelegramHtml(markdown);+ await editTelegramHtmlWithFallback(html, async (text, parseHtml) => {+ await retry(+ () => progressOp({ kind: 'edit', messageId, text, tier: parseHtml ? 'html' : 'plain' }),+ isProgressLive,+ );+ });+ },+ async deleteMessage(messageId) {+ await progressOp({ kind: 'delete', messageId });+ },+ async sendFinalChunk(markdown, part) {+ const { html } = markdownToTelegramHtml(markdown);+ const result = await sendTelegramHtmlWithFallback(html, markdown, (text, parseHtml) =>+ retry(() =>+ finalOp(part, {+ kind: 'send',+ text,+ tier: parseHtml ? 'html' : 'plain',+ ...effectFor(part),+ }),+ ),+ );+ return messageIdOf(result, 'final send');+ },+ async sendFinal(markdown) {+ // Rich 是终稿的新消息; Telegram 完整应答后的任一 4xx(含退避重试后仍 429)= 这条+ // Rich 没有落地, 交给 finalize 回落 HTML —— 与个人 bot sendRichFinal 同一判据。+ // 拿不到应答 / 服务端自判拒绝码(无渠道错误码)必须抛出, 不能伪装成可安全降级。+ try {+ const result = await retry(() =>+ finalOp(0, { kind: 'send', text: markdown, tier: 'rich', ...effectFor(0) }),+ );+ return messageIdOf(result, 'rich final');+ } catch (err) {+ if (isTelegramClientError(err)) return null;+ throw err;+ }+ },+ // 官方终稿的受管图片已由 runner 收成附件、正文里的引用已剥掉: 这里不会有图片+ // 引用; 带附件的轮次整轮交回服务端, 不走本端发布。+ chunk: chunkTelegramSource,+ extractImageUrls: () => [],+ uploadImages: async () => {+ throw new Error('official telegram finals with attachments are published by the server');+ },+ };+ const carrier = startTelegramTurnCarrier(streamingDeps);++ const close = (): void => {+ if (closed) return;+ closed = true;+ abort.abort();+ carrier.close();+ };++ return {+ update(markdown) {+ if (!isProgressLive()) return;+ carrier.replace(markdown);+ },+ finish() {+ if (closed) return;+ if (isProgressLive()) void carrier.flush();+ close();+ },+ async publishFinal(input) {+ if (closed || turnStopped || !isClientFinalEligible(input)) {+ close();+ return false;+ }+ try {+ await carrier.finalize(input.finalText);+ return isLive();+ } catch (err) {+ log.warn(+ `telegram client final for ${requestId} not confirmed; handing back to the server: ${err instanceof Error ? err.message : String(err)}`,+ );+ return false;+ } finally {+ close();+ }+ },+ close,+ };+}diff --git a/apps/desktop/src/main/im/shared/__tests__/botCommands.test.ts b/apps/desktop/src/main/im/shared/__tests__/botCommands.test.tsindex 45fd666304..44f0721efc 100644--- a/apps/desktop/src/main/im/shared/__tests__/botCommands.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/botCommands.test.ts@@ -12,6 +12,7 @@ import {buildPersonalBotCommandMenu,isBotCommandAvailableOnChannel,OFFICIAL_BOT_COMMANDS,+ buildOfficialBotCommandMenus,parsePersonalBotCommand,PERSONAL_BOT_COMMAND_LOCALE_POLICY,PERSONAL_BOT_COMMANDS,@@ -152,14 +153,30 @@ describe('bot command registry', () => {expect(undocumented).toEqual([]);});- it('个人 bot 的每条命令都有菜单文案 key', () => {- // buildPersonalBotCommandMenu 对 personal 子集用了非空断言, 由这条守住。- const missing = PERSONAL_BOT_COMMANDS.filter(- (definition) => !definition.telegramMenuDescriptionKey,- ).map((definition) => definition.command);+ it('每条命令都有菜单文案 key(个人菜单与官方菜单都由 desktop 渲染)', () => {+ // buildPersonalBotCommandMenu / buildOfficialBotCommandMenus 用了非空断言, 由这条守住。+ const missing = (BOT_COMMANDS as readonly BotCommandDefinition[])+ .filter((definition) => !definition.telegramMenuDescriptionKey)+ .map((definition) => definition.command);expect(missing).toEqual([]);});+ it('官方菜单: 默认英文 + zh / ja / ko 各一份, 命令集合即官方子集、顺序即表序', () => {+ const calls: Array<[string, string]> = [];+ const menus = buildOfficialBotCommandMenus((key, locale) => {+ calls.push([key, locale]);+ return `${locale}:${key.split('.').pop()}`;+ });+ expect(menus.map((m) => m.languageCode)).toEqual([null, 'zh', 'ja', 'ko']);+ for (const menu of menus) {+ expect(menu.commands.map((c) => c.command)).toEqual(+ OFFICIAL_BOT_COMMANDS.map((definition) => definition.command),+ );+ }+ expect(menus[1].commands.find((c) => c.command === 'effort')?.description).toBe('zh-CN:effort');+ expect(new Set(calls.map(([, locale]) => locale))).toEqual(new Set(['en', 'zh-CN', 'ja', 'ko']));+ });+it('官方镜像与服务端 TELEGRAM_COMMANDS 一一对应', () => {expect([...OFFICIAL_BOT_COMMANDS.map((definition) => definition.command)].sort()).toEqual([...OFFICIAL_SERVER_COMMANDS].sort(),diff --git a/apps/desktop/src/main/im/shared/__tests__/channelDefaultRouteSync.test.ts b/apps/desktop/src/main/im/shared/__tests__/channelDefaultRouteSync.test.tsindex 06add06369..ad70ac856f 100644--- a/apps/desktop/src/main/im/shared/__tests__/channelDefaultRouteSync.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/channelDefaultRouteSync.test.ts@@ -22,6 +22,23 @@ const mocks = vi.hoisted(() => ({boundaryPending: vi.fn((): boolean => false),}));+// 新任务经公共入口 openSession(模型准入)—— 准入本身由 sessionOpening 的测试覆盖, 这里+// 只把准入前的路由原样透传给建行回调。+vi.mock('../../../localDb/sessionOpening', () => ({+ openSession: vi.fn(+ async (+ input: { body: Record<string, unknown> },+ commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>,+ ) => {+ const row = {+ ...input.body,+ providerId: input.body.providerId ?? null,+ fastMode: !!input.body.fastMode,+ };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ },+ ),+}));vi.mock('electron', () => ({BrowserWindow: { getAllWindows: () => [] },app: { getPath: () => '/tmp/never-used-here' },@@ -70,9 +87,10 @@ vi.mock('../../../appSessionState.js', async (importOriginal) => ({}));let db: ReturnType<typeof drizzle>;-vi.mock('../../../localDb/client/current', () => ({- getDbClient: () => ({ drizzle: db }),-}));+vi.mock('../../../localDb/client/current', () => {+ const account = {};+ return { getDbClient: () => ({ drizzle: db }), getCurrentDbClientSnapshot: () => account };+});const { sessions } = await import('../../../localDb/schema');const {diff --git a/apps/desktop/src/main/im/shared/__tests__/openChannelSession.test.ts b/apps/desktop/src/main/im/shared/__tests__/openChannelSession.test.tsnew file mode 100644index 0000000000..fd69a38a75--- /dev/null+++ b/apps/desktop/src/main/im/shared/__tests__/openChannelSession.test.ts@@ -0,0 +1,89 @@+/**+ * IM 渠道新建任务经公共入口 openSession: 准入前的路由原样送进 openSession, 回调拿到+ * 准入后的路由; 渠道没给过的字段(effort / fastMode)不把准入默认值回写给调用方。+ */+import { describe, expect, it, vi } from 'vitest';++const openSession = vi.hoisted(() => vi.fn());+vi.mock('../../../localDb/sessionOpening', () => ({ openSession }));++import { openChannelSession } from '../openChannelSession';++describe('openChannelSession', () => {+ it('把渠道路由送进 openSession(agentKind 用库值), 回调拿到准入后的路由', async () => {+ openSession.mockImplementationOnce(async (input, commit) => ({+ row: {+ ...input.body,+ model: 'm-admitted',+ providerId: 'p-admitted',+ effort: 'medium',+ fastMode: false,+ },+ value: await commit(+ {+ ...input.body,+ model: 'm-admitted',+ providerId: 'p-admitted',+ effort: 'medium',+ fastMode: false,+ },+ () => undefined,+ ),+ }));+ const commit = vi.fn(async (_admitted: unknown) => 'created');+ await expect(+ openChannelSession(+ 's-1',+ {+ agentKind: 'claude-code',+ model: 'm',+ providerId: null,+ effort: 'high',+ permissionMode: 'auto',+ workingDir: '/w',+ workspaceKind: 'dialogue',+ title: 'Telegram',+ },+ commit,+ ),+ ).resolves.toBe('created');+ expect(openSession.mock.calls[0][0]).toEqual({+ id: 's-1',+ body: {+ title: 'Telegram',+ agentKind: 'cc',+ model: 'm',+ providerId: null,+ effort: 'high',+ permissionMode: 'auto',+ workspaceKind: 'dialogue',+ workingDir: '/w',+ },+ });+ // 渠道给过 effort → 回写准入后的值; 没给过 fastMode → 不回写准入默认值。+ expect(commit.mock.calls[0][0]).toEqual({+ model: 'm-admitted',+ providerId: 'p-admitted',+ effort: 'medium',+ });+ });++ it('准入拒绝时抛出, 建行回调不执行(不静默换模型)', async () => {+ openSession.mockRejectedValueOnce(new Error('模型不可用,不会自动更换模型或供应商'));+ const commit = vi.fn();+ await expect(+ openChannelSession(+ 's-2',+ {+ agentKind: 'codex',+ model: 'gone',+ providerId: 'p',+ permissionMode: 'ask',+ workingDir: '/w',+ },+ commit,+ ),+ ).rejects.toThrow('不会自动更换模型或供应商');+ expect(commit).not.toHaveBeenCalled();+ });+});diff --git a/apps/desktop/src/main/im/shared/__tests__/sessionRepoBroadcast.test.ts b/apps/desktop/src/main/im/shared/__tests__/sessionRepoBroadcast.test.tsindex 7994f52401..ac3dfec40b 100644--- a/apps/desktop/src/main/im/shared/__tests__/sessionRepoBroadcast.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/sessionRepoBroadcast.test.ts@@ -20,6 +20,23 @@ const mocks = vi.hoisted(() => {};});+// 新任务经公共入口 openSession(模型准入)—— 准入本身由 sessionOpening 的测试覆盖, 这里+// 只把准入前的路由原样透传给建行回调。+vi.mock('../../../localDb/sessionOpening', () => ({+ openSession: vi.fn(+ async (+ input: { body: Record<string, unknown> },+ commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>,+ ) => {+ const row = {+ ...input.body,+ providerId: input.body.providerId ?? null,+ fastMode: !!input.body.fastMode,+ };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ },+ ),+}));vi.mock('electron', () => ({BrowserWindow: {getAllWindows: () => [@@ -35,7 +52,10 @@ vi.mock('../../../logger', () => ({createLogger: () => mocks.logger,maskPath: (p: string) => p,}));+const STABLE_ACCOUNT = vi.hoisted(() => ({}));vi.mock('../../../localDb/client/current', () => ({+ // 账号快照: 同一引用 = 账号没变(sessionRepo 建任务前按它复核账号代次)。+ getCurrentDbClientSnapshot: () => STABLE_ACCOUNT,getDbClient: () => ({drizzle: {insert: () => ({ values: mocks.insertValues }),@@ -63,6 +83,7 @@ vi.mock('../../defaultSessionSettings', () => ({})),}));+import { openSession } from '../../../localDb/sessionOpening';import { createImSessionRepo, type ImSessionRow } from '../sessionRepo';import type { ImOrchestratorConfig, ImSessionNamespace } from '../types';@@ -108,6 +129,32 @@ describe('sessionRepo.createSession broadcast', () => {});});+ it('新任务经 openSession 准入: 插入的是准入后的路由(来源 / 推理强度)', async () => {+ vi.mocked(openSession).mockImplementationOnce(async (input, commit) => {+ const row = { ...input.body, model: 'claude-opus-4-8', providerId: 'admitted-provider', effort: 'medium', fastMode: false };+ return { row, value: await commit!(row as never, () => undefined) } as never;+ });+ const repo = createImSessionRepo({ agentKind: 'claude-code' } as ImOrchestratorConfig, ns);+ await repo.createSession('bot', 'user', undefined, preparedRow);+ expect(vi.mocked(openSession).mock.calls.at(-1)?.[0]).toMatchObject({+ id: 'slack-bot-user',+ body: { agentKind: 'cc', model: 'claude-opus-4-8', providerId: null, effort: 'high' },+ });+ expect(mocks.insertValues).toHaveBeenCalledWith(+ expect.objectContaining({ providerId: 'admitted-provider', effort: 'medium' }),+ );+ });++ it('准入拒绝: 不插行、不广播, 错误交给调用方走渠道失败提示', async () => {+ vi.mocked(openSession).mockRejectedValueOnce(new Error('不会自动更换模型或供应商'));+ const repo = createImSessionRepo({ agentKind: 'claude-code' } as ImOrchestratorConfig, ns);+ await expect(repo.createSession('bot', 'user', undefined, preparedRow)).rejects.toThrow(+ '不会自动更换模型或供应商',+ );+ expect(mocks.insertValues).not.toHaveBeenCalled();+ expect(mocks.webContentsSend).not.toHaveBeenCalled();+ });+it('DB 插入失败时不广播(避免 renderer 重拉到不存在的行)', async () => {mocks.insertConflict.mockRejectedValueOnce(new Error('insert failed'));const repo = createImSessionRepo({ agentKind: 'claude-code' } as ImOrchestratorConfig, ns);diff --git a/apps/desktop/src/main/im/shared/__tests__/sessionRepoRevive.test.ts b/apps/desktop/src/main/im/shared/__tests__/sessionRepoRevive.test.tsindex bc01e1ed9d..71bb3db5b0 100644--- a/apps/desktop/src/main/im/shared/__tests__/sessionRepoRevive.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/sessionRepoRevive.test.ts@@ -38,6 +38,23 @@ const mocks = vi.hoisted(() => {// `sql` 同理拼成可读字符串: 生产代码用 `sql\`case when ...\`` 组装 workspaceKind// 的 SET, 这里只看判据的形状 —— 它在真 SQLite 下的语义由// sessionRepoWorkspaceKind.test.ts 覆盖。+// 新任务经公共入口 openSession(模型准入)—— 准入本身由 sessionOpening 的测试覆盖, 这里+// 只把准入前的路由原样透传给建行回调。+vi.mock('../../../localDb/sessionOpening', () => ({+ openSession: vi.fn(+ async (+ input: { body: Record<string, unknown> },+ commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>,+ ) => {+ const row = {+ ...input.body,+ providerId: input.body.providerId ?? null,+ fastMode: !!input.body.fastMode,+ };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ },+ ),+}));vi.mock('drizzle-orm', () => ({and: (...conditions: unknown[]) => ({ and: conditions }),desc: (col: unknown) => ({ desc: col }),@@ -63,7 +80,10 @@ vi.mock('../../../logger', () => ({createLogger: () => mocks.logger,maskPath: (p: string) => p,}));+const STABLE_ACCOUNT = vi.hoisted(() => ({}));vi.mock('../../../localDb/client/current', () => ({+ // 账号快照: 同一引用 = 账号没变(sessionRepo 建任务前按它复核账号代次)。+ getCurrentDbClientSnapshot: () => STABLE_ACCOUNT,getDbClient: () => ({tx: mocks.tx,drizzle: {diff --git a/apps/desktop/src/main/im/shared/__tests__/sessionRepoWorkspaceKind.test.ts b/apps/desktop/src/main/im/shared/__tests__/sessionRepoWorkspaceKind.test.tsindex 12c8d2f029..7551132543 100644--- a/apps/desktop/src/main/im/shared/__tests__/sessionRepoWorkspaceKind.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/sessionRepoWorkspaceKind.test.ts@@ -19,6 +19,23 @@ import { drizzle } from 'drizzle-orm/better-sqlite3';import { getTableConfig } from 'drizzle-orm/sqlite-core';import { beforeEach, describe, expect, it, vi } from 'vitest';+// 新任务经公共入口 openSession(模型准入)—— 准入本身由 sessionOpening 的测试覆盖, 这里+// 只把准入前的路由原样透传给建行回调。+vi.mock('../../../localDb/sessionOpening', () => ({+ openSession: vi.fn(+ async (+ input: { body: Record<string, unknown> },+ commit?: (row: Record<string, unknown>, assertCurrent: () => void) => Promise<unknown>,+ ) => {+ const row = {+ ...input.body,+ providerId: input.body.providerId ?? null,+ fastMode: !!input.body.fastMode,+ };+ return { row, value: commit ? await commit(row, () => undefined) : undefined };+ },+ ),+}));vi.mock('electron', () => ({BrowserWindow: { getAllWindows: () => [] },app: { getPath: () => '/tmp/never-used-here' },@@ -47,8 +64,10 @@ vi.mock('../../defaultSessionSettings', () => ({}));let db: ReturnType<typeof drizzle>;+const account = vi.hoisted(() => ({ current: {} as object }));vi.mock('../../../localDb/client/current', () => ({getDbClient: () => ({ drizzle: db }),+ getCurrentDbClientSnapshot: () => account.current,}));const { sessions } = await import('../../../localDb/schema');@@ -224,3 +243,28 @@ describe('workspaceKind 在复活 / upsert 冲突时的归属', () => {expect(again.workingDir).toBe(PROJECT_DIR);});});++describe('新任务写库前复核账号代次', () => {+ it('准入后等锁期间换了账号: 抛错且不写库', async () => {+ const { openSession } = await import('../../../localDb/sessionOpening');+ vi.mocked(openSession).mockImplementationOnce(async (input, commit) => {+ const row = { ...input.body, providerId: null, fastMode: false } as never;+ const value = await commit!(row, () => {+ throw new Error('account changed');+ });+ return { row, value };+ });+ await expect(repo().createSession('bot1', 'u1')).rejects.toThrow('account changed');+ expect(await db.select().from(sessions)).toHaveLength(0);+ });++ it('先 prepare、再 createSession 之间换了账号: 抛错且不写库', async () => {+ const r = repo();+ const prepared = await r.prepareNewSession('bot1', 'u1');+ account.current = {};+ await expect(r.createSession('bot1', 'u1', undefined, prepared)).rejects.toThrow(+ '账号已变化',+ );+ expect(await db.select().from(sessions)).toHaveLength(0);+ });+});diff --git a/apps/desktop/src/main/im/shared/__tests__/turnRunnerSendOutcome.test.ts b/apps/desktop/src/main/im/shared/__tests__/turnRunnerSendOutcome.test.tsindex 0ce2fc6f97..855e7c8b57 100644--- a/apps/desktop/src/main/im/shared/__tests__/turnRunnerSendOutcome.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/turnRunnerSendOutcome.test.ts@@ -66,6 +66,12 @@ const mocks = vi.hoisted(() => ({clearPendingTurnChangeSets: vi.fn(),noteSilentStopUserSend: vi.fn(),noteSilentStopSessionReset: vi.fn(),+ // 与生产同语义的最小替身: 统一停止按 id 取**当前** runtime 并中止(唯一的一次 abort)。+ stopSessionTurnExplicitly: vi.fn(async (sessionId: string): Promise<void> => {+ await (mocks.getMaker() as { getSession(id: string): { abort(): Promise<void> } | undefined })+ .getSession(sessionId)+ ?.abort();+ }),onSilentStopSettled: vi.fn(() => vi.fn()),installDesktopInteractionListener: vi.fn(),takePendingInteractionsForSession: vi.fn(),@@ -157,6 +163,7 @@ vi.mock('../../../maker-ipc/register', () => ({takePendingInteractionsForSession: mocks.takePendingInteractionsForSession,noteSilentStopUserSend: mocks.noteSilentStopUserSend,noteSilentStopSessionReset: mocks.noteSilentStopSessionReset,+ stopSessionTurnExplicitly: mocks.stopSessionTurnExplicitly,onSilentStopSettled: mocks.onSilentStopSettled,}));@@ -3243,7 +3250,10 @@ describe('turnRunner send outcome policy (feishu adapter characterization)', ()userId: 'ou_user',});expect(result.stopped).toBe(true);- expect(mocks.noteSilentStopSessionReset).toHaveBeenCalledWith('feishu-session');+ // 与桌面 Stop 同一套清理: 统一停止入口负责撤续跑守卫与唯一的一次 abort,+ // turnRunner 自己不再直接 abort(重复中止会向 vendor 发两次 interrupt)。+ expect(mocks.noteSilentStopSessionReset).not.toHaveBeenCalled();+ expect(mocks.stopSessionTurnExplicitly).toHaveBeenCalledWith('feishu-session');expect(h.abort).toHaveBeenCalledTimes(1);const settleCb = (mocks.onSilentStopSettled.mock.calls[0] as unknown[])[1] as (diff --git a/apps/desktop/src/main/im/shared/__tests__/turnRunnerThreadRouting.test.ts b/apps/desktop/src/main/im/shared/__tests__/turnRunnerThreadRouting.test.tsindex 724a06bf26..944f09487f 100644--- a/apps/desktop/src/main/im/shared/__tests__/turnRunnerThreadRouting.test.ts+++ b/apps/desktop/src/main/im/shared/__tests__/turnRunnerThreadRouting.test.ts@@ -40,6 +40,12 @@ const mocks = vi.hoisted(() => ({takePendingInteractionsForSession: vi.fn(() => []),noteSilentStopUserSend: vi.fn(),noteSilentStopSessionReset: vi.fn(),+ // 与生产同语义的最小替身: 统一停止按 id 取**当前** runtime 并中止(唯一的一次 abort)。+ stopSessionTurnExplicitly: vi.fn(async (sessionId: string): Promise<void> => {+ await (mocks.getMaker() as { getSession(id: string): { abort(): Promise<void> } | undefined })+ .getSession(sessionId)+ ?.abort();+ }),onSilentStopSettled: vi.fn(() => vi.fn()),rejectAllPending: vi.fn<(reason: string, owner?: symbol) => Array<{ requestId: string; messageId: string }>>(() => []),registerPending: vi.fn(),@@ -83,6 +89,7 @@ vi.mock('../../../maker-ipc/register', () => ({takePendingInteractionsForSession: mocks.takePendingInteractionsForSession,noteSilentStopUserSend: mocks.noteSilentStopUserSend,noteSilentStopSessionReset: mocks.noteSilentStopSessionReset,+ stopSessionTurnExplicitly: mocks.stopSessionTurnExplicitly,onSilentStopSettled: mocks.onSilentStopSettled,}));vi.mock('../pendingInteractions', () => ({diff --git a/apps/desktop/src/main/im/shared/botCommands.ts b/apps/desktop/src/main/im/shared/botCommands.tsindex 8e5ae33d7f..86830c6307 100644--- a/apps/desktop/src/main/im/shared/botCommands.ts+++ b/apps/desktop/src/main/im/shared/botCommands.ts@@ -12,12 +12,18 @@* 任何只存在于单侧的命令必须写 `parityNote` 讲清楚为什么 —— 缺了 CI 红。* 差异本身不消失, 但它从此是**写下来的、拦得住的**, 而不是靠人记。*- * 当前接线边界(#1855 第二刀):+ * 当前接线边界:* - 个人 bot: 本表是运行时事实来源(菜单渲染 + 命令分发都读它)。- * - 官方 bot: 命令仍由服务端下发, 本表对官方侧是**声明性镜像**, 不接线。- * 镜像与服务端的一致性由 `botCommands.test.ts` 里的内联清单断言守住。+ * - 官方 bot: 双方协商 `telegram-commands-v1` 后, **菜单**以本表为准 —— desktop 按+ * en / zh / ja / ko 渲染(`buildOfficialBotCommandMenus`)经 provider.commands.set+ * 下发, 服务端只执行 setMyCommands; 未协商时服务端照旧用自己的 TELEGRAM_COMMANDS。+ * **命令分发**仍在服务端(官方入站由服务端收), 命令集合与服务端分发的一致性仍由+ * `botCommands.test.ts` 的内联清单守住。*/+import type { TelegramCommandMenu } from '@cindy/slack-hook-protocol';+import type { SupportedLocale } from '../../../shared/locale';+import type { ImChannelName } from './types';export const PERSONAL_BOT_COMMAND_LOCALE_POLICY = 'desktop-app' as const;@@ -40,8 +46,8 @@ export interface BotCommandDefinition {** 只有 Telegram 有 `setMyCommands` 这种平台级命令菜单, 别的渠道不消费它,* 所以字段名直接带上 telegram —— 不是命名空间没解耦, 是它本来就只服务 Telegram。- * `surfaces` 含 `personal` 的命令必填(菜单要渲染); 官方独有的命令留空,- * 因为它们的菜单文案在服务端 `TELEGRAM_COMMANDS` 里。+ * 每条命令都必填 —— 个人菜单与官方菜单(协商 telegram-commands-v1 后)都由 desktop 按+ * 这个 key 渲染。*/telegramMenuDescriptionKey?: `settings.telegramBot.commandMenu.${string}`;/**@@ -147,6 +153,7 @@ export const BOT_COMMANDS = [{command: 'workspace',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.workspace',parityNote:'/project 的同义命令(服务端两条菜单文案逐字相同)。个人 bot 用 aliases 表达同义拼写, 不重复占一个菜单位, 因此不登记为独立命令。',requiresRichCards: true,@@ -154,24 +161,28 @@ export const BOT_COMMANDS = [{command: 'unbind',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.unbind',parityNote: '清除当前 chat 的项目映射。个人 bot 尚未实现 —— 目前只能在桌面设置页解绑。',requiresRichCards: false,},{command: 'effort',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.effort',parityNote: '选择思考强度。个人 bot 尚未实现 —— 只能在桌面端改。',requiresRichCards: true,},{command: 'agent',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.agent',parityNote: '切换 Agent(Claude Code / Codex / Pi)。个人 bot 尚未实现 —— 只能在桌面端改。',requiresRichCards: true,},{command: 'status',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.status',parityNote:'查看关联状态。官方 bot 经服务端中继, 链路可断; 个人 bot 由桌面端直连 Bot API, 没有等价的「关联状态」概念 —— 这是有意的产品差异, 不是缺口。',requiresRichCards: false,@@ -179,6 +190,7 @@ export const BOT_COMMANDS = [{command: 'unlink',surfaces: ['official'],+ telegramMenuDescriptionKey: 'settings.telegramBot.commandMenu.unlink',parityNote:'解除 Telegram 关联。个人 bot 的 token 由用户自填, 解绑入口在桌面设置页 —— 有意的产品差异。',requiresRichCards: false,@@ -258,6 +270,40 @@ export function isBotCommandAvailableOnChannel(return (definition.textFallbackChannels ?? []).includes(channel);}+/**+ * 官方 bot 的命令菜单(telegram-commands-v1): 每个 Telegram 语言一份。官方菜单按用户的+ * Telegram 语言展示(服务端 setMyCommands 带 language_code), 与个人菜单「按桌面端语言」+ * 的策略不同 —— 沿用两侧各自既有的语言口径, 不在这里统一。+ *+ * 默认菜单(languageCode=null)用英文; zh 取简体(Telegram 的 language_code 只分到 zh,+ * 分不出繁简)。顺序即注册表顺序。+ */+export const OFFICIAL_BOT_COMMAND_MENU_LOCALES: ReadonlyArray<{+ languageCode: string | null;+ locale: SupportedLocale;+}> = [+ { languageCode: null, locale: 'en' },+ { languageCode: 'zh', locale: 'zh-CN' },+ { languageCode: 'ja', locale: 'ja' },+ { languageCode: 'ko', locale: 'ko' },+];++export function buildOfficialBotCommandMenus(+ translate: (+ key: NonNullable<BotCommandDefinition['telegramMenuDescriptionKey']>,+ locale: SupportedLocale,+ ) => string,+): TelegramCommandMenu[] {+ return OFFICIAL_BOT_COMMAND_MENU_LOCALES.map(({ languageCode, locale }) => ({+ languageCode,+ commands: OFFICIAL_BOT_COMMANDS.map(({ command, telegramMenuDescriptionKey }) => ({+ command,+ // 每条命令都有菜单 key(botCommands.test.ts 守门), 非空断言安全。+ description: translate(telegramMenuDescriptionKey!, locale),+ })),+ }));+}+/** 按桌面端语言渲染 owner 作用域的 Telegram 命令菜单。 */export function buildPersonalBotCommandMenu(translate: (key: NonNullable<BotCommandDefinition['telegramMenuDescriptionKey']>) => string,diff --git a/apps/desktop/src/main/im/shared/openChannelSession.ts b/apps/desktop/src/main/im/shared/openChannelSession.tsnew file mode 100644index 0000000000..72bf6a0199--- /dev/null+++ b/apps/desktop/src/main/im/shared/openChannelSession.ts@@ -0,0 +1,91 @@+/**+ * im/shared/openChannelSession.ts+ * ---------------------------------------------------------------------------+ * IM 渠道(个人 IM 与官方 hook)新建任务的公共入口: 经 `openSession` 做与桌面新建+ * 任务同一套模型准入、Git 初始化与账号代次校验(docs/dev-rules/im-turn-flow.md+ * 批次 2)。+ *+ * 只接管「这是一条新任务」的那一刻: 建行本身仍由 commit 回调里各自既有的路径完成+ * —— 个人 IM 是确定性 id 的 upsert 与 `/new` 的轮换事务(写渠道路由列), 官方 hook 是+ * `maker.createSession` 或 `/new` 的只建行。复用 / 接管 / 复活既有任务不经过这里。+ *+ * 准入可能规范化来源 / 推理强度 / Fast(与桌面新建任务同一结果), 回调拿到的是准入后的+ * 路由; 准入拒绝时抛出(文案以「不会自动更换模型或供应商」收尾), 调用方走各自既有的+ * 渠道失败提示, 不静默换模型。+ */++import type { AgentKind, Effort, PermissionMode } from '@cindy/maker-core';++import { normalizeDbAgentKind } from '../../../shared/agentKindConversion';+import { getCurrentDbClientSnapshot } from '../../localDb/client/current';+import { openSession, type SessionOpenBody } from '../../localDb/sessionOpening';++/** 渠道为新任务选定的路由(准入前)。 */+export interface ChannelSessionRoute {+ agentKind: AgentKind;+ model: string;+ providerId: string | null;+ /** 缺席 = 渠道没有显式指定(准入后的默认值不回写给调用方, 保持渠道原有省略语义)。 */+ effort?: Effort;+ /** 缺席同上。 */+ fastMode?: boolean;+ permissionMode: PermissionMode;+ workingDir: string;+ workspaceKind?: 'project' | 'dialogue';+ title?: string;+}++/** 准入后的路由: 只回写渠道显式给过的字段。 */+export interface AdmittedChannelRoute {+ model: string;+ providerId: string | null;+ effort?: Effort;+ fastMode?: boolean;+}++/**+ * 在渠道**开始读取**新任务所需状态(旧任务、默认配置)之前捕获当前账号, 返回复核函数:+ * 账号已变化时抛错。传给 `openChannelSession` 后与 openSession 自己的代次校验一起生效 ——+ * openSession 只能从它被调用的那一刻起守, 之前的读取窗口要靠调用方更早捕获。+ */+export function captureChannelAccount(): () => void {+ const owner = getCurrentDbClientSnapshot();+ return () => {+ if (!owner || getCurrentDbClientSnapshot() !== owner) {+ throw new Error('账号已变化,请重新新建任务');+ }+ };+}++export async function openChannelSession<T>(+ id: string,+ route: ChannelSessionRoute,+ commit: (admitted: AdmittedChannelRoute, assertCurrent: () => void) => Promise<T>,+ assertAccount?: () => void,+): Promise<T> {+ const body: SessionOpenBody = {+ ...(route.title ? { title: route.title } : {}),+ agentKind: normalizeDbAgentKind(route.agentKind) as SessionOpenBody['agentKind'],+ model: route.model,+ providerId: route.providerId,+ ...(route.effort !== undefined ? { effort: route.effort } : {}),+ ...(route.fastMode !== undefined ? { fastMode: route.fastMode } : {}),+ permissionMode: route.permissionMode,+ ...(route.workspaceKind ? { workspaceKind: route.workspaceKind } : {}),+ workingDir: route.workingDir,+ };+ const { value } = await openSession(+ { id, body, ...(assertAccount ? { assertCurrent: assertAccount } : {}) },+ async (row, assertCurrent) =>+ commit(+ {+ model: row.model,+ providerId: row.providerId ?? null,+ ...(route.effort !== undefined ? { effort: row.effort as Effort } : {}),+ ...(route.fastMode !== undefined ? { fastMode: row.fastMode } : {}),+ },+ assertCurrent,+ ),+ );+ return value;+}diff --git a/apps/desktop/src/main/im/shared/sessionRepo.ts b/apps/desktop/src/main/im/shared/sessionRepo.tsindex ffa31023a3..bbce577255 100644--- a/apps/desktop/src/main/im/shared/sessionRepo.ts+++ b/apps/desktop/src/main/im/shared/sessionRepo.ts@@ -34,6 +34,7 @@ import {} from '../defaultSessionSettings';import { buildImDefaultRouteRecord } from './channelDefaultRoute';import { broadcastSessionCreated, broadcastSessionPatched } from './sessionBroadcast';+import { captureChannelAccount, openChannelSession } from './openChannelSession';import type { ImOrchestratorConfig, ImSessionNamespace } from './types';const log = createLogger('im:repo');@@ -146,6 +147,13 @@ export interface ImSessionRepo {getDefaultEffortFor(modelId: string, agentKind?: AgentKind): Effort;}+/**+ * prepareNewSession 产出的默认路由 → 读取它们之前捕获的账号复核函数。调用方常先 prepare+ * (查凭证 / 回显配置)再 createSession, 账号代次要从 prepare 那一刻算起。只按对象身份+ * 关联, 不持有引用(WeakMap), 不需要清理。+ */+const preparedAccounts = new WeakMap<ImSessionRow, () => void>();+export function createImSessionRepo(config: ImOrchestratorConfig,ns: ImSessionNamespace,@@ -379,6 +387,7 @@ export function createImSessionRepo(},async prepareNewSession(botContextId, userId, scopeKey, providerSnapshot) {+ const assertAccount = captureChannelAccount();const id = ns.sessionIdFor(botContextId, userId, scopeKey);const workingDir = ns.ensureWorkingDir(botContextId);const row = rowFromDefaults(@@ -390,6 +399,7 @@ export function createImSessionRepo(// feishu 群 lane → 渠道设置「群聊新建任务权限档」)。const overridden = ns.permissionModeFor?.(userId) ?? null;if (overridden) row.permissionMode = overridden;+ preparedAccounts.set(row, assertAccount);return row;},@@ -403,67 +413,91 @@ export function createImSessionRepo(* 与设置原样保留,绝不让 UNIQUE(sessions.id) 冒泡成用户可见报错(#748)。*/async createSession(botContextId, userId, scopeKey, prepared) {+ // 账号代次从读取默认配置那一刻算起(调用方先 prepare 的, 沿用 prepare 时捕获的)。+ const defaults = prepared ?? (await this.prepareNewSession(botContextId, userId, scopeKey));+ const assertAccount = preparedAccounts.get(defaults) ?? captureChannelAccount();+ assertAccount();const db = getDbClient().drizzle;- const row = prepared ?? (await this.prepareNewSession(botContextId, userId, scopeKey));const now = Date.now();- const persisted = await withSessionRouteLock(row.id, async () => {- const priorRows = await db- .select({ status: sessions.status })- .from(sessions)- .where(eq(sessions.id, row.id))- .limit(1);- if (priorRows[0]?.status === 'deleted') {- await retireDeletedPiSubagentState(row.id);- }- const isFreshInsert = priorRows.length === 0;- await db- .insert(sessions)- .values({- id: row.id,- title: ns.defaultTitle(userId),- ...(row.workspaceKind ?? ns.workspaceKind- ? { workspaceKind: row.workspaceKind ?? ns.workspaceKind }- : {}),- workingDir: row.workingDir,- model: row.model,- effort: row.effort,- permissionMode: row.permissionMode,- fastMode: row.fastMode,- status: 'active',- agentKind: toDbAgentKind(row.agentKind),- providerId: row.providerId,- imDefaultRoute: defaultRouteRecordFor(row),- source: ns.source,- ...ns.extraInsertColumns(botContextId, userId),- createdAt: now,- updatedAt: now,- // IM 会话由用户消息触发创建,插入时即设 userSendAt,- // 避免广播后 renderer 重拉到 userSendAt=null 的行被误判为草稿。- userSendAt: now,- })- .onConflictDoUpdate({- target: sessions.id,- set: {+ // 新任务经公共入口 openSession(与桌面新建任务同一套模型准入 / Git 初始化 / 账号代次+ // 校验); 建行仍是下面这段确定性 id 的 upsert。准入可能规范化来源 / 推理强度 / Fast,+ // 新插入的行写准入后的路由; 冲突分支(并发建出 / 残留行)照旧不碰路由列。+ let row = defaults;+ const persisted = await openChannelSession(defaults.id, {+ agentKind: defaults.agentKind,+ model: defaults.model,+ providerId: defaults.providerId,+ effort: defaults.effort,+ fastMode: defaults.fastMode,+ permissionMode: defaults.permissionMode,+ workingDir: defaults.workingDir,+ ...((defaults.workspaceKind ?? ns.workspaceKind)+ ? { workspaceKind: (defaults.workspaceKind ?? ns.workspaceKind) as 'project' | 'dialogue' }+ : {}),+ title: ns.defaultTitle(userId),+ }, (admitted, assertCurrent) => {+ row = { ...defaults, ...admitted };+ return withSessionRouteLock(row.id, async () => {+ // 等锁期间可能换了账号: 写库前就地复核, 不把旧账号的任务写进新账号的库。+ assertCurrent();+ const priorRows = await db+ .select({ status: sessions.status })+ .from(sessions)+ .where(eq(sessions.id, row.id))+ .limit(1);+ if (priorRows[0]?.status === 'deleted') {+ await retireDeletedPiSubagentState(row.id);+ }+ const isFreshInsert = priorRows.length === 0;+ await db+ .insert(sessions)+ .values({+ id: row.id,+ title: ns.defaultTitle(userId),+ ...(row.workspaceKind ?? ns.workspaceKind+ ? { workspaceKind: row.workspaceKind ?? ns.workspaceKind }+ : {}),+ workingDir: row.workingDir,+ model: row.model,+ effort: row.effort,+ permissionMode: row.permissionMode,+ fastMode: row.fastMode,status: 'active',+ agentKind: toDbAgentKind(row.agentKind),+ providerId: row.providerId,+ imDefaultRoute: defaultRouteRecordFor(row),source: ns.source,- // 冲突分支撞的是残留行 —— 同 findActiveSession, 用户 `/project`- // 切出去的归属不能被渠道默认值刷掉。- ...correctedWorkspaceKind(botContextId),...ns.extraInsertColumns(botContextId, userId),+ createdAt: now,updatedAt: now,+ // IM 会话由用户消息触发创建,插入时即设 userSendAt,+ // 避免广播后 renderer 重拉到 userSendAt=null 的行被误判为草稿。userSendAt: now,- },- });- // upsert 可能走冲突分支(残留行的 sdkSessionId / 模型 / 权限被刻意保留),- // 返回值必须以 DB 持久化结果为准——直接返回 prepared 默认值会让 turn 拿- // sdkSessionId=null 新开对话,而 DB 里旧上下文仍标记 active,两边失配。- const persistedRows = await db- .select()- .from(sessions)- .where(eq(sessions.id, row.id))- .limit(1);- return { row: persistedRows[0], isFreshInsert };- });+ })+ .onConflictDoUpdate({+ target: sessions.id,+ set: {+ status: 'active',+ source: ns.source,+ // 冲突分支撞的是残留行 —— 同 findActiveSession, 用户 `/project`+ // 切出去的归属不能被渠道默认值刷掉。+ ...correctedWorkspaceKind(botContextId),+ ...ns.extraInsertColumns(botContextId, userId),+ updatedAt: now,+ userSendAt: now,+ },+ });+ // upsert 可能走冲突分支(残留行的 sdkSessionId / 模型 / 权限被刻意保留),+ // 返回值必须以 DB 持久化结果为准——直接返回 prepared 默认值会让 turn 拿+ // sdkSessionId=null 新开对话,而 DB 里旧上下文仍标记 active,两边失配。+ const persistedRows = await db+ .select()+ .from(sessions)+ .where(eq(sessions.id, row.id))+ .limit(1);+ return { row: persistedRows[0], isFreshInsert };+ });+ }, assertAccount);const persistedRow = persisted?.row;const result: ImSessionRow = persistedRow? {@@ -513,6 +547,9 @@ export function createImSessionRepo(throw new Error(`${ns.source} does not create a new task for /new`);}const routeId = ns.sessionIdFor(botContextId, userId, scopeKey);+ // 账号代次在读旧任务 / 默认配置之前捕获(调用方先 prepare 的, 沿用 prepare 时的):+ // 中途换账号时不拿旧账号读到的 previous / 默认值去新账号的库里轮换。+ const assertAccount = (prepared && preparedAccounts.get(prepared)) || captureChannelAccount();return withSessionRouteLock(routeId, async () => {const previous = await this.peekSession(botContextId, userId, scopeKey);const defaults = prepared ?? (await this.prepareNewSession(botContextId, userId, scopeKey));@@ -525,10 +562,33 @@ export function createImSessionRepo(workspaceKind: previous?.workspaceKind ?? defaults.workspaceKind,sdkSessionId: null,};- const rotate = async (): Promise<{+ const rotateAdmitted = async (): Promise<{+ current: ImSessionRow;+ previous: ImSessionRow | null;+ }> =>+ // /new 建的是一条新任务: 同样经公共入口 openSession 准入, 轮换事务写准入后的路由。+ openChannelSession(fresh.id, {+ agentKind: fresh.agentKind,+ model: fresh.model,+ providerId: fresh.providerId,+ effort: fresh.effort,+ fastMode: fresh.fastMode,+ permissionMode: fresh.permissionMode,+ workingDir: fresh.workingDir,+ workspaceKind: (fresh.workspaceKind ?? ns.workspaceKind ?? 'project') as 'project' | 'dialogue',+ title: ns.defaultTitle(userId),+ }, (admitted, assertCurrent) => {+ Object.assign(fresh, admitted);+ return rotate(assertCurrent);+ }, assertAccount);+ const rotate = async (+ assertCurrent: () => void,+ ): Promise<{current: ImSessionRow;previous: ImSessionRow | null;}> => {+ // 轮换事务写的是当前账号的库: 取库前就地复核账号代次。+ assertCurrent();const client = getDbClient();const now = Date.now();const markers = ns.extraInsertColumns(botContextId, userId);@@ -581,9 +641,9 @@ export function createImSessionRepo(// The deterministic lane lock serializes Telegram messages; the// current UUID lock also serializes against Desktop archive/delete.if (previous && previous.id !== routeId) {- return withSessionRouteLock(previous.id, rotate);+ return withSessionRouteLock(previous.id, rotateAdmitted);}- return rotate();+ return rotateAdmitted();});},};diff --git a/apps/desktop/src/main/im/shared/turnPresenter.ts b/apps/desktop/src/main/im/shared/turnPresenter.tsindex 6150a28618..b79459e09f 100644--- a/apps/desktop/src/main/im/shared/turnPresenter.ts+++ b/apps/desktop/src/main/im/shared/turnPresenter.ts@@ -30,6 +30,7 @@import {TELEGRAM_PERSONAL_CAPABILITIES,+ TELEGRAM_PROGRESS_FRAME_MAX_CHARS,type TelegramDriverCapabilities,} from '@cindy/im';import type { AgentEvent } from '@cindy/maker-core';@@ -58,9 +59,10 @@ import { turnRetryNotice } from './turnRetryNotice.js';export const PROGRESS_THROTTLE_MS = 1500;/** 无新事件时的低频刷新(过程区耗时行"第 N 步 · 42s"不冻结)。 */export const PROGRESS_TICK_MS = 5000;-/** 单帧快照长度上限: 头部截断 —— server 侧占位消息本就 3900 上限, 中间帧- * 开头(过程区 + 正文起始)信息量最大, 收口后 turn.end 会带完整文本。 */-export const PROGRESS_SNAPSHOT_MAX_CHARS = 3800;+/** 单帧快照长度上限: 头部截断 —— 中间帧开头(过程区 + 正文起始)信息量最大,+ * 收口后 turn.end 会带完整文本。数值取自 @cindy/im 的 Telegram 过程帧上限,+ * 个人 driver 停止编辑的阈值是同一个常量(两侧唯一出处); Slack / X 沿用同值。 */+export const PROGRESS_SNAPSHOT_MAX_CHARS = TELEGRAM_PROGRESS_FRAME_MAX_CHARS;/*** 纯呈现策略(#1855 L1)。无 IO —— 只放 presenter 能自己兑现的项, 两消费方共用diff --git a/apps/desktop/src/main/im/shared/turnRunner.ts b/apps/desktop/src/main/im/shared/turnRunner.tsindex e039896623..5288f586de 100644--- a/apps/desktop/src/main/im/shared/turnRunner.ts+++ b/apps/desktop/src/main/im/shared/turnRunner.ts@@ -106,7 +106,7 @@ import {wireSessionToIpcExternal,takePendingInteractionsForSession,noteSilentStopUserSend,- noteSilentStopSessionReset,+ stopSessionTurnExplicitly,onSilentStopSettled,} from '../../maker-ipc/register';import { clearPendingTurnChangeSets } from '../../turn-change-set/store';@@ -3909,9 +3909,9 @@ export function createTurnRunner(}const active = state.queue[0];if (!active || !matches(active)) return { stopped: removed.length > 0, droppedQueued: removed.length };- noteSilentStopSessionReset(state.makerSession.id);active.terminalKind = 'aborted';- await current?.abort();+ // 与桌面 Stop 同一套清理(撤续跑 / 取消恢复 / 暂停 Goal / 停输入队列并中止当前一轮)。+ await stopSessionTurnExplicitly(state.makerSession.id);return { stopped: true, droppedQueued: removed.length };}const running =@@ -3921,13 +3921,12 @@ export function createTurnRunner(// 先清排队再 abort — abort 触发的 done/error 会走 maybeDispatchNextQueued,// 队列不清空的话下一条排队消息会在中止后立刻自动派发。clearPendingSends(state);- // 重置 silent-stop 守卫(与 desktop ABORT_SESSION handler 同源): turn 若正- // 挂在 silentStop 的 1.5s 决策窗里, abort 对早已收尾的 SDK turn 是 no-op、- // 不产生任何事件,不重置的话守卫照样自动续跑,用户喊停后 agent 原地复活。- // 重置后守卫判 superseded → settle('skip') → 挂起 turn 经现有订阅按 done 收口。- noteSilentStopSessionReset(state.makerSession.id);if (state.queue[0]) state.queue[0].terminalKind = 'aborted';- await current?.abort();+ // 与桌面 Stop 同一套清理(docs/dev-rules/im-turn-flow.md 不变量 9): 撤 silent-stop /+ // 中断续跑守卫(turn 若正挂在 silentStop 的决策窗里, abort 对早已收尾的 SDK turn 是+ // no-op, 不重置的话守卫照样自动续跑, 用户喊停后 agent 原地复活)、取消上下文溢出恢复、+ // 暂停 Goal、停输入队列并中止当前一轮(唯一的一次 abort)。+ await stopSessionTurnExplicitly(state.makerSession.id);log.info(`!stop aborted turn for session=...${state.makerSession.id.slice(-8)} droppedQueued=${droppedQueued}`,);diff --git a/apps/desktop/src/main/maker-ipc/register.ts b/apps/desktop/src/main/maker-ipc/register.tsindex a8d0386184..2972ce8f4d 100644--- a/apps/desktop/src/main/maker-ipc/register.ts+++ b/apps/desktop/src/main/maker-ipc/register.ts@@ -1671,6 +1671,35 @@ export function noteSilentStopSessionReset(sessionId: string): void {resetAutomaticRecoveryForExplicitStop(sessionId);}+/** 统一明确停止的实现(coordinator 就绪后由注册流程装上)。 */+let explicitStopImpl: ((sessionId: string) => Promise<void>) | null = null;++/**+ * 用户明确喊停的统一入口 —— 与桌面 Stop 同一套清理, 顺序固定:+ * 1. 撤自动续跑与退避簿记(resetAutomaticRecoveryForExplicitStop);+ * 2. 取消上下文溢出恢复;+ * 3. 发起 Goal 暂停(同步摘掉 listener / timer, 落盘与中止并行);+ * 4. coordinator.stop: 撤已排期续跑、清队列、中止当前一轮(唯一的一次 abort)并清理+ * 待决交互;+ * 5. 等 Goal 落盘与队列快照落盘。Goal 落盘失败在中止**之后**才抛 INTERNAL —— 与桌面+ * Stop 同一顺序, 存储错误不能挡住用户的喊停。+ *+ * 外部渠道(个人 IM `/stop`、官方 hook `task.cancel`)与伙伴群聊 / 委派的停止都走这里,+ * 不再各自拼一份(见 docs/dev-rules/im-turn-flow.md 不变量 9)。调用方不要再自己+ * `session.abort()` —— 重复中止会向 vendor 发两次 interrupt。+ *+ * 注册前(启动早期 / 单测)退回最小语义: 撤自动续跑 + 暂停 Goal + 中止当前一轮。+ */+export async function stopSessionTurnExplicitly(sessionId: string): Promise<void> {+ if (explicitStopImpl) {+ await explicitStopImpl(sessionId);+ return;+ }+ resetAutomaticRecoveryForExplicitStop(sessionId);+ const goalPause = pauseGoalBeforeExplicitStop(sessionId);+ await Promise.all([goalPause, getMaker().getSession(sessionId)?.abort()]);+}+/*** silent-stop 决策结果通知:scheduler/hook runner 等 in-process 监听方无法从* session.onEvent 收到合成的 settle 信号,通过本回调获知非续跑决策已做出,@@ -10488,14 +10517,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)onAccepted,}),prepareAttachments: botGroupAttachments.prepare,- abortLane: async (sessionId) => {- await inputCoordinator.ensureQueueRestored(sessionId);- resetAutomaticRecoveryForExplicitStop(sessionId);- contextOverflowRolloverHolder?.cancelRecovery(sessionId);- await pauseGoalBeforeExplicitStop(sessionId);- inputCoordinator.stop(sessionId);- await awaitAgentInputQueueSnapshotPersistence(sessionId);- },+ abortLane: (sessionId) => stopSessionTurnExplicitly(sessionId),closeLanes: async (sessionIds) => {await Promise.all(sessionIds.map((id) => maker.closeSession(id).catch(() => undefined)));},@@ -10655,14 +10677,7 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)}),discardDelegationQueuedInputs: (sessionId, delegationId) =>discardDelegationQueuedInputs(inputCoordinator, sessionId, delegationId, awaitAgentInputQueueSnapshotPersistence),- abortSession: (async (sessionId) => {- await inputCoordinator.ensureQueueRestored(sessionId);- resetAutomaticRecoveryForExplicitStop(sessionId);- contextOverflowRolloverHolder?.cancelRecovery(sessionId);- await pauseGoalBeforeExplicitStop(sessionId);- inputCoordinator.stop(sessionId);- await awaitAgentInputQueueSnapshotPersistence(sessionId);- }),+ abortSession: (sessionId) => stopSessionTurnExplicitly(sessionId),closeSession: (sessionId) => maker.closeSession(sessionId),broadcastSessionCreated,onChanged: (payload) => {@@ -16341,6 +16356,15 @@ export function registerMakerIpc(maker: Maker, options: RegisterMakerIpcOptions)getPersistedClientIds: getPersistedInputClientIds,});agentInputCoordinatorHolder = inputCoordinator;+ explicitStopImpl = async (sessionId) => {+ await inputCoordinator.ensureQueueRestored(sessionId);+ resetAutomaticRecoveryForExplicitStop(sessionId);+ contextOverflowRolloverHolder?.cancelRecovery(sessionId);+ // 与桌面 Stop 同序: Goal 暂停同步摘掉续跑源后, 中止先发出, 再等落盘(失败此时才抛)。+ const goalPause = pauseGoalBeforeExplicitStop(sessionId);+ inputCoordinator.stop(sessionId);+ await Promise.all([goalPause, awaitAgentInputQueueSnapshotPersistence(sessionId)]);+ };setSharedTaskQueueReader((sessionId, clientId) => {const item = inputCoordinator.getProjection(sessionId).pendingQueue.find((pending) => pending.clientId === clientId);return item ? { sessionId, authorAccountId: item.sharedTaskAuthor?.accountId ?? '', state: 'pending', attachments: item.files } : undefined;diff --git a/apps/desktop/src/renderer/i18n/locales/en/common.json b/apps/desktop/src/renderer/i18n/locales/en/common.jsonindex dbb3087847..1ee0acc261 100644--- a/apps/desktop/src/renderer/i18n/locales/en/common.json+++ b/apps/desktop/src/renderer/i18n/locales/en/common.json@@ -3231,7 +3231,13 @@"permission": "Show or switch the permission mode","settings": "Show project and agent settings","ctr": "Remotely control a desktop session",- "exctr": "Exit remote control"+ "exctr": "Exit remote control",+ "workspace": "Switch project workspace",+ "unbind": "Clear the current project mapping",+ "effort": "Choose reasoning effort",+ "agent": "Choose an Agent",+ "status": "Show link status",+ "unlink": "Unlink Telegram"},"behavior": {"title": "Reactions & quoting",diff --git a/apps/desktop/src/renderer/i18n/locales/ja/common.json b/apps/desktop/src/renderer/i18n/locales/ja/common.jsonindex 0d12baf789..3489c5149a 100644--- a/apps/desktop/src/renderer/i18n/locales/ja/common.json+++ b/apps/desktop/src/renderer/i18n/locales/ja/common.json@@ -3230,7 +3230,13 @@"permission": "権限モードを表示・切り替え","settings": "プロジェクトと Agent 設定を表示","ctr": "デスクトップセッションをリモート操作",- "exctr": "リモート操作を終了"+ "exctr": "リモート操作を終了",+ "workspace": "プロジェクトワークスペースを切り替え",+ "unbind": "現在のプロジェクト設定を解除",+ "effort": "推論強度を選択",+ "agent": "Agent を選択",+ "status": "連携状態を表示",+ "unlink": "Telegram 連携を解除"},"behavior": {"title": "リアクションと引用",diff --git a/apps/desktop/src/renderer/i18n/locales/ko/common.json b/apps/desktop/src/renderer/i18n/locales/ko/common.jsonindex 458f60550c..2a0fc2ae12 100644--- a/apps/desktop/src/renderer/i18n/locales/ko/common.json+++ b/apps/desktop/src/renderer/i18n/locales/ko/common.json@@ -3230,7 +3230,13 @@"permission": "권한 모드 보기·전환","settings": "프로젝트와 Agent 설정 보기","ctr": "데스크톱 세션 원격 제어",- "exctr": "원격 제어 종료"+ "exctr": "원격 제어 종료",+ "workspace": "프로젝트 워크스페이스 전환",+ "unbind": "현재 프로젝트 매핑 해제",+ "effort": "추론 강도 선택",+ "agent": "Agent 선택",+ "status": "연결 상태 보기",+ "unlink": "Telegram 연결 해제"},"behavior": {"title": "리액션과 인용",diff --git a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.jsonindex 1d2752a781..b4d746847d 100644--- a/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json+++ b/apps/desktop/src/renderer/i18n/locales/zh-CN/common.json@@ -3230,7 +3230,13 @@"permission": "查看或切换权限模式","settings": "查看当前项目与 Agent 设置","ctr": "接管桌面端的任务",- "exctr": "退出远程控制"+ "exctr": "退出远程控制",+ "workspace": "切换项目工作区",+ "unbind": "清除当前项目映射",+ "effort": "选择推理强度",+ "agent": "选择 Agent",+ "status": "查看关联状态",+ "unlink": "解除 Telegram 关联"},"behavior": {"title": "回应与引用",diff --git a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.jsonindex 3c918575fb..8c67f83f2f 100644--- a/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json+++ b/apps/desktop/src/renderer/i18n/locales/zh-TW/common.json@@ -3230,7 +3230,13 @@"permission": "檢視或切換權限模式","settings": "檢視目前專案與 Agent 設定","ctr": "接管桌面端的任務",- "exctr": "退出遠端控制"+ "exctr": "退出遠端控制",+ "workspace": "切換專案工作區",+ "unbind": "清除目前專案對應",+ "effort": "選擇推理強度",+ "agent": "選擇 Agent",+ "status": "檢視關聯狀態",+ "unlink": "解除 Telegram 關聯"},"behavior": {"title": "回應與引用",diff --git a/docs/dev-rules/im-turn-flow.md b/docs/dev-rules/im-turn-flow.mdnew file mode 100644index 0000000000..d1c2fbe646--- /dev/null+++ b/docs/dev-rules/im-turn-flow.md@@ -0,0 +1,152 @@+# IM 一轮任务:入口账本与状态模型++> **状态**:权威开发规则(authoritative),随「IM 一轮任务合并」分批迁移持续更新+> **读取时机**:修改个人 IM 渠道(`apps/desktop/src/main/im/**`)或官方 hook+> (`apps/desktop/src/main/hook-control/**`)的找/建任务、命令、排队与插话、输入拼装、+> 事件观察、表情、交互、收尾或停止逻辑之前++个人 IM 渠道(Telegram / 飞书 / 微信 / 钉钉 / Discord / 企业微信)与官方 hook(官方+Telegram / Slack / X)是同一件事的两套实现:把渠道里的一条消息变成 Cindy 任务里的一轮,+再把结果送回渠道。本文登记两套实现**今天各自在哪一步做了什么**、**持有哪些状态**、+**合并后归谁**,以及迁移中必须守住的不变量。用户可见的两侧差异另见+[`../product-rules/telegram-bot-parity.md`](../product-rules/telegram-bot-parity.md);+台账里标「有意不同」的项以策略参数表达,合并时不抹平。++## 1. 入口账本++每一行是一轮任务的一个步骤。「现状」列写真正干活的函数;「目标」列写合并后的归属:+**公共入口**(App 的既有入口,IM 不再另写)、**共用流程**(新的 IM 一轮任务模块,两侧+同一份)、**渠道适配**(只保留入站来源、出站载体、台账登记的有意差异)。++| 步骤 | 个人 IM 现状 | 官方 hook 现状 | 目标归属 |+|---|---|---|---|+| 入站 | 各渠道 adapter → `im/shared/messageHandler.ts`(微信经 `WechatTaskStore` 持久队列) | `hook-control/manager.ts` 收 `task.dispatch` → `dispatcher.handleDispatch` | 渠道适配(入站来源各自保留) |+| 幂等与重投 | 无(个人连接无重投) | `ackHistory` / `inflightRequests` / `terminalLedger` | 渠道适配(服务端重投是 hook 的传输语义) |+| 找任务 | `turnRunner.resolveRouteTarget`:通知回复 → `/ctr` 绑定 → 确定性 id 通道行(`sessionRepo.findActiveSession` 复活归档行) | `dispatcher.resolveTarget`:接管 sessionId → 绑定复用(每条消息按工作目录映射现场重算)→ 失效则换任务并交接 | 共用流程的「定位」骨架 + 渠道策略(台账第三节「绑定的任务失效后怎么接续」有意不同) |+| 建任务 | `sessionRepo.createSession` 确定性 id upsert;`createFreshSession`(`/new` 轮换事务);随后 `maker.createSession` —— 2026-10 起两处建行都经 `openChannelSession` → **`openSession`**(模型准入) | `session-runner` 新任务的 `maker.createSession`、`/new` 的 `desktopSessionStorage.create` —— 同样经 `openChannelSession` → **`openSession`** | **公共入口 `openSession`**(已完成,批次 2);渠道专属建行在 commit 回调里。live session 仍各自 `maker.createSession`,未改用 register 内部的 `bootstrapSession`(会新增项目上下文 / Orca 指令注入等行为,见 §6) |+| 默认配置 | `resolveImSessionDefaults(channel)` + 跟随渠道默认(`channelDefaultRouteSync`) | `resolveNewSessionConfig`(目录偏好 > 全局 IM 默认 > 清单首项;权限档规则见 `defaults.ts`) | 渠道策略(台账第三节「新会话的默认…从哪读」有意不同) |+| 命令 | `messageHandler.processOne` → `slashCommands`(注册表 `botCommands.ts`) | 服务端分发命令,桌面只收 `query.*` | 渠道适配(官方命令分发在服务端) |+| 排队与插话 | `SessionState.sendQueue`(内存、无上限、重启丢失);无插话 | `dispatcher.queues`(内存、上限 20)+ `drainPolls`;无插话 | **公共入口 `AgentInputCoordinator`**(见 §5 批次 3 与 §6 待决项) |+| 输入拼装 | `prepareAgentTurnText`(群上下文 / ambient 提示)+ `buildImChannelNote` + `buildImUserMessage`;派发时前置交接 / 计划对账 / Goal 提示 | `buildContextPrefix` + `composeXPrompt` + `buildHookPromptNote`;同样前置交接 / 计划对账(仅 IM 来源)/ Goal 提示 | 共用流程(前置层同一份;渠道说明文案有意不同,见台账「入站上下文」) |+| 用户消息落库 | 部分渠道提前落库(`persistInboundUserMessageEarly`),`onAccepted` 补 `imSource` | 只在 `onAccepted` 落库,`agentMeta.hookSource` | 共用流程(`onAccepted` 落库;提前落库保留为渠道能力) |+| 发送 | `makerSession.send`,`MAIN_OWNED_SEND_CONTEXT.origin.kind='im'` | `session.send`,origin `hook`(Telegram/X)或 `im`(Slack) | 共用流程;Pi 管理命令授权来源按渠道各自声明(hook 不得伪装成本机命令) |+| 观察事件 | `turnPresenter`(buffer-replace)+ 流式 handle | `turnObserver`(finalized-segments)+ 进度发射器 | 共用流程(presenter 已同源;两个正文累积引擎有意不同) |+| 表情 | `TurnState` 的 ack 句柄 | `ackReactions`(msg.op react) | 渠道适配(出站载体不同,档位语义同源) |+| 交互 | `beginInteractionRoute` + `pendingInteractions` + 渠道卡片 | `beginInteractionRoute` + `interactions.ts`(30 分钟超时)+ 卡片发布器 | 共用流程(路由与语义层已同源;超时差异见台账缺口 2g) |+| 收尾 | `handleTurnDoneAsync` / `handleTurnErrorAsync` → 流式 handle finalize | `execute` 收口 → `turnCarrier.publishFinal` → `turn.end`(持久出箱) | 共用流程的收口骨架 + 渠道出站载体 |+| 停止 | `turnRunner.stopActiveTurn`:清 `sendQueue` + 撤自动续跑 + `abort()`;**不暂停 Goal、不停 coordinator** | `dispatcher.cancel` → `abortSession`:只 `abort()`;**不撤自动续跑、不暂停 Goal** | **公共入口:统一明确停止**(`stopSessionTurnExplicitly`,与桌面 Stop 同一套清理) |+| 重启恢复 | 无(微信例外:`WechatTaskStore`) | 终稿持久出箱(`requestLedger`,24h) | 渠道适配(终稿必达是 hook 的保障;台账缺口 3) |++## 2. 状态清单++只列跨轮持有、会影响正确性的状态。「去向」:**保留**(留在渠道适配)、**并入**(进共用流程,+两侧一份)、**替换**(由公共入口持有,删除本地副本)。++| 状态 | 位置 | 键 | 去向 |+|---|---|---|---|+| `userLocks` | `im/shared/messageHandler.ts` | `ctx:sender:scope` | 保留(入站串行化是渠道语义) |+| `sessionStates` / `SessionState.queue` | `im/shared/turnRunner.ts` | sessionId | 并入(「每会话当前一轮」的观察状态) |+| `SessionState.sendQueue` / `dispatchRetryTimer` | 同上 | sessionId | **替换**为 coordinator 队列 |+| `queues` / `running` / `drainPolls` | `hook-control/dispatcher.ts` | sessionId | **替换**为 coordinator 队列(`running` 只剩观察态) |+| `keyChains` / `sessionAdmissionChains` / `worktreeChain` | dispatcher | externalKey / sessionId | 保留(hook 的接活串行化) |+| `ackHistory` / `inflightRequests` / `pendingTurnEnds` / `pendingDeliveryTurnEnds` / `requestLedger` | dispatcher | requestId | 保留(hook 传输与终稿必达) |+| `runningByRequest` / `cancelRequested` / `pendingGroupAdmissions` | dispatcher | requestId | 保留(服务端 requestId → 任务的映射) |+| `pendingReopens` / `activeContinuations` / `pendingClaims` | dispatcher | sessionId | 保留(turn-reopen-v1 是官方能力) |+| `awaitingPersist` / `staleTakeoverReplacements` / `latestPromptBySession` | dispatcher | sessionId / key | 保留(hook 的定位策略) |+| `controlState.inProgress` / 绑定库 | `im/shared/controlState.ts` / `im/binding.ts` | bot:user | 保留(`/ctr` 是个人渠道能力) |+| `pendingInteractions.pending` / `interactions.ts pending` | 两侧 | requestId / interactionId | 并入(批次 5:交互挂起表合一,超时策略按渠道参数) |+| `groupHistoryAccess.activeBySession` | `im/shared` | sessionId | 已同源,不动 |+| Telegram 传输层(`chatQueues` / `typingLoops` / 回挂目标) | `packages/lizi-im/src/telegram/index.ts` | chat | 保留(个人出站载体) |++**不为合并新增**全局状态机或持久化表:队列与停止交给已有公共入口持有的状态;合并只移动和+删除现有状态。++## 3. 不变量(迁移每一批都必须守住)++1. **同一 externalKey / 同一渠道行 → 同一任务**;建任务与复用的判据不因迁移改变(台账第三节)。+2. **已提前落库的用户消息不重复插入**:`onAccepted` 只补元数据(`existingClientId`)。+3. **来源标签与模型说明同源**([`message-source.md`](../product-rules/message-source.md)):+ IM 写 `agentMeta.imSource`,hook 写 `agentMeta.hookSource`;新数据不得塞进 `origin`+ (coordinator 把任何 `origin.kind` 当非人工输入)。+4. **Pi 管理命令授权来源**:个人 IM 用 `authenticated-im-command`;官方 hook 的 origin+ 是 `hook`,**不得**伪装成 `local-desktop-command`;`MAIN_OWNED_SEND_CONTEXT` 是 Symbol,+ 跨队列快照时必须由宿主在派发时重新盖章,不能指望它随队列项持久化。+5. **session-new-v1**:`/new` 成功时新任务已落库并出现在列表;**turn-reopen-v1**:续跑轮+ 断连即终局、`turn.end` 直发不缓存。+6. **群历史租约**:`beginGroupHistoryAccess` 在 provider 真正开始这一轮前登记、终态释放;+ `sessionInstanceId` 挡住旧实例借用新权限。+7. **计划对账**只在真实用户轮次注入(官方仅 `source.im` 存在时)。+8. **终稿必达**(官方):`turn.end` 先进持久出箱;客户端发布终稿时以 `clientFinal` 交回。+ 带附件的轮次不由客户端发布(出箱只存文本);兜底帧写不进出箱时也不由客户端发布;本进程+ 仍在发布、正式 `turn.end` 还没进入发送 / 缓冲路径时,重连扫描与服务端重投 `task.dispatch` 都不重放出箱里的兜底帧(重投只回放 ack);终稿段+ 回执未知先同 opId 有界重发对账,仍未知才交回。+9. **明确停止 = 与桌面 Stop 同一语义**:撤自动续跑与退避簿记、取消上下文溢出恢复、暂停+ Goal、停 coordinator(中止当前一轮、清 coordinator 队列、清理待决交互)。用户喊停后不得有+ 任何自动续跑原地复活;hook 自有队列(`queues`)不在此列,并入 coordinator 前的语义见 §6;+ Goal 落盘失败只能在中止之后报错,不能挡住停止。+10. **hook 的续跑观察不把自己的轮次当成桌面轮次**:hook 轮次一旦经 coordinator 派发,+ `subscribeUiTurnDispatching` 必须能按 clientId 认出它(否则会误撤续跑)。+11. **一轮绑定入口时的账号**:新建任务从**读取**旧任务 / 默认配置之前捕获账号+ (`captureChannelAccount`,先 prepare 再建的沿用 prepare 时捕获的),经+ `openChannelSession` 带进 `openSession`,准入前后与写库前都复核,建行之后的补写(来源、发送时间、worktree)也不例外;账号变了就终止这次派发(官方 hook 在 `session.send` 前复核),不只是跳过补写;一轮的出站 msg.op+ (进度、终稿、卡片、旧卡片帧)只经所属账号代次的连接发出,换账号后视同离线。+ **边界**:`Maker.createSession` 内部「先异步启动 Agent、再取当前库写行」的窗口不在本条范围——+ 它是桌面、IM、目标恢复等所有建任务入口共有的既有问题,要堵需让账号守卫穿过 maker-core+ 启动 / 持久化边界或新增回滚机制,另行处理。++## 4. 状态模型(一轮)++```+inbound ──► admitted ──► queued? ──► dispatching ──► running ──► finalizing ──► terminal+ (渠道) (定位/建任务) (coordinator) (前置层+send) (观察事件) (渠道出站收口) ok|error|cancelled+ │ │ │ │+ └── rejected ────┴── discarded ──┴── stopped ───┘+```++- **admitted → queued**:会话忙(`isTurnRunning` 或 coordinator 有积压)时入 coordinator,+ 带 `onAccepted` / `onAcceptedRollback` / `onDiscarded`;空闲时直接进入 dispatching。+- **dispatching**:前置层(交接 / 计划对账 / Goal 提示 / 渠道说明)只在这一步加,**不进+ 持久化文本与队列文本**;`onAccepted` 是用户消息落库与「已受理」副作用(群上下文游标提交、+ ack 表情转处理中)的唯一边界。+- **running**:一轮只有一个观察者;终态只由 `done`(非 silent-stop / 非续跑中间边界)、+ 终态 error、会话 closed/error 三个出口给出(`turnObserver` 的收口规则)。+- **stopped**:任何来源的明确停止都走 `stopSessionTurnExplicitly`;队列中的项经 coordinator+ `onDiscarded` 收口(hook 回 `turn.end(cancelled)`,IM 撤排队表情)。+- **terminal**:渠道出站收口(个人:流式 handle finalize;官方:`turn.end` 与客户端终稿)。+ 每个 settle 路径(resolve / reject / 超时 / 取消 / 乱序 / 迟到 / 重复)只有一个判据。++## 5. 迁移批次++每批独立可验证:跑 `pnpm test:unit:related` 与相关 package typecheck,本地 commit。++1. **统一明确停止**(已完成):`register.ts` 里重复的内联停止序列抽成导出的+ `stopSessionTurnExplicitly`(伙伴群聊 lane 与伙伴委派原来各抄一份,改调它);IM+ `/stop`(含微信)与 hook `task.cancel` 改调它,账号边界中止仍是普通 abort。+2. **新建任务走 `openSession`**(已完成):`im/shared/openChannelSession.ts` 是两侧共用的+ 薄包装 —— 准入前的路由送进 `openSession`,建行回调拿准入后的路由;IM `createSession` /+ `createFreshSession`、hook 新任务与 `/new` 的只建行都经它。复用 / 接管 / 复活既有任务+ 不经过准入。准入拒绝时抛出,调用方走各自既有的渠道失败提示。+3. **排队走 `AgentInputCoordinator`**(2026-10-06 Dash 决定另开 PR,先出设计说明):删 IM+ `sendQueue` 与 hook `queues`;coordinator 队列项补 `imSource` / `hookSource` 字段(不进+ `origin`),派发时由宿主补渠道说明并重盖 `MAIN_OWNED_SEND_CONTEXT`;hook dispatcher 按+ clientId 认出自己的轮次。**已查明的前提**:coordinator 派发一项时接管的是整轮生命周期+ (发送事务里落库用户消息、绑定 vendor turn、出错时套用中断自动续跑 / 错误横幅 / 上下文+ 恢复),所以「只当候车室、轮到时转回渠道自己发」做不干净 —— 迁移后渠道轮次就是+ coordinator 轮次,§6 前四行的可见变化要逐条定下来再动手。+4. **共用一轮流程骨架**(随批次 3 另开 PR):把「定位 → 拼装 → 发送 → 观察 → 收口」抽成共用模块,两侧只注入+ 渠道适配(入站来源、出站载体、§1 标注的策略参数)。+5. **交互挂起表合一**、**台账缺口收敛**(随批次 3 另开 PR):缺口的最终取向逐项写回台账,用户可见变化按 §6 处理。++## 6. 待 Dash 决定(默认保持各自现状)++| 项 | 个人 IM 现状 | 官方 hook 现状 | 合并后若不决定 |+|---|---|---|---|+| 重启后排队消息 | 丢失 | 已 ack 为 queued 的任务丢失,服务端靠 lease 超时收口 | coordinator 快照会恢复为**暂停**队列,等用户再发消息才继续 |+| 渠道轮次的中断自动续跑 / 错误横幅 / 上下文恢复 | 无 | 无 | 迁到 coordinator 后自然覆盖(与桌面同语义);与 `maker-core-and-agent-behavior.md` 「IM 绑定任务不进图片历史自动恢复」那条要一并核对 |+| 排队消息在桌面端可见 / 可删 | 不可见 | 不可见 | 迁到 coordinator 后自然可见、可删(删除即视同撤回:IM 撤排队表情,hook 回 `turn.end(cancelled)`) |+| 排队上限 | 无上限 | 每会话 20 | 各自保留:IM 不限,hook 仍按 20 拒收 |+| 停止时同任务已排队的消息 | `/stop` 一并清掉 `sendQueue` | 服务端 `/stop` 只对正在跑的那一个 requestId 发 `task.cancel`;desktop hook 队列里同任务已排队的请求照常接着跑(本 PR 前即如此) | 未改:一并清掉等于替用户丢弃没被取消的请求、并以 cancelled 收口,属产品语义;随批次 3(hook 队列并入 coordinator)一起定 |+| 插话(steer) | 无 | 无 | 不新增 |+| 模型准入(`openSession`) | 只做凭证检查 | 新任务做路由检查 | 已按 Dash 指定改走 `openSession` 准入:新任务的模型 / 来源 / 推理强度 / Fast 不被支持时直接拒绝(文案「不会自动更换模型或供应商」),准入还会规范化来源与推理强度;渠道默认配置若指向已停用的模型,新任务会建不出来(以前会照建) |+| live session 改走 `bootstrapSession` | 不注入项目上下文 / Orca 指令 | 同左 | 未改:改了等于给 IM / hook 任务新增项目上下文与 Orca 指令注入、目录授权准备等行为,属产品决定 |+| 缺口 2b / 2e / 2f / 默认配置取值链 | 见台账 | 见台账 | 各自保留,合并只共享实现骨架 |diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.mdindex eb31d3b937..1244fea79d 100644--- a/docs/dev-rules/protocol-compatibility.md+++ b/docs/dev-rules/protocol-compatibility.md@@ -533,6 +533,51 @@ handler 无 sender 依赖;不加入共享任务访客白名单,不进入自## 1. 两仓本地协议演进+### 官方 Telegram 进度消息由客户端渲染(`telegram-progress-ops-v1`)++双向能力,只在 telegram 连接上声明,且必须与 `msg-op-v1` 同时协商。协商后桌面端用与个人+bot 同一份过程载体与渲染(见 `docs/product-rules/telegram-bot-parity.md` 第一节)经+`msg.op` 驱动进度消息;服务端只执行,`turn.progress` 照发但只用于续 lease(私聊草稿模式+例外,仍由服务端按 `turn.progress` 出草稿)。全部为可选字段增量:++- `MessageOpPayload.purpose?: 'turn-progress'`:有它时 `requestId` 必填,只用于+ `send` / `edit`(parse 强制)。服务端据 requestId 核验设备归属,把新消息登记为该轮进度+ 消息,终稿后照旧清理;本轮不归客户端承载或已收口时回 `PROGRESS_UNAVAILABLE`。+- `MessageOpResultPayload.errorCode?: string | null`:服务端自判拒绝码(开放集合,常量+ `MESSAGE_OP_ERROR_*`);`channelErrorCode?: number | null`:Telegram 原生 error_code+ 原样透传,`error` 放渠道原文。+- 幂等:服务端按 opId + 内容指纹去重;回执未知(含 `OUTCOME_UNKNOWN`)时客户端原样重发+ 同 opId 同正文,不换号、不换正文。服务端有应答时只回显原结果;也没有应答时每个 opId+ 只重新执行一次,之后回显缓存的 `OUTCOME_UNKNOWN`。卡片与终稿段最多原样重发 2 次,仍未知+ 就放弃(终稿以 `clientFinal.complete=false` 交回);进度首帧每个节流窗口重发一次。++任一侧缺席时行为与本能力出现前逐字相同;无数据库迁移、Mobile 冷更或部署顺序要求。实现见+`hook-control/telegramTurnCarrier.ts`、`telegramMsgOp.ts` 与+`packages/lizi-im/src/telegram/outboundPolicy.ts`。++同一轴上另有三个独立协商的能力(都要求同时协商 `msg-op-v1`,任一缺席该段照旧由服务端+渲染):++- `telegram-final-ops-v1`:普通成功轮次的终稿经 `purpose: 'turn-final'`(`send` 带+ `finalPart`;协议形状仍允许 `media`,但服务端一律拒收,桌面端也不发:带附件的轮次整轮随 `turn.end`+ 交给服务端,因为持久出箱只存终态文本,本端上传附件中途退出会丢附件)发布;+ `TurnEndPayload.clientFinal?: { complete }` 告诉服务端是否全部确认。complete 时服务端+ 不再渲染、提升续跑锚点并做收口副作用;否则删掉已落地的客户端终稿段并照旧自己发布。+ 私聊草稿模式下服务端对终稿 op 回 `TURN_UNAVAILABLE`(终稿随草稿通道由服务端发布),+ 桌面端按停手码交回。桌面端发布前先把不带 `clientFinal` 的 `turn.end` 写进持久出箱,+ 崩溃重放走「交回服务端」那一版,终稿必达不降级;本进程仍在发布时重连不重放这份兜底帧。+- `telegram-card-ops-v1`:执行中交互卡经 `purpose: 'interaction-card'`(带+ `interactionId`;收口 `edit` 带 `interactionClosed` 并清空按钮)发布;按钮 token 即+ buttonId,回调仍由服务端转成 `interaction.decision`。协商后桌面端不再为这类卡发+ `interaction.request` / `interaction.cancel`,op 被明确拒绝时才回落旧帧。+- `telegram-commands-v1`:新增 `provider.commands.set` 帧(默认菜单有且仅有一份,+ command / description 遵守 Telegram 限制),服务端执行 `setMyCommands`;只管理默认菜单与+ `zh` / `ja` / `ko`,每次全量重写,其它语言码(含显式 `en`)忽略。菜单只存服务端+ 内存、不落库:desktop 每次握手重发,服务端重启后到桌面重连前用服务端默认菜单。++新增拒绝码 `TURN_UNAVAILABLE`(终稿 / 卡片 op 时这一轮已收口或不属于该设备)。`msg.op`+各 purpose 允许的动作与附属字段由 parse 强制联动,放错位置一律拒收。+### X 回复链的结构化输入服务端负责 X 事件、账号绑定、真实回复链读取与预算、可靠派发和回传;Desktop 的diff --git a/docs/product-rules/telegram-bot-parity.md b/docs/product-rules/telegram-bot-parity.mdindex 379641c24b..3b98f19b03 100644--- a/docs/product-rules/telegram-bot-parity.md+++ b/docs/product-rules/telegram-bot-parity.md@@ -59,6 +59,12 @@ App 完成未读与提醒统一由 `renderer/hooks/useSessionRunningStatus.ts`| 普通工具权限的多处确认 | `maker-ipc/interactionRouter.ts` + `sharedPermission.ts` | IM 与 Cindy 共用一个决定,首次有效回答生效,桌面/手机与渠道同步收口。来源正文由 `im/shared/interactionSource.ts` 构造;个人富卡与官方 Hook 分别负责各自载体更新。未来渠道复用同一注册接口,详见 [共享合同](im-permission-confirmation.md)。 || 模型列表的开关就绪 | `maker-host/model-visibility-mirror.ts` | 个人 `/model` 与官方 `listAgentModels` 均等待当前账号配置同步;超时返回错误,不把未同步当成全部关闭或回退出厂开关。 || 过程区与正文的**文本合成** | `im/shared/turnPresenter.ts` + `turnActivity.ts` | 过程区怎么排(工具步骤、思考步骤、耗时行)、过程区与正文怎么拼(`composeProgressView`)。**正文累积不算**——见第三节:`createTurnPresenter` 按 `mode` 实例化两个独立引擎,累积、消息投影、`finalText()` 判据都不同,改一个引擎不影响另一个 |+| 运行中**过程消息**的生命周期、渲染与出站失败判据(官方需双方协商 `telegram-progress-ops-v1`) | `packages/lizi-im/src/telegram/streamingText.ts`(`startTelegramProgressCarrier` 与个人 `startTelegramStreaming` 是同一个 handle 类)+ `progressFrame.ts` + `outboundPolicy.ts` + `markdown.ts` 的 `markdownToTelegramHtml` | 惰性占位、1.5s 尾沿节流、首帧 send 后续 edit、单帧上限 `TELEGRAM_PROGRESS_FRAME_MAX_CHARS = 3800`(源 markdown 字符数;官方 presenter 的 `PresenterPolicy.intermediateMaxRenderedChars` 默认值也取它)、NO_REPLY 及其前缀不落地、HTML 被拒(400)回落纯文本、`message is not modified` 视为成功、429 按 `retry_after` 全长退避后重试一次——两侧跑同一份代码。**传输不同**:个人走 Bot API(`index.ts` 的 `callSend` / `sendRenderedChunk` / `editHtml`),官方走 msg.op(`hook-control/telegramTurnCarrier.ts` 只实现 `TelegramStreamingDeps` 的 msg.op 版,并经 `telegramMsgOp.ts` 把 `msg.op.result` 的 `channelErrorCode` / `error` / `retryAfterMs` 映射成同形错误);服务端只执行,不做转换与回落。未协商时官方仍由服务端渲染 `turn.progress`,本行对官方不成立 |+| 成功终稿的**收口**(官方需双方协商 `telegram-final-ops-v1`) | `packages/lizi-im/src/telegram/streamingText.ts` 的 finalize(官方经 `startTelegramTurnCarrier`,与进度消息同一个 handle)+ `chunk.ts` | Rich 新发 → 明确 4xx 回落 HTML → HTML 400 回落纯文本、按 `chunkTelegramSource` 分段、终稿落地后才尽力删过程消息——两侧同一份代码。官方另有两处传输差异:终稿段经 `purpose: 'turn-final'` 登记(服务端据此写 route、在 `turn.end` 确认后提升续跑锚点、做群中继);私聊首段挂完成特效(第三节「终稿特效」)。**只覆盖普通成功、不带附件的轮次**:失败 / 取消 / 续跑轮 / 正文恰为 NO_REPLY(ambient 判定在服务端)/ 带附件 / 私聊草稿模式都仍由服务端按 `turn.end` 发布。带附件不走本端:桌面持久出箱只存终态文本(附件字节不进 JSON 持久化),本端逐段上传附件期间退出或崩溃时,重启重放的兜底帧没有附件、服务端接管后附件会丢,所以整轮随 `turn.end` 交给服务端(与旧路径相同)。终稿必达不降级:发布前 `turn.end` 先进桌面持久出箱,没有完整确认就以 `clientFinal.complete=false` 交回服务端重发(第四节第 3 行) |+| 执行中交互卡的**渲染与按钮排布**(官方需双方协商 `telegram-card-ops-v1`) | `packages/lizi-im/src/telegram/components.ts` 的 `layoutTelegramCard` + `cardLayout.ts` | 粗体标题 + markdown 正文 → HTML、正文上限 3800(`capRenderedText` 安全截断)、label ≤12 字两两并排——两侧同一份。**回调编码不同**:个人编成内存 ref token(`buildCardPayload`),官方由服务端铸 callback_data 并照旧回 `interaction.decision`(`hook-control/telegramCardOps.ts`)。卡片的**语义层**(选项、按钮文案来源、权限入参摘要)仍各自一份,见第三节「交互卡的语义与文案」。群里的卡改投 owner 私聊及其来源说明仍由服务端按现行规则决定。op 被明确拒绝时回落 `interaction.request`(服务端渲染) |+| 官方 bot 的**命令菜单**(需双方协商 `telegram-commands-v1`) | `apps/desktop/src/main/im/shared/botCommands.ts` 的 `buildOfficialBotCommandMenus` | 官方菜单的命令集合、顺序、文案都取注册表(与个人菜单同一份 i18n key),desktop 按 en(默认)/ zh / ja / ko 各渲染一份经 `provider.commands.set` 下发,服务端只执行 `setMyCommands`,且只管理默认菜单与 zh / ja / ko(每次全量重写,缺席的语言写空,其它语言码含显式 `en` 一律忽略);菜单只存服务端内存、不落库:desktop 每次握手都重发,服务端重启后到桌面重连前(以及设备离线期间)用服务端默认菜单。**语言口径沿用两侧既有差异**:官方按用户的 Telegram 语言,个人按桌面端语言。**命令分发不在这一行**:官方命令仍由服务端收入站并分发(1c 的别名差异照旧)。未协商时服务端用自己的 `TELEGRAM_COMMANDS` |+| 渠道 `/stop` 的**明确停止** | `maker-ipc/register.ts` 的 `stopSessionTurnExplicitly` | 个人 IM 的 `/stop` / `!stop`(含微信,`im/shared/turnRunner.ts` 的 `stopActiveTurn`)与官方 hook 的 `task.cancel`(`hook-control/dispatcher.ts`,经 `stopSessionExplicitly` 注入)都走桌面 Stop 同一套清理:撤自动续跑与退避簿记、取消上下文溢出恢复、暂停 Goal、停输入队列并中止当前一轮。2026-10 之前两侧各少几步(个人不暂停 Goal、官方连自动续跑都不撤)。渠道侧只保留各自的排队收口(个人清 `sendQueue`,官方回 `turn.end(cancelled)`)。账号切换时的中止不是用户喊停,仍是普通 abort |+| 新任务的**模型准入** | `im/shared/openChannelSession.ts` → `localDb/sessionOpening.ts` 的 `openSession` | 两侧(及共用 `sessionRepo` 的全部个人 IM 渠道)新建任务时都经桌面新建任务同一套准入:模型 / 来源 / 推理强度 / Fast 不被支持就拒绝建任务,不自动换模型;准入可能规范化来源与推理强度。**默认配置从哪读仍是有意不同**(第三节),这里只统一「读出来之后怎么校验」。复用 / 接管 / 复活既有任务不经过准入 || 群历史**检索实现** | `im/shared/groupHistorySearch.ts` | 真正执行查询的就是这一份:FTS(`hook_group_messages_fts` 的 MATCH)+ 中文 LIKE 兜底,**lane 条件写在 SQL 里**(MATCH 与 LIKE 用完全相同的 lane 条件,调用方没法先全局搜再事后过滤),加上结果映射(snippet / score / source)与上限(默认 8 条、最多 20 条、query 256 字)。两侧共用 || 群历史检索的**逐 turn 授权租约** | `im/shared/groupHistoryAccess.ts` | 租约机制共用:`beginGroupHistoryAccess` 在 provider 真正开始这一轮之前登记作用域,终态 / 重排 / 失败时释放;`sessionInstanceId` 挡住「同一业务 session 重建后,旧 MCP 请求借用新实例权限」。**但产生 scope 的那一步各写各的**——个人是 `im/telegram/adapter.ts` 的 `groupHistoryAccessFor`,官方是 `hook-control/groupHistoryScope.ts` 的 `groupHistoryAccessForExternalKey`;群轮次两侧同为 lane-only,**私聊上给的不一样**,见第四节 2e。完整调用链:MCP 入口 `mcp-integrations/groupHistoryMcpServer.ts` 先 `readGroupHistoryAccess` 拿租约(拿不到直接 `NO_ACTIVE_TELEGRAM_SCOPE` 拒绝),再 `resolveTargetLane(scope, lane)` 定位,最后才调 `searchGroupHistory` || 交互卡的**语义层**(`ask_user_question` / `plan_review` / 权限确认) | `im/shared/interactionCardModel.ts` | 选项集与决策模型两侧真跑同一份:至多 6 个选项(`MAX_OPTIONS`)、multiSelect 降级单选、只渲染第一问、plan 正文截断 1500(`MAX_PLAN_LEN`)、按钮文案的**产品级**上限 30(`BTN_LABEL_MAX`)、无选项降级时唯一按钮「继续」,以及 buttonId → 决策对象的构造与 header/body 拆分。**2026-08-19 起该模块另有一份全量视图**(顶层 `questions` 数组 + `needsAskMultiCard` 判定),只被支持卡片原地更新(`updateInteractiveCard`)的个人 IM 渠道消费——目前**仅飞书个人 bot**(`ui.cards.ask.multi` 打勾卡,多题/真多选,见 `cardBuilders.buildAskMultiCard`);**本表对照的两个 Telegram bot 都不消费它**,上列 v1 规则对两侧与未提供 multi 文案的渠道仍逐字成立,看到飞书行为不同不要当漂移报官方那条链路由 `hook-control/interactions.ts` 直接 import 本模块(对 `@cindy/maker-core` 刻意只做 type-only 依赖,免得 hook 链路在运行期加载整个 barrel)。**渲染不在这里**——按钮文案来源、标题格式、省略号样式、尺寸上限都是各自渲染侧的事,见第三节 |@@ -74,10 +80,10 @@ App 完成未读与提醒统一由 `renderer/hooks/useSessionRunningStatus.ts`|---|---|| `im/shared/channelToolPolicy.ts` 的 `channelForceConfirmToolCall` | 只被个人 Telegram / 微信 / 钉钉的权限策略引用。**官方 bot 不挂**——见第三节的裁决。放在 `shared/` 下是因为个人侧三个渠道共用,不代表两个 bot 共用 || `packages/lizi-im/src/telegram/presentationCapabilities.ts` | 只导出并由**个人 driver** 消费 `TELEGRAM_PERSONAL_CAPABILITIES`,没有官方 bot 共用的契约数据。它的作用是把车道差异写在一处,不是让两侧取同一份值。官方侧同名策略在另一个仓各写一套——具体到链接预览见第四节 2c |-| `packages/lizi-im/src/discord/chunk.ts` 的长消息分段 | 个人 Telegram、Discord、企业微信复用:优先换行、超长单行优先空格,硬切保留 UTF-16 代理对,代码围栏跨段闭合/重开。企业微信长回复用每 UTF-16 单元至多 3 字节的保守预算守住 18 KiB;短回复保留原样。官方 Telegram 在服务端独立实现围栏与 HTML 长度预算,不因个人侧修改而改变。 |-| `PresenterPolicy.intermediateMaxRenderedChars`(长度上限) | **只有官方那条路消费**(`createProgressEmitter`)。个人侧用自己的私有常量 `INTERMEDIATE_EDIT_LIMIT = 3800`(`streamingText.ts`)判断何时停止编辑。**改共享的长度策略只会改到官方 bot**——两处独立维护,改一处必须核对另一处 |+| `packages/lizi-im/src/discord/chunk.ts` 的长消息分段 | 个人 Telegram、Discord、企业微信复用:优先换行、超长单行优先空格,硬切保留 UTF-16 代理对,代码围栏跨段闭合/重开。企业微信长回复用每 UTF-16 单元至多 3 字节的保守预算守住 18 KiB;短回复保留原样。官方 Telegram 协商 `telegram-final-ops-v1` 后由客户端发布的终稿经 `chunkTelegramSource`(内部即本函数)同样复用;未协商或交回服务端发布时,服务端独立实现围栏与 HTML 长度预算,不因个人侧修改而改变。 |+| `PresenterPolicy.intermediateMaxRenderedChars`(长度上限) | **只有官方那条路消费**(`createProgressEmitter`),但默认值与个人 `streamingText` 的停止编辑阈值已是同一个常量 `TELEGRAM_PROGRESS_FRAME_MAX_CHARS`(`@cindy/im` 的 `progressFrame.ts`)。改那个常量两侧一起变;只在调用方传自定义 `policy` 时才会分叉(生产没有这样传) || `PresenterPolicy.intermediateThrottleMs`(节流间隔) | 个人路径是**双层节流**:`turnRunner` 的 `CARD_PATCH_THROTTLE_MS` 确实读共享值,但真正出站的 `streamingText.ts` 还有一份写死的 `TELEGRAM_UPDATE_THROTTLE_MS = 1500`(注释称「双层节流冗余但无害」)。**改共享值只改得动 runner 那层,driver 那层不跟**——所以这个值也不是同源,改它要连 driver 的常量一起核对 |-| `im/shared/botCommands.ts` 的**官方那一半** | 官方 bot 的命令**仍由服务端 `TELEGRAM_COMMANDS` 下发**,本表对官方侧是「声明性镜像、不接线」。测试只用内联清单核对镜像,**服务端改了命令这边完全可能不同步**。个人侧那一半是真的单一真相源(菜单与分发直接读它);官方那一半是跨仓镜像,**改命令要两个仓一起核对** |+| `im/shared/botCommands.ts` 的**官方那一半** | **菜单已接线**:协商 `telegram-commands-v1` 后,官方 bot 的命令菜单(集合、顺序、描述)由这份注册表经 `buildOfficialBotCommandMenus` 下发(第一节「命令菜单」行),未协商时仍是服务端 `TELEGRAM_COMMANDS`。**命令分发没接线**:官方命令仍由服务端收入站并分发,这一半对分发只是跨仓镜像——测试只用内联清单核对,服务端改了分发这边可能不同步。个人侧那一半是真的单一真相源(菜单与分发直接读它);官方改命令要两个仓一起核对 |进度帧去重的三槽基线(`shouldEmitProgressFrame` / `createProgressEmitter`)同理:只在注入`onProgress` 时启用,也就是**只有官方那条路在用**,个人侧不消费。@@ -89,11 +95,11 @@ App 完成未读与提醒统一由 `renderer/hooks/useSessionRunningStatus.ts`| 阶段 | 个人 bot | 官方 bot ||---|---|---|-| 首帧 | 有真实内容(含工具步骤)就建一条**真实消息**;空内容不建(惰性占位) | 快照进 `turn.progress` 帧发给服务端 |-| 过程中 | **第一帧真实内容用 `sendMessage` 建消息(这一条会推送),之后持续 `editMessageText` 覆盖(编辑不推送)**,用户看着它长大:过程区在上、正文在下,正文是整轮累计内容 | **私聊**:默认普通进度消息;服务端开启 `TELEGRAM_DM_DRAFT_ENABLED` 时进 Telegram **草稿**(`sendDraft`),不在消息流里;**群**:一条进度消息,`editMessageText` 覆盖。桌面端对 Telegram 专门用 `progressBodyMode: 'whole'`,在 3800 字单帧上限内同样累计展示整轮正文;超过后退回当前 assistant 消息,避免头部截断把最新答案藏掉。Slack / X 仍只展示当前 assistant 消息 |-| `done` 交接 | 最后一帧由个人 driver 自己定稿 | 桌面端在 `turn.end` 之前先 `flushProgress()`,跳过尚余的 1.5 秒尾沿节流,把最新安全快照放进既有进度载体;这是防止 observer teardown 吞掉最后一帧的客户端兜底,**不等于**服务端终稿已发布成功 |+| 首帧 | 有真实内容(含工具步骤)就建一条**真实消息**;空内容不建(惰性占位) | 快照照旧进 `turn.progress` 帧(服务端靠它续 lease)。**双方协商 `telegram-progress-ops-v1` 后**:同一快照交给与个人 bot 同一个过程载体(`startTelegramProgressCarrier`),由桌面端渲染成 HTML、经 `msg.op`(`purpose: 'turn-progress'`)`send` 建消息,惰性占位同个人;未协商时由服务端按 `turn.progress` 渲染(纯文本) |+| 过程中 | **第一帧真实内容用 `sendMessage` 建消息(这一条会推送),之后持续 `editMessageText` 覆盖(编辑不推送)**,用户看着它长大:过程区在上、正文在下,正文是整轮累计内容 | **私聊**:默认普通进度消息;服务端开启 `TELEGRAM_DM_DRAFT_ENABLED` 时进 Telegram **草稿**(`sendDraft`),不在消息流里——协商后草稿模式仍由服务端按 `turn.progress` 承载(进度 msg.op 回 `PROGRESS_UNAVAILABLE`,桌面端本轮停手);**群 / 私聊非草稿**:一条进度消息,协商后由桌面端经 msg.op 首帧 `send`、后续 `edit`,渲染、节流、回落判据与个人 bot 同源(第一节),服务端只执行:topic、回复引用(含 `first` 档消耗记账)仍由服务端按这一轮的策略决定,首帧带 `silent`(disable_notification,与服务端旧进度消息一致,**与个人首帧推送不同**——沿用既有差异,未统一)。续跑轮协商后同样新建一条进度消息,不改写被续的旧终稿。桌面端对 Telegram 专门用 `progressBodyMode: 'whole'`,在 3800 字单帧上限内同样累计展示整轮正文;超过后退回当前 assistant 消息,避免头部截断把最新答案藏掉。Slack / X 仍只展示当前 assistant 消息 |+| `done` 交接 | 最后一帧由个人 driver 自己定稿 | 桌面端在 `turn.end` 之前先 `flushProgress()`,跳过尚余的 1.5 秒尾沿节流,把最新安全快照放进既有进度载体;协商后终稿栅栏处再同步冲刷一次过程载体(管道空闲时这一帧在 wire 上排在 `turn.end` 之前;有在途 op 时这一帧放弃,不为它推迟 `turn.end`),之后不再发任何进度 op。这是防止 observer teardown 吞掉最后一帧的客户端兜底,**不等于**服务端终稿已发布成功 || 终稿内容(**成功收口**) | **只有正文**(`composeStreamingView` 在 `turn.done` 时直接 `return body`,不再合成过程区) | **只有正文**(`presenter.finalText()` 取 body 引擎的缓冲,不经过 `composeProgressView`) |-| 终稿落在哪 | **永远新发一条独立消息**,落地后才尽力删掉停在过程态的旧载体——**删不掉就两条并存**。优先 `sendRichMessage`(表格/公式原生渲染、32768 上限免分段);**Telegram 完整应答的任一 4xx** 都判为「这条 Rich 没落地」并回落新发 HTML——判据是**有没有拿到应答**而非错误码大小:404(方法缺失,另触发实例级熔断,后续不再试 Rich)、400(本条解析不过)、**429(`callSend` 按 `retry_after` 退避重试后仍限流;不熔断,下一轮照常试 Rich)**。抛错只留给拿不到应答的情况(网络中断、超时、5xx)——那时无法判断 Telegram 是否已接收,补发 HTML 可能造成两份答案。超长时第 2 段起逐段 `send`。**受管图片**让终稿跳过 Rich 直接走 HTML 新发,图片随后由 `uploadImages` 挂到新终稿上。过程载体从不承担答案,因此最后一次编辑撞 flood 不再丢终稿 | **私聊 / 群 / topic**:新发正文,分段与附件发送完成并保存终态 route 后才尽力删除进度消息;删除失败可两条并存。私聊开启草稿时,终稿新发后草稿自然消失 |+| 终稿落在哪 | **永远新发一条独立消息**,落地后才尽力删掉停在过程态的旧载体——**删不掉就两条并存**。优先 `sendRichMessage`(表格/公式原生渲染、32768 上限免分段);**Telegram 完整应答的任一 4xx** 都判为「这条 Rich 没落地」并回落新发 HTML——判据是**有没有拿到应答**而非错误码大小:404(方法缺失,另触发实例级熔断,后续不再试 Rich)、400(本条解析不过)、**429(`callSend` 按 `retry_after` 退避重试后仍限流;不熔断,下一轮照常试 Rich)**。抛错只留给拿不到应答的情况(网络中断、超时、5xx)——那时无法判断 Telegram 是否已接收,补发 HTML 可能造成两份答案。超长时第 2 段起逐段 `send`。**受管图片**让终稿跳过 Rich 直接走 HTML 新发,图片随后由 `uploadImages` 挂到新终稿上。过程载体从不承担答案,因此最后一次编辑撞 flood 不再丢终稿 | **私聊 / 群 / topic**:新发正文,分段与附件发送完成并保存终态 route 后才尽力删除进度消息;删除失败可两条并存。私聊开启草稿时,终稿新发后草稿自然消失。**协商 `telegram-final-ops-v1` 的普通成功、不带附件的轮次**改由桌面端用左栏同一套收口经 msg.op 发布(含 Rich 优先与 4xx 回落;私聊开启草稿时例外:终稿 op 回 `TURN_UNAVAILABLE`,桌面端不重试、交回服务端随草稿通道发布;带附件的轮次整轮交回服务端);`turn.end` 带 `clientFinal.complete=true` 时服务端只做收口副作用(续跑锚点、群中继、清理),否则删掉已落地的客户端终稿段并照旧自己发布 || **失败收口**(普通轮次) | **过程区保留**:错误路径不置 `turn.done`,`composeStreamingView` 仍走运行中合成——卡片定稿成「过程区 + 正文 + ❌ 错误:…」,用户能看到失败前干到了哪一步 | 普通失败终稿正文为**空**,错误信息走独立的 `errorMessage` 字段;**输出上限 `output-limit` 例外**:Desktop 的 `run()` / `watchContinuation()` 在终态 error 拆监听前封存正文,在失败 `turn.end` 的既有 `finalText` 字段中保留正文,错误仍用独立字段,**不带过程区**。不依赖尾随 done;服务端最终发布形态尚未实机验收 || **失败收口**(群开了 `always` 的 **ambient 轮次**) | **和普通轮次一样**照吐 `❌ 错误:…`——`turnRunner` 不认识 ambient。惰性占位这时会被真建出来,群里凭空多一条错误消息,而这一轮本来连话都不打算说。**这是缺口 2f,不是裁决** | **静默**:不发失败通知(`finalFailureNoticeSent !== true && !entry.ambient`),删掉过程消息、记一句「completed silently」。删不掉时标 `retainAmbientCleanup` 留给下一拍重试 |@@ -186,7 +192,7 @@ hook 侧既有的逐轮 `[渠道说明]`,两者措辞不同但都向模型说| lane 模型 | per-principal | per-chat | 已在 `presentationCapabilities.ts` 声明 || `message_thread_id` 的**归属判据在哪一侧** | 在**服务端**:桌面这半拿不到 `is_topic_message`(协议 payload 里没有这个字段),只按服务端下发的 threadId 分桶 | 在**客户端**:入站消息走 `laneThreadIdOf`、卡片回调走 `parseCallbackQuery`,都用 `is_topic_message === true` 门控——不是 forum topic 就记进主群流(threadId 空串) | 这个字段有**两个含义**,混用会出真故障:Telegram 对**普通群的 reply 链**也会给 `message_thread_id`(值 = reply root)。**投递位置**用裸值(带上它消息就投对地方,个人侧的出站与 typing 即如此;服务端 `topicThreadIdOf` 的注释也明写「不要拿归属标识替换投递位置参数」);**归属**必须靠 `is_topic_message` 门控。而这个门控字段**只有持有 Telegram 连接的那一侧拿得到**——个人 bot 直连拿得到,官方 bot 的桌面这半只拿服务端下发的 payload,所以判据只能在服务端。这是架构决定的车道差异,不是谁漏做,已在 `presentationCapabilities.ts` 声明为 `threadIdDualSemantics`。**曾经的实机故障**:服务端早期把普通群 reply 链的 `message_thread_id` 当 topic 下发,那些发言散进一个个 reply-root 桶,agent 在群里答「我看不到群里的历史消息」(2026-08-03 实测:172 条在主群流、另有若干 reply-root 桶)。服务端现已按 `is_topic_message` 门控(`controller.ts` 的 `topicThreadIdOf`;**是否已上生产未核**),客户端保留一层兜底救存量错桶行——`buildGroupContextPrefix` 的 `fallbackThreadFilter` 让**主群流**额外读所有非空 threadId 的行(宁可多读同群发言、不可漏读),**topic lane 不读兜底集**:topic 之间严格隔离的优先级高于补读,代价是存量错桶行在 topic lane 里仍看不到 || 终稿特效 `messageEffectId` | 有 | 无 | 官方装饰位,已声明 |-| 交互卡的**渲染** | 按钮**每行一个**;`plan_review` / 权限卡的按钮文案在服务端硬编码;权限卡的工具入参是**单行 JSON 摘要**、上限 600(`HOOK_PERMISSION_INPUT_SUMMARY_MAX`);截断用单行省略号(`truncateInline`);**卡片正文上限 4000** | label ≤12 字时**两个按钮并排**(`cardLayout.ts` 的 `pairLabelMax`);按钮文案走 ui 文案包;权限卡入参是 **pretty JSON 代码块**、上限 800(`IM_PERMISSION_INPUT_PREVIEW_MAX`);截断用折行「…(已截断)」(`truncateBlock`);**卡片正文上限 3800**(`cardTextMax`,交由 `capRenderedText` 做标签栈安全闭合) | 两处都写着裁决,不是漂移。**正文上限这一条是真差异**,只是触发窗口窄:`plan_review` 的正文有共享的 `MAX_PLAN_LEN = 1500` 挡着、权限入参有 600 / 800 挡着,都撞不到;只有 `ask_user_question` 的问题正文(`headerText` / `questionBody`)不受语义层约束——问题正文长到 3800 以上时,个人侧会先截、官方侧还能再放 200 字,用户能看出来。别把它和下面那段「用户看不见的按钮阈值」混为一谈。`interactionCardModel.ts` 的模块注释:**渠道差异不在语义层统一——统一是产品决策,不归那个模块**;`plan_review` 与权限卡的选项在语义层就是 `label: null`,文案本来就由各自渲染侧给。`cardLayout.ts` 更直接:**刻意不采用官方那套渲染参数**,因为那是「待退役的服务端渲染栈」的值,合同明确不得成为共享参数源。另有一条硬约束让分层无法合并:`@cindy/im` 不得依赖 `apps/desktop`,所以语义层(desktop 包)与渲染层(`@cindy/im`)必然是两个包、各持一份。这一档的寿命跟着第四节第 2 行走:msg.op 接线后官方出站改由桌面驱动,服务端那套渲染参数会一起退役。**两侧的按钮字数上限与按钮数上限不在这一档**——见表下说明 |+| 交互卡的**语义与文案**(协商 `telegram-card-ops-v1` 后渲染与排布已同源,见第一节;本行只剩下语义层差异;未协商时左栏全部仍成立) | 按钮**每行一个**;`plan_review` / 权限卡的按钮文案在服务端硬编码;权限卡的工具入参是**单行 JSON 摘要**、上限 600(`HOOK_PERMISSION_INPUT_SUMMARY_MAX`);截断用单行省略号(`truncateInline`);**卡片正文上限 4000** | label ≤12 字时**两个按钮并排**(`cardLayout.ts` 的 `pairLabelMax`);按钮文案走 ui 文案包;权限卡入参是 **pretty JSON 代码块**、上限 800(`IM_PERMISSION_INPUT_PREVIEW_MAX`);截断用折行「…(已截断)」(`truncateBlock`);**卡片正文上限 3800**(`cardTextMax`,交由 `capRenderedText` 做标签栈安全闭合) | 两处都写着裁决,不是漂移。**正文上限这一条是真差异**,只是触发窗口窄:`plan_review` 的正文有共享的 `MAX_PLAN_LEN = 1500` 挡着、权限入参有 600 / 800 挡着,都撞不到;只有 `ask_user_question` 的问题正文(`headerText` / `questionBody`)不受语义层约束——问题正文长到 3800 以上时,个人侧会先截、官方侧还能再放 200 字,用户能看出来。别把它和下面那段「用户看不见的按钮阈值」混为一谈。`interactionCardModel.ts` 的模块注释:**渠道差异不在语义层统一——统一是产品决策,不归那个模块**;`plan_review` 与权限卡的选项在语义层就是 `label: null`,文案本来就由各自渲染侧给。`cardLayout.ts` 更直接:**刻意不采用官方那套渲染参数**,因为那是「待退役的服务端渲染栈」的值,合同明确不得成为共享参数源。另有一条硬约束让分层无法合并:`@cindy/im` 不得依赖 `apps/desktop`,所以语义层(desktop 包)与渲染层(`@cindy/im`)必然是两个包、各持一份。这一档的寿命跟着第四节第 2 行走:msg.op 接线后官方出站改由桌面驱动,服务端那套渲染参数会一起退役——**2026-10 起协商 `telegram-card-ops-v1` 后官方卡片改用 `layoutTelegramCard`**:「按钮每行一个」「正文上限 4000」这两条在协商连接上不再成立(改为并排规则与 3800),卡片正文 markdown 也按 HTML 渲染(服务端旧路径是纯文本)。按钮文案来源与权限入参摘要(600 单行 / 800 pretty)属语义层,仍各自一份,未统一。**两侧的按钮字数上限与按钮数上限不在这一档**——见表下说明 || **绑定的任务失效后怎么接续** | 丢掉旧绑定、静默新建任务(`hook-control/dispatcher.ts` 的 `resolveTarget`):原任务读不到(归档 / 删除 / 读库失败)或已移出工作目录映射都走这条;读不到时把原任务最近内容交接给新任务。**不在 IM 回复里追加任何换任务说明** | 按固定 id 原地恢复原任务(`im/shared/sessionRepo.ts` 的 `findActiveSession` 把已归档 / 删除的通道行翻回 active),保留上下文与模型、权限等设置;没有工作目录映射这一层。同样**不发说明** | 机制差异来自架构:官方绑定是可丢弃的映射,个人是确定性 id 的唯一通道行。**用户可见层面两侧一致:都不追加说明**——Dash 2026-09-28 裁决,官方原有的「原任务现在读不到…」「原任务已不在可用的工作目录里…」两段提示对 IM 里的人是噪音,已删除(PR #5193)。不要把说明加回来,也不要为「统一」去改任一侧的接续机制 |### 交互卡的**按钮**阈值:看起来不同、但用户看不见@@ -213,9 +219,9 @@ hook 侧既有的逐轮 `[渠道说明]`,两者措辞不同但都向模型说| # | 缺口 | 现状 | 归属 ||---|---|---|---|| 1 | **个人 bot 缺 3 条命令** | `/unbind`(清当前 chat 的项目映射)、`/effort`(思考强度)、`/agent`(切 Agent)官方有、个人无,目前只能在桌面端改。注册表已显式登记并由 CI 拦住 | 每条各自独立 PR |-| 1b | **官方命令镜像没有跨仓校验** | 注册表里官方那一半是手抄的声明性镜像,服务端单方面加减命令这边不会红。**别名维度是同一个洞的另一半,见 1c** | 待判:把 `TELEGRAM_COMMANDS` 分别放进两仓本地协议 package 并用同一 fixture 校验,或在服务端加反向校验。需要跨仓改动与一次协议版本推进 |+| 1b | **官方命令镜像没有跨仓校验** | 协商 `telegram-commands-v1` 后官方**菜单**以注册表为准(第一节),这一半已不需要镜像;但官方**命令分发**仍在服务端,服务端单方面加减分发命令这边仍不会红(注册表里的命令集合与服务端分发靠 `botCommands.test.ts` 的内联清单人工对齐)。**别名维度是同一个洞的另一半,见 1c** | 待判:把 `TELEGRAM_COMMANDS` 分别放进两仓本地协议 package 并用同一 fixture 校验,或在服务端加反向校验。需要跨仓改动与一次协议版本推进 || 1c | **隐藏别名 `/exitctr` 只有个人 bot 认** | 个人:`botCommands.ts` 的 `exctr` 带 `aliases: ['exitctr']`,`tokenizeBotCommand` 归一化后走同一条 `executeDetach`(`botCommands.test.ts` 的归一化用例 + `slashCommands.test.ts` 的「`/exitctr` 与 `/exctr` 同路径」各钉一条)。它是**老拼写的向后兼容**——旧 switch 里的 `case '/exitctr':` 删掉后改用别名接住。官方:服务端 `controller.ts` 的 `handleCommand` 只精确匹配 `exctr`,`/exitctr` 一路落到函数末尾的兜底 `reply(t.help)`——**用户拿到一段帮助文案,而 session 接管并没有解除**。这比回一句「未知命令」更容易误判成已生效。**结构上也拦不住**:注册表的 `aliases` 没有 surface 维度(`surfaces` 只描述命令本身),CI 又只校验规范命令名,所以别名两侧不一致永远不会红 | 待判,**不在本 PR 改代码**。两条路:服务端也认这个拼写(`command === "exctr" \|\| command === "exitctr"`),或给注册表的 alias 加 surface 维度并纳入镜像校验——后者顺带把 1b 一起补上 |-| 2 | **msg.op 动词只接了一个** | 服务端全套动词在 `xindong/cindy-server#349`(未合);桌面侧目前只消费 `react`(ack 表情,见 `hook-control/ackReactions.ts` 的 `HOOK_FEATURE_MESSAGE_OPS` 判据)。`send` / `edit` / `delete` / `typing` / `media` 未接线 | #1855 第三刀。**这是把官方 bot 的出站改由桌面驱动的关键一步**——接完之后两侧的发射与收口才可能走同一份代码,而不是各写一套 |+| 2 | **msg.op 动词只接了一部分** | 桌面侧已消费:`react`(ack 表情)、私聊独立 `send`(Pi 运行时恢复回执);以及按能力分别协商的四段客户端发布——进度消息 `send` / `edit` / `delete`(`telegram-progress-ops-v1`)、普通成功、不带附件轮次的终稿 `send`(`telegram-final-ops-v1`;协议形状里的 `media` 服务端拒收,附件始终由服务端发)、执行中交互卡 `send` / 收口 `edit`(`telegram-card-ops-v1`)、命令菜单 `provider.commands.set`(`telegram-commands-v1`)。渲染与收口已与个人 bot **同源**(第一节),服务端只执行(授权、限速、调 Bot API、登记 route 与清理),不做转换与回落;`turn.progress` 照发只用于续 lease。仍未接线:`typing`;失败 / 取消 / 续跑轮 / 带附件的终稿、私聊草稿、命令分发仍在服务端 | #1855 第三刀。服务端执行器配套在 `xindong/cindy-server`(进行中),**实际效果以服务端部署为准**;任一能力未协商时该段照旧由服务端渲染 || 2b | **NO_REPLY 哨兵官方只在 ambient 轮次生效** | 个人侧**全轮次**生效(`noReplyScope: 'all-turns'`):`streamingText.finalize` 的哨兵判定不带 ambient 门控。但**「零出站」只在惰性占位还没建过消息时成立**——哨兵前已经有正文流出的轮次消息已经发出去了,finalize 走的是**尽力撤回**:`deleteMessage` 失败被 `catch` 吞掉,那条停在过程态的消息就留在聊天里。官方只在 ambient 轮次生效,且删不掉时**不吞**——`discardProgressMessage` 返回 false,标 `retainAmbientCleanup` 并留给下一拍重试。`presentationCapabilities.ts` 把范围差异明写为**跨服务端 TODO**,即「想统一但要动服务端」,**不是**已裁决的产品差异,所以只登记在这里、不进第三节 | 待判:要统一得改服务端的哨兵判定。失败出口的差异(吞 vs 重试)一并判 || 2c | **链接预览关闭两边各写一套,覆盖面还不一样** | 个人侧读契约 `linkPreviewDisabled: true`,driver 在**答案这条路**上全部消费——正文/过程消息的发送、分段发送、编辑,以及 HTML 解析失败后的纯文本回落;**卡片消息、陌生人提示、主人通知不带**。官方侧**不读这个契约**(在服务端仓 `telegram/client.ts` 里写死 `{ is_disabled: true }`),且只写在两处:`sendAdaptiveMessage` / `editAdaptiveMessage` 的 **HTML 回落**分支;纯文本的 `sendMessage` / `editMessageText`(权限卡、通知、附件转发、续跑提示,以及 adaptive 最后一层纯文本回落)都不带,链接预览按 Telegram 默认开着。两侧的 rich 主路径(`rich_message` payload)都不带这个参数,其预览行为**未核**——非公开 API | 待判:要么把参数补进官方的纯文本出站,要么把这条策略分别升进两仓本地协议 package 并用同一 fixture 锁定。跨仓 || 2d | **行为配置(表情、回复引用、群参与模式)两边各写一套** | 档位形状与默认值两侧**逐字相同**:`emojiReactions` off/minimal/expressive 默认 minimal、`replyQuoteGroup` off/first/all 默认 first、`replyQuoteDm` off/first 默认 off、`groupActivation` per-chat mention/always **默认 mention**(个人 `?? 'mention'`;官方的协议注释写「只列偏离默认值的群,缺席 = mention」)。但声明与正本有两份——官方读本仓 `slack-hook-protocol` 的 `DEFAULT_TELEGRAM_BEHAVIOR`,**正本存服务端**,桌面只负责写 override(`hook-control/manager.ts` 把 `mention` 表达成 `null` 清除)与投影设置卡的群清单(`hook-control/groupWindow.ts` 把已知群与 activation 合并),且 hydrate 失败时**故意留「未知」而不套基线**;个人读 `@cindy/im` 的 `TELEGRAM_DEFAULT_BEHAVIOR`,正本是本地 owner-scoped JSON(`im/telegram/behaviorStore.ts`)。**判 ambient 的也是不同一侧**:个人在客户端判(`packages/lizi-im/src/telegram/index.ts` 读 activation 打 ambient 标),官方在服务端判(`controller.ts` 算出 `ambient` 再下发)。值现在一样,但没有任何东西拦着它们分叉。注意:`turnPresenter.ts` / `presentationCapabilities.ts` 里「不含 replyQuote」的裁决说的是**不进共享能力契约**,不是「两个 bot 该长得不一样」——别把它读成有意差异 | 待判:个人侧能否直接改读本仓 `slack-hook-protocol` 的 `DEFAULT_TELEGRAM_BEHAVIOR`(值一样,是最省事的一次真统一),先核 `@cindy/im` 对该 package 的依赖方向允不允许(`docs/dev-rules/architecture-invariants.md`)。**与第 6 行分工**:那行是「何时打表情」的判据,这行是「档位的声明、默认值与正本存哪」 |@@ -224,7 +230,7 @@ hook 侧既有的逐轮 `[渠道说明]`,两者措辞不同但都向模型说| 2g | **交互卡挂太久:官方 30 分钟自动收口,个人一直等** | 三类卡(`ask_user_question` / `plan_review` / 权限)在两侧走的是同一个注册入口,差别只在**有没有定时器**。官方:`hook-control/interactions.ts` 的 `registerHookInteraction` 给每张卡挂一个 `HOOK_INTERACTION_TIMEOUT_MS = 30min`,到点取共享模型的安全默认(ask 空答 / plan deny + dismissed / permission deny)resolve,并回调 `onFallback` → `session-runner.ts` 的 `sendCancel(requestId, reason)` 把卡片收掉。个人:`im/shared/pendingInteractions.ts` **没有任何定时器**,只能靠按钮决策(`resolvePending`),或 turn 收口 / session 清理 / 抢跑时的 `dropInteractionCard` → `cancelPending`(安全默认与官方同源,并把卡片改成「卡片已过期」)。**而这一轮正卡在 `await` 这张卡上,它不会自己结束**;maker-core 的 turn stall 看门狗又明确把「等用户回应交互」排除在静默之外,也不会来救。结果:**个人 bot 的卡片会一直挂着,第二天点还能点,agent 也还在等** | 待判,**不在本 PR 改代码**。先答一个产品问题:个人 bot 的卡片挂着不动算不算问题——它是用户自己的 bot,晚点回来再点也说得通;官方 bot 经服务端中继,挂着的交互会长期占住 lane,动机不一样。补的话要连「超时后卡片显示什么」一起定。**顺带**:官方那个 30 分钟的注释理由(「必须短于整 turn 硬超时 60min」)已过期——那条硬超时 2026-08-01 撤了,定时器本身仍在生效,注释已随本 PR 改正 || 2h | **自动审批故障降级后,个人 bot 有确认入口、官方待核** | 审阅器故障(网络/服务波动,**不是**模型判定该问)时,Cindy 兜底裁决从静默 `block` 改为 `ask` 交回用户决定。个人 bot 的 Telegram / 微信 / 钉钉群轮次即使带 `turnPermissionPolicy` 也会**真正弹确认卡**(`agents/pi/index.ts` 的 Auto 审阅分支),并附一条会话级提示(`im/shared/turnRetryNotice.ts`)。桌面、手机和多数渠道建议切到「完全访问」并写明风险更高;个人微信不能使用该档。出站提示和查看微信任务时的桌面横幅、历史错误卡、手机实时/尾部/历史提示都改为直接确认,不建议切档。**Auto 三态统一**:渠道策略命中也先交 AI;allow/block 静默执行/拒绝,模型 ask 与 unavailable 都交现有渠道确认入口,不能再由静态策略把动作直接转人工或把模型 ask 改成静默拒绝。官方 bot 侧的等价路径(服务端 `session-runner` 是否把 unavailable 降级的 `ask` 送到用户面前、提示文案由谁渲染)**待核** | 待核。个人侧收口于 PR #2474;官方侧若仍静默拒绝,用户会看到「已转由你确认」却没有确认入口——与个人侧修复前是同一个矛盾 || 2i | **群内回复触发与任务归属两边各写一套** | 官方 bot 的服务端正本用 `TelegramMessageRoute.botAuthored === true` 区分“消息与任务有关”和“消息由 Cindy 发出、可通过回复召唤”:回复曾触发任务的普通用户消息不会误触发,明确 `@cindyapp_bot` 仍召唤当前发言者自己的 Cindy;回复同一 principal 的 Cindy 输出可续用其历史群 lane,回复其他 principal 的 Cindy 输出只带引用上下文,任务归当前发言者,不继承原任务的 principal、设备、会话或权限。普通群与 forum topic 都适用;`/session`、interaction、取消和 reaction 继续严格校验 owner。个人 bot 则在 `packages/lizi-im/src/telegram/inbound.ts` 的 `detectGroupTrigger` 独立用 `reply_to_message.from.id === botId` 判定回复触发,且采用本地单 owner 模型;两侧没有共享代码或数据,不能因为当前触发语义相近就跳过双路核对。**纯 @(只发一句 `@bot`、没有正文)两侧同口径都算召唤**:官方服务端 `userText` 为空时 prompt 仍是原文(桌面 `hook-control/dispatcher.ts` 标题回退同理);个人 `detectGroupTrigger` 剥掉提及后为空时保留原文交给 agent(2026-10-03 修复:此前返回空串,被 `im/shared/messageHandler.ts` 当空消息静默丢弃,群里表现为「@ 了没反应」)。个人侧提及判据只认平台实体——`mention` 按 username、`text_mention` 按 user id,@ 在句中、句尾都触发;显示名召唤是唯一的字面匹配兜底 | 服务端实现见 `xindong/cindy-server#393`。本 PR 只登记正本与漂移风险,不改任一侧代码;以后修改群回复行为必须同时核对两条路径。是否把共同判据升为跨仓协议数据待判。纯 @ 的个人侧对齐只改了客户端,未动服务端 |-| 3 | **终稿必达只有官方有** | 官方侧终稿先落盘、失败重试到送达或有界放弃(`xindong/cindy-server#348`)。个人 bot 的 `streamingText.finalize` 是进程内尽力而为,桌面进程挂掉那条终稿就没了。**两侧的「有界」各有一条明确边界、且不在同一层**:官方路径经桌面账本 `hook-control/requestLedger.ts`,客户端侧的投递时效是 `HOOK_TERMINAL_DELIVERY_TTL_MS ≈ 24h`,**规则无条件**——过线的终稿一律不再发出,不论是谁在要。覆盖的出口:持久出箱 `listPending`、ACK 退避重发、离线内存缓冲、ACK 缓冲的两个消费分支(`onConnected` 入口一次性清扫,含能力降级回落),以及 **server 显式重投**——那一支只回放 `task.ack` 后返回,不发终稿、也不把记录改回 `pending`。(重投一度有过 `origin='server-request'` 豁免,后被删除:它在持久记录里没有位置,每条路径都要手工传播,连续三轮 review 各找出一条漏掉的。)server 侧只丢掉一份它自己也已放弃发布的终稿——服务端 `OUTBOX_MAX_ATTEMPTS × OUTBOX_MAX_DELAY_MS ≈ 24h` 的发布放弃线与客户端刻意取同一个数,而结果总比请求更晚,所以它索取一份过线结果时自身 outbox 早已过放弃点;X 侧入口还另有 `x-hook-server` 的 `onMention` 陈旧守卫。**个人 bot 不经过这个账本**,既没有落盘也没有这条时效,它的边界就是「进程活着就尽力,挂了就没了」 | 待判:个人侧是否需要等价保障,还是接受「桌面挂了本来就没人在跑」。**注意两侧要判的不是同一件事**:官方已定「超过 24h 的终稿不再主动补发」,个人待定的是「要不要先落盘」 |+| 3 | **终稿必达只有官方有** | 官方侧终稿先落盘、失败重试到送达或有界放弃(`xindong/cindy-server#348`)。个人 bot 的 `streamingText.finalize` 是进程内尽力而为,桌面进程挂掉那条终稿就没了。**两侧的「有界」各有一条明确边界、且不在同一层**:官方路径经桌面账本 `hook-control/requestLedger.ts`,客户端侧的投递时效是 `HOOK_TERMINAL_DELIVERY_TTL_MS ≈ 24h`,**规则无条件**——过线的终稿一律不再发出,不论是谁在要。覆盖的出口:持久出箱 `listPending`、ACK 退避重发、离线内存缓冲、ACK 缓冲的两个消费分支(`onConnected` 入口一次性清扫,含能力降级回落),以及 **server 显式重投**——那一支只回放 `task.ack` 后返回,不发终稿、也不把记录改回 `pending`。(重投一度有过 `origin='server-request'` 豁免,后被删除:它在持久记录里没有位置,每条路径都要手工传播,连续三轮 review 各找出一条漏掉的。)server 侧只丢掉一份它自己也已放弃发布的终稿——服务端 `OUTBOX_MAX_ATTEMPTS × OUTBOX_MAX_DELAY_MS ≈ 24h` 的发布放弃线与客户端刻意取同一个数,而结果总比请求更晚,所以它索取一份过线结果时自身 outbox 早已过放弃点;X 侧入口还另有 `x-hook-server` 的 `onMention` 陈旧守卫。**个人 bot 不经过这个账本**,既没有落盘也没有这条时效,它的边界就是「进程活着就尽力,挂了就没了」。官方协商 `telegram-final-ops-v1` 由桌面端发布终稿后**仍走这本账**:发布前先把不带 `clientFinal` 的 `turn.end` 写进出箱,崩溃重放时服务端删掉已落地的客户端终稿段并自己重发,所以官方这条保障不降级 | 待判:个人侧是否需要等价保障,还是接受「桌面挂了本来就没人在跑」。**注意两侧要判的不是同一件事**:官方已定「超过 24h 的终稿不再主动补发」,个人待定的是「要不要先落盘」 || 4 | 受保护群内容的隐私边界 | 个人侧已做(出站回流 fail-closed,任一分片带保护标即整条不回流)。官方侧是否等价**待核** | 待核 || 5 | 相册失败逐张回落 | 两侧都有实现,判据是否等价**待核** | 待核 || 6 | ack / 排队 / 结果表情 | 个人与官方 bot 都用 👀 表示排队;开始处理时从 👨💻 / 🤔 / 🤓 / ✍ 中随机选一个,两种开启档位均生效,不随进度轮换。正常完成和取消清除状态、不另加 👍;失败保留 👎(生动档沿用失败变体)。个人侧复用 `im/shared/turnRunner.ts` 的 ack 句柄,迟到回应由终态接管;官方新版 server 统一管理状态,鉴权后确认但不执行 Desktop 的自动 `:ack` / `:final` / `:final-fallback` 表情,`:processing` 只触发一次处理中状态,避免旧客户端重新加上 👍。表情关闭、ambient 或群不允许时静默;两种传输均为尽力反馈。 | 两仓配套实现。新版 server 可先发,旧 Desktop 的 accepted/首帧 progress 触发处理中;新版 Desktop 连旧 server 仍兼容 msg.op,但旧 server 的独立成功表情须升级 server 才能彻底消除。无协议字段、数据库或平台配置变更。 |@@ -277,6 +283,8 @@ hook 侧既有的逐轮 `[渠道说明]`,两者措辞不同但都向模型说## 相关+- 两侧「一轮任务」的入口账本、状态清单与合并批次:`docs/dev-rules/im-turn-flow.md`+- 命令注册表:`apps/desktop/src/main/im/shared/botCommands.ts`- 呈现大脑:`apps/desktop/src/main/im/shared/turnPresenter.ts`- 呈现能力契约:`packages/lizi-im/src/telegram/presentationCapabilities.ts`diff --git a/packages/lizi-im/src/index.ts b/packages/lizi-im/src/index.tsindex 9508adfc55..280c4c8755 100644--- a/packages/lizi-im/src/index.ts+++ b/packages/lizi-im/src/index.ts@@ -66,6 +66,30 @@ export { TELEGRAM_DEFAULT_BEHAVIOR } from './telegram/index.js';export type { TelegramBehaviorConfig } from './telegram/index.js';export { TELEGRAM_PERSONAL_CAPABILITIES } from './telegram/presentationCapabilities.js';export type { TelegramDriverCapabilities } from './telegram/presentationCapabilities.js';+// 运行中过程消息: 生命周期、单帧上限、渲染与失败判据 —— 官方 bot 的 msg.op 进度+// 消息与个人 driver 同源(官方只实现 TelegramProgressDeps 的 msg.op 版)。+export { TELEGRAM_PROGRESS_FRAME_MAX_CHARS } from './telegram/progressFrame.js';+export {+ startTelegramProgressCarrier,+ startTelegramTurnCarrier,+} from './telegram/streamingText.js';+export type {+ TelegramProgressCarrier,+ TelegramProgressDeps,+ TelegramStreamingDeps,+ TelegramTurnCarrier,+} from './telegram/streamingText.js';+export { markdownToTelegramHtml, stripTelegramHtmlTags } from './telegram/markdown.js';+export { chunkTelegramSource } from './telegram/chunk.js';+export { layoutTelegramCard } from './telegram/components.js';+export type { TelegramCardLayoutInput } from './telegram/components.js';+export {+ callWithTelegramRateLimitRetry,+ isTelegramBadRequest,+ editTelegramHtmlWithFallback,+ sendTelegramHtmlWithFallback,+} from './telegram/outboundPolicy.js';+export type { TelegramErrorShape } from './telegram/outboundPolicy.js';export { createTelegramMessageLifecycle } from './telegram/messageLifecycle.js';export { TelegramFinalUnconfirmedError } from './telegram/streamingText.js';export type {diff --git a/packages/lizi-im/src/telegram/__tests__/outboundPolicy.test.ts b/packages/lizi-im/src/telegram/__tests__/outboundPolicy.test.tsnew file mode 100644index 0000000000..352b46724b--- /dev/null+++ b/packages/lizi-im/src/telegram/__tests__/outboundPolicy.test.ts@@ -0,0 +1,100 @@+/**+ * outboundPolicy: 两个 bot 共用的 Telegram 失败判据。只认结构(errorCode + 渠道原文),+ * 不认具体错误类 —— 个人侧的 TelegramApiError 与官方 msg.op 映射出的错误走同一条。+ */++import { describe, expect, it, vi } from 'vitest';++import { TelegramApiError } from '../api.js';+import {+ callWithTelegramRateLimitRetry,+ editTelegramHtmlWithFallback,+ isTelegramMessageNotModified,+ sendTelegramHtmlWithFallback,+ TELEGRAM_RETRY_AFTER_FALLBACK_MS,+ telegramRetryAfterWaitMs,+} from '../outboundPolicy.js';++const badRequest = (description: string) => new TelegramApiError('sendMessage', 400, description);++describe('outboundPolicy', () => {+ it('retry_after 合法值全长采用, 缺失或非法走兜底', () => {+ expect(telegramRetryAfterWaitMs(26)).toBe(26_000);+ for (const v of [undefined, 0, -1, Number.NaN, Number.POSITIVE_INFINITY]) {+ expect(telegramRetryAfterWaitMs(v)).toBe(TELEGRAM_RETRY_AFTER_FALLBACK_MS);+ }+ });++ it('not modified 只认 Telegram 应答(带 errorCode), 不认本地错误文案', () => {+ expect(isTelegramMessageNotModified(badRequest('Bad Request: message is not modified'))).toBe(+ true,+ );+ expect(+ isTelegramMessageNotModified({+ errorCode: 400,+ message: 'message is not modified',+ }),+ ).toBe(true);+ expect(isTelegramMessageNotModified(new Error('message is not modified'))).toBe(false);+ });++ it('send: 400 回落 plain 原文, 其它错误原样抛出', async () => {+ const post = vi.fn(async (text: string, parseHtml: boolean) => {+ if (parseHtml) throw badRequest("can't parse entities");+ return text;+ });+ await expect(sendTelegramHtmlWithFallback('<b>x', '**x', post)).resolves.toBe('**x');+ expect(post.mock.calls).toEqual([+ ['<b>x', true],+ ['**x', false],+ ]);++ const network = new Error('socket hang up');+ await expect(+ sendTelegramHtmlWithFallback('h', 'p', async () => {+ throw network;+ }),+ ).rejects.toBe(network);+ });++ it('edit: not modified 视为成功; 400 剥标签回落, 回落的 not modified 也算成功', async () => {+ const put = vi.fn(async () => {+ throw badRequest('Bad Request: message is not modified');+ });+ await expect(editTelegramHtmlWithFallback('<b>x</b>', put)).resolves.toBeUndefined();+ expect(put).toHaveBeenCalledTimes(1);++ const calls: Array<[string, boolean]> = [];+ await editTelegramHtmlWithFallback('<b>粗</b> & 细', async (text, parseHtml) => {+ calls.push([text, parseHtml]);+ if (parseHtml) throw badRequest("can't parse entities");+ throw badRequest('message is not modified');+ });+ expect(calls).toEqual([+ ['<b>粗</b> & 细', true],+ ['粗 & 细', false],+ ]);+ });++ it('429: 退避后重试一次; 醒来已停止则抛回原始 429、不再请求', async () => {+ const limited = new TelegramApiError('editMessageText', 429, 'Too Many Requests', 7);+ const sleep = vi.fn(async () => undefined);+ let attempt = 0;+ const call = vi.fn(async () => {+ attempt += 1;+ if (attempt === 1) throw limited;+ return 'ok';+ });+ await expect(callWithTelegramRateLimitRetry(call, { sleep, isLive: () => true })).resolves.toBe(+ 'ok',+ );+ expect(sleep).toHaveBeenCalledWith(7_000);++ attempt = 0;+ call.mockClear();+ await expect(callWithTelegramRateLimitRetry(call, { sleep, isLive: () => false })).rejects.toBe(+ limited,+ );+ expect(call).toHaveBeenCalledTimes(1);+ });+});diff --git a/packages/lizi-im/src/telegram/__tests__/streamingText.test.ts b/packages/lizi-im/src/telegram/__tests__/streamingText.test.tsindex 013f46cc82..e981c34e9a 100644--- a/packages/lizi-im/src/telegram/__tests__/streamingText.test.ts+++ b/packages/lizi-im/src/telegram/__tests__/streamingText.test.ts@@ -1,7 +1,10 @@import { describe, expect, it, vi } from 'vitest';+import { TELEGRAM_PROGRESS_FRAME_MAX_CHARS } from '../progressFrame.js';import {+ startTelegramProgressCarrier,startTelegramStreaming,+ TELEGRAM_UPDATE_THROTTLE_MS,TelegramFinalUnconfirmedError,type TelegramStreamingDeps,} from '../streamingText.js';@@ -580,3 +583,62 @@ describe('telegram streaming finalize — 新鲜终稿与 Rich 降级', () => {expect(handle.messageId).toBe('');});});++describe('startTelegramProgressCarrier(官方 bot 只驱动过程载体)', () => {+ it('与个人 handle 同一生命周期: 惰性首帧 send、尾沿节流后 edit, flush 跳过节流, close 后静默', async () => {+ vi.useFakeTimers();+ try {+ const calls: string[] = [];+ const carrier = startTelegramProgressCarrier({+ send: async (markdown) => {+ calls.push(`send:${markdown}`);+ return 'p-1';+ },+ edit: async (messageId, markdown) => {+ calls.push(`edit:${messageId}:${markdown}`);+ },+ });+ carrier.replace(' ');+ carrier.replace('NO_');+ await vi.advanceTimersByTimeAsync(TELEGRAM_UPDATE_THROTTLE_MS);+ expect(calls).toEqual([]);++ carrier.replace('第一帧');+ await vi.advanceTimersByTimeAsync(TELEGRAM_UPDATE_THROTTLE_MS);+ expect(calls).toEqual(['send:第一帧']);+ expect(carrier.messageId).toBe('p-1');++ carrier.replace('第二帧');+ await carrier.flush();+ expect(calls).toEqual(['send:第一帧', 'edit:p-1:第二帧']);++ carrier.close();+ carrier.replace('迟到');+ await carrier.flush();+ await vi.advanceTimersByTimeAsync(TELEGRAM_UPDATE_THROTTLE_MS * 2);+ expect(calls).toHaveLength(2);+ } finally {+ vi.useRealTimers();+ }+ });++ it('超过单帧上限后停止编辑(与个人 driver 同一常量)', async () => {+ vi.useFakeTimers();+ try {+ const edits: string[] = [];+ const carrier = startTelegramProgressCarrier({+ send: async () => 'p-1',+ edit: async (_id, markdown) => {+ edits.push(markdown);+ },+ });+ carrier.replace('a');+ await carrier.flush();+ carrier.replace('x'.repeat(TELEGRAM_PROGRESS_FRAME_MAX_CHARS + 1));+ await carrier.flush();+ expect(edits).toEqual([]);+ } finally {+ vi.useRealTimers();+ }+ });+});diff --git a/packages/lizi-im/src/telegram/components.ts b/packages/lizi-im/src/telegram/components.tsindex 8b25a1ff41..2362a829e6 100644--- a/packages/lizi-im/src/telegram/components.ts+++ b/packages/lizi-im/src/telegram/components.ts@@ -21,25 +21,33 @@ export interface TelegramInlineKeyboardButton {callback_data: string;}-export function buildCardPayload(spec: InteractiveCardSpec): {- html: string;- replyMarkup: { inline_keyboard: TelegramInlineKeyboardButton[][] } | undefined;-} {+/** 交互卡的渲染输入: 标题 + markdown 正文 + 有序按钮(两个 bot 同一形状)。 */+export interface TelegramCardLayoutInput<B extends { label: string }> {+ title?: string;+ body: string;+ buttons: readonly B[];+}++/**+ * 交互卡的渲染与按钮排布(两个 bot 同源)。正文: 粗体标题 + markdown → HTML, 再按+ * `cardTextMax` 做标签栈安全截断; 按钮: label 截到 `buttonLabelMax`, 短 label+ * (≤ `pairLabelMax`)两两并排, 长 label 独占一行。+ *+ * 只排布、不编码回调 —— 回调怎么落地是传输层的事: 个人 bot 编成内存 ref token+ * (`buildCardPayload`), 官方 bot 交给服务端铸 callback_data(desktop+ * `hook-control/telegramCardOps.ts`)。+ */+export function layoutTelegramCard<B extends { label: string }>(+ spec: TelegramCardLayoutInput<B>,+): { html: string; rows: Array<Array<{ button: B; text: string }>> } {const title = spec.title ? `<b>${escapeTitle(spec.title)}</b>\n\n` : '';const { html: body } = markdownToTelegramHtml(spec.body);const html = capRenderedText(`${title}${body}`, TELEGRAM_CARD_LAYOUT.cardTextMax);- // 无按钮时必须显式下发空键盘: 省略 reply_markup 只会改文本, Telegram 保留旧键盘,- // 于是已收口的卡片(过期/已解决)仍带着可点的按钮。- if (spec.buttons.length === 0) return { html, replyMarkup: { inline_keyboard: [] } };-- const rows: TelegramInlineKeyboardButton[][] = [];- let pendingPair: TelegramInlineKeyboardButton | null = null;+ const rows: Array<Array<{ button: B; text: string }>> = [];+ let pendingPair: { button: B; text: string } | null = null;for (const button of spec.buttons) {- const rendered: TelegramInlineKeyboardButton = {- text: button.label.slice(0, TELEGRAM_CARD_LAYOUT.buttonLabelMax),- callback_data: encodeCallbackData(button.id, button.payload ?? {}),- };+ const rendered = { button, text: button.label.slice(0, TELEGRAM_CARD_LAYOUT.buttonLabelMax) };if (button.label.length <= TELEGRAM_CARD_LAYOUT.pairLabelMax) {if (pendingPair) {rows.push([pendingPair, rendered]);@@ -56,7 +64,27 @@ export function buildCardPayload(spec: InteractiveCardSpec): {rows.push([rendered]);}if (pendingPair) rows.push([pendingPair]);- return { html, replyMarkup: { inline_keyboard: rows } };+ return { html, rows };+}++export function buildCardPayload(spec: InteractiveCardSpec): {+ html: string;+ replyMarkup: { inline_keyboard: TelegramInlineKeyboardButton[][] } | undefined;+} {+ const { html, rows } = layoutTelegramCard(spec);+ // 无按钮时必须显式下发空键盘: 省略 reply_markup 只会改文本, Telegram 保留旧键盘,+ // 于是已收口的卡片(过期/已解决)仍带着可点的按钮。+ return {+ html,+ replyMarkup: {+ inline_keyboard: rows.map((row) =>+ row.map(({ button, text }) => ({+ text,+ callback_data: encodeCallbackData(button.id, button.payload ?? {}),+ })),+ ),+ },+ };}/**diff --git a/packages/lizi-im/src/telegram/index.ts b/packages/lizi-im/src/telegram/index.tsindex 517b587fc8..eb171d0729 100644--- a/packages/lizi-im/src/telegram/index.ts+++ b/packages/lizi-im/src/telegram/index.ts@@ -52,8 +52,13 @@ import {normalizeMessage,type TelegramGroupWindowEntry,} from './inbound.js';-import { markdownToTelegramHtml, stripTelegramHtmlTags } from './markdown.js';+import { markdownToTelegramHtml } from './markdown.js';import { TELEGRAM_PERSONAL_CAPABILITIES } from './presentationCapabilities.js';+import {+ callWithTelegramRateLimitRetry,+ editTelegramHtmlWithFallback,+ sendTelegramHtmlWithFallback,+} from './outboundPolicy.js';import {EXPRESSIVE_DONE_POOL,EXPRESSIVE_ERROR_POOL,@@ -103,21 +108,6 @@ const POLL_RETRY_BASE_MS = 1_000;const POLL_RETRY_MAX_MS = 30_000;/** 409 = 另一个进程在对同一 token 轮询 — 低频探测等它退出。 */const POLL_CONFLICT_RETRY_MS = 30_000;-/**- * 429 没给 `retry_after`(或给了非法值)时的兜底退避。**只用于兜底** —— 合法值- * 一律按服务端给的全长等, 不设上限: 任何上限都等于在 flood 窗口结束前提前重试,- * 那次重试必然再 429, 终稿于是又丢一次(bot-wide flood 的 retry_after 可以远超- * 一分钟)。不设上限是安全的, 因为这个等待绑定了连接生命周期取消源(见- * outboundAbortSignal), dispose / 下线 / 重连会立刻把它收口。- */-const RETRY_AFTER_FALLBACK_MS = 3_000;--/** 429 退避时长: 合法 `retry_after` 原样采用, 缺失或非法(NaN / ≤0 / 非有限)走兜底。 */-function retryAfterWaitMs(retryAfterSec: number | undefined): number {- if (typeof retryAfterSec !== 'number') return RETRY_AFTER_FALLBACK_MS;- if (!Number.isFinite(retryAfterSec) || retryAfterSec <= 0) return RETRY_AFTER_FALLBACK_MS;- return retryAfterSec * 1000;-}const MAX_OUTBOUND_FILE_BYTES = 50 * 1024 * 1024;const OWNER_NOTICE_TIMEOUT_MS = 4_500;/**@@ -1710,7 +1700,7 @@ export class TelegramIM extends BaseIM implements ChannelIM {* 2026-08-04: 一个 11 分钟群轮次的终稿撞上 `retry after 26`, 只等 10s 就重试,* 再次 429 后整条答案丢失)。任何固定上限都只是把同一个 bug 往后挪: bot-wide* flood 的 retry_after 可以是几分钟, 60s 上限照样会提前重试。只有缺失/非法值- * 才走 RETRY_AFTER_FALLBACK_MS。+ * 才走 TELEGRAM_RETRY_AFTER_FALLBACK_MS(outboundPolicy.ts)。** 退避必须绑定连接生命周期: 等待期可能长达一分钟, 期间实例完全可能被* dispose / 下线 / 换配置重连。等待本身用当前世代的 AbortSignal 取消(否则@@ -1726,18 +1716,13 @@ export class TelegramIM extends BaseIM implements ChannelIM {if (typeof params.chat_id === 'string' || typeof params.chat_id === 'number') {this.stopTypingLoopsForChat(String(params.chat_id));}- try {- return await api.call<T>(method, params);- } catch (err) {- if (err instanceof TelegramApiError && err.errorCode === 429) {- // sleep 在 abort 时提前 resolve(不 reject), 所以醒来后必须显式核验。- await sleep(retryAfterWaitMs(err.retryAfterSec), abortSignal);- // 已停止 → 放弃重试并抛回原始 429, 不再发出任何请求。- if (!this.isLiveConnection(api, generation, abortSignal)) throw err;- return api.call<T>(method, params);- }- throw err;- }+ // 退避判据与官方 bot 的 msg.op 进度出站同源(outboundPolicy.ts)。sleep 在 abort+ // 时提前 resolve(不 reject), 所以醒来后由 isLive 显式核验; 已停止就抛回原始+ // 429, 不再发出任何请求。+ return callWithTelegramRateLimitRetry(() => api.call<T>(method, params), {+ sleep: (ms) => sleep(ms, abortSignal),+ isLive: () => this.isLiveConnection(api, generation, abortSignal),+ });}/**@@ -1866,27 +1851,16 @@ export class TelegramIM extends BaseIM implements ChannelIM {? { params: replyParamsFor(reuseReplyTargetId), lease: null }: this.leaseReplyTarget(userId);const { html, imageUrls } = markdownToTelegramHtml(markdownChunk);- let sent: TgMessage;- try {- sent = await this.callSend<TgMessage>('sendMessage', {+ // HTML 被拒(400)回落原 markdown 纯文本 —— 判据与官方 msg.op 出站同源。+ const sent = await sendTelegramHtmlWithFallback(html, markdownChunk, (text, parseHtml) =>+ this.callSend<TgMessage>('sendMessage', {...target,...replyParams,- text: html || '…',- parse_mode: 'HTML',+ text,+ ...(parseHtml ? { parse_mode: 'HTML' } : {}),link_preview_options: LINK_PREVIEW_OPTIONS,- });- } catch (err) {- if (err instanceof TelegramApiError && err.errorCode === 400) {- sent = await this.callSend<TgMessage>('sendMessage', {- ...target,- ...replyParams,- text: markdownChunk || '…',- link_preview_options: LINK_PREVIEW_OPTIONS,- });- } else {- throw err;- }- }+ }),+ );this.commitReplyTarget(lease);this.recordOwnEcho(userId, markdownChunk, sent);return {@@ -1923,36 +1897,19 @@ export class TelegramIM extends BaseIM implements ChannelIM {html: string,replyMarkup: unknown,): Promise<void> {- try {+ // not modified 视为成功; HTML parse 失败(400)剥标签退回纯文本编辑(宁可丢格式+ // 不丢内容)。判据与官方 msg.op 出站同源(outboundPolicy.ts)。回落那次同样要带上+ // reply_markup: 省略的话清空键盘的意图会被丢掉。+ await editTelegramHtmlWithFallback(html, async (text, parseHtml) => {await this.callSend('editMessageText', {chat_id: chatId,message_id: Number(nativeMessageId),- text: html || '…',- parse_mode: 'HTML',+ text,+ ...(parseHtml ? { parse_mode: 'HTML' } : {}),link_preview_options: LINK_PREVIEW_OPTIONS,...(replyMarkup !== undefined ? { reply_markup: replyMarkup } : {}),});- } catch (err) {- if (err instanceof TelegramApiError && /not modified/i.test(err.message)) return;- if (err instanceof TelegramApiError && err.errorCode === 400) {- // HTML parse 失败: 剥标签退回纯文本编辑(宁可丢格式不丢内容)。- await this.callSend('editMessageText', {- chat_id: chatId,- message_id: Number(nativeMessageId),- text: stripTelegramHtmlTags(html) || '…',- link_preview_options: LINK_PREVIEW_OPTIONS,- // 同样要带上 reply_markup: 走到这条 fallback 时若省略, 清空键盘的意图会被丢掉。- ...(replyMarkup !== undefined ? { reply_markup: replyMarkup } : {}),- }).catch((fallbackErr) => {- if (fallbackErr instanceof TelegramApiError && /not modified/i.test(fallbackErr.message)) {- return;- }- throw fallbackErr;- });- return;- }- throw err;- }+ });}/**diff --git a/packages/lizi-im/src/telegram/outboundPolicy.ts b/packages/lizi-im/src/telegram/outboundPolicy.tsnew file mode 100644index 0000000000..a4eb2c44c5--- /dev/null+++ b/packages/lizi-im/src/telegram/outboundPolicy.ts@@ -0,0 +1,135 @@+/**+ * telegram/outboundPolicy.ts — Telegram 出站的失败处理判据(两个 bot 同源)。+ * ---------------------------------------------------------------------------+ * 个人 bot 直连 Bot API(`index.ts` 的 callSend / sendRenderedChunk / editHtml),+ * 官方 bot 经 msg.op 由服务端执行(desktop `hook-control/telegramProgressCarrier.ts`)。+ * 两条传输不同, 但"拿到 Telegram 的拒绝之后怎么办"是同一套产品判据, 收在这里:+ * - HTML 被拒(400) → 同一条退回纯文本, 宁可丢格式不丢内容;+ * - `message is not modified` → 内容没变的重复编辑, 视为成功;+ * - 429 → 按 `retry_after` 全长退避后重试一次, 不设上限(见 telegramRetryAfterWaitMs)。+ *+ * 判据只看**结构**(`errorCode` 数字 + 渠道原文), 不认具体错误类: 个人侧抛+ * `TelegramApiError`, 官方侧把 `msg.op.result` 的 `channelErrorCode` / `error` /+ * `retryAfterMs` 映射成同一形状。没有 `errorCode` 的错误(网络中断、超时、回执未知)+ * 一律不命中任何回落 —— 那时无法判断 Telegram 是否已接收。+ */++import { stripTelegramHtmlTags } from './markdown.js';++/** 个人 `TelegramApiError` 与官方 msg.op 失败都满足的错误形状。 */+export interface TelegramErrorShape {+ /** Telegram `error_code`(400 / 429 …)。缺席 = 不是 Telegram 的明确应答。 */+ errorCode?: number;+ /** 含 Telegram 原文 description。 */+ message: string;+ /** 429 时 Telegram 建议的等待秒数。 */+ retryAfterSec?: number;+}++function errorCodeOf(err: unknown): number | undefined {+ if (typeof err !== 'object' || err === null) return undefined;+ const code = (err as { errorCode?: unknown }).errorCode;+ return typeof code === 'number' ? code : undefined;+}++function messageOf(err: unknown): string {+ if (typeof err !== 'object' || err === null) return '';+ const message = (err as { message?: unknown }).message;+ return typeof message === 'string' ? message : '';+}++/**+ * 429 没给 `retry_after`(或给了非法值)时的兜底退避。**只用于兜底** —— 合法值+ * 一律按服务端给的全长等, 不设上限: 任何上限都等于在 flood 窗口结束前提前重试,+ * 那次重试必然再 429, 终稿于是又丢一次(bot-wide flood 的 retry_after 可以远超+ * 一分钟)。不设上限是安全的前提是等待绑定了调用方的生命周期取消源(个人侧是+ * 连接的 outboundAbortSignal, 官方侧是本轮进度载体的关闭)。+ */+export const TELEGRAM_RETRY_AFTER_FALLBACK_MS = 3_000;++/** 429 退避时长: 合法 `retry_after` 原样采用, 缺失或非法(NaN / ≤0 / 非有限)走兜底。 */+export function telegramRetryAfterWaitMs(retryAfterSec: number | undefined): number {+ if (typeof retryAfterSec !== 'number') return TELEGRAM_RETRY_AFTER_FALLBACK_MS;+ if (!Number.isFinite(retryAfterSec) || retryAfterSec <= 0)+ return TELEGRAM_RETRY_AFTER_FALLBACK_MS;+ return retryAfterSec * 1000;+}++/** Telegram 明确回了 429。 */+export function isTelegramRateLimited(err: unknown): boolean {+ return errorCodeOf(err) === 429;+}++/** Telegram 明确回了 400(HTML 实体解析失败等); 调用方据此回落纯文本。 */+export function isTelegramBadRequest(err: unknown): boolean {+ return errorCodeOf(err) === 400;+}++/** 内容未变的重复编辑。必须是 Telegram 的应答(带 errorCode), 不匹配任意本地错误文案。 */+export function isTelegramMessageNotModified(err: unknown): boolean {+ return errorCodeOf(err) !== undefined && /not modified/i.test(messageOf(err));+}++/**+ * 429 退避一次重试。`sleep` 必须能被调用方的生命周期取消提前唤醒, 醒来后由+ * `isLive` 复核 —— 已停止就放弃重试并抛回原始 429, 不再发出任何请求。+ */+export async function callWithTelegramRateLimitRetry<T>(+ call: () => Promise<T>,+ opts: {+ sleep: (ms: number) => Promise<void>;+ isLive: () => boolean;+ },+): Promise<T> {+ try {+ return await call();+ } catch (err) {+ if (!isTelegramRateLimited(err)) throw err;+ const retryAfterSec = (err as { retryAfterSec?: unknown }).retryAfterSec;+ await opts.sleep(+ telegramRetryAfterWaitMs(typeof retryAfterSec === 'number' ? retryAfterSec : undefined),+ );+ if (!opts.isLive()) throw err;+ return call();+ }+}++/**+ * 发一条渲染好的消息: 先按 HTML 发, Telegram 明确 400 时用 `plain` 原样重发。+ * `post(text, parseHtml)` 负责真正的出站(parseHtml=false 时不得带 parse_mode)。+ */+export async function sendTelegramHtmlWithFallback<T>(+ html: string,+ plain: string,+ post: (text: string, parseHtml: boolean) => Promise<T>,+): Promise<T> {+ try {+ return await post(html || '…', true);+ } catch (err) {+ if (!isTelegramBadRequest(err)) throw err;+ return post(plain || '…', false);+ }+}++/**+ * 编辑一条消息为渲染好的 HTML: not modified 视为成功; Telegram 明确 400 时剥掉+ * 标签退回纯文本编辑, 回落那次的 not modified 同样视为成功。`put(text, parseHtml)`+ * 负责真正的出站(parseHtml=false 时不得带 parse_mode)。+ */+export async function editTelegramHtmlWithFallback(+ html: string,+ put: (text: string, parseHtml: boolean) => Promise<void>,+): Promise<void> {+ try {+ await put(html || '…', true);+ } catch (err) {+ if (isTelegramMessageNotModified(err)) return;+ if (!isTelegramBadRequest(err)) throw err;+ try {+ await put(stripTelegramHtmlTags(html) || '…', false);+ } catch (fallbackErr) {+ if (isTelegramMessageNotModified(fallbackErr)) return;+ throw fallbackErr;+ }+ }+}diff --git a/packages/lizi-im/src/telegram/progressFrame.ts b/packages/lizi-im/src/telegram/progressFrame.tsnew file mode 100644index 0000000000..5fb88a7490--- /dev/null+++ b/packages/lizi-im/src/telegram/progressFrame.ts@@ -0,0 +1,37 @@+/**+ * telegram/progressFrame.ts — 运行中过程消息的单帧口径(两个 Telegram bot 同源)。+ * ---------------------------------------------------------------------------+ * 过程消息的生命周期(惰性占位、节流、send→edit)在 `streamingText.ts`, 个人 bot+ * 用 Bot API 驱动它, 官方 bot 用 msg.op 驱动它(desktop+ * `hook-control/telegramProgressCarrier.ts`)。这里只放两侧都要引用、又不属于那个+ * 生命周期类的单帧口径:+ * - 单帧上限 `TELEGRAM_PROGRESS_FRAME_MAX_CHARS`(源 markdown 字符数);+ * - 哪些帧不该落地(`isTelegramProgressFrameSilent`)。+ *+ * 上限按**源 markdown** 计, 不按渲染后的 HTML 计: Telegram 的 4096 上限是实体解析+ * 之后的可见字符数, 标签不占额度; 按 HTML 长度截会把本来放得下的正文无故截掉。+ * 3800 给渲染时新增的少量可见字符(列表符号、省略号)留了余量。+ */++/**+ * 运行中过程消息的单帧上限(源 markdown 字符数)。两个 bot 的唯一出处:+ * `streamingText` 超过它就停止编辑(终稿另行新发); 官方 presenter 的+ * `PresenterPolicy.intermediateMaxRenderedChars` 默认值取它(整轮正文超限时退回+ * 当前消息, 再超限才头部截断), 所以交给过程载体的帧不会触到这条停止线。+ */+export const TELEGRAM_PROGRESS_FRAME_MAX_CHARS = 3800;++/**+ * 自主判断沉默哨兵(全响应群的 ambient turn): 模型整条回复只有它时,+ * 本次 turn 静默。+ */+export const NO_REPLY_SENTINEL = 'NO_REPLY';++/**+ * 这一帧该不该出现在聊天里。空白帧不建消息(惰性占位); NO_REPLY 哨兵及其流式+ * 前缀(分片可能先到 "NO_")同样不落地 —— 否则准备闭嘴的轮次会先冒出一条过程消息。+ */+export function isTelegramProgressFrameSilent(markdown: string): boolean {+ const trimmed = markdown.trim();+ return trimmed === '' || NO_REPLY_SENTINEL.startsWith(trimmed);+}diff --git a/packages/lizi-im/src/telegram/streamingText.ts b/packages/lizi-im/src/telegram/streamingText.tsindex 6453e92159..1300102627 100644--- a/packages/lizi-im/src/telegram/streamingText.ts+++ b/packages/lizi-im/src/telegram/streamingText.ts@@ -15,7 +15,8 @@* (对齐 turnRunner 的 CARD_PATCH_THROTTLE_MS, 双层节流冗余但无害);* - "message is not modified" 错误静默吞掉(内容未变的重复编辑);* - 中间态超过单条上限后停止编辑(终稿由 finalize 分段补发), 与 Discord- * 的 INTERMEDIATE_EDIT_LIMIT 行为一致;+ * 的 INTERMEDIATE_EDIT_LIMIT 行为一致; 上限与"哪些帧不落地"取自+ * progressFrame.ts —— 官方 bot 经 msg.op 驱动的进度消息用的是同一份;* - **终稿永远新发**: 过程消息是可替换的载体, 不能承担最终答案。终稿先尝试* 新发 Rich Message, 不可用时回落新发 HTML/Markdown;答案落地后才尽力清理* 过程载体。@@ -27,16 +28,16 @@ import {type TelegramFinalIntent,type TelegramMessageLifecycle,} from './messageLifecycle.js';+import {+ isTelegramProgressFrameSilent,+ NO_REPLY_SENTINEL,+ TELEGRAM_PROGRESS_FRAME_MAX_CHARS,+} from './progressFrame.js';++export { NO_REPLY_SENTINEL };export const TELEGRAM_UPDATE_THROTTLE_MS = 1500;-/** 中间态渲染后 HTML 超过该长度就不再编辑(接近 4096 上限时停手)。 */-const INTERMEDIATE_EDIT_LIMIT = 3800;const IMAGE_ONLY_PLACEHOLDER = '🖼️';-/**- * 自主判断沉默哨兵(全响应群的 ambient turn): 模型整条回复只有它时,- * 本次 turn 静默 — 经典路径删掉流式占位消息, draft 路径什么都不发。- */-export const NO_REPLY_SENTINEL = 'NO_REPLY';function isNoReply(text: string): boolean {return text.trim() === NO_REPLY_SENTINEL;@@ -95,9 +96,21 @@ function isDefiniteRejection(err: unknown): boolean {return code >= 400 && code < 500;}-export interface TelegramStreamingDeps {+/**+ * 过程载体(运行中那条消息)的出站。两个 bot 都实现它: 个人走 Bot API+ * (`index.ts`), 官方走 msg.op(desktop `hook-control/telegramProgressCarrier.ts`)。+ * 渲染与失败回落(HTML 400 → 纯文本、not modified、429)由实现方经+ * `outboundPolicy.ts` 的同一组判据兑现。+ */+export interface TelegramProgressDeps {/** 发送一条 markdown 渲染消息, 返回编码 messageId。 */send: (markdown: string) => Promise<string>;+ /** 用 markdown 渲染结果覆盖既有消息。 */+ edit: (messageId: string, markdown: string) => Promise<void>;+}++/** 本端发布终稿的车道(个人 bot)才需要的出站; 过程载体之外的全部能力。 */+export interface TelegramStreamingDeps extends TelegramProgressDeps {/*** HTML/Markdown 终稿的补送专用发送。与 send 有两点不同, 都由实现方* (index.ts)负责:@@ -108,8 +121,6 @@ export interface TelegramStreamingDeps {* 身份失效时本函数应当抛错,终稿与后续分段、图片一并不发。未提供时回落 send。*/repost?: (markdown: string) => Promise<string>;- /** 用 markdown 渲染结果覆盖既有消息。 */- edit: (messageId: string, markdown: string) => Promise<void>;/*** 终稿里的受管图片旁路上传(sendPhoto)。*@@ -133,6 +144,13 @@ export interface TelegramStreamingDeps {* 回落 HTML/Markdown 新发。网络/权限失败必须抛出,不能伪装成可安全降级。*/sendFinal?: (markdown: string, reuseReplyTarget: boolean) => Promise<string | null>;+ /**+ * 终稿 HTML/Markdown 分段的专用发送(第 `part` 段, 0 起)。提供时 finalize 的首段与+ * 后续分段都走它, 不再走 `send` / `repost` —— 给需要区分"过程帧 send"与"终稿段+ * send"的传输用(官方 bot: msg.op 的 turn-progress 与 turn-final 是两种登记)。+ * 个人 bot 不提供, 行为不变。+ */+ sendFinalChunk?: (markdown: string, part: number) => Promise<string>;/** NO_REPLY 静默时删除流式占位消息。 */deleteMessage?: (messageId: string) => Promise<void>;}@@ -144,6 +162,61 @@ export function startTelegramStreaming(return TelegramStreamingTextHandle.create(deps, initial);}+/**+ * 只驱动过程载体、终稿不由本端发布的车道(官方 bot: 终稿仍由服务端按 turn.end 发布)。+ * 与个人 bot 是**同一个**生命周期实现(惰性占位、1.5s 尾沿节流、send→edit、单帧上限、+ * NO_REPLY 不落地、失败等下一窗口), 只是不暴露 finalize。+ */+export interface TelegramProgressCarrier {+ /** 过程载体的 messageId; 惰性占位下首帧落地前为空串。 */+ readonly messageId: string;+ /** 整体替换当前快照(latest-wins), 按尾沿节流出站。 */+ replace(fullText: string): void;+ /** 跳过尾沿节流, 立即尝试发出最新快照; 有在途出站时等它结束再发。 */+ flush(): Promise<void>;+ /** 永久停止: 丢弃未出站的帧, 不再发起任何出站。幂等。 */+ close(): void;+}++export function startTelegramProgressCarrier(deps: TelegramProgressDeps): TelegramProgressCarrier {+ const handle = TelegramStreamingTextHandle.createProgressOnly(deps);+ return {+ get messageId() {+ return handle.messageId;+ },+ replace: (fullText) => handle.replace(fullText),+ flush: () => handle.flush(),+ close: () => handle.close(),+ };+}++/**+ * 过程载体 + 本端终稿收口: 同一个 handle(同一份惰性占位 / 节流 / finalize), 但不暴露+ * 个人 bot 的 append / 图片旁路 —— 官方 bot 在协商了客户端终稿时用它。+ */+export interface TelegramTurnCarrier extends TelegramProgressCarrier {+ /** 与个人 bot 完全相同的终稿收口(Rich → HTML → 纯文本、分段、落地后删过程载体)。 */+ finalize(finalText: string): Promise<void>;+}++export function startTelegramTurnCarrier(deps: TelegramStreamingDeps): TelegramTurnCarrier {+ const handle = TelegramStreamingTextHandle.createWithDeps(deps);+ return {+ get messageId() {+ return handle.messageId;+ },+ replace: (fullText) => handle.replace(fullText),+ flush: () => handle.flush(),+ close: () => handle.close(),+ finalize: (finalText) => handle.finalize(finalText),+ };+}++/** 进度专用 handle 的终稿依赖占位: finalize 不对外暴露, 走到这里即接线错误。 */+function finalUnsupported(): never {+ throw new Error('telegram progress carrier does not publish finals');+}+class TelegramStreamingTextHandle implements StreamingTextHandle {private buffer = '';private flushed = '';@@ -217,6 +290,22 @@ class TelegramStreamingTextHandle implements StreamingTextHandle {return this.messageIdValue;}+ /** 见 startTelegramProgressCarrier: 同一实现, 终稿依赖占位为接线错误。 */+ static createProgressOnly(deps: TelegramProgressDeps): TelegramStreamingTextHandle {+ return TelegramStreamingTextHandle.createWithDeps({+ send: deps.send,+ edit: deps.edit,+ chunk: finalUnsupported,+ extractImageUrls: finalUnsupported,+ uploadImages: finalUnsupported,+ });+ }++ /** 同步建 handle(不带初始正文 = 惰性占位, 与 create 无 initial 时等价)。 */+ static createWithDeps(deps: TelegramStreamingDeps): TelegramStreamingTextHandle {+ return new TelegramStreamingTextHandle(deps, createTelegramMessageLifecycle());+ }+static async create(deps: TelegramStreamingDeps,initial?: string,@@ -256,6 +345,13 @@ class TelegramStreamingTextHandle implements StreamingTextHandle {this.clearPending();}+ /** 跳过尾沿节流窗口, 立即尝试发出最新快照(在途出站先等它结束)。 */+ async flush(): Promise<void> {+ if (this.done) return;+ this.clearPending();+ await this.flushIntermediate();+ }+async finalize(finalText: string): Promise<void> {if (this.finalizing) return this.finalizing;if (this.lifecycle.phase === 'final-sent' || this.lifecycle.phase === 'complete') return;@@ -385,7 +481,12 @@ class TelegramStreamingTextHandle implements StreamingTextHandle {// Hermes-style close: always mint a fresh final message. If a process// carrier already exists, repost keeps its frozen reply target; if the// turn was lazy and has no carrier, send consumes the normal target lease.- const post = staleMessageId ? (this.deps.repost ?? this.deps.send) : this.deps.send;+ const sendFinalChunk = this.deps.sendFinalChunk;+ const post = sendFinalChunk+ ? (markdown: string) => sendFinalChunk(markdown, 0)+ : staleMessageId+ ? (this.deps.repost ?? this.deps.send)+ : this.deps.send;await sendFirstChunk(() => post(seed), seed, 1);}}@@ -404,7 +505,9 @@ class TelegramStreamingTextHandle implements StreamingTextHandle {const chunk = chunks[index]!;this.deliveredChunks += 1;try {- await this.deps.send(chunk);+ await (this.deps.sendFinalChunk+ ? this.deps.sendFinalChunk(chunk, index)+ : this.deps.send(chunk));this.unconfirmedChunks.delete(index);} catch (err) {if (isDefiniteRejection(err)) {@@ -507,10 +610,9 @@ class TelegramStreamingTextHandle implements StreamingTextHandle {}}if (this.done || !this.lifecycle.progressOpen || this.buffer === this.flushed) return;- if (this.buffer.length > INTERMEDIATE_EDIT_LIMIT) return;+ if (this.buffer.length > TELEGRAM_PROGRESS_FRAME_MAX_CHARS) return;// 哨兵(或其前缀, 流式可能分片送达)不落地 — 惰性占位下连消息都不建。- const trimmed = this.buffer.trim();- if (trimmed === '' || NO_REPLY_SENTINEL.startsWith(trimmed)) return;+ if (isTelegramProgressFrameSilent(this.buffer)) return;const next = this.buffer;this.inFlight = (async () => {diff --git a/packages/slack-hook-protocol/src/__tests__/protocol-msg-op.test.ts b/packages/slack-hook-protocol/src/__tests__/protocol-msg-op.test.tsindex 26ad372842..b204015971 100644--- a/packages/slack-hook-protocol/src/__tests__/protocol-msg-op.test.ts+++ b/packages/slack-hook-protocol/src/__tests__/protocol-msg-op.test.ts@@ -11,6 +11,14 @@ import { describe, it, expect } from 'vitest';import {HOOK_FEATURE_MESSAGE_OPS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_PROGRESS_OPS,+ makeProviderCommandsSet,+ makeTurnEnd,+ MESSAGE_OP_ERROR_OUTCOME_UNKNOWN,+ MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE,makeMessageOp,makeMessageOpResult,parseHookMessage,@@ -127,3 +135,197 @@ describe('msg.op 动词集', () => {if (!parsed.ok) expect(parsed.error).toContain('unknown message type');});});++/** 拿一帧合法信封换掉 payload(只让 payload 本身决定解析结果)。 */+function withPayload(message: HookMessage, payload: Record<string, unknown>): string {+ const frame = JSON.parse(serializeHookMessage(message)) as Record<string, unknown>;+ frame.payload = payload;+ return JSON.stringify(frame);+}++describe('telegram-progress-ops-v1: 进度消息由客户端渲染、经 msg.op 驱动', () => {+ it('能力标识与服务端同名', () => {+ expect(HOOK_FEATURE_TELEGRAM_PROGRESS_OPS).toBe('telegram-progress-ops-v1');+ });++ it('purpose=turn-progress 的 send / edit 原样 round-trip', () => {+ for (const action of [+ { kind: 'send', text: '<b>x</b>', tier: 'html', silent: true },+ { kind: 'edit', messageId: '9', text: 'x', tier: 'plain' },+ ] as MessageOpAction[]) {+ const parsed = roundTrip(+ makeMessageOp({ opId: 'req-1:progress:x', requestId: 'req-1', scope: SCOPE, action, purpose: 'turn-progress' }),+ );+ expect(parsed.payload).toMatchObject({ purpose: 'turn-progress', requestId: 'req-1', action });+ }+ });++ it('purpose 缺 requestId、用在非 send/edit、或取未知值一律拒收', () => {+ const cases: Array<Record<string, unknown>> = [+ { opId: 'a', scope: SCOPE, purpose: 'turn-progress', action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-progress', action: { kind: 'react', targetMessageId: '1', emoji: '' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'final', action: { kind: 'send', text: 'x' } },+ // 继承属性名不能当成合法 purpose(查表只认自有键), 也不能让解析器抛异常。+ ...['constructor', '__proto__', 'toString', 'hasOwnProperty'].map((purpose) => ({+ opId: 'a',+ requestId: 'r',+ scope: SCOPE,+ purpose,+ action: { kind: 'send', text: 'x' },+ })),+ ];+ for (const payload of cases) {+ const parsed = parseHookMessage(withPayload(op({ kind: 'typing' }), payload));+ expect(parsed.ok).toBe(false);+ }+ });++ it('不带 purpose 的 msg.op 与本能力出现前逐字相同(老帧照常解析)', () => {+ const parsed = roundTrip(op({ kind: 'send', text: 'x' }));+ expect((parsed.payload as { purpose?: unknown }).purpose).toBeUndefined();+ });++ it('msg.op.result 的 errorCode / channelErrorCode 可选; 类型错误拒收', () => {+ const channel = roundTrip(+ makeMessageOpResult({ opId: 'o', ok: false, error: "Bad Request: can't parse entities", channelErrorCode: 400 }),+ );+ expect(channel.payload).toMatchObject({ channelErrorCode: 400 });+ const server = roundTrip(+ makeMessageOpResult({ opId: 'o', ok: false, errorCode: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE, channelErrorCode: null }),+ );+ expect(server.payload).toMatchObject({ errorCode: 'PROGRESS_UNAVAILABLE', channelErrorCode: null });+ expect(MESSAGE_OP_ERROR_OUTCOME_UNKNOWN).toBe('OUTCOME_UNKNOWN');+ for (const bad of [{ errorCode: '' }, { errorCode: 3 }, { channelErrorCode: '400' }, { channelErrorCode: 4.5 }]) {+ const parsed = parseHookMessage(+ withPayload(makeMessageOpResult({ opId: 'o', ok: false }), { opId: 'o', ok: false, ...bad }),+ );+ expect(parsed.ok).toBe(false);+ }+ });+});++describe('telegram 终稿 / 卡片 / 命令菜单由客户端发布', () => {+ const parseOp = (payload: Record<string, unknown>) =>+ parseHookMessage(withPayload(op({ kind: 'typing' }), payload));++ it('能力标识与服务端同名', () => {+ expect([+ HOOK_FEATURE_TELEGRAM_FINAL_OPS,+ HOOK_FEATURE_TELEGRAM_CARD_OPS,+ HOOK_FEATURE_TELEGRAM_COMMANDS,+ ]).toEqual(['telegram-final-ops-v1', 'telegram-card-ops-v1', 'telegram-commands-v1']);+ });++ it('turn-final: send / media 带 finalPart round-trip; 缺 finalPart 或用在 edit 拒收', () => {+ const sendFinal = roundTrip(+ makeMessageOp({+ opId: 'r:final:0',+ requestId: 'r',+ scope: SCOPE,+ purpose: 'turn-final',+ finalPart: 0,+ action: { kind: 'send', text: '**答案**', tier: 'rich', effectId: '5107584321108051014' },+ }),+ );+ expect(sendFinal.payload).toMatchObject({ purpose: 'turn-final', finalPart: 0 });+ const media = roundTrip(+ makeMessageOp({+ opId: 'r:final:1',+ requestId: 'r',+ scope: SCOPE,+ purpose: 'turn-final',+ finalPart: 1,+ action: { kind: 'media', album: true, items: [{ name: 'a.png', mimeType: 'image/png', dataBase64: 'AA' }] },+ }),+ );+ expect(media.payload).toMatchObject({ finalPart: 1 });++ for (const payload of [+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', finalPart: -1, action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-final', finalPart: 0, action: { kind: 'edit', messageId: '1', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, finalPart: 0, action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'turn-progress', finalPart: 0, action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, action: { kind: 'edit', messageId: '1', text: 'x', effectId: 'e' } },+ ]) {+ expect(parseOp(payload).ok).toBe(false);+ }+ });++ it('interaction-card: send 带按钮、收口 edit 清键盘; 缺 interactionId 或错位字段拒收', () => {+ const send = roundTrip(+ makeMessageOp({+ opId: 'r:card:i1:send',+ requestId: 'r',+ scope: SCOPE,+ purpose: 'interaction-card',+ interactionId: 'i1',+ action: {+ kind: 'send',+ text: '<b>🔐 权限请求</b>',+ tier: 'html',+ buttons: [[{ token: 'perm:allow', label: '允许一次' }, { token: 'perm:deny', label: '拒绝' }]],+ },+ }),+ );+ expect(send.payload).toMatchObject({ interactionId: 'i1' });+ const close = roundTrip(+ makeMessageOp({+ opId: 'r:card:i1:close',+ requestId: 'r',+ scope: SCOPE,+ purpose: 'interaction-card',+ interactionId: 'i1',+ interactionClosed: true,+ action: { kind: 'edit', messageId: '9', text: '已拒绝', tier: 'html', buttons: [] },+ }),+ );+ expect(close.payload).toMatchObject({ interactionClosed: true, action: { buttons: [] } });++ for (const payload of [+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', interactionId: 'i', interactionClosed: true, action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, interactionId: 'i', action: { kind: 'send', text: 'x' } },+ { opId: 'a', requestId: 'r', scope: SCOPE, purpose: 'interaction-card', interactionId: 'i', action: { kind: 'send', text: 'x', buttons: [[{ token: '', label: 'x' }]] } },+ ]) {+ expect(parseOp(payload).ok).toBe(false);+ }+ });++ it('turn.end.clientFinal 可选; 形状错误拒收', () => {+ const end = (clientFinal?: unknown) =>+ makeTurnEnd({+ requestId: 'r',+ externalKey: SCOPE.externalKey,+ sessionId: null,+ status: 'ok',+ finalText: 'x',+ errorMessage: null,+ usage: { durationMs: 1 },+ ...(clientFinal !== undefined ? { clientFinal: clientFinal as { complete: boolean } } : {}),+ });+ expect(roundTrip(end({ complete: true })).payload).toMatchObject({ clientFinal: { complete: true } });+ expect((roundTrip(end()).payload as { clientFinal?: unknown }).clientFinal).toBeUndefined();+ expect(parseHookMessage(serializeHookMessage(end({ complete: 'yes' }))).ok).toBe(false);+ });++ it('provider.commands.set: 默认菜单必须有且唯一, 命令名与描述遵守 Telegram 限制', () => {+ const ok = makeProviderCommandsSet({+ provider: 'telegram',+ menus: [+ { languageCode: null, commands: [{ command: 'new', description: 'Create a new task' }] },+ { languageCode: 'zh', commands: [{ command: 'new', description: '新建任务' }] },+ ],+ });+ expect(roundTrip(ok).payload).toEqual(ok.payload);+ for (const menus of [+ [{ languageCode: 'zh', commands: [] }],+ [{ languageCode: null, commands: [] }, { languageCode: null, commands: [] }],+ [{ languageCode: null, commands: [{ command: 'New', description: 'x' }] }],+ [{ languageCode: null, commands: [{ command: 'new', description: '' }] }],+ [{ languageCode: 'zh-CN', commands: [] }, { languageCode: null, commands: [] }],+ ]) {+ expect(parseHookMessage(withPayload(ok, { provider: 'telegram', menus })).ok).toBe(false);+ }+ });+});diff --git a/packages/slack-hook-protocol/src/build.ts b/packages/slack-hook-protocol/src/build.tsindex 470e454270..6ed8d7b61f 100644--- a/packages/slack-hook-protocol/src/build.ts+++ b/packages/slack-hook-protocol/src/build.ts@@ -93,6 +93,8 @@ import {type MessageOpResultPayload,type HookMessageOpMessage,type HookMessageOpResultMessage,+ type HookProviderCommandsSetMessage,+ type ProviderCommandsSetPayload,type TurnReopenPayload,type WelcomePayload,} from './types';@@ -314,6 +316,13 @@ export function makeProviderBehaviorSet(return envelope('provider.behavior.set', payload);}+/** provider.commands.set: 官方 Telegram 命令菜单以 desktop 注册表为准(见 types.ts)。 */+export function makeProviderCommandsSet(+ payload: ProviderCommandsSetPayload,+): HookProviderCommandsSetMessage {+ return envelope('provider.commands.set', payload);+}+export function makeProviderBehaviorState(payload: ProviderBehaviorStatePayload,): HookProviderBehaviorStateMessage {diff --git a/packages/slack-hook-protocol/src/index.ts b/packages/slack-hook-protocol/src/index.tsindex a50e876217..207a3fc1c7 100644--- a/packages/slack-hook-protocol/src/index.ts+++ b/packages/slack-hook-protocol/src/index.ts@@ -45,6 +45,7 @@ export {makeProviderBehaviorGet,makeProviderBehaviorSet,makeProviderBehaviorState,+ makeProviderCommandsSet,makeToolRequest,makeToolResponse,makeGroupMessage,diff --git a/packages/slack-hook-protocol/src/parse.ts b/packages/slack-hook-protocol/src/parse.tsindex 59f66fa20c..957a3382df 100644--- a/packages/slack-hook-protocol/src/parse.ts+++ b/packages/slack-hook-protocol/src/parse.ts@@ -353,6 +353,11 @@ function validateTurnEnd(p: Record<string, unknown>): string | null {if (d !== null && (typeof d !== 'number' || !Number.isFinite(d) || d < 0)) {return 'turn.end.usage.durationMs must be a non-negative finite number or null';}+ if (p.clientFinal !== undefined) {+ if (!isPlainObject(p.clientFinal) || typeof p.clientFinal.complete !== 'boolean') {+ return 'turn.end.clientFinal must be { complete: boolean }';+ }+ }return validateAttachments(p.attachments, 'turn.end');}@@ -436,6 +441,57 @@ function validateTurnReopen(p: Record<string, unknown>): string | null {return null;}+/** msg.op 各 purpose 允许的动作(见 types.ts MessageOpPurpose)。 */+const MESSAGE_OP_PURPOSE_KINDS: Record<string, readonly string[]> = {+ 'turn-progress': ['send', 'edit', 'delete'],+ 'turn-final': ['send', 'media'],+ 'interaction-card': ['send', 'edit'],+};++/**+ * purpose 及其附属字段的联动。附属字段只认对应 purpose: 带错位置的字段一律拒收,+ * 免得执行器把一条普通 send 当成终稿段 / 卡片登记。+ */+function validateMessageOpPurpose(p: Record<string, unknown>, kind: unknown): string | null {+ const purpose = p.purpose;+ if (purpose === undefined) {+ if (p.finalPart !== undefined || p.interactionId !== undefined || p.interactionClosed !== undefined) {+ return 'msg.op.finalPart / interactionId / interactionClosed require a matching purpose';+ }+ return null;+ }+ // 只认自有键: 'constructor' / '__proto__' 这类继承属性不能当成合法 purpose。+ const kinds =+ typeof purpose === 'string' && Object.hasOwn(MESSAGE_OP_PURPOSE_KINDS, purpose)+ ? MESSAGE_OP_PURPOSE_KINDS[purpose]+ : undefined;+ if (!kinds) return 'msg.op.purpose must be one of: turn-progress, turn-final, interaction-card';+ // purpose 按 requestId 归属到一轮(服务端据此核验设备归属并登记消息), 缺了它服务端+ // 无从判断这条消息归谁清理。+ if (!isNonEmptyString(p.requestId)) return `msg.op.requestId is required when purpose is ${purpose}`;+ if (!kinds.includes(kind as string)) {+ return `msg.op.purpose ${purpose} only applies to ${kinds.join('/')}`;+ }+ if (purpose === 'turn-final') {+ if (typeof p.finalPart !== 'number' || !Number.isSafeInteger(p.finalPart) || p.finalPart < 0) {+ return 'msg.op.finalPart must be a non-negative safe integer when purpose is turn-final';+ }+ } else if (p.finalPart !== undefined) {+ return 'msg.op.finalPart only applies to purpose turn-final';+ }+ if (purpose === 'interaction-card') {+ if (!isNonEmptyString(p.interactionId)) {+ return 'msg.op.interactionId is required when purpose is interaction-card';+ }+ if (p.interactionClosed !== undefined && (typeof p.interactionClosed !== 'boolean' || kind !== 'edit')) {+ return 'msg.op.interactionClosed must be a boolean on interaction-card edit';+ }+ } else if (p.interactionId !== undefined || p.interactionClosed !== undefined) {+ return 'msg.op.interactionId / interactionClosed only apply to purpose interaction-card';+ }+ return null;+}+/*** msg.op: 内容面上收客户端后的消息操作动词。*@@ -465,6 +521,8 @@ function validateMessageOp(p: Record<string, unknown>): string | null {if (!isPlainObject(p.action)) return 'msg.op.action must be an object';const action = p.action as Record<string, unknown>;const kind = action.kind;+ const purposeError = validateMessageOpPurpose(p, kind);+ if (purposeError) return purposeError;if (kind === 'send' || kind === 'edit') {if (typeof action.text !== 'string') return `msg.op.action.text must be a string`;if (kind === 'edit' && !isNonEmptyString(action.messageId)) {@@ -478,6 +536,26 @@ function validateMessageOp(p: Record<string, unknown>): string | null {) {return 'msg.op.action.tier must be one of: rich, html, plain';}+ if (action.buttons !== undefined) {+ if (+ !Array.isArray(action.buttons) ||+ action.buttons.some(+ (row) =>+ !Array.isArray(row) ||+ row.some(+ (b) =>+ !isPlainObject(b) ||+ !isNonEmptyString((b as Record<string, unknown>).token) ||+ typeof (b as Record<string, unknown>).label !== 'string',+ ),+ )+ ) {+ return 'msg.op.action.buttons must be rows of { token, label }';+ }+ }+ if (action.effectId !== undefined && (kind !== 'send' || !isNonEmptyString(action.effectId))) {+ return 'msg.op.action.effectId must be a non-empty string on send';+ }return null;}if (kind === 'delete') {@@ -542,6 +620,16 @@ function validateMessageOpResult(p: Record<string, unknown>): string | null {) {return 'msg.op.result.retryAfterMs must be a non-negative finite number or null';}+ if (p.errorCode !== undefined && p.errorCode !== null && !isNonEmptyString(p.errorCode)) {+ return 'msg.op.result.errorCode must be a non-empty string or null';+ }+ if (+ p.channelErrorCode !== undefined &&+ p.channelErrorCode !== null &&+ (typeof p.channelErrorCode !== 'number' || !Number.isInteger(p.channelErrorCode))+ ) {+ return 'msg.op.result.channelErrorCode must be an integer or null';+ }return null;}@@ -1243,6 +1331,49 @@ function validateProviderBehaviorSet(p: Record<string, unknown>): string | nullreturn null;}+const TELEGRAM_COMMAND_NAME = /^[a-z0-9_]{1,32}$/;+const TELEGRAM_LANGUAGE_CODE = /^[a-z]{2}$/;++/**+ * provider.commands.set: 只校验 Telegram setMyCommands 的硬限制与"默认菜单有且仅有+ * 一份"。文案与命令集合由 desktop 注册表决定, 不在协议层判。+ */+function validateProviderCommandsSet(p: Record<string, unknown>): string | null {+ if (p.provider !== 'telegram') return 'provider.commands.set.provider must be telegram';+ if (!Array.isArray(p.menus) || p.menus.length === 0) {+ return 'provider.commands.set.menus must be a non-empty array';+ }+ const seen = new Set<string>();+ for (const menu of p.menus) {+ if (!isPlainObject(menu)) return 'provider.commands.set.menus[] must be objects';+ const code = menu.languageCode;+ if (code !== null && (typeof code !== 'string' || !TELEGRAM_LANGUAGE_CODE.test(code))) {+ return 'provider.commands.set.menus[].languageCode must be a two-letter code or null';+ }+ const key = code === null ? '' : code;+ if (seen.has(key)) return 'provider.commands.set.menus[].languageCode must be unique';+ seen.add(key);+ if (!Array.isArray(menu.commands) || menu.commands.length > 100) {+ return 'provider.commands.set.menus[].commands must be an array of at most 100 items';+ }+ for (const item of menu.commands) {+ if (!isPlainObject(item)) return 'provider.commands.set commands[] must be objects';+ if (typeof item.command !== 'string' || !TELEGRAM_COMMAND_NAME.test(item.command)) {+ return 'provider.commands.set commands[].command must match [a-z0-9_]{1,32}';+ }+ if (+ typeof item.description !== 'string' ||+ item.description.length === 0 ||+ item.description.length > 256+ ) {+ return 'provider.commands.set commands[].description must be 1-256 characters';+ }+ }+ }+ if (!seen.has('')) return 'provider.commands.set.menus must include the default menu (languageCode null)';+ return null;+}+function validateProviderBehaviorState(p: Record<string, unknown>): string | null {const selectorError = validateProviderBehaviorSelector(p, 'provider.behavior.state');if (selectorError) return selectorError;@@ -1421,6 +1552,7 @@ const PAYLOAD_VALIDATORS: Record<HookMessageType, (p: Record<string, unknown>) ='provider.behavior.get': validateProviderBehaviorGet,'provider.behavior.set': validateProviderBehaviorSet,'provider.behavior.state': validateProviderBehaviorState,+ 'provider.commands.set': validateProviderCommandsSet,};/**diff --git a/packages/slack-hook-protocol/src/types.ts b/packages/slack-hook-protocol/src/types.tsindex 7d5c6e7271..5b2a66f28a 100644--- a/packages/slack-hook-protocol/src/types.ts+++ b/packages/slack-hook-protocol/src/types.ts@@ -248,6 +248,7 @@ export const HOOK_MESSAGE_TYPES = ['provider.behavior.get','provider.behavior.set','provider.behavior.state',+ 'provider.commands.set',] as const;export type HookMessageType = (typeof HOOK_MESSAGE_TYPES)[number];@@ -516,6 +517,12 @@ export interface TurnEndPayload {* 旧 server 收到未知字段静默忽略(校验器只查已知字段), 向后兼容。*/attachments?: TaskAttachment[];+ /**+ * 客户端终稿发布结果(HOOK_FEATURE_TELEGRAM_FINAL_OPS)。缺席 = 客户端没发布过终稿,+ * 服务端照旧渲染。只适用于不带附件的轮次: 带附件时 desktop 不发布终稿、不带本字段,+ * 附件照常放在 attachments 里由服务端发送(服务端对带附件的 turn.end 也不认本字段)。+ */+ clientFinal?: TurnEndClientFinal;}/**@@ -1393,12 +1400,18 @@ export type MessageOpAction =silent?: boolean;/** 该消息挂的按钮(语义与形态都由客户端定, 服务端原样下发)。 */buttons?: MessageOpButton[][];+ /**+ * 渠道消息特效(Telegram `message_effect_id`), 客户端决定挂不挂、挂哪个;+ * 服务端原样透传。缺席 = 不挂。+ */+ effectId?: string;}| {kind: 'edit';messageId: string;text: string;tier?: 'rich' | 'html' | 'plain';+ /** 缺席 = 保留原键盘; 空数组 = 清空键盘(收口的卡片必须显式清)。 */buttons?: MessageOpButton[][];}| { kind: 'delete'; messageId: string }@@ -1419,7 +1432,11 @@ export type MessageOpAction =};export interface MessageOpButton {- /** 客户端生成的回调 token; 服务端只做透传与一次性消费, 不解释语义。 */+ /**+ * 客户端生成的回调 token; 服务端只做透传与一次性消费, 不解释语义。+ * `purpose: 'interaction-card'` 时它就是 interaction 的 buttonId: 服务端自己铸+ * callback_data 并记映射, 用户点按后照旧回 interaction.decision(buttonId=token)。+ */token: string;label: string;}@@ -1449,6 +1466,203 @@ export interface MessageOpPayload {requestId?: string;scope: MessageOpScope;action: MessageOpAction;+ /**+ * 这次操作在 turn 里承担什么角色(可选; 缺席 = 普通独立操作, 与本字段出现前+ * 的语义逐字相同)。见 MessageOpPurpose。+ */+ purpose?: MessageOpPurpose;+ /**+ * `purpose: 'turn-final'` 时必填(parse 强制): 这条是终稿的第几段(0 起)。+ * 0 是答案主体: 服务端按这一轮的回复引用策略挂触发消息(与服务端自己发终稿首段+ * 同一规则), 且它是续跑锚点的候选。其余 purpose 不得携带。+ */+ finalPart?: number;+ /** `purpose: 'interaction-card'` 时必填(parse 强制): 这张卡对应的 interactionId。 */+ interactionId?: string;+ /**+ * 只用于 `purpose: 'interaction-card'` 的 `edit`: 这是收口编辑(卡片已决 / 超时 /+ * 撤销)。服务端执行编辑后作废这张卡全部回调映射, 迟到的点按不再转成 decision。+ */+ interactionClosed?: boolean;+}++/**+ * msg.op 的角色标记。+ *+ * `'turn-progress'`: 驱动 `requestId` 那一轮的**进度消息**(客户端渲染的运行中+ * 过程消息)。仅在双方协商 HOOK_FEATURE_TELEGRAM_PROGRESS_OPS 后使用, 且必须带+ * `requestId`(parse 强制)。只用于 `send` / `edit`, `tier` 显式给 html / plain,+ * 不带按钮。服务端语义:+ * - `send`: 核验 requestId 是该设备在 scope.externalKey 上**仍在运行**的一轮,+ * 把新建的消息登记为这一轮的进度消息(与旧 turn.progress 渲染登记的是同一个+ * 位置) —— 终稿仍由服务端按 turn.end 发布, 发布后照旧清理它(续跑轮: 原位+ * 修正旧终稿后清理本轮进度消息)。投递位置的副作用照旧由服务端负责: topic 由+ * lane 记录取, `replyToMessageId` 缺席时按这一轮的「回复引用」策略挂到触发+ * 消息(含 `first` 档的消耗记账, 与旧进度消息逐字相同), `silent` 对应+ * disable_notification;+ * - `edit`: messageId 必须是这一轮登记过的进度消息;+ * - 这一轮已收口 / 不认识 / 不属于该设备, 或这条 lane 的进度由服务端自己承载+ * (私聊草稿 `TELEGRAM_DM_DRAFT_ENABLED`)时, 不调用 Bot API, 回+ * `ok=false, errorCode=MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE`; 客户端据此+ * 停止本轮进度操作。+ *+ * `'turn-progress'` 也可用于 `delete`: 终稿落地后客户端尽力删掉本轮进度消息+ * (messageId 必须是这一轮登记过的进度消息; 服务端在 turn.end 收口时照旧兜底清理)。+ *+ * `'turn-final'`: 客户端发布 `requestId` 那一轮**成功**的终稿(HOOK_FEATURE_TELEGRAM_FINAL_OPS)。+ * 只用于 `send`(tier rich / html / plain), 必须带 `finalPart`; `finalPart=0` 是续跑锚点,+ * 只能是文字段。协议形状仍允许 `media`, 但服务端一律回 MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS+ * —— 附件始终由服务端随 turn.end 发布, desktop 不发。服务端:+ * - 核验这一轮仍在运行、属于该设备; turn.end 已到、不归该设备或私聊草稿模式(终稿随+ * 草稿通道由服务端发布)时回 MESSAGE_OP_ERROR_TURN_UNAVAILABLE;+ * - 投递位置照旧由服务端决定(topic 取 lane; finalPart=0 按服务端终稿首段同一回复+ * 引用规则; 其余段不引用), 消息**会推送**(不带 disable_notification, 除非 silent);+ * - 每条消息登记 botAuthored route(requestId 同一轮, 非 terminal), 并记为「客户端+ * 终稿段」—— 续跑锚点(terminal route)要等 turn.end 的 `clientFinal.complete`+ * 确认后才由服务端把 finalPart=0 那条提升上去(见 TurnEndPayload.clientFinal)。+ *+ * `'interaction-card'`: 客户端发布执行中交互卡(HOOK_FEATURE_TELEGRAM_CARD_OPS)。+ * 只用于 `send` / `edit`, 必须带 `interactionId`。正文与按钮布局全由客户端渲染;+ * 服务端:+ * - 核验 requestId 是该设备仍在运行的一轮;+ * - 投递位置沿用服务端现行规则: 私聊发到本 lane(按回复引用策略挂触发消息), 群 /+ * topic 改投 owner 私聊并在正文前加服务端本地化的来源说明与原消息链接(HTML+ * 转义后前置; 这是投递面的注记, 不属于卡片内容);+ * - 按钮: 每个 MessageOpButton.token 是 buttonId, 服务端铸 callback_data、记+ * (requestId, interactionId, buttonId) 映射, 点按后照旧回 interaction.decision、+ * 清键盘、answerCallbackQuery; 回调映射的有效期与现行卡片相同;+ * - `edit` 的 messageId 按 interactionId 记录核验(卡片可能已被改投 owner 私聊,+ * 不在本 lane 的 route 里); `interactionClosed: true` 时执行后作废回调映射;+ * - 协商后客户端不再为这类卡发 interaction.request / interaction.cancel; 本轮+ * turn.end 收口时服务端对仍未收口的客户端卡只作废回调、清键盘, 不改写正文。+ *+ * 幂等: 服务端按 opId + 内容指纹去重, **同一 opId 配不同内容**回+ * `MESSAGE_OP_ERROR_IDEMPOTENCY_CONFLICT`。所以回执未知时客户端必须原样重发+ * (同 opId 同正文), 不得沿用 opId 换正文。+ */+export type MessageOpPurpose = 'turn-progress' | 'turn-final' | 'interaction-card';++/*+ * msg.op.result.errorCode: 服务端**自己**判定的拒绝(未调用 Bot API, 或调用结果+ * 未知)。开放集合, 客户端只按码分支、不解析 error 文本; 不认识的码按"明确失败"+ * 处理。渠道 API 的拒绝不在这里, 走 channelErrorCode。+ */+/** 本轮进度不由客户端承载(私聊草稿 / 本轮已收口或不属于该设备)。客户端停止本轮进度 op。 */+export const MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE = 'PROGRESS_UNAVAILABLE';+/** 参数不在执行器支持范围内(契约错误)。客户端停止本轮同类 op, 不重试。 */+export const MESSAGE_OP_ERROR_UNSUPPORTED_PARAMETERS = 'UNSUPPORTED_PARAMETERS';+/** edit / delete 的 messageId 不属于该 lane / 该轮。客户端停止对这条消息的操作。 */+export const MESSAGE_OP_ERROR_MESSAGE_NOT_OWNED = 'MESSAGE_NOT_OWNED';+/** 设备的绑定已撤销或换代。客户端停止本轮 op。 */+export const MESSAGE_OP_ERROR_BINDING_REVOKED = 'BINDING_REVOKED';+/** 服务端限速队列拒收; 带 retryAfterMs, 客户端按它退避(与渠道 429 同处理)。 */+export const MESSAGE_OP_ERROR_RATE_LIMITED = 'RATE_LIMITED';+/** 同一 opId 配了不同内容。客户端的幂等记账出错, 按明确失败处理。 */+export const MESSAGE_OP_ERROR_IDEMPOTENCY_CONFLICT = 'IDEMPOTENCY_CONFLICT';+/** 服务端幂等记账已满, 拒收新操作(不淘汰旧回执)。明确未执行, 可换 opId 稍后再试。 */+export const MESSAGE_OP_ERROR_CAPACITY_REACHED = 'CAPACITY_REACHED';+/**+ * 已调用渠道 API 但拿不到确定结果(网络中断 / 5xx / 回执异常), 消息**可能已经落地**。+ * 客户端不得换 opId 重发同一内容: 只能原样重发同一 opId 对账。+ */+export const MESSAGE_OP_ERROR_OUTCOME_UNKNOWN = 'OUTCOME_UNKNOWN';+/** 渠道已执行但服务端登记失败(服务端已尽力撤回该消息)。明确失败, 可换 opId 重试。 */+export const MESSAGE_OP_ERROR_PERSIST_FAILED = 'PERSIST_FAILED';+/**+ * `turn-final` / `interaction-card`: 这一轮已收口(turn.end 已到)、不认识或不属于+ * 该设备。客户端停止本轮这类 op —— 终稿交回服务端按 turn.end 发布, 卡片交回+ * interaction.request 旧路径(本轮仍在跑时)。+ */+export const MESSAGE_OP_ERROR_TURN_UNAVAILABLE = 'TURN_UNAVAILABLE';++/**+ * 双向能力标识: 官方 Telegram 的运行中进度消息改由 desktop 渲染、经+ * `msg.op`(`purpose: 'turn-progress'`)驱动。必须与 HOOK_FEATURE_MESSAGE_OPS+ * 同时协商; 只在 telegram provider 的连接上声明。+ *+ * 协商后的分工(内容面在客户端, 投递面在服务端):+ * - desktop 用与个人 bot 同一个过程载体与渲染(@cindy/im+ * `startTelegramProgressCarrier` + `markdownToTelegramHtml`)生成 HTML, 首帧+ * `send`、后续 `edit`; HTML 被拒(`channelErrorCode=400`)本地回落+ * `tier: 'plain'`, `message is not modified` 视为成功, 429 按 `retryAfterMs`+ * 退避, 期间的新帧合并成最新一帧;+ * - desktop **照发** turn.progress(服务端靠它续 turn lease), 但服务端**不再+ * 用它渲染**进度消息 —— 唯一例外是服务端仍自己承载进度的私聊草稿模式+ * (此时进度 msg.op 回 PROGRESS_UNAVAILABLE, 服务端继续按 turn.progress 出草稿);+ * - 终稿发布、进度消息清理、离线自治仍归服务端, 不随本能力改变。+ *+ * 任一侧缺席: desktop 只发 turn.progress, 服务端照旧渲染, 行为与本能力出现前+ * 逐字相同。+ */+export const HOOK_FEATURE_TELEGRAM_PROGRESS_OPS = 'telegram-progress-ops-v1';++/**+ * 双向能力标识: 官方 Telegram **成功轮次**的终稿由 desktop 用与个人 bot 同一套收口+ * (@cindy/im `startTelegramStreaming` 的 finalize: Rich → HTML → 纯文本、分块、落地后+ * 删进度消息)经 `msg.op`(`purpose: 'turn-final'`)发布。须与 HOOK_FEATURE_MESSAGE_OPS+ * 同时协商, 只在 telegram 连接上声明。+ *+ * **终稿必达不降级**: desktop 先把 turn.end 写进本地持久出箱, 再发布, 最后发 turn.end+ * 并用 `clientFinal` 说明结果。服务端只在 `clientFinal.complete === true` 时跳过自己+ * 渲染; 否则(未完成 / 缺席 / 重启后从出箱重放)删掉本轮已落地的客户端终稿段并照旧自己+ * 发布 —— 最坏是一次重新发布, 不会缺答案也不会两份并存。+ *+ * 只覆盖普通轮次、不带附件的 `status: 'ok'`。失败 / 取消 / 续跑轮(原位修正旧终稿)/+ * 正文恰为 NO_REPLY(ambient 判定在服务端)/ **带任何附件**时, desktop 不发 `turn-final`,+ * 由服务端按 turn.end 照旧处理; turn.end 带附件时服务端也不认 `clientFinal`(附件始终由+ * 服务端发送)。+ */+export const HOOK_FEATURE_TELEGRAM_FINAL_OPS = 'telegram-final-ops-v1';++/**+ * 双向能力标识: 官方 Telegram 执行中交互卡(ask / plan / 权限)由 desktop 用与个人 bot+ * 同一份卡片渲染(@cindy/im `layoutTelegramCard`: 标题 + markdown 正文 → HTML、正文上限、+ * 按钮成对排布)经 `msg.op`(`purpose: 'interaction-card'`)发布与收口; 按钮回调仍由+ * 服务端收入站并照旧回 interaction.decision。须与 HOOK_FEATURE_MESSAGE_OPS 同时协商。+ * 任一侧缺席: 走 interaction.request / interaction.cancel 旧路径, 服务端照旧渲染。+ */+export const HOOK_FEATURE_TELEGRAM_CARD_OPS = 'telegram-card-ops-v1';++/**+ * 双向能力标识: 官方 Telegram 的命令菜单以 desktop 的命令注册表为唯一真相源, 经+ * `provider.commands.set` 下发。任一侧缺席: 服务端照旧用自己的 TELEGRAM_COMMANDS。+ */+export const HOOK_FEATURE_TELEGRAM_COMMANDS = 'telegram-commands-v1';++/**+ * turn.end 的客户端终稿发布结果(只在协商 HOOK_FEATURE_TELEGRAM_FINAL_OPS、且 desktop+ * 尝试过 `turn-final` 时出现)。+ */+export interface TurnEndClientFinal {+ /**+ * true = 本轮全部终稿段都拿到了成功回执: 服务端不再渲染 finalText,+ * 把 finalPart=0 那条提升为续跑锚点(terminal route), 照常做收口副作用(群中继+ * —— 文本取本帧 finalText、消息 id 取锚点; 清理进度消息与未收口卡片; 终态表情;+ * inflight 移除)。+ * false = 发布没有完整确认: 服务端删掉本轮已登记的客户端终稿段(尽力), 再照旧自己发布。+ */+ complete: boolean;+}++/**+ * provider.commands.set(desktop -> server): 官方 Telegram 命令菜单+ * (HOOK_FEATURE_TELEGRAM_COMMANDS)。每次握手成功后发一次; 服务端**只存内存、不落库**,+ * 按 `{type:'chat', chat_id: principalId}` 作用域调用 setMyCommands。服务端只管理默认+ * 菜单与 zh / ja / ko, 每次全量重写(缺席的语言写空, 其它语言码含显式 'en' 忽略); 只有该+ * 设备当前仍协商本能力时才用它的菜单。服务端重启后到 desktop 重连前(以及设备离线期间)+ * 用服务端自己的默认菜单。服务端只校验形状与 Telegram 限制, 不改文案、不增删命令。+ */+export interface ProviderCommandsSetPayload {+ provider: 'telegram';+ /** 每个语言一份; languageCode=null 是不带 language_code 的默认菜单(必须有且仅有一份)。 */+ menus: TelegramCommandMenu[];+}++export interface TelegramCommandMenu {+ /** Telegram language_code(两位小写 ISO 639-1); null = 默认菜单。 */+ languageCode: string | null;+ /** 菜单顺序即展示顺序。command 1-32 位 [a-z0-9_]; description 1-256 字。至多 100 条。 */+ commands: Array<{ command: string; description: string }>;}/**@@ -1467,6 +1681,17 @@ export interface MessageOpResultPayload {messageIds?: string[];error?: string | null;retryAfterMs?: number | null;+ /**+ * 服务端自己判定的结构化拒绝码(开放集合; 缺席/null = 没有这类拒绝)。客户端只按+ * 码分支, 不解析 `error` 文本。已定义: MESSAGE_OP_ERROR_PROGRESS_UNAVAILABLE。+ */+ errorCode?: string | null;+ /**+ * 渠道 API 拒绝时的**原生**错误码(Telegram `error_code`, 如 400 / 429), 服务端+ * 原样透传、不翻译; 此时 `error` 为渠道原文 description。客户端据此做与个人 bot+ * 同判据的回落(HTML 被拒 400 → plain)。缺席/null = 不是渠道拒绝或老服务端。+ */+ channelErrorCode?: number | null;}/**@@ -1688,6 +1913,10 @@ export type HookProviderBehaviorSetMessage = HookEnvelope<'provider.behavior.set',ProviderBehaviorSetPayload>;+export type HookProviderCommandsSetMessage = HookEnvelope<+ 'provider.commands.set',+ ProviderCommandsSetPayload+>;export type HookProviderBehaviorStateMessage = HookEnvelope<'provider.behavior.state',ProviderBehaviorStatePayload@@ -1734,6 +1963,7 @@ export type HookMessage =| HookProviderBehaviorGetMessage| HookProviderBehaviorSetMessage| HookProviderBehaviorStateMessage+ | HookProviderCommandsSetMessage| HookMessageOpMessage| HookMessageOpResultMessage;