yuanflow-cli 0.1.39 → 0.1.40

package/README.md

@@ -36,6 +36,7 @@ yuanflow-cli works detail --platform douyin --target "https://v.douyin.com/xxx/"
 yuanflow-cli works download --platform douyin --target "https://v.douyin.com/xxx/" --region CN --format agent-json
 yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --format agent-json
 yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-json
+yuanflow-cli trending video-hot-list --format agent-json
 yuanflow-cli douyin web get-sec-user-id --url "https://v.douyin.com/xxx/" --format agent-json
 yuanflow-cli douyin user-profile <sec_user_id> --format agent-json
 yuanflow-cli douyin user-posts <sec_user_id> --count 20 --cursor 0 --format agent-json
@@ -99,6 +100,26 @@ yuanflow-cli search users --platform instagram --keyword "nasa" --format agent-j
 
 Agent 不确定参数时先执行 `commands list`，再用 `schema works.douyin.detail` 或 `schema search.xiaohongshu.content` 查看参数。`--dry-run` 可预览请求映射，不发起真实接口请求，也不要求 token。
 
+### 热门内容整理
+
+热门内容整理统一走 `trending video-hot-list`，一次性查询抖音视频热榜五类榜单，并输出统一 JSON：
+
+```bash
+yuanflow-cli trending video-hot-list --format agent-json
+yuanflow-cli trending video-hot-list --page 1 --page-size 10 --date-window 2 --format agent-json
+yuanflow-cli trending video-hot-list --tags-json "[{\"value\":\"顶级垂类标签id\",\"children\":[{\"value\":\"子级垂类标签id\"}]}]" --format agent-json
+```
+
+默认查询：
+
+- `1001` 视频总榜
+- `1002` 低粉爆款
+- `1003` 高完播率
+- `1004` 高涨粉率
+- `1005` 高点赞率
+
+Agent 使用该命令后，应结合用户个人创作信息、个人创作库历史记录、历史任务或对话记录，输出可执行的选题、内容结构和发布建议，而不是只罗列榜单。
+
 ### 帐号监控
 
 `帐号监控` 随 npm 包安装到 Skill bundle，用于把帐号搜索、主页资料、主页作品、历史快照和变化对比串成稳定流程。
@@ -133,26 +154,29 @@ yuanflow-cli knowledge rule-detail --rule-code some_rule_code --output-format sh
 
 Agent 应先查看 `knowledge docs`，再把用户需求整理成 `task_frame`，按接口返回的 `next_actions` 渐进查询。v2 接口不要求 `task_intent`；旧字段仅保留兼容。`packs`、`rules` 的 `data` 可能直接是数组，Agent 不应假设固定对象结构，应优先读取 `next_actions` 继续下钻。
 
+查询前必须先明确用户具体需求，再从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
+
 `knowledge entry`、`knowledge packs`、`knowledge evaluate` 会按规则库实际校验要求本地检查 `task_frame.domain` 和 `task_frame.content_goal`，CLI 调用时必须传 `--domain` 和 `--content-goal`，或通过 `--task-frame-file` 提供同名字段。`rules` 和 `rule-detail` 用于按已选包/规则继续下钻，仍必须分别传 `--pack-code` 或 `--rule-code`。
 
 ### 视频智能剪辑
 
-视频剪辑链路先查自媒体知识库中的 `video_editing_strategy`，再进入 `video` 命令执行。第一版人工测试流程是：查询规则包、保存策略快照、扫描素材、导入文案、1 秒 1 帧抽帧、Agent 生成 `timeline_plan.agent.json`、CLI 校验并渲染。
+视频剪辑链路先查自媒体知识库中的 `video_editing_strategy`，再进入 `video` 命令执行。第一版人工测试流程是：查询规则包、保存策略快照、扫描素材、通过“音视频在线转文字”取得 ASR/时间戳结果、导入音频对齐、1 秒 1 帧抽帧、导入视觉理解结果、Agent 生成 `timeline_plan.agent.json`、CLI 校验并渲染。
 
 ```bash
 yuanflow-cli knowledge rules --pack-code video_edit_logic_layer_pack --domain 视频剪辑 --content-goal "口播视频剪辑，需要主音频匹配 B-roll 并生成 EDL" --output-format video_edit_plan --format agent-json --output "D:\规则\logic.json"
 yuanflow-cli video init --input "D:\素材" --primary-audio "D:\素材\口播.mp3" --broll "D:\素材\画面.mp4" --format agent-json
 yuanflow-cli video strategy --project "D:\素材\yuanflow-video-edit" --template-type talking_head --rules-file "D:\规则\logic.json,D:\规则\talking_head.json,D:\规则\cli.json" --format agent-json
 yuanflow-cli video inspect --project "D:\素材\yuanflow-video-edit" --format agent-json
-yuanflow-cli video transcribe --project "D:\素材\yuanflow-video-edit" --script-file "D:\素材\口播文案.txt" --format agent-json
+yuanflow-cli video align --project "D:\素材\yuanflow-video-edit" --asr-file "D:\素材\asr.json" --format agent-json
 yuanflow-cli video timeline --project "D:\素材\yuanflow-video-edit" --fps 1 --format agent-json
+yuanflow-cli video visual-review --project "D:\素材\yuanflow-video-edit" --review-file "D:\素材\yuanflow-video-edit\visual_review.agent.json" --format agent-json
 yuanflow-cli video plan --project "D:\素材\yuanflow-video-edit" --timeline-plan "D:\素材\yuanflow-video-edit\timeline_plan.agent.json" --format agent-json
 yuanflow-cli video render-preview --project "D:\素材\yuanflow-video-edit" --format agent-json
 yuanflow-cli video evaluate --project "D:\素材\yuanflow-video-edit" --file "D:\素材\yuanflow-video-edit\preview.mp4" --format agent-json
 yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --format agent-json
 ```
 
-`--template-type` 当前支持 `talking_head` 和 `short_video_sales`。知识库查询由 `knowledge` 命令负责，`video` 命令只导入规则结果并保存 `strategy_snapshot.json`，不直接远程查规则库。
+`video align` 只导入已有 ASR 或 forced alignment 结果，不直接调用在线 ASR；在线 ASR 由“音视频在线转文字”Skill 执行。`video visual-review` 只导入 Agent/人工对抽帧图片的视觉理解，不替 Agent 做语义判断。`--template-type` 当前支持 `talking_head` 和 `short_video_sales`。知识库查询由 `knowledge` 命令负责，`video` 命令只导入规则结果并保存 `strategy_snapshot.json`，不直接远程查规则库。
 
 ### 业务创作类 Skill
 
@@ -163,6 +187,8 @@ yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --form
 - `帐号定位`：账号人设、内容边界、目标受众、价值主张和栏目方向。
 - `选题策划`：选题池、系列选题、热点选题和选题优先级排序。
 - `文案创作`：小红书、公众号、朋友圈、短视频口播、直播预告、海报和转化型文案。
+- `热门内容整理`：一次性查询视频总榜、低粉爆款、高完播率、高涨粉率、高点赞率，并结合用户创作方向输出建议。
+- `创作总监`：负责内容方向把控、创新判断、复查验收和跨技能创作统筹。
 - `视频投流策略`：短视频、图文视频或内容素材的投流目标、人群、预算、素材分层和测试节奏。
 - `直播投流策略`：直播预热、直播引流、直播成交和直播间投放的人群、预算、素材、节奏和复盘策略。
 
@@ -216,7 +242,7 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --account mai
 3. 使用 `yuanflow-cli oss temp-upload` 上传音频。
 4. ASR 请求必须优先使用 OSS 返回的 `data.signed_url` 作为 `metadata.audio_url`，不要优先使用裸域名 `data.url`。
 5. 调用 `POST https://open.yuanchuangai.com/v1/audio/transcriptions`，模型 `doubao-asr`，`response_format=json`。
