using-gc

使用 GC

仅当调用方明确选择 Gas City 时才使用它。将其视为可替换的执行适配器，而不是正确性或完成边界。 该适配器无法选择 AgentOps 语义、作出具有约束力的判定，也无法将工厂完成转化为交付或验证证明。

操作者通道

进入 city 的操作者通道仅包含以下操作：

• 编写源意图 beads；
• 使用 gc mail 联系 Mayor，以分派工作并维护 city；
• 对于工作进程停滞的已路由 bead，执行一次 gc session wake <run_target>；
• 使用 gc doctor [--fix]，以及从 city 外部启动／停止 supervisor；
• 执行 ao gc prepare|check|recover-affinity；
• 读取 run、session、bead、pane 和 artifact 状态。

Mayor 编写工作流 beads 并分派它们；它负责此类工作的重试、重新分派和维护。切勿手动创建、扩容或修复由 pack 管理的 sessions：对单例或扩容的 Agent（core.control-dispatcher、role workers）执行 gc session new 会创建作用域错误的 session，使其以 start-pending 状态占用规范名称，并阻止 reconciler 启动真正的 session。Session 生命周期由 reconciler 和按需扩容机制负责。直接使用 gc sling 仅用于没有运行中 Mayor 的 city 进行调试；以这种方式启动的 run 没有协调器，其维护工作由操作者承担。

先选择工厂

AgentOps 同时支持 Gas City 和 Agentic Coding Flywheel 作为外部软件工厂运行时。仅在使用 Gas City 时采用本技能。如果调用方选择 Flywheel，请遵循其原生工作流，而不要将其包装在 Gas City 中。

AgentOps 为这两种工厂提供技能和证据契约。它不需要自己的 Gas City formula 或 role pack。启动工作进程前，请将 AgentOps 技能安装或链接到提供方运行时；随后，上游 Mayor、协调器和工作进程即可正常发现并选择 plan、implement、test、validate 及其他 AgentOps 技能。

版本信息

截至 2026-10-04，gascity 固定版本（0.1.6，提交 3b3b89f2011e06d84459aa7bea1552382f13930a）是 ao gc 强制使用的提交，且与注册表中的 0.1.6 版本一致。本技能中关于 Gas City 1.4.0 命令的信息尚未针对此版本重新验证。当 gc version 报告的版本不是 1.4.0 时，请在依赖任何命令之前使用 gc <command> --help 确认。

Gas City 1.4 运行模型

Gas City 1.4 以 run 为中心。Supervisor 提供仪表板以及类型化、分页的 session/run API。每个拥有 graph 的 city 或 rig 作用域都需要自己的 core.control-dispatcher；该确定性工作进程负责推进 formula 控制 beads。Agent 工作进程领取已路由的工作。上游 gc.mayor 技能是引导式协调器；gc.run-operator 用于启动并监督 formulas。

AgentOps 的常规流程如下：

1. 安装并固定上游 gascity 工作流和 rig-role 导入项。
2. 将项目添加为 rig，准备其标准维护运行时，并确保其提供方 sessions 能访问 AgentOps 技能。
3. 创建由调用方持有的源意图 bead，并将其 id 交给 Mayor；Mayor 会编写工作流 beads，并分派与现有 artifacts 相匹配的上游 build-basic、continuation、review 或 implementation formula。
4. 读取 run、session、bead、artifact 和 verdict 状态。绝不能根据聊天或 pane 中的文字推断任务已完成。

准备并检查 rig

在首次构建前，使用随附的 AgentOps CLI 准备并验证 rig（无需检出仓库）：

ao gc prepare --city /path/to/city --rig /path/to/rig
ao gc check --city /path/to/city --rig /path/to/rig

