OpenCode StoryClaw

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

设计理念

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

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

工作流

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

用角色 .md 中的提示词 → 生成角色参考图
用场景 .md 中的提示词 → 生成场景底图
用道具 .md 中的提示词 → 生成道具参考图
将分镜提示词中的 【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 五个阶段依次执行：

Stage A — 扫描章节，生成短剧剧本 .md
Stage B — 解析剧本为结构化 scene_data.json
Stage C — 提取角色/场景/道具，生成设定文件（含生图提示词）
Stage D — 逐 beat 生成分镜脚本（含视频提示词）
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

Name		Name	Last commit message	Last commit date
docs/superpowers		docs/superpowers
src		src
.gitignore		.gitignore
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation