lark-remote 0.4.2 → 0.4.3

package/dist/card/text-truncate.js

@@ -22,6 +22,8 @@ export const FEISHU_MAX_TABLES = 5;
  * 共用，避免三处各自定义后数值漂移。
  */
 export const CARD_BUDGET_BYTES = 28_000;
+/** markdown table 分隔行判据：以 `|` 开头，只含 `| - : 空格`。 */
+const TABLE_SEPARATOR_RE = /^\|[-: |]+$/;
 /**
  * Count the number of markdown tables in a string.
  *
@@ -32,43 +34,24 @@ export const CARD_BUDGET_BYTES = 28_000;
 export function countMarkdownTables(text) {
     let count = 0;
     for (const line of text.split('\n')) {
-        if (/^\|[-: |]+$/.test(line.trim())) {
+        if (TABLE_SEPARATOR_RE.test(line.trim())) {
             count++;
         }
     }
     return count;
 }
 /**
- * Truncate markdown tables in a string to at most `maxTables`, keeping the
- * **newest** (last) tables and removing the oldest ones.
- *
- * Strategy: find all table separator lines, determine which tables to remove
- * (those whose separator is among the oldest `count - maxTables`), then remove
- * each such table entirely (header row + separator row + data rows).
- *
- * A "table block" is a contiguous run of lines where the first line is the
- * header row, the second is the separator row (`|---|`), and subsequent lines
- * are data rows. We remove entire table blocks from the text.
+ * 按文档顺序定位字符串里的 markdown table 块。
  *
- * When tables are removed, a hint is inserted at the removal point indicating
- * how many earlier tables were omitted.
+ * `truncateMarkdownTables`（单串）与 `enforceCardBudget`（整卡预算）共用这一份
+ * 识别口径——两处各写一遍分隔行正数是下一个 bug 的温床。
  */
