看懂视频 / Understand Videos

发布信息

• 中文名：看懂视频
• 英文名：Understand Videos
• SkillHub 发布名：看懂视频
• SkillHub slug：understand-videos
• SkillHub 页面：https://skillhub.cn/skills/user_0f00a14f/understand-videos
• 当前功能版本：1.10.0
• 当前本地版本以 _meta.json 为准；没有 _meta.json 时，按未知版本处理。
• 每次跨电脑安装、复制或疑似版本不一致时，先运行 scripts/skillhub_update.py 查询平台最新版，再决定是否更新。带 SKILLHUB_API_KEY 时脚本会同时读取后台版本列表，可看到正在审核或扫描中的最新版本；没有密钥时只能看到公开已审核版本。

目标

把视频变成可核查、可学习、可复用的知识资料：语音/字幕、关键帧、场景变化、画面文字、局部细节、时间线、标注截图、问题定位、内容结构诊断，以及可交付的图文报告。内部可以区分语音、画面、字幕/OCR 和外部资料的证据来源，但最终正文不要写成“语音识别到了什么、图像识别到了什么、两者如何互证”的清单；要把这些信息揉合成视频真正想告诉读者的知识点，逐条讲透其现象、原因、条件、边界、用途、风险和可复用判断。所有核心知识点必须经过“四真知识”过滤：真的是与真机有关，真的是与发现问题有关，真的是与解决问题有关，真的是充分利用 AI 深挖、分析、整理后让人信服，而不是简单搬运口播、字幕或网页资料。遇到元器件、模块、传感器、电机、电池、电源、连接器或电路板时，要把视频中出现的器件讲清楚：它是什么、视频怎样介绍、为什么用它、起什么作用、优缺点是什么、参数和选型边界在哪里、可能怎样失效、有没有更好替代。默认用简体中文回答，少说空话，多给关键证据、截图、可执行结论和必要的外部知识佐证。对产品、拆机、硬件、工艺或方案类视频，必须进一步回答：这些知识点还能用于哪些产品或给哪些产品赋能，落地时要注意什么；关键元器件、模组、结构件和材料的大致成本在哪里，按批量假设估算产品、电路、结构等单套材料成本范围。形成正式文案或报告时，默认输出 Word 文件。

四真第一准则与训练机制

把“四真”作为真机研究、AI 提问、报告撰写和知识入库的第一准则。任何视频分析、真知报告、团队复盘或知识沉淀，都必须先回答：它是否绑定真机，是否帮助发现问题，是否能推动解决问题，是否经过 AI 深挖和人工复核后足够让人信服。

• 坚持真机牵引：所有真知报告必须绑定真实整机、具体部件、图片、编码、场景或测试现象；没有真机锚点的内容只能作为背景，不能写成核心结论。
• 坚持每日训练：围绕真机开展常态化求真训练，建议每日投入半小时至一小时，长期用真实产品、真实图片、真实视频和真实测试现象迭代判断力。
• 坚持深度追问：每次分析至少完成从现象、原因、风险、验证、改进到商用价值的多轮追问；不能停在“看到了什么”或“AI 说了什么”。
• 坚持人工验证：AI 输出必须经过实物、数据、工程常识和专业判断交叉校验；不能把模型推断、口播观点或网页摘要直接当事实。
• 坚持报告沉淀：围绕在售或合作工厂量产机型持续形成分析报告，统一归档入库，保留证据路径、版本、日期、对象、结论和待验证项。
• 坚持团队协同：不同专业从硬件、结构、嵌入式、供应链、工艺、质量等角度共同补齐整机认知，报告中要标出需要哪个专业继续确认。
• 坚持自我复核：报告完成后逐项检查是否满足“四真”，是否真正让自己信服；不信服的内容降级为待验证、假设或删除。

执行任务时，把这些规则转化为内部检查表和报告目录，不要在正式报告里写成技能说明或口号。

快速流程

1. 保持原视频只读。把派生产物保存到新目录，通常放在 E:\codexouput\tansuo\video_analysis\<video_name>_<timestamp>。
2. 先确认真机锚点和问题切入：产品名称、型号/编码、来源、照片/视频、分析对象，以及本次到底要发现什么问题、解决什么问题或沉淀什么可复用认知；缺失信息要从画面、文件名、铭牌、用户描述或资料中补齐，仍缺失则标为待确认。
3. 先判断输入来源：实际视频路径、本地文件路径、文件夹、抖音/视频号分享链接、普通网页链接或可下载视频 URL。用 scripts/download_video.py --source 统一解析；能直接定位本地文件就直接返回路径，网页链接则尝试下载为本地文件。
4. 检查运行环境：优先运行 scripts/setup_environment.py --check 和相关脚本的依赖检查；缺少 Python 包且当前用户环境可写时，可主动用 scripts/setup_environment.py --install-basic 补齐基础依赖。系统级安装、模型大文件下载、GPU/驱动、浏览器 cookie 或账号授权必须先提示用户确认。无法补齐时，按“依赖与替代方案”说明补救路径和效果损失，不要卡死在单一路径。
5. 用 scripts/video_probe.py 读取元数据、抽取音频、生成关键帧和 frame_index.csv：
   - 全局概览：--frames 12 --contact-sheet
   - 指定时刻：--timestamps 00:01:12,00:01:18.5
   - 连续动作：--interval 5
   - 镜头/画面变化：--scene-step 1 --scene-threshold 16 --max-scene-frames 80
