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

package/README.zh.md

@@ -1,6 +1,6 @@
 # @ai-zen/cli
 
-AI Agent 命令行界面，基于 `@ai-zen/agents-sdk` 和 `@ai-zen/agents-core` 构建。提供交互式对话终端，内置文件系统操作工具，支持 MCP 协议集成外部工具、子 Agent 编排和 Skill 管理。
+AI Agent 命令行界面，基于 `@ai-zen/agents-sdk` 和 `@ai-zen/agents-core` 构建。提供**双模式**运行：交互式终端（TUI）用于人与 AI 对话，纯 stdio 模式用于脚本、管道与 shell 兜底钩子。内置文件系统操作工具，支持 MCP 协议集成外部工具、子 Agent 编排和 Skill 管理。
 
 ## 安装
 
@@ -20,42 +20,78 @@ pnpm build
 npm install -g .
 ```
 
+## 运行模式
+
+CLI 有两种**互不混合**的运行模式，由启动参数与终端环境自动判定：
+
+| 模式 | 触发条件 | 面向对象 | 核心行为 |
+|------|----------|----------|----------|
+| **纯 stdio** | 带参数，**或** stdin/stdout 非 TTY（管道、重定向、CI） | 脚本、管道、shell 兜底钩子 | 无任何额外交互；读入文本，把**最终回答以纯文本写入 stdout** |
+| **TUI** | 无参数且 stdin/stdout 均为 TTY | 人类用户 | 交互式对话界面 |
+
+纯 stdio 模式下，日志 / 进度 / 工具过程 / 错误摘要一律走 **stderr**，stdout 只有结果本身（零 ANSI、零 emoji 前缀、零 spinner）；成功退出码 `0`，失败非 `0`。默认**不落盘**（不写对话存档）。
+
 ## 快速使用
 
 ```bash
-# 交互式主菜单
-zen
+# TUI：无参数且处于交互终端
+ai
+
+# 纯 stdio：参数即提示词，结果写入 stdout
+ai 你好，请介绍一下你自己。
+
+# 管道：stdin 作为内容，参数作为指令
+cat README.md | ai "用三句话总结"
 
-# 快速对话（参数作为初始消息）
-zen 你好，请介绍一下你自己。
+# 落盘：默认不保存，需要时显式 --save
+ai --save "帮我给这个函数起个名字"
+
+# 帮助 / 版本
+ai --help
+ai --version
 ```
 
-## 主菜单
+> 旧命令名 `aiz` / `zen` 作为过渡别名在当前版本仍可用，未来版本会移除。
+
+## 界面（TUI）
 
-运行 `zen` 进入主菜单：
+无参数且处于交互终端时，进入由 **Ink（React）** 打造的全屏界面。启动先呈现动画渐变的 ASCII 启动界面：
 
 ```
-🤖 欢迎使用 AI-Zen CLI
-
-? 请选择操作:
-  ▶️  继续上次未完成的对话  （如有草稿）
-  💬 开始新对话
-  📂 继续已保存的对话
-  📋 管理已保存的对话
-  🤖 管理 Agents
-  ⚙️  配置管理
-  ❌ 退出
+ █████╗ ██╗    ███████╗███████╗███╗   ██╗
+██╔══██╗██║    ╚══███╔╝██╔════╝████╗  ██║
+███████║██║      ███╔╝ █████╗  ██╔██╗ ██║
+██╔══██║██║     ███╔╝  ██╔══╝  ██║╚██╗██║
+██║  ██║██║    ███████╗███████╗██║ ╚████║
+╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
+
+              终端里的 AI 协作台
+              v1.0.0-alpha.10 · sdk x · core y
 ```
 
-### 草稿恢复
+启动界面结束后**直接进入对话界面**（若存在「上一轮会话」则自动续接，否则新建对话）。对话界面采用**底部固定**布局：分隔线、输入行与状态栏（模型 · Agent · 本轮/累计 token 用量 · 生成状态）始终贴在终端底部，对话内容在其上方滚动；生成中时输入行位置显示进度指示。
+
+对话界面包含：流式输出区（思考过程 / 回答正文 / 工具调用分行展示）、多行输入（`Enter` 发送、`Ctrl+N` 换行、`← →` 移动光标、`Ctrl+← →` 跨词）与内联 `/` 命令菜单（↑↓ 选择、`Tab` 补全）。工具调用以 `⚙ 名称(参数)` 展示并带 **JSON 语法高亮**，正文与思考按 **Markdown 源码着色**（标题 / 粗体 / 斜体 / 行内代码 / 列表 / 引用 / 链接），**围栏代码块按语言高亮并保留围栏标记**（高亮数据来自 `highlight.js` / `lowlight`）。`Ctrl+C` 在生成中取消本轮请求、空闲时退出。
 
-如果退出对话时没有保存（或进程被强制杀死），对话内容会**自动保存为草稿**。下次启动 `zen` 时会看到：
+### 首次配置（API Key）
+
+首次启动时若所选模型绑定的端点还没有 API Key，会**先弹出凭据设置屏**，而不是报错退出：
 
 ```
