企业官网建设流程全解析

DramaClaw（产品层面向用户的助手统称"虾导"）是部署在开源仓库.hermes/skills/dramaclaw/下的 AI 小说转视频流水线 Agent Skill。本文以 init.md 为骨架，系统讲解当前项目初始化阶段（Step 1-7）的完整执行协议：从剧本上传、异步摄入、项目配置、角色提取、face_prompt 补齐、分集规划到肖像生成的每一步 API 契约、决策规则与源码依据。读完本文，你将掌握"虾导"在项目已创建但未摄入的情况下，如何从零把一部小说推进到"全局准备完成（CP1）"，并理解两种运行模式（逐步确认 / 自动推进）下每一轮只能推进一个写任务的硬性纪律。

流水线全景：初始化阶段在整条链中的位置

按照 SKILL.md 的流水线总览，整条 DramaClaw 流水线被划分为三个大阶段：

后端主线固定为：raw-content → rewrite → script/generate → scenes/props → sketches → grids → audio_generation_indextts2 → single_video（逐 beat）→ compose → final delivery。初始化阶段（Steps 1-7）负责"点火"：让一个空项目具备ingested / configured / characters / episodes / portraits_done五项全局状态，之后才能进入逐集制作。注意一个关键边界：项目创建由前端/系统完成，虾导不调用POST /projects，会话必须已经绑定DRAMACLAW_PROJECT_ID。

前置检查：/pipeline/status决定从哪一步开始

进入本 playbook 之前，每次激活 skill 都必须先执行一次幂等的状态拉取：

GET ${DRAMACLAW_API_URL}/api/v1/projects/${DRAMACLAW_PROJECT_ID}/pipeline/status

其中${DRAMACLAW_PROJECT_ID}必须先解析成当前会话的真实项目名，禁止把占位符字面量拼进 URL。返回的global/episode_status/next_step决定入口分支：

从源码看，/pipeline/status的初始化分支在 src/novelvideo/api/routes/pipeline.py 中实现：global包含ingested / configured / characters / episodes / portraits_done五项布尔/数值状态，并按优先级ingest → configure → characters → episodes → portraits推导next_step，映射到_STEP_MAP中的任务类型（如ingest_fast、build_characters、build_episodes）与中文步骤名（"小说摄入""角色提取""分集规划"）。值得注意的是ingested的计算逻辑：ingest_fast任务状态为completed，或角色/分集已存在，都算已摄入。

失败处理：HTTP 5xx / 网络错误时告知"DramaClaw 后台状态暂时不可用"并停止本轮，不要凭历史状态推进；HTTP 403 说明"项目绑定异常"，同样停止。

入口决策树：什么消息才能触发初始化流程

进入初始化流程的前提是：当前消息已经带有剧本文档附件，或前端已注入[DRAMACLAW_INGEST_AUTOMATION]/ 明确摄入上下文。如果用户只是用聊天文字要求"创建/生成/写剧本"，不得进入下面流程，必须直接告知只能通过"虾料"上传剧本文档——虾导不提供生成剧本功能，也不从一句话主题创建短剧项目（此规则在 SKILL.md §1 的"剧本/短剧创建入口限制"中有完整表述，并明确禁止调用dramaclaw_generate_script、dramaclaw_plan_episodes等写接口）。

满足前置后，初始化流程按如下决策树执行：

1. 获取小说文件 当前消息必须已有剧本文档附件或虾料摄入上下文 ├─ 有 → 使用前端提供的上传/摄入上下文 └─ 没有 → 停止，提示通过"虾料"上传剧本文档 2. 自动执行（不需要问用户） 上传小说(1) → 启动摄入(2)。摄入是异步任务，启动后立即收口； 若状态仍为 queued/running，只告知后台正在摄入中，不等待完成后继续配置。 3. 智能推荐配置（§5 决策点规则） 摄入完成后分析小说内容再推荐： - 时代背景/关键词 → 视觉风格 - 角色名/背景 → 种族 - 人称视角 → 叙事方式 - 情节节奏 → rhythm 4. 一次性展示推荐方案，让用户确认/修改 5. 确认后 → 配置项目(3)；配置完成后询问运行模式，不继续启动角色提取

两个关键规则贯穿始终：

• 不要逐项问用户选择配置，分析后一次性推荐；但运行模式必须显式问。
• 配置完成后必须问运行模式：「要我每步确认，还是自动推进（每轮一步）？」，然后Read references/run-modes.md按所选模式执行，不继续启动角色提取。

Steps 1-2：上传小说与启动摄入（异步任务）

