gimbal-runs

使用 Gimbal

使用已安装的命令对项目运行工作流。调用已安装的工作流不需要编写 Go 或构建 Svelte。要创建新工作流，请使用编写工作流；要构建应用程序，请使用构建与发布。

选择工作流并了解其约定

gimbal --help
gimbal run --help
gimbal run review --help

工作流帮助信息来自所选的运行中中央目录。如果它不在当前目录下，请使用 --instance-dir /abs/instance。帮助信息会告知你有哪些已注册的工作流、输入和模型默认值。存在 df-* 技能并不意味着它是 Gimbal 命令。

默认情况下，macOS 应用会将 ~/.gimbal/desktop 用作实例目录来启动其捆绑的中央服务。要向该目录提交 CLI 运行任务，请传入 --instance-dir ~/.gimbal/desktop，或为 CLI 设置 GIMBAL_INSTANCE_DIR。 应用仅在显式配置为代理外部服务时才会使用 GIMBAL_SERVER_URL。

明确目标、目标项目、允许的更改，以及能够证明结果有用的依据。提供的章节或冲刺可以作为背景信息；相关时请加以利用，而不是每次调用都自行编造规划产物。关于承诺、章节、冲刺、任务和运行之间的区别，请参阅术语表与证明指南。

工作流帮助信息应说明用途、输入、输出或更改、完成预期和限制。如果重要部分缺失，请从工作流源代码或用户处确认，不要猜测其权威性。

对于研究文档，请查看 gimbal run research-document --help。提供目标、本地研究目录、输出路径和文档令牌预算。--source-dir 使用固定的本地原始资料；省略它则会收集网络资料。该工作流会写入语义化的 INDEX.md，在 <research-dir>/.semantic-index/ 下记录提取出的每项主张及 Jev 来源／配对结果，并在文档验收前修复或标明结果的限定条件。单独的 gimbal run research-eval --help 命令会对固定来源比较研究员和索引整理员的模型分配。该命令选出的模型仅对该测试套件暂定为胜者；报告会分别说明事实正确性、检索、修复和成本。

对于冲刺规划，请查看 gimbal run sprint-plan --help。提供一个本地意图文件，以及 ephemeral/sprints/ 下的新冲刺目录。意图文件应说明利益相关方的预期结果、边界、验收证据和有用的参考路径。该工作流会收集项目信息和既有成果，整理成带索引的工作集，随后生成三份草稿、交叉评议，并产出包含实现参考资料的提议版 plan.md。执行前请审查尚未解决的利益相关方决策；规划完成并不能证明预期结果已经交付。

开始运行

只有在工作流使用 WithSupervisor 进行 Jev 监督时，Gimbal 才要求提供 TYPESAFE_API_KEY。run-prompt、不使用 Jev 的工作流，以及实例启动均不需要该密钥。受监督的工作流在未提供密钥而进入 Jev 监督阶段时会报告明确的错误。仅联系已运行实例的帮助和命令不需要本地 TypeSafe 密钥。

gimbal --instance-dir /abs/instance --port 8080
# In another shell:
gimbal run review --instance-dir /abs/instance --project /abs/project --input '{"goal":"Review the parser changes for correctness; report concrete findings with evidence."}'

中央服务和工作流守护进程会在启动时通过重复指定 --plugin-dir DIR 来发现原生插件。请将匹配的插件构建版本部署到各个环境，并在重新构建项目插件后重启。CLI 和前端无需重新构建即可接受其变更后的输入约定。控制命令和生成过程不会加载本地插件文件。

请将 --input 设为 JSON 对象或 @/abs/input.json，也可以使用目录中的参数标志。共享的浏览器运行表单会显示相同字段；勾选 Include 可提交可选的空值、零或 false。运行获准启动前，输入错误会指出对应的可见字段。 默认情况下，central 会启动一个本地独立运行器。要将其放置在远程位置，请选择 --workflow-endpoint URL --workflow-project /abs/project-at-A 和 --work-dir /abs/workdir-at-A，该设置独立于 central 的 --project 目录。 选择 --task-endpoint URL 可在 B 处运行任务。--workflow-route 和 --task-route 接受 JSON 或 @file，其中包含已注册后端实现的 name、configuration 和 environment。 请在每个环境中配置仓库和工作区；插件路径在每个守护进程本地配置。 central 会保留运行路由，因此重启 central 后可以重新打开正在进行的运行，而无需重新提交。 观测通道断开意味着存在信息缺口，并不能证明工作已停止或失败。

