# VideoCut

**Repository Path**: txshare/video-cut

## Basic Information

- **Project Name**: VideoCut
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VideoCut · 直播切片工场

订阅直播 → 按时间段值守录制 → AI 分析与切片 → 预览挑选 → 发布或下载。

支持已知直播间直接订阅，以及通过 Bragi 无头浏览器和大模型查找直播间。AI 统一使用 ai-module，支持 Claude、ChatGPT / Codex、OpenCode。**抖音内置 StreamGet 直播源解析和 FFmpeg 录制；视频发布统一使用 MediaPublishPlatform，无需配置各平台的命令模板。**

## 部署、启动和更新

### 1. 创建并激活 Python 虚拟环境

推荐安装 **Python 3.11**，安装时启用 Python Launcher（`py`）；ChatGPT 和 OpenCode 要求 Python 3.11+。在项目根目录（包含 `app.py`、`deploy.ps1` 的目录）打开 **PowerShell**，复制下面整段执行。已有 `.venv` 时直接复用：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
if (-not (Test-Path -LiteralPath .\.venv\Scripts\python.exe)) {
    py -3.11 -m venv .venv
    if ($LASTEXITCODE -ne 0) { throw 'Virtual environment creation failed.' }
}
.\.venv\Scripts\Activate.ps1
python -c "import sys; assert sys.prefix != sys.base_prefix, 'Virtual environment is not active'; print(sys.executable)"
```

`python -m venv .venv` 的作用是在项目内建立独立的 Python 环境；`Activate.ps1` 将当前窗口的 `python`、`pip` 等命令切换到该环境。上面的执行策略只影响当前 PowerShell 窗口，无需管理员权限。最后一行应输出本项目 `.venv` 中的 Python 路径。

**下文所有 PowerShell 命令都在项目根目录、已激活的虚拟环境中运行**，围栏中不含终端提示符或待替换的路径。新开窗口后先重新激活，无需重复创建：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\.venv\Scripts\Activate.ps1
```

### 2. 安装依赖和运行工具

推荐执行完整部署，包含统一发布组件；首次安装需要联网下载依赖与 Chromium，可能耗时数分钟：

```powershell
.\deploy.ps1 -Publish
```

部署会安装核心依赖、本项目 `vendor/ai-module`、Claude Agent SDK 及其 CLI、Streamlink、Playwright、Chromium、StreamGet、faster-whisper，并实际检测 AI 组件、抖音签名和 FFmpeg。缺少 Node.js 时自动安装到项目 `tools/node/`。FFmpeg 优先使用 `tools/ffmpeg.exe`，其次查找 PATH 或 imageio-ffmpeg 自带的可执行文件。

`-Publish` 下载固定版本的 MediaPublishPlatform 登录、上传后端，保留其许可证，并在 `tools/media-publish-platform/` 建立独立环境及 Chromium，避免与本项目浏览器依赖冲突。不需要另开 MPP 服务或安装其前端；发布账号需在系统页人工登录。发布组件也能在界面安装或修复。

需要 ChatGPT / Codex 和 OpenCode 时，再安装两个引擎的 CLI；安装完成后在系统页选择引擎并配置账号或接口：

```powershell
.\deploy.ps1 -AIProvider all
```

CLI 安装在本项目 `tools/ai-cli/`，不依赖全局 npm 安装。仅需单个引擎时，`-AIProvider` 可选 `chatgpt` 或 `opencode`；默认只检查核心依赖自带的 Claude。OpenCode 固定使用当前 ai-module 已验证的 1.18.18。

额外安装中文识别引擎的完整依赖（FunASR、Torch、Torchaudio）：

```powershell
.\deploy.ps1 -ASR
```

已有环境中，仅重新安装 Python 依赖：

```powershell
python -m pip install -r requirements.txt
if ($LASTEXITCODE -ne 0) { throw 'Dependency installation failed.' }
```

`requirements.txt` 使用 ASCII 注释，兼容按 GBK 读取文件的旧版 pip。仅安装 requirements 不会安装 Node.js 或 Chromium；首次使用请执行上面的部署命令。语音模型权重在首次识别时另行下载。

仅修复本项目的浏览器，或单独安装 / 修复统一发布组件，分别执行：

```powershell
python -m playwright install chromium
if ($LASTEXITCODE -ne 0) { throw 'Chromium installation failed.' }
```

```powershell
python -m videocut.publishing.mpp_runtime install
```

### 3. 启动和更新

完成安装后，单独执行启动命令：

```powershell
python app.py
```

