@ai-zen/cli 0.9.0 → 1.0.0-alpha.10

package/CHANGELOG.md

@@ -1,4 +1,202 @@
-# Changelog
+## [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`** 的全部变化。
+
+### 💥 破坏性变更
+
+- **启动命令由 `aiz` / `zen` 改为 `ai`** —— `package.json` 的 `bin` 改为 `{ "ai", "aiz", "zen" }`；`aiz` / `zen` 作为**过渡别名**保留，未来版本移除。
+- **引入双模式运行，两种模式互不混合** —— 带位置参数、或 stdin/stdout 非 TTY（管道 / 重定向 / CI）时启用**纯 stdio 模式**：无任何额外交互，最终 assistant 文本以纯文本写入 `stdout`（零 ANSI / emoji 前缀 / spinner），日志、进度、工具过程与错误摘要一律走 `stderr`，成功退出码 `0`、失败非 `0`、默认不落盘；仅在**无参数且 stdin/stdout 均为 TTY** 时进入 **TUI 模式**。
+- **交互界面整体重写为 Ink（React）全屏 TUI** —— 取代原 inquirer 行式对话；随之**移除主菜单**（`/menu` 与 `src/menus/*`）以及 `inquirer` / `@types/inquirer` / `chalk` 依赖。
+
+### ✨ 新增
+
+- **TUI 全屏交互界面（Ink + React）**：
+  - 动画渐变 ASCII 启动界面，结束后直接进入对话（有上一轮会话则自动续接）；
+  - 对话区**吸底**（分隔线 / 输入行 / 状态栏固定底部，整帧高度恒为「终端行数 − 1」以避开 Ink 全屏分支）；
+  - 流式输出（思考 / 正文 / 工具调用分行）、历史按行裁剪自底滚动；
+  - **多行输入**（`Enter` 发送、`Ctrl+N` / `Ctrl+J` 换行）与**光标编辑**（`←`/`→`/`Home`/`End`/`Backspace`/`Delete`，`Ctrl`/`Meta` + `←`/`→` 跨词，反显光标 + 硬件光标同步）；
+  - **应用内翻页**（`PgUp`/`PgDn` 翻页、`Shift`/`Alt` + `↑`/`↓` 单行滚动、发送自动回底）；
+  - 输入历史、内联 `/` 命令菜单、状态栏、确认框。
+- **语法高亮**：工具调用参数按 **JSON** 高亮、正文与思考里的**围栏代码块**按语言高亮。高亮**数据**委托 `highlight.js`（经 `lowlight` 产出 hast），CLI 仅把 `hljs-*` scope 映射为 Ink `<Text>` 颜色 —— 与同为 Ink/React 的 Google Gemini CLI 做法一致。
+- **对话内命令**：`/help`、`/load`、`/clear`、`/new`、`/save`、`/config`、`/key`、`/migrate`、`/back`、`/editor`、`/exit`（`registry.ts` 为命令清单唯一来源，`/help` 与输入补全自动同步）。
+- **首启凭据引导 + 配置中心（Ink 原生）**：端点缺 API Key 时先弹凭据设置屏；`/config` 配置中心管理端点、模型、图片模型、默认项（默认模型 / 图片模型 / Agent / 迁移模型）、工具输出上限、**MCP 服务器**（全局 / 项目作用域）与 **Agent 定义**（顶层 Agent + Sub-agent，含四维权限）；编辑「出厂托管」条目自动转 `custom: true`，危险操作二次确认并做引用守卫。
+- **多行文本走系统编辑器**：Agent 提示词、Sub-agent 函数说明 / 参数 schema 等多行字段按 `Enter` 调起 `$EDITOR`（Windows 默认 `notepad`）；参数 schema 以 `.json` 打开并即时校验。
+- **会话持久化改革：会话即文件 + 单指针** —— 每轮结束落盘、`cli/last-session.json` 记录上一轮会话 id、首条消息后才落盘、`/save` 幂等；继续 / 加载时按消息重建历史。
+- **纯 stdio 模式配套**：`ai --help` / `-h`、`ai --version` / `-v`、`ai --save`；SDK 日志与 `console.log` 统一改道 `stderr` 以保证 stdout 纯净。
+- **IME 候选框跟随光标**：用 Ink `useCursor()` 把硬件光标同步到编辑光标，中文输入法候选框正确定位。
+
+### 🔧 变更
+
+- **依赖**：新增 `ink` / `react`（运行时）、`ink-testing-library` / `@types/react`（开发）；新增语法高亮 `highlight.js` / `lowlight`（运行时）与 `@types/hast`（开发）；**移除** `inquirer` / `@types/inquirer` / `chalk`。
+- **升级 `@ai-zen/agents-sdk`**：`1.0.0-alpha.0` → `1.0.0-alpha.1` → `1.0.0-alpha.2`（出厂模型目录刷新、模型清单托管、默认 `mcp.json` 增补 `chrome-devtools` 等；CLI 侧代码零改动）。
+- **TUI 输出统一走 Ink**：迁移进度、会话落盘失败等提示不再 `console.log` / `console.warn` 直写终端（会撕裂 Ink 帧），改为经回调渲染为 notice 块；启动 Logo 渐变也改为 Ink 逐字符 `<Text color>`。
+- **配置向导 / 覆盖层统一「吸底」布局**，列表项与键位提示裁成**严格单行**，修复 VS Code 终端里内容被裁切的问题。
+- **终端状态安全与干净退出**：`SIGINT` / `SIGTERM` / 未捕获异常均卸载 Ink、恢复 raw mode 与光标；`Ctrl+C` 语义为「忙时取消本轮、空闲时退出」；退出显式暂停 stdin 并终止进程（`farewell()`）。
+- **移除旧行式链路（死代码）**：`src/conversation-runner.ts`、`src/slash-hint-prompt.ts`、`src/delta-renderer.ts`、inquirer 版 `src/config-wizard.ts`、`src/draft-*.ts` 等；新增 `src/mode.ts` / `src/stdio-runner.ts` / `src/session-pointer.ts` / `src/conversation-persist-plugin.ts` / `src/config-editor.ts` 与 `src/tui/*` 新实现。
+- 文档：中英 README 与 `docs/zh|en/*` 同步（运行模式、`ai` 命令名、配置中心、多行编辑器等），`docs/manifest.json` 同步。
+
+### ✅ 测试
+
+- 全量单测 **13 文件 / 224 例**，`tsc --noEmit` 与 `npm run build` 零错误；e2e **12 例**真连 DeepSeek API（覆盖双模式、stdio 纯净性、退出码、`--save` 落盘）。
+- 新增测试文件：`mode.test.ts`、`stdio-runner.test.ts`、`theme.test.ts`、`screens.test.tsx`、`tui/config-wizard.test.tsx`、`tui/agent-prompt.test.tsx`、`tui/highlight.test.ts`、`sub-agent-guard-plugin.test.ts`、`auto-migrate-confirm-plugin.test.ts`、`conversation-commands/registry.test.ts`。
+- 真实 PTY 实测：启动 → 对话 → 流式 → `/load` → `/clear` → 退出交还 shell；首启凭据链路；配置中心各子屏。
 
 ## [0.9.0] - 2026-09-30
 

