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 | 基于 Cron 触发的任务启动器(创建/列出/修补/启用/禁用/运行/预览/列出任务) | references/commands.md#schedule |
catalog | 安装/同步/启用/禁用 agent、技能、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 agent)干扰。
输出纪律
- 对于解析,始终传递
--json。 人类可读/表格格式不是稳定合约——列顺序和标题会在不同版本间变化。 - 对于流式活动,通过管道交给
jq -c以保持每行一个事件。 - 你可能用到的每个
--json形状都在references/json-shapes.md中有文档。在编写jq过滤器之前,请先查阅它——大多数形状都有可选字段(当底层行非空时出现),你应该以此为依据。
错误纪律
stderr 上的错误总是包含一个 code:
agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
agent: acme/writer
cause: prereqs not acknowledged
fix: glyph catalog agent ack-prereqs acme/writer
fix: 行是你的下一条命令,原样复制。完整的 code 目录(所有错误名称 + 典型 HTTP + 修复措施)位于 references/error-codes.md。特别地:
EntryNotReadyError是你最常遇到的分支——它带有一个结构化的reason,描述 agent 是否需要ack-prereqs、是disabled、有missingDeps还是blockedDeps(可能递归)。原因表在references/error-codes.md#entrynotreadyerror-reasons。
退出码
| 退出码 | 含义 | 如何处理 |
|---|---|---|
| 0 | 成功 | 继续 |
| 1 | 通用错误(包括缺少工作区) | 读取 stderr;通常是缺少标志/环境变量 |
| 2 | 用法错误(缺少必需标志,子命令已移除) | 修正调用;不要原样重试 |
| 3 | 服务器不可达 | 询问用户 glyph start 或检查 --server |
| 4 | 服务器返回 4xx/5xx | 读取 stderr 中的 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>打印到 stderr——在下次--follow调用中传递--after <N>以无间隙、无重复地恢复。Ctrl+C 是例外(stderr 未刷新);请从最后一个 stdout NDJSON 项中推导出 seq(... | 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— 按组分类的子命令参考(workspace / session / task / schedule / catalog / workflow / runtime / server inspection)。浏览一遍,作为查找表保留。references/playbooks.md— 多步骤、目标导向的操作手册(安装并验证 agent、派发并等待、监控任务、同步条目、清理、初始化新工作区、即时创建本地 agent)。references/json-shapes.md— 常见的--json负载形状,包含具体的字段列表和可选性说明。references/error-codes.md— 服务器发出的每个code值 + 相应的glyph修复命令。