Step 1：上传小说 [SYNC]

POST /projects/$PID/ingest/upload Body: multipart/form-data, file=novel.txt

这是同步操作，直接把剧本文档写入项目的uploads/目录。源码 src/novelvideo/api/routes/ingest.py 给出了该端点的完整实现细节，可作为配置参考：

• 格式校验：仅支持supported_novel_extensions_label()列出的扩展名，否则返回error_type: unsupported；文件名会先经sanitize_upload_filename清洗，再校验is_safe_upload_target（非法文件名直接拒绝）。
• 大小与字数上限：上传字节数受MAX_NOVEL_UPLOAD_BYTES限制（超限返回file_too_large）；解析后正文的计费字数受MAX_NOVEL_IMPORT_CHARS限制（超限返回text_too_large，并提示拆分后重新上传）。
• 章节预览：上传即做章节解析（build_chapter_preview），未检测到有效章节内容会返回解析章节失败: 未检测到有效章节内容；同时生成格式检查报告format_check。写入采用"staging 暂存 +os.replace原子替换"，失败自动清理。
• 可选表单字段：spine_template（默认为项目配置中的值或drama），决定章节预览是否包含场景块（narrated模板不包含）。

Step 2：摄入 [ASYNC → ingest_fast, ep=0]

POST /projects/$PID/ingest/start Body: {"filename": "novel.txt", "rebuild": false}

摄入是异步任务，任务类型为ingest_fast、episode=0。启动后立即收口：若状态仍为queued/running，只告知"后台正在摄入中"，不等待完成再继续配置。任务状态与进度可用如下方式跟踪：

GET /projects/$PID/tasks/ingest_fast/0 SSE /projects/$PID/tasks/ingest_fast/0/stream

从 ingest.py 的实现看，ingest/start会再次做文件名安全校验、大小与字数校验，并且对drama模板项目执行严格的剧本格式检查（build_import_format_check，require_scene_headers=True）；若格式检查级别为blocking，直接返回error_type: screenplay_format与完整format_check报告。通过后任务通过get_task_backend().enqueue_project_task以queue_kind="default"、task_type="ingest_fast"入队，并携带billing.billable_chars用于计费。响应返回task_type / task_id / task_key / backend / queue与提示语"导入任务已进入队列"。

摄入路由边界：摄入只有两个路径——/projects/{project}/ingest/upload和/projects/{project}/ingest/start。ingest_fast是任务类型而非 HTTP endpoint，禁止推断/ingest/init、/ingest/setup、/ingest_script、/ingest_fast等变体路径；这些路径的 404 不代表摄入模块未启用，只代表路径错误（SKILL.md §1 工具约束，api-reference.md 摄入章节）。

覆盖重建的强制二次确认：若项目已摄入过剧本，且要重新摄入/覆盖/替换，禁止直接调用ingest/start。第一次只问"是否要覆盖当前项目"，用户明确回答"覆盖"后才进入第二次确认；第二次必须告知"覆盖会清空/重建当前项目已有角色、分集、脚本、草图、音频、视频等流水线结果"，用户明确"确定/继续"后才允许调用，且必须传：

POST /projects/$PID/ingest/start Body: {"filename": "novel.txt", "rebuild": true}

这条硬性安全规则优先级高于"直接覆盖/马上重做"之类的一步式指令。

Step 3：配置项目——智能推荐 + 用户必选（SYNC）

摄入完成后，虾导分析小说内容再一次性推荐配置，而不是逐项询问。配置写入：

PATCH /projects/$PID Body: {"visual_style": "...", "narration_style": "...", "ethnicity": "...", "rhythm": "..."}

智能推荐映射规则

其中rhythm直接对应每 beat 的时长档位，直接影响后续视频时长预算。从 src/novelvideo/project_config.py 的默认配置看，项目配置默认值为spine_template: "drama"、visual_style: "chinese_period_drama"、ethnicity: "Chinese"；加载时若visual_style不在可用风格集合中，会回退到默认值，因此写入时务必使用仓库风格服务（src/novelvideo/services/style_service.py）认可的风格 ID。

用户必选（首次或用户主动问时展示）

视频后端的默认规则在 SKILL.md §5 中重复强调：默认统一为huimeng_seedance-1.0-pro-fast；1.5-pro只在用户明确指定 1.5 Pro / 有声 1.5 / Huimeng 1.5 时传入，不作为 dialogue beat 默认值；seedance_pro/seedance-1.5-pro是旧兼容值，默认不推荐。

