# @inobit/pi-instabox

[English](./README.md) | **中文**

在 Pi 会话里驱动 instabox 沙箱：九个 `instabox_desktop_*` 桌面工具，每次调用都明说自己打到哪台箱；另有一个绑定单台箱的远端 `chrome-devtools-mcp` server，**默认开启**，要关闭就用 `--no-instabox-devtools` / `devTools: "off"` / `/instabox-devtools off`。

- **每次调用都点名箱**：可选的 `box` 参数（或五级目标解析链）决定哪台沙箱执行，且每条成功结果首行固定为 `[box=<name>]`
- **不静默降级**：箱名写错或有歧义就是错误并列出候选；唯一会降级的是失效的 `defaultBox`（每会话一条 warning）
- **schema 来自远端**：工具定义由目标箱的 `tools/list` 生成并按箱缓存，加载期的工具声明不需要 ssh
- **不碰你的工具选择集**：桌面工具是 `exposure: "deferred"`——可从 codemode 脚本调用，但不声明给模型、也不列进 codemode 描述——扩展从不调用 `setActiveTools`

## 环境要求

- **`@earendil-works/pi-coding-agent >= 0.99.0`**——硬门槛。本包依赖的 `exposure`、`namespace`、`registerMcpServer` 与 codemode/MCP 支持自 0.99.0 起才有，更早的宿主无法加载。
- Node.js **>= 24**。
- `PATH` 上有 `instabox` CLI（`instabox version`、`instabox ls --json`、`instabox ssh`、`instabox wake|start|resume`、`instabox exec`）。没有 CLI 时扩展零注册——无工具、无命令、无 MCP server、不写运行期文件（无模板缓存）——只每会话给一条 warning；唯一的落盘产物是事件日志里那一条 `cli.probe`。若只是首次 `instabox version` 探测超时，会在会话启动时用更大预算重试一次再下这个结论。
- 沙箱模板带 `instabox-computer-use`（本扩展通过 `instabox ssh <box> -- instabox-computer-use mcp` 驱动这个远端 MCP server）。

## 安装

```bash
pi install npm:@inobit/pi-instabox
```

重启 Pi 会话生效。

## 用法

**桌面工具。** 目标箱远端 `tools/list` 的每个条目变成一个 pi 工具，名为 `instabox_desktop_<远端名>`（本包面向的 `instabox-computer-use` 是九个，如 `instabox_desktop_click`），label 为 `instabox desktop <远端名>`，统一挂在 `instabox-desktop` 命名空间（别名 `instabox_desktop`）下，`exposure: "deferred"`：已注册、可从 codemode 脚本调用，但不声明给模型、也不列进 codemode 描述，因此不占那 3000 token 预算。脚本经命名空间找到它们——`describeNamespace("instabox-desktop")` 取整组，`searchTools("instabox")` 在同一份文本上做 BM25 检索（命名空间的 description 与 instructions 都在检索文本里，所以只搜命名空间名就能命中这一组）——再按名字调用（`tools.instabox_desktop_click({ … })`）。

每个工具都有一个可选 `box` 参数。不传时按下面的顺序解析目标，先命中先停：

1. 本次调用的 `box` 参数；
2. 当前分支里最后一条 user 消息提到的唯一箱名；
3. 会话目标（由 `/instabox-use` 设置）；
4. 配置里的 `defaultBox`；
5. `instabox ls` 返回的第一台。

第 1–3 级都是严格的：写错的名字是硬错误，消息里出现多个箱名是 `ambiguous`——都不猜、也都不退到下一级。只有第 4 级会降级（退到第 5 级，带一条 warning）。每条成功结果首行是 `[box=<name>]`；远端内容（文本与图片）原样透传，远端报错时保留 `isError`，并追加一行说明「未重试、未换箱」及两条补救。

**`/instabox-use [box]`**——设置或查看本会话的目标箱。不带参数时打印当前目标与候选箱；箱名不存在则拒绝，原目标保留。目标以一条自定义会话条目存储（不进 LLM 上下文，按分支生效，因此 `/tree` 切分支与 `--continue` 都能恢复）。若当时还没注册任何桌面工具（冷启动、无缓存），这条命令还会唤醒该箱、拉取 `tools/list` 并注册工具——这就是会话启动时箱子没在跑的重试路径。

