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

Pake 代码评审把 15 条 Hard Stop 规则变成可复现的 Agent 评审流程【免费下载链接】Pake Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/PakePake 是一个把网页打包成 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.jsfiles白名单包含dist/cli.js与src-tauriexports也直接指向./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_ENVproduction rollup -c与开发态的rollup -c -w区分开。2.2 发布版本四处同步第三条规则要求版本升级时保持四份文件一致文件版本载体当前仓库值package.jsonversion字段3.15.7src-tauri/Cargo.toml包级version3.15.7src-tauri/Cargo.lockpake包条目3.15.7src-tauri/tauri.conf.jsonversion字段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.ymlid-token: write权限——Trusted Publishing 依赖 OIDC 令牌换发 npm 访问凭证去掉该权限即断掉无密钥发布链路该工作流的权限声明位于文件 npm-publish.yml 第 25 行附近规范仓库标识githttps://github.com/tw93/Pake.gitcheck-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等无类型配置对象。仓库已存在强类型PakeTauriConfigbin/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 CommandsSKILL.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.jspnpm test脚本本身是pnpm run cli:build cross-env PAKE_CREATE_APP1 node tests/index.js而 runner 解析--no-build参数后会跳过真实构建real build测试见 tests/index.js 第 1561–1598 行的参数解析与用法注释因此这是开发期“跑全套但不编译 Tauri”的快速路径pnpm run cli:build以NODE_ENVproduction运行 Rollup 生产构建生产模式下 TypeScript 插件开启noEmitOnError: truerollup.config.js 第 52 行类型错误会直接使构建失败从而在评审前捕获 TS 问题。四、评审输出格式文档末尾对输出格式做了收敛要求遵循 Waza/check的“findings first”原则——问题列表优先按严重度排序每条给出紧凑的文件/行号引用总结保持简短。结合本文拆解的 15 条规则一次完整的 Pake PR 评审流程可以归纳为取 diffgh pr diff先跑format:check与npx vitest run两条快速门禁按 diff 触碰的区域对照 Hard Stops 逐条排查碰了bin/或包元数据查dist/cli.js是否重新提交碰了版本号核对四处版本 check-release-version.mjs碰了发布工作流核对id-token: write、规范仓库标识与门禁步骤检查类型PakeTauriConfig、错误处理无静默 catch、无新增用户可达unwrap、测试同生tests/unit/basename.test.ts、二进制往返测试输出按严重度排序的 findings附文件:行号引用控制总结篇幅。这套适配器的价值不在于命令本身而在于它把 Pake 发布链路中真实踩过的坑——产物未重打包、版本四处不一致、手动触发误推标签、Trusted Publishing 权限被误删——逐条翻译成了 Agent 可直接执行的检查项。对于同样维护“CLI 产物 原生应用 npm 发布”多真相面的项目这份 SKILL.md 的写法是一个可直接套用的模板。【免费下载链接】Pake Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/Pake创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考