-6. 默认只返回响应里的 `text` 干净文本；用户要求时间戳时再检查响应结构，不编造时间戳。
+6. 默认只返回响应里的 `text` 干净文本；视频剪辑任务需要音频对齐时，要优先保留 ASR 响应中的 `segments` / `words` 时间戳结构，后续交给 `yuanflow-cli video align --asr-file` 导入。接口没有返回时间戳时，不编造时间戳，改用 forced alignment 或人工按文案切分时间。
 
 请求体示例：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yuanflow-cli",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "YuanFlow 自媒体 API CLI 与 Skill 安装器。",
   "type": "module",
   "license": "MIT",

package/skills/yuanflow-skill/IP/350/277/220/350/220/245/SKILL.md

@@ -16,6 +16,7 @@ emoji: 🪪
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据用户目标构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，完成 IP 运营方案。

package/skills/yuanflow-skill/README.md

@@ -10,8 +10,10 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - `OSS文件中转工具/`：OSS 临时上传、签名链接、对象复制 Skill，走 `yuanflow-cli oss`。
 - `生图技能/`：图片生成与编辑 Skill，优先走 YuanFlow 内置 `yuanflow_image_request`。
 - `公众号生成与发布/`：公众号文章创作、主题预览、微信内联 HTML 排版、正文图片上传和草稿箱推送 Skill。
-- `小红书运营与发布/`：小红书选题调研、笔记搜索、账号分析、评论采集、文案创作、图文/视频发布和互动操作 Skill。
-- `视频智能剪辑/`：主音频 + B-roll 素材智能剪辑 Skill，先查自媒体知识库的视频剪辑策略，保存 `strategy_snapshot.json`，再按 1 秒 1 帧抽帧，由 Agent 生成 `timeline_plan` 和 EDL，交给 `yuanflow-cli video` 校验和渲染。
+- `小红书运营/`：小红书选题调研、笔记搜索、账号分析、评论采集、文案创作、发布前检查和互动操作 Skill；不建议浏览器自动发布作品，除非用户明确无视平台识别和限流风险并强制要求。
+- `热门内容整理/`：一次性查询视频总榜、低粉爆款、高完播率、高涨粉率、高点赞率，并结合用户创作方向输出建议。
+- `创作总监/`：负责内容方向把控、创新判断、复查验收和跨技能创作统筹。
+- `视频智能剪辑/`：主音频 + B-roll 素材智能剪辑 Skill，先查自媒体知识库的视频剪辑策略，保存 `strategy_snapshot.json`，再通过 ASR/forced alignment 导入 `audio_alignment.json`，按 1 秒 1 帧抽帧并回写视觉理解，由 Agent 生成 `timeline_plan` 和 EDL，交给 `yuanflow-cli video` 校验和渲染。
 - `HTML报告生成/`：单页 HTML 报告生成 Skill，内置 9 种米色留白报告模板。
 - `本地音视频转文字/`：本地 SenseVoice 音视频转文字 Skill，首次明确使用时按需下载模型。
 - `音视频在线转文字/`：通过 YuanFlow 在线 ASR 接口把音频或视频转成干净文本，视频会先抽取音频并通过 OSS 中转。
@@ -38,7 +40,7 @@ YuanFlow Skill 是 `yuanflow-cli` 的 Agent Skill 仓库，用于把社媒平台
 - 把自媒体分析、数据复盘、文案方案、账号监控、知识梳理和执行计划生成可直接打开的单页 HTML 报告。
 - 生成或改写公众号文章，进入主题选择预览后导出微信公众号编辑器可粘贴 HTML，或推送到公众号草稿箱。
 - 处理小红书单段或全流程任务，例如只写文案、只采集笔记、只分析账号、只采集评论、只做点赞收藏评论回复，或完整执行图文/视频发布流程；每轮开始前必须明确任务边界。
-- 在用户要求智能剪辑、自动剪辑、主音频匹配 B-roll、重排视频画面或生成剪辑预览时，使用视频智能剪辑 Skill；第一版先查规则库，导入策略快照，抽帧频率固定 1 秒 1 帧，由 Agent 看抽帧图生成 `timeline_plan` 和 EDL。
+- 在用户要求智能剪辑、自动剪辑、主音频匹配 B-roll、重排视频画面或生成剪辑预览时，使用视频智能剪辑 Skill；第一版先查规则库，导入策略快照，用“音视频在线转文字”或 forced alignment 建立音频对齐，抽帧频率固定 1 秒 1 帧，再回写视觉理解结果，最后生成 `timeline_plan` 和 EDL。
 - 在用户明确要求本地转写时，把本地音频或视频转成文字；视频会先抽取音频，模型和缓存都保存在 Skill 自己目录下。
 - 在用户要求在线转写、云端转写或 doubao-asr 时，把本地音频或视频经 OSS 中转后提交在线 ASR，默认只返回干净文本。
 - 在用户要求自媒体平台浏览器自动化、账号登录态隔离、Cookie/profile 保存、平台页面采集或作品发布时，使用专用自媒体浏览器自动化 Skill；普通网页浏览和搜索仍使用通用浏览器能力。
@@ -113,7 +115,9 @@ yuanflow-skill list-skills
 │  ├─ themes/
 │  ├─ references/
 │  └─ tests/
-├─ 小红书运营与发布
+├─ 小红书运营
+├─ 热门内容整理
+├─ 创作总监
 │  ├─ SKILL.md
 │  └─ references/
 ├─ 视频智能剪辑

package/skills/yuanflow-skill/SKILL.md

@@ -22,7 +22,9 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 - `OSS文件中转工具/`
 - `生图技能/`
 - `公众号生成与发布/`
-- `小红书运营与发布/`
+- `小红书运营/`
+- `热门内容整理/`
+- `创作总监/`
 - `视频智能剪辑/`
 - `HTML报告生成/`
 - `本地音视频转文字/`
@@ -140,6 +142,7 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 - 自媒体选题、开头钩子、脚本、文案、标题、改写、评分、剪辑建议、发布策略。
 - 用户明确要求查询 YuanFlow 自媒体知识库、方法包、规则方向。
 - 需要按照知识库 `next_actions` 渐进式查询方法论摘要。
+- 查询前必须先明确用户具体需求，再从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
 
 子 Skill 名称：
 
@@ -156,6 +159,8 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 | 账号人设、内容边界、目标受众、价值主张、栏目方向 | `帐号定位` |
 | 选题池、系列选题、热点选题、选题优先级排序 | `选题策划` |
 | 小红书、公众号、朋友圈、短视频口播、直播预告、海报或转化型文案 | `文案创作` |
+| 热点内容、爆款案例、高完播、高涨粉、高点赞内容整理和创作建议 | `热门内容整理` |
+| 内容方向把控、创新判断、复查验收、上线前质量门禁 | `创作总监` |
 | 主音频匹配 B-roll、自动剪辑、重排画面、生成剪辑预览或成片 | `视频智能剪辑` |
 | 短视频、图文视频或内容素材的投流目标、人群、预算、素材分层、测试节奏 | `视频投流策略` |
 | 直播间、直播预热、直播引流、直播成交的投放人群、预算、素材、节奏和复盘 | `直播投流策略` |
@@ -236,7 +241,7 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 
 - `公众号生成与发布`
 
-### 15. 走 `小红书运营与发布`
+### 15. 走 `小红书运营`
 
 遇到下面这些需求，优先进入这个子 Skill：
 
@@ -244,11 +249,11 @@ description: 当用户需要处理自媒体平台接口工作流、平台数据
 - 用户要求写小红书文案、准备发布笔记、检查素材、生成话题标签。
 - 用户要求对小红书笔记点赞、收藏、评论或回复。
 
