xudong-code-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xudong Code Review

Xudong Code Review

Run the bundled structured review helper only when the user explicitly asks for xudong-code-review, a Codex review, or an Antigravity review.
Codex is the default engine. Select Antigravity explicitly with
--engine antigravity
or its alias
--engine agy
. Use the helper defaults unless the user requests an override. Neither engine has a model fallback.
Do not invoke Xudong Code Review automatically before a commit, push, PR, merge, deploy, or final reply. Repository or workflow rules may call it only when they explicitly name it.
仅当用户明确要求
xudong-code-review
、Codex review 或 Antigravity review 时,才运行随附的结构化审查 helper。
Codex 是默认引擎。仅在明确需要时通过
--engine antigravity
或其别名
--engine agy
选择 Antigravity。除非用户要求覆盖配置,否则使用 helper 的默认值。两个引擎均没有模型 fallback。
不要在 commit、push、PR、merge、deploy 或最终回复之前自动调用 Xudong Code Review。Repository 或 workflow 规则仅在明确点名调用它时才可以调用。

Contract

约定

  • Default output includes P0 through P2 findings. Use
    --max-priority P0
    or
    P1
    to narrow the review, or
    P3
    when the caller explicitly asks for a wider review.
  • Treat review output as advisory. Never blindly apply it.
  • Verify every finding by reading the real code path and adjacent files.
  • Read dependency docs/source/types when the finding depends on external behavior.
  • Reject unrealistic edge cases, speculative risks, unrelated rewrites, and fixes that over-complicate the codebase.
  • Prefer root-cause fixes at the right ownership boundary. A coherent refactor is appropriate when it removes the bug class, duplicate policy, stale paths, or ownership confusion; do not default to a symptom patch.
  • When an accepted finding exposes a bug class or repeated pattern, inspect its owner and relevant sibling implementations before fixing.
  • Fix the same bug class across its owner-boundary neighborhood when practical; stop at unrelated invariants, different owners, and unapproved contract changes.
  • Run one bounded review pass. If an accepted finding changes code, run the smallest relevant test; rerun Xudong Code Review only when the user explicitly requests another pass.
  • For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
  • Never switch or override the requested review engine or model. Access, capacity, rate-limit, and unrelated failures are returned directly, without fallback.
  • Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search.
  • Treat heartbeat lines like
    review still running: ... elapsed=... pid=...
    as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass
    --stream-engine-output
    for live progress; tool/file chatter stays hidden.
  • Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish.
  • Tools are useful in review mode. Codex receives the validated bundle in an empty workspace so ignored files and linked-worktree metadata remain unreadable; web search stays available for dependency contracts and upstream docs.
  • Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check.
  • Reviewer subprocesses preserve engine authentication and non-credentialed proxy variables needed by headless or restricted-network environments while stripping process-injection, Git override, and credentialed proxy values.
  • Immediately before every provider call, xudong-code-review writes the exact outgoing review pack to an owner-only temporary file and scans it with TruffleHog using
    verified,unknown
    . The scan covers prompt and dataset inputs, untracked content, and every diff line, including deleted lines. A finding, scanner error, or missing TruffleHog binary refuses the send and names the implicated repository file when it can be resolved; credentials are never redacted and forwarded. Security-sensitive paths remain omitted. Safe large diffs are sent as one pass while they fit the aggregate prompt limit, then partitioned into complete bounded passes without truncation.
  • For regression provenance, keep roles separate: blamed code author, blamed PR author, PR merger/committer, current PR author, and PR/date. If no blamed PR is traceable, use the blamed commit as the provenance: commit SHA, date, and author username. Do not guess a merger or frame missing PR metadata as a separate finding.
  • Do not invoke built-in
    codex review
    , nested reviewers, or review panels from inside the review. The helper builds one validated bundle, calls the selected engine once for normal inputs or once per complete bounded chunk for oversized inputs, validates the structured results, and stops.
  • Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
  • Treat the helper's successful exit plus absence of actionable findings as the clean review result, even if the underlying Codex CLI output is terse.
  • If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
  • Do not push just to review. Push only when the user requested push/ship/PR update.
  • 默认输出包含 P0 至 P2 的审查发现。使用
    --max-priority P0
    或
    P1
    收窄审查范围,或在调用方明确要求更广泛的审查时使用
    P3
    。
  • 将审查输出视为建议。绝不要盲目应用。
  • 通过阅读真实代码路径及相邻文件来验证每项发现。
  • 如果某项发现依赖外部行为,请读取相关依赖项的文档、源代码或类型定义。
  • 拒绝不切实际的边缘情况、推测性风险、无关重写,以及会使代码库过度复杂化的修复。
  • 优先在正确的 owner boundary 修复根因。当连贯的重构能够消除某类缺陷、重复策略、失效路径或所有权混乱时,采用此类重构是合理的;不要默认只修补表象。
  • 当某项已接受的发现暴露出某类缺陷或重复模式时,修复前应检查其 owner 以及相关的同类实现。
  • 在可行的情况下,修复同一 owner boundary 范围内相同的缺陷类别;不要越界处理无关的不变量、不同 owner 或未经批准的契约变更。
  • 执行一次有界审查。如果某项已接受的发现导致代码变更,则运行最小相关测试;只有在用户明确要求再次审查时,才重新运行 Xudong Code Review。
  • 对于 security audit 抑制相关改动,验证已接受的发现仍可审计:被抑制的发现仍保留在结构化输出中,活跃输出保留不可抑制的抑制提示,汇总发现不得隐藏无关的活跃风险。
  • 绝不切换或覆盖所请求的审查引擎或模型。访问权限、容量、速率限制及无关故障将直接返回,不使用 fallback。
  • 对大型审查包要有耐心。结构化审查最长可能运行 30 分钟,尤其是在 model call 处于活跃状态并使用 Codex tools 或 web search 时。
  • 将
    review still running: ... elapsed=... pid=...
    之类的 heartbeat 输出视为健康进度,而不是卡死。只要 heartbeat 仍在推进,就让 helper 继续运行。使用
    --stream-engine-output
    获取实时进度;tool 和文件交互信息仍会隐藏。
  • 不要仅仅因为审查静默了 2 至 5 分钟,或因为它仍在 30 分钟窗口内运行,就终止审查。仅在连续缺失多个预期 heartbeat、运行超过 30 分钟或子进程明显失败后检查进程;应优先让同一个 helper 命令运行完毕。
  • Tools 在审查模式下很有用。Codex 在空白工作区中接收验证后的审查包,因此 ignored files 和 linked-worktree metadata 仍不可读取;web search 可用于查询依赖契约和上游文档。
  • 始终纳入安全视角,但不得因此妨碍合法功能。仅当变更引入了具体、可执行的风险,或移除了重要的安全检查时,才报告安全问题。
  • Reviewer 子进程会保留 headless 或受限网络环境所需的引擎认证及无凭据代理变量,同时移除进程注入、Git override 和携带凭据的代理值。
  • 每次调用 provider 前,xudong-code-review 都会将即将发送的完整审查包写入仅所有者可读的临时文件,并使用 TruffleHog 以
    verified,unknown
    模式进行扫描。扫描范围涵盖 prompt 和 dataset 输入、未跟踪内容,以及每一行 diff,包括已删除的行。如果发现凭据、扫描器报错或缺少 TruffleHog binary,则拒绝发送,并在能够解析时指出相关 repository 文件;凭据绝不会经过脱敏后继续转发。安全敏感路径仍会被省略。安全的大型 diff 在符合汇总 prompt 上限时作为一次审查发送,随后会被划分为完整的有界审查批次,且不会截断。
  • 对于回归来源,应明确区分各个角色:被归责代码的作者、被归责 PR 的作者、PR 合并者或 committer、当前 PR 作者,以及 PR 和日期。如果无法追溯被归责的 PR,则使用被归责 commit 作为来源:commit SHA、日期和作者用户名。不要猜测合并者,也不要将缺失的 PR 元数据视为单独的问题。
  • 不要在审查内部调用内置的
    codex review
    、嵌套 reviewer 或 review panel。Helper 会构建一个经过验证的审查包;对于普通输入调用所选引擎一次,对于超大输入则对每个完整的有界分块调用一次,随后验证结构化结果并停止。
  • 一旦 helper 以退出码 0 结束且没有已接受或可执行的问题,立即停止。不要为了获得更漂亮的“clean”结果、第二个意见或更清晰的结束说明而额外运行一次审查。
  • 即使底层 Codex CLI 输出较为简短,也应将 helper 成功退出且没有可执行问题视为干净的审查结果。
  • 如果因某项发现属于有意设计或不值得修复而拒绝它,仅当行内代码注释能够说明未来 reviewer 需要了解的真实不变量或所有权决策时,才添加简短注释。
  • 不要仅为进行审查而 push。仅当用户要求 push、ship 或更新 PR 时才执行 push。

