video-pipeline 1.0.4 → 1.2.0

package/.env.example

@@ -27,10 +27,10 @@ EXCEL_FILE=data/export_2026-06-10_split.xlsx
 
 # ── 输出目录（相对于项目根目录）─────────────────────────────────────────────
 # 【自由】任意合法目录名
-DOWNLOADS_DIR=downloads          # 下载的视频文件
-TRANSCODED_DIR=transcoded        # 转码后的音频文件
-REPORTS_DIR=reports              # 执行报告 JSON
-COOKIES_DIR=cookies              # 站点 cookie 文件
+DOWNLOADS_DIR=output/downloads    # 下载的视频文件
+TRANSCODED_DIR=output/transcoded  # 转码后的音频文件
+REPORTS_DIR=output/reports        # 执行报告 JSON
+COOKIES_DIR=cookies               # 站点 cookie 文件
 
 # ── 外部工具 ────────────────────────────────────────────────────────────────
 # 【自由】可改为工具的绝对路径或自定义命令名
@@ -51,6 +51,9 @@ FFPROBE=ffprobe                  # ffprobe 媒体信息
 # 远程服务模式 - whisper.cpp server (默认)
 WHISPER_BACKEND=service          # 【自由】service 或 local
 WHISPER_SERVICE=http://localhost:9588   # 【自由】服务地址
+WHISPER_TEMPERATURE=0.0           # 【自由】whisper 推理温度 (0.0~1.0, 越低越确定)
+WHISPER_TEMPERATURE_INC=0.2       # 【自由】whisper 温度增量 (fallback 时升温步长)
+WHISPER_RESPONSE_FORMAT=json      # 【自由】whisper 返回格式 (json/text/srt/vtt)
 
 # 本地模式 - openai-whisper CLI (取消下方注释并注释上方即可切换)
 # WHISPER_BACKEND=local
@@ -157,12 +160,14 @@ YOUKU_USER_AGENT=                              # 【自由】
 # ── AI 分析/关键词归纳 ─────────────────────────────────────────────────────
 # 【自由】是否启用 AI 分析环节（true/false），在 transcribe 之后执行
 AI_ENABLED=true
-# 【自由】OpenAI 兼容 API 配置
-AI_API_KEY=sk-jewvkpoAQNKAARQMYULWW1vv8x6UH4H9Qe4j10tp2AJFM3TY
-AI_BASE_URL=https://apihub.agnes-ai.com/v1
-AI_MODEL=agnes-2.0-flash
+# 【自由】OpenAI 兼容 API 配置（⚠️ 请勿提交真实 API Key 到此文件）
+AI_API_KEY=your-api-key-here
+AI_BASE_URL=https://your-api-host/v1
+AI_MODEL=your-model-name
 # 【自由】请求超时（秒），默认 300
 AI_TIMEOUT=300
+# 【自由】AI 推理温度 (0.0~2.0, 越低越确定/保守, 越高越随机/创意)
+AI_TEMPERATURE=0.3
 # 【关联】提示词模板，{content} 占位符会被识别文本替换
 # 【自由】提示词内容可随意修改，但必须保留 {content} 占位符
 AI_PROMPT_TPL=帮我归纳总结一下Keywords，尽可能全一点，这是内容：{content}

package/CHANGELOG.md

@@ -1,20 +1,29 @@
 # Changelog
 
-## [1.0.4] - 2026-06-11
+## [1.2.0] - 2026-06-11
+
+### Bug Fixes
+
+- 安全漏洞修复 + dry-run 模式完善 + 全面测试套件 (`3677b6a`)
+
+### Refactoring
+
+- 输出目录统一归入 output/ 并清理测试产物 (`f5cad03`)
+- whisper/AI 硬编码参数改为 env 可配置 (`611b079`)
+
+
+## [1.1.0] - 2026-06-11
 
 ### Features
 
-- rename npm package to video-pipeline (`644cc8a`)
-- add --url option to Python version (parity with Node.js) (`e1df301`)
+- add --input option for local file processing (Node.js + Python) (`4805e3b`)
 
 ### Bug Fixes
 
-- recreate v1.0.3 tag and regenerate CHANGELOG with correct scopes (`9c2db90`)
-- normalize CHANGELOG format to Keep a Changelog standard (`2b887f4`)
-- correct changelog per-version ranges + fix getLastTag for Windows (`755222a`)
+- whisper transcribe FormData + multi --step + auto-find wav (`f8c9fa2`)
 
 
-## [Unreleased]
+## [1.0.4] - 2026-06-11
 
 ### Features
 
@@ -23,6 +32,7 @@
 
 ### Bug Fixes
 
+- recreate v1.0.3 tag and regenerate CHANGELOG with correct scopes (`9c2db90`)
 - normalize CHANGELOG format to Keep a Changelog standard (`2b887f4`)
 - correct changelog per-version ranges + fix getLastTag for Windows (`755222a`)
 

package/README.md

@@ -1,6 +1,38 @@
-# 视频下载 / 转码 / 文本识别 / AI 分析 流程
+# 视频处理流水线 (Video Pipeline)
 
-基于 `process_videos.py`，一键完成：yt-dlp 下载 → ffmpeg 转码 → whisper 识别 → AI 关键词归纳 → 写回 Excel。
+基于 `process_videos.js` (Node.js) 或 `process_videos.py` (Python)，一键完成：yt-dlp 下载 → ffmpeg 转码 → whisper 识别 → AI 关键词归纳 → 写回 Excel。
+
+**两种使用方式：**
+- **Excel 批量处理**：从 Excel 文件读取视频 ID，自动完成全流程
+- **直链下载**：通过 `--url` 直接指定视频链接，自动识别平台并下载
+- **本地文件**：通过 `--input` 指定本地视频文件，跳过下载直接转码分析
+
+---
+
+## 安装方式
+
+### Node.js 版本（推荐）
+
+```bash
+# 全局安装
+npm install -g video-pipeline
+
+# 使用后可直接调用
+video-pipeline --help
+```
+
+### Python 版本
+
+```bash
+# 克隆或下载脚本
+git clone https://gitee.com/siriussupreme/yt-dlp_ffmpeg_whisper_memo-ai.git
+cd yt-dlp_ffmpeg_whisper_memo-ai
+
+# 安装 Python 依赖
+pip install pandas openpyxl requests python-dotenv questionary
+```
+
+---
 
 ## 环境依赖
 
