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

package/dist/config/ConfigManager.js

@@ -1,6 +1,7 @@
 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";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -54,17 +55,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 存在。
@@ -167,9 +179,47 @@ export class ConfigManager {
         const agent = await this.ensureDefaultAgent();
         const subAgent = await this.ensureDefaultSubAgent();
         await this.ensureDefaultMcpConfig();
+        await this.ensureFactorySkills();
         return { config, agent, subAgent };
     }
     // -----------------------------------------------------------------------
+    // 出厂 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 */
@@ -177,7 +227,7 @@ export class ConfigManager {
         return join(this.basePath, "mcp.json");
     }
     /**
-     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty）。
+     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty 与 chrome-devtools）。
      * 已有文件不被覆盖，尊重用户已配置的 MCP 服务器。
      * @returns 返回当前生效的 MCP 配置原始内容
      */
@@ -234,6 +284,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.d.ts

@@ -11,7 +11,9 @@ export declare const DEFAULT_SUBAGENT_DEFINITION: Omit<AgentDefinition, "created
 export declare const DEFAULT_APP_CONFIG: AppConfig;
 /**
  * SDK 出厂默认 MCP 服务器配置（mcp.json 内容，业界标准格式）。
- * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用 socket-pty 终端能力。
+ * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用：
+ *   - socket-pty       伪终端（pty）能力
+ *   - chrome-devtools  Chrome DevTools 浏览器调试/自动化能力（Google 官方 chrome-devtools-mcp）
  *
  * 若文件已存在则不覆盖（尊重用户已有配置）。
  */

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: "deepseek-v4-flash-vision-exp",
-            name: "DeepSeek-V4-Flash-Vision-Exp",
+            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-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,19 +206,21 @@ 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,
 };
 // ---------------------------------------------------------------------------
-// 默认 MCP 配置（socket-pty 终端 MCP）
+// 默认 MCP 配置（socket-pty 终端 MCP + chrome-devtools 浏览器调试 MCP）
 // ---------------------------------------------------------------------------
 /**
  * SDK 出厂默认 MCP 服务器配置（mcp.json 内容，业界标准格式）。
- * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用 socket-pty 终端能力。
+ * 首次初始化时释放到 ~/.ai-zen/mcp.json，让用户开箱即用：
+ *   - socket-pty       伪终端（pty）能力
+ *   - chrome-devtools  Chrome DevTools 浏览器调试/自动化能力（Google 官方 chrome-devtools-mcp）
  *
  * 若文件已存在则不覆盖（尊重用户已有配置）。
  */
@@ -200,6 +232,12 @@ export const DEFAULT_MCP_CONFIG = {
             args: ["-y", "@ai-zen/socket-pty", "mcp"],
             description: "可托管的伪终端（pty）：spawn/read/wait/write/resize/status/kill",
         },
+        "chrome-devtools": {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "chrome-devtools-mcp@latest"],
+            description: "Chrome DevTools 浏览器调试与自动化（Google chrome-devtools-mcp）：页面导航、性能追踪、网络与控制台检查、截图等",
+        },
     },
 };
 // ---------------------------------------------------------------------------

package/dist/config/factory-skills.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 出厂 Skill 资产 —— 随 SDK 版本释放到 `<basePath>/skills/<id>/SKILL.md`。
+ *
+ * 为什么以 TS 字符串常量内联、而不是独立 .md 文件：
+ * SDK 用 `tsc` 直接编译，不拷贝非 TS 资源；内容内联后 `dist/` 天然携带，
+ * 无需额外打包步骤，也不依赖包内相对资源路径。
+ *
+ * 覆盖策略（与 `syncManagedModels` 同构）：
+ *   - 磁盘上的 SKILL.md frontmatter 里写了 `custom: "true"` → 视为用户自有，永不被覆盖；
+ *   - 否则每次 `ConfigManager.bootstrap()` 同步为当前版本内容（模板属于产品行为，
+ *     改进了就要让老用户吃到）。
+ */
+/** 交接 Skill 的 id（目录名 = frontmatter name） */
+export declare const HANDOFF_SKILL_ID = "handoff";
+/**
+ * 交接文档兜底模板。
+ *
+ * 仅在磁盘上读不到 `handoff` Skill 时使用（用户删除 / 目录不可读）。
+ * 它是**保险丝**，不是第二真相源：正常路径下模板一律来自 SKILL.md。
+ */
+export declare const FALLBACK_HANDOFF_TEMPLATE: string;
+/** 全部出厂 Skill（顺序无意义，按 id 去重） */
+export declare const FACTORY_SKILLS: readonly {
+    id: string;
+    content: string;
+}[];
+/**
+ * 判断一份 SKILL.md 是否被用户声明为自有。
+ *
+ * 只检查 frontmatter 区块内的 `custom: true`（允许带引号），
+ * 正文里出现同样的字样不生效——避免误判导致模板停止更新。
+ */
+export declare function isCustomSkill(content: string): boolean;

