企业官网建设流程全解析

Agent 交付前多模型代码审查：plate 仓库 autoreview Skill 结构化审查工作流实战指南

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate

导读

本文以 .agents/skills/autoreview/SKILL.md 为核心，系统拆解 plate 仓库内置的 autoreview Skill——一套用于「提交/发布前收尾」的结构化 AI 代码审查工具链。它默认调用 Codex（gpt-5.5），可选 Claude、Pi、Droid、Copilot、OpenCode，通过统一 JSON Schema 输出可校验的审查结论，并内置范围治理、引擎隔离、安全脱敏与回归溯源规则。读完本文，你将掌握 autoreview 的目标选择、面板组合、模型/思考层级配置、隔离机制与退出码语义，并能在自己的仓库中直接复用这套脚本完成"干净收尾"式的代码审查。

一、autoreview 是什么：定位与适用场景

autoreview 是 plate 仓库.agents/skills/autoreview/目录下的一个 Agent Skill，配套一份约 3000 行的 Python 实现（scripts/autoreview），其核心定位是：

• 它是"收尾关卡"（closeout gate），而不是 Guardian 的auto_review审批路由。文档开篇就明确区分：这是一次代码审查，而非审批流程；
• 默认审查引擎是 Codex，使用gpt-5.5，通常能给出最好的审查结果，应保持为常规最终收尾引擎；Claude 为可选项，默认claude-fable-5；
• 触发条件（Use when）包括：用户明确要求某引擎审查（Codex / Claude / Pi / Droid / OpenCode / autoreview / second-model review）、非平凡的代码编辑之后（提交/发布前）、修复后的本地分支或 PR 分支复查。

从仓库结构看，该 Skill 还有配套的冒烟测试壳（test-review-harness、test-review-harness.ps1、test-review-harness.py）与单元测试（tests/test_autoreview_hardening.py），说明这是一条被认真测试过的自动化审查链路。

二、审查契约（Contract）：先立规则再跑审查

SKILL.md 的 Contract 小节定义了运行审查时必须遵守的硬性规则，这些规则同时也被写入了发送给引擎的 Prompt（见源码build_prompt中的 Hard rules），主要包括：

• 审查输出只是建议：绝不盲目套用，每个 finding 都必须回到真实代码路径与相邻文件核实；
• 依赖外部行为时（依赖库文档/源码/类型）要读原文档确认；
• 拒绝不切实际的边缘场景、推测性风险、大范围重写，以及让代码库过度复杂的修复；
• 倾向在正确的所有权边界内做小修复，除非重构能明显改善该 bug 类别，否则不重构；
• 发现 bug 类别或重复模式时，先在当前 PR 范围内排查同类实例，能一次性修掉同类 bug 就修，并在触及的表面、所有权边界、明确的后续工作处停下；
• 一旦审查触发的修复改了代码，必须重跑相关测试并重跑结构化审查；
• 禁止中途切换或覆盖审查引擎/模型；模型达到容量上限时，用同一引擎/模型重试同一命令数次；
• 对超大 bundle 要有耐心：单次结构化审查最长可达 30 分钟（尤其启用 Codex 工具或联网搜索时）；
• 心跳行是健康信号而非卡死：类似review still running: ... elapsed=... pid=...的输出代表进度在推进；需要实时引擎文本时可加--stream-engine-output（Codex 与 Claude 会过滤工具/文件噪音，其余引擎原样透传）；
• 不要在审查中途调用内置的codex review、嵌套审查者或审查面板——helper 只构建一个 bundle、调用一个选定引擎、校验一份结构化结果、然后停止；
• 审查模式允许只读工具与联网搜索，便于核查依赖契约、上游文档与当前行为；
• 安全视角始终在场，但不该阉割合法功能：只有当变更制造了具体可利用的风险、移除了重要安全检查、或缺少信任边界校验时，才报告安全 finding；
• 回归溯源要保持角色分离：被指责的代码作者、被指责的 PR 作者、PR 合并/提交者、当前 PR 作者、PR/日期各记各的；找不到被指责 PR 时用被指责提交作为溯源（提交 SHA、日期、作者用户名）；
• 不为了"更漂亮的干净结论"多跑一次审查：helper 成功退出且无 actionable findings 即视为干净结果。

