testing

测试 Skill — 校验 + 每日健康与回归分析

约定： 参见 conventions/quality.md 了解“先测试再批量处理”的模式；本 Skill 会在项目自身的测试套件中强制执行该模式。

两种模式

本 Skill 有两个相关但不同的模式：

1. Skill 一致性校验——gbrain 自身的一致性标准（原始 1.0 范围）。校验每个 Skill 都有带 frontmatter 的 SKILL.md，每个引用都存在，manifest 与 resolver 覆盖情况可双向对齐。

2. 项目测试套件健康度（v0.25.1 扩展）——运行项目的分层测试套件，并生成带回归分类的报告。用于每日定时任务、容器重启引导，以及“测试情况如何”之类的提问。

根据触发方式选择模式。

模式 1：Skill 一致性校验

约定

此模式保证：

• 每个 Skill 目录都有一个 SKILL.md 文件
• 每个 SKILL.md 都有有效的 YAML frontmatter（name、description）
• 每个 SKILL.md 都包含 test/skills-conformance.test.ts 要求的必需章节
• skills/manifest.json 列出每个 Skill 目录
• skills/RESOLVER.md 引用 manifest 中的每个 Skill
• openclaw.plugin.json 的 skills[] 与以上两者双向对齐
• openclaw.plugin.json 保留 OpenClaw 安装所需的原生插件字段（id、对象形式的 configSchema，以及适用时的 contracts.contextEngines）
• 不存在 MECE 违规（Skill 之间没有重复触发条件）

阶段

1. 遍历 skills 目录。 列出所有包含 SKILL.md 的子目录。
2. 校验 frontmatter。 解析 YAML，检查必需字段。
3. 校验章节。 检查必需的标题。
4. 检查 manifest。 每个 Skill 目录都必须在 manifest.json 中。
5. 检查 resolver。 manifest 中的每个 Skill 都必须有一行 RESOLVER 记录。
6. 检查双向对齐。 RESOLVER 的触发条件 ↔ frontmatter 中的触发条件。
7. 报告结果。

自动化

bun test test/skills-conformance.test.ts test/resolver.test.ts test/openclaw-plugin-manifest.test.ts

CI 门禁检查即 package.json 中的 test 脚本。

输出格式

Skill Validation Report
========================
Skills found:        N
Conformance:         N/N pass
Manifest coverage:   N/N
Resolver coverage:   N/N
Round-trip:          N/N
MECE violations:     N

Issues:
- <skill>: <issue>

模式 2：项目测试套件健康度（v0.25.1）

使用场景

• 每日测试定时任务触发时
• 用户询问“运行测试” / “测试情况如何” / “哪里坏了”时
• 重大代码变更之后（通常通过 cross-modal-review）
• 容器重启之后（引导阶段）
• 感觉有问题、想验证系统健康状况时

测试层级

层级	运行内容	实际耗时	门禁
单元	bun test（确定性，零外部调用）	<2s	每次提交
评测	LLM 评判或质量评测	~60s	每日
集成	针对真实 Postgres 的端到端测试	~5m	发布前 + 每晚
系统健康	磁盘 / 内存 / CPU / 服务存活状态	<10s	每日

每日运行流程

定时任务触发时（或用户提出请求时），需完成以下全部步骤：

1. 运行单元测试

bun test 2>&1

解析：通过总数、失败总数、跳过总数，以及文件级别的结果。

2. 运行评测（如果项目有评测配置）

# Adapt to the project's eval config
bun test --filter eval 2>&1

解析：格式相同。注意记录不稳定测试（即因 API 超时而非代码缺陷导致失败的测试）。

3. 运行系统健康检查

• 磁盘 / 内存 / CPU
• gbrain：gbrain doctor --fast --json
• 数据库连接（如适用）
• 关键文件是否存在（CLAUDE.md、AGENTS.md 等）

4. Git 差异分析（关键——回归分析）

# What changed since last test run?
git log --oneline --since="24 hours ago"

对于每个失败的测试：

1. 检查测试本身是否最近被修改过（测试变更，而非回归）。
2. 检查它所测试的代码是否最近被修改过（可能的回归）。
3. 检查是否为已知的不稳定测试（API 超时、服务宕机）。
4. 检查依赖是否已更新（gbrain、bun 等）。

