@ai-zen/cli 1.0.0-alpha.9 → 1.0.0

package/dist/config.d.ts

@@ -17,6 +17,13 @@
  *       ├── conversations/        ← 对话记录
  *       └── last-session.json     ← 「各 cwd 上一轮会话 id」指针（cwd → id）
  *
+ *   项目/.ai-zen/                 ← 项目级配置与产物
+ *   ├── skills/                   ← 项目级 Skill
+ *   ├── tools/                    ← 项目级工具
+ *   ├── sub-agents/               ← 项目级子 Agent
+ *   ├── mcp.json                  ← 项目级 MCP 配置
+ *   └── handoffs/                 ← 交接文档（任务交接的落盘产物）
+ *
  *   ~/.agents/                    ← 业界通用规范（如 Cursor、Windsurf、Cline）
  *   ├── skills/                   ← 用户级 Skill
  *   └── mcp.json                  ← 用户级 MCP 配置
@@ -38,28 +45,57 @@
  *     3. ~/.ai-zen/skills/
  *     4. ~/.agents/skills/
  */
-import type { AppConfig } from "@ai-zen/agents-sdk";
-export declare const AI_ZEN_DIR: string;
-export declare const CLI_DIR: string;
-export declare const CONFIG_FILE: string;
-export declare const CONVERSATIONS_DIR: string;
-export declare const AGENTS_DIR: string;
-export declare const SUB_AGENTS_DIR: string;
-export declare const SKILLS_DIR: string;
-export declare const TOOLS_DIR: string;
+import type { AppConfig, ReasoningPresets } from "@ai-zen/agents-sdk";
+/**
+ * 全部路径都导出为 `let`：ESM 的 import 是**活绑定**，导入方每次取值都读到最新值
+ * （实测：跨模块 import 的常量在 `refreshPaths()` 之后立刻是新目录），所以 `refreshPaths()`
+ * 不需要召回任何引用点。
+ *
+ * **会失效的是快照**：在模块顶层把路径塞进常量或实例（`const POINTER_FILE = join(CLI_DIR, …)`、
+ * `new Repo(CONVERSATIONS_DIR)`、`new ConfigManager(CONFIG_FILE)`）—— 那个值在模块求值那一刻就定死了。
+ * 这类地方一律改成函数（`pointerFile()` / `conversationRepository()` / `configManager()`），
+ * 由调用时机决定读哪个目录。
+ */
+export declare let AI_ZEN_DIR: string;
+export declare let CLI_DIR: string;
+export declare let CONFIG_FILE: string;
+export declare let CONVERSATIONS_DIR: string;
+export declare let AGENTS_DIR: string;
+export declare let SUB_AGENTS_DIR: string;
+export declare let SKILLS_DIR: string;
+export declare let TOOLS_DIR: string;
 export declare const PROJECT_SUB_AGENTS_DIR: string;
 export declare const PROJECT_SKILLS_DIR: string;
 export declare const PROJECT_TOOLS_DIR: string;
-export declare const USER_AGENTS_SKILLS_DIR: string;
-export declare const USER_AGENTS_MCP_CONFIG_FILE: string;
+/**
+ * 交接文档目录（项目级）：`<cwd>/.ai-zen/handoffs/`。
+ *
+ * 交接文档是「人也能直接读」的产物，放在项目内便于随仓库共享/评审；
+ * 目录由交接时的 write 工具或服务落盘时自动创建，无需预先建立。
+ */
+export declare const PROJECT_HANDOFFS_DIR: string;
+export declare let USER_AGENTS_SKILLS_DIR: string;
+export declare let USER_AGENTS_MCP_CONFIG_FILE: string;
 export declare const PROJECT_AGENTS_DIR: string;
 export declare const PROJECT_AGENTS_SKILLS_DIR: string;
 export declare const PROJECT_AGENTS_MCP_CONFIG_FILE: string;
