@ai-zen/cli 1.0.0-alpha.1 → 1.0.0-alpha.11

package/CHANGELOG.md

@@ -1,3 +1,175 @@
+## [1.0.0-alpha.11] - 2026-10-20
+
+### ⚠️ 依赖
+
+- `@ai-zen/agents-sdk` `1.0.0-alpha.10 → 1.0.0-alpha.11`（`createCallMcpTool` 新增 `env` 参数为破坏性变更；CLI 不直接调用该工厂，无代码改动）。
+
+### 🔧 变更（随 SDK）
+
+- **`call_mcp_tool` 输出保护**：调用 MCP 工具时，文本输出超过 `maxToolOutput`（默认 32768 字符）会完整落盘为 `result.txt`，只返回警告 + 头尾预览，可用 `read` 分批读取——不再一次把上万字符灌进上下文。
+- **图片 / 音频 / 二进制资源原样返回**：MCP 返回的 `image` / `audio` / `resource.blob` 转成 `image_url` / `file` 内容块透传（`resource.text` 并入正文、`resource_link` 转为可读线索），不再静默丢弃；媒体不受 `maxToolOutput` 约束。
+
+### 📄 文档
+
+- `docs/{zh,en}/mcp.md` 说明「仅文本受输出保护、媒体不受上限约束」；`docs/{zh,en}/getting-started.md`、`docs/manifest.json`、`README{,.zh}.md` 版本同步。
+
+## [1.0.0-alpha.10] - 2026-10-20
+
+### 💥 变更
+
+- **交接与迁移拆成两条命令**（语义唯一，命名与实现对齐）：
+  - **`/handoff`** —— 原 agent 停手、核实状态、把交接文档写到 `<项目>/.ai-zen/handoffs/`，**会话照旧**（不弹确认，可反复执行；交接回合留在 `agent.messages` 里，可继续要求细化同一份文档）；
+  - **`/migrate`**（别名 `/migration`）—— 同一次交接 + 清历史 + 开新会话（需确认）。
+  - 两条都支持 `self` / `summary` 参数（如 `/handoff summary`、`/migrate self`）跳过默认选择。
+- **自动迁移改为「执行者三选一」选择器**：上下文超阈值时不再只问「是否迁移」，而是选择 **原 agent 自交接（默认高亮，保真）/ 独立摘要（便宜）/ 跳过本次**。选择器复用既有 picker 浮层（`setPickerState`）。非交互环境（管道、重定向、e2e）无选择通道，按默认执行者迁移，不阻塞、不额外输出。
+- **交接文档目录**：新增 `PROJECT_HANDOFFS_DIR = <cwd>/.ai-zen/handoffs`，交接文档落在项目内，可随仓库共享/评审。
+
+### ♻️ 重构
+
+- **`src/migration-service.ts` → `src/handoff-service.ts`**：`createMigrationService` → `createHandoffService`，钩子从 `onBeforeMigrate` / `onMigrated` 改为 `onBeforeHandoff` / `onHandoff` / `onMigrated`。存档旧会话移到 `onHandoff`（此时已包含交接回合，归档可审计）；`/handoff` 不切换会话也因此不需要额外存档（`ConversationPersistPlugin` 每轮已落盘）。
+- **`src/auto-migrate-confirm-plugin.ts` → `src/auto-migrate-confirm.ts`**：`AutoMigrateConfirmPlugin`（继承 + 重写 `onAfterSend`）退化为 `createAutoMigratePlugin()` 工厂——「何时迁移」仍在 SDK 插件里，「用谁交接」通过 SDK 新增的 `resolveMode` 回调注入，不再重复实现阈值判断。
+- `src/agent-creator.ts` 抽出并导出 `listSkillDirs()`：Scope 装配与交接服务（读取 `handoff` Skill 正文）共用同一份目录优先级，避免两处各算一遍。
+- `ChatSessionOptions.requestConfirm` → `requestMode`（返回 `HandoffMode | null`）；`ChatSession.migrate()` / `handoff()` 返回文档路径；`ConversationContext.migrationService` → `handoffService`。
+- `ContextGuardPlugin` 接线 `isSuspended: () => handoffService.busy`：交接回合护栏从 `× 1.5` 放宽到 `× 2`。
+- 斜杠命令解析支持参数：命令名取首个 token（`/migrate summary` 不再被当成未知命令）。
+
+### ⚠️ 依赖
+
+- `@ai-zen/agents-sdk` `1.0.0-alpha.9 → 1.0.0-alpha.10`（`TaskMigrationService` → `HandoffService` 为破坏性变更）。
+
+### ✅ 测试
+
+- 新增 `src/handoff-service.test.ts`（迁移清 `lastUsage` / 新会话落盘 / `/handoff` 不切会话）、`src/auto-migrate-confirm.test.ts`（非交互默认值、选择透传、取消跳过、busy 让行）。全量 **17 文件 / 229 用例**通过，`tsc --noEmit`（含测试工程）与 `build` 零错误。
+
+### 📄 文档
+
+- `docs/{en,zh}/migration.md` 重写为「任务交接与迁移」：两条命令的差异、两种执行者的取舍、自交接的代码级保障（守卫/放宽/防递归）、文档位置与命名、模板由 `handoff` Skill 承载（`metadata.custom: "true"` 退出同步、可项目级覆盖）、成本说明。网站镜像同步。
+- `README.md` / `README.zh.md` 命令表与「任务交接与迁移」章节、`docs/{en,zh}/index.md` 特性与导航同步。
+
+## [1.0.0-alpha.9] - 2026-10-14
+
+### 🔧 修复
+
+- **自动迁移与 CLI 的交互适配（两处）**：
+  - **迁移期间输入框未真正拦住** —— 主输入 `useInput` 的 `isActive` 此前只挡「确认框 / 选择器 / 配置向导」，未挡「生成中」态。自动迁移在 `send()` 内 `await onAfterSend` 执行（`busy` 为真、输入框已被 Spinner 顶替），但按键仍会被静默吞进隐藏的输入缓冲、待本轮结束才浮现。现令主输入在 `busy` 时整体失活，另设「忙碌期」处理器仅放行 `Ctrl+C` 中止 / `Ctrl+D` 退出 / `PgUp`·`Shift+↑↓` 回看；`/migrate` 手动迁移同样纳入 `busy`。
+  - **迁移完成后仍被总上下文护栏拦截** —— 迁移（prune）会物理重置上下文，却遗留 `agent.lastUsage`（迁移前那一次请求的 `prompt_tokens`）。`ContextGuardPlugin`（`onInnerLoopStart`，硬上限 `maxTokens × 1.5`）据此误判，迁移后第一条消息即被 `ContextOverflowError` 中断。现于迁移后清空 `agent.lastUsage`，护栏首轮无据可查而放行，待下一次响应以真实用量回填。
+
+### ✅ 测试
+
+- 新增 `src/migration-service.test.ts`：断言迁移后 `agent.lastUsage` 被清空（移除修复后该用例确会失败）。全量单测 **17 文件 / 227 用例**通过，`tsc --noEmit` 与 `pnpm build` 零错误。
+
+## [1.0.0-alpha.8] - 2026-10-14
+
+### 🔧 修复
+
+- **修复长时间 TUI 会话内存无界增长导致的 OOM（崩溃）** —— CLI 入口此前从未设定 `NODE_ENV`，React 因而按 `process.env.NODE_ENV !== "production"` 载入 **development** 版 `react-reconciler`；该开发构建每次渲染都会调用 `performance.measure()`（User Timing API），而 Node 的 performance 条目缓冲**无上限、从不逐出**，长时间流式会话下条目持续累积，约 55 分钟即将堆顶到 `heap_size_limit`（本机 ~1GB）触发 OOM。现于 `src/index.ts` 顶部设 `process.env.NODE_ENV ||= "production"`；因 ESM 静态 `import` 会被提升到模块体之前执行，对 TUI 入口 `./tui/index.js` 改用动态 `import()`，确保 React/Ink 在 `NODE_ENV` 设定**之后**才被求值，从而加载 production 版 reconciler（该版不调用 `performance.measure`）。显式 `NODE_ENV=development` 仍保留开发构建，便于排查。
+
+### ✅ 测试
+
+- **端到端实证** —— 真实 ESM 下经入口加载 Ink 并连续重渲染 300 次：修复后 `performance.measure` 条目 **0 → 0**（production reconciler），显式 `NODE_ENV=development` 对照组 **0 → 905**（dev 埋点仍在）。全量单测 **16 文件 / 226 用例**通过，`tsc --noEmit` 与 `pnpm build` 零错误。
+
+## [1.0.0-alpha.7] - 2026-10-14
+
+### 📄 文档
+
+- **状态栏 token 用量纳入文档** —— `docs/zh|en/index.md` 的「主要特性」补上「状态栏实时展示 模型 · Agent · 本轮/累计 token 用量 · 生成状态」（此前仅在 README 提及），累计口径为 `sumUsage(agent.messages)`（含所有层级的子 Agent）。
+- 修正 `TODO.md` 中已过时的路径引用（`src/tui/config-wizard.tsx` → 目录 `src/tui/config-wizard/`）。
+
+### ⚠️ 依赖
+
+- `@ai-zen/agents-core` `^4.5.0 → ^4.5.1`、`@ai-zen/agents-sdk` `1.0.0-alpha.8 → 1.0.0-alpha.9`
+
+> 纯文档修正，无代码变更。
+
+## [1.0.0-alpha.6] - 2026-10-14
+
+### ♻️ 重构
+
+- **累计用量改用 SDK 的 `sumUsage`，移除 CLI 自建的内存累加器** —— 依赖 `@ai-zen/agents-sdk` `1.0.0-alpha.8` / `@ai-zen/agents-core` `4.5.0`：除助手消息的 `usage` 外，委派产生的用量现由 core 在委派边界钉到工具消息的 `subAgentUsage` 上。故 `ChatSession.totalUsage` 直接 `sumUsage(agent.messages)` 即可（含所有层级的子 Agent），删掉 `src/usage.ts` 与 `onSubAgentEnd` 内存回灌——子 Agent 开销随消息持久化，续接 / `/load` 亦不丢，且不再有双重计数风险。
+
+### ⚠️ 依赖
+
+- `@ai-zen/agents-sdk` `1.0.0-alpha.7 → 1.0.0-alpha.8`、`@ai-zen/agents-core` `^4.4.0 → ^4.5.0`
+
+### ✅ 测试
+
+- 移除 `src/usage.test.ts`（逻辑下沉 core，已由 core 覆盖）；`chat-session.test.ts` 的 `totalUsage` 用例改为覆盖「assistant 的 usage + 工具消息的 subAgentUsage」求和。全量单测 **16 文件 / 226 用例**通过，`tsc --noEmit` 与 `npm run build` 零错误。
+
+## [1.0.0-alpha.5] - 2026-10-14
+
+### 🚀 新功能
+
+- **状态栏展示 token 累计消耗** —— 依托 `@ai-zen/agents-sdk` `1.0.0-alpha.7` / `@ai-zen/agents-core` `4.4.0` 为每条 assistant 消息钉上的 `usage`，新增 `src/usage.ts`（`addUsage` / `sumMessagesUsage` 纯函数）与 `ChatSession.totalUsage`：对本会话全部 assistant 消息的 `usage` 求和即计费口径的累计消耗；子 Agent 的 messages 不在父 Agent 中，故在 `onSubAgentEnd` 单独累加并入、`/new` 时归零。状态栏由「`{tokens} tok`」升级为「`本轮 x · 累计 y tok`」（本轮 = `lastUsage.total_tokens`，累计 = `totalUsage.total_tokens`）。
+- **依赖升级** —— `@ai-zen/agents-sdk` `1.0.0-alpha.6 → 1.0.0-alpha.7`、`@ai-zen/agents-core` `^4.3.2 → ^4.4.0`（后者新增 `AgentNS.Message.usage` 逐条 token 用量）。
+
+### ✅ 测试
+
+- 新增 `src/usage.test.ts`（4 例）；`chat-session.test.ts` 增补 `totalUsage` 求和用例；`screens.test.tsx` 的 `StatusBar` 用例更新。全量单测 **17 文件 / 230 用例**通过，`tsc --noEmit` 与 `npm run build` 零错误。
+
+## [1.0.0-alpha.4] - 2026-10-13
+
+### ♻️ 重构
+
+- **TUI 渲染直接以 `agent.messages` 为唯一数据源** —— 移除 `ChatEvent` / `chatReducer` / `LiveAssistant` / `Block` / `messagesToBlocks` 等自定义中间模型。SDK 在流式期间会**实时更新 `agent.messages`**（`Agent.parseStreamData` 把每个 delta 增量写进当前那条 message），因此跨消息顺序（数组序）与单条 assistant 内部顺序（`思考 → 工具 → 正文`）天然保持，直接渲染即可，杜绝「第二套真相」的失真与维护负担。已完成消息的折行 / 高亮按「消息 + 列宽 + 内容签名」缓存（`cachedMessageToLines`），流式中那条靠内容签名自动失效。
+- **notice / error 改为独立栏位** —— 系统级提示（命令反馈 / 迁移进度 / 报错）不再混入对话转录，也**绝不写进 `agent.messages`**（那会被 `formatHistory()` 原样发给模型、污染上下文）；改在输入框上方的独立一行渲染（`src/tui/screens/notice.ts`）。
+
+### 🎯 优化
+
+- **流式增量渲染**：Ink 开启 `incrementalRendering` —— 从「每帧 erase 整屏 + 重写整屏」（`createStandard`）切到「只重绘变化的行」（`createIncremental`），每帧输出量由 O(屏幕大小) 降到 O(变化量)，SSH / 弱网下流式更稳。
+- **流式合帧**（`src/tui/screens/frame-buffer.ts`）：内容变更先攒入缓冲，按 60ms（约 16fps，低于 Ink 默认 30fps 输出节流）批量触发重渲染，把上屏频率从「每个 delta 一次」降到固定帧率。
+- **渲染缓存**：长对话下历史消息的折行 / 高亮免于每帧重算，成本不再随对话增长而恶化。
+- **思考与工具调用之间补一个空行**，排版更清晰。
+
+### ✅ 测试
+
+- 新增 `frame-buffer.test.ts`、`notice.test.ts`；`screens.test.tsx` 重写为基于 `messageToLines` / `transcriptLines` / `computeChatLayout(transcript)`。
+- `tsc` 零错误；全量单测 **16 文件 / 225 用例**通过；`npm run build` 通过。
+- 真机（pty）验证：SSH / 弱网下流式稳定，长对话滚动流畅。
+
+## [1.0.0-alpha.3] - 2026-10-13
+
+### 💥 破坏性变更
+
+- **内置工具改名（统一 `snake_case`：多词收敛、单词简化）** —— 随 `@ai-zen/agents-sdk` `1.0.0-alpha.6` 落地：SDK 将内置工具名统一为 `snake_case`，并把单词工具简化为单词 —— `readFile` → `read`、`writeFile` → `write`、`exec_async` → `spawn`、`findText` → `find_text`、`batchEdit` → `batch_edit`、`inspectFile` → `inspect_file`、`downloadFile` → `download_file`、`generateImage` → `generate_image`、`viewImage` → `view_image`、`indexedSearch` → `indexed_search`；工具类名同步为 `ReadTool` / `WriteTool` / `SpawnTool`。**若你在 Agent 定义、权限白名单（`tools.allow` / `tools.deny`）或自定义提示词里引用了旧工具名，请同步更新为 `snake_case` 新名**（旧名仅保留在 CHANGELOG 历史条目中）。
+
+### 🚀 新功能
+
+- **正文 / 思考按 Markdown 源码着色** —— AI 回答本身即 Markdown，现交给 `highlight.js` 的 `markdown` 词法着色：标题（`#`）、粗体、斜体、行内代码、列表、引用、链接各有配色；**围栏代码块保留围栏行**（开 / 闭围栏以低调暗灰渲染）并继续按标注语言做语法高亮。标记符（`#` / `**` / 反引号 等）**原样保留、只染色**（源码着色，非语义渲染）。正文用**空格优先折行**，避免把英文单词从中间切断。
+
+### 🎯 优化
+
+- **正文默认文本色改用终端默认前景色** —— 此前正文基础色写死近白 `#e2e8f0`，在**亮色主题终端**里会「白底白字」看不见。现正文（含未指定颜色的默认分段）一律回落**终端默认前景色**，绝对色只留给标题 / 代码等强调项；同步移除语法色板里两处近白 token 色（`variable` / `params`）。
+
+### ⚠️ 依赖升级
+
+- **`@ai-zen/agents-core` 升至 `^4.3.2`、`@ai-zen/agents-sdk` 升至 `1.0.0-alpha.6`** ——
+  - core `4.3.1`：**中断的并行工具轮次归一化** —— 一轮回复里并行调用的多个工具若被中断（`Ctrl+C`），未完成的工具结果会在历史里被补齐 / 归一，避免下一轮因 `tool_calls` 数量与实际工具结果数量不匹配而被服务端拒绝（默认 `fill`：保留 assistant 正文并补齐未完成结果）。
+  - core `4.3.2` / sdk `1.0.0-alpha.4…6`：内置工具统一 `snake_case` + 单词简化、`exec_async` → `spawn`、类名对齐（见「破坏性变更」）。
+  - CLI 侧仅同步工具名（文档 / 测试 fixture / 提示语），运行时行为全量委托 SDK，无需其它适配。
+
+### ✅ 测试
+
+- `tsc --noEmit`（`tsconfig.test.json`）零错误；全量单测 **15 文件 / 235 用例**通过
+- 修复 `config-wizard.test.tsx` 两个预存失败：为向导注入终端尺寸（新增可选 `terminalSize` prop），消除 `ink-testing-library` 假 stdout 缺 `rows` 时 `terminal-size` 探测本机行数、把吸底帧撑到 38 行的干扰
+- 渲染核验：标题 / 粗体 / 行内代码 / 列表 / 引用 / 链接与围栏代码块均按预期着色，普通正文无颜色（回落终端默认）
+
+## [1.0.0-alpha.2] - 2026-10-03
+
+### ⚠️ 依赖升级
+
+- **`@ai-zen/agents-sdk` 升至 `1.0.0-alpha.3`** — 拉取 SDK 对内置工具 `generateImage` 参数描述的修正。原描述写着「配置中的图片模型可通过 `aiz config show` 查看」，等于**指路让模型去执行宿主 CLI 命令**；而**工具描述会随每次请求的 `tools` 字段进入每一层 agent 的上下文**——模型据此 `exec("aiz config show")`，CLI 又把这条命令解析为**纯 stdio 模式**、以 `config show` 为提示词**再拉起一个 agent**，其工具描述里又是同一句指引，遂形成**自指型递归**（每层都真连 API，越套越深）。SDK 现已把该描述改为「若指定的模型不存在，本工具会返回当前可用的模型列表」，与 `call()` 的实际行为一致，且不再引导模型去执行宿主 CLI。该版本**无破坏性变更**，CLI 源码无需适配（类型 / 默认配置全量委托 SDK，版本横幅由实际安装版本读取，工具清单由 SDK 静态注册表自动发现）。
+
+### 📝 文档
+
+- `docs/zh|en/getting-started.md`：运行时依赖版本同步为 `@ai-zen/agents-sdk` `1.0.0-alpha.3`
+- `docs/manifest.json`：版本号同步为 `1.0.0-alpha.2`
+- 中英 README 启动横幅示例版本同步为 `v1.0.0-alpha.2`
+
+### ✅ 测试
+
+- `tsc --noEmit`（`tsconfig.test.json`）与 `npm run build` 零错误
+- 全量单测 13 文件 / 224 用例通过
+
 ## [1.0.0-alpha.1] - 2026-09-30
 
 > 本版本汇总**相对上一发布版本 `0.9.0`** 的全部变化。

