lark-remote 0.4.5 → 0.5.0

package/dist/clone.d.ts

@@ -25,7 +25,8 @@ import { type QRCodeInfo, type RegisterAppResult } from '@larksuite/channel';
 type CloneState = 'idle' | 'awaiting_scan' | 'finalizing';
 /**
  * 校验用户指定的分身名字：路径分隔符、以 . 开头、尾点/尾空格（win32 会静默
- * 吞掉）、win32 保留设备名一律拒绝。
+ * 吞掉）、win32 非法字符（`<>:"|?*`，NTFS/Win32 API 拒绝）、win32 保留设备名
+ * 一律拒绝。
  */
 export declare function isValidCloneName(name: string): boolean;
 /** 随机后缀：2 位数字 + 2 位小写字母/数字，如 `37ab`。 */
@@ -126,8 +127,9 @@ export declare class CloneSession {
     private readOldOwnerId;
     /**
      * 写配置失败时清理半成品目录。守卫：只删内容全部是本次产物
-     * （config.yaml / startup-contact.json 及其 .tmp）的目录，混入其他
-     * 文件时保留现场不动。
+     * （config.yaml / startup-contact.json 及其 tmp）的目录，混入其他
+     * 文件时保留现场不动。tmp 形态两种都认：atomic-write 现行命名
+     * （.{name}.tmp-{pid}-{ts}-{rand}）与旧版固定 `.tmp`（升级瞬间崩溃的残留）。
      */
     private cleanupPartialDir;
 }

package/dist/clone.js