-▶️  继续上次未完成的对话 (12 条消息, 2025/1/1 12:00:00)
-💬 开始新对话（放弃草稿）
+ ? 首次配置 · 设置 DeepSeek 的 API Key
+ 端点：DeepSeek · https://api.deepseek.com/v1
+ 当前：未设置
+ DeepSeek 申请地址：https://platform.deepseek.com/api_keys
+ 保存后立即进入对话（Esc 放弃并退出）。
+ ❯ ▏
 ```
 
+`Enter` 保存并直接进入对话（写入 `~/.ai-zen/config.json`），`Tab` 切明文核对，`Esc` 放弃。进入对话后仍可用 `/key` 修改**当前端点**的 Key（保存后自动重建会话，立即生效）、用 `/config` 打开配置中心（默认模型 / 端点管理：列表含「＋ 新建端点」与各端点，选中端点后可就地编辑 API Key / Base URL）。
+
+### 会话恢复
+
+每个会话都会在对话过程中**直接落盘为独立文件**（`cli/conversations/<id>.json`），不再有单独的草稿存储。一个指针文件（`cli/last-session.json`）记录**上一轮会话 id**；下次启动 `ai` 会**自动续接该会话**，接着上次继续。
+
 ### 对话命令
 
 对话中输入的所有命令以 `/` 开头。输入 `/` 会在输入行下方实时列出可用命令及说明，继续输入即按前缀收敛候选：
@@ -65,54 +101,67 @@ zen 你好，请介绍一下你自己。
   /back         撤回消息（可修改后重发）
 ```
 
-> 提示仅作展示，不改变提交语义：回车始终提交当前输入原文，命令按完整名称精确匹配；输入未识别的 `/xxx` 命令会提示「未知命令」。
+> 输入 `/` 会在输入行下方实时列出候选命令（↑↓ 选择、`Tab` 补全、`Enter` 提交/执行）；命令按完整名称匹配，输入未识别的 `/xxx` 会提示「未知命令」。
 
 | 命令 | 说明 |
 |------|------|
-| `/exit` `/quit` | 退出对话（会提示是否保存） |
-| `/save` | 保存当前对话 |
+| `/exit` `/quit` | 退出对话 |
+| `/save` | 保存当前对话（会话本就每轮实时落盘） |
+| `/load` | 加载已保存的对话（替换当前会话） |
 | `/new` | 重置会话（清空历史） |
 | `/back` | 撤回消息（回退到指定位置并可编辑后重发） |
 | `/editor` | 使用系统编辑器（vim/nano）输入长消息 |
 | `/clear` | 清屏 |
-| `/migrate` | 手动任务迁移（生成交接文档并开启新会话） |
+| `/config` | 打开配置中心（端点 / 模型 / 图片模型 / MCP 服务器 / Agent 定义 / 默认项 / 工具上限） |
+| `/key` | 设置当前端点的 API Key（保存后自动重建会话） |
+| `/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` 显式指定。
 
