KoroLiu/auto-news-shorts

auto-news-shorts 是做什么的？

你正在帮助一位用户（通常为初学者）在自己的电脑上运行此仓库。请在仓库根目录下工作。用平实的语言，以用户的母语解释每一步。

基本原则

• 切勿打印或回显密钥。 API 密钥应放入 .env 或 config.local.json，这两个文件都被 .gitignore 忽略。在检查密钥是否存在时，只报告“已设置/未设置”，绝不报告其值。
• 切勿替用户上传或发布视频。 本项目有意不包含上传代码。如果用户要求，请指引其阅读 docs/publishing-guide.md，并说明账户风险。除非用户在阅读后明确坚持要求，否则不要编写上传自动化代码。
• 不要将用户的私人材料添加到 Git 中： 语音样本、角色素材、cookies、runs/。请将其保留在 .gitignore 忽略的文件夹中。
• 优先使用用户已有的工具：他们的 Python 环境管理器、他们的浏览器。在安装大型组件（如 CUDA PyTorch 或 TTS 模型）之前先询问用户。
• 在声称某项功能可工作之前先验证：运行命令并读取输出。

1. 检查机器

运行 node -v（需要 ≥ 22.9）、ffmpeg -version、ffprobe -version，并找到 Chrome/Edge 和 Python 3。然后运行：

npm ci
npm run setup

npm run setup 会为每一项打印 ✅/❌。对于每个 ❌，请遵循 docs/setup.md 中的指引。常见修复：

• ffmpeg 缺失：安装它，或将其构建包解压到 tools/ffmpeg/ 中。
• Python 缺失：安装 Python 3.10+，或者在 config.local.json 中将 tts.python 指向一个现有的 Python 环境。

2. 配置

1. 将 .env.example 复制为 .env，并请用户将其 LLM 密钥粘贴到 LLM_API_KEY 中。不要自己键入密钥。默认提供商为 DeepSeek。其他兼容 OpenAI 的 API 可通过 LLM_BASE_URL / LLM_MODEL 使用；设置 LLM_VISION_MODEL 为该提供商的视觉模型，或留空。
2. 仅在需要特定于机器的值（路径、视觉模型、本地 TTS）时，才将 config.local.example.json 复制为 config.local.json。
3. 在 config.json 中，将 channel.name 和 channel.titleSign 设置为用户的频道。
4. 可选：
   • 通过 OpenCLI 添加 X/Reddit 来源（docs/setup.md#x-and-reddit-sources-opencli）
   • Qwen3-TTS 或 GPT-SoVITS 语音克隆（需要 NVIDIA GPU，以及用户有权使用的语音）
   • 自定义主播角色（docs/custom-host.md，包含版权警告）

3. 制作单集

• 全自动：npm run daily -- --auto（新闻）或 npm run weekly -- --auto（GitHub 项目）。
• 手动审核：npm run workbench 打开 http://127.0.0.1:3220。用户可在此处审核话题、脚本、语音和预览帧。
• 结果位于 runs/<date>-<column>/package/：视频、两个封面、metadata.txt。向用户展示此目录位置以及每个文件的用途。

运行流程可能因以下原因有意暂停：

• 在某个审核步骤（status.json 中的阶段 review-*）
• 当某条故事看起来涉及政治时（select.politicsFilter）

告诉用户有什么在等待他们。不要绕过暂停。

4. 当出现故障时

1. 读取 runs/<run>/run.log 和 runs/<run>/status.json 的末尾。
2. 在 docs/troubleshooting.md 中查找症状。
3. 从失败的阶段恢复，而不是重新开始：node src/main.mjs run --column news --from <stage>，其中 stage 为 collect、select、enrich、write、voice、render、export 之一。
4. 如果修改了代码，之后请运行 npm test 和 npm run check。

5. 自定义

• 话题规则、故事数量、屏幕文字：config.json → columns.<id>（参见 docs/configuration.md）。
• 来源：sources.json（参见 docs/sources.md）。
• 视频布局：remotion/Portrait/*.tsx。在某个运行流程生成 public/ep/<run>/ 后，使用 npm run studio 预览。
• 在用户发布自己的分支之前，运行 npm run audit，并帮助他们将自己的私人词汇放入 .audit-private.txt。