6. 打开 contact_sheet.jpg 和高价值原始帧；需要小字、铭牌、缺陷、手势、UI 状态时，从原始帧裁剪局部，不从联系图裁剪。
7. 有音频时运行 scripts/transcribe_audio.py 做语音识别；脚本优先调用本地 Whisper、python -m whisper、openai-whisper Python 包或 faster-whisper，输出 transcript.txt、transcript.json、transcript.srt 和 transcription_report.json。Whisper 依赖不可用时，优先启用 whisper-cpp-tiny 后端：调用 whisper.cpp 的 whisper-cli，优先使用技能资产中的 assets/models/ggml-tiny.bin 离线粗转写；轻量发布包缺少模型或工具时，在用户明确允许后下载并校验补齐。若 whisper.cpp 不可用或输出不可用，再尝试 FunASR：默认 paraformer-zh + fsmn-vad + ct-punc，适合中文长音频分段、标点恢复和更高质量兜底。FunASR 依赖仍不可用时，再尝试轻量离线 vosk-lite；Vosk 包或模型仍不可用时，再自动启用内置声学备用算法 fallback-vad，输出语音活动时间线、响度、停顿、节奏和置信度证据。可选使用用户已配置的 Groq、OpenAI 或其他转写服务，但不要强依赖云服务。
8. OCR 只作为辅助。小字、型号、仪表读数、人物身份、缺陷判断看不清时必须标注“不确定”。看到器件丝印、品牌、型号、封装、接口标识、铭牌或参数时，优先裁剪局部图并记录原始帧路径。
9. 把转写文本、字幕/OCR、关键帧和局部裁剪图作为内部分析材料：先提炼关键词、判断、因果、步骤、参数和知识点，再用同一时段或相邻时段的画面核查其可信度；必要时把压缩后的知识点或判断短语打入裁剪图/标注图中。随后执行“四真知识”过滤，把每个核心知识点拉回真机、真实问题、真实解决动作和可信推理链。主报告不写“语音说了什么、画面看到了什么、两者如何互证”，而是直接输出融合后的可用知识。
10. 执行 AI 多轮追问：围绕现象、公知信息、可能原因、风险、验证方式、改进路线、成本影响、量产可行性和商用价值逐轮追问。每一轮追问都要回到真机证据，不允许只堆模型观点。
11. 执行真机校验：用实物、测试、数据、图片、工程常识和专业判断筛选 AI 输出；能验证的写成结论，不能验证的写成待确认，明显不成立的删除或标为错误。
12. 对产品、拆机、硬件、工艺或方案类视频，补做两项商业化分析：一是把视频中学到的知识点迁移到可赋能的产品、场景或方案，逐项说明用途和落地注意事项；二是对关键元器件、模组、结构件、PCB、线束、电池、电源、外壳、传感器、执行器等做成本查询和批量 BOM 粗估，标明采购数量假设、渠道、币种、时间、价格区间和不确定性。
13. 需要做剪辑复盘、配图报告或二次创作时，引入 OpenCut 的时间线和镜头组织思路：把关键帧、局部图、标注图、剪辑点、口播重点和图文报告章节排成清晰顺序；OpenCut 只作为剪辑规划、镜头结构和本地项目能力参考，实际抽帧、裁剪、标注、转写和 Word 输出仍优先使用本技能脚本、image-video-annotation、FFmpeg 和文档技能。
14. 形成报告和知识入库材料：按用户问题交付摘要、关键证据定位、找 bug、拆爆款、提取口播稿、内容体检、图文 Word/PDF 报告或证据文件夹。最终正文必须逻辑清晰、容易读懂，去掉识别过程、时间戳流水、技能说明和无学习意义的内容；重点知识点要独立成节，图文结合讲透，最后做升华；发现不足、错误、矛盾或证据不足时要如实写出。报告完成后做自我复核，确认是否满足“四真”和是否值得入库。

来源获取

• 本地路径：支持 .mp4、.mov、.mkv、.webm、.avi、.m4v 等常见视频文件；用户给文件夹时，优先选最近修改的视频文件。
• 抖音、视频号、网页链接：先用 yt-dlp 尝试解析和下载。遇到登录、cookie、权限、反爬限制时，不伪装成功；改为提示用户提供本地视频、浏览器导出的可访问链接或授权 cookie 文件。
• 网页中的嵌入视频：优先让 yt-dlp 识别；必要时读取网页 HTML 中的 video/src、og:video、twitter:player:stream 等线索，再交给下载流程。
• 所有网络视频都必须落成本地文件后再分析，保证抽帧、转写、截图、报告过程可复核。

证据规则

• 区分“画面看到”“语音听到”“字幕/OCR 提取”“基于前后帧推断”。
• 具体结论尽量绑定 时间戳 + 原始帧路径 + 局部裁剪/标注图。
• 语音里的知识点必须尽量回到画面证据：讲到结构、参数、动作、问题、原因、经验时，查找对应关键帧或相邻帧。证据边界保留在分析记录、图注或括号中，主报告正文应直接围绕知识点展开，不把“语音+画面共同支持”写成独立清单。
• 只抽样时说明抽样策略，不声称逐帧完整看过。
• 模糊、遮挡、反光、分辨率不足时，不把猜测写成事实。
• 不把用户的 API key、cookie、账号信息写进日志、报告、压缩包或记忆。

多源信息融合分析