-export declare const MCP_CONFIG_FILE: string;
+export declare let MCP_CONFIG_FILE: string;
 export declare const PROJECT_MCP_CONFIG_FILE: string;
 export declare const SHARED_MCP_CONFIG_FILE: string;
 /**
- * 确保配置目录和默认文件存在。
+ * 重新解析全部路径（**仅测试使用**）。
+ *
+ * 生产代码从不在运行期改 `AI_ZEN_DIR`，所以业务路径上不需要调用它。它存在只是因为
+ * 测试会给每个用例换一个临时目录，而进程内共享模块（`vitest isolate: false`）时，
+ * 模块顶层的路径常量只在首次加载时算过一次。
+ *
+ * 调用后：导入方靠活绑定自动看到新值（见文件顶部注释）；持有快照的模块由各自的
+ * 工厂/重置负责 —— 测试侧统一走 `src/test-support/temp-dir.ts` 的 `useTempAiZenDir()`，
+ * 它保证「设 env + 刷新路径 + 收尾还原」三件事一起做。
+ */
+export declare function refreshPaths(): void;
+/**
+ * 确保配置目录和默认文件存在（进程内只真正执行一次）。
  *
  * 共享实体（Agent、SubAgent、Skill 目录等）委托给 SDK 的 ConfigManager.bootstrap()。
  * CLI 自身的运行时目录（conversations/）由本函数额外创建。
@@ -67,6 +103,13 @@ export declare const SHARED_MCP_CONFIG_FILE: string;
  */
 export declare function ensureConfigDir(): Promise<void>;
 export declare function readConfig(): Promise<AppConfig>;
+/**
+ * 读取思考策略表（`~/.ai-zen/reasoning-presets.json`）。
+ *
+ * 这张表**只属于 CLI**：档位与参数补丁的对应关系是产品的编织知识，不在 SDK 里。
+ * 文件缺失或损坏时回落到出厂种子。
+ */
+export declare function readReasoningPresets(): Promise<ReasoningPresets>;
 export declare function saveConfig(config: AppConfig): Promise<void>;
 /** MCP 配置的作用域：全局（~/.ai-zen/mcp.json） / 项目（<cwd>/.ai-zen/mcp.json） */
 export type McpScope = "global" | "project";
