@ai-zen/agents-host 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/app.d.ts

@@ -211,6 +211,13 @@ export declare class HostApp {
     /** R50 的那条警告只说一次（描述的是装配能力，不是某一轮的错） */
     private handoffWarningSent;
     private constructor();
+    /**
+     * 报一条「配置文件坏了、已恢复出厂」（D32）。
+     *
+     * 恢复动作本身在读到坏文件那一刻就做完了（写回 + 用出厂配置），这里只负责让用户知道
+     * 自己被重置过 —— warning 是 PRD F-J2 要求上通知栏的那一档。
+     */
+    private noticeRecoveredConfig;
     /**
      * 造一个 `HostApp`（不监听）。
      *
@@ -327,7 +334,7 @@ export declare class HostApp {
     private createConversationRuntime;
     /** 素材转换要的实发模型与端点（F-H7 的判定依据：模型能不能看图、端点有没有 Files API） */
     private resolveModelContext;
-    /** 读配置；坏了就是 `config_invalid`（服务层读配置时也是这个口径） */
+    /** 读配置（`config.json` 坏了由 SDK 恢复出厂，D32） */
     private readConfig;
     /** 凭证校验：顺手记下「这条进程被用过」（握手成功即算） */
     private buildVerifier;

package/dist/app.js

@@ -86,6 +86,32 @@ export function readDiskVersion() {
     return null;
 }
 // ---------------------------------------------------------------------------
+// 配置文件恢复出厂的通知口
+// ---------------------------------------------------------------------------
+/**
+ * 配置文件坏了被恢复出厂时的通知口（D32）。
+ *
+ * `host.json` 与 `config.json` 的首次读都在通知服务之前（端口要在开库之前定下来，
+ * `bootstrap()` 在造对象之前），装配期发生的恢复先攒在这里；`HostApp` 造好之后 `attach()`
+ * 接上真正的通知，攒下的补发完，此后每恢复一次当场发一次。
+ */
+class ConfigRecoverySpool {
+    queued = [];
+    sink = null;
+    /** 交给 `readHostSettings` / `ConfigManager` 的那个回调 */
+    onRecovered = (path) => {
+        if (this.sink !== null)
+            return this.sink(path);
+        this.queued.push(path);
+    };
+    /** 接上通知口，并把攒下的那些补发完 */
+    async attach(sink) {
+        this.sink = sink;
+        for (const path of this.queued.splice(0))
+            await sink(path);
+    }
+}
+// ---------------------------------------------------------------------------
 // HostApp
 // ---------------------------------------------------------------------------
 export class HostApp {
@@ -425,6 +451,20 @@ export class HostApp {
         });
         this.hubForPush = this.hub;
     }
