稳定行为规格与 YAML 用例

在保存或维护业务行为 KB 时读取。YAML 的知识价值独立于测试层与执行安排：单测足够、不做 GUI、 暂不生成代码都不是省略或删除有用 YAML 的理由。按实际需要保存背景、动作、期望与关联， 简单规则可以保持简式。不因采用 YAML 就强制 E2E、固定配额或执行 DSL。

行为比执行表达更稳定

用背景、前提、动作与可观察结果表达合同。定位器、坐标、窗口引用、驱动参数和模型提示属于投影； URL、协议字段、精确文本若本身是合同，仍保留必要精度。不可从本次产品输出反推正确期望。

按 story（任务主流程）、feature（能力合同）、case（边界或异常）组织：主干步骤进 story， 主线装不下的窗口独立为 case。它们是阅读组织方式，不规定目录、层级字段或测试数量。沿目标项目 已有布局维护可追溯关系，不要求一份 YAML 对应一个 spec，也不为每个执行原子创建用例。一份 YAML 可由多个已有单元 / 集成保障承接，或暂作不执行的 KB；生成哪层代码由真实保障缺口决定。 不必为凑齐三层补一份重复的 feature，也不要求它们逐层引用。

完整例子见 Google 搜索：以一个小项目展示行为 YAML、原子 动作、流程组装与测试入口的位置和追溯关系，演示输入查询、修改查询，再打开官方文档结果。目录 只是示例，实际项目沿已有布局组织。用例本身写清起点、输入与可观察结果，不为了展示组织方式另拆 feature 或 case。代码是否提取自已观察步骤、是否完成回放，在示例中分别说明；YAML 与代码存在都 不代表当前环境已执行或通过。

在项目中放置与追溯

先找项目根、已有行为资料和测试布局，分别确定知识归属与执行入口。行为 YAML 应能独立阅读、 维护和查找，不因暂时没有自动化而放进某个执行脚本的私有目录。没有既有约定时，可以从下面的 布局开始；目录名称只是参考，各测试层和 feature / case 都按实际需要出现。Google 示例只含 E2E：

项目根/
  specs/
    stories/              行为主线 YAML
    features/             按需，独立能力合同
    cases/                按需，边界或异常行为
  tests/
    unit/                 按需，单元测试
    integration/          按需，集成测试
    e2e/                  按需，完整界面流程；Google 示例采用此层
      actions/            可复用的动作步骤
      flows/              动作与断言的组装
      fixtures/           测试准备与本地验证素材
      *.spec.ts           测试入口

按目标失败选择代码的位置：规则可落在现有单元测试目录或与源码相邻，模块接合沿集成测试布局， 确需完整路径才放入完整流程测试。已有项目可能以模块、功能或测试层组织，不必为了匹配示例迁移。 准备、登录和设备或浏览器资源沿宿主入口复用；不把凭据或环境状态写进 YAML 和动作代码。

投影中的测试入口或组装代码应指向所依据的 YAML，例如保留相对代码文件可解析的来源路径，或使用 项目已有的可解析链接与元数据；重命名、移动时同步核对。它是追溯线索，不是自动加载、递归执行或 授权，也不需要为此在 YAML 里添加 ref。一个行为可由多层测试共同保障，一份测试也可关联多个 行为；已有实现或只有 KB 时不强造一对一文件。具体目录和调用关系见示例项目的 README。

字段与投影的关系

• id：用语义短名作为阅读和投影追溯锚点，在选定行为库中避免歧义，沿项目已有命名约定。
• description：说明这份行为材料负责什么。
• context：背景、前提、资源取得方式。可以声明已登录或应用已启动，由独立准备 flow 接回； 不复制真实凭据，仍核对本例角色、数据和起点。
• steps：自然语言 action 与可选 expect。一个行为动作可由多个执行操作实现，动词不构成 可执行枚举；执行层 action / agent / decision 不加入这里。
• expect：来自需求、协议或有权确认的行为基准，可以是字符串或列表。空缺表示没有额外断言， 不能据此声称整个行为已验证。
• lookup：给 Agent 的自然语言查找线索，不是固定源码绑定。

项目需要时可沿用 status: manual | automated | stale | obsolete 表示执行安排的就绪状态。 它不等同于 GUI / E2E，不注册 CI、不授予模型费用或工具权限，也不是本轮通过证据；KB 暂不执行 时可不填，项目已有等价状态时不再建一份。

ref 只在有阅读价值时使用

先判断读者为什么需要跳转：例如本例依赖一份已有、独立维护的权限合同，而完整复述会复制事实源。 这时才用 ref 指向材料并说明关联原因。几句就能写清的前提直接写清；只是主题相同、目录相邻， 或为了展示引用能力，不足以成为拆分与互链的理由。Google 搜索示例不需要 ref。

ref 是按需阅读线索，不继承前置、不递归展开或执行。不要把单独一个 ref 写成动作，也不要把 相关用例列表伪装成有序 steps。阅读某个关联 case 不等于本轮必须执行它；选中行为后，仍须根据 它的前提与期望取得实际观察。关联沿项目已有表达维护，不为引用另造统一结构。

