OpenCode StoryClaw

OpenCode 插件：AI 驱动的小说转短剧分镜文本生成工具。输入网文章节，自动输出剧本、角色/场景/道具设定（含生图提示词）、分镜脚本（含视频生成提示词）。

设计理念

短剧生成涉及大量文本处理（剧本改编、结构化解析、角色设定、分镜描述），这些工作交给 OpenCode 的 coding plan 套餐来完成——文本处理量大、套餐费用固定，能最大化发挥编码工具的性价比。图片和视频生成则放到即梦AI、可灵AI等专业平台，它们有月套餐，按需使用，费用可控。

文本 → OpenCode（coding plan、套餐费用固定），图片/视频 → 专业平台（月套餐、可控），各司其职，整体成本最优。

工作流

插件生成全部文本产物，你手动到即梦AI/可灵AI的 Web 页面执行生图和生视频：

1. 用角色 .md 中的提示词 → 生成角色参考图
2. 用场景 .md 中的提示词 → 生成场景底图
3. 用道具 .md 中的提示词 → 生成道具参考图
4. 将分镜提示词中的 【characters001】 等标记替换为对应参考图 → 生成视频片段

Pipeline 阶段

| 阶段 | 说明 | 工具 | |------|------|------| | A 剧本创作 | 扫描小说章节，生成短剧剧本 | scan_novel → save_script | | B 剧本解析 | 剧本解析为结构化 JSON | parse_script | | C 资源设定 | 生成角色/场景/道具设定 + 提示词 | generate_character / generate_scene / generate_prop | | D 分镜导演 | 逐 beat 生成分镜脚本（含视频提示词） | direct_storyboard | | E 元数据保存 | 汇总本集数据，更新跨集进度 | save_episode_meta |

全局风格控制

每部小说都有一个 全局风格设定.json，统一控制所有生成的角色、场景、道具提示词和分镜脚本的视觉风格。从剧本创作到每一集的分镜导演，全部产物都会读取这个文件，确保整体风格不跑偏。

风格维度

| 字段 | 作用 | 示例值 | |------|------|--------| | visual_style | 整体视觉风格 | 真人写实摄影、日系动画、3D动画、水彩插画、赛博朋克 | | color_tone | 色调倾向 | 自然色调、冷色调、暖色调、高饱和度、黑白 | | lighting | 光线风格 | 自然光、电影光影、柔和光线、霓虹灯光 | | atmosphere | 整体氛围 | 写实生活化、暗黑悬疑、欢快明亮、史诗感、恐怖 | | character_art_style | 角色参考图提示词中的风格描述 | 真人写实风格，像真实照片一样 | | scene_art_style | 场景底图提示词中的风格描述 | 真人写实摄影风格 | | prop_art_style | 道具参考图提示词中的风格描述 | 高细节，真人写实风格 | | target_platform | 目标生成平台 | 可灵AI/即梦AI | | video_style | 视频生成风格 | 真人实拍质感、动画质感、电影质感 | | forbidden_words | 提示词中禁止出现的风格词 | ["卡通", "漫画", "动漫"] | | custom_prompt_prefix | 所有提示词自动添加的前缀 | 可留空 | | custom_prompt_suffix | 所有提示词自动添加的后缀 | 自然光影 | | notes | 附加风格说明（LLM 生成时会参考） | 角色脸型要偏圆润，场景偏日式校园 |

配置风格

首次使用时自动创建默认配置（真人写实风格）。你可以随时修改：

/story-custom 我的小说 style

或直接用自然语言：

把《我的小说》改成日系动画风格，色调偏暖

LLM 会调用 init_novel_style 工具更新配置。修改后，后续新生成的角色/场景/道具设定和分镜脚本会使用新风格，已有资源不受影响。

默认配置

{
  "visual_style": "真人写实摄影",
  "color_tone": "自然色调",
  "lighting": "自然光",
  "atmosphere": "写实生活化",
  "character_art_style": "真人写实风格，像真实照片一样",
  "scene_art_style": "真人写实摄影风格",
  "prop_art_style": "高细节，真人写实风格",
  "target_platform": "可灵AI/即梦AI",
  "video_style": "真人实拍质感",
  "forbidden_words": ["卡通", "漫画", "简笔画", "动漫", "手绘", "插画"],
  "custom_prompt_prefix": "",
  "custom_prompt_suffix": "自然光影",
  "notes": ""
}

输出目录结构

workspace/
└── {小说名}/
    ├── 改编进度.json              # 跨集进度 + 资源 ID 计数器
    ├── 全局风格设定.json          # 视觉风格控制（跨集共享）
    ├── characters/                # 角色设定（跨集共享）
    │   ├── characters001-魏俊熙.md
    │   └── characters002-学姐.md
    ├── scenes/                    # 场景设定（跨集共享）
    │   ├── scenes001-报到处走廊.md
    │   └── scenes002-教室.md
    ├── props/                     # 道具设定（跨集共享）
    │   ├── prop001-石碑.md
    │   └── prop002-不明信件.md
    └── ep01/                      # 第1集
        ├── {小说名}_第1集.md      # 剧本
        ├── scene_data.json        # 结构化场景数据
        ├── episode_meta.json      # 本集元数据
        └── panels/                # 分镜脚本
            ├── panels_scene_01_beat01.md
            └── panels_scene_01_beat02.md

