企业官网建设流程全解析

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

【免费下载链接】Pake🤱🏻 Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/Pake

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 发布版本四处同步

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

这条规则在仓库中有可执行的落地物：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 的写法是一个可直接套用的模板。

【免费下载链接】Pake🤱🏻 Turn any webpage into a desktop app with one command.项目地址: https://gitcode.com/GitHub_Trending/pa/Pake