\r \r

Clawshop Skill\r

\r Clawshop 自动带货客户端。装上即用，账号密码登录后所有 AI key、采集系统、视频生成全部由我方服务器统一管理，用户零配置。\r \r

跟 clawshop skill 的区别： clawshop 是 SaaS 客户端，走 /api/v1/* + Bearer token + 短轮询事件队列。\r \r

⚠️ 铁律\r

\r

• 发完审核卡片后绝对不发任何额外消息。 不发"分镜出来了""等老板点按钮""已确认生成中"等。\r
• 每个流程最多 1 次 exec + 1 次 message。 不允许拆分。\r
• 遇到异常（超时/失败）唯一允许的动作：告诉老板"XX失败了，原因是YY"，然后等指示。\r
• 不偷偷换方案、不改卡片格式、不改流程。\r \r

⛔ 龙虾不准解读脚本 stdout（铁律）\r

\r 龙虾只负责调脚本 + NO_REPLY。所有给老板看的提示（未登录/登录失败/网络错误/账号密码错误等）一律由脚本内部 ct.send_text() 发出。\r \r

• 龙虾不准根据脚本 stdout 的 {"ok": false, "reason": "..."} 自己编话给老板\r
• 龙虾不准把 reason: not_logged_in 解读成"接口 404"、"服务挂了"、"请登录"等任何文字\r
• 龙虾不准根据 recommend_status / ack_status 等数字自己判断状态\r
• 脚本的 stdout 是给程序/调试看的，不是给老板看的\r
• 老板要看的所有文字，必须由脚本通过 send_text 主动推到 Discord\r \r 正确流程：\r

收到触发 → exec 调脚本 → 脚本内部决定发什么消息 → NO_REPLY\r
```\r
\r
**❗ 例外：Discord 斜杠命令触发时，不能 NO_REPLY！**\r
\r
Discord 斜杠命令要求 3 秒内必须有可见回复，否则显示“Command produced no visible reply”。\r
\r
当触发来源是 `/clawshop` 斜杠命令时：\r
```\r
收到 /clawshop → 发一条短 ack 文本（给 Discord 斜杠命令回复）→ exec 调脚本 → 回复结束（不再补话）\r
```\r
\r
**ack 文本模板（必须用这个，不许改）：**\r
- 未登录：`🔑 还未登录 Clawshop。请回复：\`登录 用户名 密码\``\r
- 无 URL：`⏳ 已启动热门推荐，带到合适的视频再给您发审核卡。`\r
- 有 URL：`⏳ 指定视频已接收，正在抓取分析，完成后给您发审核卡。`\r
- 登录成功：`✅ 登录成功，开始推荐...`\r
- 登录失败：`❌ 账号密码错误，请确认后重试。`\r
\r
ack 后不再补任何进度消息，等 cron 轮询拿到事件后自动发卡片。\r
\r
这句 ack 是给 Discord interaction 的回复，不算“额外消息”，不违反铁律。\r
\r
**错误示范（绝对禁止）：**\r
```\r
收到触发 → exec 调脚本 → 看 stdout reason → 自己组织语言告诉老板\r
```\r
\r
**为什么这样要求：** 以后会有多个用户用这个 skill，逻辑必须沉淀在代码里。龙虾每次解读 stdout 编话，不同用户/不同会话给出的回答就不一致，且代码无法演进。所有提示语统一由脚本管理才能保持一致行为。\r
\r
---\r
\r
## 一、整体架构\r
\r
```\r
用户 OpenClaw 实例\r
  ├── clawshop skill（本 skill）\r
  │   ├── data/\r
  │   │   ├── token.json          ← 登录后存\r
  │   │   ├── card_map.json       ← 短编号 ↔ video_id 映射\r
  │   │   └── processed_events.json ← 已处理事件去重\r
  │   └── lib/                    ← 全部脚本\r
  └── 用户配置的 Discord 频道（OpenClaw 自带）\r
\r
→ data-service（我方服务器，单一来源）\r
   └── /api/v1/*  接口 + 事件队列\r
```\r
\r
---\r
\r
## 二、用户使用流程\r
\r
### 2.0 安装后命令自动注册\r
\r
用户 `clawhub install clawshop` 装上 skill 后，需要让 `/clawshop` 在用户的 Discord 服务器里立刻生效。\r
\r
**为什么不能依赖 OpenClaw 默认同步？**\r
OpenClaw 默认把 skill 命令同步为 Discord **global command**。Global command 在 Discord 端有最长 1 小时缓存，用户装完看不到命令体验差。\r
\r
**解决方案：guild command（无缓存，立刻生效）**\r
skill 提供 `lib/register_discord.py`，调 Discord REST API 把命令注册到 bot 加入的所有 guild，注册完用户立刻能在输入框看到 `/clawshop`。\r
\r
**运行时机：**\r
- skill 首次安装后 → 提示老板跑一次\r
- bot 加入新 guild 后 → 重跑一次（幂等，重复跑不出错）\r
\r
**命令：**\r
\r
```\r
python ./lib/register_discord.py\r
```\r
\r
**输出示例：**\r
\r
```json\r
{\r
  "ok": true,\r
  "app_id": "1496036936996093992",\r
  "guild_count": 1,\r
  "results": [\r
    {\r
      "guild": "用户的服务器",\r
      "guild_id": "...",\r
      "status": 201,\r
      "ok": true,\r
      "cmd_id": "..."\r
    }\r
  ]\r
}\r
```\r
\r
**从 OpenClaw 主会话中调用：**\r
老板可以说“注册 clawshop 命令”或“注册服务器命令”，龙虾直接 `exec: python ./lib/register_discord.py` 跑一次即可。\r
\r
### 2.1 首次（脚本内部自己处理，龙虾只负责调脚本）\r
\r
```\r
1. /clawshop → 龙虾 exec trigger.py ""\r
2. trigger.py 检测 token.json 不存在 → 自己 send_text("🔑 请登录：登录 用户名 密码")\r
3. 老板回：登录 alice ****\r
4. 龙虾 exec trigger.py "登录 alice ****"\r
5. trigger.py POST /api/v1/auth/login → token 存本地 → 自己 send_text("✅ 登录成功，开始推荐...")\r
6. trigger.py 自动 POST /api/v1/recommend + 启动 cron 轮询\r
7. cron 拿到 review_1 事件 → 发卡片\r
```\r
\r
### 2.2 后续\r
\r
```\r
1. /clawshop → 龙虾 exec trigger.py ""\r
2. trigger.py 检测有 token → 直接 POST /api/v1/recommend → 启动轮询\r
3. cron 拿到事件 → 发卡片 → 老板点按钮 → 调对应 API → 继续轮询\r
4. 流程结束（review_2 通过/放弃）→ 停止轮询\r
```\r
\r
**注意：** Token 自动保存在 `data/token.json`，登录一次后永不需要重复登录，除非服务端把 token 标记失效（401，脚本会自动清本地 token 并 send_text 提示重新登录）。\r
\r
---\r
\r
## 三、触发方式\r
\r
响应：\r
- `/clawshop` Discord 斜杠命令（可选 `url:` 参数）\r
- `/推荐` 命令\r
- 文字消息含 URL（如 `推荐 https://...`）\r
- 系统提示 `Use the "clawshop" skill for this request.`\r
- 含"登录 xxx yyy"格式的消息（首次登录用）\r
\r
### 3.1 URL 提取规则\r
\r
```python\r
import re\r
def extract_url(msg: str) -> str | None:\r
    if not msg:\r
        return None\r
    s = msg.strip()\r
    s = re.sub(r'^\s*(/clawshop|/推荐|推荐|来一个)\s*', '', s, flags=re.I)\r
    s = re.sub(r'^\s*url\s*[:：]\s*', '', s, flags=re.I)\r
    s = s.strip().strip('\x3C>').strip('"\'「」『』').strip()\r
    if re.match(r'^https?://', s, flags=re.I):\r
        return s\r
    return None\r
```\r
\r
### 3.2 登录指令识别\r
\r
老板首次登录会发：`登录 用户名 密码` 或 `login user pass`。\r
\r
```python\r
import re\r
m = re.match(r'^\s*(登录|login)\s+(\S+)\s+(\S+)\s*$', msg)\r
if m:\r
    username, password = m.group(2), m.group(3)\r
```\r
\r
### 3.3 触发统一脚本\r
\r
**所有 exec 命令必须带 `workdir` 参数，指向本 skill 目录（即 SKILL.md 所在目录）。**\r
\r
```\r
exec: python ./lib/trigger.py "\x3C老板原始消息文本>"\r
workdir: \x3C本 skill 目录>\r
```\r
\r
实际调用时，模型应该用 exec 工具的 workdir 参数：\r
```json\r
{"command": "python ./lib/trigger.py \"\x3C消息>\"", "workdir": "\x3Cskill目录绝对路径>"}\r
```\r
\r
Skill 目录路径可通过 `SKILL.md` 所在位置确定，不同系统不同：\r
- Windows: `C:\Users\xxx\openclaw\skills\clawshop-pro`\r
- macOS: `/Users/xxx/openclaw/skills/clawshop-pro`\r
- Linux: `/home/xxx/openclaw/skills/clawshop-pro`\r
```\r
\r
脚本内部：\r
\r
1. **解析消息**\r
   - 是 `登录 xxx yyy` → 走登录流程\r
   - 否 → 走推荐流程\r
\r
2. **登录流程**\r
   - POST `/api/v1/auth/login` `{username, password}`\r
   - 成功 → 存 token 到 `data/token.json` → 发"✅ 登录成功，开始推荐"消息 → 继续走推荐流程\r
   - 失败 → 发"❌ 账号密码错误"消息 → 退出\r
\r
3. **推荐流程**\r
   - 检查本地 `token.json`：不存在 → 发"请先登录：`登录 用户名 密码`" → 退出\r
   - 提取 URL（同 3.1 规则）\r
   - 立即发 ack 文本到 Discord（解决斜杠命令 3s 超时）\r
     - 无 URL：`⏳ 已启动热门推荐，捐到合适的视频再给您发审核卡片。`\r
     - 有 URL：`⏳ 指定视频已接收，正在抓取分析，完成后给您发审核卡片。\
\x3Curl>`\r
   - POST `/api/v1/recommend` `{}` 或 `{"video_url": "..."}`\r
   - **启动 cron 轮询任务**（见第六节）\r
   - 脚本退出，本轮 NO_REPLY\r
\r
**绝对禁止：** 直接 `requests.post(...)` 绕开脚本；拆成多次 tool call。\r
\r
---\r
\r
## 四、API 客户端\r
\r
所有 `/api/v1/*` 接口共用同一个客户端（`lib/api.py`），自动加 `Authorization: Bearer \x3Ctoken>` header。\r
\r
### 4.1 业务接口（9 个）\r
\r
| 函数 | 路径 | 说明 |\r
|---|---|---|\r
| `login(u, p)` | `POST /api/v1/auth/login` | 拿 token |\r
| `recommend(url=None)` | `POST /api/v1/recommend` | 启动推荐 |\r
| `task_approve(vid, step)` | `POST /api/v1/tasks/{vid}/approve` 或 `/{step}/approve` | 通过 |\r
| `task_reject(vid, step)` | `POST /api/v1/tasks/{vid}/reject` | 跳过/放弃 |\r
| `task_change_product(vid)` | `POST /api/v1/tasks/{vid}/change-product` | 换商品 |\r
| `task_storyboard_redo(vid)` | `POST /api/v1/tasks/{vid}/storyboard/redo` | 重做分镜 |\r
| `task_video_redo(vid)` | `POST /api/v1/tasks/{vid}/video/redo` | 重做视频 |\r
\r
### 4.2 事件接口（2 个）\r
\r
| 函数 | 路径 | 说明 |\r
|---|---|---|\r
| `events_pending()` | `GET /api/v1/events/pending` | 拉积压事件 |\r
| `event_ack(eid)` | `POST /api/v1/events/{eid}/ack` | 确认消费 |\r
\r
### 4.3 错误处理\r
\r
- `401 invalid_token` → 删本地 token.json，发"❌ 登录失效，请重新登录：`登录 用户名 密码`"\r
- `403 forbidden` → 发"❌ 操作越权" + 错误内容\r
- `5xx` → 发"❌ 服务器错误，请稍后重试"\r
- 超时 → 发"❌ 请求超时"\r
\r
---\r
\r
## 五、事件处理（核心）\r
\r
### 5.1 事件类型\r
\r
事件格式：\r
\r
| event_type | 触发 | data 字段 | 用户可见提示（脚本内部发） |\r
|---|---|---|---|\r
| `review_1` | 一审就绪 | video_id, video_url, author, view_count, score, summary, product_name, product_url, product_image_url | 发一审卡片（`send_review_1.py`） |\r
| `review_1_5` | 分镜就绪 | video_id, storyboard_url（或 error）| 有 storyboard_url → 发分镜卡片；有 error → `⚠️ 视频 #{n} 分镜生成失败：{error}` |\r
| `review_2` | 视频就绪 | video_id, video_url（或 error）| 有 video_url → 发视频卡片；有 error → `⚠️ 视频 #{n} 生成失败：{error}` |\r
| `published` | 发布完成 | video_id, platform, status | `✅ 视频 #{n} 已成功发布到 {platform}！` |\r
| `no_match` | 没找到 | （空）| `🙅 这轮没找到合适的视频，稍后再试。` |\r
| `error` | 异常 | error_type, message | `⚠️ 服务端异常：{message}` |\r
\r
### 5.1.1 错误事件特殊处理\r
\r
- `error_type: "quota_exhausted"` → `⚠️ API余额不足，无法继续生成。请充值后重试。\
错误详情：{error内容}`\r
- 其他 error_type → `⚠️ 服务端异常：{message}`\r
\r
**所有提示文案由脚本内部 `ct.send_text()` 发出，龙虾不准自己编。**\r
\r
### 5.2 事件处理脚本\r
\r
```\r
exec: python ./lib/poll_events.py\r
```\r
\r
**轮询脚本职责（一次 exec 干完）：**\r
\r
1. 调 `events_pending()` 拉所有未处理事件\r
2. 对每个事件：\r
   - 检查 `processed_events.json`，处理过 → 直接 ack 跳过\r
   - 没处理过 → 按 event_type 分发到对应 send_review_*.py / 处理函数\r
   - 处理成功 → 写入 processed_events + 调 ack\r
3. 检查是否流程结束（review_2 通过、所有 reject、no_match）→ 停止 cron\r
4. 输出 JSON 摘要：`{"processed": N, "stopped": true/false}`\r
\r
### 5.3 子脚本\r
\r
- `lib/send_review_1.py` — 发一审卡片\r
- `lib/send_review_1_5.py` — 发分镜卡片\r
- `lib/send_review_2.py` — 发视频卡片\r
- `lib/handle_button.py` — 按钮回调\r
- `lib/card_tools.py` — 卡片工具（卡片工具）\r
\r
---\r
\r
## 六、Cron 轮询任务\r
\r
### 6.1 启动\r
\r
`lib/trigger.py` 在推荐启动后**注册一个 cron job**：\r
\r
```python\r
# 通过 OpenClaw gateway HTTP API 注册\r
POST http://127.0.0.1:18789/tools/invoke\r
Body: {\r
  "tool": "cron",\r
  "args": {\r
    "action": "add",\r
    "job": {\r
      "name": "clawshop-poll",\r
      "schedule": {"kind": "every", "everyMs": 5000},\r
      "payload": {\r
        "kind": "agentTurn",\r
        "message": "Clawshop 轮询事件: 执行 `python ./lib/poll_events.py`，有事件就处理；处理完后回复 NO_REPLY。",\r
        "lightContext": true\r
      },\r
      "deleteAfterRun": false,\r
      "delivery": {"mode": "none"}\r
    }\r
  }\r
}\r
```\r
\r
**关键参数：**\r
- `everyMs: 5000` — 每 5 秒\r
- `lightContext: true` — 不带历史上下文，省 token\r
- `delivery.mode: "none"` — 不发系统消息，由脚本自己发卡片\r
- `name: clawshop-poll` — 固定 ID 方便后续 update/remove\r
\r
### 6.2 自动停止\r
\r
**触发停止的条件：**\r
1. 流程结束事件（`review_2 approve` / `published` / `reject` 全部 / `no_match`）\r
2. 启动超过 15 分钟（max_duration_seconds）\r
\r
`poll_events.py` 内部检查后调：\r
\r
```python\r
POST http://127.0.0.1:18789/tools/invoke\r
Body: {\r
  "tool": "cron",\r
  "args": {"action": "remove", "id": "clawshop-poll"}\r
}\r
```\r
\r
### 6.3 启动时间记录\r
\r
`data/poll_state.json`：\r
```json\r
{"started_at": 1716180000, "active": true}\r
```\r
\r
每次 `poll_events.py` 启动时检查 `now - started_at > 900` → 强制停止 cron。\r
\r
---\r
\r
## 七、按钮回调\r
\r
收到 `Clicked "✅ 做 #4"` 等按钮消息：\r
\r
```\r
exec: python ./lib/handle_button.py "\x3Cclicked_label>"\r
```\r
\r
**脚本内部：**\r
\r
1. 正则提取 `#\x3Cshort_id>` → 查 card_map → 拿 video_id 和 step\r
2. 按按钮前缀映射到 action，**先发进度消息（不许改）**\r
3. 调对应的 API（不再是 `/clawshop/callback`，而是 `/api/v1/tasks/.../xxx`）：\r
\r
| 按钮 | 阶段 | action | 进度消息（老板可见） | API 调用 |\r
|---|---|---|---|---|\r
| ✅ 做 | review_1 | approve | `⏳ 视频 #{n} 开始生成分镜图，请稍候...` | `task_approve(vid, "review_1")` → `POST /api/v1/tasks/{vid}/approve` |\r
| ⏭️ 换一个 | review_1 | reject + recommend | 无（不发进度） | `task_reject(vid)` + `recommend()` |\r
| 🔄 换商品 | review_1 | change_product | `🔄 正在重新匹配商品...` | `task_change_product(vid)` |\r
| ✅ 分镜通过 | review_1_5 | approve | `⏳ 分镜已确认，正在生成视频提示词和视频，预计8-10分钟...` | `task_approve(vid, "review_1_5")` → `POST /api/v1/tasks/{vid}/storyboard/approve` |\r
| 🔄 重新生成 | review_1_5 | redo | `🔄 正在重新生成分镜图...` | `task_storyboard_redo(vid)` |\r
| ❌ 放弃 | review_1_5/review_2 | reject | `❌ 已放弃视频 #{n}` | `task_reject(vid)` + 删 card_map + 停 cron |\r
| ✅ 通过 | review_2 | approve | `📤 视频 #{n} 正在提交发布...` | `task_approve(vid, "review_2")` → `POST /api/v1/tasks/{vid}/video/approve` |\r
| 🔄 重做 | review_2 | redo | `🔄 视频 #{n} 重新生成中...` | `task_video_redo(vid)` |\r
\r
4. 按钮 review_2 approve / reject 全部 → 删 card_map + 停 cron\r
5. 按钮回调后**继续 cron 轮询**（等下一个事件）\r
\r
---\r
\r
## 八、本地状态文件\r
\r
| 文件 | 用途 | 示例 |\r
|---|---|---|\r
| `data/token.json` | 登录 token | `{"token": "abc...", "username": "alice"}` |\r
| `data/card_map.json` | 短编号 ↔ video_id | `{"date": "2026-05-20", "next_id": 3, "cards": {...}}` |\r
| `data/processed_events.json` | 已 ack 的 event_id 集合 | `{"ids": [1001, 1002, 1003]}` |\r
| `data/poll_state.json` | 轮询启动时间 | `{"started_at": 1716180000, "active": true}` |\r
\r
---\r
\r
## 九、消息处理规则\r
\r
| 收到的消息 | 动作 |\r
|---|---|\r
| `/clawshop` / `/推荐` / `推荐 URL` / 裸 URL | 触发 `lib/trigger.py` |\r
| `登录 xxx yyy` / `login xxx yyy` | 触发 `lib/trigger.py`（脚本内部识别）|\r
| `Clicked "..."` 按钮回调 | 触发 `lib/handle_button.py` |\r
| Cron `Clawshop 轮询事件: ...` | 触发 `lib/poll_events.py` |\r
| 系统提示 `Use the "clawshop" skill ...` | 按上下文判断走哪个脚本 |\r
| HEARTBEAT_OK / inter-session announce | NO_REPLY |\r
\r
---\r
\r
## 十、隔离规则\r
\r
\r
\r
- **绝不调 `/recommend` `/clawshop/callback`，只调 `/api/v1/*`**\r
\r
clawshop 完全独立运行。\r
\r
---\r
\r
## 十一、依赖\r
\r
- data-service（地址在 `config.json` 的 `data_service.base_url`）\r
- OpenClaw gateway（`http://127.0.0.1:18789`）\r
- OpenClaw cron 工具\r
- OpenClaw message 工具（发 Discord 卡片）\r
- 用户配置的 Discord（自带，不依赖特定频道 ID — 由 OpenClaw 路由）\r
\r
---\r
\r
## 十二、注意事项（血泊教训）\r
\r
1. **token 失效后必须删本地 token.json 再提示老板**，不能光提示不删。\r
2. **processed_events.json 防重复发卡片**，必须先写文件再 ack（保证 ack 失败也不会重发）。\r
3. **cron job 启动后必须能停**：流程结束、超时、报错都要停，避免无限轮询烧 token。\r
4. **lightContext: true** 必须设，否则每次轮询都加载全部上下文，token 暴涨。\r
5. **登录消息不要 echo 密码**，"已收到登录请求"就够了。\r
6. **审核卡片走老板自己的 Discord**（OpenClaw message 工具 channel: discord，不指定 channel_id，让 OpenClaw 自动路由到用户配置的频道）。\r
7. **inter-session 来的 HEARTBEAT_OK / Agent-to-agent announce 消息，一律回 `NO_REPLY`。** 回任何其他文字都会被发到 Discord 频道里污染老板的屏幕。\r
8. **收到事件但数据不完整（如 storyboard_url 为空），且没有 error 字段，静默跳过。** 不要跟老板说“还没生成好”之类的废话。\r
9. **任何 review_1 / review_1_5 / review_2 事件进来 → 必须立即调对应 send_review_*.py 发卡片。绝对不允许做“是不是重复”的判断，不允许跳过。** 即使同一个 video_id 反复出现（比如换商品后重推 review_1），也是新卡片，必须发。\r
10. **按钮回调必须查映射文件确认 video_id，不能猜。** 查不到就问老板，不要自己猜。\r
\r
---\r
\r
## 十三、完整提示文案汇总（锁定，不许改）\r
\r
### 斜杠命令 ack\r
\r
| 场景 | 文案 |\r
|---|---|\r
| 未登录 | `🔑 还未登录 Clawshop。\
请回复您的账号和密码（中间用空格隔开），例如：\
\`myname 123456\`` |\r
| 无 URL | `⏳ 已启动热门推荐，带到合适的视频再给您发审核卡。` |\r
| 有 URL | `⏳ 指定视频已接收，正在抓取分析，完成后给您发审核卡。` |\r
| 登录成功 | `✅ 登录成功（用户：{username}），开始推荐...` |\r
| 登录失败 | `❌ 账号密码错误，请确认后重试。` |\r
| 登录异常 | `❌ 登录失败：{error}` |\r
| token 失效 | `❌ 登录已失效，请重新登录：\`登录 用户名 密码\`` |\r
\r
### 按钮回调进度消息\r
\r
| 按钮 | 进度消息 |\r
|---|---|\r
| ✅ 做 #{n} | `⏳ 视频 #{n} 开始生成分镜图，请稍候...` |\r
| ⏭️ 换一个 #{n} | 无（不发进度） |\r
| 🔄 换商品 #{n} | `🔄 正在重新匹配商品...` |\r
| ✅ 分镜通过 #{n} | `⏳ 分镜已确认，正在生成视频提示词和视频，预计8-10分钟...` |\r
| 🔄 重新生成 #{n} | `🔄 正在重新生成分镜图...` |\r
| ❌ 放弃 #{n} | `❌ 已放弃视频 #{n}` |\r
| ✅ 通过 #{n} | `📤 视频 #{n} 正在提交发布...` |\r
| 🔄 重做 #{n} | `🔄 视频 #{n} 重新生成中...` |\r
\r
### 事件提示\r
\r
| 事件 | 提示文案 |\r
|---|---|\r
| review_1 | 发一审卡片（带商品图 + 按钮） |\r
| review_1_5 正常 | 发分镜卡片（带分镜图 + 按钮） |\r
| review_1_5 error | `⚠️ 视频 #{n} 分镜生成失败：{error}` |\r
| review_2 正常 | 发成品视频卡片（带视频 + 按钮） |\r
| review_2 error | `⚠️ 视频 #{n} 生成失败：{error}` |\r
| published | `✅ 视频 #{n} 已成功发布到 {platform}！` |\r
| no_match | `🙅 这轮没找到合适的视频，稍后再试。` |\r
| error (quota_exhausted) | `⚠️ API余额不足，无法继续生成。请充值后重试。\
错误详情：{error}` |\r
| error (其他) | `⚠️ 服务端异常：{message}` |\r
\r
### API 错误\r
\r
| HTTP 状态 | 提示文案 |\r
|---|---|\r
| 401 | `❌ 登录已失效，请重新登录：\`登录 用户名 密码\`` |\r
| 403 | `❌ 操作越权：{error}` |\r
| 404 | `❌ 接口不存在（服务端可能未部署）` |\r
| 5xx | `❌ 服务器错误，请稍后重试` |\r
| 超时 | `❌ 请求超时` |\r
| 网络错误 | `❌ 网络连接失败：{error}` |\r