[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-93538":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":9,"rankLanguage":9,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":9,"pushedAt":9,"updatedAt":31,"readmeContent":32,"aiSummary":9,"trendingCount":15,"starSnapshotCount":15,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},93538,"qiaomu-cut-skill","joeseesun\u002Fqiaomu-cut-skill","joeseesun","乔木智能视频导演 Skill：素材治理、双语字幕、品牌包装与可复现渲染 | Agent-native video director with governed sourcing and verifiable rendering",null,"JavaScript",227,29,113,1,0,42,97,181,94.13,"MIT License",false,"main",true,[25,26,27,28,29,30],"agent-skill","ai-video","ffmpeg","nodejs","subtitles","video-editing","2026-07-22 04:02:09","# qiaomu-cut\n\n**中文** | [English](#english)\n\n> 你只说一句“我要什么视频”，它把素材、分镜、字幕、转场、动效、渲染和质检组织成一个可复现的视频工程。\n> Say what video you want; qiaomu-cut turns it into a source-aware, renderer-ready, verifiable video project.\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-black?style=flat-square)](LICENSE)\n[![Skill](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fagent%20skill-qiaomu--cut-blueviolet?style=flat-square)](SKILL.md)\n\n![qiaomu-cut 架构示意](docs\u002Fassets\u002Fqiaomu-cut-demo.svg)\n\n## 为什么值得用\n\n普通 AI 会给你一段剪辑建议，真正开剪时还要你自己找素材、查版权、装 ffmpeg、写字幕、调转场、验编码。\n\nqiaomu-cut 把这些拆成一个可复用的视频导演系统：它先生成 `QiaoCut IR`，再按环境路由到 33台词、ClipSeek\u002FPexels\u002FPixabay、本地素材、ListenHub\u002FMarsWave 图片\u002F视频\u002FTTS\u002FVoice\u002F音乐、Coli 本地 ASR、agent 图片生成、HTML\u002FManim\u002FPPT 等可用引擎，最终由 ffmpeg-full 合成。\n\nv0.5 已真实实现的是：项目时间线渲染、三层双语 ASS、移动端大字号与平台安全区、20 套品牌片头片尾模板、无缩放快速片尾、完整句裁切规则、素材文件\u002F场景去重门、macOS 与文件型旁白、程序音乐、原声混合、`preview` \u002F `standard` \u002F `final` 三档渲染、分层验收和项目内缓存；同时完整锁定 MarsWave 上游技能快照，并用安全 adapter 接入其当前 CLI 能力、付费\u002F上传确认、私有任务 capture、生成物下载校验和 manifest 入库。HTML 视频捕获、Manim\u002FPPT 直出、复杂遮罩、速度渐变和完整转场库目前仍是工作流接口与扩展方向，不冒充已经全部内置。\n\n它不是承诺“魔法般永远一键完美”，而是把专业视频制作流程变成 agent 能执行、能验证、能继续扩展的工程。\n\n## 一行安装\n\n```bash\nnpx skills add joeseesun\u002Fqiaomu-cut-skill --skill qiaomu-cut\n```\n\n本地开发或手动安装：\n\n```bash\nmkdir -p ~\u002F.agents\u002Fskills\ncp -R qiaomu-cut ~\u002F.agents\u002Fskills\u002Fqiaomu-cut\n```\n\n验证：\n\n```bash\nnode ~\u002F.agents\u002Fskills\u002Fqiaomu-cut\u002Fscripts\u002Fqcut.js doctor --json\n```\n\n## 你可以这样说\n\n- “搜索几句电影里的脏话台词，混剪成英语学习视频。”\n- “用免费素材做一个 60 秒挖掘机英语启蒙视频。”\n- “介绍乔布斯，做一个电影感人物短片，有时间线和档案照片。”\n- “把这个口播视频剪成小红书风格，强字幕、B-roll、卡点转场。”\n- “用 3Blue1Brown 风格解释 Transformer attention。”\n- “给我的网站做一个产品发布视频，网页动效融入剪辑。”\n- “用 AI 生成三个电影感转场镜头、中文旁白和配乐，再合成 45 秒预告片。”\n\n## 它会做什么\n\n1. 把一句话需求变成 `QiaoCut IR`：时长、比例、受众、风格、分镜、素材策略、渲染器。\n2. 搜索、生成或整理素材：33台词、ClipSeek、Pexels\u002FPixabay 原站、本地文件、ListenHub 图片\u002F视频\u002F旁白\u002F音乐、Coli ASR、网页\u002F信息源。\n3. 设计专业镜头：推拉摇移、匹配剪辑、J\u002FL cut、遮罩、字幕跟随、标题卡、动态图形。\n4. 选择渲染引擎：ffmpeg-full、HTML\u002FHyperFrames-style、Motion\u002FCSS\u002FSVG、Manim、PPT\u002Fslide、composite。\n5. 先用 `preview` 快速迭代，内容锁定后再用 `standard` 或 `final` 渲染。\n6. 输出与档位匹配的成片、contact sheet、缓存命中、阶段耗时和质检信息。\n\n## 前置条件\n\n- [ ] Node.js 18+：`node --version`\n- [ ] 使用 ListenHub provider 时 Node.js 20+，并运行 `scripts\u002Fbootstrap_listenhub.sh --check`。\n- [ ] macOS 推荐 Homebrew：`brew --version`\n- [ ] ffmpeg-full：`scripts\u002Fbootstrap_macos.sh --check`\n- [ ] 需要影视台词素材时，本机已安装并登录 33台词 App，并另行安装获得授权的 `33tc` CLI adapter；用 `which 33tc` 验证，或设置 `QIAOMU_33TC_CLI`。\n- [ ] 需要发布到 GitHub 时，GitHub CLI 已登录：`gh auth status`\n- [ ] 需要 AI 图片生成时，当前 agent 环境提供图片生成工具。\n- [ ] OpenAPI 路由从环境变量 `LISTENHUB_API_KEY` 或 ListenHub 官方本机 credential store 读取凭据，命令使用 `listenhub openapi ...`；OAuth\u002Finternal 路由需用户明确执行 `listenhub auth login`，命令使用顶层 `listenhub ...`。两者不是同一认证命名空间，不要把 key 放进命令、项目或仓库；doctor 会检查两类凭据文件均为普通文件且权限不宽于 `0600`。\n\n安装 ffmpeg-full：\n\n```bash\n~\u002F.agents\u002Fskills\u002Fqiaomu-cut\u002Fscripts\u002Fbootstrap_macos.sh --install\n```\n\n这个脚本不会强制覆盖系统 `ffmpeg`。运行时优先使用：\n\n```text\nQIAOMU_FFMPEG\n\u002Fopt\u002Fhomebrew\u002Fopt\u002Fffmpeg-full\u002Fbin\u002Fffmpeg\n\u002Fusr\u002Flocal\u002Fopt\u002Fffmpeg-full\u002Fbin\u002Fffmpeg\nffmpeg\n```\n\n安装已审计版本的 ListenHub CLI 与 Coli 本地 ASR：\n\n```bash\n~\u002F.agents\u002Fskills\u002Fqiaomu-cut\u002Fscripts\u002Fbootstrap_listenhub.sh --install\nnode ~\u002F.agents\u002Fskills\u002Fqiaomu-cut\u002Fscripts\u002Fqcut.js listenhub doctor --json\n```\n\n安装脚本锁定 `@marswave\u002Flistenhub-cli@0.0.15`（`listenhub --version` 协议版本 `0.1.0`）和 `@marswave\u002Fcoli@0.0.20`。`--check` 遇到缺失、包名无法验证或版本不匹配会失败；`--install` 会对缺失或错版的包执行精确版本安装。它不运行 `npm view`，不跟随 `latest`，也不显示凭据。\n\n## CLI 示例\n\n检查本机能力：\n\n```bash\nnode scripts\u002Fqcut.js doctor --json\n```\n\n通过已登录的本机 33台词 App 搜索台词：\n\n```bash\nnode scripts\u002Fqcut.js 33tc search \"dig deeper\" --limit 8 --json\n```\n\n`qcut 33tc` 原样透传内置的 `search`、`pick`、`cut`、`tasks`、`download`、`me` 子命令。`pick` 和 `cut` 会创建剪辑任务，可能消耗账号积分；先核对影片、时间范围和输出目录，只有明确确认后才加 `--yes`。skill 不会替你静默确认。\n\n检查 ListenHub\u002FMarsWave 能力（只读，不消耗积分）：\n\n```bash\nnode scripts\u002Fqcut.js listenhub doctor --json\nnode scripts\u002Fqcut.js listenhub auth status --json # 仅查 OAuth\u002Finternal 登录状态\nnode scripts\u002Fqcut.js listenhub openapi video estimate --model doubao-seedance-2-pro --resolution 720p --duration 5 --ratio 16:9 --json\n```\n\n确认估算后创建远端任务：\n\n```bash\nnode scripts\u002Fqcut.js listenhub openapi video create \\\n  --prompt \"slow cinematic push-in on an excavator at dawn\" \\\n  --model doubao-seedance-2-pro --resolution 720p --duration 5 --ratio 16:9 \\\n  --no-wait --json --qcut-project .\u002Fexcavator-video --yes\n```\n\n上面是 API key 路由，因此必须使用 `openapi video`。只有完成 OAuth 登录后，才使用顶层 `listenhub video ...` internal 路由。配置 API key 不会让顶层路由自动获得 OAuth 状态。\n\n远端创建、解析和可能收费的音乐操作都要求 `--yes` 与 `--qcut-project`；引用本地图片\u002F视频\u002F音频时还要求 `--allow-upload`。创建返回的 task ID 会记入一份私有 capture。所有 capture 只能位于项目内 `.qiaocut\u002Fjobs\u002Flistenhub\u002F`，以 `0600` 保存；终端只显示去密钥、去签名 URL 的摘要。\n\n用创建结果中的 task ID 轮询。只读 `get` 加上 `--qcut-project` 后也会自动保存一份私有结果 capture：\n\n```bash\nnode scripts\u002Fqcut.js listenhub openapi video get TASK_ID_FROM_SUBMIT \\\n  --json --qcut-project .\u002Fexcavator-video\n```\n\n状态完成后，从这份 **poll capture** 把临时 URL 本地化并写入素材清单：\n\n```bash\nnode scripts\u002Fqcut.js fetch .\u002Fexcavator-video \\\n  --result .qiaocut\u002Fjobs\u002Flistenhub\u002F\u003Cpoll-capture>.json \\\n  --field result.videoUrl --kind video --provider listenhub --json\n```\n\n这就是 `submit → poll capture → fetch` 闭环。下载器会从 capture 补全 provider、task ID、model、积分和 capture 摘要等 provenance（provider 未返回的字段明确记为未报告），且不把临时 URL 写入 manifest。它只允许 HTTPS，拦截私网\u002F本机地址，限制重定向与体积，检查 Content-Type 和媒体魔数，使用临时文件 + 原子 no-clobber 落盘。已有本地生成物可用：\n\n```bash\nnode scripts\u002Fqcut.js ingest .\u002Fexcavator-video \u002Fpath\u002Fto\u002Fgenerated.mp4 \\\n  --kind video --provider listenhub --task-id \u003Cid> --model \u003Cmodel> --json\n```\n\n### 讲解旁白默认策略\n\n讲解\u002F口播音频优先使用 ListenHub，默认期望的 speaker\u002Fvoice 名称是“向阳乔木”。默认使用专用闭环命令，不要手工拼 speaker ID：\n\n```bash\nnode scripts\u002Fqcut.js listenhub narration \\\n  --text-file scripts\u002Fnarration.txt \\\n  --qcut-project .\u002Fexcavator-video --yes --json\n```\n\n该命令自动执行只读 speaker list，在本地对“向阳乔木”做唯一完全匹配，再调用 TTS、验证音频签名与所选容器、导入 `assets-manifest.json`、清理 staging，并返回可直接写入时间线的 `timelineNarration`。默认输出无损 WAV，避免 MP3 解码后再编码 AAC 的二次有损；需要节省空间时可显式 `--format mp3`。Manifest 会记录 speaker ID\u002Fname、speaker catalog 摘要、旁白文本摘要、任务\u002Fcapture\u002Fmodel\u002F积分等 provenance。找不到、同名多个、账号未授权或调用失败时立即停止，不会悄悄改用其他音色；此时只能使用用户已提供的 file narration，或请用户选择。\n\n当前 OpenAPI TTS 没有已验证的 estimate 子命令，因此调用前必须明说“费用\u002F积分未知”并取得本次 `--yes`；`--yes=false` 等伪确认会被拒绝。`--text-file` 必须是项目内普通文件，也可用 `--text` 传短文本。最终旁白统一以带 manifest 身份校验的 `narration.engine=file` 进入 timeline。原始 `openapi speakers\u002Ftts` 透传仅用于调试，不是默认工作流。\n\n### AI 生图默认策略\n\n生图提示词的风格必须从本片的**主题、受众、年代、情绪和媒介**推导，不把“电影感”、“粘土”、“像素”或任何单一风格硬编码为全局默认。生成第一张图前先写 visual bible：色板、时代\u002F材质、镜头与构图、光线、对比度、纹理、字体\u002F图形语言、人物和负面约束；后续镜头继承这套一致性。个别提示词与内容语义或 visual bible 不匹配时，拒绝直接生成，先重写提示词或重新规划该镜头。\n\n`qcut plan` 会产出具体的 visual bible ID、媒介、时代、情绪、色板、光线、构图、负面提示与 prompt prefix。生成结果入库时必须带回同一个 ID、实际 prompt、model 与 provider 返回的 seed（若有）；直接文件用 `qcut ingest --visual-bible-id \u003Cid> --prompt \u003Cprompt> --seed \u003Cseed>`，URL 结果在 `qcut fetch` 使用同名参数。\n\n本地转录不消耗 ListenHub 积分：\n\n```bash\nnode scripts\u002Fqcut.js listenhub asr assets\u002Finterview.wav \\\n  --model sensevoice --json --qcut-project .\u002Fexcavator-video\n```\n\n首次使用 ASR 模型可能下载约 60 MB；当前只把它描述为全文转录，不冒充逐词字幕对齐。\n\n搜索 ClipSeek 免费素材候选：\n\n```bash\nnode scripts\u002Fqcut.js clipseek \"挖掘机\" --type video --limit 5 --json\n```\n\n生成剪辑计划：\n\n```bash\nnode scripts\u002Fqcut.js plan \"做一个 60 秒挖掘机英语启蒙视频\" --workflow stock-story --json\n```\n\n创建一个可继续制作的视频工程：\n\n```bash\nnode scripts\u002Fqcut.js scaffold .\u002Fexcavator-video --brief \"做一个 60 秒挖掘机英语启蒙视频\" --json\n```\n\n填好项目内 `timeline.json` 后，先执行快速预览：\n\n```bash\nnode scripts\u002Fqcut.js render .\u002Fexcavator-video --profile preview --json\n```\n\n确认内容、字幕、节奏和构图后再生成正式成片：\n\n```bash\nnode scripts\u002Fqcut.js render .\u002Fexcavator-video --profile final --json\n```\n\n`render` 默认读取 `\u003Cproject-dir>\u002Ftimeline.json`；也可用 `--timeline alternate-timeline.json`。为兼容 v0.2，省略 `--profile` 仍等价于 `--profile final`，不会悄悄降低既有项目的输出质量。时间线里的素材、字幕、旁白和输出路径必须是项目相对路径，渲染器会同时检查词法路径与软链接物理路径。已有输出默认保留；确认目标均为可替换的生成物后，才加 `--force`。调试时可加 `--keep-build` 保留本次唯一构建目录。\n\n### 三档性能工作流\n\n| 档位 | 默认渲染策略 | 默认校验 | 适合场景 |\n|---|---|---|---|\n| `preview` | 长边不超过 960、最高 24 fps、`ultrafast`、单遍响度；不生成 contact sheet | `basic`：流、尺寸、帧率、时长、像素格式、空文件 | 反复调整素材、字幕、节奏和构图 |\n| `standard` | 长边不超过 1280、最高 30 fps、`veryfast`、单遍响度；最多 8 帧 contact sheet | `standard`：`basic` + 最终响度\u002F峰值 + 静音扫描 | 内部审阅、日常快速交付 |\n| `final` | timeline 原始尺寸\u002F帧率和既定编码参数、两遍响度、完整 contact sheet | `full`：`standard` + 全片黑场扫描 | 公开发布、归档、客户终稿 |\n\n只有 `profile=final`、`validation=full`、技术校验通过，且字幕字体不是 `system-unverified` 时，渲染报告的 `releaseReady` 才会是 `true`。`--validation basic|standard|full` 可以用于诊断，但一般不要把较弱校验与正式发布混用。\n\n非 `final` 档会使用独立文件名，例如 `renders\u002Ffinal.preview.mp4`、`renders\u002Ffinal.standard.mp4`，对应字幕和报告也带档位后缀，不会覆盖正式成片。`--output` 可指定新的项目相对输出路径。\n\n### 项目内缓存\n\n默认缓存位于 `\u003Cproject>\u002F.qiaocut\u002Fcache\u002F`，复用未变化的镜头片段、macOS TTS 和已烧录字幕的画面；缓存键包含素材指纹、时间线参数、渲染档位和 ffmpeg 版本。渲染报告会记录 `cache.hits`、`cache.misses` 和逐阶段 `timings`。排查缓存问题时可临时使用 `--no-cache`，平时不要主动关闭缓存。\n\n同一台开发机上的 60 秒 DIG 双语样片实测如下，结果仅用于比较档位和冷热缓存，不是跨机器速度承诺：\n\n| 场景 | 耗时 |\n|---|---:|\n| v0.2 原始 `final` | 71.6 秒 |\n| v0.3 `preview` 冷缓存 | 27.7 秒 |\n| v0.3 `preview` 暖缓存 | 3.3–4.1 秒 |\n| v0.3 `standard` 冷缓存（TTS 已暖） | 27.1 秒 |\n| v0.3 `standard` 暖缓存 | 4.1 秒 |\n| v0.3 `final\u002Ffull` 冷缓存（TTS 已暖） | 65.6 秒 |\n| v0.3 `final\u002Ffull` 暖缓存 | 8.5 秒 |\n\n`qcut render` 已在内部执行与档位对应的技术校验并写入 render report。渲染后不要机械地再运行一次 `qcut verify`；该命令保留给外部生成、移动后或单独收到的视频文件。\n\n生成 ASS 字幕和 HTML 场景：\n\n```bash\nnode scripts\u002Fqcut.js ass captions.json --output subtitles.ass\nnode scripts\u002Fqcut.js html-scene qiaocut-ir.json --scene s01 --output scenes\u002Fs01.html\n```\n\n生成素材授权报告：\n\n```bash\nnode scripts\u002Fqcut.js license assets-manifest.json --output license-report.md\n```\n\n查看工作流：\n\n```bash\nnode scripts\u002Fqcut.js workflow list\nnode scripts\u002Fqcut.js workflow show english-mix --json\n```\n\n验证外部生成、移动后或单独收到的视频：\n\n```bash\nnode scripts\u002Fqcut.js verify .\u002Ffinal.mp4 --json\n```\n\n## 双语字幕策略\n\n英语学习和跨语言视频默认使用三层信息架构：\n\n1. 主字幕：英文原句或主语言，承担听读训练。\n2. 中文层：自然、简洁的中文字幕，不做生硬逐词直译。\n3. 注释层：词义、语境、音标或素材来源，放在顶部安全区。\n\n三层不是所有视频的硬性模板。中文人物片、无旁白氛围片等项目应按内容删减层级。最终要从 contact sheet 和关键帧人工检查字号、遮挡、安全区与译文语义。\n\n有 `fontsDir` 时优先使用项目指定字体；没有时，渲染器会自动查找本机已安装的 Noto Sans CJK SC，并仅复制到项目私有的 `.qiaocut\u002Fcache\u002Ffonts\u002F` 供本机渲染。skill、Git 仓库和发布包不会捆绑、上传或再分发本机字体。若项目必须跨机器复现，应由项目维护者自行选择具有再分发许可的字体并遵守其许可证。\n\n## 样例输出\n\n```json\n{\n  \"schema\": \"qiaocut.ir.v0\",\n  \"workflow\": {\n    \"id\": \"stock-story\",\n    \"title\": \"免费素材故事片\"\n  },\n  \"output\": {\n    \"durationSeconds\": 60,\n    \"aspect\": \"9:16\",\n    \"deliverables\": [\n      \"final.mp4\",\n      \"qiaocut-ir.json\",\n      \"assets-manifest.json\",\n      \"license-report.md\",\n      \"quality-report.json\"\n    ]\n  },\n  \"gates\": [\"doctor\", \"source manifest\", \"license report\", \"profile-aware render verification\"]\n}\n```\n\n## 内置工作流\n\n| 工作流 | 适合做什么 |\n|---|---|\n| `english-mix` | 电影台词、英语学习、俚语\u002F脏话表达、原声复读 |\n| `stock-story` | 免费素材科普、儿童启蒙、行业介绍、B-roll 故事 |\n| `person-profile` | 人物介绍、企业家传记、历史人物、档案短片 |\n| `explainer` | 数学\u002F算法\u002F科学解释，Manim\u002F3Blue1Brown 风格 |\n| `cinematic-short` | AI 视觉叙事、概念片、预告片、电影感短片 |\n| `product-launch` | 网站\u002FApp\u002FAI 工具发布视频，网页动效融入 |\n| `social-short` | 抖音\u002F小红书\u002FTikTok 竖屏强节奏短视频 |\n| `talking-head` | 口播精剪、访谈、播客切片、字幕和 B-roll |\n| `data-story` | 数据报告、排行榜、趋势、图表动画 |\n| `hybrid-studio` | 多素材源、多引擎、复杂客户级项目 |\n\n更多细节见 [`references\u002Fworkflows.md`](references\u002Fworkflows.md)。\n\n可执行时间线字段、双语字幕结构和渲染安全规则见 [`references\u002Ftimeline-schema.md`](references\u002Ftimeline-schema.md)。\n\n## 素材源\n\n- 33台词：影视台词搜索和片段工作流。公开 skill 只委托独立安装的 `33tc` adapter，不捆绑 App 私有协议；wrapper 会清洗结构化 token\u002Fcookie\u002Fpassword 字段和 URL，外部 adapter 仍必须保证不输出无字段标签的裸凭据。`pick` \u002F `cut` 在 wrapper 层要求裸 `--yes`，`--yes=false` 不算确认且不会调用外部 adapter。\n- ClipSeek：免费素材搜索聚合。已实现只读搜索 adapter。\n- Pexels \u002F Pixabay：通过 ClipSeek 结果回到原站确认下载和许可。\n- 本地文件：用户提供的素材优先，不覆盖原文件。\n- AI 生成：封面、插画、背景、缺口 B-roll、SVG\u002F网页视觉。\n- ListenHub\u002FMarsWave：图片、短视频镜头、TTS、Voice、多角色播客、音乐、Explainer、Slides 在线结果、内容解析；所有远端结果先本地化再进入 timeline。\n- 信息源：人物\u002F公司\u002F事件视频必须记录引用来源。\n\n重要：ClipSeek 是发现入口，不是最终许可证明。公开视频必须记录原站 source page 和 license。\n\nListenHub 上游仓库的 MIT 许可只覆盖代码和文档，不覆盖服务条款、模型、上传素材或生成内容。生成物默认记录为 `ai_generated` 与 `provider_terms_unverified`；参考图、音乐、人物肖像和影视素材的既有权利不会因 AI 处理消失。\n\n影视台词片段同样不因“能下载”而自动获得公开传播或商业使用权。33台词只复用本机已安装、已登录 App\u002FCLI 的状态，skill 不上传登录凭据、不输出 token；此类片段默认按学习、评论、研究或用户已获授权的范围处理。AI 生成图片会在素材清单中标记为 `ai_generated`，不能伪装成实拍或档案照片。\n\n## 渲染与验收边界\n\n`qcut render` 负责把已经准备好的项目时间线合成为成片，并按档位生成 contact sheet、render report 和技术校验。它不是“任意素材一键必然完美”的承诺：事实准确性、影视素材权利、字幕语义、人物肖像、审美取舍和平台规则仍需针对具体项目复核。\n\n建议交付门如下：\n\n- `doctor` 通过，确认 ffmpeg-full 具备 ASS\u002F字幕、overlay、drawtext 等能力；缺失时运行 `scripts\u002Fbootstrap_macos.sh --install`，由 Homebrew 自动下载安装，但不会强制替换系统 ffmpeg。\n- 每个外部素材在 `assets-manifest.json` 中记录 provider、source page 和许可状态；ClipSeek 结果回原站核验。\n- Skill 默认先执行 `preview`；确认内容与视觉后再执行一次 `final`。`standard` 用于不需要母版级编码但仍要响度、静音和 contact sheet 的日常交付。\n- `render` 成功返回视频、可选 contact sheet 和 render report；报告明确列出 profile、validation、缓存和逐阶段耗时。\n- `render` 已包含对应档位校验，不再重复调用独立 `verify`。`final\u002Ffull` 继续检查响度\u002F峰值、黑帧和静音，并人工抽看 contact sheet；`preview\u002Fbasic` 通过不代表可以公开发布。\n\n## 配套浏览器编辑器\n\n自动生成后如需人工拖拽精修，可使用独立的开源项目 [乔木剪辑](https:\u002F\u002Fgithub.com\u002Fjoeseesun\u002Fqiaomu-cut)。它是浏览器端多轨编辑器；本仓库则是 agent 自动导演与 CLI Skill。两者职责分离，后续通过工程交换格式衔接，不把尚未实现的互导描述成现成功能。\n\n## 致谢与参考\n\nqiaomu-cut 借鉴这些公开项目的方法和思想，不复制其私有内容：\n\n- [HyperFrames](https:\u002F\u002Fhyperframes.heygen.com\u002F)：HTML\u002FCSS\u002FJS 作为 agent-native 视频创作格式。\n- [Motion](https:\u002F\u002Fmotion.dev\u002F)：网页动效、时间线、SVG\u002FHTML 动画。\n- [Manim Community](https:\u002F\u002Fwww.manim.community\u002F) 与 [3b1b\u002Fmanim](https:\u002F\u002Fgithub.com\u002F3b1b\u002Fmanim)：程序化解释动画。\n- [Theatre.js](https:\u002F\u002Fwww.theatrejs.com\u002F)：关键帧和 motion design 思路。\n- [FFmpeg](https:\u002F\u002Fffmpeg.org\u002F)：最终合成、编码和音视频处理。\n- [ClipSeek](https:\u002F\u002Fclipseek.ai\u002F)：视频\u002F照片\u002F插画素材发现。\n- [marswaveai\u002Fskills](https:\u002F\u002Fgithub.com\u002Fmarswaveai\u002Fskills)：ListenHub\u002FMarsWave 技能契约与能力说明；完整固定快照及原 MIT LICENSE 保存在 `vendor\u002Fmarswaveai-skills\u002F`，适配代码不代表双方关联或背书。\n\n## Troubleshooting\n\n| 问题 | 原因 | 解决 |\n|---|---|---|\n| `missing filter: subtitles` | 当前 ffmpeg 不是 full build | 运行 `scripts\u002Fbootstrap_macos.sh --install`，或设置 `QIAOMU_FFMPEG` |\n| ClipSeek 搜索有结果但不能直接下载 | ClipSeek 返回的是原站页面 | 打开 `sourcePage`，在 Pexels\u002FPixabay 等原站确认下载和许可 |\n| 33台词不可用 | 本机未安装 App、未登录或 `33tc` CLI 未链接 | 先打开 33台词 App 登录，再检查 `33tc search` |\n| ListenHub 显示 CLI missing \u002F wrong version | provider 依赖未安装、被 PATH 中其他包遮蔽、版本不匹配或 Node \u003C 20 | 运行 `scripts\u002Fbootstrap_listenhub.sh --install`，再执行 `scripts\u002Fbootstrap_listenhub.sh --check` 与 `qcut listenhub doctor` |\n| 远端生成被 `--yes` 门阻止 | 该操作可能收费或写远端状态 | 先跑 estimate\u002F检查上传文件和费用，再对当前请求显式加 `--yes` |\n| 本地参考素材被拒绝上传 | 未确认第三方上传 | 核对 basename、类型和大小后再加 `--allow-upload` |\n| 生成结果只有临时 URL | 还没本地化到项目 | 用私有 capture + `qcut fetch` 下载并写入 manifest，不能把 URL 直接放 timeline |\n| 生成视频没有声音 | 输入素材无音轨或混音计划未执行 | 先读本次 render report 的 `verification.audio`；仅外部视频才单独运行 `qcut verify` |\n| README 发布检查失败 | YAML\u002F占位符\u002F缺少章节 | 运行 `python3 scripts\u002Fvalidate_skill.py .` 按报告修复 |\n\n## 风险和边界\n\n- 不删除、不覆盖用户原始素材。\n- wrapper 清洗结构化 token、cookie、password、账号配置和 URL；独立 adapter 不得输出无字段标签的裸凭据。\n- 不把 API key 放进参数、日志、任务 capture、manifest 或 Git；终端输出会清洗 Bearer\u002FJWT\u002F签名 URL。\n- 不执行 vendored 上游嵌套 skill 的自动安装、agent-memory 注入或 `cola-avatar-pack` 删除指令。\n- 未经 `--allow-upload` 不把本地素材发送给 ListenHub\u002F下游模型；Provider 数据保留和训练使用策略未有证据时标记 `unknown`。\n- 不声称素材“可商用”，除非原站许可已记录。\n- 不把 AI 生成素材伪装成真实拍摄素材。\n- 不把计划当成已完成渲染；缺证据必须写 `missing evidence`。\n\n## 平台与配置\n\n| 能力 | macOS | Linux | Windows |\n|---|---|---|---|\n| ffmpeg 时间线渲染 | 已验证 | 代码可运行，依赖需手动安装，尚缺 clean-host 证明 | 当前未支持 |\n| `macos-say` 旁白 | 已验证 | 不支持；改用已有录音 | 不支持；改用已有录音 |\n| 33台词 App adapter | 需 App 登录 + 独立 `33tc` | 取决于 adapter | 取决于 adapter，尚未验证 |\n| ffmpeg-full 自动安装 | Homebrew 已实现 | 尚未自动化 | 尚未自动化 |\n| ListenHub CLI | Node 20+ 已做本机只读 smoke | CLI 契约可用，尚缺 clean-host 证明 | 尚未验证 |\n| Coli 本地 ASR | 包存在；真实模型转录尚未作为发布证据 | 尚未验证 | 尚未验证 |\n\n| 变量 | 必需 | 说明 |\n|---|---:|---|\n| `QIAOMU_FFMPEG` | 否 | 指定带 libass\u002Floudnorm\u002Fsidechaincompress\u002Flibx264 的 ffmpeg |\n| `QIAOMU_FFPROBE` | 否 | 指定与 ffmpeg 配套的 ffprobe |\n| `QIAOMU_33TC_CLI` | 33台词工作流可选 | 指向独立安装、获得授权的 33tc adapter；否则从 `PATH` 查找 |\n| `QIAOMU_LISTENHUB_CLI` | ListenHub 可选 | 覆盖 `listenhub` CLI 路径；默认从 `PATH` 查找 |\n| `QIAOMU_COLI_CLI` | 本地 ASR 可选 | 覆盖 `coli` CLI 路径；默认从 `PATH` 查找 |\n| `LISTENHUB_API_KEY` | OpenAPI 工作流可选 | 环境变量优先，也可使用官方本机 credential store；均不写入项目或仓库，命令参数禁传 key；若已在聊天\u002F日志明文暴露，应立即撤销并轮换 |\n\n`missing evidence`：未运行任何 ListenHub 付费生成；只有本机 CLI 能力\u002Fstatus、mock 门禁和本地 adapter 证据。Provider 输入保留期、训练使用、数据地域与下游删除策略未知；未找到 33台词公开 API 文档，因此公开包没有宣称“只装 App 即零额外配置”；与浏览器编辑器的工程互导仍是后续接口。\n\n---\n\n\u003Ca name=\"english\">\u003C\u002Fa>\n# English\n\nqiaomu-cut is an agent-native video director skill. A short brief becomes a reproducible project with governed sourcing, shot planning, bilingual captions, brand cards, narration routing, ffmpeg rendering, and evidence-backed verification.\n\n## What is included\n\n- `QiaoCut IR` planning and deterministic timeline rendering.\n- Preview, standard, and final render profiles.\n- Three-layer bilingual ASS captions with mobile-safe typography.\n- Twenty selectable intro\u002Foutro families; internal template metadata never appears in public video.\n- Complete-sentence clip boundaries and quality-over-count deduplication.\n- Local media, ClipSeek discovery, governed 33tc adapters, and ListenHub\u002FMarsWave provider routing.\n- Asset manifests, provenance, licensing boundaries, render reports, and no-clobber path checks.\n\n## Install and verify\n\n```bash\nnpx skills add joeseesun\u002Fqiaomu-cut-skill --skill qiaomu-cut\nnode ~\u002F.agents\u002Fskills\u002Fqiaomu-cut\u002Fscripts\u002Fqcut.js doctor --json\n```\n\nFor development:\n\n```bash\nnpm run validate\nnpm run release-check\n```\n\nNode.js 18+ is required. ListenHub integration requires Node.js 20+. Full rendering needs an ffmpeg build with libass, drawtext, overlay, loudnorm, and H.264 support.\n\n## Security, privacy, and limits\n\nRemote creation may cost credits and always requires explicit `--yes`; uploading local media also requires `--allow-upload`. Credentials stay in environment variables or provider-owned local stores and must never enter commands, manifests, captures, or Git. A downloadable movie clip is not automatically licensed for redistribution. See [SECURITY.md](SECURITY.md), [CONTRIBUTING.md](CONTRIBUTING.md), and the Chinese sections above for the complete trust and licensing model.\n\n\u003C!-- qiaomu-profile:start -->\n## 关于向阳乔木\n\n向阳乔木（乔向阳 \u002F Joe）是一位实践型 AI 产品与内容创作者，长期把前沿 AI 变化转译成可复用的工作流、产品判断、AI 编程实践、AI 搜索实践和 GEO\u002FAI 营销方法。\n\n- 个人网站: https:\u002F\u002Fqiaomu.ai\n- 博客: https:\u002F\u002Fblog.qiaomu.ai\n- X: https:\u002F\u002Fx.com\u002Fvista8\n- GitHub: https:\u002F\u002Fgithub.com\u002Fjoeseesun\u002F\n- 微信公众号: 向阳乔木推荐看\n\n### 支持与关注\n\n| 打赏支持 | 微信公众号 |\n|---|---|\n| \u003Cimg src=\"assets\u002Fqiaomu-profile\u002Fqiaomu_reward_qr.png\" alt=\"向阳乔木打赏二维码\" width=\"180\" \u002F> | \u003Cimg src=\"assets\u002Fqiaomu-profile\u002Fqiaomu_wechat_public_account_qr.jpg\" alt=\"向阳乔木推荐看公众号二维码\" width=\"180\" \u002F> |\n| 感谢支持乔木持续分享 AI 实践 | 扫码关注「向阳乔木推荐看」 |\n\n\u003C!-- qiaomu-profile:end -->\n\n## License\n\nMIT © 向阳乔木\nX: \u003Chttps:\u002F\u002Fx.com\u002Fvista8>\nGitHub: \u003Chttps:\u002F\u002Fgithub.com\u002Fjoeseesun\u002F>\n",2,"2026-07-20 02:30:05","CREATED_QUERY"]