package/README.md

@@ -66,12 +66,12 @@ When run with no arguments on an interactive terminal, the CLI opens a full-scre
 ╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
 
               AI workbench in your terminal
-              v1.0.0-alpha.1 · sdk x · core y
+              v1.0.0-alpha.11 · sdk x · core y
 ```
 
-After the splash, you land **directly in the chat screen** (resuming the last session if there is one, otherwise starting a new conversation). The chat screen is **bottom-pinned**: a divider, the input line, and the status bar (model · agent · token usage · generating) always sit at the bottom of the terminal, while the conversation scrolls above them. While generating, the spinner replaces the input line.
+After the splash, you land **directly in the chat screen** (resuming the last session if there is one, otherwise starting a new conversation). The chat screen is **bottom-pinned**: a divider, the input line, and the status bar (model · agent · this-round / cumulative tokens · generating) always sit at the bottom of the terminal, while the conversation scrolls above them. While generating, the spinner replaces the input line.
 
-The chat screen provides a streaming output area (reasoning / answer / tool calls on separate lines), a multiline input (`Enter` sends; `Ctrl+N` inserts a newline; `← →` move the cursor, `Ctrl+← →` by word), and an inline `/` command menu (↑↓ to choose, `Tab` to complete). Tool calls render as `⚙ name(args)` with **JSON syntax highlighting**, and fenced code blocks in the answer / reasoning are **syntax-highlighted by language** (highlight data from `highlight.js` via `lowlight`). `Ctrl+C` cancels the current request while generating, and exits when idle.
+The chat screen provides a streaming output area (reasoning / answer / tool calls on separate lines), a multiline input (`Enter` sends; `Ctrl+N` inserts a newline; `← →` move the cursor, `Ctrl+← →` by word), and an inline `/` command menu (↑↓ to choose, `Tab` to complete). Tool calls render as `⚙ name(args)` with **JSON syntax highlighting**; the answer / reasoning is **Markdown-source-colored** (headings, bold, italic, inline code, lists, quotes, links), and fenced code blocks are **syntax-highlighted by language with the fence markers kept** (highlight data from `highlight.js` via `lowlight`). `Ctrl+C` cancels the current request while generating, and exits when idle.
 
 ### First-run setup (API Key)
 
@@ -114,25 +114,24 @@ While in a conversation, all commands start with `/`. Typing `/` lists the avail
 | `/clear` | Clear the screen |
 | `/config` | Open the configuration center (endpoints / models / image models / MCP servers / agent definitions / defaults / tool-output cap) |
 | `/key` | Set the API Key of the current endpoint (rebuilds the session on save) |
-| `/migrate` | Manually trigger task migration (generate handoff doc & start a new session) |
+| `/handoff` | Write a handoff document only (session keeps running; no confirmation) |
+| `/migrate` `/migration` | Handoff + start a new session (discards history; asks for confirmation) |
 | `/help` | Show available commands |
 
-### Conversation Migration
+### Task Handoff & Migration
 
-When the API response's `usage.prompt_tokens` exceeds the model's `maxContextTokens`, the system first asks for a **second confirmation** (showing current usage and the threshold, defaulting to "yes"; choosing "no" skips this migration and leaves the current conversation untouched), then generates a **handover document** summarizing completed tasks, pending items, and key decisions. A new conversation session is created with this document as context, ensuring seamless continuation. The confirmation only appears when both stdin and stdout are TTYs; non-interactive scenarios such as pipes and redirections keep the previous automatic migration behavior.
+Two related commands, one pipeline:
 
-You can also manually trigger a migration at any time by typing `/migrate` in the conversation — no need to wait for the token limit. Both automatic and manual migration delegate to the SDK's `TaskMigrationService`, so the handoff document is always produced consistently.
+- **`/handoff`** — the original agent stops what it is doing and writes a handoff document to `<project>/.ai-zen/handoffs/<timestamp>-<conversation id>.md`, using its own tools to verify the real state (branch, uncommitted changes, tests, ports). The session keeps running, so you can keep refining the document.
+- **`/migrate`** — the same handoff, then history is cleared and a new session starts from the document (the breakpoint message carries only the path; the new agent reads it).
 
-The same context guard also applies to **sub-agents**: at each delegation boundary (`onSubAgentStart`) the CLI installs the same `ContextGuardPlugin` (same `maxTokens`) onto the newly built sub-agent, so a delegated sub-agent (including the Skill sub-agent created by `call_skill_sub_agent`) is interrupted as soon as its context exceeds the hard limit. This is transparent — a normally-running sub-agent is unaffected.
+Two executors: `self` (default — the original agent writes it in-session, highest fidelity) and `summary` (a single independent model call, cheap but lossy). `self` degrades to `summary` one-way on failure. Pass it explicitly with `/handoff summary` or `/migrate self`.
+
+When `usage.prompt_tokens` exceeds the model's `maxContextTokens`, an interactive terminal shows a three-way picker (self / summary / skip); non-interactive pipes migrate with the default executor without blocking.
 
-The migration prompt template includes:
-- **Conversation Breakpoint** — Last user/AI exchange verbatim
-- **Completed Tasks** — Task titles and output paths
-- **Pending Tasks** — Description, progress, next steps
-- **Important Notes** — Technical preferences, lessons learned, architecture decisions
-- **File Index** — Key files with descriptions
-- **Handover Instructions** — SOP for the relay agent (read files first, verify state, then act)
+The document template is not hard-coded: it comes from the `handoff` Skill (`~/.ai-zen/skills/handoff/SKILL.md`, released and synced by the SDK; mark `metadata.custom: "true"` to keep your own version, or override per project). See [Task Handoff & Migration](./docs/en/migration.md) for the full chain, cost notes, and the template sections.
 
+The same context guard also applies to **sub-agents**: at each delegation boundary (`onSubAgentStart`) the CLI installs the same `ContextGuardPlugin` (same `maxTokens`) onto the newly built sub-agent, so a delegated sub-agent (including the Skill sub-agent created by `call_skill_sub_agent`) is interrupted as soon as its context exceeds the hard limit. This is transparent — a normally-running sub-agent is unaffected.
 ### Shell Fallback Hook
 
 When you type an unrecognized command in your terminal, it can be automatically forwarded to AI for processing:
@@ -262,25 +261,25 @@ The CLI provides 20 built-in tools, implemented by `@ai-zen/agents-sdk`. Tool av
 | Tool | Description |
 |------|-------------|
 | `cwd` | Get current working directory |
-| `readFile` | Read file contents (supports `range` for partial reads) |
-| `inspectFile` | Inspect file structure (lines, chars, column widths, line-ending style) without reading content |
-| `writeFile` | Write content to file |
+| `read` | Read file contents (supports `range` for partial reads) |
+| `inspect_file` | Inspect file structure (lines, chars, column widths, line-ending style) without reading content |
+| `write` | Write content to file |
 | `edit` | Replace text in files (single replacement) |
-| `batchEdit` | Batch replace text in files |
+| `batch_edit` | Batch replace text in files |
 | `exec` | Execute shell commands |
-| `exec_async` | Execute a shell command asynchronously (returns immediately) |
+| `spawn` | Execute a shell command asynchronously (returns immediately) |
 | `mkdir` | Create directories |
 | `rm` | Delete files or directories |
 | `glob` | Scan files with glob patterns |
 | `ls` | List directory contents |
 | `exist` | Check if path exists |
-| `findText` | Search text in files |
-| `downloadFile` | Download file from URL |
+| `find_text` | Search text in files |
+| `download_file` | Download file from URL |
 | `rename` | Rename or move files |
 | `copy` | Copy files or directories |
 | `sleep` | Wait for a specified number of milliseconds |
-| `viewImage` | View/analyze an image — vision models only (`Model.vision`). A network URL is returned as an `image_url` content block; a local path is auto-uploaded via the Files API and returned as a `file` content block |
-| `generateImage` | Generate images from text — requires `defaultImageModel`; always returns a plain string (JSON with the image URLs plus `viewImage` / `downloadFile` hints) instead of forcing image content blocks |
+| `view_image` | View/analyze an image — vision models only (`Model.vision`). A network URL is returned as an `image_url` content block; a local path is auto-uploaded via the Files API and returned as a `file` content block |
+| `generate_image` | Generate images from text — requires `defaultImageModel`; always returns a plain string (JSON with the image URLs plus `view_image` / `download_file` hints) instead of forcing image content blocks |
 
 ### Dynamic Tools
 
@@ -299,7 +298,7 @@ In addition to built-in tools, the SDK provides 5 dynamic loading tools that are
 Tools are assembled in three phases by the SDK's `Scope` capability pipeline:
 
 1. **Discovery** — Scan filesystem for built-in tools, user tools, SubAgents, Skills, and MCP servers. All 20 built-in tools are discovered unconditionally (no filtering at this stage)
-2. **Filtering** — Apply permissions (`allow`/`deny`), security exclusions (recursion protection), and each tool's self-declared `isAvailable(config, definition)` (availability is decided at build time when the model is known; e.g. `viewImage` only for vision models, `generateImage` requires `defaultImageModel`)
+2. **Filtering** — Apply permissions (`allow`/`deny`), security exclusions (recursion protection), and each tool's self-declared `isAvailable(config, definition)` (availability is decided at build time when the model is known; e.g. `view_image` only for vision models, `generate_image` requires `defaultImageModel`)
 3. **Instantiation** — Map filtered names to `Tool` instances and register dynamic loaders
 
 Each Agent has independent permissions — no inheritance between parent Agent and SubAgent. The only exception is the temporary Skill sub-agent (created by `call_skill_sub_agent`), which reuses the caller's tool set without a second permission pass, as a transient conversation proxy rather than an independent entity.

package/README.zh.md

@@ -66,12 +66,12 @@ ai --version
 ╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
 
               终端里的 AI 协作台
-              v1.0.0-alpha.1 · sdk x · core y
+              v1.0.0-alpha.11 · sdk x · core y
 ```
 
-启动界面结束后**直接进入对话界面**（若存在「上一轮会话」则自动续接，否则新建对话）。对话界面采用**底部固定**布局：分隔线、输入行与状态栏（模型 · Agent · token 用量 · 生成状态）始终贴在终端底部，对话内容在其上方滚动；生成中时输入行位置显示进度指示。
+启动界面结束后**直接进入对话界面**（若存在「上一轮会话」则自动续接，否则新建对话）。对话界面采用**底部固定**布局：分隔线、输入行与状态栏（模型 · Agent · 本轮/累计 token 用量 · 生成状态）始终贴在终端底部，对话内容在其上方滚动；生成中时输入行位置显示进度指示。
 
-对话界面包含：流式输出区（思考过程 / 回答正文 / 工具调用分行展示）、多行输入（`Enter` 发送、`Ctrl+N` 换行、`← →` 移动光标、`Ctrl+← →` 跨词）与内联 `/` 命令菜单（↑↓ 选择、`Tab` 补全）。工具调用以 `⚙ 名称(参数)` 展示并带 **JSON 语法高亮**，正文与思考里的**围栏代码块按语言高亮**（高亮数据来自 `highlight.js` / `lowlight`）。`Ctrl+C` 在生成中取消本轮请求、空闲时退出。
+对话界面包含：流式输出区（思考过程 / 回答正文 / 工具调用分行展示）、多行输入（`Enter` 发送、`Ctrl+N` 换行、`← →` 移动光标、`Ctrl+← →` 跨词）与内联 `/` 命令菜单（↑↓ 选择、`Tab` 补全）。工具调用以 `⚙ 名称(参数)` 展示并带 **JSON 语法高亮**，正文与思考按 **Markdown 源码着色**（标题 / 粗体 / 斜体 / 行内代码 / 列表 / 引用 / 链接），**围栏代码块按语言高亮并保留围栏标记**（高亮数据来自 `highlight.js` / `lowlight`）。`Ctrl+C` 在生成中取消本轮请求、空闲时退出。
 
 ### 首次配置（API Key）
 
