ynuo 漫剧创作实测教程 —— 火山方舟 Agent Plan 版
面向：首次使用 ynuo 创作模式的用户（可用于宣传）。 场景：以《猴王出世》为例，从模型配置到成片交付，完整走一遍 「项目简报 → 剧本 → 角色资产 → 风格 → 分镜 → 媒体生成」全流程。 全程约 30–60 分钟（含媒体生成等待时间）。
前置要求：ynuo 服务已启动（
pnpm dev），已有账号并登录 Web 端。
推荐
- db.navivo.cc/sign-up?aff…
- www.suno-api.io/（music生成）
- 音频的可以使用阿里的有免费额度。
一、准备工作：火山方舟开通与密钥获取
1.1 开通火山方舟（Ark）
- 访问 火山方舟控制台，注册/登录火山引擎账号。
- 购买 Agent Plan（或确认套餐已生效）；方舟套餐覆盖模型调用额度。
- 在「API Key 管理」中创建 API Key，复制保存（形如
ark-xxxxxxxx）。- 该 Key 同时用于：文本对话模型（方舟 LLM）、即梦图像/视频生成。
1.2 开通所需模型
在方舟控制台「开通管理」中确认以下模型已开通：
| 用途 | 模型（示例） | 说明 |
|---|---|---|
| 文本对话（剧本/分镜/提示词生成） | doubao-seed-1.6 等 Doubao 系列或接入的其它方舟模型 | 会话文本模型 |
| 图像生成 | 即梦图像（doubao-seedream-*） | 角色立绘 / 分镜首帧 |
| 视频生成 | 即梦视频（doubao-seedance-*） | 分镜动态视频 |
| 配音（TTS） | 豆包语音合成 2.0（seed-tts-2.0） | 台词配音，走 openspeech 专属端点（非方舟入口） |
| 音乐 | Suno V6（经 suno-api.io 等 OpenAI 兼容中转） | 背景音乐（可选） |
注：媒体模型以控制台实际可开通列表为准；模型名需填入下方配置。
1.3 密钥配置（推荐直接在配置页填明文 Key）
媒体模型的密钥统一在 系统设置 → 媒体模型配置 中填写（数据库存储， 配置页展示为掩码、不回传前端明文）。
注意：配置条目中的「API Key 环境变量（apiKeyEnv）」字段当前版本为预留位， 未实现从环境变量解析——请直接在「API Key」栏填明文，不要只填环境变量名， 否则提交时会报「媒体模型密钥未配置」。
二、ynuo 系统配置
2.1 配置文本对话模型
路径：系统设置 → 模型配置。
- 点击「新增模型」，选择供应商/协议（火山方舟为 OpenAI 兼容协议时，
baseUrl 填
https://ark.cn-beijing.volces.com/api/v3）。 - 填入模型名（如
doubao-seed-1-6-250615）与 API Key。 - 保存后该模型出现在会话创建弹窗的模型下拉中——建创作会话时要选它。
2.2 配置媒体模型（图像/视频/配音/音乐）
路径：系统设置 → 媒体模型配置。
为每个模态各建一条配置（点「新增」）。供应商下拉按模态选：
| 模态 | 名称（示例） | 供应商（Provider） | 模型名（填「模型名」输入框） | Base URL |
|---|---|---|---|---|
| 图像 | 即梦-图像 | 火山方舟 Ark | doubao-seedream-4-0（方舟模型名） | https://ark.cn-beijing.volces.com/api/v3 |
| 视频 | 百炼-视频 | 阿里云百炼 | wan3.0-video | https://dashscope.aliyuncs.com/api/v1 |
| 视频（备选） | 即梦-视频 | 火山方舟 Ark | doubao-seedance-1-0-pro | https://ark.cn-beijing.volces.com/api/v3 |
| 配音 | 豆包-TTS | 豆包语音合成（seed-tts） | seed-tts-2.0 | https://openspeech.bytedance.com/api/v3/plan/tts/unidirectional |
| 音乐（可选） | Suno-音乐 | OpenAI 兼容（通用网关） | suno-v6 | https://www.suno-api.io |
字段说明：
- 模型名：直接填「模型名」输入框（等价于写进
params.model），如doubao-seedream-4-0。 - 高级参数 params（JSON）：差异项按模态补——
- 图像/视频（Ark）：
{"model": "..."}即可； - 配音（seed-tts）：
speaker必填，如{"model":"seed-tts-2.0","speaker":"zh_female_vv_uranus_bigtts","format":"mp3"}； 音色需在火山控制台语音音色列表中已激活； - 音乐（Suno 中转）：
{"model":"suno-v6","submitPath":"/api/music/create","pollPath":"/api/music/query","pollBody":{"song_ids":"{id}"},"statusField":"status","promptField":"description","estimatedSeconds":300}。
- 图像/视频（Ark）：
- 密钥：在「API Key」栏填明文（配置页掩码展示、不回传前端）。注意各平台
Key 来源不同——方舟/即梦用方舟 Key，豆包 TTS 用 Agent Plan 专属 API Key
（
X-Api-Key鉴权，与方舟 OpenAPI Key 不是同一把），Suno 用 suno-api.io 签发的sk-…。 - 状态：保存后确认为「启用」。禁用/删除的条目，引用它的会话调用即报错。
2.3 配置检查清单
- 文本模型已配置并在会话创建弹窗可选
- 图像/视频（必选）+ 配音（必选）媒体模型已启用
- 配音 params 已填
speaker音色（如zh_female_vv_uranus_bigtts） - 音乐模型（可选）已启用
- 各平台 API Key 已在配置页填明文（方舟 Key / Agent Plan 专属 Key / Suno Key）
- 启动 ynuo 后服务正常（
pnpm dev）
三、创建漫剧创作会话
3.1 建项目与创作任务（创作工作空间）
- Web 端进入「创作」模块，新建一个创作类项目（项目类型=创作工作空间，
如命名为「猴王出世短视频」）。
- 创作项目会自动分配独立工作空间目录；首个会话创建时若未选任务， 系统自动生成一条内容创作任务（CRE-0001）。
3.2 新建创作会话（关键参数）
点击「新建会话」，在弹窗中：
| 参数 | 填写 | 说明 |
|---|---|---|
| 会话名称 | 猴王出世 | 自定义 |
| 文本模型 | 选择 §2.1 配置的方舟模型 | 创建前必选；创建后本会话固定使用该模型 |
| 创作模式 | 开启「创作模式（漫剧/短视频媒体创作）」 | 开启后出现媒体四选 |
| 图像模型（必选） | 即梦-图像 | 角色立绘 + 分镜首帧 |
| 视频模型（必选） | 百炼-视频（或即梦-视频） | 分镜动态化 |
| 配音模型（必选） | 豆包-TTS | 台词配音 |
| 音乐模型（可选） | Suno-音乐 | 片头/背景乐 |
| 媒体生成策略 | 首次实测建议「每次生成需确认（最稳）」 | 每次付费调用前需你点确认，确认框不点不消失；熟练后可换「预算内自动执行」并设置预算 |
点「创建」。系统自动完成：
- evant 工作区脚手架（
<项目>/.ynuo/evant/：state.json流程真源）+ 项目产出区docs/（交付文档语义目录、docs/assets/媒体落点）； - 自动关联内容创作任务（
task_type=8，编号 CRE-xxxx，删除会话时级联删除）； - 加载「evant」创作工作流内置技能；
- 注册创作工具四件套（
creation_generate / creation_poll / creation_list_assets / creation_register_doc）。
验收点：会话打开后右侧出现「媒体」页签（创作面板：阶段进度、预算用量、 媒体画廊——生成中/就绪/失败/文件缺失四态卡片实时刷新）。
四、《猴王出世》全流程实操
操作原则：每阶段产出后，AI 会等你确认再推进。你只需回复 「确认 / 通过，继续」或提出修改意见。所有交付文档自动归档到 「文档」页（磁盘在
<项目>/docs/<阶段>/，索引在 project_docs 表）。
4.1 阶段 0：项目简报（S0）
在输入框发送（或直接说）：
开始创作《猴王出世》：根据《西游记》原著第一回改编，单集短视频， 画幅 9:16（抖音竖屏），时长目标 10–20 秒，神话国漫风格，面向全年龄。
AI 产出立项卡（题材定位、集数、画幅、平台、合规要点）。 确认无误后回复「通过」→ 进入剧本阶段。
合规说明：系统对真实人物/宗教敏感表述会自动虚构化处理 （如地名改「东胜神洲傲来国」这类原著虚构地名可保留）。
4.2 阶段 1：剧本（S1）—— 文案与台词
AI 按分场结构产出完整剧本（旁白、台词、镜头提示）。 以下是本教程的参考成品（AI 生成后应与此水准相当，可直接使用）：
《猴王出世》分场剧本（竖屏 60–90s）
- **S1 开场（0:00–0:08）**｜旁白：「东海之外，傲来国。海中有一座名山，唤作花果山。」 画面：云海翻腾，仙山浮出，瀑布如银河倒挂。
- **S2 神石（0:08–0:18）**｜旁白：「山顶有一块仙石，自开天辟地以来，受日精月华，感应已久。」 画面：巨石矗立峰顶，光影流转，石身微微震颤。
- **S3 破石（0:18–0:28）**｜旁白：「忽一日，天崩地裂——」 音效：轰然爆响；画面：仙石炸裂，金光冲天。
- **S4 石猴出世（0:28–0:40）**｜石猴（台词，稚气洪亮）：「俺老孙，来也！」 画面：石猴跃出，双目金光扫射云霄，惊动天庭（玉帝抬眼一瞥）。
- **S5 水帘洞（0:40–0:55）**｜众猴喧哗。石猴：「哪个敢进去寻个源头，我等即拜他为王！」 画面：石猴纵身跃入瀑布，水帘内别有洞天。
- **S6 称王收尾（0:55–1:05）**｜众猴朝拜，齐呼：「千岁大王！」 旁白：「一段传奇，自此开始——猴王出世。关注我，下集《学艺方寸山》。」
确认剧本后回复「通过」→ 进入资产阶段。
4.3 阶段 2：角色与资产（S2）—— 图像生成
AI 产出角色圣经（外形固定描述 + 负面词 + 风格锚）与资产清单， 然后逐个生成角色立绘：
- 石猴：
creation_generate(assetType=image, shotId=CHAR-石猴) - 场景：花果山全景、水帘洞内景（
shotId=SCENE-花果山等）
系统在策略为 confirm_each 时会弹出确认卡片 → 点「确认」。 生成中可在「媒体」页签看到「生成中」标签；完成后变「就绪」，可点「查看」。
一致性纪律：后续所有分镜图都会引用这里的角色 ID 与固定描述， 保证石猴每张图都长一样。立绘不满意可让 AI 换提示词重出 （会话内回复「石猴立绘重出，脸更灵动一些」——同 shotId 重试不重复计费）。
4.4 阶段 3：风格卡（S3）
AI 产出风格卡（画风关键词、色调、光影、镜头语言词库），
示例锚点：国漫神话风，赛璐璐上色，金红撞色，云雾体积光，电影级构图。
确认后进入分镜。
4.5 阶段 4：分镜（S4）—— 图生视频与配音
AI 产出分镜脚本（每镜：时长/景别/画面描述/提示词/台词），随后逐镜执行：
- 首帧图：
creation_generate(image, shotId=S01)→ 确认 → 等就绪； - 动态视频：
creation_generate(video, shotId=S01, imageUrl=<该镜首帧图的 assetId>)—— 图生视频必须传imageUrl（同镜关键帧的 assetId 或 docs/assets 路径）， 保证视频画面与关键帧形象一致；不传只给文字提示词会形象脱钩； - 台词配音：
creation_generate(assetType=tts, shotId=S04-VO)（台词送配音模型）； - 背景乐（可选）：
creation_generate(assetType=music, shotId=BGM)。
参考分镜提示词（S3 破石一镜）：
画面：花果山之巅，仙石金光大盛，龟裂蔓延，轰然炸裂， 碎石与金光粒子四散，镜头缓推近。国漫神话风，体积光，电影质感。
批量模式下可回复「按批次全部放行」，一次确认多镜。 全部镜完成 → 阶段 4 标记 done，进入交付。
4.6 交付与验收
- 交付清单：AI 产出三表 CSV（镜号/资产/时长/状态）与资产包说明。
- 验收口径：
- 「文档」页可见：立项卡、剧本、角色圣经、资产清单、风格卡、分镜脚本（6 份 .md）
- 「媒体」页签：每镜图像+视频状态「就绪」，配音/音乐就绪
- 预算用量与实际调用数一致（每行 = 一次付费调用）
五、常见问题与排查（FAQ）
| 现象 | 原因 | 处理 |
|---|---|---|
| 提交生成报「媒体模型密钥未配置」 | 配置条目的「API Key」栏为空 | 到媒体模型配置补填明文 Key（apiKeyEnv 环境变量为预留位，当前不解析） |
| 配音报「缺少音色」 | TTS 配置的 params 未填 speaker | params 补 {"speaker":"zh_female_vv_uranus_bigtts"}（音色需已在火山控制台激活） |
| 配音报「语音合成失败」 | 用了方舟 OpenAPI Key 调 openspeech 端点 | 换 Agent Plan 专属 API Key（X-Api-Key 鉴权），与方舟 Key 不是同一把 |
| 音乐报「提交响应缺少任务 id」 | Suno params 未按 song_ids 协议配置 | 按 §2.2 音乐模板更新 params（pollPath=/api/music/query + pollBody={"song_ids":"{id}"}） |
| 轮询报「模型配置已失效，请到会话设置重新选择」 | 条目被禁用/删除，或换用了别的 Key | 恢复条目启用；系统不换模型代跑（钱只花在你选过的模型上） |
| 「生成预算已用尽」 | auto_budget 策略下已用 ≥ 上限（真源=资产表行数） | 到会话设置调大预算，或改回确认模式 |
| 同一镜号重试会不会重复扣费？ | 不会。同 shotId 重试自动复用既有任务（幂等键 client_request_id 持久化在 state.json） | 重试时保持 shotId 不变即可 |
| 确认框没点就不见了，AI 自己继续跑 | 旧版本审批 60s/30s 超时自动拒绝 | 已修复：确认框为阻塞式（24h 等待），不点不消失；确需中止用「停止生成」 |
| 本地文件被误删/服务中断后媒体丢失 | 文件在磁盘被删，但平台任务仍有效 | 「媒体」页签该卡片点「重新获取」——凭平台任务 id 从远程重拉，不重复扣费 |
| 生成一直「生成中」 | 平台任务排队/慢；Poller 自动轮询推进（超时会先重查平台、仍在生成自动续期） | 「媒体」页签等状态刷新；SSE 断线时系统自动切 5s 轮询对账 |
| 角色每张图长得不一样 | 分镜未引用角色圣经固定描述 | 回复 AI：「以 CHAR-石猴 资产描述重出该镜」 |
| 视频画面与关键帧对不上 | 提交视频时没传首帧图 | 要求 AI 补 imageUrl=<同镜关键帧 assetId> 重新生成 |
/evant 命令提示 403 | 非漫剧会话（普通研发/项目会话） | 后端强制门禁，仅创作会话可用——符合预期 |
| 文档页看不到交付 .md | 归档有延迟或该阶段未产出 | 交付 .md 由 creation_register_doc 自动登记；确认阶段已完成 |
六、要点（一句话版本）
在 ynuo 里说一句「开始创作《猴王出世》」，AI 拆剧本、立角色、 出分镜、生成图像/视频/配音，交付一整套 9:16 竖屏短视频资产包—— 全程可视化确认，成本行级透明，模型你说了算。
流程图：
一句创意 → 00 立项卡 → 01 剧本(文案/台词) → 02 角色立绘
→ 03 风格卡 → 04 分镜(图→视频→配音→配乐) → 资产包交付