• 先从转写文本中提取 5 类材料：核心结论、步骤顺序、关键参数/名词、因果判断、可复用经验。
• 再从关键帧中提取 5 类材料：对象位置、动作变化、结构细节、屏幕/字幕/OCR 文字、异常或对比关系。
• 把两类材料在内部合并成“知识点卡片”：每个知识点至少说明它解决什么问题、视频中的现象是什么、背后的原因是什么、适用条件是什么、容易误判在哪里、可复用方法是什么。
• 主报告不要设置“语音摘要”“图像识别”“互证关系”这类面向识别过程的章节；这些只作为内部核查依据或证据附件。正文应按知识点、重点专题、可复用方法和限制项组织。
• 标注图可以直接写入关键词、短句或知识点，但要压缩成短标签，不能把长段转写文字塞进图里。长解释放在图注或正文，图注服务于知识点，不写成识别流水。
• 当语音、字幕/OCR 与画面矛盾时，在“不足、错误与待验证”中如实写出矛盾，并说明它影响哪些结论。
• 当某个结论只有语音、只有画面或只有外部资料支撑时，要降低确定性；可以写在图注、括号或限制项里，不要把不完整证据包装成事实。
• 当需要外部知识佐证时，优先查权威资料、行业资料或原始文档；引用后必须拉回视频中的真实对象和真实画面，说明这个外部知识对当前视频有什么用、哪里可用、哪里不能直接套用。

四真知识过滤

正式报告中的核心知识点必须通过四个问题筛选。没有通过的内容不要写成核心结论，只能降级为背景、推断、待确认项或删除。

• 真机锚点：这个知识是否紧扣视频里的真实设备、真实结构、真实动作、真实环境、真实故障或真实使用场景？能否配到关键帧、局部裁剪图、口播短句、字幕/OCR、铭牌、丝印、仪表读数或外部资料？如果只是一段通用百科，必须删减并拉回真机。
• 发现问题：这个知识能否帮助读者发现实际问题，例如设计缺陷、装配风险、选型不当、使用误区、可靠性隐患、成本浪费、体验短板、工艺不稳定或证据矛盾？如果不能帮助看出问题，只能作为背景说明。
• 解决问题：这个知识能否导向可执行动作，例如检查方法、验证实验、改进方案、选型边界、替代方案、降本路径、维修步骤、测试指标或下一步资料需求？不能行动的判断要继续追问“所以该怎么办”。
• 可信加工：这个知识是否经过 AI 辅助的检索、对照、推敲和整理后仍能让人信服？必须说明证据链、因果链、适用边界和不确定性；不能简单搬运视频口播、字幕、网页摘要或其他模型结论。

写作时把四真过滤融入正文，不要另写成“本技能如何过滤”的说明。推荐做法是让每个重点知识点都自然包含：真机证据、发现的问题、解决路径、可信理由和边界条件。

知识迁移与产品赋能

当视频中出现可复用知识点、结构方案、工艺方法、控制逻辑、用户体验设计、元器件选型、成本取舍或可靠性经验时，必须继续分析“还能用到哪里”。

• 先把知识点抽象成可迁移能力：例如检测、加热、驱动、供电、保护、降噪、密封、散热、结构固定、交互提示、维护便利、低成本实现或可靠性冗余。
• 再罗列可赋能产品：按相近产品、跨品类产品、工业/消费/汽车/医疗/家居/宠物/厨房/清洁/安防/传感器/小家电等场景分组，不要只写泛泛的“可用于智能硬件”。
• 每个产品方向至少说明 4 件事：可复用的知识点是什么、能带来什么价值、落地需要改哪些地方、特别要注意哪些风险或边界。
• 注意事项要具体：环境温湿度、安规认证、EMC、寿命、清洁维护、噪声、功耗、散热、防水防尘、材料兼容、用户误用、供应链稳定性、成本目标、装配工艺、量产一致性和应用等级差异。
• 不能把当前视频方案直接套到所有产品。凡是使用场景、功率等级、负载、材料、法规、用户接触方式或可靠性等级变化，都要说明需要重新验证。
• 最终报告建议设置“可赋能产品与落地注意事项”章节，用表格列出产品方向、复用知识点、价值、改造点、关键风险和验证建议。

成本查询与批量 BOM 粗估

当视频涉及产品、拆机、硬件结构、电路板、元器件、模组、传感器、电机、电池、电源、外壳、线束、连接器、包装或制造方案时，必须尽量给出材料成本的粗估范围。成本估算是工程判断，不是正式报价。

• 先列成本对象：关键元器件、模组、PCB、结构件、紧固件、线束、连接器、胶粘/密封材料、包装附件等；只对影响安全、性能、成本、可靠性或用户体验的项目重点查价。
• 能看到型号时按具体型号查价；型号不清时按同类器件、相近规格和应用等级查价，并明确写“按同类器件估算”。
• 查询渠道优先级：厂家官网/授权代理、立创商城、得捷、贸泽、Arrow、Octopart、1688/阿里巴巴、公开拆机 BOM、行业报价、同类产品拆解资料。必须记录价格来源、查询日期、币种、数量阶梯和是否含税/运费。
• 估算时至少给两档：小批量试产（如 100-1000 套）和批量量产（如 1 万套以上）。如果用户给出目标数量，以用户数量为准。
• 成本口径要分开：电路 BOM、结构件/外壳、模组/执行器/传感器、电池/电源、线束连接器、包装附件、装配损耗或加工费。不要把零售价、样品价和批量材料成本混在一起。
• 输出范围而不是单点：例如“约 3-6 元/套”，并说明主要不确定性来自型号不清、规格未知、采购量、品牌替代、地区、税费、良率和加工工艺。
• 对关键器件要说明成本取舍：为什么这个器件可能贵或便宜，降成本会损失什么，升级会带来什么收益，替代料需要验证哪些参数。
• 当视频证据不足时，只做“粗略 BOM 框架 + 待确认项”，不要硬编完整成本；明确需要补充 PCB 高清图、BOM、尺寸、材料、功率、认证等级或供应商报价。
• 最终报告建议设置“关键器件成本与单套材料成本粗估”章节，表格字段包括：项目、视频证据、估算规格、参考渠道、数量假设、单价范围、单套用量、小计范围、不确定性和验证建议。

