@optima-chat/optima-agent 0.9.14 → 0.9.15
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.
- package/.claude/skills/gen/SKILL.md +48 -0
- package/package.json +1 -1
|
@@ -277,3 +277,51 @@ gen task get <task_id> # 查看任务详情
|
|
|
277
277
|
gen task cancel <task_id> # 取消任务
|
|
278
278
|
gen task retry <task_id> # 重试失败的任务
|
|
279
279
|
```
|
|
280
|
+
|
|
281
|
+
## 错误处理（重要）
|
|
282
|
+
|
|
283
|
+
所有 `gen` 命令在失败时会返回结构化错误。**不要把原始 `error_message`（可能是中文报错）直接抛给用户**——根据 `error_code` 字段决定应对策略。
|
|
284
|
+
|
|
285
|
+
### 失败响应示例
|
|
286
|
+
|
|
287
|
+
```json
|
|
288
|
+
{
|
|
289
|
+
"success": true,
|
|
290
|
+
"data": {
|
|
291
|
+
"task_id": "abc-123",
|
|
292
|
+
"status": "failed",
|
|
293
|
+
"error_code": "UPSTREAM_MAINTENANCE",
|
|
294
|
+
"retryable": true,
|
|
295
|
+
"error_message": "上游生成服务正在维护中，请稍后再试"
|
|
296
|
+
}
|
|
297
|
+
}
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
注意：`success: true` + `status: "failed"` 是任务执行完成但生成失败；`success: false` 才是 CLI 调用本身失败。两者都要按 `error_code` 处理。
|
|
301
|
+
|
|
302
|
+
### 处理对照表
|
|
303
|
+
|
|
304
|
+
| `error_code` | 你应该做的 | 给用户的话术（参考） |
|
|
305
|
+
|---|---|---|
|
|
306
|
+
| `UPSTREAM_MAINTENANCE` | **不立即重试**。告知用户服务维护中，建议 5-10 分钟后再试 | "图片生成服务正在维护，建议 5-10 分钟后我再帮您试一次" |
|
|
307
|
+
| `CONTENT_POLICY_VIOLATION` | **改写 prompt** 去掉敏感/违规元素，自动重试**最多 1 次**。仍失败再交给用户 | "您的描述触发了内容审核，我换个说法重试：……" |
|
|
308
|
+
| `UPSTREAM_TIMEOUT` | 立即重试 1 次（静默） | （重试成功就别提；连续失败再说） |
|
|
309
|
+
| `UPSTREAM_RATE_LIMITED` | 等 30 秒后重试 1 次 | "请求频率过高，稍等几十秒再试" |
|
|
310
|
+
| `UPSTREAM_NETWORK` | 立即重试 1 次（静默） | （同 timeout） |
|
|
311
|
+
| `PROVIDER_INSUFFICIENT_CREDITS` | **不重试**。明确告诉用户问题不在他、不在他的余额 | "生成服务后端额度不足（与您账户余额无关），已记录" |
|
|
312
|
+
| `UPSTREAM_UNKNOWN` 或字段缺失 | **不重试**。把 `error_message` 透传给用户 | "图片生成失败：{error_message}" |
|
|
313
|
+
|
|
314
|
+
### 通用规则
|
|
315
|
+
|
|
316
|
+
1. **`retryable: true`** 的失败：自动重试**最多 1 次**，不要循环
|
|
317
|
+
2. **`retryable: false`**：永远不重试，立即给用户结果
|
|
318
|
+
3. 改写 prompt 重试时，**告诉用户你做了什么改动**（透明）
|
|
319
|
+
4. `success: false`（CLI 本身报错）直接报给用户，不重试
|
|
320
|
+
5. 没有 `error_code` 字段的旧版响应：当作 `UPSTREAM_UNKNOWN` 处理
|
|
321
|
+
|
|
322
|
+
### 反面示例（不要这样做）
|
|
323
|
+
|
|
324
|
+
❌ 把 `"维护中"` 三个字直接砸给用户
|
|
325
|
+
❌ 任何失败都自动 retry 三五次造成账单浪费
|
|
326
|
+
❌ `CONTENT_POLICY_VIOLATION` 时换汤不换药地原 prompt 重试
|
|
327
|
+
❌ `PROVIDER_INSUFFICIENT_CREDITS` 时让用户去充值（这跟用户余额无关）
|