Communitygithub.com

glyphs-ai/glyph

Glyph 是一个工作台,用于组合当今智能所采用的形式——并发现它未来将使用的语言。

glyph 是什么?

Glyph 是一个面向 AI agent 的 CLI 工作台,专为控制 glyph 服务器而设计。它提供了一套完整的命令表面,涵盖工作区、会话、任务、调度、目录和工作流管理。该技能的核心在于其严格的工作区作用域纪律和错误处理机制,确保多客户端环境下命令互不干扰,并通过明确的退出码和结构化错误信息支持机械化的故障分支处理。用户可以通过 `glyph` CLI 与服务器交互,支持 JSON 输出以便于解析,并提供实时 SSE 流式任务监控。该技能适用于开发者和 AI 代理,旨在提供一个可靠、可编程的 API 来管理复杂的 AI 工作流和组件生命周期。

兼容平台~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基于 Cron 触发的任务启动器(创建/列出/修补/启用/禁用/运行/预览/列出任务)references/commands.md#schedule
catalog安装/同步/启用/禁用 agent、技能、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 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 修复命令。

相关技能