Manage Project

项目管理工具集

提供 project.json 的角色/场景/道具批量写入、项目级 settings 与项目概述编辑，以及视频模型能力查询。

工具一览

分集规划（拆集/调整）由服务端工具 mcp__arcreel__plan_episodes / mcp__arcreel__reset_episode_planning 完成，调整已规划内容走「重置 + 重新规划」，流程见 video-workflow 阶段 2。

角色/场景/道具写入

经 mcp__arcreel__patch_project 工具写入（项目名由 session 绑定，无需传参）。按 table 分别调用， 每个 entry 以 name 为键 upsert：name 不存在则新增、存在则合并改字段。修订已有资产描述需用户显式 意图驱动（避免静默覆盖人工编辑过的字段）。本集新出现的资产由脚本规划带出、内容确认时登记，不需要在这里预先写入。 aliases（别名）是字符串列表，只供脚本规划认人，不能写进引用。

mcp__arcreel__patch_project({"table": "characters", "entries": {"角色名": {"description": "...", "voice_style": "..."}}})
mcp__arcreel__patch_project({"table": "characters", "entries": {"角色名": {"derivatives": {"战斗装": {"description": "换上黑色重甲，其余外观保持不变"}}}}})
mcp__arcreel__patch_project({"table": "scenes", "entries": {"场景名": {"description": "..."}}})
mcp__arcreel__patch_project({"table": "props", "entries": {"道具名": {"description": "..."}}})
mcp__arcreel__patch_project({"settings": {"episode_target_units": 1000}})
mcp__arcreel__patch_project({"settings": {"episode_target_duration": 90}})
mcp__arcreel__patch_project({"settings": {"source_language": "en"}})
mcp__arcreel__patch_project({"settings": {"narration_voice": "Ethan", "narration_speed": 1.2}})
mcp__arcreel__patch_project({"overview": {"genre": "悬疑", "theme": "复仇与救赎"}})

角色条目的 derivatives 表登记同一角色在本体之外的另一套外观（跨场景持续存在、可由图像生成表现）， 脚本里引用作 @[角色/衍生]。它按衍生名合并：同名改描述、新名加入、未提及的衍生原样保留（连同其资产图）。 衍生只写 description——相对本体的变化，图像编辑指令的口吻；资产图由生成流水线回写。 改衍生名走衍生子资源的改名端点（Web 端角色卡「衍生」浮层），patch_project 写新名只会新建一条。

三种调用形态三选一：传 {"table", "entries"} 走资产 upsert，传 {"settings"} 走顶层字段写入， 传 {"overview"} 走项目概述编辑；同时给出多个或都不给会被拒。settings 白名单字段：

• episode_target_units：int >= 1 设置 / null 清除。每集目标体量（按 source_language 解读为阅读单位），分集规划工具按它把握每集切分体量；未设置时工具按 episode_target_duration 经口播语速折算出等效体量，不必为了控体量而先问用户字数
• episode_target_duration：10–600 的整数秒设置 / null 清除。单集成片目标时长，脚本规划据它决定本集拆多少个分镜 / 视频单元；未设 episode_target_units 时分集规划也按它折算每集塞多少原文（episode_target_units 显式设置时以后者为准）。软目标（可被内容需要覆盖，超出只提示不阻断），仅非广告/短片项目可写，ad 项目写入会被拒（整集体量已由 target_duration 预算表达）
• source_language："zh" / "en" / "vi" 设置 / null 清除。优先级：用户显式配置 > 自动推断——用户明确指定语言时即可写入（不限于 overview 跳过或失败的场景）；无用户显式确认时不要自行猜测写入，正常路径由 overview 生成自动落盘。发现显式配置与自动推断 / 源文实际语言不一致时，提醒用户（WARN）并按显式配置继续，不阻塞流程
• brief：字符串设置 / null 清除。创作诉求短文本，仅广告/短片项目（content_mode=ad）可写，其他项目类型写入会被拒
• narration_voice：非空字符串（音色 id 照供应商文档）设置 / null 清除。项目 TTS 快照里的旁白音色，只影响当前项目；TTS 配音项目必须有音色，清除会被拒
• narration_speed：正的有限数值（如 1.2）设置 / null 清除。项目 TTS 快照里的配音语速，只影响当前项目；清除表示不向供应商传语速
• character_voice_binding："prompt" / "reference_audio" 设置 / null 清除回默认（prompt）。角色声音靠什么约束：prompt 把角色 voice_style 写进提示词做软约束，reference_audio 才把角色已设的参考音频随请求挂给视频模型换取原生音色一致。要原生一致须两件事同时成立：本项设为 reference_audio 且该角色配了参考音频

generation_mode、grid_storyboard 不在白名单内，patch_project 会拒绝写入：generation_mode 项目创建后不可更改，用户要求改生成方式（storyboard ↔ reference_video）时明确告知不可更改、无绕过方式；grid_storyboard 由用户在 Web 设置页开关，用户要求改宫格装配时指引其前往设置页操作，并告知开关只影响后续生成——已生成的分镜图不会自动失效，要按新装配方式出图须显式重新生成对应分镜。

overview 白名单字段：synopsis / genre / theme / world_setting，merge 语义（只改传入字段、 概述不存在时创建）。修订概述需用户显式意图驱动（避免静默覆盖人工编辑过的字段）。

工具返回会区分新增 N 个 / 合并改字段 N 个,并显式列出被忽略的字段（reference_image / character_sheet 等系统管理字段、type / importance 等已废弃字段）。结构非法（如缺 description）时不落盘并返回 is_error: true。 严禁用 Write/Edit/Bash 直接改 project.json——改字段走 patch_project 工具，改资产名走 rename_asset 工具， 两个资产合一走 merge_asset 工具。patch_project 按 name upsert，用它改名只会「新名新建 + 旧名残留」且不更新任何引用。

合并重复登记的资产

同一个人、地点或物件被登记成两个同表资产时（如「老王」与「王建国」），用 mcp__arcreel__merge_asset 把 source 并入 target。合并不可撤销，按以下顺序进行：

1. 与用户确认保留哪一个作 target，以及并法：同一外观并为本体（默认）；source 是 target 的另一套外观 （如「黑衣人」是主角易容后的样子）时传 as_derivative: true，只适用于角色。
2. 传 dry_run: true 调用，把回执里按集列出的引用改写数、将过期的分镜图与视频数，以及 source 不保留的内容 （描述、资产图及版本历史、声音设置、原图、参考音频）转述给用户。source 的描述里有 target 需要的信息时， 一并问用户是否先经 patch_project 补进 target。
3. 得到用户同意后，去掉 dry_run 再调用一次执行。

查视频模型能力

通过 MCP 工具查询（项目名由 session 绑定，无需传参）：

mcp__arcreel__get_video_capabilities({})

生成模式由项目唯一决定，无集级覆盖，能力查询全项目同一口径，不接受 / 不需要 episode_id 参数。

返回：JSON 文本，含 provider_id / model / supported_durations[] / max_duration / max_reference_images / source / default_duration / episode_target_duration / content_mode / generation_mode；narration / drama 的参考生视频项目另含 reference_unit_durations（with_references / without_references 两套生效档位，按视频单元有无 @ 引用分别适用；units 按 unit_id 给出每个已有正式视频单元由服务端按可用参考图判定的桶 hydrated_capability、该桶生效档位 allowed_durations、事实失败 problem，以及声明引用与可用参考图分裂时的 problems / unavailable_references——已有单元的桶与档位以它为准）；ad 项目不返回该字段——ad 的机器字段 unit 是从 shots[] 派生的轻量索引，分镜时长不受档位枚举管辖（规则见 video-workflow/SKILL.ad.md），不要等待该字段、也不要照档位重排 ad 分镜时长。

用途：所有 generation_mode（storyboard / reference_video）的脚本规划子智能体在执行时自查，用于决定单分镜 / 视频单元时长。决策优先级（高到低）：硬约束（storyboard 分镜时长必须取自 supported_durations；narration / drama 的 reference_video 视频单元时长必须取自该视频单元引用状态对应的 reference_unit_durations 档位；ad 的分镜时长按 SKILL.ad.md 的自由整数规则）> episode_target_duration / default_duration 偏好（前者是本集各单元时长合计的软目标，据它决定拆多少个；后者非 null 时作单个单元的默认值）> 内容需要（reference_video 按该视频单元内容实际需要的长度取档；narration / drama 长句、复杂画面可取更长值）。装不下时重拆视频单元，不违约时长。

错误：项目未找到或模型能力无法解析时返回 is_error: true，文本中包含原因。