JSON Contract zh TW

JSON Contract

English · 繁體中文

給 Shell script、CI job 與 LLM agent 使用的穩定介面。

要 JSON 就得明講

CLI 不會因為輸出被 pipe 就自動改變格式。要機器可讀的輸出必須明確加上 --json：

taiga issue view example-project#42 \
  --json \
  --fields id,ref,subject,status,version \
  --no-input

{
  "data": {
    "id": 123,
    "ref": 42,
    "subject": "Fix token refresh",
    "status": "In progress",
    "version": 7
  },
  "meta": {
    "contract": 1
  }
}

自動化建議一併加上 --no-input，確保任何需要互動的情況都變成明確的錯誤，而不是卡住等待輸入。

三種 envelope

情境	形狀
單筆資料	{ "data": {...}, "meta": {...} }
列表	{ "items": [...], "page": {...}, "meta": {...} }
Dry run	{ "plan": {...}, "meta": {...} }
錯誤	{ "error": { "code", "message", "retryable", ... }, "meta": {...} }

成功資料只寫 stdout，錯誤只寫 stderr，兩者不會混在同一個串流。

欄位挑選

--fields 接受逗號分隔的欄位名稱，只能與 --json 併用。指定了不存在的欄位時，CLI 會回報錯誤並列出 可用欄位，而不是安靜地回傳空值。

Contract 版本

meta.contract 目前是 1。同一個版本內只會新增 optional 欄位；移除欄位、改名或改變既有欄位的 型別，都必須提升 contract 版本並在 release notes 提供遷移說明。

Schema descriptor

taiga schema issue view --json
taiga schema --json

每個指令的 descriptor 包含 input 與 output 的 JSON Schema（draft 2020-12），以及兩個給自動化判斷用的 標註：

• safety：read、write 或 local
• idempotency：idempotent 或 non_idempotent

Agent 可以據此決定一個指令能不能在未經確認的情況下執行。

Exit code

Code	Meaning	意義
0	success	成功
1	unexpected internal failure	未預期的內部錯誤
2	usage / schema	用法或 schema 錯誤
3	authentication	認證失敗
4	forbidden	權限不足
5	not found	找不到目標
6	OCC conflict	樂觀鎖衝突
7	validation / ambiguity	驗證失敗或指涉不明確
8	throttled	被限流
9	transport / upstream	傳輸或上游錯誤
10	confirmation required	需要確認
11	ambiguous commit	提交結果不明
130	interrupted before finishing	在完成前被中斷

11 特別重要：它代表寫入請求可能已經送達 Taiga，但 CLI 無法確認結果。收到這個 code 時應該先查詢 實際狀態，而不是直接重送。

130 採用 shell 慣例的 128 加訊號編號，而不是在上表裡再佔一個號碼，因為停掉一個指令是一個決定，不是指令 失敗的一種方式。它帶的契約代碼是 interrupted，逾時的話則是 timeout。若中斷打斷的是進行中的寫入， 回報的會是 11 而不是這個 —— 因為 client 不聽了並不會讓 Taiga 把寫入收回去。

Dry run

taiga issue edit 42 \
  --subject "New subject" \
  --dry-run \
  --json \
  --no-input

Dry run 會實際連線 Taiga 查詢與解析資料（例如把 status 名稱解析成 ID、驗證 assignee 存在），因此能發現 真正的設定錯誤，但保證不送出任何 POST、PATCH 或 DELETE。輸出包含 would_write: true 與 performed: false。

全域旗標

旗標	用途
--json	輸出版本化的 JSON contract
--fields	挑選 JSON 欄位（需搭配 --json）
--no-input	永不提示輸入，需要互動時直接失敗
--quiet / -q	抑制非必要的人類輸出
--verbose / -v	對 stderr 輸出去識別化的 HTTP 診斷
--no-color	停用顏色（也遵守 NO_COLOR 環境變數）
--profile	指定 profile
--api-url	指定完整的 API base URL
--project / -p	指定專案 slug