路径相对当前文件解析；较大行为库也可按已声明的库根给完整相对路径。相对路径与符号链接不得 越过授权阅读范围；歧义或目标缺失先报告。不把引用可解析当成行为通过。

示例的保障边界

Google 示例选择的是用户找文档的任务。期望来自任务目标与 Google 公开搜索说明，不是把某次结果列表当作 永久答案。相关结果不必逐字包含所有查询词；排名、摘要、结果数量和页面布局不作固定断言。 示例明确要找 Playwright 官方文档，因此目标域名与文档主题仍须检查，不能只凭页面跳转算通过。

这里操作的是外部搜索产品，没有其内部代码，不能虚构 Google 规则单测来证明网页流程。若目标项目 拥有查询构造、编码或状态更新逻辑，可以用单元或组件测试守住相应部分；它们不证明外部搜索服务 和真实页面接合成立。测试安排留在保障分析与投影中，不混进业务 context。

同意提示与起始浏览器由准备流程处理，业务流程不隐藏重登、重开或替用户选择隐私偏好。若遇到 异常流量验证、网络不可达或站点拒绝访问， 保留实际阻碍与未验证步骤，不把拦截页、模拟搜索结果或直接访问文档站算作原搜索流程通过。

lookup 是查找资料，不是固定路径断言

组合使用业务概念、符号、现有测试行为与粗粒度目录定位当前实现。路径可以作线索，但不把它变成 正确性的唯一锚点；重构后应能用其余线索重查。具体定位结果留在本轮工作记录或已有投影里，避免 让稳定行为随每次搬文件更新。

单条线索失效不直接使行为失败；全部失效或存在歧义时先查当前合同、调用与变化。定位失败可能是 测试表达漂移，也可能是按钮误删、权限回归或产品缺陷，不能自动修到绿。行为语义真的变化时先由 有权负责人确认，再同步期望与执行投影。

维护和验证投影时读执行投影；格式与引用用项目已有解析或静态检查 核对即可，不为这套阅读材料另建通用编译器或校验框架。

Google 搜索：行为与执行投影

本目录模拟一个测试项目的根目录。Google 是外部被测系统，项目本身没有产品 src/。 specs/stories/google-search.yaml 描述搜索 Playwright 文档、细化查询并打开官方定位器文档的行为；代码按执行投影 从这份行为提取步骤，并使用 Playwright Test 的 fixture、断言和报告。

google-search/                          项目根目录
├── specs/stories/google-search.yaml    行为知识库：业务动作与期望
├── tests/e2e/                          本例的 Web 执行投影
│   ├── actions/google-search.ts        搜索、读取结果和打开文档的具体步骤
│   ├── flows/google-search.ts          runStory(page)：组装动作与断言
│   ├── google-search.spec.ts           运行入口：本地验证与真实站点用例
│   └── fixtures/google-search-seam.ts  本地验证桩，不是业务投影的必要部分
├── playwright.config.ts                测试发现、fixture 与浏览器配置
├── package.json / package-lock.json    依赖与运行命令
└── tsconfig.json                       类型检查配置

这是一种项目布局示例；实际目录沿目标项目已有约定选择。YAML 可以独立作为知识库保留， 本例选择 Web 流程不代表每份 YAML 都要生成 E2E 测试。组装代码与测试入口的文件注释都指向 源 YAML，动作和组装分别维护： 动作 → 组装 → 测试入口。这里没有为凑层级添加 feature、case 或 ref。

runStory 使用调用方传入的活 Page；导入业务模块不启动浏览器，也不关闭借入的页面。 调用者需在 Playwright Test 环境内调用，由原 owner 管理页面生命周期和起始条件。

第二次搜索是否刷新，以提交后观察到带该查询的成功主文档导航响应、当前文档 URL 和 搜索框值为依据。两次结果链接相同也可以继续；只有 URL、标题或旧列表变化不足以证明刷新。 若站点采用其他刷新方式而无法取得此证据，流程以 UNKNOWN 跳过；结果区域观察不足也跳过。 结果链接会等待出现；首次结果须有文档主题，官方域名本身不足以证明这一点。 跳过不是行为通过。Playwright 可能对包含跳过的测试返回退出码 0，必须同时查看报告。

运行

需要 Node 24、npm 和本机 Chrome。依赖由 lockfile 固定，锁定包来自公开 npm registry， 并使用锁文件中的 integrity 校验。以下命令在本目录（示例项目根）执行：

npm ci
npm run typecheck
npm test

默认测试中 tests/e2e/fixtures/google-search-seam.ts 拦截所有页面网络请求：Google 与 Playwright 文档由本地桩回填，其他请求 直接中止；真实 Google 用例默认跳过。RDT_CHANNEL 可选择其他已安装的 Playwright 浏览器通道。 在获得授权且 Google 可访问时，可用 RDT_REAL=1 npm test 运行真实入口；这会实际访问外站。

本轮证据

2026-10-27 实走中，首页和搜索框已观察，输入第一次查询并提交后 Google 返回 /sorry、 HTTP 429 验证页；未绕过验证。第一次结果期望、第二次搜索及文档页在真实站点均未观察。