+    /**
+     * 报一条「配置文件坏了、已恢复出厂」（D32）。
+     *
+     * 恢复动作本身在读到坏文件那一刻就做完了（写回 + 用出厂配置），这里只负责让用户知道
+     * 自己被重置过 —— warning 是 PRD F-J2 要求上通知栏的那一档。
+     */
+    async noticeRecoveredConfig(path) {
+        await this.noticeService.create({
+            level: "warning",
+            code: "notice.configRecovered",
+            params: { path },
+            duration: null,
+        });
+    }
     /**
      * 造一个 `HostApp`（不监听）。
      *
@@ -434,8 +474,11 @@ export class HostApp {
      */
     static async create(options = {}) {
         const paths = resolvePaths(options.aiZenDir);
+        // 配置文件坏了就恢复出厂（D32）：恢复过的文件名先攒着，等通知服务起来再补一条 warning
+        const recoveries = new ConfigRecoverySpool();
         // D25 的中间那一档：只在这一档真的要被用到时才读（参数给了就不必读，坏文件也不该拦住显式端口）
-        const configPort = options.configPort ?? (options.port === undefined ? (await readHostSettings(paths)).port : undefined);
+        const configPort = options.configPort ??
+            (options.port === undefined ? (await readHostSettings(paths, recoveries.onRecovered)).port : undefined);
         await mkdir(paths.dataRoot, { recursive: true });
         await mkdir(paths.runDir, { recursive: true });
         await mkdir(paths.assetsDir, { recursive: true });
@@ -447,13 +490,14 @@ export class HostApp {
             await db.close();
             throw error;
         }
-        const configManager = new ConfigManager(paths.configFile);
+        const configManager = new ConfigManager(paths.configFile, recoveries.onRecovered);
         // SDK 口径的首次初始化：目录 + config.json + 默认助手 + 子 Agent + mcp.json + 出厂 Skill
         // + 思考策略表。已有文件不覆盖（用户自定义的助手定义 `custom: true` 原样保留）。
         await configManager.bootstrap();
         const logging = resolveLogger(options, paths);
+        let app;
         try {
-            return new HostApp(options, paths, db, configManager, configPort, logging.logger);
+            app = new HostApp(options, paths, db, configManager, configPort, logging.logger);
         }
         catch (error) {
             // 构造途中的抛出（端口不合法、接线造不出来）也要把库关掉：worker 线程不该被漏下
@@ -461,6 +505,9 @@ export class HostApp {
             await logging.own?.close();
             throw error;
         }
+        // 通知服务就位了：装配期恢复过出厂的那几份配置各补一条 warning
+        await recoveries.attach((path) => app.noticeRecoveredConfig(path));
+        return app;
     }
     // -------------------------------------------------------------------------
     // 启停
@@ -919,7 +966,7 @@ export class HostApp {
             : undefined;
         return { model: model ?? null, endpoint: endpoint ?? null };
     }
-    /** 读配置；坏了就是 `config_invalid`（服务层读配置时也是这个口径） */
+    /** 读配置（`config.json` 坏了由 SDK 恢复出厂，D32） */
     async readConfig() {
         return await this.configManager.read();
     }

package/dist/config.d.ts

@@ -1,3 +1,4 @@
+import type { ConfigRecoveredHandler } from "@ai-zen/agents-sdk";
 /**
  * 路径与监听的来源（plan §1 的 `config.ts` 契约）。
  *
@@ -90,8 +91,10 @@ export interface HostSettings {
 /**
  * 读 `<dataRoot>/host.json`。
  *
- * 三种情况分开：文件不在 → 空设置（这一档没说话）；读不出来 / 不是 JSON 对象 → `config_invalid`
- * （写坏了要让人看见，不能当没有，否则用户改完没有任何反馈）；`port` 在但不是可用端口 →
+ * 三种情况分开：文件不在 → 空设置（这一档没说话，静默）；读不出来 / 不是 JSON / 不是对象 →
+ * 就是坏文件，恢复出厂：先把坏文件改名留档为 `host.json.broken`、再写回一份合法的 `{}`、
+ * 再回调一次（D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件；留档是数据，不是兜底 ——
+ * 用户手写的端口设置得能查回来）；`port` 在但不是可用端口 →
  * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
  */
-export declare function readHostSettings(paths: HostPaths): Promise<HostSettings>;
+export declare function readHostSettings(paths: HostPaths, onRecovered?: ConfigRecoveredHandler): Promise<HostSettings>;

package/dist/config.js

@@ -1,4 +1,4 @@
-import { readFile } from "node:fs/promises";
+import { access, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { HostError } from "./wire/errors.js";
@@ -119,11 +119,13 @@ function invalidPort(field, value, source) {
 /**
  * 读 `<dataRoot>/host.json`。
  *
- * 三种情况分开：文件不在 → 空设置（这一档没说话）；读不出来 / 不是 JSON 对象 → `config_invalid`
- * （写坏了要让人看见，不能当没有，否则用户改完没有任何反馈）；`port` 在但不是可用端口 →
+ * 三种情况分开：文件不在 → 空设置（这一档没说话，静默）；读不出来 / 不是 JSON / 不是对象 →
+ * 就是坏文件，恢复出厂：先把坏文件改名留档为 `host.json.broken`、再写回一份合法的 `{}`、
+ * 再回调一次（D32：坏了就恢复出厂，下次启动不再遇到同一个坏文件；留档是数据，不是兜底 ——
+ * 用户手写的端口设置得能查回来）；`port` 在但不是可用端口 →
  * `config_invalid`（裁定 R67：显式给出的非法值报错，不静默回落）。
  */
-export async function readHostSettings(paths) {
+export async function readHostSettings(paths, onRecovered) {
     let raw;
     try {
         raw = await readFile(paths.hostConfigFile, "utf8");
@@ -132,29 +134,17 @@ export async function readHostSettings(paths) {
         // 文件不在是正常情况（绝大多数据根上就没有这份文件）
         if (isMissingFile(error))
             return {};
-        throw new HostError("config_invalid", {
-            messageKey: "config.fileBroken",
-            params: { path: paths.hostConfigFile, reason: "unreadable" },
-            detail: { path: paths.hostConfigFile, reason: "unreadable" },
-        });
+        return await recoverHostSettings(paths, onRecovered);
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new HostError("config_invalid", {
-            messageKey: "config.fileBroken",
-            params: { path: paths.hostConfigFile, reason: "not_json" },
-            detail: { path: paths.hostConfigFile, reason: "not_json" },
-        });
+        return await recoverHostSettings(paths, onRecovered);
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        throw new HostError("config_invalid", {
-            messageKey: "config.fileBroken",
-            params: { path: paths.hostConfigFile, reason: "not_an_object" },
-            detail: { path: paths.hostConfigFile, reason: "not_an_object" },
-        });
+        return await recoverHostSettings(paths, onRecovered);
     }
     const record = parsed;
     if (!Object.prototype.hasOwnProperty.call(record, "port") || record.port === null)
@@ -164,6 +154,39 @@ export async function readHostSettings(paths) {
         throw invalidPort("port", port, "host.json");
     return { port };
 }
+/**
+ * 坏掉之后恢复出厂：先把坏文件留档，再写回一份合法的 `{}`（＝默认端口、默认语言），再回调一次。
+ */
+async function recoverHostSettings(paths, onRecovered) {
+    await archiveBroken(paths.hostConfigFile);
+    await writeFile(paths.hostConfigFile, "{}\n", "utf8");
+    await onRecovered?.(paths.hostConfigFile);
+    return {};
+}
+/**
+ * 把坏掉的设置文件改名留档为 `host.json.broken`。
+ *
+ * 与 SDK 的 `ConfigManager.archiveBroken()` 同一条规则（三个配置文件同一口径）：同名残骸
+ * 已经在就带上时间戳（同一毫秒再撞上就补序号），不覆盖上一份残骸。
+ */
+async function archiveBroken(path) {
+    const base = `${path}.broken`;
+    let target = base;
+    for (let index = 0; await exists(target); index += 1) {
+        target = index === 0 ? `${base}.${Date.now()}` : `${base}.${Date.now()}-${index}`;
+    }
+    await rename(path, target);
+}
+/** 这个路径在不在（`access` 不抛就是在） */
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isMissingFile(error) {
     return (typeof error === "object" &&
         error !== null &&

package/dist/i18n/en.d.ts

@@ -34,6 +34,7 @@ export declare const en: {
     readonly "notice.upgradeRestarting": "Updated to {version}. Restarting now.";
     readonly "notice.logWarning": "Host warning: {summary}";
     readonly "notice.logError": "Host error: {summary}";
+    readonly "notice.configRecovered": "Config file {path} was broken; factory settings restored.";
     readonly "notice.handoffWritten": "Handoff document written to {path}.";
     readonly "notice.autoNamed": "Named this conversation \"{name}\".";
     readonly "notice.languageChanged": "This connection now speaks {language}.";

package/dist/i18n/en.js

@@ -39,6 +39,7 @@ export const en = {
     "notice.upgradeRestarting": "Updated to {version}. Restarting now.",
     "notice.logWarning": "Host warning: {summary}",
     "notice.logError": "Host error: {summary}",
+    "notice.configRecovered": "Config file {path} was broken; factory settings restored.",
     "notice.handoffWritten": "Handoff document written to {path}.",
     "notice.autoNamed": "Named this conversation \"{name}\".",
     "notice.languageChanged": "This connection now speaks {language}.",

package/dist/i18n/zh.d.ts

@@ -31,6 +31,7 @@ export declare const zh: {
     "notice.upgradeRestarting": string;
     "notice.logWarning": string;
     "notice.logError": string;
+    "notice.configRecovered": string;
     "notice.handoffWritten": string;
     "notice.autoNamed": string;
     "notice.languageChanged": string;

package/dist/i18n/zh.js

@@ -35,6 +35,7 @@ export const zh = {
     "notice.upgradeRestarting": "已更新到 {version}，现在重启。",
     "notice.logWarning": "宿主警告：{summary}",
     "notice.logError": "宿主错误：{summary}",
+    "notice.configRecovered": "配置文件 {path} 坏了，已恢复出厂设置。",
     "notice.handoffWritten": "交接文档已写到 {path}。",
     "notice.autoNamed": "给这段对话起名叫「{name}」。",
     "notice.languageChanged": "这条连接现在说{language}。",

package/dist/runtime/ChatRunner.js

@@ -332,7 +332,7 @@ class TurnSession {
         const agent = await this.createAgent({
             conversationId: this.conversationId,
             workspaceId: this.conversation.workspaceId,
-            agentId: this.conversation.agentId ?? "",
+            agentId: this.conversation.agentId,
             modelId: this.conversation.modelId,
             thinkingLevel: this.conversation.thinkingLevel,
             scope: this.scope,
@@ -1089,7 +1089,7 @@ export class ChatRunner {
         }
         return prepare({
             conversationId: conversation.id,
-            agentId: conversation.agentId ?? "",
+            agentId: conversation.agentId,
             modelId: conversation.modelId,
             input: params.input,
         });

package/dist/services/ConfigService.js

@@ -601,7 +601,12 @@ export class ConfigService {
 // ---------------------------------------------------------------------------
 // 纯函数
 // ---------------------------------------------------------------------------
-/** 端点定义 → 对外形状（密钥只给掩码，F-F2） */
+/**
+ * 端点定义 → 对外形状（密钥只给掩码，F-F2）。
+ *
+ * `apiKey` 在类型上是必填，但 `config.json` 是手改得了的：SDK 的读法是 `JSON.parse as AppConfig`，
+ * 不补字段。少写这一行的配置会走到 `?? ""`（界面显示「未设置密钥」，而不是整页读不出来）。
+ */
 function toEndpointView(endpoint) {
     const apiKey = endpoint.apiKey ?? "";
     return {

package/dist/services/ConversationService.d.ts

@@ -217,8 +217,8 @@ export declare class ConversationService {
     /**
      * 读配置。
      *
-     * `config.json` 是手改得了的文件（F-G3 的同款思路）：它坏了要让用户看见「配置用不了 +
-     * 哪一步读不动」，而不是一句「宿主内部错误」——所以解析失败在这里就折成 `config_invalid`。
+     * `config.json` 是手改得了的文件，它坏了由 SDK 当场恢复出厂（D32），所以这里不再把
+     * 解析失败折成别的错——读到的要么是磁盘上那份，要么是已经写回磁盘的出厂配置。
      */
     private readConfig;
     private viewContext;

package/dist/services/ConversationService.js

@@ -578,8 +578,8 @@ export class ConversationService {
             name: row.name,
             nameIsAuto: row.nameIsAuto,
             pinned: row.pinned,
-            agentId: row.agentId ?? "",
-            modelId: row.modelId ?? "",
+            agentId: row.agentId,
+            modelId: row.modelId,
             createdAt: iso(row.createdAt),
             updatedAt: iso(row.updatedAt),
             // 这个数来自 `listByConversation` 的长度：只有**主线**消息（不含子 Agent 的，那些在同一个
@@ -599,9 +599,9 @@ export class ConversationService {
         const agent = await this.loadAgent(row.agentId, context);
         const model = this.effectiveModel(row, context.config);
         const modelState = {
-            modelId: model?.id ?? row.modelId ?? "",
+            modelId: model?.id ?? row.modelId,
             // 模型可能在配置里被删掉了：行上的 id 仍然有效（它是这段会话现在用的那个），显示名退回 id
-            name: model?.name ?? row.modelId ?? "",
+            name: model?.name ?? row.modelId,
             vision: model?.vision === true,
             source: this.modelSource(row, agent, context.config),
         };
@@ -636,20 +636,11 @@ export class ConversationService {
     /**
      * 读配置。
      *
-     * `config.json` 是手改得了的文件（F-G3 的同款思路）：它坏了要让用户看见「配置用不了 +
-     * 哪一步读不动」，而不是一句「宿主内部错误」——所以解析失败在这里就折成 `config_invalid`。
+     * `config.json` 是手改得了的文件，它坏了由 SDK 当场恢复出厂（D32），所以这里不再把
+     * 解析失败折成别的错——读到的要么是磁盘上那份，要么是已经写回磁盘的出厂配置。
      */
     async readConfig() {
-        try {
-            return await this.configManager.read();
-        }
-        catch (error) {
-            throw new HostError("config_invalid", {
-                params: { reason: error instanceof Error ? error.message : String(error) },
-                detail: { path: this.configManager.configPath },
-                cause: error,
-            });
-        }
+        return await this.configManager.read();
     }
     async viewContext(config, workspaces = [], agents = []) {
         return {

package/dist/services/DiscoveryService.d.ts

@@ -2,9 +2,16 @@
  * 能力发现服务：把「这个项目现在能用哪些 MCP / Skill / 工具 / 子 Agent」摊成分层清单。
  *
  * 对应能力编号：F-G1（MCP 5 层链，可编辑的只有 2 个作用域）、F-G2（Skill 4 层、工具与子 Agent
- * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件要能看见、能修）、
+ * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件按层分两种处置，见下）、
  * L9（MCP 的 5 层链）、R54（5 层链与各能力目录由本服务算好交给 ScopeRegistry）。
  *
+ * **F-F6 里「坏文件」的那条口径不是一句话，按文件在哪分**：用户级那份
+ * （`<数据根>/mcp.json`）坏了由 SDK 恢复出厂并留残骸（PRD D32），本服务因此看到的是一个
+ * 好文件（除非文件是运行期才坏的，那时下一次启动才恢复）；项目侧
+ * （`<cwd>/.mcp.json`、`<cwd>/.ai-zen/mcp.json`、`<cwd>/.agents/mcp.json`）与
+ * `~/.agents/mcp.json` 坏了仍然是看得见的 `broken` 状态、能修 —— 那些文件在用户的仓库里，
+ * 恢复出厂等于改人家的 git 内容。
+ *
  * 三件事分开：
  *
  *   1. **路径**（{@link DiscoveryService.scopeAbilityPaths} 等）：只有「按 cwd 推出各能力应该去
@@ -12,7 +19,8 @@
  *      `createWorkspaceScopeFactory`）拿的就是这些路径。
  *   2. **读**（{@link DiscoveryService.discover}）：把每一层的 `missing | ok | broken` 与条目
  *      报出来。`missing` 与 `broken` 必须分开（F-F6）：以前两者都当空配置，一保存就把用户的
- *      文件覆盖掉了。
+ *      文件覆盖掉了；`broken` 在项目侧与 `~/.agents` 各层是「看得见、能修」，用户级那层由
+ *      SDK 恢复出厂（D32）。
  *   3. **写**（{@link DiscoveryService.writeMcpEntry} / {@link DiscoveryService.deleteMcpEntry}）：
  *      只写 MCP 的两个可编辑作用域，一次只动一条；写回时保留这一版不认识的字段与 `oauth`
  *      （F-F6），其中 `oauth.clientSecret` 省略就按磁盘原文保留（F-F2：读出去的是掩码，
@@ -85,6 +93,13 @@ export declare class DiscoveryService {
      * `cwd` 为 `null`（还没打开项目）时只给后两层：项目侧那三层的路径得先有项目才算得出来。
      */
     mcpLayers(cwd: string | null): DiscoveryLayerPath[];
+    /**
+     * 5 层链里那两个可写的层（第 1 层与第 4 层）；没有项目时 `workspace` 那层是 `null`。
+     *
+     * 位置、能不能写、归谁只在这里定一次：读（`mcpLayers`）与写（`writableMcpLayer`）拿的
+     * 是同一份定义。
+     */
+    private editableMcpLayers;
     /** Skill 的 4 层目录：`<ws>/.ai-zen/skills` → `<ws>/.agents/skills` → `<aiZenDir>/skills` → `~/.agents/skills` */
     skillLayers(cwd: string | null): DiscoveryLayerPath[];
     /** 用户工具的 2 层目录：`<ws>/.agents/tools` → `<aiZenDir>/tools` */
@@ -100,8 +115,6 @@ export declare class DiscoveryService {
     scopeAbilityPaths(cwd: string): ScopeAbilityPaths;
     /** 只取 MCP 的 5 层路径（喂给 SDK 的 `discoverMcpServers` / `McpScopePlugin`） */
     mcpPaths(cwd: string): string[];
-    /** 按作用域找那一层的路径（写入时用） */
-    mcpLayer(scope: McpEditableScope, cwd: string | null): DiscoveryLayerPath;
     /**
      * `config.getDiscovery`（F-G1 / F-G2 / F-F6）。
      *
@@ -141,7 +154,7 @@ export declare class DiscoveryService {
         layer: DiscoveryLayerView;
         removed: boolean;
     }>;
-    /** 可写作用域 → 那一层；`workspace` 作用域必须能落到某个项目里 */
+    /** 可写作用域 → 那一层；`workspace` 作用域必须能落到某个项目里（空串也算没给） */
     private writableMcpLayer;
     private readMcpLayers;
     /** 读一个 mcp.json：不存在 / 坏了 / 能读 三种结论分开（F-F6） */

package/dist/services/DiscoveryService.js

@@ -2,9 +2,16 @@
  * 能力发现服务：把「这个项目现在能用哪些 MCP / Skill / 工具 / 子 Agent」摊成分层清单。
  *
  * 对应能力编号：F-G1（MCP 5 层链，可编辑的只有 2 个作用域）、F-G2（Skill 4 层、工具与子 Agent
- * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件要能看见、能修）、
+ * 各 2 层，只发现真实存在的目录，离项目越近越优先）、F-F6（坏文件按层分两种处置，见下）、
  * L9（MCP 的 5 层链）、R54（5 层链与各能力目录由本服务算好交给 ScopeRegistry）。
  *
+ * **F-F6 里「坏文件」的那条口径不是一句话，按文件在哪分**：用户级那份
+ * （`<数据根>/mcp.json`）坏了由 SDK 恢复出厂并留残骸（PRD D32），本服务因此看到的是一个
+ * 好文件（除非文件是运行期才坏的，那时下一次启动才恢复）；项目侧
+ * （`<cwd>/.mcp.json`、`<cwd>/.ai-zen/mcp.json`、`<cwd>/.agents/mcp.json`）与
+ * `~/.agents/mcp.json` 坏了仍然是看得见的 `broken` 状态、能修 —— 那些文件在用户的仓库里，
+ * 恢复出厂等于改人家的 git 内容。
+ *
  * 三件事分开：
  *
  *   1. **路径**（{@link DiscoveryService.scopeAbilityPaths} 等）：只有「按 cwd 推出各能力应该去
@@ -12,7 +19,8 @@
  *      `createWorkspaceScopeFactory`）拿的就是这些路径。
  *   2. **读**（{@link DiscoveryService.discover}）：把每一层的 `missing | ok | broken` 与条目
  *      报出来。`missing` 与 `broken` 必须分开（F-F6）：以前两者都当空配置，一保存就把用户的
- *      文件覆盖掉了。
+ *      文件覆盖掉了；`broken` 在项目侧与 `~/.agents` 各层是「看得见、能修」，用户级那层由
+ *      SDK 恢复出厂（D32）。
  *   3. **写**（{@link DiscoveryService.writeMcpEntry} / {@link DiscoveryService.deleteMcpEntry}）：
  *      只写 MCP 的两个可编辑作用域，一次只动一条；写回时保留这一版不认识的字段与 `oauth`
  *      （F-F6），其中 `oauth.clientSecret` 省略就按磁盘原文保留（F-F2：读出去的是掩码，
@@ -109,9 +117,30 @@ export class DiscoveryService {
      * `cwd` 为 `null`（还没打开项目）时只给后两层：项目侧那三层的路径得先有项目才算得出来。
      */
     mcpLayers(cwd) {
+        const editable = this.editableMcpLayers(cwd);
         return withoutNulls([
             projectLayer(cwd, 0, `.${FILE_MCP}`, "other"),
-            cwd === null
+            editable.workspace,
+            projectLayer(cwd, 2, join(PROJECT_AGENTS_DIR, FILE_MCP), "other"),
+            editable.user,
+            {
+                depth: 4,
+                path: join(this.homeDir, HOME_AGENTS_DIR, FILE_MCP),
+                editable: false,
+                scope: null,
+                owner: "other",
+            },
+        ]);
+    }
+    /**
+     * 5 层链里那两个可写的层（第 1 层与第 4 层）；没有项目时 `workspace` 那层是 `null`。
+     *
+     * 位置、能不能写、归谁只在这里定一次：读（`mcpLayers`）与写（`writableMcpLayer`）拿的
+     * 是同一份定义。
+     */
+    editableMcpLayers(cwd) {
+        return {
+            workspace: cwd === null
                 ? null
                 : {
                     depth: 1,
@@ -120,22 +149,14 @@ export class DiscoveryService {
                     scope: "workspace",
                     owner: "workspace",
                 },
-            projectLayer(cwd, 2, join(PROJECT_AGENTS_DIR, FILE_MCP), "other"),
-            {
+            user: {
                 depth: 3,
                 path: join(this.basePath, FILE_MCP),
                 editable: true,
                 scope: "user",
                 owner: "user",
             },
-            {
-                depth: 4,
-                path: join(this.homeDir, HOME_AGENTS_DIR, FILE_MCP),
-                editable: false,
-                scope: null,
-                owner: "other",
-            },
-        ]);
+        };
     }
     /** Skill 的 4 层目录：`<ws>/.ai-zen/skills` → `<ws>/.agents/skills` → `<aiZenDir>/skills` → `~/.agents/skills` */
     skillLayers(cwd) {
@@ -203,17 +224,6 @@ export class DiscoveryService {
     mcpPaths(cwd) {
         return this.mcpLayers(cwd).map((layer) => layer.path);
     }
-    /** 按作用域找那一层的路径（写入时用） */
-    mcpLayer(scope, cwd) {
-        const layer = this.mcpLayers(cwd).find((candidate) => candidate.scope === scope);
-        if (!layer) {
-            throw new HostError("unsupported", {
-                params: { what: `the "${scope}" MCP scope` },
-                detail: { scope, reason: "no_such_scope" },
-            });
-        }
-        return layer;
-    }
     // -------------------------------------------------------------------------
     // 读：一层的状态与条目
     // -------------------------------------------------------------------------
@@ -307,15 +317,18 @@ export class DiscoveryService {
         }
         return { layer: await this.readMcpLayerView(layer), removed };
     }
-    /** 可写作用域 → 那一层；`workspace` 作用域必须能落到某个项目里 */
+    /** 可写作用域 → 那一层；`workspace` 作用域必须能落到某个项目里（空串也算没给） */
     writableMcpLayer(scope, cwd) {
-        if (scope === "workspace" && (cwd === null || cwd.trim() === "")) {
+        const editable = this.editableMcpLayers(cwd);
+        if (scope === "user")
+            return editable.user;
+        if (editable.workspace === null || (cwd ?? "").trim() === "") {
             throw new HostError("invalid_params", {
                 params: { field: "workspaceId" },
                 detail: { field: "workspaceId", reason: "workspace_scope_needs_workspace" },
             });
         }
-        return this.mcpLayer(scope, cwd);
+        return editable.workspace;
     }
     // -------------------------------------------------------------------------
     // 内部：MCP
@@ -976,6 +989,8 @@ async function listSubdirectories(dir) {
         return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
     }
     catch {
+        // 走到这里只剩两种情形：调用前 `stat` 过了、目录刚被删掉，或没有读权限 ——
+        // 两种都按「这一层没有条目」报（层本身的 broken 已经由 `readDirectory` 报过）
         return [];
     }
 }
@@ -985,6 +1000,7 @@ async function listFiles(dir) {
         return entries.filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
     }
     catch {
+        // 同 `listSubdirectories`：目录在 `stat` 之后刚被删、或没有读权限，按空报
         return [];
     }
 }

package/dist/services/ModelService.js

@@ -290,8 +290,8 @@ export class ModelService {
         const input = params.imageModel;
         const config = await this.readConfig();
         const id = requireText(input?.id, "imageModel.id");
-        requireText(input?.name, "imageModel.name");
-        requireText(input?.modelName, "imageModel.modelName");
+        const name = requireText(input?.name, "imageModel.name");
+        const modelName = requireText(input?.modelName, "imageModel.modelName");
         const endpointId = requireText(input?.endpointId, "imageModel.endpointId");
         if (!findEndpoint(config, endpointId)) {
             throw new HostError("invalid_params", {
@@ -309,9 +309,9 @@ export class ModelService {
                 defaultQuality: input.defaultQuality,
             }),
             id,
-            name: requireText(input.name, "imageModel.name"),
+            name,
             endpointId,
-            modelName: requireText(input.modelName, "imageModel.modelName"),
+            modelName,
             custom: true,
         };
         const next = {

package/dist/services/QuestionService.d.ts

@@ -111,6 +111,9 @@ export declare class QuestionService {
      *
      * 先落库再推事件：库里那一行是「多端看同一个」的真相（D22），推送只是提醒在线的那几个
      * 窗口去拉（L5 断线即作废）。
+     *
+     * 入参不做形状校验：`kind` 与两个 `messageKey` 的类型本身就是闭集（`QuestionKind` /
+     * `MessageKey`），而这里只有 `askHandoff` 一个调用方，候选项是常量字面量。
      */
     ask(input: AskQuestionInput, language?: Language): Promise<QuestionView>;
     /**

package/dist/services/QuestionService.js

@@ -18,7 +18,6 @@
 import { randomUUID } from "node:crypto";
 import { DEFAULT_LANGUAGE, hasMessage, render } from "../i18n/index.js";
 import { HostError } from "../wire/errors.js";
-import { QUESTION_KINDS } from "../wire/states.js";
 import { readUsage } from "./MessageService.js";
 /** 交接问题的三个候选值（F-D2：自交接 / 独立摘要 / 不交接） */
 export const HANDOFF_OPTION_SELF = "self";
@@ -154,42 +153,11 @@ export class QuestionService {
      *
      * 先落库再推事件：库里那一行是「多端看同一个」的真相（D22），推送只是提醒在线的那几个
      * 窗口去拉（L5 断线即作废）。
+     *
+     * 入参不做形状校验：`kind` 与两个 `messageKey` 的类型本身就是闭集（`QuestionKind` /
+     * `MessageKey`），而这里只有 `askHandoff` 一个调用方，候选项是常量字面量。
      */
     async ask(input, language = DEFAULT_LANGUAGE) {
-        if (!QUESTION_KINDS.includes(input.kind)) {
-            throw new HostError("invalid_params", {
-                params: { field: "kind" },
-                detail: { field: "kind", value: input.kind, kinds: QUESTION_KINDS },
-            });
-        }
-        if (!hasMessage(input.prompt.messageKey)) {
-            throw new HostError("invalid_params", {
-                params: { field: "prompt" },
-                detail: { field: "prompt", reason: "unknown_message_key" },
-            });
-        }
-        if (input.options.length === 0) {
-            throw new HostError("invalid_params", {
-                params: { field: "options" },
-                detail: { field: "options", reason: "empty" },
-            });
-        }
-        const seen = new Set();
-        for (const option of input.options) {
-            if (option.value.trim().length === 0 || seen.has(option.value)) {
-                throw new HostError("invalid_params", {
-                    params: { field: "options" },
-                    detail: { field: "options", reason: "duplicate_or_empty_value", value: option.value },
-                });
-            }
-            seen.add(option.value);
-            if (!hasMessage(option.label.messageKey)) {
-                throw new HostError("invalid_params", {
-                    params: { field: "options" },
-                    detail: { field: "options", reason: "unknown_message_key", value: option.value },
-                });
-            }
-        }
         const payload = {
             code: input.code ?? input.prompt.messageKey,
             prompt: { messageKey: input.prompt.messageKey, params: input.prompt.params ?? {} },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-host",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "description": "AI-Zen Agents Host — session/workspace service shared by CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
   "license": "MIT",
   "dependencies": {
     "@ai-zen/agents-core": "^4.6.0-alpha.0",
-    "@ai-zen/agents-sdk": "^1.2.0-alpha.0",
+    "@ai-zen/agents-sdk": "^1.2.0-alpha.2",
     "ws": "^8.22.2"
   },
   "devDependencies": {