delivery

Files (4)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• projects.md · references/

SKILL.md (first lines)

# Delivery

把已准备的改动或已发布版本交付到用户指定的终点。独立于 Devflow；研发证据可以来自 Devflow、其它工作流或项目原有检查。

## 范围与入口

接受自然语言，例如 `$delivery 提交并推送，不发布`、`$delivery 创建 PR 并合并 main`、`$delivery 发布并升级远端`、`$delivery 将已发布 vX.Y.Z 升级到指定环境`。版本、项目和环境必须来自请求或当前可核对的事实，不从示例补默认值。

| 用户意图 | 默认终点 |
| --- | --- |
| 提交并推送 | 指定改动的 commit 已推到指定 remote/branch；不自动创建 PR 或改版本 |
| 创建 PR | 指定 head/base 的 PR 已创建；不自动合并 |
| 合并 main | 验证通过的目标 PR/改动已合入主分支；不发布 |
| 发布 / 提交并发布 | 按项目约定准备版本元数据并发布 tag、Release 和产物；不升级运行环境 |
| 发布并升级远端 | 发布完成，再通过项目入口升级明确环境并验收 |
| 升级 | 升级已经发布的目标版本并验收；目标未发布时不得自动补做发布 |

这些是独立授权边界，不能从前一阶段推断后一阶段。已明确授权的阶段连续完成，不重复确认；缺少必要前置阶段的授权时，先完成可审阅准备，再在相应边界停下。生产写入、服务变更或升级需明确授权；指定环境或终点有实质歧义时先完成无依赖的只读检查，再确认缺项。交付授权不包含交易、通知、账本写入或顺手修复其它业务问题。

## 绑定项目与实际入口

1. 读当前项目 `AGENTS.md`、Git 状态、remote、分支/base、完整待交付文件清单、现有验证记录，以及本阶段涉及的脚本/workflow。保护无关 dirty changes，不默认 `git add -A`、强推或直推受保护主分支。
2. 复用现有工作区；只有共享/受保护分支、无关脏改动或并行冲突需要隔离时才建 worktree。记录原状态，后续沿用，不每阶段重建。 本地 Git 源码交付先刷新目标 remote 的主分支引用，记录本地主分支 ahead/behind；新任务基于已刷新且核对过的远端基线，不从落后的本地 main 创建工作分支。
3. 从项目约定找到版本真源、预检、CI、发布、升级和验收入口；对将执行的入口确认真实行为，尤其区分只读预览与会准备 checkout/依赖的安装计划。OM/PM 的定位提示在 [项目入口](references/projects.md)，只在对应项目读取；当前源码与项目约定优先。
4. 交付前检查本次迭代是否影响 README 的项目定位、能力与边界、核心能力、工作方式、快速开始或文档导航；涉及任一部分，就依据当前实现同步更新对应章节及其引用的详细文档，并纳入同一交付和适用验证。无影响时不改；交付阶段发现遗漏时，补正文档后仅重做失效的检查。
5. 项目缺少必要入口或凭证时报告具体缺项，不临时搭建发布系统、自动安装工具或绕过检查。需要新研发工作时保留交付状态，按授权单独处理，不自动启动 Devflow 或扩大修复范围。

## 证据复用与执行

复用的是完整、可回读且适用的证据。核对实际内容（包括未提交文件）、review base、范围、实现批准依据、依赖语义和验证环境；不能只凭 commit SHA、摘要或一句 pass。内容和条件未变时，不因提交、创建 PR、恢复会话或写总结重跑研发验证/评审。

内容、base、配置、依赖或验证环境变化时重做失效检查。必须进行的新评审依照项目/用户要求覆盖完整当前范围，不能只看冲突文件。保留项目强制 CI、发布产物检查和远端验收；本地测试不证明 CI 或远端健康。Skill 不额外强制调用 planreview/deepreview，也不取消原有强制评审。

| 阶段 | 执行与退出证据 |
| --- | --- |
| 提交/推送 | 核对暂存 diff 仅包含授权范围，完成项目所需验证；一次提交并推送已授权目标。记录 commit 和远端 ref，确认远端实际包含本次提交。 |
| PR/合并 | 按 repo/head/base 查询现有 PR，复用匹配项；创建前准备具体标题、范围和验证说明。合并前刷新实际 PR head、base、required checks、review/merge 状态，绑定通过检查的提交；使用平台支持的 head 匹配条件，避免检查后提交变化仍被合并。合并后核验 merged 状态及实际主分支结果。 |
| 发布 | 按版本真源更新必要元数据，沿项目规定的提交/PR/CI路径发布，不自行绕开保护。先查询目标 tag/Release：同一已完成目标核验后复用；tag 指向冲突或产物不完整不能算成功，也不覆盖/重打 tag。退出需证明目标 commit、tag、Release 发布状态及项目要求的产物一致。 |
| 升级 | 先核验已发布目标和明确环境，执行项目支持的预览/预检，再执行已授权升级。保留锁、回滚、配置/依赖检查和服务策略；独立核验实际 active 版本/路径、所需服务健康及项目要求的其它验收。单个 install/apply 成功不是整个升级完成。 |

若发现 CI 或检查失败，先读实际失败原因；已授权范围内的必要小修复和验证继续执行，范围/行为/权限变化则交还用户决策。失败期间不推进依赖该结果的阶段，也不反复创建 PR、发布或安装同一目标。

## 端到端耗时

从用户提出本次交付请求开始计时，到授权终点验收和必要收尾结束；不要把远端 apply 的耗时当作整次交付耗时。沿用交接记录，记各阶段开始/结束时间和证据，区分执行、CI/外部等待、用户等待；并行阶段不能相加当总耗时。缺失时间标为 unknown，不从进度文案推算精确命令耗时。

- 开始时一次绑定授权阶段、发布目标和环境；无法核实的生产目标尽早询问，同时推进不依赖该答案的准备。已有明确授权连续执行，预览一致后不再人为增加确认轮次；审批拒绝仍按实际原因处理。
- 先检查验证环境，再启动昂贵预检：使用项目支持的解释器，核对测试要求的 checkout 内 `.venv`、Node、依赖和隔离路径。解释器可用不代表固定路径契约满足。已准备的隔离工作区贯穿发布，不在后续阶段重新安装和重新测试。
- 项目提供只读测试计划入口时，迭代阶段先按计划选择定向检查，并执行其要求的高风险检查；发布元数据定稿后集中运行项目要求的完整本地预检一次。后续只因明确的证据失效重跑；环境修复确实影响全量证据时仍重跑。不能因为定向重试通过就抹掉首轮失败，也不能因改动看似只有文档便跳过项目门禁。
- 等待已绑定的 CI/Release 时，批量完成独立的只读工作，例如核对远端版本、入口能力、服务清单和准备验收命令。发布产物未验证前不升级；不同项目的生产写入不默认并行。可复用入口事实，但切换前需刷新易变的 active 版本、锁和配置事实。
- 同一批独立只读查询合并执行并逐项保留结果；依赖步骤仍串行。CI 使用下文原生等待，完成后立即推进，不额外固定 sleep；恢复原 handle，不另起 watcher。合并和发布推进主分支时，收尾同步到最终已接受目标一次，避免每个中间提交都重复同步、清理。
- 最终报告总墙钟耗时、主要耗时阶段及阻塞；没有实际新一轮交付数据时，只报告流程已优化，不承诺节省比例。若主要时间在强制 CI，指出对应 workflow/job，不能靠缩短轮询或取消必需检查宣称解决。

## 本地主分支同步

GitHub 合并、fetch 和本地 main 更新是三件事；linked worktrees 共享引用，主工作区不会随 PR 合并自动快进。这里的 ahead/behind 是提交数，不是发布版本数。

本任务合并或发布推进远端主分支后，或用户明确要求同步本地时，将以下核验作为交付收尾项。只处理本机研发 checkout；固定 tag 的 release 目录及远端运行环境不在此步骤执行 pull/merge。