prepare 会验证确切的官方工作流和角色固定项，在 rig 的 .gc 目录中暂存隔离的维护者运行时，将 AgentOps 技能链接到 city 和 rig 的 Codex 接收目录，并为运行时已存在的每个会话目录预先建立 Codex 工作区和钩子信任。钩子信任需要在 PATH 中找到 Codex CLI（或使用 --codex-bin）。check 为只读操作，不会运行 Codex 子进程；如果缺少或偏离该运行时契约，它会在产生模型费用前失败。

运行 prepare，启动 city，然后再次运行 prepare（该操作具有幂等性），再进行派发。由于两项限制，这个顺序必不可少：check 无法发现过期的信任哈希，因此检查通过仅表示已记录信任，而不代表信任仍然有效；此外，prepare 运行后新建的会话主目录不在覆盖范围内。 Codex 信任预置介绍了相关机制。

推荐的 pack 和注册表

内置的 main 注册表收录官方 pack。社区注册表是可选配置：

gc pack registry list
gc pack registry refresh
gc pack registry search --all
gc pack registry show main:gascity
gc pack registry add community https://registry.gascity.com/registry.toml
gc pack registry search --registry community --all

search 会读取本地注册表缓存；show 会报告发布来源和确切的导入命令。gc import add 用于声明来源/版本，gc import install 会将其解析到 packs.lock 中。为确保 city 可复现，优先选择确切的已接受发布版本。

AgentOps 推荐使用官方 gascity 构建 pack；它属于上述已接受参考中公共 Maintainer City 工厂所展示的工作流系列：

• 仪表板：https://factory.gascity.com；
• 工作流：build-basic、build-from-*、implement、review、issue 和 PR 流程；
• 自带的 rig 角色：gc.run-operator、gc.implementation-worker、规划者、审核者和发布者；
• 作用域本地的公式控制：core.control-dispatcher；
• 引导式协调：上游的 gc.mayor 技能。

在 city 作用域安装工作流 pack，并在每个执行工作的 rig 上安装其配套角色 pack，按照 gc pack registry show main:gascity 返回的确切命令操作。保留自带的 gc.* 命名空间；不要将这些角色嵌套在 AgentOps pack 下，也不要重命名。

将工作交给 Mayor

工作通过 Mayor 进入 city。调用方编写一个包含验收标准的源意图 bead，然后将其 id 交给 Mayor；Mayor 会拆解任务、编写工作流 bead 并进行派发。

gc bd create "Add a --json flag to the export command"
gc mail send mayor -s "Build ago-XXXX" \
  -m "Decompose and launch build-basic for bead ago-XXXX with push=false open_pr=false." --notify

只有在调用方和仓库的交付策略都授权发布时，才传入 push=true open_pr=true；否则，已批准的提交会保留在其源锚点 worktree 中。

或者，在交互式 Mayor 会话中：

Use skill gc.mayor

AgentOps 技能是这些工厂 Agent 可用的工具，而不是工作流的替代品。需要某项技能的行为时，请在 bead 或提示词中明确写出该技能名称。目前的上游拆解流程不会自动将调用方拥有的源 bead 中自由格式的 Required Skills 部分传递到每个生成的工作项。请在实施前检查拆解结果；如果使用某项技能是验收条件，请将技能名称写入实际工作项或工作者提示词。技能存在和技能被调用是两回事。

将现有 city 升级到 1.4

启动其协调器之前，每个 city 运行一次：

gc doctor --fix
gc import install
gc supervisor stop --wait   # macOS when an older direct supervisor remains
gc start

然后确认：

• gc version 从预期路径报告 1.4.0；
• gc doctor 没有阻塞性故障；
• 每个拥有图的 rig 都有一个未暂停的 core.control-dispatcher；
• 导入和 packs.lock 均可解析；
• ao gc check 接受其中包含的维护者运行时和 AgentOps 技能链接；
• 在 macOS 上，supervisor LaunchAgent 指向的可执行文件与所选 gc 二进制文件相同；
• 已移除旧的独立仪表板书签或反向代理。

注册信息过时的 city 可能会阻止所有启动操作。使用 gc doctor --fix 修复该 city；如果它确实已退役，也可以明确注销。

