land

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Land

合入PR

Goals

目标

Ensure the PR is conflict-free with main.
Keep CI green and fix failures when they occur.
Squash-merge the PR once checks pass.
Do not yield to the user until the PR is merged; keep the watcher loop running unless blocked.
No need to delete remote branches after merge; the repo auto-deletes head branches.

确保PR与main分支无冲突。
保持CI运行正常，出现失败时及时修复。
所有检查通过后执行squash-merge合入PR。
PR合入完成前不要响应用户；持续运行监控循环，除非流程被阻塞。
合入后无需删除远程分支；仓库会自动删除head分支。

Preconditions

前置条件

```
gh
```
CLI is authenticated.
You are on the PR branch with a clean working tree.

```
gh
```
CLI已完成身份认证。
你当前处于PR对应的分支，工作树干净。

Steps

操作步骤

Locate the PR for the current branch.
Confirm the full gauntlet is green locally before any push.
If the working tree has uncommitted changes, commit with the
```
commit
```
skill and push with the
```
push
```
skill before proceeding.
Check mergeability and conflicts against main.
If conflicts exist, use the
```
pull
```
skill to fetch/merge
```
origin/main
```
and resolve conflicts, then use the
```
push
```
skill to publish the updated branch.
Ensure Codex review comments (if present) are acknowledged and any required fixes are handled before merging.
Watch checks until complete.
If checks fail, pull logs, fix the issue, commit with the
```
commit
```
skill, push with the
```
push
```
skill, and re-run checks.
When all checks are green and review feedback is addressed, squash-merge and delete the branch using the PR title/body for the merge subject/body.
Context guard: Before implementing review feedback, confirm it does not conflict with the user’s stated intent or task context. If it conflicts, respond inline with a justification and ask the user before changing code.
Pushback template: When disagreeing, reply inline with: acknowledge + rationale + offer alternative.
Ambiguity gate: When ambiguity blocks progress, use the clarification flow (assign PR to current GH user, mention them, wait for response). Do not implement until ambiguity is resolved.
- If you are confident you know better than the reviewer, you may proceed without asking the user, but reply inline with your rationale.
Per-comment mode: For each review comment, choose one of: accept, clarify, or push back. Reply inline (or in the issue thread for Codex reviews) stating the mode before changing code.
Reply before change: Always respond with intended action before pushing code changes (inline for review comments, issue thread for Codex reviews).

定位当前分支对应的PR。
推送前先确认本地所有检查全部通过。
如果工作树有未提交的变更，先使用
```
commit
```
技能提交，再用
```
push
```
技能推送，之后再继续后续操作。
检查与main分支的可合并性及冲突情况。
如果存在冲突，使用
```
pull
```
技能拉取/合并
```
origin/main
```
并解决冲突，之后使用
```
push
```
技能推送更新后的分支。
合入前确认已处理所有Codex评审意见（如有），并完成所有要求的修复。
监控所有检查直到运行完成。
如果检查失败，拉取日志，修复问题，使用
```
commit
```
技能提交，
```
push
```
技能推送，然后重新运行检查。
所有检查通过且评审反馈都已处理后，执行squash-merge，使用PR的标题/正文作为合并的主题/内容，然后删除分支。
上下文防护： 实现评审反馈前，确认其不会与用户声明的意图或任务上下文冲突。如果存在冲突，先回复说明理由，征求用户意见后再修改代码。
异议回复模板： 不认同评审意见时，按以下结构回复：知晓意见 + 说明理由 + 提供替代方案。
歧义处理门限： 当歧义导致流程无法推进时，使用澄清流程（将PR分配给当前GitHub用户，@提及对方，等待回复）。歧义解决前不要实现相关内容。
- 如果你明确判断自己的方案优于评审者的方案，可以无需征求用户意见继续推进，但需要回复说明理由。
单条评论处理模式： 对每条评审意见，选择以下一种处理方式：接受、澄清、驳回。修改代码前先在对应位置内联回复（Codex评审在issue线程中回复）说明处理模式。
变更前先回复： 推送代码变更前务必回复说明你计划采取的操作（评审意见在内联回复，Codex评审在issue线程回复）。

Commands

命令

undefined

undefined

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.

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.

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

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

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"

undefined

gh pr merge --squash --subject "$pr_title" --body "$pr_body"

undefined

Async Watch Helper

异步监控助手

Preferred: use the asyncio watcher to monitor review comments, CI, and head updates in parallel:

python3 .codex/skills/land/land_watch.py

Exit codes:

2: Review comments detected (address feedback)
3: CI checks failed
4: PR head updated (autofix commit detected)

推荐使用asyncio监控器并行监控评审意见、CI和head分支更新：

python3 .codex/skills/land/land_watch.py

退出码：

