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

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # Changelog
 
+## [1.0.0-alpha.10] - 2026-10-20
+
+### 💥 Breaking Changes
+
+- **`TaskMigrationService` → `HandoffService`，并拆成 `handoff()` / `migrate()` 两层** —— 「交接」（写交接文档）与「迁移」（交接 + 开新会话）此前混在一个方法里，现在概念与 API 一一对应：
+  - `handoff(params)`：停工 → 核实 → 写文档 → 校验（失败降级）。**不改动会话**；
+  - `migrate(params)`：`handoff()` 之后按 `strategy` 清历史并注入断点消息。
+  - 类型随迁：`MigrationContext` → `HandoffContext`（新增 `mode` / `requestedMode` / `handoffPath` / `migrating`），`TaskMigrationServiceOptions` → `HandoffServiceOptions`（新增 `handoffDir` / `mode` / `skillDirs` / `minHandoffBytes`）。
+  - 钩子重命名：`onBeforeMigrate` → `onBeforeHandoff`，新增 `onHandoff`（文档写好、清历史之前）。
+- **交接文档改由「原 agent 在自己会话里写」（`mode: "self"`，默认）**，而非另起一次独立的摘要调用。原实现把历史序列化成 `[role]: content` 后交给一个无工具、无原会话上下文的调用，工具名与调用参数在序列化时全部丢失，写文档的一方也无法核实分支/改动/测试状态，只能靠推演——这是文档质量差的根因。现在的 `self` 回合：原 agent 保留全部上下文与工具，可 `read` / `exec` / `git status` 核实后落盘。
+- **`summary`（旧的独立摘要）保留为逃生模式**，并作为 `self` 失败时的**单向**降级目标（无 `write` 工具 / 文件缺失或过小（重试一次）/ 工具或护栏报错）。反向永不发生——那会在上下文最满的时刻再加一次全量请求。
+- **`AutoMigrateOptions` 新增 `resolveMode`**，把「用谁交接」从插件继承转移到回调：返回 `HandoffMode` 或 `null`（跳过本次迁移）。原 CLI 的 `AutoMigrateConfirmPlugin` 子类因此退化为纯回调。
+
+### ✨ 新增
+
+- **`HandoffGuardPlugin`**：交接回合的一次性工具守卫。只放行 `write` 到交接文档（绝对路径归一后比较），拒绝 `edit` / `batch_edit` / `rm` / `rename` / `mkdir` / `copy`。拒绝返回字符串（软拒绝）而非抛错——抛错会被 core 标记为 Error + `isPreventDefault`，整轮交接直接死。边界如实记录：挡不住 `exec`，它降低误操作概率，不是沙箱。
+- **`ContextGuardPlugin` 新增 `isSuspended` / `suspendedRatio`**：交接回合（`service.busy`）把硬上限从 `× 1.5` 放宽到 `× 2`，既不被误杀又保留熔断。
+- **出厂 Skill 机制**：`ConfigManager.ensureFactorySkills()` 在 `bootstrap()` 中释放 / 同步 `skills/handoff/SKILL.md`。覆盖策略与 `syncManagedModels` 同构——frontmatter 标 `metadata.custom: "true"` 视为用户自有、永不覆盖；否则随版本同步。内容以字符串常量内联在 `config/factory-skills.ts`（`tsc` 直接编译，无需打包非 TS 资源）。
+- **交接模板的唯一真相源改为 Skill**：`HANDOFF_SECTIONS` / `createPrompt()` 已删除，代码只保留「读 Skill → 注入 → 校验文件 → 读不到时用 `FALLBACK_HANDOFF_TEMPLATE`」。Skill 只讲「怎么写」，代码只讲「写到哪、有什么能力」（本体系无模板变量引擎，不发明占位符）。
+- `HandoffService.createHandoffFileName()`（`<YYYYMMDD-HHmmss>-<会话id前8位>.md`）、`createHandoffInstruction()`、`createPostMessages(handoffPath)`（断点**只给路径**，由接手方 `read`）。
+
+### 🔧 修复
+
+- **交接触发的无限递归**：交接回合本身是一次 `send()`，其 `onAfterSend` 会再次进入 `AutoMigratePlugin`。现以 `service.busy` 让行（`handoff()` / `migrate()` 共用一把锁，顺带拒绝重入）。
+- **交接回合被自己触发/被护栏击杀**：交接恰好发生在上下文最满的时刻。除 `busy` 让行外，交接回合开跑前清空 `agent.lastUsage`（纵深防御），并由调用方在迁移后清空（否则护栏拿交接回合用量误杀新会话第一条消息）。
+
+### ✅ 测试
+
+- 新增 `HandoffService.test.ts`（24 例）、`HandoffGuardPlugin.test.ts`（7 例）、`factory-skills.test.ts`（7 例）；重写 `AutoMigratePlugin.test.ts`、`ContextGuardPlugin.test.ts`（新增 `isSuspended` 4 例）。全量 **54 文件 / 525 用例**通过，`tsc --noEmit` 与 `build` 零错误。
+
+### 📄 Docs
+
+- `docs/sdk-design-v1.md` §18 重写为「任务交接（HandoffService）」（两层语义、Template 单一真相源、两种执行者、自交接三道保险、接口、断点只给路径）；§17 插件章节、目录树与消费示例同步。
+- `README.md` / `README.zh.md`、`../docs/{en,zh}/sdk.md`、`architecture.md`、`getting-started.md` 及网站镜像同步。
+
+
+## [1.0.0-alpha.9] - 2026-10-14
+
+### ⚠️ Dependency
+
+- **`@ai-zen/agents-core` bumped to `^4.5.1`** — docs-only patch; no SDK source change.
+
+### 📄 Docs
+
+- Corrected the factory-defaults description in `docs/sdk-design-v1.md`: the preset **model count is 8** (was 7), and `DEFAULT_MCP_CONFIG` ships **two** servers (`socket-pty` + `chrome-devtools`).
+
+## [1.0.0-alpha.8] - 2026-10-14
+
+### ⚠️ Dependency
+
+- **`@ai-zen/agents-core` bumped to `^4.5.0`** — picks up `AgentNS.Message.subAgentUsage` and the `sumUsage()` primitive. The skill sub-agent tool (`call_skill_sub_agent`) is built on `AgentToolLazy`, so it inherits the delegation-boundary stamping with no SDK source change.
+
+## [1.0.0-alpha.7] - 2026-10-14
+
+### ⚠️ Dependency
+
+- **`@ai-zen/agents-core` bumped to `^4.4.0`** — picks up `AgentNS.Message.usage` (per-message token usage, stamped from the final stream chunk). No SDK source change; the `workspace:^` range resolves to `^4.4.0` on publish.
+
+## [1.0.0-alpha.6] - 2026-10-13
+
+### 💥 Breaking Changes
+
+- **`exec_async` renamed to `spawn`** — the tool wraps `child_process.spawn` and returns `{ success, pid, message }`, so the new name matches both the implementation and the "start a process, get its pid" contract. It also pairs cleanly with `exec`: `exec` runs and **waits** (captures output, has a `timeout`), `spawn` starts and **returns immediately**. Permission lists, skill `allowed-tools` and any prompt naming `exec_async` must switch to `spawn`. The behaviour is otherwise unchanged — still shell-parsed, still does **not** capture output (redirect to a file if you need it).
+- **Built-in tool classes renamed to match their new tool names** — `ReadFileTool` → `ReadTool`, `WriteFileTool` → `WriteTool`, `ExecAsyncTool` → `SpawnTool`, with the source files renamed to match. The classes re-exported from `@ai-zen/agents-sdk` change accordingly, so consumers importing them by name must update.
+
+## [1.0.0-alpha.5] - 2026-10-13
+
+### 💥 Breaking Changes
+
+- **All built-in tool names unified on `snake_case`** — the multi-word tools that used camelCase were renamed. A tool name is the API contract the model sees and is matched **verbatim** by the permission system, so any `permissions.allow` / `deny` list, skill `allowed-tools` entry or prompt that names a tool must be updated:
+
+  | old | new |
+  |---|---|
+  | `readFile` | `read` |
+  | `writeFile` | `write` |
+  | `inspectFile` | `inspect_file` |
+  | `findText` | `find_text` |
+  | `batchEdit` | `batch_edit` |
+  | `downloadFile` | `download_file` |
+  | `generateImage` | `generate_image` |
+  | `viewImage` | `view_image` |
+
+  Single-word tools (`cwd`, `edit`, `glob`, `ls`, `mkdir`, `rm`, `rename`, `copy`, `exec`, `exist`, `sleep`), the already-`snake_case` `exec_async`, the MCP / skill wrapper tools and core's `indexed_search` are unchanged. Tool descriptions and docs were updated in the same pass.
+
+### 🔧 Changed
+
+- **Dependency `@ai-zen/agents-core` bumped to `^4.3.2`** (carries the `indexedSearch` → `indexed_search` rename).
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.5`.
+
+## [1.0.0-alpha.4] - 2026-10-13
+
+### 🔧 Changed
+
+- **Dependency `@ai-zen/agents-core` bumped to `^4.3.1`** (declared as `workspace:^`, expanded to `^4.3.1` at publish time). Pulls in core 4.3.1's fix for interrupted parallel tool rounds — the assistant message carrying `tool_calls` and its results now stay all-in or all-out, so an interrupted parallel tool call no longer leaves orphan `tool` results that the server rejects. `AgentContext` gains `abortedToolRoundStrategy` (default `"fill"`) and `abortedToolRoundReason`; set `agent.abortedToolRoundStrategy = "drop"` to drop the whole round instead
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.4`.
+
+## [1.0.0-alpha.3] - 2026-10-03
+
+### 🔧 Fixed
+
+- **`generateImage` `model` parameter description no longer points at a host-CLI command** — the description used to read "配置中的图片模型可通过 'aiz config show' 查看" (the configured image models can be viewed via `aiz config show`). Since tool descriptions ship inside every request's `tools` payload, that hint propagated into **every layer** of the agent stack: the model would `exec("aiz config show")`, but the CLI resolves a bare `aiz config show` invocation as stdio mode with the instruction `config show` — i.e. a **brand-new agent** — whose own `generateImage` description repeats the very same hint, producing a self-referential recursion that keeps spawning nested agents. The parameter now reads "若指定的模型不存在，本工具会返回当前可用的模型列表" (if the specified model does not exist, this tool returns the list of currently available models), which matches the actual `!imageModel` branch in `call()` and stops the model from shelling out to the host CLI.
+
+### 📄 Docs
+
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.3`.
+
+## [1.0.0-alpha.2] - 2026-10-03
+
+### 🚀 New Features
+
+- **`chrome-devtools` added to the factory default MCP config** — `DEFAULT_MCP_CONFIG` now ships two servers instead of one: alongside `socket-pty`, a freshly released `~/.ai-zen/mcp.json` includes `chrome-devtools` (`npx -y chrome-devtools-mcp@latest`, Google's official `chrome-devtools-mcp`), so browser debugging and automation work out of the box — page navigation, performance traces, network and console inspection, screenshots. Existing `mcp.json` files are still never overwritten, so user configurations (including custom flags such as `--executablePath`) are untouched. Defined in `packages/sdk/src/config/constants.ts`, released by `ConfigManager.ensureDefaultMcpConfig()`.
+
+### ✅ Tests
+
+- `ConfigManager.bootstrap.test.ts` now asserts the factory-default `mcp.json` carries both `socket-pty` and `chrome-devtools` (the latter resolved from the `chrome-devtools-mcp` package via `npx`), covering both the `bootstrap()` and `ensureDefaultMcpConfig()` paths.
+
+### 📄 Docs
+
+- Factory-default MCP descriptions in `docs/zh/mcp.md` / `docs/en/mcp.md` and `docs/zh/sdk.md` / `docs/en/sdk.md` now list both `socket-pty` and `chrome-devtools`.
+- Current-version references in `docs/zh` and `docs/en` updated to `1.0.0-alpha.2`.
+
 ## [1.0.0-alpha.1] - 2026-10-03
 
 ### 💥 Breaking Changes

package/README.md

@@ -21,7 +21,7 @@ Desktop ──┘                    │
 types         ← pure types, zero business dependencies (incl. ToolEnv)
 config        ← ConfigManager + constants: config.json read/write + directory setup + factory defaults
 crud          ← capability-entity CRUD (Agent definitions; conversations/drafts are persisted by each consumer)
-runtime       ← model factory + Agent assembly + task migration (createModel / createAgent / SdkAgent / TaskMigrationService)
+runtime       ← model factory + Agent assembly + task handoff/migration (createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin)
 scope         ← Scope orchestration container + ScopePlugin contract + PermissionEvaluator / disclosure + plugins/ (5 self-contained capability sources: discovery + tools + plugin)
 agent-plugins ← Agent plugins (autoMigrate, autoRefreshTools, contextGuard, unknownToolHint)
 shared        ← logging, errors
@@ -68,8 +68,9 @@ const scope = new Scope({
 await scope.init();
 
 const agent = await createAgent(scope, "my-agent");
-const migrationService = new TaskMigrationService({ onMigrated }); // migrates via the agent's own model client
-agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
+const handoffService = new HandoffService({ handoffDir: "/work/.ai-zen/handoffs", skillDirs });
+agent.use(new ContextGuardPlugin({ maxTokens, isSuspended: () => handoffService.busy }));
+agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
 agent.use(new UnknownToolHintPlugin({ scope }));
 await agent.init();
@@ -97,21 +98,21 @@ All built-in tools are classes (extending `SdkCallbackTool`), instantiated by th
 | Tool | Description |
 |------|-------------|
 | `cwd` | Get the current working directory |
-| `readFile` | Read a file (optional `range` for line/column slicing; oversized output warns and suggests batched reads) |
-| `inspectFile` | Inspect a file's structural overview (line count, column distribution, etc.); streamed scan, not limited by the 300KB read threshold |
-| `writeFile` | Write a file |
+| `read` | Read a file (optional `range` for line/column slicing; oversized output warns and suggests batched reads) |
+| `inspect_file` | Inspect a file's structural overview (line count, column distribution, etc.); streamed scan, not limited by the 300KB read threshold |
+| `write` | Write a file |
 | `exec` | Execute a command (supports `timeout`; oversized stdout+stderr is dumped to `stdout.log` / `stderr.log`) |
-| `exec_async` | Execute a command asynchronously, returns immediately without waiting |
+| `spawn` | Execute a command asynchronously, returns immediately without waiting |
 | `mkdir` | Create a directory |
 | `rm` | Delete a file or directory |
 | `glob` | Scan and find files using glob patterns (oversized output dumped to `result.json`) |
 | `ls` | List directory contents (oversized output dumped to `result.json`) |
 | `exist` | Check whether a file or directory exists |
-| `findText` | Search for text or regex in files (oversized output dumped to `result.json`) |
-| `downloadFile` | Download a file from a URL and save it locally |
+| `find_text` | Search for text or regex in files (oversized output dumped to `result.json`) |
+| `download_file` | Download a file from a URL and save it locally |
 | `rename` | Rename or move a file/directory |
 | `copy` | Copy a file or directory |
-| `batchEdit` | Batch-edit file text (only unmatched items are echoed back; successful ones are counted) |
+| `batch_edit` | Batch-edit file text (only unmatched items are echoed back; successful ones are counted) |
 | `edit` | Edit text in a file |
 | `sleep` | Wait for a specified number of milliseconds |
 
@@ -119,16 +120,16 @@ Conditionally injected based on the active model / config:
 
 | Tool | Injection Condition | Description |
 |------|---------------------|-------------|
-| `generateImage` | Only when `defaultImageModel` is configured | Generate an image from a text description |
-| `viewImage` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
+| `generate_image` | Only when `defaultImageModel` is configured | Generate an image from a text description |
+| `view_image` | Only for vision models (the agent's `modelId` resolves to a model with `vision: true`) | View / analyze an image: local images are auto-uploaded via the Files API, network URLs are referenced directly |
 
-Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `findText` / `glob` / `ls` dump `result.json` (returning a head preview), and `readFile` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md).
+Tool output protection: `AppConfig.maxToolOutput` (in characters, default 32768) is the unified ceiling for tool output. Each tool handles overflow itself — `exec` dumps `stdout.log` / `stderr.log` separately (returning head/tail previews per stream), `find_text` / `glob` / `ls` dump `result.json` (returning a head preview), and `read` only warns and suggests batched reads via `range`. Dumps go to `<tmpdir>/ai-zen/tool-output/<tool>-<timestamp>-<random>/`, one directory per call, with no self-cleanup. See [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md).
 
 ## Built-in Plugins
 
 | Plugin | Description |
 |--------|-------------|
-| `AutoMigratePlugin` | Automatically triggers task migration when the context overflows; delegates the actual migration to the injected `TaskMigrationService` instance (history handled per `strategy`: default `omit` keeps it auditable, optional `prune` drops it), which reuses the agent's own model client |
+| `AutoMigratePlugin` | Automatically triggers task migration when the context overflows; delegates the actual migration to the injected `HandoffService` (history handled per `strategy`: default `omit` keeps it auditable, optional `prune` drops it). `resolveMode` lets the caller pick the handoff executor or skip the round. Steps aside while `service.busy` to avoid the handoff→migrate→handoff recursion |
 | `AutoRefreshToolsPlugin` | Re-scans the file system before each `send()` to refresh the tool list |
 | `ContextGuardPlugin` | Context safety guard — before each request, throws `ContextOverflowError` (interrupting the conversation) when the previous round's `usage.prompt_tokens` exceeds `maxTokens × ratio` (default 1.5), preventing context runaway from reading oversized files |
 | `UnknownToolHintPlugin` | Smarter unknown-tool hints — when the LLM calls a nonexistent tool, guides it to `call_mcp_tool` / points out permission issues based on MCP config (opt-in via `agent.use`) |

package/README.zh.md

@@ -20,7 +20,7 @@ Desktop ──┘                    │
 types         ← 纯类型，零业务依赖（含 ToolEnv 工具环境）
 config        ← ConfigManager + constants：读写 config.json + 目录初始化 + 出厂默认
 crud          ← 能力实体 CRUD（Agent 定义等；会话/草稿已下放给各端自行持久化）
-runtime       ← 模型工厂 + Agent 组装 + 任务迁移（createModel / createAgent / SdkAgent / TaskMigrationService）
+runtime       ← 模型工厂 + Agent 组装 + 任务交接/迁移（createModel / createAgent / SdkAgent / HandoffService / HandoffGuardPlugin）
 scope         ← Scope 编排容器 + ScopePlugin 契约 + PermissionEvaluator / disclosure + plugins/（5 个自包含能力来源：发现 + 工具 + 插件）
 agent-plugins ← Agent 插件（autoMigrate、autoRefreshTools、contextGuard、unknownToolHint）
 shared        ← 日志、错误
@@ -67,8 +67,9 @@ const scope = new Scope({
 await scope.init();
 
 const agent = await createAgent(scope, "my-agent");
-const migrationService = new TaskMigrationService({ onMigrated }); // 迁移复用传入 agent 自身的模型调用
-agent.use(new AutoMigratePlugin({ service: migrationService, maxTokens }));
+const handoffService = new HandoffService({ handoffDir: "/work/.ai-zen/handoffs", skillDirs });
+agent.use(new ContextGuardPlugin({ maxTokens, isSuspended: () => handoffService.busy }));
+agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens }));
 agent.use(new AutoRefreshToolsPlugin());
 agent.use(new UnknownToolHintPlugin({ scope }));
 await agent.init();
@@ -96,21 +97,21 @@ await scope.dispose(); // 断开 MCP、释放插件资源
 | 工具 | 说明 |
 |------|------|
 | `cwd` | 获取当前工作目录 |
-| `readFile` | 读取文件（可选 `range` 按行列范围读取；输出超限仅警告并提示用 `range` 分批） |
-| `inspectFile` | 勘察文件结构概况（行数、列数分布等），流式扫描不受 300KB 限制 |
-| `writeFile` | 写入文件 |
+| `read` | 读取文件（可选 `range` 按行列范围读取；输出超限仅警告并提示用 `range` 分批） |
+| `inspect_file` | 勘察文件结构概况（行数、列数分布等），流式扫描不受 300KB 限制 |
+| `write` | 写入文件 |
 | `exec` | 执行命令（支持 `timeout` 超时参数；stdout+stderr 超限时分文件落盘 `stdout.log` / `stderr.log`） |
-| `exec_async` | 异步执行命令，启动后立即返回，不等待结果 |
+| `spawn` | 异步执行命令，启动后立即返回，不等待结果 |
 | `mkdir` | 创建目录 |
 | `rm` | 删除文件或目录 |
 | `glob` | 使用 glob 模式扫描查找文件（输出超限落盘 `result.json`） |
 | `ls` | 列出目录内容（输出超限落盘 `result.json`） |
 | `exist` | 检查文件或目录是否存在 |
-| `findText` | 在文件中搜索文本或正则（输出超限落盘 `result.json`） |
-| `downloadFile` | 从 URL 下载文件并保存到本地 |
+| `find_text` | 在文件中搜索文本或正则（输出超限落盘 `result.json`） |
+| `download_file` | 从 URL 下载文件并保存到本地 |
 | `rename` | 重命名或移动文件/目录 |
 | `copy` | 复制文件或目录 |
-| `batchEdit` | 批量编辑文件文本（仅回显未匹配项，成功项只计数） |
+| `batch_edit` | 批量编辑文件文本（仅回显未匹配项，成功项只计数） |
 | `edit` | 编辑文件中的文本 |
 | `sleep` | 等待指定毫秒数后继续 |
 
@@ -118,16 +119,16 @@ await scope.dispose(); // 断开 MCP、释放插件资源
 
 | 工具 | 注入条件 | 说明 |
 |------|----------|------|
-| `generateImage` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
-| `viewImage` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
+| `generate_image` | 配置了 `defaultImageModel` 才注册 | 根据文字描述生成图片 |
+| `view_image` | 仅视觉模型可用（Agent 的 `modelId` 解析为 `vision: true` 的模型） | 查看/分析图片：本地图片自动经 Files API 上传，网络 URL 直接引用 |
 
-工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`findText` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`readFile` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md)。
+工具输出保护：`AppConfig.maxToolOutput`（字符数，缺省 32768）是工具输出的统一上限，超限时由各工具自行处置——`exec` 分文件落盘 `stdout.log` / `stderr.log`（返回各流头尾预览），`find_text` / `glob` / `ls` 落盘 `result.json`（返回头部预览），`read` 仅警告并提示用 `range` 分批读取。落盘目录为 `<tmpdir>/ai-zen/tool-output/<工具名>-<时间戳>-<随机串>/`，每次调用独立、不自清理。详见 [`docs/sdk-design-v1.md` §12](docs/sdk-design-v1.md)。
 
 ## 内置插件
 
 | 插件 | 说明 |
 |------|------|
-| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移，生成交接文档并追加对话断点（历史按 `strategy` 处理：默认 `omit` 标记保留可审计，可选 `prune` 物理剔除；委托注入的 `TaskMigrationService`，复用 Agent 自身的模型调用） |
+| `AutoMigratePlugin` | 上下文超限时自动触发任务迁移（历史按 `strategy` 处理：默认 `omit` 标记保留可审计，可选 `prune` 物理剔除），委托注入的 `HandoffService`；`resolveMode` 让调用方决定交接执行者或跳过本轮；`service.busy` 期间让行，避免「交接→迁移→交接」递归 |
 | `AutoRefreshToolsPlugin` | 每次 `send()` 前重新扫描文件系统，刷新工具列表 |
 | `ContextGuardPlugin` | 上下文安全护栏 — 每轮发请求前检测上一轮 `usage.prompt_tokens`，超过 `maxTokens × ratio`（默认 1.5，即 +50%）时抛 `ContextOverflowError` 中断对话，防止读入超大文件导致上下文失控 |
 | `UnknownToolHintPlugin` | 未知工具智能提示 — LLM 调用不存在的工具时，根据 MCP 配置引导使用 `call_mcp_tool` / 提示权限问题（调用方显式 `agent.use` 注册） |

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

@@ -1,23 +1,49 @@
 import type { AgentPlugin, SendContext } from "@ai-zen/agents-core";
-import { TaskMigrationService } from "../runtime/TaskMigrationService.js";
+import type { HandoffMode, HandoffService } from "../runtime/HandoffService.js";
+/** 触发迁移时的用量信息（供执行者选择、确认文案使用） */
+export interface AutoMigrateTriggerInfo {
+    /** 当前 prompt token 用量 */
+    promptTokens: number;
+    /** 上下文阈值（当前模型的 maxContextTokens） */
+    maxTokens: number;
+}
+/**
+ * 迁移执行者解析器：只负责「用什么方式交接」，不负责「何时迁移」。
+ *
+ * - 返回 `HandoffMode` → 用该执行者迁移；
+ * - 返回 `null` → 跳过本次迁移（例如用户拒绝）；
+ * - 未提供 → 使用 `HandoffService` 构造时的默认执行者。
+ */
+export type AutoMigrateModeResolver = (info: AutoMigrateTriggerInfo) => HandoffMode | null | Promise<HandoffMode | null>;
 export interface AutoMigrateOptions {
-    /** 迁移服务实例（持有迁移前后钩子；生成交接文档时复用传入 agent 的模型调用） */
-    service: TaskMigrationService;
+    /** 交接服务实例（持有交接前后钩子；编排 handoff / migrate 两条链路） */
+    service: HandoffService;
     /** 触发迁移的上下文阈值 */
     maxTokens: number;
+    /**
+     * 执行者解析（可选）。上层可在此弹确认框、读用户偏好，
+     * 或直接返回 `null` 表达「本次不迁移」——**无需**再继承本插件。
+     */
+    resolveMode?: AutoMigrateModeResolver;
 }
 /**
- * 自动迁移插件 — 只负责「触发」，实际迁移逻辑统一委托给持有的 `TaskMigrationService` 实例。
+ * 自动迁移插件 —— 只负责「何时触发」，实际迁移统一委托给持有的 `HandoffService`。
  *
- * 当 token 使用量超过 maxTokens 时触发迁移。`service.migrate()` 需要 `agent`（当前对话）作为
- * 唯一运行时参数，其余（模型、迁移前后钩子）已由服务在构造时持有。
+ * 当 `usage.prompt_tokens` 超过 maxTokens 时触发迁移：
  *
  * ```ts
  * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
