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合并。
在PR合并完成前不要中断流程；除非遇到阻塞，否则保持监控循环运行。
合并后无需删除远程分支；仓库会自动删除头部分支。

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
```
技能推送，之后再继续流程。
检查PR与main分支的可合并性及冲突情况。
若存在冲突，使用
```
pull
```
技能拉取/合并
```
origin/main
```
并解决冲突，然后用
```
push
```
技能推送更新后的分支。
确保Codex评审评论（若存在）已得到确认，且所有必要的修复已完成，再进行合并。
监控检查直至完成。
若检查失败，拉取日志、修复问题、用
```
commit
```
技能提交、
```
push
```
技能推送，然后重新运行检查。
当所有检查通过且评审反馈已处理完成后，执行squash合并并删除分支，合并的主题和正文使用PR的标题和内容。
上下文防护： 在处理评审反馈前，确认其与用户明确的意图或任务上下文无冲突。若存在冲突，需在回复中说明理由，并在修改代码前征得用户同意。
异议回复模板： 当存在不同意见时，在回复中包含：确认反馈 + 理由说明 + 替代方案建议。
歧义处理： 若因歧义导致流程阻塞，使用澄清流程（将PR分配给当前GitHub用户，@他们并等待回复）。在歧义解决前不要进行任何修改。
- 若你确信自己的方案更优，可无需询问用户直接执行，但需在回复中说明理由。
逐条评论处理模式： 对每条评审评论，选择以下三种处理方式之一：接受、澄清或提出异议。在修改代码前，需在对应位置（或Codex评审的 issue 线程中）回复说明处理方式。
先回复再修改： 推送代码变更前，务必先说明计划执行的操作（针对评审评论用 inline 回复，针对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 .agents/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检查和PR头部分支更新：

python3 .agents/skills/land/land_watch.py

退出码说明：

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

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头部分支更新后，拉取到本地，若需要则合并
```
origin/main
```
，添加一个真实作者的提交，然后强制推送以重新触发CI，之后重启检查循环。
若合并提交的pnpm锁文件损坏导致所有任务失败，解决方法是拉取最新的
```
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评论端点）查找inline反馈：

列出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]
```
，并说明当前会处理反馈还是延后处理（需包含理由）。
若反馈需要修改：
- 对于人工的inline评审评论，需在原评论的inline回复中说明计划的修复内容（
```
[codex] ...
```
  ）（请勿使用issue评论进行此操作）。
- 实施修复、提交、推送。
- 在确认反馈的位置（Codex评审用issue评论，评审评论用inline回复）回复修复详情和提交SHA（
```
[codex] ...
```
  ）。
- 落地监控工具会将Codex评审的issue评论视为未解决状态，直到发布新的
```
[codex]
```
  issue评论确认已处理相关发现。
仅当需要重新运行评审时（如提交新代码后）才请求新的Codex评审。自上次评审后无代码变更时，请勿请求新评审。
- 请求新的Codex评审前，重新运行落地监控工具，确保所有评审评论都已处理（均有
```
[codex]
```
  inline回复）。
- 推送新提交后，Codex评审工作流会在PR同步时自动重新运行（也可手动重新运行工作流）。发布一个简洁的顶层汇总评论，让评审者了解最新的变更：
```
[codex] 自上次评审后的变更：
- <变更内容简短列表>
提交：<sha>, <sha>
测试：<执行的命令>
```
- 仅当自上次请求后至少有一个新提交时，才请求新评审。
- 等待下一条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]
```
更新中说明简要理由（如超出范围、与意图冲突、无必要）。
评审中提出的正确性问题必须处理。若计划延后或拒绝正确性相关的反馈，需先验证并解释为何该问题不适用。
将每条评审评论归类为以下类型之一：正确性、设计、风格、澄清、范围。
对于正确性相关的反馈，需提供具体的验证（测试、日志或推理）后再标记为已解决。
若接受反馈，需在顶层更新中包含一行简短理由。
若拒绝反馈，需提供简短的替代方案或后续触发条件。
批量修复后，优先发布一条整合的“评审反馈已处理”顶层评论，而非多条小更新。
对于文档相关的反馈，需确认文档变更与实际行为一致（不要仅为了满足评审而修改文档）。