本候选更新后，npm run typecheck 退出码 0；npm test 退出码 0，Playwright 报告 5 passed、3 skipped。五项本地测试分别验证：新的主文档响应后延迟出现相同链接仍能到达文档页； 只有 pushState、标题变化和旧列表新增链接时，不会认定有新搜索；官方域名的无关页面不会被 当作文档结果；同名的非目标链接排在前面时仍会打开已确认的官方文档；隐藏的官方结果排在可见 官方结果前面时仍能打开可见链接。两个本地未知路径和真实站点入口均被跳过。

本地桩仅证明这些受控接缝，不能证明真实 Google 结果页的结构、定位、刷新方式或文档断言。 本轮没有真实站点的完整代码回放，真实行为仍未验证。

公开依赖锁在独立临时目录使用空 npm 缓存执行 npm ci --ignore-scripts 验证，退出码 0， 安装了五个锁定包；它们的版本与 integrity 均与原候选一致。

从行为到可维护的执行投影

在 Agent 参与生成、更新或执行测试时读取。按目标失败选择单元、组件、集成或完整路径，再选择 确定代码、Agent 协作、人工或组合。Agent 介入不等于 GUI / E2E；生成后的确定测试沿原入口运行， 不强制每次调用模型。需要现场操作时，逻辑、API、CLI、Web、桌面与移动端沿各自真实入口实走， 具体工具按需读执行面与工具。统一的是方法与行为依据，不是驱动接口。

generate：生成或更新代码

调用 /risk-driven-testing generate <behavior-yaml> [output-directory] 时，执行本页的实走、记录、 提取与回放流程，交付代码，不停在实现建议、伪代码或一份新增 YAML。若已有对应投影，先查受影响 原子与消费者，再局部更新；未指定输出目录时沿目标项目已有测试布局，缺少约定时按项目位置指导 选择与保障层次相符的位置，不另建通用运行系统。

产物保留到源 YAML 的追溯，将原子操作与组装分开，给出实际运行入口或宿主接入位置、必要依赖与 运行方法，并明确实走、代码回放及未验证部分。文件命名、数量与语言按目标项目选择，不把示例目录 当成统一模板。代码中能确定判断的期望要有可失败检查，不能只把观察结果交回后宣称生成完成。

先复用目标项目已有的测试框架、驱动与执行入口，让框架处理其已有的资源准备、等待、断言和报告； 缺少合适入口时再选成熟工具。Web 需要新建测试入口时，优先使用 Playwright Test 的 fixture、 断言和报告，实走仍可用 playwright-cli。只为实际复用或局部更新提取动作，用普通测试函数组装； 不默认为每条用例另写状态聚合、报告器、退出码或通用执行框架。动作与组装的职责要清楚，不要求 一动作一文件。

生成代码应能直接读出实际步骤。Web 实走时可收集 playwright-cli 输出的等价 Playwright 代码， 核对定位器后作为动作素材；能确定判断的 YAML 期望在对应步骤附近加断言，其他可由 Agent 判读或 保留未验证，不能把动作输出当作断言。 优先用驱动提供的定位、等待与断言表达步骤，原生能力不足以观察期望时再写采集或轮询逻辑。 提取为 action 函数后，函数内部仍是按顺序执行的具体步骤，组装层调用动作并表达必要分支； 不为了原子化把步骤转成节点配置或复杂的观察、状态对象。需要 Agent 或 decision 时，只在对应 步骤调用实际可用的入口，周围仍用普通流程组装。

框架的失败、跳过和进程退出码未必对应本技能的行为失败、运行失败与未验证：检查现有报告的实际 表达与消费者，只在缺口影响本次使用时补最小接线。跳过、环境受阻或未观察的期望不能记为通过。 借用的资源仍由原 owner 管理；不同工具的同名会话或复制的认证状态不自动成为同一活实例。

验证这项操作是否能被 skill 独立指导时，由未参与本次 skill 修改的独立 Agent 调用。调用方提供 任务、YAML、授权范围与已有现场事实，不预设代码骨架、定位器或实现答案。执行 Agent 负责从操作到 代码与回放的完整工作；调用方验收产物，缺陷交回执行 Agent 修正，不代写实现后声称 skill 已被验证。 直接调用 skill 的执行 Agent 不必为此再套一层委派。

实走、记录、提取、新回放

1. 读相关行为 YAML、必要 ref 与现行合同，核对 context、expect、lookup；不因选单测就跳过有用 KB。查消费者、测试入口、准备与工具 能力，保留有效保障；期望来自原合同，不从当前界面反推。
2. 在真实被测面按用例实走：核对目标身份、角色、数据与起点，取当前观察后执行，核对原 expect。 工具缺能力、前提不成立或合同含糊时保留缺口，不换成它无法触及的替代证明。
3. 在本轮临时记录中保留有效动作、参数、定位策略、关键前后状态与最小必要证据。录制输出是 素材，不把探索死路、临时 ref、模型内部轨迹或整段原始 trace 固化为代码。仍需智能的部分 提炼目标、允许动作、有限候选与停止条件；凭据、token 和认证 state 内容不进入代码或日志。
4. 从有效步骤提取原子操作，用现有测试函数和普通控制流组装顺序、分支、数据与观察。无需按每步 建文件、固定一份用例一个入口，或另建节点 schema、驱动 registry 与跨端运行器。
5. 从成立的可重复前提实际运行生成代码，再核对原 expect。实走成功不等于代码回放成功。静态 检查、录制完成、工具调用成功与行为通过分别报告；受阻时可保留草案，不能称已经验证。