核心文件格式

角色 characters001-魏俊熙.md

# 魏俊熙

## 固定特征
18岁少年，身材偏瘦，短发，单眼皮，肤色偏白

## 默认服装
蓝色T恤、牛仔裤、双肩背包

## 参考图提示词
真人写实风格，18岁少年，身材偏瘦，短发，单眼皮，肤色偏白，
蓝色T恤、牛仔裤、双肩背包，自然正面表情，白色纯净背景，
包含正面全身、侧面全身、背面全身及正面脸部特写，自然光影

提示词中的风格描述来自 全局风格设定.json 的 character_art_style。切换为动画风格后，新生成的角色提示词会自动变为：

日系动画风格，18岁少年，身材偏瘦，短发，单眼皮，肤色偏白，
蓝色T恤、牛仔裤、双肩背包，自然正面表情，白色纯净背景，
包含正面全身、侧面全身、背面全身及正面脸部特写，柔和光线

场景和道具同理，分别读取 scene_art_style 和 prop_art_style。

分镜脚本 panels_scene_01_beat01.md

## Panel 1（全景 · 4秒）

【characters001】穿白色T恤背单肩包的男生，面对镜头一手拖行李箱在
【scenes001】走廊缓步走向报到台，微微仰头望向石碑【prop001】，
表情从好奇转为疑惑。

**涉及：** characters001(魏俊熙)、scenes001(报到处走廊)、prop001(石碑)
**景别：** 全景
**时长：** 4秒

---

## Panel 2（近景 · 3秒）

穿白色T恤的男生，近景，微微仰头望向石碑，表情疑惑，
目光缓缓扫过石碑上的文字。

**涉及：** characters001(魏俊熙)、scenes001(报到处走廊)
**景别：** 近景
**时长：** 3秒

提示词中的标记与设定文件一一对应：

• 【characters001】 → characters/characters001-魏俊熙.md 的参考图
• 【scenes001】 → scenes/scenes001-报到处走廊.md 的参考图
• 【prop001】 → props/prop001-石碑.md 的参考图

手动操作时，将标记替换为对应参考图即可在可灵/即梦生成视频。

跨集连贯性

| 机制 | 作用 | |------|------| | 全局风格设定 | 统一控制所有产物的视觉风格，跨集不跑偏 | | 滑动窗口回顾 | 最近 2 集源章节作为上下文 | | 剧情摘要 | 累积全局剧情概要 | | 悬念钩子 | 上集未解决悬念传递到下集 | | 上一集 meta | 角色状态、资源使用记录 | | 资源 ID 注册表 | 跨集编号连续递增（characters001→002→...） | | 角色固定特征 | 分镜描述同一角色时用词一致（从角色 .md 取） | | 分镜风格参考 | 延续上一集的镜头语言风格 | | 角色复用 | 已有角色/场景/道具自动跳过，不重复创建 |

安装

前置条件

• OpenCode 已安装
• Node.js >= 18

1. 安装插件包

npm install opencode-storyclaw

2. 配置

在 OpenCode 配置文件中注册插件。支持项目级和全局两种方式：

项目级（推荐）

在项目根目录创建 .opencode.json：

{
  "plugin": ["opencode-storyclaw"]
}

仅当前项目生效。

全局

编辑全局配置文件：

| 系统 | 路径 | |------|------| | macOS / Linux | ~/.config/opencode/opencode.json | | Windows | %APPDATA%\opencode\opencode.json |

在 plugin 数组中添加：

{
  "plugin": [
    "opencode-storyclaw"
  ]
}

所有项目均可使用。

3. 验证

重启 OpenCode 后，输入以下命令确认插件已加载：

/story-status

如果看到工具调用提示，说明安装成功。

命令一览

| 命令 | 说明 | |------|------| | /story-solo <小说名> | 全自动：一键完成整集改编（剧本→解析→设定→分镜） | | /story-custom <小说名> <阶段> | 分步执行：每次只跑一个阶段，中间可检查和调整 | | /story-status [小说名] | 查看改编进度：已改编集数、已有角色/场景/道具、悬念钩子 |

也可以直接用自然语言，LLM 会自动选择合适的工具。所有命令都能用自然语言替代。

使用指南

1. 准备小说文件

在项目工作目录下创建小说文件夹，按章节拆分为 .txt 文件：

workspace/
└── 我的校园奇遇/
    ├── 第1章 开端.txt
    ├── 第2章 迷雾.txt
    ├── 第3章 真相.txt
    └── ...

文件名格式：第{N}章 {标题}.txt，按文件名排序确定章节顺序。

