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

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 (5) hide show
  1. package/miaoda/ai-data-processing/SKILL.md +4 -1
  2. package/miaoda/semantic-search/SKILL.md +6 -3
  3. package/miaoda/testing-guide/SKILL.md +12 -9
  4. package/miaoda-modern/testing-guide/SKILL.md +12 -9
  5. package/package.json +1 -1
package/miaoda/ai-data-processing/SKILL.md CHANGED
@@ -47,6 +47,8 @@ SELECT * FROM rds_ai.list_model();
47
47
 
48
48
  按业务需求选定模型，取其 `model_name` 作为第二个参数。
49
49
 
50
+ ⚠️ **模型可用性由租户管理后台管控。** `list_model()` 返回的是平台预置清单；管理员下架或停用其中某个模型后，平台自动在其余可用预置模型中选择，业务 SQL 无需改动。因此除非用户明确要求锁定模型，否则不传 `model_name`；锁定的模型被停用时，加工结果可能出现风格波动。预置模型全部不可用时调用直接失败，处置见「关键注意事项」。
51
+
50
52
  ## 实现步骤
51
53
 
52
54
  以下 SQL 使用 `tickets` / `priority` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键和 `task_kind`。
@@ -378,10 +380,11 @@ LIMIT 20;
378
380
  | ❌ 业务事务路径（同步 trigger / 大批量 UPDATE）里直接调 `rds_ai.ai_query` | HTTP 调用会因网络抖动、限流、超时、模型异常抛错，阻塞业务写入、占锁并产生大额模型调用 | trigger 只入队，模型调用统一由 `ai_run_pending_jobs()` 的 EXCEPTION 块兜住；批量场景先小样本验证，再经 `ai_job` 分批处理 |
379
381
  | ❌ 422 / `quota_exceeded` 报错后继续重试 | 当前应用 AI 调用额度已用完，重试只会继续报错 | 任务直接置 `failed`、停止入队，续费后批量重跑；提示用户「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」 |
380
382
  | ❌ 429 / `rate_limit_exceeded` 报错后原速重跑 | 调用过于密集触发限流 | 保持重试 + 指数退避；调小 `ai_run_pending_jobs` 单次批量、放慢 worker 节奏；提示用户「AI 调用过于频繁触发了限流，已自动放慢节奏，稍后会继续跑完」 |
383
+ | ❌ 500 / `model_unavailable` 报错后继续重试或继续入队 | 租户预置模型已被全部下架或停用，平台无模型可选，重试不会恢复 | 任务置 `failed` 并停止入队；提示用户「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」；模型恢复后重跑失败任务即可 |
381
384
  | ❌ prompt 不约束输出格式 | 解释性文本会作为脏值写回业务表 | 分类任务写清枚举值并在 SQL 函数里校验结果；JSON 抽取写清 JSON schema |
382
385
  | ❌ trigger 只靠 `UPDATE OF <col>` 判断变化 | 无关更新会重复入队、重复消耗 | 函数里再用 `IS NOT DISTINCT FROM` 判断源字段变化 |
383
386
 
384
- `rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
387
+ `rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码（422 / 429 / 500）或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
385
388
 
386
389
  **禁止**的写法（会阻塞业务写入事务）：
387
390
 
package/miaoda/semantic-search/SKILL.md CHANGED
@@ -57,6 +57,8 @@ SELECT rds_ai.ai_embed('你好')::vector;
57
57
  -- → vector(1024)