package/README.md

@@ -1,6 +1,6 @@
 # @ai-zen/cli
 
-A command-line interface for AI agents, built on `@ai-zen/agents-sdk` and `@ai-zen/agents-core`. Provides an interactive conversation terminal with built-in file system tools, sub-agent orchestration, and skill management.
+A command-line interface for AI agents, built on `@ai-zen/agents-sdk` and `@ai-zen/agents-core`. It runs in **two modes**: an interactive terminal (TUI) for conversations with the AI, and a pure stdio mode for scripts, pipes, and the shell fallback hook. It ships built-in file system tools and supports MCP integration, sub-agent orchestration, and skill management.
 
 ## Installation
 
@@ -20,42 +20,78 @@ pnpm build
 npm install -g .
 ```
 
+## Run Modes
+
+The CLI has two **non-mixing** run modes, chosen automatically from the launch arguments and the terminal environment:
+
+| Mode | Trigger | Audience | Behavior |
+|------|---------|----------|----------|
+| **Pure stdio** | Arguments present, **or** stdin/stdout is not a TTY (pipe, redirect, CI) | Scripts, pipes, shell fallback hook | No extra interaction; reads input and writes the **final answer as plain text to stdout** |
+| **TUI** | No arguments and both stdin/stdout are TTYs | Human users | Interactive chat UI |
+
+In pure stdio mode, logs / progress / tool activity / error summaries all go to **stderr**; stdout carries the result only (no ANSI, no emoji prefix, no spinner). Exit code is `0` on success and non-zero on failure. Nothing is persisted by default (no conversation archive).
+
 ## Quick Start
 
 ```bash
-# Interactive main menu
-zen
+# TUI: no arguments, interactive terminal
+ai
+
+# Pure stdio: argument is the prompt, result goes to stdout
+ai Hello, introduce yourself.
 
