@optima-chat/optima-agent 0.9.14 → 0.9.16

package/.claude/skills/gen/SKILL.md

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

package/.claude/skills/video-edit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: video-edit
-description: "剪辑用户【已有的】口播视频——去除卡顿停顿让视频更流畅紧凑。
+description: "剪辑用户【已有的】口播视频——去除卡顿停顿、NG 重拍、口头禅让视频更流畅紧凑。
 
   必备前提：用户已经有视频文件（拍好的、上传的、或给出文件路径）。
 
@@ -26,30 +26,50 @@ description: "剪辑用户【已有的】口播视频——去除卡顿停顿让
 只有当用户提到平台但**没说目标时长**时（如"剪成 TikTok"无时长），才追问"目标多长？"。
 其他情况**直接动手**，不要废话。
 
-## 核心原则：一键出片，不满意再调
+## 核心原则：你是语义剪辑器
 
-用户说"剪一下"，你**直接出成片**，不要中途停下来问确认。像开拍 app 一样：上传 → 自动出片 → 不满意再调。
+cut 工具**只能删静音**（>=0.25s 的停顿），它**永远删不了**这些：
+- NG 重拍（重新说一遍同一句）
+- 重复字（"我我我"，发声不停顿）
+- 口头禅（"嗯"/"啊"/"那个"/"就是"）
+- 跑题片段（语法完整但内容废）
 
-**不满意时的调整**：用户看完成片说"第X段不该删"/"XX那句话留着"，你编辑 `cut_proposal.md`（去掉/加上 `#` 注释），重跑 `cut` + `subtitle`，几秒出新版。
+**所以你必须自己审一遍 proposal**——你就是这个流程的语义剪辑器。如果跳过审片直接出片，成片会有大量 NG/口头禅/重复，用户会觉得"非常多卡顿"。
 
 ## 你的内部流程
 
 ### 默认剪辑（剪 + 字幕，最常见）
 
-一步到位，不要分步等确认：
+四步走：
+
+```bash
+video-edit analyze <video>
+```
+
+读 `<video>.work/cut_proposal.md`。每行是一个短语，看每行决定保留还是删除：
+
+- **删（行首加 `#`）**：
+  - 单独的口头禅 phrase："嗯"/"啊"/"呃"/"那个"/"就是"/"对吧"/"然后那个"
+  - NG 重拍：相邻两行说同一件事但措辞稍变（"我们要做的就是——我们要做的是"），**留最后一遍**（通常最干净）
+  - 字面重复："我我我"/"那那那"
+  - 跑题/废话：与主题无关的旁白、自语、笑场
+  - 太短的连接词单独成行（如只有"那"/"嗯啊"）
+- **留**：所有有信息量的句子
+
+按上述规则编辑 proposal，保存。然后：
+
 ```bash
-video-edit both <video>
+video-edit cut <video>
 video-edit subtitle <video>
 ```
 
-`both` = analyze + cut，一口气完成转写、静音检测、生成 proposal、执行剪辑。
-`subtitle` 从原始转写推算字幕时间轴（不会重新调 whisper），烧录输出 `<原片>_subbed.mp4`。
+`cut` 按你标注的 proposal 剪辑，`subtitle` 对成片重新转写并烧字幕。
 
 ### 用户要求调整时
 
 用户看完成片说某段不对：
-1. 读 `<video>.work/cut_proposal.md`
-2. 编辑对应行（`#` 注释 = 删除，去掉 `#` = 保留）
+1. 重新读 `<video>.work/cut_proposal.md`
+2. 调整对应行（`#` 注释 = 删除，去掉 `#` = 保留）
 3. 删除 `<video>.work/subs.ass`（让 subtitle 重新生成）
 4. 重跑：
 ```bash
@@ -61,22 +81,10 @@ video-edit subtitle <video>
 
 ### 限时长精剪（用户给了目标时长）
 
-```bash
-video-edit analyze <video>
-```
-
-读 `<video>.work/cut_proposal.md`，**你自己**做这些判断：
+`analyze` → 审 proposal 时**额外做这些**：
 - 找钩子句放最前
-- 删跑题、删 NG、删填充词
-- 压到目标时长
-- 把要删的行首加 `#`，保存
-- 删除 `<video>.work/subs.ass`
-
-然后：
-```bash
-video-edit cut <video>
-video-edit subtitle <video>
-```
+- 压到目标时长（更激进地删）
+- 其余流程同上
 
 ### 仅字幕（用户明确说不剪）
 