2：检测到评审意见（需要处理反馈）
3：CI检查失败
4：PR head分支已更新（检测到自动修复提交）

Failure Handling

故障处理

If checks fail, pull details with
```
gh pr checks
```
and
```
gh run view --log
```
, then fix locally, commit with the
```
commit
```
skill, push with the
```
push
```
skill, and re-run the watch.
Use judgment to identify flaky failures. If a failure is a flake (e.g., a timeout on only one platform), you may proceed without fixing it.
If CI pushes an auto-fix commit (authored by GitHub Actions), it does not trigger a fresh CI run. Detect the updated PR head, pull locally, merge
```
origin/main
```
if needed, add a real author commit, and force-push to retrigger CI, then restart the checks loop.
If all jobs fail with corrupted pnpm lockfile errors on the merge commit, the remediation is to fetch latest
```
origin/main
```
, merge, force-push, and rerun CI.
If mergeability is
```
UNKNOWN
```
, wait and re-check.
Do not merge while review comments (human or Codex review) are outstanding.
Codex review jobs retry on failure and are non-blocking; use the presence of
```
## Codex Review — <persona>
```
issue comments (not job status) as the signal that review feedback is available.
Do not enable auto-merge; this repo has no required checks so auto-merge can skip tests.
If the remote PR branch advanced due to your own prior force-push or merge, avoid redundant merges; re-run the formatter locally if needed and
```
git push --force-with-lease
```
.

如果检查失败，通过
```
gh pr checks
```
和
```
gh run view --log
```
拉取详情，然后在本地修复，使用
```
commit
```
技能提交，
```
push
```
技能推送，然后重新运行监控。
自行判断识别偶发失败。如果失败是偶发问题（例如仅单个平台超时），可以无需修复继续推进。
如果CI推送了自动修复提交（由GitHub Actions创建），不会触发新的CI运行。检测到PR head更新后，拉取到本地，必要时合并
```
origin/main
```
，添加一个真实作者的提交，强制推送重新触发CI，然后重启检查循环。
如果合并提交的所有任务都因pnpm lockfile损坏报错，修复方案是拉取最新的
```
origin/main
```
，合并，强制推送，重新运行CI。
如果可合并性状态为
```
UNKNOWN
```
，等待后重新检查。
还有未处理的评审意见（人工或Codex评审）时不要合入。
Codex评审任务失败后会自动重试，且不会阻塞流程；以是否存在
```
## Codex Review — <persona>
```
开头的issue评论（而非任务状态）作为评审反馈可用的信号。
不要开启自动合并；本仓库没有设置必须通过的检查，因此自动合并可能跳过测试。
如果远程PR分支因你之前的强制推送或合入已经更新，避免冗余合并；必要时在本地运行格式化工具，执行
```
git push --force-with-lease
```
即可。

Review Handling

评审处理

Codex reviews now arrive as issue comments posted by GitHub Actions. They start with
```
## Codex Review — <persona>
```
and include the reviewer’s methodology + guardrails used. Treat these as feedback that must be acknowledged before merge.
Human review comments are blocking and must be addressed (responded to and resolved) before requesting a new review or merging.
If multiple reviewers comment in the same thread, respond to each comment (batching is fine) before closing the thread.
Fetch review comments via
```
gh api
```
and reply with a prefixed comment.

Use review comment endpoints (not issue comments) to find inline feedback:

List PR review comments:

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

PR issue comments (top-level discussion):

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

Reply to a specific review comment:

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

```
in_reply_to
```
must be the numeric review comment id (e.g.,
```
2710521800
```
), not the GraphQL node id (e.g.,
```
PRRC_...
```
), and the endpoint must include the PR number (
```
/pulls/<pr_number>/comments
```
).
If GraphQL review reply mutation is forbidden, use REST.
A 404 on reply typically means the wrong endpoint (missing PR number) or insufficient scope; verify by listing comments first.
All GitHub comments generated by this agent must be prefixed with
```
[codex]
```
.
For Codex review issue comments, reply in the issue thread (not a review thread) with
```
[codex]
```
and state whether you will address the feedback now or defer it (include rationale).
If feedback requires changes:
- For inline review comments (human), reply with intended fixes (
```
[codex] ...
```
  ) as an inline reply to the original review comment using the review comment endpoint and
```
in_reply_to
```
  (do not use issue comments for this).
- Implement fixes, commit, push.
- Reply with the fix details and commit sha (
```
[codex] ...
```
  ) in the same place you acknowledged the feedback (issue comment for Codex reviews, inline reply for review comments).
- The land watcher treats Codex review issue comments as unresolved until a newer
```
[codex]
```
  issue comment is posted acknowledging the findings.
Only request a new Codex review when you need a rerun (e.g., after new commits). Do not request one without changes since the last review.
- Before requesting a new Codex review, re-run the land watcher and ensure there are zero outstanding review comments (all have
```
[codex]
```
  inline replies).
