@ai-zen/agents-sdk 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/agent-plugins/AutoMigratePlugin.js

@@ -1,17 +1,22 @@
 import { getLogger } from "../shared/logger.js";
-const log = getLogger();
 /**
- * 自动迁移插件 — 只负责「触发」，实际迁移逻辑统一委托给持有的 `TaskMigrationService` 实例。
+ * 自动迁移插件 —— 只负责「何时触发」，实际迁移统一委托给持有的 `HandoffService`。
  *
- * 当 token 使用量超过 maxTokens 时触发迁移。`service.migrate()` 需要 `agent`（当前对话）作为
- * 唯一运行时参数，其余（模型、迁移前后钩子）已由服务在构造时持有。
+ * 当 `usage.prompt_tokens` 超过 handoffTokens 时触发迁移：
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
- *   maxTokens: 250_000,
+ *   service: handoffService,
+ *   handoffTokens: 250_000,
+ *   resolveMode: async ({ promptTokens, handoffTokens }) =>
+ *     (await askUser(promptTokens, handoffTokens)) ? "self" : null,
  * }));
  * ```
+ *
+ * 两层让行（缺一不可）：
+ *   - `service.busy`：交接回合本身就是一次 `send()`，其 `onAfterSend` 会再次到这里；
+ *     不跳过就会「交接触发迁移 → 迁移再交接」无限递归；
+ *   - 交接回合结束后的用量也仍可能超阈值，故 busy 判断必须覆盖整个交接 + 迁移过程。
  */
 export class AutoMigratePlugin {
     options;
@@ -20,17 +25,25 @@ export class AutoMigratePlugin {
     }
     async onAfterSend(ctx) {
         const agent = ctx.agent;
-        const { service, maxTokens } = this.options;
+        const { service, handoffTokens, resolveMode } = this.options;
+        // 交接/迁移进行中：让行（防递归）
+        if (service.busy)
+            return;
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        if (promptTokens <= maxTokens)
+        if (promptTokens <= handoffTokens)
             return;
         try {
-            await service.migrate({ agent, promptTokens, maxTokens });
+            const mode = resolveMode
+                ? await resolveMode({ promptTokens, handoffTokens })
+                : undefined;
+            if (mode === null)
+                return; // 用户选择跳过本次迁移
+            await service.migrate({ agent, promptTokens, handoffTokens, mode: mode ?? undefined });
         }
         catch (err) {
-            log.error(`[autoMigrate] 迁移失败: ${err?.message ?? err}`);
+            getLogger().error(`[autoMigrate] 迁移失败: ${err?.message ?? err}`);
         }
     }
 }

package/dist/agent-plugins/ContextGuardPlugin.d.ts

@@ -1,34 +1,32 @@
 import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
 export interface ContextGuardOptions {
-    /** 上下文告警阈值（token）。用量超过 maxTokens × ratio 即中断。 */
-    maxTokens: number;
     /**
-     * 超出比例。用量 > maxTokens × ratio 时判定为「严重超限」（如读入超大文件），
-     * 在请求前抛出 ContextOverflowError 中断对话。默认 1.5（即 +50%）。
+     * 强行阻断阈值（tokens，绝对值）。
+     *
+     * 语义只有一条：请求前上一轮用量超过它 → 中断本轮。没有倍数、没有放宽档——
+     * 想调松就把它调大，「安全边界写多少就是多少」比「隐式乘以某个系数」可预测得多。
      */
-    ratio?: number;
+    guardTokens: number;
 }
 /**
  * 上下文安全护栏插件。
  *
- * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
- * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
- *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：超过 `guardTokens`
+ * 即抛 `ContextOverflowError` 中断对话，交由上层向用户报错。
  *
  * 与迁移插件职责分离：
- * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
- * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ * - `ContextGuardPlugin`：硬线，只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - `AutoMigratePlugin`：软线（`tokenThresholds.handoff`），在正常范围内做交接迁移。
+ *   两条线都是绝对值，`guard` 应当明显大于 `handoff`，交接回合的额外请求才有余量。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
- * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
- *   maxTokens: 250_000,
- * }));
+ * const { handoff, guard } = config.models[i].tokenThresholds;
+ * agent.use(new ContextGuardPlugin({ guardTokens: guard }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens: handoff }));
  * ```
  */
 export declare class ContextGuardPlugin implements AgentPlugin {
-    private options;
+    private readonly guardTokens;
     constructor(options: ContextGuardOptions);
     onInnerLoopStart(ctx: SendContext): Promise<void>;
 }