5. 对每个失败进行分类

分类	标记	处理方式
REGRESSION（回归）：代码已改动，测试随之失败	🔴	标记导致失败的提交
STALE（过时）：测试期望旧行为，代码本身正确	🟡	修复测试，而不是代码
FLAKE（不稳定）：API 超时、服务宕机、LLM 结果波动	⚠️	记录即可，不必警觉；重试一次
NEW（新增）：测试刚添加，尚未通过	🟢	确认是否为有意为之
INFRA（基础设施）：容器重启导致状态丢失	🛠	运行 bootstrap，然后重新测试

6. 报告格式

🧪 Daily Tests — YYYY-MM-DD

Unit:   X/Y passed (Z skipped)
Evals:  X/Y passed
System: [health summary]

REGRESSIONS:
  🔴 <test-name>: broke by commit <sha> "<commit message>"

STALE TESTS:
  🟡 <test-name>: expects X but code now does Y (commit <sha>)

FLAKES:
  ⚠️ <test-name>: timeout (retry passed)

✅ ALL CLEAR  (when applicable)

7. 自动修复规程

可以自动修复：

• 文件重命名后，测试仍期望旧的文件路径 → 更新测试
• 测试仍期望旧的版本字符串 → 更新
• 测试期望的文件已被有意删除 → 删除该测试
• 文件移动后导致导入路径失效 → 修复导入

不得自动修复：

• 测试期望行为 A，但代码现在执行 B → 先询问。可能是测试正确而代码存在缺陷。
• 安全测试失败 → 始终上报，绝不自动修复。
• 测试因 TODO 被跳过 → 未弄清原因前，不得取消跳过。

不确定时：查看修改代码的提交信息，检查是否存在相关 PR 或讨论，仍不清楚则询问用户。

状态（回归历史）

将结果记录到 ~/.gbrain/test-state.json 中，用于趋势追踪：

{
  "lastRun": "2026-04-16T13:37:00Z",
  "unit": { "passed": 1262, "failed": 31, "skipped": 8 },
  "evals": { "passed": 17, "failed": 0 },
  "system": { "doctor": "ok", "gbrain": "0.25.1" },
  "failureHistory": [
    { "test": "<name>", "since": "2026-04-14", "classification": "stale" }
  ]
}

这将支持以下功能：

• 趋势追踪（质量是在变好还是变差？）
• 不稳定测试检测（同一测试间歇性失败）
• 回归速度（每次改动后，我们多快会引入回归？）

失败时

对于任何 gbrain 错误 code、退出码、[AGENT] 块或提示块，请遵循 Agent 操作员规程。本技能特有的规则如下：

• 测试因缺少 API 密钥或提供方不稳定而失败：应归类为环境故障而非代码故障，并说明缺失的是哪个密钥。
• 安全测试失败：始终上报给用户，绝不自动修复。
• gbrain doctor 无法连接知识库（GBRAIN_DB_ACCESS）：在运行集成测试之前，先转至 db-repair 技能处理。

反模式

• ❌ 新增技能后跳过一致性验证
• ❌ 将技能添加到 manifest.json 却未同时添加到 RESOLVER.md
• ❌ 把每个红色测试都当作回归。应先分类；许多属于过时或不稳定。
• ❌ 在不了解跳过原因的情况下自动取消跳过测试
• ❌ 自动“修复”安全测试失败
• ❌ 未实际运行系统健康检查就报告“一切正常”

约定

本技能保证：

• 路由与 frontmatter 中的标准触发条件一致。
• 输出写入 writes_to: 中列出的目录（如适用）。
• 遵循所引用的约定（quality.md、brain-first.md、_brain-filing-rules.md）。
• 保持隐私约定：不包含真实姓名，不包含特定 fork 的文件系统路径字面量，不引用上游 fork。

完整的行为约定记录在上文各正文章节中；本节仅用于一致性测试。

输出格式

本技能的输出结构已在上文正文章节中说明（见“输出”“知识库页面格式”或同类章节）。此处的章节标题仅用于一致性测试（test/skills-conformance.test.ts）。