@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.7b2c2ad → 0.1.0-dev.7cbbb20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/miaoda/charts-skill/SKILL.md +1 -1
  2. package/miaoda/creative-to-fullstack/SKILL.md +38 -226
  3. package/miaoda/debug-investigation/SKILL.md +17 -8
  4. package/miaoda/feishu/SKILL.md +4 -4
  5. package/miaoda/forms-skill/SKILL.md +46 -4
  6. package/miaoda/lark-apps-db/SKILL.md +12 -4
  7. package/miaoda/lark-apps-db/references/full-reference.md +13 -4
  8. package/miaoda/lark-apps-ops/SKILL.md +2 -1
  9. package/miaoda/lark-apps-ops/references/lark-apps-export.md +46 -0
  10. package/miaoda/lark-design-prototype/DESIGN.md +603 -0
  11. package/miaoda/lark-design-prototype/SKILL.md +85 -0
  12. package/miaoda/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
  13. package/miaoda/lark-design-prototype/references/case-matching.md +53 -0
  14. package/miaoda/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
  15. package/miaoda/lark-design-prototype/references/cases/data-table.md +30 -0
  16. package/miaoda/lark-design-prototype/references/cases/official-home.md +26 -0
  17. package/miaoda/lark-design-prototype/references/cases/workspace-home.md +34 -0
  18. package/miaoda/lark-design-prototype/references/color-roles.md +163 -0
  19. package/miaoda/lark-design-prototype/references/component-selection.md +134 -0
  20. package/miaoda/lark-design-prototype/references/design-quality-checklist.md +156 -0
  21. package/miaoda/lark-design-prototype/references/form-shell-patterns.md +77 -0
  22. package/miaoda/lark-design-prototype/references/icon-semantics.md +237 -0
  23. package/miaoda/lark-design-prototype/references/layout-interaction.md +164 -0
  24. package/miaoda/lark-design-prototype/references/page-contract.md +281 -0
  25. package/miaoda/lark-design-prototype/references/product-patterns.md +93 -0
  26. package/miaoda/lark-design-prototype/references/prompt-expansion.md +107 -0
  27. package/miaoda/lark-design-prototype/references/restoration-traps.md +113 -0
  28. package/miaoda/lark-design-prototype/references/token-semantics.md +112 -0
  29. package/miaoda/lark-design-prototype/references/visual-brief.md +125 -0
  30. package/miaoda/lark-design-prototype/references/visual-style-prompts.md +61 -0
  31. package/miaoda/lark-design-prototype/scripts/icon-query.mjs +272 -0
  32. package/miaoda/lark-design-prototype/scripts/token-query.mjs +76 -0
  33. package/miaoda/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
  34. package/miaoda/miaoda-sql/SKILL.md +6 -0
  35. package/miaoda/performance-review/SKILL.md +3 -3
  36. package/miaoda/testing-guide/SKILL.md +114 -13
  37. package/miaoda-modern/charts-skill/SKILL.md +1 -1
  38. package/miaoda-modern/debug-investigation/SKILL.md +1 -1
  39. package/miaoda-modern/forms-skill/SKILL.md +70 -7
  40. package/miaoda-modern/lark-apps-ops/SKILL.md +2 -1
  41. package/miaoda-modern/lark-apps-ops/references/lark-apps-export.md +46 -0
  42. package/miaoda-modern/lark-design-prototype/DESIGN.md +603 -0
  43. package/miaoda-modern/lark-design-prototype/SKILL.md +85 -0
  44. package/miaoda-modern/lark-design-prototype/references/assets/card-illustration-library.md +113 -0
  45. package/miaoda-modern/lark-design-prototype/references/case-matching.md +53 -0
  46. package/miaoda-modern/lark-design-prototype/references/cases/conversational-ai-home.md +27 -0
  47. package/miaoda-modern/lark-design-prototype/references/cases/data-table.md +30 -0
  48. package/miaoda-modern/lark-design-prototype/references/cases/official-home.md +26 -0
  49. package/miaoda-modern/lark-design-prototype/references/cases/workspace-home.md +34 -0
  50. package/miaoda-modern/lark-design-prototype/references/color-roles.md +163 -0
  51. package/miaoda-modern/lark-design-prototype/references/component-selection.md +134 -0
  52. package/miaoda-modern/lark-design-prototype/references/design-quality-checklist.md +156 -0
  53. package/miaoda-modern/lark-design-prototype/references/form-shell-patterns.md +77 -0
  54. package/miaoda-modern/lark-design-prototype/references/icon-semantics.md +237 -0
  55. package/miaoda-modern/lark-design-prototype/references/layout-interaction.md +164 -0
  56. package/miaoda-modern/lark-design-prototype/references/page-contract.md +281 -0
  57. package/miaoda-modern/lark-design-prototype/references/product-patterns.md +93 -0
  58. package/miaoda-modern/lark-design-prototype/references/prompt-expansion.md +107 -0
  59. package/miaoda-modern/lark-design-prototype/references/restoration-traps.md +113 -0
  60. package/miaoda-modern/lark-design-prototype/references/token-semantics.md +112 -0
  61. package/miaoda-modern/lark-design-prototype/references/visual-brief.md +125 -0
  62. package/miaoda-modern/lark-design-prototype/references/visual-style-prompts.md +61 -0
  63. package/miaoda-modern/lark-design-prototype/scripts/icon-query.mjs +272 -0
  64. package/miaoda-modern/lark-design-prototype/scripts/token-query.mjs +76 -0
  65. package/miaoda-modern/lark-design-prototype/scripts/verify-static-html.mjs +117 -0
  66. package/miaoda-modern/performance-review/SKILL.md +3 -3
  67. package/miaoda-modern/reviewer-usage/SKILL.md +2 -0
  68. package/package.json +1 -1
  69. package/shared/attachment/SKILL.md +5 -1
  70. package/miaoda/creative-to-fullstack/references/artifact-signals.md +0 -46
  71. package/miaoda/creative-to-fullstack/references/ui-to-function.md +0 -134
  72. package/miaoda-modern/testing-guide/SKILL.md +0 -221