@@ -110,21 +142,33 @@ WHISPER_LANGUAGE=zh          # 空=多语言自动检测（默认），需要指
 ## 目录结构
 
 ```
-├── process_videos.py              # 主流程脚本
-├── .env.example                   # 环境变量模板（可提交 Git）
-├── .env                           # 实际环境变量（已 gitignore，按需修改）
-├── export_2026-06-10_split.xlsx   # 数据源（YouTube视频 / 普诺赛中文站 两个 sheet）
-├── cookies/
-│   ├── bilibili.txt               # B站 cookie（Netscape 格式）
-│   └── youtube.txt                # YouTube cookie 备用（Firefox 直读方案不需要）
-├── downloads/                     # yt-dlp 下载输出（mp4）
+├── process_videos.js              # Node.js 主流程脚本（推荐）
+├── process_videos.py              # Python 主流程脚本（备选）
+├── package.json                   # Node.js 项目配置（npm 包）
+├── .env.example                  # 环境变量模板（可提交 Git）
+├── .env                          # 实际环境变量（已 gitignore，按需修改）
+├── data/                         # 数据源目录
+│   └── export_2026-06-10_split.xlsx   # Excel 数据源
+├── cookies/                     # 站点 cookie 文件
+│   ├── bilibili.txt            # B站 cookie（Netscape 格式）
+│   └── youtube.txt             # YouTube cookie 备用（Firefox 直读方案不需要）
+├── downloads/                    # yt-dlp 下载输出（mp4）
 │   ├── YouTube视频/
 │   └── 普诺赛中文站/
-├── transcoded/                    # ffmpeg 转码输出（wav 16kHz mono）
+├── transcoded/                   # ffmpeg 转码输出（wav 16kHz mono）
 │   ├── YouTube视频/
 │   └── 普诺赛中文站/
-└── reports/                       # 执行报告（JSON）
-    └── report_YYYYMMDD_HHMMSS.json
+├── reports/                      # 执行报告（JSON）
+│   └── report_YYYYMMDD_HHMMSS.json
+├── scripts/                      # 辅助脚本
+│   ├── release.js                 # 版本发布脚本
+│   └── regenerate-changelog.js  # CHANGELOG 重建脚本
+├── .github/                      # GitHub Actions 工作流
+├── .husky/                      # Git hooks（commit 消息检查）
+├── node_modules/                 # Node.js 依赖（已 gitignore）
+├── CHANGELOG.md                  # 版本变更记录
+├── README.md                     # 使用文档
+└── LICENSE                       # MIT 许可证
 ```
 
 ---
@@ -167,35 +211,39 @@ yt-dlp 可直接从 Firefox 浏览器读取 cookie，无需手动导出：
 
 ```bash
 # 下载 + 转码 + 识别 + AI分析，指定 sheet + extra.id
+node process_videos.js --sheet "YouTube视频" --id 2143
+# 或 Python 版本
 python process_videos.py --sheet "YouTube视频" --id 2143
 
 # 只跑下载
+node process_videos.js --sheet "普诺赛中文站" --id 16 --step download
+# 或 Python 版本
 python process_videos.py --sheet "普诺赛中文站" --id 16 --step download
 
 # 只跑转码（需要已有下载文件）
-python process_videos.py --sheet "普诺赛中文站" --id 16 --step transcode
+node process_videos.js --sheet "普诺赛中文站" --id 16 --step transcode
 
 # 只跑识别（需要已有转码文件）
-python process_videos.py --sheet "普诺赛中文站" --id 16 --step transcribe
+node process_videos.js --sheet "普诺赛中文站" --id 16 --step transcribe
 
 # 只跑 AI 分析（需要已有识别文本）
-python process_videos.py --sheet "普诺赛中文站" --id 16 --step analyze
+node process_videos.js --sheet "普诺赛中文站" --id 16 --step analyze
 
 # 强制重新下载（忽略已有文件）
-python process_videos.py --sheet "YouTube视频" --id 2143 --force
+node process_videos.js --sheet "YouTube视频" --id 2143 --force
 ```
 
 ### 批量全量
 
 ```bash
 # 全量执行（2 个并发，失败重试 3 次）
-python process_videos.py --concurrency 2 --retry 3
+node process_videos.js --concurrency 2 --retry 3
 
 # 只跑某一 sheet
-python process_videos.py --sheet "YouTube视频" --concurrency 2 --retry 3
+node process_videos.js --sheet "YouTube视频" --concurrency 2 --retry 3
 
 # 先干跑预览
-python process_videos.py --dry-run
+node process_videos.js --dry-run
 ```
 
 ### 重跑失败
@@ -203,10 +251,10 @@ python process_videos.py --dry-run
 ```bash
 # 第一次跑完后生成 reports/report_xxx.json
 # 查看失败项：
-python process_videos.py --retry-failed reports/report_20260610_143000.json --dry-run
+node process_videos.js --retry-failed reports/report_20260610_143000.json --dry-run
 
 # 重跑：
-python process_videos.py --retry-failed reports/report_20260610_143000.json --concurrency 2 --retry 3
+node process_videos.js --retry-failed reports/report_20260610_143000.json --concurrency 2 --retry 3
 ```
 
 ### 超时控制（防止任务卡死）
