build2-community/build2-review

build2-review 是做什么的？

解析 ROOT

令 HERE 为包含此 SKILL.md 的目录（系统上下文中的绝对路径）。

ROOT 是 build2 技能树。使用第一个其 guides/packaging-guide-review.md 存在的候选路径：

1. HERE/../build2（同级布局：此目录位于 build2 技能旁边，包括复制到用户级技能目录中的副本）
2. HERE/../..（嵌套布局：此目录位于 build2 技能的 skills/ 子目录下）

如果都不存在，则停止。

所有后续的 read_file 路径均为 ${ROOT}/...。

这是一个只读的本地完整性检查。它的存在是为了在发布前捕获打包问题，通过运行 cppget.org 审查员会使用的相同清单对仓库进行检查。它绝不能创建、评论或合并 GitHub 问题或拉取请求，绝不能推送分支，绝不能发送电子邮件，也绝不能修改正在审查的仓库（无提交、无标签、无文件编辑、无 bdep release、无 bdep publish、无 git push）。如果以下某个步骤会进行此类更改，则跳过该步骤并将其转化为报告的发现。正在审查的仓库必须在此检查前后完全一致。为报告的发现起草计划（而不执行该计划）不算作更改，请参见“计划模式”部分了解何时适用。

${ROOT}/guides/packaging-guide-review.md 中的清单和标准是真理之源。复制清单项。不要转述所需标准。不要发明审查标准。

审查仅涵盖构建和打包支持。忽略上游源码质量、上游文档以及上游 C/C++ 的风格。

硬性规则

1. 无外部可见更改：绝不能创建、评论或合并 GitHub 问题或拉取请求，绝不能推送分支，绝不能发送电子邮件。这是无条件的，即使用户在运行过程中明确要求执行其中一项操作也适用：拒绝并引导他们使用单独的手动审查工作流程（请参见下面的“停止并询问”），而不是在此处执行。
2. 不更改正在审查的仓库：无提交、标签或文件编辑，无 git push，无 bdep release，无 bdep publish。仅做检查（git log、git show、git diff、读取文件）。如果需要构建或测试某些内容来验证某一项，请在临时目录中进行树外构建，切勿在正在审查的仓库的工作树内进行。
3. 如果提供了本地路径，则直接使用它，只读。不要检出不同的 ref，不要执行 stash 或 reset。
4. 如果提供了远程仓库或 URL，则将其只读克隆到 /tmp/claude/ 下的临时目录中。切勿使用具有推送功能的远程仓库或 git push。将克隆视为一次性使用。
5. 未经亲自验证，切勿勾选清单项。
6. 阻塞与非阻塞的区分遵循指南的标准。如有疑问，请明确说明，而不要默默降级概念性的 buildfile 错误。
7. 输出是对话中的报告（可选地也写入 /tmp/claude/ 下的临时文件）。切勿将其发布到任何外部位置。

强制性读取（报告发现之前）

在报告任何发现之前，使用 read_file 完整读取以下文件。不要略读。

1. ${ROOT}/guides/packaging-guide-review.md
2. ${ROOT}/guides/packaging-guide-antipatterns.md
3. ${ROOT}/HOWTO/package-naming.md
4. ${ROOT}/guides/packaging-guide-testing.md，仅第 9 步（“测试包”）部分。第 10 步（“发布”）将 review 合并到 main，此范围之外，忽略它。

按末尾的映射表按需加载。packaging-guide-review.md 中的初始审查清单是您要处理的清单。该文件是唯一的副本。

参数

$ARGUMENTS 是 /build2-review（或 /build2 review）之后的文本。按顺序解析。第一个匹配的规则获胜。

第一个令牌	种类
空 / 省略	解析目标后自动检测
initial	完整首次提交清单
version	新上游版本，基于差异
revision	新打包修订版，基于差异并增加额外检查
其他任何内容	视为 <repo-or-local-path> 并自动检测种类

剩余令牌：<repo-or-local-path>（GitHub URL、owner/repo 或本地克隆路径）和可选的 <version>。如果目标缺失，请询问。

在开始之前将选定的种类和版本报告给用户。

获取仓库

如果用户提供了本地路径，则直接使用它，只读。

否则，只读克隆到临时目录（永远不要推送到此克隆，也永远不要将其添加为其他任何内容的推送目标）：

git clone --recurse-submodules --shallow-submodules <url> /tmp/claude/<name>

分类

从 manifest 的 version: 字段确定 <VERSION>（如果有多个包，则取最新的已发布标签）。确定种类：

证据	种类
尚无已发布标签，或者被审查的 ref 仍是第一个 bdep new 提交	initial
已存在 vX.Y.Z 标签，并且此版本是 X.Y.Z+R	revision
之前版本已打标签，这是新的 X.Y.Z	version

验证仓库的第一个提交（只读）：

git log -p "$(git rev-list --all | tail -1)"

该提交必须仅包含 bdep new 生成的文件，其消息必须是确切的命令行。记录任何偏差作为发现。不要忽略。

种类：initial

对照 packaging-guide-review.md 中“初始审查清单”部分的每一项对仓库进行检查。仅在亲自验证后（目录树、manifest、buildfile、安装布局、测试、标签）才勾选项。对每个项使用链接的 HOWTO/指南，而不是凭记忆。

完全按照指南的方式对每个发现进行分类：

