storyforge/docs/AUDIT_2026-03-18.md

StoryForge 现状审计

日期：2026-03-18 更新：2026-03-20

结论

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

现有功能归位

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

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

2. 旧数据集运行链实际承担的功能

• 仅承担“数据集/文档同步”的外部依赖角色
• 代码痕迹集中在：
  • collector-service/app/fastgpt.py
  • docker-compose.yml
  • 若干 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 命令集成
• 账号级内容源同步同样复用 yt-dlp --flat-playlist，不额外维护抓取器

2. ASR

• 现有实现已部署，入口现已标准化为“两级优先级”：
  • 优先调用 HTTP ASR 服务
  • HTTP 不可用或返回空结果时，回退到 whisper.cpp 命令行
• 本次已按 mac-whisper-service 的 /transcribe 协议完成接入，并用任务 job_e95f9b5579fd4c5aa40f04de611e9fd0 验证 artifacts.asr_backend=http
• 进一步联调发现真实长视频转写耗时约 44 秒，因此 collector 侧 ASR_HTTP_TIMEOUT_SEC 默认值已提升到 120 秒；本机 mac-whisper-service 运行时也需要把 WHISPER_TIMEOUT_MS 提升到 120000
• 修复后再次验证成功，任务 job_bb405e2e878849e38c4bb31f7781e1e3 已写入真实 HTTP ASR 文本并记录 artifacts.asr_http_payload
• collector 运行镜像已补上 ffmpeg 和 yt-dlp，避免容器内缺依赖导致音频抽取或下载失效

2.1 内容源账号同步

• 已新增 content_source_sync_pipeline
• 用户可通过 POST /v2/pipelines/content-source-sync 提交创作者账号 URL
• 后端会创建父任务，使用 yt-dlp --flat-playlist 抓取最近 N 条视频 URL，再自动派生用户自己的 video_link 子分析任务
• jobs.parent_job_id 已加入数据模型，父子任务关系可持久化查询
• 已用 bilibili 账号 URL 联调验证：
  • 父任务：job_b02109cf9e8244fbb5b86f184a7c7574
  • 子任务：job_7f169db61af441f8a7f186d03db2d91c、job_28c47774028441378a3974860c375ab7

结论：账号级调度不再是空白能力，但目前只验证了 bilibili URL 形态，抖音 / 小红书仍需真链路核实。

3. Windows cutvideo

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

当前状态：

• StoryForge 已支持把 upload_video 或已完成的 video_link 源素材自动上传到 cutvideo
• real-cut 任务可直接传 source_job_id，由后端完成 staging 后再提交到剪辑服务
• Windows 机器已部署带 POST /api/uploads 的 cutvideo 版本，并完成局域网联调

3.1 douyin 工作台

• collector-service 已具备 /v2/douyin/* 工作台接口
• 已补充两类关键联调增强：
  • 分享文案中的 URL 自动提取与归一化
  • public 页面命中抖音反爬挑战时的显式诊断返回
• 真实 smoke 结果表明，纯 public 主页抓取会落到 byted_acrawler 挑战页，而不是正常 profile 数据页
• 同时，manual_profile_payload + manual_work_payloads 已验证可完成账号入库、分析报告生成、相似账号搜索和对标关系写入
• 现已新增浏览器辅助采集工具 /Users/kris/code/StoryForge-gitea/scripts/douyin-browser-capture/capture_and_sync.mjs
• 同目录现已新增本地控制台 /Users/kris/code/StoryForge-gitea/scripts/douyin-browser-capture/control_panel.mjs
• 该工具使用真实 Playwright Chromium 会话打开抖音页面，允许人工登录 / 过滑块后继续自动提取 <script> JSON、网络 JSON、视频详情页和创作者中心页数据
• 浏览器工具最终直接调用现有 /v2/douyin/accounts/sync，不新增第二套持久化模型
• 控制台模式已经支持“开始采集 -> 浏览器登录 -> 网页点继续 -> 自动同步”的点击式流程，并修复了 ready-file 提前点击的竞态

结论：douyin 方向不再是“接口存在但不可用”，当前状态是“public 直抓受反爬限制，但人工采集兜底链已跑通”。

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，而不是继续在旧目录长期演进。

补充验证（2026-03-20）：

• /Users/kris/code/huobao-drama-upstream 当前工作分支为 codex/qnaigc-compat
• 该分支已包含 qnaigc 图片异步查询、Kling 视频协议、结果 URL 解析、远程首尾帧保留等补丁
• 另外补了 ResourceTransferService 的 no-op MinIO 转存方法，当前 go build ./... 已可全量通过
• 使用复制自旧目录的 config.yaml + drama_generator.db + data/storage 在隔离目录启动了 upstream 实例，地址为 http://127.0.0.1:5681
• 上游实例健康检查通过，POST /api/v1/dramas 可正常创建剧本
• 新的图片和视频生成请求已能走到 provider 调用层，但当前复制出的 AI 配置凭证返回 403 access denied for invalid user
• 进一步在旧改版隔离实例 http://127.0.0.1:5682 上重放了 fresh 图片请求，返回同样的 403 access denied for invalid user
• 结论因此进一步收敛：当前 blocker 不是 upstream 回归，而是外部图片/视频凭证已失效
• 已在 huobao-drama-upstream 增加按服务类型的运行时覆盖能力，可用 HUOBAO_TEXT_* / HUOBAO_IMAGE_* / HUOBAO_VIDEO_* 环境变量接管数据库中的 AI 配置
• 已在 huobao-drama-upstream 固化 scripts/run_storyforge_smoke.sh，可自动复制旧库配置与数据、起隔离实例并校验 /health

结论更新：huobao-drama-upstream 的代码级兼容迁移已经完成，当前剩余 blocker 是外部图片/视频凭证失效，导致无法用“旧配置副本”继续 fresh 生成；但新的运行时 env 覆盖路径已经就位，后续补新 key 不需要再手改 SQLite。

当前已完成迁移面

• 旧运行链依赖已从 collector-service 主代码中剥离
• 旧运行残留容器 plugin / sandbox / pg / minio / redis / mongo 已于 2026-03-20 实际下线并清理
• 数据库已支持 project/content_source/job_events
• collector-service 已增加：
  • n8n 触发
  • cutvideo 集成 client
  • huobao-drama 集成 client
  • 内部编排接口
• docker-compose.yml 已改为 collector + n8n + cli-proxy-api
• n8n 工作流导出文件已纳入仓库
• collector-service 的 live 运行态已回归到 StoryForge-gitea 自身源码构建，不再依赖旧导入目录的临时 bind mount
• collector-service 现已在 live 8081 提供 /v2/douyin/* 接口，并保留原有 real-cut / ai-video / content-source-sync 路由
• 曾混入本仓库的 android-app/ 已确认来自独立 AI Glasses 工程叠加，现已从 StoryForge 主仓库边界中拆出，后续不再作为当前主工作区的一部分维护

当前主要风险

1. 小红书账号级内容源还未做真实平台验证
2. douyin public 直抓仍受反爬限制，但现在已经有“真实浏览器 + 人工登录 + 自动提取 + 回写现有工作台”的可落地协作链
3. huobao-drama-upstream 已完成代码迁移并可编译，但 fresh smoke 受外部图片/视频凭证 403 invalid user 阻塞
4. Android / OTA 旧链路已拆出当前仓库，相关验证和发布不再属于 StoryForge 主线范围