1. 刷新正确 remote，核验本地与远端主分支（按项目可能不是 `main`），用 `git worktree list --porcelain` 定位实际检出它的工作区；不在任务分支上误执行主分支 merge，不为同步每次新建 worktree。
2. 本地无独有提交且落后时才自动快进。主分支已被检出且无活动任务占用时，在该工作区运行 `git -c merge.autoStash=false merge --ff-only <已核验远端目标>`；主分支未被任何 worktree 检出时，可用不带强制标记的 `git fetch <remote> <主分支>:<主分支>` 做原生快进更新。
3. 已跟踪文件或 index 有未提交修改、本地有独有提交/分叉、活动 owner 或状态不明时保留现场，记录 `local_main_sync=blocked` 和原因；不自动 stash、reset、rebase、clean 或强改引用。仅有未跟踪文件时，先确认其路径与快进改动不冲突，快进后核验它们保持原样；不因不相关的 `assets/` 一概跳过同步。Git 拒绝更新时保留失败结果，不加 force 重试。
4. 核验本地 SHA 与本次刷新并接受的远端目标一致、ahead/behind 为 0/0，再记录 `local_main_sync=passed`。记录主工作区、双方 SHA 和剩余 dirty 状态；并发远端更新不靠无限循环追赶，明确核验的目标和时间。不适用时记录原因，不能虚构 passed。

远端合并/发布成功和本地同步阻塞分开报告；阻塞未处理前不得笼统声称“交付收尾全部完成”。后续仅恢复本地同步，不能因此重做已完成的 PR、发布或升级。

## 输出与等待

大量输出保存到唯一的私有日志或项目已有 artifact。入口支持 `--report-dir` 等报告模式时先确认该版本支持，再使用；否则重定向日志并显式保留真实退出码，不能让 `tee`、`tail`、`|| true` 的结果掩盖失败。成功时摘要，失败时按线索读取原始日志；截断证据不算覆盖。日志和报告沿用项目权限/脱敏规则，避免回传凭证。

CI 优先用原生等待。先把 run 绑定到正确 repo、workflow、目标 SHA/tag 和当前 attempt，再用 `gh run watch "$RUN_ID" --exit-status --interval 30`；可用时加 `--compact`，保存输出并记录真实退出码。一次 run 成功不代替其它 required checks。只在失败后读取必要 job 日志；不持续唤醒模型重复查询相同状态。

异步任务保存原 handle/run id，优先完成通知、增量输出和原生等待；确需轮询则约 30 秒起步，无变化退避至约 60 秒，并遵守工具限制和宿主进度更新要求。返回运行状态、等待超时或连接中断都不等于失败终止或成功。

## 恢复与统一交接

在现有任务摘要或交付 artifact 中维护一份短记录，无需新数据库、常驻服务或通用执行器：

- `stage`：commit / pr / merge / release / upgrade / verify；`status`：running / passed / failed / unknown / blocked；
- `target`：repo、实际 head/base、commit/tag、运行环境（不适用字段省略）；
- `authorized_scope`：本次已授权阶段与目标；
- `evidence`：验证记录、PR/run/任务 id、日志和项目原始报告路径；
- `exit_code`、`failed_step`、`next_action`：实际结果和下一动作，不确定时明确 unknown。

这是交接格式，保留项目原始 JSON，不要求为了统一命名改写现有命令的响应协议。归一化时不能丢掉失败原因、回滚状态、已写入结果或跳过检查。

恢复先查实际状态：推送查远端 ref，PR 查 head/base 与合并状态，发布查 tag/Release/产物，升级查原进程/锁/状态及 active 版本和服务。原任务仍在运行就等待；已完成就核验后继续；不确定就保持 unknown，只做状态查询。只有确认未生效或入口明确支持安全重试，才在原授权范围重试。原操作可能成功但报告写入失败时，先核实实际结果，不重放副作用；回滚同样遵循项目受控机制和授权，不能因网络中断直接触发。

最后简报实际完成阶段、commit/PR/tag/环境、验证结论、证据路径及未决事项。仅在项目清理条件满足、无活动 owner、工作区干净且改动确认已合入时清理本任务 worktree；保留未合并或脏改动。达到用户授权终点即完成，不追加发布、升级或研发确认门。

From liuxie066/liuxie-skills, MIT.

More from liuxie066/liuxie-skills