关于回归溯源的两个细节

• 若被指责的 PR 由clawsweeper[bot]等自动化合并，应尽可能定位人工触发者：先查时间线与评论，被限流时用 gitcrawl/缓存或公开 PR HTML，寻找@clawsweeper automerge、/landpr或武装 automerge 的标签/状态评论，报告automerge triggered by @login，找不到则如实说明；
• 若gh/Gitcrawl 报告database disk image is malformed，先运行一次gitcrawl doctor --json让便携缓存自修复再重试；若 Gitcrawl 报告便携清单不匹配或源/运行时 DB 健康错误，同样先跑gitcrawl doctor --json检查source_db_health、runtime_db_health、portable_store_status，再决定是否回退到实时 GitHub。

三、范围治理（Scope Governor）：审查不是重写任务的许可

autoreview 反复强调"收尾关卡"身份，Scope Governor 小节给出了可操作的范围冻结机制：

首次审查前，先冻结范围基线：原始请求或 issue、目标分支、预期行为、所有权边界、变更文件、非测试 LOC。对继承而来或已膨胀的分支，用预期的 PR diff 作为基线，而不是接受全部既有分支漂移。

修补 finding 前必须先分类：

出现以下情况必须停止修补并报告范围破坏：

• 窄 PR 演变成架构变更、协议变更、迁移或发布流程变更；
• 未经明确批准，diff 超过原文件数或非测试 LOC 的 2 倍；
• 两轮审查触发的修补仍未收敛——先暂停，重新分类所有剩余 finding 再改；
• 最佳修复是"先定义规范契约"而非再堆一层本地推断；
• 修复已接受的 finding 会让 PR 不再描述相同的行为、issue 或所有权边界。

两轮暂停之后，只有当下所有剩余已接受 finding 仍是范围内阻塞项时才继续；否则保留有用分析、确定最小可安全落地的子集，为更大修复开启后续跟踪，不要为了满足审查者而继续提交推测性修复。关键例外必须显式声明：活跃数据丢失、崩溃、安装/升级破坏、发布阻塞、具体安全暴露——不属于这五类就不足以撑爆范围。

四、发布分支与发布流程纪律

对 release、beta、stable、hotfix、签名、公证、appcast、包发布、发布检查等工作，即使分支名不像发布分支，也要使用冻结纪律：

• 只修发布阻塞项、失败的发布基础设施、精确 backport、安装/升级破坏、数据丢失、崩溃或具体安全暴露；
• 非阻塞的 autoreview findings 应作为main的后续项，而不是扩大发布分支的理由；
• 不引入新产品行为、配置面、协议形状、迁移、插件所有权、文档叙事或流程策略，除非它直接解除发布阻塞；
• 证明要锚定发布目标：精确分支/ref、失败检查或发布风险原因、最小命令/证明、修复是否必须前向移植到main；
• 发布收尾时若发现真实但非关键的设计问题，停下并制定后续 issue/PR 计划，绝不用发布分支当重构跑道。

五、Skill 路径设置（一次配置，随处引用）

脚本路径只需设置一次，之后统一使用"$AUTOREVIEW"与"$AUTOREVIEW_HARNESS"引用。三种可选方式：

# 项目内 Skill（当前仓库） export AUTOREVIEW=".agents/skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS=".agents/skills/autoreview/scripts/test-review-harness"

# openclaw/agent-skills 源码检出 export AUTOREVIEW="skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS="skills/autoreview/scripts/test-review-harness"

# 全局 Skill export AGENTS_HOME="${AGENTS_HOME:-$HOME/.agents}" export AUTOREVIEW="$AGENTS_HOME/skills/autoreview/scripts/autoreview" export AUTOREVIEW_HARNESS="$AGENTS_HOME/skills/autoreview/scripts/test-review-harness"

使用 Claude Code 时设置AGENTS_HOME="$HOME/.claude"用于全局 Skill；项目内 Skill 位于当前仓库.claude/skills/下。

六、选择审查目标（Pick Target）：local / branch / commit