Scope

范围

Xudong Code Review does not expand the task. Fix only verified blockers in the requested path. Mention unrelated findings without opening a new workstream, and stop when the requested review pass is complete.
Xudong Code Review 不会扩展任务范围。仅修复所请求路径中经过验证的阻塞问题。可以提及无关发现,但不要为此开启新的工作流,并在所请求的审查轮次完成后停止。

Skill Path

Skill 路径

Invoke the installed script directly from the repository being reviewed. The examples below use the global installation at
~/.agents/skills/xudong-code-review
. For a project-local installation, replace that prefix with
.agents/skills/xudong-code-review
; for a custom installation, use its actual path.
bash
undefined
从被审查的 repository 中直接调用已安装的脚本。 以下示例使用全局安装路径
~/.agents/skills/xudong-code-review
。 对于项目本地安装,请将此前缀替换为
.agents/skills/xudong-code-review
;对于自定义安装,请使用其实际路径。
bash
undefined

Global installation:

全局安装:

"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help

Project-local installation:

项目本地安装:

.agents/skills/xudong-code-review/scripts/code-review --help

On native Windows, run the extensionless helper with Python and use the
`test-review-harness.ps1` wrapper for the smoke harness, as shown below.
.agents/skills/xudong-code-review/scripts/code-review --help