@@ -101,10 +144,26 @@ export interface McpConfig {
 /** 作用域对应的 mcp.json 路径 */
 export declare function mcpConfigPath(scope: McpScope): string;
 /**
- * 读取指定路径的 mcp.json，不存在 / 解析失败时返回空结构。
+ * 读取 mcp.json 的结果。
+ *
+ * 「文件不存在」与「读取 / 解析失败」必须分开：前者是正常的空配置，后者是文件已损坏。
+ * 以前两者都返回 `{ mcpServers: {} }`，于是损坏的文件在配置中心里看起来「没有服务器」，
+ * 用户一保存就把原内容整个覆盖掉 —— 静默丢数据。
+ */
+export type McpReadResult = {
+    ok: true;
+    config: McpConfig;
+} | {
+    ok: false;
+    error: string;
+};
+/** 读失败时按空配置继续（仅用于「读来只为做判断」的场景；界面上要显示损坏由编辑屏负责） */
+export declare function mcpConfigOrEmpty(result: McpReadResult): McpConfig;
+/**
+ * 读取指定路径的 mcp.json。
  * 采用业界标准 `mcpServers` 顶层字段（与 SDK discoverMcpServers 一致）。
  */
-export declare function readMcpConfigAt(path: string): Promise<McpConfig>;
+export declare function readMcpConfigAt(path: string): Promise<McpReadResult>;
 /**
  * 原子写入指定路径的 mcp.json（必要时创建父目录）。
  */
@@ -112,11 +171,11 @@ export declare function writeMcpConfigAt(path: string, mcpConfig: McpConfig): Pr
 /**
  * 读取某个作用域的 mcp.json（默认全局 ~/.ai-zen/mcp.json）。
  */
-export declare function readMcpConfig(scope?: McpScope): Promise<McpConfig>;
+export declare function readMcpConfig(scope?: McpScope): Promise<McpReadResult>;
 /**
  * 原子写入某个作用域的 mcp.json（默认全局 ~/.ai-zen/mcp.json）。
  */
 export declare function writeMcpConfig(mcpConfig: McpConfig, scope?: McpScope): Promise<void>;
 /** 读取项目级 <cwd>/.ai-zen/mcp.json（等价于 readMcpConfig("project")） */
-export declare function readProjectMcpConfig(): Promise<McpConfig>;
+export declare function readProjectMcpConfig(): Promise<McpReadResult>;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAgBtE;;;;;;;;;GASG;AACH,eAAO,IAAI,UAAU,QAAgB,CAAC;AAItC,eAAO,IAAI,OAAO,QAA0B,CAAC;AAC7C,eAAO,IAAI,WAAW,QAAkC,CAAC;AACzD,eAAO,IAAI,iBAAiB,QAAiC,CAAC;AAI9D,eAAO,IAAI,UAAU,QAA6B,CAAC;AACnD,eAAO,IAAI,cAAc,QAAiC,CAAC;AAC3D,eAAO,IAAI,UAAU,QAA6B,CAAC;AACnD,eAAO,IAAI,SAAS,QAA4B,CAAC;AAIjD,eAAO,MAAM,sBAAsB,QAA+C,CAAC;AACnF,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,iBAAiB,QAA0C,CAAC;AACzE;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,QAA6C,CAAC;AAU/E,eAAO,IAAI,sBAAsB,QAAkC,CAAC;AACpE,eAAO,IAAI,2BAA2B,QAAoC,CAAC;AAI3E,eAAO,MAAM,kBAAkB,QAAiC,CAAC;AACjE,eAAO,MAAM,yBAAyB,QAAqC,CAAC;AAC5E,eAAO,MAAM,8BAA8B,QAAuC,CAAC;AAInF,eAAO,IAAI,eAAe,QAA+B,CAAC;AAC1D,eAAO,MAAM,uBAAuB,QAA6C,CAAC;AAClF,eAAO,MAAM,sBAAsB,QAAmC,CAAC;AA2BvE;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,IAAI,IAAI,CAenC;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CASrD;AAoBD,wBAAsB,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAGrD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAGtE;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAGjE;AAID,qEAAqE;AACrE,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,KAAK,CAAC;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,6CAA6C;IAC7C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,0DAA0D;IAC1D,UAAU,EAAE,aAAa,CAAC;CAC3B;AAED,yBAAyB;AACzB,wBAAgB,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAErD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3F,iDAAiD;AACjD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAe1E;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,KAAK,GAAE,QAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEtF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,GAAE,QAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAEpG;AAED,iEAAiE;AACjE,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,aAAa,CAAC,CAEnE"}

package/dist/config.js

@@ -17,6 +17,13 @@
  *       ├── conversations/        ← 对话记录
  *       └── last-session.json     ← 「各 cwd 上一轮会话 id」指针（cwd → id）
  *
+ *   项目/.ai-zen/                 ← 项目级配置与产物
+ *   ├── skills/                   ← 项目级 Skill
+ *   ├── tools/                    ← 项目级工具
+ *   ├── sub-agents/               ← 项目级子 Agent
+ *   ├── mcp.json                  ← 项目级 MCP 配置
+ *   └── handoffs/                 ← 交接文档（任务交接的落盘产物）
+ *
  *   ~/.agents/                    ← 业界通用规范（如 Cursor、Windsurf、Cline）
  *   ├── skills/                   ← 用户级 Skill
  *   └── mcp.json                  ← 用户级 MCP 配置
@@ -40,94 +47,191 @@
  */
 import { promises as fs } from "fs";
 import { dirname, join } from "path";
-import { ConfigManager as SdkConfigManager } from "@ai-zen/agents-sdk";
+import { ConfigManager as SdkConfigManager, getLogger } from "@ai-zen/agents-sdk";
+import { t } from "./i18n/index.js";
 // ==================== 根目录 ====================
-export const AI_ZEN_DIR = process.env.AI_ZEN_DIR || join(process.env.HOME || process.env.USERPROFILE || "", ".ai-zen");
+/**
+ * 解析配置根目录：显式 `AI_ZEN_DIR` 优先，否则 `$HOME/.ai-zen`。
+ *
+ * 单独抽成函数是为了让 {@link refreshPaths} 能在测试用例之间重算。
+ */
+function resolveRoot() {
+    return (process.env.AI_ZEN_DIR || join(process.env.HOME || process.env.USERPROFILE || "", ".ai-zen"));
+}
+/**
+ * 全部路径都导出为 `let`：ESM 的 import 是**活绑定**，导入方每次取值都读到最新值
+ * （实测：跨模块 import 的常量在 `refreshPaths()` 之后立刻是新目录），所以 `refreshPaths()`
+ * 不需要召回任何引用点。
+ *
+ * **会失效的是快照**：在模块顶层把路径塞进常量或实例（`const POINTER_FILE = join(CLI_DIR, …)`、
+ * `new Repo(CONVERSATIONS_DIR)`、`new ConfigManager(CONFIG_FILE)`）—— 那个值在模块求值那一刻就定死了。
+ * 这类地方一律改成函数（`pointerFile()` / `conversationRepository()` / `configManager()`），
+ * 由调用时机决定读哪个目录。
+ */
+export let AI_ZEN_DIR = resolveRoot();
 // ==================== CLI 运行时目录 ====================
-export const CLI_DIR = join(AI_ZEN_DIR, "cli");
-export const CONFIG_FILE = join(AI_ZEN_DIR, "config.json");
-export const CONVERSATIONS_DIR = join(CLI_DIR, "conversations");
+export let CLI_DIR = join(AI_ZEN_DIR, "cli");
+export let CONFIG_FILE = join(AI_ZEN_DIR, "config.json");
+export let CONVERSATIONS_DIR = join(CLI_DIR, "conversations");
 // ==================== 共享目录 ====================
-export const AGENTS_DIR = join(AI_ZEN_DIR, "agents");
-export const SUB_AGENTS_DIR = join(AI_ZEN_DIR, "sub-agents");
-export const SKILLS_DIR = join(AI_ZEN_DIR, "skills");
-export const TOOLS_DIR = join(AI_ZEN_DIR, "tools");
+export let AGENTS_DIR = join(AI_ZEN_DIR, "agents");
+export let SUB_AGENTS_DIR = join(AI_ZEN_DIR, "sub-agents");
+export let SKILLS_DIR = join(AI_ZEN_DIR, "skills");
+export let TOOLS_DIR = join(AI_ZEN_DIR, "tools");
 // ==================== 项目级目录（基于 CWD）====================
 export const PROJECT_SUB_AGENTS_DIR = join(process.cwd(), ".ai-zen", "sub-agents");
 export const PROJECT_SKILLS_DIR = join(process.cwd(), ".ai-zen", "skills");
 export const PROJECT_TOOLS_DIR = join(process.cwd(), ".ai-zen", "tools");
+/**
+ * 交接文档目录（项目级）：`<cwd>/.ai-zen/handoffs/`。
+ *
+ * 交接文档是「人也能直接读」的产物，放在项目内便于随仓库共享/评审；
+ * 目录由交接时的 write 工具或服务落盘时自动创建，无需预先建立。
+ */
+export const PROJECT_HANDOFFS_DIR = join(process.cwd(), ".ai-zen", "handoffs");
 // ==================== 业界通用规范 ~/.agents/ 目录 ====================
-const USER_AGENTS_DIR = join(process.env.HOME || process.env.USERPROFILE || "", ".agents");
-export const USER_AGENTS_SKILLS_DIR = join(USER_AGENTS_DIR, "skills");
-export const USER_AGENTS_MCP_CONFIG_FILE = join(USER_AGENTS_DIR, "mcp.json");
+function resolveUserAgentsDir() {
+    return join(process.env.HOME || process.env.USERPROFILE || "", ".agents");
+}
+let USER_AGENTS_DIR = resolveUserAgentsDir();
+export let USER_AGENTS_SKILLS_DIR = join(USER_AGENTS_DIR, "skills");
+export let USER_AGENTS_MCP_CONFIG_FILE = join(USER_AGENTS_DIR, "mcp.json");
 // ==================== 业界通用规范 项目/.agents/ 目录 ====================
 export const PROJECT_AGENTS_DIR = join(process.cwd(), ".agents");
 export const PROJECT_AGENTS_SKILLS_DIR = join(PROJECT_AGENTS_DIR, "skills");
 export const PROJECT_AGENTS_MCP_CONFIG_FILE = join(PROJECT_AGENTS_DIR, "mcp.json");
 // ==================== MCP 配置 ====================
-export const MCP_CONFIG_FILE = join(AI_ZEN_DIR, "mcp.json");
+export let MCP_CONFIG_FILE = join(AI_ZEN_DIR, "mcp.json");
 export const PROJECT_MCP_CONFIG_FILE = join(process.cwd(), ".ai-zen", "mcp.json");
 export const SHARED_MCP_CONFIG_FILE = join(process.cwd(), ".mcp.json");
 // ==================== SDK ConfigManager ====================
-const sdkConfigMgr = new SdkConfigManager(CONFIG_FILE);
+/**
+ * 按**当前** `CONFIG_FILE` 造一个 ConfigManager。
+ *
+ * 不缓存实例：`ConfigManager` 在构造时固化路径，缓存它等于把路径也缓存了 ——
+ * 进程内共享模块时（测试换 `AI_ZEN_DIR`）就会一直读写旧目录。构造本身很轻，
+ * 重活（bootstrap / 解析）在 `read()` 里，且由 `ensureConfigDir()` 兜住只做一次。
+ */
+function configManager() {
+    return new SdkConfigManager(CONFIG_FILE);
+}
 // ==================== 目录初始化 ====================
 /**
- * 确保配置目录和默认文件存在。
+ * 一次性初始化的 Promise（进程生命周期内只跑一次）。
+ *
+ * 为什么必须缓存 **Promise** 而不是「已初始化」布尔：`readConfig()` 内部就会调它，而
+ * `readConfig()` 被 TUI 的 effect、命令层、`createAgent()`、`getScope()` 反复调用 ——
+ * 等于每次读配置都重跑一遍全量初始化（bootstrap + 多次 stat/mkdir）。而布尔判据在
+ * `await` 窗口期内不成立，并发调用会一起穿透、重复 bootstrap。
+ */
+let initPromise = null;
+/**
+ * 重新解析全部路径（**仅测试使用**）。
+ *
+ * 生产代码从不在运行期改 `AI_ZEN_DIR`，所以业务路径上不需要调用它。它存在只是因为
+ * 测试会给每个用例换一个临时目录，而进程内共享模块（`vitest isolate: false`）时，
+ * 模块顶层的路径常量只在首次加载时算过一次。
+ *
+ * 调用后：导入方靠活绑定自动看到新值（见文件顶部注释）；持有快照的模块由各自的
+ * 工厂/重置负责 —— 测试侧统一走 `src/test-support/temp-dir.ts` 的 `useTempAiZenDir()`，
+ * 它保证「设 env + 刷新路径 + 收尾还原」三件事一起做。
+ */
+export function refreshPaths() {
+    AI_ZEN_DIR = resolveRoot();
+    CLI_DIR = join(AI_ZEN_DIR, "cli");
+    CONFIG_FILE = join(AI_ZEN_DIR, "config.json");
+    CONVERSATIONS_DIR = join(CLI_DIR, "conversations");
+    AGENTS_DIR = join(AI_ZEN_DIR, "agents");
+    SUB_AGENTS_DIR = join(AI_ZEN_DIR, "sub-agents");
+    SKILLS_DIR = join(AI_ZEN_DIR, "skills");
+    TOOLS_DIR = join(AI_ZEN_DIR, "tools");
+    MCP_CONFIG_FILE = join(AI_ZEN_DIR, "mcp.json");
+    USER_AGENTS_DIR = resolveUserAgentsDir();
+    USER_AGENTS_SKILLS_DIR = join(USER_AGENTS_DIR, "skills");
+    USER_AGENTS_MCP_CONFIG_FILE = join(USER_AGENTS_DIR, "mcp.json");
+    // 一次性初始化缓存是按旧目录算的，必须作废，否则新目录永远不会被 bootstrap
+    initPromise = null;
+}
+/**
+ * 确保配置目录和默认文件存在（进程内只真正执行一次）。
  *
  * 共享实体（Agent、SubAgent、Skill 目录等）委托给 SDK 的 ConfigManager.bootstrap()。
  * CLI 自身的运行时目录（conversations/）由本函数额外创建。
  * SDK 的出厂默认配置会自动写入 config.json（如果不存在）。
  */
 export async function ensureConfigDir() {
-    // SDK bootstrap：目录 + config.json + default Agent + default SubAgent
-    await sdkConfigMgr.bootstrap();
-    // CLI 运行时目录
-    const cliDirs = [CLI_DIR, CONVERSATIONS_DIR];
-    for (const dir of cliDirs) {
+    if (!initPromise) {
+        initPromise = initOnce().catch((error) => {
+            // 失败不缓存：否则一次瞬时故障（如磁盘短暂只读）会让整个进程永久失能
+            initPromise = null;
+            throw error;
+        });
+    }
+    return initPromise;
+}
+async function initOnce() {
+    // SDK bootstrap：目录 + config.json + default Agent + default SubAgent + 出厂思考策略表
+    await configManager().bootstrap();
+    // CLI 运行时目录（recursive 模式已存在时不报错，无需先 access 探测）
+    for (const dir of [CLI_DIR, CONVERSATIONS_DIR]) {
         try {
-            await fs.access(dir);
+            await fs.mkdir(dir, { recursive: true });
         }
-        catch {
-            try {
-                await fs.mkdir(dir, { recursive: true });
-            }
-            catch {
-                console.warn(`⚠️  无法创建目录: ${dir}`);
-            }
+        catch (error) {
+            // 走统一日志出口：TUI 下已改道落盘、stdio 下走 stderr。
+            // 这里不能用 console.warn —— 那会绕过日志系统，界面里看不见、日志文件里也查不到。
+            getLogger().warn(t("app.mkdirFailed", { dir, error: error?.message ?? error }));
         }
     }
 }
 // ==================== 配置读写 ====================
 export async function readConfig() {
     await ensureConfigDir();
-    return await sdkConfigMgr.read();
+    return await configManager().read();
+}
+/**
+ * 读取思考策略表（`~/.ai-zen/reasoning-presets.json`）。
+ *
+ * 这张表**只属于 CLI**：档位与参数补丁的对应关系是产品的编织知识，不在 SDK 里。
+ * 文件缺失或损坏时回落到出厂种子。
+ */
+export async function readReasoningPresets() {
+    // 表归 SDK 管（CLI / 桌面端共享），此处只做透传；缺失/损坏时 SDK 会回落出厂种子
+    return await configManager().readReasoningPresets();
 }
 export async function saveConfig(config) {
     await ensureConfigDir();
-    await sdkConfigMgr.write(config);
+    await configManager().write(config);
 }
 /** 作用域对应的 mcp.json 路径 */
 export function mcpConfigPath(scope) {
     return scope === "project" ? PROJECT_MCP_CONFIG_FILE : MCP_CONFIG_FILE;
 }
+/** 读失败时按空配置继续（仅用于「读来只为做判断」的场景；界面上要显示损坏由编辑屏负责） */
+export function mcpConfigOrEmpty(result) {
+    return result.ok ? result.config : { mcpServers: {} };
+}
 /**
- * 读取指定路径的 mcp.json，不存在 / 解析失败时返回空结构。
+ * 读取指定路径的 mcp.json。
  * 采用业界标准 `mcpServers` 顶层字段（与 SDK discoverMcpServers 一致）。
  */
 export async function readMcpConfigAt(path) {
+    let raw;
     try {
-        await fs.access(path);
+        raw = await fs.readFile(path, "utf-8");
     }
-    catch {
-        return { mcpServers: {} };
+    catch (cause) {
+        // 只有「文件不存在」算正常空配置；权限 / 是目录这类真错误照样报上去
+        if (cause?.code === "ENOENT")
+            return { ok: true, config: { mcpServers: {} } };
+        return { ok: false, error: cause?.message ?? String(cause) };
     }
     try {
-        const raw = JSON.parse(await fs.readFile(path, "utf-8"));
-        // 兼容并归一：以 mcpServers 为准，缺失时回退到空的 mcpServers
-        return { mcpServers: raw.mcpServers ?? {} };
+        const parsed = JSON.parse(raw);
+        return { ok: true, config: { mcpServers: parsed.mcpServers ?? {} } };
     }
-    catch {
-        return { mcpServers: {} };
+    catch (cause) {
+        return { ok: false, error: cause?.message ?? String(cause) };
     }
 }
 /**

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/conversation-commands/registry.d.ts

@@ -13,12 +13,134 @@ export interface CommandMeta {
     /** 主命令名（不含 `/` 前缀），同时是处理函数表的键 */
     name: string;
     /** 等价别名（不含 `/` 前缀） */
-    aliases?: string[];
-    /** 一句话说明 */
-    description: string;
+    aliases?: readonly string[];
+    /**
+     * 一句话说明的 i18n key。
+     *
+     * 这里存 **key 而不是文案**：本模块是纯数据，加载时机靠前（甚至早于语言初始化），
+     * 存成文案就定死了「加载那一刻的语言」。渲染时由 `getCommandHints()` 用 `t()` 现取。
+     */
+    descriptionKey: string;
+    /**
+     * 执行期间会调用模型（较慢，几十秒）。
+     *
+     * 宿主据此**拦住输入框**：否则用户以为没反应、继续打字，按键会被静默吞进隐藏的
+     * 输入缓冲，等命令结束后才突然冒出来（迁移过程中出现过这个 bug）。
+     * 这是命令的属性而不是宿主的白名单 —— 新增命令只改本文件，宿主自动跟上。
+     */
+    blocksInput?: boolean;
 }
-/** 命令元数据表（数组顺序即展示顺序） */
+/**
+ * 命令元数据表（数组顺序即展示顺序）。
+ *
+ * 用 `as const` 声明以保留命令名的字面量类型，从而派生出 `CommandName`：
+ * 命令处理器表以 `Record<CommandName, …>` 声明，于是「新增命令但忘了写处理器」是
+ * **编译错误**，而不是运行时静默落到「未知命令」。
+ *
+ * 但 `as const` 的代价是联合类型里**没有别名的条目压根没有 `aliases` 字段**，
+ * 遍历时访问会报错。所以这里只把它作为内部字面量，对外导出的
+ * {@link COMMAND_REGISTRY} 放宽成 `readonly CommandMeta[]` —— 类型保护一分不少，
+ * 而所有遍历点都能直接读 `command.aliases`，不需要额外的取值 helper。
+ */
+declare const REGISTRY_ENTRIES: readonly [{
+    readonly name: "save";
+    readonly descriptionKey: "cmd.save.desc";
+}, {
+    readonly name: "load";
+    readonly descriptionKey: "cmd.load.desc";
+}, {
+    readonly name: "new";
+    readonly descriptionKey: "cmd.new.desc";
+}, {
+    readonly name: "back";
+    readonly descriptionKey: "cmd.back.desc";
+}, {
+    readonly name: "editor";
+    readonly descriptionKey: "cmd.editor.desc";
+}, {
+    readonly name: "clear";
+    readonly descriptionKey: "cmd.clear.desc";
+}, {
+    readonly name: "config";
+    readonly descriptionKey: "cmd.config.desc";
+}, {
+    readonly name: "model";
+    readonly descriptionKey: "cmd.model.desc";
+}, {
+    readonly name: "agent";
+    readonly descriptionKey: "cmd.agent.desc";
+}, {
+    readonly name: "reload";
+    readonly descriptionKey: "cmd.reload.desc";
+}, {
+    readonly name: "update";
+    readonly descriptionKey: "cmd.update.desc";
+    readonly blocksInput: true;
+}, {
+    readonly name: "mcp";
+    readonly descriptionKey: "cmd.mcp.desc";
+}, {
+    readonly name: "lang";
+    readonly descriptionKey: "cmd.lang.desc";
+}, {
+    readonly name: "think";
+    readonly aliases: readonly ["effort"];
+    readonly descriptionKey: "cmd.think.desc";
+}, {
+    readonly name: "key";
+    readonly descriptionKey: "cmd.key.desc";
+}, {
+    readonly name: "handoff";
+    readonly descriptionKey: "cmd.handoff.desc";
+    readonly blocksInput: true;
+}, {
+    readonly name: "migrate";
+    readonly descriptionKey: "cmd.migrate.desc";
+    readonly blocksInput: true;
+}, {
+    readonly name: "help";
+    readonly descriptionKey: "cmd.help.desc";
+}, {
+    readonly name: "exit";
+    readonly aliases: readonly ["quit"];
+    readonly descriptionKey: "cmd.exit.desc";
+}];
+/** 命令主名的字面量联合（别名已归一到主名） */
+export type CommandName = (typeof REGISTRY_ENTRIES)[number]["name"];
+/** 命令元数据表：值来自上面的字面量，类型放宽到 `readonly CommandMeta[]` 便于遍历 */
 export declare const COMMAND_REGISTRY: readonly CommandMeta[];
+/**
+ * 把命令名（含别名）归一到主名；未知命令返回 `undefined`。
+ *
+ * `/think` 与 `/effort` 是同一条命令的两种写法，处理器只按主名注册一份。
+ */
+export declare function canonicalCommandName(name: string): CommandName | undefined;
+/** 命中命令的元数据（别名可查） */
+export declare function findCommand(name: string): CommandMeta | undefined;
+/** 该命令执行期间是否应拦住输入框（见 {@link CommandMeta.blocksInput}） */
+export declare function commandBlocksInput(name: string): boolean;
+/**
+ * 从原始输入里取命令参数（首个 token 之后的全部 token）。
+ *
+ * 与 {@link parseCommandInput} 共用 {@link splitCommandInput}，保证「命令名边界」与
+ * 「参数边界」用的是同一把尺子。
+ */
+export declare function parseCommandArgs(text: string): string[];
+/**
+ * 解析斜杠输入：`/migrate summary` → `{ name: "migrate", args: ["summary"] }`。
+ *
+ * 命令名的解析**只有这一处**：此前宿主自己也 `slice(1).split(/\s+/)[0]` 了一遍，
+ * 于是「命令名怎么算」在命令层与宿主层各有一份实现。
+ *
+ * 注意「只打了个 `/`」也算命令（`name` 为空串）：宿主按斜杠前缀分流，空命令名
+ * 落到「未知命令」——与拆出本函数之前的行为一致。
+ *
+ * @returns 非斜杠输入返回 `null`
+ */
+export declare function parseCommandInput(text: string): {
+    name: string;
+    args: string[];
+} | null;
 /** 命令展示条目：等价写法（如 `/exit` `/quit`）折叠为一条 */
 export interface CommandHint {
     /** 全部等价写法（不含 `/` 前缀），首个为主命令名 */
@@ -42,4 +164,5 @@ export declare const COMMAND_LABEL_WIDTH: number;
 export declare function matchCommandHints(keyword: string): CommandHint[];
 /** 全部命令名（含别名，升序），供启动横幅等场景展示 */
 export declare function getCommandNames(): string[];
+export {};
 //# sourceMappingURL=registry.d.ts.map

package/dist/conversation-commands/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/conversation-commands/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,iBAAiB;AACjB,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAwB;AACxB,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAalD,CAAC;AAEF,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAwB;AACxB,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAS/C;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACqC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAOhE;AAED,+BAA+B;AAC/B,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAM1C"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/conversation-commands/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,iBAAiB;AACjB,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,QAAA,MAAM,gBAAgB;mBACZ,MAAM;6BAAkB,eAAe;;mBACvC,MAAM;6BAAkB,eAAe;;mBACvC,KAAK;6BAAkB,cAAc;;mBACrC,MAAM;6BAAkB,eAAe;;mBACvC,QAAQ;6BAAkB,iBAAiB;;mBAC3C,OAAO;6BAAkB,gBAAgB;;mBACzC,QAAQ;6BAAkB,iBAAiB;;mBAC3C,OAAO;6BAAkB,gBAAgB;;mBACzC,OAAO;6BAAkB,gBAAgB;;mBACzC,QAAQ;6BAAkB,iBAAiB;;mBAC3C,QAAQ;6BAAkB,iBAAiB;;;mBAC3C,KAAK;6BAAkB,cAAc;;mBACrC,MAAM;6BAAkB,eAAe;;mBACvC,OAAO;;6BAAuC,gBAAgB;;mBAC9D,KAAK;6BAAkB,cAAc;;mBACrC,SAAS;6BAAkB,kBAAkB;;;mBAC7C,SAAS;6BAAkB,kBAAkB;;;mBAC7C,MAAM;6BAAkB,eAAe;;mBAEvC,MAAM;;6BAAqC,eAAe;EACzB,CAAC;AAE5C,2BAA2B;AAC3B,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,2DAA2D;AAC3D,eAAO,MAAM,gBAAgB,EAAE,SAAS,WAAW,EAAqB,CAAC;AAEzE;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAO1E;AAED,qBAAqB;AACrB,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAGjE;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAcD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAEvD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG,IAAI,CAIvF;AAED,0CAA0C;AAC1C,MAAM,WAAW,WAAW;IAC1B,gCAAgC;IAChC,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY;IACZ,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAwB;AACxB,wBAAgB,eAAe,IAAI,WAAW,EAAE,CAS/C;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QACqC,CAAC;AAEtE;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAOhE;AAED,+BAA+B;AAC/B,wBAAgB,eAAe,IAAI,MAAM,EAAE,CAM1C"}