vcshort 0.2.0__tar.gz

vcshort-0.2.0/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.4
+Name: vcshort
+Version: 0.2.0
+Summary: AI 短视频制作 CLI：剧本 → 资产 → 分镜 → 视频 → 合成
+Author: skywalker
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/itrxiAi/vc-short-plugin
+Project-URL: Repository, https://github.com/itrxiAi/vc-short-plugin
+Keywords: short-video,ai,storyboard,video-generation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: ruamel.yaml>=0.17
+Requires-Dist: opencv-python-headless<5,>=4.8
+Requires-Dist: imageio-ffmpeg>=0.4.9
+
+# vc-short-plugin
+
+AI 短视频制作插件（剧本 → 资产 → 分镜 → 视频 → 合成），支持 WorkBuddy、Devin、Claude Code、Cursor。
+
+## 安装
+
+分两部分：**CLI**（`vcshort` 命令，通过 pip 安装）和**插件**（`skills/` 目录，通过各 agent 的插件机制安装）。skill 里直接调用 `vcshort`，不依赖固定路径。
+
+### 1. 安装 Python
+
+- **Windows**：https://www.python.org/downloads/windows/ 下载 `python-3.x.x-amd64.exe`，安装时勾选 **Add Python to PATH**
+- **macOS**：`brew install python@3.12` 或从 python.org 下载安装包
+- **Linux**：`sudo apt install python3 python3-pip`
+
+### 2. 安装 vcshort CLI
+
+发布到 PyPI 后：
+
+```bash
+pip install vcshort
+```
+
+本地源码安装：
+
+```bash
+git clone https://github.com/itrxiAi/vc-short-plugin.git
+cd vc-short-plugin
+pip install -e .
+```
+
+### 3. 安装 agent 插件
+
+插件目录需要让 agent 能读到 `skills/` 下的 `SKILL.md`。
+
+### WorkBuddy
+
+WorkBuddy → 插件市场 → 添加市场 → 填入本仓库地址
+`https://github.com/itrxiAi/vc-short-plugin` → 搜索 `vc-short` → 安装
+（或 CLI 内：`/plugin marketplace add itrxiAi/vc-short-plugin` → `/plugin install vc-short@vc-short`）
+
+### Devin / Claude Code / Cursor
+
+指向仓库克隆目录（假设 clone 到 `~/vc-short-plugin`）：
+
+```bash
+# Devin CLI
+devin plugins install --local ~/vc-short-plugin
+
+# Claude Code（macOS/Linux）
+ln -s ~/vc-short-plugin ~/.claude/plugins/vc-short
+
+# Claude Code（Windows，cmd）
+mklink /J "%USERPROFILE%\.claude\plugins\vc-short" "%USERPROFILE%\vc-short-plugin"
+
+# Cursor：将 ~/vc-short-plugin 拷贝或链接到 ~/.cursor/plugins/local/vc-short
+```
+
+安装完成后在 agent 对话中调用 `/vc-short:init` 等技能即可。
+
+### 目录内容
+
+```
+vc-short-plugin/
+├── skills/          # 12 个技能（SKILL.md）
+├── agents/          # 子代理（script-reviewer）
+├── src/vcshort/     # CLI 源码
+├── pyproject.toml   # 包元数据与依赖
+├── requirements.txt # 依赖列表
+├── .codebuddy-plugin/marketplace.json   # WorkBuddy/CodeBuddy 插件市场清单
+└── plugin.json      # 插件清单（WorkBuddy / Claude Code / Devin 兼容）
+```
+
+### 本地构建与发布（可选）
+
+```bash
+git clone https://github.com/itrxiAi/vc-short-plugin.git
+cd vc-short-plugin
+./build.sh          # 构建 wheel/sdist 并本地验证
+```
+
+发布到 PyPI：
+
+```bash
+python -m twine upload dist/*
+```
+
+或打 tag 触发 GitHub Actions 自动发布（见 `.github/workflows/publish.yml`）。
+
+## 使用
+
+安装后技能通过 slash command 调用，建议按顺序执行：
+
+### `/vc-short:init <项目名>` — 初始化项目
+
+创建项目骨架目录。**产物：**
+
+- `<项目名>/config.yaml` — 全局配置（`style`、`aspect_ratio`、`api.api_key`）
+- `<项目名>/assets/` — 资产根目录（含 `characters/`、`scenes/`、`costumes/`、`props/` 子目录）
+- `<项目名>/chapters/` — 章节根目录
+
+执行后需准备 `chapters/ch01/novel.md`：可以直接粘贴小说原文，也可以用 `/vc-short:crawl-novel` 从阅读页爬取。
+
+### `/vc-short:crawl-novel` — 爬取小说章节
+
+用 Playwright 打开小说阅读页，带重叠滚动截图，再由 Agent 逐张读图转写。**产物：**
+
+- `chapters/<章节号>/novel.md` — 该章小说原文
+- `chapters/<章节号>/brief.md` — 该章简述（一句话梗概、出场人物、场景、主要事件、章末钩子）
+- 中间产物（截图、拼接预览图、crawl.json）放在 `<项目>/.crawl/ch<NN>/`，转写完成后删除；章节目录下保留 `novel.md` 和 `brief.md`
+
+阅读页正文用自定义字体混淆，DOM 文本不可用，因此必须读截图转写，不读 DOM、不调用 OCR。不绕过登录、验证码或付费墙，检测到付费墙即停止并报告。
+
+依赖**系统 `python3` + playwright**（插件便携 Python 不含）：`python3 -m pip install playwright && python3 -m playwright install chromium`。
+
+### `/vc-short:extract` — 提取角色/场景/道具
+
+从 `chapters/<章节号>/script.md` 提取角色、场景和道具，缺描述时按需 grep `novel.md` 搜名字补描述，与已有 `assets/` 目录匹配，用户确认后生成映射和 asset yaml。**产物：**
+
+- `chapters/<章节号>/extract.tmp.json` — 临时文件（LLM 生成 → 脚本写回 `matched` → 用户确认 → `--confirm` 后删除）
+- `chapters/<章节号>/character_map.yaml` — 角色映射（剧本角色名 → assets 目录名，最终版）
+- `chapters/<章节号>/scene_map.yaml` — 场景映射（剧本场景描述 → assets 目录名）
+- `chapters/<章节号>/prop_map.yaml` — 道具映射（剧本道具名 → assets 目录名）
+- `assets/characters/<名称>/character.yaml` — 角色档案（不覆盖已有）
+- `assets/scenes/<名称>/scene.yaml` — 场景档案（不覆盖已有）
+- `assets/props/<名称>/prop.yaml` — 道具档案（不覆盖已有）
+
+未匹配的新资产需用 `/vc-short:gen-image` 生成图片。
+
+### `/vc-short:gen-image` — 生成图片资产
+
+调用 doubao-seedream API 生成角色/服装/道具/场景图片，保存到 `assets/` 目录。**产物：**
+
+- 角色：`assets/characters/<角色名>/<角色名>.png`（默认形态）或 `<角色名>-<形态>.png`（其他形态）
+- 服装：`assets/costumes/<服装名>.png`
+- 道具：`assets/props/<道具名>.png`
+- 场景：`assets/scenes/<场景名>/<N>.png`（数字递增，支持多张）
+
+### `/vc-short:fix-image` — 修改图片
+
+基于原图 + 提示词调用 doubao-seededit API 编辑已有资产。**产物：**
+
+- 覆盖原图片文件（如 `assets/characters/<角色名>/<角色名>.png`）
+- `<原文件名>.png.bak` — 原图自动备份，不满意可恢复
+
+### `/vc-short:gen-script` — 改编剧本
+
+将 `chapters/<章节号>/novel.md` 改编为适合短视频的剧本。**产物：**
+
+- `chapters/<章节号>/script.md` — 改编剧本（场景用 `## SC001 内 · 地点 · 时间` 标题分隔，按戏剧工作切场景，不按时长；支持 `[连续性]`/`[画面文字]`/`[转场]` 生产标签）
+
+### `/vc-short:gen-shots` — 拆分分镜
+
+按镜头职责拆分：每镜有唯一职责（本镜结束时观众知道了什么变化）、`起点 → 唯一动作 → 终点` 状态链、对白估时定档（5/10/15 秒）、冻结首帧提示词。LLM 直接写 Markdown 分镜文档，CLI 编译为 shot YAML。**产物：**
+
+- `chapters/<章节号>/shots.md` — 分镜文档（drama 风格 `## SHOT-场序-镜序` 块，人可读的创作产物，保留不删）
+- `chapters/<章节号>/shots/shot_001_01/shot.yaml` — 分镜参数（`source`、`purpose`、`script_segment`、`action`、`keyframe_prompt`、`end_state`、`characters`、`scene`、`camera`、`status: pending`）
+- `chapters/<章节号>/shots/shot_001_02/shot.yaml` — 同主号 = 「同一地点 + 同一批角色」的连续分镜，子号递增
+- `chapters/<章节号>/shots/shot_002_01/shot.yaml` — 地点或角色组变化后开新主号
+
+### `/vc-short:gen-video` — 生成分镜视频
+
+调用图生视频 API，将分镜 YAML 转为视频，并提取首尾帧保持分镜连贯。首帧优先用 `keyframe.png`（可用 `--with-keyframe` 按 `keyframe_prompt` 自动生成），无首帧图时用上一镜尾帧保持连贯。**产物：**
+
+- `chapters/<章节号>/shots/shot_<N>/shot.mp4` — 分镜视频（5/10/15 秒，分辨率 720p）
+- `chapters/<章节号>/shots/shot_<N>/keyframe.png` — 首帧图（可选，`--with-keyframe` 自动生成）
+- `chapters/<章节号>/shots/shot_<N>/first_frame.png` — 视频首帧
+- `chapters/<章节号>/shots/shot_<N>/last_frame.png` — 视频尾帧（下一分镜生成时作为参考图）
+
+### `/vc-short:compose-chapter` — 合成章节视频
+
+用 ffmpeg concat 按分镜号顺序拼接章节下所有 `shot.mp4`。**产物：**
+
+- `chapters/<章节号>/chapter.mp4` — 章节完整视频（可用 `--output` 自定义文件名）
+
+### `/vc-short:config-manager list` — 列出资产
+
+扫描 `assets/` 目录，按角色/场景/服装/道具分类列出已有资产及图片数量，不产生文件，仅打印到终端。
+
+## 目录结构
+
+```
+vc-short-plugin/
+├── .devin-plugin/
+│   └── plugin.json          # Devin 插件清单
+├── .claude-plugin/
+│   └── plugin.json          # Claude Code / WorkBuddy 插件清单
+├── plugin.json              # Cursor / Agent Plugins 清单
+├── skills/                  # 12 个技能
+│   ├── init/SKILL.md
+│   ├── crawl-novel/SKILL.md
+│   ├── extract/SKILL.md
+│   ├── gen-character/SKILL.md
+│   ├── gen-image/SKILL.md
+│   ├── fix-image/SKILL.md
+│   ├── gen-voice/SKILL.md
+│   ├── gen-script/SKILL.md
+│   ├── gen-shots/SKILL.md
+│   ├── gen-video/SKILL.md
+│   ├── compose-chapter/SKILL.md
+│   └── config-manager/SKILL.md
+├── agents/                  # 子代理定义
+├── src/vcshort/             # Python CLI 源码
+│   ├── cli.py               # 主入口（subparsers 分发）
+│   ├── init.py
+│   ├── extract.py
+│   ├── gen_image.py
+│   ├── fix_image.py
+│   ├── gen_voice.py
+│   ├── gen_shots.py
+│   ├── gen_video.py
+│   ├── compose_chapter.py
+│   └── config_manager.py
+├── build.sh                 # 本地构建脚本：生成 wheel/sdist 并验证
+├── pyproject.toml           # 包元数据、依赖与 console_scripts 入口
+├── requirements.txt         # 依赖列表（与 pyproject.toml 同步）
+└── README.md
+```
+
+## 工作原理
+
+- 用户机器需自行安装 **Python 3.10+**
+- `pip install vcshort` 后，`vcshort` 命令加入 PATH，skill 里直接调用
+- `src/vcshort/__main__.py` 是 `python -m vcshort` 入口；`vcshort` 命令由 `pyproject.toml` 的 `[project.scripts]` 注册
+- 技能目录（`skills/`）由各 agent 的插件机制加载；skill 与 CLI 通过 `vcshort` 命令解耦
+- CI 按 tag 触发：
+  - `.github/workflows/build.yml` 验证源码并打包 wheel
+  - `.github/workflows/publish.yml` 把 wheel 上传到 PyPI
+
+## 依赖
+
+- 系统 Python 3.10+ 及 `pyproject.toml` 中的包：`requests`、`PyYAML`、`ruamel.yaml`、`opencv-python-headless`、`imageio-ffmpeg`
+- 火山引擎方舟 API Key（填入项目的 `config.yaml`）