元器件专项分析

当视频中出现元器件、模块、传感器、电机、电池、电源、连接器、线束、保险丝、继电器、MOS 管、二极管、电容、电阻、电感、芯片、PCB 或仪表读数时，必须按“能看清多少、讲清多少”的原则处理。

• 先从视频中提取器件清单：名称/类别、丝印或型号、封装/外形、所在位置、相邻器件、连接对象、视频中对它的讲述、对应截图或局部放大图。
• 对每个关键器件写清 6 件事：视频中的详细介绍、为什么使用它、在系统中的功用、优点、缺点或限制、参数/选型/应用边界。
• 对重要器件继续分析失效风险：过压、过流、过温、ESD、潮湿、振动、老化、接触不良、散热不足、误装、低成本替代带来的风险。
• 能看到具体型号或关键参数时，可查阅网上资料佐证。优先使用厂家数据手册、官方应用笔记、认证/标准文件、芯片厂商页面、可靠拆机资料和专业资料；不要只引用电商标题或论坛猜测。
• 查资料后要升华：说明资料中的参数、典型应用、限制或失效模式如何解释视频中的设计选择；哪些地方能直接套用，哪些地方因为场景、成本、工况、安规或可靠性不能直接套用。
• 给出替代方案时至少从成本、可靠性、可采购性、性能余量、维护难度、应用等级（消费、工业、汽车等）和制造装配影响中选择相关维度说明。
• 对决定成本的关键器件或模组，尽量查询当前公开价格或同类器件价格，按数量阶梯估算单套材料成本范围；不能查到具体型号时，按类别和规格区间估算并标明不确定性。
• 成本分析必须和选型理由放在一起：说明当前器件为什么值得用、哪里可能过度设计、哪里可能低配带来风险、有哪些可替代路线。
• 如果型号看不清或画面无法证明，不要硬编型号；写“疑似类别/待确认型号”，并说明需要补拍的角度、清晰度或资料。

截图与标注

优先截取能支撑判断的画面，而不是平均截一堆无用图。详细规则见 annotation-guide.md。

必须保留：

• 原始抽帧：frames/
• 局部裁剪：crops/
• 标注副本：annotated/
• 帧索引：frame_index.csv

值得截图的时刻包括：镜头切换、字幕变化、动作开始/停止、异常声光、产品铭牌、器件丝印、仪表读数、UI 报错、缺陷位置、讲解者手指或工具指向关键对象的瞬间。

标注能力包括：任意位置文字标注、顶部说明条、方框、箭头、局部裁剪、小图叠加、对比小窗、图中图、证据编号，以及把口播中的关键词/短句/知识点压缩后写入裁剪图或标注图。所有标注必须画在副本上。

OpenCut 辅助剪辑与配图输出

当用户要求“剪辑复盘、图文并茂、关键帧编排、视频分析后输出 Word、把截图配进报告、做二次创作建议”时，可把 OpenCut 作为时间线和镜头组织参考。它的价值不是替代本技能做转写、抽帧或自动导出，而是帮助把视频内容整理成更像专业剪辑稿和报告分镜的结构。

• 时间线整理：按开场、对象出现、关键动作、局部细节、异常/对比、结论画面，把关键帧和口播重点排列成读者容易理解的顺序。
• 剪辑点规划：标出应保留、可删减、需要慢放、需要局部放大、需要前后对比的画面；每个剪辑点都要说明服务哪个知识点。
• 配图节奏：正式 Word 报告中不要堆图；每个重点知识点优先选择 1 张全局图、1 张局部裁剪图或 1 张标注图，必要时再补对比图。
• 分镜式输出：复杂视频可生成“报告分镜表”，字段包括章节、画面来源、局部截图、图中标注、正文要讲的知识点、待验证证据和是否进入正文。
• 能力边界：当前本机 OpenCut 仓库主要作为开源剪辑项目和 UI/时间线参考，不能默认当成熟的命令行批量渲染、自动导出或视频理解后端。没有验证到可用导出接口时，不要承诺由 OpenCut 自动完成成片输出。

需要实际剪切、拼接、转码、抽音频、抽帧、截图标注或批量生成报告时，优先使用 FFmpeg、image-video-annotation、本技能脚本和文档生成技能；OpenCut 负责帮助组织镜头逻辑、剪辑建议和报告配图顺序。

深度分析方法

当用户要求形成“真知分析”“深度分析”“高价值文案”“图文报告”时，读取 deep-video-analysis-method.md。分析必须以视频中的真实对象、真实动作、真实画面为锚点，从重点画面出发追问原因、结果、变量、边界和可复用经验。不要泛泛总结，不要只写观后感；每次升华都要回到视频证据。

按问题看视频

当用户带着问题来，例如“这里为什么报错”“这段讲了什么”“帮我找关键画面”，先把问题转成时间定位策略：