**`/instabox-status`**——一次性诊断：配置摘要（`defaultBox`、`devTools`、`devToolsBox`、`autoInstallDevTools`、`remotePath`——那里出现的 `devToolsBox` 只是 DevTools 的默认箱，不是开关）、DevTools 开关及其来源（`instabox-devtools: on (config)` / `on (--instabox-devtools)` / `off (--no-instabox-devtools)` / `off (/instabox-devtools)`）、会话目标、解析出的目标及其来源、已注册的 `instabox_desktop_*` 工具与 exposure（显示为 `deferred`）、当前声明来自哪台箱的缓存模板（`tool declarations: from the cached template of box "…"`）、active tools、codemode 状态，以及扩展注册的 MCP server——`instabox-devtools` 在 DevTools server 注册期间出现在最后这一段（见 [DevTools MCP](#devtools-mcp)）。

**`/instabox-devtools [status|on [box]|off|reset]`**——远端 DevTools MCP server 的运行期开关：不带参数（或 `status`）显示开关及其来源（`on (config)` / `on (--instabox-devtools)` / `off (--no-instabox-devtools)` / `on (INSTABOX_MCP_DEVTOOLS)` / `off (/instabox-devtools)`）、本会话已注册的 server、会话绑定的箱，以及下一次将使用的箱及其来源（`session` / `flag` / `config`）；`on [box]` 在本会话打开该能力并注册或替换 server，给了箱名就同时把它绑到本会话；`off` 在本会话关闭并注销它、但**不清除**该绑定；`reset` 只清会话绑定。细节见 [DevTools MCP](#devtools-mcp)。

**工具声明的来源。**加载期命中缓存就静默注册桌面工具——零 ssh、零提示。否则会话启动在后台替你决定：有缓存时对「声明来源」那台箱做一次版本校验（会话目标 → `defaultBox` → 缓存里最近拉取的那台，均要求该箱有缓存条目）；没有缓存时先 `ls`，取**第一台 `state === "running"`** 的箱，一台 running 都没有时取列表第一台。**连接即唤醒**：无论桌面工具调用还是这个后台同步，建连前都先确保箱子在跑（`instabox wake`、再 `instabox start`、再 `instabox resume`），因此暂停的箱会在后台被唤醒——不显示进度、不阻塞会话——而不是被跳过。成功一律静默：工具出现就是唯一的成功信号。只有真的同步不了才提示：`instabox ls` 为空或失败 → 一条「没有可用沙箱」；同步本身失败 → 一条带 `/instabox-use <box>` 的提示，都是每会话一次。

**codemode 前提。** `deferred` exposure 的含义是:工具已注册、可从 codemode 脚本调用,但永不声明给模型、也永不列进 codemode 描述--deferred 工具被完全排除在那段描述之外,因此不占它那 3000 token 共享预算,工具陆续注册也不会让描述变化。模型仍需知道它们存在,所以扩展在 `before_agent_start` 写一段 system prompt section(tag `instabox-desktop`,只在桌面工具已注册时写):一行 intro 加一行 `- instabox-desktop (codemode): <描述>`,与 pi 写给 MCP 工具的 `mcp_servers` 段同款。那行描述**不是**写死的常量--它按远端数据生成:取远端 `initialize` 的 `instructions` 首行(截断到 250 字符),远端没给时回退到包内命名空间描述--因此远端升版(或任意一次重拉,例如 168 小时 TTL 到期)后,下一次注册(加载期缓存命中、`session_start` 后台同步、`/instabox-use`)就自动换上新描述,不需要改代码。内容只在远端数据变化时变,因此不会每轮产生 system prompt 补丁,也不破坏 prompt 前缀缓存。脚本里用 `describeNamespace("instabox-desktop")` 拿到命名空间与整组的工具名,用 `describeTool(name)` 取单个工具的完整声明(`ALL_TOOLS` 里也带声明),或用 `searchTools("instabox")` 做 BM25 检索。codemode 本身仍须处于激活态--只有脚本才跑得动这些工具--扩展不会替你激活 codemode,且只在**已注册桌面工具**时才判定状态(会话启动一次,`/instabox-status` 每次实时读)。若 codemode 未激活、且会话里没有 `codemode` exposure 的 MCP server,你会收到每会话一条 warning 并附带补救命令:用 `pi --tools +codemode` 启动,或在 settings 里设 `"defaultTools": ["+codemode"]`。若本会话根本没有 `codemode` 工具条目(被 `--tools` / `--exclude-tools` 剔除,或内置扩展被替换),则用另一条一次性文案明说桌面工具在本会话不可调用。配置了 DevTools server 时（默认开启，见 [DevTools MCP](#devtools-mcp)），pi 会自动激活 codemode，因此两条提示都不会出现。两种情况下 `/instabox-use` 与 `/instabox-status` 都可用。

## 配置

可选 `config.json`（全局 `<agentDir>/extensions/pi-instabox/config.json`，或 trusted 时项目 `<cwd>/.pi/extensions/pi-instabox/config.json`）：

```json
{
  "defaultBox": "",
  "devTools": "on",
  "devToolsBox": "",
  "autoInstallDevTools": true,
  "remotePath": "/opt/npm/bin:/usr/local/bin:/usr/bin:/bin",
  "devToolsArgs": [
    "--headless",
    "--userDataDir=/data/home/.agent-chrome",
    "--executablePath=/usr/bin/chromium",
    "--viewport=1280x800",
    "--no-usage-statistics"
  ],
  "timeouts": {
    "prepareMs": 60000,
    "wakeMs": 20000,
    "startMs": 30000,
    "connectMs": 15000,
    "initializeMs": 15000,
    "listToolsMs": 15000,
    "callMs": 120000
  }
}
```

| 键 | 默认值 | 含义 |
| --- | --- | --- |
| `defaultBox` | `""` | 解析链靠后的兜底目标；空串＝未配置（退到 `instabox ls` 第一台） |
| `devTools` | `"on"` | 远端 DevTools MCP 的开关：只认 `"on"` / `"off"`（其它值——包括布尔 `true` / `false`——一律忽略，用下层的值）。`"off"` 时保持关闭，除非 `--instabox-devtools` 或 `/instabox-devtools on` 覆盖。优先级：`--instabox-devtools` / `--no-instabox-devtools` → `INSTABOX_MCP_DEVTOOLS` → 本键 |
| `devToolsBox` | `""` | `chrome-devtools-mcp` 的默认箱；它本身不开启该能力，且 `--instabox-devtools-box` 与会话绑定（`/instabox-devtools on <box>`）都会覆盖它 |
| `autoInstallDevTools` | `true` | 远端缺 `chrome-devtools-mcp` 时尝试一次 `sudo -n env "PATH=<remotePath>" npm i -g chrome-devtools-mcp` |
| `remotePath` | `/opt/npm/bin:/usr/local/bin:/usr/bin:/bin` | 箱内使用的 PATH；默认值覆盖目前已在箱模板上见到的 npm 前缀 |
| `devToolsArgs` | 见上 | 原样透传给 `chrome-devtools-mcp` |
| `timeouts.prepareMs` | `60000` | 一次工具调用准备阶段的截止时间：查状态 → 唤醒链 → 确认 `running` → 建连 |
| `timeouts.wakeMs` | `20000` | `instabox wake` 的单步上限（自动暂停的箱） |
| `timeouts.startMs` | `30000` | `instabox start` / `instabox resume` 的单步上限 |
| `timeouts.connectMs` | `15000` | 从 spawn 到远端 MCP server 吐出第一个字节的单步上限 |
| `timeouts.initializeMs` | `15000` | `initialize` 请求 |
| `timeouts.listToolsMs` | `15000` | `tools/list` 请求 |
| `timeouts.callMs` | `120000` | `tools/call` 请求（含截图的桌面操作）；不在准备预算里 |

`prepareMs` 是截止时间，其余字段只是单步上限：每一步的超时取 `min(单步上限, 剩余预算)`，轮询与退避的等待也按剩余预算收窄，所以一步卡住不会把总时长顶成各步上限之和。预算耗尽时调用报 `prepare timed out after 60000ms (box "<名称>", step: wake|start|resume|confirm|connect)` 并带上该步 `stderr` 尾部，不换箱、不重试。`timeouts.callMs` 从准备阶段之后开始计时，因此不包含在 `prepareMs` 里。

叠加顺序后者覆盖前者：内置默认值 → 全局 `config.json` → 项目 `config.json`（仅 trusted 项目）→ 环境变量。非法值被忽略，即该层保留下一层的值；`timeouts` 逐字段合并，显式写 `"devToolsArgs": []` 表示清空。

环境变量（空串＝未设置）：`INSTABOX_MCP_DEFAULT_BOX`、`INSTABOX_MCP_DEVTOOLS`（`on` / `off`，**只认小写**——开/关 DevTools server）、`INSTABOX_MCP_DEVTOOLS_BOX`、`INSTABOX_MCP_AUTO_INSTALL`（`0` / `1`）、`INSTABOX_MCP_PATH`（远端 PATH）。

## 路径

`<agentDir>` 是 pi 的 agent 目录：默认 `~/.pi/agent`，可用 `PI_CODING_AGENT_DIR` 覆盖（`~` 会展开）。

| 路径 | 内容 |
| --- | --- |
| `<agentDir>/extensions/pi-instabox/config.json` | 配置文件（即上文的全局层） |
| `<agentDir>/pi-instabox/templates.json` | per-box 模板缓存：每台箱的 `tools/list` 加远端 `serverInfo.version` 与 `fetchedAt`。加载期的工具声明只读这个文件（零 ssh、零提示），声明来自哪台箱是**缓存优先**的：会话目标（该箱有缓存条目才算）→ `config.defaultBox`（同上）→ 缓存里最近拉取的那台。**缓存为空时后台不走解析链**：取第一台 `state === "running"` 的箱，一台 running 都没有时取列表第一台；running 的箱不需要唤醒，暂停的箱会先在后台被唤醒（不显示进度）。随后每次会话启动用一次握手校验该箱（暂停时会先唤醒它）：`serverInfo.version` 相同就复用缓存、不动磁盘，不同则重拉 `tools/list` 并重写该箱条目；另有 168 小时 TTL 兜底（超期无论版本是否相同都会重拉），校验失败则静默沿用缓存。比对用的就是这次握手返回的 `serverInfo.version`，无需额外配置 |
| `<agentDir>/logs/pi-instabox/pi-instabox.jsonl` | 事件日志（目录 `0700`、文件 `0600`）：一行一事件，超 1 MiB 轮转为 `.1` … `.3`。**扩展加载时**（配置与路径解析完、CLI 探测前）就开始记，因此探测失败也有记录；可以删。见[日志](#日志) |

## 日志

每个会话从**扩展加载时**起就往 `<agentDir>/logs/pi-instabox/pi-instabox.jsonl` 追加结构化事件（目录 `0700`、文件 `0600`）：先解析配置与路径，随即接上日志，然后才跑 `instabox version` 探测——所以探测失败/超时也有记录；没有 CLI 的会话只有 `cli.probe` 那一条，别的不写。装配失败同样只写日志，不建模板缓存、不建其它运行期文件。

- **格式：**一行一条 JSON —— `{"ts":"2026-11-09T12:00:00.000Z","level":"info","event":"session.start","fields":{…}}`。事件数据在 `fields` 子对象里，不摊平到顶层：`undefined` 字段被丢掉，字符串截断到 2000 字符，键名命中 `token|secret|password|api[-_]?key` 的字段整体写成 `"[redacted]"`。**消息正文与调用参数从不写盘**——事件只带名字、状态、计数与耗时（`box`、`source`、`mentions`、`candidates`、`ms` 等）。
- **级别：**默认 `info`（生命周期 + 每一次工具调用一条 `resolve`，选箱可事后复盘，不需要任何开关）。`PI_INSTABOX_DEBUG=1` 把文件切到 `debug`，额外记池状态采样、spawn 参数、模板缓存命中与 `session_tree` 的目标切换。`warn` / `error` 记录在两个级别下都写，所以「忘了开 debug」不会让失败消失。`off` 只存在于代码层（`createFileLogger({ level: "off" })`），没有对外开关。
- **轮转：**到 1 MiB 就滚动成 `pi-instabox.jsonl.1` … `pi-instabox.jsonl.3`（`.1` 最新）。大小判定在**写入之后**，所以刚滚动完的主文件是空的，下一条事件写入时重新出现。
- **写盘失败不进会话：**建目录或追加失败只经内部 debug 渠道报一次然后吞掉；日志永远不是工具可用的前提。

| 事件 | 级别 | 字段 |
| --- | --- | --- |
| `cli.probe` | info / warn | `ok`、`reason`（`missing` / `timeout` / `error`）、`version`、`ms` |
| `cli.ls` | info | `ok`、`count`、`reason`、`ms` |
| `cli.lifecycle` | info | `command`（`start` / `wake` / `resume`）、`box`、`ok`、`reason`、`ms` |
| `cli.exec` | info | `box`、`timeoutSec`、`ok`、`ms` |
| `load.assembled` | info | `cacheHit`、`box`、`tools`（加载期声明的工具数） |
| `session.start` | info | `target`、`source`（会话启动原因）、`mode` |
| `session.tree` | debug | `target` |
| `session.shutdown` | info | `open`（收掉的连接数） |
| `resolve` | info | `param`、`source`（`param` / `message` / `session` / `config` / `first`）、`box`、`mentions`、`candidates`（前 10 个）、`degraded`（跳过了失效的 `defaultBox`） |
| `resolve.fail` | warn | `kind`（`no-boxes` / `invalid-param` / `invalid-session` / `ambiguous` / `invalid-config`）、`message`、`candidates`（前 10 个） |
| `pool.connect` | info | `box`、`ok`、`ms`、`error` |
| `pool.prepare` | info / warn | `box`、`ok`、`ms`（整个准备阶段）、`step`（`wake` / `start` / `resume` / `confirm` / `connect`；只在预算耗尽时出现）、`timeoutMs`（该步实际拿到的预算） |
| `pool.wake` | info / warn | `box`、`step`（`wake` / `start` / `resume`）、`ok`、`ms`、`timeoutMs`（该步实际拿到的预算） |
| `pool.state` | debug | `box`、`state`、`desiredState` |
| `pool.reuse` | debug | `box` |
| `pool.dispose` | debug | `box` |
| `remote.spawn` | debug | `command`、`args` |
| `remote.initialize` | info | `ok`、`ms`、`protocolVersion`、`serverInfoVersion` |
| `remote.listTools` | info | `ok`、`count`、`ms` |
| `remote.call` | info | `tool`、`ok`、`ms`、`isError` |
| `template.hit` | debug | `box`、`serverInfoVersion`、`stale`（TTL 已过） |
| `template.refetch` | info | `box`、`reason`、`ms`、`tools` |
| `template.fail` | warn | `box`、`error`、`stale`（沿用了缓存模板） |
| `tool.call` | info | `tool`、`box`、`ok`、`ms`、`isError` |
| `codemode` | debug | `state`（`active` / `inactive` / `missing`）、`server`（存在 codemode exposure 的 MCP server） |
| `devtools.register` | info | `box`、`ok` |
| `devtools.enabled` | info | `box`、`source`（`session` / `flag` / `config` / `command`） |
| `devtools.disabled` | info | ——（无字段） |
| `devtools.reset` | info | ——（无字段） |
| `devtools.prepare` | info / warn | `box`、`ok`、`ms`、`error`（`ok` 为 false 时不注册） |
| `devtools.install` | info / warn | `box`、`ok`、`skipped`（`autoInstallDevTools` 关闭） |
| `error` | warn | `where`、`message`（被吞掉的失败：会话分支、`session_start` 后台任务、`ui.notify`） |

**排查一次选错箱。**成功的 `resolve` 是 `info` 级，默认级别下就已经落盘——不用切级别，直接过滤：

```bash
grep '"event":"resolve"' ~/.pi/agent/logs/pi-instabox/pi-instabox.jsonl
```

每条记录说明：五级里哪一级命中（`source`）、命中的是哪台箱（`box`）、本轮 user 消息里出现了哪些箱名（`mentions`——**零命中也记**，而零命中正是「落到下一级」的原因）、当时备选的名字（`candidates`）、是否跳过了失效的 `defaultBox`（`degraded`）。硬失败就在旁边，以 `resolve.fail` 落盘，带 `kind` 与 `candidates`：`box` 参数不存在、会话目标不存在、消息里提到两台箱、或箱列表为空。`PI_INSTABOX_DEBUG=1` 打开的是决策周边的细节（池状态采样、spawn 参数、模板命中），不是决策本身。

## DevTools MCP

远端 `chrome-devtools-mcp` server **默认开启**（`devTools: "on"`）。开关与箱名的入口如下，开关先命中先用：

| 入口 | 含义 |
| --- | --- |
| `--instabox-devtools` | 强制打开该能力（boolean，默认 `false`） |
| `--no-instabox-devtools` | 强制关闭（boolean，默认 `false`）；压过配置里的默认值 |
| `INSTABOX_MCP_DEVTOOLS` | `on` / `off`（只认小写，其它值忽略），位置在 flag 与配置之间 |
| `devTools`（配置） | 开关本身（`"on"` / `"off"`，默认 `"on"`） |
| `--instabox-devtools-box <name>` | 承载该 server 的箱；覆盖 `devToolsBox`、但低于会话绑定（string，默认 `""`） |
| `/instabox-devtools [status\|on [box]\|off\|reset]` | 本会话的运行期覆盖与会话绑定（见下文） |

关闭方式：`--no-instabox-devtools`、`config.json` 里的 `"devTools": "off"`、`INSTABOX_MCP_DEVTOOLS=off`，或在当前会话执行 `/instabox-devtools off`。flag / 环境变量 / 配置 / 命令四个入口用的是同一套词表：开关叫 `devTools`，状态只有 `on` / `off`。

箱子按三级取，先命中先用：`/instabox-devtools on <box>` 写下的**会话绑定**（按分支生效的 session entry，`--continue` 能恢复、`/tree` 切分支会跟着变）→ `--instabox-devtools-box` → `config.devToolsBox`。三者都没配时（且开关开着）**不注册**；由于开关默认开启、这属于后台行为，此时**完全静默**（只有 `PI_INSTABOX_DEBUG=1` 时看得见一行 `[pi-instabox] …` debug）。箱不在 `instabox ls` 里同理：不注册、绝不静默换一台，也不提示——除非你是显式要这个能力（`--instabox-devtools` 或 `/instabox-devtools on`）。开关显式关着却只给 `--instabox-devtools-box`，会有一条 warning 说要加 `--instabox-devtools` 强制开启、什么都不启用；只配 `config.devToolsBox` 则完全静默，因为配置只负责提供默认箱。

开关打开后，扩展先准备箱子，再注册**一条普通的 stdio MCP 配置**，名为 `instabox-devtools`：

```json
{ "command": "instabox", "args": ["ssh", "<box>", "--", "env", "PATH=<remotePath>", "chrome-devtools-mcp", "...devToolsArgs"] }
```

这就是你完全可以自己写进 `mcp.json` 的同一条条目——区别只在于由扩展按需注册/注销。不生成脚本、不落盘、不额外包一层进程。

准备阶段是**注册之前**的普通函数调用（MCP 客户端自己从不唤醒箱，pi 也不会重连失败的 server）：

1. **准备箱子**：直接复用桌面工具那套 `pool.ensureReady()`（只有一份实现、一套语义：箱不存在则失败并列出候选，`running` 直接返回，否则 `wake` → `start` → `resume` 且每步之后轮询 `running`，全程共享 `timeouts.prepareMs` 截止时间）。箱准备不好就**不注册**；只有显式要这个能力（`--instabox-devtools` 或 `/instabox-devtools on`）才给一条 warning 说明原因，默认开启的后台路径只 debug。
2. **查二进制**：`instabox exec <box> --env PATH=<remotePath> --timeout 20 -- sh -c 'command -v chrome-devtools-mcp'`。缺失且 `autoInstallDevTools` 开启时装一次 `sudo -n env "PATH=<remotePath>" npm i -g chrome-devtools-mcp`（60 秒；sudo 会按 `secure_path` 重写 PATH，所以远端 PATH 显式再传一遍）。检查或安装失败只 warn——server 照旧注册，真正的 `command not found` 会在第一次 MCP 调用时原样冒出来。

`devToolsArgs` 原样接在 `chrome-devtools-mcp` 之后；`remotePath` 同时是 `instabox ssh` 载荷与上面那些 `instabox exec` 的 `PATH`。注册本身带 `exposure: "codemode"` 与 180 秒每请求超时（现在它只约束 MCP 请求——准备阶段发生在 server 存在之前）。

**`/instabox-devtools`** 不带参数就是 `status`，打印五行：开关及其来源（`instabox-devtools: on (config)` / `on (--instabox-devtools)` / `off (--no-instabox-devtools)` / `on (INSTABOX_MCP_DEVTOOLS)` / `off (/instabox-devtools)`）、本会话已注册的 server（`registration: <名称> (via <来源>)`，未注册时为 `registration: (none)`；`<来源>` 本命令注册的取 `command`，其余取提供箱名的那一级 `session` / `flag` / `config`）、本会话绑定的箱（`session binding: <名称>` / `session binding: (unset)`）、下一次 `on` 或会话启动将使用的箱及其来源（`effective box: <名称> (<来源>)` / `effective box: (unset)`；三级按 `session` → `flag` → `config` 解析）、候选箱（`candidates: …`）。中间三段分开报是有意的：`reset` 只清会话绑定，所以 `registration` 仍指向那台还在跑的 server，而 `effective box` 已经回退到下一次会用的箱。`on [box]` 在本会话打开该能力并为该箱注册 server（箱名依次取参数、会话绑定、`--instabox-devtools-box`、`devToolsBox`），给了箱名参数时同时把它写成会话绑定；重复执行 `on` 会先注销旧注册再重注，所以拿到的是新连接而不是复用旧连接。箱名不存在则拒绝且保持现状。`off` 在本会话关闭该能力并注销 server：它的工具变成 `exposure: "hidden"`（pi 不支持反注册工具），因此从 codemode 的 `ALL_TOOLS` 与 `searchTools` 里消失，已经发出的调用会报错，但转录里已有的消息不变；之后再 `on` 会建立新连接。`off` **不清除**会话绑定。`reset` 只清会话绑定：下一次 `on`（以及开关开着时的下一次会话启动）回退到 `--instabox-devtools-box` → `config.devToolsBox`，开关状态与已注册的 server 都不动。

它的工具——DOM/无障碍快照、元素截图、CSS 级联、网络、console、性能 trace——不会声明给模型。模型在 codemode 脚本里发现它们：

```js
const ns = describeNamespace("mcp__instabox_devtools"); // { name, tools }
// 或: searchTools("devtools")
```

正因为这个 server 是 `codemode` exposure，它在注册期间会让 pi 自动激活 codemode，这也是同一会话里桌面工具变得可调用的原因。

**首次连接失败时 pi 不会自己重试。**该 MCP server 会一直处于失败状态直到你用 `/mcp` 重连、再执行一次 `/instabox-devtools on <box>`（这是一次全新注册）或重启会话，期间命名空间里拿不到任何工具。这也是扩展在注册**之前**先唤醒箱、先确认二进制的原因：等到那条 stdio 命令真正跑起来时，箱已经 running、二进制也已就位。唤醒不了的箱根本不注册；显式开启时有一条 warning 说明原因，于是开启时就能看到明确信息，而不是面对一个死掉的命名空间；默认开启的后台路径同样只 debug。

## 兼容与限制

- **宿主门槛：**`pi-coding-agent >= 0.99.0`（见环境要求）。本包钉死编译所用类型，升级只会体现为 `check` 失败，而不是运行期意外。
- **工具选择集归你：**扩展从不调用 `setActiveTools`，不写 `settings.json`，也不改 `defaultTools`；它只报告 codemode 状态与补救命令。
- **codemode 未激活＝不可调用：**工具已注册，但 codemode 关掉时模型够不到它们；也没有任何列表会提到它们——模型得先自己搜（`describeNamespace("instabox-desktop")` / `searchTools("instabox")`）才知道名字。见「用法」里的前提说明。
- **工具集跟随模板而非扩展：**定义来自该箱缓存的 `tools/list`。不同箱可能跑不同版本的 `instabox-computer-use`，因此工具集与 schema 可能逐箱不同。校验口径是每次会话启动一次握手：远端版本相同则沿用缓存的工具、不动磁盘，不同则重拉并重写该箱条目，另有 168 小时 TTL 单独触发重拉。工具名稳定（`instabox_desktop_<远端名>`），所以写死了名字的 codemode 脚本跨版本仍可用。
- **默认安静：**后台声明成功不提示——成功路径没有任何通知，工具直接出现。会话启动只有两种提示：`ls` 空/失败的「没有可用沙箱」、同步失败并给出 `/instabox-use <box>`。DevTools 默认开启但**不主动打扰**：箱名缺失、箱不在 `ls` 里、箱唤醒不了、`chrome-devtools-mcp` 安装失败这些情况只写 debug（`PI_INSTABOX_DEBUG=1`）与 JSONL 里的 `warn` 记录；只有显式开启（`--instabox-devtools` 或 `/instabox-devtools on`）才各给一条 warning，开关显式关着却给了 `--instabox-devtools-box` 也提示（这是明确但无法执行的请求，见 [DevTools MCP](#devtools-mcp)）。内部 `[pi-instabox] …` 的 stderr 输出与 JSONL 日志的 `debug` 级记录（见[日志](#日志)）默认关闭，设 `PI_INSTABOX_DEBUG=1` 才能看到唤醒、spawn 参数与握手内部细节；**选箱不需要开关**：每次工具调用都会以 `info` 落一条 `resolve`。
- **全部暂停也会被拉起：**没有 running 的箱时，取 `instabox ls` 第一台在后台唤醒并拉模板——唤醒发生在建连这一步，所以缓存命中但箱已暂停时也会为版本校验把它唤醒；唤醒失败降级为那一条提示，会话不会被阻塞或拖住。
- **桌面截图成本高：**浏览器相关工作优先走 DevTools server（默认开启）；不需要时用 `--no-instabox-devtools` 或 `"devTools": "off"` 关掉。命名空间说明里也对模型传达了同一条。
- **`box` 只作用于桌面工具：**它为 `instabox_desktop_*` 调用选择沙箱。DevTools server 固定绑定一台箱——会话绑定优先，其次 `--instabox-devtools-box`，最后 `devToolsBox`；换箱用 `/instabox-devtools on <box>`（同时更新会话绑定），不需要重新加载扩展；`/instabox-devtools reset` 可以撤掉这条会话绑定。能力本身跟随 `devTools`（默认 `"on"`），直到某个 flag 或 `/instabox-devtools off` 改了它。
- **`off` 会留下旧工具名：**`/instabox-devtools off` 只是把它们隐藏。转录里已经出现过的工具名仍可能被模型尝试，然后以报错告终——连接已关，而 pi 不会因为隐藏而改写历史消息。

## 开发

```bash
pnpm --filter @inobit/pi-instabox check      # tsc --noEmit
pnpm --filter @inobit/pi-instabox test       # vitest
pnpm --filter @inobit/pi-instabox pack:check # tarball 内容
pi -ne -e builtin:codemode -e builtin:mcp -e ./packages/pi-instabox
```

冒烟命令必须把内置扩展带回来：`-ne` / `--no-extensions` 会连同已安装的扩展一起禁用 `codemode` 与 `mcp`，缺了它们桌面工具无法调用、`registerMcpServer` 也会失败。单测全程离线——每处外部边界（`exec`、`spawn`、文件系统、时钟、`Text`）都可注入，因此没有测试会 spawn `instabox`、连箱子或访问网络。

## 许可证

MIT
