zhouxiaoka--autoclip/HANDOFF.md

AutoClip — 项目状态 / 进度 / 计划

更新：2026-05-30 · 分支 main（领先 origin 若干 commit，未 push）

AutoClip 是一款 AI 视频切片工具：输入 B站/YouTube 链接或本地视频，自动识别精彩片段、 生成切片与合集。本文是项目的当前状态与路线图的单一事实来源。

---

一、架构与交付形态

层	技术	目录
后端	FastAPI + Celery（桌面模式用本地队列）+ SQLite	backend/
前端	React + TypeScript + Ant Design + Vite	frontend/
桌面壳	Tauri 2 + Rust	src-tauri/
LLM	OpenAI / Gemini(google-genai) / 通义千问(dashscope) / 硅基流动	backend/core/llm_providers.py

三种交付形态：Docker 部署、本地脚本启动（start_autoclip.sh）、桌面客户端（macOS DMG）。 近期工作集中在桌面客户端。

---

二、当前进度（已完成且验证）

桌面客户端打包链路从"打不出能用的包"做到了端到端可装可用：

1. 统一打包路线 —— 砍掉历史上互相打架的 PyInstaller / prepare_resources 两条死路线， 只保留 python-build-standalone（PBS）：便携 Python + 后端源码 + 静态 ffmpeg/ffprobe 全部打进 .app，用户机器零依赖。脚本：scripts/build_macos_arm.sh。

2. 修好一连串发版阻断 bug（都已实测验证）：

   • ffmpeg 不可用：原来打包的是 homebrew 动态版（57 个 /opt/homebrew 依赖），换成静态 arm64 ffmpeg+ffprobe（零非系统依赖），并让 Rust 启动器通过 AUTOCLIP_FFMPEG_PATH/ AUTOCLIP_FFPROBE_PATH 指向内置二进制。
   • 黑屏：Vite 把 React/antd 拆成两个 vendor chunk，antd 先于 React 初始化 → createContext 报错、React 不挂载。去掉手动分包后正常渲染。
   • 项目列表一直转圈：/api/v1/projects/ 因缺 pytz 报 500。补齐 pytz 及 LLM SDK (openai/google-genai/dashscope) 到 requirements.txt。
   • 依赖漂移护栏：构建期 AST 扫描后端所有 import，缺任何一个直接 fail，杜绝"开发能跑、打包就 500"。

3. CI 统一 —— 7 个从未成功的桌面构建工作流 → 1 个 desktop-build.yml（跑 PBS 脚本， v* tag 自动挂 Release）。保留 ci.yml（测试）、i18n-sync.yml（文档）、 nightly-desktop-smoke.yml（后端冒烟）。

4. 仓库清理 —— 删掉约 30 个废弃脚本、嵌套鬼目录、94M 旧 PyInstaller 备份等； scripts/ 只剩 4 个活脚本；重写 scripts/README.md 与 BUILD_GUIDE.md。

5. Gemini SDK 迁移 —— 从已停更的 google-generativeai 迁到统一的 google-genai。

产物：src-tauri/target/release/bundle/macos/AutoClip Desktop_1.0.0_aarch64.dmg（~260M）。

---

三、遗漏 / 未验证（按优先级）

已闭环（不再是遗漏）：完整切片流程已在打包后的 app 里端到端跑通（粘 B站 链接 → 下载 → 字幕 → DashScope 分析 → 评分 → 标题 → 切割 → 出 5 个切片，79s 完成）；无字幕视频现在可 在「设置 → 语音转写」按需安装 faster-whisper 自动转写（实测安装 214MB、转写出 SRT）。

中

• 签名/公证：目前 ad-hoc 签名，未做 Apple Developer ID 签名 + 公证，用户首次必须右键打开。
• 仅 arm64：没有 Intel mac / Windows / Linux 包。
• 依赖未锁版本：requirements.txt 多数包没固定版本，跨时间/跨机器构建有漂移风险。
• 构建慢：每次构建都重装全部 pip 依赖（PBS python 被 rm -rf 重建）。可缓存已装好的运行时。
• Gemini 迁移未对真实 API 验证：代码与新版 google-genai SDK 接口已对齐并能 import，但没有 Gemini key 实际调用过（DashScope 路径已实跑验证）。

低

• 前端单 bundle ~1.5MB：去掉分包后是一个大 chunk，桌面端无所谓，若以后也跑 Web 可考虑按路由懒加载。
• 单步重试 submit_single_step_task 仍走 Redis send_task（桌面没改），目前没有入口用到； 整条流水线的 .delay() 已由 DesktopAwareTask 接管本地执行。

---

四、未来计划（路线图）

1. 正式签名与公证：申请 Apple Developer ID，签名 + notarize，消除"右键打开"。
2. 多平台打包：把 build_macos_arm.sh 的 runner / PBS URL / ffmpeg URL / tauri target 参数化， 扩到 Intel mac、Windows、Linux（PBS 与静态 ffmpeg 都有对应平台版本；faster-whisper 本就跨平台）。
3. 依赖锁定：固定 requirements.txt 版本（或引入 lock 文件），保证可复现构建。
4. 构建提速：缓存 PBS python + 已装依赖，避免每次重装。
5. 自动 UI 冒烟：在 CI 里加一步，验证打包后的前端能挂载（而不仅是后端接口通）。
6. 产品向：B站上传、字幕编辑、批量处理、云端同步（见 RELEASE_CHECKLIST.md 后续计划）。

---

五、关键文件

• 打包脚本：scripts/build_macos_arm.sh（说明见 scripts/README.md、BUILD_GUIDE.md）
• 后端启动器（Rust）：src-tauri/src/backend_manager.rs
• 桌面后端入口：backend/desktop_main.py
• ffmpeg 路径解析：backend/utils/ffmpeg_utils.py
• LLM 提供商：backend/core/llm_providers.py
• 桌面流水线本地执行：backend/core/celery_app.py（DesktopAwareTask）、backend/utils/task_submission_utils.py
• Whisper 运行时（按需安装）：backend/services/whisper_runtime.py、whisper_model_manager.py、 前端 frontend/src/components/SpeechRecognitionConfig.tsx
• 前端 API 配置：frontend/src/utils/apiConfig.ts
• CI：.github/workflows/desktop-build.yml

六、安装（给用户）

1. 双击 DMG → 拖 AutoClip Desktop 到 Applications
2. 首次右键应用 → 打开（ad-hoc 签名，绕过 Gatekeeper）
3. 进设置页填 LLM API key 即可使用

命令行排查后端：

'/Applications/AutoClip Desktop.app/Contents/MacOS/autoclip-desktop'
# 应看到 Backend started on port: XXXXX / Application startup complete