@@ -215,7 +263,7 @@ python process_videos.py --retry-failed reports/report_20260610_143000.json --co
 
 ```bash
 # 自定义超时（单位秒）
-python process_videos.py \
+node process_videos.js \
     --download-timeout 900 \    # 下载 15 分钟
     --transcode-timeout 600 \   # 转码 10 分钟
     --transcribe-timeout 1200 \ # 识别 20 分钟
@@ -228,6 +276,51 @@ python process_videos.py \
 - 无论超时多少次，**不会阻塞其他并发任务**，失败项会记录到报告
 - 超时失败的任务可用 `--retry-failed` 单独重跑
 
+### 直接指定 URL 下载
+
+```bash
+# 直接指定视频链接，自动识别平台（支持标准链接、短链接、内嵌链接）
+node process_videos.js --url "https://www.youtube.com/watch?v=zzJmKPX8a3c"
+python process_videos.py --url "https://www.bilibili.com/video/BV1xx411c7mD"
+
+# 指定输出文件名（不含扩展名）
+node process_videos.js --url "https://youtu.be/zzJmKPX8a3c" --name "产品介绍"
+
+# 只执行部分步骤
+node process_videos.js --url "https://www.youtube.com/watch?v=zzJmKPX8a3c" --step transcode
+```
+
+**支持的 URL 格式：**
+- YouTube: 标准页、短链接、Shorts、内嵌页、直播
+- B站: 标准页（BV/av号）、短链接、内嵌页、移动端
+- 腾讯视频: 标准页、内嵌页、移动端
+- 优酷: 标准页
+
+**文件命名规则：**
+- 默认：`{平台}_{视频ID}`（如 `youtube_zzJmKPX8a3c`）
+- 自定义：通过 `--name` 指定（如 `--name "产品介绍"`）
+- 冲突处理：自动提示选择（覆盖 / 跳过 / 自定义名称）
+
+### 处理本地文件
+
+```bash
+# 指定本地视频文件，跳过下载，直接转码→识别→分析
+node process_videos.js --input "downloads/产品介绍.mp4"
+python process_videos.py --input "downloads/产品介绍.mp4"
+
+# 指定输出文件名
+node process_videos.js --input "downloads/产品介绍.mp4" --name "产品介绍_分析"
+
+# 只执行部分步骤
+node process_videos.js --input "downloads/产品介绍.mp4" --step analyze
+```
+
+**文件校验：**
+- 检查文件是否存在
+- 检查文件格式是否支持（视频/音频）
+- 检查是否可以正常读取
+- 校验失败会提示错误并退出
+
 ### 工具预检（执行前自动检测）
 
 每次执行任务前，脚本会自动检测本次涉及步骤所需的工具/服务是否可用：
@@ -249,19 +342,25 @@ python process_videos.py \
 
 | 参数 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `--sheet` | str | 全部 | 指定 sheet：`YouTube视频` 或 `普诺赛中文站` |
-| `--id` | str | — | 指定 extra.id 或 title（单条测试） |
-| `--step` | str | 全跑 | 只执行某步：`download` / `transcode` / `transcribe` |
+| `--sheet <name>` | str | 全部 | 指定 sheet 名称 |
+| `--id <id>` | str | — | 指定 extra.id 或 title（单条测试） |
+| `--step <step>` | str | 全跑 | 只执行某步：`download` / `transcode` / `transcribe` / `analyze` |
 | `--force` | flag | off | 强制重做下载+转码，忽略已有文件 |
-| `--concurrency` | int | 1 | 并发数，建议 2~3 |
-| `--retry` | int | 0 | 每步失败最大重试次数 |
-| `--retry-delay` | float | 5 | 重试间隔基数（秒），指数退避 5→10→20 |
-| `--download-timeout` | int | 600 | 单个下载任务最长执行时间（秒） |
-| `--transcode-timeout` | int | 600 | 单个转码任务最长执行时间（秒） |
-| `--transcribe-timeout` | int | 600 | 单个识别任务最长执行时间（秒） |
-| `--analyze-timeout` | int | 300 | 单个 AI 分析任务最长执行时间（秒） |
+| `--concurrency <n>` | int | 1 | 并发数，建议 2~3 |
+| `--retry <n>` | int | 0 | 每步失败最大重试次数 |
+| `--retry-delay <n>` | float | 5 | 重试间隔基数（秒），指数退避 5→10→20 |
+| `--download-timeout <n>` | int | 600 | 单个下载任务最长执行时间（秒） |
+| `--transcode-timeout <n>` | int | 600 | 单个转码任务最长执行时间（秒） |
+| `--transcribe-timeout <n>` | int | 600 | 单个识别任务最长执行时间（秒） |
+| `--analyze-timeout <n>` | int | 300 | 单个 AI 分析任务最长执行时间（秒） |
 | `--dry-run` | flag | off | 干跑模式，只列任务不执行 |
-| `--retry-failed` | path | — | 从报告 JSON 重跑失败项 |
+| `--retry-failed <path>` | path | — | 从报告 JSON 重跑失败项 |
+| `--init` | flag | off | 复制 .env.example 到当前目录并重命名为 .env |
+| `--file <path>` | path | — | 指定 Excel 文件路径（优先级高于 EXCEL_FILE 环境变量） |
+| `--input <path>` | path | — | 指定本地视频文件路径（跳过下载，直接转码→识别→分析） |
+| `--url <url>` | str | — | 直接指定视频下载链接（跳过 Excel），支持标准链接和内嵌链接 |
+| `--name <name>` | str | — | 指定输出文件名，不含扩展名（与 --url / --input 配合使用） |
+| `--env-file <path>` | path | .env | 指定要加载的 .env 文件路径 |
 
 ---
 
@@ -340,11 +439,13 @@ AI_TIMEOUT=300
 
 ```bash
 # 已有识别文本，只跑 AI 分析
+node process_videos.js --sheet "普诺赛中文站" --id 427 --step analyze
+# 或 Python 版本
 python process_videos.py --sheet "普诺赛中文站" --id 427 --step analyze
 
 # 单独跑 analyze 超过 16 条不会写入 Excel
 # 要想写入 Excel 跑完整流程 --step analyze
-python process_videos.py --sheet "YouTube视频" --step analyze --concurrency 2
+node process_videos.js --sheet "YouTube视频" --step analyze --concurrency 2
 ```
 
 ### 禁用 AI 分析
@@ -442,16 +543,18 @@ python process_videos.py --sheet "YouTube视频" --step analyze --concurrency 2
 
 ```bash
 # 1. 干跑预览
+node process_videos.js --dry-run
+# 或 Python 版本
 python process_videos.py --dry-run
 
 # 2. 单条验证
-python process_videos.py --sheet "YouTube视频" --id 2143 --retry 2
+node process_videos.js --sheet "YouTube视频" --id 2143 --retry 2
 
 # 3. 全量执行
-python process_videos.py --concurrency 3 --retry 3
+node process_videos.js --concurrency 3 --retry 3
 
 # 4. 查看报告，重跑失败项