-迁移提示词模板包含：
-- **对话断点** — 最后一段对话原文引用
-- **已完成的任务** — 任务标题和产出路径
-- **未完成的任务** — 描述、进度、下一步
-- **重要记忆** — 技术偏好、踩坑记录、架构决策
-- **文件索引** — 关键文件及用途说明
-- **接手指令** — 先读文件验真、再对状态、后行动的 SOP
+当 `usage.prompt_tokens` 超过模型的 `maxContextTokens`，交互式终端会弹出三选一选择器（自交接 / 独立摘要 / 跳过）；管道等非交互场景按默认执行者迁移，不阻塞。
 
+文档模板不在代码里：来自 `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 处理：
 
 ```bash
 # 安装钩子
-zen hook install
+ai hook install
 
 # 之后随便输入点什么：
 > 今天天气怎么样？
 # 这条消息会被转发给 AI，而不是显示 "command not found"
 
 # 卸载钩子
-zen hook uninstall
+ai hook uninstall
 ```
 
+钩子函数体调用的是 `ai "$@"`（纯 stdio 模式），答案就地写入当前 shell 会话。若此前安装过旧版 `aiz` 钩子，重新执行 `ai hook install` 会自动升级；也可先 `ai hook uninstall` 再安装。
+
 ## 配置管理
 
-配置文件存储在 `~/.ai-zen/config.json`（或 `$AI_ZEN_DIR/config.json`），与其他 AI-Zen 客户端共享。其中 `maxContextTokens` 是迁移触发阈值（通常设为模型实际上下文窗口的约 25%，例如 1M tokens 的模型设为 250,000）。
+配置文件存储在 `~/.ai-zen/config.json`（或 `$AI_ZEN_DIR/config.json`），与其他 AI-Zen 客户端共享，是**唯一数据源**。常用项可在 TUI 内直接编辑，无需手改 JSON：
+
+| 场景 | 做法 |
+|------|------|
+| 首次启动、端点缺 Key | 启动时自动弹出**凭据设置屏** |
+| 修改当前模型所用端点的 Key | 对话内 `/key`（保存后自动重建会话） |
+| 端点 / 模型 / 图片模型、MCP 服务器、Agent 定义（含 Sub-agent）、默认项、工具输出上限 | 对话内 `/config`（配置中心，全面管理） |
+| 其它高级项（Skill / 用户工具等） | 手动编辑 `~/.ai-zen/` 下的文件 |
+
+其中 `maxContextTokens` 是迁移触发阈值（通常设为模型实际上下文窗口的约 25%，例如 1M tokens 的模型设为 250,000）。
 
 ```jsonc
 {
@@ -126,11 +175,12 @@ zen hook uninstall
   ],
   "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 @@ zen hook uninstall
       "defaultSize": "1024x1024"
     }
   ],
-  "defaultModel": "deepseek-v4-flash",
+  "defaultModel": "deepseek-flash",
   "defaultImageModel": "cogview-4",
   "defaultAgent": "default",
-  "defaultMigrationModel": "deepseek-v4-flash"
+  "defaultMigrationModel": "deepseek-flash"
 }
 ```
 
+> 说明：`models` / `imageModels` 中**未标 `custom: true`** 的条目属于**出厂托管**——每次启动会与 SDK 出厂清单对齐、被替换为最新定义；自建模型请加 `"custom": true`。`endpoints` 始终保留用户配置，不受影响。
+
 ### 环境变量
 
 - `AI_ZEN_DIR` — 覆盖共享根目录（默认 `~/.ai-zen`）。CLI 运行时数据在 `$AI_ZEN_DIR/cli/`，共享资源（agents、skills、tools、MCP 等）在 `$AI_ZEN_DIR/`。
@@ -160,7 +212,7 @@ zen hook uninstall
 ├── config.json               ← 端点与模型配置（与其他 AI-Zen 客户端共享）
 ├── cli/                      ← CLI 运行时数据
 │   ├── conversations/        ← CLI 对话记录
-│   └── drafts/               ← CLI 草稿
+│   └── last-session.json     ← 「上一轮会话 id」指针
 ├── agents/                   ← Agent 定义（共享）
 │   ├── default.json          ← 默认 Agent（首次运行自动创建）
 │   └── my-custom-agent.json
@@ -209,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），不再强制返回图片内容块 |
 
 ### 动态工具
 
@@ -246,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——它是临时的对话分身而非独立实体，因此沿用调用者的工具能力（不再走第二遍权限过滤）。
@@ -304,13 +356,14 @@ OAuth 2.0 授权流程（`mcp.json` 中的 `oauth` 字段）已定义类型和
 
 | ID | 名称 | 端点 |
 |----|------|------|
-| `gpt-5.5` | GPT-5.5 | OpenAI |
-| `glm-5.1` | GLM-5.1 | 智谱AI |
-| `glm-5v-turbo` | GLM-5V-Turbo（视觉） | 智谱AI |
+| `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 | 智谱AI |
+| `glm-5.3-flash` | GLM-5.3-Flash（视觉） | 智谱AI |
+| `glm-5.3-flashx` | GLM-5.3-FlashX（视觉） | 智谱AI |
 | `glm-4.7-flash` | GLM-4.7-Flash | 智谱AI |
