091b66a9bb
将角色与 Skill 从 .claude 迁入 .agent，移除 Claude CLI 运行时并接入固定 Opus 角色 profile、完整 schema、预算 deadline、raw 与回执证据链。 同步拆分 Skill 职责、复利 lesson、Gate 回放、Dashboard 人审入口、数据库登记和机械门禁；候选设计正文不包含在本提交中。
116 lines
5.2 KiB
Markdown
116 lines
5.2 KiB
Markdown
# Skill 测试与评测规范
|
||
|
||
> 状态：生效规范
|
||
> 适用范围：`agent-example/.agent/skills/*/SKILL.md`、其确定性工具和 Skill 行为评测。
|
||
> Owner：`agent-example/harness/`
|
||
> 本文件是开发与评测支架规范，不属于任何 Skill 的运行时提示词。
|
||
|
||
## 1. 三层边界
|
||
|
||
### 1.1 Skill 运行时指令
|
||
|
||
`SKILL.md` 只描述 Agent 执行该 Skill 时必须知道的稳定合同，以及实际执行所需的业务工具与流程。**必备内容的清单按 Skill 分类裁剪，Owner 是 [`skill-quality-rubric.md`](skill-quality-rubric.md) 的维度 D4**；本节只规定禁止内容。
|
||
|
||
`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 行为评测的证据类型可区分；
|
||
- 改动范围内的回归测试真实执行，失败不会被吞掉；
|
||
- 报告明确区分已验证事实、推断和未验证的模型质量假设。
|