• 找 bug/异常：用场景变化 + 指定时刻 + 间隔抽帧，比较异常前后状态。
• 看录屏/UI：提高抽帧密度，必要时关闭相似帧合并；重点看按钮、提示、输入值、状态栏和错误信息。
• 产品/拆机/电路板：优先截铭牌、连接器、丝印、走线、热源、损伤、工具指向位置和前后对比。
• 元器件/模块：优先截器件本体、丝印型号、周边连接关系、散热路径、绝缘隔离、固定方式、接口方向、铭牌参数和异常痕迹；能查到型号时补充资料佐证，并回到视频解释它为什么这样用。
• 课程/讲解/访谈：转写语音，按主题建立时间线，再用关键帧补充画面证据。
• 监控/事件复盘：只描述可见动作和时间关系，不做身份、动机、责任等无证据判断。

短视频内容体检

当用户要求“能不能发、为什么没人看、拆爆款、改口播、改标题、改封面、优化成片”时，读取 content-scoring.md，用六项体检：

• 开头留人 20
• 继续观看 15
• 容易看懂 15
• 真实可信 15
• 传播动力 15
• 行动意愿 20

每个扣分都要有原句、画面位置或时间点证据。评分后必须直接改好：给可发布口播稿、标题、封面文字、剪辑清单或 A/B 测试建议。材料不足时只检查能看到的部分，不给虚假的总分。

输出模板

根据任务选择模板，详细结构见 video-output-templates.md。

• 普通理解：一句话结论、视频想传递的核心知识点、重点知识点逐条讲透、关键截图、画面文字、待确认点。
• 找 bug：复现路径、关键异常点、证据帧、可能原因、下一步验证。
• 拆爆款：前 3 秒、信息缺口、节奏、镜头语言、证据、可复用结构、可改版本。
• 口播提取：除用户明确要求原始字幕外，默认输出整理稿；只保留必要时间点和听不清标记，不输出整段时间戳流水。
• 图文报告：输出 Word 文件，配原图、局部图、知识点标注图和图注；重点知识点独立成节，图文结合详细说明，最后做升华，并如实写出不足、错误、矛盾和待验证点。
• 元器件报告：输出器件清单、视频中的介绍、使用原因、功用、优缺点、参数/选型边界、失效风险、替代方案、成本查询、单套材料成本粗估、外部资料佐证和升华结论；每个关键器件至少配一张原图或局部标注图。
• 产品赋能与成本报告：输出视频知识点可赋能的产品清单、落地注意事项、关键器件价格来源、数量假设、单价区间、电路/结构/整机材料成本范围和待验证项。

真知报告必含内容

当用户要求“真知分析、深度研究、图文报告、知识入库、产品/拆机/硬件/工艺分析”时，输出至少包含以下内容。可根据材料调整先后顺序，但不能漏掉；没有证据的部分要补充追问、标为待确认或说明需要补充什么资料。

1. 真机信息：产品名称、型号/编码、来源、照片、分析对象；能从画面或资料确认的直接写，不能确认的列为待确认。
2. 问题切入：本次分析要发现或解决什么问题，例如质量风险、设计缺陷、成本机会、工艺问题、用户体验、可复用方案或商用价值。
3. 初步观察：整机、部件、材料、工艺、结构或电路特征；配关键截图、局部裁剪图或标注图，不堆无意义截图。
4. AI 多轮追问：围绕相关知识、公知信息、可能原因、风险和验证方式展开，至少覆盖现象、原因、风险、验证、改进和商用价值；正式报告只呈现追问后的高价值结论，不写成聊天记录。
5. 真机校验：结合实物、测试、数据、图片和工程常识筛选 AI 输出，说明哪些结论可确认、哪些是推断、哪些需要补拍/测试/BOM/图纸/规格书继续验证。
6. 深知结论：明确本机型、本部件、本场景下真正有价值的认知；每条结论都要讲清为什么值得学习、适用边界和误用风险。
7. 问题与方案：指出风险、根因、优化建议、验证方法和量产可行性；方案要能落到设计、选型、测试、工艺、供应链或质量动作。
8. 复用价值：说明该结论可用于哪些产品、项目、客户沟通或后续改进；写清复用条件、改造点、应用等级差异和验证建议。

报告末尾增加“四真自我复核”：逐项判断真机锚点、发现问题、解决问题、可信加工是否成立，并给出仍未让人信服的证据缺口。这个复核要像工程检查，不写成空泛表态。

最终交付取舍规则