在原生 Windows 上,使用 Python 运行无扩展名的 helper,并使用
`test-review-harness.ps1` wrapper 运行 smoke harness,如下所示。

Pick Target

选择目标

Dirty local work:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode local
Use this only when the patch is actually unstaged/staged/untracked in the current checkout.
--mode uncommitted
is accepted as an alias for
--mode local
. For committed, pushed, or PR work, point the helper at the commit or branch diff instead; do not force dirty modes just because the helper docs mention dirty work first. A clean local review only proves there is no local patch.
Branch/PR work:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base origin/main
Optional review context is first-class. Prompt files and datasets must be repo-relative so review bundles cannot pull arbitrary host files:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base origin/main --prompt-file review-notes.md --dataset evidence.json
If an open PR exists, use its actual base:
bash
base=$(gh pr view --json baseRefName --jq .baseRefName)
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base "origin/$base"
Committed single change:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode commit --commit HEAD
Use commit review for already-landed or already-pushed work on
main
. Reviewing clean
main
against
origin/main
is usually an empty diff after push. For a small stack, review each commit explicitly or review the branch before merging with
--base
.
本地未提交改动:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode local
仅当当前 checkout 中确实存在未暂存、已暂存或未跟踪的 patch 时,才使用此模式。
--mode uncommitted
可作为
--mode local
的别名。 对于已 commit、已 push 或属于 PR 的工作,应改为让 helper 指向相应的 commit 或 branch diff;不要仅仅因为 helper 文档先介绍了 dirty 模式,就强制使用 dirty 模式。 对干净的本地工作区进行审查只能证明不存在本地 patch。
Branch 或 PR 工作:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base origin/main
可选的审查上下文属于一等输入。Prompt 文件和 dataset 必须使用 repo-relative 路径,防止审查包读取任意 host 文件:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base origin/main --prompt-file review-notes.md --dataset evidence.json
如果存在 open PR,请使用其实际 base:
bash
base=$(gh pr view --json baseRefName --jq .baseRefName)
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode branch --base "origin/$base"
单个已 commit 的变更:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode commit --commit HEAD
对于已经合入或已经 push 到
main
的工作,使用 commit review。Push 之后,将干净的
main
与
origin/main
比较通常会得到空 diff。对于小型 commit 栈,应明确审查每个 commit,或者在合并前使用
--base
审查 branch。