Step 4：角色提取（ASYNC → build_characters）

配置确认后，进入角色提取。必须使用专用工具dramaclaw_build_characters（不要自己拼路径），它内部就是POST /projects/$PID/characters/build：

dramaclaw_build_characters # 触发提取（项目默认取 DRAMACLAW_PROJECT_ID） dramaclaw_get_task(task_type="build_characters", episode=0) # 轮询状态 SSE /projects/$PID/tasks/build_characters/0/stream # 或流式

完成后读取角色列表：

GET /projects/$PID/characters

Step 4 失败处理：若build_characters返回空结果，从小说内容分析角色后通过手动添加接口逐个补齐：

POST /projects/$PID/characters Body: {"name":"角色名","role":"主角","is_main":true,"gender":"female","age_group":"youth","description":"描述","face_prompt":"面部特征"}

手动添加角色的字段在 api-reference.md 角色章节有完整定义：name / role / is_main / gender / age_group / description / face_prompt。gender取值如female，age_group取值如youth。落地约束：POST/characters只传了name/role/gender/age时，不要说"已写入人设和外观提示词"（SKILL.md §1 grounding 规则）。

Step 5：face_prompt 前置检查（SYNC）

肖像生成依赖角色的face_prompt。进入肖像生成（Step 7）之前，必须先读取角色列表，检查核心角色/重要角色的face_prompt：

GET /projects/$PID/characters PATCH /projects/$PID/characters/$CHAR_NAME Body: {"face_prompt": "具体面部特征描述"}

缺失时优先使用专用工具：

dramaclaw_update_character_face_prompt(name="$CHAR_NAME", face_prompt="...")

规则要点：

• 内容边界：face_prompt只写脸部特征——发型、脸型、五官、肤色、年龄感、气质；不要写服装、身份、场景。
• 生成依据：根据角色名、性别、年龄段、description 生成一句具体面部特征描述。
• 补齐顺序：只有缺失角色全部补齐后，才允许进入肖像生成。
• 肖像报错处理：如果肖像任务报"请先设置面部特征 (face_prompt)"，停在当前角色，补齐该角色face_prompt后再重试，不要跳过或继续生成其它依赖项。

从源码看，face_prompt是角色数据的核心字段之一：src/novelvideo/api/routes/characters.py 在角色列表响应中直接透出face_prompt，并支持 PATCH 更新；在身份/肖像相关逻辑中，face_prompt会被用作appearance_prompt或作为身份图生成的兜底外观描述（"Identity has no appearance_details, face_prompt, or costume_image" 即表示三者皆空时无法生成）。这解释了为什么 Step 5 是 Step 7 肖像生成的硬前置。

Step 6：分集规划（ASYNC → build_episodes）

POST /projects/$PID/episodes/plan Body: {"target_episodes": 10, "planning_mode": "chapters"} GET /projects/$PID/tasks/build_episodes/0 SSE /projects/$PID/tasks/build_episodes/0/stream

planning_mode: "chapters"表示按小说章节切分分集，target_episodes为目标集数。完成后读取分集列表：

GET /projects/$PID/episodes

Step 6.5：角色分级标准

在分集规划完成后、肖像生成前，虾导按以下标准对角色分级，决定哪些角色需要生成肖像与身份图：

分级的意义在于控制肖像/身份图生成成本与一致性工作量：只有核心角色与重要配角进入图像生成管线。该分级结果会展示在 CP1 检查点，用户可在此处修改角色分级。

Step 7：肖像生成（SYNC）与 CP1 检查点

POST /projects/$PID/characters/$CHAR_NAME/portrait Body: {"style": "...", "ethnicity": "...", "model": "nanobanana"}

肖像按角色逐个生成（model默认nanobanana，style/ethnicity与 Step 3 配置保持一致）。从 pipeline.py 看，global.portraits_done的判定是：存在is_main角色，且每个主要角色都已有compute_portrait_path指向的肖像文件——即肖像未齐时next_step仍会指向portraits。

Step 7 完成 → 阶段过渡

无论手动/自动模式，初始化完成（全局五项状态齐备）后输出阶段摘要，例如：

"全局准备完成：项目 X，5角色(2核心3重要)，10集，肖像已生成"

随后按运行模式进入 CP1 检查点：

• 逐步确认模式：从 Step 4 起每个写操作步骤前都停下问用户，一次只推进一步。CP1 处展示核心角色 Portrait + 级别 + 分集标题，用户可改角色分级/外貌/分集数量，确认后再问「执行下一步吗」。
• 自动推进模式：自动选择下一步，但每轮最多启动一个写任务，启动后立即收口。到 CP1（展示核心角色+分集标题）时也必须停下，等待用户继续。