@@ -114,25 +114,24 @@ ai --version
 | `/clear` | 清屏 |
 | `/config` | 打开配置中心（端点 / 模型 / 图片模型 / MCP 服务器 / Agent 定义 / 默认项 / 工具上限） |
 | `/key` | 设置当前端点的 API Key（保存后自动重建会话） |
-| `/migrate` | 手动任务迁移（生成交接文档并开启新会话） |
+| `/handoff` | 编写任务交接文档（会话照旧，不弹确认） |
+| `/migrate` `/migration` | 交接 + 开启新会话（清空历史，需确认） |
 | `/help` | 显示可用命令 |
 
-### 任务迁移
+### 任务交接与迁移
 
-当 API 响应中的 `usage.prompt_tokens` 超过模型的 `maxContextTokens` 时，系统会先**二次确认**（展示当前用量与阈值，默认「是」；选择「否」则跳过本次迁移、当前对话不受影响），确认后生成**交接文档**，汇总已完成任务、待办事项和关键决策，然后创建新会话并将交接文档注入为上下文，实现无缝衔接。确认框仅在 stdin/stdout 均为 TTY 时出现；管道、重定向等非交互场景无确认通道，保持既有自动迁移行为。
+两条命令，同一条管道：
 
-你也可以在对话中随时输入 `/migrate` 手动触发迁移，而无需等待 token 超限。手动与自动迁移均委托给 SDK 的 `TaskMigrationService`，交接文档生成始终一致。
+- **`/handoff`** — 原 agent 停下手头工作，用自己的工具核实真实状态（分支、未提交改动、测试、端口），把交接文档写到 `<项目>/.ai-zen/handoffs/<时间戳>-<会话id>.md`。会话照旧运行，因此可以继续打磨这份文档。
+- **`/migrate`** — 同一次交接，然后把历史清空、以该文档开启新会话（断点消息只带路径，由新 agent 自己读取）。
 
