c9f69d9d6d
范围（不含 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 存储边界冲突留待单独治理。
116 lines
5.3 KiB
Markdown
116 lines
5.3 KiB
Markdown
# 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 只负责从外部发现、运行、收集和裁决测试/评测证据：
|
||
|
||
1. 扫描运行时 Skill 文档中的开发测试污染；
|
||
2. 登记和分类确定性工具测试、集成测试、fake pipeline 测试和真实探针；
|
||
3. 驱动 Skill 行为评测案例；
|
||
4. 生成带证据类型和失败原因的结构化报告；
|
||
5. 防止空跑、静默跳过、宽泛异常吞错和证据级别越权。
|
||
|
||
Harness 不负责：
|
||
|
||
- 修改 `SKILL.md` 或业务代码；
|
||
- 判断文学质量；
|
||
- 用字符串出现证明自然语言合同有效；
|
||
- 把 fake、离线回放或小样本结果升级成生产结论。
|
||
|
||
## 3. 证据分级
|
||
|
||
从低到高仅表示证据类型，不允许自动跨级：
|
||
|
||
1. 静态结构检查：frontmatter、路径、禁用污染模式；
|
||
2. 确定性离线测试：纯函数、schema、状态机和失败分支；
|
||
3. 真实依赖集成测试：PostgreSQL、文件系统或外部服务；
|
||
4. Skill 行为评测：外部 Agent/模型运行与结构化裁决；
|
||
5. 人工内容评审：文学质量、声音和语义效果。
|
||
|
||
任一层通过都不能代替更高层证据。没有行为评测，不得声称 Skill 内容有效；没有真实依赖证据，不得声称生产链路可用。
|
||
|
||
## 4. 改动门禁
|
||
|
||
### 只改运行时合同
|
||
|
||
- 通过 harness 的运行时文档污染扫描；
|
||
- 更新受影响的行为评测案例，或记录只改措辞、不改变行为的理由；
|
||
- 不新增把测试细节塞回 `SKILL.md` 的说明。
|
||
|
||
### 只改确定性工具
|
||
|
||
- 更新针对变更不变量的离线测试；
|
||
- 对真实数据库、网络和模型测试单独标记；
|
||
- 保留失败关闭和副作用边界证据。
|
||
|
||
### 改变 Skill 意图或边界
|
||
|
||
- 更新行为评测清单和正/负向案例；
|
||
- 检查消费者、Agent 槽位和 `meta/chains` 映射；
|
||
- 重新执行相关层级的验证，不得只跑 Python 单测。
|
||
|
||
## 5. 明确禁止
|
||
|
||
- 用 `assertIn` 检查几个词出现，就宣称 Skill 内容正确；
|
||
- 用测试文件或测试输出作为运行时事实源；
|
||
- 用 `except Exception: pass` 把错误依赖、连接失败或实现错误当成预期拒绝；
|
||
- 用任意总入口的“零测试”结果当成通过；
|
||
- 把离线 fake、模型探针或小样本合同回放写成真实质量结论；
|
||
- 为了让 harness 变绿而修改业务合同、降低断言或静默跳过测试。
|
||
|
||
## 6. 完成定义
|
||
|
||
本治理任务只有同时满足以下条件，才可称为完成：
|
||
|
||
- 运行时 `SKILL.md` 不再携带开发测试说明；
|
||
- harness 能机械发现并阻断明显的测试污染；
|
||
- 实现测试、集成测试和 Skill 行为评测的证据类型可区分；
|
||
- 改动范围内的回归测试真实执行，失败不会被吞掉；
|
||
- 报告明确区分已验证事实、推断和未验证的模型质量假设。
|