-它可以执行完整流程，也可以只做部分能力。每次开始前必须先明确用户本轮任务边界：只写文案、只采集、只分析、只互动、只发布，还是完整流程。
+它可以执行完整流程，也可以只做部分能力。每次开始前必须先明确用户本轮任务边界：只写文案、只采集、只分析、只互动、只发布，还是完整流程。默认不建议使用浏览器自动发布作品，因为平台识别算法可能检测并限流；只有用户明确无视此说明并强制要求时才允许自动发布。
 
 子 Skill 名称：
 
-- `小红书运营与发布`
+- `小红书运营`
 
 ### 16. 走 `个人创作库`
 

package/skills/yuanflow-skill//345/205/254/344/274/227/345/217/267/347/224/237/346/210/220/344/270/216/345/217/221/345/270/203/SKILL.md

@@ -36,7 +36,7 @@ emoji: 📰
 ### 完全重新创作
 
 1. 先明确主题、读者、账号定位、文章目的和期望风格。
-2. 使用 `自媒体知识库` 查询公众号创作相关知识点，根据主题构造 `domain` 和 `content_goal`。
+2. 使用 `自媒体知识库` 查询公众号创作相关知识点，根据主题构造 `domain` 和 `content_goal`。查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
 3. 结合知识库结果输出文章结构、标题候选和正文。
 4. 用户确认正文后再进入排版、导出或草稿箱流程。
 

package/skills/yuanflow-skill//345/210/233/344/275/234/346/200/273/347/233/221/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: 创作总监
+description: 当用户需要对自媒体内容进行方向把控、创新判断、结构复查、质量验收、上线前审稿或跨技能创作统筹时使用。
+emoji: 🎯
+---
+
+# 创作总监
+
+本 Skill 是 YuanFlow 自媒体创作链路的把控与验收角色。它不替代具体执行技能，而是负责判断创作目标是否清楚、选题是否成立、内容是否有创新、结构是否完整、表达是否适合平台，以及最终产物是否达到可发布或可交付标准。
+
+## 分类
+
+自媒体技能区
+
+## 核心职责
+
+1. 把控：明确用户目标、平台、受众、账号定位和成败标准。
+2. 创新：判断内容是否有新角度、新表达、新结构或新组合，避免同质化。
+3. 复查：检查选题、标题、开头、脚本、文案、画面、封面、话题、节奏和转化逻辑。
+4. 验收：给出是否可发布、需要修改、需要重做或需要补数据的结论。
+5. 调度：根据任务需要调用个人创作库、自媒体知识库、热门内容整理、选题策划、文案创作、视频智能剪辑、HTML报告生成等技能。
+
+## 开始前必须确认
+
+1. 本次要把控的对象：选题、标题、脚本、文案、封面、视频结构、发布计划、复盘报告或完整项目。
+2. 目标平台：抖音、小红书、公众号、视频号、B站、快手、TikTok、YouTube 或其它。
+3. 目标用户和账号定位。
+4. 用户当前阶段：从 0 到 1 创作、半成品复查、发布前验收、发布后复盘。
+5. 是否允许调用其它技能补充数据或重新生成内容。
+
+## 调度逻辑
+
+根据用户任务选择能力：
+
+- 需要历史资产：调用 `个人创作库`。
+- 需要方法论：调用 `自媒体知识库`。查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
+- 需要趋势和爆款参考：调用 `热门内容整理`。
+- 需要选题池：调用 `选题策划`。
+- 需要标题、脚本、正文、发布文案：调用 `文案创作`。
+- 需要小红书专项流程：调用 `小红书运营`。
+- 需要公众号草稿和排版：调用 `公众号生成与发布`。
+- 需要视频剪辑结构：调用 `视频智能剪辑`。
+- 需要可视化汇总：调用 `HTML报告生成`。
+
+## 把控维度
+
+### 1. 目标把控
+
+- 用户真正想要的是增长、转化、建立信任、表达观点、带货、获客、沉淀品牌，还是完成一次内容交付。
+- 内容是否服务于这个目标，而不是只追求热闹。
+
+### 2. 选题把控
+
+- 是否有明确受众。
+- 是否有足够痛点、爽点、利益点或新信息。
+- 是否和账号长期定位一致。
+- 是否有平台适配性。
+
+### 3. 创新把控
+
+- 是否只是套模板。
+- 是否有独特观点、案例、反常识、结构创新、表达创新或视觉创新。
+- 是否能形成用户记忆点。
+
+### 4. 结构复查
+
+- 开头是否足够快进入主题。
+- 中段是否有递进，而不是平铺。
+- 结尾是否有明确行动、观点或记忆点。
+- 是否存在信息重复、逻辑跳跃或表达过载。
+
+### 5. 发布验收
+
+- 标题、封面、正文、脚本、话题、素材是否完整。
+- 是否存在平台风险、夸大承诺、敏感表达、侵权风险或自动化发布风险。
+- 小红书等平台不建议使用浏览器自动化直接发布作品，除非用户明确无视平台识别和限流风险并强制要求。
+
+## 输出格式
+
+默认输出：
+
+1. 总体判断：可继续 / 需要修改 / 建议重做。
+2. 核心问题：按影响优先级列出。
+3. 创新建议：给出可执行的新角度或新结构。
+4. 修改清单：明确改哪里、怎么改。
+5. 验收标准：修改后用什么标准判断合格。
+6. 下一步建议：进入具体技能执行，或生成 HTML 汇总报告。
+
+## 注意事项
+
+- 不要只夸内容，要敢于指出不可发布的问题。
+- 不要替具体技能编造已经查询到的数据；需要数据就调用对应技能。
+- 不要把所有内容都推倒重做，优先判断能否局部修复。
+- 用户只要轻量建议时，输出短版；用户要求完整审稿时，再输出详细版。

package/skills/yuanflow-skill//345/260/217/347/272/242/344/271/246/350/277/220/350/220/245/{344/270/216/345/217/221/345/270/203/SKILL.md → SKILL.md}

@@ -1,13 +1,15 @@
 ---
-name: 小红书运营与发布
+name: 小红书运营
 description: 当用户需要小红书选题调研、文案创作、笔记搜索、账号分析、评论采集、图文或视频发布、点赞收藏评论回复等小红书运营任务时使用。
 emoji: 📕
 ---
 
-# 小红书运营与发布
+# 小红书运营
 
 本 Skill 用于把小红书任务从“明确边界、采集分析、内容创作、素材检查、登录确认、发布执行、互动操作、结果回报”串成一个可控流程。它拥有完整能力，但用户可以只使用其中一部分，例如只写文案、只采集笔记、只分析账号、只采集评论、只做发布前检查，或一次性完成完整运营流程。
 
+重要提醒：不建议让 Agent 使用浏览器自动化直接发布作品。小红书等平台的识别算法可能检测自动化发布行为，并对账号内容进行限流或风控。除非用户在看到此说明后仍明确要求“无视风险，强制使用浏览器自动发布”，否则本 Skill 默认只做发布前检查、素材整理、文案准备和人工发布指导。
+
 ## 分类
 
 自媒体技能区
@@ -20,7 +22,8 @@ emoji: 📕
 4. 是否涉及封面或正文插图：如果需要生成封面或插图，必须使用 `生图技能`，并先和用户确认图片比例是 4:3 还是 3:4；用户已明确给出比例时直接采用。
 5. 发布确认策略：
    - 默认每次真实发布前必须向用户确认。
-   - 如果用户明确说“后续都自动直接发布”“这个账号以后不用重复问”，可以把该偏好作为用户记忆；后续同类任务不重复确认，但仍需在执行结果里说明已按用户记忆自动执行。
+   - 不建议自动发布作品，因为平台识别算法可能检测并限流。只有用户明确表示已了解风险且强制要求浏览器自动发布时，才允许继续执行自动化发布。
+   - 如果用户明确说“后续都自动直接发布”“这个账号以后不用重复问”，必须再次提示平台自动化发布限流风险；用户仍明确坚持后，才可以把该偏好作为用户记忆；后续同类任务不重复确认，但仍需在执行结果里说明已按用户记忆自动执行。
 6. 评论和回复默认必须确认；点赞、收藏可按用户明确指令直接执行。
 7. 登录态使用 YuanFlow 独立浏览器配置，不要求用户复用默认 Chrome，不读取用户默认浏览器 Cookie。
 