-# Quick chat (pass message as argument)
-zen Hello, introduce yourself.
+# Pipe: stdin is the content, the argument is the instruction
+cat README.md | ai "summarize in three sentences"
+
+# Persist: off by default, opt in with --save
+ai --save "name this function for me"
+
+# Help / version
+ai --help
+ai --version
 ```
 
-## Main Menu
+> The legacy command names `aiz` / `zen` still work as transition aliases in this version and will be removed in a future release.
+
+## Interface (TUI)
 
-Run `zen` to enter the main menu:
+When run with no arguments on an interactive terminal, the CLI opens a full-screen interface built with **Ink (React)**. It starts with an animated, gradient ASCII splash:
 
 ```
-🤖 Welcome to AI-Zen CLI
-
-? Select an action:
-  ▶️  Continue last unfinished conversation  (if draft exists)
-  💬  Start a new conversation
-  📂  Continue a saved conversation
-  📋  Manage saved conversations
-  🤖  Manage Agents
-  ⚙️   Configuration
-  ❌  Exit
+ █████╗ ██╗    ███████╗███████╗███╗   ██╗
+██╔══██╗██║    ╚══███╔╝██╔════╝████╗  ██║
+███████║██║      ███╔╝ █████╗  ██╔██╗ ██║
+██╔══██║██║     ███╔╝  ██╔══╝  ██║╚██╗██║
+██║  ██║██║    ███████╗███████╗██║ ╚████║
+╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
+
+              AI workbench in your terminal
+              v1.0.0-alpha.10 · sdk x · core y
 ```
 
-### Draft Recovery
+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**; 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)
 
-If you exit a conversation without saving (or the process is killed), the conversation is **automatically saved as a draft**. Next time you start `zen`, you'll see:
+On first launch, if the endpoint bound to the selected model has no API Key yet, a **credential screen** appears instead of an error:
 
 ```
-▶️  Continue last unfinished conversation (12 messages, 2025/1/1 12:00:00)
-💬  Start a new conversation (discard draft)
+ ? First-run setup · Set the API Key for DeepSeek
+ Endpoint: DeepSeek · https://api.deepseek.com/v1
+ Current: not set
+ Get a key at: https://platform.deepseek.com/api_keys
+ Saving enters the chat immediately (Esc aborts and exits).
+ ❯ ▏
 ```
 
+`Enter` saves it (to `~/.ai-zen/config.json`) and drops you straight into the chat; `Tab` toggles plaintext, `Esc` aborts. Inside the chat, `/key` changes the **current endpoint's** key (the session is rebuilt on save, so it applies immediately) and `/config` opens the configuration center (default model / endpoint management: a list of [add endpoint] plus each endpoint; select one to edit its API key / base URL in place).
+
+### Session Recovery
+
+Every conversation is persisted directly as its own file (`cli/conversations/<id>.json`) while you chat — there is no separate draft store. A single pointer (`cli/last-session.json`) remembers the **last session id**; next time you start `ai`, that session is **resumed automatically** so you pick up where you left off.
+
 ### Conversation Commands
 
 While in a conversation, all commands start with `/`. Typing `/` lists the available commands, with descriptions, right below the input line; typing more characters narrows the candidates by prefix:
@@ -65,54 +101,67 @@ While in a conversation, all commands start with `/`. Typing `/` lists the avail
   /back         Undo messages (roll back to a specific point and resend)
 ```
 
-> Hints are display-only and do not change submission semantics: Enter always submits exactly what you typed, and commands are matched by their full names. An unrecognized `/xxx` command reports "Unknown command".
+> Typing `/` lists candidate commands below the input line (↑↓ to choose, `Tab` to complete, `Enter` to submit/run). Commands are matched by their full names; an unrecognized `/xxx` reports "Unknown command".
 
 | Command | Description |
 |---------|-------------|
-| `/exit` `/quit` | Exit the conversation (prompts to save) |
-| `/save` | Save the current conversation |
+| `/exit` `/quit` | Exit the conversation |
+| `/save` | Save the current conversation (it is already flushed on every turn) |
+| `/load` | Load a saved conversation (replaces the current session) |
 | `/new` | Reset the conversation (clear history) |
 | `/back` | Undo messages (roll back to a specific point and resend) |
 | `/editor` | Open system editor for long-form input |
 | `/clear` | Clear the screen |
-| `/migrate` | Manually trigger task migration (generate handoff doc & start a new session) |
+| `/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) |
+| `/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:
 
 ```bash
 # Install the hook
-zen hook install
+ai hook install
 
 # After that, try typing something random:
 > what's the weather today?
 # This will be forwarded to AI instead of showing "command not found"
 
 # Uninstall
-zen hook uninstall
+ai hook uninstall
 ```
 
