SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场relay-merge

relay-merge

部署与运维

查看项目

更新于 10-16 03:23

技能介绍

用途

relay-merge 用于在 relay-review 记录通过结论后，显式合并一次 Relay 运行。它仅适用于受支持的 GitHub 路径。本地 Reviewed Result 通过规范恢复流程关闭，不会进入此技能。合并始终是操作员的显式动作；审查绕过和可变状态覆盖不属于 Relay 契约。

主要能力

  • 只读门禁校验：调用规范 Relay inspect，除非以下各项指向同一提交，否则失败关闭：实时 GitHub PR 头与远程分支；保留工作树 HEAD 与 Git 树；持久化 PR 事实；通过的验证事实；独立审查事实与冻结的 Done Criteria 哈希。
  • 显式合并与清理：在获取 run-lock 后重复检查，发出持久化合并授权，调用 GitHub，重新校验精确合并的 PR，并追加一条 merge_recorded 事实，随后移除干净的关联工作树。
  • 幂等重试：授权与合并回执使重试在崩溃后保持幂等。中断后使用相同的 actor 和方法重新运行同一命令。
  • 合并队列处理：GitHub 可能将请求接受到合并队列而 PR 仍处于打开状态，此时返回 status: merge_pending；重跑会观察持久化的待处理请求而不会再次提交，仅在 GitHub 报告精确审查头已合并后才记录合并。
  • 崩溃安全：在外部调用前立即 fsync 一个不可变请求意图。若崩溃留下该意图但 GitHub 证明既无精确合并也无排队请求，finalize 以 ambiguous-outcome 错误失败，要求规范恢复，而不是冒险重复调用。
  • 基线校验：最终预检重新检查不可变的配置基线与源 SHA。若审查后基线提交前进，finalize 要求已审查基线为其祖先，并将精确审查的 Git 路径集与 GitHub 的基线前进路径比较。零重叠仍可合并；重叠则类型化失败，要求将分支更新到当前基线，然后进行规范验证。

使用方式

输入包括：不可变的 Relay run.json 与仅追加的 events.jsonl；保留的运行工作树及其精确打开的 PR；--run-id 或显式 --run-dir；可选的不透明操作员身份、合并方法和操作 id。

步骤 1：只读门禁

RUN_ID=<run-id-from-dispatch>
node "${RELAY_SKILL_ROOT:-skills}/relay-merge/scripts/gate-check.js" \
  --repo . --run-id "$RUN_ID" --json

如果推导出的动作不是 merge，则遵循该动作。切勿从 PR 评论、已退役状态或缺失证据合成合并覆盖。

步骤 2：显式合并与清理

node "${RELAY_SKILL_ROOT:-skills}/relay-merge/scripts/finalize-run.js" \
  --repo . --run-id "$RUN_ID" --merge-method squash --json

finalize-run.js 在获取 run-lock 后重复检查，发出持久化合并授权，调用 GitHub，重新校验精确合并的 PR，并追加一条 merge_recorded 事实。随后移除干净的关联工作树。脏、已更改、未注册或仓库不匹配的工作树会被保留，而不是强制移除。Finalize 不调用 GitHub REST /user 端点；--actor 记录合并操作员。

持久化授权值是权威的；更改任一值会在另一次 GitHub 合并请求前失败。当操作员需要稳定的外部记录关联 id 时，使用 --operation-id <id>。--no-cleanup 有意保留工作树；之后的普通重跑会执行终端清理而不会再次合并。

步骤 3：可选的合并后项目更新

append-learnings.js 和 dev-backlog sprint 更新是独立的项目变更。在 finalize-run.js 返回 status: merged 后显式运行它们；它们不属于合并事务。

参见 references/append-learnings.md 了解标记边界的学习写入器，references/operator-emergencies.md 了解恢复指南。序列化全套门禁指南位于 references/full-gate.md。

适用场景

适用于受支持的 GitHub 路径上、已通过独立审查并记录通过结论的 Relay 运行合并。

限制

  • 仅适用于受支持的 GitHub 路径。
  • 合并始终是操作员的显式动作，不支持审查绕过或可变状态覆盖。
  • GitHub 合并 API 提供原子 expected-source-SHA 守卫（--match-head-commit），但没有 expected-base compare-and-swap。因此请求前检测到的基线重定向会失败关闭，而剩余的后检查/请求前基线纳米竞态（外部协作者更改 PR 元数据）是已记录的 GitHub 平台威胁边界，不是弱化的源 SHA 或配置基线不变量。
  • 请求后的合并队列/基线移动会在恢复时重新检查，但 Relay 无法撤销外部已完成的合并。
  • 路径重叠是代理指标，跨不同路径的语义冲突仍在此证明之外。
  • GitHub compare 将文件证据上限设为 300 条；该边界和不完整的提交分页会失败关闭。
  • 脏、已更改、未注册或仓库不匹配的工作树会被保留，而不是强制移除。