@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.b2f659e → 0.1.0-dev.c8cc2b5

package/miaoda-modern/testing-guide/SKILL.md

@@ -1,218 +0,0 @@
----
-name: testing-guide
-description: 派发 E2E 子 agent（Task subagent_type="E2E"）前**必读**——无论是用户主动要求，还是 agent 自行决定要测/复验功能，不能仅凭用户字面要求就直接派发。Also use when user wants to check, verify, or troubleshoot application functionality via browser. 触发词：检查页面, 看看有没有问题, 走一遍流程, 帮我看看, 试一下, 哪里出问题了, XX不好使, 检查一下, 测一下, 派发 E2E, 打开浏览器测, 验收功能
-steering: true
-steering-topic: testing
-gate-tools:
-  - tool: task
-    when:
-      subagent_type: E2E
----
-
-# 检查与验证：工具选择指南
-
-根据用户意图选择正确的派遣方式：派遣 E2E 子 agent（通过 `Task(subagent_type="E2E")` 打开浏览器操作一遍）或调用 `api_request`（直接请求后端接口）。
-
-## 用户沟通规范
-
-与用户沟通时，**禁止**出现 "E2E" / "端到端测试" / "E2E agent" 等术语。E2E agent 的定义就是「用浏览器替你实际操作应用，验收功能是否正常、排查页面问题」——对外直接说这个意思即可：
-
-| 禁止 | 改用 |
-|------|------|
-| E2E、端到端测试 | 浏览器测试、浏览器操作 |
-| E2E agent、派遣 E2E | 无需提及 agent，直接说"我用浏览器帮你..." |
-
-## 决策规则
-
-```
-用户想确认应用是否正常
-  ├─ 明确要求验证「后端接口」「API 返回值」「请求响应」 → api_request
-  └─ 其他所有情况 → Task(subagent_type="E2E")（打开浏览器，以用户视角操作应用）
-                  ├─ 只看视觉（白屏/布局/样式/文案）→ agent_options.mode: "lite"
-                  └─ 涉及交互/业务流程/数据 → 不传或 agent_options.mode: "standard"
-```
-
-- **模糊需求一律派遣 E2E**：未明确提到「接口」「API」「后端」时必须派遣 E2E，不要主动选择 `api_request`
-- **`api_request` 仅限显式请求**：仅当明确提到接口 / API / 后端 / 请求 / 响应、且意图是验证接口逻辑而非页面功能时才使用
-- **E2E 结束后禁止追加 `api_request`**：浏览器操作的结果即为最终结果，**严禁**再自动补充验证
-
-### E2E 的 mode 选择
-
-通过 `agent_options.mode` 指定，**可选参数**，不传或非 `lite` 一律按 `standard` 处理：
-
-| mode | 适用场景 | 行为 | 总超时 | 录屏 |
-|------|---------|------|-------|------|
-| `standard`（缺省） | 涉及业务流程、数据流、交互后状态变化 | 完整交互（点击/输入/滚动/提交）+ Network 验证 + 录制 | 5 分钟 | ✅ |
-| `lite` | 只看视觉渲染（CSS/布局/文案/图标）或快速冒烟 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`，**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
-
-**仅改 CSS / 文案 / 图标 / 布局**（无事件处理、无状态、无数据获取）应直接选 `lite`——更快且 token 消耗显著低，不要默认走 standard 浪费配额；但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。testRequirements 里出现"点击"、"填写"、"提交"等动词，**禁止** `lite`，必须 `standard`。
-
-## 工具选择速查表
-
-| 用户表达 | 选择 | 原因 |
-| --- | --- | --- |
-| "检查一下页面" / "看看有没有问题" / "走一遍流程" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E（standard） | 打开浏览器以用户视角操作 / 复现 |
-| "刚改了 CSS，看看样式对不对" | E2E（lite） | 仅视觉巡检，省时省 token |
-| "测试一下这个接口的返回值对不对" / "调一下后端 API 看看响应" | `api_request` | 明确指定接口验证 |
-
-## 派遣 E2E 时的 prompt / 用例规范
-
-`prompt` 不是一句话需求，而是一份**结构化验收脚本**。Case 越具体结果越可信；含糊需求只会让 agent 瞎点一通。
-
-> **核心原则：agent 只「机械执行 + 报判断」，不做推理。** 判定标准全写死在断言里——别让它自己推断"该测什么"或定义"什么算正常 / 好看"。它的活只有：执行动作 → 看现象 → 报通过 / 不通过。
-
-### 调用结构
-
-```js
-task({
-  subagent_type: "E2E",
-  agent_options: { mode: "standard" }, // standard=可点击/输入，lite=只截图
-  description: "验收创作工具",        // 一句话任务名
-  prompt: `
-    对<被测应用一句话描述>进行端到端验收测试。
-
-    ## 应用结构
-    - <页面名> (<路由>) — <布局/职责>
-    - ...
-
-    ## 测试用例
-    ### Case 1: <页面/模块> - <场景>
-    1. <动作步>
-    2. 断言：<可观察现象>
-    ...
-  `,
-  // ...其他参数：按 Task 工具的实际签名如实补全，别只填上面示例里的字段
-})
-```
-
-### prompt 三段式
-
-| 段落 | 内容 | 作用 |
-|------|------|------|
-| 概述 | 一句话说明被测应用是什么 | 让 agent 建立全局认知 |
-| `## 应用结构` | 每个页面的路由 + 布局/职责 | 告诉 agent 去哪、看什么 |
-| `## 测试用例` | 多个 Case，每个含编号步骤 | agent 逐条执行并断言 |
-
-### Case 编写规则
-
-- **标题**：`### Case N: <模块> - <场景>`，一个 Case 一个独立场景
-- **动作步 / 断言步交替**：动作步动词开头（访问 / 点击 / 输入 / 切换）；断言步以「断言：」开头
-- **可定位 + 二元判定**：动作指到具体对象（可见文本，如「发布新帖」按钮）；断言给非黑即白判据（出现 / 消失 / 等于 / ≥N / 含某文案），不写"正常""是否合理 / 美观"（见下方对照）
-- **独立可重入**：删除 / 提交等副作用操作走「取消」或验证后还原，不污染后续 Case
-
-### Case 复杂度约束（必跑到终态）
-
-每个 Case 必须**跑到最终可观测结果**，「打开弹窗 / 看到字段 / 按钮存在」都只是中间态，不算验证。
-
-- **跑到终态**：提交后出现在列表 / 跳转后内容正确 / 删除后从列表消失
-- **AI 功能看到输出**：翻译 / 摘要 / 生成等核心卖点，须断言到 AI 产出的内容，不停在"AI 弹窗打开"
-- **主链路 + AI 都覆盖**，不因"非主链路"遗漏
-- **Case ≤ 10**：过多会 token 膨胀、超时
-- **不碰登录 / 认证**：应用无登录逻辑，禁止登录 / 注册 / OAuth / CAPTCHA 相关 Case
-
-| ❌ 停在中间状态 | ✅ 跑到最终结果 |
-|------|------|
-| 打开预约弹窗，验证表单字段 | 填写表单全部字段并提交，预约出现在管理列表中 |
-| 验证翻译弹窗是否正常打开 | 点翻译选目标语言确认，内容区域显示翻译后的文本 |
-| 删除确认对话框是否出现 | 点确认后，记录从列表中消失 |
-| 验证课程信息"完整"展示 | 详情页显示课程名、章节列表、≥1 条学员案例 |
-
-### 断言可观察化对照
-
-| ❌ 含糊（agent 无法核对） | ✅ 可观察 |
-|------|------|
-| "页面正常加载" | "页面包含「创作配置」标题" |
-| "按钮可用" | "「一键生成」按钮处于可点击态" |
-| "跳转成功" | "URL 变为 /materials" |
-| "有数据" | "表格中至少展示 3 行数据" |
-| "弹窗出现" | "弹出详情弹窗，展示标题、正文、配图" |
-| "样式好看" | "卡片使用圆角 + 微投影，整体为暖色调" |
-
-### 断言要查到信号层（最易漏检，必读）
-
-UI 快照「看起来正常」是最大假阴来源——接口 500、图片 404、失败 toast 都不一定改变页面结构。功能 / 资源类 Case 的断言**必须落到 network / console**，不能只靠无障碍快照或截图：
-
-| 漏检模式 | 错误做法 | 正确断言 |
-|------|------|------|
-| 接口报错（提交 / 生成 / 翻译失败） | 看到表单还在、按钮在就判过 | 触发后断言关键接口（尤其 `/api/capability/*` 等业务 / 能力接口）响应码，**非 2xx（4xx/5xx）即 failed** |
-| 图片 / 静态资源 404 | 无障碍快照有 `image` 节点就判过 | 404 的 `<img>` 仍是 image 节点——**必须查 network 该资源非 404，或截图确认像素真渲染** |
-| 失败 toast / 空结果 / 错误兜底 | 没撞见失败 toast 就判过 | 空结果 / 错误兜底 UI / 白屏是**常驻态**，出现即判 failed；失败 toast 瞬时易漏，**撞见可判挂、漏看≠通过**——失败的权威判据是上一行的 network 响应码（非 2xx 即 failed） |
-
-**核心动作必须真正触发到终态**：验证某功能 = 实际点击触发按钮（提交 / 生成 / 翻译 / 上传）并等待结果；只验「表单能填 / 按钮存在 / 弹窗打开」就判过 = 根本没测到该功能，必然漏报。
-
-### 禁止编写工具能力外的 Case（否则只会产生「假失败」）
-
-E2E agent 只在离散时刻抓快照 / 截图，**看不到瞬时过程、不逐帧解析动画、不能在导航前改写流量**。下列现象超出工具能力，写成断言只会被报成"失败（工具能力限制）"——属于无效 Case，**从源头就不要写**：
-
-| ❌ 工具看不到的现象 | 为什么看不到 | ✅ 改成可观察的终态断言 |
-|------|------|------|
-| 骨架屏 / loading 占位符 | 它是过场态，本就不该当验证目标——数据回来就消失，根本不要去看它 | 直接断言加载完成后的真实内容出现（内容在 = 加载链路通） |
-| toast / 轻提示一闪而过（"提交成功""已复制"） | 几秒自动消失，离散快照常错过 | 改断它代表的**真实结果**（记录进列表 / 状态切换），权威判据是 network 响应码（非 2xx 即 failed）；无明显终态时用 network 调用或重载后持久态代替，**绝不把 toast 当断言对象** |
-| CSS 动画 / 过渡 / 滚动是否"流畅""有动效" | 截图是静态帧，不逐帧评估动画播放 | 断言动画**结束后的状态**（元素已展开 / 已隐藏 / 已就位） |
-| 靠拦截 / mock 网络返回来造错误（如"让接口返回 500 看兜底"） | 工具不能在页面加载前注入拦截或改写响应 | 只验真实响应；要看错误兜底需后端真异常或用真实异常数据，不靠伪造流量 |
-
-断言对象若是瞬时中间态 / toast 本身 / 动效本身 / 需伪造网络的分支——改写成稳定终态断言，或直接删掉。
-
-### 建议覆盖维度
-
-覆盖维度（按实际功能裁剪）：
-
-| 维度 | 典型 Case |
-|------|-----------|
-| 页面加载 / 初始空状态 | 打开后标题、表单、空状态引导文案是否就位 |
-| 表单交互 / 输入校验 | 输入前按钮禁用 → 输入后变可点击；选择器值更新 |
-| 导航切换 | 点击 tab → URL 变化 → 内容正确 → 可返回 |
-| 详情查看 | 点击查看 → 弹窗展示内容 → 关闭 → 回到列表 |
-| 危险操作确认 | 点击删除 → 确认弹窗 → 点取消 → 记录未删除 |
-| AI 功能（核心卖点） | 触发翻译 / 摘要 / 智能生成 → 断言 AI 实际输出的内容出现 |
-| 视觉一致性 | 配色、圆角/投影、响应式单列堆叠 |
-
-## E2E 轮数与复测策略
-
-E2E 派遣是**昂贵操作**（每次消耗大量 token + 时间）。E2E agent 只负责暴露问题，**不负责定位根因**。
-
-**每次任务执行**的 E2E 总派遣上限 **3 轮**（同一应用内多次任务分别计算）：
-
-| 轮次 | testRequirements 内容 | 说明 |
-|------|----------------------|------|
-| 第 1 轮 | spec 验收任务的全量 Case（≤5 个） | 首次全面验收 |
-| 第 2 轮 | 上一轮 failed + 未完成的 Case | 定向复测，**不要重新生成全量 testRequirements** |
-| 第 3 轮 | 上一轮仍 failed 的 Case | 最后一次机会 |
-| 第 4 轮起 | 禁止再派遣 E2E | 转为根因分析模式 |
-
-**定向复测规则**：
-- 已通过的 Case 最多复测 1 次：担心修复引入回归时可纳入复测，同一 Case 累计通过 2 次后不再纳入
-- 如果上一轮因超时中断，E2E 会返回"已测通过/已测失败/未测"三组——已测通过的结果可信不需重测，只测"失败"和"未测"的
-
-**白屏 / 整页打不开 → 复测前先重启 devServer**：白屏多为 **devServer 编译挂死 / HMR 卡住**，非代码 bug，直接再派只会重复白屏、白吃一轮配额。顺序：**① 重启 devServer → ② 查编译输出 / runtime-log 确认无报错（不派 E2E）→ ③ 再正常复测**；真要肉眼确认用 `lite` 截图，别用 standard 探活。
-
-**测试范围**：首轮（spec 验收）总 Case **≤ 5**（单次派发上限 ≤10 见 Case 复杂度约束），一行一个 Case，必须含主链路流程测试。禁止测试有真实副作用的功能（发送飞书消息、飞书建群）。
-
-**停止派遣 E2E 的触发条件**（满足任一即停止）：
-
-| 条件 | 说明 |
-|------|------|
-| 已派遣 ≥ 3 轮 | 硬上限 |
-| 同一 Case **未经代码修改**连续失败 ≥ 2 次 | 修复后重试不算连续 |
-| 本次错误信息与上次完全一致 | 说明修复未命中根因 |
-
-达到上限后仍有 failed：在 commit_task 结果中标注未通过的 Case，继续推进后续任务。
-
-**停止后的行动**（按优先级执行）：
-
-1. **查后端日志**：若涉及数据/接口错误，用日志查询工具排查 traceid / 服务端日志
-2. **直接读代码**：根据 E2E 报告的 URL 和 problem 定位源文件，人工分析根因
-3. **重启 dev server**：白屏 / 打不开时按上方「白屏 → 复测前先重启 devServer」流程处理
-4. **告知用户**：列出已尝试的修复 + 失败现象，请求补充上下文
-
-## Common Mistakes
-
-| 错误                                  | 正确做法                              |
-| ------------------------------------- | ------------------------------------- |
-| 用户说"测一下"就调 `api_request`      | 默认派遣 E2E（打开浏览器操作）        |
-| E2E 完成后又调 `api_request` 补充验证 | 浏览器操作结果即为最终结果，不追加    |
-| 用户说"看看有没有 bug"就同时调两个    | 只派遣 E2E                            |
-| 用户说"检查接口"时派遣 E2E            | 明确提到接口时用 `api_request`        |
-| 仅改 CSS / 文案，仍走 `standard`      | 优先用 `lite`，速度快、token 消耗低   |
-| 达到停止条件（≥3 轮 / 同一错误未改代码连续失败）仍继续派 E2E | 停止派遣，转为根因分析（读代码 / 查日志） |
-| 复测时全量重测 / 白屏直接再派一轮 | 只传 failed + 未完成的 Case；白屏先重启 devServer 再复测 |