Oversized Bundles

超大审查包

The helper scans the full patch before partitioning it. A safe bundle that fits the aggregate prompt limit remains one integrated review pass. Larger bundles are split at bundle sections and file boundaries where possible; an oversized single-file block is split at line boundaries with repeated file/hunk context and an absolute new- or old-file line offset. Untracked snapshots use injection-safe source-line records so continuation passes retain reportable locations. A single physical diff line split across passes also retains its original addition, deletion, or context marker. Every original bundle byte appears exactly once across the pass sequence, and all validated reports are merged before required-finding and exit-status checks. The helper caps one run at eight bounded passes so an unexpectedly huge branch cannot create unbounded model calls; split still-larger work into coherent review targets.
Chunking makes large-diff review usable, but it cannot give one model call every cross-file implementation detail. For architecture-heavy changes, still prefer a coherent branch or PR shape whose semantic decision surface fits one pass. Removing verified non-authoritative generated noise remains useful, but never drop lockfiles, generated clients, policies, manifests, schemas, or other independently semantic artifacts merely to shrink the review.
Helper 会在划分审查包之前扫描完整 patch。符合汇总 prompt 上限的安全审查包会保持为一次集成审查。更大的审查包会尽可能按审查包 section 和文件边界拆分;如果单个文件块仍然过大,则按行边界拆分,并重复提供文件和 hunk 上下文以及新文件或旧文件的绝对行偏移。未跟踪快照使用防注入的 source-line 记录,使后续批次仍能保留可报告的位置。如果单个物理 diff 行被拆分到不同批次,也会保留其原始的添加、删除或上下文标记。
每个原始审查包字节在批次序列中恰好出现一次,并且所有验证后的报告都会在执行必需发现检查和退出状态检查之前合并。Helper 将单次运行限制为最多八个有界批次,避免异常庞大的 branch 产生不受限制的 model call;如果工作仍然过大,应将其拆分为连贯的审查目标。
分块能够使大型 diff 审查变得可用,但无法让一次 model call 获得所有跨文件实现细节。对于架构层面的重大变更,仍应优先采用连贯的 branch 或 PR 形态,使语义决策面能够容纳在一次审查中。删除已经验证为非权威的生成噪声仍然有帮助,但绝不能仅仅为了缩减审查包而丢弃 lockfile、生成的 client、policy、manifest、schema 或其他自身具有独立语义的重要产物。

Model and reasoning

模型与推理

Select
--engine codex
(default),
--engine antigravity
, or its alias
--engine agy
. Omit
--model
and
--thinking
to use the helper defaults. Use these flags only when an override is requested. For Antigravity, run
agy models
to list available models and use a base model name because the helper passes effort separately through
--effort
. There is no automatic engine/model fallback or
--fallback-model
option. Access, capacity, rate-limit, and network failures are returned directly.
Use
--help
to inspect the accepted reasoning levels. Codex passes reasoning through
model_reasoning_effort
; Antigravity passes it through
--effort
. The selected engine and model must support the requested effort.
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode local
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --codex-speed fast
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --codex-config 'model_verbosity="low"'
选择
--engine codex
(默认)、
--engine antigravity
或其别名
--engine agy
。 省略
--model
和
--thinking
以使用 helper 默认值。仅当用户要求覆盖配置时使用这些 flag。对于 Antigravity,运行
agy models
列出可用模型,并使用基础模型名称,因为 helper 会通过
--effort
单独传递 effort。 不存在自动的 engine 或 model fallback,也没有
--fallback-model
选项。 访问权限、容量、速率限制和网络故障将直接返回。
使用
--help
查看可接受的推理级别。Codex 通过
model_reasoning_effort
传递推理配置;Antigravity 通过
--effort
传递。所选引擎和模型必须支持请求的 effort。
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --mode local
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --codex-speed fast
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --codex-config 'model_verbosity="low"'

Antigravity (authenticate once with interactive agy first):

Antigravity(先通过交互式 agy 完成一次认证):

"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine antigravity --mode local "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine agy --mode local "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine antigravity --mode branch --base origin/main

`--codex-speed` accepts `fast`, `flex`, and `default`; the selected model must
support the requested tier. Dedicated options take precedence over matching
`--codex-config` values. Config overrides accept only safe model/response tuning.
Both Codex tuning options are rejected with `--engine antigravity`.
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine antigravity --mode local "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine agy --mode local "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --engine antigravity --mode branch --base origin/main

`--codex-speed` 接受 `fast`、`flex` 和 `default`;所选模型必须支持请求的级别。专用选项的优先级高于对应的 `--codex-config` 值。配置覆盖仅接受安全的模型和响应调优项。使用 `--engine antigravity` 时会拒绝两个 Codex 调优选项。

Configuration

配置

Review settings use fixed defaults and explicit CLI flags; configuration environment variables and repository configuration files are not loaded. Model and reasoning defaults are owned by the constants in
scripts/code-review
; do not duplicate them here or pass explicit values merely to reproduce defaults. Both engines use P0 through P2 findings, no timeout, and no streamed engine output. Use
--model
,
--thinking
,
--max-priority
,
--engine-timeout-seconds
,
--stream-engine-output
,
--codex-config
, or
--codex-speed
to override them. Select
--engine antigravity
to use
agy
on
PATH
; use
--antigravity-bin
for an explicit path. Codex resolves
codex
on
PATH
, with
--codex-bin
for an explicit path. Authentication, proxy, and certificate environment variables remain supported.
审查设置使用固定默认值和明确的 CLI flag;不会加载配置环境变量或 repository 配置文件。模型和推理默认值由
scripts/code-review
中的常量控制;不要在此处重复定义,也不要仅为复现默认值而显式传入。两个引擎默认均使用 P0 至 P2 的审查发现,不设置超时,也不流式输出引擎输出。使用
--model
、
--thinking
、
--max-priority
、
--engine-timeout-seconds
、
--stream-engine-output
、
--codex-config
或
--codex-speed
覆盖这些设置。选择
--engine antigravity
以使用
PATH
中的
agy
;也可使用
--antigravity-bin
指定显式路径。Codex 从
PATH
解析
codex
,也可使用
--codex-bin
指定显式路径。认证、代理和证书环境变量仍受支持。

Structured output and isolation

结构化输出与隔离

