集成本地 Codex App Server 作为短剧制作总导演

Codex 本地总导演集成规格

Problem Statement

火宝已有剧本、角色、场景、分镜、图片、视频和合成能力，但用户需要在一个统一的 AI 对话界面中描述制作意图，并由本机已登录的 Codex 理解上下文、规划步骤、调用这些能力和反馈结果。

Solution

在剧集制作工作台右侧嵌入可折叠 Codex 对话面板。火宝后端管理本机 Codex App Server 生命周期，建立项目级会话并附加当前剧集上下文。Codex 作为总导演/编排代理，通过受控制作工具调用现有制作 Agent、数据库服务和媒体生成服务。前端以 Markdown 和结构化工具事件展示回复、差异预览、确认请求、媒体结果和任务进度。

User Stories

1. 作为编剧，我想在工作台内直接向 Codex 描述改写要求，以便不离开当前剧集完成剧本创作。
2. 作为编剧，我想让 Codex 读取当前剧集的原始内容和格式化剧本，以便它基于真实上下文工作。
3. 作为编剧，我想预览剧本修改差异并确认后保存，以便避免误覆盖内容。
4. 作为制片人，我想让 Codex 提取当前剧集的角色、场景和关键道具，以便减少重复录入。
5. 作为制片人，我想让 Codex 复用项目已有资产，以便保持跨剧集一致性。
6. 作为美术人员，我想让 Codex 生成和优化角色、场景、道具提示词，以便快速准备视觉资产。
7. 作为美术人员，我想选择 Codex 图像能力或火宝图片服务，以便按任务选择合适的生成路径。
8. 作为用户，我想在对话中看到图片生成结果，以便立即判断是否需要重试或修改。
9. 作为用户，我想看到工具调用步骤和任务进度，以便理解 Codex 正在执行的操作。
10. 作为用户，我想在项目内跨剧集继续同一 Codex 会话，以便保持创作意图连续。
11. 作为用户，我想新建独立会话，以便进行不影响主流程的创意讨论。
12. 作为用户，我想让读取操作自动执行，以便对话保持流畅。
13. 作为用户，我想在可逆写入前确认，以便控制数据变更。
14. 作为用户，我想在删除、付费图片/视频生成和整集合成前逐次确认，以便控制风险和成本。
15. 作为桌面端用户，我想让火宝自动检测本机 Codex 是否可用，以便知道本地代理能否启动。
16. 作为桌面端用户，我想在 Codex 服务重启后恢复或重新建立项目会话，以便继续工作。
17. 作为服务器部署用户，我想在本地 Codex 不可用时继续使用现有远程 AI 配置，以便不影响原有功能。
18. 作为用户，我想看到 Codex、工具和媒体任务的错误与重试入口，以便从失败中恢复。

Implementation Decisions

• 主要 seam 是后端 Codex 编排服务；它封装 App Server 连接、项目会话、剧集上下文、工具注册、权限决策和事件转发。
• 后端按需启动并管理本机 codex app-server --stdio；前端只连接火宝后端，不直接启动或暴露 Codex 进程。
• Codex 是总导演/编排代理；现有四个制作 Agent 和图片、视频、FFmpeg 服务继续作为受控工具。
• 会话按项目归属，当前剧集作为动态上下文；支持新建独立会话。
• 工具结果统一为结构化事件，包括文本、工具调用、确认请求、差异预览、媒体结果、进度、错误和完成状态。
• 读取默认允许；剧本保存、资产创建和其他可逆写入需要用户确认；删除、付费生成、视频合成等高风险操作逐次确认。
• 图片能力双通道并行：Codex 可用的图像能力和火宝现有图片服务都可产出制作资产，平台统一持久化、展示和追踪。
• 首期覆盖对话、剧集上下文、剧本读写、资产提取、双通道图片和任务回写；视频生成、整集合成和复杂多代理协作属于后续阶段。
• 首期优先支持本地开发和 Electron；服务器模式继续使用现有 AI 配置，不依赖个人本地 Codex 登录状态。
• 需要增加 Codex 会话、事件和确认状态的持久化模型，并与现有生成任务日志关联。

Testing Decisions

• 测试外部行为：会话创建、上下文注入、工具权限、确认流程、事件顺序、错误恢复和结果回写。
• 后端沿用现有路由和服务结构测试风格，增加 App Server 协议适配器的可替换测试端点或模拟传输。
• 前端测试面板渲染、事件流状态、确认/取消、差异预览和媒体卡片，不测试 Vue 内部实现细节。
• 至少覆盖 Codex 不可用、App Server 重启、工具失败、重复消息和高风险操作拒绝等场景。

Out of Scope

• 不替换现有四个制作 Agent。
• 不在首期支持远程服务器运行个人 Codex。
• 不直接复刻 Codex 桌面 App 的完整 UI。
• 不在首期实现视频生成、整集合成和多用户协作改造。
• 不绕过火宝现有 AI 服务配置、任务系统和媒体存储。

Further Notes

Codex 的本地权限必须限制在火宝项目工作目录和明确的数据目录内。媒体生成仍可能产生外部 API 费用，确认卡片应显示提供商、模型和预计任务类型。