@ai-zen/agents-sdk 1.0.0-alpha.16 → 1.0.0-alpha.18

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.0.0-alpha.18] - 2026-10-22
+
+### 🔧 行为变更（不兼容）
+
+- **模型的唯一真相源改为 `AgentDefinition.modelId`，`AppConfig.defaultModel` 删除** —— 此前模型有两处来源：Agent 定义里的 `modelId` 优先，缺失时回退 `config.defaultModel`。而 CLI 等客户端还会在**会话存档**里另记一份模型名用于展示。三份值一旦分叉，就会出现「界面写着 DeepSeek、请求却发给 GLM」的静默错位：用户看到 401 却怎么切都切不回来（切换命令按显示层判断「已经是当前模型」直接返回，实际模型从未改变）。现在：
+  - `AppConfig` 删除 `defaultModel` 字段，出厂配置同步删除；`migrateConfig` 会把磁盘上的旧字段**清掉**（一次性，写入后不再出现）；
+  - `createAgent` 只读 `definition.modelId`，**缺失直接报错**，不再有任何隐式回退；
+  - `ViewImageTool.isAvailable` / `resolveModelAndEndpoint` 同步去掉 `defaultModel` 兜底，反查不到即视为「无端点」，让调用方走降级路径而不是猜一个模型。
+- **`DEFAULT_AGENT_DEFINITION.modelId = "deepseek-flash"`（新增导出 `DEFAULT_MODEL_ID`）** —— 出厂默认 Agent 自带模型 ID，装完即用，不再依赖配置层的默认值。
+- **升级兼容：`ensureDefaultAgent()` 会为缺 `modelId` 的历史 Agent 补上** —— 优先沿用老的 `config.defaultModel`（若该模型仍在清单里），否则回落到出厂 `deepseek-flash`，因此升级不会改变用户正在用的模型。
+
+### ✅ 测试
+
+- 全量 **57 文件 / 602 例通过**（6 skipped）。
+- 新增/改写重点：`createAgent` 缺 `modelId` 必须抛错、`ensureDefaultAgent` 补齐并落盘、`migrateConfig` 清除废弃字段且不就地改原对象、`resolveModelAndEndpoint` 未命中返回 `null` 端点、MCP / 图片工具按 `ctx.agent.model` 反查端点（不再靠默认模型兜底）。
+
 ## [1.0.0-alpha.16] - 2026-10-22
 
 ### 🔧 行为变更（不兼容，向上修复）

package/dist/config/ConfigManager.d.ts