For Codex, the helper supplies its JSON Schema through
--output-schema
and reads the final report from
--output-last-message
. It parses and validates the report before returning findings. Malformed output fails the review.
Codex runs in an empty temporary workspace with isolated HOME/XDG/runtime roots. The validated bundle is its sole repository input. A named permission profile allows filesystem reads only inside that workspace; ignored credentials and linked-worktree metadata remain outside the readable boundary. Web search is available unless
--no-web-search
is set.
--no-tools
is unsupported.
--ignore-user-config
skips unrelated user configuration,
--ignore-rules
skips user/project execpolicy rules, and project instructions, hooks, plugins, and MCP servers are disabled. Only
cli_auth_credentials_store
,
forced_login_method
, and
forced_chatgpt_workspace_id
are reconstructed from the external Codex configuration to preserve authentication. File authentication is linked into the isolated runtime so token refreshes remain durable; trusted keyring settings and certificate paths are preserved without forwarding process-injection variables.
Antigravity requires a CLI with
--settings
support (verified with
agy 1.5.6
). It runs from an empty temporary workspace with isolated HOME/XDG roots and a generated custom agent with default components disabled. Only
finish
(schema submission),
search_web
, and
read_url_content
are exposed; file reads/writes, shell commands, MCP, browser execution, and delegation are unavailable.
--no-web-search
removes both web tools, leaving bundle-only review with only
finish
available. Keep
finish
in the custom agent's tool list:
--json-schema
alone does not restore a tool excluded by that list.
--no-tools
is unsupported by either engine.
The helper sends one NDJSON user message on stdin and passes the same review Schema via
--json-schema
. It requires exactly one terminal
result
with
status: SUCCESS
and an object in
structured_output
, then applies the shared report and location validation. Free-text responses never substitute for missing structured output. Both streaming and buffered runs use this path.
User/project rules, hooks, plugins, MCP settings, and saved model preferences are not loaded. OS keyring authentication is retained; on macOS only
~/Library/Keychains
is linked into the temporary HOME. If the CLI uses its file-auth fallback, only
~/.gemini/antigravity-cli/antigravity-oauth-token
is linked (a hard link is used for file auth when symlinks are unavailable). These auth sources must resolve outside the reviewed repository. No credentials are copied into the review workspace.
GEMINI_API_KEY
selects the Gemini API provider when present, with
GOOGLE_GEMINI_BASE_URL
preserved for a custom endpoint; unrelated provider keys and process-injection variables are stripped. Session settings keep AI credit overage disabled.
Antigravity retains a temporary conversation while running; the helper deletes its isolated runtime after completion. CLI flags and structured output are documented in the official headless guide.
对于 Codex,helper 通过
--output-schema
提供 JSON Schema,并通过
--output-last-message
读取最终报告。它会在返回发现之前解析并验证报告。
Codex 在空白临时工作区中运行,并使用隔离的 HOME、XDG 和 runtime roots。经过验证的审查包是其唯一的 repository 输入。指定的 permission profile 仅允许读取该工作区内部的文件;ignored credentials 和 linked-worktree metadata 均位于可读边界之外。除非设置
--no-web-search
,否则 web search 可用。不支持
--no-tools
。
--ignore-user-config
会跳过无关的用户配置,
--ignore-rules
会跳过用户或项目的 execpolicy rules,同时禁用项目 instructions、hooks、plugins 和 MCP servers。仅从外部 Codex 配置重建
cli_auth_credentials_store
、
forced_login_method
和
forced_chatgpt_workspace_id
,以保留认证能力。文件认证会链接到隔离 runtime 中,以便 token refresh 持久生效;可信 keyring 设置和证书路径会被保留,但不会转发进程注入变量。
Antigravity 要求 CLI 支持
--settings
(已使用
agy 1.5.6
验证)。它在空白临时工作区中运行,使用隔离的 HOME 和 XDG roots,并生成一个禁用默认组件的自定义 agent。仅开放
finish
(schema submission)、
search_web
和
read_url_content
; 文件读写、shell 命令、MCP、browser execution 和 delegation 均不可用。
--no-web-search
会同时移除两个 web tools,仅保留
finish
以进行纯审查包审查。请确保
finish
保留在自定义 agent 的 tool list 中:仅使用
--json-schema
无法恢复已被该 list 排除的 tool。任一引擎都不支持
--no-tools
。
Helper 通过 stdin 发送一条 NDJSON user message,并通过
--json-schema
传入相同的 review Schema。它要求恰好存在一个
status: SUCCESS
的 terminal
result
,且
structured_output
为 object,然后应用共享的报告和位置验证。Free-text 响应绝不能替代缺失的结构化输出。Streaming 和 buffered 运行均使用此路径。
不会加载用户或项目规则、hooks、plugins、MCP settings 以及保存的模型偏好。保留 OS keyring 认证;在 macOS 上,仅将
~/Library/Keychains
链接到临时 HOME。如果 CLI 使用 file-auth fallback,则仅链接
~/.gemini/antigravity-cli/antigravity-oauth-token
;当 symlink 不可用时,file auth 会使用 hard link。这些认证源必须解析到被审查 repository 之外的位置。不会将任何凭据复制到审查工作区。当存在
GEMINI_API_KEY
时,它会选择 Gemini API provider,同时保留
GOOGLE_GEMINI_BASE_URL
以支持自定义 endpoint;无关的 provider key 和进程注入变量会被移除。Session settings 会保持 AI credit overage 处于禁用状态。
Antigravity 在运行期间会保留临时 conversation;helper 会在完成后删除其隔离 runtime。CLI flag 和结构化输出记录在官方 headless guide中。