58
58
  ```
59
59
 
60
+ ⚠️ **模型可用性由租户管理后台管控。** embedding 仅此一个模型、无备选，管理员将其下架或停用后 `rds_ai.ai_embed` 即不可用，调用报 `model_unavailable`（处置见「关键注意事项」）。
61
+
60
62
  ## 实现步骤
61
63
 
62
64
  以下 SQL 使用 `products` / `embedding` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键、返回列和索引名。
@@ -281,14 +283,15 @@ LIMIT 10;
281
283
 
282
284
  ## 关键注意事项
283
285
 
284
- ### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流)
286
+ ### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流) / 500 (无可用模型)
285
287
 
286
- `rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字。识别后给用户的提示要分开：
288
+ `rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字。识别后给用户的提示要分开：
287
289
 
288
290
  - **422 / quota_exceeded** — 当前应用的 AI 调用额度已用完。提示用户：「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」。**不要重试**，重试只会继续报错。
289
291
  - **429 / rate_limit_exceeded** — 调用过于密集触发限流。提示用户：「AI 调用过于频繁触发了限流，稍后再试，或调小回填批次 / 降低并发即可恢复」。**可重试**，建议指数退避。
292
+ - **500 / model_unavailable** — 租户预置的 embedding 模型已被管理员下架或停用，且无备选模型。提示用户：「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」。**不要重试**，模型恢复后重跑存量回填即可。
290
293
 
291
- trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑。
294
+ trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑，遇到 500 停整批并提示联系租户管理员。
292
295
 
293
296
  ### ⚠️ 同步 trigger 调 rds_ai.ai_embed 必须 BEGIN/EXCEPTION 兜底
294
297
 
package/miaoda/testing-guide/SKILL.md CHANGED
@@ -29,32 +29,34 @@ gate-tools:
29
29
  ├─ Task 工具定义的 subagent_type 选项里没有 E2E（E2E 被关闭/不可用，非"本轮没派过"）→ api_request（接口级验收）+ 读代码/读日志兜底，不要尝试派 E2E
30
30
  ├─ 明确要求验证「后端接口」「API 返回值」「请求响应」 → api_request
31
31
  └─ 其他所有情况 → Task(subagent_type="E2E")（打开浏览器，以用户视角操作应用）
32
- ├─ 只看视觉（白屏/布局/样式/文案）→ agent_options.mode: "lite"
33
- └─ 涉及交互/业务流程/数据 → 不传或 agent_options.mode: "standard"
32
+ ├─ 默认（用户没主动要求跑功能）→ 不传 mode，走 lite（只截图看视觉）
33
+ └─ 用户明确要求验证交互/业务流程/数据（点击/填写/提交/走一遍流程）→ agent_options.mode: "standard"
34
34
  ```
35
35
 
36
36
  - **E2E 不可用时改走 api_request（最高优先，先于下面所有规则判断）**：当 Task 工具定义的 subagent_type 选项里没有 E2E（用户关闭了浏览器验收 / 环境不支持；判断依据是工具定义中是否含 E2E 选项，不是"本轮有没有派过 E2E"）时，下面"模糊需求一律派遣 E2E"不再适用——改用 `api_request` 做接口级验收，配合读代码 / 读运行时日志确认核心链路，**不要尝试派 E2E、也不要空等**；此时验收范围收敛到接口与数据层可判定结果，视觉类目标顺延到非核心降级范围
37
37
  - **模糊需求一律派遣 E2E**（仅当 E2E 可用）：未明确提到「接口」「API」「后端」时必须派遣 E2E，不要主动选择 `api_request`
38
+ - **默认走 lite，standard 需用户明确要求功能测试**：用户没有主动要求跑具体功能（只说"看看有没有问题"这类模糊需求也算没主动要求）时，一律不传 mode 走 `lite`；只有用户明确要验证交互 / 业务流程 / 数据（点击、填写、提交、走一遍流程等）时才传 `agent_options.mode: "standard"`
38
39
  - **`api_request` 仅限显式请求**：仅当明确提到接口 / API / 后端 / 请求 / 响应、且意图是验证接口逻辑而非页面功能时才使用
39
40
  - **E2E 结束后禁止追加 `api_request`**：浏览器操作的结果即为最终结果，**严禁**再自动补充验证
40
41
 
41
42
  ### E2E 的 mode 选择
42
43
 
43
- 通过 `agent_options.mode` 指定，**可选参数**，不传或非 `lite` 一律按 `standard` 处理：
44
+ 通过 `agent_options.mode` 指定，**可选参数**，不传或非 `standard` 一律按 `lite` 处理：
44
45
 
45
46
  | mode | 适用场景 | 行为 | 总超时 | 录屏 |
46
47
  |------|---------|------|-------|------|
47
- | `standard`（缺省） | 涉及业务流程、数据流、交互后状态变化 | 完整交互（点击/输入/滚动/提交）+ Network 验证 + 录制 | 5 分钟 | ✅ |
48
- | `lite` | 只看视觉渲染（CSS/布局/文案/图标）或快速冒烟 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`，**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
48
+ | `lite`（缺省） | 只看视觉渲染（CSS/布局/文案/图标）、快速冒烟，或用户未主动要求跑功能的模糊验收 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`，**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
49
+ | `standard` | **仅当用户明确要求**验证业务流程、数据流、交互后状态变化 | 完整交互（点击/输入/滚动/提交）+ Network 验证 + 录制 | 5 分钟 | ✅ |
49
50
 