@@ -89,11 +97,24 @@ video-edit subtitle <video>
 ### 无字幕版（用户明确说不要字幕）
 
 ```bash
-video-edit both <video>
+video-edit analyze <video>
+# 审 proposal 标 #
+video-edit cut <video>
 ```
 
 交付 `<原片>_edited.mp4`，不跑 subtitle。
 
+## 审片心法
+
+读 proposal 时**不要逐行纠结**——每行 1 秒判断，按这个决策树：
+
+1. 这行只有口头禅/单字 → `#`
+2. 这行跟前一行/后一行说同一件事 → 留信息量最高的那遍
+3. 这行内容跟主题无关 → `#`
+4. 其他 → 留
+
+**追求"看着不卡"，不追求 100% 完美**。删多了用户会说"这句要留"，你再调；删少了成片很卡，用户体验更差。**宁可激进一点**。
+
 ## 交付怎么说
 
 简洁，**只说结果**：
@@ -101,13 +122,13 @@ video-edit both <video>
 - ✅ "剪好了，xxx_subbed.mp4，时长 23 秒"
 - ✅ "无字幕版剪好了，xxx_edited.mp4，时长 23 秒"
 - ❌ "我用了 video-edit analyze，然后编辑了 cut_proposal.md..."
-- ❌ "review 显示 3 个 WARN，但都不影响..."
+- ❌ "审片删了 8 行 NG..."
 
 ## 不要做的事
 
-- ❌ 用户说"剪一下"就追问平台/钩子/时长——直接 `both` + `subtitle`
+- ❌ 跳过审 proposal 直接 `both` 出片——必有大量卡顿
+- ❌ 用户说"剪一下"就追问平台/钩子/时长——按默认流程动手
 - ❌ 用户说"剪一下"只交付 `_edited.mp4` 不烧字幕——**默认带字幕**
-- ❌ 剪之前停下来展示方案等确认——**直接出片**，不满意再调
 - ❌ 把命令名、cut_proposal.md 路径暴露给用户——内部实现细节
 - ❌ 编造命令（仅 5 个：both / analyze / cut / review / subtitle）
 - ❌ 用户说"剪掉前 X 秒"/"剪掉中间一段"——定点裁剪不是去卡顿，告诉用户"我擅长去卡顿停顿，定点裁剪请用别的方式"
@@ -116,8 +137,8 @@ video-edit both <video>
 
 | 命令 | 用途 |
 |---|---|
-| `video-edit both <video>` | **默认用这个**：analyze + cut 一步到位 |
-| `video-edit analyze <video>` | 仅转写 + 生成 proposal（限时长精剪时用） |
+| `video-edit analyze <video>` | 转写 + 生成 proposal（**默认入口**，审完后跑 cut） |
 | `video-edit cut <video>` | 按 proposal 剪辑，生成 `_edited.mp4` |
+| `video-edit subtitle <video>` | 对成片重新转写 + 烧字幕，输出 `<原片>_subbed.mp4` |
+| `video-edit both <video>` | analyze + cut 一步到位（**已弃用**：跳过审片质量差） |
 | `video-edit review <video>` | 诊断用：检查 `_edited.mp4`，输出 review_report.md |
-| `video-edit subtitle <video>` | 烧字幕。传**原片路径**，自动找 `_edited.mp4` 做输入，输出 `<原片>_subbed.mp4` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/optima-agent",
-  "version": "0.9.14",
+  "version": "0.9.16",
   "description": "基于 Claude Agent SDK 的电商运营 AI 助手",
   "type": "module",
   "main": "dist/src/index.js",