@@ -5,6 +5,8 @@ import type { AppConfig, AgentDefinition, ReasoningPresets } from "../types/inde
 export declare class ConfigManager {
     readonly configPath: string;
     readonly basePath: string;
+    /** 当前配置里的模型 id 集合（bootstrap 时填充，供默认 Agent 校验 modelId） */
+    private knownModelIds;
     constructor(configPath: string);
     /**
      * 读取配置。文件不存在时返回出厂默认配置。
@@ -34,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 存在。
      *
@@ -119,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

@@ -10,6 +10,8 @@ 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);
@@ -90,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;
@@ -184,8 +206,12 @@ 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();
@@ -365,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) {
@@ -386,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),
     };
@@ -403,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 */

package/dist/config/constants.js

@@ -4,11 +4,20 @@ import { Message } from "@ai-zen/agents-core";
 // ---------------------------------------------------------------------------
 /** 默认 Agent ID */
 export const DEFAULT_AGENT_ID = "default";
+/**
+ * 出厂默认模型 id。
+ *
+ * 模型的**唯一真相源是 `AgentDefinition.modelId`**：配置里不再有 `defaultModel`，
+ * 会话存档里也不记模型。这个常量只用于给出厂默认 Agent 填一个初始值。
+ */
+export const DEFAULT_MODEL_ID = "deepseek-flash";
 /** 默认 Agent 定义（不含时间戳） */
 export const DEFAULT_AGENT_DEFINITION = {
     id: DEFAULT_AGENT_ID,
     name: "默认助手",
     description: "默认的 AI 助手，适用于日常问答和任务执行。",
+    // 模型写在 Agent 定义上，是运行期唯一真相源（无 config.defaultModel 兜底）
+    modelId: DEFAULT_MODEL_ID,
     messages: [
         Message.System(`你是一个幽默风趣、严谨可靠的智能助手，请用中文回复。当前操作系统：${process.platform}。
 
@@ -223,7 +232,6 @@ export const DEFAULT_APP_CONFIG = {
             defaultSize: "1024x1024",
         },
     ],
-    defaultModel: "deepseek-flash",
     defaultImageModel: "cogview-4",
     defaultAgent: "default",
     defaultMigrationModel: "deepseek-flash",

package/dist/config/migrate.d.ts

@@ -57,6 +57,9 @@ export declare function migrateModelReasoning(model: Model): {
 /**
  * 迁移整个配置。只处理对话模型（`models`）——
  * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
+ *
+ * 同时清除已废弃的 `defaultModel`：模型的真相源已改为 `AgentDefinition.modelId`，
+ * 配置级默认值连同字段一起消失（旧值先由 `ConfigManager.bootstrap()` 搬到默认 Agent 上）。
  */
 export declare function migrateConfig(config: AppConfig): {
     config: AppConfig;

package/dist/config/migrate.js

@@ -102,6 +102,9 @@ export function migrateModelReasoning(model) {
 /**
  * 迁移整个配置。只处理对话模型（`models`）——
  * 图片模型（`imageModels`）既没有上下文阈值、也没有思考概念。
+ *
+ * 同时清除已废弃的 `defaultModel`：模型的真相源已改为 `AgentDefinition.modelId`，
+ * 配置级默认值连同字段一起消失（旧值先由 `ConfigManager.bootstrap()` 搬到默认 Agent 上）。
  */
 export function migrateConfig(config) {
     let changed = false;
@@ -112,7 +115,13 @@ export function migrateConfig(config) {
             changed = true;
         return reasoning.model;
     });
+    const next = { ...config, models };
+    // 已废弃字段：不参与运行，也不允许再写回磁盘
+    if ("defaultModel" in next) {
+        delete next.defaultModel;
+        changed = true;
+    }
     if (!changed)
         return { config, changed };
-    return { config: { ...config, models }, changed };
+    return { config: next, changed };
 }

package/dist/runtime/createAgent.js

@@ -15,9 +15,10 @@ export async function createAgent(scope, agentId) {
     const definition = await new AgentRepository(scope.agentsDir).read(agentId);
     if (!definition)
         throw new Error(`Agent "${agentId}" 不存在`);
-    const modelId = definition.modelId ?? scope.config.defaultModel;
-    if (!modelId)
-        throw new Error("未指定模型且无默认模型");
+    const modelId = definition.modelId;
+    if (!modelId) {
+        throw new Error(`Agent "${agentId}" 未绑定模型（缺少 modelId）。请在配置里给它指定一个模型。`);
+    }
     const { client, model, modelConfig } = createModel(scope, modelId, definition.modelParams);
     const tools = scope.buildTools(definition, {
         exclude: {

package/dist/scope/plugins/builtin/ViewImageTool.js

@@ -29,7 +29,7 @@ function isLocalUrl(value) {
 export class ViewImageTool extends SdkCallbackTool {
     /** 仅视觉模型可用：从 definition.modelId 解析当前模型，非视觉模型由 buildTools 过滤 */
     isAvailable(config, definition) {
-        const modelId = definition.modelId ?? config.defaultModel;
+        const modelId = definition.modelId;
         const model = (config.models ?? []).find((m) => m.id === modelId);
         return model?.vision === true;
     }

package/dist/shared/content-blocks.js

@@ -74,9 +74,6 @@ export function resolveModelAndEndpoint(config, apiModelName) {
         : undefined;
     if (byApiName)
         return { model: byApiName, endpoint: findEndpoint(byApiName.endpointId) };
-    const fallback = models.find((m) => m.id === config.defaultModel);
-    if (fallback)
-        return { model: fallback, endpoint: findEndpoint(fallback.endpointId) };
     return { endpoint: null };
 }
 /** 端点是否声明了 Files API 能力 */

package/dist/types/index.d.ts

@@ -131,6 +131,12 @@ export interface AgentDefinition {
     name: string;
     description?: string;
     messages: AgentNS.Message[];
+    /**
+     * 绑定模型 id —— **运行期唯一真相源**。
+     *
+     * 缺省即「无模型可用」，`createAgent` 会直接报错；不存在配置层的 `defaultModel`
+     * 兜底，也不存在会话级的模型记录。要换模型就改这里（`/model` 写的就是它）。
+     */
     modelId?: string;
     /**
      * Agent 级模型参数覆盖，浅合并进模型的 `defaultParams`。
@@ -176,7 +182,6 @@ export interface ImageModel {
 }
 /** config.json 结构 */
 export interface AppConfig {
-    defaultModel?: string;
     endpoints: Endpoint[];
     models: Model[];
     /** 图片生成模型列表 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-zen/agents-sdk",
-  "version": "1.0.0-alpha.16",
+  "version": "1.0.0-alpha.18",
   "description": "AI-Zen Agents SDK — shared business logic for CLI and Desktop",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",