Context Efficiency

上下文效率

Run the helper directly so target selection, engine choice, structured validation, and exit status all stay in one path. If output is noisy, summarize the completed helper output after it returns; do not ask another agent or reviewer to rerun the review.
直接运行 helper,使目标选择、引擎选择、结构化验证和退出状态始终位于同一执行路径中。如果输出过于嘈杂,请在 helper 返回后总结其已完成的结果;不要让另一个 agent 或 reviewer 重新运行审查。

Helper

Helper

Show the helper options:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help
The smoke harness has thin shell wrappers over a shared Python implementation:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness" --fixture benign
"$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness" --engine antigravity --fixture benign
On native Windows, invoke the extensionless Python helper through Python:
powershell
python "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help
and the smoke harness:
powershell
& "$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness.ps1" -Fixture benign
The helper:
  • chooses dirty local changes first
  • accepts
    --mode uncommitted
    as an alias for
    --mode local
  • otherwise uses current PR base if
    gh pr view
    works
  • otherwise uses
    origin/main
    for non-main branches
  • does not fetch automatically during branch review; the selected base ref must already resolve locally
  • supports Codex (default) and explicit
    --engine antigravity
    /
    --engine agy
    ; both Antigravity spellings resolve to the same engine and defaults
  • resolves bare
    git
    ,
    gh
    , reviewer, and PowerShell shell commands from absolute
    PATH
    entries only, never from the reviewed checkout; explicit
    --*-bin
    paths are interpreted from the reviewed repository root when relative and accepted only when both the supplied path and resolved target stay outside the reviewed repository
  • use
    --mode commit --commit <ref>
    for already-committed work, especially clean
    main
    after landing
  • scans safe Git patches in full, recognizes synthetic fixture values tied to their credential field, reviews them in one pass up to the aggregate prompt limit, and automatically uses complete bounded passes above it
  • should be left in
    --mode auto
    or forced to
    --mode branch
    for PR/branch work; do not force
    --mode local
    after committing
  • writes only to stdout unless
    --output
    ,
    --json-output
    , or live streamed engine stderr is set
  • supports
    --dry-run
    (validates bundle construction, reviewer CLI resolution, and local isolation startup with a version probe without contacting a provider; exits nonzero if any check fails), an opt-in per-reviewer wall-clock bound via
    --engine-timeout-seconds
    ,
    --prompt
    , repo-relative
    --prompt-file
    , repo-relative
    --dataset
    ,
    --no-web-search
    , repeatable Codex-only safe model/response tuning with
    --codex-config key=value
    , Codex-only
    --codex-speed fast|flex|default
    , and commit refs
  • supports
    --stream-engine-output
    for live progress while preserving structured validation; Codex hides tool/file event details and reports usage at turn completion; Antigravity emits compact activity and terminal-status summaries
  • applies the model and reasoning defaults defined in the helper; explicit
    --model
    and
    --thinking
    values override them, without fallback
  • gives either engine the validated bundle in an empty workspace with web search available
  • prints
    review still running: <engine> elapsed=<seconds>s pid=<pid>
    to stderr at long-running intervals while waiting for the selected review engine, unless streamed output or compact Codex activity has been visible recently
  • prints
    code-review clean: no accepted/actionable findings reported
    when the selected review command exits 0
  • exits nonzero when accepted/actionable findings are present