vcshort-0.2.0/README.md

@@ -0,0 +1,232 @@
+# vc-short-plugin
+
+AI 短视频制作插件（剧本 → 资产 → 分镜 → 视频 → 合成），支持 WorkBuddy、Devin、Claude Code、Cursor。
+
+## 安装
+
+分两部分：**CLI**（`vcshort` 命令，通过 pip 安装）和**插件**（`skills/` 目录，通过各 agent 的插件机制安装）。skill 里直接调用 `vcshort`，不依赖固定路径。
+
+### 1. 安装 Python
+
+- **Windows**：https://www.python.org/downloads/windows/ 下载 `python-3.x.x-amd64.exe`，安装时勾选 **Add Python to PATH**
+- **macOS**：`brew install python@3.12` 或从 python.org 下载安装包
+- **Linux**：`sudo apt install python3 python3-pip`
+
+### 2. 安装 vcshort CLI
+
+发布到 PyPI 后：
+
+```bash
+pip install vcshort
+```
+
+本地源码安装：
+
+```bash
+git clone https://github.com/itrxiAi/vc-short-plugin.git
+cd vc-short-plugin
+pip install -e .
+```
+
+### 3. 安装 agent 插件
+
+插件目录需要让 agent 能读到 `skills/` 下的 `SKILL.md`。
+
+### WorkBuddy
+
+WorkBuddy → 插件市场 → 添加市场 → 填入本仓库地址
+`https://github.com/itrxiAi/vc-short-plugin` → 搜索 `vc-short` → 安装
+（或 CLI 内：`/plugin marketplace add itrxiAi/vc-short-plugin` → `/plugin install vc-short@vc-short`）
+
+### Devin / Claude Code / Cursor
+
+指向仓库克隆目录（假设 clone 到 `~/vc-short-plugin`）：
+
+```bash
+# Devin CLI
+devin plugins install --local ~/vc-short-plugin
+
+# Claude Code（macOS/Linux）
+ln -s ~/vc-short-plugin ~/.claude/plugins/vc-short
+
+# Claude Code（Windows，cmd）
+mklink /J "%USERPROFILE%\.claude\plugins\vc-short" "%USERPROFILE%\vc-short-plugin"
+
+# Cursor：将 ~/vc-short-plugin 拷贝或链接到 ~/.cursor/plugins/local/vc-short
+```
+
+安装完成后在 agent 对话中调用 `/vc-short:init` 等技能即可。
+
+### 目录内容
+
+```
+vc-short-plugin/
+├── skills/          # 12 个技能（SKILL.md）
+├── agents/          # 子代理（script-reviewer）
+├── src/vcshort/     # CLI 源码
+├── pyproject.toml   # 包元数据与依赖
+├── requirements.txt # 依赖列表
+├── .codebuddy-plugin/marketplace.json   # WorkBuddy/CodeBuddy 插件市场清单
+└── plugin.json      # 插件清单（WorkBuddy / Claude Code / Devin 兼容）
+```
+
+### 本地构建与发布（可选）
+
+```bash
+git clone https://github.com/itrxiAi/vc-short-plugin.git
+cd vc-short-plugin
+./build.sh          # 构建 wheel/sdist 并本地验证
+```
+
+发布到 PyPI：
+
+```bash
+python -m twine upload dist/*
+```
+
+或打 tag 触发 GitHub Actions 自动发布（见 `.github/workflows/publish.yml`）。
+
+## 使用
+
+安装后技能通过 slash command 调用，建议按顺序执行：
+
+### `/vc-short:init <项目名>` — 初始化项目
+
+创建项目骨架目录。**产物：**
+
+- `<项目名>/config.yaml` — 全局配置（`style`、`aspect_ratio`、`api.api_key`）
+- `<项目名>/assets/` — 资产根目录（含 `characters/`、`scenes/`、`costumes/`、`props/` 子目录）
+- `<项目名>/chapters/` — 章节根目录
+
+执行后需准备 `chapters/ch01/novel.md`：可以直接粘贴小说原文，也可以用 `/vc-short:crawl-novel` 从阅读页爬取。
+
+### `/vc-short:crawl-novel` — 爬取小说章节
+
+用 Playwright 打开小说阅读页，带重叠滚动截图，再由 Agent 逐张读图转写。**产物：**
+
+- `chapters/<章节号>/novel.md` — 该章小说原文
+- `chapters/<章节号>/brief.md` — 该章简述（一句话梗概、出场人物、场景、主要事件、章末钩子）
+- 中间产物（截图、拼接预览图、crawl.json）放在 `<项目>/.crawl/ch<NN>/`，转写完成后删除；章节目录下保留 `novel.md` 和 `brief.md`
+
+阅读页正文用自定义字体混淆，DOM 文本不可用，因此必须读截图转写，不读 DOM、不调用 OCR。不绕过登录、验证码或付费墙，检测到付费墙即停止并报告。
+
+依赖**系统 `python3` + playwright**（插件便携 Python 不含）：`python3 -m pip install playwright && python3 -m playwright install chromium`。
+
+### `/vc-short:extract` — 提取角色/场景/道具
+
+从 `chapters/<章节号>/script.md` 提取角色、场景和道具，缺描述时按需 grep `novel.md` 搜名字补描述，与已有 `assets/` 目录匹配，用户确认后生成映射和 asset yaml。**产物：**
+
+- `chapters/<章节号>/extract.tmp.json` — 临时文件（LLM 生成 → 脚本写回 `matched` → 用户确认 → `--confirm` 后删除）
+- `chapters/<章节号>/character_map.yaml` — 角色映射（剧本角色名 → assets 目录名，最终版）
+- `chapters/<章节号>/scene_map.yaml` — 场景映射（剧本场景描述 → assets 目录名）
+- `chapters/<章节号>/prop_map.yaml` — 道具映射（剧本道具名 → assets 目录名）
+- `assets/characters/<名称>/character.yaml` — 角色档案（不覆盖已有）
+- `assets/scenes/<名称>/scene.yaml` — 场景档案（不覆盖已有）
+- `assets/props/<名称>/prop.yaml` — 道具档案（不覆盖已有）
+
+未匹配的新资产需用 `/vc-short:gen-image` 生成图片。
+
+### `/vc-short:gen-image` — 生成图片资产
+
+调用 doubao-seedream API 生成角色/服装/道具/场景图片，保存到 `assets/` 目录。**产物：**
+
+- 角色：`assets/characters/<角色名>/<角色名>.png`（默认形态）或 `<角色名>-<形态>.png`（其他形态）
+- 服装：`assets/costumes/<服装名>.png`
+- 道具：`assets/props/<道具名>.png`
+- 场景：`assets/scenes/<场景名>/<N>.png`（数字递增，支持多张）
+
+### `/vc-short:fix-image` — 修改图片
+
+基于原图 + 提示词调用 doubao-seededit API 编辑已有资产。**产物：**
+
+- 覆盖原图片文件（如 `assets/characters/<角色名>/<角色名>.png`）
+- `<原文件名>.png.bak` — 原图自动备份，不满意可恢复
+
+### `/vc-short:gen-script` — 改编剧本
+
+将 `chapters/<章节号>/novel.md` 改编为适合短视频的剧本。**产物：**
+
+- `chapters/<章节号>/script.md` — 改编剧本（场景用 `## SC001 内 · 地点 · 时间` 标题分隔，按戏剧工作切场景，不按时长；支持 `[连续性]`/`[画面文字]`/`[转场]` 生产标签）
+
+### `/vc-short:gen-shots` — 拆分分镜
+
+按镜头职责拆分：每镜有唯一职责（本镜结束时观众知道了什么变化）、`起点 → 唯一动作 → 终点` 状态链、对白估时定档（5/10/15 秒）、冻结首帧提示词。LLM 直接写 Markdown 分镜文档，CLI 编译为 shot YAML。**产物：**
+
+- `chapters/<章节号>/shots.md` — 分镜文档（drama 风格 `## SHOT-场序-镜序` 块，人可读的创作产物，保留不删）
+- `chapters/<章节号>/shots/shot_001_01/shot.yaml` — 分镜参数（`source`、`purpose`、`script_segment`、`action`、`keyframe_prompt`、`end_state`、`characters`、`scene`、`camera`、`status: pending`）
+- `chapters/<章节号>/shots/shot_001_02/shot.yaml` — 同主号 = 「同一地点 + 同一批角色」的连续分镜，子号递增
+- `chapters/<章节号>/shots/shot_002_01/shot.yaml` — 地点或角色组变化后开新主号
+
+### `/vc-short:gen-video` — 生成分镜视频
+
+调用图生视频 API，将分镜 YAML 转为视频，并提取首尾帧保持分镜连贯。首帧优先用 `keyframe.png`（可用 `--with-keyframe` 按 `keyframe_prompt` 自动生成），无首帧图时用上一镜尾帧保持连贯。**产物：**
+
+- `chapters/<章节号>/shots/shot_<N>/shot.mp4` — 分镜视频（5/10/15 秒，分辨率 720p）
+- `chapters/<章节号>/shots/shot_<N>/keyframe.png` — 首帧图（可选，`--with-keyframe` 自动生成）
+- `chapters/<章节号>/shots/shot_<N>/first_frame.png` — 视频首帧
+- `chapters/<章节号>/shots/shot_<N>/last_frame.png` — 视频尾帧（下一分镜生成时作为参考图）
+
+### `/vc-short:compose-chapter` — 合成章节视频
+
+用 ffmpeg concat 按分镜号顺序拼接章节下所有 `shot.mp4`。**产物：**
+
+- `chapters/<章节号>/chapter.mp4` — 章节完整视频（可用 `--output` 自定义文件名）
+
+### `/vc-short:config-manager list` — 列出资产
+
+扫描 `assets/` 目录，按角色/场景/服装/道具分类列出已有资产及图片数量，不产生文件，仅打印到终端。
+
+## 目录结构
+
+```
+vc-short-plugin/
+├── .devin-plugin/
+│   └── plugin.json          # Devin 插件清单
+├── .claude-plugin/
+│   └── plugin.json          # Claude Code / WorkBuddy 插件清单
+├── plugin.json              # Cursor / Agent Plugins 清单
+├── skills/                  # 12 个技能
+│   ├── init/SKILL.md
+│   ├── crawl-novel/SKILL.md
+│   ├── extract/SKILL.md
+│   ├── gen-character/SKILL.md
+│   ├── gen-image/SKILL.md
+│   ├── fix-image/SKILL.md
+│   ├── gen-voice/SKILL.md
+│   ├── gen-script/SKILL.md
+│   ├── gen-shots/SKILL.md
+│   ├── gen-video/SKILL.md
+│   ├── compose-chapter/SKILL.md
+│   └── config-manager/SKILL.md
+├── agents/                  # 子代理定义
+├── src/vcshort/             # Python CLI 源码
+│   ├── cli.py               # 主入口（subparsers 分发）
+│   ├── init.py
+│   ├── extract.py
+│   ├── gen_image.py
+│   ├── fix_image.py
+│   ├── gen_voice.py
+│   ├── gen_shots.py
+│   ├── gen_video.py
+│   ├── compose_chapter.py
+│   └── config_manager.py
+├── build.sh                 # 本地构建脚本：生成 wheel/sdist 并验证
+├── pyproject.toml           # 包元数据、依赖与 console_scripts 入口
+├── requirements.txt         # 依赖列表（与 pyproject.toml 同步）
+└── README.md
+```
+
+## 工作原理
+
+- 用户机器需自行安装 **Python 3.10+**
+- `pip install vcshort` 后，`vcshort` 命令加入 PATH，skill 里直接调用
+- `src/vcshort/__main__.py` 是 `python -m vcshort` 入口；`vcshort` 命令由 `pyproject.toml` 的 `[project.scripts]` 注册
+- 技能目录（`skills/`）由各 agent 的插件机制加载；skill 与 CLI 通过 `vcshort` 命令解耦
+- CI 按 tag 触发：
+  - `.github/workflows/build.yml` 验证源码并打包 wheel
+  - `.github/workflows/publish.yml` 把 wheel 上传到 PyPI
+
+## 依赖
+
+- 系统 Python 3.10+ 及 `pyproject.toml` 中的包：`requests`、`PyYAML`、`ruamel.yaml`、`opencv-python-headless`、`imageio-ffmpeg`
+- 火山引擎方舟 API Key（填入项目的 `config.yaml`）