类别	场景
阻塞	高严重性或影响、影响许多用户、概念性错误（buildfile 中的错误编译选项）、或后期无法在不破坏兼容性的情况下修复
非阻塞	应在修订版或下一版本中修复，不使检查失败
备注	仅观察

检查时按需加载：

• 名称：${ROOT}/HOWTO/package-naming.md
• 许可证：${ROOT}/guides/packaging-license.md
• 伴随的 -tests 摘要/README：${ROOT}/HOWTO/tests-extra-dependencies.md
• 私有头文件：${ROOT}/HOWTO/third-party-private-headers.md
• 编译选项：${ROOT}/HOWTO/buildfile-compile-options.md
• 不该做什么：${ROOT}/guides/packaging-guide-antipatterns.md
• buildfile、manifest 或 README 中的日记式注释或笔记（过程叙述、早期尝试无效的方法、过程中的意外）：${ROOT}/guides/packaging-guide-antipatterns.md，“不要留下日记式注释或笔记”

在验证“对上游使用 git 子模块和符号链接”时：还在每个包目录中运行 find . -type l -exec test -d {} \; -print，并确认每个结果在该包自己的 <pkg>/.gitattributes 中都有匹配的 symlink=dir 条目（参见 ${ROOT}/guides/packaging-guide-summary.md 第 5 步）。git 不记录符号链接类型，因此缺少此条目的目录符号链接会静默破坏 Windows 检出。将缺失条目视为阻塞。

测试安装和分发

静态检查清单还不够。还需要在树外构建包以捕获仅在构建时才会显现的问题（缺失或私有头文件进入安装树、buildfile 图中缺失文件、损坏的 clean 规则）。在 /tmp/claude/ 下的临时目录中进行，绝不在被审查的仓库内。遵循 ${ROOT}/guides/packaging-guide-testing.md 中的“第 9 步：测试包”：

1. 安装情况： b install config.install.root=/tmp/claude/<name>-install，然后针对该安装副本进行源外构建并运行 tests/。确认没有意外安装（没有缺失的头文件，没有错误安装的私有头文件）。
2. 源码分发： b dist config.dist.root=/tmp/claude/<name>-dist config.dist.uncommitted=true，然后在提取的存档中运行 configure、update、test 和 clean。仅凭绿色通过的 bdep test 是不够的，这是 cppget.org 实际构建包的方式。

之后删除两个临时目录。将任何失败记录为发现（安装或分发不正确的包通常是阻塞的）。

报告

使用与指南结果注释相同的节布局向用户展示结果，但不要将其发布到任何地方：

阻塞问题：

...

非阻塞问题：

...

备注：

...

省略空节。如果写了临时副本，请提及它的路径。

种类：version

将基础（之前已审查的）版本与目标版本进行对比。如果克隆中两个标签都可用，则首选本地的 git diff <old-tag>..<new-tag>，否则使用 GitHub 对比视图：

https://github.com/<owner>/<project>/compare/vOLD...vNEW

注意构建级别的兼容性：重命名的导出目标或配置变量即使上游的 API 是稳定的，也是破坏性更改。

报告以下之一：

1. 无实质性打包更改，无问题： 直接说明，无需清单。
2. 无实质性打包更改，存在问题： 直接列出它们（无需清单）。
3. 实质性打包更改： 运行完整的上述初始流程，清单以及安装和分发测试。

种类：revision

与 version 相同，另外如果以下任何一项不成立，则将其标记为发现：

• 更改仅限于 buildfile、manifest 和类似打包文件中的错误修复。
• 上游源码修复仅限于从上游反向移植的关键错误。
• 严格向后兼容它所替换的版本。
• 没有主要的结构性更改（源码布局、导出的目标名称、配置变量名称）。

计划模式

此技能无论哪种情况都保持只读，它从不自行执行修复。仅改变的是是否在报告旁边起草所需更改和改进的计划。

• 如果当前会话处于计划模式（期望助手在做出更改之前提出实施计划以供批准，而不是立即执行）：报告后，也起草一份解决阻塞和非阻塞发现的计划，然后通过环境提供的任何计划批准机制呈现它。计划的範圍限于阻塞和非阻塞发现，除非用户要求，否则跳过备注。将相关修复分组，并指出任何涉及生成的 bdep new 布局、manifest 或 buildfile 文件且需要特别注意或排序的修复。
• 否则，按照既定的报告流程进行并就此停止。不要起草、提议或暗示实施计划，修复由用户或单独的工作流程来执行。

停止并询问

当以下任一情况为真时，停止而不是猜测：

• 您无法确定版本或种类。
• 您无法访问仓库（克隆失败，本地路径无效）。
• 第一个提交不是 bdep new 提交，并且用户尚未决定如何在报告中记录该情况。
• 对于会破坏兼容性的发现，阻塞与非阻塞不明确。
• 用户要求实际打开 GitHub 审查问题/PR、合并某些内容或发送 [email protected] 电子邮件。这是一个单独的、超出范围的此技能不执行的工作流程。
• 用户要求创建包而不是检查它（切换到 build2-package）。

按需加载映射表

需要	文件
清单和标准	${ROOT}/guides/packaging-guide-review.md
不该做什么	${ROOT}/guides/packaging-guide-antipatterns.md
名称	${ROOT}/HOWTO/package-naming.md
许可证	${ROOT}/guides/packaging-license.md
伴随包	${ROOT}/HOWTO/tests-extra-dependencies.md
创建包	../build2-package/SKILL.md