使用绝对项目路径。默认不要传递角色模型标志：工作流显示的默认值是其预期角色配置，传入标志会替换其中一项。仅在用户要求特定模型或推理力度、默认模型无法运行且用户批准替换，或工作流自身的帮助信息明确指出当前工作属于适合使用更廉价模型的范围清晰场景时，才覆盖角色设置。在最后一种情况下，常规工作优先选择文档中说明的 Sol 或 Opus，但如果帮助信息中的歧义、风险或难度标准适用，则保留已配置的前沿默认模型。 不要因一般性的成本压力而对无关角色一概覆盖。覆盖前，请阅读 --help 中每个角色对应的行，并说明最终映射。结果报告中记录实际使用的模型。

OpenCode 模型需明确指定：opencode/<model-id> 会选择 OpenCode 的 opencode 提供方，而 opencode/<provider>/<model-id> 会选择 OpenCode 中配置的其他提供方。这两种格式均适用于工作流角色标志和 gimbal run-prompt --model。共享服务器会在首次使用时启动，并在会话关闭后继续运行。其状态目录默认为 ~/.gimbal/opencode，也可通过 GIMBAL_OPENCODE_DIR 指定；gimbal opencode start|stop [--state-dir DIR] 可直接管理该服务器，停止操作会中断正在进行的工作。原始请求、结果和 SSE 捕获文件会写入 <state-dir>/captures/。

对于使用 Diffusion Router 的 Pi，请发现当前密钥可用且支持聊天和工具的模型 ID：

curl -fsS https://router.diffusion.io/v1/models \
  -H "Authorization: Bearer ${DIFFUSION_API_KEY}" |
  jq -r '.data[] | select(.capabilities.openai_chat == true and .capabilities.tools == true) | .id'

在工作流角色标志或 gimbal run-prompt --model 中，为选定的开放权重模型 ID 添加 pi/diffusion/ 前缀，例如 pi/diffusion/deepseek-4.1-flash-background。 Gimbal 无需依赖 models.dev 即可路由这些模型。请在服务器环境中设置 DIFFUSION_API_KEY。Pi 运行环境原生运行于 Gimbal 进程中；无需单独安装 Pi、Bun 或 Node。 Shell 工具仍会启动子命令。

另一种实用配置是将前沿能力用于规划，然后把低风险、可撤销且可独立检查的后台工作分配给 Terra 或 Sonnet。若耗时并不重要，且工作流具有范围明确的验证反馈机制，能够拒绝质量较差的已完成尝试并尝试更好的分配，则优先采用此配置。 计划并非证明，因此应根据风险进行独立验证。不要假设工作流会重试提供方、运行环境或执行错误；只有明确的重试路径才会执行重试。

独立运行进程启动后，命令会返回运行 ID。使用 --follow 等待运行结果。如果 central 断开连接，follow 会在最长 30 秒内重新发现所选实例，并继续观测同一运行，而不会重新提交；若未能恢复连接，则会返回明确错误。命令退出或守护进程停止后，运行仍会继续。使用相同的实例目录重启守护进程，即可恢复对其已接纳项目的观测和控制。守护进程的 --port 0 会选择一个可用的浏览器端口；--uds 会通过 Unix 套接字提供服务。

使用 --task-endpoint 可在选定的独立守护进程中执行 Agent、命令和由作用域管理的服务。有关工作区配置、传输的制品和作用域密钥，请参阅任务守护进程。

消息任务路由

filesystem、river 和 http-sse 原生插件负责传递请求和保留事件，而工作流仍使用普通 Go 编写。从同一代码检出目录和 Go 工具链构建 CLI 与各个插件；go build -buildmode=plugin -o /abs/plugins/filesystem.so ./plugins/messaging-filesystem 可构建 filesystem 插件。River 和 HTTP 包分别是 ./plugins/messaging-river 和 ./plugins/messaging-http。使用 --plugin-dir /abs/plugins 启动 central。 对于已发布的 CLI，添加 -trimpath，并遵循分发中的确切源码、工具链和工作区要求。

路由文件包含 Name 和 Configuration。选择一种配置：

Name	Configuration
filesystem	{"Directory":"/abs/private-messages"}
river	{"DSNFile":"/abs/private-postgres-dsn","Queue":"gimbal"}
http-sse	{"URL":"http://127.0.0.1:18091"}

对于 filesystem 或 River，使用与调用方相同的路由启动一个 worker：

gimbal message-worker --plugin-dir /abs/plugins --task-route @/abs/route.json
gimbal run service-check --instance-dir /abs/instance --project /abs/project --work-dir /abs/project/work --task-route @/abs/route.json --task 'Write the required file.' --follow
gimbal message-watch --plugin-dir /abs/plugins --task-route @/abs/route.json --run RUN_ID