Google 搜索示例展示同一项目中行为 YAML、原子动作、组装与 测试入口的位置及追溯关系，并说明已观察部分和未验证候选。它展示投影的具体产物，不要求每份作为 KB 保存的 YAML 都生成代码或采用相同目录。

生成前区分实走 Agent 能用的工具与代码运行环境能调用的能力。action 必须落到运行环境可调用的 函数、CLI 或 API，并具备所需系统权限；不能把 Agent 内置 computer-use 工具名直接写成可执行动作。 只有 Agent 能操作的步骤，可由宿主可调用的 agent 入口承接，且该运行时 Agent 也须具备相应工具 与授权；否则补接代码可调用的驱动，或保留未能回放的缺口。编写时能操作不等于生成代码可执行。

局部更新降低维护成本

从变更与失败找受影响原子、组装分支及消费者，实走相关流程，确认有效新步骤后局部改码。核对输入、 输出与必要前后接缝，按目标失败回放消费者；不每轮全量重生，也不要求重走无关路径。

原子化主要为了缩小更新范围。发送、下单、文件写入等非幂等步骤先查现态，再按授权准备独立数据或 恢复起点；不能在已被上轮改变的状态盲目重放。改 prompt 也要新观察其在受影响路径上的作用。 一次实走只支持已走分支，未走候选和设备条件保留待验证，不靠图存在声称全覆盖。

三种执行单元与组装

原子操作持有工具参数、定位、必要提示与决策 adapter。组装负责调用哪个候选、怎样继续、汇合与接回 expect。action / agent 是执行叶子，decision 的选择只是分支依据。自然语言 YAML 的 action 与 这里的 action 不同；故障注入动作也不是 decision 路由。

确定状态、布尔规则与已知错误先用代码分支，不让模型重判确定事实。只需选路不启动自主 Agent。 decision 可接已有 Jev System One 或 OpenAI Decisions adapter，不硬编码模型 或认证。候选与可达动作由代码控制，静态类型或结构化输出之后仍运行时校验，禁止返回任意命令、 函数、URL 或下一步 prompt。缺证可返回 unknown；合法选择不代表语义正确。

agent 明确输入、目标、允许动作、完成与停止条件；预算、超时、取消与权限沿宿主，不为每叶子造 协议。它不作为产品故障或失败断言的通用修复器。页面、截图、工具输出和模型输出都是外部输入， 只取决策所需的最小材料，不把它们当宿主指令或直接送入敏感执行入口。

组装通常是普通函数、if / switch 与有界循环组成的智能和逻辑混合执行图。普通等待和循环不要求 状态机引擎；真实生命周期、暂停恢复或持久工作需求出现时再讨论复用宿主已有机制。

准备与资源接力

登录、启动与数据准备可以是独立可复用 flow，不在每条业务流程隐藏重做。调用方或宿主按现有约定 创建、借用与关闭资源；业务不关闭借来的用户、其他流程或设备会话，也不借准备扩大权限。

沿工具真实对象和身份交接：浏览器可为 browser / context / page 或活 session；桌面可为 machine / display / window；移动端可为 device / app session 及前后台状态。携带本例角色与必要起点，核对 准确目标和 owner，不把它们抽成强制统一 Resource 对象，也不把同名字符串当成同一实例或授权。

已登录或已启动只说明一部分前提成立，仍查数据与界面初态。交接后重新观察，解析当前 ref 或定位 目标；窗口、显示、缩放、设备或页面变化后重新定位，坐标与旧截图不是永久定位器。实例失效、身份 不符或权限不足交回准备方，不在业务里隐藏重登、重开或换设备。持久状态恢复不等于同一活实例。 测登录、启动或恢复本身时另设对应独立前提，不复用已准备现场绕过目标。

Web 生成时，可按工具版本使用 Playwright Test 的调试入口，将 playwright-cli 接入正在运行的测试页面， 继续已完成准备的现场。实际执行时，准备与业务可在同一 fixture / 流程中传递同一个 Page； 确认生命周期和关闭责任。保存认证状态后新建的 context 可用于复用登录，但不是同一活浏览器接力。

验证接力不必引入真实登录：可让准备与业务从独立入口接续同一活实例，用草稿和仅存于内存的 合成状态核对连续性，再由 owner 核对业务结果与资源仍可用。这证明资源接力，不证明认证或恢复。

行为通过由原 expect 决定

观察独立于动作的“已完成”声明，不要求第二个 Agent 或模型；结构化状态、进程结果、持久副作用、 无障碍树或当前截图按目标失败选用。Agent 自报成功、录制完成或 decision 输出合法都不能代替断言。