package/dist/config/factory-skills.js

@@ -0,0 +1,126 @@
+/**
+ * 出厂 Skill 资产 —— 随 SDK 版本释放到 `<basePath>/skills/<id>/SKILL.md`。
+ *
+ * 为什么以 TS 字符串常量内联、而不是独立 .md 文件：
+ * SDK 用 `tsc` 直接编译，不拷贝非 TS 资源；内容内联后 `dist/` 天然携带，
+ * 无需额外打包步骤，也不依赖包内相对资源路径。
+ *
+ * 覆盖策略（与 `syncManagedModels` 同构）：
+ *   - 磁盘上的 SKILL.md frontmatter 里写了 `custom: "true"` → 视为用户自有，永不被覆盖；
+ *   - 否则每次 `ConfigManager.bootstrap()` 同步为当前版本内容（模板属于产品行为，
+ *     改进了就要让老用户吃到）。
+ */
+/** 交接 Skill 的 id（目录名 = frontmatter name） */
+export const HANDOFF_SKILL_ID = "handoff";
+/**
+ * 交接文档兜底模板。
+ *
+ * 仅在磁盘上读不到 `handoff` Skill 时使用（用户删除 / 目录不可读）。
+ * 它是**保险丝**，不是第二真相源：正常路径下模板一律来自 SKILL.md。
+ */
+export const FALLBACK_HANDOFF_TEMPLATE = [
+    "# 交接文档",
+    "",
+    "立即停工：不再实现任何功能、不继续未完成任务、不向用户提问。",
+    "唯一任务是：核实当前真实状态 → 把交接文档写到「本次交接参数」给出的路径。",
+    "",
+    "## 💬 对话断点",
+    "## 🎯 任务目标",
+    "## 📊 当前状态",
+    "## ✅ 已完成",
+    "## 📋 未完成",
+    "## 🧠 关键决策",
+    "## ⚠️ 约束与偏好",
+    "## 📁 文件索引",
+    "## 🔔 接手第一步",
+    "",
+    "无法核实的信息写「⚠️ 未核实」，禁止推测。",
+].join("\n");
+/** 出厂 Skill：交接（handoff） */
+const HANDOFF_SKILL = `---
+name: handoff
+description: 编写任务交接文档——对话停手离场时，把任务目标、当前真实状态、关键决策与下一步写成一份可被他人直接接手的文档。
+metadata:
+  custom: "false"
+---
+
+# 交接文档书写规范
+
+## 何时适用
+
+上下文即将超限触发任务迁移、用户明确要求「写交接文档」、或你被要求「交班」时。
+
+## 铁律（违反即视为失败）
+
+1. **立即停工**：不再实现任何功能、不继续未完成的任务、不顺手修 bug、不做重构。
+2. **不向用户提问**，不做方案讨论，不征求确认。
+3. 只做两件事：**核实当前真实状态** → **写文档**。
+4. 允许读取类操作（read / ls / glob / find_text / inspect_file / cwd，以及 git status、git diff、git log 等只读命令）。
+   禁止修改工作区：不改源码、不 npm install、不 commit、不 push。唯一允许写入的文件是交接文档本身。
+5. **一次性写完**，不要反复重写；不要读大文件；不要把长代码贴进文档。
+
+## 落盘
+
+路径由「本次交接参数」给出，**原样使用**，不得改名、不得换目录、不得省略。
+用 write 工具写入后，用 read 回读一次，确认内容完整（无 read 能力时跳过此步）。
+
+## 文档结构（按序书写，标题保持原样）
+
+## 💬 对话断点
+用户最后要求了什么、你最后回复/交付了什么。各一段，不要复述整段对话。
+
+## 🎯 任务目标
+用户到底想要什么（意图与验收标准），而不是你执行过的步骤清单。
+
+## 📊 当前状态
+分支与 commit、未提交改动、测试是否通过、有无进程/端口在跑、依赖是否装好。
+
+## ✅ 已完成
+每项写：做了什么 + 产出路径（文件/目录） + 怎么验证它确实生效。
+
+## 📋 未完成
+按优先级排列；每项写「下一步最小动作」，具体到文件或可执行命令。
+
+## 🧠 关键决策
+为什么这样做（取舍理由）；以及走过的死路——防止接手者重蹈覆辙。
+
+## ⚠️ 约束与偏好
+用户强调过的规矩、项目约定、不可改动的部分、必须遵守的风格。
+
+## 📁 文件索引
+路径 + 作用 + 本次是否改动（新增 / 修改 / 仅阅读）。
+
+## 🔔 接手第一步
+3 条以内可直接执行的命令或动作，让接手者立刻能开工。
+
+## 状态核实清单
+
+- \`git status\` / \`git diff --stat\`：当前分支、是否有未提交改动
+- 最近一次测试结果：跑过就写结果摘要；没跑就写「未运行」，**不要写「应该能过」**
+- 交接涉及的关键文件：用 ls / read 确认确实存在于磁盘
+- 正在运行的服务与端口：\`ps\` / \`lsof -i\` 或项目自带的启动脚本
+
+> ⚠️ 若「本次交接参数」声明工具不可用：以上每一项都写「⚠️ 未核实」，**禁止推测**具体路径、进度与测试状态。
+
+## 写作要求
+
+- 每句话都要让接手者能「立刻开始干活」；禁止「继续开发」「完善功能」「优化一下」这类空话。
+- 已无法在当前上下文中确定的信息，写「需向用户确认 XXX」，不要编造。
+- 全文控制在 300 行以内。
+`;
+/** 全部出厂 Skill（顺序无意义，按 id 去重） */
+export const FACTORY_SKILLS = [
+    { id: HANDOFF_SKILL_ID, content: HANDOFF_SKILL },
+];
+/**
+ * 判断一份 SKILL.md 是否被用户声明为自有。
+ *
+ * 只检查 frontmatter 区块内的 `custom: true`（允许带引号），
+ * 正文里出现同样的字样不生效——避免误判导致模板停止更新。
+ */
+export function isCustomSkill(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return false;
+    return /^\s*custom:\s*["']?true["']?\s*$/m.test(match[1]);
+}

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePl
 export { allInOne } from "./scope/plugins/allInOne.js";
 export type { AllInOneOptions } from "./scope/plugins/allInOne.js";
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
+export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
 export { createModel } from "./runtime/createModel.js";
@@ -30,16 +31,17 @@ export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.j
 export type { McpConnectOptions } from "./scope/plugins/mcp/McpConnectionManager.js";
 export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
 export type { SdkCallbackToolOptions } from "./scope/plugins/builtin/SdkCallbackTool.js";
-export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
-export type { MigrationContext, MigrationStrategy, TaskMigrationServiceOptions, } from "./runtime/TaskMigrationService.js";
+export { HandoffService } from "./runtime/HandoffService.js";
+export type { HandoffContext, HandoffMode, HandoffParams, HandoffServiceOptions, MigrateParams, MigrationStrategy, } from "./runtime/HandoffService.js";
+export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";
-export type { AutoMigrateOptions } from "./agent-plugins/AutoMigratePlugin.js";
+export type { AutoMigrateOptions, AutoMigrateTriggerInfo, AutoMigrateModeResolver, } from "./agent-plugins/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
 export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export type { ContextGuardOptions } from "./agent-plugins/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, } from "./scope/plugins/builtin/index.js";
 export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";

package/dist/index.js

@@ -17,6 +17,8 @@ export { SubAgentsScopePlugin } from "./scope/plugins/subagents/SubAgentsScopePl
 export { allInOne } from "./scope/plugins/allInOne.js";
 // 配置 — ConfigManager
 export { ConfigManager, DEFAULT_AGENT_ID, DEFAULT_AGENT_DEFINITION, DEFAULT_SUBAGENT_ID, DEFAULT_SUBAGENT_DEFINITION, DEFAULT_APP_CONFIG, DEFAULT_MCP_CONFIG, CONFIG_SUB_DIRS, } from "./config/ConfigManager.js";
+// 出厂资产 — 出厂 Skill（随版本释放到 <basePath>/skills/）
+export { FACTORY_SKILLS, HANDOFF_SKILL_ID, FALLBACK_HANDOFF_TEMPLATE, isCustomSkill, } from "./config/factory-skills.js";
 // CRUD — 实体仓储（仅 Agent 定义等能力实体）
 export { EntityRepository } from "./shared/EntityRepository.js";
 export { AgentRepository } from "./crud/AgentRepository.js";
@@ -26,7 +28,8 @@ export { SdkAgent } from "./runtime/SdkAgent.js";
 export { createAgent } from "./runtime/createAgent.js";
 export { McpConnectionManager } from "./scope/plugins/mcp/McpConnectionManager.js";
 export { SdkCallbackTool } from "./scope/plugins/builtin/SdkCallbackTool.js";
-export { TaskMigrationService } from "./runtime/TaskMigrationService.js";
+export { HandoffService } from "./runtime/HandoffService.js";
+export { HandoffGuardPlugin } from "./runtime/HandoffGuardPlugin.js";
 // 插件
 export { AutoMigratePlugin } from "./agent-plugins/AutoMigratePlugin.js";
 export { AutoRefreshToolsPlugin } from "./agent-plugins/AutoRefreshToolsPlugin.js";
@@ -34,7 +37,7 @@ export { ContextGuardPlugin } from "./agent-plugins/ContextGuardPlugin.js";
 export { UnknownToolHintPlugin } from "./agent-plugins/UnknownToolHintPlugin.js";
 // 工具 — 内置工具类 + 动态工具工厂
 export { BUILTIN_TOOL_CLASSES } from "./scope/plugins/builtin/index.js";
-export { CwdTool, ReadFileTool, InspectFileTool, WriteFileTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, ExecAsyncTool, SleepTool, } from "./scope/plugins/builtin/index.js";
+export { CwdTool, ReadTool, InspectFileTool, WriteTool, ExecTool, MkdirTool, RmTool, GlobTool, LsTool, ExistTool, FindTextTool, DownloadFileTool, RenameTool, CopyTool, BatchEditTool, EditTool, SpawnTool, SleepTool, } from "./scope/plugins/builtin/index.js";
 export { GenerateImageTool } from "./scope/plugins/builtin/GenerateImageTool.js";
 export { ViewImageTool } from "./scope/plugins/builtin/ViewImageTool.js";
 export { createLoadSkillTool, createCallSkillSubAgentTool } from "./scope/plugins/skills/skillTools.js";

package/dist/runtime/HandoffGuardPlugin.d.ts

@@ -0,0 +1,35 @@
+import type { AgentPlugin, ToolCallContext } from "@ai-zen/agents-core";
+/**
+ * 交接回合的工具守卫 —— 保证「原 agent 停下手头一切工作」不只是提示词约定。
+ *
+ * 交接由**同一个 agent** 在自己的会话里完成，它天然有继续干活的动力。
+ * 本插件在交接回合期间拦截写入类工具，只放行对交接文档那一份文件的写入：
+ *   - `write`：仅当目标路径（按交接时给定的 cwd 归一后）等于交接文档路径时放行；
+ *   - `edit` / `batch_edit` / `rm` / `rename` / `mkdir` / `copy`：一律拒绝；
+ *   - 读取类工具与其他工具：放行。
+ *
+ * 拒绝方式是**软拒绝**（返回字符串）：core 的 `onToolCall` 语义会把该字符串作为
+ * 工具结果回给模型并继续下一轮，因此模型能读到引导（「只允许写交接文档」）并转回正题。
+ * 反例：抛错会让该工具结果标记为 Error 且 `isPreventDefault`，整轮交接直接中断。
+ *
+ * 边界（必须如实记录，不要误以为是安全边界）：
+ *   - **挡不住 `exec`**：`echo > file`、`cat > file <<EOF` 永远能绕过。本插件降低的是
+ *     「顺手改代码」的误操作概率，不是沙箱。
+ *   - 一次性：`arm()` 后生效，`disarm()` 后完全让行。`Agent.use()` 没有移除 API，
+ *     故用「同一实例 + 开关」而非反复注册，避免插件数组无限增长。
+ */
+export declare class HandoffGuardPlugin implements AgentPlugin {
+    /** 写入类工具（除白名单的 write 外一律拒绝） */
+    private static readonly WRITE_TOOLS;
+    /** 当前交接文档绝对路径；undefined 表示未处于交接回合（完全让行） */
+    private handoffPath?;
+    /** 相对路径解析基准（交接时 agent 的 cwd） */
+    private cwd;
+    /** 进入交接回合：仅允许写入 handoffPath（相对路径按 cwd 归一） */
+    arm(handoffPath: string, cwd?: string): void;
+    /** 离开交接回合：恢复为完全让行 */
+    disarm(): void;
+    /** 是否处于交接回合（供上层/测试观察） */
+    get armed(): boolean;
+    onToolCall(ctx: ToolCallContext): string | undefined;
+}

package/dist/runtime/HandoffGuardPlugin.js

@@ -0,0 +1,65 @@
+import { resolve as resolvePath } from "node:path";
+/**
+ * 交接回合的工具守卫 —— 保证「原 agent 停下手头一切工作」不只是提示词约定。
+ *
+ * 交接由**同一个 agent** 在自己的会话里完成，它天然有继续干活的动力。
+ * 本插件在交接回合期间拦截写入类工具，只放行对交接文档那一份文件的写入：
+ *   - `write`：仅当目标路径（按交接时给定的 cwd 归一后）等于交接文档路径时放行；
+ *   - `edit` / `batch_edit` / `rm` / `rename` / `mkdir` / `copy`：一律拒绝；
+ *   - 读取类工具与其他工具：放行。
+ *
+ * 拒绝方式是**软拒绝**（返回字符串）：core 的 `onToolCall` 语义会把该字符串作为
+ * 工具结果回给模型并继续下一轮，因此模型能读到引导（「只允许写交接文档」）并转回正题。
+ * 反例：抛错会让该工具结果标记为 Error 且 `isPreventDefault`，整轮交接直接中断。
+ *
+ * 边界（必须如实记录，不要误以为是安全边界）：
+ *   - **挡不住 `exec`**：`echo > file`、`cat > file <<EOF` 永远能绕过。本插件降低的是
+ *     「顺手改代码」的误操作概率，不是沙箱。
+ *   - 一次性：`arm()` 后生效，`disarm()` 后完全让行。`Agent.use()` 没有移除 API，
+ *     故用「同一实例 + 开关」而非反复注册，避免插件数组无限增长。
+ */
+export class HandoffGuardPlugin {
+    /** 写入类工具（除白名单的 write 外一律拒绝） */
+    static WRITE_TOOLS = new Set([
+        "edit",
+        "batch_edit",
+        "rm",
+        "rename",
+        "mkdir",
+        "copy",
+    ]);
+    /** 当前交接文档绝对路径；undefined 表示未处于交接回合（完全让行） */
+    handoffPath;
+    /** 相对路径解析基准（交接时 agent 的 cwd） */
+    cwd = process.cwd();
+    /** 进入交接回合：仅允许写入 handoffPath（相对路径按 cwd 归一） */
+    arm(handoffPath, cwd) {
+        this.cwd = cwd ? resolvePath(cwd) : process.cwd();
+        this.handoffPath = resolvePath(this.cwd, handoffPath);
+    }
+    /** 离开交接回合：恢复为完全让行 */
+    disarm() {
+        this.handoffPath = undefined;
+    }
+    /** 是否处于交接回合（供上层/测试观察） */
+    get armed() {
+        return this.handoffPath !== undefined;
+    }
+    onToolCall(ctx) {
+        const handoffPath = this.handoffPath;
+        if (handoffPath == null)
+            return;
+        const name = ctx.tool_call?.function?.name ?? "";
+        if (name === "write") {
+            const raw = ctx.parsedArgs?.path;
+            if (typeof raw === "string" && resolvePath(this.cwd, raw) === handoffPath) {
+                return;
+            }
+            return `交接回合只允许写交接文档：${handoffPath}（write 的 path 请原样使用该路径），请立即开始撰写。`;
+        }
+        if (HandoffGuardPlugin.WRITE_TOOLS.has(name)) {
+            return `交接回合禁止修改工作区（${name}）：你的唯一任务是把交接文档写入 ${handoffPath}。`;
+        }
+        return;
+    }
+}