Pake 代码评审：把 15 条 Hard Stop 规则变成可复现的 Agent 评审流程

Pake 是一个把网页打包成 Tauri 桌面应用的 CLI 工具，其发布链路横跨 TypeScript 单文件构建、四份版本文件和 npm Trusted Publishing 工作流。本文基于仓库内的代码评审技能文件 SKILL.md，完整解读 Pake 为 AI Agent 定制的 Code Review 适配器：它如何在通用评审方法之上叠加 15 条项目专属的“硬性停止规则（Hard Stops）”，提供一套可直接复制的快速评审命令，并规定评审输出的组织格式。读完本文，你可以照此在 Pake 仓库（或结构类似的 Tauri + npm 双发布项目）中执行一次有据可依的代码评审。

一、评审适配器的定位：通用方法 + 项目约束

.agents/skills/code-review/SKILL.md 是一份面向 Agent 的技能定义文件，其 YAML frontmatter 声明了技能元信息：技能名为 code-review，版本 1.2.0，允许使用的工具限定为 Bash、Read、Grep、Glob，并设置了 disable-model-invocation: true（即不由模型自动触发，需显式调用）。文档开篇即声明分工：通用评审方法沿用 Waza /check 流程，本适配器只负责叠加 Pake 特定的命令、硬性停止规则（Hard Stops）和发布产物（artifact）规则。

这种“通用方法 + 项目补丁”的组织方式值得借鉴：评审方法论（如何取 diff、如何排序问题）是稳定的，而真正决定评审质量的，是针对项目自身发布机制、构建产物和易错点逐条固化的约束。以下按主题拆解这 15 条 Hard Stops。

二、Hard Stops 详解（按主题分组）

2.1 构建产物与 Rollup 内嵌元数据同步

第一条与第二条规则针对同一个风险点：bin/ 目录下的 TypeScript 源码会被 Rollup 打包成单文件 dist/cli.js，而这个产物是必须提交进仓库的发布物，不是纯生成缓存。

仓库证据支撑了这一规则：

• package.json 中 bin 字段将 pake 命令指向 dist/cli.js，files 白名单包含 dist/cli.js 与 src-tauri，exports 也直接指向 ./dist/cli.js——也就是说，npm 包对外暴露的入口就是这个构建产物；
• package.json 的 repository.url、version 等元数据会被 Rollup 插件体系嵌入产物。rollup.config.js 中生产模式以 bin/cli.ts 为入口、输出 dist/cli.js，并通过 @rollup/plugin-json 引入 JSON 配置、用 replace 插件固化 process.env.NODE_ENV，因此 package.json 的 name/version/repository/bin/scripts/exports 一旦变化，产物内容也随之变化。

由此得出评审动作：任何改动 bin/ 或上述包元数据的 PR，必须附带用 pnpm run cli:build 重新生成并提交的新 dist/cli.js，否则 npm 用户装到的仍是旧逻辑。cli:build 脚本定义为 cross-env NODE_ENV=production rollup -c，与开发态的 rollup -c -w 区分开。

2.2 发布版本四处同步

第三条规则要求版本升级时保持四份文件一致：

文件	版本载体	当前仓库值
package.json	version 字段	3.15.7
src-tauri/Cargo.toml	包级 version	3.15.7
src-tauri/Cargo.lock	pake 包条目	3.15.7
src-tauri/tauri.conf.json	version 字段	3.15.7

这条规则在仓库中有可执行的落地物：scripts/check-release-version.mjs 会解析上述四处版本并与 package.json 逐项比对，此外还检查 dist/cli.js 中打包进去的版本字符串、repository.url 是否为规范值，以及 files 白名单必须包含 LICENSE-EXCEPTION、llms.txt、dist/cli.js 且不得整体打包 dist 目录。评审时凡见版本号变更，应确认该脚本仍能在 CI 通过，而不是人工目测四份文件。

该脚本还有一个值得注意的细节：它只在 GITHUB_REF_TYPE === "tag" 时才信任 GITHUB_REF_NAME 作为发布标签，因为 workflow_dispatch 手动触发时该环境变量持有的是分支名而非版本——这正是第七条规则的由来。

2.3 npm Trusted Publishing 工作流保护

第四条规则约束 npm 发布工作流的改动，必须保留以下要素：

• 工作流文件 .github/workflows/npm-publish.yml；
• id-token: write 权限——Trusted Publishing 依赖 OIDC 令牌换发 npm 访问凭证，去掉该权限即断掉无密钥发布链路（该工作流的权限声明位于文件 npm-publish.yml 第 25 行附近）；
• 规范仓库标识 git+https://github.com/tw93/Pake.git（check-release-version.mjs 第 82–86 行会校验 package.json 的 repository.url 与此完全一致）；
• scripts/check-release-version.mjs 本身。

从工作流步骤看（Check release version → Check formatting → Run unit tests → Build CLI → Check package contents → Publish to npm → Verify published version），发布前已内置了版本、格式、单测与产物检查门禁，评审此类 PR 时若看到门禁被裁剪或权限被改动，应直接标记为高风险变更。

2.4 发布状态的多真相面分离

第五条规则指出：npm registry、GitHub Release/附件、工作流运行状态、issue 关闭这四个“真相面”必须各自独立维护，不能把一处状态当作另一处的代理。第六条规则则针对 workflow_dispatch 手动触发发布的路径：不得从 headBranch、运行标题或 compare UI 推断发布标签，必须使用显式的 tag/ref，并核对发布包的 gitHead 字段。理由如 check-release-version.mjs 第 7–11 行的注释所示——手动触发时 GITHUB_REF_NAME 持有分支名，若被误当版本会导致发错包。