50
- **仅改 CSS / 文案 / 图标 / 布局**（无事件处理、无状态、无数据获取）应直接选 `lite`——更快且 token 消耗显著低，不要默认走 standard 浪费配额；但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。testRequirements 里出现"点击"、"填写"、"提交"等动词，**禁止** `lite`，必须 `standard`。
51
+ **缺省即 `lite`**——但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。**只有用户明确要求跑功能**（testRequirements 里出现"点击"、"填写"、"提交"等动词，或用户直接要求验证某功能）时，才传 `standard`。
51
52
 
52
53
  ## 工具选择速查表
53
54
 
54
55
  | 用户表达 | 选择 | 原因 |
55
56
  | --- | --- | --- |
56
- | "检查一下页面" / "看看有没有问题" / "走一遍流程" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E（standard） | 打开浏览器以用户视角操作 / 复现 |
57
- | "刚改了 CSS，看看样式对不对" | E2E（lite） | 仅视觉巡检，省时省 token |
57
+ | "检查一下页面" / "看看有没有问题" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E（lite，缺省） | 未主动要求跑功能，默认视觉巡检 |
58
+ | "刚改了 CSS，看看样式对不对" | E2E（lite） | 仅视觉巡检 |
59
+ | "点提交试试能不能成功" / "帮我把下单流程走一遍" / "走一遍流程" / "验证一下这个功能" | E2E（standard） | 用户明确要求功能 / 交互验证 |
58
60
  | "测试一下这个接口的返回值对不对" / "调一下后端 API 看看响应" | `api_request` | 明确指定接口验证 |
59
61
 
60
62
  ## 派遣 E2E 时的 prompt / 用例规范
@@ -215,6 +217,7 @@ E2E 派遣是**昂贵操作**（每次消耗大量 token + 时间）。E2E agent
215
217
  | E2E 完成后又调 `api_request` 补充验证 | 浏览器操作结果即为最终结果，不追加 |
216
218
  | 用户说"看看有没有 bug"就同时调两个 | 只派遣 E2E |
217
219
  | 用户说"检查接口"时派遣 E2E | 明确提到接口时用 `api_request` |
218
- | 仅改 CSS / 文案，仍走 `standard` | 优先用 `lite`，速度快、token 消耗低 |
220
+ | 用户没主动要求跑功能，却默认传 `standard` | 缺省走 `lite`；仅用户明确要求交互 / 功能验证才传 `standard` |
221
+ | 仅改 CSS / 文案，仍走 `standard` | 优先用 `lite` |
219
222
  | 达到停止条件（≥3 轮 / 同一错误未改代码连续失败）仍继续派 E2E | 停止派遣，转为根因分析（读代码 / 查日志） |
220
223
  | 复测时全量重测 / 白屏直接再派一轮 | 只传 failed + 未完成的 Case；白屏先重启 devServer 再复测 |
package/miaoda-modern/testing-guide/SKILL.md CHANGED
@@ -28,31 +28,33 @@ gate-tools:
28
28
  用户想确认应用是否正常
29
29
  ├─ 明确要求验证「后端接口」「API 返回值」「请求响应」 → api_request
30
30
  └─ 其他所有情况 → Task(subagent_type="E2E")（打开浏览器，以用户视角操作应用）
31
- ├─ 只看视觉（白屏/布局/样式/文案）→ agent_options.mode: "lite"
32
- └─ 涉及交互/业务流程/数据 → 不传或 agent_options.mode: "standard"
31
+ ├─ 默认（用户没主动要求跑功能）→ 不传 mode，走 lite（只截图看视觉）
32
+ └─ 用户明确要求验证交互/业务流程/数据（点击/填写/提交/走一遍流程）→ agent_options.mode: "standard"
33
33
  ```
34
34
 
35
35
  - **模糊需求一律派遣 E2E**：未明确提到「接口」「API」「后端」时必须派遣 E2E，不要主动选择 `api_request`
36
+ - **默认走 lite，standard 需用户明确要求功能测试**：用户没有主动要求跑具体功能（只说"看看有没有问题"这类模糊需求也算没主动要求）时，一律不传 mode 走 `lite`；只有用户明确要验证交互 / 业务流程 / 数据（点击、填写、提交、走一遍流程等）时才传 `agent_options.mode: "standard"`
36
37
  - **`api_request` 仅限显式请求**：仅当明确提到接口 / API / 后端 / 请求 / 响应、且意图是验证接口逻辑而非页面功能时才使用
37
38
  - **E2E 结束后禁止追加 `api_request`**：浏览器操作的结果即为最终结果，**严禁**再自动补充验证
38
39
 
39
40
  ### E2E 的 mode 选择
40
41
 
41
- 通过 `agent_options.mode` 指定，**可选参数**，不传或非 `lite` 一律按 `standard` 处理：
42
+ 通过 `agent_options.mode` 指定，**可选参数**，不传或非 `standard` 一律按 `lite` 处理：
42
43
 
43
44
  | mode | 适用场景 | 行为 | 总超时 | 录屏 |
44
45
  |------|---------|------|-------|------|
45
- | `standard`（缺省） | 涉及业务流程、数据流、交互后状态变化 | 完整交互（点击/输入/滚动/提交）+ Network 验证 + 录制 | 5 分钟 | ✅ |
46
- | `lite` | 只看视觉渲染（CSS/布局/文案/图标）或快速冒烟 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`，**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
46
+ | `lite`（缺省） | 只看视觉渲染（CSS/布局/文案/图标）、快速冒烟，或用户未主动要求跑功能的模糊验收 | 仅 `open` / `goto` / `wait` / `snapshot` / `screenshot`，**禁止** `click` / `fill` / `type` / `scroll` / `select` / `press` / `drag` / `hover` | 2 分钟 | ❌ |
47
+ | `standard` | **仅当用户明确要求**验证业务流程、数据流、交互后状态变化 | 完整交互（点击/输入/滚动/提交）+ Network 验证 + 录制 | 5 分钟 | ✅ |
47
48
 