运行模式：逐步确认 vs 自动推进

运行模式在配置完成后由用户显式选择（references/run-modes.md）：

两种模式共用同一套 pipeline 步骤顺序与专用工具，区别只在于"是否每步解释并确认"；两种模式都不能在一轮里连续启动多个写任务。

模式一：逐步确认（step-by-step）

每一步的固定动作：

1. 报下一步（一句话）：要做什么（步骤中文名）+ 会调用的工具 + 前置是否已满足。例：「下一步：分集规划（dramaclaw_plan_episodes，目标 10 集）。原文与角色已就绪，可执行。」
2. 停下来问：「执行这一步吗？（继续 / 跳过 / 调整参数 / 停）」——然后结束本轮输出，等用户回复，不要自动往下做。
3. 用户回复后：继续/执行/好/下一步→ 先查当前任务状态；已有 queued/running 则告知后台正在生成中并停止；无运行中任务则调对应专用工具启动当前一步 →立即收口。跳过→ 不执行，直接报再下一步。改成 N 集/用某风格→ 按调整后参数执行。停/暂停→ 停在当前步。

初始化阶段（Steps 1-7）的逐步顺序为：上传小说 → 摄入(ingest) → 配置项目 → 角色提取dramaclaw_build_characters→ 角色 face_prompt 检查/补齐dramaclaw_update_character_face_prompt（仅缺失角色）→ 分集规划dramaclaw_plan_episodes→ 角色肖像dramaclaw_generate_portrait（逐个核心角色）。其中 Steps 1-2 是摄入准备动作，可合并成「准备阶段」一次确认；从 Step 3 配置项目起，每个写操作步骤都单独确认。

模式二：自动推进（bounded auto）

自动推进不是单轮跑完整集。为避免聊天超时和队列拥塞，必须遵守：

• 一次用户消息最多启动1 个写操作/异步任务；
• 启动任务成功后立即收口，告诉用户"已进入队列/已启动"，提示下一步等任务完成后继续；
• 不在同一轮等待长任务完成，不继续提交下一步；
• 任何失败、429、前置缺失、任务不存在、404 或网络错误都立即停止并反馈错误原文。

自动推进的含义是：用户下次说"继续"时，按pipeline/status.next_step自动选择下一步，不需要每步重新解释流程；但每轮仍只推进一个任务。

初始化阶段的执行纪律与常见错误处理

单轮执行上限（防超时硬规则）

一次用户消息最多只能启动1 个写操作/异步任务（plan/build/generate/optimize/render/audio/video/compose/reingest 等）。任务启动成功后必须立即收口回复"已进入队列/已启动"，不要继续轮询到完成，不要继续启动下一步，不要在同一轮补跑整条流水线（SKILL.md §1）。

错误即停

任一写工具返回ok:false、HTTP 4xx/5xx、identity_plan_required、Task not found、当前项目...队列任务已满、404 或网络错误时，本轮必须立即停止所有后续工具调用，把后端error/detail/message原文转成简短自然语言告诉用户，并说明应该等待、补哪个前置或重新选择正确入口。禁止在同一轮反复重试同一工具、改猜其它路径或继续往下执行。

静默执行规则

仅对本轮被允许执行的单个步骤适用；不得用"静默执行"作为连续推进多个写任务的理由。执行本轮单步操作时，不要在步骤内部叙述"正在做什么/刚做了什么/接下来要做什么"，完成或启动后用一段话输出结果/状态。

常见前置缺失对照

从初始化到逐集生成的衔接

初始化（Steps 1-7）完成后，pipeline/status的global五项状态全部就绪，next_step进入逐集维度（identity_plan → identity_images → script → sketches → coloring → global_optimize → first_frames → tts → video → compose → done）。此时：

• 逐步确认模式：CP1 确认后，每集从 Step 8（身份规划dramaclaw_plan_identities）开始逐步推进，每完成一集问「继续做第 N+1 集吗？」；
• 自动推进模式：用户每次说"继续"，按next_step自动选择并只推进一个任务；
• 更细的逐集步骤与 API 契约见 playbooks/episode.md 与 references/pipeline-details.md；API 端点不确定时优先查 references/api-reference.md。

一句话收束：初始化阶段的灵魂是"状态驱动"——永远以pipeline/status.next_step为准，一次一步、启动即收口、错误即停；Step 1-7 走完，剧本才真正变成了"可逐集制作"的工程。