automated-assessment

自动化评估技能

针对启用检查点的技能进行系统性合规评估。

用法

/assess                              # All matching skills
/assess skill-repo typo3-testing     # Specific skills only
/assess --force                      # Ignore preconditions
/assess --mechanical-only            # Scripted checks only
/assess --autofix                    # Fix issues automatically
/assess --review                     # Categorize failures
/assess --autoimprove                # Fix + propose improvements
/assess dependency-compatibility     # Dependency compat checks
/assess --pre-push                   # Pre-push validation gate
/assess --check-coverage             # Verify checkpoint coverage

选项

选项	效果
<skill-names>	仅运行指定技能的检查点（也接受 dependency-compatibility 等领域名称）
--force	跳过前置条件检查
--mechanical-only	跳过 LLM 审查
--autofix	通过负责的技能修复失败项，并重新验证
--review	对失败项分类，并提出技能改进建议
--autoimprove	修复并提出检查点变更建议；添加 --create-issues 以创建问题
--json	原始 JSON 输出
--pre-push	运行推送前门禁（PHPStan、测试、PHP-CS-Fixer、Rector）
--check-coverage	验证检查点覆盖是否充分

步骤

1. 记录目标修订版本、环境和预期范围；查找匹配的检查点
2. 运行机械检查点，并将执行失败与项目缺陷分别记录
3. 按领域归类所需的 LLM 检查；独立验证候选发现
4. 分别报告已确认的发现、未解决的检查和覆盖情况

进行 LLM 审查时，请使用 references/checkpoint-workflow.md 中的候选项／验证契约。 向验证者提供原始证据和相关仓库访问权限，不要提供作者的结论。 仅在风险相互独立时选择并行专家；对于未变化的修订版本和属性，复用证据，不要为每项技能另开一轮。共享任务的审查预算，最多进行三轮修复／审查；之后必须明确报告未解决结果。

评估优先规则

在进行项目范围的质量增强（覆盖率、变异测试、质量门禁或静态分析级别）之前，先运行适用的评估。其差距报告将作为任务清单。对于范围已经明确的小型变更，应保持关注点不变；如果没有检查点覆盖请求，不要凭空创建无关评估，也不要用近似匹配的技能替代。

工作流

1. 使用相关技能运行 /assess
2. 审查差距报告——这将成为任务清单
3. 按优先级修复（先处理错误，再处理警告；使用 --autofix 自动解决）
4. 重新运行 /assess 进行验证

没有合适选项时，请如实说明

不要选择技能，胜过选择最接近的技能。 如果没有任何可用技能的检查点覆盖该请求，请报告这一点并停止。在一项消融研究中，替换为相邻领域技能的得分甚至低于完全不选择技能——参见 references/capability-selection.md。

此结论在运行任何检查点之前得出，因此没有运行结果可序列化：--json 无报告可输出，应以自然语言向调用方说明差距和接近但不匹配的选项。不要为此合成 skill_gaps 条目——该结构包含检查点失败的 skill，而此处没有选择任何技能，也没有进行任何测量。

在不使用 /assess 的情况下运行单个技能的检查

单跳形式是带有技能名称的斜杠命令——/assess typo3-extension-upgrade——在另一个技能的工作流中使用时，应优先选择这种形式。它不需要路径。

直接调用适用于脚本和不支持斜杠命令的测试框架。它需要加载器基础目录中的同级路径、检查点文件，以及作为最后一个参数的项目根目录，并且每个 target: 都会相对于该根目录解析——如果从其他位置运行，检查就会读取错误的目录树。检查点文件是技能 front matter 中 checkpoints: 下指定的文件；只有在未指定文件时，才使用技能基础目录下的 checkpoints.yaml（详见 references/checkpoint-workflow.md 中的发现规则）。如果技能覆盖了检查点文件，却传入根目录下的文件，就会运行错误的文件，或不运行任何文件。