48
- **仅改 CSS / 文案 / 图标 / 布局**（无事件处理、无状态、无数据获取）应直接选 `lite`——更快且 token 消耗显著低，不要默认走 standard 浪费配额；但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。testRequirements 里出现"点击"、"填写"、"提交"等动词，**禁止** `lite`，必须 `standard`。
49
+ **缺省即 `lite`**——但 `lite` 不能触发 popup / toast / 提交后状态切换等需要操作的现象。**只有用户明确要求跑功能**（testRequirements 里出现"点击"、"填写"、"提交"等动词，或用户直接要求验证某功能）时，才传 `standard`。
49
50
 
50
51
  ## 工具选择速查表
51
52
 
52
53
  | 用户表达 | 选择 | 原因 |
53
54
  | --- | --- | --- |
54
- | "检查一下页面" / "看看有没有问题" / "走一遍流程" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E（standard） | 打开浏览器以用户视角操作 / 复现 |
55
- | "刚改了 CSS，看看样式对不对" | E2E（lite） | 仅视觉巡检，省时省 token |
55
+ | "检查一下页面" / "看看有没有问题" / "哪里出问题了" / "试试能不能用" / "XX 不好使" | E2E（lite，缺省） | 未主动要求跑功能，默认视觉巡检 |
56
+ | "刚改了 CSS，看看样式对不对" | E2E（lite） | 仅视觉巡检 |
57
+ | "点提交试试能不能成功" / "帮我把下单流程走一遍" / "走一遍流程" / "验证一下这个功能" | E2E（standard） | 用户明确要求功能 / 交互验证 |
56
58
  | "测试一下这个接口的返回值对不对" / "调一下后端 API 看看响应" | `api_request` | 明确指定接口验证 |
57
59
 
58
60
  ## 派遣 E2E 时的 prompt / 用例规范
@@ -213,6 +215,7 @@ E2E 派遣是**昂贵操作**（每次消耗大量 token + 时间）。E2E agent
213
215
  | E2E 完成后又调 `api_request` 补充验证 | 浏览器操作结果即为最终结果，不追加 |
214
216
  | 用户说"看看有没有 bug"就同时调两个 | 只派遣 E2E |
215
217
  | 用户说"检查接口"时派遣 E2E | 明确提到接口时用 `api_request` |
216
- | 仅改 CSS / 文案，仍走 `standard` | 优先用 `lite`，速度快、token 消耗低 |
218
+ | 用户没主动要求跑功能，却默认传 `standard` | 缺省走 `lite`；仅用户明确要求交互 / 功能验证才传 `standard` |
219
+ | 仅改 CSS / 文案，仍走 `standard` | 优先用 `lite` |
217
220
  | 达到停止条件（≥3 轮 / 同一错误未改代码连续失败）仍继续派 E2E | 停止派遣，转为根因分析（读代码 / 查日志） |
218
221
  | 复测时全量重测 / 白屏直接再派一轮 | 只传 failed + 未完成的 Case；白屏先重启 devServer 再复测 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lark-apaas/coding-miaoda-sandbox-skills",
3
- "version": "0.1.0-dev.6f4e4bc",
3
+ "version": "0.1.0-dev.7b2c2ad",
4
4
  "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
5
5
  "type": "module",
6
6
  "files": [