AGENT SKILL

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. 观测独立性

同一条事实尽量取两路独立观测(双通道),并优先更接近用户的来源:

  1. 用户可见行为(界面文本、可见状态、真实输入的事件序列);
  2. 公开接口(宿主/插件暴露的公开 API 返回值);
  3. 持久化副作用(store 读回);
  4. 页面内部快照(观测探针);
  5. 被测代码自述(自己打点自己报)——最低,不单独作证。

双通道不是各测一半:两路都要指向同一事实,且允许失败。两路都过还不能证明有区分力,需要第 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)

回答四个问题:

  1. 假绿:这条检查怎么坏才会红?故意破坏一次(注入/旧产物/负例)能红吗?
  2. 假红:红了以后,是产品坏还是测试自己坏了?分型依据够吗?
  3. 区分力:拿旧版本/故障注入对照,它从红变绿(或反之)了吗?两侧都绿=没有证据力。
  4. 可重放:换一台机器/换人,只按 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 根:

  1. 把仓内 skills/real-evidence/ 整个目录复制到用户级 skill 根下的同名目录;
  2. 用户级 skill 根是约定位置:$DSH_HOME/skills(未设置 DSH_HOME 时用 ~/.dsh/skills);
  3. 目录形态为 <skill-root>/real-evidence/SKILL.md,只扫一层;
  4. 目录刷新由宿主 watcher 处理,新增/改名/改 frontmatter 不需要重启;
  5. 安装是运行期动作:不把安装命令/安装结果写进仓库文件。

实现层参考(相对仓内路径)

  • 跑起来: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

04 同仓库更多 Skills