init

2026-06-30 15:02:20 +08:00
commit 3948b5a48a
306 changed files with 77275 additions and 0 deletions
@@ -0,0 +1,109 @@
+# LocalMiniDrama OpenClaw Skill
+
+让用户通过 OpenClaw（小龙虾）自然语言控制 LocalMiniDrama，完成 AI 短剧从剧本到成片的全流程。
+
+## 版本
+
+`1.1.0` — 完整覆盖后端 API，修复路径前缀，新增角色/场景/道具/AI配置/工程导入导出/小说导入等能力。
+
+## 安装
+
+### 方式一：本地安装
+
+```bash
+# 复制到 OpenClaw workspace skills 目录
+cp -r ./openclaw-skill ~/.openclaw/workspace/skills/local-mini-drama
+```
+
+### 方式二：发布到 SkillHub / ClawHub（后续）
+
+```bash
+skillhub publish ./openclaw-skill
+```
+
+## 配置
+
+### 云服务器用户
+
+```bash
+openclaw skill config local-mini-drama --set base_url=http://你的服务器IP:5679
+```
+
+### 本地电脑用户（需内网穿透）
+
+```bash
+# 假设你用 cpolar 绑定了 localhost:5679
+openclaw skill config local-mini-drama --set base_url=https://xxx.cpolar.io
+```
+
+### 可选配置
+
+```bash
+# 默认画面比例（16:9 横屏 / 9:16 竖屏 / 1:1 方形）
+openclaw skill config local-mini-drama --set default_aspect_ratio=9:16
+
+# 默认单个视频片段时长（秒）
+openclaw skill config local-mini-drama --set default_video_duration=5
+```
+
+## 使用方法
+
+在 OpenClaw 中对话即可触发：
+
+| 用户输入 | 触发动作 |
+|---------|---------|
+| "帮我创建一个仙侠短剧" | 创建项目 + 流式生成剧本 |
+| "生成一个都市爱情短剧，讲述..." | 完整流程：创建+剧本+角色+分镜+图片+视频 |
+| "生成本集分镜" | 为当前集数生成分镜 |
+| "批量生成图片" | 批量出图 |
+| "批量生成视频" | 批量出视频 |
+| "合成这集视频" | 触发视频合成 |
+| "这集做好了吗" | 查询合成进度 |
+| "给李逍遥生成一张图" | 生成角色形象图 |
+| "导出这个工程" | 导出 ZIP |
+| "我有篇小说，帮我制作短剧" | 小说导入 + 生成 |
+| "配置一下通义千问" | AI 配置管理 |
+
+## API 覆盖范围（v1.1.0）
+
+| 模块 | 覆盖情况 |
+|------|---------|
+| 剧集（Drama）CRUD | ✅ 完整 |
+| 剧本生成（流式/非流式）| ✅ 完整 |
+| 角色管理 + 生成 | ✅ 完整 |
+| 场景管理 + 生成 | ✅ 完整 |
+| 道具管理 + 生成 | ✅ 完整 |
+| 分镜生成 + 管理 | ✅ 完整 |
+| 图片生成 | ✅ 完整 |
+| 视频生成 | ✅ 完整 |
+| 视频合成 | ✅ 完整 |
+| 工程导入导出 | ✅ 完整 |
+| 小说导入 | ✅ 完整 |
+| AI 配置管理 | ✅ 完整 |
+| 全局设置 | ✅ 完整 |
+| 角色库/场景库/道具库 | ✅ 完整 |
+| 内容改良（翻译/原创/混剪）| ✅ 完整 |
+| 异步任务查询 | ✅ 完整 |
+
+## 文件结构
+
+```
+openclaw-skill/
+├── SKILL.md       # Skill 主文件（包含 YAML frontmatter 和完整 API 指令）
+├── skill.json     # Manifest 清单
+├── tools.json     # 工具定义
+└── README.md      # 本说明文件
+```
+
+## 与 v1.0.0 的主要变化
+
+1. **修复 API 路径**：所有路径补全 `/api/v1` 前缀
+2. **新增 trigger 词**：从 5 个扩展到 30+ 个
+3. **新增 AI 配置管理**：支持配置/测试/预设 API Key
+4. **新增角色/场景/道具库**：全局素材库管理
+5. **新增工程导入导出**：ZIP 工程文件
+6. **新增小说导入**：从小说文本自动生成剧集结构
+7. **新增分镜高级操作**：优化提示词、超分、帧提示词、批量推断摄影参数
+8. **新增内容改良**：一键翻译出海、原创化、混剪
+9. **完善异步任务轮询策略**：明确轮询间隔和超时处理
+10. **新增 skill 配置项**：`default_aspect_ratio`、`default_video_duration`
@@ -0,0 +1,778 @@
+---
+name: local-mini-drama
+version: 1.1.0
+description: LocalMiniDrama 本地短剧助手 — 通过自然语言控制短剧项目全流程：创建剧本、生成角色/场景/道具、生成分镜、批量出图、出视频、合成完整剧集、支持小说导入和工程导入导出
+trigger: "生成短剧|创建短剧|制作短剧|短剧创作|生成分镜|生成视频|生成图片|生成角色|生成场景|生成道具|导出工程|导入工程|导入小说|合成视频|短剧项目|短剧助手|帮我写剧本|写一个短剧|我要拍短剧|生成本集|继续制作|查看项目|查看剧本|查看分镜|角色库|场景库|道具库|AI配置|配置密钥|配置API"
+config:
+  base_url:
+    type: string
+    description: LocalMiniDrama 后端地址，如 http://localhost:5679 或 http://你的服务器IP:5679
+    default: "http://localhost:5679"
+  default_aspect_ratio:
+    type: string
+    description: 默认画面比例
+    default: "16:9"
+  default_video_duration:
+    type: number
+    description: 默认单个视频片段时长（秒）
+    default: 5
+tools: [http, memory]
+requiredContext:
+  - drama_id
+  - episode_id
+author: xuanyustudio
+homepage: https://github.com/xuanyustudio/LocalMiniDrama
+---
+
+# LocalMiniDrama 本地短剧助手
+
+通过自然语言控制 LocalMiniDrama 后端，完成从零到短剧成片的全流程 AI 生成。
+
+## 核心概念
+
+- **Drama（剧集）**：一个短剧项目，包含多集（Episode）
+- **Episode（集数）**：单集内容，包含剧本（story）和分镜（Storyboard）
+- **Storyboard（分镜）**：单个镜头，含台词、动作、画面描述、图片、视频
+- **Character（角色）**：剧集中的角色，支持全局角色库复用
+- **Scene（场景）**：剧集中的场景，支持全局场景库
+- **Prop（道具）**：剧集中的道具，支持全局道具库
+
+## 触发条件
+
+用户想要创建、管理、生成短剧相关内容时使用此技能。
+
+---
+
+## ⚡ 快速开始
+
+### 1. 获取后端地址
+
+```js
+const baseUrl = config.base_url || "http://localhost:5679";
+```
+
+### 2. 列出已有项目（判断是否需要新建）
+
+```
+GET {baseUrl}/api/v1/dramas?page=1&page_size=20
+```
+
+### 3. 创建新剧集项目
+
+```
+POST {baseUrl}/api/v1/dramas
+Content-Type: application/json
+
+{
+  "title": "少年修仙传",
+  "style": "古风仙侠",
+  "type": "short_drama",
+  "metadata": {
+    "aspect_ratio": "16:9",
+    "video_duration": 5
+  }
+}
+```
+
+> `metadata.aspect_ratio` 支持 `16:9`（横屏）、`9:16`（竖屏）、`1:1`（方形）
+
+### 4. 生成剧本（支持流式）
+
+**流式（推荐）**：实时接收 AI 生成的剧本内容
+```
+POST {baseUrl}/api/v1/generation/story/stream
+Content-Type: application/json
+
+{
+  "premise": "一个少年意外获得上古修仙传承...",
+  "style": "古风仙侠",
+  "episode_count": 3,
+  "genre": "仙侠"
+}
+```
+
+**非流式**：等待完整结果后一次性返回
+```
+POST {baseUrl}/api/v1/generation/story
+Content-Type: application/json
+
+{
+  "premise": "...",
+  "style": "古风仙侠",
+  "episode_count": 3
+}
+```
+
+流式响应格式（SSE）：
+- `{ "type": "start" }` — 开始
+- `{ "type": "progress", "text": "已生成的文字..." }` — 增量文本
+- `{ "type": "done", "result": { "episodes": [...] } }` — 完成，附结构化集数
+- `{ "type": "error", "message": "..." }` — 错误
+
+**将生成的剧本保存到项目集数**：
+> 字段名：`script_content`（不是 `content`），`title`（集标题），`episode_number`
+
+```
+PUT {baseUrl}/api/v1/dramas/{drama_id}/episodes
+Content-Type: application/json
+
+{
+  "episodes": [
+    {
+      "episode_number": 1,
+      "title": "山涧奇遇，石中传承",
+      "script_content": "第一集剧本完整正文..."
+    }
+  ]
+}
+```
+
+---
+
+## 📋 项目管理
+
+### 获取项目详情
+```
+GET {baseUrl}/api/v1/dramas/{drama_id}
+```
+
+### 更新项目信息
+```
+PUT {baseUrl}/api/v1/dramas/{drama_id}
+Content-Type: application/json
+
+{
+  "title": "新标题",
+  "style": "都市言情",
+  "metadata": { "aspect_ratio": "9:16" }
+}
+```
+
+### 删除项目（软删除）
+```
+DELETE {baseUrl}/api/v1/dramas/{drama_id}
+```
+
+### 获取项目统计
+```
+GET {baseUrl}/api/v1/dramas/stats
+```
+
+---
+
+## 👤 角色管理
+
+### 获取项目角色列表
+```
+GET {baseUrl}/api/v1/dramas/{drama_id}/characters
+```
+
+### AI 提取剧本角色（异步任务）
+```
+POST {baseUrl}/api/v1/generation/characters
+Content-Type: application/json
+
+{
+  "drama_id": "项目ID"
+}
+```
+→ 返回 `{ "task_id": "...", "status": "pending" }`，用 `GET /api/v1/tasks/{task_id}` 轮询
+
+### 手动保存角色
+```
+PUT {baseUrl}/api/v1/dramas/{drama_id}/characters
+Content-Type: application/json
+
+{
+  "characters": [
+    { "name": "李逍遥", "description": "少年，侠客", "appearance": "白衣少年，剑眉星目" },
+    { "name": "赵灵儿", "description": "仙女", "appearance": "青衣少女" }
+  ]
+}
+```
+
+### 生成角色形象图（AI）
+```
+POST {baseUrl}/api/v1/characters/{character_id}/generate-image
+Content-Type: application/json
+
+{
+  "prompt_override": "古风仙侠，白衣少年，剑眉星目..."
+}
+```
+
+### 生成角色四视图
+```
+POST {baseUrl}/api/v1/characters/{character_id}/generate-four-view-image
+```
+
+### 从图片提取角色描述
+```
+POST {baseUrl}/api/v1/characters/{character_id}/extract-from-image
+Content-Type: application/json
+
+{
+  "image_url": "/static/storage/..."
+}
+```
+
+### 全局角色库
+```
+GET  {baseUrl}/api/v1/character-library
+POST {baseUrl}/api/v1/character-library   # 新建角色
+PUT  {baseUrl}/api/v1/character-library/{id}
+DELETE {baseUrl}/api/v1/character-library/{id}
+```
+
+---
+
+## 🏠 场景管理
+
+### 获取项目场景
+```
+GET {baseUrl}/api/v1/dramas/{drama_id}/scenes
+```
+
+### 提取场景（从集数剧本）
+```
+POST {baseUrl}/api/v1/episodes/{episode_id}/extract-backgrounds
+```
+
+### 生成场景图
+```
+POST {baseUrl}/api/v1/scenes/{scene_id}/generate-image
+```
+
+### 全局场景库
+```
+GET  {baseUrl}/api/v1/scene-library
+POST {baseUrl}/api/v1/scene-library
+PUT  {baseUrl}/api/v1/scene-library/{id}
+DELETE {baseUrl}/api/v1/scene-library/{id}
+```
+
+---
+
+## 🎬 道具管理
+
+### 获取项目道具
+```
+GET {baseUrl}/api/v1/dramas/{drama_id}/props
+```
+
+### 提取道具
+```
+POST {baseUrl}/api/v1/episodes/{episode_id}/extract-props
+```
+
+### 生成道具图
+```
+POST {baseUrl}/api/v1/props/{prop_id}/generate
+```
+
+### 全局道具库
+```
+GET  {baseUrl}/api/v1/prop-library
+POST {baseUrl}/api/v1/prop-library
+PUT  {baseUrl}/api/v1/prop-library/{id}
+DELETE {baseUrl}/api/v1/prop-library/{id}
+```
+
+---
+
+## 🎥 分镜管理
+
+### 生成分镜（异步任务）
+```
+POST {baseUrl}/api/v1/episodes/{episode_id}/storyboards
+Content-Type: application/json
+
+{
+  "model": "qwen-plus",          // 可选，AI 模型名称
+  "style": "古风仙侠",            // 可选，覆盖项目风格
+  "storyboard_count": 8,         // 可选，分镜数量（默认自动）
+  "video_duration": 5,            // 可选，单个视频秒数
+  "aspect_ratio": "16:9",        // 可选，覆盖比例
+  "include_narration": false      // 是否含旁白
+}
+```
+→ 返回 `{ "task_id": "...", "status": "pending" }`
+
+### 获取集数分镜列表
+```
+GET {baseUrl}/api/v1/episodes/{episode_id}/storyboards
+```
+
+### 获取单条分镜详情
+```
+GET {baseUrl}/api/v1/storyboards/{storyboard_id}
+```
+
+### 更新分镜
+```
+PUT {baseUrl}/api/v1/storyboards/{storyboard_id}
+Content-Type: application/json
+
+{
+  "dialogue": "调整后的台词",
+  "action": "调整后的动作",
+  "image_prompt": "调整后的画面描述"
+}
+```
+
+### 删除分镜
+```
+DELETE {baseUrl}/api/v1/storyboards/{storyboard_id}
+```
+
+### 新增分镜（在指定位置前插入）
+```
+POST {baseUrl}/api/v1/storyboards/{storyboard_id}/insert-before
+```
+
+### 批量推断摄影参数（毫秒级，无需 AI）
+```
+POST {baseUrl}/api/v1/storyboards/batch-infer-params
+Content-Type: application/json
+
+{
+  "episode_id": "集数ID",
+  "overwrite": false   // 是否覆盖已有参数
+}
+```
+
+### 优化分镜画面描述（AI）
+```
+POST {baseUrl}/api/v1/storyboards/{storyboard_id}/polish-prompt
+```
+
+### 生成分镜首/尾帧提示词
+```
+POST {baseUrl}/api/v1/storyboards/{storyboard_id}/frame-prompt
+Content-Type: application/json
+
+{
+  "frame_type": "first",   // "first" | "last" | "key"
+  "panel_count": 3,
+  "model": "qwen-plus"
+}
+```
+
+### 分镜图片超分（2x）
+```
+POST {baseUrl}/api/v1/storyboards/{storyboard_id}/upscale
+```
+
+---
+
+## 🖼️ 图片生成
+
+### 批量生成图片（推荐）
+```
+POST {baseUrl}/api/v1/images/episode/{episode_id}/batch
+Content-Type: application/json
+
+{
+  "types": ["image"]          // 或 ["image", "video"] 同时出图和视频
+}
+```
+
+### 查询图片任务
+```
+GET {baseUrl}/api/v1/images/{image_gen_id}
+```
+
+### 获取分镜关联的图片
+```
+GET {baseUrl}/api/v1/storyboards/{storyboard_id}/images
+```
+
+### 手动上传图片覆盖分镜
+```
+POST {baseUrl}/api/v1/storyboards/{storyboard_id}/upload
+Content-Type: multipart/form-data
+
+file: <图片文件>
+```
+
+---
+
+## 🎞️ 视频生成
+
+### 批量生成视频
+```
+POST {baseUrl}/api/v1/videos/episode/{episode_id}/batch
+Content-Type: application/json
+
+{
+  "types": ["video"]
+}
+```
+
+### 查询视频任务
+```
+GET {baseUrl}/api/v1/videos/{video_gen_id}
+```
+
+### 查询合并进度
+```
+GET {baseUrl}/api/v1/episodes/{episode_id}/merge-status
+```
+
+---
+
+## ✂️ 视频合成
+
+### 触发合成
+```
+POST {baseUrl}/api/v1/video-merges
+Content-Type: application/json
+
+{
+  "episode_id": "集数ID",
+  "merge_type": "concatenate"   // 串联所有分镜视频
+}
+```
+
+### 查询合成任务
+```
+GET {baseUrl}/api/v1/video-merges/{merge_id}
+```
+
+### 获取最终视频下载
+```
+GET {baseUrl}/api/v1/episodes/{episode_id}/download
+```
+
+---
+
+## ⏳ 异步任务查询
+
+所有生成类任务（角色、分镜、图片、视频）均为异步，**必须轮询查询状态**：
+
+```
+GET {baseUrl}/api/v1/tasks/{task_id}
+```
+
+任务状态响应：
+```json
+{
+  "task_id": "...",
+  "status": "pending" | "processing" | "completed" | "failed",
+  "progress": 65,
+  "result": { ... },
+  "error": "失败原因（失败时）"
+}
+```
+
+**轮询策略**：
+- 初始等待：500ms
+- pending/processing：每 2s 查询一次
+- 超过 60 次（2 分钟）视为超时，提示用户后台继续
+
+---
+
+## 📖 工程导入导出
+
+### 导出工程 ZIP
+```
+GET {baseUrl}/api/v1/dramas/{drama_id}/export
+```
+→ 返回 ZIP 文件下载
+
+### 导入工程 ZIP
+```
+POST {baseUrl}/api/v1/dramas/import
+Content-Type: multipart/form-data
+
+file: <xxx.zip>
+```
+
+### 从小说文本导入（自动拆章生成剧集结构）
+```
+POST {baseUrl}/api/v1/dramas/import-novel
+Content-Type: multipart/form-data
+（或者 JSON body）
+
+text: <小说全文>
+title: "小说标题"
+max_chapters: 20
+ai_summarize: true   // 是否用 AI 压缩章节
+```
+
+---
+
+## 🤖 AI 配置管理
+
+### 获取所有 AI 配置
+```
+GET {baseUrl}/api/v1/ai-configs
+```
+
+### 创建 AI 配置
+```
+POST {baseUrl}/api/v1/ai-configs
+Content-Type: application/json
+
+{
+  "name": "通义千问",
+  "vendor": "dashscope",
+  "api_key": "sk-...",
+  "model": "qwen-plus",
+  "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1"
+}
+```
+
+### 测试连接
+```
+POST {baseUrl}/api/v1/ai-configs/{config_id}/test
+```
+
+### 一键预设
+```
+POST {baseUrl}/api/v1/ai-configs/preset/dashscope   # 通义千问
+POST {baseUrl}/api/v1/ai-configs/preset/volcengine   # 豆包/火山引擎
+```
+
+### 批量更新密钥
+```
+PUT {baseUrl}/api/v1/ai-configs/bulk-update-key
+Content-Type: application/json
+
+{
+  "api_key": "sk-..."
+}
+```
+
+---
+
+## 💾 全局设置
+
+### 获取/设置语言（提示词语言）
+```
+GET  {baseUrl}/api/v1/settings/language
+PUT  {baseUrl}/api/v1/settings/language   { "language": "zh" | "en" }
+```
+
+### 获取/设置生成参数默认值
+```
+GET  {baseUrl}/api/v1/settings/generation
+PUT  {baseUrl}/api/v1/settings/generation
+```
+
+### 提示词覆盖
+```
+GET  {baseUrl}/api/v1/settings/prompts
+PUT  {baseUrl}/api/v1/settings/prompts/{key}   { "value": "..." }
+DELETE {baseUrl}/api/v1/settings/prompts/{key}
+```
+
+---
+
+## 📰 内容改良（一键原创/翻译/混剪）
+
+### 一键翻译出海（配字幕、BGM）
+```
+POST {baseUrl}/api/v1/globalize/start
+Content-Type: multipart/form-data
+
+file: <视频文件>
+bgm: <BGM音频>
+subtitle_file: <字幕文件>
+target_lang: "en"
+```
+
+### 一键原创化
+```
+POST {baseUrl}/api/v1/original/start
+```
+
+### 文稿改良
+```
+POST {baseUrl}/api/v1/rewrite/start
+```
+
+### 批量混剪
+```
+POST {baseUrl}/api/v1/mixcut/start
+Content-Type: multipart/form-data
+
+videos: <最多120个视频文件>
+```
+
+---
+
+## 🔄 标准工作流（正确顺序）
+
+> ⚠️ **顺序至关重要！必须先提取角色/场景/道具，再生成分镜。**
+> 否则分镜中 `characters` 列表为空、`background` 为 null，角色形象和场景无法关联到具体镜头。
+
+### 完整制作流程
+
+**Step 1：创建项目**
+```
+POST /api/v1/dramas
+→ 记下返回的 drama_id
+```
+
+**Step 2：生成剧本（流式）**
+```
+POST /api/v1/generation/story/stream
+```
+> body 字段：`premise`（梗概）、`style`（风格）、`genre`（类型）、`episode_count`（集数）
+
+**Step 3：保存剧本到集数**
+```
+PUT /api/v1/dramas/{drama_id}/episodes
+```
+> 字段名：`script_content`（不是 `content`），`title`（集标题），`episode_number`
+
+**Step 4：提取角色（AI 自动从剧本分析）**
+```
+POST /api/v1/generation/characters
+Content-Type: application/json
+
+{
+  "drama_id": "项目ID",
+  "episode_id": "集数ID（可选）",
+  "outline": "剧本摘要（可选，默认取当前集数剧本内容）",
+  "count": 10
+}
+→ 返回 { "task_id": "..." }，轮询 task 状态，完成后角色自动写入数据库
+```
+
+**Step 5：提取场景（AI 自动从剧本分析）**
+```
+POST /api/v1/images/episode/{episode_id}/backgrounds/extract
+→ 返回 { "task_id": "..." }，轮询 task，返回场景列表含 location/time/atmosphere
+```
+
+**Step 6：提取道具（AI 自动从剧本分析）**
+```
+POST /api/v1/episodes/{episode_id}/props/extract
+→ 返回 { "task_id": "..." }，轮询 task，返回道具列表
+```
+
+**Step 7：生成角色形象图（可选，建议在生成分镜前完成）**
+```
+POST /api/v1/characters/{character_id}/generate-image
+→ 角色图生成后关联到角色库，分镜 AI 会自动使用角色形象
+```
+
+**Step 8：生成场景图（可选）**
+```
+POST /api/v1/scenes/{scene_id}/generate-image
+```
+
+**Step 9：生成分镜（此时角色已就绪，场景会自动推断）**
+```
+POST /api/v1/episodes/{episode_id}/storyboards
+→ 轮询 task，分镜中 characters 字段会自动填充，background 自动推断
+```
+
+**Step 10：批量生成图片**
+```
+POST /api/v1/images/episode/{episode_id}/batch
+→ 轮询图片任务直到完成
+```
+
+**Step 11：批量生成视频**
+```
+POST /api/v1/videos/episode/{episode_id}/batch
+→ 轮询视频任务直到完成
+```
+
+**Step 12：合成最终视频**
+```
+POST /api/v1/video-merges
+→ 轮询直到 completed
+→ GET /api/v1/episodes/{episode_id}/download 获取下载
+```
+
+---
+
+### ❌ 错误流程（已废弃）
+
+```
+生成剧本 → 保存剧本 → ❌直接生成分镜
+```
+这种方式会导致分镜中 `characters=[]`、`background=null`，因为分镜 AI 生成时还不知道有哪些角色和场景。
+
+### 快速问答流程（无需新建项目）
+
+**问："我有一个仙侠剧本，帮我制作"**
+1. `POST /api/v1/dramas` 创建项目
+2. `POST /api/v1/generation/story/stream` 生成剧本
+3. 后续同上
+
+**问："给这个角色生成一张图"**
+1. `GET /api/v1/dramas/{drama_id}/characters` 获取角色列表
+2. `POST /api/v1/characters/{id}/generate-image`
+
+**问："这集视频做好了吗"**
+1. `GET /api/v1/episodes/{episode_id}/merge-status` 查合成状态
+2. 或 `GET /api/v1/episodes/{episode_id}/storyboards` 查各分镜视频状态
+
+**问："帮我制作这个短剧"**
+→ 执行完整制作流程（Step 1–12）
+
+---
+
+## 📝 响应格式规范
+
+所有成功响应：
+```json
+{
+  "success": true,
+  "data": { ... },
+  "timestamp": "2026-03-31T..."
+}
+```
+
+所有错误响应：
+```json
+{
+  "success": false,
+  "error": { "code": "ERROR_CODE", "message": "错误描述" },
+  "timestamp": "..."
+}
+```
+
+常见错误码：
+- `VALIDATION_ERROR`：参数校验失败
+- `NOT_FOUND`：资源不存在
+- `INTERNAL_ERROR`：服务端错误
+- `AI_ERROR`：AI 服务调用失败（检查 API Key 和模型配置）
+
+---
+
+## ⚠️ 注意事项
+
+1. **base_url 必须包含协议头**：`http://` 或 `https://`，末尾不带 `/`
+2. **异步任务必须轮询**：不要假设创建任务后立即完成
+3. **生图/视频失败优先检查**：
+   - AI Config 中图片/视频 API Key 是否配置
+   - 账户额度是否充足
+4. **竖屏创作**：`metadata.aspect_ratio = "9:16"`，视频 API 参数也要对应
+5. **工程文件导入**：仅支持从 `LocalMiniDrama` 导出的 ZIP 格式
+6. **小说导入**：建议单次不超过 30 章，超长文本先让用户分段
+
+---
+
+## 常见对话模板
+
+| 用户意图 | 推荐操作 |
+|---------|---------|
+| "帮我创建一个仙侠短剧" | 创建项目 → 生成剧本（流式）→ 保存剧本 → 提取角色/场景/道具 → 生成分镜 |
+| "帮我制作这个短剧" | 执行完整制作流程 Step 1–12 |
+| "生成本集分镜" | 确认已有角色/场景/道具 → POST storyboards |
+| "这集做好了吗" | GET merge-status |
+| "给李逍遥生成一张图" | 获取角色 → POST generate-image |
+| "我上传了图片，给我提取角色" | POST extract-from-image |
+| "把这个工程导出" | GET export |
+| "我有篇小说，帮我制作短剧" | POST import-novel → 生成剧本 → 后续流程 |
+| "配置一下通义千问" | POST preset/dashscope 或 POST ai-configs |
+| "增加一个分镜" | POST insert-before |
+| "优化一下这个分镜的描述" | POST polish-prompt |
+
+> **⚠️ 重要提醒**：每次执行"生成分镜"之前，必须先确认已完成"提取角色/场景/道具"。未提取就生成分镜，会导致分镜中 characters=[]、background=null。
@@ -0,0 +1,27 @@
+{
+  "name": "local-mini-drama",
+  "version": "1.1.0",
+  "description": "LocalMiniDrama 本地短剧助手 - AI短剧生成工具，从剧本到成片的全流程",
+  "author": "xuanyustudio",
+  "homepage": "https://github.com/xuanyustudio/LocalMiniDrama",
+  "trigger": "生成短剧|创建短剧|制作短剧|短剧创作|生成分镜|生成视频|生成图片|生成角色|生成场景|生成道具|导出工程|导入工程|导入小说|合成视频|短剧项目|短剧助手|帮我写剧本|写一个短剧|我要拍短剧|生成本集|继续制作|查看项目|查看剧本|查看分镜|角色库|场景库|道具库|AI配置|配置密钥|配置API",
+  "requiredTools": ["http", "memory"],
+  "config": {
+    "base_url": {
+      "type": "string",
+      "description": "LocalMiniDrama 后端地址",
+      "default": "http://localhost:5679"
+    },
+    "default_aspect_ratio": {
+      "type": "string",
+      "description": "默认画面比例",
+      "default": "16:9"
+    },
+    "default_video_duration": {
+      "type": "number",
+      "description": "默认单个视频片段时长（秒）",
+      "default": 5
+    }
+  },
+  "keywords": ["短剧", "AI视频", "剧本生成", "分镜", "AI短剧", "localminidrama"]
+}
@@ -0,0 +1,12 @@
+{
+  "tools": [
+    {
+      "name": "http",
+      "description": "发送 HTTP 请求到 LocalMiniDrama 后端 API。用于所有 CRUD 操作、生成任务触发、状态查询等。base_url 从 skill 配置中获取，默认 http://localhost:5679，所有路径自动拼接 /api/v1 前缀。"
+    },
+    {
+      "name": "memory",
+      "description": "在 skill 会话中存储和读取当前项目的上下文信息。记住当前 drama_id、episode_id、当前步骤等，避免每轮都让用户重复指定。key 命名规范：local_drama_drama_id、local_drama_episode_id、local_drama_current_step。"
+    }
+  ]
+}