Communitygithub.com

glyphs-ai/glyph

Glyph 是一個組合當今智能表現形式的工作台,並協助發現未來它將使用的語言。

glyph 是什麼?

本技能提供一個完整的 CLI 操作介面,讓 AI 代理可以控制 Glyph 伺服器。它涵蓋了 `glyph` 命令的所有子命令群組,包括工作區管理、互動式工作階段、一次性任務調度、排程任務、目錄管理、工作流程 DAG 操作與伺服器檢查。更重要的是,它詳細說明了工作區作用域規範(透過 `GLYPH_WORKSPACE` 環境變數隔離不同客戶端)、輸出規範(優先使用 `--json` 格式以確保解析穩定性),以及錯誤處理規範(根據 `code` 與 `fix:` 行進行機械化分支判斷)。支援所有主流 CLI 平台,並提供多份參考文件(命令參考、Playbook、JSON 結構與錯誤碼目錄)作為進階使用依據。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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建立 / 列出 / 顯示 / 更新 / 移除 / 重新載入工作區;列印目前 IDreferences/commands.md#workspace
session管理互動式工作階段(列出 / 新增 / 顯示 / 移除 / 啟動終端機)references/commands.md#session
task調度一次性任務、列出(可按 --origin 範圍篩選)、檢視任務、追蹤活動、取消、移除references/commands.md#task
schedule排程觸發的任務啟動器(建立 / 列出 / 修補 / 啟用 / 停用 / 執行 / 預覽 / 列出任務)references/commands.md#schedule
catalog安裝 / 同步 / 啟用 / 停用代理程式、技能、MCPreferences/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 命令。

相關技能