-python process_videos.py --retry-failed reports/report_xxx.json --concurrency 2 --retry 3
+node process_videos.js --retry-failed reports/report_xxx.json --concurrency 2 --retry 3
 ```
 
 ---
@@ -568,22 +671,58 @@ python process_videos.py --retry-failed reports/report_xxx.json --concurrency 2
 
 ## 换电脑使用
 
-1. 安装上述所有必装工具，确保 `yt-dlp`、`ffmpeg`、`ffprobe`、`node` 均在 PATH
-2. `pip install pandas openpyxl requests python-dotenv`
-3. `cp .env.example .env`，根据实际情况修改 `.env` 中的路径、代理端口和字段映射
-4. 用 Firefox 登录 YouTube，设置 `YOUTUBE_COOKIES_FROM_BROWSER=firefox`
-5. B站 cookie 仍需手动导出 `cookies/bilibili.txt`
-6. 启动代理（Clash Verge 等），确认端口匹配 `YOUTUBE_PROXY`
-7. `python process_videos.py --dry-run` 验证
+### Node.js 版本
+
+1. 安装 Node.js (18+)：[nodejs.org](https://nodejs.org/)
+2. 安装视频处理工具：
+   ```bash
+   npm install -g video-pipeline
+   ```
+3. 克隆或下载项目文件（`.env.example`、`.env`、`cookies/` 等）
+4. 安装必装工具：`yt-dlp`、`ffmpeg`、`ffprobe`，确保均在 PATH
+5. 用 Firefox 登录 YouTube，设置 `YOUTUBE_COOKIES_FROM_BROWSER=firefox`
+6. B站 cookie 仍需手动导出 `cookies/bilibili.txt`
+7. 启动代理（Clash Verge 等），确认端口匹配 `YOUTUBE_PROXY`
+8. `video-pipeline --dry-run` 验证
+
+### Python 版本
+
+1. 安装 Python 3.9+：[python.org](https://www.python.org/)
+2. 安装必装工具：`yt-dlp`、`ffmpeg`、`ffprobe`，确保均在 PATH
+3. 安装 Python 依赖：`pip install pandas openpyxl requests python-dotenv questionary`
+4. `cp .env.example .env`，根据实际情况修改 `.env` 中的路径、代理端口和字段映射
+5. 用 Firefox 登录 YouTube，设置 `YOUTUBE_COOKIES_FROM_BROWSER=firefox`
+6. B站 cookie 仍需手动导出 `cookies/bilibili.txt`
+7. 启动代理（Clash Verge 等），确认端口匹配 `YOUTUBE_PROXY`
+8. `python process_videos.py --dry-run` 验证
+
+---
 
 ## 适配其他 Excel
 
 如果需要用这套脚本处理**其他项目的 Excel**（列名不同、平台不同）：
 
+**方法一：修改 .env 文件**
+
 1. 复制 `.env.example` 为新 `.env`（或修改现有 `.env`）
 2. 修改 `EXCEL_FILE` 指向新 Excel
 3. 修改列映射（`COL_ID`、`COL_TITLE`、`COL_CONTENT` 及各平台列名）
 4. 修改 `VIDEO_SHEETS` 为新的 sheet 名称
 5. 如需新平台，在 `PLATFORM_PRIORITY` 中添加 key，并配置对应的 `{KEY}_URL_TPL`
-6. `python process_videos.py --dry-run` 验证配置
+6. `node process_videos.js --dry-run` 验证配置
 7. 跑全量
+
+**方法二：使用 --file 选项（推荐）**
+
+```bash
+# 直接指定 Excel 文件，无需修改 .env
+node process_videos.js --file "data/其他项目.xlsx" --dry-run
+
+# 配合 --env-file 使用自定义环境变量
+node process_videos.js --file "data/其他项目.xlsx" --env-file ".env.其他项目" --dry-run
+```
+
+**优点：**
+- 无需修改 `.env` 文件
+- 可以为不同项目创建不同的 `.env` 配置文件
+- 命令行优先级高于环境变量

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "video-pipeline",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "description": "视频下载、转码、文本识别、AI 关键词分析一体化流程 CLI 工具",
   "keywords": [
     "video",

package/process_videos.js

@@ -43,10 +43,10 @@ function envPath(key, defaultValue) {
 }
 
 let EXCEL_FILE = envPath('EXCEL_FILE', 'data/export_2026-06-10_split.xlsx');
-const DOWNLOADS_DIR = envPath('DOWNLOADS_DIR', 'downloads');
-const TRANSCODED_DIR = envPath('TRANSCODED_DIR', 'transcoded');
+const DOWNLOADS_DIR = envPath('DOWNLOADS_DIR', 'output/downloads');
+const TRANSCODED_DIR = envPath('TRANSCODED_DIR', 'output/transcoded');
 const COOKIES_DIR = envPath('COOKIES_DIR', 'cookies');
-const REPORTS_DIR = envPath('REPORTS_DIR', 'reports');
+const REPORTS_DIR = envPath('REPORTS_DIR', 'output/reports');
 
 const YTDLP = process.env.YTDLP || 'yt-dlp';
 const FFMPEG = process.env.FFMPEG || 'ffmpeg';
@@ -57,6 +57,9 @@ const WHISPER_MODEL = process.env.WHISPER_MODEL || 'base';
 const WHISPER_DEVICE = process.env.WHISPER_DEVICE || 'cpu';
 const WHISPER_LANGUAGE = process.env.WHISPER_LANGUAGE || '';
 const WHISPER_SERVICE_MODEL = process.env.WHISPER_SERVICE_MODEL || '';
+const WHISPER_TEMPERATURE = process.env.WHISPER_TEMPERATURE || '0.0';
+const WHISPER_TEMPERATURE_INC = process.env.WHISPER_TEMPERATURE_INC || '0.2';
+const WHISPER_RESPONSE_FORMAT = process.env.WHISPER_RESPONSE_FORMAT || 'json';
 let _SERVICE_MODEL_LOADED = null;
 
 const TRANSCODE_EXT = process.env.TRANSCODE_EXT || '.wav';
@@ -80,6 +83,21 @@ const PLATFORM_COL_MAP = {
   youkuId: COL_YOUKUID,
 };
 
+// ============================== 工具函数 ==============================
+function c(color, text) {
+  const colors = {
+    dim: '\x1b[2m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    blue: '\x1b[34m',
+    magenta: '\x1b[35m',
+    reset: '\x1b[0m',
+  };
+  return (colors[color] || '') + text + colors.reset;
+}
+
 const PLATFORM_PRIORITY = (process.env.PLATFORM_PRIORITY || 'bilibiliBvid,youtubeId,tencentVid,youkuId')
   .split(',').map(s => s.trim()).filter(Boolean);
 
@@ -166,27 +184,6 @@ function timestamp() {
   return new Date().toTimeString().slice(0, 8);
 }
 
-// ============================== 锁 / 并发控制 ==============================
-let _printLock = false;
-const _printQueue = [];
-function printLock(fn) {
-  return new Promise(resolve => {
-    _printQueue.push(async () => {
-      _printLock = true;
-      try { fn(); } finally { _printLock = false; }
-      resolve();
-    });
-    if (_printQueue.length === 1) processQueue();
-  });
-}
-async function processQueue() {
-  while (_printQueue.length) {
-    await _printQueue[0]();
-    _printQueue.shift();
-  }
-}
-
-// 简化：Node.js 单线程，简单场景下不需要锁
 function lockedPrint(s) {
   console.log(s);
 }
@@ -259,7 +256,12 @@ class TaskResult {
 
 // ============================== 工具函数 ==============================
 function safeFilename(name) {
-  return String(name).replace(/[\\/:*?"<>|]/g, '_').trim();
+  let safe = String(name).replace(/[\\/:*?"<>|]/g, '_').trim();
+  // 防止路径遍历：过滤 ..
+  while (safe.includes('..')) safe = safe.replace('..', '_');
+  // 防止以 . 开头（Unix 隐藏文件）
+  safe = safe.replace(/^\.+/, '');
+  return safe || 'unknown';
 }
 
 function readExcelSheet(sheetName) {
@@ -461,7 +463,7 @@ async function resolveUrlConflict(proposedPath) {
     console.log(c('yellow', '文件名不能为空，使用默认名称'));
     return { action: 'proceed', path: proposedPath };
   }
-  const newPath = path.join(dir, `${customName}${ext}`);
+  const newPath = path.join(dir, `${safeFilename(customName)}${ext}`);
   return resolveUrlConflict(newPath);
 }
 
@@ -682,6 +684,7 @@ async function stepAnalyze(text, maxRetries, retryDelay, timeout = 300) {
   const baseUrl = (process.env.AI_BASE_URL || '').replace(/\/$/, '');
   const model = process.env.AI_MODEL || '';
   const promptTpl = process.env.AI_PROMPT_TPL || '帮我归纳总结一下Keywords，尽可能全一点，这是内容：{content}';
+  const aiTemperature = parseFloat(process.env.AI_TEMPERATURE || '0.3');
   const aiTimeout = parseInt(process.env.AI_TIMEOUT || String(timeout), 10);
 
   if (!apiKey || !baseUrl || !model) {
@@ -693,7 +696,7 @@ async function stepAnalyze(text, maxRetries, retryDelay, timeout = 300) {
   const payload = JSON.stringify({
     model,
     messages: [{ role: 'user', content: prompt }],
-    temperature: 0.3,
+    temperature: aiTemperature,
   });
 
   let lastErr = null;
@@ -835,7 +838,7 @@ async function stepDownload(row, sheetName, maxRetries, retryDelay, force, timeo
   }
 
   try {
-    const { result, retriesUsed, error } = await retryCall(doDownload, maxRetries, retryDelay, stem);
+    await retryCall(doDownload, maxRetries, retryDelay, stem);
   } catch (e) {
     logError(`[${stem}] yt-dlp download failed: ${(e.stderr || e.message).slice(-2000)}`);
     return { file: null, retries: maxRetries, error: (e.stderr || e.message).slice(0, 500) };
@@ -1033,14 +1036,12 @@ async function transcribeService(audioFile, stem, maxRetries, retryDelay, timeou
       }
 
       // Run inference
-      const fileStream = fs.createReadStream(audioFile);
-      const fileStat = fs.statSync(audioFile);
+      const fileBlob = await fs.openAsBlob(audioFile);
       const form = new FormData();
-      // Use ReadStream directly - Node.js fetch supports it natively for FormData
-      form.append('file', fileStream, path.basename(audioFile));
-      form.append('temperature', '0.0');
-      form.append('temperature_inc', '0.2');
-      form.append('response_format', 'json');
+      form.append('file', fileBlob, path.basename(audioFile));
+      form.append('temperature', WHISPER_TEMPERATURE);
+      form.append('temperature_inc', WHISPER_TEMPERATURE_INC);
+      form.append('response_format', WHISPER_RESPONSE_FORMAT);
 
       const controller = new AbortController();
       const timer = setTimeout(() => controller.abort(), timeout * 1000);
@@ -1133,7 +1134,6 @@ function writeAllContentsToExcel(results, keywordsDict = null) {
   }
 
   // Write content column
-  writeColumn(null, COL_CONTENT, updates); // null sheetName means iterate all sheets
   for (const [sheetName, rowsObj] of groupBySheetMap(updates)) {
     writeColumn(sheetName, COL_CONTENT, Object.entries(rowsObj));
   }
@@ -1166,20 +1166,28 @@ function groupBySheetMap(updates) {
 }
 
 // ============================== 报告 ==============================
+function computeSummary(results) {
+  let success = 0, partial = 0, failed = 0, noVideo = 0;
+  for (const r of results) {
+    if (r.overall_status === 'success') success++;
+    else if (r.overall_status === 'partial') partial++;
+    else if (r.overall_status === 'failed') failed++;
+    else if (r.overall_status === 'no_video') noVideo++;
+  }
+  return { total: results.length, success, partial, failed, no_video: noVideo };
+}
+
 function generateReport(results, config) {
   fs.mkdirSync(REPORTS_DIR, { recursive: true });
   const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15).replace(/(\d{8})(\d{6})/, '$1_$2');
   const reportFile = path.join(REPORTS_DIR, `report_${ts}.json`);
 
-  const success = results.filter(r => r.overall_status === 'success').length;
-  const partial = results.filter(r => r.overall_status === 'partial').length;
-  const failed = results.filter(r => r.overall_status === 'failed').length;
-  const noVideo = results.filter(r => r.overall_status === 'no_video').length;
+  const summary = computeSummary(results);
 
   const report = {
     timestamp: new Date().toISOString(),
     config,
-    summary: { total: results.length, success, partial, failed, no_video: noVideo },
+    summary,
     items: results.map(r => r.toJSON()),
     failed_items: results.filter(r => r.overall_status === 'failed' || r.overall_status === 'partial')
       .map(r => ({
@@ -1197,15 +1205,12 @@ function generateReport(results, config) {
 }
 
 function printReportSummary(results) {
-  const success = results.filter(r => r.overall_status === 'success').length;
-  const partial = results.filter(r => r.overall_status === 'partial').length;
-  const failed = results.filter(r => r.overall_status === 'failed').length;
-  const noVid = results.filter(r => r.overall_status === 'no_video').length;
+  const { total, success, partial, failed, no_video: noVid } = computeSummary(results);
 
   console.log(`\n${'='.repeat(60)}`);
   console.log(`  执行摘要`);
   console.log(`${'='.repeat(60)}`);
-  console.log(`  总计: ${results.length}`);
+  console.log(`  总计: ${total}`);
   console.log(`  ✅ 成功: ${success}`);
   console.log(`  ⚠️ 部分成功: ${partial}`);
   console.log(`  ❌ 失败: ${failed}`);
@@ -1226,6 +1231,35 @@ function printReportSummary(results) {
   }
 }
 
+
+// ============================== 环境预检 + 用户确认 ==============================
+async function checkAndConfirmEnv(envCheck, dryRun, confirmMsg) {
+  if (envCheck.allOk) return true;
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('  \u26a0\ufe0f  工具/服务预检：以下依赖不可用');
+  console.log('='.repeat(60));
+  for (const issue of envCheck.issues) console.log(`  \u2022 ${issue}`);
+  console.log('\n  涉及的步骤将失败。');
+  if (dryRun) return true;
+  try {
+    const rl = require('readline').createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve => {
+      rl.question(`\n  ${confirmMsg}(输入 yes 继续，其他任意键取消): `, ans => {
+        rl.close();
+        resolve(ans.trim().toLowerCase());
+      });
+    });
+    if (answer !== 'yes') {
+      console.log('用户取消执行（工具不可用）');
+      return false;
+    }
+    return true;
+  } catch (e) {
+    console.log('非交互环境，取消执行');
+    return false;
+  }
+}
+
 // ============================== 单任务处理 ==============================
 async function processOneTask(row, sheetName, steps, maxRetries, retryDelay, force,
   whisperAvailable, positionLabel = '', downloadTimeout = 600, transcodeTimeout = 600,
@@ -1359,6 +1393,258 @@ async function processOneTask(row, sheetName, steps, maxRetries, retryDelay, for
 }
 
 // ============================== 主控流程 ==============================
+// ═══════════════════════════════════════════════════════════════════
+// 本地文件流水线（--input 模式）
+// ═══════════════════════════════════════════════════════════════════
+
+/**
+ * 验证本地视频文件，检测可执行步骤
+ * 返回 { valid, format, hasVideo, hasAudio, videoCodec, audioCodec,
+ *         duration, width, height, errors, feasibleSteps }
+ */
+function validateInputFile(filePath) {
+  const result = {
+    valid: false, format: '', hasVideo: false, hasAudio: false,
+    videoCodec: '', audioCodec: '', duration: 0, width: 0, height: 0,
+    errors: [], feasibleSteps: [],
+  };
+
+  // 1. 文件存在性
+  const absPath = path.resolve(filePath);
+  if (!fs.existsSync(absPath)) {
+    result.errors.push('文件不存在');
+    return result;
+  }
+  const stat = fs.statSync(absPath);
+  if (!stat.isFile()) {
+    result.errors.push('不是一个文件');
+    return result;
+  }
+  if (stat.size === 0) {
+    result.errors.push('文件大小为 0');
+    return result;
+  }
+
+  // 2. ffprobe 分析
+  if (!which(FFPROBE)) {
+    result.errors.push(`ffprobe 不可用 (${FFPROBE})`);
+    result.valid = true; // 文件本身有效，但无法探测流信息
+    result.feasibleSteps = ['transcode', 'transcribe', 'analyze']; // 乐观推测
+    return result;
+  }
+
+  try {
+    const probeRaw = execSync(
+      `${FFPROBE} -v error -show_entries stream=codec_type,codec_name,width,height -show_entries format=format_name,duration -of json "${absPath}"`,
+      { encoding: 'utf-8', timeout: 30000 }
+    );
+    const info = JSON.parse(probeRaw);
+
+    // 提取 format 信息
+    if (info.format) {
+      result.format = (info.format.format_name || '').split(',')[0];
+      result.duration = parseFloat(info.format.duration || '0');
+    }
+
+    // 提取 stream 信息
+    if (info.streams) {
+      for (const s of info.streams) {
+        if (s.codec_type === 'video') {
+          result.hasVideo = true;
+          result.videoCodec = s.codec_name || '';
+          result.width = s.width || 0;
+          result.height = s.height || 0;
+        }
+        if (s.codec_type === 'audio') {
+          result.hasAudio = true;
+          result.audioCodec = s.codec_name || '';
+        }
+      }
+    }
+
+    result.valid = true;
+
+    // 3. 判断可执行步骤
+    if (result.hasVideo) {
+      result.feasibleSteps.push('transcode');
+    }
+    if (result.hasAudio) {
+      result.feasibleSteps.push('transcribe', 'analyze');
+    }
+    // 无视频无音频 → 所有步骤不可行
+    if (!result.hasVideo && !result.hasAudio) {
+      result.feasibleSteps = [];
+      result.errors.push('文件不包含视频或音频流，无法处理');
+    }
+
+    // 如果只有视频没有音频：只能转码
+    if (result.hasVideo && !result.hasAudio) {
+      result.errors.push('文件不含音频轨道，将跳过语音识别和 AI 分析');
+    }
+
+  } catch (e) {
+    result.errors.push(`ffprobe 解析失败: ${(e.stderr || e.message || '').slice(0, 200)}`);
+    result.valid = true; // 文件存在且不为空，让 ffmpeg 自行判断
+    result.feasibleSteps = ['transcode', 'transcribe', 'analyze'];
+  }
+
+  return result;
+}
+
+/**
+ * 处理 --input 模式下的文件冲突（已存在的转码/识别结果）
+ * @param {string} proposedPath - 即将生成的输出文件路径
+ * @returns {Promise<{action: 'overwrite'|'skip', path: string}>}
+ */
+async function resolveInputConflict(proposedPath) {
+  if (!fs.existsSync(proposedPath)) {
+    return { action: 'overwrite', path: proposedPath };
+  }
+  const size = (fs.statSync(proposedPath).size / 1024 / 1024).toFixed(1);
+  console.log(`\n⚠️  文件已存在: ${proposedPath} (${size} MB)`);
+  const choice = await select({
+    message: '如何处理已有文件?',
+    choices: [
+      { name: '覆盖已有文件 (overwrite)', value: 'overwrite', description: '删除现有文件，重新生成' },
+      { name: '跳过此步骤 (skip)', value: 'skip', description: '保留现有文件，不重新处理' },
+    ],
+  });
+  return { action: choice, path: proposedPath };
+}
+
+/**
+ * --input 模式的独立流水线
+ * 不通过 processOneTask（因为它依赖 findDownloadedFile 从 DOWNLOADS_DIR 找文件），
+ * 直接串联 step 函数，保证输入文件路径准确传递。
+ */
+async function runInputTask(opts) {
+  const {
+    inputPath, stem, sheetName, steps,
+    maxRetries, retryDelay, force,
+    transcodeTimeout, transcribeTimeout, analyzeTimeout,
+    whisperAvailable, fileInfo,
+  } = opts;
+
+  console.log(c('dim', '\n── 开始执行 ──\n'));
+
+  // ── download: 跳过（本地文件）──
+  console.log(`  [${stem}] 📥 下载: ${c('yellow', '已跳过 (本地文件)')}`);
+
+  // ── transcode ──
+  let tcFile = null;
+  if (steps.includes('transcode')) {
+    console.log(`  [${stem}] 🎵 开始转码...`);
+    try {
+      const { file, error } = await stepTranscode(inputPath, sheetName, maxRetries, retryDelay, force, transcodeTimeout);
+      tcFile = file;
+      if (file && fs.existsSync(file)) {
+        const size = (fs.statSync(file).size / 1024 / 1024).toFixed(1);
+        console.log(`  [${stem}] 🎵 转码完成: ${file} (${size} MB)`);
+      } else {
+        console.log(`  [${stem}] 🎵 转码: ${c(file ? 'yellow' : 'red', file ? '已跳过 (文件已存在)' : '失败 — ' + (error || ''))}`);
+      }
+    } catch (e) {
+      console.log(`  [${stem}] 🎵 转码: ${c('red', '异常 — ' + (e.message || '').slice(0, 200))}`);
+    }
+    if (!tcFile) {
+      console.log(c('yellow', '\n⚠️  转码未产出文件，后续步骤将跳过\n'));
+    }
+  } else if (steps.includes('transcribe')) {
+    // 无 transcode 步骤但有 transcribe：优先使用已有转码文件
+    const tcDir = path.join(TRANSCODED_DIR, sheetName);
+    const expectedTc = path.join(tcDir, stem + TRANSCODE_EXT);
+    if (fs.existsSync(expectedTc)) {
+      tcFile = expectedTc;
+      console.log(`  [${stem}] 🎵 转码: ${c('yellow', '使用已有文件 ' + path.basename(expectedTc))}`);
+    } else {
+      console.log(`  [${stem}] 🎵 转码: ${c('red', '未找到转码文件，将尝试用原始文件识别（可能失败）')}`);
+      tcFile = inputPath;
+    }
+  } else {
+    tcFile = inputPath;
+  }
+
+  // ── transcribe ──
+  let transcribeText = '';
+  if (steps.includes('transcribe') && tcFile) {
+    if (!whisperAvailable) {
+      console.log(`  [${stem}] 📝 识别: ${c('red', 'whisper 不可用')}`);
+    } else {
+      console.log(`  [${stem}] 📝 开始语音识别...`);
+      try {
+        const { text, error } = await stepTranscribe(tcFile, maxRetries, retryDelay, transcribeTimeout);
+        if (text && typeof text === 'string') {
+          transcribeText = text;
+          console.log(`  [${stem}] 📝 识别完成: ${text.length} 字符`);
+        } else {
+          console.log(`  [${stem}] 📝 识别: ${c('red', '失败 — ' + (error || ''))}`);
+        }
+      } catch (e) {
+        console.log(`  [${stem}] 📝 识别: ${c('red', '异常 — ' + (e.message || '').slice(0, 200))}`);
+      }
+    }
+  }
+
+  // ── AI analyze ──
+  let analyzeText = '';
+  if (steps.includes('analyze') && transcribeText) {
+    const aiEnabled = (process.env.AI_ENABLED || 'true').toLowerCase() === 'true';
+    if (aiEnabled) {
+      console.log(`  [${stem}] 🤖 开始 AI 分析...`);
+      try {
+        const { text: kw, error } = await stepAnalyze(transcribeText, maxRetries, retryDelay, analyzeTimeout);
+        if (kw && typeof kw === 'string') {
+          analyzeText = kw;
+          console.log(`  [${stem}] 🤖 AI分析完成: ${kw.length} 字符`);
+        } else {
+          console.log(`  [${stem}] 🤖 AI分析: ${c('red', '失败 — ' + (error || ''))}`);
+        }
+      } catch (e) {
+        console.log(`  [${stem}] 🤖 AI分析: ${c('red', '异常 — ' + (e.message || '').slice(0, 200))}`);
+      }
+    } else {
+      console.log(`  [${stem}] 🤖 AI分析: ${c('yellow', '已禁用 (AI_ENABLED=false)')}`);
+    }
+  }
+
+  // ── 保存文本结果 ──
+  if (transcribeText || analyzeText) {
+    const outDir = path.join(REPORTS_DIR, 'input-tasks');
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, `${stem}.txt`);
+    const lines = [
+      `文件: ${inputPath}`,
+      `平台: local`,
+      `文件格式: ${fileInfo.format || 'unknown'}`,
+      `时长: ${fileInfo.duration ? fileInfo.duration.toFixed(1) + 's' : 'unknown'}`,
+      '', '='.repeat(60), '',
+    ];
+    if (transcribeText) {
+      lines.push('【语音识别内容】', '', transcribeText, '');
+    }
+    if (analyzeText) {
+      lines.push('【AI 分析关键词】', '', analyzeText);
+    }
+    fs.writeFileSync(outFile, lines.join('\n'), 'utf-8');
+    console.log(`\n  📄 报告已保存: ${outFile}`);
+  }
+
+  // ── 总结 ──
+  console.log('');
+  const success = [];
+  if (tcFile) success.push('transcode');
+  if (transcribeText) success.push('transcribe');
+  if (analyzeText) success.push('analyze');
+  const failed = steps.filter(s => s !== 'download' && !success.includes(s));
+  if (failed.length === 0) {
+    console.log(c('green', '✅ 全部步骤执行成功'));
+  } else {
+    console.log(c('yellow', `⚠️  ${failed.length} 个步骤未成功: ${failed.join(', ')}`));
+  }
+  console.log('');
+}
+
+
 // ═══════════════════════════════════════════════════════════════════
 // URL 直链流水线（--url 模式）
 // ═══════════════════════════════════════════════════════════════════
@@ -1512,30 +1798,8 @@ async function run({
 
   logInfo(`tasks: ${tasks.length}, concurrency: ${concurrency}, max retries: ${maxRetries}`);
 
-  // ── 工具/服务预检 ──
   const envCheck = await checkEnvironmentAsync(steps);
-  if (!envCheck.allOk) {
-    console.log(`\n${'='.repeat(60)}`);
-    console.log('  ⚠️  工具/服务预检：以下依赖不可用');
-    console.log('='.repeat(60));
-    for (const issue of envCheck.issues) {
-      console.log(`  • ${issue}`);
-    }
-    console.log('\n  涉及的步骤将失败。');
-    if (!dryRun) {
-      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-      const answer = await new Promise(resolve => {
-        rl.question('\n  是否继续执行？(输入 yes 继续，其他任意键取消): ', ans => {
-          rl.close();
-          resolve(ans.trim().toLowerCase());
-        });
-      });
-      if (answer !== 'yes') {
-        logInfo('用户取消执行（工具不可用）');
-        return;
-      }
-    }
-  }
+  if (!await checkAndConfirmEnv(envCheck, dryRun, '是否继续执行？')) return;
 
   // ── 干跑模式 ──
   if (dryRun) {
@@ -1746,26 +2010,8 @@ async function runFromReport(reportPath, steps, maxRetries, retryDelay, concurre
     return;
   }
 
-  // ── 工具/服务预检 ──
   const envRfr = await checkEnvironmentAsync(steps);
-  if (!envRfr.allOk) {
-    console.log(`\n${'='.repeat(60)}`);
-    console.log('  ⚠️  工具/服务预检：以下依赖不可用');
-    console.log('='.repeat(60));
-    for (const issue of envRfr.issues) console.log(`  • ${issue}`);
-    console.log('\n  涉及的步骤将失败。');
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise(resolve => {
-      rl.question('\n  是否继续重跑？(输入 yes 继续，其他任意键取消): ', ans => {
-        rl.close();
-        resolve(ans.trim().toLowerCase());
-      });
-    });
-    if (answer !== 'yes') {
-      logInfo('用户取消重跑（工具不可用）');
-      return;
-    }
-  }
+  if (!await checkAndConfirmEnv(envRfr, dryRun, '是否继续重跑？')) return;
 
   let whisperAvailable = false;
   if (steps.includes('transcribe')) {
@@ -1823,13 +2069,13 @@ if (process.argv[1] === __filename || process.argv[1]?.endsWith('process_videos.
     .description('视频下载、转码、文本识别、AI分析一体化流程')
     .option('--sheet <name>', '指定 sheet 名称')
     .option('--id <id>', '指定 extra.id 或 title（单条测试）')
-    .option('--step <step>', '只执行某一步：download / transcode / transcribe / analyze', (val) => {
+    .option('--step <step>', '指定执行步骤（可多次指定），如 --step transcode --step transcribe', (val, prev) => {
       const allowed = ['download', 'transcode', 'transcribe', 'analyze'];
       if (!allowed.includes(val)) {
         console.error(`Invalid step: ${val}. Must be one of: ${allowed.join(', ')}`);
         process.exit(1);
       }
-      return val;
+      return [...(prev || []), val];
     })
     .option('--force', '强制重做下载+转码（忽略已有文件）')
     .option('--concurrency <n>', '并发数，默认 1', parseInt, 1)
@@ -1843,8 +2089,9 @@ if (process.argv[1] === __filename || process.argv[1]?.endsWith('process_videos.
     .option('--retry-failed <path>', '从报告 JSON 重跑失败项')
     .option('--init', '复制 .env.example 到当前目录并重命名为 .env')
     .option('--file <path>', '指定 Excel 文件路径（优先级高于 EXCEL_FILE 环境变量）')
+    .option('--input <path>', '指定本地视频文件路径（跳过下载，直接转码→识别→分析）')
     .option('--url <url>', '直接指定视频下载链接（跳过 Excel），支持标准链接和内嵌链接')
-    .option('--name <name>', '指定下载文件名，不含扩展名（与 --url 配合使用）')
+    .option('--name <name>', '指定输出文件名，不含扩展名（与 --url / --input 配合使用）')
     .option('--env-file <path>', '指定要加载的 .env 文件路径（默认: 当前目录 .env）');
 
   program.parse();
@@ -1906,7 +2153,7 @@ if (process.argv[1] === __filename || process.argv[1]?.endsWith('process_videos.
     EXCEL_FILE = path.resolve(opts.file);
     logInfo(`Excel 文件覆盖为: ${EXCEL_FILE}`);
   }
-  const steps = opts.step ? [opts.step] : ['download', 'transcode', 'transcribe', 'analyze'];
+  const steps = opts.step?.length ? opts.step : ['download', 'transcode', 'transcribe', 'analyze'];
   // ── --url 模式：直接处理单个视频链接 ──
   if (opts.url) {
     const parsed = parseUrl(opts.url);
@@ -1926,11 +2173,19 @@ if (process.argv[1] === __filename || process.argv[1]?.endsWith('process_videos.
     console.log(`  视频ID: ${c('cyan', parsed.videoId)}`);
     console.log(`  链接: ${c('cyan', parsed.watchUrl)}`);
 
-    // 构建文件路径: downloads/<platform>/<name>.mp4
+    // dry-run 模式
+    if (opts.dryRun) {
+      console.log(c('dim', '\n── 开始执行 (dry-run) ──\n'));
+      console.log(`  将执行步骤: ${c('cyan', steps.join(' → '))}`);
+      console.log(`  输出名称: ${c('cyan', opts.name || parsed.videoId)}`);
+      process.exit(0);
+    }
+
+    // 构建文件路径: output/downloads/<platform>/<name>.mp4
     fs.mkdirSync(DOWNLOADS_DIR, { recursive: true });
     const dlDir = path.join(DOWNLOADS_DIR, parsed.platform);
     fs.mkdirSync(dlDir, { recursive: true });
-    const fileName = opts.name || parsed.videoId;
+    const fileName = safeFilename(opts.name || parsed.videoId);
     const proposedPath = path.join(dlDir, `${fileName}.mp4`);
 
     // 冲突处理（--force 时直接覆盖）
@@ -1982,6 +2237,123 @@ if (process.argv[1] === __filename || process.argv[1]?.endsWith('process_videos.
     process.exit(0);
   }
 
+  // ── --input 模式：直接处理本地视频文件 ──
+  if (opts.input) {
+    const inputPath = path.resolve(opts.input);
+    console.log(c('dim', '\n── 文件校验 ──'));
+    console.log(`  文件: ${c('cyan', inputPath)}`);
+
+    const fileInfo = validateInputFile(inputPath);
+    if (!fileInfo.valid) {
+      console.log(c('red', `\n❌ 无法处理该文件:`));
+      for (const e of fileInfo.errors) {
+        console.log(c('red', `   ${e}`));
+      }
+      process.exit(1);
+    }
+
+    // 展示文件信息
+    console.log(`  格式: ${c('cyan', fileInfo.format || 'unknown')}`);
+    if (fileInfo.hasVideo) {
+      console.log(`  视频: ${c('cyan', fileInfo.videoCodec)} ${fileInfo.width}x${fileInfo.height}`);
+    }
+    if (fileInfo.hasAudio) {
+      console.log(`  音频: ${c('cyan', fileInfo.audioCodec)}`);
+    }
+    if (fileInfo.duration > 0) {
+      const dur = fileInfo.duration;
+      const mm = Math.floor(dur / 60);
+      const ss = Math.floor(dur % 60);
+      console.log(`  时长: ${c('cyan', `${mm}:${String(ss).padStart(2, '0')}`)} (${dur.toFixed(1)}s)`);
+    }
+    if (fileInfo.errors.length > 0) {
+      console.log('');
+      for (const e of fileInfo.errors) {
+        console.log(c('yellow', `  ⚠️  ${e}`));
+      }
+    }
+
+    // 展示可执行步骤
+    const defaultSteps = fileInfo.feasibleSteps;
+    // 用户可通过 --step 指定步骤，但只保留可行的
+    let steps;
+    if (opts.step?.length) {
+      steps = opts.step.filter(s => defaultSteps.includes(s));
+      if (steps.length === 0) {
+        console.log(c('yellow', `\n⚠️  --step ${opts.step.join(', ')} 不可行（文件不支持）\n`));
+        process.exit(1);
+      }
+    } else {
+      steps = defaultSteps;
+    }
+    console.log(`\n  可执行步骤: ${c('green', steps.join(' → '))}`);
+
+    // dry-run 模式
+    if (opts.dryRun) {
+      console.log(c('dim', '\n── 开始执行 (dry-run) ──\n'));
+      console.log(`  [本地文件] 将执行步骤: ${c('cyan', steps.join(' → '))}`);
+      console.log(`  输入文件: ${c('cyan', inputPath)}`);
+      if (opts.name) {
+        console.log(`  输出名称: ${c('cyan', opts.name)}`);
+      }
+      process.exit(0);
+    }
+
+    // 确定输出文件名
+    const sheetName = 'local';
+    const baseName = safeFilename(opts.name || path.parse(inputPath).name);
+    const stem = baseName;
+
+    // 检查转码输出文件是否已有冲突
+    if (steps.includes('transcode') && !opts.force) {
+      const tcDir = path.join(TRANSCODED_DIR, sheetName);
+      const tcPath = path.join(tcDir, stem + TRANSCODE_EXT);
+      const conflict = await resolveInputConflict(tcPath);
+      if (conflict.action === 'skip') {
+        console.log(c('yellow', '\n⏭️  已跳过转码\n'));
+        steps = steps.filter(s => s !== 'transcode');
+      }
+    }
+
+    if (steps.length === 0) {
+      console.log(c('yellow', '\n无剩余步骤可执行\n'));
+      process.exit(0);
+    }
+
+    // 确保目录存在
+    if (steps.includes('transcode')) {
+      fs.mkdirSync(path.join(TRANSCODED_DIR, sheetName), { recursive: true });
+    }
+
+    // 检查 whisper 可用性
+    let whisperAvailable = false;
+    if (steps.includes('transcribe')) {
+      whisperAvailable = await checkWhisperAvailable();
+      if (!whisperAvailable) {
+        const backend = WHISPER_BACKEND === 'local' ? 'local CLI' : WHISPER_SERVICE;
+        logWarn(`⚠️ whisper not available (${backend}), transcribe step will fail`);
+      }
+    }
+
+    // 执行流水线
+    await runInputTask({
+      inputPath,
+      stem,
+      sheetName,
+      steps,
+      maxRetries: opts.retry,
+      retryDelay: opts.retryDelay,
+      force: opts.force || false,
+      transcodeTimeout: opts.transcodeTimeout,
+      transcribeTimeout: opts.transcribeTimeout,
+      analyzeTimeout: opts.analyzeTimeout,
+      whisperAvailable,
+      fileInfo,
+    });
+
+    process.exit(0);
+  }
+
 
   run({
     targetSheet: opts.sheet || null,