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

package/miaoda/ai-data-processing/SKILL.md

@@ -47,6 +47,8 @@ SELECT * FROM rds_ai.list_model();
 
 按业务需求选定模型，取其 `model_name` 作为第二个参数。
 
+⚠️ **模型可用性由租户管理后台管控。** `list_model()` 返回的是平台预置清单；管理员下架或停用其中某个模型后，平台自动在其余可用预置模型中选择，业务 SQL 无需改动。因此除非用户明确要求锁定模型，否则不传 `model_name`；锁定的模型被停用时，加工结果可能出现风格波动。预置模型全部不可用时调用直接失败，处置见「关键注意事项」。
+
 ## 实现步骤
 
 以下 SQL 使用 `tickets` / `priority` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键和 `task_kind`。
@@ -378,10 +380,11 @@ LIMIT 20;
 | ❌ 业务事务路径（同步 trigger / 大批量 UPDATE）里直接调 `rds_ai.ai_query` | HTTP 调用会因网络抖动、限流、超时、模型异常抛错，阻塞业务写入、占锁并产生大额模型调用 | trigger 只入队，模型调用统一由 `ai_run_pending_jobs()` 的 EXCEPTION 块兜住；批量场景先小样本验证，再经 `ai_job` 分批处理 |
 | ❌ 422 / `quota_exceeded` 报错后继续重试 | 当前应用 AI 调用额度已用完，重试只会继续报错 | 任务直接置 `failed`、停止入队，续费后批量重跑；提示用户「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」 |
 | ❌ 429 / `rate_limit_exceeded` 报错后原速重跑 | 调用过于密集触发限流 | 保持重试 + 指数退避；调小 `ai_run_pending_jobs` 单次批量、放慢 worker 节奏；提示用户「AI 调用过于频繁触发了限流，已自动放慢节奏，稍后会继续跑完」 |
+| ❌ 500 / `model_unavailable` 报错后继续重试或继续入队 | 租户预置模型已被全部下架或停用，平台无模型可选，重试不会恢复 | 任务置 `failed` 并停止入队；提示用户「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」；模型恢复后重跑失败任务即可 |
 | ❌ prompt 不约束输出格式 | 解释性文本会作为脏值写回业务表 | 分类任务写清枚举值并在 SQL 函数里校验结果；JSON 抽取写清 JSON schema |
 | ❌ trigger 只靠 `UPDATE OF <col>` 判断变化 | 无关更新会重复入队、重复消耗 | 函数里再用 `IS NOT DISTINCT FROM` 判断源字段变化 |
 
-`rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
+`rds_ai.ai_query` 抛错时，PG 错误信息通常带 HTTP 状态码（422 / 429 / 500）或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字；失败任务停在 `ai_job` 表，错误码可从 `error_message` 字段读出供 UI 展示和告警归类。
 
 **禁止**的写法（会阻塞业务写入事务）：
 

package/miaoda/semantic-search/SKILL.md

@@ -57,6 +57,8 @@ SELECT rds_ai.ai_embed('你好')::vector;
 -- → vector(1024)
 ```
 
+⚠️ **模型可用性由租户管理后台管控。** embedding 仅此一个模型、无备选，管理员将其下架或停用后 `rds_ai.ai_embed` 即不可用，调用报 `model_unavailable`（处置见「关键注意事项」）。
+
 ## 实现步骤
 
 以下 SQL 使用 `products` / `embedding` 作为示例。Agent 生成实际方案时，必须替换成用户应用里的真实表名、字段名、主键、返回列和索引名。
@@ -281,14 +283,15 @@ LIMIT 10;
 
 ## 关键注意事项
 
-### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流)
+### ⚠️ ai_embed 报错优先看状态码：422 (额度不足) / 429 (限流) / 500 (无可用模型)
 
-`rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` 关键字。识别后给用户的提示要分开：
+`rds_ai.ai_embed` 抛错时，PG 错误信息里通常会带 HTTP 状态码或 `quota_exceeded` / `rate_limit_exceeded` / `model_unavailable` 关键字。识别后给用户的提示要分开：
 
 - **422 / quota_exceeded** — 当前应用的 AI 调用额度已用完。提示用户：「AI 调用额度已耗尽，请联系应用 Owner 在控制台续费或升级套餐后再试」。**不要重试**，重试只会继续报错。
 - **429 / rate_limit_exceeded** — 调用过于密集触发限流。提示用户：「AI 调用过于频繁触发了限流，稍后再试，或调小回填批次 / 降低并发即可恢复」。**可重试**，建议指数退避。
+- **500 / model_unavailable** — 租户预置的 embedding 模型已被管理员下架或停用，且无备选模型。提示用户：「当前租户无可用 AI 模型，请联系租户管理员恢复后再试」。**不要重试**，模型恢复后重跑存量回填即可。
 
-trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑。
+trigger 已经用 `EXCEPTION WHEN OTHERS THEN NEW.embedding := NULL` 兜住单条失败，业务写入不会回滚；后续走存量回填补齐。批量回填（步骤 7）建议捕获错误码：遇到 422 立刻停止整批并提示续费，遇到 429 退避后续跑，遇到 500 停整批并提示联系租户管理员。
 
 ### ⚠️ 同步 trigger 调 rds_ai.ai_embed 必须 BEGIN/EXCEPTION 兜底
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-miaoda-sandbox-skills",
-  "version": "0.1.0-dev.942e73f",
+  "version": "0.1.0-dev.b2f659e",
   "description": "Miaoda 合并沙箱 skills 包（包含原 miaoda-skills 的 miaoda / miaoda-modern / miaoda-design / shared 四条业务线）；发布公网 npm，随沙箱运行时经 update-skills 同步到 .agent/skills/",
   "type": "module",
   "files": [