浏览器打开 [VideoCut 本机界面](http://127.0.0.1:5000)。保持终端、应用和电脑运行，预约才会执行；电脑休眠期间无法值守。启动命令持续运行是正常现象，需要执行其他命令时打开另一个 PowerShell 窗口并激活环境。

**更新代码或依赖后**：先停止录制并等待收尾，在终端按 Ctrl+C，按需重新部署，再运行 `python app.py`。浏览器按 Ctrl+F5，加载更新后的脚本。网页保存的系统配置通常立即生效，无需重启；直接修改 `config.json` 后需要重启。退出虚拟环境可执行 `deactivate`，这不会删除环境。

后台启动的实例会将 PID 与日志路径记录到 `data/tmp/service_current.json`。重启前先停止录制并等待收尾，核实该 PID 仍是本项目的 `app.py` 后结束旧进程树，再启动新实例；同一数据目录只运行一个实例。

## Android App

手机界面使用“流水线、订阅、片段、投放、更多”五个入口；直播间、系统、执行会话和账号管理从“更多”进入。窄屏任务与订阅按纵向信息组展示，投放页显示所选账号数量，设置按分区展开。Android 在宽窗口改用侧边导航，并跟随系统字体缩放。界面规范见 `DESIGN.md`。更新模板后由开发者手动重启服务并刷新页面。

Android 客户端位于 `android/`，支持流水线、订阅及时间表、直播、片段库、投放记录、系统设置和 AI 会话。客户端使用原生连接界面、导航、全屏播放及文件保存，业务页面复用本项目并适配手机。**手机连接现有 VideoCut 服务；录制、识别、剪辑和平台上传均在服务端运行，关闭手机 App 不会停止后台队列。** 要求 Android 8.0 及以上、可更新的 Android System WebView。

### 手机发布与服务端账号投放

- Android 1.3.0 起，片段详情提供“选择手机 App 发布”。客户端下载完整视频后，通过开源 [AndroidX FileProvider](https://github.com/androidx/androidx/blob/androidx-main/core/core/src/main/java/androidx/core/content/FileProvider.java) 和 Android 系统分享面板交给支持接收视频的已安装 App。请在平台 App 内确认当前账号、编辑内容并点击发布；平台对系统分享视频的支持以实际安装版本为准。此入口只交接视频，**不会把打开分享面板视为发布成功，也不会伪造平台、账号或回执**。
- “服务端账号投放”继续使用 MediaPublishPlatform。必须先在系统页输入账号名称并完成平台登录；登录窗口出现在运行服务的电脑。手机已登录抖音等 App，并不代表服务器已有对应账号。没有账号时页面会给出配置入口和“刷新账号”，投放按钮暂不可用。
- 服务端任务失败后进入 pending，由用户核实平台后台后手动运行。发布组件会保留实际失败原因；浏览器临时文件放在配置的数据目录 `publishing/mpp/tmp/`，避免默认系统临时盘已满导致浏览器启动失败。
- [抖音官方 Android SDK](https://open.douyin.com/platform/resource/docs/develop/share/android) 可对接抖音发布页，但需要开放平台登记应用、申请权限和配置签名。GitHub 上的 [TikTok OpenSDK](https://github.com/tiktok/tiktok-opensdk-android) 适用于 TikTok，不等于国内抖音；[ShareSDK 示例](https://github.com/MobClub/ShareSDK-for-Android) 也不能替代各平台授权。当前手机入口采用 Android 系统分享，不宣称获得跨平台自动投稿能力。

直播间会区分排队、录制、封档和中断；过期检测结果会显示“状态未知”，可点击“立即检测”确认。录制进程退出后撤销旧的“直播中”缓存。直播流持续无新数据默认 120 秒后停止并封档，任务留待手动检查；可在系统“录制归档与处理流水线”中调整无数据超时。

Android 源码、资源、Manifest 和可复现构建所需的 Gradle 脚本纳入版本管理；编译产物、IDE/Gradle 缓存、`local.properties`、本机配置、签名私钥及密码排除。已有发布身份需按下文备份和恢复签名文件。

### 服务账号与手机连接

新版 App 只填写服务端地址和端口，例如 `https://你的服务域名:8445`，然后在 VideoCut 页面注册或登录，不填写连接密钥，也不登录基础设施。

首次部署，在运行服务的电脑浏览器打开 `http://127.0.0.1:5000/account/register` 创建管理员。必须直接从本机访问，公开端口注册不能取得管理员权限。手机注册的账号等待批准，管理员在“服务账号”（`/account/users`）批准或停用。已批准账号共享当前 VideoCut 工作区，包括视频、系统配置及投放账号，应仅批准可信人员。管理员账号只能从本机初次创建；停用普通账号会立即撤销已有会话。用户可修改密码、退出登录，改密码会撤销其他会话。

中继管理中先保持原保护方式，部署业务服务和新版 App 后，将 VideoCut 那一行的“登录认证”切换为“应用自行注册登录（透明转发）”再保存。其他没有业务认证的服务不要切换。服务可以继续只监听 127.0.0.1；来自转发连接的请求仍必须验证账号，不能因为 Agent 在本机就跳过验证。

账号密码以加盐摘要保存；会话签名密钥保存在 `data/mobile/session-secret`，保留该文件可跨服务重启保持会话。旧版业务连接密钥入口已移除。下面的构建结果需覆盖安装。

### 编译和安装

安装 Android Studio，并在 SDK Manager 中安装 **Android SDK Platform 35、Build Tools 35.0.0**；使用 JDK 17 或以上。构建脚本优先使用 Android Studio 自带 JDK，或 `JAVA_HOME`、PATH 中的 JDK。SDK 通过 `ANDROID_HOME`、`ANDROID_SDK_ROOT` 或 Android Studio 默认目录定位。之后在项目根目录执行：

```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass -Force
.\android\build.ps1
if ($LASTEXITCODE -ne 0) { throw 'Android build failed.' }
```

首次构建需联网下载 Gradle 及 Android 构建插件，不需要安装 Node.js 或额外 App 框架。SDK/JDK 使用自定义目录时，可通过以下整段命令交互选择，避免复制无效的示例路径：

```powershell
$androidSdkPath = Read-Host 'Android SDK directory'
$androidJavaPath = Read-Host 'JDK 17+ directory'
.\android\build.ps1 -SdkPath $androidSdkPath -JavaHome $androidJavaPath
if ($LASTEXITCODE -ne 0) { throw 'Android build failed.' }
```

脚本默认构建**已签名的 Release 版本**，也可显式使用 `-Release`。可安装 APK 输出为 `android/app/build/outputs/apk/release/app-release.apk`，传到手机后安装，首次需允许文件来源安装。Release 关闭应用和 WebView 调试。此前安装过 Debug 版时，因签名不同，需先卸载 Debug 版，再安装 Release 并重新输入连接信息。

首次构建会生成本项目专用的 Release 密钥，保存在 `android/signing/videocut-release.p12`，配套密码和别名在同目录 `keystore.properties`。**请安全备份整个 `android/signing/` 目录**，后续更新必须复用该密钥；签名目录、APK、Gradle 缓存及本机 SDK 路径均不进入版本管理。`android/release-certificate.sha256` 是可以提交的公开证书指纹，用于防止误换签名。换电脑后构建 Release 前先恢复签名目录；缺失已有签名时脚本会报错，不会重新生成替代密钥。[Android 签名说明](https://developer.android.com/studio/publish/app-signing)

需要调试或执行通过 WebView 调试接口的 Android 自动化验证时，单独构建 Debug：

```powershell
.\android\build.ps1 -Debug
if ($LASTEXITCODE -ne 0) { throw 'Android debug build failed.' }
```

Debug APK 输出为 `android/app/build/outputs/apk/debug/app-debug.apk`，使用独立的开发签名。

### 从手机直接投放

1. 服务端电脑的“系统设置 → 统一发布”安装 MediaPublishPlatform，为需要的平台分别登录账号。扫码、验证码和登录窗口在服务端电脑完成，手机复用这些账号。
2. 手机进入片段库，打开已生成的片段，填写标题和正文，勾选一个或多个“平台 · 账号”，点击“直接投放到所选账号”。可选竖版，竖版生成在后台执行。
3. 每个账号独立排队、执行和保留结果；同一账号串行，不同账号受系统共享并发数控制。页面显示“已接收”只表示任务已创建，确认上传后才显示“已投放”。平台审核、最终可见性以平台后台为准。
4. 片段详情、片段库及“投放记录”均显示成功平台和账号；投放记录可按平台、状态筛选，查看错误、平台回执（平台提供时）及执行会话。失败和停止任务保留，点击“运行原任务”重试前先核实平台是否已经提交，避免重复发布。网络重试使用同一请求编号，不会重复创建任务。

账号名称在创建任务时保存，之后改名不会篡改历史。旧版未保存账号的记录标为“历史记录未保存账号”，不会猜测归属。

## 项目目录与测试

根目录的 Python 文件只保留 Web 入口 `app.py`。部署、依赖、配置及说明仍在根目录；业务模块、公共工具和测试分别归档：

```text
app.py                   Web 入口与路由
videocut/
  config.py / db.py       配置与数据库
  jobs.py                后台调度与任务队列
  ai/                    模型调用、会话日志、原生会话浏览器工具、Bragi 计划
  subscriptions/         订阅查找与时间表
  recording/             平台检测、直播录制、抖音工作进程
  processing/            音频识别、AI 分析、剪辑流水线
  publishing/            发布适配
  system/                配置管理、组件检测、后台测试
  web/                   仪表盘视图数据
utils/                   进程控制、Windows Job、媒体工具、通知、文件与路径工具
test/                    自动测试（test_*.py）
  manual/                手动诊断和浏览器验证
templates/ / static/     网页模板与静态资源
android/                 Android 客户端、Gradle Wrapper 和构建脚本
actions/ / vendor/       浏览器动作及第三方模块
tools/                   部署安装的本地运行组件
data/ / config.json      本机数据与配置
```

在项目根目录运行全部自动测试，限定 `test/`，避免扫描第三方模块：

```powershell
python -m unittest discover -s test -t . -p "test_*.py" -v
```

只运行一个测试模块：

```powershell
python -m unittest test.test_ai_sessions -v
```

用隔离数据验证订阅布局、Markdown 工具结果和流水线节点，不调用真实 AI 或平台账号：

```powershell
python -m test.manual.verify_subscriptions_layout
if ($LASTEXITCODE -ne 0) { throw 'Subscription UI verification failed.' }
python -m test.manual.verify_ai_tool_markdown
if ($LASTEXITCODE -ne 0) { throw 'Markdown UI verification failed.' }
python -m test.manual.verify_dashboard_nodes
if ($LASTEXITCODE -ne 0) { throw 'Dashboard UI verification failed.' }
python -m test.manual.verify_system_settings
if ($LASTEXITCODE -ne 0) { throw 'System settings UI verification failed.' }
python -m test.manual.verify_android_publishing
if ($LASTEXITCODE -ne 0) { throw 'Mobile publishing UI verification failed.' }
```

以下单独测试会**真实调用当前配置的模型，可能产生费用**，通过本地测试页面验证 ai-module 与 Bragi 工具链：

```powershell
python -m test.manual.verify_native_ai
```

AI、ASR、抖音子进程统一通过 `python -m videocut.…` 启动，内部命令显式使用项目根目录，迁移不改变 `config.json`、`data/`、`tools/` 的位置。部署和启动命令保持不变。旧进程加载的是旧模块路径，更新后由开发者停止旧实例并重新启动，再在浏览器按 Ctrl+F5。

## 首次配置与独立测试

进入顶部“系统”，按实际需求配置：

| 配置项 | 关键操作 |
|---|---|
| AI 引擎 · ai-module | 选择 Claude、ChatGPT / Codex 或 OpenCode，分别配置接口、密钥和模型；测试当前所选引擎后保存 |
| 语音识别 | 默认 auto，未安装 FunASR 时使用 faster-whisper；可选模型、CPU线程数和解码候选数，首次转写可能下载模型 |
| 录制归档与处理流水线 | 默认每30分钟归档，分析与发布共用5个处理槽位；可独立配置值守、录制上限及 FFmpeg 线程数 |
| 抖音内置录制 | 设置原画/超清/高清/标清/流畅及解析超时；可用具体房间链接独立测试 |
| 直播间查找 · ai-module | 操作步数不限，可设置总时限，默认900秒；独立测试与保存 |
| 监测预约 | 设置轮询间隔及新增订阅的默认提前量；具体时间段在订阅中设置 |
| 切片与字幕 | 设置片段时长、字幕、视频编码器、CPU 编码档位和质量；可实际检测硬件编码 |
| 目录与保留 | 设置外部录像目录和原始录像保留天数；0 表示永久保留 |
| 代理 | 显式填写项目使用的代理，需要时测试当前地址 |
| 通知 | 填 ntfy 地址；“发送测试通知”会实际推送消息 |
| 统一发布 · MediaPublishPlatform | 安装组件并检测浏览器；打开平台登录窗口，选择账号、保存并独立验证 |

每组都能独立测试和保存，也可展开“完整 JSON 配置（高级编辑）”一次性编辑。两种方式共用校验；分项保存不会覆盖其他组。API Key 留空保留已有密钥，勾选“清除已有密钥”才删除。

直播间 Agent 不限制浏览器操作步数或 SDK 会话轮数。旧配置中的 `crawler_max_steps`（如24）会忽略，新的任务参数不再发送 `max_steps`；日志仅记录已执行到第几步。任务仍遵守配置的总时限，也可手动暂停。

**测试当前输入不会自动保存，已保存也不等于测试通过。** “全部只读检测”逐项检查，不投稿、不发送通知，但会真实调用已配置的大模型，可能产生接口费用。

检测结果的边界：

- AI 引擎通过：ai-module 完整结束并返回有效最终文本；思考、中间流、取消和不完整输出不算通过。
- ASR 通过：依赖可以加载，尚未验证模型下载和实际转录。
- 发布组件：实际加载登录与上传模块、启动 Chromium；平台账号测试会访问平台检查登录状态，不会投稿。
- “未启用 / 待配置”“待进一步验证”需要根据提示处理，不能视为全部通过。

测试在后台执行，显示状态和已用时间，可继续操作其他页面。添加前的订阅测试与系统测试限制同时运行的数量，重复提交相同的运行中测试会复用任务，其他测试会提示等待。后台状态轮询不反复执行模型调用。切换页面不会取消已启动的测试，可通过本次 AI 日志查看过程。

### ai-module 配置和迁移

模块源码位于 `vendor/ai-module/`，部署不依赖另一份 leap-share2，也不会复制那个项目的数据库、登录态或密钥文件。模型测试、直播查找和内容分析统一使用模块原生的 Claude、ChatGPT、OpenCode 适配器。

1. 在“系统 → AI 引擎”选择 Claude、ChatGPT / Codex 或 OpenCode。各引擎分别保存接口、密钥、模型和 CLI 路径，切换选择不会覆盖其他引擎的配置。旧 Claude 配置会保留。
2. Claude 默认沿用同一 Windows 用户的本机 CLI 账号、接口和模型；也可取消“沿用本机”，填写独立的 Anthropic 兼容接口、密钥和模型。不能将 `/chat/completions` 地址填写为 Claude 的接口基址。
3. ChatGPT 使用 ai-module 的 Codex app-server 适配器，可沿用已有 Codex 登录和配置，也可独立填写 OpenAI 兼容接口、密钥、模型。未安装 CLI 时，可在当前引擎下面点击“安装 / 修复”，或使用部署脚本的 `-AIProvider chatgpt`。官方账号首次登录使用已安装的 Codex CLI；无需手工安装另一个 Python SDK。
4. OpenCode 使用原生适配器与独立供应商配置。模型格式为 `供应商ID/模型ID`；可填写 OpenAI 兼容接口和密钥，也可在高级 JSON 的 `providers` 中设置其他原生供应商。CLI 安装按钮与 `-AIProvider opencode` 都安装已验证版本 1.18.18。高级供应商配置包含的密钥也应妥善保管。
5. 点击“测试验证”测试**当前所选引擎**，查看最终回复和执行会话，通过后保存。更换引擎影响后续启动的任务，已运行任务仍使用启动时的配置。
6. 设置单次调用超时（1—1800 秒，默认 180）。系统测试和切片遵守该设置；持续爬虫会话使用独立的 Agent 总时限。超时会终止本次工作进程及其 CLI 子进程，测试在后台执行，可继续操作页面。

检查组件和登录命令：

```powershell
python -m videocut.ai.ai_worker --check claude
```

需要使用 Claude 官方账号登录时，单独执行以下交互命令；使用独立接口密钥时直接在系统页配置即可：

```powershell
$claudeCli = python -c "from videocut.ai.ai_worker import cli_path; print(cli_path())"
if ($LASTEXITCODE -ne 0) { throw 'Claude CLI was not found.' }
& $claudeCli auth login
```

ChatGPT / Codex CLI 安装后，需要使用官方账号登录时单独执行（已登录或使用独立密钥时可跳过）：

```powershell
python -m videocut.ai.runtime_tools login chatgpt
```

独立配置调用、爬虫查找和 AI 切片都走同一个模块入口。调用日志包含 native 会话、状态、思考、最终文本与用量；高频思考计数合并记录。每次调用使用临时工作区；Claude 单独继承认证、接口和模型路由，隔离插件市场与用户钩子。ChatGPT 和 OpenCode 使用 ai-module 各自的原生配置与权限策略。数据分析直接返回结果；网页操作由注册的 Bragi 工具执行。

## 添加订阅、登录与测试

### 选择订阅方式

进入“订阅管理”：

| 方式 | 填什么 | 适用情况 |
|---|---|---|
| 直接链接 · 已知直播间 | 完整直播间链接 | 已经知道房间地址，无需 LLM 查找 |
| AI 爬虫 · 查找直播间 | 入口页面链接和查找提示词 | 只知道网站入口或主播，需要自动搜索和进入直播间 |

平台可自动识别，也可手动选择；主播名可选。两种方式共用时间段、登录和测试功能。

AI 示例：入口填 `https://live.douyin.com/`，提示词填“主播叫小七说事”。需要先在系统页启用 ai-module 并测试通过；网站可能要求登录或验证，主播未开播时也可能没有匹配结果。

查找直接使用 `ai_module.run_ai` 的原生持续会话。通过模块的 Actions MCP 注册表挂接 `bragi`、`browser_snapshot`、`browser_navigate`、`browser_evaluate`，四个工具共用同一个无头浏览器和订阅的登录状态。搜索、定位、条件判断、路线选择与错误重试均由 ai-module 完成。本项目不再实现搜索调度循环、主播/人数提示词正则解析或专用的完成/停止工具。操作步数和 SDK 轮数不限，总时限默认900秒，可在系统页设置。

无头查找限制并发，阻止持续加载的视频资源，保留正常页面、图片、字体与网络请求。页面结构、工具结果和完整提示词发送给所配置的模型。模型使用真实浏览器工具判断用户目标，最终返回当前房间 URL 和页面证据；应用检查结果格式及 URL 与实际浏览器页面是否一致，然后保存 XML。工具适配只负责浏览器线程、资源和调用，不决定搜索策略。

### 需要登录时，先打开可见窗口

**“测试验证”使用无头浏览器，不会自动弹出登录页面。无需先添加订阅，直接按以下步骤登录：**

1. 在添加表单中填好页面链接，点链接下方的“打开登录窗口”。
2. 在**运行 VideoCut 的电脑桌面**找到新打开的浏览器窗口，可查看任务栏。
3. 在这个窗口中扫码、登录或完成验证。没有出现二维码时，手动点网站里的“登录”。
4. 返回 VideoCut，等“保存登录状态”可用后点击保存；窗口就绪后有 5 分钟操作时间。
5. 看到保存成功后，再点“测试验证”。保存了状态文件，不等于网站已经确认登录有效。

这是独立的浏览器会话，日常浏览器中已有的登录不会自动共享。窗口打开期间，先保存或关闭窗口，再添加或测试。

远程访问时，窗口出现在服务端电脑，不会出现在访问网页的手机或另一台电脑上。无交互桌面的 Windows 服务无法完成可见登录，应在电脑桌面的 PowerShell 中启动应用。

添加前的登录状态按站点保存，添加成功后复制为该订阅的独立状态。已有订阅登录过期时，在对应行重新“打开登录窗口”并保存；新草稿的登录不会覆盖已有订阅的独立状态。

无头浏览器启动时，会话会记录“已加载保存的浏览器状态”或“没有可复用的浏览器状态”。前者仅表示状态已加载；如果网站仍显示登录或滑块验证，应在同一订阅重新打开登录窗口、完成人工操作并保存，再点“重新探索”。

### 验证后添加，添加后也可验证

1. 填链接；AI 方式还需填提示词，需要时先登录。
2. 点“添加订阅”旁的“测试验证”，查看结果及“查看本次 AI 日志”。
3. 用“设置时间段”设置预约，确认后点“添加订阅”。
4. 添加成功后，在该订阅行仍可“测试验证”、登录、调整时间段和启停值守。

测试忽略时间表，不创建订阅、不启动录制。结果区分找到直播间、是否开播和录制支持情况，不能仅凭“找到链接”判断全流程通过。

### 成功后保存 Bragi XML，失效后自动重建

1. AI 方式“测试验证”成功后，自动生成 Bragi XML，结果旁可点“查看 XML”。已有订阅行也提供入口；链接后加 `?download=1` 可下载。
2. XML 保存已验证直播间的稳定打开路径，不重复保存易过期的搜索框选择器。对应 JSON 保存来源和提示词指纹、核验证据与文件校验值。
3. 下次测试或预约监测优先执行 XML，对比当前地址与原生会话保存的页面证据；一致时不调用模型。
4. XML 无法执行、跳转变化或已保存的页面证据变化时，在**同一次任务**中调用 ai-module 原生会话重新确认或查找，成功后更新 XML。
5. “重新探索”主动跳过缓存。如果定时查找或上次测试还在运行，会接管并停止旧的查找进程，再执行新的探索；重复点击复用同一测试任务，旧结果不会覆盖新结果。后台监测在手动任务期间暂停该订阅的重复查找，页面显示实际查找进度。
6. 草稿测试生成的 XML 在添加订阅时复制给该订阅，后续独立维护；来源或提示词指纹不符时不复用旧配置。登录窗口需先保存或关闭后再重新探索。

配置位于 `data/bragi/draft_<指纹>.xml/.json` 或 `data/bragi/sub_<订阅编号>.xml/.json`，备份时保留配套文件。XML 负责导航，目标条件由 ai-module 判断，登录状态仍独立保存在 `data/browser/`。旧版自建 Agent 的缓存文件会保留，但不自动复用；需经原生会话重新确认后生成第2版配置。AI 关闭时有效的第2版 XML 仍可执行；失效后需要重新启用 AI。

### 草稿自动缓存

添加表单会缓存链接、提示词、平台、主播名、已确认的时间段、提前量和常开值守选项。切换页面、刷新或重新打开后会恢复。

- 缓存限同一浏览器、同一访问地址和端口；`localhost` 与 `127.0.0.1` 不共享缓存。
- 添加失败保留草稿；添加成功自动清空，也可点“清空草稿”。
- 时间段对话框内未确认或已取消的修改不会写入草稿。
- 清空草稿不会删除已有订阅或网站登录状态。

## 时间段对话框

新增和已有订阅均点“设置时间段”，在一个对话框中完成全部设置：

1. 选择“一次性”“每天”或“每周”；一次性选择日期，每周选择对应星期行。
2. 在时间轴空白处，从开始时间拖到结束时间，创建一个区间。
3. 再次在空白处拖动，继续增加区间；**同一天可以有多个时段**。
4. 拖动区间中部移动，拖动两端调整；点击区间或下方列表，可精确输入到分钟或“删除区间”。
5. 设置“提前…分钟进入”；新订阅点“完成设置”，已有订阅点“保存并应用”。

例如：每天 09:00—11:00、14:30—16:00，选择“每天”后拖出两段即可。只在每周三晚直播，选择“每周”，在周三行添加区间。临时直播则选“一次性”并指定日期。

拖动按 15 分钟吸附，精确输入支持分钟。支持一次性、每天、每周混合；跨午夜可设置“次日结束”，重复时段的结束时间早于开始时间时表示次日结束。一次性也可精确调整跨日期范围。取消不改变原设置。

- 选择“7×24 常开值守”后，持续值守，不受预约区间限制。
- 提前量对每段生效；进入提前窗口即可查找、检测，若已开播，也可能提前开始录制。
- 重叠时段连续录制；所有有效窗口结束后停止，响应精度取决于监测轮询间隔。
- 时间统一采用运行应用的电脑本地时间和时区。

## 录制、分析与外部录像

已启用的订阅在有效时间段内轮询，检测到开播后自动录制。在“直播间”查看状态和画面；需要时点“停止”，等待录像收尾并进入分析队列。若要停止后续自动值守，还需停用该订阅，否则有效时间段内仍可能再次录制。

### 连续归档与并行音频流水线

内置录制保持同一条直播流，默认每30分钟封存一个 TS 文件。分段在下一个可用关键帧结束，可能略晚于30分钟；停止时保存最后不足30分钟的一段。每段独立入库，归档一完成就排队分析，后面的直播继续录制。短于最短片段时长的尾段保留原文件并标记，不生成虚假精彩片段。

处理顺序是：语音处理（FFmpeg 提取16kHz单声道 WAV，接着 ASR 生成带时间戳的转写）→ ai-module 按真实讲话选精彩区间、生成吸引人的标题和内容引导 → FFmpeg 按秒剪辑、字幕和封面 → 片段库。音频提取与转写是同一个任务，连续占用一个处理槽位，中间不重新排队，完成后进入 AI 选段队列。标题和引导要求与实际内容对应。分析、剪辑和发布共用默认 **5 个处理槽位**；订阅检测与录制分别独立运行，默认并发上限各为 5。

选段参考 [FunClip](https://github.com/modelscope/FunClip) 的转写文本驱动方式：给实际转写段编号，由 ai-module 返回起止段编号，再按原始时间戳确定剪辑边界。FunASR 请求句级时间戳；旧版模型返回的秒数会扩展到它覆盖的完整转写段。应用复核时长、编号及重叠区间，标题和内容引导随片段保存；已有分析缓存和成功片段仍按原记录复用。

开启烧录字幕时，先生成以片段起点为零的 SRT，再由 FFmpeg 一次完成精确裁剪和字幕合成，每个片段只编码一次。可单独下载 SRT，关闭烧录时仍生成字幕文件。中文及特殊字符路径通过独立工作目录处理；渲染成功后才原子替换成片，失败或停止清理临时文件，保留先前成片。完成合成和封面后才显示到片段库。该优化减少重复视频编码，语音转写的耗时仍由所选 ASR 引擎和硬件决定。

**剪辑速度与硬件编码**：在“系统 → 切片与字幕”选择编码器，默认 `auto`。程序会实际编码几帧，检测 AMD AMF、NVIDIA NVENC、Intel Quick Sync；发现可用设备就使用硬件编码，均不可用时才选择 CPU / x264。仅在 FFmpeg 编码器列表中出现名称不算检测通过。人工指定某个硬件时，设备不可用会报错；实际剪辑失败仍进入 pending，不会自动再跑一遍 CPU 编码。

硬件模式保留原分辨率、精确剪辑边界和烧录字幕。CPU 速度档位默认 `veryfast`，可改 `superfast` / `ultrafast`；更快的档位通常产生更大的文件。编码质量默认22，数值越低画质越高，但不同编码器的同一数字不代表完全相同的画质或码率。`ffmpeg_threads` 同时限制本次剪辑的解码、滤镜及软件编码线程，避免多个任务各自开满 CPU。竖版生成也使用所选编码器。

本次执行会话记录实际编码器、片段起止时间、字幕状态、耗时及处理倍速。例如速度 `2x` 表示每秒处理约2秒的片段视频；应按选出片段的总时长评估，不能用整场录像时长代替。剪辑进度会计入正在生成的片段，不再等整个片段结束才跳动。编码参数修改影响下一次启动的编码，已经完成的片段继续复用；代码更新后由开发者重新启动服务。

首页可直接设置处理并发数，系统页及完整 JSON 也可设置处理、订阅检测和录制上限（各 1—32）。系统页可设置归档长度（1—1440分钟）、每个 FFmpeg 的线程数（1—16）以及语音引擎/模型。归档长度对新启动的录制生效；并发数调整影响后续领取的任务，降低上限不会打断正在执行的任务。

仪表盘和片段库显示排队、语音处理、AI选段、剪辑和失败原因，并自动刷新；语音处理详情区分正在提取音频或转写，合并进度的前10%用于提取、后90%用于转写。**成片生成后才进入片段库**。卡片和详情展示标题与内容引导，发布简介默认使用内容引导。处理失败可点“重试”，已有音频、转写和AI选段会复用，已成功的片段不会重复生成。旧版单独转写的任务会归入语音处理节点，仍可运行或暂停。

语音转写较慢时，在系统页“语音识别”查看 Whisper 模型、CPU线程数与解码候选数。当前 Whisper 后端在本地 CPU 使用 int8，默认 small、4线程、5候选；此前写死的2线程限制已移除。单任务可尝试4—8线程；多个转写任务会分别占用这些线程，不宜同时把任务并发和线程数调高。将候选数调为1或选更轻量的 base 可以偏向速度，但可能降低识别准确率，默认保持原来的 small/5候选。参数对新启动的转写子进程生效，正在执行的任务沿用启动时配置。日志记录实际设备、线程、候选数、音频时长和转写耗时；模型加载也可能包含首次下载。系统页依赖检查不会运行真实音频或承诺转写速度。

### 首页流水线与优先级队列

- 首页显示“订阅 → 录制归档 → 语音处理 → AI 选段 → 视频剪辑 → 发布投放”的紧凑流程图。节点仅显示名称和“空闲（0/总任务数）”或“工作中（执行数/总任务数）”；工作中的节点使用绿色背景，空闲使用灰色背景。总数包含执行队列与 pending，失败任务不会从节点消失。点击节点查看全部任务，优先级和 pending 筛选、运行与暂停都在下方任务区；已完成录像通过“已处理录像”查看。
- “订阅”是常驻值守队列，每个启用订阅占一个任务，窗口外显示“等待预约时间段”，检测时显示执行状态。失败或暂停后留在订阅节点的 pending 中；停用、删除才移出该节点。后台按高级优先、同级按最久未检测优先领取，并发默认 5。发现开播后进入录制队列，并将优先级传给录制任务与归档视频。
- 点击节点，下方显示该队列任务的名称、优先级、状态、当前节点进度、耗时、错误和日志入口。支持按状态、级别筛选及分页，每 5 秒自动刷新；所选节点和筛选条件保留在地址栏，刷新页面仍可继续查看。
- 在任务行的“优先级”下拉框选择“高级”或“普通”，立即保存并更新队列。高级任务先领取，同级按入队顺序执行。正在运行的任务不会被抢占；其优先级调整会传递到下一处理节点。录制任务的级别会传递给当前及后续归档视频。
- 录制进度根据 FFmpeg 输出时间戳计算，到归档时长后封档；音频提取、faster-whisper 转写显示实际处理百分比，剪辑以成功入库片段数显示进度，并附当前片段编码进度。AI 分析、FunASR 和发布器未提供可靠百分比时，显示运行状态和耗时。
- 发布仍需在片段库人工确认后入队。发布中断或失败时，先到目标平台核实结果，避免重复投放。
- 排队或执行中的任务均可点“暂停”，进入所属节点的 pending。执行中的任务先显示“暂停中”，终止该任务的 AI、FFmpeg、语音识别或发布子进程后释放槽位；录制会封档已录部分。已生成的归档和片段保留。
- **失败后不自动重试，也不会在重启后重新排队。** 点 pending 任务的“**运行**”，原任务保留阶段和优先级，重新进入同级队尾，复用已完成产物。订阅与录制分别控制：订阅“运行”不会带动录制 pending，录制“运行”也不会解除订阅的暂停；录制任务在 pending 时，自动监测不会重复创建它。发布需先核实平台结果再运行，避免重复投放。

队列保存在 SQLite 中。重启后仍未执行的排队任务保留；被中断、失败、手动停止、暂停的任务保持待运行，需要手动点“运行”重新入队。重试复用已生成的音频、转写、AI 结果和成功片段，保留高级/普通级别。

缺少语音、识别/AI失败会保留原始录像并显示错误，不再静默用规则生成“AI片段”。语音设为 none 会阻止音频分析。首次使用模型需要网络和磁盘空间；默认 small，更快的验证可选 tiny。faster-whisper 已随部署安装，FunASR 需 `deploy.ps1 -ASR`。

重启后被中断的任务标记为失败或已停止，不自动重试；未封档录像保留，可检查后重试。中断的发布不会自动重投，应先到平台核实。一个数据目录只运行一个后台调度实例。服务由开发者手动启动。

内置录制使用 yt-dlp、Streamlink、StreamGet 和 FFmpeg，适用于抖音、B站、YouTube、Twitch、部分通用网站和媒体直链；仍受平台、网络和账号权限影响。

### 抖音内置录制

使用 [StreamGet](https://github.com/ihmily/streamget) 4.0.10 解析直播源，FFmpeg 直接录制，不需要另开外部录制器。

1. 部署后进入“系统 → 运行组件”，检测“抖音录制 / StreamGet + Node.js”，确认依赖、Node.js 执行、抖音签名和 FFmpeg 都能运行。
2. 在“系统 → 抖音内置录制”选画质和解析超时（默认原画、90秒）。测试链接可留空检查组件，也可填具体直播间检测开播状态；测试不录制、不保存配置。
3. 已知直播间直接填 `https://live.douyin.com/房间号`；只知道入口时使用 AI 查找。需要账号时在订阅页打开登录窗口、登录并保存，直播解析会复用该订阅的登录状态。
4. 测试结果显示“直播中”后可点“立即录制”；也可启用订阅，按时间段自动检测开播并录制。“未开播”表示状态已确认，可继续值守；“状态未知”需查看错误和日志，不能按未开播处理。
5. 录制使用新解析的直播源，默认每30分钟归档，归档后立即入队分析；停止时保存尾段。无需配置 `watch_dir`。

入口首页不能作为直接录制地址，必须先找到具体直播间。画质缺档时由解析组件选择可用档位。账号 Cookie 用于抖音解析，不转发给无关 CDN。解析请求校验证书；网络代理留空直连，FFmpeg 录制代理需使用 HTTP/HTTPS。

录制启动错误会显示在订阅行及日志的“直播录制”来源，详细 FFmpeg 输出位于该次录像目录的 `recording.log`。平台要求登录或验证时，在订阅页人工完成后重测；无需重建已有有效 XML。

手动检查组件：

```powershell
python -m videocut.recording.douyin_worker check
```

### 外部录像接入（可选）

保留已有外部录制器、导入历史录像或其他工具的视频时，可使用目录接入：

1. 使用外部录制器（例如 [DouyinLiveRecorder](https://github.com/ihmily/DouyinLiveRecorder)）完成录制，在外部工具中也设置每30分钟分段。
2. 在“系统”的目录配置中，将 `watch_dir` 指向**运行 VideoCut 的电脑上**的录像目录，保存并测试目录读写。
3. 应用递归扫描 MP4、FLV；文件至少 5 MiB，且约 5 分钟未修改后，自动入库排队分析。
4. 也可在“仪表盘”填写已有录像的服务器本地完整路径，点“入库并分析”；手动入库支持 MP4、FLV、TS。

目录监听无需添加订阅即可工作。内置抖音录制不依赖该目录；使用外部工具时，在外部工具中配置其录制任务。

## 发布与账号

发布已统一接入 [MediaPublishPlatform](https://github.com/funfan0517/MediaPublishPlatform)，复用其登录、账号验证和单视频上传模块。支持小红书、微信视频号、抖音、快手、TikTok、Instagram、Facebook、B站、百家号；YouTube、今日头条 / 西瓜暂保留手动上传入口。是否实际可发仍取决于平台页面、账号权限及网络，组件安装通过不代表九个平台均已完成真实投稿验证。

1. 在“系统 → 统一发布 · MediaPublishPlatform”点击“安装 / 修复发布组件”，完成后运行组件检测；也可用部署命令的 `-Publish` 提前安装。
2. 浏览器路径留空时使用该组件自带的 Chromium，也可填写本机 Chrome / Edge 可执行文件路径。登录始终显示窗口；发布可选择无头模式。
3. 在对应平台下面填写账号名称，点击“打开登录窗口”。窗口会出现在**运行 VideoCut 的电脑**上，在里面人工登录或扫码，等待账号验证完成。
4. 刷新系统页，在该平台的“发布账号”中选择账号，点击“测试验证”，通过后保存。各平台可添加多个账号，每个平台选择一个默认发布账号。
5. 在片段详情页填写标题和正文，勾选需要的平台账号，点击“直接投放到所选账号”，可一次提交多个平台、多个账号。入队时固定账号，后来更改默认账号不会改变已排队任务。片段库、片段详情和“投放记录”显示成功平台及对应账号，失败原因和执行会话也按账号分别保留。

发布任务与分析共用处理槽位，同一账号串行使用，不同账号允许并发。失败或停止进入发布节点的 pending，需手动运行；不会自动换号或重复点击发布。提交后未得到页面成功确认时按失败处理，应先到平台后台核实，再决定是否重试。平台审核和作品最终是否公开，以平台后台为准。

组件源码固定在 `08132364e9b929aba77f6a91b468f9ae7ba70f1e`，独立环境放在 `tools/media-publish-platform/`，登录与账号数据在 `data/publishing/mpp/`，保留上游 MIT 许可证。VideoCut 直接调用单视频上传模块，无需 MPP 的独立 HTTP 服务、前端或逐平台命令，不受其 HTTP 上传接口的 160 MiB 限制。任务停止会终止本次上传子进程及其浏览器；已提交到平台的内容需到平台处理。

单独检测组件（不会登录或投稿）：

```powershell
python -m videocut.publishing.mpp_runtime check
```

旧的 `biliup` / `sau` 命令模板升级时停止使用，改为选择 MPP 账号。订阅页的来源网站登录状态与发布账号分别保存，不能混用。未配置自动发布时，可下载视频后使用片段页的手动上传入口。

## MediaCrawler 采集扩展

[MediaCrawler](https://github.com/NanmiCoder/MediaCrawler) 尚未接入，可用于关键词、作者、作品与评论采集以及发布后的公开互动指标。它不能直接代替按提示词核验直播间；直播查找继续使用 ai-module + Bragi，录制继续使用 StreamGet + FFmpeg。其单进程爬虫接口也不能直接充当本项目的并发任务队列。[采集接口源码](https://github.com/NanmiCoder/MediaCrawler/blob/main/api/routers/crawler.py)

MediaCrawler 当前采用非商业学习许可证，商业使用需要作者书面许可；外部服务调用也不自动改变此限制。[MediaCrawler LICENSE](https://github.com/NanmiCoder/MediaCrawler/blob/main/LICENSE)

## Markdown 执行会话与常见排查

顶部“执行会话”按会话汇总模型测试、爬虫、登录、语音识别、AI 切片、XML缓存命中/失效、Agent操作、发布和异常。每次执行有独立页面 `/ai-logs/<追踪号>`，以 Markdown 连续显示过程，通过 SSE 实时更新，结束后在文末追加结论；并发执行互不混合。支持按来源、状态、关键词筛选会话，旧追踪号链接仍可打开。

展示方式参考 WorkBuddy 的 AI 输出预览：累积全文后统一渲染 Markdown，支持标题、粗体、删除线、换行、列表、表格、引用和本地代码高亮。正文与结论都显示渲染结果，模型回复不再包在 JSON 事件外壳里；真正的 JSON 数据仍按代码块展示。旧会话首次打开会转换展示格式，不重新调用 AI、不改变执行状态。代码高亮复用 WorkBuddy 随附的 Highlight.js 11.9.0，资源和 BSD 许可证保存在 `static/vendor/`，运行时无需访问外网或依赖 WorkBuddy 目录。

工具输出同样参考 WorkBuddy 的事件分流：按 `tool_use(id)`、`tool_result(id)` 和 `tool_diff(id)` 关联调用与结果，每次调用显示一个默认折叠的结果块，包含调用内容、成功/失败状态和返回正文。MCP 文本块先拆包，JSON、XML 和差异按对应代码格式展示；普通输出保留原文，含完整代码围栏的 Markdown 才作为文档渲染。SSE 更新保留已展开的结果。下载的 Markdown 使用 `ai-tool` 围栏保留调用 ID 与结果；旧会话仅转换已保存且仍能精确匹配的脱敏片段，不重建被隐藏的内容。

添加订阅前的测试和系统测试旁边可展开查看结论及实时 Markdown。已保存的订阅列表与流水线任务仅保留“查看错误原因”，完整过程通过操作区的“会话详情”打开。订阅列表左侧第一行显示基本信息，第二行合并显示用户提示词；右侧操作区跨两行，集中放置测试、登录、录制、会话详情与错误信息。测试后，错误和会话链接自动更新。页面刷新或切换不会丢失已保存会话。独立页可下载 `.md`，取消“跟随最新内容”后便于阅读前文。执行失败、暂停、服务中断分别保留对应结论；内部一次操作失败但 Agent 随后修复成功，不会把整个会话误判为失败。

排查时按顺序查看页面加载、搜索关键词、候选链接、模型响应、最终选择或失败原因。AI 正确提取了主播名，也不代表搜索已经提交或已经进入直播间；需要继续检查浏览器执行与最终结果。

| 现象 | 处理方法 |
|---|---|
| 测试时没有登录窗口 | 测试是无头模式；另点“打开登录窗口”，在运行应用的电脑桌面登录 |
| 提示登录后搜索或安全验证 | 在新登录窗口中完成登录/验证，保存后重测；已有订阅使用该行的登录入口 |
| 找到抖音房间，但状态未知 | 在系统页检测 StreamGet / Node.js，检查网络；需要账号或验证时，在该订阅行登录并保存后重测 |
| AI 调用失败或连接超时 | 查看 native 错误；检查 CLI 账号、网关地址、模型及项目中显式填写的代理 |
| AI 调用超时 | 查看调用阶段、模型负载和代理；系统测试和切片使用“单次调用超时”；爬虫使用“Agent总时限”，可在系统页分别调整 |
| HTTP 401 / 404 | 检查 CLI 账号或独立配置的凭据、原生模型名和 Anthropic 兼容网关地址；不能沿用 OpenAI 聊天接口路径 |
| HTTPS 证书失败 | 使用 CLI 原生证书校验，企业 CA 可通过 `NODE_EXTRA_CA_CERTS` 配置；`REQUESTS_CA_BUNDLE` / `CURL_CA_BUNDLE` 文件也会映射给 CLI，保留证书验证 |
| 测试久久不结束 | 查看后台已用时间和本次日志；不要反复新开测试。更新代码后重启服务并 Ctrl+F5 |
| Chromium 或命令不存在 | 重跑对应部署步骤，在项目 `.venv` 中安装，再到系统页运行检测 |
| PowerShell 提示字符串缺少终止符 | 使用仓库中 ASCII 编码的 `deploy.ps1`，避免旧版中文脚本的编码解析问题 |
| 外部录像未入库 | 检查服务器本地目录、文件格式、大小和最后修改时间，确认应用持续运行 |

AI 通过 ai-module 的所选原生引擎调用。Claude 独立配置使用 Anthropic 兼容接口，ChatGPT 使用 Codex，OpenCode 使用原生供应商配置。项目显式配置代理，留空直连；各引擎的认证和接口按所选模式生效。

Markdown 会话与结构化诊断事件保存在 `data/app.db`，不会按单条事件裁剪掉会话前文；旧版已有日志在首次打开时转为会话文档。单条诊断详情最多 64 KB。密钥、Authorization、Cookie 和常见敏感网址参数会脱敏，原始 HTML 作为文本显示；提示词、页面摘录和字幕仍可能包含私人内容，分享前请检查。SSE 断线会自动重连并读取保存的完整文档，不会触发模型重跑。

## 数据、备份与开发验证

| 路径 | 内容 |
|---|---|
| `config.json` | 完整系统配置，包含 API 密钥 |
| `data/app.db` | 订阅、场次、片段、任务、发布记录和 AI 日志 |
| `data/browser/` | 独立浏览器登录状态，包含 Cookie/localStorage |
| `data/recordings/` | 内置录制的 TS 归档、分段清单和 recording.log |
| `data/audio/`、`data/analysis/` | 提取音频、带时间戳转写和 AI 选段缓存 |
| `data/models/` | faster-whisper 模型缓存 |
| `data/bragi/` | 成功路径 XML 和配套核验元数据 |
| `data/clips/`、`data/covers/` | 片段及封面 |
| `data/tmp/` | 临时文件 |
| `data/ai_runtime/` | AI 调用的临时工作区，完成或失败后清理 |

备份前停止应用，保存 `config.json` 和 `data/`；外部录像在另一个目录时需单独备份。原始录像保留策略会定期清理已分析场次的原文件，包括手动入库或目录接入的外部文件；对应音频和分析缓存也清理，切片保留。失败录像保留供重试。需要永久保留原文件时，将保留天数设为 0。`config.json` 和 `data/browser/` 包含敏感信息，不要提交或公开分享。

核心模块：`app.py` 提供网页，`videocut/jobs.py` 负责调度与队列，`videocut/recording/` 连续分段录制，`videocut/processing/` 处理音频与切片，`videocut/subscriptions/` 管理查找、登录和时间段。`videocut/ai/browser_tools.py` 只负责给 ai-module 挂接通用浏览器工具，`videocut/ai/bragi_plans.py` 管理 XML 缓存，`videocut/ai/ai_worker.py` 调用原生 `run_ai`。`videocut/system/` 管理配置和检测，`utils/` 提供公共工具，`videocut/publishing/` 负责发布。

项目回归检查：

```powershell
python -m unittest discover -s test -t . -p "test_*.py" -v
```

更多技术方案见 [SOLUTION.md](SOLUTION.md)。仅用于已获授权的内容或自有直播；录制和传播前确认内容授权。