项目基线检查器 是做什么的?
一个可测试的就绪性标准:69 条规则,每条规则都对应一个零依赖的 Node 运行器在仓库静态时执行的检查。阻塞器会导致 CI 失败(exit 1);无法用脚本判断的事项通过带日期的签名台账来解决。核心思想:不要相信书面承诺——让 check 来验证。
工具包位于此文件同目录下:check.mjs(运行器)、rules.json(69 条规则)、config.example.json、templates/、README.md(快速入门指南)、REFERENCE.md(完整参考:规则表、分类、架构图、CI 接入)、以及 GLOSSARY.md(DevOps/供应链术语的通俗解释)。
首先解析技能目录。 下面 $SKILL_DIR 指的是包含此 SKILL.md 文件的目录的绝对路径——请将其解析为具体路径后再运行任何命令(不要将字面量字符串 $SKILL_DIR 传给 shell)。路径通常为 ~/.claude/skills/baseline。check.mjs 会从自身所在目录加载 rules.json,因此两者必须保持在同一位置;始终通过绝对路径调用运行器(node "<abs>/check.mjs" …),而不是将其复制到其他地方。运行器仅需要 Node ≥ 18 和 git;如果 node 缺失,请告知用户,而不是自行猜测。
调用方式
根据用户的话语推断意图,并选择模式。如果未指定,默认使用 score。
模式:score(默认)——"运行基线检查"、"/baseline"、"检查此仓库"
- 选择目标仓库:请求中明确给出的路径,否则为当前工作目录。确认它看起来像个仓库(有清单文件或
.git)。 - 运行运行器(人类可读):
node "$SKILL_DIR/check.mjs" --repo <target>- 如果绝对不要执行仓库的引导/测试命令(BUILD-05),则添加
--no-exec——例如在不可信的仓库、没有时间运行测试、或命令未配置的情况下。在安全时优先执行,因为 BUILD-05 是最重要的检查。 - 如果用户想要专家级规则(SBOM、代码扫描、变异测试、符号完整性、依赖漏洞扫描、覆盖率下限),则添加
--profile advanced。当project_type=service时,service配置会自动启用。 - 添加
--json以便以编程方式解析结果,而不是显示评分卡。
- 如果绝对不要执行仓库的引导/测试命令(BUILD-05),则添加
- 向用户展示结果,首先展示阻塞器(这些会导致 CI 失败),然后是需要修复的警告。按类别分组。不要倾倒全部 69 行——总结:就绪百分比、阻塞器数量、以及具体的 FAIL/值得注意的 WARN 及其一行说明。提供修复或搭建的选项。
模式:init——"在此处设置基线"、"采用此标准"、"搭建基线"
- 将工具包复制到仓库中(建议
tools/baseline/),或者原地引用。 - 只在文件缺失时搭建构件(未经询问绝不覆盖):
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # 仅当仓库有对外声明时 cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # 如果尚无状态文档 mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json - 根据仓库实际情况编辑
baseline.config.json:设置project_type、bootstrap_command(用于 BUILD-05 的干净检出安装+测试命令)、以及makes_external_claims(设为 false 将跳过 CLAIM-* 规则)。可选的*_globs键(freshness/generated/grounding)保持为空,直到仓库采用相应约定。 - 向他们展示
README.md中的 CI 接入方式,并将baseline作业设为必需检查(即 BUILD-06 规则)。 - 运行第一次评分。
模式:fix——"修复基线失败项"、"让它全绿"
- 先评分。对于用户希望解决的每个阻塞器/警告,应用规则自身的
fix字段(从rules.json中读取)作为具体编辑操作——添加缺失的 LICENSE、将 action 固定到 SHA、将.env添加到.gitignore并轮换密钥、添加负面测试等。 - 对于
manual(签名)规则,不要伪造检查——帮助用户完成判断(影响范围、已有方案检查、wedge/moat),并在.project-baseline/signoff.json中记录带日期的条目。 - 重新评分以确认。
模式:explain——"SEC-03 检查什么"、"为什么 CTX-05 失败"
从 rules.json 中读取规则(每条规则包含 title、rationale、fix、source 和 check)并通俗地解释,同时说明运行器实际检查了什么。对于不熟悉的术语(SBOM、SLSA、来源证明、签名台账等),此目录中的 GLOSSARY.md 提供了通俗定义。
运行器如何进行判断(以便你解释详细输出)
- 每条规则结果为 PASS / FAIL / WARN / SIGN-OFF / SKIP。只有
blocker类型的 FAIL 才会导致退出代码 1。 - SKIP 表示该规则不适用:
project_type不匹配(n/a for <type>)、处于关闭状态(profile 'advanced' off)、采用的可选功能尚未启用、或没有可检查的内容。跳过项不计入就绪百分比。 - 配置层级:
core始终运行;service在project_type=service时自动运行;advanced仅在--profile advanced或配置中profiles:["advanced"]时运行。 - 声明是可选加入: CLAIM-* 仅在声明注册表存在或明确设置
makes_external_claims:true时运行。没有声明注册表的仓库不会受到惩罚。 - 配置会自动检测;仓库根目录下的
baseline.config.json会覆盖默认值。各键的含义详见config.example.json。 - 运行器是零依赖的(Node ≥ 18 + git)且具有崩溃恢复能力:某个规则的检查无法执行时,会降级为 SKIP,绝不会导致整个运行失败。
注意事项
- 切勿将警告误报为阻塞器,反之亦然——严重性定义在
rules.json和运行器的输出中。 - 在仓库可信且引导命令已设置的情况下,优先真实运行 BUILD-05(省略
--no-exec)——绿色的最重要检查是最强的单一信号。 - 完整原理、规则表、类别描述、架构图和 CI 片段位于此目录的
REFERENCE.md中——如果用户想要深入了解,请读取该文件。