测试在玩AI

给 DSH 装一个 Claude Code 模式：一个 preset 插件的痛点、做法与实测

Sat, 10 Oct 2026 00:00:00 GMT

DSH（DeepSeek Harness，npm 上的 @deepseek-ai/dsh）的预设体系里，有一段配置决定了 Agent「怎么干活」——persona 的 prefix。官方 standard 预设的这一段是这个：

prefix: You are a coding agent powered by the {{model}} model.
suffix: Your working directory is {{cwd}}.

一句话。官方 minimal 预设则是另一种极端：complete: true，prefix 固定为 You are a helpful software engineer assistant.，includeRuntimeContext: false——按官方文档说法，这个 agent 身上「其他 prompt section 和面向模型的插件全部缺席」。

两种我都不想要。我想要的是任务纪律被明文写下来：别自述、先读后改、改完自己跑测试、别整文件重写。于是写了这个插件：

仓库：https://github.com/ABK3528/dsh-preset-claude-code（MIT，v1.0.1）
形态：DSH bundle 插件。不 fork 官方、不改官方预设，只是以一个新 bundle 层的身份，往组合树里插一行自己的 preset
效果：新建会话的预设列表里多一个「Claude Code 模式」，order: 0，排在官方 standard(1) / ptc(2) / minimal(3) / cordis(4) 之前
实测（同一模型、同一道题、只换 persona 那一段）：输出 token 1483 → 851，工具调用 10 → 8，墙钟 10s → 7s，正确性不变

一句话概括这件事：DSH 的「风格」不是模型参数，是预设里的一段提示词——所以想换风格不用换模型，装一个 preset 插件就行。

一、我在 DSH 上遇到的四个痛点

1.1 引擎很强，但「怎么干活」没人管

DSH 把一件事分得很清楚：模型、工具、上下文、权限都是组件，而一个 Agent 的行为风格几乎全压在 persona 这一段上。官方四个预设里，standard 的人设就是上面那一句话，其余靠模型本能。

于是同一道题，在默认人设下会变成这样：它先解释一遍自己准备做什么，再动手，最后交一份 1220 字节的汇报；而我要的其实只是「改完，跑通，告诉我改了什么」。（这个数字不是印象，是下面第四节的实测结果。）

这不是模型能力问题，是提示词里没有约束。Claude Code 的提示词里，「不要叙述你即将做什么」「动手前先读文件」「改完主动验证」是明文条款；在 DSH 默认预设里，这些条款不存在。

1.2 想改风格，三条路都不顺手

做法	为什么不顺手
fork 官方 bundle	改动面太大，官方一升级就要重放，等于自己维护一个分叉
直接改 `~/.dsh` 里的预设行	能生效，但没法分发、没法版本化，换台机器重来一遍
把 `persona` 行挂在 preset 外面	直接失败：官方文档说得很明确，`dsh-persona` 行是 scope-only 的，挂在 agent scope 之外会「与 prompt registry 自己的 `deployment:persona-prefix` 注册相撞并 fail loud」

第三条是我最初的做法，启动即报错。它反过来解释了这个插件的形态：persona 必须装进一个 preset 里，而不是挂在外面——因为一个进程里的「全局人设」已经有主了，这个行的存在意义就是「针对某一个 agent 把它顶掉」。

1.3 我在多个 harness 之间来回切

我平时会在几个 CLI agent 之间切换。提示词纪律不统一，切换成本全落在人身上：这个要提醒它先读代码，那个要提醒它跑测试。把 Claude Code 那套纪律抽成 DSH 的一个预设，本质上是把「我的工作方式」从某个具体工具里解耦出来，变成一份可安装、可版本化的配置。

1.4 最坑的一点：装上了 ≠ 生效了

这个坑值得单独一节，因为它同时也是这次改动里最值钱的发现——见第三节。

二、插件的做法：不 fork，只插一行

2.1 DSH 的组合是分层的

官方 apps/cli/reference/README.md 把启动时的配置组合规则写得很清楚，配置树是这样叠出来的：

原文：the effective tree is composed over an empty root by applying, in order: each bundle patch named in the profile manifest's dsh.profile.bundles list, the profile's own cordis.patch.yml, the home-level $DSH_HOME/cordis.patch.yml … and each --patch overlay in argv order. Later layers win per row; a patch replaces the targeted row's complete config value rather than deep-merging keys, and may insert new rows.

两句话翻译过来：后面的层按行覆盖前面的层，而补丁是「整行替换」，不是深合并。这两点决定了插件的全部写法：

插件以「一个新的 bundle 层」的身份出现 → 官方那四个预设一行都不用动，我的 order: 0 只是排在它们前面；
因为 config 是整行替换 → 写 preset 时必须把 config 写全，别指望和官方默认值合并。这是我踩的第二个坑：第一版写了残缺的 config，--dump-config 一出来默认值全丢了。

2.2 这个插件的实体，是一份 patch 文件

lib/index.js 只有 396 字符，就是宿主生命周期入口：

export default class ClaudeCodePresetPlugin {
  static name = 'dsh-preset-claude-code';
  constructor(ctx, config) { this.ctx = ctx; this.config = config || {}; }
}

真正干活的是 cordis.patch.yml——一份声明式补丁：

# dsh bundle patch: inserts Claude Code agent preset into DSH host composition
- insert:
    - id: preset-claude-code
      name: '@deepseek-ai/dsh-agent-preset'
      config:
        id: claude-code
        name: Claude Code 模式
        order: 0
        plugins:
          - id: persona
            name: '@deepseek-ai/dsh-persona'
            config:
              complete: true
              includeRuntimeContext: true
              suffix: Your working directory is {{cwd}}.
              prefix: >-
                You are Claude Code, Anthropic's official CLI ...
                # Core Operating Principles 1. Direct Action: ...
          # ... 省略：工具行与两个隔离组，见下图

好处是简单、可审计：一个 preset 长什么样，读 YAML 就知道。代价也很直接——test/validate.test.js 只能做静态断言（检查 patch 文本里必须出现 @deepseek-ai/dsh-persona、@deepseek-ai/dsh-tool-bash 等字样），它验证不了「装上去之后真的生效」。1.4 那个坑就是这么漏过去的。下一步我打算把 dsh --dump-config 的输出做成快照测试，让「生效」这件事也有断言。

2.3 preset 里面装了什么

