storyforge/docs/AUDIT_2026-03-18.md

StoryForge 现状审计

日期：2026-03-18

结论

当前应以 /Users/kris/code/StoryForge-gitea 作为主工作区继续推进，而不是 /Users/kris/code/Fastgpt。后者更像一次不完整的导入快照，前者才是可持续开发的真实仓库。

现有功能归位

1. collector-service 之前承担的功能

• 账号注册、登录、审批
• 本地模型配置
• 知识库、智能体、任务管理
• 视频链接/上传视频/文本三类入口
• 下载器、ffmpeg、whisper.cpp 风格的本地处理调用
• Android OTA 查询/发布

2. FastGPT 实际承担的功能

• 仅承担“数据集/文档同步”的外部依赖角色
• 代码痕迹集中在：
  • collector-service/app/fastgpt.py
  • docker-compose.yml
  • 若干 fastgpt_* 字段

结论：FastGPT 并不是业务内核，适合迁移后整体删除。

3. n8n 适合接管的功能

• 任务触发
• 工作流分流
• 外部能力编排入口
• 任务执行顺序控制

不适合承载：

• 用户、项目、Agent、知识库、任务、历史记录的主数据
• 业务状态唯一真相源

结论：应采用“业务状态在 collector-service，流程编排在 n8n”的分层。

多用户与数据边界

当前已明确采用：

• accounts
• projects
• knowledge_bases
• assistants
• content_sources
• jobs
• job_events

推荐模型：user + project。

理由：

• 只做 user 级隔离，会导致一个用户内部不同内容工作流难以再分边界
• project 可以自然承接“一个创作者方向 / 一个客户 / 一个账号矩阵 / 一个内容实验”
• assistant、knowledge_base、job、content_source 都能挂到 project，便于后续扩展协作空间

外部链路审计

1. 下载器

• 已存在，不需要重写
• 现阶段通过 yt-dlp 命令集成

2. ASR

• 现有实现已部署，但入口未完全标准化
• 当前后端支持 ffmpeg + whisper.cpp 风格接入
• 若需要接现有常驻 ASR 服务，后续只需把 transcribe_media() 改成 HTTP/RPC 适配即可

3. Windows cutvideo

• 仓库：/Users/kris/code/cutvideo
• 具备清晰 API：
  • POST /api/jobs
  • GET /api/tasks/{task_id}
  • GET /api/runs/{run_id}
• 适合集成为“由 StoryForge 后端授权调用的局域网剪辑能力”

当前限制：

• 现有 cutvideo API 主要接受 input_dir
• 对“用户上传实拍素材后直接推送到 Windows 机器”这一步，还缺一层文件转运方案

4. huobao-drama

• 旧改版位置：/Users/kris/code/huobaoduanju/huobao-drama-master
• 最新 upstream：/Users/kris/code/huobao-drama-upstream
• 旧改版主要多了一套 ad_workflow 方向，和当前 StoryForge MVP 不完全对齐
• 最新版已具备：
  • POST /api/v1/dramas
  • POST /api/v1/images
  • GET /api/v1/images/{id}
  • POST /api/v1/videos
  • GET /api/v1/videos/{id}
  • reference_mode=first_last

本次真实联调里，旧改版为了兼容 qnaigc 需要补 4 个点：

• pkg/image/openai_image_client.go
• application/services/image_generation_service.go
• pkg/video/openai_sora_client.go
• application/services/video_generation_service.go

核对结果：

• 以上 4 个文件与本机 upstream 同名文件在补丁前没有明显结构分叉
• 当前差异基本就是 qnaigc 图片异步查询、Kling 视频 JSON 协议、结果 URL 解析、远程首尾帧 URL 保留这几处兼容逻辑

结论：这批补丁是可移植补丁，MVP 已在旧改版实例上验证通过；下一步应把同样补丁迁到最新版 huobao-drama-upstream，而不是继续在旧目录长期演进。

当前已完成迁移面

• FastGPT 运行时依赖已从 collector-service 主代码中剥离
• 数据库已支持 project/content_source/job_events
• collector-service 已增加：
  • n8n 触发
  • cutvideo 集成 client
  • huobao-drama 集成 client
  • 内部编排接口
• docker-compose.yml 已改为 collector + n8n + cli-proxy-api
• n8n 工作流导出文件已纳入仓库

当前主要风险

1. cutvideo 的素材传输还未完整闭环
2. 本地 ASR 的“最终生产入口”仍需按你现有部署方式再绑一次
3. huobao-drama 已在本机旧改版实例上跑通，但兼容补丁尚未迁到 upstream 仓库并形成正式提交