# StoryForge 现状审计

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

## 结论

当前应以 `/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` 命令集成
- 账号级内容源同步同样复用 `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。

## 当前已完成迁移面

- FastGPT 运行时依赖已从 `collector-service` 主代码中剥离
- 旧 FastGPT 运行残留容器 `storyforge-fastgpt-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` 自身源码构建，不再依赖 `/Users/kris/code/Fastgpt/collector-service/app` 的临时 bind mount
- `collector-service` 现已在 live `8081` 提供 `/v2/douyin/*` 接口，并保留原有 `real-cut / ai-video / content-source-sync` 路由
- Android Explore 页已补上“账号同步”入口，可直接创建内容源账号同步任务，并支持平台、主页链接、账号标识、最大抓取条数、跳过已存在、自动触发分析等参数
- Android 工作区缺失的 `com.aiglasses.app.data` 数据层已从同源代码补回，当前 `./gradlew :app:compileDebugKotlin` 与 `:app:assembleDebug` 均已通过，并产出 `app-debug.apk`

## 当前主要风险

1. 小红书账号级内容源还未做真实平台验证
2. `douyin` public 直抓仍受反爬限制，但现在已经有“真实浏览器 + 人工登录 + 自动提取 + 回写现有工作台”的可落地协作链
3. `huobao-drama-upstream` 已完成代码迁移并可编译，但 fresh smoke 受外部图片/视频凭证 `403 invalid user` 阻塞
4. Android 端目前已能完成 Debug APK 构建，但仍缺少真机安装和功能回归验证