helper 按目标自动构建 diff bundle，三种模式对应三种场景：

脏工作区（local）——仅当补丁确实处于未暂存/已暂存/未跟踪状态时使用：

"$AUTOREVIEW" --mode local

--mode uncommitted是--mode local的别名。注意：干净的本地审查只能证明"没有本地补丁"，已提交、已推送或 PR 工作必须指向 commit 或 branch diff，不要因为文档先讲脏工作区就强行用脏模式。

分支/PR 工作（branch）：

"$AUTOREVIEW" --mode branch --base origin/main

审查上下文是一等公民，Prompt 文件与数据集必须仓库相对（防止 bundle 拉取任意主机文件）：

"$AUTOREVIEW" --mode branch --base origin/main --prompt-file review-notes.md --dataset evidence.json

存在开放 PR 时使用其真实基线：

base=$(gh pr view --json baseRefName --jq .baseRefName) "$AUTOREVIEW" --mode branch --base "origin/$base"

已提交的单个变更（commit）——用于已落地/已推送的main工作：

"$AUTOREVIEW" --mode commit --commit HEAD

对干净main与origin/main对比通常是空 diff；小提交栈可逐个显式审查，或在合并前用--base审查整个分支。

七、并行收尾（Parallel Closeout）

格式化先行（因为格式化可能改变行号），然后测试与审查可并行：

"$AUTOREVIEW" --parallel-tests "<focused test command>"

Windows 上默认--parallel-testsshell 保留 Pythonshell=True的cmd.exe语义；聚焦测试命令为 PowerShell 专属时用--parallel-tests-shell powershell或--parallel-tests-shell pwsh。

权衡在于：测试可能迫使代码改动从而使审查过期。若测试或审查导致代码编辑，重跑受影响的测试并重跑审查，直到没有 accepted/actionable findings；那次重跑干净退出后就停止，不要为冗余确认再烧一轮长审查。

八、多审查者面板（Review Panels）

对同一份冻结 bundle 跑多个审查者：

"$AUTOREVIEW" --reviewers codex,claude,pi,droid

--panel是 Codex+Claude 的简写（除非--engine改变首个审查者）：

"$AUTOREVIEW" --panel

显式设置各审查者模型与思考层级：

"$AUTOREVIEW" --reviewers codex,claude --model codex=gpt-5.5 --thinking codex=high --model claude=claude-fable-5 --thinking claude=max

简单模型 ID 也支持内联语法：

"$AUTOREVIEW" --reviewers codex:gpt-5.5:high,claude:claude-fable-5:max

模型 ID 含斜杠或多余冒号时，优先键值形式：

"$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high "$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high "$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low "$AUTOREVIEW" --reviewers codex,pi --model codex=gpt-5.5 --model pi=anthropic/claude-sonnet-4 "$AUTOREVIEW" --reviewers codex,opencode --model codex=gpt-5.5 --model opencode=opencode/north-mini-code-free "$AUTOREVIEW" --reviewers codex,droid --model codex=gpt-5.5 --model droid=claude-opus-4-8

多审查者面板是可选加入的：仅在明确要求或风险值得额外开销时使用，主 Agent 仍要在接受每个 finding 前亲自核实。

九、模型与思考层级（Models and Thinking）

--model可全局或按引擎（engine=model）传入，--thinking同理（engine=level）；多审查者时重复使用即可。

推荐模型默认值：

Droid、Copilot、Pi、OpenCode 在此不设内置默认模型，因为其 provider 目录在 Codex/Claude 收尾路径之外，且随安装环境而异。

各引擎的模型旗标与思考层级：

匹配当前main行为的示例：

# Codex 显式模型与推理 "$AUTOREVIEW" --engine codex --model gpt-5.5 --thinking high # Claude Code 别名或全名，可加可用性回退链 "$AUTOREVIEW" --engine claude --model claude-fable-5 --thinking max "$AUTOREVIEW" --engine claude --model claude-fable-5 --fallback-model claude-opus-4-8,claude-sonnet-4-6 # Factory Droid 显式模型与推理力度 "$AUTOREVIEW" --engine droid --model claude-opus-4-8 --thinking low # GitHub Copilot（仅模型，无思考旋钮） "$AUTOREVIEW" --engine copilot --model gpt-5.2 # Pi 显式模型与思考层级 "$AUTOREVIEW" --engine pi --model anthropic/claude-sonnet-4 --thinking high --pi-bin pi # OpenCode 显式 provider/模型与 variant "$AUTOREVIEW" --engine opencode --model opencode/north-mini-code-free --thinking high