显示 helper 选项:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help
Smoke harness 使用一组基于共享 Python 实现的轻量 shell wrapper:
bash
"$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness" --fixture benign
"$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness" --engine antigravity --fixture benign
在原生 Windows 上,通过 Python 调用无扩展名的 helper:
powershell
python "$HOME/.agents/skills/xudong-code-review/scripts/code-review" --help
并运行 smoke harness:
powershell
& "$HOME/.agents/skills/xudong-code-review/scripts/test-review-harness.ps1" -Fixture benign
Helper:
  • 优先选择 dirty local changes
  • 接受
    --mode uncommitted
    作为
    --mode local
    的别名
  • 如果
    gh pr view
    可用,则使用当前 PR base
  • 对于非 main branch,否则使用
    origin/main
  • branch review 期间不会自动 fetch;所选 base ref 必须已能在本地解析
  • 支持 Codex(默认)以及显式的
    --engine antigravity
    或
    --engine agy
    ;两种 Antigravity 写法都会解析到同一个引擎和默认配置
  • 仅从绝对
    PATH
    条目解析裸
    git
    、
    gh
    、reviewer 和 PowerShell shell 命令,绝不从被审查的 checkout 解析;显式
    --*-bin
    相对路径以被审查的 repository root 为基准进行解释,且仅当提供的路径和解析后的目标都位于被审查 repository 之外时才接受
  • 对已 commit 的工作使用
    --mode commit --commit <ref>
    ,尤其是合入后保持干净的
    main
  • 完整扫描安全的 Git patch,识别与凭据字段关联的合成 fixture 值,在符合汇总 prompt 上限时通过一次审查进行评估,并在超过上限时自动使用完整的有界批次
  • 对于 PR 或 branch 工作,应保留在
    --mode auto
    ,或强制使用
    --mode branch
    ;commit 之后不要强制使用
    --mode local
  • 除非设置
    --output
    、
    --json-output
    或实时的 streamed engine stderr,否则仅向 stdout 写入内容
  • 支持
    --dry-run
    ,通过 version probe 验证审查包构建、reviewer CLI 解析和本地隔离启动,而不联系 provider;如果任何检查失败,则以非零状态退出
  • 支持通过
    --engine-timeout-seconds
    为每个 reviewer opt-in 设置 wall-clock 上限
  • 支持 repo-relative 的
    --prompt
    、
    --prompt-file
    和
    --dataset
  • 支持
    --no-web-search
  • 支持使用
    --codex-config key=value
    重复配置仅限 Codex 的安全模型与响应调优项
  • 支持 Codex-only 的
    --codex-speed fast|flex|default
  • 支持 commit refs
  • 支持
    --stream-engine-output
    以提供实时进度,同时保留结构化验证;Codex 会隐藏 tool 和 file event 详情,并在 turn 完成时报告用量;Antigravity 会输出紧凑的活动信息和 terminal-status 摘要
  • 应用 helper 中定义的模型和推理默认值;显式的
    --model
    和
    --thinking
    值会覆盖默认值,且不会 fallback
  • 向任一引擎提供空白工作区中的验证后审查包,并保持 web search 可用
  • 等待所选审查引擎时,会按较长运行间隔向 stderr 输出
    review still running: <engine> elapsed=<seconds>s pid=<pid>
    ,除非近期已经显示 streamed output 或紧凑的 Codex 活动信息
  • 当所选 review command 以退出码 0 结束时,输出
    code-review clean: no accepted/actionable findings reported
  • 当存在已接受或可执行的问题时,以非零状态退出

Final Report

最终报告

Report material findings and the resulting status in chat. If there are none, say so plainly. Do not add command logs, test ledgers, proof blocks, or review receipts unless the user asks for them.
在聊天中报告重要发现及相应状态。如果没有发现,请直接说明。不要添加 command logs、test ledgers、proof blocks 或 review receipts,除非用户明确要求。