+The hook calls `ai "$@"` (pure stdio mode) so the answer is printed in your current shell session. If you previously installed the legacy `aiz` hook, re-running `ai hook install` upgrades it automatically; you can also run `ai hook uninstall` first.
+
 ## Configuration
 
-Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json` if set), shared with other AI-Zen clients. The `maxContextTokens` field on each model sets the migration threshold (typically ~25% of the model's actual context window, e.g. 250,000 for a 1M-token model).
+Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json` if set), shared with other AI-Zen clients and used as the **single source of truth**. The TUI can edit the common fields for you:
+
+| Scenario | How |
+|----------|-----|
+| First launch, endpoint has no key | The **credential screen** appears automatically |
+| Change the current model's endpoint key | `/key` in the chat (session rebuilt on save) |
+| Endpoints / models / image models, MCP servers, agent definitions (incl. sub-agents), defaults, tool-output cap | `/config` (the configuration center — full management) |
+| Other advanced fields (skills / user tools, …) | Edit the files under `~/.ai-zen/` manually |
+
+The `maxContextTokens` field on each model sets the migration threshold (typically ~25% of the model's actual context window, e.g. 250,000 for a 1M-token model).
 
 ```jsonc
 {
@@ -126,11 +175,12 @@ Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json`
   ],
   "models": [
     {
-      "id": "gpt-5.5",
-      "name": "GPT-5.5",
+      "id": "gpt-6.1-sol",
+      "name": "GPT-6.1 Sol",
       "endpointId": "openai",
-      "modelName": "gpt-5.5",
-      "maxContextTokens": 250000
+      "modelName": "gpt-6.1-sol",
+      "maxContextTokens": 250000,
+      "custom": true
     }
   ],
   "imageModels": [
@@ -142,13 +192,15 @@ Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json`
       "defaultSize": "1024x1024"
     }
   ],
-  "defaultModel": "deepseek-v4-flash",
+  "defaultModel": "deepseek-flash",
   "defaultImageModel": "cogview-4",
   "defaultAgent": "default",
-  "defaultMigrationModel": "deepseek-v4-flash"
+  "defaultMigrationModel": "deepseek-flash"
 }
 ```
 
+> Note: entries in `models` / `imageModels` **without `custom: true`** are **factory-managed** — on every launch they are reconciled with (and replaced by) the SDK factory catalog; add `"custom": true` for your own entries. `endpoints` are never managed and always keep your configuration.
+
 ### Environment Variable
 
 - `AI_ZEN_DIR` — Override the shared root directory (default: `~/.ai-zen`). CLI runtime data goes to `$AI_ZEN_DIR/cli/`, and shared resources (agents, skills, tools, MCP, etc.) go to `$AI_ZEN_DIR/`.
@@ -160,7 +212,7 @@ Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json`
 ├── config.json               ← Endpoints & models (shared with other AI-Zen clients)
 ├── cli/                      ← CLI runtime data
 │   ├── conversations/        ← CLI conversations
-│   └── drafts/               ← CLI drafts
+│   └── last-session.json     ← Pointer to the last session id
 ├── agents/                   ← Agent definitions (shared)
 │   ├── default.json          ← Default agent (created on first run)
 │   └── my-custom-agent.json
@@ -209,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
 
@@ -246,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.
@@ -304,13 +356,14 @@ The OAuth 2.0 authorization flow (the `oauth` field in `mcp.json`) has its types
 
 | ID | Name | Endpoint |
 |----|------|----------|
-| `gpt-5.5` | GPT-5.5 | OpenAI |
-| `glm-5.1` | GLM-5.1 | ZhipuAI |
-| `glm-5v-turbo` | GLM-5V-Turbo (vision) | ZhipuAI |
+| `gpt-6-astra` | GPT-6 Astra | OpenAI |
+| `gpt-6.1-sol` | GPT-6.1 Sol | OpenAI |
+| `gpt-6-luna` | GPT-6 Luna | OpenAI |
+| `glm-5.3` | GLM-5.3 | ZhipuAI |
+| `glm-5.3-flash` | GLM-5.3-Flash (vision) | ZhipuAI |
+| `glm-5.3-flashx` | GLM-5.3-FlashX (vision) | ZhipuAI |
 | `glm-4.7-flash` | GLM-4.7-Flash | ZhipuAI |
-| `deepseek-v4-pro` | DeepSeek-V4-Pro | DeepSeek |
-| `deepseek-v4-flash` | DeepSeek-V4-Flash | DeepSeek (**default**) |
-| `deepseek-v4-flash-vision-exp` | DeepSeek-V4-Flash-Vision-Exp (vision) | DeepSeek |
+| `deepseek-flash` | DeepSeek-V4.1-Flash (vision) | DeepSeek (**default**) |
 
 ## Development