按确切的注册名称或路径退役旧 HQ/canary，但不要停止替代对象所需的整机 supervisor：

gc cities --json
gc stop /path/to/old-city --timeout 45s
gc unregister /path/to/old-city
gc cities --json

unregister 遇到未知目标时会失败，而不会悄悄接受。保留 city 目录，直到其 Beads 状态已备份或确认可以丢弃。使用上游 Gas City 模板创建替代项，安装其固定版本的导入项，并通过 gc cities --json、gc --city <new-city> status 和 gc --city <new-city> doctor --json 验证。

通过 Mayor 协调：tending 循环

将意图交给 Mayor 后，协调器会执行五个动词。每个动词都有唯一负责人；跨越负责人职责正是本节要防止的常见故障类型。

动词	负责人	接口
监控	协调器	按固定周期访问 $API/runs/census 和 $API/runs/<run-id>，并使用 gc mail inbox 查看 Mayor 的回复。census 中出现 failed > 0、某个 run 处于 failed/canceled 状态，或有未读的 Mayor 邮件，都是执行信号；其他情况都只是一次 tick。
观察	协调器	出现执行信号时，按顺序检查可见性层——census、run 详情、bead 图、会话列表、窗格状态——并在第一个能解释情况的层级停止。不要从窗格状态开始。
提醒	协调器，仅一次	有活动会话的已路由 bead：gc session wake <run_target> 一次。已就绪但无人派发的 bead，应通过邮件将其 id 发给 Mayor；派发由 Mayor 负责。针对同一事项进行第二次提醒，说明诊断有误——应改为给 Mayor 发邮件。
重定向	Mayor	优先级、范围、取消或模型/提供商变更都通过邮件发送，并附上 bead/run id。协调器绝不重新 sling、编辑工作流 bead，也不修补正在运行的 run。
返工	GC 优先，然后 Mayor	失败的审核结果通过原生修复循环（review_fix_formula，默认 fix-loop-base）重新进入 run；有界的门控重试使用 gc converge 循环。只有处于终止状态的 failed/canceled run，或已完成但结果不符合调用方验收标准的 run，才会退回：将 run id 和失败证据通过邮件发给 Mayor，以便重新拆解并重新启动。

协调器手动执行的返工（编辑失败 run 的工作树、重新 sling 其公式、关闭其 bead）会让同一意图出现第二个未经协调的执行者；随后 Mayor 的重新启动就会与之冲突。

停滞处理协议

首先判断 bead 的状态。

• 仍为 ready，从未派发：派发工作属于 Mayor。将 bead id 发给它，然后停止并检查。只有在没有活动 Mayor 时，才可将 gc sling <run_target> <bead-id> 用作一次性的调试备用方案；之后，操作员接管该次运行的跟进工作。

• 已路由／进行中：重新 sling 是空操作。唤醒其所属 worker 一次：

  gc session wake <run_target>
  

然后捕获会话状态中指定的确切 tmux 面板并运行 gc doctor。如果面板停在 Codex 信任对话框，说明其主目录未完成预置（参见下文的面板真相）。绝不要在某个 city 内部修复该 city。绝不要用 gc session new 来应对停滞；上文的操作员通道说明了原因。

如果唤醒一次后仍未解除停滞，或者 city 本身需要维护（协调器停滞、会话始终无法退出 draining 状态、模型或 provider 重新接线），请将请求连同 bead 或 run id 发给 Mayor：

gc mail send mayor -s "<subject>" -m "<request with bead ids>" --notify

上游 pack 可能会将未来某个受 affinity 约束的步骤分配给已确认 drain 的会话。只能在 city 外部诊断此问题：

ao gc recover-affinity --city /path/to/city --rig /path/to/rig

