skills/unnoo__zsxq-skill
1
0
Fork 0
mirror of https://github.com/unnoo/zsxq-skill.git synced 2026-09-14 19:59:58 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix(scenario): generate-video 路径去硬编码、去平台化

Browse Source 
路径修改：
- ~/.claude/skills/zsxq/scripts/ 全部改为 skill 根目录相对路径
  （scripts/scenarios/generate-video/），不依赖 Claude Code 安装路径
- ~/Desktop/内容雷达/ 全部改为用户指定的输出目录，
  默认 /tmp/zsxq-video-<slug>/，跨平台可用
- Chrome 路径给出多平台常见值（macOS/Linux/Windows）
  而非只写 macOS 绝对路径
- 文档顶部新增说明：所有文件路径相对于 skill 根目录

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
zhuguojie
2026-07-31 12:32:35 +08:00
parent 225709fd80
commit 04ec5aa5e6
1 changed files with 44 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/zsxq/references/scenarios/generate-video.md
+44 -32
View File
@@ -3,10 +3,12 @@
把知识星球的帖子/文章内容转为**竖版动画视频**（2160×3840，9:16，~17-21s），适合发布到抖音、视频号、小红书。AI 提炼内容为结构化脚本，通过内置渲染脚本生成动画 HTML，可选录制 4K MP4。
> **依赖**：本场景需 Node.js ≥ 18；MP4 录制另需 ffmpeg + puppeteer。详见「所需输入」环境依赖。
>
> **所有文件路径均相对于 skill 根目录**（即 `SKILL.md` 所在目录）。如场景文档位于 `references/scenarios/generate-video.md`，则 `../../scripts/` 指向 `scripts/scenarios/generate-video/`。
> [!CAUTION]
> - **视频生成涉及 LLM 对内容的提炼和改写**：AI 提炼后的脚本可能改变原文语气或强调方向，生成前必须向用户展示脚本预览并等待确认
> - **输出文件在本机，不向星球发布任何内容**：动画 HTML 和 MP4 保存在本地 `~/Desktop/内容雷达/` 目录，不会写回知识星球
> - **输出文件在本机，不向星球发布任何内容**：动画 HTML 和 MP4 保存在用户指定的输出目录（默认临时目录），不会写回知识星球
> - **确保有转载/改编原文内容的权利**：视频素材来源于星球成员帖子，星主应确认帖子授权范围再制作视频
## 适用意图
@@ -34,14 +36,14 @@
| 星球（group_id 或星球名） | 内容来源是帖子时**是** | 帖子所属的星球。只给名称时先用 `group +list` 解析 group_id |
| 作者名 | 否 | 显示在视频封面上的作者昵称（取自 `topic +detail` 的 `owner.name` 或 `owner.alias`，用户也可覆盖） |
| 品牌色 | 否 | 视频主题色（十六进制，不指定时用默认品牌色） |
| 保存目录 | 否 | 默认 `~/Desktop/内容雷达/`；用户可指定其它路径 |
| 输出目录 | 否 | 默认 `/tmp/zsxq-video-<slug>/`；用户可指定其它路径 |
**环境依赖（本场景专属，非全 skill 必需）**：
| 依赖 | 必须？ | 安装方式 | 说明 |
|------|--------|---------|------|
| Node.js ≥ 18 | **是** | `node --version` 确认 | 运行渲染脚本 |
| npm install（脚本依赖） | 否（仅 MP4） | `cd ~/.claude/skills/zsxq/scripts/scenarios/generate-video && npm install` | 安装 puppeteer。首次安装可用 `PUPPETEER_SKIP_DOWNLOAD=true npm install` 跳过 Chromium 下载，然后用系统已装的 Chrome |
| npm install（脚本依赖） | 否（仅 MP4） | 在 `scripts/scenarios/generate-video/` 目录下 `npm install` | 安装 puppeteer。首次安装可用 `PUPPETEER_SKIP_DOWNLOAD=true npm install` 跳过 Chromium 下载，然后用系统已装的 Chrome |
| ffmpeg | 否（仅 MP4） | `brew install ffmpeg` | 视频编码 |
## 使用的原子操作
@@ -53,7 +55,7 @@
| `topic +detail` | [../topic-detail.md](../topic-detail.md) | 取选定帖子的完整正文（`content` 字段）、作者（`owner.name`/`owner.alias`）、标题（`title`） |
| `topic +search` | [../topic-search.md](../topic-search.md) | 按关键词搜索特定内容 |
场景专属处理（非 CLI 操作）：AI 内容提炼与 JSON 结构化（规则见 [refinement-rules](generate-video/refinement-rules.md)）；渲染动画 HTML 与录制 MP4 由本场景内置脚本完成。
场景专属处理（非 CLI 操作）：AI 内容提炼与 JSON 结构化（规则见 [refinement-rules](generate-video/refinement-rules.md)）；渲染动画 HTML 与录制 MP4 由 `scripts/scenarios/generate-video/` 下的内置脚本完成。
## 执行流程
@@ -63,7 +65,7 @@
```bash
node --version # 应 ≥ v18
ls ~/.claude/skills/zsxq/scripts/scenarios/generate-video/render.js
# 检查 skill 根目录下的 scripts/scenarios/generate-video/render.js 是否存在
```
- **成功**：继续
@@ -73,7 +75,7 @@ ls ~/.claude/skills/zsxq/scripts/scenarios/generate-video/render.js
如果用户后续要录制 MP4，再检查：
```bash
ls ~/.claude/skills/zsxq/scripts/scenarios/generate-video/node_modules/puppeteer # puppeteer 是否已安装
# puppeteer 是否已安装在 scripts/scenarios/generate-video/node_modules/
which ffmpeg # ffmpeg 是否可用
```
@@ -140,19 +142,22 @@ zsxq-cli topic +detail --topic-id <TOPIC_ID> --json
用户确认脚本后：
```bash
# 1. 将 JSON 写入文件
# （Write 工具写入 ~/Desktop/内容雷达/<slug>.json）
# 1. 确定输出目录（用户指定，或默认 /tmp/zsxq-video-<slug>/）
mkdir -p <OUT_DIR>
# 2. 渲染动画 HTML（结构化模板）
node ~/.claude/skills/zsxq/scripts/scenarios/generate-video/render.js \
~/Desktop/内容雷达/<slug>.json \
~/Desktop/内容雷达/<slug>.html
# 2. 将 JSON 写入 <OUT_DIR>/script.json
# 3. 浏览器预览
open ~/Desktop/内容雷达/<slug>.html
# 3. 渲染动画 HTML（结构化模板）
node scripts/scenarios/generate-video/render.js \
<OUT_DIR>/script.json \
<OUT_DIR>/output.html
# 4. 浏览器预览
open <OUT_DIR>/output.html
```
- `render.js` 为结构化模板（4 页）；金句模板用 `render-minimal.js`
- 路径 `scripts/scenarios/generate-video/` 相对于 skill 根目录，下同
- render.js 成功 → 打开浏览器让用户预览动画效果
- 用户不满意动画 → 返回第 3 步修改 JSON 后重新渲染
- 用户满意 → 问是否要录制 MP4
@@ -161,24 +166,27 @@ open ~/Desktop/内容雷达/<slug>.html
用户想要最终视频文件时：
> 需已安装 puppeteer + ffmpeg（见环境依赖）。如果系统已装有 Google Chrome，可跳过 Chromium 下载，用系统 Chrome 录制。
> 需已安装 puppeteer + ffmpeg（见环境依赖）。如果系统已装有 Chrome，可跳过 Chromium 下载，用系统 Chrome 录制。
```bash
# 1. 封面截图
PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
node ~/.claude/skills/zsxq/scripts/scenarios/generate-video/record.js \
~/Desktop/内容雷达/<slug>.html \
~/Desktop/内容雷达/<slug>-cover.png --cover
PUPPETEER_EXECUTABLE_PATH="<系统 Chrome 路径>" \
node scripts/scenarios/generate-video/record.js \
<OUT_DIR>/output.html \
<OUT_DIR>/cover.png --cover
# 2. 录制完整视频
PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
node ~/.claude/skills/zsxq/scripts/scenarios/generate-video/record.js \
~/Desktop/内容雷达/<slug>.html \
~/Desktop/内容雷达/<slug>-4k.mp4 \
PUPPETEER_EXECUTABLE_PATH="<系统 Chrome 路径>" \
node scripts/scenarios/generate-video/record.js \
<OUT_DIR>/output.html \
<OUT_DIR>/output-4k.mp4 \
17 # 时长：2 + (页数-1) × 5
```
录制使用虚拟时钟（确定性帧同步），约需 1–2 分钟。
录制使用虚拟时钟（确定性帧同步），约需 1–2 分钟。`<系统 Chrome 路径>` 常见值：
- macOS：`/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
- Linux：`/usr/bin/google-chrome`
- Windows：`C:\Program Files\Google\Chrome\Application\chrome.exe`
## 分支与停止条件
@@ -189,7 +197,7 @@ PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google
- **帖子过长（> 1500 字）**：AI 只取核心论点，不试图覆盖全文
- **内容来源为纯链接分享/纯数据/无文字**：告知不适合做视频
- **AI 提炼被用户多次退回**（超过 3 轮修改）：建议换帖子或手动写脚本
- **record.js 缺失依赖**（puppeteer/ffmpeg 未装）：告知用户缺少什么，问是安装依赖还是只要 HTML。如果 puppeteer 已装但找不到 Chromium，提示设置 `PUPPETEER_EXECUTABLE_PATH` 指向系统 Chrome
- **record.js 缺失依赖**（puppeteer/ffmpeg 未装）：告知用户缺少什么，问是安装依赖还是只要 HTML。如果 puppeteer 已装但找不到 Chrome，提示设置 `PUPPETEER_EXECUTABLE_PATH` 指向系统 Chrome
- **录制失败**：保留 HTML 文件，不阻塞
- **限流（API 调用的 429 / frequently）**：退避几秒重试，不循环猛刷
- **用户只要预览、不要视频**：停在 HTML 预览阶段结束
@@ -198,15 +206,16 @@ PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google
1. **选帖确认**（场景 B）：列出候选帖子后，用户明确选择要处理哪一篇
2. **脚本预览确认**：AI 提炼后的 JSON 脚本展示给用户，确认或修改后才渲染（核心确认点——提炼可能改变原文语气）
3. **录制 MP4 前**：告知 MP4 录制需 1–2 分钟，询问是否确认（较大资源消耗）
4. **降级确认**：环境不满足录制条件时，确认是否接受仅 HTML 输出
3. **输出目录确认**：用户未指定时告知默认路径 `/tmp/zsxq-video-<slug>/`，询问是否需要更改
4. **录制 MP4 前**：告知 MP4 录制需 1–2 分钟，询问是否确认（较大资源消耗）
5. **降级确认**：环境不满足录制条件时，确认是否接受仅 HTML 输出
## 完成标准
- AI 已按 [refinement-rules](generate-video/refinement-rules.md) 完成内容提炼，输出符合 schema 的结构化 JSON
- 脚本预览已经用户确认（至少一轮确认通过）
- `render.js` / `render-minimal.js` 成功输出动画 HTML 至用户目录（含 open 预览）
- （可选）`record.js` 成功录制 4K MP4 至用户目录
- `render.js` / `render-minimal.js` 成功输出动画 HTML 至输出目录（含 open 预览）
- （可选）`record.js` 成功录制 4K MP4 至输出目录
- 用户不满意渲染结果时，已支持返回修改脚本重试
## 失败与回退
@@ -214,14 +223,17 @@ PUPPETEER_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google
- **只读阶段（第 0–2 步）**完全无副作用，可安全重跑
- **提炼阶段（第 3 步）**不产生外部文件，修改 JSON 重新展示即可
- **渲染阶段（第 5 步）**：render.js 报错先检查 JSON 格式（常见：引号未闭合、字段缺失），修正后重跑
- **录制阶段（第 6 步）**：若失败则保留 HTML 供用户手动操作；puppeteer 未安装则 `cd ~/.claude/skills/zsxq/scripts/scenarios/generate-video && npm install`；Chromium 缺失（报 `ERR_BROWSER_NOT_FOUND`）则设 `PUPPETEER_EXECUTABLE_PATH` 指向系统 Chrome
- **录制阶段（第 6 步）**：若失败则保留 HTML 供用户手动操作；puppeteer 未安装则在 `scripts/scenarios/generate-video/` 目录下 `npm install`；Chromium 缺失（报 `ERR_BROWSER_NOT_FOUND`）则设 `PUPPETEER_EXECUTABLE_PATH` 指向系统 Chrome
- 通用错误（404、参数缺失、解析失败等）见 [auth-errors](../auth-errors.md#常见错误处理)
## 附加资源
- 提炼铁律 / 黑名单 / 质量自查清单：[`generate-video/refinement-rules.md`](generate-video/refinement-rules.md)
- 渲染脚本：`scripts/scenarios/generate-video/render.js`（结构化模板）/ `render-minimal.js`（金句模板）/ `record.js`（录制）
- 脚本依赖安装：`cd ~/.claude/skills/zsxq/scripts/scenarios/generate-video && npm install`（仅录制 MP4 需要 puppeteer）；跳过 Chromium 下载用 `PUPPETEER_SKIP_DOWNLOAD=true npm install`
- 渲染脚本（均位于 `scripts/scenarios/generate-video/`，相对于 skill 根目录）：
- `render.js` — 结构化模板（4 页）
- `render-minimal.js` — 金句模板（6 页）
- `record.js` — 4K MP4 录制
- 脚本依赖安装：在 `scripts/scenarios/generate-video/` 下执行 `npm install`（仅录制 MP4 需要 puppeteer）；跳过 Chromium 下载用 `PUPPETEER_SKIP_DOWNLOAD=true npm install`
- 拉帖子列表：[group-topics](../group-topics.md)；帖子详情：[topic-detail](../topic-detail.md)
- 星球列表：[group-list](../group-list.md)；主题搜索：[topic-search](../topic-search.md)
- 分享链接解析：[share-links](../share-links.md)