official/cli 技能
你是一個透過 CLI 控制 Glyph 伺服器的 AI。本技能是整個 glyph 命令表面的地圖,再加上 --help 無法呈現的慣例 — 最重要的是工作區作用域規範,它能防止你的命令與其他客戶端競爭,以及退出碼/錯誤碼規範,讓你能機械化地根據失敗情況進行分支。
設定
glyph 在啟動你的任務或工作階段時,會將所需資訊注入環境變數:
GLYPH_SERVER— 伺服器 URL(CLI 會自動使用)GLYPH_WORKSPACE— 工作區 UUID(工作區作用域的命令會繼承使用)
快速驗證:
glyph health # 退出碼 0 ⇒ CLI 可運作 + 伺服器可連線
glyph workspace current --json | jq # 確認工作區已解析
命令表面一覽
每個工作區作用域的命令都會繼承 --server / --workspace-id / --output / --json,並遵循下方的共用退出碼表格。子命令群組:
| 群組 | 用途 | 參考文件 |
|---|---|---|
workspace | 建立 / 列出 / 顯示 / 更新 / 移除 / 重新載入工作區;列印目前 ID | references/commands.md#workspace |
session | 管理互動式工作階段(列出 / 新增 / 顯示 / 移除 / 啟動終端機) | references/commands.md#session |
task | 調度一次性任務、列出(可按 --origin 範圍篩選)、檢視任務、追蹤活動、取消、移除 | references/commands.md#task |
schedule | 排程觸發的任務啟動器(建立 / 列出 / 修補 / 啟用 / 停用 / 執行 / 預覽 / 列出任務) | references/commands.md#schedule |
catalog | 安裝 / 同步 / 啟用 / 停用代理程式、技能、MCP | references/commands.md#catalog |
workflow | 種子工作流程、讀取/變更其即時 DAG(展開、透過 update-spec 修補未開始節點的規格)、回應人工節點、終止 | references/commands.md#workflow |
runtime | 列出已註冊的執行環境(copilot 等) | references/commands.md#runtime |
| 伺服器檢查 | health, config, status, logs — 無生命週期管理 | references/commands.md#server-inspection |
| 伺服器生命週期 | serve / start / stop / restart — 不在本技能範圍內 | — |
工作區規範
每個工作區作用域的命令都需要一個明確的選擇器。CLI 會從你的環境變數讀取 GLYPH_WORKSPACE(已經設定),因此命令可以直接執行:
glyph task dispatch --agent writer --brief "..."
若要對不同工作區執行操作,請在命令中傳遞 --workspace-id <id>:
glyph task list --workspace-id ws-Y
CLI 不會查詢任何伺服器端的共用「目前工作區」狀態 — 選擇器是進程本機的,不受其他客戶端(其他 CLI 工作階段、儀表板分頁、同一伺服器上的 AI 代理)干擾。
輸出規範
- 若要解析,請一律使用
--json。 人類/表格格式不是穩定契約 — 欄位順序和標題會在不同版本間變更。 - 若要串流活動,請透過
jq -c管道傳遞,以保持每行一個事件。 - 你可能會用到的每個
--json結構都記錄在references/json-shapes.md中。在編寫jq過濾器前,請先查閱該文件 — 大多數結構都有選擇性欄位(當底層資料列非空時才會出現),你應該以此為判斷依據。
錯誤規範
標準錯誤輸出上的錯誤訊息一律帶有 code:
代理程式 "writer" 尚未就緒:前提條件未確認(HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: 前提條件未確認
fix: glyph catalog agent ack-prereqs acme/writer
fix: 行是你的下一個命令,請照原樣執行。完整的 code 目錄(所有錯誤名稱 + 典型 HTTP 狀態碼 + 修正方式)記錄在 references/error-codes.md 中。特別是:
EntryNotReadyError是你最常會遇到的分支 — 它會攜帶結構化的reason,描述代理程式是需要ack-prereqs、是disabled、有missingDeps,還是有blockedDeps(可遞迴)。原因表格在references/error-codes.md#entrynotreadyerror-reasons。
退出碼
| 退出碼 | 意義 | 應對方式 |
|---|---|---|
| 0 | 成功 | 繼續 |
| 1 | 一般錯誤(包含缺少工作區) | 讀取標準錯誤輸出;通常是缺少旗標/環境變數 |
| 2 | 使用錯誤(缺少必要旗標、已移除的子命令) | 修正調用方式;不要原樣重試 |
| 3 | 伺服器無法連線 | 請使用者執行 glyph start 或檢查 --server |
| 4 | 伺服器回傳 4xx/5xx | 讀取標準錯誤輸出中的 code;查閱 references/error-codes.md |
退出碼 2 表示**「命令本身有誤」** — 未變更調用方式前絕對不要重試。退出碼 4 表示「伺服器拒絕了此請求」 — 讀取 code 欄位,它會告訴你下一步該做什麼。
常見陷阱
- 要等待任務完成,請使用
glyph task activity <tid> --follow(即時 SSE)。在 shell 迴圈中輪詢task list會浪費資源且延遲真實事件。 - 若要取得「截至目前發生過什麼?」的快照,請不要使用
--follow—glyph task activity <tid> --json會在一次呼叫中回傳目前活動加上totalItems。--follow會阻塞直到任務終止。 - 先終止再移除。 單純的
task rm <tid>要求任務必須處於終止狀態(succeeded/failed/cancelled);如果任務仍在執行中,請先執行glyph task cancel <tid>,然後再執行task rm。只有當你同時想要刪除工作目錄和執行階段狀態(事後的stderr.log將會遺失)時,才使用--purge。session rm和workspace rm也有同樣的區別。 - 始終使用印出的
last seq:來恢復--follow。 在每次正常退出(event: end或串流關閉)以及串流中途出錯退出時,CLI 都會在標準錯誤輸出印出last seq: <N>— 在下一次--follow調用中傳遞--after <N>即可無間斷且無重複地恢復。Ctrl+C 是例外(標準錯誤輸出未更新);請改根據最後一個 stdout NDJSON 項目推導序號(... | tail -1 | jq .seq)。完整的恢復操作手冊在references/playbooks.md#monitor-a-long-running-task。 - 一律從
glyph workspace list --json | jq取得工作區 ID。 儀表板 URL 片段會在不同版本間偏離,並非線路契約。 schedule patch是稀疏的 — 只有你傳遞的旗標才會傳送到線路上。若要移除某個欄位,請傳遞--clear-details/--clear-runtime(空的--details ""會被視為未傳遞,而非清除)。
參考文件(進行非平凡工作前必讀)
references/commands.md— 按群組劃分的子命令參考(工作區 / 工作階段 / 任務 / 排程 / 目錄 / 工作流程 / 執行環境 / 伺服器檢查)。先瀏覽一次,然後作為查閱資料。references/playbooks.md— 多步驟目標導向的操作手冊(安裝並驗證代理程式、調度並等待、監控任務、同步項目、清理、建立新工作區、即時建立本機代理程式)。references/json-shapes.md— 常見的--json載荷結構,附有具體欄位清單和可選性備註。references/error-codes.md— 伺服器發出的每一個code值 + 對應的修正glyph命令。