> ## 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.

# 結果信封（schema 1）

> 每個 Extension.js 指令在 --output json 下印出的 schema-1 JSON 信封，以及公開的 schema、錯誤碼表與 golden 固件。

每個指令解析一份 JSON 文件，而不是去刮取記錄行。

在 `--output json` 之下，每個會結束的指令都會在 stdout 上剛好回一個 schema-1 信封。長時間執行的指令則以 [生命週期影格](/docs/contracts/lifecycle-stream) 的形式串流出同樣的結構。

## 信封結構

| 欄位          | 型別            | 意義                                     |
| ----------- | ------------- | -------------------------------------- |
| `schema`    | `1`           | 信封版本。只做增量變更時這個數字不變。                    |
| `ok`        | boolean       | 指令是否成功。                                |
| `command`   | string        | 產生這個結果的指令。                             |
| `status`    | string        | 簡短的機器狀態，例如 `ready`、`usage` 或 `failed`。 |
| `value`     | any 或 null    | 指令的負載。失敗時也可能帶著負載，`doctor` 就是促成這個設計的案例。 |
| `error`     | object 或 null | 當 `ok` 為 false 時出現，見下文。                |
| `warnings`  | string\[]     | 非致命的提示。                                |
| `truncated` | boolean       | 選用。當負載因為超出大小上限而被截斷時設定。                 |
| `hint`      | string        | 選用。下一步的建議。                             |

`error` 物件：

| 欄位        | 型別     | 意義                                                            |
| --------- | ------ | ------------------------------------------------------------- |
| `code`    | string | 來自 [錯誤碼表](/docs/contracts/error-codes) 的穩定 `E_*` 識別碼。請比對這個欄位。 |
| `message` | string | 自由文案，隨時可能被改寫。永遠不要拿它來比對。                                       |
| `name`    | string | 選用。原始錯誤類別的名稱。                                                 |
| `engine`  | string | 選用。發生失敗的瀏覽器引擎。                                                |
| `hint`    | string | 選用。修復建議文案。                                                    |
| `refs`    | object | 選用。message 中提到的可操作部分：`flag`、`command`、`path`、`version`。       |

## 成功與失敗範例

```json theme={null}
{
  "schema": 1,
  "ok": true,
  "command": "capabilities",
  "status": "ok",
  "value": {
    "name": "extension",
    "version": "4.1.3",
    "envelopeSchema": 1,
    "readySchemaVersion": 2,
    "outputJsonCommands": [
      "build",
      "capabilities",
      "create",
      "dev",
      "doctor",
      "eval",
      "inspect",
      "install",
      "logs",
      "open",
      "preview",
      "publish",
      "reload",
      "start",
      "storage",
      "telemetry",
      "uninstall"
    ]
  },
  "error": null,
  "warnings": []
}
```

```json theme={null}
{
  "schema": 1,
  "ok": false,
  "command": "eval",
  "status": "failed",
  "value": null,
  "error": {
    "code": "E_TARGET_NOT_FOUND",
    "message": "No tab matched the requested target.",
    "hint": "List targets with `extension inspect --list-tabs`."
  },
  "warnings": []
}
```

## 給人看的文案去哪了

`EXTENSION_OUTPUT` 環境變數是機器模式的開關。當它是 `json` 或 `ndjson` 時，影格獨佔 stdout，給人看的文案讓路：

* 資訊性輸出與警告會安靜下來，或在串流需要時改走 stderr。
* 錯誤文案永遠不會被抑制。它一律寫到 stderr，所以啟動失敗仍然看得見，而 stdout 保持可解析。

把 stdout 接給你的解析器，把 stderr 留給人。兩者永不混在一起。

## 公開的契約產物

`extension-develop` 套件透過 `./contract/*` export，把契約當成可匯入的檔案一併發佈：

| 產物                                                | 這是什麼                                                                                     |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `extension-develop/contract/envelope.schema.json` | 信封的 JSON Schema。它的 `$id` 是 `https://extension.js.org/contract/envelope-1.json`。          |
| `extension-develop/contract/codes.json`           | 長期穩定的錯誤碼表，附帶 `folded` 與 `legacy` 對應。                                                     |
| `extension-develop/contract/golden.*.json`        | golden 固件，每個指令、每種狀態各一份，例如 `golden.dev.ready.json` 與 `golden.eval.target-not-found.json`。 |

請用這份 schema 驗證你的消費端，並把測試釘在 golden 固件上。錯誤碼只會新增，永遠不會被改名或移除。

## 後續步驟

* 用 [錯誤碼表](/docs/contracts/error-codes) 針對失敗做分支處理。
* 用 [生命週期串流](/docs/contracts/lifecycle-stream) 追蹤長時間執行的工作階段。