能确定判断的 expect 优先由生成代码中的可失败检查承接，并传到现有执行入口的失败结果；返回 FAIL 字符串但进程仍成功退出不算断言成立。不只返回观察值再依赖 Agent 逐次判定。 输入与观察要能区分目标失败：例如普通文本无法区分文本显示与 HTML 解析，可用含标记的合成输入 核对是否原样显示。怀疑断言无效时，可在授权范围用最小受控反例验证，再恢复并复测；不要求每条 用例都增加故障注入。

• unknown / 未完成：观察不足或目标歧义。按缺口补取授权观察再判断，仍不足保留未决；不能 记绿，也不凭未知认定产品缺陷。测试入口显式处理未决，不能把正常函数返回当成功。
• 运行失败：工具、环境、provider、超时或输出校验失败。保留错误类别，接现有异常与报告入口， 不伪装为 unknown 后静默换路或重复调用直到碰巧成功。
• 行为失败：有效观察未满足原 expect。查环境、投影漂移、产品缺陷或语义变化；不能让 Agent 补做产品应自动完成的动作、改宽断言或换容易通过的路径。

例如同一应用允许列表打开联系人或搜索打开联系人，decision 可以选择受支持入口，action 或 agent 分别执行，两路都汇合到“正确联系人会话已打开且可输入”的观察。自动重发若是合同，则不能另选 手工重发来证明通过。更新继续沿原触发条件验证，连续复测与恢复读测试接续。

按被测面选择真实工具

只在生成或维护对应执行投影时读取。先问目标失败能从哪里被观察，再核对当前工具与宿主能力； 不因某工具可截图就用它证明所有平台。这里不定义统一驱动接口、端列表 registry 或跨端执行器。

逻辑、API 与 CLI

规则、协议、进程退出与文件副作用沿已有测试函数、客户端或真实进程入口验证。GUI 不能替代这些 边界，mock 也不证明外部接合成立。参数用结构化调用或 executable + argv，不拼接 shell 字符串； 外部数据先验证，回执不明确先查现态，再决定是否重试。

Web：默认 playwright-cli

用 playwright-cli 实走、更新与回放，复用项目已有启动入口、账号准备及 fixture，不另开浏览器绕过 setup，也不要求新增 Playwright Test。每次有效操作的 Ran Playwright code 可作 TypeScript 素材； 用 generate-locator 从当前 ref 提取并核对语义定位器。按行为 YAML 的 expect 补断言，不能把当前 UI 自动升为正确合同。官方代码生成指南 只提供工具用法，不改变凭据、行为期望或授权边界。

准备方已在活会话 chat-user 完成登录并保持开启时，后续可取新观察：

playwright-cli -s=chat-user snapshot

后续动作继续指定同一 -s，核对当前 page 与本例起点，重新解析 ref。CLI 原子动作可以是 executable playwright-cli 与 argv [`-s=${session}`, "click", currentRef]；也可以由已有运行 入口调用接收当前 page 的普通 Playwright 函数。run-code --filename 载入按 CLI 合同包装的 JS 函数片段，不直接运行任意导出 TS 模块或完整 spec；多动作片段属于 flow 或组装，不因单次调用 就成为一次原子 action。agent 的自主浏览器操作也绑定同一会话，decision 只选路。

命名会话复用活实例；state-save / state-load 或持久 profile 只恢复其支持的状态，不等于活浏览器、内存和在途流程。借用已有浏览器前核对 attach 与 open 参数、context / page 身份及 owner；attach 借用结束时 detach，不 close 用户或其他流程持有的浏览器。

跨流程接力同时明确工作与产物目录。已有 session 的输出位置可能仍沿创建时的目录，不能假定 更换命令 cwd 就会迁移默认快照等临时产物；复用时核实实际位置，工具支持时显式指定输出路径。

Desktop：准备 Cua Driver，再验证目标应用

桌面验证要核对 machine、display、应用与 window 身份，权限、前台焦点、缩放和屏幕变化都会影响 动作。当前截图、坐标与录制仅是现场素材，状态变化后重新观察定位；不能把浏览器页面通过当成 原生窗口、系统对话框或设备接合通过。

按 YAML 的 expect 选择 AX 或截图证据。纯文本结果若已由同一窗口的 AX 暴露，可读取独立输出并 区分输入回显与执行结果；截图不作为所有动作的前置条件。Cua Driver 的 get_window_state 传 include_screenshot:false 且不传 screenshot_out_file 可仅取 AX；缺少截图只在当前验证确实需要 像素证据时才构成阻断。参数与行为按已装版本核对，见 0.38 观察合同。

发送全局快捷键前核对系统当前前台应用与目标窗口；查询某应用的第一个窗口，不代表系统焦点已在 该应用。焦点不符先纠正并重新观察，不能用无变化的窗口数推断快捷键没有影响其他应用。

桌面操作默认准备代码也可调用的 Cua Driver。先查现有安装、版本与服务；缺失时读取 官方 Quickstart，按当前平台安装并启动，把这部分作为 测试环境准备，不因 PATH 没有命令就停止，也不先退回全局键鼠脚本。已有安装可用则复用，不要求 每轮重装。区分 Cua Driver 与 Cua Spaces、Lume、SDK，按本次所需安装，不默认拉起整套产品。