环境变量默认值

CLI 旗标优先级高于环境变量：

底层映射关系（源码run_codex/run_claude/run_droid/run_pi/run_opencode中可见）：Codex 将思考映射为model_reasoning_effort，Claude 映射为--effort，Droid 映射为-r, --reasoning-effort，Pi 映射为--thinking，OpenCode 映射为--variant，Copilot 拒绝--thinking。只有 Claude 接受--fallback-model：全局 CLI/env 回退要求至少一个 Claude 审查者，按引擎指定的回退覆盖要求该审查者被选中；非 Claude 的回退覆盖（包括AUTOREVIEW_<NONCLAUDE>_FALLBACK_MODEL）会 fail-closed 而非静默忽略——源码reviewer_args中明确抛错："--fallback-modelis only supported for claude"。

十、审查引擎隔离（Review Engine Isolation）

这是 autoreview 最具安全工程色彩的部分：当审查在仓库内运行时，外部审查者 CLI不得加载分支可控制的项目本地信任或配置。各引擎的隔离旗标：

源码中的关键实现细节（可对照 scripts/autoreview 阅读）：

• Codex：--ignore-user-config跳过 exec 运行的配置加载；autoreview 只从CODEX_HOME/config.toml重建文档化的cli_auth_credentials_store、forced_login_method、forced_chatgpt_workspace_id三个键（codex_auth_config_flags），既保留认证与工作区限制，又不转发无关用户配置。显式仓库信任覆盖与零项目文档预算，让被审仓库的AGENTS.md与.codex/信任面进不了审查 prompt；--ignore-rules跳过用户/项目 execpolicy 规则；
• Claude：--safe-mode禁用项目 hooks、skills、plugins、MCP 服务器与 CLAUDE.md，同时保留正常认证、模型选择、内置工具与权限；--setting-sources user避免加载被审检出的项目/本地设置；--strict-mcp-config与--disallowedTools mcp__*让 MCP 对审查运行不可用；此处不用--bare，因为 Claude headless 文档说明它会跳过 OAuth 与 keychain 读取。ensure_claude_isolation_supported会在运行前校验版本（v2.1.169+）与--help中是否包含全部必需旗标，缺一则 fail-closed；
• Pi：--no-approve让单次运行忽略项目本地文件；helper 要求 Piv0.79.0+且--help输出广告所有必需隔离旗标（旧二进制可能静默忽略未知旗标）。当前包为@earendil-works/pi-coding-agent，已弃用的@mariozechner/pi-coding-agent0.73.x会被有意拒绝。版本探测与审查命令都从中性临时目录运行而非被审仓库：--no-context-files移除AGENTS.md/CLAUDE.md，资源禁用旗标排除.pi扩展、skills、prompts、themes，--no-session避免写入审查会话，只读白名单不包含bash、edit、write；
• OpenCode：从中性临时目录启动，用--dir指向被审仓库，OPENCODE_DISABLE_PROJECT_CONFIG=1禁用项目配置并注入OPENCODE_CONFIG_CONTENT；权限默认拒绝、允许 read/grep/glob、保留 OpenCode 的.env询问规则、--no-web-search门控websearch/webfetch；注入配置还会清空 command/instructions/plugin 数组，禁用 write/edit/bash/task/skill/todowrite 工具而不改变用户认证存储。审查 prompt 经 stdin 传递而非 argv，最终结构化 JSON 从type: "text"事件中提取。OpenCode 拒绝--no-tools。

从源码看，还有一层通用隔离：safe_engine_env阻断BASH_ENV、ENV、GIT_CONFIG*、LD_PRELOAD、NODE_OPTIONS、PYTHONHOME、PYTHONPATH等危险环境变量，safe_engine_path只从绝对 PATH 条目解析可执行文件，且绝不从被审检出的目录解析（仓库内同名codex/ps等会被跳过），并用GIT_CONFIG_COUNT注入固定 git 覆盖（关闭 fsmonitor、pager、外部 diff 等）。

