lark-remote 0.4.4 → 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`。 */
@@ -59,11 +60,6 @@ type RegisterAppFn = (options: {
         status: string;
     }) => void;
 }) => Promise<RegisterAppResult>;
-/**
- * 默认新实例拉起：同入口 + 同参数，仅替换 --config-dir（detached，返回 pid）。
- * spawn 骨架（log fd / windowsHide / error 兜底）单源于 restart.ts。
- */
-export declare function spawnDetachedCloneBridge(targetDir: string): number | undefined;
 export interface CloneSessionOptions {
     connector: CloneConnector;
     /** 当前实例的 config.yaml 路径（配置复制源）。 */
@@ -111,7 +107,7 @@ export declare class CloneSession {
     /**
      * 扫码成功后的自动绑定落地：
      * 1. 复制当前 config.yaml，仅替换 feishu.appId/appSecret；
-     * 2. 同步 workspace / 常用指令 / 会话状态（session 按 openId 重绑）；
+     * 2. 同步 cwd / 常用指令 / 会话状态（session 按 openId 重绑）；
      * 3. 用 registerApp 返回的新应用 openId 写 startup-contact.json（免认领绑定）；
      * 4. detached 拉起指向新目录的新实例（启动后自动向新应用发启动通知）；
      * 5. 在原应用回执「绑定完成 + 配置目录」，退出流程。
@@ -131,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

@@ -6,7 +6,7 @@ import path from 'node:path';
 import YAML from 'yaml';
 import { getLogger } from './logger/index.js';
 import { renderQrImage } from './config/qr.js';
-import { silentlyUnlink } from './common/fs.js';
+import { bestEffortUnlink } from './common/fs.js';
 import { atomicWrite, atomicWriteJson } from './persistence/atomic-write.js';
 import { spawnDetachedBridge } from './restart.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;
@@ -48,7 +51,7 @@ export function generateCloneSuffix() {
  * 默认新实例拉起：同入口 + 同参数，仅替换 --config-dir（detached，返回 pid）。
  * spawn 骨架（log fd / windowsHide / error 兜底）单源于 restart.ts。
  */
-export function spawnDetachedCloneBridge(targetDir) {
+function spawnDetachedCloneBridge(targetDir) {
     const args = [];
     const argv = process.argv.slice(2);
     for (let i = 0; i < argv.length; i++) {
@@ -238,7 +241,7 @@ export class CloneSession {
             return;
         }
         finally {
-            silentlyUnlink(qrPath);
+            bestEffortUnlink(qrPath);
         }
         await this.connector
             .sendWithRetry(ctx.chatId, {
@@ -264,7 +267,7 @@ export class CloneSession {
     /**
      * 扫码成功后的自动绑定落地：
      * 1. 复制当前 config.yaml，仅替换 feishu.appId/appSecret；
-     * 2. 同步 workspace / 常用指令 / 会话状态（session 按 openId 重绑）；
+     * 2. 同步 cwd / 常用指令 / 会话状态（session 按 openId 重绑）；
      * 3. 用 registerApp 返回的新应用 openId 写 startup-contact.json（免认领绑定）；
      * 4. detached 拉起指向新目录的新实例（启动后自动向新应用发启动通知）；
      * 5. 在原应用回执「绑定完成 + 配置目录」，退出流程。
@@ -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/clamp.d.ts

@@ -0,0 +1,2 @@
+/** Clamp `v` into [min, max]. */
+export declare function clampInt(v: number, min: number, max: number): number;

package/dist/common/clamp.js

@@ -0,0 +1,5 @@
+/** Clamp `v` into [min, max]. */
+export function clampInt(v, min, max) {
+    return Math.min(Math.max(v, min), max);
+}
+//# sourceMappingURL=clamp.js.map

package/dist/common/fs.d.ts

@@ -1,11 +1,12 @@
 /**
- * Unlink a file, silently ignoring ENOENT and other errors.
+ * Unlink a file, swallowing errors instead of throwing to the caller.
  *
  * Use for cleanup paths (pid files, temp files, stale locks) where the
  * file may already be gone or was never created — a missing file is not
- * an error worth propagating.
+ * an error worth propagating. Not truly silent: gives up on busy files
+ * with a warning log (see below).
  */
-export declare function silentlyUnlink(path: string): void;
+export declare function bestEffortUnlink(path: string): void;
 export declare function isBusyError(err: unknown): boolean;
 export interface BusyRetryOptions {
     /** 平台注入（测试用）；默认当前宿主。占用重试仅 win32 生效 */

package/dist/common/fs.js

@@ -2,20 +2,21 @@ import fs from 'node:fs';
 import { getLogger } from '../logger/index.js';
 import { currentPlatform, isWin32 } from '../platform/select.js';
 /**
- * Unlink a file, silently ignoring ENOENT and other errors.
+ * Unlink a file, swallowing errors instead of throwing to the caller.
  *
  * Use for cleanup paths (pid files, temp files, stale locks) where the
  * file may already be gone or was never created — a missing file is not
- * an error worth propagating.
+ * an error worth propagating. Not truly silent: gives up on busy files
+ * with a warning log (see below).
  */
-export function silentlyUnlink(path) {
+export function bestEffortUnlink(path) {
     try {
         withBusyRetry(() => fs.unlinkSync(path));
     }
     catch (err) {
         // 占用放弃（win32 重试耗尽 / posix 首次占用即失败）：按设计「告警，
         // 不静默吞」，但清理路径不向调用方抛错（保持本函数契约）
-        getLogger().warn(`[fs] silentlyUnlink gave up on busy file ${path}: ${String(err)}`);
+        getLogger().warn(`[fs] bestEffortUnlink gave up on busy file ${path}: ${String(err)}`);
     }
 }
 /**

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

@@ -5,7 +5,7 @@ interface CliArgs {
     help?: boolean;
     version?: boolean;
     update?: boolean;
-    advanceHelp?: boolean;
+    advancedHelp?: boolean;
 }
 export declare function resolveConfigDir(configDirArg: string | undefined): string;
 export declare function getConfigDir(): string;
@@ -18,11 +18,10 @@ export declare function printVersion(): void;
 /** Print CLI help to stdout. */
 export declare function printHelp(): void;
 /**
- * Print advanced-config reference to stdout (CLI `--advance-help`).
+ * Print advanced-config reference to stdout (CLI `--advanced-help`).
  *
  * 目标读者是 coding agent（用户让 agent 代改 config.yaml）：披露所有
- * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。飞书侧
- * 等价命令为 /advancehelp（内容同源，卡片渲染）。
+ * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。
  */
-export declare function printAdvanceHelp(): void;
+export declare function printAdvancedHelp(): void;
 export {};

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];
@@ -52,8 +55,8 @@ export function parseCliArgs(args = process.argv.slice(2)) {
         else if (arg === '--dev') {
             result.dev = true;
         }
-        else if (arg === '--advance-help') {
-            result.advanceHelp = true;
+        else if (arg === '--advanced-help') {
+            result.advancedHelp = true;
         }
         else if (arg === '--update' || arg === 'update') {
             // 裸子命令等价形式：`lark-remote update` 与 `--update` 同义。
@@ -94,24 +97,23 @@ export function printHelp() {
         '  --settings <path>     指定 Claude 配置文件路径',
         '  --dev                 开发模式：标记从源码 bun src/index.ts 启动（看门狗据此选择拉起方式）',
         '  --update              升级到最新版本后退出（用于 cron/脚本自动化升级）',
-        '  --advance-help        高级配置参考：config.yaml 全部高级字段的语义与改法（面向 coding agent）',
+        '  --advanced-help        高级配置参考：config.yaml 全部高级字段的语义与改法（面向 coding agent）',
         '  -h, --help            显示本帮助信息',
         '  -v, --version         显示版本号',
     ];
     process.stdout.write(lines.join('\n') + '\n');
 }
 /**
- * Print advanced-config reference to stdout (CLI `--advance-help`).
+ * Print advanced-config reference to stdout (CLI `--advanced-help`).
  *
  * 目标读者是 coding agent（用户让 agent 代改 config.yaml）：披露所有
- * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。飞书侧
- * 等价命令为 /advancehelp（内容同源，卡片渲染）。
+ * /config 卡片未暴露的 YAML 字段——名称、默认值、语义、改法。
  */
-export function printAdvanceHelp() {
+export function printAdvancedHelp() {
     const configDir = resolveConfigDir(parseCliArgs().configDir);
-    const configPath = configDir + '/config.yaml';
+    const configPath = path.join(configDir, 'config.yaml');
     const lines = [
-        'lark-remote 高级配置参考（--advance-help）',
+        'lark-remote 高级配置参考（--advanced-help）',
         '',
         '目标读者：coding agent。用户把本输出交给 agent，agent 据此代改配置。',
         '',

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/config/wizard.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 import YAML from 'yaml';
 import { AppConfigSchema } from './index.js';
 import { needsQrImage, renderQrImage, renderTerminalQr } from './qr.js';
-import { silentlyUnlink } from '../common/fs.js';
+import { bestEffortUnlink } 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';
@@ -77,7 +77,7 @@ async function runRegistrationWizard(configPath) {
     }
     finally {
         if (wroteImage)
-            silentlyUnlink(imagePath);
+            bestEffortUnlink(imagePath);
     }
 }
 function isInteractiveTerminal() {