-同样的上下文护栏也作用于**子 Agent**：每次委派边界（`onSubAgentStart`）CLI 都会把同一个 `ContextGuardPlugin`（同一 `maxTokens`）安插到新建的子 Agent 上，因此被委派的子 Agent（含 `call_skill_sub_agent` 创建的技能子 Agent）在上下文超出硬上限时同样会被中断。该过程是透明的，正常运行的子 Agent 不受影响。
+两种执行者：`self`（默认——原 agent 在会话内写，保真度最高）与 `summary`（一次独立模型调用，便宜但有损）。`self` 失败时**单向**降级为 `summary`。可用 `/handoff summary` 或 `/migrate self` 显式指定。
+
+当 `usage.prompt_tokens` 超过模型的 `maxContextTokens`，交互式终端会弹出三选一选择器（自交接 / 独立摘要 / 跳过）；管道等非交互场景按默认执行者迁移，不阻塞。
 
-迁移提示词模板包含：
-- **对话断点** — 最后一段对话原文引用
-- **已完成的任务** — 任务标题和产出路径
-- **未完成的任务** — 描述、进度、下一步
-- **重要记忆** — 技术偏好、踩坑记录、架构决策
-- **文件索引** — 关键文件及用途说明
-- **接手指令** — 先读文件验真、再对状态、后行动的 SOP
+文档模板不在代码里：来自 `handoff` Skill（`~/.ai-zen/skills/handoff/SKILL.md`，由 SDK 释放并随版本同步；在 frontmatter 写 `metadata.custom: "true"` 可保留你自己的版本，也可在项目内覆盖）。完整链路、成本说明与模板章节见 [任务交接与迁移](./docs/zh/migration.md)。
 