@@ -88,6 +91,7 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --title "标
 1. 先确认任务边界：只写标题、只写正文、标题+正文、发布版笔记、种草文案、测评文案、探店文案、合集文案或完整发布流程。
 2. 确认账号定位、目标用户、产品/主题、语气风格、禁忌表达、字数范围、是否需要话题标签。
 3. 写任何小红书文案前，必须先使用 `自媒体知识库` 查找并参考对应写作方法论，例如选题、标题、钩子、种草、测评、探店、合集、转化或发布策略；不要跳过知识库直接凭空输出文案。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
 4. 如果用户要求参考平台趋势，先采集或搜索同类笔记，再结合知识库方法论创作。
 5. 输出小红书文案时默认包含：
    - 标题候选
@@ -114,7 +118,7 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --title "标
 3. 标题应符合小红书长度限制，过长时先给用户改写建议。
 4. 话题必须通过平台官方候选插入，优先使用 `yuanflow_browser_automation` 的 `select-platform-topics`；成功标准是正文编辑器 DOM 中出现 `a.tiptap-topic`、`data-topic`、`contenteditable="false"`，不能只看见普通 `#关键词` 文本。
 5. 话题异常时先用 `inspect-platform-topic-dom` 写出 DOM 诊断文件，再根据诊断重试；不要只靠坐标、截图颜色或文本候选点击判断。
-6. 默认发布前确认；用户已明确授权自动发布时，可直接执行。
+6. 默认发布前确认；不建议浏览器自动发布。只有用户明确表示无视平台识别和限流风险、强制要求自动发布时，才可执行自动化发布。
 7. 发布失败时报告失败阶段：未登录、素材不存在、上传失败、页面元素变化、提交失败或平台风控。
 8. 任务完整结束后可以询问用户对结果是否满意；如果用户明确表示满意，可将最终结果、素材路径、关键制作流程、发布前检查结论保存到 `个人创作库`，便于后续复用。
 
@@ -123,7 +127,7 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --title "标
 1. 检查标题、正文、视频路径、封面、话题、可见性、发布时间和目标账号。
 2. 视频路径必须是本地可访问文件。
 3. 不要把图文和视频混成一个发布任务。
-4. 默认发布前确认；用户已明确授权自动发布时，可直接执行。
+4. 默认发布前确认；不建议浏览器自动发布。只有用户明确表示无视平台识别和限流风险、强制要求自动发布时，才可执行自动化发布。
 
 ## 互动流程
 
@@ -154,6 +158,7 @@ yuanflow-cli browser dry-run --platform xiaohongshu --task publish --title "标
 ## 常见错误
 
 - 用户只想写文案，却直接尝试发布。
+- 用户没有明确无视平台风控风险，却使用浏览器自动发布作品。
 - 采集任务没有确认关键词、数量或目标笔记。
 - 发布前没有检查图片/视频路径是否存在。
 - 把小红书 MCP 当成独立安装项使用。

package/skills/yuanflow-skill//345/270/220/345/217/267/345/256/232/344/275/215/SKILL.md

@@ -16,6 +16,7 @@ emoji: 🧭
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据账号行业、目标人群、内容目标和商业目标构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出账号定位方案。

package/skills/yuanflow-skill//346/226/207/346/241/210/345/210/233/344/275/234/SKILL.md

@@ -16,6 +16,7 @@ emoji: ✍️
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据平台、受众、语气、内容目标和转化目标构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出文案。

package/skills/yuanflow-skill//347/203/255/351/227/250/345/206/205/345/256/271/346/225/264/347/220/206/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: 热门内容整理
+description: 当用户需要整理抖音视频热榜、爆款案例、高完播率、高涨粉率、高点赞率内容，并结合个人创作方向输出创作建议时使用。
+emoji: 🔥
+---
+
+# 热门内容整理
+
+本 Skill 用于把热门内容从“榜单采集、结构化整理、创作相关性判断、个人化建议”串成完整流程。它不是简单罗列链接，而是帮助用户判断哪些热点值得借鉴、如何借鉴、哪些不适合照搬。
+
+## 分类
+
+自媒体技能区
+
+## 开始前必须确认
+
+1. 用户的创作方向、账号定位、目标平台和目标受众。
+2. 用户希望参考的主题、行业、关键词或内容垂类；如果用户没有指定，先按全部垂类查询。
+3. 是否已有个人创作库历史记录、历史任务或历史对话可参考。
+4. 输出目标：选题建议、内容拆解、脚本方向、账号定位参考、投放素材参考或复盘报告。
+
+## 数据查询逻辑
+
+优先使用 YuanFlow 受控工具 `yuanflow_cli_call` 调用：
+
+```bash
+yuanflow-cli trending video-hot-list --format agent-json
+```
+
+默认参数：
+
+- `page=1`
+- `page_size=10`
+- `date_window=2`
+- `tags` 为空时查询全部垂类
+
+必须一次性查询全部榜单分类：
+
+- `1001` 视频总榜
+- `1002` 低粉爆款
+- `1003` 高完播率
+- `1004` 高涨粉率
+- `1005` 高点赞率
+
+如果用户明确指定垂类标签，使用 `--tags-json` 传入：
+
+```bash
+yuanflow-cli trending video-hot-list --tags-json "[{\"value\":\"顶级垂类标签id\",\"children\":[{\"value\":\"子级垂类标签id\"}]}]" --format agent-json
+```
+
+## 分析流程
+
+1. 先读取个人创作库，查找用户过往的选题、文案、脚本、发布计划和数据复盘。
+2. 再执行五类榜单查询，按榜单分类保存结果。
+3. 对每个榜单提取标题、主题、表达形式、互动指标、账号特征和可复用方法。
+4. 交叉比较五个榜单，识别共同趋势和差异：
+   - 总榜代表平台当前广泛热度。
+   - 低粉爆款代表普通账号可借鉴机会。
+   - 高完播率代表内容结构和留存能力。
+   - 高涨粉率代表人设、系列化和关注理由。
+   - 高点赞率代表情绪价值、观点共鸣和表达记忆点。
+5. 结合用户个人创作信息、创作库历史记录、历史任务或对话记录，给出个人化建议。
+
+## 输出结构
+
+必须输出：
+
+1. 查询范围和参数说明。
+2. 五类榜单摘要。
+3. 热点共同规律。
+4. 与用户创作方向最相关的机会点。
+5. 不建议照搬的风险点。
+6. 可执行选题建议。
+7. 可执行内容结构建议。
+8. 下一步建议：是否进入选题策划、文案创作、创作总监复查或 HTML 报告生成。
+
+## 注意事项
+
+- 不把“热门”简单等同于“适合用户做”。
+- 不只看播放或点赞，要结合完播、涨粉、账号体量和内容形式判断。
+- 不要把五个榜单混成一个列表，必须保留分类来源。
+- 不要跳过用户个人创作信息；没有历史记录时要明确说明“未读取到可参考历史”。
+- 如果用户需要沉淀结果，询问是否写入个人创作库。

package/skills/yuanflow-skill//347/233/264/346/222/255/346/212/225/346/265/201/347/255/226/347/225/245/SKILL.md

@@ -16,6 +16,7 @@ emoji: 📡
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据直播平台、直播目标、产品、预算和目标人群构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出直播投流策略。

package/skills/yuanflow-skill//347/233/264/346/222/255/350/257/235/346/234/257/347/224/237/346/210/220/SKILL.md