十一、上下文效率与 Helper 行为

直接运行 helper，让目标选择、引擎选择、结构化校验与退出状态保持在同一条路径上；输出太吵时，在 helper 返回后汇总其输出，不要请另一个 Agent 或审查者重跑。

查看帮助与冒烟测试：

"$AUTOREVIEW" --help

冒烟测试壳是共享 Python 实现的薄 shell 包装：

"$AUTOREVIEW_HARNESS" --fixture benign --engine codex

Windows 原生环境下用 Python 调用无扩展名 helper：

python skills\autoreview\scripts\autoreview --help

以及冒烟测试：

skills\autoreview\scripts\test-review-harness.ps1 -Fixture benign -Engine codex

Helper 的关键行为（与源码main()/choose_target对应）：

• 优先选择脏本地改动；--mode uncommitted是--mode local别名；
• 否则在gh pr view可用时使用当前 PR 基线；再否则非main分支使用origin/main；
• 分支审查期间不自动 fetch，所选基线 ref 必须已在本解析；
• 支持--engine codex/claude/droid/copilot/pi/opencode，默认取AUTOREVIEW_ENGINE或codex；
• 裸git、gh、审查者与 PowerShell shell 命令只从绝对 PATH 条目解析，绝不从被审检出解析；显式相对--*-bin路径从被审仓库根解析；
• 默认只写 stdout，除非设置--output、--json-output或实时流式引擎 stderr；
• 支持--dry-run、--parallel-tests、--parallel-tests-shell、--prompt、仓库相对--prompt-file、仓库相对--dataset、--no-tools、--no-web-search与 commit refs；
• --stream-engine-output（或AUTOREVIEW_STREAM_ENGINE_OUTPUT=1）在保留结构化校验的同时流式输出引擎文本；Codex 与 Claude 隐藏工具/文件事件细节、输出紧凑活动摘要、回合结束时报告用量；
• 支持--panel/--reviewers可选面板，以及按引擎的--model、--thinking、Claude--fallback-model；
• 内置模型默认codex=gpt-5.5、claude=claude-fable-5；CLI 省略时尊重AUTOREVIEW_MODEL、AUTOREVIEW_THINKING、AUTOREVIEW_FALLBACK_MODEL及按引擎的AUTOREVIEW_<ENGINE>_MODEL/_THINKING；
• 默认允许只读工具与联网搜索（选定 CLI 支持处），prompt 中禁止嵌套审查；Codex 通过codex exec运行（仅认证用户设置、只读沙箱、隔离旗标、结构化输出）；
• Claude 以--safe-mode（v2.1.169+）、--setting-sources user、禁用 MCP、显式允许工具、可选--fallback-model运行；
• Droid 以droid exec只读模式运行，转发--model与-r, --reasoning-effort，流式时切换--output-format stream-json；
• Piv0.79.0+从中性临时目录运行，启用工具时内置只读工具read,grep,find,ls；
• OpenCode 从中性临时目录运行opencode run --dir <repo> --pure --format json，转发--model与--variant，注入默认拒绝权限、禁用项目配置，prompt 走 stdin；
• 长时等待期间向 stderr 打印review still running: <engine> elapsed=<seconds>s pid=<pid>（除非近期可见流式输出或紧凑 Codex 活动）；
• 选定审查命令退出 0 时打印autoreview clean: no accepted/actionable findings reported；
• 存在 accepted/actionable findings 时非零退出。

心跳与进程监控（源码层佐证）

run_with_heartbeat以 60 秒为周期对子进程communicate超时，超时即采样 CPU/内存/状态并输出心跳行（emit_heartbeat）。文档给出的健康判定是：不要因为安静 2-5 分钟就杀审查，也不要在 30 分钟窗口内因为"还在跑"就杀掉；只在错过多个预期心跳、超过 30 分钟、或子进程明显失败后再检查进程，并且优先让同一 helper 命令自然结束。心跳的 CPU 采样还会验证只读边界——源码自测会构造一个仓库内名为ps的恶意可执行文件，确认心跳采样绝不会执行它。

