real-evidence
对抗式真机证据审查方法:把一条检查写成可证伪声称,用独立观测取原始证据,按四类判定与四分型下结论,留证据六元组,再用反例维度与 test-the-test 反审。用于设计/修改真机检查、审查真机测试报告、判断一条 PASS 有没有证据力、给失败分型。
- License 许可
- MIT
- 最近更新
- 2026-11-09
- Stars
- ★ 159
- Forks
- 2
01 前言 Front Matter
- name
- real-evidence
- whenToUse
- 设计或修改真机检查、审查真机报告、判断 PASS 是否可信、给失败分型时。
- description
- 对抗式真机证据审查方法:把一条检查写成可证伪声称,用独立观测取原始证据,按四类判定与四分型下结论,留证据六元组,再用反例维度与 test-the-test 反审。用于设计/修改真机检查、审查真机测试报告、判断一条 PASS 有没有证据力、给失败分型。
- user-invocable
- true
03 SKILL.md 正文
real-evidence:真机证据审查方法
这个 skill 只装方法:如何立论、如何找反例、如何观测、如何判定、如何留证据、如何反审。
具体怎么起环境、怎么读钩子、报告字段怎么定义,由仓内实现层文档回答(见文末「实现层参考」)。
机器绑定(路径、端口、浏览器、凭据)不写进方法与文档,边界见 docs/real/boundary-policy.md。
何时用 / 不用
用:
- 你要新增或修改一条真机检查;
- 你要审查一份真机报告,判断 PASS / FAIL / BLOCKED 是否成立;
- 你怀疑某条断言「一直绿,但其实测不到东西」;
- 你要给一条失败定分型(product / spec / test / tool)。
不用:
- 只想跑一次套件看结论:直接按 onboarding 跑,不必先读方法;
- 要改 harness 实现:走仓内实现层流程,本 skill 不给代码级步骤。
四个心智模型
1. 声称—条件—判据
一条检查必须能被写成一句可证伪的声称,且三者分开:
- 声称(claim):要么成立、要么不成立的事实句。反例:「功能正常」不是声称;「物理点击模板行后草稿逐字等于模板正文」是。
- 条件(conditions):这次判定的边界——产物版本/哈希、宿主版本、浏览器运行时、fixture 名、runTag。离开条件,判定不能复用。
- 判据(criteria):可观测的「期望 vs 实测」,并且观测来源明确。判据不能依赖被测代码自述。
写完先自问:如果它坏了,哪一个观测会变? 答不出来,说明它还不是检查。
2. 观测独立性
同一条事实尽量取两路独立观测(双通道),并优先更接近用户的来源:
- 用户可见行为(界面文本、可见状态、真实输入的事件序列);
- 公开接口(宿主/插件暴露的公开 API 返回值);
- 持久化副作用(store 读回);
- 页面内部快照(观测探针);
- 被测代码自述(自己打点自己报)——最低,不单独作证。
双通道不是各测一半:两路都要指向同一事实,且允许失败。两路都过还不能证明有区分力,需要第 3 点。
3. 判定分类
| 判定 | 含义 | 常见错用 |
|---|---|---|
| PASS | 判据成立,且观测路径可失败 | 把「没测到」当 PASS |
| FAIL | 判据不成立,属产品/规格/测试/工具之一 | 把环境没就绪记成 FAIL |
| BLOCKED | 前置条件不成立,检查没执行或没法执行 | 用它掩盖真实的判据不成立 |
| N-A | 按规格确实不适用,必须写理由 | 静默跳过 |
FAIL 再分四型:
product产品缺陷:期望明确、观测到的不符合;spec规格缺陷:期望本身可疑或规格没写清,无法据此判产品对错;test测试假象:不可复现/环境抖动导致的红,重跑可能绿,须记 flakySuspect;tool工具故障:测试工具链自身坏了,不得冒充产品失败。
BLOCKED 也要分:environment(环境没就绪,非缺陷)与 tool(控制通道故障)。
预期失败(negative control)必须显式标注;声明「应该红」的用例没红,要单独记一条「无区分力」失败。
4. 证据六元组
每条关键检查都给六元组,缺一不可:
| 字段 | 写什么 | 写砸的样子 |
|---|---|---|
claim |
可证伪的事实句 | 「功能正常」 |
conditions |
产物/宿主/浏览器/fixture/runTag | 只写「本地」 |
steps |
可重放的布置序列 | 「点击一下」 |
observations |
原始观测:期望 vs 实测 | 只写结论 |
inference |
从观测到判定的推理,含替代解释 | 直接复述 claims |
verdict |
四类之一 + 分型依据 | 只写 FAIL |
审查协议(六阶段)
按顺序做;每阶段有完成判据,不满足就别进下一阶段。
阶段 0:收材料
拿到:被测产物标识(名/版本/哈希)、宿主与浏览器运行时、fixture 名、证据路径(报告 JSON)。 缺材料先补,别用推测填。
完成判据:六元组的「条件」字段已经能写出来。
阶段 1:立论
把要验证的行为写成 claims(一条检查一句),写出对应判据与观测来源。
若规格不清:不猜,直接归入 spec 疑点,找规格 owner。
完成判据:每条 claim 都有「坏了会变」的观测;规格不清的已单列。
阶段 2:找反例
用下面的反例维度逐条扫一遍,列出「这条检查可能假绿/假红」的具体路径,至少写 3 条。
完成判据:反例清单存在,且至少一条已被现有证据排除或确认。
阶段 3:独立观测
按「观测独立性」取一两路证据;原始观测先记录、后解释,不要把解释当观测。 等待与轮询只等可判定条件;超时要留下末次观测,不能只写「超时了」。
完成判据:期望与实测成对出现,来源标注清楚,超时附末次观测。
阶段 4:判定与分型
先给四类判定,再给 FAIL 四分型与依据(source:显式声明还是推断,依据信号是什么)。
工具故障与产品缺陷分开;环境未就绪优先 BLOCKED。
完成判据:判定 + 分型 + 分型依据三者齐全;BLOCKED/N-A 都写了原因。
阶段 5:写六元组
按证据六元组填写,关键检查六项齐全;失败附产物或写明 artifactsWhy。
完成判据:六元组无空缺;另一个人能只凭它重放。
阶段 6:反审(test-the-test)
回答四个问题:
- 假绿:这条检查怎么坏才会红?故意破坏一次(注入/旧产物/负例)能红吗?
- 假红:红了以后,是产品坏还是测试自己坏了?分型依据够吗?
- 区分力:拿旧版本/故障注入对照,它从红变绿(或反之)了吗?两侧都绿=没有证据力。
- 可重放:换一台机器/换人,只按 steps 能复现吗?哪一步依赖了本机绑定?
完成判据:四个问题都有答案;发现本机绑定就改文档或 gate,不把绑定留在检查里。
反例维度清单
- 输入保真:真实指针/键盘 vs 合成事件?合成路径可能绕过产品的真实处理。
- 状态污染:上一场景的草稿/撤销历史/store 是否残留?换场景要不要重载页面?
- 时序竞态:UI 先更新、落点后归位?只等文本没等光标?
- 环境漂移:宿主版本、浏览器、locale、时区、慢机器超时。
- 版本差异:拿旧产物/旧宿主跑,同一断言还成立吗?差异是产品行为还是观测语义?
- 观测偏差:被测代码自述当证据?钩子缺失导致读取 null 被当成「没发生」?
- 路径覆盖:只测了指针没测键盘?只测键盘没测指针?只测正常流没测降级?
- 假绿:两侧都绿(bothGreen)时,永远不要判「通过」或「有证据」。
与实现同步的契约常量
下面三个常量必须与仓内实现层保持一致;方法层文档改不动实现,改到不一致时门禁会红。
<!-- method-contract:start --> VERDICTS: PASS | FAIL | BLOCKED | N-A FAILURE_TYPE_IDS: product | spec | test | tool EVIDENCE_TUPLE_FIELDS: claim | conditions | steps | observations | inference | verdict <!-- method-contract:end -->
机器绑定边界
方法层文档与 skill 只出现占位符与运行期参数:<artifact-tgz>、<evidence-root>、<pack-dir>、
<host>:<port>、$DSH_HOME、~/.dsh、仓内相对路径。出现盘符路径、用户主目录、固定端口、
浏览器安装路径、固定 locale、IPv4 字面量等即视为绑定进文档,按 docs/real/boundary-policy.md 判定为违规。
安装与分发
本 skill 在仓内 skills/real-evidence/ 维护,单一事实源;分发到用户级 skill 根:
- 把仓内
skills/real-evidence/整个目录复制到用户级 skill 根下的同名目录; - 用户级 skill 根是约定位置:
$DSH_HOME/skills(未设置DSH_HOME时用~/.dsh/skills); - 目录形态为
<skill-root>/real-evidence/SKILL.md,只扫一层; - 目录刷新由宿主 watcher 处理,新增/改名/改 frontmatter 不需要重启;
- 安装是运行期动作:不把安装命令/安装结果写进仓库文件。
实现层参考(相对仓内路径)
- 跑起来:
docs/real/onboarding.md - 判定与证据协议:
docs/real/report.md - 机器绑定政策:
docs/real/boundary-policy.md - 分层与分发决策:
docs/adr/0011-real-test-kit-layering.md - 观测层与钩子:
docs/real/observability.md、docs/real/hooks.md - 宿主契约:
docs/real/host-contract.md - fixture 语义:
docs/real/fixture.md - 区分力(差分/故障注入):
docs/real/diff.md - kit 全貌:
scripts/real/README.md