lark-remote 0.1.6 → 0.1.8

package/CHANGELOG.md

@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.8] - 2026-08-19
+
+### 新增
+
+- DSH（DeepSeek Harness）Agent 接入：纯 HTTP 连接 DSH Web Host（无本地子进程），支持会话创建/续跑、`selectModel` 模型对齐、SSE mux 事件订阅、会话历史读取
+- `/config` DSH 配置卡：Host 地址 / 会话 preset / 模型 / 推理强度，模型与预设目录预取动态加载（失败回退固定兜底清单）
+- AskUserQuestion 公共契约（`question-common`）：标准提问审批事件工厂 + 按序答案映射，claude / codex / kimi / pi 统一接入
+- Codex AskUserQuestion：支持自由文本题、补充说明（user_note）、`autoResolutionMs` 透传为单请求审批超时
+- Kimi elicitation 表单回编 + request_permission 兜底桥
+- 工具权限审批卡（`kind === 'tool'`）：ExitPlanMode 等非命令工具展示工具名 + 用途说明，计划审批语义
+- 提问卡单选/多选图标区分（⚪/🔵 vs ⬜/☑️）、自由文本题输入框、自定义答案回显
+
+### 变更
+
+- claude session usage 扫描对齐 codex 语义：非累计字段为末轮（本 run）scope，累计走 `cumulative*` 字段
+- Compact 按钮能力门控放开到所有 `runCompact` 能力 runner（claude / codex / kimi / opencode / pi）
+- claude `/config` 权限模式下拉排除 `manual`（`default` 的别名，避免等价重复项）
+- workspace 保存即触达：`save` 内部调用 `touch`，新保存的工作区排在列表最前
+- DSH 可用性探测跳过二进制检查（HTTP-only Agent）
+
+### 修复
+
+- claude session usage 扫描：修复第三方网关（如 DeepSeek）将零 usage 写在占位行、真实 usage 只在末行导致的 per-run 统计全 0（改为按 message id 逐字段 max 聚合）
+- 审批答案重复投递（重复 nonce 二次点击）改为中性提示，不再误报"提交失败"
+- usage 统计一致性护栏：本 run 超出累计时显式标记 `⚠️ 累计异常`（只标记不修正，便于排查数据源问题）
+
+## [0.1.7] - 2026-08-18
+
+### 新增
+
+- pi RPC 模式 runner：通过持久连接复用共享 `ConnectionManager`，支持审批与上下文压缩
+- kimi / opencode ACP 模式 runner：纯 ACP 持久连接，支持审批 + Compact
+- 共享 ACP / JSON-RPC 连接层（`runner/common/acp`、`runner/common/jsonrpc`）：统一 codex / kimi / opencode / pi 的连接管理
+- 入站图片/文件自动落盘：往飞书私聊发图片/文件自动保存到 `.lark-remote-temp/`，可直接让 agent 处理
+- `/order alias`：注册快捷别名，输入 `$name` 即展开
+- 会话分页/截断共享辅助模块（`session/common/pagination`）
+- Codex 命令审批卡片示例图
+
+### 变更
+
+- codex runner 统一走 app-server 审批模式；移除 codex/kimi/opencode/pi 的 exec/jsonl 旧模式与死代码
+- `codex-bundled-test-helpers` 迁移至 `tests/lib/`
+- 用户文档：新增入站文件、`/order alias`、kimi acp 配置说明
+
+### 修复
+
+- 修复文档引用指向被排除的本地文档导致的破链
+
 ## [0.1.6] - 2026-08-14
 
 ### 新增
@@ -14,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Codex runner 工厂：自动选择直连模式或 App Server 模式
 - `rollout-reader`：Codex App Server rollout 开关读取
 - Run card 审批区域渲染 + context limit 百分比显示
-- 架构文档：`codex-app-server-integration.md`
+- 架构文档：`docs/zh/guides/codex-config.md`
 
 ### 修复
 
@@ -153,3 +201,5 @@ Initial release.
 [0.1.4]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.4
 [0.1.5]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.5
 [0.1.6]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.6