十二、结构化输出与安全脱敏：bundle 是怎么被"洗干净"的

源码 scripts/autoreview 揭示了审查 bundle 的构建与校验流水线：

• 统一 JSON Schema（SCHEMA）：顶层必需findings、overall_correctness、overall_explanation、overall_confidence；每个 finding 必需title（≤140 字符）、body（≤2000）、priority（P0–P3）、confidence（0–1）、category（bug/security/regression/test_gap/maintainability）、code_location（file_path+line）。校验器validate_report逐项检查类型、枚举与长度，并在--require-finding存在时要求 finding 文本包含指定子串；
• 敏感内容防线：SENSITIVE_PATH_PARTS（.aws、.ssh、secrets等）与SENSITIVE_NAME_PATTERNS（.env*、私钥文件名、*secret*/*token*/*credential*等）阻断敏感路径；SECRET_VALUE_PATTERNS匹配私钥块、api_key=/token=/password=赋值、Bearer、sk-/github_pat_/glpat-/npm_/xox及 AWS/GCP 密钥格式；symlink、仓库外路径、二进制文件都会被拒。命中即抛错：refusing to include secret-like content in review bundle；
• 范围锚定：validate_report会丢弃 code_location 不在本次变更文件集合内的 finding（打印autoreview ignored out-of-scope finding ...），若全部被忽略且总体判定为 incorrect，会自动改写为 correct 并追加说明。这从实现层面落实了"只报告本 diff 引入或暴露的缺陷"；
• Prompt 组装：build_prompt内嵌硬规则（只返回一个 JSON 对象、禁止嵌套审查命令、只读工具、报告安全类别的枚举）、范围纪律文本（review_scope_policy）以及变更 bundle，再交给选定引擎。

十三、测试与验证体系

• 冒烟测试（scripts/test-review-harness.py）：在临时 git 仓库中构造malicious（含真实安全 bug 的补丁：命令注入、路径穿越、密码泄露）或benign（安全敏感但正确的补丁）两种 fixture，逐引擎跑 autoreview；malicious场景使用--require-finding command --expect-findings断言引擎必须报出命令注入类 finding，benign场景则验证不会误报合法的 shell/文件系统/认证邻接功能；还通过validate_prompt_policy断言 prompt 包含范围纪律文本；
• 引擎隔离自测：self_test_engine_isolation会构造一个充满AGENTS.md、.codex/规则、.claude/hooks/skills/MCP、.pi/扩展、.opencode/配置的"敌意仓库"，用假引擎二进制记录 argv/stdin/env，逐一断言 Codex/Claude/Pi/OpenCode 的隔离旗标正确注入、恶意项目配置未泄漏、审查进程不在敌意仓库内运行、prompt 不落入 argv；
• 单元测试（tests/test_autoreview_hardening.py）与 helper 内置的--self-test-*系列（config defaults、fallback scope、heartbeat metrics、JSON 数组/JSONL 解析器、opencode 隔离）共同构成回归防线。

十四、最终报告（Final Report）

一次审查收尾后，报告必须包含：

• 使用的审查命令；
• 运行的测试/证明；
• 接受/拒绝的 findings 及简要理由；
• 最终 helper/审查运行的干净结果，或某个剩余 finding 被有意拒绝的原因。

不要为了改善报告措辞而多跑一次审查——若最终 helper 运行退出 0 且无 accepted/actionable findings，就如实报告那一次运行是干净的。

结语

autoreview Skill 的价值不在于"多一个 AI 审查入口"，而在于把一次代码审查变成可校验、可归因、有边界的工程流程：统一 Schema 让结果可被程序验证，范围治理防止审查变成重写，引擎隔离杜绝"被审仓库反向控制审查者"，敏感过滤与心跳监控则让长时审查既安全又可观察。对任何希望把多模型代码审查接入自身提交/发布流水线的团队，plate 仓库这套实现都是一个可以直接参考甚至复用的范本——入口脚本、冒烟测试与文档均位于 .agents/skills/autoreview 目录下。

【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate