zizi c9f69d9d6d 治理: Skill 测试治理第一阶段——harness 控制平面 + 实现测试迁出运行时目录

范围（不含 design-story-foundation、docs/、humanization/README.md 等进行中改动）:

1. 新增 harness/ 控制平面
   - skill_harness.py 静态审计：32 个运行时 Skill 的 frontmatter/manifest/文档污染，当前 0 问题
   - run_selected.py 选择性执行器：manifest 与磁盘一一对账、依赖阻断、
     空跑与 skip-only 失败关闭、AST 测试形状门
   - manifests/skills.json：32 个 Skill 的合同责任方与协作领域登记
   - manifests/test-inventory.json：81 个测试资产登记
   - specs/skill-testing.md 与 README.md：测试分层、证据边界与 harness 职责

2. 实现测试从 .claude/skills/*/scripts/ 迁至 tests/skills/<skill>/
   - 71 个测试文件迁移并修复项目根与临时目录运行导入
   - 数据库触发器测试宽泛异常收窄为 psycopg.errors.RaiseException
   - 抽取离线大测试拆出真实 PG smoke（默认阻断，不计入离线通过）
   - 抽取 presence 去重边界拆出独立测试：493 + 78 = 571 项检查不变

3. 运行时文档清理
   - 13 个 SKILL.md 移除自测/离线验证段落、测试命令与测试文件事实源表述，
     只保留运行时合同；业务运行合同、额度、授权与离线模式均保留

4. SoT 同步
   - AGENTS.md：新增 Skill 领域索引（7 个合同责任方分组，覆盖 32 个运行时 Skill）
   - 领域 07：测试入口改由 harness/manifests/ 登记，SKILL.md 不承载测试命令
   - humanization 覆盖矩阵：活动测试路径同步迁移

验证证据: harness 自测 15 项 + runner 自测 13 项通过；静态审计 32 Skill / 0 问题；
73 个非数据库测试通过；8 个集成条目中 6 个 PostgreSQL 项被依赖门明确阻断；
py_compile 与 git diff --check 通过。未连接 PostgreSQL、网络、真实模型或额度。

已知边界: 真正 skill_behavior_eval 仍为 0，尚未验证任何 Skill 自然语言行为；
evaluate-frozen-replay 的 raw 存储边界冲突留待单独治理。

2026-08-19 01:50:20 +08:00

5.3 KiB

Raw Blame History

Skill 测试与评测规范

状态：生效规范适用范围：agent-example/.claude/skills/*/SKILL.md、其确定性工具和 Skill 行为评测。 Owner：agent-example/harness/ 本文件是开发与评测支架规范，不属于任何 Skill 的运行时提示词。

1. 三层边界

1.1 Skill 运行时指令

SKILL.md 只描述 Agent 执行该 Skill 时必须知道的稳定合同：唯一目的、消费者、输入、输出、schema/version、允许读取、允许副作用、禁止动作、数据库读写、授权、预算、raw 和失败关闭规则，以及实际执行所需的业务工具与流程。

SKILL.md 不承载开发者测试说明、测试文件路径、测试框架命令、夹具细节或测试结论。

禁止在运行时 Skill 文本中出现：

## 自测、## 测试、## 开发验证 等开发测试章节；
test_*.py、*_test.py、pytest、unittest 等实现测试入口；
“本测试通过”“测试覆盖 N 项”等开发证据；
把测试文件、测试常量或测试输出说成事实源或业务合同。

评测 Skill 的生产/评测执行命令可以保留，但必须是用户请求该评测时实际执行的业务步骤，而不是验证实现代码的开发测试。

1.2 确定性工具验证

工具验证回答“Python、数据库或状态机实现是否守住机械合同”，不回答模型是否写得好，也不证明 Skill 的自然语言指令有效。

单元测试、离线合同测试和数据库集成测试属于这一层；
项目运行时 Skill 的实现测试统一放在 tests/skills/<skill>/，领域包保留自己的 tests/；两者都必须在 harness 的开发验证清单中登记；
测试通过只能证明列出的机械行为，不得升级为模型质量或产品可用性结论；
真实数据库、网络、模型和额度探针必须显式标记并单独授权。

1.3 Skill 行为评测

行为评测回答“把 Skill 内容交给 Agent 后，Agent 是否按合同行动”。评测由 harness 从外部驱动，不能由 SKILL.md 自己宣布通过。

行为评测至少区分：

正向触发：应该使用该 Skill 的任务；
负向触发：不应该使用该 Skill 的任务；
输入缺失与越界；
输出合同与失败关闭；
关键禁止动作；
多样例稳定性和已知混淆项。

行为评测结果必须保留输入、Skill 版本指纹、模型/运行配置、输出摘要、判定证据和失败原因。小样本合同回放不等于文学质量、通用效果或生产完成。

2. Harness 职责

Harness 只负责从外部发现、运行、收集和裁决测试/评测证据：

扫描运行时 Skill 文档中的开发测试污染；
登记和分类确定性工具测试、集成测试、fake pipeline 测试和真实探针；
驱动 Skill 行为评测案例；
生成带证据类型和失败原因的结构化报告；
防止空跑、静默跳过、宽泛异常吞错和证据级别越权。

Harness 不负责：

修改 SKILL.md 或业务代码；
判断文学质量；
用字符串出现证明自然语言合同有效；
把 fake、离线回放或小样本结果升级成生产结论。

3. 证据分级

从低到高仅表示证据类型，不允许自动跨级：

静态结构检查：frontmatter、路径、禁用污染模式；
确定性离线测试：纯函数、schema、状态机和失败分支；
真实依赖集成测试：PostgreSQL、文件系统或外部服务；
Skill 行为评测：外部 Agent/模型运行与结构化裁决；
人工内容评审：文学质量、声音和语义效果。

任一层通过都不能代替更高层证据。没有行为评测，不得声称 Skill 内容有效；没有真实依赖证据，不得声称生产链路可用。

4. 改动门禁

只改运行时合同

通过 harness 的运行时文档污染扫描；
更新受影响的行为评测案例，或记录只改措辞、不改变行为的理由；
不新增把测试细节塞回 SKILL.md 的说明。

只改确定性工具

更新针对变更不变量的离线测试；
对真实数据库、网络和模型测试单独标记；
保留失败关闭和副作用边界证据。

改变 Skill 意图或边界

更新行为评测清单和正/负向案例；
检查消费者、Agent 槽位和 meta/chains 映射；
重新执行相关层级的验证，不得只跑 Python 单测。

5. 明确禁止

用 assertIn 检查几个词出现，就宣称 Skill 内容正确；
用测试文件或测试输出作为运行时事实源；
用 except Exception: pass 把错误依赖、连接失败或实现错误当成预期拒绝；
用任意总入口的“零测试”结果当成通过；
把离线 fake、模型探针或小样本合同回放写成真实质量结论；
为了让 harness 变绿而修改业务合同、降低断言或静默跳过测试。

6. 完成定义

本治理任务只有同时满足以下条件，才可称为完成：

运行时 SKILL.md 不再携带开发测试说明；
harness 能机械发现并阻断明显的测试污染；
实现测试、集成测试和 Skill 行为评测的证据类型可区分；
改动范围内的回归测试真实执行，失败不会被吞掉；
报告明确区分已验证事实、推断和未验证的模型质量假设。

5.3 KiB Raw Blame History Unescape Escape