+[0.1.7]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.7
+[0.1.8]: https://github.com/bungabungawoda/lark-remote/releases/tag/v0.1.8

package/README.en.md

@@ -16,13 +16,17 @@ Designed for a single-user, peer-to-peer private chat. The agent's system prompt
 
 ## ⚠️ Security Warning (read first)
 
-This tool turns Feishu messages directly into local agent executions, and agents run with **full permissions** by default (Claude `bypassPermissions`, Codex `approval_policy=never` + full access) — effectively handing a shell on your machine to whoever can chat with the bot. You MUST:
+This tool turns Feishu messages directly into local agent executions. Claude runs with **full permissions** by default (fixed `bypassPermissions`); Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`), which is relatively safe; other agents run with their CLI defaults. Agents can still read and write the local directories you specify. You MUST:
 
 - **Use it only in your own private (p2p) chat.** Never add the bot to any group chat; never let anyone else talk to it.
 - Restrict the app's visibility to **yourself only** in the Feishu Open Platform.
 - Don't run it on a machine holding data you can't afford to lose; prefer a dedicated user / machine / container.
 - Keep credentials such as `appSecret` in your local `config.yaml` only — **never commit them anywhere**.
 
+In Codex approval mode, an approval card arrives before any command runs — approve or reject it right in Feishu:
+
+![Codex command approval card example](docs/images/approval-card.png)
+
 ## Prerequisites
 
 - OS: macOS / Linux. **Windows is not supported yet** (relies on POSIX behaviors such as Unix signals, bash, and file locks)
@@ -153,6 +157,10 @@ Full docs under [`docs/`](docs/):
 
 > This package is a CLI tool only — no programmatic API is exposed.
 
+## Acknowledgments
+
+This project was inspired by [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) — thanks for demonstrating the feasibility of bridging Feishu with local coding agents.
+
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/README.md

@@ -16,13 +16,17 @@
 
 ## ⚠️ 安全警告（必读）
 
-本工具会把飞书消息直接转为本地 agent 执行，agent 默认以**完全权限**运行（Claude `bypassPermissions`、Codex `approval_policy=never` + full access），等价于把一台机器的 shell 交给聊天对端。请务必：
+本工具会把飞书消息直接转为本地 agent 执行。Claude 默认以**完全权限**运行（固定 `bypassPermissions`）；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`），相对安全；其他 agent 以各自 CLI 的默认权限运行。agent 仍可读写你指定的本地目录，请务必：
 
 - **仅限你自己的私聊（p2p）使用**。不要把机器人拉进任何群聊，不要让任何其他人能与它对话。
 - 在飞书开放平台把应用可见范围限制到**只有你自己**。
 - 运行本工具的机器上不要存放与损失承受力不符的数据；建议在独立用户/机器/容器里运行。
 - `appSecret` 等凭据只在本地 `config.yaml`，**不要提交到任何仓库**。
 
+Codex 审批模式下，执行命令前会收到审批卡片，可直接在飞书里允许或拒绝：
+
+![Codex 命令审批卡片示例](docs/images/approval-card.png)
+
 ## 前置条件
 
 - 操作系统：macOS / Linux。**暂不支持 Windows**（依赖 Unix 信号、bash、文件锁等 POSIX 行为）
@@ -120,12 +124,16 @@ bridge 启动后不在终端输出，运行日志写入 `~/.lark-remote/logs/YYY
 | `/reconnect` | - | 重连飞书 |
 | `/restart` | - | 原地自重启 bridge（新进程同 config 接管） |
 | `/config get\|set` | `/c` | 查改运行时配置（agent-aware 卡片） |
-| `/order save\|list` | `/o` | 保存或列出常用指令 |
+| `/order save\|list\|alias` | `/o` | 收藏常用指令；`/order alias` 注册快捷别名（输入 `$name` 展开） |
 | `!<cmd>` | - | 执行 bash 命令并流式输出到卡片（绕过串行队列） |
 | `/exit` | `/e` | 退出 bridge |
 
 直接发非 `/` 开头的消息即转发给当前默认 agent。
 
+往飞书私聊发**图片/文件**会自动保存到当前目录的 `.lark-remote-temp/<YYYYMMDDHHmm>/`
+（建议把 `.lark-remote-temp/` 加进项目 `.gitignore`），随后说「请处理刚才保存的文件」
+即可让 agent 直接读本地文件。更多用法见 [docs/zh/usage.md](docs/zh/usage.md)。
+
 ## 测试
 
 ```bash