@@ -16,6 +16,7 @@ emoji: 🎤
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据直播主题、产品、目标人群和转化目标构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出直播话术。

package/skills/yuanflow-skill//350/207/252/345/252/222/344/275/223/347/237/245/350/257/206/345/272/223/SKILL.md

@@ -8,6 +8,8 @@ emoji: 🧠
 
 这个 Skill 负责使用 YuanFlow 的自媒体知识库原子能力。它和社媒数据采集、作品评论、作品下载是独立能力，不要混用接口。
 
+查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
+
 ## 环境判断
 
 1. 在 YuanFlow 主程序内，优先调用内置工具 `yuanflow_cli_call`。

package/skills/yuanflow-skill//350/247/206/351/242/221/346/212/225/346/265/201/347/255/226/347/225/245/SKILL.md

@@ -46,6 +46,7 @@ emoji: 📈
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 5. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据平台、投放目标、预算、人群和素材类型构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 6. 结合用户要求、账号最近 5 条视频数据、历史参考记录和知识库结果，输出视频投流策略。

package/skills/yuanflow-skill//350/247/206/351/242/221/346/231/272/350/203/275/345/211/252/350/276/221/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 视频智能剪辑
-description: "用于把主音频、文案、B-roll 视频或图片素材组合成可解释的智能剪辑项目。执行前先查询自媒体知识库中的视频剪辑策略规则，再按 1秒1帧抽帧，由 Agent 判断画面语义并生成 EDL，交给 yuanflow-cli video 校验和渲染。"
+description: "用于把主音频、文案、B-roll 视频或图片素材组合成可解释的智能剪辑项目。执行前先查询自媒体知识库中的视频剪辑策略规则，再用音视频在线转文字取得 ASR/时间戳，导入音频对齐，按 1秒1帧抽帧并回写视觉理解，由 Agent 生成 EDL，交给 yuanflow-cli video 校验和渲染。"
 metadata:
   builtin_skill_version: "1.0.1"
   yuanflow:
@@ -25,6 +25,7 @@ tags:
 推荐查询顺序：
 
 1. 先用 `knowledge entry` 建立任务入口，`domain` 填 `视频剪辑`，`content_goal` 写清本次剪辑目标。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
 2. 再用 `knowledge packs --capability-code video_editing_strategy` 查看视频剪辑策略下的方法包。
 3. 必查 `video_edit_logic_layer_pack`，获得通用剪辑逻辑层规则。
 4. 如果任务是口播、旁白、主音频驱动，查询 `talking_head_edit_template_pack`。
@@ -101,8 +102,9 @@ CLI 会生成 `strategy_snapshot.json`，后续 Agent 必须基于这个快照
 
 - 主音频可以是口播、旁白或已经录好的音频。
 - B-roll 可以是视频或图片素材。
-- 第一版视觉理解不调用视觉模型，使用 `yuanflow-cli video timeline --fps 1` 按 1秒1帧抽帧。
-- Agent 需要查看抽帧结果，自己判断每段画面的语义、主体、动作和适合承接的文案。
+- 第一版音频对齐优先使用“音视频在线转文字”Skill 的 ASR 时间戳结果；如果 ASR 没有时间戳，使用 forced alignment 或人工按文案切分，不编造时间戳。
+- 第一版视觉理解不调用固定视觉模型，使用 `yuanflow-cli video timeline --fps 1` 按 1秒1帧抽帧。
+- Agent 或人工需要查看抽帧结果，判断每段画面的语义、主体、动作和适合承接的文案，再用 `video visual-review` 回写结构化视觉描述。
 - 第一版 `video plan` 不自动生成 EDL，由 Agent 生成 EDL 后交给 CLI 校验和渲染。
 
 ## 执行原则
@@ -161,18 +163,27 @@ yuanflow-cli video inspect --project "D:\素材\yuanflow-video-edit" --format ag
 
 如果只是验证命令结构，可以加 `--dry-run`。
 
-### 3. 导入文案或转写
+### 3. 音频对齐
 
-如果用户已有文案：
+主音频驱动的剪辑必须先建立音频时间轴。优先使用“音视频在线转文字”Skill 调用在线 ASR；如果 ASR 返回 `segments` / `words` 时间戳，保存为 JSON 后导入：
 
 ```bash
-yuanflow-cli video transcribe \
+yuanflow-cli video align \
   --project "D:\素材\yuanflow-video-edit" \
-  --script-file "D:\素材\口播文案.txt" \
+  --asr-file "D:\素材\asr.json" \
   --format agent-json
 ```
 
-如果用户只有音频，先使用“音视频在线转文字”或“本地音视频转文字”得到文本，再用 `--script-file` 导入。
+如果 ASR 只返回纯文本，没有时间戳：
+
+- 先明确说明缺少时间戳。
+- 可用 forced alignment 或人工按文案切分生成 `segments`。
+- 只有在用户允许“粗对齐”时，才能按文本段落和音频总时长均分兜底。
+
+`video align` 会生成：
+
+- `audio_alignment.json`
+- 带 `start_s / end_s` 的 `beats.json`
 
 ### 4. 生成 1秒1帧时间线
 
@@ -191,14 +202,51 @@ CLI 会生成：
 
 Agent 必须基于这些抽帧图片判断画面，不要凭文件名猜。
 
-### 5. Agent 生成 timeline_plan 和 EDL
+### 5. 视觉理解回写
+
+Agent 或人工查看抽帧图片后，先写出 `visual_review.agent.json`，不要直接跳到 EDL。基础格式：
+
+```json
+{
+  "version": 1,
+  "reviews": [
+    {
+      "segment_id": "vis_0001",
+      "description": "产品近景，手持展示刷头。",
+      "subjects": ["产品", "手"],
+      "scene": "厨房水槽",
+      "motion": "展示",
+      "semantic_tags": ["product_closeup", "kitchen"],
+      "quality_score": 0.88
+    }
+  ]
+}
+```
+
+导入视觉理解：
+
+```bash
+yuanflow-cli video visual-review \
+  --project "D:\素材\yuanflow-video-edit" \
+  --review-file "D:\素材\yuanflow-video-edit\visual_review.agent.json" \
+  --format agent-json
+```
+
+CLI 会生成或更新：
+
+- `visual_understanding.json`
+- 带结构化描述的 `visual_segments.json`
+
+### 6. Agent 生成 timeline_plan 和 EDL
 
 Agent 读取：
 
 - `project.json`
 - `assets.json`
+- `audio_alignment.json`
 - `beats.json`
 - `visual_segments.json`
+- `visual_understanding.json`
 - `strategy_snapshot.json`
 - 抽帧图片
 
@@ -268,7 +316,7 @@ Agent 读取：
 }
 ```
 
-### 6. 校验 EDL
+### 7. 校验 EDL
 
 ```bash
 yuanflow-cli video plan \
@@ -289,14 +337,14 @@ yuanflow-cli video plan \
 
 只有校验通过后，才允许渲染。
 
-### 7. 渲染预览和自检
+### 8. 渲染预览和自检
 
 ```bash
 yuanflow-cli video render-preview --project "D:\素材\yuanflow-video-edit" --format agent-json
 yuanflow-cli video evaluate --project "D:\素材\yuanflow-video-edit" --file "D:\素材\yuanflow-video-edit\preview.mp4" --format agent-json
 ```
 
