@ai-zen/agents-sdk 1.0.0-alpha.0 → 1.0.0-alpha.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.0.0-alpha.1] - 2026-10-03
+
+### 💥 Breaking Changes
+
+- **Factory model catalog refreshed (verified against vendor sources on 2026-10-03)** — every stale or retired model ID in `DEFAULT_APP_CONFIG.models` is replaced:
+  - **OpenAI**: `gpt-5.5` → `gpt-6-astra` / `gpt-6.1-sol` / `gpt-6-luna`
+  - **Zhipu**: `glm-5.1` / `glm-5v-turbo` → `glm-5.3` / `glm-5.3-flash` / `glm-5.3-flashx`
+  - **DeepSeek**: `deepseek-v4-pro` / `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` → `deepseek-flash`. The two V4-Flash variants were retired by the vendor, and V4-Pro requests are routed to V4.1-Flash.
+  - Defaults: `defaultModel` / `defaultMigrationModel` move from `deepseek-v4-flash` to `deepseek-flash`.
+- **`Model.maxContextTokens` semantics clarified — it is the task-migration (handoff) trigger threshold, not the model context window** — `AutoMigratePlugin` does not estimate or learn: it only compares `usage.prompt_tokens` from the API response against this value. The previous comment read "上下文窗口 token 上限" ("context window token limit"), which is why values had been filled in with raw window sizes. Values are now ~25% of the real window (250K for ≥1M-window models), except `glm-4.7-flash` (200K window) which uses 100K.
+
+### 🚀 New Features
+
+- **Managed model catalog sync (`custom` opt-out)** — `ConfigManager.ensureDefaultConfig()` now reconciles the factory catalog on every `bootstrap()`. Entries in `models` / `imageModels` that do **not** carry `custom: true` are dropped and replaced by the latest `DEFAULT_APP_CONFIG` definitions; entries marked `custom: true` are treated as user-owned and kept verbatim (user wins on id collision, no duplicates). A dangling `defaultModel` / `defaultImageModel` / `defaultMigrationModel` falls back to the factory default, so no reference is ever left pointing at a removed model. `endpoints` are never managed. The sync is idempotent — it only writes when something actually changed. Implemented in `ConfigManager.syncManagedModels`.
+- **`Model` / `ImageModel` gained an optional `custom?: boolean` field** — marks an entry as user-owned so the factory sync leaves it untouched.
+
+### ✅ Tests
+
+- Added coverage for the model catalog sync: stale non-custom entries replaced, `custom: true` entries preserved, user version winning on id collision without duplication, image models reconciled, dangling default IDs falling back, and idempotency across repeated calls.
+- E2E model IDs updated to the current vendor names (`deepseek-flash`).
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.1`.
+- `DEFAULT_APP_CONFIG` row in `sdk-design-v0.md` updated to the new model catalog.
+
 ## [1.0.0-alpha.0] - 2026-09-30
 
 ### 💥 Breaking Changes

package/dist/config/ConfigManager.d.ts

@@ -18,6 +18,11 @@ export declare class ConfigManager {
     ensureDirs(): Promise<void>;
     /**
      * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
+     *
+     * 已存在时执行「出厂模型清单同步」（见 syncManagedModels）：
+     * models / imageModels 中凡是**没有** `custom: true` 的条目一律视为出厂托管，
+     * 会被移除并替换为 DEFAULT_APP_CONFIG 中的最新定义；标了 `custom: true` 的
+     * 条目视为用户自有，原样保留。同步结果与磁盘内容一致时不写盘。
      */
     ensureDefaultConfig(): Promise<AppConfig>;
     /**
@@ -70,4 +75,16 @@ export declare class ConfigManager {
     /** 原子写 JSON 文件（先写 .tmp 再 rename，避免半成品）。 */
     private writeJson;
 }
+/**
+ * 同步出厂托管的模型清单（与默认 Agent 的 custom 机制一致）。
+ *
+ * 规则：
+ * - 未标 `custom: true` 的条目 → 由 SDK 托管，从结果中移除，改用 defaults 中的最新定义；
+ * - 标了 `custom: true` 的条目 → 用户自有，原样保留；与出厂定义同 id 时用户版本优先；
+ * - 默认模型 ID（defaultModel / defaultImageModel / defaultMigrationModel）
+ *   在合并后若已不存在 → 回退到出厂默认，避免悬空引用。
+ *
+ * 端点（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";

package/dist/config/ConfigManager.js

@@ -54,17 +54,28 @@ export class ConfigManager {
     }
     /**
      * 确保 config.json 存在。不存在时写入出厂默认配置 DSL。
+     *
+     * 已存在时执行「出厂模型清单同步」（见 syncManagedModels）：
+     * models / imageModels 中凡是**没有** `custom: true` 的条目一律视为出厂托管，
+     * 会被移除并替换为 DEFAULT_APP_CONFIG 中的最新定义；标了 `custom: true` 的
+     * 条目视为用户自有，原样保留。同步结果与磁盘内容一致时不写盘。
      */
     async ensureDefaultConfig() {
+        let existing;
         try {
             await fs.access(this.configPath);
-            return await this.read();
+            existing = await this.read();
         }
         catch {
             await this.ensureDirs();
             await this.write(DEFAULT_APP_CONFIG);
             return { ...DEFAULT_APP_CONFIG };
         }
+        const synced = syncManagedModels(existing);
+        if (JSON.stringify(synced) !== JSON.stringify(existing)) {
+            await this.write(synced);
+        }
+        return synced;
     }
     /**
      * 确保 basePath/agents/default.json 存在。
@@ -234,6 +245,38 @@ export class ConfigManager {
         await fs.rename(tmpPath, path);
     }
 }
+/**
+ * 同步出厂托管的模型清单（与默认 Agent 的 custom 机制一致）。
+ *
+ * 规则：
+ * - 未标 `custom: true` 的条目 → 由 SDK 托管，从结果中移除，改用 defaults 中的最新定义；
+ * - 标了 `custom: true` 的条目 → 用户自有，原样保留；与出厂定义同 id 时用户版本优先；
+ * - 默认模型 ID（defaultModel / defaultImageModel / defaultMigrationModel）
+ *   在合并后若已不存在 → 回退到出厂默认，避免悬空引用。
+ *
+ * 端点（endpoints）不参与托管，始终保持用户配置。
+ */
+export function syncManagedModels(config) {
+    const pick = (existing, defaults) => {
+        const kept = (existing ?? []).filter((m) => m.custom === true);
+        const keptIds = new Set(kept.map((m) => m.id));
+        // 出厂定义在前，用户自有条目随后；同 id 时用户版本胜出（出厂侧已剔除）
+        return [...defaults.filter((m) => !keptIds.has(m.id)), ...kept];
+    };
+    const models = pick(config.models, DEFAULT_APP_CONFIG.models);
+    const imageModels = pick(config.imageModels, DEFAULT_APP_CONFIG.imageModels ?? []);
+    const modelIds = new Set(models.map((m) => m.id));
+    const imageIds = new Set(imageModels.map((m) => m.id));
+    const resolve = (id, ids, fallback) => id && ids.has(id) ? id : fallback;
+    return {
+        ...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),
+    };
+}
 /**
  * 比较两段消息列表的提示词内容是否一致。
  *

package/dist/config/constants.js

@@ -85,71 +85,101 @@ export const DEFAULT_APP_CONFIG = {
             description: "DeepSeek API 端点",
         },
     ],
+    // 模型清单（2026-10-03 依据各厂商官方来源核对）：
+    //   OpenAI   → openai.com 发布公告 / API 目录（platform 文档站对脚本有访问限制）
+    //   智谱     → docs.bigmodel.cn 模型概览/定价 + open.bigmodel.cn/api/paas/v4/models
+    //   DeepSeek → api-docs.deepseek.com 定价页与 News + api.deepseek.com/v1/models
+    //
+    // 更新策略：本清单为「出厂托管」清单。用户 config.json 中凡未标 `custom: true`
+    // 的模型（含 imageModels）在初始化时一律被移除并替换为本清单中的最新定义；
+    // 标了 `custom: true` 的条目视为用户自有，原样保留。实现见
+    // ConfigManager.syncManagedModels。
+    //
+    // maxContextTokens 是「任务迁移（交接）触发阈值」，不是模型的真实上下文窗口：
+    // 迁移判断只看 API 响应返回的 usage.prompt_tokens。窗口 ≥1M 的模型统一取 250K
+    // （约 25%），glm-4.7-flash 窗口仅 200K，取 100K。
     models: [
+        // ---------- OpenAI ----------
         {
-            id: "gpt-5.5",
-            name: "GPT-5.5",
+            id: "gpt-6-astra",
+            name: "GPT-6 Astra",
             endpointId: "openai",
-            modelName: "gpt-5.5",
+            modelName: "gpt-6-astra",
             maxContextTokens: 250_000,
             defaultParams: {},
-            description: "OpenAI 最新旗舰模型，擅长编程与代码调试、在线研究、数据分析",
+            vision: true,
+            description: "OpenAI 最强旗舰（2026-09）：高级分析、软件工程、深度研究与科学工作",
         },
         {
-            id: "glm-5.1",
-            name: "GLM-5.1",
-            endpointId: "bigmodelcn",
-            modelName: "glm-5.1",
+            id: "gpt-6.1-sol",
+            name: "GPT-6.1 Sol",
+            endpointId: "openai",
+            modelName: "gpt-6.1-sol",
             maxContextTokens: 250_000,
             defaultParams: {},
-            description: "智谱AI 最新旗舰模型，支持8小时长程Agent任务",
+            vision: true,
+            description: "OpenAI 最新旗舰（2026-09-29）：Agentic Coding、计算机操作与文档密集型专业任务",
         },
         {
-            id: "glm-5v-turbo",
-            name: "GLM-5V-Turbo",
-            endpointId: "bigmodelcn",
-            modelName: "glm-5v-turbo",
+            id: "gpt-6-luna",
+            name: "GPT-6 Luna",
+            endpointId: "openai",
+            modelName: "gpt-6-luna",
             maxContextTokens: 250_000,
             defaultParams: {},
             vision: true,
-            description: "智谱AI 多模态Coding基座（支持图片输入）",
+            description: "OpenAI GPT-6 系列快速低成本模型：适合高吞吐、低延迟场景",
         },
+        // ---------- 智谱 BigModel ----------
         {
-            id: "glm-4.7-flash",
-            name: "GLM-4.7-Flash",
+            id: "glm-5.3",
+            name: "GLM-5.3",
             endpointId: "bigmodelcn",
-            modelName: "glm-4.7-flash",
+            modelName: "glm-5.3",
             maxContextTokens: 250_000,
-            defaultParams: {},
-            description: "智谱AI 免费轻量模型",
+            defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            description: "智谱最新旗舰：复杂软件工程与长程 Agent 任务（强制开启思考，1M 上下文）",
         },
         {
-            id: "deepseek-v4-pro",
-            name: "DeepSeek-V4-Pro",
-            endpointId: "deepseek",
-            modelName: "deepseek-v4-pro",
+            id: "glm-5.3-flash",
+            name: "GLM-5.3-Flash",
+            endpointId: "bigmodelcn",
+            modelName: "glm-5.3-flash",
             maxContextTokens: 250_000,
-            defaultParams: { thinking: { type: "disabled" } },
-            description: "DeepSeek 旗舰模型，Agentic Coding开源第一",
+            defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            vision: true,
+            description: "智谱原生多模态模型（图片/视频/文件）：视觉 Coding，1M 上下文",
         },
         {
-            id: "deepseek-v4-flash",
-            name: "DeepSeek-V4-Flash",
-            endpointId: "deepseek",
-            modelName: "deepseek-v4-flash",
+            id: "glm-5.3-flashx",
+            name: "GLM-5.3-FlashX",
+            endpointId: "bigmodelcn",
+            modelName: "glm-5.3-flashx",
             maxContextTokens: 250_000,
-            defaultParams: { thinking: { type: "enabled" } },
-            description: "DeepSeek 经济高效模型",
+            defaultParams: { thinking: { type: "enabled" }, reasoning_effort: "max" },
+            vision: true,
+            description: "GLM-5.3-Flash 高速版（200 tokens/s），原生多模态",
+        },
+        {
+            id: "glm-4.7-flash",
+            name: "GLM-4.7-Flash",
+            endpointId: "bigmodelcn",
+            modelName: "glm-4.7-flash",
+            // 该模型真实窗口仅 200K，阈值下调至 100K（约窗口的 50%），留足 response 空间
+            maxContextTokens: 100_000,
+            defaultParams: {},
+            description: "智谱免费文本模型：200K 上下文，适合轻量任务",
         },
+        // ---------- DeepSeek ----------
         {
-            id: "deepseek-v4-flash-vision-exp",
-            name: "DeepSeek-V4-Flash-Vision-Exp",
+            id: "deepseek-flash",
+            name: "DeepSeek-V4.1-Flash",
             endpointId: "deepseek",
-            modelName: "deepseek-v4-flash-vision-exp",
+            modelName: "deepseek-flash",
             maxContextTokens: 250_000,
             defaultParams: { thinking: { type: "enabled" } },
             vision: true,
-            description: "DeepSeek 视觉实验模型（支持图片/文件输入）",
+            description: "DeepSeek 旗舰（2026-09-10）：552B MoE 非对称架构，原生多模态，1M 上下文",
         },
     ],
     imageModels: [
@@ -176,10 +206,10 @@ export const DEFAULT_APP_CONFIG = {
             defaultSize: "1024x1024",
         },
     ],
-    defaultModel: "deepseek-v4-flash",
+    defaultModel: "deepseek-flash",
     defaultImageModel: "cogview-4",
     defaultAgent: "default",
-    defaultMigrationModel: "deepseek-v4-flash",
+    defaultMigrationModel: "deepseek-flash",
     // 工具输出上限（字符数），与 DEFAULT_MAX_TOOL_OUTPUT 保持一致
     maxToolOutput: 32_768,
 };

package/dist/types/index.d.ts

@@ -26,13 +26,27 @@ export interface Model {
     name: string;
     endpointId: string;
     modelName?: string;
+    /**
+     * 任务迁移（交接）触发阈值 —— **不是**模型的真实上下文窗口。
+     *
+     * AutoMigratePlugin 不估算、不学习：只在 API 响应返回后，用 `usage.prompt_tokens`
+     * 与该值比较，超过即触发交接迁移。建议取模型真实窗口的约 25%，为 response 留出空间。
+     */
     maxContextTokens: number;
+    /** 旧版字符数阈值（兼容迁移） */
     maxContextChars?: number;
     defaultParams?: Record<string, unknown>;
     /** 是否支持图片输入（视觉模型）。看图工具（viewImage）仅对视觉模型启用；generateImage 是否返回图片内容块也据此判断 */
     vision?: boolean;
     description?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.models 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** Agent 定义，有 function 字段时为 SubAgent */
 export interface AgentDefinition {
@@ -64,6 +78,13 @@ export interface ImageModel {
     defaultSize?: string;
     defaultQuality?: string;
     version?: number;
+    /**
+     * 是否用户自定义。
+     *
+     * 为 true 时 SDK 初始化不会用出厂定义替换该模型；缺省（或 false）视为出厂托管，
+     * 初始化时会与 DEFAULT_APP_CONFIG.imageModels 同步（出厂清单为准）。
+     */
+    custom?: boolean;
 }
 /** config.json 结构 */
 export interface AppConfig {

package/package.json

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