新 AI 能力上线，怎么驾驭 AI 给它建一套检查

让 AI 先读懂框架规矩

别一上来就让 AI 干活。先让它把这个工具的规矩吃透——执行器有哪些动作、目录怎么放、场景协议长什么样、有哪些纪律（比如"动作必须通用、不为单个业务写死"）。这一步不做，后面它写出来的东西全是不守规矩的紧耦合代码。

请先阅读这个检查工程的全部规则文档，不要写任何代码。读完后，用你自己的话讲清楚：
 
1. 通用执行器负责什么、不负责什么
2. 现有的"动作词汇表"有哪些动作，分别干什么
3. 一个 feature（特性）的目录结构是怎样的，文档/场景/记录各放哪
4. 有哪些必须遵守的纪律（比如什么时候才能给执行器加新动作）
 
讲清楚之后停下来，等我确认，再进入下一步。

为什么先让它复述： 这是最省力的一道关。它复述对了，说明它真读懂了，后面一次就能做对；复述歪了，你当场就能纠，成本最低。不要省这一步。

喂 PRD，让 AI 理解新特性是干什么的

把这个新能力的 PRD（或设计文档）丢给 AI，让它先建立认知——这个功能是干嘛的、用户怎么触发它、预期的交互链路是什么。然后让它基于你的设计意图，先给出一份"场景总览"：这个特性大致该覆盖哪些检查场景。

这一步还不碰浏览器，是纯纸面推演。目的是让你和 AI 对"要检查什么"先达成共识。

这是新能力「<特性名>」的 PRD：<贴 PRD 内容或路径>
 
请阅读后告诉我：
1. 这个功能是干什么的，用户从哪里触发、怎么交互
2. 它的预期主流程是什么，有哪些关键边界情况
3. 基于以上，给我一份"场景总览"：你认为这个特性应该覆盖哪些检查场景（主流程 + 边界），每个场景一句话说清验什么
 
先不要写任何执行代码，也不要急着探测。我们先就"要检查哪些场景"对齐。

你要做的判断： 场景总览是你掌控业务的地方。AI 给的总览往往偏"功能点罗列"，你要按真实用户视角补——哪些边界它没想到、哪些场景其实不重要。这份总览改定了，才往下走。

让 AI 写临时探测脚本，自己去摸真实页面

这是第一部分的核心。纸面推演完了，得让 AI 去摸真实页面——这个功能的入口在浏览器里到底长什么样、按钮叫什么、元素在哪、点下去返回什么。

做法是让 AI 写一个一次性的临时探测脚本去跑（不是正式场景，是探路用的），自己登录、自己点、自己把看到的元素和返回打印出来。

现在去摸真实页面。请你写一个一次性的临时探测脚本（放到 archive/probe-scripts/ 下），
目标是搞清楚「<特性名>」在页面里的真实形态：
 
1. 它的入口在哪——是对话框里发消息，还是某个页面上的按钮/菜单？
2. 触发后的关键元素是什么——选择器、文本、有没有候选卡片？
3. 交互返回长什么样——把页面可见文本、关键 DOM、相关接口返回都打印/截图存下来
 
脚本只做探测、只读不写，跑完把你的发现整理给我。遇到找不到的元素，
先把你已经抓到的页面结构发给我，告诉我你卡在哪，我来帮你定位。

人机分工就在这一步现形： 基本是 AI 自己探、自己写、自己跑。但它经常会卡在某个找不到的元素上——这时候你来兜底：打开页面，把那个按钮/元素在哪、选择器是什么指给它看。你出"它看不见的那一眼"，它接着把活干完。这就是"能让它自己做就自己做，卡死了我才介入"的真实节奏。

现有动作不够用，就让 AI 给执行器加新动作

探测时你很可能发现：这个新特性的入口或交互，现有的动作词汇表覆盖不了。比如它不是对话式的，是藏在详情页里的一个能力；或者它需要点开一个折叠卡片、操作一个下拉框——这些现有的 send / click 表达不了。

这时候才给执行器加新动作。注意纪律：新动作必须保持通用，绝不能为这一个业务写死。

根据探测结果，现有动作词汇表无法表达「<某个操作>」。请给执行器加一个新动作。
 
要求：
1. 这个动作必须是通用的——描述的是一类浏览器操作，不绑定任何具体业务
2. 命名、参数、挂载方式都遵循现有动作的写法，和 open_comi/send/click 保持一致风格
3. 不要在执行器里出现任何这个特性的业务名词
4. 加完后，更新动作词汇表的说明文档
 
如果你觉得用现有动作的组合其实也能表达，先告诉我，我们不轻易加动作。

为什么要克制： 执行器是所有特性共用的地基，每加一个动作都是在给地基增重。原则是"几个不同特性都需要同一个操作时，才把它沉淀进执行器"。能用现有动作拼出来，就别加。

Step 5（可选）：需要更细的数据时，再做一次单点探测