@@ -1,134 +0,0 @@
1
- # UI→功能推导映射表
2
-
3
- 设计稿里的每个 UI 元素都是功能需求的证据。本表把「稿子上画了什么」翻译成「工程要实现什么」:数据模型、接口、页面行为三层缺一不可。
4
-
5
- ## UI→功能映射表
6
-
7
- | 稿内 UI 元素 | 数据模型 | 接口 | 页面行为 |
8
- |--------------|----------|------|----------|
9
- | 表单(输入框/选择器/提交按钮) | 表单字段 → 实体字段(含类型与必填) | 创建/更新写入接口 + 校验 | 提交、校验提示、成功/失败反馈 |
10
- | 列表/卡片流 | 列表项字段 → 实体查询投影 | 查询接口:排序、过滤、分页 | 空态、加载态、分页/滚动加载 |
11
- | 详情页 | 单实体全字段 | 按 ID 查询 | 不存在时的 404 处理 |
12
- | 统计卡片/图表 | 无新实体,基于既有实体聚合 | 聚合接口(count/sum/avg + group by 维度) | 时间/维度筛选联动 |
13
- | 头像/昵称/个人页/「我的」tab | 用户实体 + 业务数据挂 userId | 当前用户接口;业务查询按用户隔离 | 登录态展示 |
14
- | 状态标签(待办/进行中/已完成等) | 实体 status 字段 + 合法流转 | 状态变更接口(校验流转合法性) | 状态筛选、变更操作入口 |
15
- | 搜索框 | — | 查询接口加关键字参数 | 防抖、无结果态 |
16
- | 删除/归档按钮 | 软删或归档字段 | 删除/归档接口 | 确认交互 |
17
- | 日期/日历视图 | 实体时间字段 | 按时间范围查询 | 日/周/月切换 |
18
- | 稿内示例数据(列表里的假条目、图表假数值) | — | — | 写入数据库成为初始数据;页面必须走真实查询,不许写死 |
19
-
20
- 推导原则:**稿内看得见的每条数据都要能回答「它从哪张表的哪个字段来」**;回答不了的,就补齐真实数据模型和数据链路,不得用硬编码或假逻辑代替。
21
-
22
- **多维组件必须逐维度登记字段绑定**:一个组件同时承载多个可见维度时(如状态标签的「显示文案」与「视觉状态/颜色」是两个维度),每个维度显式写明绑定哪个字段(如文案 ← `docType`、颜色 ← `status`),不得用同一个状态字段既当文案又当颜色,导致所有行渲染成同一个值。
23
-
24
- ## 源稿可见内容与默认数据状态
25
-
26
- 高保真不只包含布局和样式。源稿在默认(未交互)状态下可见的内容、数据和素材同样是 UX 规格;把静态示例改成 DB/API 驱动时,只改变数据来源,不改变默认展示结果。这条约束覆盖应用的每一个页面、每一处可见内容。
27
-
28
- | 源稿证据 | 实现要求 |
29
- |----------|----------|
30
- | 区块标题、说明、标签、按钮文案 | 原样保留,不擅自缩写、润色或改写语义 |
31
- | 分类、卡片、列表等重复条目 | 保留源稿的数量、名称、顺序、分组和对应关系 |
32
- | 价格、时长、进度、统计等示例值 | 作为初始数据写入数据库,统一单位后由真实 API 返回;页面展示值与源稿一致 |
33
- | 图片、SVG、图标、CSS 渐变、背景 | 复用或等价转译并保持与条目的映射;不得用生成图片替换已有素材 |
34
- | 默认选中、筛选、分页、空态和业务状态 | 首次进入时由真实数据与页面状态复现,不用硬编码结果覆盖 API |
35
-
36
- **页面可见字段不得静默改写**:凡直接显示或决定页面默认外观的字段,包括文案、字符/图标、图片、颜色、渐变、数值、单位、顺序和默认状态,均须从源稿逐字段传递到其存放位置并到达页面。存放位置按性质划分:业务数据,以及属于单条数据自身内容的视觉值(每条数据自有的封面图、封面渐变、标识色),写入数据库成为初始数据、经接口到达页面;不参与查询和聚合、由设计稿为固定集合指定的纯视觉值(字符图标、装饰 emoji、固定区块配色),作为前端组件常量或主题 token,直接从源稿代码复制。字符图标不得静默改成图标库名称,素材不得改成语义占位符。确有必要转译时,在方案中登记源表示、目标表示、转换实现和验收方式,并验证视觉等价。
37
-
38
- 规划时对每组默认展示数据登记五项内容:目标页面或区块、源文件与行号区间、全部默认展示字段、数据库与接口与页面链路、原值保留或必要转换策略。字段集合必须完整,但不要把大段源码或全部字段值复制进 plan;重复条目应覆盖所有直接渲染或决定外观的字段(如 `name/icon/count/order`),不得只概括成“若干分类/卡片”。写入初始数据、实现 API 投影或素材映射的 Agent 必须在动手前就近读取对应源文件;不能因为 UI Agent 已读源稿,就依据其摘要重新编造数据。
39
-
40
- 验收时逐页沿真实链路核对:
41
-
42
- 源稿可见内容、数据库初始数据与素材、API 返回、页面渲染,四层逐字段一致
43
-
44
- 数据库非空、接口成功、返回条数正确或页面结构相似都不算通过;必须按方案登记的默认展示字段逐字段核对文案、字符/图标、条目数量与顺序、示例值与单位、素材对应关系和默认状态。
45
-
46
- ## 前后端接口与数据口径一致
47
-
48
- 同一业务数据经过前端、API、服务端、数据库或插件时,字段名、类型、单位、取值范围、枚举、是否必填和默认值必须一致。优先在共享接口类型中定义请求与响应结构,前后端不得各自发明不同口径。
49
-
50
- 只为容易产生歧义的数据建立口径清单,不要罗列所有普通字段。必须登记:金额、比例、时长、距离、时间等带单位字段,状态和类型枚举,单值/多值,可空/选填/默认值,插件结构化输出,以及展示值与存储值不同的字段。
51
-
52
- | 业务数据 | 请求/响应字段 | 类型与取值 | 单位/范围 | 服务端与 DB | 页面展示 |
53
- |----------|---------------|------------|-----------|-------------|----------|
54
- | 示例:商品价格 | `minPrice` / `maxPrice` | `number` | 分,非负整数 | DB 存分,仅在明确边界转换 | 展示时除以 100 |
55
- | 示例:搜索类型 | `types` | `SearchType[]` | 约定枚举,可多选 | 按数组执行 `IN` 查询 | 多选筛选器 |
56
- | 示例:置信度 | `confidence` | `integer` | 0–100 | DB 与插件归一化后均存 0–100 | 直接追加 `%` |
57
-
58
- ## 持久化业务结果与异常恢复
59
-
60
- 如果一次用户操作的结果需要在刷新、重新进入或异常重试后继续存在,或者会约束后续允许执行的操作,就把它视为持久化业务结果。业务结果不限于状态枚举,也包括实体创建、关系变化、数量或进度变化、生命周期阶段和异步产物。Tab、弹窗、展开收起等纯页面状态不要求落库,除非源稿明确表达跨会话保留。
61
-
62
- | 业务对象 | 操作/事件 | 操作前提 | 成功后的业务结果 | 持久化内容 | 重复/并发处理 | 刷新与异常恢复 |
63
- |----------|-----------|----------|--------------------|------------|---------------|----------------|
64
- | `<实体或关系>` | `<用户操作或系统事件>` | `<允许执行的业务条件>` | `<可观察、可继续使用的事实>` | `<表、字段或外部结果引用>` | `<幂等、拒绝或并发控制>` | `<重新读取、重试或对账>` |
65
-
66
- - 以服务端和持久化存储中的业务事实为准;前端只在重新读取后确认结果,不得仅凭本地状态或 HTTP 2xx 宣布完成。
67
- - 在服务端校验操作前提并原子持久化业务结果;不满足前提的操作返回明确错误,不得静默成功。
68
- - 对可能重复产生副作用的操作定义幂等或并发控制;请求超时或中断时,先重新读取真实结果,再决定是否重试。
69
- - 对异步处理持久化任务状态、结果引用和失败信息,使页面重新进入后能够继续查询或恢复。
70
-
71
- ## 可见功能闭环清单
72
-
73
- 逐项登记所有具有交互语义的可见元素:按钮、链接、可点击卡片、表单控件、搜索/筛选/排序/分页、Tab/导航/弹窗、上传/下载/导出、播放器、开关和步骤流转。纯文案、分割线、背景等明确非交互装饰不登记;不要据此补造源稿未展示或暗示的产品功能。
74
-
75
- 同一组件模板中行为和链路完全相同的重复控件可以合并登记,但每个可见交互都必须能对应到清单中的一项;行为、参数或结果不同的控件分别登记。
76
-
77
- | 页面 / 可见元素 | 用户操作 | 可见结果 | 实现链路 | 验收方式 |
78
- |-----------------|----------|----------|----------|----------|
79
- | 示例:课程详情 /「立即购买」 | 点击 | 报名成功,按钮变为已加入 | `onClick → POST /enrollments → enrollment 表 → 刷新详情` | 从按钮触发;刷新后仍为已加入 |
80
- | 示例:播放器 / 播放按钮 | 点击 | 开始播放,时间与进度变化 | 播放器状态 → 进度写接口 → progress 表 | 播放后读取进度并刷新确认 |
81
-
82
- 实现链路按交互类型填写:
83
-
84
- - **导航/本地状态**:控件 → 正确路由、Tab、弹窗或组件状态;不得用空 `href`、错误路由或只切换无关图标代替。
85
- - **查询**:控件 → 查询参数 → API DTO → DB 查询 → 列表/统计结果;前后端复用同一数据口径,并用页面实际发送的参数验收查询结果。
86
- - **写入**:控件 handler → 写 API → DB/文件/平台能力 → 成功/失败反馈 → 重新读取;请求与响应遵循共享接口类型,不得只改前端内存、只改初始数据或返回固定成功。
87
- - **插件/外部能力**:控件 → 真实 capability/服务 → 可验证结果;先明确插件输入输出的字段、类型、范围与空值处理,不可用时报告阻塞,不得用延时、随机数、正则校验或假 toast 冒充。
88
-
89
- 方案提交前扫描可见功能清单、风险和实现说明。若用「模拟、占位、静态展示、Toast 反馈、仅格式校验、仅记录、不对接」代替源稿表达的功能,必须改为真实链路;能力确实不可用时标记阻塞和未完成,不得把降级方案列为已实现范围。
90
-
91
- ## UI→capability 常见信号示例(非完整插件目录)
92
-
93
- 创意稿里被 mock 的 AI/飞书类能力,生成时用**真实插件**实现。下表只帮助从 UI 语义识别插件候选并触发 `plugin-guide`,不是平台能力清单;表外疑似插件能力也要召回 `plugin-guide`。实际可用能力以其动态提供的 `available_plugin_instances`、`available_plugins` 及候选实例的 `get_plugin_ai_json` 为准。
94
-
95
- | 稿内 UI 语义 | 候选 capability(以动态目录为准) |
96
- |--------------|-------------------|
97
- | "AI 生成/智能生成/一键生成文案"、聊天对话框、智能问答 | `ai-text-generate` |
98
- | "AI 生图/配图/封面生成/头像生成" | `ai-text-to-image` |
99
- | 上传图片"识别/提取字段"(发票/名片/证件/表单) | `ai-image-to-json` |
100
- | 上传文档"解析/总结/提炼" | `ai-doc-parser` → `ai-text-to-json` / `ai-text-summary` |
101
- | "翻译" | `ai-translate` |
102
- | "语音转写/录音转文字" | `ai-speech-to-text` |
103
- | 图片"抠图/去背景" | `ai-image-matting` |
104
- | "发送到飞书/通知群/推送消息" | `send-feishu-message` |
105
- | "同步到多维表格/写入 Base/存表格" | `feishu-bitable` |
106
- | "建群/拉群" | `feishu-group-create` |
107
-
108
- 识别出候选后**召回 `plugin-guide` skill**,由它完成实例复用或创建、运行时合同读取和真实调用。本 skill 不复述插件目录与调用规范。
109
-
110
- **边界**:数据库读写、文件上传/存储**不是插件**(内置服务 DataLoom / file-service,走对应 skill);语义检索走 `semantic-search` skill。别把这三类误建成 capability。
111
-
112
- ## mock 信号识别表(grep 创意产物定位待替换点)
113
-
114
- 创意稿无「插件规划」时,AI/飞书能力都是 mock 的。规划阶段 grep 这些信号,逐个登记进方案的 capability 清单:
115
-
116
- | mock 反模式 | 典型形态 | 应替换为 |
117
- |-------------|----------|----------|
118
- | 假异步 AI | `setTimeout(() => setState(硬编码对象))`、`simulate*`/`mock*`/`fake*` 函数名 | 对应 AI capability |
119
- | 预置结果数组 | `MOCK_*` / `PRESET_*` 常量假装 AI 生成结果 | 对应 AI capability |
120
- | 外链占位图 | `picsum.photos` / `placeholder.com` / `unsplash` 替代 AI 生图 | `ai-text-to-image` |
121
- | 假飞书反馈 | `toast('已发送到飞书')` 无真实调用 | `send-feishu-message` |
122
- | 随机数假逻辑 | `Math.random()` 替代 AI 分类/评分 | 对应 AI capability |
123
-
124
- ("展示用示例数据"是允许的 mock——写入数据库成为初始数据即可,与上面的"插件能力 mock"区分:前者是数据,后者是能力。)
125
-
126
- ## 方案(plan)必须包含
127
-
128
- - **页面清单**:路由 / 页面名 / 来源屏(画板 label 或文件名)
129
- - **源稿实现定位与默认展示字段归属**:目标页面或区块 / 源文件或区段 / 全部默认展示字段 / DB、API 与页面链路 / 原值保留或必要转译策略 / UI、初始数据、API 与素材负责人;字段集合必须完整,但不复制大段源码或全部字段值
130
- - **实体与关系**:表、字段、关联、状态机
131
- - **页面-接口映射**:每页消费/调用哪些接口
132
- - **可见功能清单**:页面与控件 / 用户操作 / 可见结果 / 实现链路 / 验收方式
133
- - **数据口径清单(存在易歧义数据时)**:业务数据 / 请求与响应字段 / 类型与取值 / 单位与范围 / 服务端与 DB / 页面展示
134
- - **持久化业务结果清单(存在需跨刷新/重新进入/异常重试保留或约束后续操作的结果时)**:业务对象 / 操作或事件 / 操作前提 / 成功后的业务结果 / 持久化内容 / 重复与并发处理 / 刷新与异常恢复
@@ -1,221 +0,0 @@
1
- ---
2
- name: testing-guide
3
- description: 派发 E2E 子 agent(Task subagent_type="E2E")前**必读**——无论是用户主动要求,还是 agent 自行决定要测/复验功能,不能仅凭用户字面要求就直接派发。Also use when user wants to check, verify, or troubleshoot application functionality via browser. 触发词:检查页面, 看看有没有问题, 走一遍流程, 帮我看看, 试一下, 哪里出问题了, XX不好使, 检查一下, 测一下, 派发 E2E, 打开浏览器测, 验收功能
4
- steering: true
5
- steering-topic: testing
6
- gate-tools:
7
- - tool: task
8
- when:
9
- subagent_type: E2E
10
- ---
11
-
12
- # 检查与验证:工具选择指南
13
-
14
- 根据用户意图选择正确的派遣方式:派遣 E2E 子 agent(通过 `Task(subagent_type="E2E")` 打开浏览器操作一遍)或调用 `api_request`(直接请求后端接口)。
15
-
16
- ## 用户沟通规范
17
-
18
- 与用户沟通时,**禁止**出现 "E2E" / "端到端测试" / "E2E agent" 等术语。E2E agent 的定义就是「用浏览器替你实际操作应用,验收功能是否正常、排查页面问题」——对外直接说这个意思即可:
19
-
20
- | 禁止 | 改用 |
21
- |------|------|
22
- | E2E、端到端测试 | 浏览器测试、浏览器操作 |
23
- | E2E agent、派遣 E2E | 无需提及 agent,直接说"我用浏览器帮你..." |
24
-
25
- ## 决策规则
26
-
27
- ```
28
- 用户想确认应用是否正常
29
- ├─ 明确要求验证「后端接口」「API 返回值」「请求响应」 → api_request
30
- └─ 其他所有情况 → Task(subagent_type="E2E")(打开浏览器,以用户视角操作应用)
31
- ├─ 默认(用户没主动要求跑功能)→ 不传 mode,走 lite(只截图看视觉)
32
- └─ 用户明确要求验证交互/业务流程/数据(点击/填写/提交/走一遍流程)→ agent_options.mode: "standard"
33
- ```
34
-
35
- - **模糊需求一律派遣 E2E**:未明确提到「接口」「API」「后端」时必须派遣 E2E,不要主动选择 `api_request`
36
- - **默认走 lite,standard 需用户明确要求功能测试**:用户没有主动要求跑具体功能(只说"看看有没有问题"这类模糊需求也算没主动要求)时,一律不传 mode 走 `lite`;只有用户明确要验证交互 / 业务流程 / 数据(点击、填写、提交、走一遍流程等)时才传 `agent_options.mode: "standard"`
37
- - **`api_request` 仅限显式请求**:仅当明确提到接口 / API / 后端 / 请求 / 响应、且意图是验证接口逻辑而非页面功能时才使用
38
- - **E2E 结束后禁止追加 `api_request`**:浏览器操作的结果即为最终结果,**严禁**再自动补充验证
39
-
40
- ### E2E 的 mode 选择
41
-
42
- 通过 `agent_options.mode` 指定,**可选参数**,不传或非 `standard` 一律按 `lite` 处理:
43
-
44
- | mode | 适用场景 | 行为 | 总超时 | 录屏 |
45
- |------|---------|------|-------|------|
46
- | `lite`(缺省) | 只看视觉渲染(CSS/布局/文案/图标)、快速冒烟,或用户未主动要求跑功能的模糊验收 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`,**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
47
- | `standard` | **仅当用户明确要求**验证业务流程、数据流、交互后状态变化 | 完整交互(点击/输入/滚动/提交)+ Network 验证 + 录制 | 5 分钟 | ✅ |
48
-
49
- **缺省即 `lite`**——但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。**只有用户明确要求跑功能**(testRequirements 里出现"点击"、"填写"、"提交"等动词,或用户直接要求验证某功能)时,才传 `standard`。
50
-
51
- ## 工具选择速查表
52
-
53
- | 用户表达 | 选择 | 原因 |
54
- | --- | --- | --- |
55
- | "检查一下页面" / "看看有没有问题" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E(lite,缺省) | 未主动要求跑功能,默认视觉巡检 |
56
- | "刚改了 CSS,看看样式对不对" | E2E(lite) | 仅视觉巡检 |
57
- | "点提交试试能不能成功" / "帮我把下单流程走一遍" / "走一遍流程" / "验证一下这个功能" | E2E(standard) | 用户明确要求功能 / 交互验证 |
58
- | "测试一下这个接口的返回值对不对" / "调一下后端 API 看看响应" | `api_request` | 明确指定接口验证 |
59
-
60
- ## 派遣 E2E 时的 prompt / 用例规范
61
-
62
- `prompt` 不是一句话需求,而是一份**结构化验收脚本**。Case 越具体结果越可信;含糊需求只会让 agent 瞎点一通。
63
-
64
- > **核心原则:agent 只「机械执行 + 报判断」,不做推理。** 判定标准全写死在断言里——别让它自己推断"该测什么"或定义"什么算正常 / 好看"。它的活只有:执行动作 → 看现象 → 报通过 / 不通过。
65
-
66
- ### 调用结构
67
-
68
- ```js
69
- task({
70
- subagent_type: "E2E",
71
- agent_options: { mode: "standard" }, // standard=可点击/输入,lite=只截图
72
- description: "验收创作工具", // 一句话任务名
73
- prompt: `
74
- 对<被测应用一句话描述>进行端到端验收测试。
75
-
76
- ## 应用结构
77
- - <页面名> (<路由>) — <布局/职责>
78
- - ...
79
-
80
- ## 测试用例
81
- ### Case 1: <页面/模块> - <场景>
82
- 1. <动作步>
83
- 2. 断言:<可观察现象>
84
- ...
85
- `,
86
- // ...其他参数:按 Task 工具的实际签名如实补全,别只填上面示例里的字段
87
- })
88
- ```
89
-
90
- ### prompt 三段式
91
-
92
- | 段落 | 内容 | 作用 |
93
- |------|------|------|
94
- | 概述 | 一句话说明被测应用是什么 | 让 agent 建立全局认知 |
95
- | `## 应用结构` | 每个页面的路由 + 布局/职责 | 告诉 agent 去哪、看什么 |
96
- | `## 测试用例` | 多个 Case,每个含编号步骤 | agent 逐条执行并断言 |
97
-
98
- ### Case 编写规则
99
-
100
- - **标题**:`### Case N: <模块> - <场景>`,一个 Case 一个独立场景
101
- - **动作步 / 断言步交替**:动作步动词开头(访问 / 点击 / 输入 / 切换);断言步以「断言:」开头
102
- - **可定位 + 二元判定**:动作指到具体对象(可见文本,如「发布新帖」按钮);断言给非黑即白判据(出现 / 消失 / 等于 / ≥N / 含某文案),不写"正常""是否合理 / 美观"(见下方对照)
103
- - **独立可重入**:删除 / 提交等副作用操作走「取消」或验证后还原,不污染后续 Case
104
-
105
- ### Case 复杂度约束(必跑到终态)
106
-
107
- 每个 Case 必须**跑到最终可观测结果**,「打开弹窗 / 看到字段 / 按钮存在」都只是中间态,不算验证。
108
-
109
- - **跑到终态**:提交后出现在列表 / 跳转后内容正确 / 删除后从列表消失
110
- - **AI 功能看到输出**:翻译 / 摘要 / 生成等核心卖点,须断言到 AI 产出的内容,不停在"AI 弹窗打开"
111
- - **主链路 + AI 都覆盖**,不因"非主链路"遗漏
112
- - **Case ≤ 10**:过多会 token 膨胀、超时
113
- - **不碰登录 / 认证**:应用无登录逻辑,禁止登录 / 注册 / OAuth / CAPTCHA 相关 Case
114
-
115
- | ❌ 停在中间状态 | ✅ 跑到最终结果 |
116
- |------|------|
117
- | 打开预约弹窗,验证表单字段 | 填写表单全部字段并提交,预约出现在管理列表中 |
118
- | 验证翻译弹窗是否正常打开 | 点翻译选目标语言确认,内容区域显示翻译后的文本 |
119
- | 删除确认对话框是否出现 | 点确认后,记录从列表中消失 |
120
- | 验证课程信息"完整"展示 | 详情页显示课程名、章节列表、≥1 条学员案例 |
121
-
122
- ### 断言可观察化对照
123
-
124
- | ❌ 含糊(agent 无法核对) | ✅ 可观察 |
125
- |------|------|
126
- | "页面正常加载" | "页面包含「创作配置」标题" |
127
- | "按钮可用" | "「一键生成」按钮处于可点击态" |
128
- | "跳转成功" | "URL 变为 /materials" |
129
- | "有数据" | "表格中至少展示 3 行数据" |
130
- | "弹窗出现" | "弹出详情弹窗,展示标题、正文、配图" |
131
- | "样式好看" | "卡片使用圆角 + 微投影,整体为暖色调" |
132
-
133
- ### 断言要查到信号层(最易漏检,必读)
134
-
135
- UI 快照「看起来正常」是最大假阴来源——接口 500、图片 404、失败 toast 都不一定改变页面结构。功能 / 资源类 Case 的断言**必须落到 network / console**,不能只靠无障碍快照或截图:
136
-
137
- | 漏检模式 | 错误做法 | 正确断言 |
138
- |------|------|------|
139
- | 接口报错(提交 / 生成 / 翻译失败) | 看到表单还在、按钮在就判过 | 触发后断言关键接口(尤其 `/api/capability/*` 等业务 / 能力接口)响应码,**非 2xx(4xx/5xx)即 failed** |
140
- | 图片 / 静态资源 404 | 无障碍快照有 `image` 节点就判过 | 404 的 `<img>` 仍是 image 节点——**必须查 network 该资源非 404,或截图确认像素真渲染** |
141
- | 失败 toast / 空结果 / 错误兜底 | 没撞见失败 toast 就判过 | 空结果 / 错误兜底 UI / 白屏是**常驻态**,出现即判 failed;失败 toast 瞬时易漏,**撞见可判挂、漏看≠通过**——失败的权威判据是上一行的 network 响应码(非 2xx 即 failed) |
142
-
143
- **核心动作必须真正触发到终态**:验证某功能 = 实际点击触发按钮(提交 / 生成 / 翻译 / 上传)并等待结果;只验「表单能填 / 按钮存在 / 弹窗打开」就判过 = 根本没测到该功能,必然漏报。
144
-
145
- ### 禁止编写工具能力外的 Case(否则只会产生「假失败」)
146
-
147
- E2E agent 只在离散时刻抓快照 / 截图,**看不到瞬时过程、不逐帧解析动画、不能在导航前改写流量**。下列现象超出工具能力,写成断言只会被报成"失败(工具能力限制)"——属于无效 Case,**从源头就不要写**:
148
-
149
- | ❌ 工具看不到的现象 | 为什么看不到 | ✅ 改成可观察的终态断言 |
150
- |------|------|------|
151
- | 骨架屏 / loading 占位符 | 它是过场态,本就不该当验证目标——数据回来就消失,根本不要去看它 | 直接断言加载完成后的真实内容出现(内容在 = 加载链路通) |
152
- | toast / 轻提示一闪而过("提交成功""已复制") | 几秒自动消失,离散快照常错过 | 改断它代表的**真实结果**(记录进列表 / 状态切换),权威判据是 network 响应码(非 2xx 即 failed);无明显终态时用 network 调用或重载后持久态代替,**绝不把 toast 当断言对象** |
153
- | CSS 动画 / 过渡 / 滚动是否"流畅""有动效" | 截图是静态帧,不逐帧评估动画播放 | 断言动画**结束后的状态**(元素已展开 / 已隐藏 / 已就位) |
154
- | 靠拦截 / mock 网络返回来造错误(如"让接口返回 500 看兜底") | 工具不能在页面加载前注入拦截或改写响应 | 只验真实响应;要看错误兜底需后端真异常或用真实异常数据,不靠伪造流量 |
155
-
156
- 断言对象若是瞬时中间态 / toast 本身 / 动效本身 / 需伪造网络的分支——改写成稳定终态断言,或直接删掉。
157
-
158
- ### 建议覆盖维度
159
-
160
- 覆盖维度(按实际功能裁剪):
161
-
162
- | 维度 | 典型 Case |
163
- |------|-----------|
164
- | 页面加载 / 初始空状态 | 打开后标题、表单、空状态引导文案是否就位 |
165
- | 表单交互 / 输入校验 | 输入前按钮禁用 → 输入后变可点击;选择器值更新 |
166
- | 导航切换 | 点击 tab → URL 变化 → 内容正确 → 可返回 |
167
- | 详情查看 | 点击查看 → 弹窗展示内容 → 关闭 → 回到列表 |
168
- | 危险操作确认 | 点击删除 → 确认弹窗 → 点取消 → 记录未删除 |
169
- | AI 功能(核心卖点) | 触发翻译 / 摘要 / 智能生成 → 断言 AI 实际输出的内容出现 |
170
- | 视觉一致性 | 配色、圆角/投影、响应式单列堆叠 |
171
-
172
- ## E2E 轮数与复测策略
173
-
174
- E2E 派遣是**昂贵操作**(每次消耗大量 token + 时间)。E2E agent 只负责暴露问题,**不负责定位根因**。
175
-
176
- **每次任务执行**的 E2E 总派遣上限 **3 轮**(同一应用内多次任务分别计算):
177
-
178
- | 轮次 | testRequirements 内容 | 说明 |
179
- |------|----------------------|------|
180
- | 第 1 轮 | spec 验收任务的全量 Case(≤5 个) | 首次全面验收 |
181
- | 第 2 轮 | 上一轮 failed + 未完成的 Case | 定向复测,**不要重新生成全量 testRequirements** |
182
- | 第 3 轮 | 上一轮仍 failed 的 Case | 最后一次机会 |
183
- | 第 4 轮起 | 禁止再派遣 E2E | 转为根因分析模式 |
184
-
185
- **定向复测规则**:
186
- - 已通过的 Case 最多复测 1 次:担心修复引入回归时可纳入复测,同一 Case 累计通过 2 次后不再纳入
187
- - 如果上一轮因超时中断,E2E 会返回"已测通过/已测失败/未测"三组——已测通过的结果可信不需重测,只测"失败"和"未测"的
188
-
189
- **白屏 / 整页打不开 → 复测前先重启 devServer**:白屏多为 **devServer 编译挂死 / HMR 卡住**,非代码 bug,直接再派只会重复白屏、白吃一轮配额。顺序:**① 重启 devServer → ② 查编译输出 / runtime-log 确认无报错(不派 E2E)→ ③ 再正常复测**;真要肉眼确认用 `lite` 截图,别用 standard 探活。
190
-
191
- **测试范围**:首轮(spec 验收)总 Case **≤ 5**(单次派发上限 ≤10 见 Case 复杂度约束),一行一个 Case,必须含主链路流程测试。禁止测试有真实副作用的功能(发送飞书消息、飞书建群)。
192
-
193
- **停止派遣 E2E 的触发条件**(满足任一即停止):
194
-
195
- | 条件 | 说明 |
196
- |------|------|
197
- | 已派遣 ≥ 3 轮 | 硬上限 |
198
- | 同一 Case **未经代码修改**连续失败 ≥ 2 次 | 修复后重试不算连续 |
199
- | 本次错误信息与上次完全一致 | 说明修复未命中根因 |
200
-
201
- 达到上限后仍有 failed:在 commit_task 结果中标注未通过的 Case,继续推进后续任务。
202
-
203
- **停止后的行动**(按优先级执行):
204
-
205
- 1. **查后端日志**:若涉及数据/接口错误,用日志查询工具排查 traceid / 服务端日志
206
- 2. **直接读代码**:根据 E2E 报告的 URL 和 problem 定位源文件,人工分析根因
207
- 3. **重启 dev server**:白屏 / 打不开时按上方「白屏 → 复测前先重启 devServer」流程处理
208
- 4. **告知用户**:列出已尝试的修复 + 失败现象,请求补充上下文
209
-
210
- ## Common Mistakes
211
-
212
- | 错误 | 正确做法 |
213
- | ------------------------------------- | ------------------------------------- |
214
- | 用户说"测一下"就调 `api_request` | 默认派遣 E2E(打开浏览器操作) |
215
- | E2E 完成后又调 `api_request` 补充验证 | 浏览器操作结果即为最终结果,不追加 |
216
- | 用户说"看看有没有 bug"就同时调两个 | 只派遣 E2E |
217
- | 用户说"检查接口"时派遣 E2E | 明确提到接口时用 `api_request` |
218
- | 用户没主动要求跑功能,却默认传 `standard` | 缺省走 `lite`;仅用户明确要求交互 / 功能验证才传 `standard` |
219
- | 仅改 CSS / 文案,仍走 `standard` | 优先用 `lite` |
220
- | 达到停止条件(≥3 轮 / 同一错误未改代码连续失败)仍继续派 E2E | 停止派遣,转为根因分析(读代码 / 查日志) |
221
- | 复测时全量重测 / 白屏直接再派一轮 | 只传 failed + 未完成的 Case;白屏先重启 devServer 再复测 |