cd <project-root>
"$SKILL_DIR/../automated-assessment/scripts/run-checkpoints.sh" --force \
  "<the checkpoint file that rule resolves to>" .

经过测量，这也是优先提及斜杠命令的原因：将直接调用作为一个步骤放进技能正文后，三次试验中它都出现在 Agent 的上下文中，却一次也没有被尝试——十二次试验中没有一次绑定过任何类型的变量，因此，需要拼装路径的调用就是不会被采用的调用。将相同的检查写成正文中可直接粘贴运行的代码块后，三次试验中它都运行了。调用方已知前置条件成立时，--force 会跳过这些条件；--json 用于生成机器可读的报告。每条结果行都包含检查点 ID、其 desc 和一条证据字符串；对于 script 类型的检查，该证据仅为“脚本失败”——运行器不会透传脚本本身的输出——因此，检查的 desc 会告诉你该去哪里查看。blocked 行表示运行器拒绝了该命令，检查从未运行。

检查点类型

机械检查： file_exists、file_not_exists、contains、not_contains、regex、json_path、gh_api、command。大模型检查： llm_review（按领域分组）。参见 references/checkpoints-schema.md。

领域

repo-health security code-quality documentation git-workflow docker ddev upgrade dependency-compatibility pre-push

自动修复与审查

--autofix 会调用负责的技能处理失败项，并重新验证。状态：auto-fixed、needs-review、unfixable。--review/--autoimprove 会创建反馈循环。

推送前门禁

只检查已安装的工具（vendor/bin/*）。缺少的可执行文件会被跳过，而非视为通过；即使干净退出且有工具被跳过，也不能证明已完成全面验证。 ID：PP-01（PHPStan）、PP-02（PHPUnit）、PP-03（PHP-CS-Fixer）、PP-04（Rector）。

严重级别

error = 阻止发布，warning = 建议，info = 可选。

结果

pass fail skip blocked——分别计数（total == pass + fail + skip + blocked）。如果命令对应的可执行文件不存在（未安装 Composer 时的 vendor/bin/*，或不在 PATH 中的工具），则记为 skip，证据为 executable not found: <word>，而不是发现的问题。

绝不要将 blocked 检查点报告为发现的问题。 这表示运行器通过其允许列表拒绝了该命令，因此没有测量任何内容：缺陷出在检查点文件，而非受评估的项目。将被阻止的检查点报告为失效检查，针对所属技能运行 scripts/validate-checkpoints.sh <file>，并在该技能中提交问题。被拒绝的前置条件也是同一情况，只不过高一层——JSON 原因写的是 REFUSED by the runner allowlist，这与“此技能不适用”并不相同。参见 references/checkpoints-schema.md →“结果”。

只有在注明测量范围的情况下，零个已确认发现才是有效结果。缺少工具或资源、超时、无法获取证据以及审查中断，都会导致该范围不完整；它们既不代表阴性测试成功，也不能证明项目存在缺陷。保留运行器的四种状态，并在评估报告中记录执行原因。静态审查不等于测试执行，报告本身也不会强制执行合并门槛或构成人工批准。证据等级参见 references/verification-patterns.md，发现问题的处置方式和后续遗漏的缺陷参见 references/calibration.md。

参考资料

• references/checkpoints-schema.md -- 检查点 YAML 架构和类型
• references/learning-derived-checkpoints.md -- 从复盘到检查点的路由约定
• references/checkpoint-coverage-requirements.md -- 每项技能必须覆盖的类别
• references/capability-selection.md -- 为什么拒绝优于替代，以及用于衡量这一点的消融实验
• references/checkpoint-workflow.md -- 包含自动修复循环的完整评估工作流
• references/calibration.md -- 校准债务、审计频率、生成时的锚点、棘轮反模式
• references/dependency-compatibility.md -- 多主版本评估触发条件
• references/migration-guide.md -- 如何向现有技能添加检查点
• references/verification-patterns.md -- 验证模式和结果架构