行 / 组	作用	关键配置
`persona`	身份与行为纪律，接管 system prompt	`complete: true`、`includeRuntimeContext: true`
`agent-instructions`	读 `AGENTS.md` / `CLAUDE.md`	`maxBytes: 65536`
工具行	bash / pwsh（按平台二选一）、fs、fs-search、jobs、skill-filesystem、tool-skill、goal、todo、ask-user、web、present	`disabled: !!js process.platform === 'win32'`
`planning` 组	计划模式（动代码前先说方案）	`group: true`、`isolate: { planMode: true }`
`compaction` 组	压缩、`/compact`、工具结果剪枝	`isolate: { compaction: true, toolResultPruner: true }`

三个设计决定，每个都有明确的理由：

① 为什么 complete: true。 官方文档说，开了它之后「prompt registry 会把这段 prefix 恢复成唯一的 section；身份、后缀、工具指引、监听器都不能再追加提示词文本」。等于把「这个 agent 是谁」完全交给这一段，所以它必须自己把该说的说完——我配 includeRuntimeContext: true 把工作目录之类的运行时上下文补回来，否则连这些也会被抑制掉。

② 为什么工具行要一行行显式列。 preset 是完整组合，不是增量。想让它手里有什么牌，就写什么。

③ 为什么用 isolate 组。 planMode 与 compaction 各自隔离成组，避免和宿主重复注册同一批服务。

2.4 提示词里我都写了什么

不是照抄，是按「我在 DSH 上真正想让模型改掉的行为」列的：

直接行动——不要在做之前叙述你即将做什么，直接调工具；纯文本回复（除最终交付）控制在 1–2 句；
先读后改——动手前必须读文件和检索代码，不许猜文件结构、行号、函数签名；
手术刀编辑——优先精确字符串替换，而不是整文件重写；
执行与自愈——改完主动跑测试/静态检查，报错就读栈修因再验证；
另外三条：上下文经济（定向读取，别灌上下文）、原生斜杠工作流（/init、/doctor、/compact、/review）、权限与安全边界（破坏性操作要谨慎，严格留在工作区内）。

三、实测一：装上去，但没生效

装好包、重启客户端、新建会话——预设列表里什么都没有。翻日志找到了这句话：

$ dsh plugin --profile t1 add link:/path/to/dsh-preset-claude-code
dsh: initialized profile t1 at ~/.dsh/profiles/t1
+ dsh-preset-claude-code link:/path/to/dsh-preset-claude-code
dsh: warning: dsh-preset-claude-code declares no dsh.bundle
     — installed as a plain dependency, not a profile layer

包确实装进了 node_modules，但它从来没有进入组合树。证据两条：

# profile manifest 里的 bundle 列表，没有我的包
$ python3 -c "import json;print(json.load(open('~/.dsh/profiles/t1/package.json'))['dsh'])"
{'profile': {'bundles': ['@deepseek-ai/dsh-base']}}

# 组合树里搜不到我的 preset
$ dsh --profile t1 --dump-config | grep -c preset-claude-code
0

原因在官方文档里写着：dsh plugin add 成功之后，DSH 会拿安装结果去对账 dsh.profile.bundles——「每个解析到声明了 "dsh": { "bundle": { "patch": "./cordis.patch.yml" } } 的包的依赖会加入层栈」，没声明的「只作为普通依赖保留，并给一次性警告」。我的 package.json 里当时没有这个字段。

修法四行 JSON：

