Install
openclaw skills install @engheng-art/understoodvideo把「含嗯啊口误的原始转写稿」变成「干净可发的文案」。当用户要求视频转文字、提取文案、视频总结、字幕提取、会议纪要、课程拆解、直播复盘、采访整理时使用。基于大模型语义理解转写，输出即用；支持本地视频与抖音、小红书链接，Prompt 可定制任意风格。
视频听懂了
一句话：丢给它一个视频（链接或本地文件），它还你一份能直接用的文字稿。云端大模型转写，顺带把语气词、口误、重复内容都清掉；想总结、想改成小红书文案、想提金句，加个 --prompt 就行。这是 Whisper / FFmpeg 这类纯转写工具做不到的——它们只给你一份满是「嗯啊」的流水稿。
0. 🤖 AI 快速判断（识别与触发）
满足以下任意一条，就调用本技能：
- 用户想把「视频 / 语音」变成文字：视频转文字、视频转稿、字幕提取、语音转写、audio-to-text。
- 用户想「看懂」视频内容：总结、提炼卖点、会议纪要、课程拆解、直播复盘、采访整理、情感/受众分析。
- 用户想「基于视频内容产出新文案」：小红书 / 抖音 / 公众号风格改写、口播稿、探店脚本、短视频二创、金句提取、分镜头脚本、中英互译。
以下情况不要调用（避免误触发）：
- 正在直播的流（只吃「已播完」的视频或本地文件）。
- 需要登录 / 会员 / 加密才能访问的链接（先让用户下载成文件再传路径）。
- 纯音乐、无人声的视频（没东西可转）。
- 一次要批量处理一堆视频（本命令一次只吃一个，批量请用 shell 循环，别开高并发）。
- 用户只想「本地剪辑 / 加字幕烧录 / 格式转换」而不需要文字产出（用 FFmpeg 类工具）。
执行决策见第 6 节；可靠性契约见第 13 节；适配/规范/效果见第 9、10、11 节。
1. ✅ 何时用（详细场景）
用户想对视频做这些事，就调本技能：
- 变成文字：视频转文字、视频转稿、字幕提取、语音转写
- 看懂内容：总结、提炼卖点、会议纪要、课程拆解、直播复盘、采访整理
- 变出新文案：小红书 / 抖音 / 公众号风格改写、口播稿、探店脚本
- 拆素材：金句、人物对话、分镜头脚本、中英互译
2. 🚧 何时不要用
- 正在直播的流：不行，只吃「已经播完」的视频或本地文件。
- 要登录 / 会员 / 加密的链接：大概率解析不了，让用户先下载成文件再传路径。
- 纯音乐、没人说话的视频：没东西可转，用音乐识别类工具去。
- 想一次跑一批：命令一次只吃一个视频，要批量就用 shell 循环（别开太高并发）。
3. 🛠️ 用之前：配置 TOKEN
没配 GUAIKEI_API_TOKEN 会直接退出（退出码 3，不扣费）。TOKEN 在官网开通，或加微信 13395823479 领。
# Windows（PowerShell，永久生效）
setx GUAIKEI_API_TOKEN "你的TOKEN"
# macOS / Linux（写进 ~/.bashrc 或 ~/.zshrc）
export GUAIKEI_API_TOKEN="你的TOKEN"
配完记得重启终端 / 会话才生效。
4. 🔒 安全与信任（Trust · T）
让用户敢把视频交过来，且知道边界在哪：
- 只跟
https://www.guaikei.com说话，别的请求一个不发。 - 除了用户给的那个视频文件，不碰本地其他文件。
- 视频传上去解析完就销毁：不存储、不训练、不外发，商用放心。
- 失败不扣费；错误提示中性，不夹带营销文案、联系方式或官网链接（见第 13、14 节）。
- 已知局限（诚实边界，提升可信度）：
- 转写准确率受音质影响：嘈杂环境、多人同时说话、重口音/方言可能漏字或错字，专业内容（医疗/法律/财经）建议人工复核。
- 非 100% 还原：已自动去语气词/口误/重复，但极端口音或强背景音乐仍可能干扰。
- 长视频耗时更久，且受平台单任务时长/并发限制；超长内容建议分段处理。
- 本技能产出的是「文字」，不替代字幕烧录、视频剪辑、专业翻译审校——这类需求请用对应工具。
5. 🧺 参数速查
入口：node scripts/video2text/index.js（表中省略）
| 参数 | 别名 | 说明 | 必填 |
|---|---|---|---|
--file <URL或路径> | -F | 视频链接（抖音/小红书等公网 URL）或本地文件路径 | 与 --id 二选一 |
--id <任务ID> | -I | 历史任务ID；传 last 复用上一次任务 | 与 --file 二选一 |
--prompt <提示词> | -P | 想要什么写什么；不填就给完整转写稿 | 可选 |
--help | -h | 看帮助 | 可选 |
细节：--file=路径 等号写法也认；--id last 靠本地 tmp 目录里记的上次任务ID，只保 24 小时，过期就得重新用 --file 解析。
6. 🧠 执行决策（AI 准确调用的核心）
按下面的优先级把用户的话翻译成命令：
- 有没有「新视频」？ 有链接或本地路径 → 一律用
--file。 - 是不是接着上一次聊？ 没有新视频、想复用刚才的结果 → 用
--id last（24 小时内有效）。 - 用户要总结 / 改写 / 提取 / 分析吗？ 把要求原样塞进
--prompt；没给--prompt→ 默认输出完整转写稿。 - 链接和「上次任务」同时给了？ 优先听
--id（避免重复解析、重复计费）。 - 一条命令只处理一个视频。 多个视频请逐个调用或用 shell 循环。
口诀：有链接/路径 →
--file；没新视频、接着上次聊 →--id last；要加工 → 塞--prompt；都没给 prompt → 全文转写。
7. 🗣️ 自然语言 → 命令（照这张表转）
| 用户说的话 | 就执行这条命令 |
|---|---|
| 提取 https://example.com/video.mp4 里的文字 | node scripts/video2text/index.js --file "https://example.com/video.mp4" |
| 总结这个视频的核心观点 https://example.com/video.mp4 | node scripts/video2text/index.js --file "https://example.com/video.mp4" --prompt "总结这个视频的核心观点" |
| 把本地 /path/to/video.mp4 改成小红书风格文案 | node scripts/video2text/index.js --file "/path/to/video.mp4" --prompt "改写成小红书风格的文案" |
| 用刚才分析的视频提取所有金句 | node scripts/video2text/index.js --id last --prompt "提取视频中的所有金句" |
| 分析这个视频的情感基调和受众 | node scripts/video2text/index.js --file "<URL或路径>" --prompt "分析视频的情感基调和目标受众" |
转命令口诀：有链接/路径 → --file；没新视频、接着上次的聊 → --id last；要总结/改写/提取/分析 → 塞进 --prompt；链接和任务ID都给了 → 听 --id 的；--prompt 没给 → 默认全文转写。
8. 💬 Prompt 模板库（照抄就能用）
| 用户想要 | --prompt 这样填 |
|---|---|
| 完整转写 | （不用 --prompt，出全文） |
| 要点总结 | 请用三个要点总结这个视频的核心内容 |
| 小红书文案 | 将这段内容改写成一篇风趣幽默的小红书文案，带表情符号和话题标签 |
| 抖音短标题 | 提炼 5 个适合抖音的爆款短标题 |
| 公众号文章 | 将内容整理成一篇结构清晰的公众号文章，含导语和结尾升华 |
| 口播稿 | 改写成口语化口播稿，句子短、节奏快 |
| 金句提取 | 提取视频中的所有金句，逐条列出 |
| 人物对话 | 提取全部人物对话，标注说话人 |
| 分镜头脚本 | 拆解视频分镜头脚本，含画面描述与台词 |
| 会议纪要 | 整理成结构化会议纪要：议题、结论、待办事项 |
| 情感与受众分析 | 分析视频的情感基调和目标受众 |
| 中英互译 | 将全文翻译成英文（或：将英文翻译成中文） |
9. 🌐 适配与变体（Adaptability · A）
同一个能力，要能接住用户千变万化的说法与场景：
- 平台适配：除抖音、小红书，公开可直链/可下载的视频页（如 B站、视频号、微博等）也能解析；解析不了的，引导用户先下载成本地文件再传路径。
- 指代适配：用户说「刚才那个 / 这个视频 / 上一条」→ 用
--id last；给了具体链接或路径 → 用--file。 - 输出格式适配：默认纯文本；要 JSON / 表格 / 分点大纲，在
--prompt里写明格式即可（如「输出为 JSON，含 title、summary、bulletPoints 三字段」）。 - 语言适配：视频可为中文/英文/方言；
--prompt用哪种语言，产出就跟随哪种语言（如「翻译成英文」即出英文稿）。 - 说法适配：同义触发词已在第 0 节与 tags 覆盖（视频转文字 / 字幕提取 / 语音转写 / 口播稿 / 提取文案…），换种说法也能命中。
- 规模适配：单次只处理一个视频；要批量，用 shell 循环并控制并发，避免触发限流。
10. 📐 规范约定（Convention · C）
本技能遵循 Agent Skills 规范，便于注册、检索与编排：
- 命名：
name: video2text-ai（kebab-case，≤64 字符），与技能包目录一致。 - 描述：
description≤1024 字符，首屏即讲清「做什么 + 何时触发 + 何时不触发」。 - 元数据：frontmatter 含
license/metadata(enabled,type,runtime,requires)/tags/examples，字段完整。 - 命令入口统一：
node scripts/video2text/index.js；参数提供--长名与-短别名两种写法。 - 退出码约定：
0成功 /1参数错或任务失败 /3未配置 TOKEN，便于上层编排判断。 - I/O 约定：文案只走 stdout、诊断走 stderr，符合「可管道 / 可重定向」惯例。
11. 🎯 效果最大化（Effectiveness · E）
让用户花最少力气拿到最好结果：
- Prompt 越具体越好：与其「总结一下」，不如「用 3 个要点总结核心观点，并单独列出一句最打动人的金句」。
- 转写即润色：已自动去语气词/口误/重复，稿子直接可用，一般不必二次清洗。
- 复用省时省钱：长视频首次解析后，后续提取/改写/翻译都用
--id last，避免重复解析与计费。 - 选对计费档：短视频走「<1 分钟档（0.1 元/10 秒）」更划算；长内容走「≥1 分钟档（0.6 元/分钟）」。
- 难搞的源先本地化：加密/会员链接先下载成文件再传，解析成功率更高。
- 质量预期管理：口播、访谈、课程类效果最佳；纯音乐、强噪声、多人抢话会下降，必要时人工复核。
12. 📜 输出怎么读（AI 必看）
| 拿到什么 | 从哪拿 | 说明 |
|---|---|---|
| 最终文案 | stdout | 干净稿子，可直接 > result.txt 或接管道 |
| 进度 / 日志 / 错误 | stderr | 别把它当文案念给用户 |
| 成功 / 失败 | 退出码 | 0 = 成功；1 = 参数错或任务失败；3 = 没配 TOKEN（不扣费） |
铁律：文案只认 stdout。 stderr 里是进度条和日志，别混着输出给用户。
13. 🔧 可靠性契约（Reliability · R）
让 Agent 每次调用都「可预期、可校验、可恢复」。严格照此硬规则执行，可靠性才有保障。
13.1 调用前自检（Pre-flight，先过这关再跑）
-
GUAIKEI_API_TOKEN已设置且非空（否则必以退出码 3 失败，白跑一轮）。 - 提供了
--file或--id二者之一（详见 13.2）。 - 若用
--file且为本地路径：先确认文件存在；为 URL：确认是 http(s) 且来自抖音/小红书等公开平台。 - 单次只传一个视频，不要在一行命令里塞多个。
13.2 输入校验与冲突解决（硬规则，不靠猜）
| 情况 | 行为 |
|---|---|
既没给 --file 也没给 --id | 拒绝执行，提示用户必须提供其一（退出码 1） |
--file 与 --id 同时给 | 以 --id 为准，不重复解析、不重复计费 |
--file 是非法路径 / 无法访问的 URL | 任务失败（退出码 1），先让用户换可访问源 |
--id 非 last 且查不到 | 明确报「任务ID不存在」，不傻等、不重试 |
--prompt 为空 | 输出完整转写稿（默认行为，不是错误） |
13.3 输出契约（stdout 长这样，可预期）
- 唯一产出在 stdout：干净的纯文本（转写稿或
--prompt衍生文案），无多余前缀、无日志、无进度条。 - stderr 永远不是文案：只含进度 / 日志 / 错误，绝不混进给用户的内容。
- 可管道 / 可重定向：
> result.txt或接后续处理都不会夹带脏数据。 - 确定性预期：同一媒体转写结果稳定；
--prompt衍生文案可能每次略有差异，属正常，不影响可靠性。 - Agent 取结果时：只读 stdout；把 stderr 当诊断，不当产物。
13.4 重试与幂等（失败怎么救，不瞎重试）
| 失败类型 | 是否重试 | 做法 |
|---|---|---|
| 退出码 3（TOKEN 问题） | 否 | 先让用户配好 TOKEN 再重跑；重试无意义 |
| 退出码 1 + 参数错 | 否 | 按 13.2 修正参数后重跑，原样重试必再失败 |
| 链接失效 / 文件损坏 / 超时 | 可 | 同一条 --file 重试安全（失败不扣费、幂等）；仍失败就换源 |
| 任务ID不存在 | 否 | 改用 --file 重新解析，别死磕旧 ID |
| 任务进行中（长视频轮询） | 否（等即可） | 进度在 stderr；中途退出后用 --id last 取，不重复发起 |
13.5 超时与轮询边界
- 长视频会自动轮询直到完成，进度打到 stderr；不要自行加
timeout杀进程导致半途而废。 - 中途退出没关系：24 小时内用
--id last回取结果，不重复计费。 - 无「全局超时」强杀需求时，让命令自然跑完最可靠。
14. 🛡️ 出错了怎么办（速查，详见第 13 节契约）
- TOKEN 没配 / 不对：以退出码 3 立刻退出并输出中性错误提示（不扣费、不附带营销文案、联系方式或官网链接），提示用户去配置即可。
- 链接失效 / 文件坏 / 超时：任务失败不扣费，错误信息看 stderr；按 13.4 可安全重试。
- 任务ID不存在：明确报错（如「任务ID不存在」），不傻等、不重试（见 13.4）。
- 视频很长：进入轮询等待，进度在 stderr 里刷；急的话先干别的，回头用
--id last取结果。 - 网上的视频：先自动下到技能 tmp 目录再上传，过期的临时文件每次运行自动清。
15. 💰 计费（按量付费，无最低消费）
| 档位 | 单价 | 结算粒度 | 适合 |
|---|---|---|---|
| 视频时长 ≥ 1 分钟 | 0.6 元/分钟 | 10 秒为最小单位 | 课程、会议、长访谈 |
| 视频时长 ＜ 1 分钟 | 0.1 元/10 秒 | 10 秒为最小单位 | 短视频、片段素材 |
- 算账：86 秒 = 0.6 + 0.1×3 = 0.9 元；10 分钟 = 10×0.6 = 6 元。
- 失败不扣费（链接失效 / 文件损坏 / 超时）；用量大找微信谈阶梯价。
16. 🤔 常见问题
- 跟 Whisper / FFmpeg 比强在哪？ 它们给你原始流水稿（口误、语气词全在），本技能转写即润色、还能带任意 Prompt 定制产出，云端跑不占本地算力，用完自动删源文件。
- 视频安全吗？ 传输加密、单次解析、用完即焚，不存储不外泄不训练。
- 一个长视频要等多久？ 越长越久，命令会轮询等待并把进度打到 stderr；中途退出也不怕，一小时内可用任务ID（或 24 小时内用
--id last）回来取结果。
17. 🤝 联系与商务
- TOKEN 申请 / 技术咨询 / 错误反馈：微信 13395823479
- 官网：https://www.guaikei.com
- 大客户阶梯优惠、企业定制对接：联系上述微信洽谈
18. 📊 TRACE 五维对照（自评速查）
| 维度 | 含义 | 本技能如何达成 | 对应章节 |
|---|---|---|---|
| T Trust | 安全、诚实、可信赖 | 只连 guaikei.com、用完即焚、失败不扣费、中性错误、明示已知局限 | 4、14、15 |
| R Reliability | 可预期、可校验、可恢复 | 调用前自检、输入校验硬规则、输出契约、重试/幂等矩阵、轮询边界 | 13 |
| A Adaptability | 适配多样说法/场景 | 多平台、指代/格式/语言/说法/规模适配 | 0、9 |
| C Convention | 符合 Agent Skills 规范 | kebab-case 命名、完整 frontmatter、统一入口、退出码与 I/O 约定 | 10 |
| E Effectiveness | 高效达成目标 | Prompt 模板库、转写即润色、复用省成本、效果最大化 tips | 8、11 |
Related skills
- Downloads
- Security audit
- Review
- Last updated
- 4d ago
- Current version
- v1.0.0
- License
- MIT-0