• 最终报告只写用户能学习、判断或行动的内容：结论、证据、因果、规律、方法、风险和建议。
• 报告必须突出融合后的知识价值：不要罗列“语音识别到了什么、图像识别到了什么、两者互相证明什么”，也不要把“语音摘要”和“关键截图”写成两个孤立列表；应围绕知识点把口播要点、关键帧、裁剪图、标注图和必要外部知识组织成一条清楚的逻辑线。
• 重点知识点要逐一“揉碎”：先说明它是什么，再解释为什么成立、视频哪里体现、适用条件是什么、容易踩什么坑、下次如何判断或复用。重点内容要独立成节，配图、局部放大图或标注图详细说明。
• 涉及元器件时，不能只说“用了某器件”。必须说明它在视频对象中的位置、作用、选用原因、优缺点、关键参数、使用边界和失效风险；能查到可靠资料时，用资料把分析升华成选型方法或设计判断。
• 涉及产品、拆机、结构或方案时，要继续回答“这些知识点还能赋能哪些产品”，并列出每类产品的复用价值、改造点、应用等级差异和验证注意事项。
• 涉及硬件成本时，要查询或估算关键元器件、模组、结构件和材料价格，按数量阶梯给出电路、结构、整机等单套材料成本范围；所有成本都要标注来源、日期、币种、数量假设和不确定性。
• 报告最后必须有升华：把视频中的零散现象沉淀成方法、判断标准、检查表、改进建议或可迁移认知。发现不足、错误、矛盾、证据缺口或不适用场景时，在末尾如实表达。
• 不把识别过程写进正文，例如调用了哪个后端、跑了哪些命令、生成了哪些中间文件、模型怎样回退；这些只留在 transcription_report.json 等证据文件里。
• 不输出时间戳流水账。不要把每几秒的画面/口播排成大表；只保留能支撑结论的关键时间点、关键截图和必要原句。
• 不写技能说明、工具说明、能力展示、内部流程说明，也不要告诉读者“本技能可以……”。报告要像给人看的专业材料，不像软件说明书。
• 删除无学习意义的填充内容：空泛评价、重复描述、无证据猜测、与用户问题无关的素材罗列、无结论的截图堆砌。
• 如果用户明确要求“完整时间线、完整字幕、识别过程、调试日志”，才把这些内容放到附录或单独文件，不放在主报告正文。

Word 输出要求

• 用户要求“文案、资料、报告、真知分析、图文并茂输出”时，默认创建 .docx，不要只在对话中给正文。
• Word 文件使用中文字体和 UTF-8 内容链路，避免乱码；图片标题、表格、图注和文件名都使用可读中文。
• 正式报告中只呈现视频本身、融合后的知识点、分析判断和可复用认知，不写内部方法来源、识别过程、技能说明或与来源材料相关的无关场景字样。
• 输出结构应体现“明朗化、系统化、专业化”：先讲清核心结论，再讲透因果关系，最后沉淀可复用判断；避免时间戳流水和素材堆砌。
• Word 正文要按读者学习路径组织：先给真机信息和问题切入，再写初步观察、核心结论、重点知识点、AI 多轮追问后的判断、真机校验、问题与方案、复用价值、成本或器件分析，最后升华为可复用方法并做“四真自我复核”；不要出现“语音识别结果如下”“图像识别结果如下”“两者互证如下”等标题。
• 生成后尽量渲染检查页面，确认无乱码、图片缺失、文字遮挡、表格拥挤和图注错位。

版本查询与自动更新

用 scripts/skillhub_update.py 管理平台版本。脚本默认查询 SkillHub 公开页，不把密钥写入文件；如需访问私有接口，把密钥只放在当前进程环境变量 SKILLHUB_API_KEY。

常用命令：

python scripts/skillhub_update.py
python scripts/skillhub_update.py --download-to "E:\codexouput\tansuo\skillhub_packages\understand-videos_latest.zip"
python scripts/skillhub_update.py --install --target "C:\Users\JackZhou\.codex\skills\understand-videos"
python scripts/skillhub_update.py --install --target "C:\Users\JackZhou\.workbuddy\skills\understand-videos"

执行规则：

• 更新前先读取 _meta.json 的 version，再查询 SkillHub 版本。带 SKILLHUB_API_KEY 时以后台 dashboard_latest_version 为准；不带密钥时以公开 latestVersion.version 为准。
• 只有用户明确要求更新或安装时才执行 --install。
• 安装时必须校验 zip 路径安全，禁止解出绝对路径或 .. 路径。
• 安装前保留 understand-videos_backup_<时间戳> 备份；如果用户要求配置列表只保留最新版，把备份移出技能根目录。
• 输出必须使用中文和 UTF-8；不得把 SKILLHUB_API_KEY、cookie、账号等信息写入报告、日志或压缩包。

脚本

scripts/skillhub_update.py

• 查询 SkillHub 平台发布名称、slug、公开页面、当前本地版本和平台最新版。
• 可下载 SkillHub 最新公开包；用户明确传入 --install 时，覆盖本地 skill 目录并保留备份。
• 适合跨电脑迁移后快速检查“本机是否是平台最新版”。

scripts/download_video.py

• 统一解析本地路径、文件夹、视频 URL 和网页链接。
• 用 yt-dlp 下载用户有权访问的视频链接，包括抖音、视频号、网页嵌入视频等能被解析的来源。
• 输出本地视频路径 JSON，后续交给 video_probe.py。
• 遇到 401/403/cookie 要求时回退为本地文件模式。

python scripts/download_video.py --source "D:\video\clip.mp4" --out "E:\codexouput\tansuo\video_analysis\downloaded"
python scripts/download_video.py --source "https://example.com/video" --out "E:\codexouput\tansuo\video_analysis\downloaded"
python scripts/download_video.py --source "https://v.douyin.com/xxxx/" --cookies-from-browser chrome --out "E:\codexouput\tansuo\video_analysis\downloaded"

scripts/video_probe.py

• 用系统 FFmpeg 或 imageio-ffmpeg 获取元数据。
• 抽取 audio_16k_mono.wav、关键帧、联系图、frame_index.csv 和 metadata.json。

python scripts/video_probe.py --video "D:\input\clip.mp4" --out "E:\codexouput\tansuo\video_analysis\clip" --frames 12 --contact-sheet
python scripts/video_probe.py --video "D:\input\clip.mp4" --out "E:\codexouput\tansuo\video_analysis\clip" --scene-step 1 --scene-threshold 16 --max-scene-frames 80 --contact-sheet
python scripts/video_probe.py --video "D:\input\clip.mp4" --out "E:\codexouput\tansuo\video_analysis\clip" --timestamps "00:01:12,00:01:18.5"

