# 模型可见工具面契约（生成物） > 由 `scripts/gen-tool-contract-md.cjs`（经 tsx 运行 `src-ui/scripts/gen-tool-contract-md.ts`） > 从 `buildToolRegistry` 出厂行表装配产物生成 — 勿手改；工具面变更后重新生成并同 commit。 > 本文档不含时间戳：字节稳定是 `--check` 构建守护的前提。 可见工具 19 个（域折叠形态 + 常驻件）；隐藏旧名 107 个（附录）。 装配说明：标准注册表 = composition 行表出厂序；**引擎侧工具面不在这里**——图谱引擎 （`hologram-engine serve`）的可见面由引擎自己决定（契约 v5 = 域 + action 折叠，见 `docs/agents/engine-plugin-contract.md`），接进兰台后以 `mcp__hologram__*` 形态出现， 其真源 = 引擎 Rust 侧 `DOMAIN_SPECS`。 范围说明：会话级 capability 工具（Skill / enter_exit_plan_mode / 通信族等）经 blueprint 在会话装配期追加，不在本文档（其契约由 convergence phase 快照钉住）；本文档覆盖 buildToolRegistry 装配产物，与 tool-schemas.full.json 同范围。 ## 可见面总览 | 工具 | 只读 | 动作数 | 说明（首行） | |------|------|--------|--------------| | [`web_search`](#web_search) | ✓ | — | Search the internet for real-time information. Uses a free anonymous search API first; if it fails, automatically falls back to Bing/DuckDuckGo scraping. No API key required. | | [`ask_user`](#ask_user) | ✓ | — | Ask the user one or more questions when you need clarification or confirmation before proceeding. Use when the request is ambiguous, you need to choose between approaches, or you need approval for a destructive action. Supports: single question (question/header/options/multiSelect), multiple questions in one call (questions array — recommended for 2+, asked one at a time), and open-ended questions (omit options — the user types a free-text answer). Returns the user's answer(s). | | [`wait`](#wait) | ✓ | — | Block until a target completes, then return immediately — event-driven, NOT a fixed sleep. Pass agentId to wait for that sub-agent to finish: returns its final status the moment it completes (no polling loops, no guessing durations). For background shell jobs use bash_wait (dedicated tool). Omit agentId and pass durationMs ONLY as a fallback for non-event waits (watcher re-analysis, file appearance). Max 10 minutes per call. | | [`show_asset`](#show_asset) | ✓ | — | Create a visual asset block in the conversation (chart/table/metric/graph/html...) rendered as a component. Use for any deliverable that benefits from spatial layout or needs to be referred/updated later (charts, tables, impact graphs, metric dashboards, SVG/HTML cards). The block enters the chat flow and can be pinned to the canvas by the user. Kinds and their payload schemas are listed by list_block_kinds; presentation selects the visual form within the kind white-list (omit for the default). Check list_block_kinds before your first call. | | [`update_asset`](#update_asset) | ✓ | — | Update an existing asset block in-place by assetId (payload/presentation replace; the block id and pin position keep unchanged — pinned copies update live). Rules: kind is NOT changeable (changing semantics means creating a new asset with show_asset); presentation is changeable (skin swap, within the same kind white-list). Errors name what went wrong and what to do instead. | | [`list_block_kinds`](#list_block_kinds) | ✓ | — | List all available asset block kinds with their payload JSON Schema, presentation white-lists, and streaming mode. Call before show_asset to learn what you can generate and how the payload must be shaped; the list reflects the live registry (plugin-contributed kinds appear automatically). | | [`office`](#office) | — | 12 | Read, edit, and produce Office files (.docx / .xlsx / .pptx) through OfficeCLI — the same engine as the `officecli` command line, but with typed actions and no quoting on your side. | | [`composition`](#composition) | — | 7 | Read and author agent compositions (presets). A preset is a named patch layered on the factory composition: it enables/disables registered rows, replaces or inserts prompt sections, and caps seams. Use composition(list) to see presets and available row ids, composition(validate) to check a patch before writing it, composition(write) to save a user preset under the composition directory, and composition(delete) to remove one. A preset affects only sessions that select it; an existing session keeps the composition it started with. | | [`fs`](#fs) | — | 9 | File-system operations: read / write / edit / list / glob / mkdir / move / rename / delete. Use fs(read) to inspect files, fs(write)/fs(edit) to modify them. Path params accept workspace-root-relative paths (e.g. "src/agent/tool.ts"); fs(list)/fs(glob) may omit the path — omitted = the workspace root. fs(read)/fs(edit) may also omit the path — omitted = the file from your most recent fs(read)/fs(edit) (results end with a [file: ...] line showing where you landed). | | [`shell`](#shell) | — | 4 | Shell execution: run (build/test commands only, bundled bash by default; interpreter:"pwsh" ONLY for Windows-native tasks like registry/ACL/MSI/COM/WMI), plus output / wait / kill for background jobs. Working directory is sticky per agent (a successful cd persists across calls; results end with a [cwd: ...] line). bash_output returns only NEW bytes since your last read — polling watch modes/dev servers is cheap. Do NOT use shell(run) for file search, code search, or git — use fs/search/git instead. | | [`git`](#git) | — | 13 | Git operations: status / diff / log / stage / commit / push / pull / checkout / branch / stash / unstash / discard / init / blame. path may be omitted for every action — omitted = the workspace root. Key semantics: file = one file for diff/discard/blame (omit it on diff = all changes); files = comma-separated list (or "." for all) for stage — commit accepts files too and auto-stages them before committing. | | [`search`](#search) | ✓ | 1 | Search source text across files: content matches, file lists, or match counts. directory may be omitted — omitted = the workspace root. | | [`web`](#web) | ✓ | 1 | Fetch a URL and return readable text (documentation, API responses, raw files). | | [`agent`](#agent) | — | 7 | Sub-agent and inter-agent coordination: spawn / status / kill / message / request / reply / inbox / ack / list / merge / discover / lookup / isolation. 委派：agent(spawn) 阻塞到子 Agent 完成，结果即工具返回；同轮发多个可并行。短任务（<1min）用同步 spawn；长任务或互不依赖的并行用 async=true（立即返回 agentId，完成后 result 消息进 inbox——agent(ack) 确认后 agent(merge) 合并）。异步最多 5 并发，池满先 agent(merge) 清理已完成的。 写类任务必须给每个子 Agent 不重叠的文件范围：fork 模式（worktree 隔离，靠 agent(merge) 合并回来）；读/检查类用 fresh 模式（直接改主工作区）。大任务切细、子 Agent 的 prompt 精简、别自己包揽子任务。 agent(merge) 串行合并已完成的 worktree，冲突存为 diff 由你手动应用；合并不可逆，先确认子 Agent 工作无误。 agent(message) 即发（30 分钟过期）；agent(request) 阻塞等回复（30s 默认、最大 120s）。 agent(discover) 发布发现（architecture/bug/pattern/config），agent(lookup) 查他人发现，最新发现每轮自动注入。 | | [`task`](#task) | — | 5 | Task board: create / get / list / update / stop / board. | | [`browser`](#browser) | — | 39 | Browser control: launch a controlled Chrome/Edge (isolated profile; headless/windowSize/profile/proxy supported), connect to a user-started debug-port browser instance, list/switch isolated account sessions (multi-account), list/attach/switch tabs (new_tab/close_tab), navigate/back/forward/reload, snapshot interactive elements (AX tree preferred, iframe/shadow+accessible-name fallback; ref-based ops), extract page content (text/markdown), inspect/report visual state, read console/network events (paired by requestId) + single request detail + HAR export, manage cookies (list/set/delete), screenshot (fullPage), audit log, and operate (click/hover/type/select/upload/dialog/press with modifiers/scroll/viewport/eval). target="self" = 兰台 webview 只读会话（inspect/report/snapshot/content/console/network/network_detail/network_har/screenshot/status 支持）；省略 target = 已 attach 的外部页面。交互范式：先 snapshot 拿 ref 编号，操作按 ref 引用（不要手写 CSS selector）；操作自带等待与反馈；敏感目标每次单独确认。attach 用 targetId（来自 browser(targets) 的 CDP target id）。connect 连接用户已启动的浏览器实例（端口由用户提供，或先 discover 选择），操作其真实数据；kill 只断开不杀该进程。多账号：browser(launch, profile:"work") 创建独立持久登录态，browser(switch_session,"work") 切换，browser(sessions) 查看；不同 profile 的 cookie/登录态完全隔离。用户没给端口时先 discover 列实例让用户选（进程表查询，用户无需知道端口号）。 | | [`desktop`](#desktop) | — | 18 | Windows desktop control (in-process UIA COM, millisecond-latency): probe process tree + windows with channel routing advice (cdp/uia/vision per window), read a window control tree (interactive-only by default, paginated), find/read controls, and operate them by ref or selector (click/type/select/expand/scroll/keys/activate). Write actions return world-change feedback (title/focus/value/toggle before→after). Permission model: first takeover of a window asks once (then pattern actions flow); sensitive targets and physical input (coordinate clicks/SendKeys/wheel) always ask separately; a global input lease serializes physical injection across agents. desktop(audit) reviews what was done. desktop(screenshot) is high-privacy and asks every time. Self-drawn apps (WeChat/QQ/DingTalk) expose empty trees — use desktop(uia_window_shot) + vision instead. Locator params (hwnd/pid/title) may be omitted on uia_* actions — omitted = the focused window (set by your last explicit locator or uia_activate). | | [`cordis`](#cordis) | — | 6 | Dynamic-plugin runtime (shapes mirror DSH tool-cordis): define an immutable package (plain-JS factory returning { name?, apply(ctx) }; sandboxed — dangerous globals are undefined, contributions via guarded ctx.register), run it (first activation asks user approval), stop (chain-recycle contributions), undefine (delete all packages), inspect_list / inspect_self (source + diagnostics, rebuildable trail). | | [`goal`](#goal) | — | 3 | Long-running session goal (one current goal per session): get / create / update. The goal persists in the session log and keeps working across automatic goal rounds; goal(create) may infer intent from a direct human request (not for single-turn work), goal(get) returns the goal_id and revision that goal(update) requires, and goal(update, update_action=edit\|pause\|resume\|complete\|blocked) drives the lifecycle. complete/blocked are also allowed from the goal's own automatic round (blocked needs the same blocking condition across at least 3 rounds); a paused goal can only be resumed by the human /goal command. | ## 工具明细 ### `web_search` > Search the internet for real-time information. Uses a free anonymous search API first; if it fails, automatically falls back to Bing/DuckDuckGo scraping. No API key required. - 只读：是 | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `query` | ✓ | string | Search keywords | | `maxResults` | — | integer | Number of results to return (default 10, max 10) | ### `ask_user` > Ask the user one or more questions when you need clarification or confirmation before proceeding. Use when the request is ambiguous, you need to choose between approaches, or you need approval for a destructive action. Supports: single question (question/header/options/multiSelect), multiple questions in one call (questions array — recommended for 2+, asked one at a time), and open-ended questions (omit options — the user types a free-text answer). Returns the user's answer(s). - 只读：是 | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `question` | — | string | The question to ask the user (single-question form). For 2+ questions use the questions array instead. | | `header` | — | string | Short label (max 12 chars) shown as a tag, e.g. "Confirm", "Approach", "File" | | `options` | — | array\ | 2-4 predefined choices the user can pick from. Omit for an open-ended question — the user types a free-text answer. | | `multiSelect` | — | boolean | Set to true to allow selecting multiple options (default: false) | | `questions` | — | array\ | Multiple questions in one call (recommended for 2+). Asked one at a time in order; the returned answers array aligns with this array. Each answer is a string (single choice / free text) or an array of strings (multi-select), or null if the user cancelled. | ### `wait` > Block until a target completes, then return immediately — event-driven, NOT a fixed sleep. Pass agentId to wait for that sub-agent to finish: returns its final status the moment it completes (no polling loops, no guessing durations). For background shell jobs use bash_wait (dedicated tool). Omit agentId and pass durationMs ONLY as a fallback for non-event waits (watcher re-analysis, file appearance). Max 10 minutes per call. - 只读：是 | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `agentId` | — | string | Sub-agent ID to wait for (from agent_spawn result or agent_status). Waits until it completes/fails/stops. | | `durationMs` | — | number | Fallback sleep when agentId is omitted (1000 = 1s, max 600000). Prefer agentId/bash_wait. | | `timeoutMs` | — | number | Max wait in ms (default 600000 = 10 min). | ### `show_asset` > Create a visual asset block in the conversation (chart/table/metric/graph/html...) rendered as a component. Use for any deliverable that benefits from spatial layout or needs to be referred/updated later (charts, tables, impact graphs, metric dashboards, SVG/HTML cards). The block enters the chat flow and can be pinned to the canvas by the user. Kinds and their payload schemas are listed by list_block_kinds; presentation selects the visual form within the kind white-list (omit for the default). Check list_block_kinds before your first call. - 只读：是 | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `kind` | ✓ | string | 资产语义 kind（list_block_kinds 可查全量与 schema） | | `presentation` | — | string | 表现形态（kind 白名单内；缺省用默认表现） | | `title` | — | string | 短标题（snake_case 风格，可作下载/引用名） | | `payload` | ✓ | unknown | 资产数据（须为 JSON；纯数据，不含回调） | | `stream` | — | boolean | append 型 kind 可流式构建（终值仍以本调用为准） | ### `update_asset` > Update an existing asset block in-place by assetId (payload/presentation replace; the block id and pin position keep unchanged — pinned copies update live). Rules: kind is NOT changeable (changing semantics means creating a new asset with show_asset); presentation is changeable (skin swap, within the same kind white-list). Errors name what went wrong and what to do instead. - 只读：是 | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `assetId` | ✓ | string | 资产 id（show_asset 返回） | | `presentation` | — | string | 新表现形态（kind 白名单内；缺省保持原表现） | | `payload` | ✓ | unknown | 新资产数据（纯 JSON；整体替换） | ### `list_block_kinds` > List all available asset block kinds with their payload JSON Schema, presentation white-lists, and streaming mode. Call before show_asset to learn what you can generate and how the payload must be shaped; the list reflects the live registry (plugin-contributed kinds appear automatically). - 只读：是 ### `office` > Read, edit, and produce Office files (.docx / .xlsx / .pptx) through OfficeCLI — the same engine as the `officecli` command line, but with typed actions and no quoting on your side. > Actions: view (read text/annotated/outline/stats/issues) · get (element + children) · query (CSS-like selector) · validate (OpenXML schema) · create · set / add / remove (element edits) · batch (≥3 edits in one atomic pass) · merge (fill {{key}} templates) · screenshot (render page/slides to PNG) · playbook (load a per-format build guide: word/academic-paper/pptx/pitch-deck/excel/financial-model/…). > Writes flush to disk immediately, so other tools and the user see fresh bytes at once. > Before producing a deliverable, run the delivery gate: validate → view issues (overflow/format/structure) → scan view text for leftover placeholders — note issues does NOT catch placeholders, missing image alt text, or empty content; and it does catch pptx overflow/off-slide shapes and xlsx formula errors. > Load the `officecli` skill for the full playbook (units, colors, template flow, tracked changes, pitfalls). - 只读：否 - 域：`office` - action 枚举（12）：`view` · `get` · `query` · `validate` · `create` · `set` · `add` · `remove` · `batch` · `merge` · `screenshot` · `playbook` - 只读 action：`view` · `get` · `query` · `validate` · `playbook` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | string（枚举见 action 表/描述） | 动作（读：view/get/query/validate/playbook；写：create/set/add/remove/batch；交付：merge/screenshot） | | `file` | — | string | 目标 Office 文件（.docx/.xlsx/.pptx）。相对路径按工作区根解析。除 playbook 外所有动作必填。 | | `playbook` | — | string（枚举见 action 表/描述） | playbook 动作的专项技能名（逐格式构建指南，正文 25–65 KB）：word/academic-paper/word-form/pptx/pitch-deck/morph-ppt/morph-ppt-3d/excel/financial-model/data-dashboard。一件产物只载一个，别重复载。 | | `path` | — | string | 元素路径（get/set/remove 用）：1-based 本地名路径，如 /body/p[2]、/slide[1]/shape[@id=2]、/Sheet1/A1。 | | `mode` | — | `text` / `annotated` / `outline` / `stats` / `issues` / `html` / `svg` / `forms` | view 的读数模式（缺省 text）：text/annotated/outline/stats/issues/html/svg/forms。 | | `selector` | — | string | query 的 CSS 式选择器，如 paragraph[style=Heading1]、cell[value>5000]。 | | `props` | — | object | set/add 的属性表（值一律字符串，如 {"text":"标题","style":"Heading1"}；单位/颜色写法见 officecli 技能 §8）。 | | `type` | — | string | add 的元素类型：paragraph/run/table/slide/shape/picture/comment/sheet/cell… | | `parent` | — | string | add 的父路径（缺省 /），如 /body、/slide[1]、/Sheet1、/styles。 | | `json` | — | boolean | view/get/query/validate/batch 追加 --json（结构化输出；token 更贵，按需开）。 | | `items` | — | array | batch 的改动项数组（≥3 处改动优先用它：一次开关 + 原子回滚）。 | | `data` | — | object | merge 的数据映射（键 = 模板里的 {{key}}）。 | | `out` | — | string | 输出路径（screenshot 的 PNG / merge 的成品文件）。相对路径按工作区根解析。 | | `page` | — | integer | screenshot 的页号（1-based）。 | | `grid` | — | boolean | screenshot 出整册联系表（--grid auto）而不是单页。 | | `depth` | — | integer | get 的展开深度。 | ### `composition` > Read and author agent compositions (presets). A preset is a named patch layered on the factory composition: it enables/disables registered rows, replaces or inserts prompt sections, and caps seams. Use composition(list) to see presets and available row ids, composition(validate) to check a patch before writing it, composition(write) to save a user preset under the composition directory, and composition(delete) to remove one. A preset affects only sessions that select it; an existing session keeps the composition it started with. - 只读：否 - 域：`composition` - action 枚举（7）：`list` · `read` · `validate` · `write` · `delete` · `rename` · `copy` - 只读 action：`list` · `read` · `validate` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `list` / `read` / `validate` / `write` / `delete` / `rename` / `copy` | Which operation to perform. | | `id` | — | string | Preset id (read/write/delete/rename/copy): lowercase letters, digits and hyphens. | | `newId` | — | string | Target preset id (rename/copy): the new id to create. | | `yaml` | — | string | Patch YAML text (validate/write): the roster.patch.yml body. | | `name` | — | string | Display name written into preset.yml (write). | | `description` | — | string | Display description written into preset.yml (write). | | `overwrite` | — | boolean | write: replace an existing user preset (default false = refuse). | | `rows` | — | boolean | list: include the addressable row ids (tool rows, prompt sections, capabilities, shell rows, seams). | | `filter` | — | string | list(rows): only rows whose id contains this substring. | ### `fs` > File-system operations: read / write / edit / list / glob / mkdir / move / rename / delete. Use fs(read) to inspect files, fs(write)/fs(edit) to modify them. Path params accept workspace-root-relative paths (e.g. "src/agent/tool.ts"); fs(list)/fs(glob) may omit the path — omitted = the workspace root. fs(read)/fs(edit) may also omit the path — omitted = the file from your most recent fs(read)/fs(edit) (results end with a [file: ...] line showing where you landed). - 只读：否 - 域：`fs` - action 枚举（9）：`read` · `write` · `edit` · `list` · `glob` · `mkdir` · `move` · `rename` · `delete` - 只读 action：`read` · `list` · `glob` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `read` / `write` / `edit` / `list` / `glob` / `mkdir` / `move` / `rename` / `delete` | Which operation to perform. | | `path` | — | string | Target path. Relative paths resolve against the workspace root; where the action allows omitting it, omitted = the workspace root. | | `offset` | — | integer | Line number to start reading from (0-indexed, default: 0) | | `limit` | — | integer | Maximum number of lines to return (default: all lines) | | `lineNumbers` | — | boolean | Set to true to prefix each line with a cat -n style line number (6-digit + tab). Default: raw file text — use this for exact string matching. | | `content` | — | string | Full file content to write | | `_forceGate` | — | boolean | Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: write); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: edit); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: move); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: rename); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: delete) | | `oldString` | — | string | The exact text to find and replace (must match the file exactly, including whitespace) | | `newString` | — | string | The text to replace it with (must be different from oldString) | | `replaceAll` | — | boolean | Replace all occurrences instead of just the first (default: false). Use when the old_string appears multiple times. | | `pattern` | — | string | Glob pattern to match file paths against (e.g. "**/*.rs", "src/**/agent*.ts", "*.json") | | `from` | — | string | Source path | | `to` | — | string | Destination path | | `new_name` | — | string | New name (not path, just the name) | ### `shell` > Shell execution: run (build/test commands only, bundled bash by default; interpreter:"pwsh" ONLY for Windows-native tasks like registry/ACL/MSI/COM/WMI), plus output / wait / kill for background jobs. Working directory is sticky per agent (a successful cd persists across calls; results end with a [cwd: ...] line). bash_output returns only NEW bytes since your last read — polling watch modes/dev servers is cheap. Do NOT use shell(run) for file search, code search, or git — use fs/search/git instead. - 只读：否 - 域：`shell` - action 枚举（4）：`run` · `output` · `wait` · `kill` - 只读 action：`output` · `wait` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `run` / `output` / `wait` / `kill` | Which operation to perform. | | `command` | — | string | The shell command to run (e.g. "npm test", "cargo build", "pytest -x") | | `cwd` | — | string | Optional working directory for the command. Defaults to the current workspace root. | | `timeoutMs` | — | integer | Timeout in milliseconds (default: 300000 = 5 min, max: 600000 = 10 min) (action: run); Maximum wait time in milliseconds (default: 60000 = 60s, max: 600000 = 10min) (action: wait) | | `runInBackground` | — | boolean | Set to true to run in background (returns job ID immediately). Use bash_output(id) to check progress, bash_wait(id) to wait for completion, bash_kill(id) to stop. | | `interpreter` | — | `bash` / `pwsh` | Optional interpreter. Default/omit = bundled bash (Unix syntax). Set "pwsh" ONLY for Windows-native tasks bash cannot do (registry queries, ACL, MSI, COM, WMI) — PowerShell syntax required. | | `jobId` | — | integer | The job ID returned by run_shell with runInBackground: true (action: output); The job ID returned by run_shell with runInBackground: true (action: wait); The job ID returned by run_shell with runInBackground: true (action: kill) | ### `git` > Git operations: status / diff / log / stage / commit / push / pull / checkout / branch / stash / unstash / discard / init / blame. path may be omitted for every action — omitted = the workspace root. Key semantics: file = one file for diff/discard/blame (omit it on diff = all changes); files = comma-separated list (or "." for all) for stage — commit accepts files too and auto-stages them before committing. - 只读：否 - 域：`git` - action 枚举（13）：`status` · `diff` · `log` · `stage` · `commit` · `push` · `pull` · `checkout` · `branch` · `stash` · `unstash` · `discard` · `init` - 只读 action：`status` · `diff` · `log` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | string（枚举见 action 表/描述） | Which operation to perform. | | `path` | — | string | Target path. Relative paths resolve against the workspace root; where the action allows omitting it, omitted = the workspace root. | | `file` | — | string | Optional: specific file to diff. If omitted, shows all unstaged changes. (action: diff); File path to discard changes for (relative to repo root) (action: discard) | | `staged` | — | boolean | Set to true to show staged changes instead of unstaged | | `count` | — | integer | Number of recent commits to show (default: 10) | | `files` | — | string | File path(s) to stage, separated by commas. Use "." to stage all. (action: stage); File path(s) to stage before committing, separated by commas (same syntax as git stage). Omit to commit whatever is already staged. (action: commit) | | `message` | — | string | Commit message (conventional commits format recommended) (action: commit); Optional stash message for identification (action: stash) | | `_forceGate` | — | boolean | Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: commit); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: checkout); Bypass the architecture gate for HIGH-risk writes. Set to true only after confirming safety via trace_impact. (action: discard) | | `branch` | — | string | Branch name to switch to (action: checkout); New branch name (action: branch) | ### `search` > Search source text across files: content matches, file lists, or match counts. directory may be omitted — omitted = the workspace root. - 只读：是 - 域：`search` - action 枚举（1）：`content` - 只读 action：`content` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `content` | Which operation to perform. | | `path` | — | string | Target path. Relative paths resolve against the workspace root; where the action allows omitting it, omitted = the workspace root. | | `pattern` | — | string | Text or regex pattern to search for (case-insensitive) | | `fileTypes` | — | string | Optional comma-separated file extensions to filter (e.g. ".ts,.py,.rs") | | `maxResults` | — | integer | Maximum number of results to return (default: 50, max: 200) | | `useRegex` | — | boolean | Set to true to interpret pattern as a regex (e.g. "function\\s+\\w+"). Default: false (literal substring) | | `contextLines` | — | integer | Number of context lines before and after each match (like grep -C). Default: 0. Max: 10. | | `outputMode` | — | `content` / `files_with_matches` / `count` | Output mode: "content" = matching lines with context, "files_with_matches" = just file paths, "count" = match counts per file. Default: content. | | `showLineNumbers` | — | boolean | Include line numbers in output (default: true) | | `headLimit` | — | integer | Max results/files to return (default: 250, 0 = unlimited) | | `offset` | — | integer | Skip first N results for pagination (default: 0) | | `globFilter` | — | string | Additional glob filter on file paths (e.g. "**/*.rs", "src/**/*.ts") | ### `web` > Fetch a URL and return readable text (documentation, API responses, raw files). - 只读：是 - 域：`web` - action 枚举（1）：`fetch` - 只读 action：`fetch` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `fetch` | Which operation to perform. | | `url` | — | string | The URL to fetch (HTTPS or HTTP only) | ### `agent` > Sub-agent and inter-agent coordination: spawn / status / kill / message / request / reply / inbox / ack / list / merge / discover / lookup / isolation. 委派：agent(spawn) 阻塞到子 Agent 完成，结果即工具返回；同轮发多个可并行。短任务（<1min）用同步 spawn；长任务或互不依赖的并行用 async=true（立即返回 agentId，完成后 result 消息进 inbox——agent(ack) 确认后 agent(merge) 合并）。异步最多 5 并发，池满先 agent(merge) 清理已完成的。 写类任务必须给每个子 Agent 不重叠的文件范围：fork 模式（worktree 隔离，靠 agent(merge) 合并回来）；读/检查类用 fresh 模式（直接改主工作区）。大任务切细、子 Agent 的 prompt 精简、别自己包揽子任务。 agent(merge) 串行合并已完成的 worktree，冲突存为 diff 由你手动应用；合并不可逆，先确认子 Agent 工作无误。 agent(message) 即发（30 分钟过期）；agent(request) 阻塞等回复（30s 默认、最大 120s）。 agent(discover) 发布发现（architecture/bug/pattern/config），agent(lookup) 查他人发现，最新发现每轮自动注入。 - 只读：否 - 域：`agent` - action 枚举（7）：`spawn` · `status` · `isolate_create` · `isolate_diff` · `isolate_merge` · `isolate_discard` · `isolate_status` - 只读 action：`status` · `isolate_diff` · `isolate_status` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `spawn` / `status` / `isolate_create` / `isolate_diff` / `isolate_merge` / `isolate_discard` / `isolate_status` | Which operation to perform. | | `description` | — | string | Short label for the sub-agent task (3-5 words, used in progress display) | | `prompt` | — | string | Complete, self-contained task directive for the sub-agent. Must include: what to do, which files to modify, and the expected outcome. Do NOT instruct the sub-agent to run builds or tests — it cannot do so (parallel build tools cause file-lock deadlocks). Verification is the parent agent's responsibility after all sub-agents finish. When spawning multiple sub-agents in parallel, give each a distinct, non-overlapping set of files to avoid write conflicts. | | `subagent_type` | — | `fresh` / `fork` | Omit to fork (inherits your recent context — DEFAULT). Set to "fresh" for a clean-slate sub-agent. | | `tool_allowlist` | — | array\ | Optional list of tool names the sub-agent is allowed to use. If omitted, all tools are available. Example: ["read_file", "search_content", "inspect_symbol"] for a read-only research agent. | | `timeout_minutes` | — | number | Optional timeout override (default 30 minutes). The sub-agent is aborted when it exceeds this. | | `async` | — | boolean | If true, returns immediately with the sub-agent ID. The sub-agent runs in the background; its result arrives via agent_message (type: "result"). If false (default), blocks until the sub-agent finishes. Use agent_merge to merge completed async sub-agents. | | `output_schema` | — | object | Optional JSON Schema (object-rooted) the sub-agent result must satisfy. Supported keywords: type/properties/required/additionalProperties/items/enum/const/oneOf. Only valid in blocking mode (async=false). The validated JSON object is returned as the tool result. | | `agent_id` | — | string | Identifier for this isolation workspace (action: isolate_create); Isolation workspace to diff (action: isolate_diff); Isolation workspace to merge (action: isolate_merge); Isolation workspace to discard (action: isolate_discard) | ### `task` > Task board: create / get / list / update / stop / board. - 只读：否 - 域：`task` - action 枚举（5）：`create` · `get` · `list` · `update` · `stop` - 只读 action：`get` · `list` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | `create` / `get` / `list` / `update` / `stop` | Which operation to perform. | | `title` | — | string | Short task title (3-8 words) (action: create); New title (optional) (action: update) | | `detail` | — | string | What needs to be done, in one sentence (action: create); Updated detail text (optional) (action: update) | | `id` | — | integer | Task ID to fetch (action: get); Task ID to update (action: update); Task ID to stop (action: stop) | | `status` | — | `pending` / `in_progress` / `completed` / `cancelled` | Optional status filter. Omit to list all. (action: list); New status for the task (action: update) | ### `browser` > Browser control: launch a controlled Chrome/Edge (isolated profile; headless/windowSize/profile/proxy supported), connect to a user-started debug-port browser instance, list/switch isolated account sessions (multi-account), list/attach/switch tabs (new_tab/close_tab), navigate/back/forward/reload, snapshot interactive elements (AX tree preferred, iframe/shadow+accessible-name fallback; ref-based ops), extract page content (text/markdown), inspect/report visual state, read console/network events (paired by requestId) + single request detail + HAR export, manage cookies (list/set/delete), screenshot (fullPage), audit log, and operate (click/hover/type/select/upload/dialog/press with modifiers/scroll/viewport/eval). target="self" = 兰台 webview 只读会话（inspect/report/snapshot/content/console/network/network_detail/network_har/screenshot/status 支持）；省略 target = 已 attach 的外部页面。交互范式：先 snapshot 拿 ref 编号，操作按 ref 引用（不要手写 CSS selector）；操作自带等待与反馈；敏感目标每次单独确认。attach 用 targetId（来自 browser(targets) 的 CDP target id）。connect 连接用户已启动的浏览器实例（端口由用户提供，或先 discover 选择），操作其真实数据；kill 只断开不杀该进程。多账号：browser(launch, profile:"work") 创建独立持久登录态，browser(switch_session,"work") 切换，browser(sessions) 查看；不同 profile 的 cookie/登录态完全隔离。用户没给端口时先 discover 列实例让用户选（进程表查询，用户无需知道端口号）。 - 只读：否 - 域：`browser` - action 枚举（39）：`launch` · `connect` · `discover` · `kill` · `sessions` · `switch_session` · `cookies` · `targets` · `attach` · `new_tab` · `close_tab` · `navigate` · `back` · `forward` · `reload` · `snapshot` · `content` · `inspect` · `report` · `console` · `network` · `network_detail` · `network_har` · `screenshot` · `audit` · `click` · `hover` · `type` · `select` · `upload` · `dialog` · `press` · `scroll` · `viewport` · `eval` · `status` · `wait` · `fill` · `navigate_snapshot` - 只读 action：`discover` · `sessions` · `targets` · `snapshot` · `content` · `inspect` · `report` · `console` · `network` · `network_detail` · `network_har` · `screenshot` · `audit` · `status` · `wait` | 参数 | 必选 | 类型 | 说明 | |------|------|------|------| | `action` | ✓ | string（枚举见 action 表/描述） | Which operation to perform. | | `url` | — | string | Optional URL to open in the controlled browser (action: launch); set/delete: cookie URL (either url or domain is required) (action: cookies); URL to open in the new tab (default about:blank) (action: new_tab); URL to navigate to (action: navigate); URL to navigate to (action: navigate_snapshot) | | `port` | — | integer | Debug port (default: auto-probe from 9223; 9222 is reserved for 兰台 webview) (action: launch); Debug port of the running browser instance (e.g. 9223) (action: connect) | | `headless` | — | boolean | Run Chrome without a visible window (default false) | | `windowSize` | — | object | Launch window size (--window-size=width,height) | | `profile` | — | string | Named persistent account profile/session slot (e.g. "work"); omit for temporary default profile | | `proxy` | — | string | Chrome --proxy-server value (e.g. "socks5://127.0.0.1:1080") | | `proxyBypass` | — | string | Chrome --proxy-bypass-list value (e.g. "localhost;127.0.0.1") | | `session` | — | string | Optional account slot name to register this instance under (default: default) (action: connect); Account session slot name to activate (action: switch_session) | | `op` | — | `list` / `set` / `delete` | Cookie operation | | `urls` | — | array\ | list: only return cookies for these URLs (default all cookies in this browser context) | | `name` | — | string | set/delete: cookie name | | `value` | — | string | set: cookie value (action: cookies); Option value (preferred) or visible option text (action: select) | | `domain` | — | string | set/delete: cookie domain (either url or domain is required) | | `path` | — | string | set/delete: cookie path (default /) | | `httpOnly` | — | boolean | set: HttpOnly flag | | `secure` | — | boolean | set: Secure flag | | `sameSite` | — | `Strict` / `Lax` / `None` | set: SameSite restriction | | `expires` | — | number | set: expiration time in Unix seconds (default session cookie) | | `targetId` | — | string | CDP target id from browser(targets) — not "self" (action: attach); CDP target id of the tab to close (action: close_tab) | | `scope` | — | string | Optional CSS selector to limit the snapshot (default: whole page) (action: snapshot); Optional CSS selector to limit extraction (default: whole page) (action: content); Optional CSS selector to limit the scan (default: whole page) (action: report) | | `maxResults` | — | integer | Max elements per page (default 80) (action: snapshot); Max elements (default 20) (action: inspect); Max elements in the snapshot (default 80) (action: navigate_snapshot) | | `offset` | — | integer | Skip this many interactive elements (for paging; default 0) (action: snapshot); Skip this many content characters (for paging; default 0) (action: content) | | `target` | — | string | "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: snapshot); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: content); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: inspect); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: report); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: console); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: network); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: network_detail); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: network_har); "self" = 兰台 webview（只读）；省略 = 已 attach 的外部页面 (action: screenshot) | | `format` | — | `text` / `markdown` | Output format: text (default) or markdown | | `maxChars` | — | integer | Max content characters per page (default 8000) | | `selector` | — | string | CSS selector (or ref number from snapshot) of element(s) to inspect (action: inspect); Ref number from snapshot or CSS selector of element to click (action: click); Ref number from snapshot or CSS selector of element to hover (action: hover); Ref number from snapshot or CSS selector of input/textarea/contenteditable to focus (action: type); Ref number from snapshot or CSS selector of the