默认执行 dry run。如果列出的每项分配都正确，请使用 --apply 重复执行。此项有界修复只会清除当前处于 ready 状态、且其 gc.session_affinity=require 会话已不再运行的 formula bead 上的 assignee。它不会 sling、重试、关闭、重启或选择工作。

可见性：四个层次

1. Supervisor/运行状态 — gc dashboard、运行详情、gc status 和 gc session list --json。运行详情整合了阶段阶梯、结构化记录、 令牌速率和估算消耗速率。即使提供方卡住，成员名单仍可能报告其处于活动状态。

   程序化运行状态来自 supervisor 的类型化运行 API—— 这也是仪表板所呈现的数据。gc status 会打印 API 基址；gc status --json 和 任何其他 CLI 子命令都不会携带运行对象。

   API="http://127.0.0.1:<port>/v0/city/<city-name>"
   curl -s "$API/runs/<run-id>"   # {run_id, title, status, target, scope, started_at, updated_at}
   curl -s "$API/runs/census"     # {status_counts: {pending, active, waiting, canceling, completed, failed, canceled, skipped}}
   

   轮询运行状态和清点结果以查看进展；failed 计数非零是 第一个可供机器读取的失败信号。仪表板的运行页面 (/city/<city-name>/runs/<run-id>) 是同一批对象的人类可读视图。

2. Bead 图 — gc bd --rig <rig> ready --json 和 show <id> --json。 这是工作流状态的真实依据，但已认领的 bead 无法显示卡住的窗格。

3. 窗格实况 — tmux -L <socket> capture-pane -pt <session>。这会显示 信任提示、更新提醒、API/DNS 故障和交互卡死。若窗格停留在 Codex 的 Do you trust the contents of this directory?（或之后出现的 Press t to trust all 挂钩对话框），表示该会话目录尚未预先设置——工作流会将派发排入队列并标为待处理，没有活动工作器，也不会报告错误。几乎总是因为主目录是在上次 ao gc prepare 之后创建的；请重新运行 prepare，然后重启该会话。 ao gc check 会指出未受信任的目录或挂钩，避免你在此情况下派发任务。 Gas City 似乎也会通过向窗格发送按键自动应答此对话框，因此卡死状态可能会自行解除——应将其视为不应依赖的竞态，而不是跳过预先设置的理由。

4. 健康检查机制 — gc doctor、gc order history、存储健康状态和 事件。这能证明代谢机制正常运作，而非语义验收通过。

当各层信息不一致时，应相信更直接的观察结果：判断会话是否卡死时，以窗格信息为准，而非成员名单；判断工作流是否完成时，以 bead/运行状态为准，而非文字说明。

gc status 可能返回部分 no_agents_running 快照，而 gc session list --json 却显示 Mayor 或工作器仍在运行。应将其视为可观测性不一致，而非重启许可。使用会话和窗格实况判断存活状态，使用 bead/运行状态判断工作流进度，并使用 Doctor 判断代谢机制。Supervisor 的 CPU 异常、原生停止操作超时或反复重写挂钩，仍属于上游运维缺陷；此助手会报告问题，但绝不会终止或修补 GC 进程。

调用方拥有的输入 bead 与生成的工作流根目录有各自独立的生命周期。成功的 build-basic 运行可能会关闭其工作流根目录，同时让输入 bead 保持打开。同样，push=false 和 open_pr=false 会产生一次成功的空操作发布，而已批准的提交仍保留在其源锚定工作树中。两种状态本身都不代表语义完成。

边界

• GC quest、运行、尝试、停滞、取消和内部关闭状态都保留在 GC 中。它们绝不会转化为 AgentOps 的 Plan、Candidate、RPI 或 verdict 状态。
• GC 关闭或运行完成不等于 AgentOps 完成。只有新的 Validate 上下文才能给出语义结果，或在有此请求时持久化 verdict.v2。
• 此技能不会自动进行选择、重试、语义验证、Git 操作、集成、关闭、发布或交付。
• 操作员职责范围之外的一切事务都属于 Mayor 或 reconciler。