scripts/transcribe_audio.py

• 从视频或已抽取音频中执行语音识别，生成 transcript.txt、transcript.json、transcript.srt 和 transcription_report.json。
• 支持自动语言识别、指定中文或其他语言、翻译任务、上下文提示词、依赖检查和失败回退说明。
• 优先使用本地 whisper 命令；没有命令时尝试 openai-whisper Python 包；也可在已安装时使用 faster-whisper。
• Whisper 依赖不可用时，优先使用 whisper-cpp-tiny：完整本地安装会调用 assets/bin/whisper.cpp/win-x64/Release/whisper-cli.exe，加载 assets/models/ggml-tiny.bin。该模型大小为 77,691,713 字节，SHA256 为 be07e048e1e599ad46341c8d2a135645097a538221678b7acdd1b1919c6e1b21。tiny 模型速度快、体积小，适合离线初稿和快速定位；噪声、低音量、重口音、专有名词、长静音段可能误识别或重复输出，正式报告必须结合画面字幕、OCR 或人工复核。
• whisper.cpp 工具缺失时，可通过 --whisper-cpp-cli 指定本机路径；Windows 预编译包缺失时，在用户明确允许后用 --download-whisper-cpp-tool 下载并校验。模型缺失时，在用户明确允许后用 --download-whisper-cpp-model 从 Hugging Face 或镜像补齐。
• 自动后端顺序：whisper 命令 -> openai-whisper Python 包 -> faster-whisper -> whisper.cpp tiny -> FunASR -> Vosk -> 内置声学备用算法。每层失败原因写入 transcription_report.json 的 auto_backend_errors，不要只看最终输出。
• whisper.cpp 不可用或输出不可用时，再使用 funasr 后端。默认模型是 paraformer-zh，搭配 fsmn-vad 和 ct-punc，适合中文语音、长音频分段和标点恢复；首次运行会把模型缓存到 ~/.cache/understand-videos/funasr，也可用 --funasr-model-dir 指定本地模型目录。更强模型可显式指定 FunAudioLLM/Fun-ASR-Nano-2512；多语言场景可指定 FunAudioLLM/Fun-ASR-MLT-Nano-2512。Nano 类模型通常需要 --funasr-trust-remote-code，正式报告中必须结合视频画面、字幕、OCR 或人工复核专业词。
• FunASR 不可用时，再使用 vosk-lite 轻量离线转文字。Vosk 需要 vosk Python 包和本地小模型目录；可通过 --vosk-model 指定，也可在用户明确允许时用 --download-vosk-model 下载官方小模型。默认中文使用 vosk-model-small-cn-0.22，英文使用 vosk-model-small-en-us-0.15。
• 缺少 Whisper 依赖时，自动启用内置 fallback-vad 声学备用算法：把音频规范化为 16k 单声道 PCM，按短帧计算 RMS 响度、峰值、过零率、动态噪声底，合并短停顿，输出 fallback_speech_timeline.csv 和 fallback_acoustic_frames.csv。该算法可靠定位“哪里有语音、哪里停顿、哪里重读”，但不能等同于自然语言听写；报告中必须标注“备用算法检测，不是完整转写”。

python scripts/transcribe_audio.py --check-deps
python scripts/transcribe_audio.py --media "D:\input\clip.mp4" --out "E:\codexouput\tansuo\video_analysis\clip\transcript" --language auto --model base
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --language zh --model small --initial-prompt "这是一段产品讲解视频"
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend whisper-cpp-tiny --language zh
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend whisper-cpp-tiny --language zh --whisper-cpp-cli "D:\tools\whisper.cpp\whisper-cli.exe"
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend funasr --language zh
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend funasr --funasr-model paraformer-zh --funasr-vad-model fsmn-vad --funasr-punc-model ct-punc
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend funasr --funasr-model "FunAudioLLM/Fun-ASR-Nano-2512" --funasr-trust-remote-code
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend vosk-lite --language zh --vosk-model "D:\models\vosk-model-small-cn-0.22"
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend vosk-lite --language zh --download-vosk-model
python scripts/transcribe_audio.py --audio ".\audio_16k_mono.wav" --out ".\transcript" --backend fallback-vad

scripts/annotate_frame.py

• 裁剪局部截图，画框、箭头、任意位置中文文字、小图叠加和图中图，只生成副本。

python scripts/annotate_frame.py --image ".\frames\frame_001_00-01_120.jpg" --out ".\annotated\motor_label.jpg" --crop "120,80,520,360" --box "30,30,220,110,铭牌区域" --label "00:01.120 电机铭牌"
python scripts/annotate_frame.py --image ".\frames\frame_010.jpg" --out ".\annotated\compare.jpg" --text "40,40,关键状态" --inset ".\crops\detail.jpg,620,60,260,180,局部放大"

依赖策略