vcshort-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcshort"
+version = "0.2.0"
+description = "AI 短视频制作 CLI：剧本 → 资产 → 分镜 → 视频 → 合成"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    {name = "skywalker"},
+]
+keywords = ["short-video", "ai", "storyboard", "video-generation"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "requests>=2.28",
+    "PyYAML>=6.0",
+    "ruamel.yaml>=0.17",
+    "opencv-python-headless>=4.8,<5",
+    "imageio-ffmpeg>=0.4.9",
+]
+
+[project.scripts]
+vcshort = "vcshort.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/itrxiAi/vc-short-plugin"
+Repository = "https://github.com/itrxiAi/vc-short-plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

vcshort-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcshort-0.2.0/src/vcshort/__init__.py

@@ -0,0 +1,3 @@
+"""vcshort — AI 短视频制作 CLI。"""
+
+__version__ = "0.1.0"

vcshort-0.2.0/src/vcshort/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from vcshort.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

vcshort-0.2.0/src/vcshort/apply_flashback_fog.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""回忆/闪回视频后处理：给画面边缘叠加一圈白色雾气。"""
+
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+try:
+    import cv2
+    import numpy as np
+except ImportError:
+    cv2 = None
+    np = None
+
+
+def _has_ffmpeg() -> bool:
+    try:
+        subprocess.run(["ffmpeg", "-version"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        return True
+    except Exception:
+        return False
+
+
+def apply_flashback_fog(
+    video_path: str | Path,
+    output_path: str | Path | None = None,
+    inner: float = 0.55,
+    outer: float = 1.0,
+    max_alpha: float = 0.75,
+    gamma: float = 2.0,
+) -> Path:
+    """给视频叠加边缘白雾，返回输出视频路径。
+
+    参数（已按 004_01 效果固定）：
+      - inner: 中心清晰区半径比例（0~1），默认 0.55
+      - outer: 雾完全覆盖区半径比例，默认 1.0
+      - max_alpha: 边缘最大雾浓度，默认 0.75
+      - gamma: 雾浓度曲线幂次，默认 2.0（越靠边越浓）
+    """
+    if cv2 is None or np is None:
+        print("错误：回忆雾效需要 opencv-python 和 numpy，请安装：pip install opencv-python numpy", file=sys.stderr)
+        sys.exit(1)
+    if not _has_ffmpeg():
+        print("错误：回忆雾效需要 ffmpeg", file=sys.stderr)
+        sys.exit(1)
+
+    video_path = Path(video_path)
+    if output_path is None:
+        output_path = video_path
+    else:
+        output_path = Path(output_path)
+
+    # 临时文件
+    tmp_dir = Path(tempfile.gettempdir())
+    video_no_audio = tmp_dir / f"{video_path.stem}_fog_no_audio.mp4"
+    audio_path = tmp_dir / f"{video_path.stem}_audio.aac"
+
+    try:
+        # 提取音频
+        subprocess.run(
+            ["ffmpeg", "-y", "-i", str(video_path), "-vn", "-c:a", "copy", str(audio_path)],
+            check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+        )
+
+        # 读取视频
+        cap = cv2.VideoCapture(str(video_path))
+        if not cap.isOpened():
+            print(f"错误：无法打开视频 {video_path}", file=sys.stderr)
+            sys.exit(1)
+
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        out = cv2.VideoWriter(str(video_no_audio), fourcc, fps, (w, h))
+
+        # 径向雾遮罩：中心清晰，边缘白色
+        x = np.linspace(-1, 1, w)
+        y = np.linspace(-1, 1, h)
+        xx, yy = np.meshgrid(x, y)
+        dist = np.sqrt(xx**2 + yy**2)
+        alpha = np.clip((dist - inner) / (outer - inner), 0, 1)
+        alpha = (alpha ** gamma) * max_alpha
+        alpha = alpha[:, :, np.newaxis].astype(np.float32)
+
+        frame_count = 0
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+            frame_f = frame.astype(np.float32)
+            fogged = frame_f * (1 - alpha) + 255.0 * alpha
+            fogged = np.clip(fogged, 0, 255).astype(np.uint8)
+            out.write(fogged)
+            frame_count += 1
+
+        cap.release()
+        out.release()
+        print(f"回忆雾效处理 {frame_count} 帧")
+
+        # 合并音频
+        subprocess.run(
+            [
+                "ffmpeg", "-y",
+                "-i", str(video_no_audio),
+                "-i", str(audio_path),
+                "-c:v", "libx264", "-c:a", "copy",
+                "-pix_fmt", "yuv420p",
+                "-shortest",
+                str(output_path),
+            ],
+            check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE,
+        )
+        print(f"已保存回忆雾效视频: {output_path}")
+    finally:
+        # 清理临时文件
+        if video_no_audio.exists():
+            video_no_audio.unlink()
+        if audio_path.exists():
+            audio_path.unlink()
+
+    return output_path
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="apply_flashback_fog", description="给视频叠加回忆白雾")
+    parser.add_argument("video", help="输入视频路径")
+    parser.add_argument("-o", "--output", default=None, help="输出路径（默认覆盖输入）")
+    args = parser.parse_args(argv)
+    apply_flashback_fog(args.video, args.output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())