未配置后端依赖项的 worker 会将作用域密钥保存在进程私有内存中。具名环境使用编排提供的共享密钥目录。

在不同的 shell 中运行这些命令。River 需要可访问的 PostgreSQL，以及一个包含连接字符串的私有文件；worker 会初始化其架构。其操作队列默认为 gimbal，单独的控制队列默认为 gimbal_control，操作 worker 数量默认为 4。使用不同队列隔离独立部署。

HTTP 每个环境使用一个 URL。worker 路由还需指定 Listen（127.0.0.1:18091）和绝对路径 EventsDir。Agent 会话、命令和服务使用编排所选的守护进程。

若要自动启动具名环境，调用方路由需添加 Environment 和 Backends。例如，使用 filesystem 插件：

{
  "Name": "filesystem",
  "Configuration": {"Directory": "/abs/control"},
  "Environment": "development",
  "Backends": {
    "Orchestrator": {
      "Name": "local",
      "Configuration": {
        "Directory": "/abs/private-backends",
        "Environments": {
          "development": {
            "Command": ["/abs/gimbal", "message-worker", "--plugin-dir", "/abs/plugins", "--task-route", "@/abs/worker.json"],
            "Route": {"Name": "filesystem", "Configuration": {"Directory": "/abs/development-messages"}}
          }
        }
      }
    },
    "Secrets": {"Name": "file", "Configuration": {"Directory": "/abs/private-backends/secrets"}}
  }
}

worker.json 包含与该环境的 Route 相同的 Name 和 Configuration。编排会提供 worker 就绪状态，并通过私有标准输入传递所选的密钥配置。具名的编排器注册和密钥注册独立于消息插件。本地子进程编排器需要共享密钥；file 后端会在调用方和 worker 之间共享其私有目录。memory 后端适用于同一进程中的调用方和 worker，在本地子进程编排中不受支持。它会在分发前启动守护进程，保留无关的作用域使用，并在清理最后一个原生作用域后停止守护进程。不要手动启动此 worker。具名环境需要消息路由；直接任务端点不能绕过放置机制。

service-check 工作流需要在守护进程环境中具备 Docker、psql、Python 3 和 Agent harness。它会创建 Postgres 和 Web 服务，发布作用域连接值，通过并行消费者查询数据库，并让 Agent 使用 Gimbal 密钥回调获取 Web 响应。请使用全新的工作目录，并明确指定成本较低的模型，例如 gpt-5.6-luna。

在此实现中，worker 和调用方共享本地路径。重启 worker 不会恢复原生操作或会话。消息路由不支持转向和分叉。投递状态不确定并不能证明原生失败或已停止。message-watch 会独立读取保留的历史记录；停止它不会取消工作。其 JSONL 可能包含私有 Agent 内容。事件文件或 PostgreSQL 行会一直保留，直到显式删除。

查找运行并观察其工作

gimbal runs --work-dir /abs/project
gimbal watch RUN_ID --work-dir /abs/project

使用同一项目目录。runs 会返回响应中的本地运行时的活动运行的 JSON。watch 会先输出初始快照，然后输出以换行符分隔的 JSON 变更。查看运行状态、范围、会话和轮次，了解正在发生什么。

没有结束时间的轮次表示会话处于活动状态。复制该会话的准确 ID。角色名称、会话 ID、轮次 ID 和循环范围 ID 分别代表不同内容。发现结果为空，可能表示运行时不存在或无法访问；这不能确切说明已保存的历史记录。

引导会话或下一步规划决策

gimbal steer RUN_ID --work-dir /abs/project --session SESSION_ID "Investigate the failing parser test before expanding the review."
gimbal steer RUN_ID --work-dir /abs/project --loop LOOP_SCOPE_ID "Prioritize the CLI work in the next assignment."

准确选择一个目标。会话引导会发送到该会话的活动轮次；landed: false 表示消息已丢弃，不会保存供后续轮次使用。循环引导会为负责分派任务的循环排队一条消息，供其下一次规划决策使用。

提供可执行的修正建议和相关证据，然后观察 Agent 的行动。landed: true 表示消息已送达；queued: true 表示消息已排队。二者都不能证明指令已得到遵循。

评估结果及其证明

检查与目标相关的工作或行为。审查发现应指出具体缺陷；实现声明需要通过观察变更后的行为来验证。测试和命令结果仅能证明其实际测试的内容。记录的失败结果不能被声称已通过的文字推翻。

运行可以结束，规划器也可以停止分派任务，但请求的结果仍可能未达成。对于承诺，应明确说明声明、范围、证据、验证者和检查过的状态。如果工作流或验收约定要求独立验证，就应进行独立验证；验证者检查的是结果，而非接受工作者的说法作为证明。