{
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

再装一遍，证据反转：

$ dsh plugin --profile t2 add link:/path/to/dsh-preset-claude-code-fixed
$ python3 -c "...['dsh']"
{'profile': {'bundles': ['@deepseek-ai/dsh-base', 'dsh-preset-claude-code']}}

$ dsh --profile t2 --dump-config | grep -n "preset-claude-code" | head -3
362:# == dsh-preset-claude-code
363:- id: preset-claude-code
367:    name: Claude Code 模式

（顺带一提：--dump-config 会给每一行标出它来自哪个层——# == dsh-preset-claude-code 就是这一行来自哪个 bundle 的证据。查「我的插件到底进没进树」，这一个命令够了。）

:::warning 教训：插件「装上了」和「生效了」是两件事。 判定标准只有一个——组合树（dump）里有没有你那一行。这个坑不是靠读文档能避免的：README 的安装说明照着 pnpm 的习惯写，pnpm add 返回成功，人自然认为成功了。 :::

四、实测二：换 persona 到底值多少

「回复变短了」这种话不算结论，所以做了一次尽量只动一个变量的对照。

设置（除了 persona，全一样）：

维度	值
引擎	DSH `0.2.0-rc.2`，`--profile headless` 一次性任务
模型	`deepseek-official` / `deepseek-flash`，`reasoningEffort: high`
权限	permission preset `workspace-write`，approval `ask`
任务	仓库里一个带两个 bug 的 `mathx.py` + 一个可执行测试脚本
唯一变量	agent 的 persona 前缀：A 用 DSH 默认 `standard` 那一句；B 用插件的 Claude Code 前缀

两个测量细节值得说一下，因为它们让「感觉」变成了「数」：

测试到底跑没跑：测试脚本每次被执行都往 runs.log 追一行。模型说「测试通过」不算数，文件里的记录才算。
token 与工具调用：从 $DSH_HOME/sessions/**/session.v4.jsonl.zstd（多帧 zstd）解出事件流，统计 assistant/message 的 usage 和 tool/call 的计数，不靠肉眼估。

指标	A · 默认 standard persona	B · Claude Code persona
输出 token	1483	851（-43%）
工具调用总数	10	8
├ `bash`	5	3
├ `read`	3	2
├ `glob`	0	1
└ `edit`	2	2
步骤数	6	6
墙钟	10 s	7 s
最终答复长度	1220 B	399 B
测试执行次数	2（复现 + 验证）	2（复现 + 验证）
结果	两个 bug 都修好	两个 bug 都修好

比 token 数更有意思的是工具路径变了。默认人设下它用 bash 去探路（5 次）；Claude Code 人设下变成先 glob 找结构、再 read 读文件，bash 只用来跑测试（3 次）。这不只是「话少了」，是行为路径变了——从「边试边看」变成「先定位再动手」。

:::note 边界要说清楚：n=1，一道题，一次运行，样本小，只说明方向，不构成基准测试。另外这次实验是把 persona 前缀挂到 deployment 的 system-prompt 行上跑的（headless 一次性任务没有预设注册表，没法选预设），所以它衡量的是提示词那部分的收益，不等于整个 preset 的收益。要更硬的结论，需要多题、多次、多模型地跑。 :::

五、使用感受

先说好的：

最直观的变化是动手变早了：默认人设下它习惯先叙述再执行，现在是直接调工具；complete: true 把身份完全接管之后，这种自述倾向被压得很明显。
改完会自己跑测试，报错自己读栈、自己修、再验一遍——这是我手动提醒次数掉得最多的一项。
plan mode 那条最实用：动代码之前先把方案摆清楚、等 exit_plan_mode。这段「架构师姿态」是写进 plan-mode 的 section 里的，所以它是提示词级的约束，不是靠模型自觉。
工具集是显式列的，所以我很清楚「这个模式下模型手里有什么牌」，而不是跟着宿主走。

再说代价和还没解决的：

>- 折叠标量把编号列表拍平了。 dump 出来我的 prefix 是这么一行：# Core Operating Principles 1. Direct Action: ... 2. Codebase Grounding: ...——八个原则挤成一整段，标题和编号的结构信息丢了大半。这是我下一步第一件要改的事：换成 |（literal block）保留换行。
complete: true 是双刃剑。 干净（宿主不能追加任何提示词文本）的另一面是：提示词得自己写全，漏了就是真没有。
order: 0 只解决排序，不解决默认。 registry 的 default 仍然是 standard；想让它成为默认，还得改 registry 的 default 配置。
bundle 层的变更要重启。 装/删 bundle 之后，正在跑的 profile 不会热更新（官方文档明确写了这个启动边界），只有 cordis.patch.yml 的普通编辑才走热重载。桌面端就是「重启客户端」。
校验只能静态做（见 2.2）。这是目前最真实的缺口：这个插件的「正确性」眼下只由一条 grep 式的断言和我的手工 dump 保证。

一句话总结： 提示词层是当前性价比最高的一档——不动模型、不动工具、不动权限，只换一段 persona，换来的行为差异可以量化。尤其对「整天在不同 agent 之间切」的人来说，把工作方式做成一份可安装的配置，比反复口头提醒可靠得多。

六、想自己写一个 preset 插件？三步

写 cordis.patch.yml：insert 一行 @deepseek-ai/dsh-agent-preset，config 写全（patch 是整行替换，不深合并）；
package.json 里声明 dsh.bundle.patch，然后 dsh plugin --profile <name> add <包名或本地路径>；
验证：dsh --profile <name> --dump-config | grep <你的 preset id>，顺手 --dump-config-schema 看你的行有没有进 schema。

如果只是自己用、不打算分发，还有更轻的一条路：dsh --profile web --patch ./cordis.patch.yml——把它当覆盖层用，什么都不用安装。

参考

插件仓库：https://github.com/ABK3528/dsh-preset-claude-code
dsh CLI 行为参考（profile 启动、插件管理、配置 dump 的分层与覆盖规则）：https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/reference/README.md
包文档：@deepseek-ai/dsh-persona（complete / includeRuntimeContext / scope-only 的原因）、@deepseek-ai/dsh-agent-preset-registry（预设注册表与 roster）

不写一行用例的线上巡检：一个自主爬站引擎的痛点、做法与两组实测

Sat, 10 Oct 2026 00:00:00 GMT

线上故障最常见的形态，其实不是「服务挂了」。挂了反而简单——HTTP 503、探针变红、告警响，谁都知道出事了。

难的是另一种：**页面还在，按钮还能点，功能悄悄没了。**一个接口返回 500，前端 catch 住，右下角弹一句「系统开小差，请稍后重试」，页面本身 HTTP 200，探活绿油油。用户来投诉的时候，你的监控面板上什么都看不出来。

我在公司是唯一一个 QA（对，整个测试团队只有一个人），平时测的是 AI 网关这类后台系统。这类页面按钮多、状态多、改造频繁，两种常规手段都不太趁手：

手段	真实体验
`curl /health` 探活	用户能点的东西它一个都没碰过。SPA 里接口 500 而页面 200 的场景，它 100% 看不见
手写 Playwright / Cypress 用例	写得出来，维护不起。表格里一个 `<button>` 被重构成 `<div role="button">`，几十条用例一起红；加一个新字段，我得改三处选择器

我想要的东西很具体：给一个根 URL，它自己逛、自己判断有没有坏、自己出报告。我不要写选择器，也不要维护用例。

于是做了 jev-inspector：Apache-2.0，纯 Python，仓库里约 4,500 行代码（核心包 jev_inspector/ 2,636 行，其中爬取引擎 crawler.py 950 行），唯一依赖是 playwright>=1.40.0，其余全部走标准库。

一、先说清楚：为什么「随便写个爬虫点链接」不行

我一开始也是这么想的，直到发现这类任务有三个死局，任何一个都能让脚本在几分钟内自己把自己弄死。

死局一：无限下钻。 一个订单列表页有 30 行，每行 2 个按钮；一个商品站有 100 万个详情页。普通爬虫会一直走下去，内存和算力都耗在同一种模板页面上，而真正关键的结算页、设置页一个都没碰到。

死局二：状态污染与回溯失败。 点一个「提交」会永久改变状态；点一个「在新标签页打开」会跳到另一个上下文；点开一个带遮罩的弹窗之后，页面上其它元素全被挡住——Playwright 会一直等「元素可点击」，等到超时为止。页面回不去，整轮巡检就卡在那儿了。

死局三：标签页泄漏。 只要站里有 target="_blank" 或 window.open，无头浏览器的标签页会不断堆积，内存几分钟内就上去，最后把宿主机拖死。

这三条决定了它不是「爬虫 + 循环点击」，而是一套浏览器状态调度问题。

二、它的做法：四张网

2.1 四层递进去重（对付下钻）

层	做什么	我的理解
L1 URL 规范化	去掉锚点、剔除 `utm_*` 与时间戳、重排 query	同一个页面别被算成十个
L2 路径原型配额	把 `/items/10001`、`/items/10002` 抽象成 `/items/:id`，每种模板只采样 N 页	从根上斩断无限下钻，这是整套里最关键的一层
L3 DOM 结构指纹	向上回溯容器，给 `tr`、`li.card` 这类同构元素算指纹，同一种只测第一个	30 行表格不会点 60 次
L4 模型语义去重	剩下真需要判断的交给判定层	兜底，我这次没配 key，走的是关键词路径

2.2 三级弹性回溯（对付状态污染）

回溯的三级是从源码里读出来的，_apply_elastic_backtrack 这个方法写得很清楚：

L1 原位软回溯：按一次 Escape，然后找 .toast、.modal-backdrop、button.close、[aria-label="Close"] 逐个点掉/隐藏。注意这一级是静默的——它不写 INFO 日志，只在异常时 debug 一句。也就是说「弹窗被自动关掉了」这件事在日志里没有痕迹，想确认得看截图或自己加日志。
L2 历史回溯：一旦发现 URL 漂移，page.go_back(wait_until="domcontentloaded", timeout=4000)。
L3 硬重置：go_back 之后还在错页上，就 goto 回基准 URL，重新拿一个干净上下文。

2.3 多标签页守护

在 BrowserContext 级别挂 context.on("page")：所有被 target="_blank" 或 window.open 打开的新页面都会被抓到，先在它上面做一轮 console / 4xx 检查（子页面的错误也算证据），然后立刻 .close()。主巡检页面的焦点和浏览器内存因此保持恒定。

2.4 判定层：证据链是四路，不是一路

这一点是我最看重的设计。判断「这一页坏没坏」，它同时收四种证据：

提示类 DOM 元素的文本（.toast / .alert / [role=alert] / [class*=error] …，且要求元素真的可见）；
这一轮动作之后新增的 console 日志里带 error / fail / 500 / 失败 这类关键词的行；
网络层实时拦到的所有 4xx / 5xx 响应（静态资源除外）；
alert / confirm 这类浏览器弹窗的文本。

四路汇总之后再判定，命中就写一条错误记录并自动截一张现场图：

error_record = {
    "action": "button['刷新数据'] (xpath: //*[@id=\"refresh-btn\"])",
    "detected_texts": [
        "Console: [error] Failed to load resource: the server responded with a status of 500",
        "Console: [error] 请求失败: HTTP 500",
        "HTTP 500 Internal Server Error on http://127.0.0.1:8765/api/flaky",
    ],
    "error_type": "request_error",
    "jev_confidence": 0.85,
    "severity_score": 0.75,
    "screenshot": "screenshots/error_1791624769615.png",
}

三、实测一：我造了一个假站点，让它自己去逛

光看代码不算数。为了有个可控的靶子，我用标准库写了一个假站（http.server，一共 100 多行），刻意埋了几个典型坑：

5 个页面：首页、订单列表（30 行 × 2 个按钮）、个人资料（表单 + 下拉 + 复选）、管理后台（tab 组件）、归档（12 条同构卡片）；
1 个接口稳定返回 500，前端 catch 后弹 toast「系统开小差，请稍后重试」，页面本身 200；
1 个接口要 4 秒才返回；
首页一个「打开审批弹窗」按钮（遮罩型弹窗）、一个「在新标签页打开」按钮（window.open）、一条指向 example.com 的外链；
后台两个危险按钮：「清空全部缓存」（命中默认词表里的「清空全部」）和「退出登录」。

服务端还记了一份 requests.log——工具说自己访问了什么不算数，服务器收到什么才算数，这是我做测试的习惯。

python3 main.py --url http://127.0.0.1:8765/ --crawl-mode site \
  --max-pages 8 --max-depth 2 \
  --report report.json --html-report report.html --no-fail-on-error

一轮 43.99 秒跑完，结果如下（全部取自 report.json 与运行日志）：

指标	实测值
巡检页面数	8
发现 URL 数	11
站点拓扑有向边	59
执行动作数	25
遇到的原生元素	832
去重跳过次数	807
原生元素采样率	3.0%
独立控件指纹	25 种（自测 25 种 → `element_coverage_rate` 1.0）
URL 原型	6 个
捕获错误	1 条（`request_error`，置信 0.85，严重度 0.75）
总耗时	43.99 s

它确实抓到了

① 那个 500 被三路证据一起钉住。 上面那段 detected_texts 就是原始记录：console 报了两行、网络层报了一行，外加快照一张。这是我最想要的能力——页面 200、探活全绿的时候，它还是把问题揪出来了。

② 危险按钮被跳过了。 日志里就两行：

[INFO] [inspection.engine] Skipping destructive button/action: '清空全部缓存'
[INFO] [inspection.engine] Skipping destructive button/action: '退出登录'

整轮跑完，假站的会话没断，requests.log 里也没有任何登出/清空相关的请求。对一个要在生产环境跑的巡检工具来说，这条比「多抓几个 bug」重要得多。

③ 分页原型配额生效了。 列表页有 ?page=2..6 五个分页链接，巡检把它们点开了（requests.log 里 ?page=4/5/6 各 1 次，点完立刻回溯），但只有 ?page=2、?page=3 被当成页面排队巡检——因为 /list.html 这个原型的配额是 3 页（含第 1 页）。url_archetype_distribution 里 127.0.0.1:8765/list.html: 3，其余都是 1。这就是「无限下钻」被挡住的样子。

④ 外链弹窗被守护者接住并关掉了。 点到 example.com 那条 target="_blank" 外链时：

[INFO] [Multi-Tab Guardian] New window/tab detected: <Page url='https://example.com/external'>
[INFO] [Multi-Tab Guardian] New tab loaded: https://example.com/external
[INFO] [Multi-Tab Guardian] Closed popup tab. Focus preserved on main inspection page.

同一轮里，L2 回溯触发了 12 次——其中 5 次是在订单列表页里点开分页链接（URL 变成 ?page=N）之后，引擎发现页面漂移、把页面拉回来的，没有一次卡死在错页上。

而这份报告里有个数字「漂亮得可疑」

element_coverage_rate: 1.0，也就是控件覆盖率 100%。同一个响应里，raw_sampling_rate 是 0.03。

两个数字都没错，但它们是两个口径：

element_coverage_rate = 已测指纹 25 / 发现指纹 25 —— 分母是去重之后的集合，天然容易接近 100%；
raw_sampling_rate = 25 / 832 —— 分母是页面上真实存在的元素数。

也就是说「100% 覆盖」的意思是「在它认为不同的 25 种控件里，25 种都点过了」，而不是「832 个元素我都碰过」。看这类报告必须两个数一起看，只看前一个会得出很舒服但没用的结论。这算是我对这个项目第 1 条改进意见：报告首页应该把两个数并列展示。

还有个更具体的问题：管理后台那页一共 7 个按钮（2 个 tab、3 个工具按钮、2 个危险按钮），实际只执行了 1 个动作（点开「统计」tab）——2 个危险按钮被守卫拦下，另外 4 个被结构指纹判成同质元素跳过了，报告依然给 100%。这一页的去重记录长这样：

{"element": "Tag: <a>, Text: '首页', Container: 'standalone', Pattern: 'header > a'",
 "reason": "Structural fingerprint matches already tested container type",
 "signature": "single|a|text:首页|pattern:header > a"}

这一轮 807 次跳过，100% 都出自 L3 结构指纹（L1 URL 规范化、L2 路径原型配额这两层在这么小的站上根本没被触发）。指纹的原料是「标签 + id/文本 + 路径模式」，所以同一个容器里长得一样的一排功能按钮会被判成同一种控件——省了重复点击，也顺手漏掉了同类里的其它功能。我的想法是按「按钮文本 + 语义」再分一层，或者给关键按钮留个白名单。

四、实测二：把「静默失败」拆成 2×2

第一节那个 500 之所以抓得住，是因为它同时有 console 报错和网络 4xx/5xx。真正难的是三路证据都没有的那种失败：纯前端状态机弹了一句文案，没有请求、没有 console、没有非 2xx。

我造了第二个靶子：只有一个按钮的页面，点完 3 秒后出现一句纯文本提示「校验失败，请联系管理员」——没有 fetch、没有 console.error。然后做了 2×2 对照，两个变量：

提示元素写成 <div id="toast">（不在扫描器的选择器集合里）还是 <div id="toast" class="toast">（在里面）；
wait_after_action 用默认的 1.0 s 还是 5.0 s。

结果如下（每组一轮，配置只差这两项）：

提示元素	等待窗口	状态	捕获到的证据
`id="toast"`	1.0 s	PASSED，0 错误	无
`id="toast"`	5.0 s	PASSED，0 错误	无
`class="toast"`	1.0 s	PASSED，0 错误	无
`class="toast"`	5.0 s	FAILED，1 错误	`校验失败，请联系管理员`

**四组只成功了一组。**两个前提缺一不可：

选择器得命中：扫描器收的是 .toast / .message / .alert / .notification / .error / .danger / .warning / [role=alert] / [class*=error] / [class*=alert]。我第一版用 id="toast" → 索引不到，等多久都没用。
等待窗口得够长：默认 wait_after_action = 1.0 s，而提示 3 秒后才渲染，检查那一刻元素还是空的。改成 5.0 s 立刻抓到。

只有第三、四组之间的差别，才能把「工具没看见」和「页面真没问题」区分开。

:::warning **教训：PASSED 的含义是「这一轮我没看见故障」，不是「这一页没问题」。**静默失败捕获是有前提的，而且这些前提得自己检查。我现在接入任何站点前都会先过三件事：① 站点的提示组件用什么 class / role，在不在扫描集合里；② 关键异步操作多久才渲染结果，wait_after_action 够不够；③ 哪几条业务文案是「失败」的意思，要不要补进关键词表。这三条比我第一版写的任何测试脚本都值钱。 :::

五、两件得坦白的事

① 判定层我这次跑的是「关键词兜底」路径。 配了 TYPESAFE_API_KEY 时，页面证据会被丢给 JevClient 做一次模型研判；没配（或调用失败）就退化成源码里这一行：

is_err = any(kw in combined_text.lower()
             for kw in ["500", "404", "crash", "error", "失败", "网络错误", "internal server error"])

也就是说，中文文案里没有上面这些词、网络层又没留下痕迹的话，靠兜底是认不出来的。这也是我在实验二里必须先给假站的 toast 补上 class="toast" 的原因。想接自己的判定逻辑，正路是扩展钩子（BaseExtension 提供了 on_page_loaded / on_after_action / on_error_detected / on_finish 等 7 个挂点）——不过仓库里目前只有基类，没有示例插件，这一块得自己摸索。

② README 里的测试数字和实测对不上。 徽章写 Tests-45_Passing，README 里写着 Ran 45 tests in 70.24s；我在本地跑 python3 -m unittest discover -p "test_*.py"，跑了两遍：

Ran 36 tests in 70.318s

OK

Ran 36 tests in 69.168s

OK

耗时几乎一模一样（69~70 s vs README 的 70.24 s），条数差 9 个。我数了两遍 def test_，确实是 36 个。顺带说一句，这套测试不是打桩：里面真的起了本地 HTTP 服务、真的开了 Chromium 跑整站遍历（其中一条用例的单轮巡检就耗时 14.5 秒），这点比数字本身更让我放心。但徽章和 README 该改过来——这是我自己项目，先记在自己账上。

六、使用感受

先说好的：

真的是零脚本。 从 git clone 到出第一份报告，我花的全部时间就是 pip install playwright 加上一条命令。这对「被测系统一天改三次」的团队是刚需——巡检脚本的维护成本是个无底洞。
产物是给人看的，不是给机器看的。 JSON 里有 summary、站点拓扑、逐个动作、去重记录；同时生成一份 HTML 看板，还能写 Prometheus 指标文件（我这轮就落了一份 inspection_metrics.prom，web_inspection_status{target=...} 0），告警模块内置了飞书/钉钉/企微/Slack 四种 webhook 格式。
它和确定性用例是互补的，不是替代关系。 这点是我想清楚之后才明白的：探索式巡检负责「在我没写用例的地方高频扫一遍」，仓库里的 flow 引擎（goto / click / fill / assert，带 text_contains、visible、url_matches 断言和 SLA 时延违约判定）负责「关键链路必须准」。我的用法是 90% 探索 + 10% 关键链路确定性用例，比纯靠任何一边都稳。
危险动作有一道闸。 词表可配，命中即跳过——这是敢把它指向真实生产环境的前提。

再说代价和没解决的：

单站串行，站点一大就慢。 8 页 44 秒，平均每页 4~5 秒；并发调度在 scheduler.py（ThreadPool + SQLite 存历史 + /health /metrics 探口）这一层，单站内部仍是串行。大站要拆成多个候选入口并行跑。
两个覆盖率要一起看（见第三节），报告首页目前只突出一个，容易误导。
L3 结构指纹对「同容器内的一排功能按钮」过于激进，会把还该点的按钮一起去重掉。需要白名单或自定义钩子补。
判定层依赖关键词或外部模型，中文文案要么进词表，要么走钩子；这块是目前最薄的一环。
等待窗口和动作超时是两个不同的旋钮。 action_timeout_ms（默认 5000）管的是单次交互能不能点成功，wait_after_action（默认 1.0 s）管的是点完之后给异步渲染留多久——实验二翻的就是后一个的盘。
README 和徽章的数字要跟实测对齐（上面第 ② 条）。

**一句话总结：这个工具的价值不在于「覆盖所有按钮」——那份 100% 的覆盖率随时可能骗你；它的价值在于在我没写用例、探活也照不到的地方，它能自己逛过去，并且在页面仍然返回 200 的时候把故障钉住。**一个只有一个人的测试团队，这种「不用维护的覆盖率」比多写 50 条用例实在得多。

七、如果你也想试

git clone https://github.com/ABK3528/jev-inspector.git && cd jev-inspector
pip install -r requirements.txt && playwright install chromium

# 整站巡检一轮
python3 main.py --url https://your-app.com --crawl-mode site \
  --max-pages 10 --max-depth 2 --report report.json --html-report report.html

# 常驻 + 健康检查/指标端口
python3 run_inspection.py --config sites_config.sample.json --serve --port 8089
# CI 里让它失败即退出（错误数 > 0 时返回码 1）
python3 main.py --url https://your-app.com --fail-on-error

接入生产前，建议按第四个实验的结论先做三件小事：把站点的提示组件选择器核对一遍、把 wait_after_action 调到覆盖你的异步渲染时间、把「失败」类文案补进关键词表。做完这三步，PASSED 才值得信。

参考

项目仓库：https://github.com/ABK3528/jev-inspector（Apache-2.0）
仓库里 README 记录的公网实测（Hacker News 8 页、1,067 条拓扑边、2,128 个元素去重掉 2,104 个、44.76 s）：我没有复跑，只作为作者自测记录引用；本文所有数字都来自我自己那两组本地实验
追问某一行行为时的入口：jev_inspector/engine/crawler.py（去重、回溯、判定、标签页守护都在这个文件里）、jev_inspector/decision/jev_client.py（模型客户端）、jev_inspector/extensions/base.py（7 个扩展钩子）

trace-to-test × browser-harness：把一次浏览器操作，编译成零 LLM 的确定性回归

Wed, 30 Sep 2026 00:00:00 GMT

UI 回归测试一直有个尴尬的地方：报告是红的，但它说明不了产品是坏的还是脚本是坏的。人得先花时间确认这一点，才谈得上定位。

trace-to-test 是我最近写的一个框架，专门解决这件事。做法可以一句话说完：把一次真实的浏览器操作录下来，编译成一条声明式回归，再以零 LLM 的方式确定性重放——重放结束只给你一个结论，而那个结论会区分「产品漂移」和「测试写坏」。

仓库：https://github.com/ABK3528/trace-to-test
语言：Python ≥ 3.12，机制层零业务词，可跨项目复用
录制层：browser-harness（CDP 直控 Chrome），可选依赖锁 0.1.8
现状：v1 打通了一条 UI 竖切（录制 → 编译 → 回放），make demo 一条命令可自证

两条老路，各自的硬伤

做法	硬伤
手写脚本（Selenium / Playwright）	锚点靠人挑。写的时候页面长什么样就照着写，页面一改整片红，而红的是不是产品坏了没人能一眼判断
让 LLM 每次现场驱动浏览器	不确定。同一个用例今天过明天不过，不可 CI，而且失败原因无法归因

这两种做法的共同问题不是「不好写」，而是结论不可信。第一条路把「产品改文案」和「元素被删掉」混成同一个红；第二条路连「这个红可不可重复」都保证不了。

还有一条常被忽略的路——视觉回归（像素 diff）。它同样解决不了归因：像素变了到底是布局重构还是缺陷？v1 明确不做这条，只做语义锚点 + 文本/状态断言。

核心主张：AI 只进两个阶段

框架的全部设计都指向一个取舍：让 AI 在「探索」和「编译」两个阶段介入，把它的判断固化成一段不依赖模型的确定性代码。

阶段	谁来做	产物
① 录制	人（或 AI）手动走一遍真实流程；浏览器驱动与录制由 `browser-harness` 提供	`events.jsonl`：动作、坐标、URL、截图、获焦元素
② 编译	编译器 + 一次带探针的回放	`workflow.json` / `checks.json` / `unresolved.jsonl` / `checks.todo.md`
③ 回放	纯代码，零 LLM	三态判定之一 + 失败点

回放路径上没有任何模型调用，也没有随机性来源。同一条 workflow 在 CI 上可以跑一万次，结果一致——这正是它能进 CI 的前提。

录制层是 browser-harness

链路的第一段不是本框架自己实现的：驱动浏览器、并把动作录下来的那一层是 browser-harness（browser-use 出品的开源包）。trace-to-test 把它当可选依赖锁在 0.1.8（uv sync --extra browser，不 fork、不 vendor），自己只负责编译和回放。

它不走 WebDriver，而是用一条 CDP 连接直控真实 Chrome——这点对本框架很关键，因为编译期的探针回放需要在真实页面上执行 elementFromPoint 这类 DOM 查询。对上层它暴露三样东西：

模块	作用	本框架怎么用
`helpers`	`goto` / `fill_input` / `click_at_xy` / `press_key` / `wait*` 等动作	`Session` 的每一次动作都走它
`recorder`	把动作按时间序写成录制	录制模式下由 `Session` 显式调用
`admin`	daemon 生命周期（自起 Chrome、退出回收）	保证只连自己起的 Chrome + 独立 profile

一次录制的产物就是一个目录，core/transcript/ 只读它、不做推断：

meta.json      {name, title, started}
events.jsonl   一行一个动作：动作名 + 坐标 + URL + 截图名 + 获焦元素
0001.jpg …     每步动作之后的截图帧

框架与 browser-harness 的契约只有这一层。 所以它升级时受影响面有限，但也不是零：core/transcript/recording.py 里那份动作名集合与上游 recorder.ACTIONS 逐字对齐，并有一条测试盯着——上游改格式会先让测试红，而不是让回归静默变绿。这也是这里锁 0.1.8 而不跟最新版的原因：录制格式是唯一的对外契约，升级要连带改集合和固定录制样本，值得单独一次提交。

三个绕不过去的细节（都写在代码注释里）：

只有走 tracing 包装才会产生录制。 直接 import helpers 驱动浏览器不会写出 events.jsonl，所以 Session 自己调 recorder.observe；且坐标必须按位置参数传——recorder._details() 是按下标取值的，改成关键字参数坐标就变成 null，编译器随即无坐标可反解。
BU_NAME / BU_CDP_URL 必须在 import browser_harness 之前写进 os.environ。 daemon 名是 import 时读一次的，写晚了会静默落回默认 daemon 并挂到你自己正在用的浏览器上。框架用这两个变量把 browser-harness 关进自起的 Chrome + 独立 profile，退出时按 user-data-dir= 精确回收（裸路径会误伤无关进程）。
密码框内容被上游遮蔽成 •，URL 里的凭据也会被 scrub 成 REDACTED。这直接决定了「要编译的流程应当从已登录会话开始录」（详见下文已知边界）。

这条链上有两个语义鸿沟

「录制 → 回放」听起来像录像回放，实际不是。中间隔着两个语义鸿沟，这也是这个框架存在的全部理由。

鸿沟一：录制记的是「做了什么」，回归要的是「怎么找到它」

events.jsonl 里一条点击长这样：

{"helper": "click_at_xy", "x": 412, "y": 306, "url": "http://127.0.0.1:8712/list", "box": {...}}

坐标直接写进回归，等于把分辨率、字号、布局全锁死。所以 core/compile/ 的真身不是转录器，而是**「坐标 → 语义锚点」的反解器**。

麻烦在于：录制里没有「被点中的那个元素」。browser-harness 写进 events.jsonl 的 box 是当前获焦元素的框，不是点击目标。想知道「当时点的是谁」，只能拿着坐标回到实时页面上重新问一次浏览器。

因此编译是一次带探针的回放：按录制顺序重放，在每个需要锚点的动作执行之前，用 document.elementFromPoint(x, y)（点击类）或 document.activeElement（输入/按键类）取元素快照，再交给纯函数排序器产出候选锚点。编译器复用回放引擎——两者是同一个引擎的两种模式：回放模式断言结果，探针模式采集锚点。

这也带来两条硬约束：编译期目标必须可达，且视口要与录制时一致（探针按录制坐标去问元素，视口变了它问到的就是另一个元素，而一切看起来都正常）。

锚点的优先级是固定的：

testid 排第一而不是文本，理由很实在：文案会随发布变化，拿文案定位会把「按钮没了」和「按钮改叫别的了」混成一件事。所以 role/text 类锚点会被标上 copy_sensitive: true，交给三态判定去区分——见下文。

而 xy 只是最后兜底：用到会打 WARN，并且必须在报告里单列。

:::warning 反解不出的事件不许默默降级成坐标。 解不出的动作会写成 unresolved.jsonl 的一条，带上原始事件、候选锚点列表、以及为什么解不出（例如 value_ref_required、ambiguous）。人补齐后重新编译。这是「录的时候能跑、换个环境就死」的唯一闸门。 :::

鸿沟二：录到的观测值不能当期望值

把「探索时看到什么」直接写成断言，等于把当下的现状固化成基线——如果那一刻已经有个 bug，这个 bug 就被写成期望值了。

所以编译器只产路径和观测快照，断言位留空，标成 TODO_ASSERT，并产出一份待办：

# 待补断言：wf-demo-smoke-…

编译器只给路径与观测点，**期望值必须来自外部**（需求文档 / 夹具 / 手写）。
- [ ] step 4 (click `登 录`): 断言语义 —— 期望值请从需求文档/夹具取
- [ ] step 7 (click `confirm-create`): 断言语义 —— 期望值请从需求文档/夹具取

checks.json 里每条断言必须带 source 字段声明期望值出处（spec: / prd: / fixture: / handwritten:）。core/lint/checks_lint.py 会拒收两类反模式并返回非零退出码：

无断言（只有一个能跑通的路径，等于没测）；
source 缺失或形如 observed:*（即抄了编译期观测值）。

怎么读结果：三态判定

回放只给一个结论，取三态之一：

结果	判据	含义
`PASS`	步骤全部定位成功，且外部来源的断言全过	通过
`FAIL_PRODUCT`	锚点找得到，但断言值不对（`reason=assertion`）	产品漂移或缺陷
`FAIL_PRODUCT`	锚点失效，但存在近似匹配（`reason=anchor_drift`）	元素还在，只是文案改了 → 产品改动
`FAIL_ANCHOR`	锚点找不到且无可近似匹配（`reason=missing`）	元素没了 / 结构变了 → 脚本问题
`FAIL_ANCHOR`	锚点匹配到多个不同元素（`reason=ambiguous`）	判据不唯一 → 脚本问题

其中 anchor_drift 这条值得单独说。role/text 锚点是对文案敏感的：文案一变它们就失效。如果直接判 FAIL_ANCHOR，真实的文案改动会被误报成「测试写坏了」；反过来拿坐标兜底，又退回了鸿沟一。所以这类锚点失效时会做一次归一化近似匹配（去空白、去标点、大小写折叠，相似度 ≥ 阈值即算命中）：

元素还在、只是标签变了 → 归 FAIL_PRODUCT，带 reason=anchor_drift；
连近似匹配都没有 → 才归 FAIL_ANCHOR。

testid 锚点不做近似匹配（它没有可比较的文本），锚点失效时直接 FAIL_ANCHOR。这正是「改文案」和「摘锚点」两种场景能分开的原因。

:::note 一个容易踩的次序问题。 回放在第一个失败点即停（后面的步骤结果不可信），所以断言挂在哪一步很重要。要证明「锚点缺失 → FAIL_ANCHOR」，断言必须挂在最后一个动作之后。否则摘掉 testid 时先撞上的会是断言自己的 testid，判定被归成 FAIL_PRODUCT，两种状态就分不开了。 :::

三态之外：两个「还没有结论」的标注

回放判 FAIL_PRODUCT 之前，会先跑三项业务无关的自查。它们不构成第四态，只决定「现在能不能下结论」：

自查	命中时	为什么不是第四态
目标构建标识与本 workflow 记录的不一致	`STALE_TARGET`，不下产品结论	环境没对齐，此时判产品坏或脚本坏都不成立
首轮失败、次轮通过	`COLD_START_FLAKE`，重跑一次再判	重跑后的结果仍归入三态之一
依赖的探针端点未就绪	`FAIL_ENV`，与产品问题分开计	只表示「这次没验成」，不表示产品有问题

一句话：FAIL_ENV / STALE_TARGET 是**「本次未得出结论」的标注**，不是结论。遇到它们先恢复可判定条件再重跑，不要当产品或脚本的 bug 去改代码。

架构：机制层和适配层的边界是硬的

框架分两层，边界不是「建议」，是 scripts/portability_check.sh 会扫的：

层	目录	规矩
机制层	`core/` `checks/` `skills/`	零业务词、零 agent 专属依赖。唯一需要保证可移植的部分
适配层	`adapters/`	业务只准活在这里：被测目标声明、凭据来源、期望值（oracle）来源、提示词骨架的项目实例片段

make portability 拿 scripts/business_words.txt 去 grep 机制层，必须零命中；白名单只放 <target> 这类占位符，且逐条带理由——新增一条白名单等于放宽约束，得在 PR 里说明。

落到你自己的项目，checklist 只有四条：

[ ] 把项目专属词汇加进 scripts/business_words.txt，确认机制层仍通过 make portability
[ ] 在 adapters/ 实现本项目的 target 与 oracle 接口
[ ] 把真实的探索流程放进 adapters/instance/
[ ] 先跑通一条端到端竖切，再谈扩展——不要先定接口

最后一条是我自己的教训：接口在只有一条竖切的时候定，几乎是必错。

上手：三条命令

需要 Python ≥ 3.12、uv，以及本机装好的 Chrome / Chromium。

git clone https://github.com/ABK3528/trace-to-test.git
cd trace-to-test
uv sync --extra browser --extra dev   # browser: browser-harness（CDP 直控本机 Chrome）；dev: pytest

仓库自带一个零依赖的极简靶场（target_app/：登录页、异步列表、弹窗、暗色模式、一个可控的偶发失败端点），用来自证整条链。跑它：

make demo

它会真录一遍、编译、补全，然后在四种情况下回放，最后打印判定表（下面是我本机的真实输出）：

recording saved: …/recordings/demo-smoke-… (10 frames)
compiled → demo/build/compiled  (7 steps, 2 unresolved)
  unresolved: seq 3 fill_input — value_ref_required
  unresolved: seq 4 fill_input — value_ref_required
preflight: ok (-)
✅ baseline                     PASS           reason=-
✅ copy drifted                 FAIL_PRODUCT   reason=anchor_drift
✅ testids stripped             FAIL_ANCHOR    reason=missing
✅ artifact carries no coordinates 3 click step(s), xy=[None, None, None]
✅ recorded coords are stale now with='HTML|…' without='BUTTON|登 录'
✅ layout shifted (120px)       PASS           reason=-

🎉 三态可证：改文案 → FAIL_PRODUCT，摘锚点 → FAIL_ANCHOR，原样 → PASS
🎉 回放走锚点：产物不带坐标，且位移 120px 后仍 PASS（坐标已失效）

前两行证明三态分得开（改文案 → 产品问题；摘掉稳定钩子 → 测试问题）。后三行证明回放走的是锚点而不是坐标：把靶场布局整体下移 120px，录制时的坐标全部失效，回放仍然 PASS。

:::tip 在容器/CI 里以 root 运行时，Chrome 会拒绝启动（Running as root without --no-sandbox is not supported）。v0.1.0 尚未内置这个分支，在 core/primitives/session.py 的 chrome_launch_args() 里补一个 os.geteuid() == 0 时加 --no-sandbox 即可。指定浏览器用 TTT_CHROME=<可执行文件路径>。 :::

编译产物长什么样

workflow.json 是纯路径，不含坐标：

{
  "id": "wf-demo-smoke-…",
  "title": "Login and open create dialog",
  "source": { "recording": "demo-smoke-…", "compiled_at": "2026-09-30T03:27:08+00:00",
              "viewport": [1440, 900], "build": "demo-build-1" },
  "steps": [
    { "n": 1, "action": "goto",  "path": "/login" },
    { "n": 2, "action": "fill",  "selector": "#username", "value_ref": "env:DEMO_USERNAME" },
    { "n": 4, "action": "click", "anchor": { "by": "role", "role": "button", "name": "登 录", "copy_sensitive": true } },
    { "n": 7, "action": "click", "anchor": { "by": "testid", "value": "confirm-create" } }
  ]
}

注意 value_ref: env:DEMO_USERNAME——value_ref 只允许指向环境变量或适配层声明的凭据名，密码/令牌不进 workflow。

checks.json 是断言的 sidecar，每条都带 source：

{ "checks": [
  { "id": "c1", "after_step": 7, "kind": "count",
    "anchor": { "by": "testid", "value": "item-row" },
    "expect": "3", "source": "spec:demo/spec.md#2-列表页",
    "observed_at_compile": "" }
] }

observed_at_compile 只供人工比对，永不参与回放判定。

测试策略：`make test` 不覆盖什么

make test          # 195 passed, 5 skipped in 4.75s
make portability   # ✅ portability check passed (core checks)

那 5 个 skipped 正是「本框架的差异化没有被执行」的证据——端到端用例需要真实浏览器，默认跳过，只有 TTT_E2E=1 才跑。要证明框架端到端能跑通，跑 make demo，不是 make test。

已知边界（v1 的诚实清单）

这些是设计上就知道、且写在 README 里的：

type_text 暂不编译，探索流程请优先用 fill_input；
录制层锁在 browser-harness 0.1.8（上游已到 0.1.13，且它本身是个仍在快速演进的 agent 浏览器工具）：录制格式是唯一的对外契约，升级要连带更新动作名集合与固定录制样本；
scroll 事件按设计丢弃：既不产生步骤，也不记 Unresolved。所以「滚动之后才点到的元素」可能编译出一个视口外的目标——要稳定就在探索脚本里先把元素滚进视口；
xy 只是兜底锚点，用到会打 WARN；
v1 只覆盖 UI 轨：接口生成 / 流程编排 / 契约三轨只留了骨架；
一个进程同一时刻只开一个 Session（daemon 名进程内稳定），要并发请用不同进程；
密码是已知边界：录制器把密码框内容遮蔽成 •，所以编译期探针会键入一串圆点、登录过不去，之后的锚点会诚实地落进 Unresolved——这是正确行为，不是缺陷。要编译的流程应当从已登录会话开始录，或在补全阶段用 value_ref（env:<VAR>）把凭证接回；
录制期点击竞态：无头 Chrome 下合成点击偶尔不触发 dialog.showModal()。实测在一次 14 连跑的背靠背序列里连续失败 10 次（无头、本机带载），随后又连续成功——失败率没有被良好刻画，别拿它当稳定概率。它只发生在探索/录制阶段，回放路径不受影响。

把这些写进 README 而不是藏起来，是因为测试工具的边界本身就是它的一部分可信度：知道它在哪会假红，才知道什么时候该信它。

后面

三条轨（接口生成 / 流程编排 / 契约）的骨架已经留位，每条轨开工时遵循同一原则：先有一条竖切跑通，再定该轨的接口。

如果你也在被「红了但不知道是谁的错」折磨，可以先把靶场跑一遍（make demo，两分钟），再看 demo/build/final/ 下的产物。仓库是公开的：https://github.com/ABK3528/trace-to-test。设计文档在 docs/trace-to-test-design.md，机制的实施计划在 docs/trace-to-test-mechanism-plan.md。