Fleetshift状态机完全指南:11种target状态如何从pending走到prMerged

原创2026-11-06 21:06:592,227 阅读
文章标签:AI 插件AI 技能开发工具开发者门户工作流自动化

Fleetshift状态机完全指南:11种target状态如何从pending走到prMerged

portal-ai-plugins 是面向 Claude Code、Codex、Cursor 等编程智能体的 AI 插件集,其中的 Fleetshift 能力可以让 AI agent 在大量仓库上批量应用同一项变更,并自动开出 PR。本文从状态机视角完整解析 Fleetshift shift 的 11 种 target 状态(从 pending 到 prMerged),帮你快速看懂 shift 的实时进度、判断何时可以开 PR,以及失败时去哪里查日志。

一、先认识 Fleetshift:一个"批量改仓库"的状态机

Fleetshift 的核心概念是 shift——一份可复用的定义,包含三要素:

  • agent prompt:告诉 AI 在每个目标仓库里做什么
  • targets:一组仓库(每个 target 对应一个 agent job)
  • PR 元数据:完成后的 PR 标题与描述策略

shift 创建后,每个 target 都会沿一条清晰的状态链流转,整个生命周期可以分为三个阶段:

  1. 排队阶段:target 等待被触发
  2. 执行阶段:agent job 运行并产生结果
  3. PR 阶段:成功的变更被转换为可评审的 Pull Request

每个 target 的当前状态,就是判断"我的 shift 怎么样了"的最快依据。

二、11种target状态完整清单

下表覆盖 skills/fleetshift-check-shift/SKILL.md 中 statusBreakdown 返回的全部 11 种状态:

状态 阶段 含义 监控视角是否终态
pending 排队 尚未触发执行,没有 job 字段 否
jobRunning 执行 agent job 正在运行 否
jobComplete 执行 job 成功结束且有变更,可开 PR 否(可进入 PR 阶段)
jobFailed 执行 job 失败,需要排查 是
stopped 执行 被 stop-jobs 急停开关叫停 是
noChanges 执行 agent 跑完了但没产生任何变更 是
skipped 执行 job 被跳过 是
prCreating PR 正在为目标仓库创建 PR 否
prOpen PR PR 已打开,等待人工评审 是(等待人工)
prMerged PR PR 已合并,这才是真正的"完成" 是
prClosed PR PR 被未合并即关闭 是

排队与执行阶段:pending 到 jobFailed

  • pending 是起点。触发前,未运行的 target 都会以 pending 出现且不带 job 字段,因此 target 总数与 shift 定义的数量严格一致。
  • 触发后进入 jobRunning,随后落入五种结果之一:jobComplete、jobFailed、stopped、noChanges、skipped。
  • 其中 jobComplete 是唯一的"可开 PR"状态;noChanges 表示 agent 判定无需改动,属正常结果而非错误。

PR 阶段:prCreating 到 prMerged

  • 只有 jobComplete 的 target 才有资格开 PR,prCreating 只是短暂的过渡态,随即进入 prOpen。
  • 之后状态完全由人工评审决定:合并则 prMerged,放弃则 prClosed。
  • 注意:completedCount 统计的只有 prMerged 的 target,PR 开了但没合并并不算完成。

三、如何快速查看状态分布(check-shift 工作流)

查看状态属于纯只读操作,几天甚至几周后依然安全可跑,见 skills/fleetshift-check-shift/SKILL.md:

  • 全局概览:fleetshift:list-shifts 返回每个 shift 的 statusCounts(各状态 target 计数)和 completedCount
  • 单个 shift:fleetshift:get-shift 返回聚合的 statusBreakdown,一行就能回答"多少完成、多少失败、多少在跑"
  • 按状态过滤:fleetshift:get-shift-targets 支持 "status":"jobFailed" 这类条件,直接捞出失败项;target 上还会附带 prUrl / prNumber
  • 单 job 深挖:用 target 的 jobIdentifier 调 fleetshift:get-job-status 和 fleetshift:get-job-logs

四、三个最容易踩的坑 ⚠️

  1. 别把 completedCount 当总进度。它只数 prMerged,一个 20 个 target 的 shift 可能 18 个已完成但 completedCount 仍为 0——真实进度要看 statusBreakdown。
  2. 重跑会覆盖结果。每个 target 只保留最近一次运行,重跑一个 jobComplete 的 target 后,若新运行失败,旧结果将无法再用于开 PR。所以惯例是先 fleetshift-create-prs 开 PR,再考虑重跑。
  3. 日志只保留 30 天。get-job-status 本身不带失败原因,日志是唯一依据;updatedAt 超过 30 天的失败 target 会查不到归档日志,只能重跑取证。

五、运行时的有界监控与急停

fleetshift-run-shift 工作流(skills/fleetshift-run-shift/SKILL.md)永远不会无限等待:最多 10 次轮询、每次间隔不少于 30 秒、单个 shift 总时长上限 15 分钟;到达任一终态即停止轮询。

如果你中途改主意,"急停开关"三步走:停止继续触发、结束轮询、对尚未进入终态的 job 调用 fleetshift:stop-jobs,被叫停的 target 状态变为 stopped,可随时重跑。

六、延伸阅读:Fleetshift 五大技能

技能 用途 文档
创建 shift 起草并创建 shift 定义 skills/fleetshift-create-shift/SKILL.md
运行 shift 触发、有界监控、急停 skills/fleetshift-run-shift/SKILL.md
查看进度 只读状态与 PR 报告 skills/fleetshift-check-shift/SKILL.md
故障诊断 从状态与日志找根因 skills/fleetshift-troubleshoot-shift/SKILL.md
批量开 PR 为 jobComplete 目标开 PR skills/fleetshift-create-prs/SKILL.md

所有工作流的总览见 README.md。掌握这套状态机后,你只要记住一条主线:pending 等触发 → 结果五选一 → 只有 jobComplete 能走向 prOpen,最终 prMerged 才算闭环。

登录后查看全文
portal-ai-plugins