# 项目综述（bgxiong-ai-story）— 比格熊数字导演工作站
| 项 | 说明 |
|----|------|
| **文档性质** | 面向非技术读者的项目全景：市场背景、产品与技术要点、阶段性成果与方向（中性表述）。 |
| **统计口径** | 工程规模统计截至 **2026-07-18**（v0.2.721），仅统计个人自研源码与内部文档，不含第三方依赖库与自动生成的安装包内容。 |
## 1. 定位概览
比格熊数字导演工作站（bgxiong-ai-story）是一套 **AI 驱动的多模态影视前期制作工作站**，产品形态为 **安装在电脑上的桌面客户端软件**（而非浏览器网页产品）。它把故事结构（项目—剧集—场次—片段/镜头）、角色与演员资产、分镜故事板、文本 / 图像 / 视频 / 语音生成、对白编辑与配音、视觉精修、自动剪辑与专业软件导出等 **全流程** 放在 **同一套本地工程与同一应用窗口** 里闭环完成，面向影视、短视频、动漫、广告与教育实训等 **前期创意到粗剪交付** 场景。
产品名称「比格熊数字导演工作站」体现其核心理念：**用 AI 将「一句话故事」自动拆解为完整的可视化制作管线**——从故事种子到剧集、场次、镜头、分镜图、视频成片、配音、自动剪辑、最终导出到专业剪辑软件（如 Final Cut Pro），全链路自动化，大幅降低短视频与动画制作门槛。
相较于 v0.2.618 时期的「AI 分镜工作台」定位，当前 v0.2.721 已演进为 **覆盖从创意到粗剪交付全链路的数字导演工作站**：新增了语音配音工作台、视觉精修编辑工具、AI 自动剪辑引擎、NLE 时间线导出、故事工程备份与迁移、跨平台架构抽象等重大能力模块。产品正从「生成工具」走向「制作管线」。
云端 AI、开放平台接口在本产品中的角色，更接近 **用户按需接驳的能力插件**：用来完成某次生成或某种模型推理；**工程本体、数据结构、任务编排、设置与日志** 仍以客户端与本地存储为主轴。这与「做一个网站外壳，里面嵌各家网页或只转发接口」有本质区别——前者是 **可离线打开的工程文件型生产力工具**，后者往往离不开会话、Cookie 与远端页面形态，数据和体验的掌控链也更短。
---
## 2. 市场视角
- **需求背景**：多工具并行（文档、表格、浏览器里各家模型页面）容易造成上下文断裂、素材与版本散落；创作方难复盘「用了哪家模型、最终下过怎样指令」。短视频与 AI 动画行业爆发式增长，创作者需要从「一句话创意」到「可交付粗剪」的一站式工具，而非多个孤立工具的拼凑。
- **产品切入点**：用 **结构化本地工程** 承接创意流程；用户在设置与各界面里 **明确选定** 文本、配图、改图、视频、语音等通道，系统按选择执行，**不做**用户未同意的暗中替换，降低合规与品控风险。 **自动剪辑引擎** 将分镜素材自动组装为时间线，并导出为 Final Cut Pro 等专业软件可直接打开的项目文件，打通了「AI 生成 → 专业后期」的最后一公里。
- **典型用户**：独立创作者、小型制作组、内容团队、MCN 机构、院校实训等需要在 **可控环境** 下完成从创意到粗剪全流程的群体。
---
## 3. 为什么是桌面客户端
下面几条概括 **客户端路线相对「云端套壳」或「纯浏览器工具」** 的差异；不是说「完全不用云」，而是 **云服务于生成能力，客户端承载创作资产与工业流程**。
- **工程与数据默认在用户自己电脑上**
项目、章节场次关系、分镜结构、任务记录、素材引用等落在 **本地数据库与本地目录**，用户对自己的剧本与物料拥有直观的 **占有感与备份方式**（拷贝文件夹、整机备份、离线归档、工程导出导入），而不是默认「全部托管在第三方网页账号背后」。
- **不绑死在浏览器标签页的生命周期**
关闭浏览器、清理站点数据、某家网站改版或下线，通常 **不会**一笔勾销你的「工作台形态」。客户端像普通办公软件一样常驻本机，打开即是同一套界面与同一套工程逻辑。
- **云端是「可选外挂」，不是「唯一脊梁」**
需要文生图、图生图、视频、语音等时再按用户选择去访问各家开放平台；同时支持 **本地装载的大模型**（llama.cpp 文本推理、Whisper 语音识别、本地 TTS 语音合成），弱网、断网或保密环境下仍可浏览与编辑工程结构、跑本地推理，**不把「能上网」当作使用产品的绝对前提**。
- **更深地接入本机能力**
日志与诊断、数据目录配置、可选本地工作流（如 ComfyUI）、大批量读写与路径解析、媒体运行时（FFmpeg 集成）、磁盘清理、运行时自动下载与管理（llama、Whisper、TTS 引擎、FFmpeg）等，都是 **操作系统级客户端** 天然擅长的领域；这些若仅靠网页沙箱，往往处处受限或体验割裂。
- **复杂界面与大体量交互敢往深了做**
例如大面积无限画布、多标签重度工作台、长列表任务中心、语音波形编辑、视频预览与帧定位——按 **桌面性能预期** 做虚拟渲染与内存策略，而不是在手机浏览器或嵌套网页里「凑合能用」。
- **隐私与对内合规更好叙事**
敏感台词与设定默认留在本机；对外发出的仅是用户在某个按钮上 **明确触发** 的那次生成请求。机构关心「剧情与素材出不出域」时，客户端架构更容易给出清晰边界。
- **产品心智：工具 vs 入口**
「云端套壳」常常是聚合入口，换一个模型页等于换一个站；本产品则在客户端内固定 **同一套菜单、同一套设置与能力映射、同一套任务与日志语义**，长期使用成本低，也更像 **正经的生产软件**。
---
## 4. 产品与系统概要
- **形态**：Windows 等环境下的 **桌面应用**，界面为现代 Web 技术呈现，与 **本机 Rust 后台服务**（Tauri 2）协同工作，数据主要落在本机。
- **数据**：核心资料使用 **本地 SQLite 数据库**持久保存；数据库采用 **50+ 张表** 覆盖故事结构、画布状态、AI 任务、媒体轨道、语音合成、权限、备份迁移等全领域；数据库、对外接口与界面之间 **字段命名规则统一**（冻结词表 + SSOT 索引），减少「同名不同义」导致的差错。
- **架构**：后端已落地 **四层分层架构**（领域层 → 应用层 → 基础设施层 → 组合层），通过 **170+ 个持久化适配器** 实现领域逻辑与数据库的解耦，为未来扩展（内存存储、远程存储、iOS 适配）奠定基础。
- **智能能力**：既支持对接 **云端** 图像、视频、语音等开放平台能力（即梦、可灵、通义万相、Seedance、OpenAI、DashScope 等），也支持 **本地大模型**（llama.cpp 文本推理、Whisper 语音识别、本地 TTS 语音合成），兼顾联网弹性、离线可能以及隐私敏感场景。
- **运行时管理**：外挂运行时（llama.cpp、Whisper、TTS 引擎、FFmpeg、Python）通过 **版本化 CDN 清单 + 自动下载 + 断点续传** 统一管理，用户无需手动配置复杂环境。
- **运维与排障**：关键操作链路会写入 **本地日志**（tracing 分级日志 + 日志保留策略）；涉及后台任务时，从「已提交 → 执行过程 → 结束结果」分段留痕，便于出问题后按时间线追查，而不是只靠口头描述。
- **自动化扩展**：同一套故事与素材的领域模型，还提供 **命令行工具**与**离线数据库迁移脚本**，便于以后做批处理、脚本或与外部系统对接。
### 4.1 设计上值得单独说的几点
- **用户选定的模型才生效，禁止暗中换通道**
每一次云端或本地推理，都必须对应用户在当前界面或设置里 **明确选好的服务商与模型**；全局默认值只在「用户尚未选择」时起补充作用。**不允许**对用户没选中的通道自动轮询、悄悄兜底，也不允许例如「参考图失败就无声改成纯文字生图」这类隐蔽替换。这在消费级工具里不常见，但对 **采购合规、成本可归因、结果可复现** 很重要；产品上用统一的模型选择与「记住上次实际使用」的体验，避免多套界面、多套记忆规则打架。
- **最终指令与任务过程可追溯**
在 **真正发出请求之前**，会把下发给所选模型的 **最终文本指令** 记入可检索日志；纳入任务中心的流程则按 **提交 → 进行中更新 → 结束汇总** 留存。多步骤、多模态的长链路事后可以对齐时间线，有利于长期维护与企业环境交付。
- **故事板：最终台词稿单一来源**
数据库、接口与界面之间遵循同一套数据约定；分镜故事板里，**最终送给模型的那段提示** 集中在约定的分段内容里统一维护，而不是在多个地方各存一份、时间一长就对不上。这样导出、备份或多端协作时不容易分叉。
- **演员库可以不绑死在某一个故事上**
「演员」允许作为 **全局可复用资产** 管理，不必先创建某个故事才能建档；跨项目共用肖像与设定时，边界更清晰，后续若做协作或素材库也更容易扩展。
- **设置里的「能力映射」统领全站的模型列表顺序**
文本、配图、改图、视频、语音等能力，按账号区块与模型行的顺序组成清单，再反映到各功能页的模型下拉列表；顺序与是否隐藏由用户在设置里 **保存**，**不跟着**厂商网页或偶然的网络返回顺序飘。多家供应商加多台本地模型混用时，这是 **列表可控、心智稳定** 的关键。
- **自研无限画布：为「很多张图 / 很多卡」做的性能策略**
大面积拖拽、缩放、摆卡片（演员形象墙、场次、分镜浏览、片段画布、Clips 片段画布等）共用一套 **自研画布内核**，**不依赖**额外的重型第三方画布商业包。做法是分层减负：**只重点处理屏幕附近的内容**（外加一圈缓冲，避免边缘闪烁）、**分批加载**避免一口气创建成百上千张卡片卡住界面、对视野外的元素 **减少无谓绘制**，并对视频、大图在 **离开视野后主动降级或收回资源**，避免「划走了还在后台解码占内存」。缩放以指针为中心、手感一致；瀑布流排布与画布核心分开，多处界面复用同一套交互习惯。内部规格文档中对 **数百个节点** 量级写了性能目标（首次打开耗时、拖动流畅度、内存占用上限），属于「先定体验指标再实现」的基础设施思路。**v0.2.721 新增画布节点编组功能**，支持将多个节点打组管理，大幅提升复杂画布的整理效率。
- **统一 AI 端点注册表与调度层**
后端 `open_platform` 模块实现统一端点注册表（39 个源文件），即梦、可灵、通义万相、Seedance、OpenAI 等各家接口各异，但业务管线只需调用统一接口。新增厂商只需注册新端点，业务管线零侵入，可持续升级。支持文生图、图生图、图生视频、文生视频、TTS 语音合成、唇形同步等多种生成能力。
- **通用有向图引擎（GraphCore）**
自研通用图引擎模块，提供有向图的 CRUD、拓扑排序、连通性分析、性能优化等能力，统一支撑分镜故事板、片段画布、Clips 片段画布等多个画布场景的节点连线与关系管理，避免各模块重复造轮子。
- **AI 任务队列与状态机**
内置完整的 AI 任务队列系统（30 个源文件），含状态机、调度器、分发器、14 种任务类型 Handler、持久化层与事件总线。支持任务并发控制、进度心跳、失败重试、配额管理，面向批量生成场景。
- **本地 AI 能力内置**
通过 llama.cpp 集成本地文本推理（含 llama-server 灵活模型加载），通过 Whisper 集成本地语音识别，通过本地 TTS 引擎（VoxCPM、IndexTTS 等）集成本地语音合成。在离线、保密或低成本场景下，核心 AI 能力不依赖云端。所有本地运行时通过统一的版本化管理与自动下载机制分发，用户无需手动配置。
- **权限系统与配额管理**
内置可插拔权限框架（权限后端、装饰器、审计日志、缓存层），支持用户激活、账号管理、AI 任务日配额控制，面向机构采购与团队使用场景。
- **全链路视频生成管线**
从分镜图到视频成片，支持多家视频模型（即梦、可灵、Seedance、通义万相等）的统一调度，含视频定价、限流、任务生命周期管理、唇形同步（5 种适配器：Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵）、TTS 语音合成、字幕生成等完整管线。
- **ComfyUI 本地工作流深度集成**
不仅是简单调用，而是完整集成：HTTP/WebSocket 双协议客户端、工作流扫描与编译器、占位符注入、自定义工作流支持、图像/视频双管线、设置管理等（27 个源文件），让用户可以用 ComfyUI 自定义本地生图/生视频流程。
- **FFmpeg 媒体运行时**
统一的媒体处理层，封装 FFmpeg 的定位、参数构建、执行、探测解析，提供媒体能力注册与格式选择，供视频转码、音频提取、字幕合成、自动剪辑、波形生成等全链路使用。
- **内部 HTTP 桥接服务（Local Bridge）**
内置本地 HTTP 服务（40 个源文件），作为前端界面与本地 AI 能力之间的高效桥梁。承载自动剪辑、字幕识别、高光检测、封面生成、图像处理等长耗时任务，支持作业队列、进度推送、会话管理与会话级安全守卫。这套架构让本地重任务不阻塞界面交互，用户体验更流畅。
---
## 5. 当前成果（产品与工程）
**功能范围（摘要）**
主要功能页覆盖故事总览、剧集与场次看板、场景与素材管理、分镜故事板与镜头工作台、片段画布（无限画布 + 节点编组）、视频片段管理（Clips）、角色与演员、**对白编辑与配音工作台**、**语音合成工作台（TTS Studio）**、**配音项目管理（Voice Studio）**、**视觉精修编辑工具**、**AI 自动剪辑引擎**、**NLE 时间线导出（Final Cut Pro）**、**故事工程备份与迁移**、任务中心、帮助学习中心等；设置中提供账号与绑定、**能力与模型映射**、可选本地工作流（如 ComfyUI）、**运行时管理（自动下载与版本控制）**、本地模型管理、TTS/视频实验室、诊断与数据存储位置、BUG 报告与日志上云等；界面文案支持中英文。
**研发体量（静态统计，便于理解投入）**
| 类别 | 文件数 | 代码行数（约） |
|------|--------|----------------|
| 后端桌面服务（Rust） | 1,542 | 31.1 万 |
| 前端界面与逻辑（TS/TSX） | 3,515 | 43.3 万 |
| **自研程序合计** | **≈ 5,057** | **≈ 74.4 万** |
| 内部设计 / 规范 / 记录文档 | ≈ 1,534 | — |
**技术栈明细**
| 层 | 技术选型 |
|----|----------|
| 桌面壳 | Tauri 2（Rust 进程托管，非 Electron） |
| 前端框架 | React 19.2 + TypeScript 5.9 + Vite 8 |
| 前端测试 | Vitest 4.1 |
| 后端语言 | Rust（edition 2021） |
| 数据库 | SQLite（WAL 模式 + r2d2 连接池） |
| 架构模式 | 四层分层架构（领域层 / 应用层 / 基础设施层 / 组合层） |
| 持久化层 | 170+ SQLite 适配器，依赖反转设计 |
| Rust 依赖 | 771+ 个 crate |
| AI 调度 | 统一端点注册表（open_platform），云端/本地双模式 |
| 本地 AI | llama.cpp（文本推理）+ Whisper（语音识别）+ 本地 TTS（VoxCPM、IndexTTS 等） |
| 运行时管理 | 版本化 CDN 清单 + 自动下载 + 断点续传 |
| 媒体处理 | FFmpeg 集成（视频转码、探测、合成、波形生成、静音检测） |
| 本地桥接 | 内部 HTTP 服务（作业队列、进度推送、会话管理） |
| 图像生成 | 即梦、通义万相、ComfyUI 等 |
| 视频生成 | 即梦、可灵、Seedance、通义万相等 |
| 语音合成 | 多家云端 TTS + 本地 TTS 引擎（适配器架构） |
| 唇形同步 | 多适配器架构（Hedra、LivePortrait、MuseTalk、Wav2Lip、可灵） |
| 自动剪辑 | AI 驱动的镜头边界检测（BTD）+ FCPXML 时间线生成 |
| NLE 导出 | Final Cut Pro XML（FCPXML）导出 |
| 本地工作流 | ComfyUI 完整集成（HTTP/WebSocket、工作流编译器、管线注入） |
| 自动更新 | Tauri Updater（被动安装模式，支持静默后台下载） |
| 权限系统 | 可插拔权限框架 + 日配额管理 + 审计日志 |
| 异步运行时 | Tokio（多线程） |
| HTTP 客户端 | reqwest 0.13（native-tls、HTTP/2、gzip、multipart、stream） |
大量内部文档对应作者在 **数据约定、交互规范、故障排查与版本迁移** 上的持续沉淀，便于长期维护与日后扩展。
---
## 6. 后端核心模块地图
后端共 1,542 个 Rust 源文件，按职责划分为以下核心模块群：
| 模块群 | 关键内容 | 职责 |
|--------|----------|------|
| **故事管线** | `story_chapter_pipeline`、`chapter_scenes_plan`（pipeline / plan_granularity / scene_shots_pipeline / content_parser / llm_client）、`story_sync_pipeline`、`story_role_generation` | 故事→剧集→场次的 LLM 级联生成；场次规划粒度校验与自动修复；故事圣经同步管线；故事角色 AI 生成 |
| **分镜引擎** | `storyboard_*`（specs / stage_a / stage_b / merge / rules / render / graph / composition_compiler / image_prompt_lint / compiler_lint_contract / shot_membership / shot_number_policy / playbook / continuity / shot_prompt_optimize / stage_a_inputs / stage_b_ingest） | 分镜生成、导演化语义层、质量门、渲染输出、构成编译器、提示词校验、编译器校验合约、镜头成员关系、镜头编号策略、**分镜剧本动作语法**、**镜头连续性批量编排**、**镜头提示词智能优化** |
| **提示词工程** | `ai_prompts/`（builtins×35+ / render / types / registry）、`prompt_expert/`（gate / registry / genre_axis / style_axis / slots） | 内置提示词模板库、渲染引擎；**动态提示词专家系统**：叙事类型轴 + 风格轴 + 插槽组装，替代硬编码模板 |
| **叙事与风格** | `narrative_genre/`、`creative_format/`、`ai_output_language/`、`story_style_domain.rs` | 叙事类型定义、创意格式定义、AI 输出语言门控、故事级画面风格单一来源 |
| **AI 任务队列** | `ai_queue/`（state_machine / scheduler / dispatcher / facade / events / persistence / handlers×14） | 完整任务队列：状态机、调度、分发、14 种 Handler、持久化、配额管理 |
| **开放平台** | `open_platform/`（provider / dispatch / gen_error / provider_metadata / tts / jimeng / volc_* / kling_* / dashscope_* / qwen / seedance） | 统一端点注册表、多厂商适配、错误归一化 |
| **图像生成** | `image_generation/`（multi_view / persist / pipelines / refine_service / refine_session_store / service / visual_style） | 生图管线、多视角定妆照、视觉风格词表注册表、精修服务与会话存储 |
| **视觉编辑** | `visual_edit/`（bridge / capabilities / ops / persist / storage / submit）、`refine_local_edit/`（ops / types）、`refine_regions/`（guide / preview / selection） | **图像精修编辑管线**：裁剪、蒙版笔刷、旋转、笔刷合并；区域引导与选择；提交校验与持久化 |
| **图像布局分析** | `image_layout_analysis/`（vision_adapter / cache / graph / vocabulary / validate / staging / consumers） | **AI 驱动的画面构成分析**：视觉模型适配、缓存层、构图词汇表、轴连续性校验、提示词片段生成 |
| **外观提取管线** | `appearance/`（extract / batch_extract / ingest / persist / sanitize / digest / bundle_schema / effective_portrait_prompt / narrative_assembly / ensure） | 角色外观特征提取、批量处理、持久化、提示词组装 |
| **演员描述优化** | `cast_portrait_description_optimize/`（catalog / optimize / orchestrate / router / validate） | 演员定妆描述智能优化、多模型路由、结果验证 |
| **定妆照构建** | `portrait_build/`（catalog / compose / digest / ipc / resolve / types / validate） | **定妆照构建管线 v2**：目录化配置、组合引擎、摘要、校验、前后端 IPC 对齐 |
| **视频管线** | `video_task`、`video_task_poller`、`video_param_mapper`、`video_rate_limiter`、`video_pricing`、`segment_video_pipeline`、`segment_video_narrative/`（compose / hydrate / resolve / optimize_parse / persist）、`video_prompt_compiler`、`video_prompt_pipeline/`（vendor_optimize） | 视频任务调度、轮询、参数映射、限流、定价；**片段视频叙事引擎**：组装→注入→解析→优化→持久化；提示词编译与供应商优化 |
| **视频后期** | `video_post_process/`（preflight / provider / resolve / volc_mediakit）、`video_delivery/`（capabilities / planner） | **视频后期处理管线**：预检、供应商解析、火山引擎 MediaKit 集成；**视频交付规划器** |
| **自动剪辑** | `auto_edit/`（btd / cfr_proxy / cleanup / detect / subtitles / types）、`autocut_fcpxml/`（time / xml_util） | **AI 自动剪辑引擎**：镜头边界检测（BTD）、CFR 代理生成、字幕对齐、素材清理；**FCPXML 时间线生成**，导出至 Final Cut Pro |
| **Clips 导出** | `clips_export/`（archive_orphans / copy_plan / fcpxml / naming / paths / progress / resolve_media / scan / scan_history） | **片段工程导出**：FCPXML 生成、媒体文件归档、复制计划、进度推送、历史扫描 |
| **高光检测** | `highlight_pipeline/`（prompt / run / validate） | **AI 高光片段检测**：LLM 驱动的内容分析，自动识别精彩片段 |
| **ComfyUI** | `comfyui/`（client / commands / pipeline / workflow / http / settings / analyzer） | 本地 ComfyUI 完整集成（双协议、编译器、管线） |
| **本地 AI** | `local_ai/`（text_generation / speech_recognition / llama_server / model_manager / speech_synthesis） | llama.cpp 文本推理、Whisper 语音识别、本地 TTS 引擎（VoxCPM、IndexTTS 适配器） |
| **运行时管理** | `runtimes/`（download / llama / whisper / tts / ffmpeg_ensure / python / locator / registry / migrate / active） | **统一运行时生命周期**：版本化 CDN 清单解析、自动下载安装、版本迁移、激活管理 |
| **语音与配音** | `speech/`（adapters×4 / dialogue_audio_state / materialize / synthesis_request / tts_mode_capability / tts_reference_audio / tts_reference_prepare）、`voice_studio/`（export / model / repository / segment_text / service） | **统一语音合成层**：DashScope / Mimo 适配器、对话音频状态管理、参考音频预处理；**配音项目管理**：导出、分段文本、服务层 |
| **唇形同步** | `lipsync_provider/`（factory / hedra / kling / liveportrait / musetalk / wav2lip） | 5 种唇形同步适配器 |
| **音频处理** | `audio_align/`（cross_correlate / envelope / pcm）、`audio_silence/` | **音频对齐**（互相关算法 + 包络检测）、**静音检测与尾部裁剪** |
| **角色与演员** | `role_nodes`、`role_physique`、`role_portrait_supplement`、`portrait_*`、`visual_asset/`、`role_display_name`、`portrait_frame/` | 角色管理、体型管线、肖像版本链、场景/道具资产、显示名、**定妆照相框管理** |
| **片段画布** | `segment_canvas/`（commands / queries / types / utils / canvas_commands×8 / grouping） | 无限画布引擎、画布状态持久化、**节点编组**、快照、迁移、场景锚点、批量导入 |
| **画布输入端口** | `canvas_input_ports/`（fixtures / tests）、`canvas_input_ports_app/` | **统一画布端口系统**：含测试夹具与单元测试，支撑片段、Clips 等多画布场景 |
| **画布卡片** | `canvas_card_config/`（storyboard_shot）、`canvas_image_nodes/` | 画布卡片配置、图像节点管理 |
| **画布瓦片预览** | `canvas_tile_preview/`（commands / ensure / cleanup / meta / paths） | 画布瓦片预览派生缓存（读侧 SSOT），webp 缩略图生成、LOD 加载策略与清理 |
| **视频瓦片海报** | `video_tile_poster/`（commands / ensure / cleanup） | 视频瓦片海报帧提取与缓存管理 |
| **Clips 片段** | `clips/`（commands×11 / types / clip_video_meta）、`clip_framework/` | 视频片段 CRUD、导入、导出、画布、视频绑定；**片段框架索引** |
| **图引擎** | `graph_core/`（engine / runtime / store / types / perf） | 通用有向图引擎，支撑分镜、片段画布与 Clips 画布 |
| **工作流图** | `workflow_graph_store/` | **工作流图持久化存储**，支撑复杂编辑工作流的节点编排 |
| **媒体运行时** | `media_runtime/`（ffmpeg_cli / service / registry / selector / capabilities） | FFmpeg 集成、媒体能力注册、格式探测 |
| **本地桥接服务** | `local_bridge/`（http / transport / handlers / job_store / app_state / auto_edit_worker / cover_worker / highlight_worker / image_worker / subtitle_timeline_worker / subtitle_recognize_handler / llm / speech_trim / progress_emit） | **内部 HTTP 桥接服务**（40 个源文件）：12 条 HTTP 路由、传输认证、作业队列存储、6 种后台 Worker、LLM 调用、语音裁剪、进度事件推送 |
| **参考图策略** | `pad_policy/`（envelope_v3 / materialize / materialize_manual / patch / persist / scope / dismissal / shot_visible_characters / profile_workbench / stable_key / host_adapter / migrate_v2） | **参考图策略引擎 v3**：信封持久化、手动物化、补丁、作用域、角色可见性、工作台画像、v2 迁移 |
| **故事备份** | `story_backup/`（collector / commands / export / import / integrity / media_refs / scope / table_registry / types） | **故事工程备份与迁移**：全量导出、预览、导入（含 ID 重映射）、完整性校验、媒体引用追踪 |
| **权限与安全** | `permission/`（mod / backends / decorator / integration / db_migrations / example）、`authz/`（facade / registry / enforce_opts / session_bootstrap / lease / tests）、`credential_crypto`、`quota_guard` | 可插拔权限框架、授权会话引导增强、凭证加密、配额管理 |
| **跨平台架构** | `platform/`（traits / desktop / context / error） | **平台抽象层**（21 个源文件）：能力、配置、凭证、路径、进程、存储、窗口宿主七维 trait 接口 + 桌面端实现 |
| **四层架构** | `domain/`（entities / ports / nodes / error）、`application/`（ports / dto / services）、`infrastructure/`（persistence / sqlite）、`composition/`（app_container） | **领域驱动设计四层架构**：9 个领域实体 + 12 个 Repository 端口；35+ 个 Application 端口 + 8 个 Service；170+ 个 SQLite 适配器；组合根依赖注入容器 |
| **数据库** | `db/`（schema / pool / backup / migrations×18+ / model_catalog_repo）、`migration/` | SQLite 迁移（50+ 张表）、连接池、备份、模型目录 |
| **电影语言** | `cinematic_language/`（framing / schema_gen / mod） | 画面构成枚举（占幅/裁切/透视）、JSON Schema 生成、Stage A v3 SSOT |
| **云端身份** | `cloud/`（client_identity） | 云端客户端身份标识与会话管理 |
| **应用更新** | `app_update_boot.rs`、`app_update_download/` | 应用冷启动更新检查与静默后台下载 |
| **激活管理** | `activation_client/` | **客户端激活管理**：许可证激活与验证 |
| **文档文本导入** | `document_text/`（mod / docx / rtf / plain / registry / types / limits） | 外部文档文本提取（DOCX/RTF/TXT），支持拖拽导入剧本 |
| **通用下载** | `generic_downloader/`（fetch / paths / resume / session / types）、`resumable_download/`（fetch / paths / resume / throttle / types） | **通用文件下载器** + **断点续传下载器**（流量控制），支撑运行时、模型等大文件分发 |
| **远程资源** | `remote_resource/`（manual_install / mirror_chain） | **远程资源镜像链**：多源回退下载 + 手动安装指引 |
| **软等待** | `soft_wait/`（etag / pull / types） | **ETag 条件轮询**：高效的异步任务结果等待机制 |
| **渲染适配** | `render_target_adapter/`（image_adapter / video_adapter / types） | **渲染目标适配器**：统一图像/视频两种渲染出口 |
| **运维** | `log_init`、`disk_cleanup`、`bug_report`、`app_update_*` | 日志、磁盘清理、BUG 报告打包上传、自动更新 |
---
## 7. 前端核心模块地图
前端共 3,515 个 TSX/TS 源文件，按职责划分为以下核心模块群：
| 模块群 | 关键目录 | 职责 |
|--------|----------|------|
| **故事 Tab** | `components/story-tab/`（StoryTab / hooks / modals / ui） | 故事总览、剧集列表、故事圣经编辑器、剧集插入、剧本文案保存弹框、导出脚本 |
| **剧集 Tab** | `components/chapter-tab/`（panels / sections / modals / hooks） | 剧集看板、场次规划、关键帧、批量生成 |
| **场次 Tab** | `components/scene-tab/` | 场次列表、上下文菜单、加载态 |
| **分镜工作台** | `components/storyboard/`（panels / modals / hooks / history / graph / orchestration） | 分镜故事板、镜头工作台、AI 提示词版本历史、视觉参数同步、批量生成编排 |
| **分镜镜头内容** | `components/storyboard-shot-content/` | 分镜镜头编辑：画幅比、镜头角度、景别、用户自定义字段、**视觉参数区块** |
| **分镜画布** | `components/storyboard-shot-canvas/`（renderers / overlays / handlers / minimap） | 分镜节点画布、边渲染、缩放控件 |
| **片段画布** | `components/segment-canvas/`（graph / domain / transitions） | 无限画布、图推导、撤销重做、**节点编组**、瓦片同步、**场景锚点** |
| **角色 Tab** | `features/character-tab/`（canvas / editor / actor-list / columns / layout / ai / pads） | 角色管理、演员列表、**演员编辑器**、定妆照画布、AI 生成 |
| **角色 Tab** | `features/role-tab/`（canvas / detail / hooks / modals / lightbox / portrait-pads / domain / ai） | 角色详情、肖像灯箱、批量肖像生成 |
| **视觉资产库** | `components/visual-asset-library-tab/` | 视觉资产统一管理、编辑、列表展示 |
| **Clips 片段** | `clips/`（ClipsCanvas / ClipsNodeEditor / ClipsMinimap / ClipsVideoPreview / ClipsImportModal / ClipsExportAllModal） | 片段画布、节点编辑、**导入导出（含 FCPXML）**、视频预览 |
| **对白编辑器** | `components/dialogue-editor/`（DialogueTrackEditorPanel / DialogueTrackCard / DialogueTrackList / DialogueTtsRichPanel / DialogueAudioVersionList / DialogueRoleSelector / DialogueTextEditorField / DialogueTrackVideoPreview / AudioPlayer） | **对白轨道编辑器**（15 个组件）：多轨对白编辑、TTS 音频生成、角色选择、音频版本管理、视频预览联动 |
| **语音合成工作台** | `components/speech-synthesis-workbench/`（SpeechSynthesisWorkbenchShell / ReferenceAudioPanel / SpeechSynthesisParamsBody） | **语音合成工作台**：参考音频管理、合成参数配置、多模型切换 |
| **TTS 工作室** | `components/tts-studio/`（TtsStudioWorkbench / TtsStudioWorkbenchModal / TtsStudioTextPanel / TtsStudioResultPlayer / EmotionControlPanel / TtsSidecarProgressOverlay） | **TTS 工作室**（6 个组件）：文本面板、情感控制、结果播放器、侧车进度叠加层 |
| **配音工作室** | `components/voice/`（VoiceTab / VoiceWorkbench / VoiceSynthesisPanel / VoiceProjectList / VoiceTaskList / VoiceExportAllModal / VoiceRenderRow / VoiceResultPlayer / VoiceTextPanel / WaveformBars / WaveformPlayer / WaveformThumbnail / InputLevelMeter / ReferenceAudioPanel / ReferenceAudioWaveform / ReferencePrepareProgressOverlay） | **配音项目管理**（17 个组件）：项目列表、合成面板、任务列表、波形可视化、导出、参考音频管理 |
| **视觉编辑** | `components/visual-edit/`（plugins/CropRectPlugin / MaskBrushPlugin） | **图像精修编辑**：裁剪矩形插件、蒙版笔刷插件 |
| **精修编辑工具** | `components/refine-edit-tools/`（CropOverlay / MaskBrush / QuickSelect / UndoRedo / ShortcutBindings） | 裁剪、蒙版、快速选择等视觉编辑工具集 |
| **运行时管理** | `components/runtime-auto-download/`（RuntimeAutoDownloadOverlayHost） | **运行时自动下载面板**：进度展示、状态管理 |
| **跨平台模块** | `platform/`（capabilities / hostIntegration / invariant / shell / usePlatformShell） | **平台能力抽象**：能力查询、宿主集成、平台 Shell、不变式校验 |
| **设置 Tab** | `components/settings-tab/` / `components/settings/` | 账号、能力映射、ComfyUI、本地模型、TTS/视频实验室、**运行时下载管理**、数据迁移 |
| **帮助模块** | `help-module/` | 学习中心、引导 |
| **认证** | `auth/`（AuthProvider / store / sessionLifecycle） | 登录、注册、密码重置、Token 管理、会话生命周期 |
| **面板弹出多屏** | `components/popout-panel/`、`app-shell/PopoutEntityHostExecuteRegistrar.tsx`、`app-shell/SidebarFloatingLayer.tsx` | 画布面板弹出为独立窗口，多屏协作工作流 |
| **模型能力卡片** | `components/model-capabilities/`（CapabilityCardShell / T2iCapability / I2iCapability / TextCapability / SpeechCapability） | 统一的模型能力展示卡片组件 |
| **多视角提示词** | `components/multi-view/`、`domain/multi-view/prompt-pipeline/` | 多视角定妆照提示词五阶段管线前端对齐 |
| **画布宿主** | `components/canvas-host/ConnectedCanvasShell.tsx` | 统一画布宿主壳层，接入持久化与同步 |
| **画布瓦片预览** | `domain/canvas-tile-preview/`（lodPolicy / previewCache / useCanvasTileDisplayUrl） | 画布瓦片 LOD 分级加载策略、预览缓存、显示 URL hook |
| **UI 组件库** | `components/ui-*`（modal / toast / panel / form / icon / list / lightbox / edge-resize-shell / chrome-textarea / chrome-select / misc） | 通用 UI 原子组件 |
| **无限画布内核** | `infinite-canvas/`（InfiniteCanvas / components / hooks / utils / layout / canvas-chrome / CanvasNodeTileDockPanel） | 自研画布引擎：四叉树空间索引、masonry 布局、虚拟化渲染、缩放平移、瓦片边框、持久化、节点停靠面板 |
| **领域逻辑** | `domain/`（model-surfaces / local-media-upload / audio / imageGenWarnings / multi-view / reference-pad / canvas-tile-preview / storyboard-shot / document-text-import / segmentContent / **actor-editor** / **chapter-editor** / **content-autosave** / **dialogue-tts** / **local-tts** / **narrative-genre** / **refine-edit-tools** / **segment-video-narrative** / **speech-synthesis-workbench** / **story-production-genre** / **tts-bootstrap** / **tts-reference** / **tts-sidecar** / **tts-studio** / **visual-edit** / **voice**） | 模型选择编解码、上传队列、音频、生成警告、多视角生成、参考面板、画布瓦片预览 LOD、分镜视觉参数会话、文档文本导入、片段内容 SSOT、**演员编辑器**、**剧集编辑器**、**内容自动保存**、**对白 TTS**、**本地 TTS**、**叙事类型**、**精修编辑工具**、**片段视频叙事**、**语音合成工作台**、**故事制作类型**、**TTS 引导**、**TTS 参考**、**TTS 侧车**、**TTS 工作室**、**视觉编辑**、**配音** |
| **API 层** | `api/`（graphApi / migration / segmentCanvasV2Api / clipFramework） | Tauri IPC 调用封装 |
| **快捷键** | `shortcuts/` | **全局快捷键系统**：统一快捷键绑定与管理 |
| **系统** | `system/`（form-control-clipboard / selectable-copy） | 右键复制粘贴、可选复制 |
---
## 8. 数据架构概览
本地 SQLite 数据库采用 **幂等迁移** 策略，当前包含 **50+ 张表**，按领域分组：
| 领域 | 核心表 | 说明 |
|------|--------|------|
| **故事结构** | `stories`、`nodes`、`edges`、`node_chapter_order` | 故事→剧集→场次→片段的层级图 |
| **画布状态** | `segment_canvas_node`、`segment_canvas_edge`、`segment_canvas_layout_state`、`segment_canvas_view_state`、`segment_canvas_snapshot`、`segment_canvas_file_ref`、`segment_canvas_delete_audit`、`segment_canvas_placement_order`、**`segment_canvas_grouping`** | 片段画布全量持久化 + **节点编组** |
| **画布端口** | **`canvas_input_ports_segment`**、**`canvas_input_ports_clips`**、**`canvas_input_ports_offline`** | **统一画布输入端口持久化**（片段/Clips/离线） |
| **画布图像** | **`canvas_image_nodes`** | **画布图像节点元数据** |
| **AI 任务** | `ai_tasks`、`ai_queue_tasks`、`ai_queue_task_events` | 任务记录 + 队列持久化 + 事件流 |
| **分镜** | `storyboard_graph_state`、`storyboard_shot_specs`、`storyboard_scene_revision`、**`storyboard_character_scope`**、**`storyboard_character_lock`**、**`storyboard_continuity`**、**`storyboard_manual_segment`**、**`storyboard_merge_conditioning`**、**`storyboard_merge_consistency`**、**`storyboard_merge_pad`** | 分镜图状态、镜头规格、场次修订、**角色范围与锁定**、**镜头连续性**、**手动分段**、**合并条件与一致性** |
| **角色与资产** | `assets`、`scene_assets`、`prop_assets`、`role_portrait_versions`、`portrait_last_generations`、**`portrait_builds`**、**`portrait_frames`**、**`portrait_extracted_hints`** | 全局资产、场景/道具资产、肖像版本链、**定妆照构建记录**、**相框配置**、**外观提取提示** |
| **参考图策略** | **`pad_policy_envelope`**、**`pad_policy_scope`**、**`pad_policy_workbench`**、**`pad_policy_video_workbench`**、**`pad_policy_shot_visible`**、**`pad_policy_upstream_*`** | **参考图策略引擎 v3 持久化**：信封、作用域、工作台画像、角色可见性、上游自动绑定 |
| **内容历史** | `node_content_history`、`story_content_history`、`scene_asset_content_history`、`prop_asset_content_history`、`video_workbench_session_history` | 版本回溯、撤销依据 |
| **Clips** | `clips`、`clip_edges`、`clip_framework_index`、`clips_canvas_viewport`、`clips_canvas_tile_pos`、`clips_canvas_placement_order` | 视频片段图、画布视口、排列、**框架索引** |
| **Clips 导出** | **`clips_export_history`** | **片段导出历史记录** |
| **媒体轨道** | `audio_tracks`、`dialogue_tracks`、`lipsync_providers` | 音频轨、对话轨、唇形同步供应商 |
| **对白音频** | **`dialogue_audio_versions`**、**`dialogue_audio_state`** | **对白音频版本链**、**音频状态管理** |
| **语音合成** | **`tts_reference_audio`**、**`tts_studio_projects`**、**`voice_studio_projects`**、**`voice_studio_tasks`**、**`speech_synthesis_jobs`** | **TTS 参考音频**、**TTS 工作室项目**、**配音项目与任务**、**语音合成作业** |
| **模型配置** | `model_official_catalog`、`model_capability_catalog`、`app_user_settings` | 官方模型目录、能力目录、用户设置 |
| **运行时** | **`runtime_registry`**、**`runtime_download_sessions`** | **运行时版本注册表**、**下载会话管理** |
| **故事备份** | **`story_backup_exports`**、**`story_backup_imports`**、**`migration_exports`**、**`migration_imports`** | **故事工程导出/导入记录**、**迁移导出/导入** |
| **删除编排** | **`delete_orchestration_inventory`** | **级联删除编排清单**：删除前的影响范围预估 |
| **权限** | `user_permissions`、`permission_audit_log`、`user_permissions_cache` | 用户权限、审计日志、缓存 |
| **布局** | `actor_list_layout`、`story_node_list_layout`、`chapter_scene_list_layout`、`scene_asset_list_layout`、`prop_asset_list_layout`、**`chapter_bundle_layout`**、**`segment_play_order`**、**`segment_scene_order`** | 各列表拖拽排序持久化；**剧集包布局**、**片段播放顺序**、**片段场次顺序** |
| **图引擎** | `graph_core_graph`、**`workflow_graph_state`** | 通用有向图持久化、**工作流图状态** |
| **其他** | `user_tier_cloud`、`task_running_wait_tips`、`dialogue_tracks`、`video_workbench_session_history`、**`activation_state`**、**`local_media_uploads`**、**`orphan_references`** | 云端用户层级、运行提示、**激活状态**、**本地上传**、**孤儿引用追踪** |
---
## 9. 近期重大更新（v0.2.618 → v0.2.721，2026.6.17—7.18）
自 v0.2.618 以来，31 天内完成 **169 次提交**，涉及 **2954 个文件变更**（新增约 21.2 万行，删除约 7.1 万行）。自研代码总量从约 57.6 万行增长至约 **74.4 万行**（+16.8 万行），文件数从约 4,153 增至约 **5,057**（+904 文件）。版本号跨越 0.2.618 → 0.2.721，标志产品从「AI 分镜工作台」向「全链路数字导演工作站」的实质性飞跃。以下按主题归纳重大更新：
### 9.1 AI 自动剪辑引擎与 NLE 导出（7/2—7/10）
**这是本阶段最具里程碑意义的能力升级**——产品从「生成素材」跨越到「自动剪辑 + 专业软件交付」。
- **AI 自动剪辑引擎**（`auto_edit/`，7 个源文件）：AI 驱动的镜头边界检测（BTD）、CFR 代理生成、字幕对齐、素材清理。自动分析分镜视频素材，识别镜头切换点并生成时间线。
- **FCPXML 时间线生成**（`autocut_fcpxml/`，3 个源文件）：将 AI 分析结果生成 Final Cut Pro 可识别的 FCPXML 时间线文件，用户可直接在 Final Cut Pro 中打开、继续精剪。
- **Clips 导出体系**（`clips_export/`，13 个源文件）：片段工程导出为 FCPXML 时间线，含媒体文件归档、复制计划、进度推送、历史扫描。
- **内部 HTTP 桥接服务**（`local_bridge/`，40 个源文件）：作为前端与自动剪辑、字幕识别、高光检测、封面生成等长耗时本地任务的中间层，支持作业队列、进度推送、会话管理。
### 9.2 语音与配音工作台（6/25—7/17）
**配音能力从实验性功能升级为完整工作台**，覆盖从文本到合成、编辑、导出全流程。
- **统一语音合成层**（`speech/`，12 个源文件）：DashScope、Mimo 等多供应商适配器，对话音频状态管理，参考音频预处理，TTS 模式能力检测。
- **配音项目管理**（`voice_studio/`，6 个源文件）：配音项目的创建、管理、导出，分段文本与 TTS 任务编排。
- **对白编辑器**（15 个前端组件）：多轨对白编辑面板，支持逐句 TTS 生成、角色选择、音频版本管理、视频预览联动。
- **TTS 工作室**（6 个前端组件）：文本输入、情感控制、结果播放器、进度叠加层。
- **配音工作台前端**（17 个组件）：项目列表、合成面板、任务列表、波形可视化与播放器、导出、参考音频管理、输入电平表。
- **音频对齐**（`audio_align/`，4 个源文件）：基于互相关算法的音频对齐，支持包络检测与 PCM 处理。
- **静音检测**（`audio_silence/`）：静音段检测与尾部裁剪，提升对白音频质量。
### 9.3 视觉编辑与精修工具（7/9—7/15）
**图像生成后处理能力从概念落地为可用的编辑管线**。
- **视觉编辑管线**（`visual_edit/`，19 个源文件）：裁剪、蒙版笔刷、旋转、笔刷合并等操作的完整后端管线，含提交校验、持久化存储、生图桥接。
- **本地精修编辑**（`refine_local_edit/`，8 个源文件）：本地图像编辑操作（裁剪、旋转、笔刷合并、笔画栅格化）。
- **精修区域选择**（`refine_regions/`，4 个源文件）：区域引导、预览生成、选区管理。
- **前端编辑插件**：裁剪矩形插件、蒙版笔刷插件；配合已有的快速选择、撤销重做、快捷键绑定等工具。
- **图像布局 AI 分析**（`image_layout_analysis/`，18 个源文件）：AI 视觉模型驱动的画面构成分析，含构图词汇表、轴连续性校验、缓存层、提示词片段生成。为后续智能构图建议与自动优化奠定基础。
### 9.4 跨平台架构抽象（6/18—7/14）
**为 iOS/iPad 支持铺设的架构地基**全面落地。
- **平台抽象层**（`platform/`，21 个源文件）：能力、配置、凭证、路径、进程、存储、窗口宿主七维 trait 接口 + 桌面端完整实现。
- **前端平台模块**（`platform/`，6 个源文件）：能力查询、宿主集成、Shell 抽象、不变式校验。
- **架构意义**：后端核心逻辑与操作系统解耦，iOS 端只需实现对应的 trait 接口，无需修改任何业务代码。
### 9.5 四层分层架构落地（6/7—7/18）
**从 MVC 模式向领域驱动设计（DDD）四层架构的全面迁移**。
- **领域层**（`domain/`，15 个源文件）：9 个领域实体 + 12 个 Repository 端口接口，定义纯业务逻辑。
- **应用层**（`application/`，48 个源文件）：35+ 个 Repository trait + 8 个 Application Service，封装业务用例。
- **基础设施层**（`infrastructure/`，170+ 个源文件）：SQLite 适配器全面覆盖各领域，通过依赖反转实现领域层与数据库的解耦。
- **组合层**（`composition/`，2 个源文件）：依赖注入容器，统一管理各层组件的创建与装配。
- **架构意义**：为未来扩展（内存存储、远程存储、iOS Core Data 适配）提供了清晰的插拔边界。170+ 个 SQLite 适配器按单一职责原则拆分，每个适配器只负责一个领域聚合的持久化。
### 9.6 提示词专家系统（7/9—7/14）
**从硬编码提示词模板向动态组装专家系统的跃迁**。
- **提示词专家引擎**（`prompt_expert/`，7 个源文件）：叙事类型轴 + 风格轴 + 插槽的动态组装，替代固定模板。
- **叙事类型定义**（`narrative_genre/`）：正式的故事叙事类型元数据。
- **创意格式定义**（`creative_format/`）：创意产出的格式约定。
- **AI 输出语言门控**（`ai_output_language/`）：基于用户设置的输出语言自动切换。
- **架构意义**：添加新的叙事类型或风格不再需要修改模板文件，只需注册新的轴条目和插槽映射。
### 9.7 运行时统一管理（6/28—7/10）
**外挂运行时从「用户自己装」升级为「自动下载 + 版本管理」**。
- **运行时管理**（`runtimes/`，21 个源文件）：版本化 CDN 清单解析、自动下载安装、断点续传、版本迁移、激活管理、FFmpeg 确保、Python 定位。
- **运行时注册表**（`runtime_registry` 表）：持久化记录各运行时的版本与安装状态。
- **通用下载器**（`generic_downloader/` + `resumable_download/`，12 个源文件）：支持多源回退、流量控制、断点续传的通用文件下载基础设施。
- **前端运行时管理**（`runtime-auto-download/`）：自动下载进度面板，用户可见的运行时状态管理。
- **架构意义**：用户安装产品后，llama.cpp、Whisper、TTS 引擎、FFmpeg 等运行时自动按需下载，无需手动配置复杂环境。
### 9.8 故事工程备份与迁移（7/1—7/11）
**从「数据库文件就是工程」升级为「结构化导出/导入」**。
- **故事备份**（`story_backup/`，13 个源文件）：全量导出（含媒体文件引用追踪）、完整性校验、预览、导入（含 ID 重映射）、表注册表。
- **迁移增强**（`migration/`）：导出/导入记录持久化、跨版本兼容。
- **架构意义**：用户可以像 Office 文档一样「另存为」和「打开」工程文件，为协作与分发奠定基础。
### 9.9 分镜引擎增强（7/11—7/17）
- **分镜剧本动作语法**（`storyboard_playbook/`，2 个源文件）：定义场景类型的结构化动作描述语言。
- **镜头连续性批量编排**（`storyboard_continuity/`，3 个源文件）：批量链式处理分镜镜头的上下文连续性。
- **镜头提示词智能优化**（`storyboard_shot_prompt_optimize/`，5 个源文件）：基于邻居镜头上下文自动优化当前镜头的提示词。
- **Stage A 输入管理**（`storyboard_stage_a_inputs/`）：分镜 Stage A LLM 输入的标准化管理。
- **Stage B 摄取管理**（`storyboard_stage_b_ingest/`）：分镜 Stage B 输出结果的标准化摄取。
### 9.10 画布系统升级（7/3—7/18）
- **画布节点编组**（7/17）：支持将多个画布节点打组，统一拖拽、缩放、管理，大幅提升复杂画布的整理效率。
- **统一画布输入端口**（`canvas_input_ports/` + `canvas_input_ports_app/`）：含测试夹具与单元测试的端口系统，统一片段、Clips 等多画布场景的连线端口逻辑。
- **画布卡片配置**（`canvas_card_config/`）：可配置的画布卡片系统，支持分镜卡片等不同卡片类型的定制化展示。
- **画布图像节点**（`canvas_image_nodes/`）：独立的图像节点元数据管理。
- **画布删除流程优化**：完整的级联删除编排系统（`delete_orchestration/`），删除前预计算影响范围。
### 9.11 其他重要改进
- **高光检测管线**（`highlight_pipeline/`，3 个源文件）：LLM 驱动的视频精彩片段自动识别。
- **片段视频叙事引擎**（`segment_video_narrative/`，10 个源文件）：视频叙事的组装→注入→解析→优化→持久化全链路。
- **视频后期管线**（`video_post_process/` + `video_delivery/`，8 个源文件）：后期预检、火山引擎 MediaKit 集成、交付规划。
- **定妆照构建管线 v2**（`portrait_build/`，9 个源文件）：目录化配置、组合引擎、摘要、校验、前后端 IPC 对齐。
- **定妆照相框管理**（`portrait_frame/`）：独立的相框配置与管理。
- **参考图策略引擎 v3**（`pad_policy/`，15 个源文件）：信封持久化 v3、手动物化、补丁机制、作用域、角色可见性、工作台画像、v2 迁移。
- **客户端激活管理**（`activation_client/`）：许可证激活与验证。
- **全局快捷键系统**（`shortcuts/`）：统一的快捷键绑定与管理。
- **内容自动保存**（`domain/content-autosave/`）：编辑器内容的自动保存机制。
- **启动白屏修复**：消除发布版冷启动时的白色闪烁与命令行窗口闪现。
---
## 10. 未来与演进方向
### 10.1 跨平台架构升级（iOS/iPad 支持）
已启动跨平台基础架构升级，目标是让产品能在 iPad 上运行。核心改造包括：
- **PlatformPaths trait**：抽象文件系统访问，替换直接的系统文件调用
- **ProcessExecutor trait**：抽象外部进程调用，iOS 上全部走云端降级
- **AiPlatformCapabilities trait**：iOS 禁用本地 AI（llama/TTS/whisper），自动降级到云端
- **配置源抽象**：iOS 无环境变量，改用 bundled config + NSUserDefaults
平台抽象层（`platform/`，21 个源文件 + 前端 6 个源文件）已完成桌面端全部 trait 实现，iOS 端只需实现对应接口。前端已落地 `platform/` 模块的能力查询与 Shell 抽象。
### 10.2 语音与配音能力深化
- **本地 TTS 引擎扩展**：持续接入更多本地 TTS 引擎（VoxCPM、IndexTTS 等），降低云端配音成本
- **情感语音合成**：情感控制面板的细粒度化，让 AI 配音更具表现力
- **多角色对话配音**：一键为整个对白轨道批量生成多角色配音
- **唇形同步增强**：5 种适配器持续迭代，提升口型匹配精度
### 10.3 自动剪辑能力增强
- **智能转场检测**：从简单的镜头边界检测扩展到转场类型识别（硬切、叠化、淡入淡出）
- **BGM 自动匹配**：基于场景情绪自动推荐背景音乐
- **字幕自动生成与对齐**：字幕识别 + 对白轨道 + 时间线自动对齐
- **Premiere Pro / DaVinci Resolve 导出**：在 FCPXML 基础上扩展更多 NLE 格式支持
### 10.4 视觉编辑能力增强
- **AI 辅助构图建议**：基于 `image_layout_analysis` 模块的 AI 画面分析能力，提供智能构图优化建议
- **批量精修**：对一批生成图像应用相同的精修操作（统一裁剪、风格滤镜等）
- **参考图智能匹配**：基于场景上下文自动推荐合适的参考图
### 10.5 产品演进
- **分镜与生成一体化**：强化分镜与生成的一体化体验，批量任务、模板与复用
- **故事圣经同步**：故事圣经变更自动同步至受影响剧集（已落地 `story_sync_pipeline`）
- **故事工程可移植**：通过备份/导出/导入体系，实现跨设备、跨用户的故事工程迁移
- **更多云端能力接入**：按场景接入更多云端能力与本地模型组合
- **全局助手**：Chat 后端与 AgentLoop 架构，提供 AI 辅助创作体验
### 10.6 工程演进
- **四层架构深化**：持续领域层纯化——将残留的业务逻辑从基础设施层回迁至领域层
- **iOS 适配器实现**：在现有 170+ SQLite 适配器基础上，按需实现 Core Data 适配器
- **全仓颜色主题模块**：统一的深色/浅色主题切换系统
- **松耦合对接**：与云端素材、协同类产品探索松耦合对接（本地工程仍是权威数据源）
### 10.7 生态演进
- **可信、可选、可审计**：持续面向中文创作者工作流，向可信、可选、可审计的多模态前期工具链演进
- **模板市场**：灯光/风格预设、分镜模板、角色外观包的社区分享
- **云端渲染农场**：大模型推理卸载到云端，桌面端保持低功耗
---
*代码仓库内另行维护更细的技术约束与模块说明（约 1,534 篇内部文档），供开发与测试使用；本文不展开。*