+同样的上下文护栏也作用于**子 Agent**：每次委派边界（`onSubAgentStart`）CLI 都会把同一个 `ContextGuardPlugin`（同一 `maxTokens`）安插到新建的子 Agent 上，因此被委派的子 Agent（含 `call_skill_sub_agent` 创建的技能子 Agent）在上下文超出硬上限时同样会被中断。该过程是透明的，正常运行的子 Agent 不受影响。
 ### Shell 兜底钩子
 
 当你在终端输入一个不存在的命令时，自动转发给 AI 处理：
@@ -262,25 +261,25 @@ CLI 提供 20 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用
 | 工具 | 说明 |
 |------|------|
 | `cwd` | 获取当前工作目录 |
-| `readFile` | 读取文件内容（支持 `range` 分批读取） |
-| `inspectFile` | 勘察文件结构概况（行数、字符数、列宽分布、行尾风格），不读取内容 |
-| `writeFile` | 写入文件 |
+| `read` | 读取文件内容（支持 `range` 分批读取） |
+| `inspect_file` | 勘察文件结构概况（行数、字符数、列宽分布、行尾风格），不读取内容 |
+| `write` | 写入文件 |
 | `edit` | 替换文件中的文本（单次替换） |
-| `batchEdit` | 批量编辑文本 |
+| `batch_edit` | 批量编辑文本 |
 | `exec` | 执行 shell 命令 |
-| `exec_async` | 异步执行 shell 命令（立即返回，不等待结果） |
+| `spawn` | 异步执行 shell 命令（立即返回，不等待结果） |
 | `mkdir` | 创建目录 |
 | `rm` | 删除文件或目录 |
 | `glob` | 通配符扫描文件 |
 | `ls` | 列出目录 |
 | `exist` | 检查路径是否存在 |
-| `findText` | 在文件中查找文本 |
-| `downloadFile` | 从 URL 下载文件 |
+| `find_text` | 在文件中查找文本 |
+| `download_file` | 从 URL 下载文件 |
 | `rename` | 重命名或移动文件 |
 | `copy` | 复制文件或目录 |
 | `sleep` | 等待指定毫秒数 |
-| `viewImage` | 查看/分析图片 — 仅视觉模型可用（`Model.vision`）。网络图片直接以 `image_url` 内容块返回；本地图片经 Files API 自动上传后以 `file` 内容块返回 |
-| `generateImage` | 根据描述生成图片 — 需配置 `defaultImageModel`；统一返回字符串（含图片 URL 列表与 `viewImage` / `downloadFile` 提示的 JSON），不再强制返回图片内容块 |
+| `view_image` | 查看/分析图片 — 仅视觉模型可用（`Model.vision`）。网络图片直接以 `image_url` 内容块返回；本地图片经 Files API 自动上传后以 `file` 内容块返回 |
+| `generate_image` | 根据描述生成图片 — 需配置 `defaultImageModel`；统一返回字符串（含图片 URL 列表与 `view_image` / `download_file` 提示的 JSON），不再强制返回图片内容块 |
 
 ### 动态工具
 
@@ -299,7 +298,7 @@ CLI 提供 20 个内置工具，由 `@ai-zen/agents-sdk` 实现。工具可用
 工具装配由 SDK 的 `Scope` 能力管线管理，分为三个阶段：
 
 1. **发现** — 扫描文件系统获取内置工具、用户工具、SubAgent、Skill 和 MCP 服务器。20 个内置工具全部无条件发现（此阶段不做过滤）
