@ai-zen/cli 1.0.0-alpha.2 → 1.0.0-alpha.22

package/README.md

@@ -66,12 +66,81 @@ When run with no arguments on an interactive terminal, the CLI opens a full-scre
 ╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
 
               AI workbench in your terminal
-              v1.0.0-alpha.2 · sdk x · core y
+              v1.0.0-alpha.21 · 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 a **status bar** (three priority-ordered blocks: model · agent · reasoning effort | this-round / cumulative tokens · generation rate | key hints; a block that does not fit moves to the next line whole, so nothing is truncated and no block gets split) always sit at the bottom of the terminal, while the conversation scrolls above them. While generating, the spinner replaces the input line and its label shows **which phase** the round is in: connecting → queued (waiting for the first token) → thinking → calling a tool → waiting for the tool to return → streaming; the two tool phases include the tool name. The generation rate shows a live value while streaming (2-second sliding window, estimated from output deltas) and switches to this round's average once it finishes (preferring the real `completion_tokens` from the API).
 
-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; `Ctrl+W` / `Alt+Backspace` delete the previous word, `Alt+D` / `Ctrl+Delete` the next word; `Ctrl+K` kills to end of line; `Ctrl+U` kills to line start; `PgUp`/`PgDn` (or `Alt+V`/`Ctrl+V`) scroll the transcript, the mouse wheel scrolls by line; on macOS `⌘← →` moves by word, `⌘⌫`/`⌘⌦` deletes by word, `⌘[`/`⌘]` pages and `⌘;`/`⌘'` scrolls by line (depending on whether the terminal reports Cmd — see below)., 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.
+
+### Keyboard & terminal compatibility (macOS, etc.)
+
+The convention for terminal TUIs on macOS is **Option-as-Meta plus readline-style Ctrl keys**: `Cmd` is not part of the terminal protocol (`super` is only reported under the [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)), so `⌘` is left to the terminal itself (copy / paste / search). This CLI follows that convention.
+
+**Step one: make Option act as Meta.** macOS terminals do not send the Option modifier by default — until you enable it, every `Option+X` shortcut does nothing:
+
+| Terminal | Setting |
+|---|---|
+| Apple Terminal | Settings → Profiles → Keyboard → check **Use Option as Meta Key** |
+| iTerm2 | Settings → Profiles → Keys → General → Left/Right Option key = `Esc+` |
+| VS Code / Cursor | add `"terminal.integrated.macOptionIsMeta": true` to settings |
+| Ghostty / kitty / WezTerm | enable Option-as-Alt / Option-as-Meta in the config |
+
+Key map (aligned with [Claude Code](https://docs.claude.com/en/docs/claude-code/interactive-mode)):
+
+| Keys | Action |
+|---|---|
+| `Enter` | Send |
+| `Ctrl+J`, `Ctrl+Enter`, `Alt+Enter`, `Shift+Enter` | Newline |
+| `Ctrl+C` | While generating: interrupt; when idle: clear the draft, press again to exit |
+| `Ctrl+D` | With a draft: delete the character after the cursor; empty input: press twice to exit |
+| `Esc` | While generating: interrupt; otherwise clear the draft and jump to the bottom |
+| `Ctrl+A` / `Ctrl+E` | Line start / end |
+| `Ctrl+P` / `Ctrl+N` | Previous / next history entry (also moves the slash menu) |
+| `Ctrl+K` / `Ctrl+U` | Kill to line end / line start |
+| `Ctrl+W` | Kill back to the previous whitespace (punctuation does not split: `src/utils/foo.ts` goes in one press) |
+| `Alt+B` / `Alt+F` | Move by word |
+| `Alt+D`, `Alt+Backspace`, `Ctrl+Delete` | Delete by word |
+| `Ctrl+Y` / `Alt+Y` | Yank the last killed text / cycle older entries |
+| `Ctrl+_` | Undo the last input edit |
+| `Ctrl+S` | Stash the draft / press again to restore |
+| `Ctrl+V` | Reserved for image paste (**not implemented yet**; shows a notice) |
+| `Ctrl+L` | Clear the screen (context kept) |
+| `PgUp` / `PgDn` | Page through the transcript |
+| Mouse wheel | Scroll by line (3 lines per notch). With mouse reporting on, text selection needs `Shift` (native terminal selection); `tmux` users need `set -g mouse off`, otherwise the wheel is swallowed by copy-mode |
+| `Shift+↑ ↓`, `Alt+↑ ↓`, `⌘;` / `⌘'`* | Scroll by line |
+| `\` + `Enter` | Newline (works in any terminal) |
+
+> After an interrupt (`Ctrl+C` / `Esc`), **the reasoning and content the model already produced stay in the context** — on the next turn it picks up that half-finished sentence instead of pretending it never said it. Use `/new` if you want a clean slate. Tool rounds are still reconciled all-in or all-out: unfinished tools get a reason backfilled, so no illegal "call without result" history is left behind.
+
+Not implemented (no counterpart here): `Ctrl+O` transcript viewer, `Ctrl+R` reverse search, `Ctrl+B` background tasks, `Ctrl+T` task list, `Shift+Tab` permission modes.
+
+`Ctrl+V` (Claude Code's "paste image") is **not implemented yet** — pressing it shows a notice. It first needs a proper "file → content block" capability probe (Files API upload vs base64 inline) instead of hard-coding a single endpoint. Note that macOS maps `⌘⌫` to `Ctrl+U`, which is why `Ctrl+U` kills to line start here; use `Esc` to clear the draft.
+
+\* `⌘` combos only carry the `super` bit when the terminal **enables the kitty keyboard protocol** (and for iTerm2, when Cmd is mapped to Super). Terminals without it (e.g. Apple Terminal) can only map `⌘` to `ESC` sequences (e.g. `⌘←` → `ESC[1;9D`, equivalent to `Alt+←`), or you can use the Alt combos above.
+
+> macOS maps `⌘⌫` to `Ctrl+U` in iTerm2 and Terminal.app, which is why `Ctrl+U` here follows readline semantics (delete to line start): making it "clear everything" would throw away the whole draft whenever a Mac user presses `⌘⌫`.
+
+> On macOS `Ctrl+← →` is usually swallowed by the system: Mission Control binds it to "Move left/right a space". Uncheck it under System Settings → Keyboard → Keyboard Shortcuts → Mission Control.
+
+If a key still does nothing, turn on the key diagnostics and press it once:
+
+```bash
+AIZ_DEBUG_KEYS=1 aiz
+# in another shell
+tail -f /tmp/aiz-key-debug.log
+```
+
+The first line records the terminal environment (`TERM`, `TERM_PROGRAM`, ...); every keypress then appends one line:
+
+```
+key input="d" flags=[meta] raw=true
+key input="" flags=[pageUp] raw=false
+```
+
+- **No new line after pressing** → the key never reached the app (system shortcut / terminal key mapping)
+- **Line present but `flags` unexpected** → the sequence arrived; the matching logic is at fault (paste that line in a report)
+- **`raw=false`** → stdin was not in raw mode, so the terminal interpreted the key itself (e.g. scrolled its scrollback)
 
 ### First-run setup (API Key)
 
@@ -92,6 +161,19 @@ On first launch, if the endpoint bound to the selected model has no API Key yet,
 
 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.
 
+### UI language (Chinese / English)
+
+On first launch the language is detected from the system: `LC_ALL` → `LC_MESSAGES` → `LANG` → the system `Intl` locale, **falling back to English**. The result is stored in `~/.ai-zen/cli/preferences.json`; from then on the stored preference wins, so changing the system language will not make the UI drift. `/lang` toggles at any time (no argument flips between the two), and `/lang zh` / `/lang en` select one directly.
+
+The preference lives in the CLI's own `preferences.json`, **not in the shared `config.json`** — the latter is the config contract shared by the CLI and the Desktop app.
+
+The whole TUI is covered (chat screen, commands and `/help`, every configuration-center screen, the handoff picker, the splash / boot-error screens), plus the terminal output of `ai --help` and `ai hook install / uninstall`. **Deliberately not translated:**
+
+- **pipe mode (`ai "prompt"` / piped input) prints and errors in English only** — it is meant for scripts and should not follow a human user's UI language;
+- the working-directory note injected into the model's history: English plus a `[system-injected: …]` marker saying it was not typed by the user. This is the only piece of protocol content left untranslated (the `task` parameter description of a new Sub-agent does follow the UI language);
+- the three code-block markers `ai hook` writes into `~/.bashrc` (`# === ai hook … ===`) — translating them would lose track of the old block;
+- the conversation-id stamp `chat_YYYY_MM_DD_HH_mm_ss` — it doubles as the file name, so following the UI language would interleave old and new files.
+
 ### 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:
@@ -105,34 +187,39 @@ While in a conversation, all commands start with `/`. Typing `/` lists the avail
 
 | Command | Description |
 |---------|-------------|
-| `/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) |
+| `/exit` `/quit` | Exit the conversation (offers to save) |
+| `/save` | Save the conversation (already flushed every turn) |
+| `/load` | Load a conversation (replaces this one) |
 | `/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 |
+| `/back` | Retract a message (roll back to a point and resend) |
+| `/editor` | Compose a long message in your editor (vim/nano) |
 | `/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) |
-| `/help` | Show available commands |
+| `/config` | Open the configuration center (endpoints / models / image models / MCP / agent definitions / defaults / tool-output cap) |
+| `/model` | Switch model (writes the Agent's `modelId`; thinking level resets to the model default) |
+| `/agent` | Switch the main Agent (writes `defaultAgent` and rebuilds the session; unusable Agents are marked with the reason) |
+| `/reload` | Refresh the runtime (rediscovers tools / MCP; messages and context are kept) |
+| `/mcp` | Manage MCP servers (add / remove / edit / toggle; `/mcp global` and `/mcp project` pick a scope) |
+| `/lang` | Switch the interface language (`/lang zh`, `/lang en` set it explicitly; no argument toggles) |
+| `/think` `/effort` | Switch reasoning effort (`/think default` follows the model default) |
+| `/key` | Set the endpoint API key (rebuilds the session on save) |
+| `/handoff` | Write a handoff document (keeps the session) |
+| `/migrate` | Hand off and start a new session |
+| `/help` | Show help |
 
-### 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 `tokenThresholds.handoff`, 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:
@@ -149,7 +236,11 @@ ai hook install
 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.
+The hook calls **`ai --tui --new "$@"`**: it opens the interactive UI and **auto-sends the mistyped command as the first message**. A hook fires when a human at an interactive prompt typed something wrong, so it should open the TUI (you can follow up, and there is history) rather than dump a paragraph to stdout and exit. `--new` additionally makes each hook session a **fresh conversation**, instead of appending the mistyped command to whatever you had been doing in that directory. If you installed an older hook, re-running `ai hook install` upgrades it in place — the installed function body is compared with the current one and overwritten when it differs; you can also `ai hook uninstall` first.
+
+`--tui` is usable by hand too: `ai --tui explain this error` opens the TUI and sends it. In a non-TTY environment (a script or a pipe) it fails with an error instead of degrading to pipe mode — otherwise the whole full-screen UI would be written into the pipe.
+
+`--new` works on its own as well: `ai --new` starts a fresh conversation instead of resuming the last one in this directory. It only affects the TUI path; in stdio mode it is ignored (a stdio run is always a one-off session).
 
 ## Configuration
 
@@ -162,7 +253,7 @@ Configuration is stored in `~/.ai-zen/config.json` (or `$AI_ZEN_DIR/config.json`
 | 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).
+The `tokenThresholds` field on each model sets two usage lines: `handoff` (soft — a handoff is triggered above it) and `guard` (hard — the round is aborted above it, before the request). Both are absolute values; `guard ≈ handoff × 1.5` is recommended (typically ~25% of the model's actual context window for `handoff`, e.g. 250,000 for a 1M-token model).
 
 ```jsonc
 {
@@ -180,7 +271,8 @@ The `maxContextTokens` field on each model sets the migration threshold (typical
       "name": "GPT-6.1 Sol",
       "endpointId": "openai",
       "modelName": "gpt-6.1-sol",
-      "maxContextTokens": 250000,
+      "tokenThresholds": { "handoff": 250000, "guard": 375000 },
+      "reasoningPreset": "openai",
       "custom": true
     }
   ],
@@ -193,7 +285,6 @@ The `maxContextTokens` field on each model sets the migration threshold (typical
       "defaultSize": "1024x1024"
     }
   ],
-  "defaultModel": "deepseek-flash",
   "defaultImageModel": "cogview-4",
   "defaultAgent": "default",
   "defaultMigrationModel": "deepseek-flash"
@@ -201,10 +292,14 @@ The `maxContextTokens` field on each model sets the migration threshold (typical
 ```
 
 > 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.
+>
+> The model is **not** selected in `config.json`: each Agent binds one in its own definition file (`agents/<id>.json`, field `modelId`), which is the single source of truth at runtime. `/model` writes exactly that field.
 
 ### 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/`.
+- `AIZ_DEBUG_KEYS=1` — Enables key diagnostics logging (off by default, zero overhead); `AIZ_KEYS_FILE=<path>` overrides the target file (default `/tmp/aiz-key-debug.log`).
+- `AIZ_DEBUG_SDK=0` — Disables SDK global logging. **On by default**: everything is written to `$AI_ZEN_DIR/logs/sdk.log` (no library logs ever reach the screen), rotated to `sdk.log.1` once the file passes 2MB; `AIZ_SDK_LOG_FILE=<path>` overrides the location. Check this file when debugging "MCP won't connect" or "Skill failed to parse".
 
 ## Filesystem Layout
 
@@ -213,7 +308,8 @@ The `maxContextTokens` field on each model sets the migration threshold (typical
 ├── config.json               ← Endpoints & models (shared with other AI-Zen clients)
 ├── cli/                      ← CLI runtime data
 │   ├── conversations/        ← CLI conversations
-│   └── last-session.json     ← Pointer to the last session id
+│   ├── last-session.json     ← Pointer to the last session id
+│   └── preferences.json      ← CLI-local preferences (interface language, etc.)
 ├── agents/                   ← Agent definitions (shared)
 │   ├── default.json          ← Default agent (created on first run)
 │   └── my-custom-agent.json
@@ -226,7 +322,8 @@ The `maxContextTokens` field on each model sets the migration threshold (typical
 ├── tools/                    ← User-defined tools (shared)
 │   └── my-tool.js
 ├── mcp.json                  ← MCP config (shared)
-└── mcp-oauth/                ← MCP OAuth tokens (shared)
+├── mcp-oauth/                ← MCP OAuth tokens (shared)
+└── logs/                     ← Diagnostics (sdk.log: SDK global log, 2MB rotation)
 
 /path/to/project/
 ├── .mcp.json                 ← Project-shared MCP config (committable)
@@ -262,25 +359,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 +396,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,81 @@ ai --version
 ╚═╝  ╚═╝╚═╝    ╚══════╝╚══════╝╚═╝  ╚═══╝
 
               终端里的 AI 协作台
-              v1.0.0-alpha.2 · sdk x · core y
+              v1.0.0-alpha.21 · sdk x · core y
 ```
 
-启动界面结束后**直接进入对话界面**（若存在「上一轮会话」则自动续接，否则新建对话）。对话界面采用**底部固定**布局：分隔线、输入行与状态栏（模型 · Agent · token 用量 · 生成状态）始终贴在终端底部，对话内容在其上方滚动；生成中时输入行位置显示进度指示。
+启动界面结束后**直接进入对话界面**（若存在「上一轮会话」则自动续接，否则新建对话）。对话界面采用**底部固定**布局：分隔线、输入行与**状态栏**（按优先级分三块：模型 · Agent · 思考强度 ｜ 本轮 / 累计 token 用量 · 生成速率 ｜ 快捷键提示；窄屏时放不下的块整块顺延到下一行，既不截断内容也不劈开单块）始终贴在终端底部，对话内容在其上方滚动；生成中时输入行位置显示**分阶段进度**（连接中 → 排队中（等待首 token）→ 思考中 → 调用工具 → 等待工具返回 → 输出中，工具阶段带上工具名）。生成速率在生成中显示实时值（最近 2 秒滑动窗口，按输出增量估算），一轮结束后换成这一轮的平均值（优先用 API 返回的真实 `completion_tokens`）。
 
-对话界面包含：流式输出区（思考过程 / 回答正文 / 工具调用分行展示）、多行输入（`Enter` 发送、`Ctrl+N` 换行、`← →` 移动光标、`Ctrl+← →` 跨词）与内联 `/` 命令菜单（↑↓ 选择、`Tab` 补全）。工具调用以 `⚙ 名称(参数)` 展示并带 **JSON 语法高亮**，正文与思考里的**围栏代码块按语言高亮**（高亮数据来自 `highlight.js` / `lowlight`）。`Ctrl+C` 在生成中取消本轮请求、空闲时退出。
+对话界面包含：流式输出区（思考过程 / 回答正文 / 工具调用分行展示）、多行输入（`Enter` 发送、`Ctrl+N` 换行、`← →` 移动光标、`Ctrl+← →` 跨词、`Ctrl+W` / `Alt+Backspace` 删前一个词、`Alt+D` / `Ctrl+Delete` 删后一个词、`Ctrl+K` 删到行尾、`Ctrl+U` 删到行首、`PgUp`/`PgDn`（或 `Alt+V`/`Ctrl+V`）翻页、鼠标滚轮按行滚动；macOS 上另支持 `⌘← →` 跨词、`⌘⌫`/`⌘⌦` 按词删除、`⌘[`/`⌘]` 翻页、`⌘;`/`⌘'` 按行滚动（取决于终端是否上报 Cmd，见下））与内联 `/` 命令菜单（↑↓ 选择、`Tab` 补全）。工具调用以 `⚙ 名称(参数)` 展示并带 **JSON 语法高亮**，正文与思考按 **Markdown 源码着色**（标题 / 粗体 / 斜体 / 行内代码 / 列表 / 引用 / 链接），**围栏代码块按语言高亮并保留围栏标记**（高亮数据来自 `highlight.js` / `lowlight`）。`Ctrl+C` 在生成中取消本轮请求、空闲时退出。
+
+### 键盘与终端兼容（macOS 等）
+
+macOS 上终端 TUI 的通行做法是 **Option 当 Meta + readline 系 Ctrl 键**：`Cmd` 不在终端协议里（`super` 只有 kitty 键盘协议才会上报，见 [kitty keyboard protocol](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)），因此 `⌘` 主要留给终端自身（复制 / 粘贴 / 搜索）。本 CLI 的键位与这条路线一致。
+
+**第一步：把 Option 设为 Meta**。macOS 终端默认不发送 Option 修饰位，不设则所有 `Option+X` 全部无效：
+
+| 终端 | 设置 |
+|------|------|
+| Apple Terminal | 设置 → 描述文件 → 键盘 → 勾选「**将 Option 用作 Meta 键**」 |
+| iTerm2 | Settings → Profiles → Keys → General → Left/Right Option key 设为 `Esc+` |
+| VS Code / Cursor | settings 里加 `"terminal.integrated.macOptionIsMeta": true` |
+| Ghostty / kitty / WezTerm | 配置文件中启用 Option-as-Alt / Option-as-Meta |
+
+键位一览（与 [Claude Code](https://docs.claude.com/en/docs/claude-code/interactive-mode) 对齐）：
+
+| 键位 | 作用 |
+|------|------|
+| `Enter` | 发送 |
+| `Ctrl+J`、`Ctrl+Enter`、`Alt+Enter`、`Shift+Enter` | 换行 |
+| `Ctrl+C` | 生成中：中断本轮；空闲：有草稿先清空，再按退出 |
+| `Ctrl+D` | 有草稿：删光标后一个字符；空输入：连按两次退出 |
+| `Esc` | 生成中：中断；否则清空草稿并回到底部 |
+| `Ctrl+A` / `Ctrl+E` | 行首 / 行尾 |
+| `Ctrl+P` / `Ctrl+N` | 历史上一条 / 下一条（也用于斜杠菜单选择） |
+| `Ctrl+K` / `Ctrl+U` | 删到行尾 / 删到行首 |
+| `Ctrl+W` | 删到前一空白（标点不切分：`src/utils/foo.ts` 一次删完） |
+| `Alt+B` / `Alt+F` | 跨词移动 |
+| `Alt+D`、`Alt+Backspace`、`Ctrl+Delete` | 按词删除（标点算分隔） |
+| `Ctrl+Y` / `Alt+Y` | 取回刚删掉的文本 / 循环取回更早的 |
+| `Ctrl+_` | 撤销上一次输入编辑 |
+| `Ctrl+S` | 暂存当前草稿 / 再按恢复 |
+| `Ctrl+V` | 预留：粘贴图片（**暂未实现**，按下会提示） |
+| `Ctrl+L` | 清屏（保留上下文） |
+| `PgUp` / `PgDn` | 应用内翻页回看 |
+| 鼠标滚轮 | 按行滚动（每格 3 行）。开启鼠标上报后拖选复制需按住 `Shift`（终端原生选择）；`tmux` 用户需 `set -g mouse off`，否则滚轮会先被 copy-mode 拦下 |
+| `Shift+↑ ↓`、`Alt+↑ ↓`、`⌘;` / `⌘'`* | 按行滚动 |
+| `\` + `Enter` | 换行（任何终端可用） |
+
+> 中断（`Ctrl+C` / `Esc`）后，模型**已经输出的思考与内容会保留在上下文里** —— 下一轮它会接着这半句话往下说，而不是当作自己没说过。想要彻底重置，用 `/new` 开新会话。工具调用轮次仍按「整轮进出」归一：没跑完的工具会补上中断原因，不会留下「有调用无结果」的非法历史。
+
+未实现（我们的场景没有对应物）：`Ctrl+O` 转录查看器、`Ctrl+R` 反向历史搜索、`Ctrl+B` 后台任务、`Ctrl+T` 任务清单、`Shift+Tab` 权限模式。
+
+`Ctrl+V`（Claude Code 的「粘贴图片」）**暂未实现**：按下会提示未支持。原因是它需要先解决「文件 → 内容块」的端点能力探测（Files API 上传 vs base64内联），不能简单硬编码某个端点。⌘⌫ 已被终端映射为 `Ctrl+U`，所以这里删到行首；要清空草稿用 `Esc`。
+
+\* `⌘` 组合只有终端**启用 kitty 键盘协议**时才会带上 `super` 位（iTerm2 还需把 Cmd 映射为 Super）；不支持的终端（如 Apple Terminal）只能在终端里把 `⌘` 映射成 `ESC` 序列（如 `⌘←` → `ESC[1;9D`，等价于 `Alt+←`），或直接用上表的 Alt 组合。
+
+> macOS 的 `⌘⌫` 会被 iTerm2 / Terminal.app 映射为 `Ctrl+U`，因此本 CLI 的 `Ctrl+U` 取 readline 语义「删到行首」——若做成「清空全部」，Mac 用户按 `⌘⌫` 会丢掉整个草稿。
+
+> `Ctrl+← →` 无效通常是系统原因：macOS 默认把它绑定给「调度中心 → 向左/向右移动一个空间」，按键在到达终端前就被截走。可在「系统设置 → 键盘 → 键盘快捷键 → 调度中心」取消勾选。
+
+若某个键仍然没反应，打开**按键诊断**再按一次：
+
+```bash
+AIZ_DEBUG_KEYS=1 aiz
+# 另开一个窗口
+tail -f /tmp/aiz-key-debug.log
+```
+
+首行记录终端环境（`TERM` / `TERM_PROGRAM` 等），之后每次按键一行：
+
+```
+key input="d" flags=[meta] raw=true
+key input="" flags=[pageUp] raw=false
+```
+
+- **按了键却没有新行** → 键被系统 / 终端截走（改系统快捷键或终端键位映射）
+- **有行但 `flags` 与预期不符** → 序列已到达应用，是匹配逻辑问题（反馈时贴这一行）
+- **`raw=false`** → stdin 不在 raw mode，按键被终端自己解释（例如去滚 scrollback）
 
 ### 首次配置（API Key）
 
@@ -92,6 +161,19 @@ ai --version
 
 每个会话都会在对话过程中**直接落盘为独立文件**（`cli/conversations/<id>.json`），不再有单独的草稿存储。一个指针文件（`cli/last-session.json`）记录**上一轮会话 id**；下次启动 `ai` 会**自动续接该会话**，接着上次继续。
 
+### 界面语言（中文 / English）
+
+首次启动按系统语言自动识别：`LC_ALL` → `LC_MESSAGES` → `LANG` → 系统 `Intl` locale，**识别不出来兑底英文**。识别结果写进 `~/.ai-zen/cli/preferences.json`，之后以偏好为准 —— 改了系统语言不会让界面语言漂移。`/lang` 可随时切换（无参在两者间切换），`/lang zh` / `/lang en` 直接指定。
+
+偏好存在 CLI 独立的 `preferences.json` 里，**不写共享的 `config.json`** —— 后者是 CLI 与 Desktop 共用的配置契约。
+
+覆盖范围：整套 TUI（主对话框、命令与 `/help`、配置中心全部屏幕、交接方式选择器、启动屏与启动错误屏），以及 `ai --help` 与 `ai hook install / uninstall` 的终端输出。**以下刻意不翻**：
+
+- **管道模式（`ai "提示词"` / 管道输入）的输出与报错一律英文** —— 它是给脚本用的，不应随人的界面语言变；
+- 注入给模型的工作目录提示：英文 + `[system-injected: …]` 标记（标明不是用户敲的）。这是唯一不翻的协议内容（新建 Sub-agent 的 `task` 参数描述仍随界面语言）；
+- `ai hook` 写进 `~/.bashrc` 的三个代码块标记串（`# === ai hook … ===`） —— 翻了就找不到旧块；
+- 会话 id 时间戳 `chat_YYYY_MM_DD_HH_mm_ss` —— 它同时是文件名，跟着语言变会让历史文件与新文件混排。
+
 ### 对话命令
 
 对话中输入的所有命令以 `/` 开头。输入 `/` 会在输入行下方实时列出可用命令及说明，继续输入即按前缀收敛候选：
@@ -105,34 +187,39 @@ ai --version
 
 | 命令 | 说明 |
 |------|------|
-| `/exit` `/quit` | 退出对话 |
-| `/save` | 保存当前对话（会话本就每轮实时落盘） |
-| `/load` | 加载已保存的对话（替换当前会话） |
+| `/exit` `/quit` | 退出对话（提示保存） |
+| `/save` | 保存对话（本就每轮实时落盘） |
+| `/load` | 加载对话（替换当前会话） |
 | `/new` | 重置会话（清空历史） |
-| `/back` | 撤回消息（回退到指定位置并可编辑后重发） |
-| `/editor` | 使用系统编辑器（vim/nano）输入长消息 |
+| `/back` | 撤回上一条（回退到指定位置并可编辑重发） |
+| `/editor` | 用外部编辑器（vim/nano）写长消息 |
 | `/clear` | 清屏 |
-| `/config` | 打开配置中心（端点 / 模型 / 图片模型 / MCP 服务器 / Agent 定义 / 默认项 / 工具上限） |
-| `/key` | 设置当前端点的 API Key（保存后自动重建会话） |
-| `/migrate` | 手动任务迁移（生成交接文档并开启新会话） |
-| `/help` | 显示可用命令 |
+| `/config` | 打开配置中心（端点 / 模型 / 图片模型 / MCP / Agent 定义 / 默认项 / 工具上限） |
+| `/model` | 切换模型（写入 Agent 的 `modelId`，思考强度重置为模型默认） |
+| `/agent` | 切换主 Agent（写入 `defaultAgent` 并重建会话；跑不起来的标为不可用并给出原因） |
+| `/reload` | 刷新运行环境（重新发现工具 / MCP；消息与上下文保留） |
+| `/mcp` | 管理 MCP 服务器（增删改 / 启停；`/mcp global`、`/mcp project` 指定作用域） |
+| `/lang` | 切换界面语言（`/lang zh`、`/lang en` 直指定，不带参数则切换） |
+| `/think` `/effort` | 切换思考强度（`/think default` 跟随模型默认） |
+| `/key` | 设置端点 API Key（保存后重建会话） |
+| `/handoff` | 生成交接文档（不切换会话） |
+| `/migrate` | 交接并开启新会话 |
+| `/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` 超过模型的 `tokenThresholds.handoff`，交互式终端会弹出三选一选择器（自交接 / 独立摘要 / 跳过）；管道等非交互场景按默认执行者迁移，不阻塞。
 
+文档模板不在代码里：来自 `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 处理：
@@ -149,7 +236,11 @@ ai hook install
 ai hook uninstall
 ```
 
-钩子函数体调用的是 `ai "$@"`（纯 stdio 模式），答案就地写入当前 shell 会话。若此前安装过旧版 `aiz` 钩子，重新执行 `ai hook install` 会自动升级；也可先 `ai hook uninstall` 再安装。
+钩子函数体调用的是 **`ai --tui --new "$@"`**：进入交互界面，并把摸错的命令**作为首条消息自动发给模型**。钩子的发起场景是「人坐在交互终端前敲错了命令」，所以它应该进 TUI（可以追问、有历史），而不是落到管道模式吐一段字就退出；`--new` 进一步保证钩子会话**总是新开一条对话**，不会把敲错的命令追加进该目录原有的长对话里。已装过旧版钩子的话，重新执行 `ai hook install` 会原地升级（会比较已安装的函数体与当前版本，不一致就覆盖）；也可先 `ai hook uninstall` 再安装。
+
+`--tui` 也可以手动用：`ai --tui 帮我看看这个报错` 会直接进 TUI 并发送。它在非 TTY 环境（如写进脚本或管道里）会报错退出而不是降级成管道模式 —— 否则整屏界面内容会被写进管道。
+
+`--new` 也可以单独用：`ai --new` 直接开新一条对话，不续接该目录的上一轮会话。它只对 TUI 生效，stdio 模式下会被忽略（一次 stdio 调用本就是一次性会话）。
 
 ## 配置管理
 
@@ -162,7 +253,7 @@ ai hook uninstall
 | 端点 / 模型 / 图片模型、MCP 服务器、Agent 定义（含 Sub-agent）、默认项、工具输出上限 | 对话内 `/config`（配置中心，全面管理） |
 | 其它高级项（Skill / 用户工具等） | 手动编辑 `~/.ai-zen/` 下的文件 |
 
-其中 `maxContextTokens` 是迁移触发阈值（通常设为模型实际上下文窗口的约 25%，例如 1M tokens 的模型设为 250,000）。
+其中 `tokenThresholds` 是两条用量线：`handoff`（交接软线，超过它触发任务交接）与 `guard`（强行阻断硬线，请求前超过它中断本轮）。两者都是绝对值，建议 `guard ≈ handoff × 1.5`（`handoff` 通常设为模型实际上下文窗口的约 25%，例如 1M tokens 的模型设为 250,000）。
 
 ```jsonc
 {
@@ -180,7 +271,8 @@ ai hook uninstall
       "name": "GPT-6.1 Sol",
       "endpointId": "openai",
       "modelName": "gpt-6.1-sol",
-      "maxContextTokens": 250000,
+      "tokenThresholds": { "handoff": 250000, "guard": 375000 },
+      "reasoningPreset": "openai",
       "custom": true
     }
   ],
@@ -193,7 +285,6 @@ ai hook uninstall
       "defaultSize": "1024x1024"
     }
   ],
-  "defaultModel": "deepseek-flash",
   "defaultImageModel": "cogview-4",
   "defaultAgent": "default",
   "defaultMigrationModel": "deepseek-flash"
@@ -201,10 +292,14 @@ ai hook uninstall
 ```
 
 > 说明：`models` / `imageModels` 中**未标 `custom: true`** 的条目属于**出厂托管**——每次启动会与 SDK 出厂清单对齐、被替换为最新定义；自建模型请加 `"custom": true`。`endpoints` 始终保留用户配置，不受影响。
+>
+> 模型**不在 `config.json` 里指定**：每个 Agent 在自己的定义文件（`agents/<id>.json`）的 `modelId` 字段上绑定模型，这是运行期的唯一真相源；`/model` 切换写的也是它。
 
 ### 环境变量
 
 - `AI_ZEN_DIR` — 覆盖共享根目录（默认 `~/.ai-zen`）。CLI 运行时数据在 `$AI_ZEN_DIR/cli/`，共享资源（agents、skills、tools、MCP 等）在 `$AI_ZEN_DIR/`。
+- `AIZ_DEBUG_KEYS=1` — 开启按键诊断日志（默认关闭，零开销）；`AIZ_KEYS_FILE=<路径>` 可改落盘位置（默认 `/tmp/aiz-key-debug.log`）。
+- `AIZ_DEBUG_SDK=0` — 关闭 SDK 全局日志。**默认开启**，一律写入 `$AI_ZEN_DIR/logs/sdk.log`（界面上不显示任何库日志），单文件 2MB 封顶后轮转为 `sdk.log.1`；`AIZ_SDK_LOG_FILE=<路径>` 可改落盘位置。排查「MCP 连不上」「Skill 解析失败」时看这个文件。
 
 ## 文件系统布局
 
@@ -213,7 +308,8 @@ ai hook uninstall
 ├── config.json               ← 端点与模型配置（与其他 AI-Zen 客户端共享）
 ├── cli/                      ← CLI 运行时数据
 │   ├── conversations/        ← CLI 对话记录
-│   └── last-session.json     ← 「上一轮会话 id」指针
+│   ├── last-session.json     ← 「上一轮会话 id」指针
+│   └── preferences.json      ← CLI 本地偏好（界面语言等）
 ├── agents/                   ← Agent 定义（共享）
 │   ├── default.json          ← 默认 Agent（首次运行自动创建）
 │   └── my-custom-agent.json
@@ -226,7 +322,8 @@ ai hook uninstall
 ├── tools/                    ← 用户自定义工具（共享）
 │   └── my-tool.js
 ├── mcp.json                  ← MCP 配置（共享）
-└── mcp-oauth/                ← MCP OAuth 令牌（共享）
+├── mcp-oauth/                ← MCP OAuth 令牌（共享）
+└── logs/                     ← 诊断日志（sdk.log：SDK 全局日志，2MB 轮转）
 
 /path/to/project/
 ├── .mcp.json                 ← 项目共享 MCP 配置（可提交 git）
@@ -262,25 +359,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 +396,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;AAwBnD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAOxC;AAED,wBAAsB,QAAQ,IAAI,OAAO,CAAC,KAAK,CAAC,CAS/C;AAuCD;;;;;GAKG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAWhD;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,CAmBhF"}