沿官方文档与已装版本核对 permissions status、status、doctor 和目标应用发现；安装成功或 健康命令 exit 0 都不代替阅读实际警告与验证目标能力。macOS 权限须归于实际安装的 CuaDriver 应用；启动与重启沿官方应用入口，不用 shell 后台直接运行 bundle 内二进制代替，并核对实际宿主 归属。需要用户完成系统授权时说明准确对象与实际缺项，不通过其他已授权宿主冒用权限。安装与 运行沿本次授权，系统授权仍由系统实际授予。仅 localize 或编辑指导时不据此启动环境安装。 用户已确认完成授权而实际调用仍拒绝时，核对当前版本、进程归属和本轮真实回执，按需查官方 已知问题；未能解释的矛盾保留为环境或工具状态不一致，不反复要求用户完成同一项授权。

本机可先验证 Cua 对目标应用的后台输入与观察，核对实际用户指针、前台焦点和应用结果；不凭 agent cursor 或工具成功推断没有干扰。需要前台输入或后台路线拒绝时，再选择独立测试机器、 虚拟机或约定的占用时段，不静默切换到全局输入。独立窗口、进程与 session label 都不自动构成隔离。 后台建窗与读取成功不代表该窗口已有可用输入焦点；准备后分别核对定向输入和关闭能力。按实际 回执区分执行与拒绝，不因权限齐备或健康检查通过就宣称完整场景可回放。 Cua CLI 各工具回执按实际合同解析，不能对所有 call 统一 JSON.parse：观察工具可返回 JSON， kill_app 可返回文本成功回执。

不把 osascript + System Events / Accessibility 作为默认替代路线：它可能作用于共享前台与输入， 一次回放成功不代表低干扰或稳定。确需本机共享桌面操作时，先与用户明确操作范围及占用时段。 Agent 内置工具的可用性不代表独立脚本可调用；按执行投影核对实走与回放 两端能力。安装失败、系统权限不足和目标应用不支持后台操作分别处理，保留具体缺口。

输入参数通过 JSON 序列化构造，先检查真实字符串与 LF、CR、TAB 等控制字符；一次拆行不足以 推断 Driver 解释了反斜杠转义或存在相应缺陷。在选定的测试环境中，键盘输入仍可能受活动输入法 改写，须核对实际输入和结果。若借助剪贴板，先保全原状态且不暴露内容，在成功与失败出口恢复； 清空不等于恢复。操作与清理绑定本轮创建的窗口，现场坐标不固化为永久身份。

trycua 的当前桌面工具以 Cua Driver 为入口，CLI / MCP 提供观察和动作。已有 recording / replay 能力也不等于稳定代码生成：轨迹可能依赖当前元素缓存，元素 token 不能跨 snapshot / session 永久复用，录制结果须筛选后提取投影并新回放。具体能力与平台条件见官方材料，按当前安装版本 核对，不把其他产品的 computer-use 工具接口冒认为 trycua API。

参考 Cua Driver 0.38 发布与 录制 / 回放工具合同。 官方支持路线与目标环境可用性分开核对；先查实际安装、系统授权与宿主条件，只有实际观察才支持 对应桌面路径已验证的结论。

macOS 本机路线要核对 CuaDriver.app 或 embedding 的进程身份与系统授权， 不以任意 CLI 进程替代已授权宿主。Driver 的 session label 须沿同一 daemon 使用，它不隔离应用焦点、缓存或权限；结束本轮 session 不等于停止共享服务。

Mobile：按实际设备与工具能力选择

核对 OS、真机或模拟器、device、app session、前后台与输入状态；沿项目当前可用工具实走与回放。 模拟器通过不代表真机、硬件或系统权限已验证，桌面远控能力不自动成为手机原生 app 自动化能力。 未确认工具支持时保留缺口，不用桌面截图、移动网页或 iPhone 遥控桌面的客户端代替 iOS / Android 原生行为证据。登录与资源接力仍沿设备和 app 的真实身份、权限与 owner，不强制套浏览器 context。

Cua 仓库有 Android 模拟器与 ADB 路线，见 Android runtime与 本地模拟器集成入口。 这些代码不证明目标设备已跑通，也不推导 Android 真机或 iOS 原生 app 支持。需要专用手机驱动时， 可核对 Appium UiAutomator2的 Android 真机 / 模拟器路线，或 XCUITest的 iOS 真机 / simulator 路线；目标 OS、设备、Xcode / WDA、签名和权限条件以当前工具合同为准。

项目本地化

仅在选择 localize [target-project] 时使用。产物是目标项目独立维护、后续 Agent 可直接使用的 测试判断方法及必要发现路由。本模式只改指导，不改产品、测试或 CI，不运行测试、安装依赖、 提交或发布。命令定义检查与运行证明分开。

找到影响项目取舍的事实

