land

Land

目标

• 确保 PR 与 main 没有冲突。
• 保持 CI 全绿，出现失败时及时修复。
• 检查通过后，以 squash 方式合并 PR。
• PR 合并前不要结束与用户的交互；除非遇到阻碍，否则持续运行监视循环。
• 合并后无需删除远程分支；仓库会自动删除 head 分支。

前提条件

• gh CLI 已通过身份验证。
• 当前位于 PR 分支，且工作区干净。

步骤

1. 查找当前分支对应的 PR。
2. 推送前，确认本地完整测试流程全部通过。
3. 如果工作区有未提交的更改，使用 commit 技能提交，并使用 push 技能推送，然后再继续。
4. 检查与 main 的合并状态及冲突。
5. 如果存在冲突，使用 pull 技能获取并合并 origin/main，解决冲突后，再使用 push 技能发布更新后的分支。
6. 合并前，确保已确认 Codex 审查评论（如有），并处理所有必需的修复。
7. 持续监视检查，直到全部完成。
8. 如果检查失败，获取日志、修复问题、使用 commit 技能提交、使用 push 技能推送，然后重新运行检查。
9. 所有检查通过且审查反馈已处理后，使用 PR 标题和正文作为合并主题和正文，以 squash 方式合并，并删除分支。
10. 上下文检查： 实施审查反馈前，确认其不会与用户表达的意图或任务上下文冲突。如果存在冲突，请在评论中说明理由，并先征求用户意见，再修改代码。
11. 异议模板： 有不同意见时，在评论中回复：表示理解 + 说明理由 + 提供替代方案。
12. 歧义门槛： 如果存在阻碍进展的歧义，使用澄清流程（将 PR 指派给当前 GitHub 用户并提及该用户，然后等待回复）。歧义解决前不要实施更改。
    • 如果你确信自己比审查者更了解情况，可以不询问用户，直接继续，但要在评论中说明理由。
13. 逐条评论处理模式： 对每条审查评论，选择以下一种方式：接受、澄清或提出异议。修改代码前，先在评论中回复（Codex 审查则在议题讨论串中回复），说明所选模式。
14. 先回复再更改： 推送代码更改前，务必先说明打算采取的行动（审查评论在评论中回复，Codex 审查在议题讨论串中回复）。

命令

# Ensure branch and PR context
branch=$(git branch --show-current)
pr_number=$(gh pr view --json number -q .number)
pr_title=$(gh pr view --json title -q .title)
pr_body=$(gh pr view --json body -q .body)

# Check mergeability and conflicts
mergeable=$(gh pr view --json mergeable -q .mergeable)

if [ "$mergeable" = "CONFLICTING" ]; then
  # Run the `pull` skill to handle fetch + merge + conflict resolution.
  # Then run the `push` skill to publish the updated branch.
fi

# Preferred: use the Async Watch Helper below. The manual loop is a fallback
# when Python cannot run or the helper script is unavailable.
# Wait for review feedback: Codex reviews arrive as issue comments that start
# with "## Codex Review — <persona>". Treat them like reviewer feedback: reply
# with a `[codex]` issue comment acknowledging the findings and whether you're
# addressing or deferring them.
while true; do
  gh api repos/{owner}/{repo}/issues/"$pr_number"/comments \
    --jq '.[] | select(.body | startswith("## Codex Review")) | .id' | rg -q '.' \
    && break
  sleep 10
done

# Watch checks
if ! gh pr checks --watch; then
  gh pr checks
  # Identify failing run and inspect logs
  # gh run list --branch "$branch"
  # gh run view <run-id> --log
  exit 1
fi

# Squash-merge (remote branches auto-delete on merge in this repo)
gh pr merge --squash --subject "$pr_title" --body "$pr_body"

异步监视辅助工具

首选：使用 asyncio 监视器并行监控审查评论、CI 和 head 更新：

python3 .agents/skills/land/land_watch.py

退出代码：

• 2：检测到审查评论（处理反馈）
• 3：CI 检查失败
• 4：PR head 已更新（检测到自动修复提交）

失败处理

• 如果检查失败，请使用 gh pr checks 和 gh run view --log 获取详细信息，然后在本地修复，使用 commit 技能提交，使用 push 技能推送，再次运行监视。
• 请自行判断失败是否为偶发故障。如果是偶发故障（例如，仅有一个平台超时），可以不修复，继续进行。
• 如果 CI 推送了自动修复提交（由 GitHub Actions 编写），不会触发新的 CI 运行。检测 PR 的最新提交，拉取到本地，必要时合并 origin/main，添加一个由真实作者编写的提交，然后强制推送以重新触发 CI，再重新开始检查循环。
• 如果合并提交上的所有作业都因 pnpm 锁文件损坏错误而失败，解决方法是获取最新的 origin/main，执行合并，强制推送，然后重新运行 CI。
• 如果可合并状态为 UNKNOWN，请等待后重新检查。
• 如果仍有待处理的评审评论（来自人工或 Codex 评审），请勿合并。
• Codex 评审作业会在失败时重试，且不会阻塞流程；请以是否存在 ## Codex Review — <persona> 问题评论作为评审反馈是否可用的信号，而非作业状态。
• 请勿启用自动合并；此代码库没有必需的检查，因此自动合并可能跳过测试。
• 如果远程 PR 分支因你之前的强制推送或合并而前进，请避免重复合并；如有需要，在本地重新运行格式化程序，然后执行 git push --force-with-lease。