-| `deepseek-v4-pro` | DeepSeek-V4-Pro | DeepSeek |
-| `deepseek-v4-flash` | DeepSeek-V4-Flash | DeepSeek（**默认模型**） |
-| `deepseek-v4-flash-vision-exp` | DeepSeek-V4-Flash-Vision-Exp（视觉） | DeepSeek |
+| `deepseek-flash` | DeepSeek-V4.1-Flash（视觉） | DeepSeek（**默认模型**） |
 
 ## 开发
 

package/dist/agent-creator.d.ts

@@ -6,8 +6,25 @@
  */
 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>;
-export declare function resetScope(): void;
+/**
+ * 重置 Scope 单例：释放当前 Scope（断开 MCP 连接等），下次 `getScope()` 按磁盘配置重建。
+ *
+ * 配置变更后（如 TUI 的 `/config` 改了端点凭据）必须调用：Scope 的 `config` 只在创建时
+ * 读取一次，不重建则新配置不生效。`_scope` 是同步置空的，便于并发调用方立刻拿到新实例。
+ */
+export declare function resetScope(): Promise<void>;
 export interface CreateAgentOptions {
     messages?: AgentNS.Message[];
     agentId?: string;

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,wBAAgB,UAAU,IAAI,IAAI,CAEjC;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,
@@ -53,8 +62,23 @@ export async function getScope() {
     await _scope.init();
     return _scope;
 }
-export function resetScope() {
+/**
+ * 重置 Scope 单例：释放当前 Scope（断开 MCP 连接等），下次 `getScope()` 按磁盘配置重建。
+ *
+ * 配置变更后（如 TUI 的 `/config` 改了端点凭据）必须调用：Scope 的 `config` 只在创建时
+ * 读取一次，不重建则新配置不生效。`_scope` 是同步置空的，便于并发调用方立刻拿到新实例。
+ */
+export async function resetScope() {
+    const scope = _scope;
     _scope = null;
+    if (!scope)
+        return;
+    try {
+        await scope.dispose();
+    }
+    catch {
+        /* 释放失败不影响后续重建 */
+    }
 }
 export async function createAgent(options) {
     const { messages, agentId } = options;

package/dist/agent-creator.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EACL,KAAK,EACL,QAAQ,EACR,WAAW,IAAI,cAAc,GAE9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,UAAU,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EACjD,UAAU,EACV,sBAAsB,EAAE,kBAAkB,EAAE,iBAAiB,EAC7D,sBAAsB,EAAE,2BAA2B,EACnD,yBAAyB,EAAE,8BAA8B,GAC1D,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,wDAAwD;AAExD,IAAI,MAAM,GAAiB,IAAI,CAAC;AAEhC,uCAAuC;AACvC,MAAM,MAAM,GAAG,UAAU,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAElC,qBAAqB;IACrB,oBAAoB;IACpB,2BAA2B;IAC3B,8CAA8C;IAC9C,0BAA0B;IAC1B,gDAAgD;IAChD,MAAM,QAAQ,GAAG;QACf,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,WAAW,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC;QAC1C,8BAA8B;QAC9B,IAAI,CAAC,UAAU,EAAE,UAAU,CAAC;QAC5B,2BAA2B;KAC5B,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,sBAAsB;IACtB,0BAA0B;IAC1B,8CAA8C;IAC9C,yBAAyB;IACzB,gDAAgD;IAChD,MAAM,WAAW,GAAG;QAClB,kBAAkB;QAClB,yBAAyB;QACzB,UAAU;QACV,sBAAsB;KACvB,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAEjB,MAAM,GAAG,IAAI,KAAK,CAAC;QACjB,MAAM;QACN,SAAS,EAAE,UAAU;KACtB,CAAC,CAAC,GAAG,CACJ,GAAG,QAAQ,CAAC;QACV,cAAc,EAAE,CAAC,sBAAsB,EAAE,cAAc,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACvE,WAAW;QACX,UAAU,EAAE,CAAC,iBAAiB,EAAE,SAAS,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;QACzD,QAAQ;KACT,CAAC,CACH,CAAC;IAEF,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;IAEpB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AASD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IACtC,MAAM,KAAK,GAAG,MAAM,QAAQ,EAAE,CAAC;IAE/B,wCAAwC;IACxC,MAAM,KAAK,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,CAAC,CAAC;IAEhE,wBAAwB;IACxB,kDAAkD;IAClD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,KAAK,CAAC,QAAQ,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IACjC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"agent-creator.js","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"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"}

package/dist/agents-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Agent / Sub-agent 定义仓储 —— CLI 层
+ *
+ * 管理两处定义目录（均为「每实体一个 JSON，文件名 = `<id>.json`」）：
+ *   - 顶层 Agent：`~/.ai-zen/agents/*.json`（`/config`「默认 Agent」可选的那些）
+ *   - 子 Agent：  `~/.ai-zen/sub-agents/*.json`（可被委派，额外带 `function` 定义）
+ *
+ * 单文件读写委托 SDK 的 `AgentRepository`（`EntityRepository`），本模块只做「按 kind 分派」
+ * 与「快照 + 写操作」的组装，便于 TUI 与单测共用。
+ */
+import type { AgentDefinition } from "@ai-zen/agents-sdk";
+/** Agent 定义的类型：顶层 Agent / 子 Agent */
+export type AgentKind = "agent" | "subagent";
+/** 某个 kind 对应的定义目录 */
+export declare function agentDir(kind: AgentKind): string;
+/** kind 的中文名 */
+export declare function agentKindLabel(kind: AgentKind): string;
+/** 「Agent 定义」管理用的仓储：快照 + 写 / 删操作 */
+export interface AgentStore {
+    agents: AgentDefinition[];
+    subAgents: AgentDefinition[];
+    save: (kind: AgentKind, def: AgentDefinition) => Promise<void>;
+    remove: (kind: AgentKind, id: string) => Promise<void>;
+}
+/** 取某 kind 的定义列表 */
+export declare function agentList(store: AgentStore, kind: AgentKind): AgentDefinition[];
+/** 按 id 查找某 kind 的定义 */
+export declare function findAgentDefinition(store: AgentStore, kind: AgentKind, id: string | undefined): AgentDefinition | undefined;
+/** 用给定快照 + 真实文件读写构造仓储 */
+export declare function createAgentStore(agents: AgentDefinition[], subAgents: AgentDefinition[]): AgentStore;
+/** 从磁盘读取 Agent / Sub-agent 快照，并附带真实读写能力 */
+export declare function readAgentStore(): Promise<AgentStore>;
+//# sourceMappingURL=agents-store.d.ts.map

package/dist/agents-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-store.d.ts","sourceRoot":"","sources":["../src/agents-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAG1D,qCAAqC;AACrC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7C,sBAAsB;AACtB,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEhD;AAED,gBAAgB;AAChB,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAEtD;AAED,oCAAoC;AACpC,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,SAAS,EAAE,eAAe,EAAE,CAAC;IAC7B,IAAI,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,EAAE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,oBAAoB;AACpB,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,eAAe,EAAE,CAE/E;AAED,wBAAwB;AACxB,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,MAAM,GAAG,SAAS,GACrB,eAAe,GAAG,SAAS,CAG7B;AAED,yBAAyB;AACzB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,SAAS,EAAE,eAAe,EAAE,GAAG,UAAU,CAWpG;AAED,2CAA2C;AAC3C,wBAAsB,cAAc,IAAI,OAAO,CAAC,UAAU,CAAC,CAI1D"}

package/dist/agents-store.js

@@ -0,0 +1,50 @@
+/**
+ * Agent / Sub-agent 定义仓储 —— CLI 层
+ *
+ * 管理两处定义目录（均为「每实体一个 JSON，文件名 = `<id>.json`」）：
+ *   - 顶层 Agent：`~/.ai-zen/agents/*.json`（`/config`「默认 Agent」可选的那些）
+ *   - 子 Agent：  `~/.ai-zen/sub-agents/*.json`（可被委派，额外带 `function` 定义）
+ *
+ * 单文件读写委托 SDK 的 `AgentRepository`（`EntityRepository`），本模块只做「按 kind 分派」
+ * 与「快照 + 写操作」的组装，便于 TUI 与单测共用。
+ */
+import { AgentRepository } from "@ai-zen/agents-sdk";
+import { AGENTS_DIR, SUB_AGENTS_DIR } from "./config.js";
+/** 某个 kind 对应的定义目录 */
+export function agentDir(kind) {
+    return kind === "agent" ? AGENTS_DIR : SUB_AGENTS_DIR;
+}
+/** kind 的中文名 */
+export function agentKindLabel(kind) {
+    return kind === "agent" ? "Agent" : "Sub-agent";
+}
+/** 取某 kind 的定义列表 */
+export function agentList(store, kind) {
+    return kind === "agent" ? store.agents : store.subAgents;
+}
+/** 按 id 查找某 kind 的定义 */
+export function findAgentDefinition(store, kind, id) {
+    if (!id)
+        return undefined;
+    return agentList(store, kind).find((def) => def.id === id);
+}
+/** 用给定快照 + 真实文件读写构造仓储 */
+export function createAgentStore(agents, subAgents) {
+    return {
+        agents,
+        subAgents,
+        save: async (kind, def) => {
+            await new AgentRepository(agentDir(kind)).write(def);
+        },
+        remove: async (kind, id) => {
+            await new AgentRepository(agentDir(kind)).delete(id);
+        },
+    };
+}
+/** 从磁盘读取 Agent / Sub-agent 快照，并附带真实读写能力 */
+export async function readAgentStore() {
+    const agents = await new AgentRepository(AGENTS_DIR).list();
+    const subAgents = await new AgentRepository(SUB_AGENTS_DIR).list();
+    return createAgentStore(agents, subAgents);
+}
+//# sourceMappingURL=agents-store.js.map

package/dist/agents-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents-store.js","sourceRoot":"","sources":["../src/agents-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAKzD,sBAAsB;AACtB,MAAM,UAAU,QAAQ,CAAC,IAAe;IACtC,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,CAAC;AACxD,CAAC;AAED,gBAAgB;AAChB,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC;AAClD,CAAC;AAUD,oBAAoB;AACpB,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,IAAe;IAC1D,OAAO,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;AAC3D,CAAC;AAED,wBAAwB;AACxB,MAAM,UAAU,mBAAmB,CACjC,KAAiB,EACjB,IAAe,EACf,EAAsB;IAEtB,IAAI,CAAC,EAAE;QAAE,OAAO,SAAS,CAAC;IAC1B,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;AAC7D,CAAC;AAED,yBAAyB;AACzB,MAAM,UAAU,gBAAgB,CAAC,MAAyB,EAAE,SAA4B;IACtF,OAAO;QACL,MAAM;QACN,SAAS;QACT,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;YACxB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACvD,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,EAAE,EAAE;YACzB,MAAM,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC;AAED,2CAA2C;AAC3C,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,MAAM,MAAM,GAAG,MAAM,IAAI,eAAe,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC5D,MAAM,SAAS,GAAG,MAAM,IAAI,eAAe,CAAC,cAAc,CAAC,CAAC,IAAI,EAAE,CAAC;IACnE,OAAO,gBAAgB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC"}

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"}