@@ -24,13 +24,16 @@ const WIN_RESERVED_NAMES = new Set([
 ]);
 /**
  * 校验用户指定的分身名字：路径分隔符、以 . 开头、尾点/尾空格（win32 会静默
- * 吞掉）、win32 保留设备名一律拒绝。
+ * 吞掉）、win32 非法字符（`<>:"|?*`，NTFS/Win32 API 拒绝）、win32 保留设备名
+ * 一律拒绝。
  */
 export function isValidCloneName(name) {
     if (!name || name.includes('/') || name.includes('\\') || name.startsWith('.'))
         return false;
     if (/[\s.]$/.test(name))
         return false;
+    if (/[<>:"|?*]/.test(name))
+        return false;
     if (WIN_RESERVED_NAMES.has(name.toLowerCase()))
         return false;
     return true;
@@ -393,12 +396,13 @@ export class CloneSession {
     }
     /**
      * 写配置失败时清理半成品目录。守卫：只删内容全部是本次产物
-     * （config.yaml / startup-contact.json 及其 .tmp）的目录，混入其他
-     * 文件时保留现场不动。
+     * （config.yaml / startup-contact.json 及其 tmp）的目录，混入其他
+     * 文件时保留现场不动。tmp 形态两种都认：atomic-write 现行命名
+     * （.{name}.tmp-{pid}-{ts}-{rand}）与旧版固定 `.tmp`（升级瞬间崩溃的残留）。
      */
     cleanupPartialDir(targetDir) {
         try {
-            const allowed = /^(config\.yaml|startup-contact\.json)(\.tmp)?$/;
+            const allowed = /^(config\.yaml|startup-contact\.json)(\.tmp)?$|^\.(config\.yaml|startup-contact\.json)\.tmp-\d+-\d+-[a-z0-9]+$/;
             const entries = fs.readdirSync(targetDir);
             if (!entries.every((e) => allowed.test(e))) {
                 getLogger().warn(`[clone] target dir has foreign entries, kept: ${targetDir}`);

package/dist/common/truncate.d.ts

@@ -11,7 +11,7 @@
 export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\uFF09";
 /**
  * Max byte budget for a single session `tool_result` event's content when
- * replaying an opencode session (L2 pre-fold). Pre-folding here bounds the
+ * replaying an opencode session (pre-fold). Pre-folding here bounds the
  * in-memory `events[]` array and the intermediate card JSON so a single
  * pathological tool_result never inflates the replay payload to megabytes.
  */

package/dist/common/truncate.js

@@ -11,7 +11,7 @@
 export const DEFAULT_TRUNCATE_SUFFIX = '…（已截断）';
 /**
  * Max byte budget for a single session `tool_result` event's content when
- * replaying an opencode session (L2 pre-fold). Pre-folding here bounds the
+ * replaying an opencode session (pre-fold). Pre-folding here bounds the
  * in-memory `events[]` array and the intermediate card JSON so a single
  * pathological tool_result never inflates the replay payload to megabytes.
  */
@@ -76,7 +76,7 @@ export function truncate(str, max, options) {
     if (budget <= 0)
         return suffix;
     // Iterate by Unicode codepoint (for...of) so the cut never lands inside a
-    // surrogate pair (P2-31 anchor: must not emit a lone surrogate).
+    // surrogate pair (must not emit a lone surrogate).
     let end = 0;
     for (const ch of s) {
         if (end + ch.length > budget)

package/dist/common/ttl-cache.d.ts

@@ -4,11 +4,11 @@
  * Consolidates the per-reader memory caches that previously hand-rolled the
  * same "mtime/TTL + entry cap" Map pattern (kimi/pi/opencode session readers).
  * Semantics follow the kimi implementation:
- * - TTL is measured from the cache-write time (P1-17 defect 2), not key mtime.
+ * - TTL is measured from the cache-write time (defect 2), not key mtime.
  *   Note: ttlMs = 0 effectively disables caching — `Date.now() - at >= 0` is
  *   always true, so every entry expires immediately.
  * - A hit refreshes recency (LRU); eviction removes the least recently
- *   inserted/used entry past `maxEntries` (P1-17 defect 1: unbounded growth).
+ *   inserted/used entry past `maxEntries` (defect 1: unbounded growth).
  *   The old pi implementation did NOT re-insert on hit (FIFO eviction); the
  *   eviction order for pi therefore changes from FIFO to LRU here.
  */

package/dist/common/ttl-cache.js

@@ -4,11 +4,11 @@
  * Consolidates the per-reader memory caches that previously hand-rolled the
  * same "mtime/TTL + entry cap" Map pattern (kimi/pi/opencode session readers).
  * Semantics follow the kimi implementation:
- * - TTL is measured from the cache-write time (P1-17 defect 2), not key mtime.
+ * - TTL is measured from the cache-write time (defect 2), not key mtime.
  *   Note: ttlMs = 0 effectively disables caching — `Date.now() - at >= 0` is
  *   always true, so every entry expires immediately.
  * - A hit refreshes recency (LRU); eviction removes the least recently
- *   inserted/used entry past `maxEntries` (P1-17 defect 1: unbounded growth).
+ *   inserted/used entry past `maxEntries` (defect 1: unbounded growth).
  *   The old pi implementation did NOT re-insert on hit (FIFO eviction); the
  *   eviction order for pi therefore changes from FIFO to LRU here.
  */

package/dist/config/codex-config.d.ts

@@ -52,32 +52,32 @@ export interface BundledModelInfo {
  * 依据：codex 运行时对"已配置但文件缺失/不可解析"的目录是硬错误
  * （core/src/config/mod.rs load_model_catalog ?），绝不会回退内置目录；因此键存在即
  * catalog 模式，文件缺失自然落入 `codex debug models` 失败路径 → 模型列表回退
- * [currentModel]（P1-1）。
+ * [currentModel]。
  */
 export declare function isCodexCatalogMode(codexHome?: string): boolean;
 /**
  * 单一解析器：把 `codex debug models`（活动目录）或 `--bundled`（内置目录）的原始 JSON
- * 输出解析为模型列表（P2-4 去重）。过滤/排序镜像 codex：
+ * 输出解析为模型列表（去重）。过滤/排序镜像 codex：
  * - show_in_picker = visibility == List（openai_models.rs ModelPreset::from）；
  * - API 模式（lark 用 API key 认证）下 codex filter_by_auth 过滤 supported_in_api=false；
  * - 按 priority 升序（build_available_models）。
- * 档位按目录声明**原样透传**（含 custom/none，P2-5），不按标准枚举过滤、不虚构兜底：
+ * 档位按目录声明**原样透传**（含 custom/none），不按标准枚举过滤、不虚构兜底：
  * 未声明档位 → 空列表（codex with_model 语义：len=0 时用声明 default，都没有则不发
- * effort；P1）。空串档位/空串 default 被过滤（P3-9：codex ReasoningEffort::from_str
+ * effort；）。空串档位/空串 default 被过滤（codex ReasoningEffort::from_str
  * 对 "" 硬错误）。supported_in_api===true 过滤等价于 codex 的 chatgpt_mode ||
- * supported_in_api：本项目以 API-key 模式运行 codex，chatgpt_mode 恒 false（P3-3）。
+ * supported_in_api：本项目以 API-key 模式运行 codex，chatgpt_mode 恒 false。
  */
 export declare function parseCodexModelsOutput(stdout: string): BundledModelInfo[];
 /**
  * 统一目录入口：catalog 模式（model_catalog_json 已声明，含声明退化 ''）跑
  * `debug models`（无 --bundled），否则（未声明或 config.toml 解析失败）跑
- * `debug models --bundled`。注（P3-4）：codex 无参 `debug models` 在
+ * `debug models --bundled`。注：codex 无参 `debug models` 在
  * uses_codex_backend()/has_command_auth() 时会请求远端 /models（models-manager
  * manager.rs / models_endpoint.rs）；本项目以 API-key 模式运行（无 ChatGPT/命令
  * 认证），结果与 bundled 一致，故非 catalog 用 --bundled（已文档化）。
  * 缓存：键含 binary/home/mode/models.json mtime:size + config.toml mtime:size
- * （P3-4/P3-15/P3-5）；成功结果 TTL 1h，失败/空结果短 TTL 负缓存；stat 异常时
- * 指纹为空（P1-1/P3-10）。
+ * 成功结果 TTL 1h，失败/空结果短 TTL 负缓存；stat 异常时
+ * 指纹为空。
  *
  * 同步路径（卡片构建用）：缓存命中直接返回；若有一个后台异步加载
  * （`loadCodexCatalogModelsAsync` / 启动 warm）在途，则不阻塞事件循环、不重复
@@ -117,7 +117,7 @@ export declare function getReasoningEffortOptions(model: string, codexHome?: str
 /**
  * Get default reasoning effort for a model.
  * 未声明/未知模型 → undefined（codex 语义：ModelPreset.default_reasoning_effort
- * unwrap_or(ReasoningEffort::None)，即不传 effort；P3-12）。
+ * unwrap_or(ReasoningEffort::None)，即不传 effort；）。
  */
 export declare function getDefaultReasoningEffort(model: string, codexHome?: string): string | undefined;
 interface LoadCodexConfigOpts {

package/dist/config/codex-config.js

@@ -48,7 +48,7 @@ const FALLBACK_MODELS = ['o3', 'o4-mini', 'gpt-4o', 'gpt-4.1', 'gpt-4.1-mini', '
 const ANTHROPIC_FALLBACK_MODELS = ['claude-sonnet-4-20250514', 'claude-opus-4-20250115'];
 /** Bundled models from codex binary, 1h TTL is enough (only change on binary upgrade) */
 const BUNDLED_CACHE_TTL_MS = 60 * 60 * 1000;
-/** 失败/空结果负缓存 TTL：避免每次卡片构建同步阻塞最长 8s（P3-5） */
+/** 失败/空结果负缓存 TTL：避免每次卡片构建同步阻塞最长 8s */
 const NEGATIVE_CACHE_TTL_MS = 30 * 1000;
 let catalogCache = null;
 /** In-flight async catalog loads, keyed by cache key — dedup concurrent warm ups. */
@@ -58,7 +58,7 @@ const catalogInFlight = new Map();
  * 返回语义：
  * - undefined：config.toml 不存在或**未声明**该键 → 非 catalog 模式；
  * - ''（空串哨兵）：已声明但不可用（值为空串/非字符串）→ 按"catalog 声明退化"处理
- *   （P2-1，绝不回退 bundled/FALLBACK）；
+ *   （绝不回退 bundled/FALLBACK）；
  * - TOML_PARSE_FAILED_SENTINEL：config.toml 存在但解析失败 → 无法得知是否声明，
  *   按非 catalog 处理（用户未声明 model_catalog_json 时的默认行为）；
  * - 具体路径：声明有效（含文件缺失，文件缺失由调用方按 active 命令失败处理）。
@@ -87,7 +87,7 @@ function readModelCatalogJsonPath(codexHome) {
     }
     catch {
         // config.toml 解析失败：codex 对非法配置是硬错误；此处无法得知是否声明了
-        // model_catalog_json，按非 catalog 处理（P3-5），不冒充 catalog 声明退化
+        // model_catalog_json，按非 catalog 处理，不冒充 catalog 声明退化
         return TOML_PARSE_FAILED_SENTINEL;
     }
 }
@@ -96,7 +96,7 @@ function readModelCatalogJsonPath(codexHome) {
  * 依据：codex 运行时对"已配置但文件缺失/不可解析"的目录是硬错误
  * （core/src/config/mod.rs load_model_catalog ?），绝不会回退内置目录；因此键存在即
  * catalog 模式，文件缺失自然落入 `codex debug models` 失败路径 → 模型列表回退
- * [currentModel]（P1-1）。
+ * [currentModel]。
  */
 export function isCodexCatalogMode(codexHome) {
     const home = resolveCodexHome(codexHome);
@@ -105,15 +105,15 @@ export function isCodexCatalogMode(codexHome) {
 }
 /**
  * 单一解析器：把 `codex debug models`（活动目录）或 `--bundled`（内置目录）的原始 JSON
- * 输出解析为模型列表（P2-4 去重）。过滤/排序镜像 codex：
+ * 输出解析为模型列表（去重）。过滤/排序镜像 codex：
  * - show_in_picker = visibility == List（openai_models.rs ModelPreset::from）；
  * - API 模式（lark 用 API key 认证）下 codex filter_by_auth 过滤 supported_in_api=false；
  * - 按 priority 升序（build_available_models）。
- * 档位按目录声明**原样透传**（含 custom/none，P2-5），不按标准枚举过滤、不虚构兜底：
+ * 档位按目录声明**原样透传**（含 custom/none），不按标准枚举过滤、不虚构兜底：
  * 未声明档位 → 空列表（codex with_model 语义：len=0 时用声明 default，都没有则不发
- * effort；P1）。空串档位/空串 default 被过滤（P3-9：codex ReasoningEffort::from_str
+ * effort；）。空串档位/空串 default 被过滤（codex ReasoningEffort::from_str
  * 对 "" 硬错误）。supported_in_api===true 过滤等价于 codex 的 chatgpt_mode ||
- * supported_in_api：本项目以 API-key 模式运行 codex，chatgpt_mode 恒 false（P3-3）。
+ * supported_in_api：本项目以 API-key 模式运行 codex，chatgpt_mode 恒 false。
  */
 export function parseCodexModelsOutput(stdout) {
     const parsed = JSON.parse(stdout);
@@ -133,7 +133,7 @@ export function parseCodexModelsOutput(stdout) {
             const declared = m.supported_reasoning_levels
                 .filter((r) => r !== null && typeof r === 'object' && 'effort' in r)
                 .map((r) => String(r.effort))
-                // P3-9：codex 拒绝空串档位（openai_models.rs from_str "" → Err）
+                // codex 拒绝空串档位（openai_models.rs from_str "" → Err）
                 .filter((effort) => effort.length > 0);
             supportedReasoningLevels.push(...declared);
         }
@@ -153,13 +153,13 @@ export function parseCodexModelsOutput(stdout) {
 /**
  * 统一目录入口：catalog 模式（model_catalog_json 已声明，含声明退化 ''）跑
  * `debug models`（无 --bundled），否则（未声明或 config.toml 解析失败）跑
- * `debug models --bundled`。注（P3-4）：codex 无参 `debug models` 在
+ * `debug models --bundled`。注：codex 无参 `debug models` 在
  * uses_codex_backend()/has_command_auth() 时会请求远端 /models（models-manager
  * manager.rs / models_endpoint.rs）；本项目以 API-key 模式运行（无 ChatGPT/命令
  * 认证），结果与 bundled 一致，故非 catalog 用 --bundled（已文档化）。
  * 缓存：键含 binary/home/mode/models.json mtime:size + config.toml mtime:size
- * （P3-4/P3-15/P3-5）；成功结果 TTL 1h，失败/空结果短 TTL 负缓存；stat 异常时
- * 指纹为空（P1-1/P3-10）。
+ * 成功结果 TTL 1h，失败/空结果短 TTL 负缓存；stat 异常时
+ * 指纹为空。
  *
  * 同步路径（卡片构建用）：缓存命中直接返回；若有一个后台异步加载
  * （`loadCodexCatalogModelsAsync` / 启动 warm）在途，则不阻塞事件循环、不重复
@@ -372,13 +372,13 @@ export function _clearCodexCatalogInFlightForTest() {
 export function getReasoningEffortOptions(model, codexHome) {
     const models = getCodexCatalogModels(codexHome);
     const found = models.find((m) => m.slug === model);
-    // 未命中（含未知模型，codex fallback 元数据 supported 为空）→ []，不虚构档位（P1）
+    // 未命中（含未知模型，codex fallback 元数据 supported 为空）→ []，不虚构档位
     return found?.supportedReasoningLevels ?? [];
 }
 /**
  * Get default reasoning effort for a model.
  * 未声明/未知模型 → undefined（codex 语义：ModelPreset.default_reasoning_effort
- * unwrap_or(ReasoningEffort::None)，即不传 effort；P3-12）。
+ * unwrap_or(ReasoningEffort::None)，即不传 effort；）。
  */
 export function getDefaultReasoningEffort(model, codexHome) {
     const models = getCodexCatalogModels(codexHome);
@@ -459,7 +459,7 @@ export function loadCodexConfig(opts = {}) {
             // 活动目录全局：codex 运行时 provider 与模型无绑定（StaticModelsManager），
             // 每个 provider 下拉都展示目录全部 slug
             // 活动目录不可用（命令失败/空）时回退 [currentModel]——无目录元数据时档位/能力
-            // 不可信；禁止泄漏 FALLBACK_MODELS/内置目录。model 键缺失时不得虚构 'o3'（P1-2）。
+            // 不可信；禁止泄漏 FALLBACK_MODELS/内置目录。model 键缺失时不得虚构 'o3'。
             const catalogCurrentModel = modelKeyRaw ?? catalogSlugs[0] ?? '';
             const providerModelList = catalogSlugs.length > 0 ? catalogSlugs : modelKeyRaw ? [modelKeyRaw] : [];
             providerModels = {};
@@ -492,7 +492,7 @@ export function loadCodexConfig(opts = {}) {
                 providerEnvKeys[name] = config.env_key;
             }
         }
-        // anthropic 显式配置但未写 env_key 时保留默认键（P3-9：恢复旧版无条件映射的
+        // anthropic 显式配置但未写 env_key 时保留默认键（恢复旧版无条件映射的
         // 配置场景行为；未配置时不再虚构）
         if (rawProviderNames.includes('anthropic') &&
             !modelProviders['anthropic']?.env_key &&
@@ -519,7 +519,7 @@ export function loadCodexConfig(opts = {}) {
     }
     catch {
         // config.toml 解析失败（readModelCatalogJsonPath 已把此场景标记为 catalog 声明退化 ''）：
-        // catalogMode 为 true 时绝不回退 bundled/FALLBACK（P2-1），返回空 provider/模型列表；
+        // catalogMode 为 true 时绝不回退 bundled/FALLBACK，返回空 provider/模型列表；
         // 非 catalog 才走 FALLBACK 兜底。
         if (catalogMode) {
             return {
@@ -553,7 +553,7 @@ export function loadCodexConfig(opts = {}) {
  * - If no provider: return all models from all providers (with currentModel prepended if not in any list)
  */
 function buildModelOptions(currentModel, currentProvider, provider, providerModels) {
-    // 不为空 currentModel 虚构默认值（catalog 退化场景由上层显式传入，P1-2）；
+    // 不为空 currentModel 虚构默认值（catalog 退化场景由上层显式传入）；
     // 空值时直接返回原始列表
     const cm = currentModel;
     if (provider && providerModels[provider]) {

package/dist/config/dir.js

@@ -11,6 +11,9 @@ export function resolveConfigDir(configDirArg) {
             p = os.homedir();
         else if (p.startsWith('~/'))
             p = path.join(os.homedir(), p.slice(2));
+        // cmd/PowerShell 不展开 ~；`~\` 是 Windows 侧的常见键入形态，与 `~/` 同口径
+        else if (p.startsWith('~\\'))
+            p = path.join(os.homedir(), p.slice(2));
         return path.resolve(p);
     }
     return path.join(os.homedir(), DEFAULT_DIR);
@@ -35,7 +38,7 @@ export function parseCliArgs(args = process.argv.slice(2)) {
             result.version = true;
         }
         else if (arg === '--config-dir' && i + 1 < args.length) {
-            // P1-20: peek, don't consume — when the next arg is itself a flag,
+            // peek, don't consume — when the next arg is itself a flag,
             // roll back so it continues parsing (previously --settings/--help
             // right after --config-dir were silently swallowed).
             const nextArg = args[i + 1];
@@ -108,7 +111,7 @@ export function printHelp() {
  */
 export function printAdvancedHelp() {
     const configDir = resolveConfigDir(parseCliArgs().configDir);
-    const configPath = configDir + '/config.yaml';
+    const configPath = path.join(configDir, 'config.yaml');
     const lines = [
         'lark-remote 高级配置参考（--advanced-help）',
         '',

package/dist/config/index.d.ts

@@ -17,7 +17,7 @@ export declare const PI_THINKING_LEVELS: readonly ["off", "minimal", "low", "med
 /**
  * Default SIGTERM→SIGKILL grace period (ms). Exported so runners (SpawningRunner)
  * and config-loading paths (src/index.ts) can reuse the same source of truth
- * instead of re-literalizing `5000` (Clean Code P3-1, G25).
+ * instead of re-literalizing `5000` (Clean Code G25).
  */
 export declare const DEFAULT_STOP_GRACE_MS: 5000;
 /** Codex app-server turn idle timeout default (minutes). */
@@ -299,7 +299,7 @@ export declare function loadConfig(configPath: string): AppConfig;
  */
 export declare function mapAgentKey(key: string): string;
 /**
- * 拒绝原型链危险 key 段（§P1-4）。
+ * 拒绝原型链危险 key 段。
  *
  * `/config` 直写路径的 key 是用户自由输入：`__proto__.polluted` 会通过
  * `current['__proto__']` 拿到 Object.prototype 并写入，污染整个进程且不可恢复；
@@ -324,7 +324,7 @@ export declare function setConfigValue(configPath: string, config: AppConfig, ke
  * Set multiple nested values in config, write back to YAML file once.
  *
  * 在 draft 副本上操作（structuredClone），验证通过后才写盘，避免校验失败时
- * 内存中的 config 已被污染（P0 atomicity）。
+ * 内存中的 config 已被污染（atomicity）。
  */
 export declare function setConfigValues(configPath: string, config: AppConfig, updates: Record<string, string | undefined>): AppConfig;
 /** Type helpers for agent config (used by getAgentConfig). */

package/dist/config/index.js

@@ -45,7 +45,7 @@ const DEFAULTS = {
 /**
  * Default SIGTERM→SIGKILL grace period (ms). Exported so runners (SpawningRunner)
  * and config-loading paths (src/index.ts) can reuse the same source of truth
- * instead of re-literalizing `5000` (Clean Code P3-1, G25).
+ * instead of re-literalizing `5000` (Clean Code G25).
  */
 export const DEFAULT_STOP_GRACE_MS = DEFAULTS.STOP_GRACE_MS;
 /** Codex app-server turn idle timeout default (minutes). */
@@ -115,9 +115,9 @@ export const CodexConfigSchema = z.object({
     /**
      * Reasoning effort level。codex 标准档位 minimal/low/medium/high/xhigh/max/ultra
      * 之外还接受 none 与模型自定义值（ReasoningEffort::Custom），目录声明什么就存什么
-     * （P2-5），故用字符串而非枚举。
+     * 故用字符串而非枚举。
      */
-    // codex 拒绝空串档位（ReasoningEffort::from_str "" → Err，P3-3）
+    // codex 拒绝空串档位（ReasoningEffort::from_str "" → Err）
     reasoningEffort: z.string().min(1).optional(),
     /** Approval policy (Codex 官方 AskForApproval 标准值). 默认 on-request。 */
     approvalPolicy: z.enum(['untrusted', 'on-request', 'never']).default('on-request'),
@@ -363,7 +363,7 @@ function coerceValue(raw) {
     return raw;
 }
 /**
- * 拒绝原型链危险 key 段（§P1-4）。
+ * 拒绝原型链危险 key 段。
  *
  * `/config` 直写路径的 key 是用户自由输入：`__proto__.polluted` 会通过
  * `current['__proto__']` 拿到 Object.prototype 并写入，污染整个进程且不可恢复；
@@ -423,7 +423,7 @@ export function setConfigValue(configPath, config, key, value) {
  * Set multiple nested values in config, write back to YAML file once.
  *
  * 在 draft 副本上操作（structuredClone），验证通过后才写盘，避免校验失败时
- * 内存中的 config 已被污染（P0 atomicity）。
+ * 内存中的 config 已被污染（atomicity）。
  */
 export function setConfigValues(configPath, config, updates) {
     const draft = structuredClone(config);
@@ -472,7 +472,7 @@ function renderConfigPatch(configPath, updates, validated) {
             doc.deleteIn(parts);
             continue;
         }
-        // 保存载荷里只写"校验结果中存活下来"的键：schema 不认识的键（§P2-24 的 foo.bar）
+        // 保存载荷里只写"校验结果中存活下来"的键：schema 不认识的键（foo.bar）
         // 会被 Zod 剥掉，跟着打在 Document 上就是把垃圾永久写进用户配置文件。
         // 磁盘上原有的未知键不受影响 —— 那是用户手写的，本函数不碰。
         const accepted = getConfigValue(validated, parts.join('.'));

package/dist/config/opencode-config.js

@@ -22,7 +22,7 @@ const FALLBACK_PROVIDERS = Object.keys(FALLBACK_MODELS);
 const OPENCODE_CONFIG_CACHE_TTL_MS = 60_000;
 /**
  * 失败负缓存 TTL：命令失败后 30s 内直接用 fallback，避免每次 /config 卡片构建
- * 都同步阻塞事件循环最长 10s（§P1-8，与 codex-config 负缓存对齐）。
+ * 都同步阻塞事件循环最长 10s（与 codex-config 负缓存对齐）。
  */
 const OPENCODE_NEGATIVE_CACHE_TTL_MS = 30_000;
 let opencodeConfigCache = null;
@@ -57,7 +57,7 @@ function buildFallbackResult() {
  */
 export function loadOpencodeConfig() {
     const now = Date.now();
-    // 正缓存命中：TTL 内不重复 execSync（P1-8）
+    // 正缓存命中：TTL 内不重复 execSync
     if (opencodeConfigCache && now - opencodeConfigCache.timestamp < OPENCODE_CONFIG_CACHE_TTL_MS) {
         return opencodeConfigCache.result;
     }
@@ -74,7 +74,7 @@ export function loadOpencodeConfig() {
         // 执行 opencode models --verbose 获取所有模型信息
         const res = spawnProcessSync(resolved.file, ['models', '--verbose'], {
             encoding: 'utf-8',
-            // P1-8：30s → 10s，与 codex/kimi 对齐；maxBuffer 防模型清单 ENOBUFS 隐性截断
+            // 30s → 10s，与 codex/kimi 对齐；maxBuffer 防模型清单 ENOBUFS 隐性截断
             timeout: 10000,
             maxBuffer: 64 * 1024 * 1024,
         });

package/dist/connector/index.d.ts

@@ -73,7 +73,7 @@ export interface InboundMediaPayload {
 }
 /**
  * 媒体消息到达的轻量描述（未下载）：供上层先做 owner/配置闸门，
- * 通过后再调 downloadInboundMedia —— 下载发生在认证之后（P1 review 修复）。
+ * 通过后再调 downloadInboundMedia —— 下载发生在认证之后（修复）。
  */
 /** SDK 给出的可下载资源种类（`resources[].type`）。 */
 export type InboundResourceKind = 'image' | 'file' | 'audio' | 'video' | 'sticker';
@@ -180,14 +180,14 @@ export declare class FeishuConnector {
      */
     private checkUploadable;
     /**
-     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁）
      * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
      * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
      * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
      * 标签（'sendFile' | 'sendImage'）。
      */
     private uploadAndSendMedia;
-    /** 单次「上传 + 发媒体消息」；文件流在此拥有，任何失败路径都销毁（P2-18）。 */
+    /** 单次「上传 + 发媒体消息」；文件流在此拥有，任何失败路径都销毁。 */
     private uploadWithToken;
     /**
      * Upload a file to Feishu and send it to the specified chat.
@@ -201,13 +201,13 @@ export declare class FeishuConnector {
      */
     sendImage(chatId: string, filePath: string): Promise<string>;
     /**
-     * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
+     * Cached tenant_access_token for sendFile. The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch
      * could return data.code != 0 with an undefined token. Cache with expiry and
      * validate the response code.
      *
      * 缓存的两条失效路径：到期（下面 expire）与被服务端判 token 无效
-     * （invalidateTenantToken，见 §B13）。
+     * （invalidateTenantToken）。
      */
     private cachedToken;
     private cachedTokenExpireAt;

package/dist/connector/index.js

@@ -111,7 +111,7 @@ function withTimeout(promise, ms, label, onLateSettle) {
     });
 }
 /**
- * 判断 send 失败是否值得重试一次（§9.5 限流重试口径，§P1-3 修正）。
+ * 判断 send 失败是否值得重试一次（§9.5 限流重试口径）。
  *
  * @larksuite/channel@0.7.1 的 classifyError 把飞书业务码 99991400/99991401
  * （频率控制）归类为 `code='permission_denied'`（SDK 源码实证），并保留原始
@@ -271,6 +271,19 @@ export class FeishuConnector {
                     ttl: DEDUP_TTL_MS,
                     maxEntries: 1000,
                 },
+                // 关掉 SDK 的入站去抖合批（`ChatPipeline` + `mergeBatch`），delayMs=0 让每条
+                // 消息单独成批、保留自己的 messageId（`enabled` 仍为 true，per-chat 串行与
+                // 卡片动作同通道不受影响）。
+                //
+                // 背景：SDK 默认 600ms 内把同一会话的多条消息合并成一条，`mergeBatch` 只保留
+                // **最后一条**的 `messageId` 却把多条消息的 `resources` 求并集。飞书客户端
+                // "一次选多图/多文件"会背靠背秒发成多条独立消息，被合并后下载侧拿同一个
+                // `messageId` 下所有 `fileKey`，除最后一条外全部报错 234003（HTTP 400）：
+                // 表现为"多图只有 1 张保存成功，其余下载失败"。合批本应由本项目自己的
+                // 700ms 装配器（`InboundTurnAssembler`）负责，SDK 这层是叠加的第二次合批。
+                batch: {
+                    text: { delayMs: 0 },
+                },
             },
         });
         // 卡片 patch 的统一出口（观测 + 重试）：
@@ -305,7 +318,7 @@ export class FeishuConnector {
             // SDK 只为 image/file/audio/video/media/sticker 五类产出非空 resources，
             // 枚举 msg_type 必然漏（2026-09-15 事故：mp4 被当文本转发给 agent）。
             // 一条消息可以**同时**产出资源事件与文本事件（post 既有文字又有图），
-            // 由 B3 的装配器合并成同一个 turn。
+            // 由的装配器合并成同一个 turn。
             const hasResources = msg.resources.length > 0;
             if (hasResources) {
                 // 只上报「媒体到达」，不在此下载：owner/配置闸门在 index.ts 里先执行，
@@ -489,7 +502,7 @@ export class FeishuConnector {
                     return result.messageId;
                 }
                 catch (retryErr) {
-                    // P2-17: throw the RETRY error, not the outer `err`. Previously
+                    // throw the RETRY error, not the outer `err`. Previously
                     // `throw err` here re-threw the first (rate-limit) failure, hiding
                     // the real reason the retry attempt failed (e.g. auth invalid).
                     getLogger().warn('[feishu] retry after rate limit still failed');
@@ -595,7 +608,7 @@ export class FeishuConnector {
         }
     }
     /**
-     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁，P2-18）
+     * sendFile/sendImage 共用骨架：token → 上传（流在任何失败路径销毁）
      * → 发送媒体消息。上传端点 / form 字段 / 响应 key / msg_type 的差异由调用方
      * 以 uploadUrl + buildForm + keyField + msgType 表达；timeout、noKeepAliveAgent
      * （Bun keep-alive 修复）与错误包装在此单源。label 是对外错误前缀与日志
@@ -627,13 +640,13 @@ export class FeishuConnector {
             throw new Error(`${label} failed: ${errorInfo}`, { cause: err });
         }
     }
-    /** 单次「上传 + 发媒体消息」；文件流在此拥有，任何失败路径都销毁（P2-18）。 */
+    /** 单次「上传 + 发媒体消息」；文件流在此拥有，任何失败路径都销毁。 */
     async uploadWithToken(accessToken, chatId, filePath, uploadUrl, buildForm, keyField, msgType) {
         let fileStream = null;
         try {
             fileStream = fs.createReadStream(filePath);
             const form = buildForm(fileStream);
-            // P2-18: timeout 120s（大文件慢链路）；httpsAgent: noKeepAliveAgent 防止
+            // timeout 120s（大文件慢链路）；httpsAgent: noKeepAliveAgent 防止
             // Bun 复用已被服务端 RST 的 keep-alive socket（ECONNRESET after ~30s）。
             const uploadResp = await axios.post(uploadUrl, form, {
                 headers: {
@@ -647,7 +660,7 @@ export class FeishuConnector {
                 throw new FeishuBusinessError(`Upload failed: ${uploadResp.data.msg}`, uploadResp.data.code);
             }
             const mediaKey = uploadResp.data.data[keyField];
-            // P2-18: timeout 30s；noKeepAlive 同上。
+            // timeout 30s；noKeepAlive 同上。
             const sendResp = await axios.post('https://open.feishu.cn/open-apis/im/v1/messages', {
                 receive_id: chatId,
                 msg_type: msgType,
@@ -667,7 +680,7 @@ export class FeishuConnector {
             return sendResp.data.data.message_id;
         }
         catch (err) {
-            // P2-18: destroy the read stream on failure so the fd is released.
+            // destroy the read stream on failure so the fd is released.
             if (fileStream) {
                 try {
                     fileStream.destroy();
@@ -708,13 +721,13 @@ export class FeishuConnector {
         }, 'image_key', 'image');
     }
     /**
-     * Cached tenant_access_token for sendFile (P2-18). The token is valid ~2h;
+     * Cached tenant_access_token for sendFile. The token is valid ~2h;
      * fetching it on every file send wastes a round-trip and an unguarded fetch
      * could return data.code != 0 with an undefined token. Cache with expiry and
      * validate the response code.
      *
      * 缓存的两条失效路径：到期（下面 expire）与被服务端判 token 无效
-     * （invalidateTenantToken，见 §B13）。
+     * （invalidateTenantToken）。
      */
     cachedToken = null;
     cachedTokenExpireAt = 0;
@@ -736,7 +749,7 @@ export class FeishuConnector {
         this.cachedTokenExpireAt = 0;
     }
     async fetchTenantAccessToken() {
-        // P2-18: timeout 30s on the token request.
+        // timeout 30s on the token request.
         // httpsAgent: noKeepAlive — same Bun keep-alive fix as upload above.
         const tokenResp = await axios.post('https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal', {
             app_id: this.appId,

package/dist/inbound/event.d.ts

@@ -1,7 +1,7 @@
 /**
  * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
  *
- * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
  * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
  * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
  * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，

package/dist/inbound/event.js

@@ -1,7 +1,7 @@
 /**
  * 装配器事件（设计依据见 `docs/zh/architecture/inbound-unified-input-design.md`）。
  *
- * 设计文档早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
+ * 早期的媒体事件形态是「下载完成后的 attachments/failures」。实际链路里
  * 下载是异步的（`index.ts` 先过 owner/enabled 闸门再下载），若等下载完成才投递事件，
  * 「先图后文」在慢下载下会先提交一个只含文本的 turn（正是要修的症状）。因此媒体事件
  * 携带一个 **outcome promise**：装配器立刻知道「本 turn 还有 in-flight 下载」，

package/dist/inbound/placeholder.d.ts

@@ -1,7 +1,7 @@
 /**
  * 入站消息结构占位符识别与剥离（纯函数，无 IO，便于表驱动测试）。
  *
- * 背景（P0 事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
+ * 背景（事故 2026-09-15）：`@larksuite/channel` 把非文本消息渲染成结构占位符，
  * 富文本（`post`）里的图片是 `![image](img_v3_…)` —— 首字符恰好是 `!`，于是被
  * `src/router/index.ts` 的裸前缀判定当成 bash 命令执行了整段消息。
  *
@@ -12,7 +12,7 @@
  * 取舍（有意为之）：剥离对所有消息生效，所以用户在**纯文本**消息里手打
  * `![image](…)` / `<file key="…"/>` 这类字面量也会被当成占位符剥掉。代价是极少数
  * 「讨论本工具自身语法」的消息会丢片段；换来的是任何入口都不可能把占位符当命令
- * （P0 事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
+ * （事故正是 `![image](img_v3_…)` 的首字符 `!` 命中 bash 判定）。
  */
 export type PlaceholderKind = 'image' | 'file' | 'video' | 'audio' | 'sticker' | 'share' | 'location' | 'folder' | 'vote' | 'todo' | 'meeting' | 'calendar' | 'hongbao' | 'forwarded' | 'unsupported' | 'unknown';
 export interface StripResult {