-### 8. 最终导出
+### 9. 最终导出
 
 ```bash
 yuanflow-cli video render-final --project "D:\素材\yuanflow-video-edit" --format agent-json

package/skills/yuanflow-skill//351/200/211/351/242/230/347/255/226/345/210/222/SKILL.md

@@ -16,6 +16,7 @@ emoji: 💡
    - 如果没有命中，说明“未发现可用历史参考记录”，继续下一步。
 2. 调用 `自媒体知识库`。
    - 先查 `knowledge docs` 或 `knowledge entry`，根据平台、受众、内容目标和选题方向构造 `domain` 和 `content_goal`。
+   - 查询时，必须先明确用户具体需求，然后从知识库的一级能力开始，依次使用渐进式查询。不能跳级、跨越式查询。
    - 按返回的 `next_actions` 分层查看 `packs`、`rules` 或 `rule-detail`，直到拿到足够的方法摘要。
    - 不要自己拼 SQL，不要跳过知识库直接凭空输出。
 3. 结合用户要求、历史参考记录和知识库结果，输出选题策划结果。

package/src/agent-protocol.js

@@ -6,6 +6,7 @@ import { listOssCommands } from './oss-tools.js';
 import { listBrowserCommands } from './browser-tools.js';
 import { listSearchCommands, listWorkCommands } from './work-tools.js';
 import { listVideoCommands } from './video-tools.js';
+import { listTrendingCommands } from './trending-tools.js';
 
 const ERROR_MAP = [
   {
@@ -109,6 +110,7 @@ export function buildCommandRegistry() {
   const ossCommands = listOssCommands();
   const browserCommands = listBrowserCommands();
   const videoCommands = listVideoCommands();
+  const trendingCommands = listTrendingCommands();
   return [
     ...shortcuts,
     ...endpoints,
@@ -119,6 +121,7 @@ export function buildCommandRegistry() {
     ...ossCommands,
     ...browserCommands,
     ...videoCommands,
+    ...trendingCommands,
   ].sort((left, right) => left.key.localeCompare(right.key));
 }
 

package/src/cli.js

@@ -27,6 +27,7 @@ import {
   searchContent,
   searchUsers,
 } from './work-tools.js';
+import { fetchVideoHotList } from './trending-tools.js';
 
 export async function main(argv) {
   const args = argv.slice(2);
@@ -72,6 +73,11 @@ export async function main(argv) {
     return;
   }
 
+  if (command === 'trending') {
+    await handleTrending(rest);
+    return;
+  }
+
   if (command === 'knowledge') {
     await handleKnowledge(rest);
     return;
@@ -351,6 +357,19 @@ async function handleSearch(args) {
   });
 }
 
+async function handleTrending(args) {
+  const { positionals, options } = parseOptions(args);
+  const [action = 'video-hot-list'] = positionals;
+  if (action !== 'video-hot-list') {
+    throw new Error('未知 trending 命令。用法：yuanflow-cli trending video-hot-list');
+  }
+  const result = await fetchVideoHotList({ options });
+  await outputResult(result, options, {
+    command: 'trending video-hot-list',
+    meta: { endpoint: result.endpoint.path, kind: result.endpoint.kind },
+  });
+}
+
 async function handleKnowledge(args) {
   const { positionals, options } = parseOptions(args);
   const [action = 'docs'] = positionals;
@@ -578,6 +597,7 @@ function printHelp() {
   yuanflow-cli works download --platform youtube --target "dQw4w9WgXcQ" --dry-run
   yuanflow-cli search content --platform xiaohongshu --keyword "美妆" --dry-run
   yuanflow-cli search users --platform instagram --keyword "nasa" --dry-run
+  yuanflow-cli trending video-hot-list --dry-run --format agent-json
   yuanflow-cli knowledge docs --dry-run
   yuanflow-cli knowledge entry --output-format short_video_script --domain 自媒体运营 --content-goal "写一个创业者短视频选题" --target-audience 创业者 --format agent-json
   yuanflow-cli oss signed-url --key path/to/file.png --ttl-seconds 1800 --format agent-json
@@ -585,14 +605,16 @@ function printHelp() {
   yuanflow-cli browser task-plan --platform xiaohongshu --task publish --account main --format agent-json
   yuanflow-cli video init --input "D:\\素材" --primary-audio "D:\\素材\\口播.mp3" --broll "D:\\素材\\画面.mp4" --format agent-json
   yuanflow-cli video strategy --project "D:\\素材\\yuanflow-video-edit" --template-type talking_head --rules-file "D:\\规则\\logic.json,D:\\规则\\template.json,D:\\规则\\cli.json" --format agent-json
+  yuanflow-cli video align --project "D:\\素材\\yuanflow-video-edit" --asr-file "D:\\素材\\asr.json" --format agent-json
   yuanflow-cli video timeline --project "D:\\素材\\yuanflow-video-edit" --fps 1 --format agent-json
+  yuanflow-cli video visual-review --project "D:\\素材\\yuanflow-video-edit" --review-file "D:\\素材\\yuanflow-video-edit\\visual_review.agent.json" --format agent-json
   yuanflow-cli video plan --project "D:\\素材\\yuanflow-video-edit" --timeline-plan "D:\\素材\\yuanflow-video-edit\\timeline_plan.agent.json" --format agent-json
   yuanflow-cli list douyin
 
 说明：
   社媒请求调用 Yuan API 的 /social/*path；知识库和 OSS 原子能力调用 /api/* 或 /atomic/*。
   browser 命令是自媒体平台专用浏览器自动化协议，只返回受控 profile/cookie/任务路径与执行计划，不用于普通网页搜索。
-  video 命令是视频智能剪辑基础链路：规则库策略快照、主音频+B-roll、1秒1帧抽帧、Agent 生成 timeline_plan/EDL、CLI 校验和渲染。
+  video 命令是视频智能剪辑基础链路：规则库策略快照、主音频+B-roll、ASR 时间戳对齐、1秒1帧抽帧、视觉理解回写、Agent 生成 timeline_plan/EDL、CLI 校验和渲染。
   需要鉴权的请求都会使用 Authorization: Bearer <token>。
   token 优先级：--token > YUANCHUANG_API_TOKEN > 本地 config.token。
   YuanFlow 主程序内使用时，token 由主程序认证系统注入，不需要手动配置。

package/src/trending-tools.js

@@ -0,0 +1,117 @@
+import { callEndpoint } from './request.js';
+
+const VIDEO_HOT_LIST_PATH = '/douyin/billboard/fetch_hot_total_video_list';
+
+const VIDEO_HOT_BOARD_TYPES = [
+  { subType: 1001, label: '视频总榜' },
+  { subType: 1002, label: '低粉爆款' },
+  { subType: 1003, label: '高完播率' },
+  { subType: 1004, label: '高涨粉率' },
+  { subType: 1005, label: '高点赞率' },
+];
+
+export function listTrendingCommands() {
+  return [
+    {
+      key: 'trending.video-hot-list',
+      command: 'trending video-hot-list',
+      kind: 'trending',
+      description: '一次性查询抖音视频热榜五类榜单：视频总榜、低粉爆款、高完播率、高涨粉率、高点赞率。',
+      method: 'POST',
+      socialPath: VIDEO_HOT_LIST_PATH,
+      positionals: [],
+      options: [
+        { flag: '--page', name: 'page', required: false, label: '页码，默认 1' },
+        { flag: '--page-size', name: 'page_size', required: false, label: '每页数量，默认 10' },
+        { flag: '--date-window', name: 'date_window', required: false, label: '时间窗口，默认 2 按天' },
+        { flag: '--tags-json', name: 'tags', required: false, label: '垂类标签 JSON 数组，空则全部垂类' },
+      ],
+      returns: '返回五类视频热榜的统一 JSON，字段结构以上游实际响应为准。',
+    },
+  ];
+}
+
+export async function fetchVideoHotList({ options }) {
+  const query = buildVideoHotListQuery(options);
+  const boards = [];
+
+  for (const board of VIDEO_HOT_BOARD_TYPES) {
+    const requestBody = {
+      page: query.page,
+      page_size: query.page_size,
+      date_window: query.date_window,
+      sub_type: board.subType,
+      ...(query.tags !== undefined ? { tags: query.tags } : {}),
+    };
+    const response = await callEndpoint(VIDEO_HOT_LIST_PATH, {
+      ...options,
+      method: 'POST',
+      body: requestBody,
+    });
+    boards.push({
+      sub_type: board.subType,
+      label: board.label,
+      request: requestBody,
+      response,
+    });
+  }
+
+  return {
+    platform: 'douyin',
+    endpoint: {
+      method: 'POST',
+      path: VIDEO_HOT_LIST_PATH,
+      kind: 'video-hot-list',
+    },
+    query,
+    boards,
+    guidance: [
+      '结合用户个人创作信息、个人创作库历史记录、历史任务或对话记录输出建议。',
+      '不要只罗列榜单，必须区分五类榜单来源并提炼可执行选题和内容结构。',
+      '重点比较总榜、低粉爆款、高完播率、高涨粉率、高点赞率之间的差异。',
+    ],
+  };
+}
+
+function buildVideoHotListQuery(options = {}) {
+  return {
+    page: parsePositiveInteger(options.named?.page, 1, 'page'),
+    page_size: parsePositiveInteger(options.named?.['page-size'] ?? options.named?.page_size, 10, 'page_size'),
+    date_window: parsePositiveInteger(options.named?.['date-window'] ?? options.named?.date_window, 2, 'date_window'),
+    ...(parseTags(options.named?.['tags-json'] ?? options.named?.tags) !== undefined
+      ? { tags: parseTags(options.named?.['tags-json'] ?? options.named?.tags) }
+      : {}),
+  };
+}
+
+function parsePositiveInteger(value, fallback, name) {
+  if (value === undefined || value === null || value === '') {
+    return fallback;
+  }
+  const number = Number(value);
+  if (!Number.isInteger(number) || number <= 0) {
+    throw new Error(`${name} 必须是正整数。`);
+  }
+  return number;
+}
+
+function parseTags(value) {
+  if (value === undefined || value === null || value === '') {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value;
+  }
+  try {
+    const parsed = JSON.parse(String(value));
+    if (!Array.isArray(parsed)) {
+      throw new Error('tags-json 必须是数组。');
+    }
+    return parsed;
+  } catch (error) {
+    if (error?.message === 'tags-json 必须是数组。') {
+      throw error;
+    }
+    throw new Error('tags-json 必须是合法 JSON 数组。');
+  }
+}

package/src/video-tools.js

@@ -9,7 +9,9 @@ const IMAGE_EXTS = new Set(['.jpg', '.jpeg', '.png', '.webp']);
 const PROJECT_FILE = 'project.json';
 const ASSETS_FILE = 'assets.json';
 const BEATS_FILE = 'beats.json';
+const AUDIO_ALIGNMENT_FILE = 'audio_alignment.json';
 const VISUAL_SEGMENTS_FILE = 'visual_segments.json';
+const VISUAL_UNDERSTANDING_FILE = 'visual_understanding.json';
 const EDL_FILE = 'edl.json';
 const STRATEGY_FILE = 'strategy_snapshot.json';
 const TIMELINE_PLAN_FILE = 'timeline_plan.json';
@@ -39,11 +41,19 @@ export function listVideoCommands() {
       option('--script-file', 'scriptFile', false, '读取文案文件。'),
       option('--transcript-file', 'transcriptFile', false, '读取转写 JSON 或文本文件。'),
     ]),
+    videoCommand('align', '导入 ASR 或 forced alignment 时间戳结果，生成 audio_alignment.json 和带时间戳 beats.json。', [
+      option('--project', 'project', true, '剪辑项目目录。'),
+      option('--asr-file', 'asrFile', true, '音视频在线转文字或 forced alignment 输出的 JSON 文件。'),
+    ]),
     videoCommand('timeline', '按 1 秒 1 帧抽帧并生成 visual_segments.json。', [
       option('--project', 'project', true, '剪辑项目目录。'),
       option('--fps', 'fps', false, '抽帧频率，基础版建议 1。'),
       option('--dry-run', 'dryRun', false, '不调用 ffmpeg，只生成占位帧清单。'),
     ]),
+    videoCommand('visual-review', '导入 Agent/人工对抽帧结果的视觉理解，回写 visual_segments.json。', [
+      option('--project', 'project', true, '剪辑项目目录。'),
+      option('--review-file', 'reviewFile', true, 'Agent 或人工生成的 visual_review.agent.json。'),
+    ]),
     videoCommand('plan', '校验 Agent 生成的 timeline_plan 和 EDL，写入标准 timeline_plan.json / edl.json。', [
       option('--project', 'project', true, '剪辑项目目录。'),
       option('--timeline-plan', 'timelinePlan', false, 'Agent 生成的 timeline_plan.agent.json。'),
@@ -72,12 +82,14 @@ export async function runVideoCommand({ action, options }) {
   if (action === 'inspect') return inspectProject(options);
   if (action === 'strategy') return saveStrategySnapshot(options);
   if (action === 'transcribe') return importTranscript(options);
+  if (action === 'align') return importAudioAlignment(options);
   if (action === 'timeline') return buildTimeline(options);
+  if (action === 'visual-review') return importVisualReview(options);
   if (action === 'plan') return planFromAgentEdl(options);
   if (action === 'render-preview') return renderVideo(options, { final: false });
   if (action === 'render-final') return renderVideo(options, { final: true });
   if (action === 'evaluate') return evaluateVideo(options);
-  throw new Error('未知 video 命令。用法：yuanflow-cli video init|inspect|strategy|transcribe|timeline|plan|render-preview|render-final|evaluate');
+  throw new Error('未知 video 命令。用法：yuanflow-cli video init|inspect|strategy|transcribe|align|timeline|visual-review|plan|render-preview|render-final|evaluate');
 }
 
 function videoCommand(action, description, options) {
@@ -208,6 +220,58 @@ async function importTranscript(options) {
   return { ok: true, action: 'video.transcribe', project: projectSummary(project), beats };
 }
 
+async function importAudioAlignment(options) {
+  const project = await readProject(options);
+  const asrPath = requiredPath(options.named?.['asr-file'], '缺少 --asr-file。');
+  const parsed = JSON.parse(await fs.readFile(asrPath, 'utf8'));
+  const segments = extractAlignmentSegments(parsed);
+  if (segments.length === 0) {
+    return {
+      ok: false,
+      action: 'video.align',
+      project: projectSummary(project),
+      alignment_validation: {
+        ok: false,
+        errors: ['ASR/对齐结果里没有可用的 segments，无法生成带时间戳 beats。'],
+      },
+    };
+  }
+
+  const alignment = {
+    version: 1,
+    source: path.resolve(asrPath),
+    imported_at: new Date().toISOString(),
+    text: stringOrDefault(parsed.text || parsed.data?.text || parsed.result?.text, segments.map((item) => item.text).join('')),
+    segments,
+  };
+  const beats = segments.map((segment, index) => ({
+    beat_id: `beat_${String(index + 1).padStart(3, '0')}`,
+    text: segment.text,
+    start_s: segment.start_s,
+    end_s: segment.end_s,
+    intent: '',
+    visual_need: '',
+    emotion: '',
+    alignment_source: 'audio_alignment',
+  }));
+  await writeJson(path.join(project.work_dir, AUDIO_ALIGNMENT_FILE), alignment);
+  await writeJson(path.join(project.work_dir, BEATS_FILE), {
+    source: path.resolve(asrPath),
+    imported_at: new Date().toISOString(),
+    alignment_file: path.join(project.work_dir, AUDIO_ALIGNMENT_FILE),
+    beats,
+  });
+  return {
+    ok: true,
+    action: 'video.align',
+    project: projectSummary(project),
+    alignment,
+    beats,
+    alignment_path: path.join(project.work_dir, AUDIO_ALIGNMENT_FILE),
+    beats_path: path.join(project.work_dir, BEATS_FILE),
+  };
+}
+
 async function saveStrategySnapshot(options) {
   const project = await readProject(options);
   const templateType = stringOrDefault(options.named?.['template-type'], 'custom');
@@ -310,6 +374,61 @@ async function buildTimeline(options) {
   };
 }
 
+async function importVisualReview(options) {
+  const project = await readProject(options);
+  const reviewPath = requiredPath(options.named?.['review-file'], '缺少 --review-file。');
+  const review = JSON.parse(await fs.readFile(reviewPath, 'utf8'));
+  const visualSegments = await readOptionalJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE));
+  if (!Array.isArray(visualSegments) || visualSegments.length === 0) {
+    return {
+      ok: false,
+      action: 'video.visual-review',
+      project: projectSummary(project),
+      review_validation: { ok: false, errors: ['请先执行 video timeline 生成 visual_segments.json。'], warnings: [] },
+    };
+  }
+
+  const reviewValidation = validateVisualReview(review, visualSegments);
+  if (!reviewValidation.ok) {
+    return { ok: false, action: 'video.visual-review', project: projectSummary(project), review_validation: reviewValidation };
+  }
+
+  const byId = new Map((review.reviews || []).map((item) => [item.segment_id, item]));
+  const reviewedSegments = visualSegments.map((segment) => {
+    const item = byId.get(segment.segment_id);
+    if (!item) return segment;
+    return {
+      ...segment,
+      description: item.description,
+      subjects: Array.isArray(item.subjects) ? item.subjects : [],
+      scene: stringOrDefault(item.scene, ''),
+      motion: stringOrDefault(item.motion, ''),
+      semantic_tags: Array.isArray(item.semantic_tags) ? item.semantic_tags : [],
+      quality_score: isFiniteNumber(item.quality_score) ? Number(item.quality_score) : null,
+      visual_review_source: path.resolve(reviewPath),
+      agent_review_required: false,
+    };
+  });
+  const payload = {
+    version: 1,
+    source: path.resolve(reviewPath),
+    imported_at: new Date().toISOString(),
+    reviewed_count: review.reviews.length,
+    reviews: review.reviews,
+  };
+  await writeJson(path.join(project.work_dir, VISUAL_UNDERSTANDING_FILE), payload);
+  await writeJson(path.join(project.work_dir, VISUAL_SEGMENTS_FILE), reviewedSegments);
+  return {
+    ok: true,
+    action: 'video.visual-review',
+    project: projectSummary(project),
+    review_validation: reviewValidation,
+    visual_understanding_path: path.join(project.work_dir, VISUAL_UNDERSTANDING_FILE),
+    visual_segments_path: path.join(project.work_dir, VISUAL_SEGMENTS_FILE),
+    reviewed_segments: reviewedSegments.filter((segment) => byId.has(segment.segment_id)),
+  };
+}
+
 async function planFromAgentEdl(options) {
   const project = await readProject(options);
   const timelinePlanSource = normalizeOptionalPath(options.named?.['timeline-plan']);
@@ -334,9 +453,9 @@ async function planFromAgentEdl(options) {
       action: 'video.plan',
       project: projectSummary(project),
       agent_action_required: true,
-      required_inputs: ['strategy_snapshot.json', 'beats.json', 'visual_segments.json', '用户剪辑 brief'],
+      required_inputs: ['strategy_snapshot.json', 'audio_alignment.json 或 beats.json', 'visual_segments.json', 'visual_understanding.json', '用户剪辑 brief'],
       expected_outputs: [path.join(project.work_dir, TIMELINE_PLAN_FILE), path.join(project.work_dir, EDL_FILE)],
-      message: '由 Agent 读取规则库策略快照、beats 和 1秒1帧抽帧结果后生成 timeline_plan；timeline_plan 内可包含 edl，或再用 --edl 单独传入。',
+      message: '由 Agent 读取规则库策略快照、音频对齐结果、beats、视觉理解结果和 1秒1帧抽帧结果后生成 timeline_plan；timeline_plan 内可包含 edl，或再用 --edl 单独传入。',
     };
   }
   const edl = edlSource ? JSON.parse(await fs.readFile(edlSource, 'utf8')) : timelinePlan.edl;
@@ -480,6 +599,36 @@ function validateTimelinePlan(plan, beatsPayload, visualSegments) {
   return { ok: errors.length === 0, errors, warnings };
 }
 
+function validateVisualReview(review, visualSegments) {
+  const errors = [];
+  const warnings = [];
+  if (!review || typeof review !== 'object' || Array.isArray(review)) {
+    return { ok: false, errors: ['visual_review 必须是 JSON 对象。'], warnings };
+  }
+  if (!Array.isArray(review.reviews) || review.reviews.length === 0) {
+    errors.push('visual_review.reviews 必须是非空数组。');
+  }
+  const knownSegmentIds = new Set((visualSegments || []).map((segment) => segment.segment_id));
+  const seen = new Set();
+  for (const [index, item] of (review.reviews || []).entries()) {
+    const label = `reviews[${index}]`;
+    if (!item.segment_id) errors.push(`${label}.segment_id 不能为空。`);
+    if (item.segment_id && !knownSegmentIds.has(item.segment_id)) {
+      errors.push(`${label}.segment_id 未出现在 visual_segments.json 中: ${item.segment_id}`);
+    }
+    if (item.segment_id && seen.has(item.segment_id)) {
+      errors.push(`${label}.segment_id 重复: ${item.segment_id}`);
+    }
+    if (item.segment_id) seen.add(item.segment_id);
+    if (!item.description) errors.push(`${label}.description 不能为空，必须说明画面内容。`);
+    if (!Array.isArray(item.subjects)) warnings.push(`${label}.subjects 建议使用数组。`);
+    if (item.quality_score !== undefined && (!isFiniteNumber(item.quality_score) || Number(item.quality_score) < 0 || Number(item.quality_score) > 1)) {
+      errors.push(`${label}.quality_score 必须是 0 到 1 之间的数字。`);
+    }
+  }
+  return { ok: errors.length === 0, errors, warnings };
+}
+
 function buildRenderCommands(project, edl, assets, output, { final }) {
   const byId = new Map(assets.map((asset) => [asset.asset_id, asset]));
   const renderDir = path.join(project.work_dir, 'renders');
@@ -594,6 +743,29 @@ async function readScriptInput(options) {
   return '';
 }
 
+function extractAlignmentSegments(payload) {
+  const candidates = [
+    payload?.segments,
+    payload?.data?.segments,
+    payload?.result?.segments,
+    payload?.data?.result?.segments,
+    payload?.response?.segments,
+    payload?.words,
+    payload?.data?.words,
+    payload?.result?.words,
+  ];
+  const found = candidates.find((item) => Array.isArray(item));
+  return (found || [])
+    .map((item) => {
+      const text = stringOrDefault(item.text || item.word || item.sentence, '').trim();
+      const start = firstFiniteNumber(item.start_s, item.start, item.begin_s, item.begin, item.from);
+      const end = firstFiniteNumber(item.end_s, item.end, item.stop_s, item.stop, item.to);
+      return { text, start_s: start, end_s: end };
+    })
+    .filter((item) => item.text && isFiniteNumber(item.start_s) && isFiniteNumber(item.end_s) && Number(item.end_s) > Number(item.start_s))
+    .map((item) => ({ text: item.text, start_s: Number(item.start_s), end_s: Number(item.end_s) }));
+}
+
 function splitScriptToBeats(script) {
   return String(script)
     .replace(/\r/g, '\n')
@@ -755,6 +927,13 @@ function isFiniteNumber(value) {
   return Number.isFinite(Number(value));
 }
 
+function firstFiniteNumber(...values) {
+  for (const value of values) {
+    if (isFiniteNumber(value)) return Number(value);
+  }
+  return null;
+}
+
 function projectSummary(project) {
   return {
     project_id: project.project_id,