有些场景光知道入口还不够，还得拿到更细的数据才能写准断言——比如某张表单到底有哪些字段、字段的真实值是什么。这时候再做一次更聚焦的探测，把这些数据抓回来。

场景「<场景名>」需要更细的数据才能写断言。请针对它单独探测一次：
 
把 <这个表单/这个页面> 的真实字段名、字段值、表格结构抓下来，
整理成我能直接拿来写断言的清单——哪些字段该出现、它们的值是什么。

不是每个场景都要这步。 对话式的简单查询，Step 3 探一次就够了；涉及复杂表单、要验字段回填的，才需要这层补充探测。

把探测结论沉淀成这个特性的 skill/index 文档

第一部分的真正交付物在这——不只是写一份文档，而是为这个特性建立起完整的目录结构，并写一份"说明书"：教 AI（也教未来的你）以后该怎么检查这个特性。

现在把前面所有探测结论沉淀下来。请：
 
1. 创建这个特性的目录结构：features/<特性名>/ 下的 docs/、scenarios/、records/
2. 在 docs/index.md 里写清楚这个特性的"检查说明书"：
   - 功能是干什么的、入口在哪、怎么交互
   - 检查它要用到哪些动作（含这次新加的动作）
   - 探测发现的坑（比如多候选、内容折叠、DOM 会混历史对话）
   - 场景总览（从 Step 2 来，已和我对齐过的）
3. 全部遵循框架的目录约定和文档规范
 
写完告诉我目录结构和 index.md 的内容，我来审。

跑通的标志： 执行器认识这个新特性了（必要的动作都有了），而且有一份 skill/index 文档，让 AI 以后能照着它给这个特性写检查场景。第一部分到此结束。

基于说明书，让 AI 写场景文档（人话版）

从这里开始进入第二部分。后面这几步对任何特性都一样，是通用套路。

先让 AI 拿着 Step 6 的 skill/index，把场景总览里的每个场景，展开成一份"人话版"的场景文档——每个场景检查哪条链路、每一步发什么、预期回复里该有什么。这一层还不是给机器跑的，是给你审业务逻辑的。

请基于 features/<特性名>/docs/index.md，把场景总览里的场景展开成场景文档
（docs/<scenario>.md，人话描述，先不写 JSON）：
 
每个场景写清楚：
- 这个场景检查什么（一句话）
- 步骤链路：第几步做什么操作、发什么话
- 每步的预期：回复里应该出现什么、不应该出现什么
 
写完我来逐条审，确认业务逻辑对了，再转 JSON。

这是你掌控业务的最后一道关。 转成 JSON 之后就是机器的事了，业务对不对，全看这份人话文档审得细不细。

让 AI 把场景文档转成可执行 JSON

人话文档审定，让 AI 把它翻译成执行器能跑的场景 JSON。

请把 docs/<scenario>.md 翻译成 scenarios/<scenario>.json，
严格用现有动作词汇表和场景协议。翻译完逐条告诉我：
每个断言为什么这么写、候选选择用的是 click 还是 click_nth。

你重点审两件事：

1. 候选选择有没有用对。 如果探测发现目标不是第一个候选（比如排第三个），就必须用 click_nth 配 index，而不是默认 click 点第一个。
2. 断言关键词稳不稳。 关键词必须是不随 AI 回复波动的稳定文本。卡一句完整的话，今天能过明天就挂；卡一个核心词（比如"出差""北京"），才扛得住流式波动。

执行，看报告

一行命令跑起来，看每一步的截图和 AI 回复。

执行 scenarios/<scenario>.json，跑完把报告路径发我，
失败的步骤先列出来，不要急着改，我们下一步统一复核。

失败不要慌，也不要让 AI 立刻去"修"。机器判分一定有误判，先记下来，进入下一步统一处理。

人工复核归因，沉淀结论

这才是一次检查真正的终点。逐条看失败断言，分清楚到底是哪种：

• 功能真有问题——AI 答错了、漏字段了、路由跑偏了，这是真 bug。
• 断言设计问题——AI 其实答得合理，是你的关键词卡太死或不稳定。
• 执行器能力问题——某个操作现有动作表达不了。

机器判分是起点，人复核归因才是终点。 脚本报的失败里，常有 AI 给了合理回复却被判挂的——这种要剔除，剩下的才算真问题。

跑了多个场景后，可以让 AI 把多份报告汇总成一份整体检查报告：

请读取 features/<特性名>/records/ 下本轮所有执行记录，
按「应用检查报告模板」汇总成一份整体报告：
 
1. 基本信息（任务、环境、时间、用例总数：通过 X / 不通过 Y）
2. 检查清单明细表（每个场景：业务分类、目标、动作链路、检查结果）
3. 问题明细表（问题类型、严重程度、问题描述）
 
注意：脚本判定的失败要逐条复核，把 AI 给了合理回复的误判剔除后，
再认定真问题数。复核过程和剔除了几例，在备注里写清楚。

AI 出汇总初稿，你再手动调一调措辞和归类——一份能直接拿去报 bug、能回归的检查报告就成了。