Agent Harness Testing — 通用项目测试方法论
你在别人的项目中工作。你不知道他们的测试框架、不知道他们的构建系统、不知道他们的 CI。但你必须验证你的改动是正确且安全的——不能跳过测试、不能编造结果、不能假设一切正常。
总则（先复现再修复、先红灯再绿灯、结果必须来自真实执行、探针必须清理）已由运行时强制： 证据义务状态机跟踪 RED→GREEN、编辑门拦截无复现的源码修改、探针追踪扫描残留、 交付门禁核验验证证据。本 Skill 是操作手册——怎么探测测试能力、怎么构造红灯、 怎么模拟环境，不再复述总则。
Stage 1: 探测测试能力
进入陌生项目的第一件事——不是改代码，是了解怎么验证。
1.1 运行 inspect_project
这会返回项目摘要：语言、包管理器、scripts、入口文件、测试框架提示。先用它建立全局认知。
1.2 读项目配置文件
根据语言读对应配置：
| 语言 | 读什么 | 找什么 |
|---|---|---|
| Node/TS | package.json | scripts.test, scripts.typecheck, scripts.lint, devDependencies 中的 vitest/jest/mocha |
| Python | pyproject.toml / setup.cfg | [tool.pytest], [tool.mypy], [tool.ruff] |
| Go | go.mod + 项目根 *_test.go | 测试文件存在即表示 go test ./... 可用 |
| Rust | Cargo.toml | [dev-dependencies] 中的 test 相关 crate |
1.3 列出测试文件
bash# Node ls **/*.test.ts **/*.spec.ts **/__tests__/*.ts 2>/dev/null # Python ls **/test_*.py **/*_test.py 2>/dev/null # Go ls **/*_test.go 2>/dev/null # Rust ls tests/ 2>/dev/null
1.4 试跑一条测试命令
bash# Node 常见 npx vitest --run 2>&1 | head -5 npx jest --passWithNoTests 2>&1 | head -5 # Python python -m pytest --co 2>&1 | head -5 # Go go test ./... 2>&1 | head -5 # Rust cargo test 2>&1 | head -5
如果试跑失败，看错误信息——可能缺依赖（npm install）、环境变量（.env）、或服务（Docker）。
不要跳过——记录障碍并告知用户，问是否需要帮助配置。
1.5 生成能力地图
探测完成后，心里形成一张表：
typecheck: 可用 (npx tsc --noEmit) / 不可用 lint: 可用 (npx eslint) / 不可用 unit test: 可用 (npx vitest --run) / 不可用 e2e: 可用 (npx playwright test) / 不可用 build: 可用 (npm run build) / 不可用 env sim: 可用 (docker compose up) / 不可用
Stage 2: 按任务类型选择测试策略
Bugfix
必须: RED 红灯测试 → 修复 → GREEN 绿灯测试 → 回归测试 如果无法写红灯测试: 说明原因 + 给替代验证方式
红灯测试构造方法：
- 从用户描述和错误日志提取失败场景
- 找现有测试文件，复制结构
- 写最简失败用例（最小数据、最少依赖）
- 运行 → 必须失败
- 确认失败断言与 Bug 描述一致
- 开始修复
如果无法构造（问题仅在生产环境/第三方回调/并发竞态复现）：
- 明确说明：为什么本地无法复现
- 给出替代验证方式：staging 环境回放、日志对比、代码审查要点
- 不跳过验证——只是换一种验证方式
Feature
必须: 新功能测试（覆盖 happy path + 边界）→ typecheck → lint 推荐: 集成测试（如果涉及多模块）
Refactor
必须: 相关回归测试 + typecheck 如果是缓存/不变量/前缀结构: 全量模块测试
Performance
必须: benchmark 对比（改动前后） 推荐: 压力测试、profile 数据
Security
必须: 安全测试（越权、过期令牌、注入） 推荐: staging smoke test
Stage 3: 探针管理
探针是临时诊断工具，不是永久代码。
三类探针
| 类型 | 写法 | 生命周期 | 示例 |
|---|---|---|---|
| 临时日志 | console.log("[probe:name]", data) | 修复后必须删除 | console.log("[probe:filter]", candidates) |
| 结构化日志 | logger.info({ event: "name", ... }) | 可保留（用于线上诊断） | logger.info({ event: "draw.select", id, stock }) |
| 断言探针 | assert(cond, "msg") | 修复确认后转为测试断言或删除 | assert(stock >= 0, "stock must not be negative") |
探针纪律
- 插入前：在注释或 commit message 中标记位置和目的
- 使用中：保持探针干净——只输出必要字段，不打印整个对象
- 清理时：必须逐条检查
console.log/debugger/ 临时assert是否残留 - 任务完成标记前，确认无临时探针残留。有残留 = 任务未完成。
Stage 4: 环境模拟
优先使用真实依赖而不是全 mock。
检查项目是否有 Docker 环境
bashls docker-compose.yml docker-compose.yaml Dockerfile Makefile 2>/dev/null
如果有 docker-compose.yml：
bash# 启动依赖 docker compose up -d db redis # 跑集成测试 npm run test:integration # 关闭 docker compose down
如果只有 Makefile
bash# 找 service/test 相关目标 grep -E '^(test|db|redis|service|up|down):' Makefile
如果什么都没有
- 用 SQLite 文件做数据库测试（临时文件，测试完删除）
- 用
node --experimental-test-runner做最轻量测试 - 说明：当前项目没有类生产环境，集成测试标记为"mock 验证"
注意 .env 和密钥
- 不在对话中输出
.env内容 - 如果需要环境变量，让用户补充
- 不在测试代码中硬编码密钥
Stage 5: 验证报告
任务完成时必须输出结构化验证报告，而非"已完成"。
最小报告模板
## 验证报告 ### 改动 - 文件1: 改了什么 - 文件2: 改了什么 ### 测试结果 - [PASS] 目标测试 (command) - [PASS] typecheck (command) - [SKIP] e2e (原因: 项目未配置) ### 未验证项 - 项目无 e2e 配置，手动验收路径: ... ### 风险 - 并发场景下的行为未验证
诚实报告（未跑=未验证、0 passed ≠ 通过、失败附错误信息）与反模式清单由 运行时诚实门禁 + 交付契约强制，不在此复述。
快速检查清单
任务完成前自问：
□ 我读了相关代码和测试吗？ □ Bugfix: 我构造了红灯测试（或说明了无法复现的原因）吗？ □ 我实际运行了测试并看了输出吗？ □ 测试结果能支撑"已验证"的结论吗？ □ typecheck/lint/build 通过了吗？ □ 临时探针清理了吗？ □ 我是否修改了无关文件？ □ 如果是高风险改动，我做了额外验证吗？ □ 我的验证报告是否诚实（不夸大、不推测）？
这 9 个问题全部能答"是"，任务才算完成。
