# 抖创工坊 ## Git 推送约定 - 本项目的更新只能推送到远程 `main` 分支。用户要求提交或推送时，先核对目标为 `origin/main`；不得创建或推送其它远程分支，除非用户明确修改此约定。 - 功能或修复推送到 `main` 后同步 GitHub Issues：更新关联事项的进度、提交链接、验收结果与剩余缺项；没有对应记录时补建。只有满足该 Issue 完成条件才关闭，部分完成和未验证事项保持打开。 基于 Electron + React 的桌面应用，用于抖音视频采集、转录、AI 洗稿、Skills 蒸馏、本地竖屏视频生成与多平台发布（发布中心按平台分栏：**抖音**图文由外部 sau 引擎提交、**今日头条**文章与**小红书**图文由自研 Playwright 执行器提交（小红书默认只填到草稿），其余人工交付；每个平台内部再按图文/视频/文章分）。当前视频生成通过 HyperFrames CLI 本地渲染 HTML/CSS/GSAP 成 MP4。 ## 项目架构 ``` douyin/ ├── src/ # 后端（Node + Express） │ ├── app.ts / server.ts # Express 装配 / 独立 HTTP 入口 │ ├── lib/ │ │ ├── jobs.ts ai-cleaner.ts storage.ts media.ts asr.ts # 任务/洗稿/存储/下载/ASR │ │ ├── hyperframes-video.ts video-output.ts range-response.ts │ │ ├── assets-store.ts assets-routes.ts # 素材库 │ │ ├── local-users.ts local-auth.ts local-user-routes.ts # 本机操作者与会话 │ │ ├── publishing-*.ts # 发布中心（资产/文案/平台/服务/存储/路由） │ │ ├── sau-runner.ts # 抖音图文（外部 sau CLI） │ │ ├── article-draft.ts toutiao-article.ts toutiao-media.ts # 文章内核 + 头条限额/渲染/封面 │ │ ├── toutiao-browser.ts toutiao-page.ts toutiao-runner.ts # 头条解析链/页面步骤/执行器 │ │ ├── note-media.ts # 图文配图裁 3:4（平台中立） │ │ ├── xhs-browser.ts xhs-page.ts xhs-runner.ts # 小红书解析链/页面步骤/执行器 │ │ ├── collections.ts nickname.ts user-page-crawler.ts # 合集/昵称/主页采集 │ │ └── secret-scan.ts # 凭据扫描 │ └── types.ts ├── renderer/src/ # 前端（React 19 + Vite + Tailwind） │ ├── pages/ # JobListPage JobDetailPage PublishingPage AssetsPage │ │ # CollectionList/Detail SkillList TrashPage SettingsPage │ ├── components/ # PublishPreviewDialog QrLoginPanel ToutiaoLoginPanel XhsLoginPanel │ │ # CreateNotePackageDialog CreateToutiaoArticleDialog PublishingChannelTabs │ │ # shell/（侧栏、顶栏、移动端导航） │ ├── utils/publishing.ts # 发布中心纯函数（渠道/计数/动作可见性/提示） │ ├── services/api.ts store/ types/index.ts ├── electron/ # 主进程、配置 IPC、内嵌后端装配 ├── scripts/ # 只读侦察与复核脚本（probe-*、verify-*、check-secrets） ├── docs/ # specs / plans / research / worklog / patches └── dist/ dist-electron/ # 两套编译产物（见「构建与运行」） ``` ## 技术栈 ### 后端 - Node.js 18+、Express 4、TypeScript - `openai`：OpenAI-compatible AI 洗稿 - `yt-dlp`：视频下载（外部二进制） - `ffmpeg` / `ffprobe`：音视频处理（外部二进制） - whisper.cpp：内置本地 ASR，默认 `ggml-small` 多语言模型 - HyperFrames CLI：本地竖屏 MP4 渲染（生成视频步骤需要 Node.js 22+ 和 FFmpeg） ### 前端 - React 19、Vite、React Router DOM 7、Zustand、Tailwind CSS、Axios ### 桌面端 - Electron 34、electron-builder ## 核心流程 ### 手动分步主链路 ``` 用户输入（URL 或分享文本） ↓ POST /api/jobs 创建任务并解析输入 ↓ 用户在详情页逐步确认执行： 1. 视频转录（yt-dlp + ffmpeg + 内置 whisper.cpp） 2. AI 洗稿 3. 生成视频提示词 4. 生成 9:16 MP4（HyperFrames） ``` 每个步骤独立执行。用户点击某一步后，后端在同一次请求内自动重试最多 3 次；失败后停在当前步骤，用户可手动重试。后一步必须等前一步成功后才能执行。 ### 数据存储 **目录取决于运行方式**（易踩坑，按模式确认）：独立后端 `node dist/server.js` → **仓库内 `storage/`**（`src/server.ts` 的 `path.join(rootDir, "storage")`）； Electron → `app.getPath('userData')/storage`（即 `~/Library/Application Support/douyin-ai-video/storage`， 配置里的 `storagePath` 可覆盖）。 ``` storage/ ├── raw/{videos,audio,transcripts,page,text}/ # 下载的视频、WAV、结构化转录、页面元数据、分享文本 ├── processed/{scripts,cleaned,scenes,subtitles}/ ├── output/videos/ # HyperFrames 项目、snapshots/ 静帧、MP4 ├── output/publishing/ # 发布交付包（自包含：成片 + 封面 + images/） ├── assets/{images,audio}/ # 素材库 ├── cache/ # jobs / collections / publishing / assets / local-users 索引 └── logs/ ``` 注意 `output/videos/{jobId}/hyperframes/snapshots/frame-NN-at-Xs.png` 是 `hyperframes snapshot` 的产物， 每场景一张 1080×1920 静帧，可直接当图文素材。 ### 任务状态与步骤 ```typescript type JobStatus = "queued" | "processing" | "done" | "failed"; type JobStage = | "submitted" | "parsed" | "downloading" | "downloaded" | "extracting" | "audio_extracted" | "transcribing" | "transcribed" | "cleaning" | "cleaned" | "generating-video-prompts" | "scripted" | "generating-video" | "rendered" | "failed"; type WorkflowMode = "manual" | "auto"; type PipelineStep = "transcribe" | "clean" | "generate_video_prompts" | "generate_video"; type PipelineStepStatus = "pending" | "running" | "succeeded" | "failed"; ``` ## API 接口 ### 任务管理 - `POST /api/jobs` - 创建任务 - `GET /api/jobs` - 获取未删除任务列表 - `GET /api/jobs/:id` - 获取任务详情 - `DELETE /api/jobs/:id` - 软删除任务到垃圾桶 - `GET /api/jobs/trash` - 获取垃圾桶任务并触发过期清理 - `POST /api/jobs/:id/restore` - 恢复垃圾桶任务 - `DELETE /api/jobs/:id/permanent` - 永久删除垃圾桶任务及关联文件 ### 手动步骤 - `POST /api/jobs/:id/steps/transcribe` - `POST /api/jobs/:id/steps/clean` - `POST /api/jobs/:id/steps/generate-video-prompts` - `POST /api/jobs/:id/steps/generate-video` - `POST /api/jobs/:id/reclean` - 补充内容重新洗稿（body: `{ supplementalText }`），已完成的视频任务也可用 ### 内容获取 - `GET /api/jobs/:id/script` - 历史脚本资产 - `GET /api/jobs/:id/cleaned` - AI 清洗结果 - `GET /api/jobs/:id/raw-transcript` - 结构化原始转录 - `GET /api/jobs/:id/video-prompts` - 视频提示词 - `GET /api/jobs/:id/video-output` - HyperFrames 视频输出信息 - `GET /api/jobs/:id/video/download` - 下载 MP4 - `GET /api/jobs/:id/video/stream` - 成片流（支持 Range） - `GET /api/jobs/:id/raw-video/stream` - **已下载的原视频**流（支持 Range；原视频在「视频转录」步骤落盘到 `raw/videos/{jobId}.mp4`） ### 素材库 - `GET /api/assets?kind=image|audio` - 列表 - `POST /api/assets/images` / `POST /api/assets/audio` - 多文件上传（multipart，字段名 `files`） - `GET /api/assets/:id/raw` - 原文件（支持 Range，音频进度条依赖） - `DELETE /api/assets/:id` - 删除记录与磁盘文件 ### 本机操作者与权限 - `POST /api/local-sessions/auto` - **启动即用的自动会话**（无 PIN）；无管理员时自动创建「本机用户」 - `GET /api/local-sessions/current` - 当前会话用户 - `GET /api/local-users` - 用户列表 - `POST /api/local-sessions` - 普通开会话（管理员仍需 PIN） ### 发布中心（人工交付） - `POST /api/jobs/:id/publishing/preview`：body 可带 `contentType: "note"`（图文）、 `imageSource: "frames"|"library"` + `imageAssetIds[]`；响应回 `images`/`imageLimit`/`copyLimits`。 配套 `GET /api/jobs/:id/publishing/assets`。 - `POST /api/publishing/packages`（可带 `contentType: "note"` + `noteCopy` + 图片来源）、 `GET /api/publishing/packages`、`GET /api/publishing/packages/:id`。 - `GET /api/publishing/packages/:id/preview`：**包级预览**（产出 `previewRevision`，下发 `copyChecks`； 前端只渲染、不复刻字数规则）。 - `GET /api/publishing/packages/:id/images/:index`：图文包第 `index` 张图（0 基，对应 `imagePaths`；越界 404）。 - `GET /api/publishing/packages/:id/article`：文章包的 `article.html`（降级通路，可粘进编辑器）。 - `POST /api/publishing/tasks/:id/auto-publish`：**按「内容类型 × 平台」分派** （`note×douyin` → sau；`article×toutiao` → 自研头条执行器；`note×xiaohongshu` → 自研小红书执行器）。 **必须带 `previewRevision`**：缺失 400、不一致 409；body 可用 `dryRun: true`（**仅小红书**：只填到草稿，**服务端强制不点发布**； 其余通路传它一律 400）。配套 `POST .../auto-publish/code`（抖音短信验证码 → `/verify_code.txt`）。 - **小红书图文草稿仅存于专用浏览器本地 IndexedDB，不同步到 App 或默认浏览器**。执行器必须点「暂存离开」并读回当前账号、本次时间及完整标题/正文/图片/AI 声明，成功保存才记录 `xhsDraftId`。`POST /api/publishing/xhs/drafts/window` 用同一 profile 打开有头浏览器并选择「图文笔记」；窗口留给用户，关闭后释放互斥。旧 `draftOnly` 记录不代表已核实保存，界面必须提示待核实。不要改回填完立即关窗、`openExternal` 或引导去 App 找网页草稿。 - 登录与自检：`POST/GET/DELETE /api/publishing/toutiao/login`（应用内扫码）、 `POST /api/publishing/toutiao/login/window`（浏览器窗口扫码，同步等 180s）、`POST /api/publishing/toutiao/verify`； 小红书同形：`/api/publishing/xhs/login`、`/login/window`、`/verify`（**零副作用**自检）。 - `PATCH /api/publishing/tasks/:id/content` / `/schedule`、`POST .../cancel` `/restore` `/mark-published` `/record-failure`（`withdraw` 与删除/恢复发布包**仅管理员**）。 ## 关键数据结构 > 完整的类型定义**以代码为准**（`src/types.ts` / `renderer/src/types/index.ts`）。 > 这里只列**行为相关**的字段，避免文档与代码各说一份。 - `JobRecord`：`id` / `sourceUrl` / `topic` / `status` / `stage` / `workflowMode` / `steps` / `deletedAt`+`trashExpiresAt`（垃圾桶 30 天）/ `videoPath` `audioPath` `audioManifestPath` `transcriptPath` `videoProjectPath` `videoOutputPath` `videoGeneratedAt` / `storagePath` / 时间戳。 - `TranscriptAsset`：`transcript`（纯文本）+ `segments`（`{start,end,text}`）+ 可选 `words` （`{start,end,word,probability}`）/ `duration` / `language` / `model` / `provider: "whisper.cpp"`。 - `CleanedScript.output`：`title` / `summary` / `keyPoints` / `cleanScript` / `voiceoverScript` / `videoOutline[{title,bullets,visualPrompt}]` / `videoPrompts` / `tags` / `hyperframesVideo{provider:"hyperframes", projectPath, videoPath, manifestPath, duration, 1080×1920}`。 其余字段（`transcriptModel` / `rawText` / `enhancedScenes` / `qualityNotes` / `aspectRatio` / `width` / `height` 等）一律以代码为准。 ## 配置管理 - **桌面端配置**由 Electron 决定：`app.getPath('userData')/config.json`（即 `~/Library/Application Support/douyin-ai-video/config.json`）；其中 `storagePath` 无值则回落到同目录 `storage/`。 API Key 由 Electron `safeStorage` 加密存储。 ⚠️ `~/.douyin-ai-video/` 是**另一个**用途（`douyin-cookie.txt` 抖音登录态等），**不是** Electron 读配置的位置 （早期文档写的 `~/.douyin-ai-video/config.json` 是错的，2026-09-17 按实测更正）。 - **独立后端**（`npm start` = `node dist/server.js`）从环境变量读 AI 配置（见 `src/server.ts`）： `AI_PROVIDER` / `AI_API_KEY` / `AI_MODEL` / `AI_BASE_URL`。 桌面端配置形状：`{ aiKeys: [{ id, name, provider, apiKey, baseURL, model, isActive }] }`。 - **抖音图文（sau）**：`SAU_BINARY`（`sau` 可执行文件，例如 `/.venv/bin/sau`）+ `SAU_BASE_DIR`（其仓库根，含 `conf.py`； `cookies/` 与 `verify_code.txt` 相对它）。两条入口（独立后端与 Electron）都已透传。 缺省时**不静默失败**：该通路 422 并给安装指引，其余功能不受影响。 Electron 环境变量优先，回退桌面 config.json 的 `sauBinary`/`sauBaseDir`；两项均未保存时，首次完整环境路径会通过现有配置保存机制记住。临时环境覆盖不改写已有（含部分）配置，独立后端仍只读环境变量。 - **头条**：`TOUTIAO_BROWSER_BINARY`（缺省按解析链：显式配置 → Electron 注入 → 开发态 `vendor/package-assets/browser/chrome-headless-shell/**` → Playwright 缓存 → 系统 Chrome）、 `TOUTIAO_PROFILE_DIR`（**必须落在 storage 内**）。找不到浏览器时 422 + 两条可照抄的命令与逐层诊断。 - **小红书**：`XHS_BROWSER_BINARY` / `XHS_PROFILE_DIR`（同形，两条入口都透传）。 - **ASR** 固定内置 `whisper.cpp`（**不再调用** OpenAI Whisper API / FunASR / faster-whisper）：模型 `ggml-small`；`MediaService.extractAudio()` 输出 `raw/audio/{jobId}.wav`（`pcm_s16le` / 16kHz / 单声道）；打包资源 `resources/whisper/whisper-cli` 与 `resources/whisper/models/ggml-small.bin`，打包前跑 `npm run prepare:whisper` （构建机步骤，需要 `cmake`、C/C++ 工具链与 `tar`；最终用户不需要）。旧字段 `asrProvider`/`asrApiKey`/`asrBaseURL`/`asrModel` 仍兼容读取但不再使用。⚠️ 缺少 `whisper-cli` 或 `ggml-small.bin` 时转录步骤应失败，并提示重新运行 `npm run prepare:whisper` 或重装完整应用。 ## 构建与运行 ```bash npm install npm run dev # Vite + Electron（= dev:renderer + dev:electron） npm run dev:electron # 只起桌面端（内含 build:electron 与 mark-cjs） npm run dev:renderer # 只起前端（Vite） npm start # 独立后端：node dist/server.js（用**仓库内** storage/） npm test / test:hyperframes npm run check # 三合一门禁；check:backend / check:renderer / check:secrets 可单跑 npm run build:backend / build:renderer / build:electron # npm run build = 三者 + mark-cjs npm run prepare:whisper / check:whisper / prepare:package:mac / check:package-assets npm run package # mac 打包（prepare:package:mac + build + check:package-assets + electron-builder） ``` > ⚠️ **改了源码必须编译对应产物再重启**，这里有**两套**独立产物，踩错任一个的表现都是「改了没生效」： | 改动位置 | 产物 | 编译 | 生效方式 | | --- | --- | --- | --- | | `src/`（`app.ts`、`lib/*.ts`） | `dist/` | `build:backend` | 重启后端（含 Electron 内嵌后端） | | `electron/`（主进程、配置 IPC、`electron/server.ts`） | `dist-electron/` | `build:electron` | 重启 Electron | | `renderer/` | Vite 内存 | 无需 | HMR 自动热更 | - **`build:backend` 不产出 `dist-electron/`，反之亦然**；`npm run dev` 的 `dev:electron` 内含 `build:electron`， 但**直接 `node_modules/.bin/electron .`（或 `electron .`）会绕过它**（此时 `dist-electron/` 仍是旧的）。 - 典型事故（2026-09-17）：给 `electron/server.ts` 加了 `SAU_*` 透传，env 确实进了 Electron 进程， 但 `dist-electron/server.js` 是旧的 → 无论怎么配都报「未配置」。 - `npm run check`（`--noEmit`）与 `npm test`（tsx 跑源码）**都不产出任何产物**，不能替代编译。 ## 关键注意事项 ### 数据来源与加载 - 视频转录来自音频 ASR，是洗稿**优先输入**；分享文本是参考信息，**没有转录时才作为 fallback**； 前端必须清晰区分「视频转录」与「分享文本」。 - 内容加载优先 `cleaned`；`script` 是历史接口、不作为新主链路依赖；转录经 `/raw-transcript` 取， 响应兼容 `transcript` 字符串并扩展 `segments`。 ### 视频生成与手动步骤 - 新任务默认 `workflowMode: "manual"`；`JobStore.create()` 只建任务、不自动跑链路；后一步必须等前一步 `succeeded`； 运行中重复触发 409；每次触发后端**自动最多重试 3 次**，失败即停在当前步骤等人工重试。 顺序固定：transcribe → clean → generate_video_prompts → generate_video。 - `video-prompts` 是新主链路正式输出，HyperFrames 生成视频必须先完成该步。 - 生成视频是**本地 HTML/CSS/GSAP 动画渲染**（不是 Sora/Remotion/HeyGen），依赖 Node 22+、FFmpeg、 `npx hyperframes doctor`；流程：`doctor --json` → 生成项目（写 `index.html`/`video-source.json`/`DESIGN.md`） → `lint`/`validate`/`inspect`/`render`；产物默认 `output/videos/{jobId}/hyperframes/renders/video.mp4`。 默认可保留无声；工作台「成片配音与音乐」可开启 macOS 系统离线中文 TTS、选择本机音频素材与音量（最高 50%）。`GET /api/video-audio/capabilities` 返回已安装中文语音，`POST /api/jobs/:id/steps/generate-video` 可传 `{audio:{voiceover,voice,rate,backgroundAssetId,backgroundVolume}}`。选项写入 `job.videoAudio`，重试保留；已完成步骤只有明确传音频选项才允许重新生成，任务互斥和旧产物保护仍生效。 - 配音按分镜 narration 完整分段，不截断；以实测音频时长写 `assets/audio/subtitles.srt` 与 `audio-manifest.json`，最多 1.35 倍加速适配，仍放不下则报错请调整稿件。音乐从素材库安全快照读取，循环、淡入淡出并在口播时自动压低，限制峰值。预览引用同一 `mix.wav`，最终以本地 FFmpeg 明确映射 AAC 音轨再验收；固定版 CLI 的旧 `filter_complex_script` 不兼容新 FFmpeg 时也不会交付无声成片。未配置音频不生成音轨；失败不降级为无声成功。 - 本地中文 TTS 当前仅支持 macOS 的已安装系统语音，Windows/Linux 暂不支持中文 TTS（可使用背景音乐）；不启用付费云服务、不上传素材、不保存新凭据。`npm run test:hyperframes` 验收真实中文配音、字幕、混音及 AAC；`scripts/verify-job-date-audio.ts` 用隔离 API/系统 Chrome 验收日期组合筛选与音频控件，需先编译 renderer。 ### 重新洗稿（reclean） - 重新洗稿走独立接口 `POST /api/jobs/:id/reclean`，不经过 `steps/clean`（后者对已 `succeeded` 的步骤返回 409）。 - 传入的 `supplementalText` 会与视频转录合并，重新调用 AI 洗稿；结果持久化到 `processed/cleaned/{id}.json`（顶层含 `supplementalText` 字段）。 - 重新洗稿成功后会把下游 `generate_video_prompts`、`generate_video` 重置为 `pending`，并清空 `videoProjectPath`/`videoOutputPath`/`videoGeneratedAt`，避免展示或复用旧的视频产物。 - 前端入口：工作台始终显示「补充内容重新洗稿」按钮（只要 clean 步骤 `succeeded`），不限于未完成的任务；已生成视频的任务同样可重新洗稿。 ### 垃圾桶 - 删除任务是软删除：设置 `deletedAt` 和 `trashExpiresAt`。 - 垃圾桶保留 30 天，启动和查询列表时清理过期任务。 - 永久删除会清理该 jobId 关联产物；处理中任务禁止永久删除。 - 永久删除需要同步清理 `output/videos/{jobId}` 下的 HyperFrames 项目和 MP4。 ### 素材库 - 主导航「素材」（`/assets`）：上传/列表/缩略图/试听/删除；**图片可选入图文发布**，音频本轮不接入任何流程。 - **图片进图文包＝两种来源二选一**：`frames`（缺省，该作品的场景静帧，按场景序）或 `library` （素材库多选，**按点选顺序**入包）。来源与顺序都进 `previewRevision` ⇒ 换来源/调顺序让旧 revision 失效（409）。 - `library` 经 `AssetStore.resolveFile` 解析成绝对路径后才交给 `createNotePackageAssets`（id→路径的归属校验 只有这一个真源）；选 0 张报 400、超 35 张报 422；`frames` 一张静帧都没有**不**报错 （沿用「缺图也把包建出来、只标 `missing_images`」的口径）。 - 安全：**落盘文件名一律服务端生成**（`randomUUID` + 白名单扩展名），客户端名字只作 `originalName` 展示、 **绝不参与路径拼接**；读取与删除都校验路径落在 `assets/` 内。 - 限额：图片 `jpg/jpeg/png/webp` ≤20MB、音频 `mp3/wav/m4a/aac` ≤50MB、单次 ≤20 个文件 （违规 415 / 413 / 400）。`GET /api/assets/:id/raw` 支持 Range（音频进度条依赖），与成片流共用 `range-response.ts`。 - 上传是 multipart（`multer` memoryStorage）；⚠️ **busboy 按 latin1 解码 `filename`**，中文名要按 `decodeMultipartFilename()` 回退转换。图片尺寸与 WAV 时长由纯 Node 解析容器头得到； **MP3/M4A 时长为 `undefined`**（界面显示「—」），如需补全可接 `ffprobe`。 ### 在线音频素材（2026-09-30） - 「素材」音频区的「在线音频」支持网易云/QQ 热歌、飙升、新歌榜与主动搜索；试听后多选下载，每批 ≤20 首。仅公开音源，不读取平台 Cookie，不接入成片。 - `online-audio-sources.ts` 固定 HTTPS 来源与媒体域名，DNS 公网检查并固定地址、禁止重定向；媒体 ≤50MB，经 FFprobe 读取音频帧验证后由同一个 AssetStore 入库。记录来源与试听片段标识；同平台曲目去重，素材索引写入串行且损坏时拒绝覆盖。 - 榜单缓存 10 分钟、刷新至少间隔 60 秒，失败保留旧榜单。试听缓存 `cache/online-audio/media/` 与素材库分离、启动清空；导入批次只在内存保留，前端 sessionStorage 恢复最近进度，后端重启明确标中断。 - API `/api/online-audio/catalog`、`/boards`、`/boards/refresh`、`/search`、`/preview`、`/media/:token`、`/imports`、`/imports/:id`；试听准备与下载复用本机会话，批次查询校验操作者归属。 - `node --import tsx scripts/verify-online-audio.ts` 两家真实来源验收，全程临时存储；`--serve` 起 3100 隔离真实 API，退出删除临时目录。`scripts/verify-online-audio-ui.js` 是浏览器响应乱序回归，不写真实数据。 ### 原视频播放与操作者模型 - 「视频转录」会把原视频下到 `raw/videos/{jobId}.mp4`；详情页成果画布「视频」格子提供**原视频 / 成片**切换 （默认：有成片看成片，否则看原视频）。没下载时显示「原视频尚未下载」并引导先转录，**不自动下载**。 - `GET /api/jobs/:id/raw-video/stream` 与成片流共用同一份**根目录/inode 安全校验** （`video-output.ts` 的 `resolveContainedMp4`）—— `job.videoPath` 是持久化绝对路径，校验各写一份＝开放任意文件读取。 - 面向使用者的登录/切换/用户管理界面**已全部移除**；启动时前端调 `POST /api/local-sessions/auto` 取会话 （优先复用已有 `isActive` 管理员，按 `createdAt`/`id` 升序确定性选取；不存在才建无 PIN 的「本机用户」； 不删不改任何历史用户）。**管理员 PIN 的契约没放宽**：普通 `POST /api/local-sessions` 无 PIN 仍 401， 无 PIN 分支只存在于 `openLocalOperator()` 这一条显式路径上。发布中心的权限与审计（`requireActor`/`actor` 快照）完全保留。 ### 字幕图集创作（2026-10-09 更新） - 独立导航 `/galleries` 与工作台 `/galleries/:id`；原视频区域有快捷入口。已有原视频即可创作，不要求洗稿或 HyperFrames 成片，不改变作品步骤状态。 - 原生字幕只取画面像素；转录分段仅辅助定位。默认自动规划整套，目标每张 6～9 条（默认 8），长句或多行字幕会减少条数并增加张数；手动支持 1～9 条。先查看每张文字与候选拼图，确认整套字幕后一次生成；时间、区域、主画面取景和拆分/合并收进高级调整。本地 FFmpeg 输出 1080×1440 PNG，保持原比例，不重绘文字。草稿与未确认方案可恢复。目标条数在 6～9 条范围内均衡分图，避免一条尾页；字幕高度和紧凑间距共同决定容量。新自动方案使用 filmstrip 标记：主画面裁去黑边与原字幕区后满宽取景；每条以自身时间的主视觉画面为背景，拼入完整原生字幕像素带，上下各至少 20 输出像素背景，连续衔接。主画面至少 432 高，字幕条至少 96 高；规划与渲染共用容量规则。满宽取景可能裁掉上下内容，可在高级调整取景；已有 compact 和手动排版保留。 - 自动候选在 macOS 使用本地 Apple Vision OCR，自动规划以约 0.5 秒间隔采样（每窗口 7～80 帧），保留窗口内多次字幕变化，以重叠 ASR 分段的完整上下文核对字符顺序、字幕位置与尺寸；无标点合并窗口最多 4 秒。新闻标签、过大或偏侧文字及不匹配文字排除，仍可能漏检或误选，必须整套核对；无候选不能确认生成。未匹配定位窗口多于已匹配窗口的低覆盖方案禁止确认与生成（旧缓存方案也复核）。构建机先运行 `npm run prepare:subtitle-ocr`（需 Swift 工具链），Mac 打包自动编译并携带桥接二进制，用户机器无需 Swift。Windows 自动 OCR 暂未实现；无本地 OCR 时保留旧像素候选并在方案中明确警告（不能当作已识别对白）。统一校准与手动高级调整仍可用；识别运行失败明确报错，不以像素冒充 OCR。预览与最终图哈希一致，长字幕不能靠拉伸挤进 9 条。 - `POST /api/galleries/:id/plan`（version、targetLines、可选统一字幕区域）、`POST .../plan/render`（version、planId、subtitlesConfirmed）、`GET .../plan/images/:index`（planId、version）。方案绑定源指纹和转录哈希，修改图片草稿使方案失效；确认与生成结束都复核来源，自动图集发布预览也拒绝旧转录。 - 自动创作整套图文在正文为空时同时生成标题、背景引入、实际编号要点、互动结尾与话题；已有正文保留。`POST /api/galleries/:id/copy`（version）独立重生成文案，已有内容须在产品界面确认替换，失败保留原记录。文案输入优先完整转录全文（未选入图片的片段仍参与），只使用 OCR 核实候选补充核对，识别不清列入 `copyReference.notes`；模型输出仍须核对，不能当作事实已验证。复用现有 AI 配置，DeepSeek 成文调用关闭 thinking，预算遵从 maxOutputTokens／默认2400；最多三次尝试，超限压缩重写、截断响应拒绝。共享限额标题20、正文1000、话题10×20。只改文案保留候选与已生成图片，发布预览使用最新正文；AI文案绑定转录哈希与源指纹，来源变化拒绝旧文案。无配置／成文失败不阻断图片规划，明确提示原因。 - `GalleryService`/`GalleryMedia`/`gallery-routes` 由 `app.ts` 共用装配。索引 `cache/galleries.json`，产物 `output/galleries/{id}/{generation}/`；生成串行，失败保留旧图仅供参考，成功替换后清理上一代。原视频使用 `resolveSourceVideo` 校验后从已打开 handle 复制到私有临时快照，FFprobe/FFmpeg 不重新打开原路径；源指纹含 inode/size/mtime/ctime。 - 保存、删除、生成带 `version`；图集发布预览也必须带当前版本。图片 URL 绑定 `generation`，源或图片变化须重生成。`createGalleryNote` 仅接受服务内部已解析路径及有序预期哈希，打包副本与预览不一致就回滚。 - 发布复用 `note × douyin`，确认字幕与使用权后只建自包含包，再到发布中心预览并人工触发 sau。不会自动发布；修改/删除图集不影响已建包。最新全量回归1231通过、1跳过；未调用真实抖音提交。配套文案验收见 `docs/research/2026-10-09-gallery-copy-verification.md`。 ### 转录可靠性与历史修复（2026-10-09） - whisper.cpp 的 `offsets.from/to` 固定毫秒，`start/end` 固定秒；音频实际时长从 WAV 容器读取，默认 `-mc 0` 关闭跨段文字上下文。严重循环、非法时间及越界拒绝作为成功输入；正常强调不去重。规则通过不代表台词准确，原生字幕仍以视频像素为准。 - `GET /api/jobs/:id/raw-transcript` 只读附带 `qualityIssues`，洗稿及自动图集共用检查。`POST /api/jobs/:id/retranscribe` 提供受控修复（作品转录页和图集均有入口），复用安全媒体快照与现有最多三次尝试；不会启动时批量改历史数据。 - 先把旧转录、脚本和洗稿保存为同目录 `.json.before-retranscribe-.json`，再写 `cache/retranscribe/.json` 恢复记录后切换；成功清除下游有效引用并重置为 pending，物理旧成果和已建发布包保留。失败恢复原文件，重启先恢复未完成事务，保留最新垃圾桶状态，提交结束前禁止永久删除。 - `node --import tsx scripts/check-transcript-quality.ts` 只读扫描桌面存储（支持 `--storage=...`、`--self-test`）；`scripts/verify-subtitle-gallery.ts` 默认隔离真实 FFmpeg/API 验收，`--serve` 提供 3183 合成 UI。两者不得静默修复真实数据；合成标记不证明真实字幕语义正确。 ### 热点选题（2026-09-30） - 独立 `/hotspots` 主导航（移动端在「更多」）。首版抖音、头条、百度、知乎、B站热榜；公开请求，不读取用户平台 Cookie。抖音仅用本次匿名会话 Cookie，不落盘。微博公开请求 403，首版不接入；小红书采集、X 与财经行情不在范围内。 - `hotspot-sources.ts` 固定来源 URL，逐源解析/校验 HTTPS 来源域名，最多 100 条；请求 8s 超时、响应 ≤1MiB、禁止重定向。不混算热度，不将获取时间当事件发布时间。格式参考 MIT NewsNow，许可在 `docs/third-party/`，打包包含该目录。 - `HotspotService` 每源 `cache/hotspots/{sourceId}.json`：10 分钟缓存、手动刷新至少间隔 60s（失败也限频），同源并发合并；失败保留旧有效榜单并明确标旧，无数据时显示不可用。服务端下发 `expiresAt`，页面每 30s 仅更新过期标签，没有后台定时抓取。 - 收藏 `cache/hotspot-favorites.json` 只接收服务端缓存中的 sourceId/itemId，保存条目快照；下榜后保留。备注 ≤2000 字符，更新/取消收藏带 version，冲突 409；原子串行写入，不静默覆盖损坏索引。浏览器备注编辑失败保留输入，关闭/离开保护未保存编辑。 - API：`GET /api/hotspots`、`POST /api/hotspots/refresh`、`GET/POST /api/hotspots/favorites`、`PATCH/DELETE /api/hotspots/favorites/:id`；收藏写入复用本机会话。仅选题，不创建视频任务、不生成或发布内容。 - `node --import tsx scripts/verify-hotspots.ts --live` 只读取真实公开来源；不带参数启动 3100 隔离 UI 夹具（首个备注 PATCH 故意 503），退出清理自身临时存储。不要对真实数据跑模拟写入。 - 共用数据路由由 `createAppRouter` 选择：开发 HTTP 使用 BrowserRouter，Electron 打包的 `file:` 使用 HashRouter；保留 `useBlocker` 未保存导航保护，避免文件路径被当作页面路由而 404。 - 热榜采用 CSS 多列（1/2/3 列），卡片不可跨列拆分、按列阅读。不要改回同行等高 grid：知乎长标题会给其它卡片下方制造整行空白。 ### 资料搜索与阅读第一期（2026-10-08） - 热榜与收藏标题打开详情，榜单摘要直接展示；「读取来源／搜索相关报道」才发外部请求。文章的「资料与事实」复用 `ResearchPanel`。话题／问题／搜索摘录不能作为正文证据；正文以纯文本展示，不加载外部图片。 - 共用 `ResearchService` 与 `/api/research/status`、`/search`、`/read`；`POST /api/hotspots/detail` 仅接收缓存／收藏条目身份。直接阅读优先，按需回退 Jina；Exa 仅匿名 `web_search_exa`，SDK 精确锁定 1.32.1，不读个人 MCP 或发布登录态。 - 桌面 `research:{jinaEnabled,exaEnabled}` 复用 userData 配置并即时读取；缺省关闭。独立后端只接受 `RESEARCH_JINA_ENABLED=1`／`RESEARCH_EXA_ENABLED=1`，设置页只显示其状态。开关保存／状态查询不联网探测。 - 搜索 30s／缓存10分钟；单链接直接15s、Jina30s、总50s／快照30分钟；响应2MiB、正文20000字符、失败也限频60s、同操作者最多3并发。快照在内存有界保存，重启／过期／驱逐410，已导入正文持久化在文章中。 - 每批1～3份正文，以 `readId/hash` 服务端解析；创建文章与 `POST /api/articles/:id/sources/import` 原子写入，校验归属、version、重复URL与10份总量，导入使下游失效。未保存文章编辑禁止导入，失败保留选择。 - `research-http.ts` 使用公网DNS绑定与有界原生HTTPS流，禁止重定向；SDK响应桥不使用 `Readable.toWeb`（取消后迟到事件曾导致闭合控制器异常）。不要为了代理环境连通性绕过地址绑定。 - `node --import tsx scripts/verify-content-research.ts` 隔离mock验收；`--serve` 启动3180隔离UI，`--live` 只读真实公开服务。真实Exa三领域查询有结果；本机Jina直连超时，不能宣称全部站点已读通。详见 `docs/research/2026-10-08-content-research-verification.md`。第二／三期尚未实现。 ### 外观主题（2026-09-30） - 右上角常驻 ThemeSwitcher 提供深色/浅色/跟随系统（桌面/移动端共用），立即全局生效；根元素 `data-theme` 驱动唯一 CSS 令牌表和原生 `color-scheme`，不逐页硬编码配色。用户要求直接切换，原「外观」设置分组已移除。媒体标题区使用 70% 黑遮罩与固定浅色 `on-media`，不是会随主题变色的 `ink`。 - 桌面复用配置 `app.theme`，第一次选择后保存 `themeConfigured: true`；旧未启用 theme 字段不改变原有深色外观。浏览器开发态用 localStorage，不请求或保存平台凭据。React 挂载前初始化，跟随系统监听媒体查询；保存失败明确提示本次生效但未保存。 - 浅色主/次/三级文字和状态文字 ≥4.5、交互边界 ≥3；对比度门禁在 `renderer/src/styles/theme.test.ts`。设置分组深链通过 `useSearchParams` 读取，兼容 Electron file/hash URL。 ### 发布中心的「渠道」页签（一级 = 平台，二级 = 内容类型，2026-09-21 改版） - **一级 = 平台**（抖音 / 小红书 / 今日头条 / 微信公众号 / 其它平台＝视频号+B站）； **二级 = 内容类型**（图文 / 视频 / 文章），**只在「该渠道真的出现了多于一种类型」时才渲染**（只含一项＝假选择）。 ⚠️ 改版原因（用户反馈）：原版拿**内容类型**做一级，于是「抖音」在一级界面上根本不存在 （图文与视频被拆进两个页签），而「今日头条文章」这种平台+类型混写的标签又不同构。**别改回内容类型做一级**。 - **纯函数只在 `renderer/src/utils/publishing.ts`**：`PUBLISH_CHANNELS` / `channelTasksOf` / `selectChannelPackages` / `channelContentTypes` / `countChannelPackages` / `countChannelContentTypes` / `countStatusesInChannel` / `contentTypeAfterChannelChange` / `channelEmptyHint`， 各有用例。**没有「包属于哪个渠道」这种单值函数** —— 一个包可同时出现在多个页签（同一份图文发抖音+小红书）， 凡涉及渠道一律按**任务平台**判定。 - ⚠️ **计数只数渠道内的任务**：拿整个包的 `tasks` 去数会让小红书的数字漏进抖音页签 （改版前每包只属一个渠道所以没暴露，现有专门用例守）。 - **状态语义仍然只有服务端一份**：前端只传 `status`，绝不在前端复刻「待处理/资产异常」的判定。 - **渠道维度在前端筛**（服务端 `platform` 是**单值**过滤，表达不了「其它平台」这类多平台页签）： 列表 = 服务端按 `status` 过滤后的结果，再按「渠道平台集 + 子页签内容类型」筛一遍； `contentType` / `platform` 两个查询参数**不再由发布中心下发**（后端字段还在）。 - **计数来自「不带状态筛选」的那次请求**（同时发 `status=all`）：渠道得包数、子页签得各类型包数、 状态页签得**当前渠道内**完整计数。别改回「在已筛选列表上再数一遍」—— 那会让「失败」在「待处理」里恒为 0。 - 渠道 / 内容类型 / 状态**都写进 URL**（`?channel=` / `?contentType=`）且互不冲掉：合并 query（`setView()`）， 别用 `setParams({status})` 整体替换。换渠道时内容类型**收窄到合法范围**（没有就回「全部」），否则会出现 一屏空列表却看不出原因。 - 界面约定：**平台下拉已移除**（一级页签本身就是平台）；每个渠道一行说明（谁在提交、什么前置条件， **视频与「其它平台」必须写明不会自动上传**）；空态给**可照抄的入口**。微信公众号文章只通过官方 API 保存草稿，视频仍是人工交付。 - ⚠️ **渠道映射必须覆盖每一种可创建的「内容类型 × 平台」组合**：视频向导把 `PUBLISHING_PLATFORMS` **全量**列出 （含今日头条、微信公众号），所以「头条视频」「公众号视频」这类包真的存在 —— `contentTypes` 漏一个， 它们就在**所有**页签里都看不见（静默丢数据）。用例 `每一种可创建的「内容类型 × 平台」组合都唯一落在某个渠道里`； `node --import tsx scripts/verify-publishing-channels.ts` 用**真实索引**复核（只读零副作用，末尾报有无包不属于任何页签）。 - 规格与计划：`docs/superpowers/specs/2026-09-18-publishing-channel-tabs-design.md`（含 2026-09-21 改版一节）、 `docs/superpowers/plans/2026-09-18-publishing-channel-tabs.md`。 ### 微信公众号文章草稿（2026-09-29） - 仅 `article × wechat_mp`：封面永久素材 → 可选正文图 → 微信兼容 HTML → `draft/add`。不调用正式发布/群发，不使用浏览器代点发布。 - 复用 `CreateToutiaoArticleDialog`（`platform="wechat_mp"`）、发布包与预览流程。封面单选；`articleImageAssetIds` 为独立的有序正文图片列表，选图归属沿用 AssetStore；作者/摘要与图片顺序进入对应预览指纹。 - 设置「微信公众号」保存 AppID/AppSecret/默认作者；AppSecret 用 safeStorage 加密，不回显。加密/解密失败拒绝保存，避免明文或覆盖丢失。配置即时读取，token 仅本次操作缓存；独立入口使用 `WECHAT_MP_APP_ID` / `WECHAT_MP_APP_SECRET` / `WECHAT_MP_AUTHOR`。 - `POST /api/publishing/wechat/verify`：普通稳定 token + draft/count，只证明连接/查询；不上传内容，但可能触发管理员风险确认。个人未认证订阅号不能仅凭查询成功宣称可写，认证也不保证解决权限问题。 - `task.status` 不变；成功子记录保存 `draftOnly: true` 与 `draftMediaId`，绝不等同正式发布。草稿请求网络失败/异常响应保留 `outcomeUncertain`；成功、不确定或遗留 running 都禁止直接重发。核对后台后确需另建时人工创建新包。 - 当前已通过模拟链路测试，真实账号仍未验收。实测必须覆盖封面+一张正文图，并由用户在后台确认。见 `docs/research/2026-09-29-wechat-draft-feasibility.md` 第 7 节。 ### 公众号对标与文章模板（2026-09-30） - 文章页入口 `/articles/benchmarks`：用户自选领域、读者与关键词，`cache/wechat-benchmarks.json` 原子串行保存；写入带本机会话与 version，冲突 409、损坏索引拒绝覆盖。API `/api/wechat-benchmarks` 的 GET/POST、`/:id` PATCH/DELETE、`/search` POST。 - 搜狗公开搜索仅提供文章/来源账号线索，不带阅读量，不读取用户 Cookie、不绕验证码。固定来源、沿用网页 HTTPS/DNS 固定/15 秒/2MiB 限制；10 分钟内存缓存、至少 60 秒请求间隔。失败保留既有候选，可手动录入；昵称不自动当作已核验身份。 - 每组 ≤10 关键词、≤100 账号，每账号 ≤20 篇样本。身份与赛道由用户核验，阅读量未知为空，数字必须有来源/观察时间；任一样本有下界时中位数保守标下界。服务端判定选中、身份/相关性确认、阅读中位数达到可调门槛（初始 1000）的有效数量；≥10 才能从对标创建文章。参考进入 requirements，不能当作事实来源。 - 现有独立文章工作台增加写作结构与排版选择；`layoutTemplate` 默认为旧样式，切换保留正文但使旧预览失效。少量 MIT 样式在清洗后应用，图片槽位/字数检查不变，归属见 `docs/third-party/wechat-article-editor.md`。旧视频转文章向导仍使用原默认排版。 - 对标表单 sessionStorage 保存未完成编辑和当前组；409 后先载入最新内容对照，再由使用者明确选择继续采用编辑，不能自动覆盖或强制清空。 - `node --import tsx scripts/verify-wechat-benchmarks.ts` 以临时存储启动 3100 夹具，首次保存故意 503；另运行 `node scripts/verify-wechat-benchmarks-ui.mjs` 检查恢复/门槛/模板/窄屏。UI 脚本要求隔离标识，禁止对真实数据模拟写入。`--live [关键词]` 仅请求一次真实公开搜索，不读取账号凭据。 ### 凭据扫描（提交前门禁） - `npm run check` **包含 `check:secrets`**：扫被跟踪与未忽略的新文件，命中「像真凭据」的串就非零退出。 逻辑在 `src/lib/secret-scan.ts`（13 条用例），CLI 是薄封装 `scripts/check-secrets.ts`。 - 为什么有它：2026-09-20 一条「`wx` + 16 位十六进制」的**占位值**触发了 GitHub secret scanning 误报。 误报的代价不只是吓一跳 —— 它会训练人忽略这类告警，所以判断挪到本地提交前。 - **两条口径**：① 「GitHub 也会报」的形态（微信 AppID / `sk-` / `ghp_` / `AKIA` / `AIza` / `xox` / JWT / 私有密钥头）**不看假值白名单**（否则就是「本地放行、GitHub 照报」；想通过就把假值改成可读串）；② 我们自己加的形态（抖音 cookie、 `Bearer`）**要看**白名单与「值像不像真凭据」。 - **测试假值一律一眼可辨**：`test-app-id` / `fake-secret` / `example-token` / `` / `{{token}}`； **别用看起来像真的随机串**。⚠️ **注释里也不要写那个字面量**（扫描看内容，注释照样命中）； 用例里要构造就用 `join`/拼接。 - 确需保留形态时在该行写 `secret-scan:allow` 并说明原因（**优先改名**）。命中真凭据的正确顺序是 **先撤销/轮换、再改代码**（只删字符串没用，历史里还在）。上报一律**打码**（`wxa1…0718`）。 ### 侧栏可折叠 - 桌面端左侧主导航可展开/收起，收起为纯图标、展开显示导航文字；选择存 localStorage（`douyin-ai-video.rail-expanded`）。 - 侧栏宽度只有一个真源：`AppShell` 根节点声明的 CSS 变量 `--rail-w`（收起 `md:56px` / `xl:64px`，展开 `208px`），由侧栏、内容区与两个顶栏变体共同消费 —— **不要在别处再写死 56px/64px 偏移**。 - 折叠开关固定在侧栏**底部**且两个状态都可见。早期版本把它做成「整个 logo 行」，导致收起态与改造前毫无差别、用户找不到入口（已按实测反馈修正）。 ### 抖音图文自动发布（外部 sau 引擎） - 只做**抖音图文**（`sau douyin upload-note`）；视频与其它平台仍是人工交付。 - 引擎是外部依赖、**不内置**（自装 `social-auto-upload`，约 970MB）。三个实测坑：① 按其官方步骤装完 CLI 起不来 （`pyproject.toml` 只声明 `patchright`，但仍有 7 个 uploader 与 `myUtils` 在 `import playwright`，需手动 `uv pip install playwright`）；② `requires-python = ">=3.10,<3.13"`（3.13 要另装 3.12）； ③ 仓库+venv 约 440MB、patchright chromium 约 520MB。另：上游 `uploader/__init__.py` 在 **import 阶段**就 `mkdir /cookies`，所以该目录必须可写。 - **`task.status` 全程不变**：`autoPublish` 只是任务上的子记录，`succeeded` 的语义是**已提交**，绝不写 `published` —— 是否真发出去由人工点「标记已发布」确认。**这是本功能最关键的不变式。** - **一次只允许一个**：运行中/等验证码时再触发 409；遗留 `running` 超过 30 分钟视为「进程已死」允许重试。 - **不自动重试**：失败后必须人工再点（人知道上一次到底发出去没有）。 - **「发布前必经预览」是服务端约束**：`auto-publish` 必须带 `previewRevision`（图文包覆盖有序 `imagePaths` 与 `noteCopy`），缺失 400、不一致 409，两种情况都**不产生** `autoPublish` 记录。 - 图文包的 `video*` 字段「不适用」，其中 `videoSha256` 承载**图片清单哈希**（各图 sha256 有序拼接再哈希）作为 等价完整性凭据；`PublishAssetHealth` 的 `missing_images` 由它判定。 - ⚠️ **验证码通路对图文不通**（从上游源码实测更正）：`verify_code.txt` 只有上游**视频**通路会读；`upload-note` 既不读它、发布循环也没有次数上限 ⇒ 图文遇到短信挑战的真实结局是「循环到超时（900s）→ `failed`」， `awaiting_code` 在图文通路**不可达**，写验证码文件**没有效果**。界面必须让操作者知道：卡住的正确动作是 **去抖音后台核实**，且重试前先确认上一次是否已发出（上游会 `force=True` 重复点击发布，**重复发布是最大风险**）。 - **我们对上游打了 1 个本地补丁**（见 `docs/patches/`）：抖音把图文发布页标题框 placeholder 从「填写作品标题」 改成「添加作品标题」，上游仍按旧文案匹配 → 图文发布稳定 120s 超时；补丁只把匹配放宽成 `作品标题`。 ⚠️ **上游 `git pull` 会覆盖它，升级后必须重新 `git apply`。** - 媒体元素（``/`