确认指定路径或当前路径的项目根、适用指令和已有改动。路径无法确定目标时只澄清该问题。 先沿实际 Agent 入口、技能索引和相关模块指导，找到现有测试策略归属、技能目录惯例及执行 交接方式。职责匹配才合并；运行诊断或视觉验收技能仍由原 owner 负责，多轮验证接续沿用 现有工作记录和必要方法，不因适配策略新建平行流程。

从本次适配涉及的真实变化、合同或已知故障找出需要判断的失败，再按判断所需读测试、配置、 脚本、CI 或模块文档。例如，已有逻辑测试能否触及客户端接线，要看实际调用与测试边界； 不能仅按技术栈名推断。阅读服务于这些选择，不要求全仓 inventory，也不为每个模块编造风险。 尚无测试规范时，从已知输入输出、退出码、副作用等实际合同建立最小判断，未知保持未知。

核实会让后续 Agent 行动的具体位置：期望依据和现有用例在哪里、相关验证命令如何定义、 从哪个目录运行、需要什么环境与权限、证据通常落在哪里。配置存在只说明有定义，不说明 可运行。缺命令、缺环境或无现行记录方式时明确指出，不用示例命令或虚构流程填空。

把事实写成项目方法

用项目事实实例化主技能的保障比较，形成后续变化仍可使用的取舍理由，而非复制通用规则后 附一张工具表。说明本项目哪些失败通常由现有保障揭露，什么接合或条件容易遗漏，何时维持、 修复、补充、替换或暂缓；将漏检后果、诊断和维护负担一起纳入理由。无需凑齐所有结论。 已有权威文档包含有效判断时直接引用，把新增判断放在缺口处。

例如，若检查确认 CLI 逻辑测试覆盖参数规则，却没有观察真实进程退出码与文件写入， 本地方法应说明何种变化复用逻辑测试、何种变化需要进程边界观察，以及当前未覆盖什么。 这只是适配思路，不能写成目标项目已有这些测试或命令。对没有成熟流程的项目，给出基于 实际位置的最小行动路径；不创建行为库、CI 门禁或成熟工作流的假象。

将必要保障接在对应选择上：项目要求的精确协议或文本、替身隔离、各客户端集成观察，不能 因看似脆弱或重复被抹去；已有分级、覆盖目标和发布条件保留其效力与依据。源项目的门槛与 工具偏好不自动成为目标约束，通用方法也不构成禁止合理本地约束的理由。

本地方法须使后续 Agent 能找到稳定的期望依据，并据实际行为区分测试漂移、产品缺陷与 经授权的语义变化；不能一见定位失败就修到绿。按实际需要保留行为说明到自动化、回放或 知识复用的关系，说明实际观察才支持通过结论。清理继续比较保障与替代，不另建治理流程。 对暂缓或受阻部分写清失败窗口、理由与重议条件。

将所选观察与已核实的路径、命令、运行目录、参数、环境前提及结果位置接在一起，必要细节 可放本地 reference。标明命令仅检查过定义，或准确引用已有运行证据。后续已授权补测、修复 和复测要交到实际执行入口；没有专用工作流时说明按正常开发推进，不让策略职责成为停工理由。 费用、真实数据、副作用、服务启动和人工观察等边界沿用目标指令。

需要行为库或投影维护时，按目标项目实际需要吸收相应方法与资源，保留既有逻辑、API、CLI 与 各端观察的分工。工具细节只接入已核实的目标能力；Web、桌面与移动端不强制套同一驱动接口。 本模式可检查命令定义与会话身份约定，但不因执行投影包含实走步骤就启动产品、设备、虚拟机或模型。

写入可独立维护的载体

优先定向合并职责匹配的本地技能。没有匹配项时，沿用项目目录与命名习惯创建专用技能； 本地技能须使用可区分于通用技能的名称；在可行范围内核对项目已有技能及当前可用通用技能 的名称，发生同名冲突时选择带项目限定的名称，不按路径顺序静默覆盖。若连技能目录也没有， 且宿主没有其他约定，可在 project-testing 未被占用时创建 .agents/skills/project-testing/SKILL.md，配所需的本地 references。采用宿主要求的 frontmatter，确保其中的 name 与技能目录名一致；没有额外约定时至少写明名称、触发 与职责边界。实际落地后使用真实路径，不留下骨架或占位项。

本地技能应包含可行动的项目取舍、期望维护方法和执行接续关系。必要方法与资源随产物提供， 不能只是“先读通用技能”的 wrapper；隐藏通用来源后仍须可用。来源可作简短说明，不能成为 安装、访问或运行依赖，也不要求出现源项目名称。本地版本由项目维护，无强制同步关系； 候选判断保留候选状态，不因生成文件宣称成熟。不将这次静态审查的过程史写进长期方法。

按职责合并并接入实际发现路径

重跑先读当前本地技能、references、发现入口及人工修改，对照此次来源变化和项目依据， 只合并有依据的部分，不整份覆盖或重置，也不另建重复策略技能。保留有效的项目决定； 冲突无法消解时保留现状，具体报告双方依据与未合并部分，继续完成独立确定的部分。 只有影响取舍且必须由用户决定的冲突才提问。