package/dist/agent-plugins/ContextGuardPlugin.js

@@ -2,36 +2,32 @@ import { ContextOverflowError } from "../shared/errors.js";
 /**
  * 上下文安全护栏插件。
  *
- * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：
- * - 若用量超过 maxTokens × ratio，说明上下文已严重超限（通常因读入超大文件），
- *   在请求前抛出 ContextOverflowError，**中断对话**，交由上层向用户报错。
+ * 在每次内循环**发请求前**检测上一轮用量（usage.prompt_tokens）：超过 `guardTokens`
+ * 即抛 `ContextOverflowError` 中断对话，交由上层向用户报错。
  *
  * 与迁移插件职责分离：
- * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
- * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ * - `ContextGuardPlugin`：硬线，只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
+ * - `AutoMigratePlugin`：软线（`tokenThresholds.handoff`），在正常范围内做交接迁移。
+ *   两条线都是绝对值，`guard` 应当明显大于 `handoff`，交接回合的额外请求才有余量。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
- * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
- *   maxTokens: 250_000,
- * }));
+ * const { handoff, guard } = config.models[i].tokenThresholds;
+ * agent.use(new ContextGuardPlugin({ guardTokens: guard }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, handoffTokens: handoff }));
  * ```
  */
 export class ContextGuardPlugin {
-    options;
+    guardTokens;
     constructor(options) {
-        this.options = options;
+        this.guardTokens = options.guardTokens;
     }
     async onInnerLoopStart(ctx) {
-        const { agent } = ctx;
-        const { maxTokens, ratio = 1.5 } = this.options;
+        const promptTokens = ctx.agent.lastUsage?.prompt_tokens;
         // 首轮请求前尚无用量数据，跳过（只能在发出首轮请求、拿到 usage 后才有据可查）
-        const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        if (promptTokens > maxTokens * ratio) {
-            throw new ContextOverflowError(promptTokens, maxTokens, ratio);
+        if (promptTokens > this.guardTokens) {
+            throw new ContextOverflowError(promptTokens, this.guardTokens);
         }
     }
 }

package/dist/config/ConfigManager.d.ts

@@ -1,15 +1,23 @@
-import type { AppConfig, AgentDefinition } from "../types/index.js";
+import type { AppConfig, AgentDefinition, ReasoningPresets } from "../types/index.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
 export declare class ConfigManager {
     readonly configPath: string;
     readonly basePath: string;
+    /** 当前配置里的模型 id 集合（bootstrap 时填充，供默认 Agent 校验 modelId） */
+    private knownModelIds;
     constructor(configPath: string);
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
+     *
+     * 读到即**迁移**（`config/migrate.ts`）：上层拿到的永远是当前字段形状，
+     * 旧字段（`maxContextTokens` / `maxContextChars`）不会漏到调用方。
+     * 迁移结果不在这里落盘——落盘只在 `ensureDefaultConfig()` 做一次。
      */
     read(): Promise<AppConfig>;
+    /** 读磁盘原文（不做任何迁移/同步），供 `ensureDefaultConfig()` 对比写盘用 */
+    private readRaw;
     write(config: AppConfig): Promise<void>;
     /**
      * 确保基础目录结构存在。
@@ -28,13 +36,20 @@ export declare class ConfigManager {
     /**
      * 确保 basePath/agents/default.json 存在。
      *
-     * - default.json 已存在且 custom === true → 用户声明为自定义，原样返回，不做任何改动
-     * - default.json 已存在且 custom !== true → 仅同步出厂提示词（messages），
-     *   其余字段（name/permissions/modelId 等）保留；提示词一致时不写盘
-     * - agents/ 为空 → 写入默认 Agent
+     * - default.json 已存在且 custom === true → 用户声明为自定义，不替换提示词（缺 modelId 仍补）
+     * - default.json 已存在且 custom !== true → 同步出厂提示词（messages），
+     *   其余字段（name/permissions 等）保留；提示词与 modelId 都一致时不写盘
+     * - agents/ 为空 → 写入默认 Agent（含 modelId）
      * - 已有其他 Agent → 返回 null
+     *
+     * 模型真相源只有 `AgentDefinition.modelId`：这里保证默认 Agent **一定有** modelId，
+     * 运行期不再有任何 `config.defaultModel` 兜底。
+     *
+     * @param legacyDefaultModel 老配置里的 `config.defaultModel`。仅在 Agent **既无 modelId**
+     *   且该模型仍在模型清单里时用它补齐，让升级不改变用户实际在用的模型；之后
+     *   这个字段就彻底不存在了。
      */
-    ensureDefaultAgent(): Promise<AgentDefinition | null>;
+    ensureDefaultAgent(legacyDefaultModel?: string): Promise<AgentDefinition | null>;
     /**
      * 确保 basePath/sub-agents/{DEFAULT_SUBAGENT_ID}.json 存在。
      *
@@ -52,6 +67,38 @@ export declare class ConfigManager {
         agent: AgentDefinition | null;
         subAgent: AgentDefinition | null;
     }>;
+    /** 策略表文件路径（与 config.json 同级） */
+    get reasoningPresetsPath(): string;
+    /**
+     * 读取思考策略表。
+     *
+     * 文件缺失或无法解析时返回出厂种子（内存值，不写盘）——保证调用方永远拿到可用的表：
+     * 用户误删文件后客户端仍能正常选档位，下次 `ensureReasoningPresets()` 会重新释放。
+     */
+    readReasoningPresets(): Promise<ReasoningPresets>;
+    /**
+     * 释放 / 同步出厂思考策略。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构，**按策略逐个判断**（粒度到单个策略）：
+     *   - 文件不存在 → 写入出厂种子；
+     *   - 某策略标了 `custom: true` → 用户自有，原样保留；
+     *   - 某策略未标 → 用出厂版覆盖该策略（内容相同则不写盘）；
+     *   - 用户自建的非出厂策略 → 始终保留。
+     *
+     * @returns 实际写入的策略名列表（未变化 / 用户自有 均不计入）
+     */
+    ensureReasoningPresets(): Promise<string[]>;
+    /**
+     * 释放 / 同步出厂 Skill。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构：
+     *   - 磁盘上不存在 → 写入出厂内容；
+     *   - 存在且 frontmatter 标了 `custom: "true"` → 用户自有，原样保留；
+     *   - 存在但未标 → 视为出厂托管，同步为当前版本内容（内容相同则不写盘）。
+     *
+     * @returns 实际写入的 Skill id 列表（内容未变化 / 用户自有 均不计入）
+     */
+    ensureFactorySkills(): Promise<string[]>;
     /** mcp.json 路径：{basePath}/mcp.json */
     get mcpPath(): string;
     /**
@@ -81,10 +128,12 @@ export declare class ConfigManager {
  * 规则：
  * - 未标 `custom: true` 的条目 → 由 SDK 托管，从结果中移除，改用 defaults 中的最新定义；
  * - 标了 `custom: true` 的条目 → 用户自有，原样保留；与出厂定义同 id 时用户版本优先；
- * - 默认模型 ID（defaultModel / defaultImageModel / defaultMigrationModel）
+ * - 默认模型 ID（defaultImageModel / defaultMigrationModel）
  *   在合并后若已不存在 → 回退到出厂默认，避免悬空引用。
  *
+ * 注意 `defaultModel` 已不再存在：模型真相源是 `AgentDefinition.modelId`。
+ *
  * 端点（endpoints）不参与托管，始终保持用户配置。
  */
 export declare function syncManagedModels(config: AppConfig): AppConfig;
-export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_MODEL_ID, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/ConfigManager.js

@@ -1,12 +1,17 @@
 import { promises as fs } from "node:fs";
 import { dirname, join } from "node:path";
 import { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+import { FACTORY_SKILLS, isCustomSkill } from "./factory-skills.js";
+import { FACTORY_REASONING_PRESETS, REASONING_PRESETS_FILE } from "./reasoning-presets.js";
+import { migrateConfig } from "./migrate.js";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
 export class ConfigManager {
     configPath;
     basePath;
+    /** 当前配置里的模型 id 集合（bootstrap 时填充，供默认 Agent 校验 modelId） */
+    knownModelIds = new Set();
     constructor(configPath) {
         this.configPath = configPath;
         this.basePath = dirname(configPath);
@@ -16,13 +21,22 @@ export class ConfigManager {
     // -----------------------------------------------------------------------
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
+     *
+     * 读到即**迁移**（`config/migrate.ts`）：上层拿到的永远是当前字段形状，
+     * 旧字段（`maxContextTokens` / `maxContextChars`）不会漏到调用方。
+     * 迁移结果不在这里落盘——落盘只在 `ensureDefaultConfig()` 做一次。
      */
     async read() {
+        const raw = await this.readRaw();
+        return raw ? migrateConfig(raw).config : { ...DEFAULT_APP_CONFIG };
+    }
+    /** 读磁盘原文（不做任何迁移/同步），供 `ensureDefaultConfig()` 对比写盘用 */
+    async readRaw() {
         try {
             await fs.access(this.configPath);
         }
         catch {
-            return { ...DEFAULT_APP_CONFIG };
+            return null;
         }
         const raw = await fs.readFile(this.configPath, "utf-8");
         return JSON.parse(raw);
@@ -61,18 +75,16 @@ export class ConfigManager {
      * 条目视为用户自有，原样保留。同步结果与磁盘内容一致时不写盘。
      */
     async ensureDefaultConfig() {
-        let existing;
-        try {
-            await fs.access(this.configPath);
-            existing = await this.read();
-        }
-        catch {
+        const onDisk = await this.readRaw();
+        if (!onDisk) {
             await this.ensureDirs();
             await this.write(DEFAULT_APP_CONFIG);
             return { ...DEFAULT_APP_CONFIG };
         }
-        const synced = syncManagedModels(existing);
-        if (JSON.stringify(synced) !== JSON.stringify(existing)) {
+        // 先迁移历史字段，再同步出厂模型清单；两者结果与磁盘原文不同才写盘
+        const migrated = migrateConfig(onDisk).config;
+        const synced = syncManagedModels(migrated);
+        if (JSON.stringify(synced) !== JSON.stringify(onDisk)) {
             await this.write(synced);
         }
         return synced;
@@ -80,28 +92,48 @@ export class ConfigManager {
     /**
      * 确保 basePath/agents/default.json 存在。
      *
-     * - default.json 已存在且 custom === true → 用户声明为自定义，原样返回，不做任何改动
-     * - default.json 已存在且 custom !== true → 仅同步出厂提示词（messages），
-     *   其余字段（name/permissions/modelId 等）保留；提示词一致时不写盘
-     * - agents/ 为空 → 写入默认 Agent
+     * - default.json 已存在且 custom === true → 用户声明为自定义，不替换提示词（缺 modelId 仍补）
+     * - default.json 已存在且 custom !== true → 同步出厂提示词（messages），
+     *   其余字段（name/permissions 等）保留；提示词与 modelId 都一致时不写盘
+     * - agents/ 为空 → 写入默认 Agent（含 modelId）
      * - 已有其他 Agent → 返回 null
+     *
+     * 模型真相源只有 `AgentDefinition.modelId`：这里保证默认 Agent **一定有** modelId，
+     * 运行期不再有任何 `config.defaultModel` 兜底。
+     *
+     * @param legacyDefaultModel 老配置里的 `config.defaultModel`。仅在 Agent **既无 modelId**
+     *   且该模型仍在模型清单里时用它补齐，让升级不改变用户实际在用的模型；之后
+     *   这个字段就彻底不存在了。
      */
-    async ensureDefaultAgent() {
+    async ensureDefaultAgent(legacyDefaultModel) {
         const agentsDir = join(this.basePath, "agents");
         const defaultPath = join(agentsDir, `${DEFAULT_AGENT_ID}.json`);
+        const fallbackModelId = legacyDefaultModel && this.knownModelIds.has(legacyDefaultModel)
+            ? legacyDefaultModel
+            : DEFAULT_AGENT_DEFINITION.modelId;
         try {
             const existing = JSON.parse(await fs.readFile(defaultPath, "utf-8"));
-            // 用户声明为自定义 → 完全跳过替换
-            if (existing.custom === true)
-                return existing;
+            // 缺 modelId → 补上（历史配置升级路径）
+            const withModel = existing.modelId
+                ? existing
+                : { ...existing, modelId: fallbackModelId };
+            const modelPatched = !existing.modelId;
+            // 用户声明为自定义 → 不替换提示词，但补上的 modelId 要落盘
+            if (withModel.custom === true) {
+                if (modelPatched) {
+                    await fs.writeFile(defaultPath, JSON.stringify(withModel, null, 2), "utf-8");
+                }
+                return withModel;
+            }
             // 仅同步提示词；内容一致则不写盘、不动时间戳
             const messages = DEFAULT_AGENT_DEFINITION.messages;
-            if (sameMessages(existing.messages ?? [], messages))
-                return existing;
+            const sameMsgs = sameMessages(withModel.messages ?? [], messages);
+            if (sameMsgs && !modelPatched)
+                return withModel;
             const updated = {
-                ...existing,
+                ...withModel,
                 messages,
-                updatedAt: new Date().toISOString(),
+                updatedAt: sameMsgs ? withModel.updatedAt : new Date().toISOString(),
             };
             await fs.writeFile(defaultPath, JSON.stringify(updated, null, 2), "utf-8");
             return updated;
@@ -174,13 +206,121 @@ export class ConfigManager {
      */
     async bootstrap() {
         await this.ensureDirs();
+        // 迁移前读一次磁盘原文：只为了拿旧的 `defaultModel`（字段已从类型里移除），
+        // 让升级不改变用户原本在用的模型
+        const raw = (await this.readRaw());
         const config = await this.ensureDefaultConfig();
-        const agent = await this.ensureDefaultAgent();
+        this.knownModelIds = new Set((config.models ?? []).map((m) => m.id));
+        const agent = await this.ensureDefaultAgent(raw?.defaultModel);
         const subAgent = await this.ensureDefaultSubAgent();
         await this.ensureDefaultMcpConfig();
+        await this.ensureFactorySkills();
+        await this.ensureReasoningPresets();
         return { config, agent, subAgent };
     }
     // -----------------------------------------------------------------------
+    // 思考策略表（{basePath}/reasoning-presets.json）
+    // -----------------------------------------------------------------------
+    /** 策略表文件路径（与 config.json 同级） */
+    get reasoningPresetsPath() {
+        return join(this.basePath, REASONING_PRESETS_FILE);
+    }
+    /**
+     * 读取思考策略表。
+     *
+     * 文件缺失或无法解析时返回出厂种子（内存值，不写盘）——保证调用方永远拿到可用的表：
+     * 用户误删文件后客户端仍能正常选档位，下次 `ensureReasoningPresets()` 会重新释放。
+     */
+    async readReasoningPresets() {
+        try {
+            const raw = await fs.readFile(this.reasoningPresetsPath, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // 缺失或损坏 → 回落出厂种子
+        }
+        return { ...FACTORY_REASONING_PRESETS };
+    }
+    /**
+     * 释放 / 同步出厂思考策略。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构，**按策略逐个判断**（粒度到单个策略）：
+     *   - 文件不存在 → 写入出厂种子；
+     *   - 某策略标了 `custom: true` → 用户自有，原样保留；
+     *   - 某策略未标 → 用出厂版覆盖该策略（内容相同则不写盘）；
+     *   - 用户自建的非出厂策略 → 始终保留。
+     *
+     * @returns 实际写入的策略名列表（未变化 / 用户自有 均不计入）
+     */
+    async ensureReasoningPresets() {
+        let onDisk = null;
+        try {
+            onDisk = JSON.parse(await fs.readFile(this.reasoningPresetsPath, "utf-8"));
+        }
+        catch {
+            onDisk = null;
+        }
+        if (!onDisk || typeof onDisk !== "object" || Array.isArray(onDisk)) {
+            await fs.mkdir(this.basePath, { recursive: true });
+            await fs.writeFile(this.reasoningPresetsPath, JSON.stringify(FACTORY_REASONING_PRESETS, null, 2), "utf-8");
+            return Object.keys(FACTORY_REASONING_PRESETS);
+        }
+        const next = { ...onDisk };
+        const written = [];
+        for (const [name, preset] of Object.entries(FACTORY_REASONING_PRESETS)) {
+            const existing = onDisk[name];
+            if (existing?.custom === true)
+                continue; // 用户改过 → 冻结
+            if (JSON.stringify(existing) === JSON.stringify(preset))
+                continue; // 已是最新
+            next[name] = preset;
+            written.push(name);
+        }
+        if (written.length > 0) {
+            await fs.writeFile(this.reasoningPresetsPath, JSON.stringify(next, null, 2), "utf-8");
+        }
+        return written;
+    }
+    // -----------------------------------------------------------------------
+    // 出厂 Skill（{basePath}/skills/<id>/SKILL.md）
+    // -----------------------------------------------------------------------
+    /**
+     * 释放 / 同步出厂 Skill。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构：
+     *   - 磁盘上不存在 → 写入出厂内容；
+     *   - 存在且 frontmatter 标了 `custom: "true"` → 用户自有，原样保留；
+     *   - 存在但未标 → 视为出厂托管，同步为当前版本内容（内容相同则不写盘）。
+     *
+     * @returns 实际写入的 Skill id 列表（内容未变化 / 用户自有 均不计入）
+     */
+    async ensureFactorySkills() {
+        const written = [];
+        for (const skill of FACTORY_SKILLS) {
+            const dir = join(this.basePath, "skills", skill.id);
+            const file = join(dir, "SKILL.md");
+            let existing = null;
+            try {
+                existing = await fs.readFile(file, "utf-8");
+            }
+            catch {
+                existing = null;
+            }
+            // 用户声明自有 → 永不覆盖
+            if (existing != null && isCustomSkill(existing))
+                continue;
+            // 内容已一致 → 不重复写盘
+            if (existing === skill.content)
+                continue;
+            await fs.mkdir(dir, { recursive: true });
+            await fs.writeFile(file, skill.content, "utf-8");
+            written.push(skill.id);
+        }
+        return written;
+    }
+    // -----------------------------------------------------------------------
     // MCP 配置（~/.ai-zen/mcp.json）
     // -----------------------------------------------------------------------
     /** mcp.json 路径：{basePath}/mcp.json */
@@ -251,9 +391,11 @@ export class ConfigManager {
  * 规则：
  * - 未标 `custom: true` 的条目 → 由 SDK 托管，从结果中移除，改用 defaults 中的最新定义；
  * - 标了 `custom: true` 的条目 → 用户自有，原样保留；与出厂定义同 id 时用户版本优先；
- * - 默认模型 ID（defaultModel / defaultImageModel / defaultMigrationModel）
+ * - 默认模型 ID（defaultImageModel / defaultMigrationModel）
  *   在合并后若已不存在 → 回退到出厂默认，避免悬空引用。
  *
+ * 注意 `defaultModel` 已不再存在：模型真相源是 `AgentDefinition.modelId`。
+ *
  * 端点（endpoints）不参与托管，始终保持用户配置。
  */
 export function syncManagedModels(config) {
@@ -272,7 +414,6 @@ export function syncManagedModels(config) {
         ...config,
         models,
         imageModels,
-        defaultModel: resolve(config.defaultModel, modelIds, DEFAULT_APP_CONFIG.defaultModel),
         defaultImageModel: resolve(config.defaultImageModel, imageIds, DEFAULT_APP_CONFIG.defaultImageModel),
         defaultMigrationModel: resolve(config.defaultMigrationModel, modelIds, DEFAULT_APP_CONFIG.defaultMigrationModel),
     };
@@ -289,4 +430,4 @@ function sameMessages(a, b) {
     return a.every((message, index) => message.role === b[index].role &&
         JSON.stringify(message.content) === JSON.stringify(b[index].content));
 }
-export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";
+export { DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_MODEL_ID, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./constants.js";

package/dist/config/constants.d.ts

@@ -1,6 +1,13 @@
 import type { AgentDefinition, AppConfig } from "../types/index.js";
 /** 默认 Agent ID */
 export declare const DEFAULT_AGENT_ID = "default";
+/**
+ * 出厂默认模型 id。
+ *
+ * 模型的**唯一真相源是 `AgentDefinition.modelId`**：配置里不再有 `defaultModel`，
+ * 会话存档里也不记模型。这个常量只用于给出厂默认 Agent 填一个初始值。
+ */
+export declare const DEFAULT_MODEL_ID = "deepseek-flash";
 /** 默认 Agent 定义（不含时间戳） */
 export declare const DEFAULT_AGENT_DEFINITION: Omit<AgentDefinition, "createdAt" | "updatedAt">;
 /** 默认 SubAgent ID */