> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Doctor 命令：诊断 dev 会话

> 用 Extension.js 的 doctor 命令诊断一个正在运行的 dev 会话。按顺序检查就绪契约、控制通道、令牌、执行器与浏览器。

当一个 dev 会话（或与它通信的自动化 verb）不工作时，用 `doctor` 找出原因。

`doctor` 按依赖顺序逐一检查 dev 会话的控制通道各环节——从磁盘上的就绪契约一直到对扩展内执行器的实时探测——并指出**第一个失败的环节**和具体修复方法，而不是让你面对每条命令各自的死胡同报错。

## 何时使用 `doctor`

* `extension logs` 或某个 act verb 连不上，你想知道是哪个环节断了。
* agent 或脚本通过 `ready.json` 驱动会话，需要一个机器可读的健康检查。
* dev 会话看起来还活着，但扩展不再响应。

## 用法

<CodeGroup>
  ```bash npm theme={null}
  extension doctor [project-path] [options]
  ```

  ```bash pnpm theme={null}
  extension doctor [project-path] [options]
  ```

  ```bash yarn theme={null}
  extension doctor [project-path] [options]
  ```

  ```bash bun theme={null}
  extension doctor [project-path] [options]
  ```

  ```bash deno theme={null}
  extension doctor [project-path] [options]
  ```
</CodeGroup>

省略路径时,Extension.js 诊断当前工作目录对应的会话。

## 参数与 flag

| flag                      | 作用                                            | 默认值             |
| ------------------------- | --------------------------------------------- | --------------- |
| `[project-path]`          | 扩展项目根目录路径。                                    | `process.cwd()` |
| `--browser <browser>`     | 诊断哪个会话（`chrome`、`chromium`、`edge`、`firefox`）。 | `chromium`      |
| `--output <pretty\|json>` | 输出格式（`json` 为 agent 输出原始检查结果）。                | `pretty`        |

## 检查内容

检查按依赖顺序运行。当某个环节失败时，依赖它的后续检查会标记为 **skip**，并注明是被哪个检查阻塞的——skip 不等于通过。

| # | 检查                | 验证内容                                                             |
| - | ----------------- | ---------------------------------------------------------------- |
| 1 | `ready-contract`  | `dist/extension-js/<browser>/ready.json` 存在且 `status: "ready"`。  |
| 2 | `server-process`  | 契约里的 dev 服务器 `pid` 仍然存活（pid 已死意味着契约是陈旧的）。                        |
| 3 | `port-agreement`  | 持久化的控制端口与实时契约的 `controlPort` 一致（不一致会让缓存的 service worker 卡在旧端口上）。 |
| 4 | `control-channel` | 控制服务器在契约端口上接受此 `instanceId` 的连接。                                 |
| 5 | `eval-token`      | 会话以 `--allow-eval` 运行时，会话令牌可从项目根目录读取。                            |
| 6 | `executor`        | 一次实时探测能在扩展的 background 上下文中往返。                                   |
| 7 | `browser`         | 已启动的浏览器没有在 dev 服务器仍在运行时意外退出。                                     |

pretty 输出每个检查打印一行，并附上第一个失败检查的修复建议。全部通过时退出码为 `0`，任一检查失败时为 `1`，CI 和脚本可以直接据此把关。

## 机器可读输出

`--output json` 把检查结果打印为一个 JSON 数组，每个检查一个对象：

```json theme={null}
[
  {
    "check": "ready-contract",
    "status": "pass",
    "detail": "status ready — controlPort 43021, instanceId a1b2c3"
  },
  {
    "check": "server-process",
    "status": "fail",
    "detail": "dev-server pid 4242 is dead — ready.json is stale",
    "remediation": "A previous dev session died uncleanly; restart it: extension dev --browser=chromium --allow-control"
  }
]
```

`status` 为 `pass`、`fail` 或 `skip`；有已知修复方法的失败会带 `remediation`。

## 典型流程

1. 启动会话：`extension dev --browser=chromium --allow-control`（需要 eval verb 时加 `--allow-eval`）。
2. 后续命令连不上时，在同一项目根目录运行 `extension doctor`。
3. 按第一个失败检查给出的修复建议处理，然后再次运行 `doctor` 确认。

## 下一步

* 在 [`dev`](/docs/commands/dev) 中了解 `doctor` 的起点——就绪契约。
* 通过 [调试](/docs/debugging) 从健康的会话中流式读取扩展日志。
* 在 [全局 flag](/docs/workflows/global-flags) 中查看共享 flag。