2.5 CLI 参数新增需显式论证

第七条规则针对 CLI 表面（surface）膨胀：任何新的用户可见 flag、别名或帮助文案变体，必须附带“为什么现有选项或默认值无法覆盖”的显式论证，且该论证需维护者认可，不接受评审者自行推断。Pake CLI 已有 --width、--height、--hide-title-bar、--multi-arch、--proxy-url 等参数（可参考 tests/index.js 中的 E2E 用例），评审时应优先建议复用既有参数组合。

2.6 类型与错误处理红线

第八至第十条是三条硬性代码红线：

• 禁止新增 tauriConf: any 等无类型配置对象。仓库已存在强类型 PakeTauriConfig，bin/helpers/merge.ts 中多处函数签名（如 mergeWindowOptions、配置合并入口）均以 PakeTauriConfig 为参数类型；新增代码应沿用该类型而非退化为 any；
• 用户可达路径上禁止 panic! / .unwrap()。评审 src-tauri/ 下涉及配置解析、CLI 事件处理的 Rust 代码时，应确认错误沿 Result 向上传递。需要注意仓库现状：src-tauri/src/ 下仍有若干 unwrap 调用（如 lib.rs 中对静态常量 URL 的解析、util.rs 等），评审重点是新增用户可达路径不得扩大这一模式；
• 禁止静默 catch {}：错误必须通过 logger.warn 透出真实信息（日志组件见 bin/options/logger.ts）。

2.7 测试同生规则

最后两条规则把“实现变更”与“测试变更”绑定：

• 第十一条：bin/utils/ 或 bin/helpers/ 下每新增一个工具模块，必须有对应的 tests/unit/<basename>.test.ts。仓库中可验证这一约定：bin/utils/ico.ts ↔ tests/unit/ico.test.ts、bin/utils/name.ts ↔ tests/unit/name.test.ts、bin/options/icon.ts ↔ tests/unit/icon.test.ts，文件名一一对应；
• 第十二条：二进制解析器（如 ICO 解析）必须有往返测试（round-trip test）——即“解析 → 再序列化 → 对比”闭环，不能只靠 builder 侧断言；
• 第十三条：Linux WebKit/AppImage 运行时 flag 变更必须保持默认值保守、补充决策逻辑测试，且当用户可能需要回退命令时同步更新 docs/faq.md / docs/faq_CN.md；
• 第十四条：macOS --new-window 或鉴权 URL 相关变更，必须附带针对弹窗/鉴权路由的定向测试，对应注入脚本为 src-tauri/src/inject/event.js。

三、快速评审命令（Quick Review Commands）

SKILL.md 给出五条评审常用命令，以下保留原样并补充其在仓库中的实际含义：

# Get PR diff
gh pr diff

# Format check
pnpm run format:check

# Run unit tests (fast, sub-second)
npx vitest run

# Full suite without the slow real build
pnpm test -- --no-build

# Build CLI and catch TypeScript errors
pnpm run cli:build

逐条对照源码：

• pnpm run format:check 在 package.json 中定义为 prettier --check . --ignore-unknown，只检查不写入，适合 CI 与评审前自检；
• npx vitest run 的行为由 vitest.config.ts 决定：include 覆盖 bin/**/*.{test,spec}.ts、tests/unit/**、tests/integration/** 三个位置，且 resolve.alias 将 @ 指向 ./bin——这与 rollup.config.js 中 @ → bin 的别名保持一致，保证测试与生产构建引用同一套模块路径；
• pnpm test -- --no-build 走统一测试入口 tests/index.js：pnpm test 脚本本身是 pnpm run cli:build && cross-env PAKE_CREATE_APP=1 node tests/index.js，而 runner 解析 --no-build 参数后会跳过真实构建（real build）测试（见 tests/index.js 第 1561–1598 行的参数解析与用法注释），因此这是开发期“跑全套但不编译 Tauri”的快速路径；
• pnpm run cli:build 以 NODE_ENV=production 运行 Rollup 生产构建，生产模式下 TypeScript 插件开启 noEmitOnError: true（rollup.config.js 第 52 行），类型错误会直接使构建失败，从而在评审前捕获 TS 问题。

四、评审输出格式

文档末尾对输出格式做了收敛要求：遵循 Waza /check 的“findings first”原则——问题列表优先，按严重度排序，每条给出紧凑的文件/行号引用，总结保持简短。

结合本文拆解的 15 条规则，一次完整的 Pake PR 评审流程可以归纳为：

1. 取 diff（gh pr diff），先跑 format:check 与 npx vitest run 两条快速门禁；
2. 按 diff 触碰的区域对照 Hard Stops 逐条排查：碰了 bin/ 或包元数据？查 dist/cli.js 是否重新提交；碰了版本号？核对四处版本 + check-release-version.mjs；碰了发布工作流？核对 id-token: write、规范仓库标识与门禁步骤；
3. 检查类型（PakeTauriConfig）、错误处理（无静默 catch、无新增用户可达 unwrap）、测试同生（tests/unit/<basename>.test.ts、二进制往返测试）；
4. 输出按严重度排序的 findings，附 文件:行号 引用，控制总结篇幅。

这套适配器的价值不在于命令本身，而在于它把 Pake 发布链路中真实踩过的坑——产物未重打包、版本四处不一致、手动触发误推标签、Trusted Publishing 权限被误删——逐条翻译成了 Agent 可直接执行的检查项。对于同样维护“CLI 产物 + 原生应用 + npm 发布”多真相面的项目，这份 SKILL.md 的写法是一个可直接套用的模板。