车库

Studio 已知问题与技术债

本页是 2026-09 一次代码调研的快照，供后续排期参考；具体是否仍然成立，动手前请用对应文件路径复核一次。每条只陈述现象与影响，不代为判断要不要修、优先级多高——那是排期时该做的事。

后端（platform/studio/api）

位置现象影响
src/apps/comic_gen/、FastAPI title命名债：comic_gen/AI Video Creation API 遗留命名已修复（2026-09）：包目录改名 src/apps/studio/，类名 ComicGenPipeline→StudioPipeline，FastAPI/模型目录 title 改为 "Studio API"/"Studio Model Catalog"，前端 workspaceAria 文案同步；docs/upstream-AGENTS.md 里的 LumenX 与 ~/.tron/comic/projects 路径未动，见下一条
src/apps/studio/api.py（document/document/snapshots/sync_derivation/shot_blocks/* 等结构化脚本编辑器端点）数据硬编码写死在 ~/.tron/comic/projects，完全脱离 STUDIO_DATA_DIR/enter_data_dir() 的 chdir 约定（其余约 140 处路径都遵守这个约定）容器化部署时容器内 $HOME 大概率不是持久化卷挂载点，重建容器可能直接丢失编辑器的文档/快照/派生数据；且这份数据与 output/projects.json 里的 Script.original_text 是两份互不同步的副本。这个路径里也残留着 "tron/comic" 命名，但它是数据存储位置而非单纯命名问题，改名前必须先解决"脱离 STUDIO_DATA_DIR"这个根因，否则会让已有本地数据失联
src/models/doubao.py、README「配置（后端）」表ARK_API_KEY（豆包/方舟）在文档和代码里都定义了，但全仓库搜索没有任何地方实际引用/路由到它孤儿配置：要么补上路由让它生效，要么把文档和这个类一起清理
src/apps/studio/api.py（POST /projects/{id}/export）ExportRequest 的 resolution/format/subtitles 三个字段接收但从不生效，实际永远走固定的 1080p/mp4/无字幕逻辑如果前端暴露了这几个选项给用户，是"UI 承诺了后端没实现"的落差
src/apps/studio/pipeline.py: _maybe_apply_bgm_mux最终成片混音只混合对白 + BGM 两路，SFX 轨（frame.sfx_url）生成出来了但从未出现在导出结果里功能做了一半：SFX 生成 API 能用，但用户听不到最终成片里的音效
src/models/factory.py（ModelFactory）vs pipeline.py: process_video_task / playground/service.py"给模型名选 provider 适配器"这件事有三份独立实现，互相不复用，ModelFactory 疑似已过时但未删除三处逻辑分叉维护，新增模型/新增路由规则容易漏改某一处
docs/upstream-AGENTS.md文档描述的"LumenX Atelier"（画布式创作产品）在当前仓库的 src/apps/ 下完全不存在，是直接从上游仓库搬运、未本地化裁剪的文档作为架构参考引用时容易把"上游其它分支的规划"误当成"本仓库现状"
src/utils/__init__.py: enter_data_dir()依赖进程级 os.chdir() + 约 140 处相对路径寻址这是能工作的设计，但对"单进程多 worker"或未来的水平扩展是隐性约束——一个进程只能服务一个 STUDIO_DATA_DIR

前端（platform/studio/web）

位置现象影响
components/modules/ScriptEditor/ vs components/modules/ScriptProcessor.tsx一整套独立的 Tiptap 富文本剧本编辑器（好莱坞格式、场次大纲、离线缓存）与 R2V 流程主用的简单文本框并存，功能明显重叠是否要合并、ScriptEditor 是不是"计划替换但还没接入主流程"的半成品，从代码里看不出明确结论
components/modules/Timeline.tsx文件存在，但在 ProjectClient.tsx 的主流程 import 列表里未见引用疑似孤立的时间轴编辑器原型，需要人工确认是死代码还是未接入的隐藏功能
components/modules/Cast.tsx代码内 TODO 注释明确写"新增资产弹窗是占位，完整生成流程留待后续 patch""新增资产"目前是不完整的 UI 占位
components/modules/AssetInspector.tsx代码注释写明当前 ImageVariant 只有 id/url/created_at/prompt_used，缺 seed/model/size；前端 UI 已按"有值才渲染"写好，等后端补字段后端字段不补，这部分信息在前端永远不显示
src/lib/api.ts（如 polishVideoPrompt/refineFramePrompt 附近的大段注释）部分缓解（2026-09）：后端 api/scripts/export_openapi.py 现在把 FastAPI 自动推导的 schema 冻结成 api/openapi.json，web 侧 pnpm generate:api-types 据此生成 src/generated/api-types.ts；但 api.ts 里现有的 100+ 手写方法尚未改用这些生成类型标注参数/返回值，仍是旧的"契约写在注释里"状态基础设施已就位、风险敞口未消：只要没有把某个调用点迁移到用生成类型标注，那个点的契约漂移风险跟之前一样；迁移是后续可以逐个调用点渐进做的工作，不需要一次性重写 api.ts
src/lib/auth.ts: redirectToLogin()401 时直接跳转 admin 首页，不带任何"返回地址"参数已修复（2026-09）：Studio 现在有自己的登录页 + 静默刷新（AuthGate/authStore），401 先尝试用 refresh token 续期，续期也失败才原地换成登录页（不再跳转 admin 首页）；URL hash 不变，重新登录后自动回到原来的项目/镜头。剩余的小代价：AuthGate 卸载整棵组件树再重新挂载，组件内存态（未保存的输入、打开的弹窗）不会保留，见 studio-web-flow.md 鉴权一节
components/modules/StoryboardR2V.tsx、VideoGenerator.tsx轮询任务状态用固定 3-5 秒间隔的 setInterval，无退避、无最大轮询时长任务长期卡住（比如厂商接口异常）时会无限期持续请求，没有自动止损机制
src/components/series/__tests__/SeriesDetailPage.spec.tsx、ImportFileDialog.spec.tsxpnpm test:ui 的 46 个失败全部来自这两个文件，原因是渲染时没有用 NextIntlClientProvider 包裹纯测试基建缺口，加一个共享的 renderWithIntl 测试工具理论上能一次性修完，不代表业务逻辑有问题
next.config.mjs：typescript: { ignoreBuildErrors: true }生产静态构建不因类型错误失败类型安全完全依赖开发者主动跑 pnpm typecheck，如果 CI 没有单独强制这一步，带类型错误的产物可能上线

相关页面