lark-remote 0.4.4 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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
+
+### 修复
+
+- **消息不再漂移到新会话**：紧跟在文字消息之后点击「新会话」「切换工作目录」「继续会话」等会变更会话的卡片按钮时，此前消息可能落到新会话里执行。现在这类卡片动作会先等消息合并窗口落地（消息仍绑定旧会话/旧目录），再执行动作；同时入队时刻固定会话代际，堵住「已开新会话后又被旧消息把旧会话复活」的漏判
+
+### 变更
+
+- **内部清理重构**：删除生产死代码与重复测试脚手架，统一内部命名，无行为变化
+
 ## [0.4.4] - 2026-10-04
 
 ### 修复

package/dist/binder.d.ts

@@ -8,7 +8,7 @@ type BindDecision = {
     kind: 'bind_success';
 };
 /**
- * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 userId 可用。
  *
  * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
@@ -17,30 +17,31 @@ type BindDecision = {
  *
  * 状态机：
  * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
- * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ * - 已绑定：仅 userId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
- * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ * cardAction 同样校验 operator.openId（飞书 SDK 字段，值即 userId）=== bound.userId；
+ * 未绑定也视为非 owner。
  */
 export declare class OwnerBinder {
     private readonly store;
     private rejectedTotal;
     constructor(store: StartupContactStore);
     isBound(): boolean;
-    /** 已绑定的 owner openId；未绑定时 undefined。 */
-    boundOpenId(): string | undefined;
-    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
-    isOwner(openId: string): boolean;
+    /** 已绑定的 owner userId；未绑定时 undefined。 */
+    boundUserId(): string | undefined;
+    /** 用户是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(userId: string): boolean;
     /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
     get rejectedCount(): number;
     /**
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意消息均可）
      */
-    classify(senderId: string, content: string, chatId: string): BindDecision;
+    authorize(userId: string, chatId: string): BindDecision;
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
-    recordRejectedCardAction(openId: string): void;
+    recordRejectedCardAction(userId: string): void;
 }
 /**
  * 控制台绑定引导文案（首次未绑定时输出到 stderr；守护模式下被 watchdog

package/dist/binder.js

@@ -1,6 +1,6 @@
 import { getLogger } from './logger/index.js';
 /**
- * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 openId 可用。
+ * Owner 绑定器：首次私聊发送任意消息完成"认领"，此后仅该 userId 可用。
  *
  * 设计依据：lark-remote 进程持有用户本机完整权限，唯一合法主体是 owner 本人。
  * 飞书自建应用的私聊入口本身就是 owner 掌控的（应用只有 owner 能看到/使用，
@@ -9,9 +9,10 @@ import { getLogger } from './logger/index.js';
  *
  * 状态机：
  * - 未绑定：第一条私聊消息（任意内容）即完成绑定 -> 写入 startup-contact.json。
- * - 已绑定：仅 senderId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
+ * - 已绑定：仅 userId === bound.userId 的消息放行；其余静默丢弃（计数 + debug）。
  *
- * cardAction 同样校验 operator.openId === bound.userId（未绑定也视为非 owner）。
+ * cardAction 同样校验 operator.openId（飞书 SDK 字段，值即 userId）=== bound.userId；
+ * 未绑定也视为非 owner。
  */
 export class OwnerBinder {
     store;
@@ -22,14 +23,14 @@ export class OwnerBinder {
     isBound() {
         return this.store.getContact() !== undefined;
     }
-    /** 已绑定的 owner openId；未绑定时 undefined。 */
-    boundOpenId() {
+    /** 已绑定的 owner userId；未绑定时 undefined。 */
+    boundUserId() {
         return this.store.getContact()?.userId;
     }
-    /** 卡片操作者是否为已绑定的 owner（未绑定返回 false）。 */
-    isOwner(openId) {
+    /** 用户是否为已绑定的 owner（未绑定返回 false）。 */
+    isOwner(userId) {
         const bound = this.store.getContact()?.userId;
-        return bound !== undefined && bound === openId;
+        return bound !== undefined && bound === userId;
     }
     /** 累计被拒（非 owner）消息/卡片数，用于 DoS 可观测。 */
     get rejectedCount() {
@@ -39,26 +40,26 @@ export class OwnerBinder {
      * 对入站私聊消息做绑定/授权判定，含副作用：
      * - `owner`：放行，调用方继续正常处理
      * - `rejected`：已绑定但非 owner，静默丢弃（计数 + debug）
-     * - `bind_success`：未绑定收到首条消息，写入绑定（任意内容均可）
+     * - `bind_success`：未绑定收到首条消息，写入绑定（任意消息均可）
      */
-    classify(senderId, content, chatId) {
+    authorize(userId, chatId) {
         const bound = this.store.getContact();
         if (bound) {
-            if (senderId === bound.userId)
+            if (userId === bound.userId)
                 return { kind: 'owner' };
             this.rejectedTotal++;
-            getLogger().debug(`[binder] rejected message from ${senderId} (total rejected=${this.rejectedCount})`);
+            getLogger().debug(`[binder] rejected message from ${userId} (total rejected=${this.rejectedCount})`);
             return { kind: 'rejected' };
         }
         // 未绑定：任意内容即绑定（首条消息完成认领）
-        this.store.save({ chatId, userId: senderId });
-        getLogger().info(`[binder] owner bound: openId=${senderId} chatId=${chatId}`);
+        this.store.save({ chatId, userId });
+        getLogger().info(`[binder] owner bound: userId=${userId} chatId=${chatId}`);
         return { kind: 'bind_success' };
     }
     /** 卡片操作被拒时计数（与消息路径共用计数器）。 */
-    recordRejectedCardAction(openId) {
+    recordRejectedCardAction(userId) {
         this.rejectedTotal++;
-        getLogger().debug(`[binder] rejected card action from ${openId} (total rejected=${this.rejectedCount})`);
+        getLogger().debug(`[binder] rejected card action from ${userId} (total rejected=${this.rejectedCount})`);
     }
 }
 /**

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.d.ts

@@ -1,38 +1,12 @@
 import { type AppConfig } from '../config/index.js';
 import type { MediaOutcome } from '../inbound/turn.js';
-import type { InboundResourceKind, InboundMediaItem, InboundMediaPayload } from '../connector/index.js';
+import type { InboundMediaPayload } from '../connector/index.js';
 export interface InboundMediaDeps {
     /** 解析用户 cwd（bridge.resolveCwd 注入，统一三份复制点）。 */
     resolveCwd: (userId: string) => string | undefined;
     /** 读取当前配置（活引用，随 /config 保存更新，避免启动快照过期）。 */
     getConfig: () => AppConfig;
 }
-/**
- * 文件名 sanitize：
- * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
- * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
- */
-export declare function sanitizeFileName(name: string): string;
-/**
- * 资源扩展名（图片/视频/语音）：优先 MIME 映射，未知时按魔数兜底；
- * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
- */
-export declare function extensionFor(_kind: InboundResourceKind, mimeType: string | undefined, head: Buffer): string | undefined;
-/**
- * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
- * 极罕见情况（扩展名本身超限）直接截断全名。
- */
-export declare function limitFileNameLength(name: string, maxBytes?: number): string;
-/**
- * 生成落盘文件名：
- * - image：`image_<HHmmss>_<n>.<ext>`（ext 按 MIME/魔数）；
- * - 其它有原名的资源（file/video/audio/sticker）：保留原名（已 sanitize）；
- * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
- *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
- */
-export declare function buildFileName(item: InboundMediaItem, index: number, receivedAt: Date): string;
-/** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
-export declare function uniqueTargetPath(dir: string, fileName: string): string;
 export declare class InboundMediaHandler {
     private readonly deps;
     constructor(deps: InboundMediaDeps);

package/dist/bridge/inbound-media.js

@@ -3,7 +3,8 @@ import path from 'node:path';
 import { DEFAULT_INBOUND_MEDIA_DIR_NAME } from '../config/index.js';
 import { atomicMoveFile } from '../persistence/atomic-write.js';
 import { getLogger } from '../logger/index.js';
-import { silentlyUnlink } from '../common/fs.js';
+import { bestEffortUnlink } from '../common/fs.js';
+import { truncateUtf8 } from '../common/truncate.js';
 /**
  * 入站媒体落盘。
  *
@@ -52,43 +53,46 @@ function hasControlChar(s) {
     return false;
 }
 /** 子目录时间戳：YYYYMMDDHHmm（本地时间，精确到分钟）。 */
-function timeStampDir(d) {
+function timestampDir(d) {
     return (`${d.getFullYear()}${pad2(d.getMonth() + 1)}${pad2(d.getDate())}` +
         `${pad2(d.getHours())}${pad2(d.getMinutes())}`);
 }
 /** 文件名时间戳：HHmmss（本地时间）。 */
-function timeStampHms(d) {
+function timestampHms(d) {
     return `${pad2(d.getHours())}${pad2(d.getMinutes())}${pad2(d.getSeconds())}`;
 }
 /**
  * 文件名 sanitize：
- * path.basename 剥离目录（防 `../` 穿越），再替换控制字符与路径分隔符；
+ * path.basename 剥离目录（防 `../` 穿越），再替换控制字符、路径分隔符与
+ * win32 非法字符（`<>:"|?*`，NTFS/Win32 API 拒绝，落盘直接 EPERM/EINVAL），
+ * 并剥掉尾部的点与空格（win32 会静默剥离它们，导致落盘名 ≠ originalName）；
  * 空名 / `.` / `..` 视为无效（返回空串由调用方生成兜底名）。
  */
-export function sanitizeFileName(name) {
+function sanitizeFileName(name) {
     const base = path.basename(name).trim();
     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 映射，未知时按魔数兜底；
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
-export function extensionFor(_kind, mimeType, head) {
+function extensionFor(_kind, mimeType, head) {
     const normalized = mimeType?.split(';')[0]?.trim().toLowerCase();
     if (normalized && MIME_TO_EXT[normalized])
         return MIME_TO_EXT[normalized];
@@ -137,13 +141,11 @@ export function extensionFor(_kind, mimeType, head) {
     }
     return undefined;
 }
-/** 按 UTF-8 字节数截断字符串（避免截在多字节字符中间）。 */
-import { truncateUtf8 } from '../common/truncate.js';
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。
  */
-export function limitFileNameLength(name, maxBytes = MAX_FILE_NAME_BYTES) {
+function limitFileNameLength(name, maxBytes = MAX_FILE_NAME_BYTES) {
     if (Buffer.byteLength(name, 'utf8') <= maxBytes)
         return name;
     const ext = path.extname(name);
@@ -172,15 +174,15 @@ function readFileHead(filePath, maxBytes = MAGIC_HEAD_BYTES) {
  * - 无原名的资源：`<kind>_<HHmmss>_<n>.<ext>`，ext 按 MIME/魔数
  *   （旧实现落成无扩展名的 `file_HHmmss_n`，mp4/opus/gif 都不可识别）。
  */
-export function buildFileName(item, index, receivedAt) {
+function buildFileName(item, index, receivedAt) {
     const original = item.fileName ? limitFileNameLength(sanitizeFileName(item.fileName)) : '';
     if (item.kind !== 'image' && original)
         return original;
     const ext = extensionFor(item.kind, item.mimeType, readFileHead(item.tempPath));
-    return `${item.kind}_${timeStampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
+    return `${item.kind}_${timestampHms(receivedAt)}_${index}${ext ? `.${ext}` : ''}`;
 }
 /** 同名冲突自动加序号（name-1.ext、name-2.ext…），不覆盖已有文件。 */
-export function uniqueTargetPath(dir, fileName) {
+function uniqueTargetPath(dir, fileName) {
     const ext = path.extname(fileName);
     const stem = fileName.slice(0, fileName.length - ext.length);
     let candidate = path.join(dir, fileName);
@@ -216,7 +218,7 @@ export class InboundMediaHandler {
             };
         }
         const receivedAt = new Date();
-        const dir = path.join(cwd, this.safeDirName(), timeStampDir(receivedAt));
+        const dir = path.join(cwd, this.safeDirName(), timestampDir(receivedAt));
         try {
             fs.mkdirSync(dir, { recursive: true });
         }
@@ -254,7 +256,7 @@ export class InboundMediaHandler {
                 });
             }
             catch (err) {
-                silentlyUnlink(item.tempPath);
+                bestEffortUnlink(item.tempPath);
                 const label = item.fileName
                     ? sanitizeFileName(item.fileName) || item.fileName
                     : `第 ${i + 1} 个`;
@@ -287,7 +289,7 @@ export class InboundMediaHandler {
     /** 清理未被移动的临时文件（无 cwd / 目录创建失败等提前返回路径）。 */
     cleanupTemps(payload) {
         for (const item of payload.media) {
-            silentlyUnlink(item.tempPath);
+            bestEffortUnlink(item.tempPath);
         }
     }
     resolveCwd(userId) {