-2. **过滤** — 应用权限（`allow`/`deny`）、安全排除（递归保护），以及各工具自声明的 `isAvailable(config, definition)`（在模型已知的构建阶段判断可用性；如 `viewImage` 仅视觉模型、`generateImage` 需配置 `defaultImageModel`）
+2. **过滤** — 应用权限（`allow`/`deny`）、安全排除（递归保护），以及各工具自声明的 `isAvailable(config, definition)`（在模型已知的构建阶段判断可用性；如 `view_image` 仅视觉模型、`generate_image` 需配置 `defaultImageModel`）
 3. **实例化** — 将过滤后的名称映射为 `Tool` 实例，注册动态加载器
 
 每个 Agent 拥有独立的权限配置，父 Agent 与 SubAgent 之间不继承权限。唯一的例外是 `call_skill_sub_agent` 创建的临时 Skill 子 Agent——它是临时的对话分身而非独立实体，因此沿用调用者的工具能力（不再走第二遍权限过滤）。

package/dist/agent-creator.d.ts

@@ -6,6 +6,17 @@
  */
 import { Scope, SdkAgent } from "@ai-zen/agents-sdk";
 import type { AgentNS } from "@ai-zen/agents-core";
+/**
+ * Skill 目录列表（优先级从高到低）：
+ *   1. 项目/.ai-zen/skills/
+ *   2. 项目/.agents/skills/            ← 业界通用规范
+ *   3. ~/.ai-zen/skills/
+ *   4. ~/.agents/skills/               ← 业界通用规范
+ *
+ * 同时供 Scope 装配与交接服务（读取 `handoff` Skill 正文）使用，避免两处各算一遍。
+ * 只返回**当前真实存在**的目录，不存在的不参与发现。
+ */
+export declare function listSkillDirs(): string[];
 export declare function getScope(): Promise<Scope>;
 /**
  * 重置 Scope 单例：释放当前 Scope（断开 MCP 连接等），下次 `getScope()` 按磁盘配置重建。

package/dist/agent-creator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-creator.d.ts","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,KAAK,EAGL,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAiBnD,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,CA8C/C;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAShD;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAchF"}
+{"version":3,"file":"agent-creator.d.ts","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EACL,KAAK,EAGL,QAAQ,EACT,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAiBnD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAOxC;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,CAqC/C;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAShD;AAID,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAchF"}

package/dist/agent-creator.js

@@ -13,6 +13,24 @@ import { readConfig } from "./config.js";
 let _scope = null;
 /** existsSync 的别名，用于数组 .filter() 场景 */
 const exists = existsSync;
