lark-remote 0.4.5 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.5.1] - 2026-10-09
+
+### 修复
+
+- **旧卡片上的 Compact 按钮点下去不再报「该任务已结束或不属于当前会话」**：Compact 按钮只带本轮 run 的标识，此前按「每个工作目录最新一条 run」反查会话，而 compact 动作走串行队列——排队期间后续 run 收尾会覆盖那一个槽位，旧卡片于是必然失效。现在每条 run 收尾时按自己的标识记下会话与 agent，按钮自证身份，排队多久都不失效；Compact 也改为按该 run 自己的目录反查，中途切过目录不会压错会话
+- **同一会话的多条排队卡片不再互相顶掉**：队列条目此前复用飞书卡片的消息 id 当身份，同一会话里多条卡片撞同一个 key，先入队的那条被后面的覆盖、状态更新串到别的卡片上。改为每次入队铸造独立身份
+- **排队卡片会说清「在等谁」**：Compact 与普通消息共用同一条串行队列，Compact 占着执行位时新消息卡片仍写「位置: 第 1 位 / 前面还有: 0 条」，看着像马上就能轮到自己。现在没有等待中的消息时头部改为「等待当前任务结束」、正文写明正在执行的是 Compact 并收起位置行；占用者是 Compact 时「⚡ 立即执行」在渲染层置灰、执行层再加一道守卫，「❌ 撤销」保持可用
+- **codex 多 agent 会话不再把会话指针写坏**：codex app-server 会把子 agent 的开轮通知一起推过来，此前不判断归属，子线程的事件覆盖了本轮的线程标识，顶层会话指针被写成子线程标识——该值在会话索引里不是键，之后恢复会话报 `cannot resume an unloaded multi-agent v2 sub-agent`，`/restart` 也救不回来。现在通知按线程归属过滤；审批结算仍按请求标识走，子 agent 的审批照常可以回答
+- **带 `dsh` 的卡片不再静默退回默认 agent**：agent 名单此前被手抄成多份并发生漂移，收敛为单一来源、校验由该名单派生，消除「用错 reader → 未找到 session」的静默降级
+
+### 变更
+
+- **消除两处宿主环境相关的测试假红**：宿主带上本机没有的 locale（macOS 常见的 `LC_ALL=C.UTF-8`）时，bash 每次启动都往 stderr 打 setlocale 警告，让输出断言随机变红，测试 setup 阶段现在剔掉该变量（保留 UTF-8 解析所需项）；JSON-RPC 退出计时用例的计时起点从进程启动改到收到 `initialize` 应答，慢速 Windows runner 上不再因启动耗时超过阈值而误红
+- **英文架构文档补齐**：`docs/en/architecture/design.md` 增补与中文侧对应的五个章节，英中两侧不再不对称
+- **注释与用例名清理**：延续上一版的清理，去掉剩余指向未发布文档的引用与评审编号，并修正清理过程中留下的残句。无行为变化
+
+## [0.5.0] - 2026-10-07
+
+### 新增
+
+- **CI 增加 Windows 全量验证**：新增 `windows-latest` job（install → typecheck → test → build → `--version`/`--help` 冒烟）。此前只有 ubuntu job，被平台门控跳过的用例在 CI 里是盲区，win32 独有回归只能靠本地发现
+
+### 修复
+
+- **一次发多图/多文件不再只保存 1 个**：飞书客户端「一次选多图/多文件」会背靠背秒发成多条独立消息，SDK 层 600ms 去抖把它们合并成一条——只保留最后一条的 `messageId`，却把多条消息的附件求并集。下载侧于是拿同一个 `messageId` 去下所有文件，除最后一条外全部报 234003（HTTP 400）。现关掉 SDK 这层合批（`chatQueue` 串行与卡片动作通道保留），合批交回项目自身的合并窗口
+- **Windows 上会话偶尔「消失」**：按工作目录查会话时，大小写/分隔符/尾斜杠的归一不统一，`C:\Work` 与 `c:/work/` 被当成两个目录，`/resume` 列表会漏列。现统一走同一套判等键
+- **Windows 上含 `<>:"|?*` 或尾点的文件名落盘失败**：入站附件名现在会剥掉 win32 非法字符与尾部点/空格（win32 会静默剥离它们，导致落盘名与记录名不一致）
+- **Windows 上可能误杀其他工作目录的 agent**：pid 文件名此前只按消毒后的目录名区分，`/w/a+b` 与 `/w/a_b` 会撞同一个文件，启动时的孤儿回收可能杀掉对方工作目录里存活的 agent。现后缀掺入原始目录的哈希
+- **`~` 开头的配置目录在 Windows 上不展开**：`~\` 形式此前不识别
+
+### 变更
+
+- **注释与测试命名清理**：去掉源码、测试注释与用例名中指向未发布内部文档的引用（评审条目号、场景号、轮次号、文件名前缀），让公开仓库里的引用都能落地。无行为变化
+
 ## [0.4.5] - 2026-10-07
 
 ### 修复

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

@@ -95,7 +95,7 @@ export declare class ApprovalCoordinator {
         nonce?: string;
     }): Promise<void>;
     /**
-     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * AskUserQuestion 自定义答案（Other）：自由文本直接作为该
      * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
      */
     answerCustom(action: {

package/dist/bridge/approval-coordinator.js

@@ -180,7 +180,7 @@ export class ApprovalCoordinator {
         }
         const selected = new Set(q.selected ?? []);
         if (q.multiSelect) {
-            // review P2-1：多选切换按钮同一 nonce 重复投递（双击/飞书重投递）只应
+            // 多选切换按钮同一 nonce 重复投递（双击/飞书重投递）只应
             // toggle 一次，否则勾选会被二次 toggle 抵消。单选用例的重复防护在
             // respondQuestionAnswers（提交即幂等，选中是 set 语义）。
             this.assertFreshNonce(ctx.requestId, ctx.nonce);
@@ -226,7 +226,7 @@ export class ApprovalCoordinator {
         }
     }
     /**
-     * AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接作为该
+     * AskUserQuestion 自定义答案（Other）：自由文本直接作为该
      * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
      */
     async answerCustom(action, ctx) {
@@ -451,7 +451,7 @@ export class ApprovalCoordinator {
         void this.responder(requestId, { action: 'cancel' }).catch((err) => {
             getLogger().warn(`[approval-coordinator] expiry cancel failed requestId=${requestId}: ${err instanceof Error ? err.message : String(err)}`);
             // 响应失败不是「正常过期」：状态升级为 failed，避免误判为已正常通知
-            // server（spec R1：responder 抛错时状态置 failed）。
+            // server（spec responder 抛错时状态置 failed）。
             tracked.state = 'failed';
             // 兜底：cancel 未能送达时主动中断 turn，避免 server 无限等待审批响应。
             void this.interruptTurn().catch((interruptErr) => {

package/dist/bridge/inbound-media.js

@@ -63,7 +63,9 @@ function timestampHms(d) {
 }
 /**
  * 文件名 sanitize：
- * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
+ * path.basename 剥离目录（防 `../` 穿越），再替换控制字符、路径分隔符与
+ * win32 非法字符（`<>:"|?*`，NTFS/Win32 API 拒绝，落盘直接 EPERM/EINVAL），
+ * 并剥掉尾部的点与空格（win32 会静默剥离它们，导致落盘名 ≠ originalName）；
  * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
  */
 function sanitizeFileName(name) {
@@ -71,19 +73,20 @@ function sanitizeFileName(name) {
     const chars = [];
     for (const ch of base) {
         const code = ch.charCodeAt(0);
-        // 控制字符与路径分隔符一律替换为下划线（no-control-regex 不允许字面
-        // 控制字符转义出现在正则里，逐字符判断语义等价且无 lint 冲突）。
-        if (code <= 0x1f || code === 0x7f || ch === '/' || ch === '\\') {
+        // 控制字符、路径分隔符与 win32 非法字符一律替换为下划线（no-control-regex
+        // 不允许字面控制字符转义出现在正则里，逐字符判断语义等价且无 lint 冲突）。
+        if (code <= 0x1f || code === 0x7f || '/\\<>:"|?*'.includes(ch)) {
             chars.push('_');
         }
         else {
             chars.push(ch);
         }
     }
-    const sanitized = chars.join('');
-    if (sanitized === '' || sanitized === '.' || sanitized === '..')
+    // 尾部的点与空格：win32 落盘时被静默剥离，提前剥掉保证记录名与磁盘名一致
+    const trimmedEnd = chars.join('').replace(/[. ]+$/, '');
+    if (trimmedEnd === '' || trimmedEnd === '.' || trimmedEnd === '..')
         return '';
-    return sanitized;
+    return trimmedEnd;
 }
 /**
  * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；

package/dist/bridge/index.d.ts

@@ -4,8 +4,8 @@ import type { SessionReaderRegistry, SessionStore } from '../session/index.js';
 import type { AppConfig } from '../config/index.js';
 import { type RunCardChannel } from '../card/run-card-session.js';
 import type { RunTerminal } from '../card/run-state.js';
-import type { AgentKind } from '../runner/types.js';
-import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding } from './queue-manager.js';
+import { type AgentKind } from '../runner/types.js';
+import { QueueManager, type QueuedTask, type EnqueueOptions, type AgentBinding, type ExecutingInfo } from './queue-manager.js';
 import type { InboundMediaPayload } from '../connector/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
 /**
@@ -36,7 +36,7 @@ export interface CommandContext {
     /**
      * 本轮（装配窗口）全部入站 messageId，`messageId` 是其中最后一条。
      * 只有走入站装配器的路径会填；卡片动作等单消息路径留空，收尾退化为只处理
-     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤（§B8）。
+     * `messageId`。缺它会导致合并轮次里先到的消息挂着 Typing 不撤。
      */
     turnMessageIds?: string[];
 }
@@ -127,7 +127,7 @@ export declare class Bridge {
      */
     private runners;
     /**
-     * Runner 槽位在「活跃运行期间配置变更」时被标 stale（CC-06/P1）：clearRunners() 对
+     * Runner 槽位在「活跃运行期间配置变更」时被标 stale：clearRunners() 对
      * 活跃 cwd 只标 stale、不立即 evict（避免误杀长驻连接），当前 run 结束后由
      * finalizeRun 安全 evict+dispose，下一轮 getRunner 创建新配置的 runner。
      * key 为 `${cwd}\u0000${agentKind}`。
@@ -141,10 +141,16 @@ export declare class Bridge {
     /** Approval coordinators keyed by runId. */
     private approvalCoordinators;
     /**
-     * 最近一次已完成的、runner 有 runCompact 的 run（按 cwd）。run 结束后
-     * activeRuns 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     * 最近若干次已完成的、runner 有 runCompact 的 run（cwd → runId → 记录）。
+     * run 结束后 activeRuns 已清空，而终态卡上的 Compact 按钮只带 runId，
+     * 需要它反查 sessionId + agentKind。
+     *
+     * 为什么按 runId 存而不是「每 cwd 只留最新一条」：compact 卡片动作走串行
+     * 队列（会被正在跑的 run 挡住），点击到执行之间可能夹着别的 run 收尾。
+     * 单槽会被覆盖 —— 旧卡片的压缩必然报「该任务已结束或不属于当前会话」，
+     * 与 session 是否还在、能否压缩无关（2026-10-08 线上缺陷）。
      */
-    private lastCompactableRun;
+    private compactableRuns;
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -174,17 +180,17 @@ export declare class Bridge {
     syncActiveApprovalModes(): void;
     /** Per-agent approval-mode settings snapshot from the current config. */
     private approvalModeSettingsFor;
-    /** Get the current runner for a cwd. Used by router for agent-specific commands (P3.2). */
+    /** Get the current runner for a cwd. Used by router for agent-specific commands (.2). */
     getCurrentRunner(cwd: string): AgentRunner;
     /**
      * Whether the runner for the given agent kind has runCompact capability.
-     * Used by router for compact button gating (design doc §6.2-2: duck-typing
+     * Used by router for compact button gating (duck-typing
      * instead of hardcoding agentKind === 'codex').
      */
     hasRunCompact(cwd: string, kind?: AgentKind): boolean;
     /** 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
-     *  唯一捕获点：排队消息在 T0 把 agent+session 钉进 AgentBinding，随任务闭包带到 T1
-     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移（方案 D4）。 */
+     *  唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
+     *  执行时刻，避免 /new、/config 在排队期间改写 live 状态导致语义漂移。 */
     currentBinding(userId: string): AgentBinding;
     /**
      * Clear all cached runner instances. Call after config changes that affect runner config.
@@ -192,7 +198,7 @@ export declare class Bridge {
     clearRunners(): void;
     /**
      * Evict a (cwd, agentKind) runner cache slot. Unregisters the runner from the
-     * process-level exit dispatcher first (P1-1: without removal the singleton
+     * process-level exit dispatcher first (without removal the singleton
      * Set<Runner> retains every historical runner instance, so memory still grows
      * with run count), then deletes the slot. Every runner-discarding path
      * (clearRunners / finalizeRun / interruptCurrentRun) must go through this.
@@ -233,6 +239,11 @@ export declare class Bridge {
         tasksAhead: number;
         isRunning: boolean;
     };
+    /**
+     * lane 当前占用者的展示信息（排队卡与「立即执行」守卫共用）。
+     * 典型用途：占用者是 Compact 时拒绝 queue.immediate，避免中断压缩。
+     */
+    getQueueExecutingInfo(cwd: string): ExecutingInfo | undefined;
     /** Remove a task from the queue by messageId. Returns true if found and removed. */
     removeFromQueue(cwd: string, messageId: string): boolean;
     /**
@@ -323,6 +334,17 @@ export declare class Bridge {
      * Returns true if the in-place update succeeded, false if it fell back.
      */
     updateCardInPlace(card: object, ctx: CommandContext): Promise<boolean>;
+    /**
+     * Best-effort in-place refresh of a KNOWN card (no fallback send).
+     *
+     * `updateCardInPlace` falls back to sending a new card when the PATCH fails,
+     * which is right for the card the user just clicked (a silent failure would
+     * leave the click with no feedback) but wrong when refreshing *sibling*
+     * cards: an expired/withdrawn card would spawn a duplicate card on every
+     * edit. Callers that fan out to several cards use this instead and drop the
+     * card id from their set on `false`.
+     */
+    patchCard(messageId: string, card: object): Promise<boolean>;
     /** Send a file to the user via Feishu. */
     sendFile(filePath: string, ctx: CommandContext): Promise<void>;
     /**
@@ -354,7 +376,7 @@ export declare class Bridge {
      */
     private createRunSession;
     /**
-     * §9.12 空闲看门狗：单 interval + 截止时间判定（P2-1），普通 run 与 compact
+     * §9.12 空闲看门狗：单 interval + 截止时间判定，普通 run 与 compact
      * 共用同一套兜底。事件到达只 `touch()` 刷新时间戳（无 timer 操作）；静默超过
      * `idleTimeoutMs` 才 finish('idle_timeout') + runner.stop()，让该工作区的串行
      * 队列继续推进（否则一个挂死的 run 永久堵住后续消息）。
@@ -443,7 +465,7 @@ export declare class Bridge {
         nonce: string;
     }): Promise<void>;
     /**
-     * Claude AskUserQuestion 自定义答案（Other，review P3-4）：自由文本直接
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
      * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
      */
     handleApprovalAnswerCustom(opts: {
@@ -465,11 +487,27 @@ export declare class Bridge {
         text: string;
         nonce: string;
     }): Promise<void>;
+    /**
+     * 记下一次「可压缩 run」：终态卡上的 Compact 按钮点击时据此反查
+     * sessionId + agentKind。runId 是按钮自带的唯一键，同 cwd 内唯一。
+     * 超出上限按插入序淘汰最旧的一条（Map 保持插入序；重复写同一 runId
+     * 先 delete 再 set 以刷新位置）。
+     */
+    private recordCompactableRun;
+    /**
+     * 按 runId 反查可压缩 run 记录（跨 cwd 扫描）。
+     *
+     * 为什么不带 cwd 过滤：按钮属于「那一次 run」，与用户此刻在哪个工作目录、
+     * 排队期间有没有 /cd 无关。`/stop` 的 interruptCurrentRun 同样是全局按 runId
+     * 找（从不查当前 cwd），compact 与它保持一致。用当前 cwd 收窄会让「切了工作区
+     * 再点旧卡片」和「排队期间 /cd」两种情况误报「该任务已结束或不属于当前会话」。
+     */
+    private findCompactableRun;
     /**
      * Handle compact card action — trigger a compaction request for any
-     * runCompact-capable runner（codex/kimi/opencode/pi/claude，按
-     * lastCompactableRun 记录的 agentKind 路由）。Validates the run exists
-     * and is in a terminal state, then calls the runner's runCompact().
+     * runCompact-capable runner（codex/kimi/opencode/pi/claude）。按钮带的是
+     * 那次 run 的 runId，据此反查该 run 实际使用的 sessionId + agentKind
+     * + cwd（compactableRuns，按 runId 记录），再调 runner 的 runCompact()。
      */
     handleCompactAction(value: {
         runId?: string;