+ *   service: handoffService,
  *   maxTokens: 250_000,
+ *   resolveMode: async ({ promptTokens, maxTokens }) =>
+ *     (await askUser(promptTokens, maxTokens)) ? "self" : null,
  * }));
  * ```
+ *
+ * 两层让行（缺一不可）：
+ *   - `service.busy`：交接回合本身就是一次 `send()`，其 `onAfterSend` 会再次到这里；
+ *     不跳过就会「交接触发迁移 → 迁移再交接」无限递归；
+ *   - 交接回合结束后的用量也仍可能超阈值，故 busy 判断必须覆盖整个交接 + 迁移过程。
  */
 export declare class AutoMigratePlugin implements AgentPlugin {
     private options;

package/dist/agent-plugins/AutoMigratePlugin.js

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

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

@@ -7,6 +7,15 @@ export interface ContextGuardOptions {
      * 在请求前抛出 ContextOverflowError 中断对话。默认 1.5（即 +50%）。
      */
     ratio?: number;
+    /**
+     * 是否处于「需要放宽」的阶段（例如交接回合）。返回 true 时改用 `suspendedRatio`。
+     *
+     * 为什么需要：交接恰好发生在上下文最满的时刻，而交接回合本身还要再发 1~2 次请求。
+     * 若仍按 1.5 倍判定，正常交接会被护栏误杀；完全让行又会失去熔断，故改为放宽而非放行。
+     */
+    isSuspended?: () => boolean;
+    /** 放宽后的比例，默认 2.0（即 maxTokens × 2） */
+    suspendedRatio?: number;
 }
 /**
  * 上下文安全护栏插件。
@@ -18,13 +27,14 @@ export interface ContextGuardOptions {
  * 与迁移插件职责分离：
  * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
  * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ * - 交接回合由 `isSuspended` 放宽阈值（而非完全让行），保证交接不被误杀、又保留熔断。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
- * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
+ * agent.use(new ContextGuardPlugin({
  *   maxTokens: 250_000,
+ *   isSuspended: () => handoffService.busy,
  * }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens: 250_000 }));
  * ```
  */
 export declare class ContextGuardPlugin implements AgentPlugin {

package/dist/agent-plugins/ContextGuardPlugin.js

@@ -9,13 +9,14 @@ import { ContextOverflowError } from "../shared/errors.js";
  * 与迁移插件职责分离：
  * - ContextGuardPlugin 只做「严重超限即中断」的安全兜底，绝不继续对话/迁移；
  * - AutoMigratePlugin 在正常范围内（超 maxTokens 但未达硬上限）做交接迁移。
+ * - 交接回合由 `isSuspended` 放宽阈值（而非完全让行），保证交接不被误杀、又保留熔断。
  *
  * ```ts
- * agent.use(new ContextGuardPlugin({ maxTokens: 250_000 }));
- * agent.use(new AutoMigratePlugin({
- *   service: new TaskMigrationService({ onMigrated }),
+ * agent.use(new ContextGuardPlugin({
  *   maxTokens: 250_000,
+ *   isSuspended: () => handoffService.busy,
  * }));
+ * agent.use(new AutoMigratePlugin({ service: handoffService, maxTokens: 250_000 }));
  * ```
  */
 export class ContextGuardPlugin {
@@ -25,13 +26,15 @@ export class ContextGuardPlugin {
     }
     async onInnerLoopStart(ctx) {
         const { agent } = ctx;
-        const { maxTokens, ratio = 1.5 } = this.options;
+        const { maxTokens, ratio = 1.5, isSuspended, suspendedRatio = 2 } = this.options;
         // 首轮请求前尚无用量数据，跳过（只能在发出首轮请求、拿到 usage 后才有据可查）
         const promptTokens = agent.lastUsage?.prompt_tokens;
         if (promptTokens == null)
             return;
-        if (promptTokens > maxTokens * ratio) {
-            throw new ContextOverflowError(promptTokens, maxTokens, ratio);
+        // 交接回合等需要放宽的阶段：放宽阈值但保留熔断
+        const effectiveRatio = isSuspended?.() ? suspendedRatio : ratio;
+        if (promptTokens > maxTokens * effectiveRatio) {
+            throw new ContextOverflowError(promptTokens, maxTokens, effectiveRatio);
         }
     }
 }

package/dist/config/ConfigManager.d.ts

@@ -52,10 +52,21 @@ export declare class ConfigManager {
         agent: AgentDefinition | null;
         subAgent: AgentDefinition | null;
     }>;
+    /**
+     * 释放 / 同步出厂 Skill。
+     *
+     * 覆盖策略与 `syncManagedModels` 同构：
+     *   - 磁盘上不存在 → 写入出厂内容；
+     *   - 存在且 frontmatter 标了 `custom: "true"` → 用户自有，原样保留；
+     *   - 存在但未标 → 视为出厂托管，同步为当前版本内容（内容相同则不写盘）。
+     *
+     * @returns 实际写入的 Skill id 列表（内容未变化 / 用户自有 均不计入）
+     */
+    ensureFactorySkills(): Promise<string[]>;
     /** mcp.json 路径：{basePath}/mcp.json */
     get mcpPath(): string;
     /**
-     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty）。
+     * 确保 basePath/mcp.json 存在。不存在时写入出厂默认 MCP 配置（含 socket-pty 与 chrome-devtools）。
      * 已有文件不被覆盖，尊重用户已配置的 MCP 服务器。
      * @returns 返回当前生效的 MCP 配置原始内容
      */

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";
 /**
  * 配置管理器 — 负责配置文件的读写、目录初始化、默认实体创建。
  */
@@ -178,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 */
@@ -188,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 配置原始内容
      */

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

@@ -214,11 +214,13 @@ export const DEFAULT_APP_CONFIG = {
     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）
  *
  * 若文件已存在则不覆盖（尊重用户已有配置）。
  */
@@ -230,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;