沿现有发现链添加或更新最小触发与本地链接：根入口已路由到索引时更新对应索引即可。 多个实际宿主消费者确实各有入口时，维护它们必要的路由，不能为了“唯一入口”留下失联 消费者；也不把方法正文复制到各入口或创建所有宿主配置。完全没有发现入口时，创建只含 必要触发与技能链接的最小根 AGENTS.md。保留无关指导及其他技能职责。

静态交付

核对实际变更范围、frontmatter、触发与发现链，以及新增或修改的相对资源链接能否从所在 文件解析。检查引用命令的定义、目录与参数，清掉未填骨架、占位路径和虚构命令；必要未知 明确保留。在 Git 项目核对 status、diff 和空白错误，保留无关工作。本模式不执行所引用的 产品或测试验证命令来证明适配有效，也不自动做测试或产品改动；上述 Git 与链接等静态检查 仍须完成。

交还生成或合并的文件与发现入口、支撑项目取舍的依据、保留的本地决定和冲突、静态检查 及剩余未知。明确指导适配不等于命令运行、测试通过或技能激活效果得到验证。

多轮验证与中断接续

在用户要求充分验证、反复测试，或需要恢复未完成验证时读取。这里组织证据与下一步， 不替代项目的运行诊断、行为评价或视觉观察方法。单次命令检查无需启动多轮流程。

保留一份可接续的工作记录

先沿用户目标、适用项目指令与现行合同确定范围、完成依据和允许的替代做法。复用本轮已有 记录；没有记录时按项目惯例保留最小工作记录，不强制目录、模板、永久台账或执行器。 记下实际版本及未提交差异、环境、工具能力、授权和预算，后续变化写在同一记录中。

条目对应一个可核对的验证问题，可引用现有用例及相关分支。覆盖与本次风险有关的正常路径、 边界、变更、失败、并发、恢复和跨模块接合，不把所有理论窗口都变成必跑矩阵。用户要求 全量时覆盖所声明的完整范围；范围改变应保留理由，不能静默缩成抽样。

如使用勾选，勾选表示已满足本次验证目标且有依据，不只是命令执行过。未执行、期望 未满足、等待复测或缺少必要观察的条目保持未勾选，记录事实、证据与下一步。 确实不适用的分支单列原因；缺环境、能力、授权或预算是待测或受阻，不能改成“不适用” 并宣称全量完成。可选优化不阻止满足目标的条目完成，但应与必要缺口区分。

例如，下面只是记录方式，不是实测结果：

验证目标：保存被拒时不写入，并保留用户草稿。
条件：实际代码版本、未提交差异、环境与授权见本轮记录。

- [x] 无写权限保存：第1轮观察到拒绝且无持久写入，证据见对应请求与文件检查。
- [ ] 拒绝后的草稿：第1轮草稿丢失；修复后待按原输入复测，并核对正常保存仍可用。

续接：保留原输入与差异；先核对未决保存请求，再继续草稿复测。

沿原触发条件复验

沿正常入口执行，独立核对产物与原始事实，记录实际版本、条件、结果和证据。 确定性合同可以明确通过或失败；开放行为保留文字评价，接受符合目标的合理路径。 运行完成、结果正确与用户收到交付分别核实；不以一个程序状态代替其他结论。

出现偏差时先核实触发、影响、责任与反例，区分环境问题、实现缺陷、合理取舍和改进机会。 按授权修复，保留原观察；修复及复测另记，不能用放宽权限、删除数据、换资料身份或改变 必要期望制造通过。建议不自动成为代码改动或新增门禁。

下一轮应回答仍未解决的问题，覆盖原触发条件、改动影响的消费者与关键接合，并核对正常 行为。说明哪些条件变化、旧证据哪些仍适用；没有新变化或未决风险时不机械重跑全部检查。 需要新场景检验迁移时，保留它与原场景复测的区别。

随机表现需要与本次结论相称的重复和场景变化，不能凭一次碰巧成功关闭反复出现的问题， 也不规定统一轮数或反复抽样只保留成功样本。结论限定在实际观察范围内。 代码存在或一条路径通过不代表所有端、角色和候选分支已验证。

中断后先查状态，再行动

中断前保存已观察结果、有效产物、当前版本、现场与原工作定位、未知回执、待复测项和 下一步；涉及浏览器、桌面或设备时保留准确资源身份与 owner。只停止或清理属于本轮且已确认 可清理的资源，保留核对和恢复所需材料，不把原始私密内容复制进长期记录。

恢复时先核对同一记录、版本、资料、授权、服务、设备和未决执行。未知提交或在途工作沿原身份 查明现状，不能先重跑制造重复副作用。已有产物不等于用户已收到，日志已保存也不等于 恢复已验证。仅重开被实际变化影响的已完成项；发现原证据不足或勾选错误时，同样重开并 保留更正原因。

必要前提缺失、预算耗尽或用户中断时，留下未完成项及原因，继续不依赖它们的工作。 “测试直到通过”不授予额外费用、外发、部署或不可逆操作权限。

收尾逐项核对声明范围、必要整体路径与证据，满足全部适用目标后才报告本轮完成；其余 报告为部分完成或受阻。交还实际环境、主要观察、修复与复测、剩余限制和记录位置。