2. 一键改编（推荐）

/story-solo 我的校园奇遇

插件会自动按 A→B→C→D→E 五个阶段依次执行：

1. Stage A — 扫描章节，生成短剧剧本 .md
2. Stage B — 解析剧本为结构化 scene_data.json
3. Stage C — 提取角色/场景/道具，生成设定文件（含生图提示词）
4. Stage D — 逐 beat 生成分镜脚本（含视频提示词）
5. Stage E — 保存元数据，更新跨集进度

首次运行会自动创建默认的全局风格设定（真人写实风格）。

3. 分步执行

如果你想在中间检查或调整产物，用 /story-custom 逐阶段执行：

/story-custom 我的校园奇遇 A     # 只跑 Stage A：生成剧本

检查剧本满意后，继续下一阶段：

/story-custom 我的校园奇遇 B     # 解析剧本为 scene_data.json
/story-custom 我的校园奇遇 C     # 生成角色/场景/道具设定
/story-custom 我的校园奇遇 D     # 生成分镜脚本
/story-custom 我的校园奇遇 E     # 保存元数据

每个阶段完成后会汇报结果，你可以随时手动修改中间产物再继续。

4. 多集连续改编

再次执行同一命令，插件会自动从上次停下的章节继续：

/story-solo 我的校园奇遇    # 第1次：生成第1集
/story-solo 我的校园奇遇    # 第2次：自动续接，生成第2集

跨集连贯性通过以下机制保证：

• 滑动窗口回顾最近 2 集源章节
• 上集悬念钩子自动传递
• 角色/场景/道具自动复用（不重复创建，ID 连续递增）

5. 查看进度

/story-status 我的校园奇遇

输出示例：

小说：我的校园奇遇
已改编：3 集
下一集：第4集（从第11章开始）

角色（5个）：
  characters001-魏俊熙
  characters002-学姐
  characters003-张教授
  ...

场景（4个）：
  scenes001-报到处走廊
  scenes002-教室
  ...

道具（2个）：
  prop001-石碑
  prop002-不明信件

上集悬念：学姐留下的信件内容尚未揭晓

不传小说名则列出所有小说的进度：

/story-status

6. 自定义风格

默认使用真人写实风格。切换为其他风格：

/story-custom 我的校园奇遇 style

或直接用自然语言：

把《我的校园奇遇》改成日系动画风格，色调偏暖

把《我的校园奇遇》改成赛博朋克风格，暗黑氛围，霓虹灯光

LLM 会调用 init_novel_style 更新 全局风格设定.json。修改后，后续新生成的角色/场景/道具设定和分镜脚本会使用新风格，已有资源不受影响。

7. 完整使用示例

以下是一个完整的工作流程示例：

# 1. 准备小说文件（手动操作）
workspace/都市逆袭/
├── 第1章 落魄.txt
├── 第2章 转机.txt
├── 第3章 反击.txt
└── 第4章 涅槃.txt

# 2. 在 OpenCode 中一键改编第1集
/story-solo 都市逆袭

# → 自动生成 ep01/ 目录，包含剧本、角色设定、场景设定、分镜脚本

# 3. 用生成的提示词到即梦AI/可灵AI生成参考图
#    - 取 characters/characters001-林晨.md 中的提示词 → 生成角色参考图
#    - 取 scenes/scenes001-天桥底.md 中的提示词 → 生成场景底图
#    - 取 prop/prop001-旧怀表.md 中的提示词 → 生成道具图

# 4. 用分镜提示词生成视频
#    - 打开 ep01/panels/panels_scene_01_beat01.md
#    - 将【characters001】替换为角色参考图，【scenes001】替换为场景底图
#    - 复制到可灵AI/即梦AI → 生成视频片段

# 5. 查看进度
/story-status 都市逆袭

# 6. 继续改编第2集
/story-solo 都市逆袭

# → 自动从第3章续接，生成 ep02/

工具列表

| 工具名 | 说明 | |--------|------| | scan_novel | 扫描小说文件夹，返回章节文本和改编进度 | | save_script | 保存剧本 .md 并更新改编进度 | | parse_script | 读取剧本，指导 LLM 解析为 scene_data.json | | generate_character | 生成角色设定 .md（含参考图提示词） | | generate_scene | 生成场景设定 .md（含参考图提示词） | | generate_prop | 生成道具设定 .md（含参考图提示词） | | direct_storyboard | 生成分镜脚本 .md（含视频提示词和资源标记） | | save_episode_meta | 保存本集元数据并更新改编进度 | | init_novel_style | 初始化或更新全局风格设定 |

技术栈

• Runtime — Node.js + TypeScript
• Plugin API — @opencode-ai/plugin（tool helper + Zod schema）
• 无外部 LLM 依赖 — 使用 OpenCode 配置的模型套餐

环境要求

• Node.js >= 18
• OpenCode
• LLM 模型（通过 OpenCode 配置）

License

MIT