基础能力需要 Python、Pillow、FFmpeg 或 imageio-ffmpeg。URL 下载需要 yt-dlp。语音识别优先使用本地 Whisper：可用 whisper 命令、openai-whisper Python 包或 faster-whisper；Whisper 不可用时优先使用 whisper.cpp tiny + ggml-tiny.bin 做离线粗转写，本机完整版可携带模型，平台轻量包可在用户允许后自动下载并校验补齐；whisper.cpp 不可用或输出不可用时再用 FunASR 做中文高质量兜底，需要 funasr、modelscope、torch、torchaudio，默认模型为 paraformer-zh；FunASR 仍不可用时再用轻量离线 vosk-lite，需要 vosk Python 包和小模型；Vosk 仍不可用时使用内置 fallback-vad 备用算法生成语音活动证据；也可在用户明确配置后使用 Groq、OpenAI 或其他服务。OCR 可用 Tesseract、PaddleOCR、EasyOCR 或视觉模型。要输出 Word/PDF 报告时，配合本机文档技能生成并渲染检查。

跨电脑下载技能后，先主动做依赖体检：

python scripts/setup_environment.py --check
python scripts/setup_environment.py --install-basic
python scripts/transcribe_audio.py --check-deps

执行规则：

• 可主动配置：当前 Python 用户环境内的轻量包，例如 pillow、imageio-ffmpeg、yt-dlp、requests、python-docx。安装前后都要输出依赖状态。
• 需提示确认：系统级 FFmpeg、Tesseract、浏览器扩展、模型大文件、whisper.cpp 二进制、Vosk 模型、FunASR/Torch、GPU/驱动、cookie/账号授权。
• 安装失败不终止任务：先走可用能力，并把“缺少什么、补救办法、缺少后少什么效果”写给用户。
• 不把安装日志、账号、cookie、API key 写入报告或发布包。

缺少可选依赖时，不中断整体任务；先用可用的抽帧、截图、人工视觉识别和证据时间线完成分析，并明确说明哪些能力没有启用。

常见缺失与影响：

• 缺 FFmpeg 且没有 imageio-ffmpeg：不能稳定抽帧、抽音频和生成联系图；补救是安装 imageio-ffmpeg、系统 FFmpeg，或用播放器/剪辑软件手工导出关键帧。
• 缺 yt-dlp：网页/抖音/视频号链接下载能力下降；补救是安装 yt-dlp、提供本地视频、浏览器可访问直链或录屏。
• 缺 Whisper/whisper.cpp/FunASR/Vosk：语音转文字质量下降；补救是安装其中任一后端、使用云端转写，最差可用 fallback-vad 只保留语音活动、停顿和重读位置，但不能得到完整文字。
• 缺 OCR：小字、丝印、屏幕文字识别依赖人工查看或视觉模型，元器件型号和仪表读数可信度下降；补救是提供高清截图、局部放大图、Tesseract/PaddleOCR/EasyOCR 或人工确认。
• 缺 Word/PDF 生成依赖：只能先输出 Markdown/图片文件夹，正式 Word/PDF 排版和渲染检查会受限；补救是安装 python-docx、LibreOffice/Office 或使用本机文档技能。

跨电脑运行时按以下顺序补齐：

1. Python 路线：安装 Python 3.10+，再安装 pillow imageio-ffmpeg yt-dlp vosk；需要 Whisper 精度时再补 openai-whisper，需要更快转写可补 faster-whisper；需要中文高质量备用识别时安装 funasr modelscope torch torchaudio，首次运行自动下载或读取 FunASR 模型；需要 OCR 或 OpenCV 时再补 pytesseract opencv-python。
2. 无系统 FFmpeg 路线：安装 imageio-ffmpeg，video_probe.py 会自动寻找它内置的 FFmpeg。
3. whisper.cpp 路线：优先使用本机技能资产中的 Windows whisper-cli.exe 和 ggml-tiny.bin；其他电脑上如果没有二进制或模型，可安装 whisper.cpp，或传入 --download-whisper-cpp-tool --download-whisper-cpp-model 自动补齐。SkillHub 轻量发布包如果不携带二进制和大模型，也必须保留脚本自动下载和 SHA256 校验逻辑，本机安装后再补齐资产。
4. 无 Python 路线：用 VLC、mpv、PotPlayer、剪映、达芬奇、Premiere 或系统截图工具导出关键帧；用 Whisper Desktop、剪映字幕、飞书妙记、通义听悟、FunASR Web/服务化版本、OpenAI/Groq/其他转写服务生成字幕；再把截图和字幕交给模型分析。
5. 浏览器/网页视频路线：优先让 yt-dlp 下载；失败时使用浏览器开发者工具、平台导出、录屏或用户提供本地文件。涉及登录、cookie、权限时必须让用户授权，不伪装成功。
6. 云端替代路线：在本机性能不足时，可以用云端转写、OCR、视频理解模型或其他 Agent 先生成时间线/截图候选，再由本技能复核证据并输出 Word 报告。

依赖分层：

• 必需：能读取输入视频或截图；能输出中文文本。
• 强烈建议：Pillow 或等价图片处理工具，用于标注截图；FFmpeg、imageio-ffmpeg 或等价抽帧工具，用于稳定抽帧。
• 可选增强：yt-dlp、whisper.cpp/ggml-tiny.bin、FunASR、ModelScope、Torch/Torchaudio、Vosk 小模型、Whisper/openai-whisper、faster-whisper、OCR、OpenCV、PyAV、moviepy、pysubs2、python-docx、PDF/Word 渲染工具。
• 内置兜底：fallback-vad 声学语音活动检测，不依赖 Whisper 模型，适合在无法安装语音识别模型时保留语音节奏、停顿和疑似口播时间证据。
• 不可强依赖：任何单一云服务、单一浏览器 cookie、单一平台下载能力。缺失时换用本地文件、录屏、手工抽帧或用户提供材料继续分析。