已保存的记录位于 /abs/project/.gimbal/runs/RUN_ID/。要在浏览器中检查历史记录，请在项目目录中运行 gimbal --port 0。实时 watch 需要有正在运行的所属实例；查看已保存的历史记录不会恢复其会话。 Codex 会主动尝试恢复断开的连接，最多在一分钟内重试三次。仍存续的原生轮次会重新连接；已完成的结果则从历史记录中读取。如果守护进程仍不可用，或无法确定能否安全继续，那么同一调用、运行和任务会保持暂停状态，直到所属实例退出。 记录中的连接通知会说明原因。检查现有工作并确认先前操作已停止后，可通过以下命令请求另一批有次数限制的协调重试：

gimbal steer RUN_ID --work-dir /abs/project --session SESSION_ID resume

这是 Codex 会话暂停时用于适配器恢复的控制，不表示原生消息已送达或任务已完成。适配器会在重新连接或启动同一线程的后续操作前再次检查历史记录。它绝不会重放已接受的结果。也可使用 gimbal cancel RUN_ID --work-dir /abs/project 取消。 该命令还会重试对终止运行尚未完成的远程清理。清理失败时，所属实例会保留停止控制；这不能证明工作进程已停止。实例重启后，控制会重新连接到仍在运行的独立工作流进程；但无法恢复已退出的工作流进程。对于 --task-endpoint 运行，中央服务会使用保留的所属实例路由来清理该进程的远程范围；清理失败时仍可重试。

Gimbal 没有通用的恢复命令。代码库中的承诺辅助工具可以自行定义可恢复状态、计划和徽章；这些属于独立功能。

直接检查时，应先查看已存储的运行结果和轮次结果，然后查看相关会话记录或记录的命令输出。请遵循使用方项目关于保留或共享证据的政策。

运行实用的用户测试

gimbal run validate-product --suite-file /abs/suite.yaml --instance-dir /abs/instance --project /abs/project --follow 会使用 Opus 5.5 运行一到三个由调用方指定的工作负载，使用 Gemini Flash 检查其截图，并综合整理发现。测试套件必须为受测产品提供 issue_repo。最终 Agent 会检查重复项，使用 gimbal upload-artifact 上传支持性截图，并在该仓库中发布受支持的发现。每个 工作负载结束后，同一个测试者会回答一项后续问题：分别列出 UX 和 UI 方面最喜欢和最不喜欢的三个特点，并提供具体示例。复盘内容会附加到任务报告中；经过的工作负载时间不包括复盘。请提供产品、本地任务分配文件、隔离的工作区、启动／就绪命令或现有 URL，以及输出目录。启动选定的实例；如果启动时尚未允许访问 /abs/project，工作流命令会在首次启动时允许访问该路径。 --follow 会等待分流和问题发布。命令的帮助信息说明了 JSON/YAML 输入和模型覆盖选项。发布需要经过身份验证的 gh，以及配置好的公开资源目标。

分配有用的任务，而不是穷尽所有功能的检查清单。测试者绝不能查看受测产品的源代码。他们会截取带说明的截图，并分别报告任务是否成功和可用性情况；视频仅供人工审核。运行前请安装带有 libx264 的 FFmpeg。reports.json 会指向每个 2.5× H.264 video.mp4，视频上限为 1280×720，可直接用于 gimbal upload-artifact； 原始 video.webm 会保留在旁边。 通过让 Gimbal 构建另一个项目来测试 Gimbal 时，请使用委托运行自己的 Web 监听器，以便实时监控 UI/API。独立的历史记录查看器可能会保留由其他进程运行的任务的过时快照。

从对话开始工作

在 Git 检出目录中运行 gimbal --port 0，然后打开对话。创建对话时选择 Codex、Claude 或 agy/Gemini；Gimbal 会创建其工作树和分支。请 Agent 启动审查或实现工作，然后打开关联的运行，以便在同一服务器中监控。实现工作需要在对话的工作树中提供本地完成定义文件。对话回合进行期间，请保持服务器运行。已启动的工作流会独立运行。服务器重启后，已保存的 Codex 对话会在下一条消息到达时恢复其原生线程。已保存的 Claude 和 agy/Gemini 对话仍可查看历史记录，但目前无法继续。

报告发生的情况

请提供工作流、项目、模型、运行 ID、有用的结果以及观察到的证据。进行引导时，请说明目标、交付结果和后续行为。将失败或尚未证实的要求与已完成的工作分开说明。报告长度应与任务相称。