+/**
+ * Skill 目录列表（优先级从高到低）：
+ *   1. 项目/.ai-zen/skills/
+ *   2. 项目/.agents/skills/            ← 业界通用规范
+ *   3. ~/.ai-zen/skills/
+ *   4. ~/.agents/skills/               ← 业界通用规范
+ *
+ * 同时供 Scope 装配与交接服务（读取 `handoff` Skill 正文）使用，避免两处各算一遍。
+ * 只返回**当前真实存在**的目录，不存在的不参与发现。
+ */
+export function listSkillDirs() {
+    return [
+        PROJECT_SKILLS_DIR,
+        PROJECT_AGENTS_SKILLS_DIR,
+        SKILLS_DIR,
+        USER_AGENTS_SKILLS_DIR,
+    ].filter(exists);
+}
 export async function getScope() {
     if (_scope)
         return _scope;
@@ -30,17 +48,8 @@ export async function getScope() {
         join(AI_ZEN_DIR, "mcp.json"),
         USER_AGENTS_MCP_CONFIG_FILE,
     ].filter(exists);
-    // Skills 目录优先级（从高到低）：
-    //   1. 项目/.ai-zen/skills/
-    //   2. 项目/.agents/skills/            ← 业界通用规范
-    //   3. ~/.ai-zen/skills/
-    //   4. ~/.agents/skills/               ← 业界通用规范
-    const skillsPaths = [
-        PROJECT_SKILLS_DIR,
-        PROJECT_AGENTS_SKILLS_DIR,
-        SKILLS_DIR,
-        USER_AGENTS_SKILLS_DIR,
-    ].filter(exists);
+    // Skills 目录优先级（从高到低）：见 listSkillDirs()
+    const skillsPaths = listSkillDirs();
     _scope = new Scope({
         config,
         agentsDir: AGENTS_DIR,

package/dist/agent-creator.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"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"}

package/dist/auto-migrate-confirm.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 自动迁移的「执行者选择」入口（CLI 层）。
+ *
+ * 背景：SDK 的 `AutoMigratePlugin` 在 `usage.prompt_tokens` 超过阈值时触发迁移，
+ * 但「谁来写交接文档」是产品决策——保真度高的**原 agent 自交接**，还是便宜的**独立摘要**。
+ * SDK 已把该决策抽象为 `resolveMode` 回调，CLI 在这里把它接到「用户三选一」上：
+ * 原 agent 自交接 / 独立摘要 / 跳过本次迁移。
+ *
+ * 边界（保持 SDK 的分工，不重复实现「何时迁移」的语义）：
+ *   - **何时迁移**：`AutoMigratePlugin`（阈值判断 + busy 让行）；
+ *   - **用什么执行者**：本模块的 `resolveMode`；
+ *   - **实际怎么交接**：共享的 `HandoffService`（与 `/migrate`、`/handoff` 同一条链路）。
+ *
+ * 交互约定：
+ *   - 仅在 stdin 与 stdout **均为 TTY**（人类交互终端）时询问；
+ *   - 非交互环境（管道、重定向、e2e 脚本）没有选择通道，直接按 `defaultMode` 迁移，
+ *     不阻塞等待输入、不额外输出，管道语义不变；
+ *   - 选择器默认高亮 `self`（保真），Esc/取消 = 跳过本次迁移，不影响当前对话
+ *     （历史未被剔除）；只要仍处于超限状态，下次发送后还会再问。
+ */
+import { AutoMigratePlugin, type AutoMigrateTriggerInfo, type HandoffMode, type HandoffService } from "@ai-zen/agents-sdk";
+export interface AutoMigrateModeOptions {
+    /** 交接服务实例（与 `/migrate`、`/handoff` 共用同一实例） */
+    service: HandoffService;
+    /** 触发迁移的上下文阈值 */
+    maxTokens: number;
+    /**
+     * 用户的执行者选择（由调用方注入：TUI 用选择器浮层）。
+     * 返回 `null` 表示跳过本次迁移。
+     */
+    choose: (info: AutoMigrateTriggerInfo) => Promise<HandoffMode | null>;
+    /** 非交互环境下的执行者，默认 `self` */
+    defaultMode?: HandoffMode;
+    /** 是否需要向用户确认；默认「stdin 与 stdout 均为 TTY」。可注入，便于单测 */
+    shouldConfirm?: () => boolean;
+    /** 输出信息（如「已跳过本次迁移」）；由调用方注入（TUI 走 Ink notice），默认丢弃 */
+    log?: (text: string) => void;
+}
+/** 默认交互判定：仅当 stdin 与 stdout 均为 TTY 时才具备选择通道 */
+export declare function canPromptUser(): boolean;
+/** 构造带「执行者选择」的自动迁移插件 */
+export declare function createAutoMigratePlugin(options: AutoMigrateModeOptions): AutoMigratePlugin;
+//# sourceMappingURL=auto-migrate-confirm.d.ts.map

package/dist/auto-migrate-confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate-confirm.d.ts","sourceRoot":"","sources":["../src/auto-migrate-confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,WAAW,EAChB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,sBAAsB;IACrC,6CAA6C;IAC7C,OAAO,EAAE,cAAc,CAAC;IACxB,iBAAiB;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACtE,2BAA2B;IAC3B,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC;IAC9B,qDAAqD;IACrD,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,+CAA+C;AAC/C,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAwB;AACxB,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,iBAAiB,CA4B1F"}

package/dist/auto-migrate-confirm.js

@@ -0,0 +1,46 @@
+/**
+ * 自动迁移的「执行者选择」入口（CLI 层）。
+ *
+ * 背景：SDK 的 `AutoMigratePlugin` 在 `usage.prompt_tokens` 超过阈值时触发迁移，
+ * 但「谁来写交接文档」是产品决策——保真度高的**原 agent 自交接**，还是便宜的**独立摘要**。
+ * SDK 已把该决策抽象为 `resolveMode` 回调，CLI 在这里把它接到「用户三选一」上：
+ * 原 agent 自交接 / 独立摘要 / 跳过本次迁移。
+ *
+ * 边界（保持 SDK 的分工，不重复实现「何时迁移」的语义）：
+ *   - **何时迁移**：`AutoMigratePlugin`（阈值判断 + busy 让行）；
+ *   - **用什么执行者**：本模块的 `resolveMode`；
+ *   - **实际怎么交接**：共享的 `HandoffService`（与 `/migrate`、`/handoff` 同一条链路）。
+ *
+ * 交互约定：
+ *   - 仅在 stdin 与 stdout **均为 TTY**（人类交互终端）时询问；
+ *   - 非交互环境（管道、重定向、e2e 脚本）没有选择通道，直接按 `defaultMode` 迁移，
+ *     不阻塞等待输入、不额外输出，管道语义不变；
+ *   - 选择器默认高亮 `self`（保真），Esc/取消 = 跳过本次迁移，不影响当前对话
+ *     （历史未被剔除）；只要仍处于超限状态，下次发送后还会再问。
+ */
+import { AutoMigratePlugin, } from "@ai-zen/agents-sdk";
+/** 默认交互判定：仅当 stdin 与 stdout 均为 TTY 时才具备选择通道 */
+export function canPromptUser() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/** 构造带「执行者选择」的自动迁移插件 */
+export function createAutoMigratePlugin(options) {
+    const { service, maxTokens, choose, defaultMode = "self", shouldConfirm = canPromptUser, log = () => { }, } = options;
+    return new AutoMigratePlugin({
+        service,
+        maxTokens,
+        resolveMode: async (info) => {
+            // 非交互环境：没有选择通道，按默认执行者迁移（不阻塞、不额外输出）
+            if (!shouldConfirm())
+                return defaultMode;
+            const mode = await choose(info);
+            if (mode == null) {
+                log("⏭️ 已跳过本次任务迁移，继续当前对话。");
+                log("💡 上下文仍接近上限：可随时输入 /migrate 手动迁移；若继续增长至严重超限，对话会被安全护栏中断。");
+                return null;
+            }
+            return mode;
+        },
+    });
+}
+//# sourceMappingURL=auto-migrate-confirm.js.map

package/dist/auto-migrate-confirm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate-confirm.js","sourceRoot":"","sources":["../src/auto-migrate-confirm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EACL,iBAAiB,GAIlB,MAAM,oBAAoB,CAAC;AAoB5B,+CAA+C;AAC/C,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,uBAAuB,CAAC,OAA+B;IACrE,MAAM,EACJ,OAAO,EACP,SAAS,EACT,MAAM,EACN,WAAW,GAAG,MAAM,EACpB,aAAa,GAAG,aAAa,EAC7B,GAAG,GAAG,GAAG,EAAE,GAAE,CAAC,GACf,GAAG,OAAO,CAAC;IAEZ,OAAO,IAAI,iBAAiB,CAAC;QAC3B,OAAO;QACP,SAAS;QACT,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC1B,mCAAmC;YACnC,IAAI,CAAC,aAAa,EAAE;gBAAE,OAAO,WAAW,CAAC;YAEzC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC;YAChC,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;gBACjB,GAAG,CAAC,sBAAsB,CAAC,CAAC;gBAC5B,GAAG,CACD,wDAAwD,CACzD,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/config.d.ts

@@ -15,7 +15,14 @@
  *   ├── mcp-oauth/                ← MCP OAuth token（共享）
  *   └── cli/                      ← CLI 运行时数据
  *       ├── conversations/        ← 对话记录
- *       └── last-session.json     ← 「上一轮会话 id」指针
+ *       └── last-session.json     ← 「各 cwd 上一轮会话 id」指针（cwd → id）
+ *
+ *   项目/.ai-zen/                 ← 项目级配置与产物
+ *   ├── skills/                   ← 项目级 Skill
+ *   ├── tools/                    ← 项目级工具
+ *   ├── sub-agents/               ← 项目级子 Agent
+ *   ├── mcp.json                  ← 项目级 MCP 配置
+ *   └── handoffs/                 ← 交接文档（任务交接的落盘产物）
  *
  *   ~/.agents/                    ← 业界通用规范（如 Cursor、Windsurf、Cline）
  *   ├── skills/                   ← 用户级 Skill
@@ -50,6 +57,13 @@ export declare const TOOLS_DIR: string;
 export declare const PROJECT_SUB_AGENTS_DIR: string;
 export declare const PROJECT_SKILLS_DIR: string;
 export declare const PROJECT_TOOLS_DIR: string;
+/**
+ * 交接文档目录（项目级）：`<cwd>/.ai-zen/handoffs/`。
+ *
+ * 交接文档是「人也能直接读」的产物，放在项目内便于随仓库共享/评审；
+ * 目录由交接时的 write 工具或服务落盘时自动创建，无需预先建立。
+ */
+export declare const PROJECT_HANDOFFS_DIR: string;
 export declare const USER_AGENTS_SKILLS_DIR: string;
 export declare const USER_AGENTS_MCP_CONFIG_FILE: string;
 export declare const PROJECT_AGENTS_DIR: string;