-export function truncateMarkdownTables(text, maxTables = FEISHU_MAX_TABLES) {
-    if (maxTables <= 0)
-        return text;
-    const tableCount = countMarkdownTables(text);
-    if (tableCount <= maxTables)
-        return text;
+function findMarkdownTableBlocks(text) {
     const lines = text.split('\n');
-    // Step 1: Find all table separator line indices
-    const separatorIndices = [];
-    for (let i = 0; i < lines.length; i++) {
-        if (/^\|[-: |]+$/.test(lines[i].trim())) {
-            separatorIndices.push(i);
-        }
-    }
     const blocks = [];
-    for (const sepIdx of separatorIndices) {
+    for (let sepIdx = 0; sepIdx < lines.length; sepIdx++) {
+        if (!TABLE_SEPARATOR_RE.test(lines[sepIdx].trim()))
+            continue;
         // Header is the line just before the separator
         let start = sepIdx - 1;
         if (start < 0)
@@ -90,30 +73,37 @@ export function truncateMarkdownTables(text, maxTables = FEISHU_MAX_TABLES) {
         while (end < lines.length && /^\|/.test(lines[end].trim())) {
             end++;
         }
-        blocks.push({ start, end, separatorIdx: sepIdx });
+        blocks.push({ start, end });
     }
-    // Step 3: Determine which blocks to remove (oldest first)
-    const toRemoveCount = blocks.length - maxTables;
-    // blocks are in document order (oldest first), so remove from the front
-    const blocksToRemove = new Set(blocks.slice(0, toRemoveCount));
-    // Map: start line index → block (for lookup when processing lines)
+    return blocks;
+}
+/**
+ * 删掉 `text` 中文档顺序**最旧**的至多 `maxDrop` 个 table 块（保留其余，含最新
+ * 的那些），并在最后一个删除点插入省略提示。`maxDrop <= 0` 时原样返回。
+ *
+ * 与 `truncateMarkdownTables` 同一口径：删最旧、留最新。
+ */
+export function dropOldestMarkdownTables(text, maxDrop) {
+    if (maxDrop <= 0)
+        return text;
+    const lines = text.split('\n');
+    const blocksToRemove = findMarkdownTableBlocks(text).slice(0, maxDrop);
+    if (blocksToRemove.length === 0)
+        return text;
     const blockByStart = new Map();
-    for (const b of blocks) {
+    for (const b of blocksToRemove)
         blockByStart.set(b.start, b);
-    }
-    // Step 4: Rebuild the text, skipping removed table blocks and inserting hints
+    const toRemove = blocksToRemove.length;
     const result = [];
     let i = 0;
-    let removedSoFar = 0;
+    let dropped = 0;
     while (i < lines.length) {
         const block = blockByStart.get(i);
-        if (block && blocksToRemove.has(block)) {
-            // Skip the entire table block
-            removedSoFar++;
+        if (block) {
+            dropped++;
             i = block.end;
-            // Insert hint at the removal point
-            if (removedSoFar === toRemoveCount) {
-                result.push(`_💡 前 ${toRemoveCount} 个表格已省略_`);
+            if (dropped === toRemove) {
+                result.push(`_💡 前 ${dropped} 个表格已省略_`);
             }
             continue;
         }
@@ -122,4 +112,19 @@ export function truncateMarkdownTables(text, maxTables = FEISHU_MAX_TABLES) {
     }
     return result.join('\n');
 }
+/**
+ * Truncate markdown tables in a string to at most `maxTables`, keeping the
+ * **newest** (last) tables and removing the oldest ones.
+ *
+ * 注意：`maxTables` 是**这一个字符串**的上限。飞书 11310 数的是**整卡**，
+ * 表分散在多个字段时必须走 `card-budget.ts` 的整卡预算，不能逐字段调用本函数。
+ */
+export function truncateMarkdownTables(text, maxTables = FEISHU_MAX_TABLES) {
+    if (maxTables <= 0)
+        return text;
+    const dropCount = findMarkdownTableBlocks(text).length - maxTables;
+    if (dropCount <= 0)
+        return text;
+    return dropOldestMarkdownTables(text, dropCount);
+}
 //# sourceMappingURL=text-truncate.js.map

package/dist/cli.js

@@ -1,4 +1,21 @@
 #!/usr/bin/env node
+/**
+ * CLI 引导层（bootstrap）：在 import 应用模块图之前决定运行时（bun/node）并拉起它。
+ *
+ * **这是全仓唯一被认可的 spawn 收口例外**（即 AGENTS.md「子进程 spawn 只走
+ * platform/spawn.ts」红线的显式豁免）。三个理由缺一不可：
+ *   1. 时序：preflight（Node 版本守卫、-v/-h/--advance-help）必须在 import 应用
+ *      模块图之前跑完——dist/cli.js 刻意不使用 ES2020+ 语法以便在 node 12 上仍
+ *      可被解析，而 dist/index.js 是 ES2022；先 import platform/spawn 就等于先把
+ *      应用模块图拖进来，守卫当场失效（报错堆栈全落在 Node 内部）。
+ *   2. 依赖：platform/spawn.ts 依赖 cross-spawn（应用依赖树的一部分），在「刚
+ *      诊断出 Node 太老」的那个时刻并不可加载。
+ *   3. 语义：这里 spawn 的是**另一份运行时**（bun 重启自己），不是 agent/工具
+ *      子进程，不参与组杀、pid 文件、windowsHide 注入这整套 runner 语义。
+ *
+ * 结论：不要为了“统一收口”把这里改走 platform/spawn；反过来，除本文件之外
+ * 任何地方新增子进程都必须走 platform/spawn.ts。
+ */
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';

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

@@ -11,6 +11,9 @@
 /**
  * Resolve codex home directory.
  * Priority: explicit codexHome param > $CODEX_HOME env > ~/.codex
+ *
+ * 空串/纯空白按「未设置」处理：`??` 只挡 undefined，放过空串会让
+ * `path.join('', 'config.toml')` 变成相对**进程 cwd** 的路径。
  */
 export declare function resolveCodexHome(codexHome?: string): string;
 /** loadCodexConfig() return type */

package/dist/config/codex-config.js

@@ -22,9 +22,12 @@ const CODEX_MAX_BUFFER = 4 * 1024 * 1024;
 /**
  * Resolve codex home directory.
  * Priority: explicit codexHome param > $CODEX_HOME env > ~/.codex
+ *
+ * 空串/纯空白按「未设置」处理：`??` 只挡 undefined，放过空串会让
+ * `path.join('', 'config.toml')` 变成相对**进程 cwd** 的路径。
  */
 export function resolveCodexHome(codexHome) {
-    return codexHome ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
+    return codexHome?.trim() || process.env.CODEX_HOME?.trim() || path.join(os.homedir(), '.codex');
 }
 /**
  * Fallback lists

package/dist/config/dir.js

@@ -133,20 +133,20 @@ export function printAdvanceHelp() {
         '',
         'Codex（agents.codex.appServer.*）：',
         '  binary                (默认 codex)     codex 二进制路径',
-        '  requestTimeoutMs      (默认 60000)     单次 RPC 请求超时(ms)',
-        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  requestTimeoutMs      (默认 60000)     单次 RPC 请求超时(ms)，0=不超时',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)，0=不回收',
         '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
         '',
         'Kimi（agents.kimi.acp.*）：',
         '  binary                (默认 kimi)      kimi 二进制路径',
-        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)',
-        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)，0=不超时',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)，0=不回收',
         '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
         '',
         'OpenCode（agents.opencode.acp.*）：',
         '  binary                (默认 opencode)  opencode 二进制路径',
-        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)',
-        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)',
+        '  requestTimeoutMs      (默认 60000)     单次请求超时(ms)，0=不超时',
+        '  idleTtlMs             (默认 1800000)   连接空闲回收(ms)，0=不回收',
         '  turnIdleTimeoutMinutes(默认 30)        turn 无输出超时(分钟)，0=关闭（卡片也可改）',
         '',
         'Pi：',

package/dist/config/index.d.ts

@@ -3,11 +3,13 @@ export { getConfigDir } from './dir.js';
 /** Valid effort values for Claude */
 export declare const CLAUDE_EFFORTS: readonly ["low", "medium", "high", "xhigh", "max"];
 /**
- * Claude 官方 --permission-mode 枚举（claude --help 输出，2026-08 实测）。
- * 额外支持 'default'：Claude settings.json 的官方未设置值，等价于不传
- * --permission-mode（交互式默认：高风险工具逐个询问）。
- * 'manual' 是 'default' 的别名（claude CLI 等价），schema 保留以向后兼容旧配置，
- * 但 UI 下拉不展示（见 router/config/claude.ts）。
+ * Claude 的权限模式取值：'default' 之外都是 CLI `--permission-mode` 的真实枚举
+ * （2026-09-20 实测 claude --help：acceptEdits | auto | bypassPermissions | manual
+ * | dontAsk | plan）。
+ * 'default' 是本项目自造的值，不是 CLI 的取值 —— 它表示"不传 --permission-mode"，
+ * 由 CLI 自己决定默认模式，转换在 runner/claude/session.ts 的 spawn 参数处。
+ * 'manual' 与 'default' 不是别名关系：一个是显式传给 CLI 的取值，一个是省略该参数，
+ * schema 保留两者只为兼容旧配置（UI 下拉的处理见 router/config/claude.ts）。
  */
 export declare const CLAUDE_PERMISSION_MODES: readonly ["default", "acceptEdits", "auto", "bypassPermissions", "manual", "dontAsk", "plan"];
 /** Valid thinking levels for Pi */

package/dist/config/index.js

@@ -10,11 +10,13 @@ import { KIMI_THINKING_EFFORTS } from './kimi-config.js';
 /** Valid effort values for Claude */
 export const CLAUDE_EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max'];
 /**
- * Claude 官方 --permission-mode 枚举（claude --help 输出，2026-08 实测）。
- * 额外支持 'default'：Claude settings.json 的官方未设置值，等价于不传
- * --permission-mode（交互式默认：高风险工具逐个询问）。
- * 'manual' 是 'default' 的别名（claude CLI 等价），schema 保留以向后兼容旧配置，
- * 但 UI 下拉不展示（见 router/config/claude.ts）。
+ * Claude 的权限模式取值：'default' 之外都是 CLI `--permission-mode` 的真实枚举
+ * （2026-09-20 实测 claude --help：acceptEdits | auto | bypassPermissions | manual
+ * | dontAsk | plan）。
+ * 'default' 是本项目自造的值，不是 CLI 的取值 —— 它表示"不传 --permission-mode"，
+ * 由 CLI 自己决定默认模式，转换在 runner/claude/session.ts 的 spawn 参数处。
+ * 'manual' 与 'default' 不是别名关系：一个是显式传给 CLI 的取值，一个是省略该参数，
+ * schema 保留两者只为兼容旧配置（UI 下拉的处理见 router/config/claude.ts）。
  */
 export const CLAUDE_PERMISSION_MODES = [
     'default',
@@ -96,9 +98,9 @@ const ClaudeConfigSchema = z.object({
 const CodexAppServerConfigSchema = z.object({
     /** Path to the codex binary for app-server mode. */
     binary: z.string().default('codex'),
-    /** Request timeout in milliseconds. */
+    /** Request timeout in milliseconds. 0 = 不设超时（不是「0ms 即超时」）。 */
     requestTimeoutMs: z.number().int().min(0).default(60000),
-    /** Idle TTL for connection pool in milliseconds. */
+    /** Idle TTL in milliseconds. 0 = 不回收常驻连接（对齐 claude.idleTtlMinutes）。 */
     idleTtlMs: z.number().int().min(0).default(1800000),
     /** Turn idle timeout in minutes: no app-server output for this long triggers
      *  turn/interrupt and fails the run. 0 disables the timeout. */
@@ -141,9 +143,9 @@ const OpencodeConfigSchema = z.object({
         .object({
         /** Path to opencode binary for ACP mode. */
         binary: z.string().default('opencode'),
-        /** Request timeout in milliseconds. */
+        /** Request timeout in milliseconds. 0 = 不设超时（不是「0ms 即超时」）。 */
         requestTimeoutMs: z.number().int().min(0).default(60000),
-        /** Idle TTL for ACP connection in milliseconds. */
+        /** Idle TTL in milliseconds. 0 = 不回收常驻连接（对齐 claude.idleTtlMinutes）。 */
         idleTtlMs: z.number().int().min(0).default(1800000),
         /** Turn idle timeout in minutes (0 disables). */
         turnIdleTimeoutMinutes: z.number().int().min(0).default(DEFAULT_TURN_IDLE_TIMEOUT_MINUTES),
@@ -165,7 +167,7 @@ const PiConfigSchema = z.object({
 const KimiConfigSchema = z.object({
     /** Model ID or alias, e.g. 'kimi-code/k3'. */
     model: z.string().default('kimi-code/k3'),
-    /** Thinking effort: 'on', 'max'. */
+    /** Thinking effort，取值见 KIMI_THINKING_EFFORTS（'low' | 'high' | 'max'）。 */
     thinkingEffort: z.enum(KIMI_THINKING_EFFORTS).default('max'),
     /** Permission mode: 'manual' (approve each), 'auto' (engine decides), 'yolo' (allow all). */
     permissionMode: z.enum(['manual', 'auto', 'yolo']).default('manual'),
@@ -174,9 +176,9 @@ const KimiConfigSchema = z.object({
         .object({
         /** Path to kimi binary for ACP mode. */
         binary: z.string().default('kimi'),
-        /** Request timeout in milliseconds. */
+        /** Request timeout in milliseconds. 0 = 不设超时（不是「0ms 即超时」）。 */
         requestTimeoutMs: z.number().int().min(0).default(60000),
-        /** Idle TTL for ACP connection in milliseconds. */
+        /** Idle TTL in milliseconds. 0 = 不回收常驻连接（对齐 claude.idleTtlMinutes）。 */
         idleTtlMs: z.number().int().min(0).default(1800000),
         /** Turn idle timeout in minutes (0 disables). */
         turnIdleTimeoutMinutes: z.number().int().min(0).default(DEFAULT_TURN_IDLE_TIMEOUT_MINUTES),
@@ -442,9 +444,46 @@ export function setConfigValues(configPath, config, updates) {
         const errors = result.error.issues.map((i) => `  ${i.path.join('.')}: ${i.message}`).join('\n');
         throw new Error(`[lark-remote] config validation failed:\n${errors}`);
     }
-    atomicWrite(configPath, YAML.stringify(result.data));
+    atomicWrite(configPath, renderConfigPatch(configPath, updates, result.data));
     return result.data;
 }
+/**
+ * 写盘内容：读磁盘原文，把改动逐条打在 YAML Document 上（setIn 会按需补中间层），
+ * 而不是把校验结果整份 stringify —— 后者会把 dir.ts 正引导用户手写的注释、以及
+ * schema 不认识的键（Zod 默认剥离）在第一次保存时清光，还会把每个默认值都落进文件。
+ *
+ * 原文读不到或解析不了（进程启动后被改坏）时退回校验结果：那份原文已无保留价值，
+ * 与修复前的行为一致。
+ */
+function renderConfigPatch(configPath, updates, validated) {
+    let doc;
+    try {
+        doc = YAML.parseDocument(fs.readFileSync(configPath, 'utf-8'), { prettyErrors: true });
+        if (doc.errors.length > 0)
+            throw new Error(doc.errors[0].message);
+    }
+    catch (err) {
+        getLogger().warn(`[config] existing file unusable, rewriting from validated config: ${err.message}`);
+        return YAML.stringify(validated);
+    }
+    for (const [key, value] of Object.entries(updates)) {
+        const parts = mapAgentKey(key).split('.');
+        if (value === undefined) {
+            doc.deleteIn(parts);
+            continue;
+        }
+        // 保存载荷里只写"校验结果中存活下来"的键：schema 不认识的键（§P2-24 的 foo.bar）
+        // 会被 Zod 剥掉，跟着打在 Document 上就是把垃圾永久写进用户配置文件。
+        // 磁盘上原有的未知键不受影响 —— 那是用户手写的，本函数不碰。
+        const accepted = getConfigValue(validated, parts.join('.'));
+        if (accepted === undefined) {
+            getLogger().warn(`[config] save payload key not in schema, not written: ${key}`);
+            continue;
+        }
+        doc.setIn(parts, accepted);
+    }
+    return doc.toString();
+}
 /**
  * 按 dot-separated key 删除嵌套值（不存在的键静默忽略）。
  */

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

@@ -7,7 +7,10 @@
 /** Valid thinking effort values for kimi (Layer 1: Schema enum source) */
 export declare const KIMI_THINKING_EFFORTS: readonly ["low", "high", "max"];
 export type KimiThinkingEffort = (typeof KIMI_THINKING_EFFORTS)[number];
-/** Fallback efforts when all values are filtered out */
+/**
+ * 兜底 effort 全集就是 schema 枚举本身（不是另一份字面量，否则新增取值要改两处）。
+ * 类型放宽为 readonly string[]：消费侧拿的是外部输入过滤后的兜底列表，不做枚举窄化。
+ */
 export declare const FALLBACK_EFFORTS: readonly string[];
 /** Load Kimi config and return available models */
 interface KimiConfigResult {

package/dist/config/kimi-config.js

@@ -8,8 +8,11 @@ import { getLogger } from '../logger/index.js';
 import { spawnProcessSync } from '../platform/spawn.js';
 /** Valid thinking effort values for kimi (Layer 1: Schema enum source) */
 export const KIMI_THINKING_EFFORTS = ['low', 'high', 'max'];
-/** Fallback efforts when all values are filtered out */
-export const FALLBACK_EFFORTS = ['low', 'high', 'max'];
+/**
+ * 兜底 effort 全集就是 schema 枚举本身（不是另一份字面量，否则新增取值要改两处）。
+ * 类型放宽为 readonly string[]：消费侧拿的是外部输入过滤后的兜底列表，不做枚举窄化。
+ */
+export const FALLBACK_EFFORTS = KIMI_THINKING_EFFORTS;
 /** 清空缓存（仅供测试使用，生产代码无调用点） */
 export function invalidateKimiConfigCache() {
     kimiConfigCache = null;

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

@@ -6,14 +6,8 @@
 interface PiProviderInfo {
     /** Provider 名称 */
     name: string;
-    /** API 端点（可选） */
-    baseUrl?: string;
-    /** API 类型 */
-    api?: string;
     /** 该 provider 下的模型列表 */
     models: string[];
-    /** 是否有认证信息 */
-    isAuthenticated: boolean;
 }
 /** loadPiConfig() 的返回类型，包含 provider 和 model 的聚合信息 */
 export interface PiConfigResult {
@@ -29,7 +23,8 @@ export declare function _getAuthFilePath(): string;
 /**
  * 读取 pi 的 provider 和 model 配置
  *
- * @returns provider 列表，每个 provider 包含名称、模型列表和认证状态
+ * @returns provider 列表，每项含名称与其模型列表；auth.json 里有凭据但
+ * models.json 未声明的 provider 以空模型列出（只为让 provider 选项不丢）
  */
 export declare function loadPiProviderConfig(): PiProviderInfo[];
 /**

package/dist/config/pi-config.js

@@ -11,9 +11,12 @@ import path from 'node:path';
  * 默认 ~/.pi/agent。每次调用时动态读取环境变量，避免模块级缓存导致
  * singleFork 模式下测试设置 env 过晚（与 CLAUDE_SETTINGS_PATH 模式类似，
  * 但 pi-config 的常量原本在模块级求值，改为惰性求值以支持运行时切换）。
+ *
+ * 空串/纯空白按「未设置」处理：`??` 只挡 undefined，放过空串会让 models.json
+ * 解析成相对**进程 cwd** 的路径。
  */
 function getPiConfigDir() {
-    return process.env.PI_CONFIG_DIR ?? path.join(os.homedir(), '.pi', 'agent');
+    return process.env.PI_CONFIG_DIR?.trim() || path.join(os.homedir(), '.pi', 'agent');
 }
 /** @internal Exported for testing only — verify env var is respected. */
 export function _getModelsFilePath() {
@@ -55,7 +58,8 @@ function getPiModelFallback(provider) {
 /**
  * 读取 pi 的 provider 和 model 配置
  *
- * @returns provider 列表，每个 provider 包含名称、模型列表和认证状态
+ * @returns provider 列表，每项含名称与其模型列表；auth.json 里有凭据但
+ * models.json 未声明的 provider 以空模型列出（只为让 provider 选项不丢）
  */
 export function loadPiProviderConfig() {
     const results = new Map();
@@ -87,10 +91,7 @@ export function loadPiProviderConfig() {
         const cfg = config;
         results.set(name, {
             name,
-            baseUrl: cfg.baseUrl,
-            api: cfg.api,
             models: (cfg.models ?? []).map((m) => m.id),
-            isAuthenticated: !!authData[name],
         });
     }
     // 4. 对于 auth.json 中有凭据但未在 models.json 中定义的 provider
@@ -100,7 +101,6 @@ export function loadPiProviderConfig() {
             results.set(name, {
                 name,
                 models: [],
-                isAuthenticated: true,
             });
         }
     }

package/dist/config/wizard.js

@@ -5,6 +5,7 @@ import YAML from 'yaml';
 import { AppConfigSchema } from './index.js';
 import { needsQrImage, renderQrImage, renderTerminalQr } from './qr.js';
 import { silentlyUnlink } from '../common/fs.js';
+import { atomicWrite } from '../persistence/atomic-write.js';
 /** Where the fallback QR image is written (next to the config it will seed). */
 const QR_IMAGE_NAME = 'qr-code.gif';
 /**
@@ -96,12 +97,15 @@ function hasFeishuCredentials(configPath) {
     const feishu = parsed?.feishu;
     return Boolean(feishu && feishu.appId && feishu.appSecret);
 }
-/** Persist a full config file seeded with the given feishu credentials. */
+/**
+ * Persist a full config file seeded with the given feishu credentials.
+ *
+ * 走 atomicWrite（tmp+rename）而不是裸 writeFileSync：这份文件里有 appSecret，
+ * 半截落盘 = 下次启动读不出凭据 + 盘上留着残密钥。目录创建由 atomicWrite 负责。
+ */
 function writeConfigWithCredentials(configPath, appId, appSecret) {
-    const dir = path.dirname(configPath);
-    fs.mkdirSync(dir, { recursive: true });
     const config = AppConfigSchema.parse({ feishu: { appId, appSecret } });
-    fs.writeFileSync(configPath, YAML.stringify(config), 'utf-8');
+    atomicWrite(configPath, YAML.stringify(config));
 }
 /**
  * Ensure a usable config exists before `loadConfig` is called.

package/dist/connector/index.d.ts

@@ -158,6 +158,15 @@ export declare class FeishuConnector {
     streamCard(chatId: string, initial: object, producer: CardStreamProducer, opts?: {
         replyTo?: string;
     }): Promise<string>;
+    /**
+     * 原地替换已发消息的卡片内容。
+     *
+     * 走 `rawClient.im.v1.message.patch` 而不是 `channel.updateCard()`，唯一目的就是
+     * 拿到返回值：飞书的业务码拒绝以 HTTP 200 + `{code!=0}` 返回，SDK 的 `patchCard`
+     * 把返回值丢了，调用方于是拿到假成功（卡片定格在被打回的那一帧，用户却收到
+     * 「已保存」）。抛出去让 `bridge.updateCardInPlace()` 的 catch 走 sendResult 兜底。
+     * `rawClient` 缺失（测试 mock）时回退 SDK 入口，行为退化为「看不见业务码」。
+     */
     updateCard(messageId: string, card: object): Promise<void>;
     /** Format error for logging without causing circular serialization */
     private formatError;
@@ -180,6 +189,8 @@ export declare class FeishuConnector {
      * 标签（'sendFile' | 'sendImage'）。
      */
     private uploadAndSendMedia;
+    /** 单次「上传 + 发媒体消息」；文件流在此拥有，任何失败路径都销毁（P2-18）。 */
+    private uploadWithToken;
     /**
      * Upload a file to Feishu and send it to the specified chat.
      * Uses the im/v1/files upload API.
@@ -196,9 +207,17 @@ export declare class FeishuConnector {
      * 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）。
      */
     private cachedToken;
     private cachedTokenExpireAt;
+    /** 在途的取 token 请求：并发发送合流成一次请求（飞书该端点有限流）。 */
+    private tokenFetch;
     private getTenantAccessToken;
+    /** 清掉缓存的 token：鉴权被拒时旧值已经没有价值，留着只会继续失败。 */
+    private invalidateTenantToken;
+    private fetchTenantAccessToken;
 }
 export {};