@@ -152,6 +160,10 @@ FEISHU_LIVE_TEST=1 bun run test tests/feishu-reaction-emoji-live.test.ts
 
 > 本包为纯 CLI 工具，不提供编程 API。
 
+## 致谢
+
+本项目受到了 [lark-coding-agent-bridge](https://github.com/zarazhangrui/lark-coding-agent-bridge) 的启发，感谢该项目展示了飞书与本地 Coding Agent 桥接的可行性。
+
 ## License
 
 [MIT](LICENSE) © bungabungawoda

package/dist/bridge/approval-coordinator.d.ts

@@ -6,30 +6,25 @@
  * - onResolved: update state, clear timer
  * - submit: validate → atomic state transition → async respond
  * - togglePerm: flip permission item selection
- * - onTurnEnded / onConnectionLost: mark all as expired
+ * - onTurnEnded: mark all as expired
  */
 import type { ApprovalRequestedEvent, ApprovalView, AgentEvent } from '../runner/types.js';
-export type ApprovalState = 'pending' | 'submitting' | 'resolved' | 'failed' | 'expired';
+import type { ApprovalAction } from '../runner/types.js';
+type ApprovalState = 'pending' | 'submitting' | 'resolved' | 'failed' | 'expired';
 export interface TrackedApproval {
     requestId: number | string;
-    kind: 'command' | 'file' | 'permissions';
+    kind: 'command' | 'file' | 'permissions' | 'question' | 'tool';
     state: ApprovalState;
     view: ApprovalView;
     createdAt: number;
     timeoutTimer: ReturnType<typeof setTimeout> | null;
+    /** AskUserQuestion 已答问题索引 → 答案 label[]（kind === 'question'）。 */
+    answers?: Map<number, string[]>;
+    /** AskUserQuestion 补充说明（Codex user_note）：问题索引 → 文本。 */
+    notes?: Map<number, string>;
 }
-export type ApprovalResponder = (requestId: number | string, response: unknown) => Promise<void>;
-export type ApprovalAction = {
-    action: 'accept';
-} | {
-    action: 'accept_for_session';
-} | {
-    action: 'accept_with_execpolicy_amendment';
-} | {
-    action: 'decline';
-} | {
-    action: 'cancel';
-};
+type ApprovalResponder = (requestId: number | string, response: unknown) => Promise<void>;
+export type { ApprovalAction } from '../runner/types.js';
 export interface ApprovalToggleAction {
     permId: string;
     selected: boolean;
@@ -38,19 +33,11 @@ export declare class ApprovalCoordinator {
     private approvals;
     /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
     private submittedNonces;
-    private readonly runId;
-    private readonly userId;
-    private readonly chatId;
-    private readonly workspace;
     private readonly approvalTimeoutMs;
     private readonly responder;
     private readonly interruptTurn;
     private readonly pushToCard;
     constructor(opts: {
-        runId: string;
-        userId: string;
-        chatId: string;
-        workspace: string;
         approvalTimeoutMs: number;
         responder: ApprovalResponder;
         interruptTurn: () => Promise<void>;
@@ -68,24 +55,66 @@ export declare class ApprovalCoordinator {
      * Handle turn ended — mark all pending approvals as expired.
      */
     onTurnEnded(): void;
-    /**
-     * Handle connection lost — same as onTurnEnded.
-     */
-    onConnectionLost(): void;
     /**
      * Submit an approval decision.
-     * Returns a promise that resolves when the response is sent.
      */
     submit(action: ApprovalAction, ctx: {
         requestId: number | string;
         nonce?: string;
-    }): Promise<string>;
+    }): Promise<void>;
     /**
      * Toggle a permission item's selected state.
      */
     togglePerm(action: ApprovalToggleAction, ctx: {
         requestId: number | string;
-    }): Promise<string>;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 选项点击。
+     *
+     * - 单选：点击即选中该选项；全部问题答完时自动通过 responder 提交答案。
+     * - 多选：切换 selected 并推 approval_view_updated 重渲染，等待
+     *   submitAnswers() 显式提交。
+     */
+    toggleAnswer(action: {
+        questionIndex: number;
+        option: string;
+    }, ctx: {
+        requestId: number | string;
+        nonce?: string;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 提交该问题当前勾选的选项；全部问题答完时通过 responder 提交。
+     */
+    submitAnswers(action: {
+        questionIndex: number;
+    }, ctx: {
+        requestId: number | string;
+        nonce?: string;
+    }): Promise<void>;
+    /**
+     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
+     */
+    answerCustom(action: {
+        questionIndex: number;
+        text: string;
+    }, ctx: {
+        requestId: number | string;
+        nonce?: string;
+    }): Promise<void>;
+    /**
+     * AskUserQuestion 补充说明（Codex user_note）：选项之外的可选文本，随答案
+     * 提交；不单独构成答案（仍需选项/自定义答案才能完成该问题）。note 更新
+     * 后回流视图（卡片回显），同一请求可多次修改（新 nonce 来自新渲染）。
+     */
+    answerNote(action: {
+        questionIndex: number;
+        text: string;
+    }, ctx: {
+        requestId: number | string;
+        nonce?: string;
+    }): Promise<void>;
     /**
      * Update a pending approval's view (out-of-order item/started arrives late).
      * Only applies while the approval is still pending — resolved/expired
@@ -96,11 +125,19 @@ export declare class ApprovalCoordinator {
      * Get the number of pending approvals.
      */
     pendingCount(): number;
-    /**
-     * Get the head (oldest pending) approval, or undefined.
-     */
-    head(): TrackedApproval | undefined;
     private clearTimer;
+    /** nonce 去重：同一 nonce 只允许生效一次（防连点/飞书重投递）。 */
+    private assertFreshNonce;
+    /** 记录问题答案到 tracked.answers（懒初始化 Map）。 */
+    private recordAnswer;
+    private getPendingQuestion;
+    private allQuestionsAnswered;
+    /** 推送 question 卡片视图更新（选项勾选状态变化）。 */
+    private pushQuestionViewUpdate;
+    /** 全部问题已答：构建 answers 并提交（非空校验 + 原子状态迁移）。 */
+    private respondQuestionAnswers;
+    /** 推 approval_resolved 到卡片（移除审批区；幂等，失败仅记日志）。 */
+    private pushResolved;
     private expireApproval;
     private actionToDecision;
 }

package/dist/bridge/approval-coordinator.js

@@ -6,7 +6,7 @@
  * - onResolved: update state, clear timer
  * - submit: validate → atomic state transition → async respond
  * - togglePerm: flip permission item selection
- * - onTurnEnded / onConnectionLost: mark all as expired
+ * - onTurnEnded: mark all as expired
  */
 import { getLogger } from '../logger/index.js';
 // =============================================================================
@@ -16,19 +16,11 @@ export class ApprovalCoordinator {
     approvals = new Map();
     /** 已提交过的 nonce（按 requestId）：同一按钮连点/飞书重投递只生效一次。 */
     submittedNonces = new Map();
-    runId;
-    userId;
-    chatId;
-    workspace;
     approvalTimeoutMs;
     responder;
     interruptTurn;
     pushToCard;
     constructor(opts) {
-        this.runId = opts.runId;
-        this.userId = opts.userId;
-        this.chatId = opts.chatId;
-        this.workspace = opts.workspace;
         this.approvalTimeoutMs = opts.approvalTimeoutMs;
         this.responder = opts.responder;
         this.interruptTurn = opts.interruptTurn;
@@ -45,9 +37,12 @@ export class ApprovalCoordinator {
             existing.view = event.view;
             return;
         }
+        // 事件级 timeoutMs 优先（Codex autoResolutionMs / Pi extension timeout），
+        // 缺省回落 run 级默认超时。放在事件上而非桥按 agentKind 分支，公共层
+        // 保持无 agent 分支。
         const timer = setTimeout(() => {
             this.expireApproval(event.requestId);
-        }, this.approvalTimeoutMs);
+        }, event.timeoutMs ?? this.approvalTimeoutMs);
         const tracked = {
             requestId: event.requestId,
             kind: event.kind,
@@ -79,15 +74,8 @@ export class ApprovalCoordinator {
             }
         }
     }
-    /**
-     * Handle connection lost — same as onTurnEnded.
-     */
-    onConnectionLost() {
-        this.onTurnEnded();
-    }
     /**
      * Submit an approval decision.
-     * Returns a promise that resolves when the response is sent.
      */
     async submit(action, ctx) {
         const tracked = this.approvals.get(ctx.requestId);
@@ -97,14 +85,7 @@ export class ApprovalCoordinator {
         // nonce 去重：同一张卡片渲染出的按钮连续点击（或飞书重投递）携带相同
         // nonce，只允许生效一次；不同渲染的按钮 nonce 不同，状态机（pending →
         // submitting）仍然兜底防二次提交。
-        if (ctx.nonce !== undefined) {
-            const seen = this.submittedNonces.get(ctx.requestId) ?? new Set();
-            if (seen.has(ctx.nonce)) {
-                throw new Error(`Approval request ${ctx.requestId} already submitted (duplicate nonce)`);
-            }
-            seen.add(ctx.nonce);
-            this.submittedNonces.set(ctx.requestId, seen);
-        }
+        this.assertFreshNonce(ctx.requestId, ctx.nonce);
         if (tracked.state !== 'pending') {
             throw new Error(`Approval request ${ctx.requestId} is no longer pending (state=${tracked.state})`);
         }
@@ -123,11 +104,14 @@ export class ApprovalCoordinator {
         try {
             await this.responder(ctx.requestId, action);
             tracked.state = 'resolved';
+            // 提交成功后立即从卡片移除审批区（agent 无关）：claude 控制协议没有
+            // resolved 回发，不推就会「已点允许按钮仍在」残留 UI；codex 的 server
+            // 稍后也会发 approval_resolved，reducer 按 requestId 过滤幂等。
+            this.pushResolved(ctx.requestId);
         }
         catch {
             tracked.state = 'failed';
         }
-        return `Approval ${tracked.requestId} (${tracked.kind}): ${decision}`;
     }
     /**
      * Toggle a permission item's selected state.
@@ -152,7 +136,118 @@ export class ApprovalCoordinator {
             throw new Error(`Permission item ${action.permId} not found in request ${ctx.requestId}`);
         }
         item.selected = action.selected;
-        return `Permission ${action.permId}: ${action.selected ? 'granted' : 'denied'}`;
+    }
+    /**
+     * Claude AskUserQuestion 选项点击。
+     *
+     * - 单选：点击即选中该选项；全部问题答完时自动通过 responder 提交答案。
+     * - 多选：切换 selected 并推 approval_view_updated 重渲染，等待
+     *   submitAnswers() 显式提交。
+     */
+    async toggleAnswer(action, ctx) {
+        const tracked = this.getPendingQuestion(ctx.requestId);
+        const questions = tracked.view.questions;
+        const q = questions[action.questionIndex];
+        if (!q) {
+            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
+        }
+        const option = q.options.find((o) => o.label === action.option);
+        if (!option) {
+            throw new Error(`Option "${action.option}" not found in question ${action.questionIndex}`);
+        }
+        const selected = new Set(q.selected ?? []);
+        if (q.multiSelect) {
+            // review P2-1：多选切换按钮同一 nonce 重复投递（双击/飞书重投递）只应
+            // toggle 一次，否则勾选会被二次 toggle 抵消。单选用例的重复防护在
+            // respondQuestionAnswers（提交即幂等，选中是 set 语义）。
+            this.assertFreshNonce(ctx.requestId, ctx.nonce);
+            if (selected.has(action.option)) {
+                selected.delete(action.option);
+            }
+            else {
+                selected.add(action.option);
+            }
+            q.selected = [...selected];
+            this.pushQuestionViewUpdate(ctx.requestId, tracked);
+            return;
+        }
+        // 单选：替换选择；全部问题答完立即提交，否则等待后续问题。
+        q.selected = [action.option];
+        this.recordAnswer(tracked, action.questionIndex, [action.option]);
+        if (this.allQuestionsAnswered(tracked)) {
+            return this.respondQuestionAnswers(tracked, ctx);
+        }
+        this.pushQuestionViewUpdate(ctx.requestId, tracked);
+    }
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 提交该问题当前勾选的选项；全部问题答完时通过 responder 提交。
+     */
+    async submitAnswers(action, ctx) {
+        const tracked = this.getPendingQuestion(ctx.requestId);
+        const questions = tracked.view.questions;
+        const q = questions[action.questionIndex];
+        if (!q) {
+            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
+        }
+        if (!q.multiSelect) {
+            throw new Error('该问题为单选，请直接点击选项');
+        }
+        const selected = q.selected ?? [];
+        if (selected.length === 0) {
+            throw new Error('请先选择至少一个选项');
+        }
+        this.recordAnswer(tracked, action.questionIndex, selected);
+        if (this.allQuestionsAnswered(tracked)) {
+            return this.respondQuestionAnswers(tracked, ctx);
+        }
+    }
+    /**
+     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
+     */
+    async answerCustom(action, ctx) {
+        const tracked = this.getPendingQuestion(ctx.requestId);
+        const questions = tracked.view.questions;
+        const q = questions[action.questionIndex];
+        if (!q) {
+            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
+        }
+        if (q.multiSelect) {
+            throw new Error('自定义答案仅支持单选');
+        }
+        const text = action.text.trim();
+        if (!text) {
+            throw new Error('请输入自定义答案');
+        }
+        q.selected = [text];
+        this.recordAnswer(tracked, action.questionIndex, [text]);
+        if (this.allQuestionsAnswered(tracked)) {
+            return this.respondQuestionAnswers(tracked, ctx);
+        }
+        this.pushQuestionViewUpdate(ctx.requestId, tracked);
+    }
+    /**
+     * AskUserQuestion 补充说明（Codex user_note）：选项之外的可选文本，随答案
+     * 提交；不单独构成答案（仍需选项/自定义答案才能完成该问题）。note 更新
+     * 后回流视图（卡片回显），同一请求可多次修改（新 nonce 来自新渲染）。
+     */
+    async answerNote(action, ctx) {
+        const tracked = this.getPendingQuestion(ctx.requestId);
+        const questions = tracked.view.questions;
+        const q = questions[action.questionIndex];
+        if (!q) {
+            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
+        }
+        const text = action.text.trim();
+        if (!text) {
+            throw new Error('请输入补充说明');
+        }
+        this.assertFreshNonce(ctx.requestId, ctx.nonce);
+        tracked.notes ??= new Map();
+        tracked.notes.set(action.questionIndex, text);
+        q.note = text;
+        this.pushQuestionViewUpdate(ctx.requestId, tracked);
     }
     /**
      * Update a pending approval's view (out-of-order item/started arrives late).
@@ -176,20 +271,6 @@ export class ApprovalCoordinator {
         }
         return count;
     }
-    /**
-     * Get the head (oldest pending) approval, or undefined.
-     */
-    head() {
-        let oldest;
-        let oldestTime = Infinity;
-        for (const [, tracked] of this.approvals) {
-            if (tracked.state === 'pending' && tracked.createdAt < oldestTime) {
-                oldest = tracked;
-                oldestTime = tracked.createdAt;
-            }
-        }
-        return oldest;
-    }
     // =========================================================================
     // Internal
     // =========================================================================
@@ -199,6 +280,103 @@ export class ApprovalCoordinator {
             tracked.timeoutTimer = null;
         }
     }
+    /** nonce 去重：同一 nonce 只允许生效一次（防连点/飞书重投递）。 */
+    assertFreshNonce(requestId, nonce) {
+        if (nonce === undefined)
+            return;
+        const seen = this.submittedNonces.get(requestId) ?? new Set();
+        if (seen.has(nonce)) {
+            throw new Error(`Approval request ${requestId} already submitted (duplicate nonce)`);
+        }
+        seen.add(nonce);
+        this.submittedNonces.set(requestId, seen);
+    }
+    /** 记录问题答案到 tracked.answers（懒初始化 Map）。 */
+    recordAnswer(tracked, questionIndex, values) {
+        tracked.answers ??= new Map();
+        tracked.answers.set(questionIndex, values);
+    }
+    getPendingQuestion(requestId) {
+        const tracked = this.approvals.get(requestId);
+        if (!tracked) {
+            throw new Error(`Approval request ${requestId} not found`);
+        }
+        if (tracked.kind !== 'question') {
+            throw new Error(`Approval request ${requestId} is not a question request`);
+        }
+        if (tracked.state !== 'pending') {
+            throw new Error(`Approval request ${requestId} is no longer pending`);
+        }
+        return tracked;
+    }
+    allQuestionsAnswered(tracked) {
+        const questions = tracked.view.questions ?? [];
+        if (questions.length === 0)
+            return false;
+        for (let i = 0; i < questions.length; i++) {
+            const answered = (tracked.answers?.get(i)?.length ?? 0) > 0;
+            if (!answered)
+                return false;
+        }
+        return true;
+    }
+    /** 推送 question 卡片视图更新（选项勾选状态变化）。 */
+    pushQuestionViewUpdate(requestId, tracked) {
+        void this.pushToCard([
+            {
+                type: 'approval_view_updated',
+                requestId,
+                view: tracked.view,
+                timestamp: new Date().toISOString(),
+            },
+        ]).catch((err) => {
+            getLogger().warn(`[approval-coordinator] question view update failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    /** 全部问题已答：构建 answers 并提交（非空校验 + 原子状态迁移）。 */
+    async respondQuestionAnswers(tracked, ctx) {
+        this.assertFreshNonce(ctx.requestId, ctx.nonce);
+        if (tracked.state !== 'pending') {
+            throw new Error(`Approval request ${ctx.requestId} is no longer pending (state=${tracked.state})`);
+        }
+        const questions = tracked.view.questions ?? [];
+        const answers = {};
+        const notes = {};
+        for (let i = 0; i < questions.length; i++) {
+            const selected = tracked.answers?.get(i) ?? [];
+            answers[questions[i].question] = questions[i].multiSelect ? selected : selected[0];
+            const note = tracked.notes?.get(i);
+            if (note)
+                notes[questions[i].question] = note;
+        }
+        tracked.state = 'submitting';
+        this.clearTimer(tracked);
+        try {
+            await this.responder(ctx.requestId, {
+                action: 'answer',
+                answers,
+                ...(Object.keys(notes).length > 0 ? { notes } : {}),
+            });
+            tracked.state = 'resolved';
+            this.pushResolved(ctx.requestId);
+        }
+        catch {
+            tracked.state = 'failed';
+        }
+    }
+    /** 推 approval_resolved 到卡片（移除审批区；幂等，失败仅记日志）。 */
+    pushResolved(requestId) {
+        void this.pushToCard([
+            {
+                type: 'approval_resolved',
+                requestId,
+                outcome: 'resolved',
+                timestamp: new Date().toISOString(),
+            },
+        ]).catch((err) => {
+            getLogger().warn(`[approval-coordinator] resolved card event failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
     expireApproval(requestId) {
         const tracked = this.approvals.get(requestId);
         if (!tracked || tracked.state !== 'pending')
@@ -231,6 +409,10 @@ export class ApprovalCoordinator {
                 return 'acceptForSession';
             case 'accept_with_execpolicy_amendment':
                 return 'acceptWithExecpolicyAmendment';
+            case 'accept_all':
+                return 'acceptAll';
+            case 'answer':
+                return 'answer';
             case 'decline':
                 return 'decline';
             case 'cancel':
@@ -247,6 +429,8 @@ export function decisionToApprovalAction(decision) {
             return { action: 'accept_for_session' };
         case 'acceptWithExecpolicyAmendment':
             return { action: 'accept_with_execpolicy_amendment' };
+        case 'acceptAll':
+            return { action: 'accept_all' };
         case 'decline':
             return { action: 'decline' };
         case 'cancel':