- After pushing new commits, the Codex review workflow will rerun on PR synchronization (or you can re-run the workflow manually). Post a concise root-level summary comment so reviewers have the latest delta:
```
[codex] Changes since last review:
- <short bullets of deltas>
Commits: <sha>, <sha>
Tests: <commands run>
```
- Only request a new review if there is at least one new commit since the previous request.
- Wait for the next Codex review comment before merging.

Codex评审现在以GitHub Actions发布的issue评论形式送达，开头为
```
## Codex Review — <persona>
```
，包含评审者使用的方法和防护规则。这些评论属于必须在合入前确认的反馈。
人工评审意见属于阻塞项，必须在请求新评审或合入前处理完成（回复并解决）。
如果多名评审者在同一个线程中评论，关闭线程前回复每条评论（可以批量回复）。
通过
```
gh api
```
拉取评审意见，使用带前缀的评论回复。

使用评审评论接口（而非issue评论接口）查找内联反馈：

列出PR评审评论：

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

PR issue评论（顶层讨论）：

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评审回复突变被禁止，使用REST接口。
回复时返回404通常意味着接口错误（缺少PR编号）或权限不足；先通过列出评论验证。
本Agent生成的所有GitHub评论都必须添加
```
[codex]
```
前缀。
对于Codex评审的issue评论，在issue线程（而非评审线程）中回复，前缀带
```
[codex]
```
，说明你将立即处理还是延后处理该反馈（包含理由）。
如果反馈需要修改代码：
- 对于内联人工评审评论，作为原评审评论的内联回复，使用评审评论接口和
```
in_reply_to
```
  参数回复你计划的修复方案（
```
[codex] ...
```
  ），不要使用issue评论回复。
- 实现修复，提交，推送。
- 在你之前确认反馈的同一位置回复修复详情和提交sha（
```
[codex] ...
```
  ）：Codex评审在issue评论回复，评审意见在内联回复。
- 合入监控器会将Codex评审的issue评论视为未处理，直到发布了更新的
```
[codex]
```
  前缀的issue评论确认收到反馈为止。
仅当你需要重新运行评审时（例如新提交后）才请求新的Codex评审。自上次评审后没有变更时不要请求新评审。
- 请求新的Codex评审前，重新运行合入监控器，确保没有未处理的评审意见（所有意见都有
```
[codex]
```
  内联回复）。
- 推送新提交后，Codex评审工作流会在PR同步时重新运行（你也可以手动重新运行工作流）。发布一条简洁的顶层汇总评论，方便评审者查看最新变更：
```
[codex] Changes since last review:
- <short bullets of deltas>
Commits: <sha>, <sha>
Tests: <commands run>
```
- 仅当自上一次评审请求后至少有一个新提交时才请求新评审。
- 合入前等待下一条Codex评审评论。

Scope + PR Metadata

范围与PR元数据

The PR title and description should reflect the full scope of the change, not just the most recent fix.
If review feedback expands scope, decide whether to include it now or defer it. You can accept, defer, or decline feedback. If deferring or declining, call it out in the root-level
```
[codex]
```
update with a brief reason (e.g., out-of-scope, conflicts with intent, unnecessary).
Correctness issues raised in review comments should be addressed. If you plan to defer or decline a correctness concern, validate first and explain why the concern does not apply.
Classify each review comment as one of: correctness, design, style, clarification, scope.
For correctness feedback, provide concrete validation (test, log, or reasoning) before closing it.
When accepting feedback, include a one-line rationale in the root-level update.
When declining feedback, offer a brief alternative or follow-up trigger.
Prefer a single consolidated "review addressed" root-level comment after a batch of fixes instead of many small updates.
For doc feedback, confirm the doc change matches behavior (no doc-only edits to appease review).

PR标题和描述应反映变更的完整范围，而不仅仅是最近的修复。
如果评审反馈扩大了范围，自行决定是现在纳入还是延后处理。你可以接受、延后或驳回反馈。如果选择延后或驳回，在顶层
```
[codex]
```
更新中说明简短理由（例如超出范围、与意图冲突、非必要）。
评审意见中提出的正确性问题必须处理。如果你计划延后或驳回正确性相关的问题，先验证并说明该问题不适用的理由。
将每条评审意见分类为：正确性、设计、风格、澄清、范围。
对于正确性反馈，关闭前提供具体的验证依据（测试、日志或推理）。
接受反馈时，在顶层更新中加入一行说明理由。
驳回反馈时，提供简短的替代方案或后续触发条件。
批量修复完成后，优先发布一条统一的“评审已处理”顶层评论，而非多条小更新。
对于文档反馈，确认文档变更与实际行为一致（不要为了满足评审要求只修改文档）。