审查处理

• Codex 审查现在会以 GitHub Actions 发布的问题评论形式到达。这些评论以 ## Codex Review — <persona> 开头，并包含审查者采用的方法和防护措施。合并前必须确认已处理这些反馈。
• 人工审查评论具有阻塞性，必须在请求新的审查或合并前予以处理（回复并解决）。
• 如果多个审查者在同一讨论串中发表评论，请在关闭讨论串前逐条回复（可以批量回复）。
• 通过 gh api 获取审查评论，并使用带前缀的评论进行回复。
• 使用审查评论端点（而不是问题评论）查找行内反馈：
  • 列出 PR 审查评论：

    gh api repos/{owner}/{repo}/pulls/<pr_number>/comments
    

  • PR 问题评论（顶层讨论）：

    gh api repos/{owner}/{repo}/issues/<pr_number>/comments
    

  • 回复特定审查评论：

    gh api -X POST /repos/{owner}/{repo}/pulls/<pr_number>/comments \
      -f body='[codex] <response>' -F in_reply_to=<comment_id>
    

• in_reply_to 必须是数字形式的审查评论 id（例如 2710521800），而不能是 GraphQL 节点 id（例如 PRRC_...），且端点必须包含 PR 编号（/pulls/<pr_number>/comments）。
• 如果 GraphQL 审查回复 mutation 被禁止，请使用 REST。
• 回复时出现 404 通常意味着端点错误（缺少 PR 编号）或权限范围不足；请先验证能否列出评论。
• 此 Agent 生成的所有 GitHub 评论都必须以 [codex] 为前缀。
• 对于 Codex 审查的问题评论，请在问题讨论串中回复（而非审查讨论串），使用 [codex]，并说明你会立即处理反馈还是暂缓处理（包括理由）。
• 如果反馈要求进行更改：
  • 对于行内审查评论（人工），使用审查评论端点和 in_reply_to，以行内回复形式回复原始审查评论，说明计划进行的修复（[codex] ...）；不要使用问题评论进行回复。
  • 实施修复、提交并推送。
  • 在确认反馈时的同一位置回复修复详情和提交 sha（[codex] ...）（Codex 审查使用问题评论，审查评论使用行内回复）。
  • Land watcher 会将 Codex 审查的问题评论视为未解决，直到发布一条更新的 [codex] 问题评论确认相关发现。
• 只有在需要重新运行审查时（例如提交新代码后）才请求新的 Codex 审查。若自上次审查后没有更改，不要请求新的审查。
  • 请求新的 Codex 审查前，重新运行 land watcher，并确保没有待处理的审查评论（所有评论均已收到 [codex] 行内回复）。
  • 推送新提交后，Codex 审查工作流会在 PR 同步时重新运行（也可以手动重新运行工作流）。请发布一条简洁的根级摘要评论，让审查者了解最新变更：

    [codex] 自上次审查以来的更改：
    - <简短列出变更>
    提交：<sha>、<sha>
    测试：<运行的命令>
    

  • 只有在上次请求后至少有一个新提交时，才请求新的审查。
  • 合并前等待下一条 Codex 审查评论。

范围 + PR 元数据

• PR 标题和描述应体现变更的完整范围，而不只是最近一次修复。
• 如果评审反馈扩大了范围，请决定现在纳入还是推迟处理。你可以接受、推迟或拒绝反馈。如果推迟或拒绝，请在根目录级别的 [codex] 更新中说明，并简要给出原因（例如：超出范围、与意图冲突、不必要）。
• 应解决评审评论中提出的正确性问题。如果计划推迟或拒绝某项正确性问题，请先验证，再解释为何该问题不适用。
• 将每条评审评论归类为以下类型之一：正确性、设计、风格、澄清、范围。
• 对于正确性反馈，在关闭问题前提供具体验证（测试、日志或推理）。
• 接受反馈时，请在根目录级别的更新中用一行说明理由。
• 拒绝反馈时，请简要说明替代方案或后续触发条件。
• 一批修复完成后，优先使用一条整合的“已处理评审意见”根目录级评论，而不是发布多条零散更新。
• 对于文档反馈，请确认文档变更与实际行为一致（不要仅为迎合评审而只改文档）。