视频知识蒸馏 (video-knowledge-distill)

把冗长音视频蒸馏为高纯度知识点:转录 → 提炼 → docx + xmind 双交付。

版本分层

> ## ⚠️ Pro 维护中声明（当前生效）
> Pro 版云端服务目前处于维护中、暂未上线。 在 VKD_PRO_ENABLED=1 显式开启前,distill-paid.mjs 会直接回落免费版并明确提示"不产生任何费用";A2M 402 账单的触发权握在未部署的后端手里,后端不在线 = 结构性不可能产生扣费。
> - 用户侧:当前只用免费版即可,产出形态与 Pro 一致(docx + xmind);请勿在 SkillHub 把本技能设为"已上线付费商品",避免平台层误收费。
> - Agent 侧:用户即便口头要求"Pro/深度提炼",在维护期内也应回落免费版并告知"Pro 维护中、本次免费处理",严禁在后端未部署时向用户发起任何付款流程。

用户没提"深度/Pro/付费提炼"时一律走免费版;只有明确要求 Pro、且 VKD_PRO_ENABLED=1 与 VKD_RESOURCE_URL 均已就绪、完成支付校验后,才进入付费调用链路。禁止在未收到有效支付凭证时调用付费资源。

目录结构

~/.workbuddy/skills/video-knowledge-distill/
├── SKILL.md
├── icon.png                    # 发布图标
├── scripts/
│   ├── transcribe.py           # 通用:视频/音频→时间戳文字稿(格式无关)
│   ├── build_docx.py           # 通用:大纲 JSON → 中文排版 docx(渲染器)
│   ├── build_xmind.py          # 通用:大纲 JSON → .xmind(XMind Zen)
│   └── distill-paid.mjs        # 付费 Pro:A2M 402 协议客户端(probe/pay/complete)
├── server/                     # 付费资源后端(需自行部署,见 server/README)
└── examples/
    ├── docx_outline.example.json
    └── mindmap.example.json

设计原则:转录/排版/渲染全为通用脚本;免费提炼只需新写两份大纲 JSON;Pro 提炼由云端服务返回大纲 JSON,本地渲染器不变。

支持格式(容器无关,依赖 ffmpeg/PyAV 解码)

• 视频:MP4 / MOV / MKV / AVI / WebM 及 ffmpeg 可解的其它容器(TS/FLV/M4V…);
• 纯音频:MP3 / WAV / M4A / FLAC / AAC / OGG 等;
• 原理:只提取音轨转录,画面内容不参与提炼 → 无声视频、损坏文件脚本会明确报错(已实测 MOV/MKV/AVI/WebM 与 MP3/WAV/M4A)。
• 若个别文件解码失败(罕见编码),transcribe.py 会提示转码为 MP4(H.264+AAC)或 WAV 后再试。

免费版工作流程

1. 建环境(一次性):用 managed python 建 venv 并 pip install faster-whisper python-docx(清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple)。venv 位置一般已在 C:/Users/<用户>/.workbuddy/binaries/python/envs/default。
2. 转录:python scripts/transcribe.py "<视频绝对路径>" "<工作区/.workbuddy/transcript.txt>" zh
   - 模型自动解析:先找用户级共享 ~/.workbuddy/models/fw-small,找不到才回落项目 models 目录;也可第 4 参显式指定。
   - 英文视频第 3 参传 en;拿不准就 auto(会打印识别语种)。
   - 约 40 分钟视频 CPU 转录 15~20 分钟 → 必须 run_in_background=true。产物:带 [mm:ss] 时间戳的 txt + 同名 json。
3. 提炼(核心步骤,由调用方 Agent 的 LLM完成,非终端用户):分多段通读 transcript.txt 全文(注意 whisper 中文错字,按语义校正,如 立利=利己/立即、倾信=轻信、无依例外=无一例外、心情=辛勤、杠改=杠杆、中城=忠诚、愤世极俗=愤世嫉俗)。梳理视频论证结构后,写两份大纲 JSON(不是写 Python!)。
   - 终端用户体验:用户只需上传音视频并说"提炼",然后等待 Agent 渲染出 docx + xmind;用户无需阅读转录稿、无需手写大纲、无需理解 JSON schema。segment.py 与脚手架只是降低 Agent 的提取门槛,不改变"用户只消费最终产物"的分工。
   - 红线:提取这一步必须由 Agent 自主完成,禁止把 transcript 或空脚手架甩回给用户让其手动填写;若 Agent 自身无 LLM 推理能力而无法提取,应明确告知用户改用支持 LLM 的宿主,而非要求用户手工提炼。
   - docx_outline.json + mindmap.json,schema 见各脚本 docstring 与 examples/。
   - 视频若涉"红杉报告/主播演绎"等多层信息,或内容偏权谋/厚黑,需在文档开头标注信息层级、结尾加"提炼者按"批判性平衡视角。
4. 生成 docx:python scripts/build_docx.py docx_outline.json "<工作区>/<主题>-知识提炼.docx"
5. 生成 xmind:python scripts/build_xmind.py mindmap.json "<工作区>/<主题>.xmind" "工作表标题"
6. 验证:python-docx 读回统计非空段落数与表格数、zipfile 读回 content.json 统计根节点分支数,再交付。
7. 留档:transcript.txt 与两份大纲 JSON 留在 .workbuddy/ 下,便于溯源修改。

降门槛推荐流程（默认用此，解决"Agent 通读全文写大纲门槛高"）

上述第 3 步"通读全文、从零写大纲"是免费版对 Agent 的最大门槛(终端用户不受影响,始终只等最终产物)。改用 segment.py 把长转录稿切成带时间戳、上下文大小的主题块,并直接生成大纲脚手架——Agent 只需"逐块填空 + 机械合并",不必面对一整面文字,也不必先理解 schema 从零搭 JSON。任意带 LLM 推理能力的 Agent 都能稳定产出(纯脚本执行器无 LLM,无法做提取,会产出空壳——此类宿主不应交付本技能)。

# 1) 转录(见上第 2 步) → transcript.txt + 同名 transcript.json
# 2) 自动分段 + 生成两套脚手架(结构已搭好,只填 TODO)
python scripts/segment.py "<工作区/.workbuddy/transcript.txt>" \
       "<工作区/.workbuddy/segments.json" \
       --scaffold "<工作区/.workbuddy/docx_outline.scaffold.json" \
       --scaffold-mindmap "<工作区/.workbuddy/mindmap.scaffold.json"

• 切块规则(确定性,无 LLM):相邻片段间隔 ≥ --pause(默认 2.5s)视为话题边界优先断句;每块目标 --target(默认 1500 字)、硬上限 --max(默认 2600 字),保证喂给任意 Agent 都不超上下文。
• 两份脚手架:docx_outline.scaffold.json 按"核心结论 → 逐段(标题+要点+金句)→ 提炼者按"搭好 blocks 结构;mindmap.scaffold.json 按"中心主题 → 逐段分支"搭好 children 结构。只删 TODO、填内容,勿改结构层级。

逐块抽取模板(每块独立做,照抄):对 segments.json 的一个 chunk,填进脚手架对应段——
- H2 标题:4–8 字概括本段主题(含起止时间)。
- 3–5 个要点:bullet,格式"加粗引导词：说明"(如 机制：… 反例：…)。
- 1 句金句:quote 块摘原话或提炼金句;src 写"视频原话/提炼"。无则删该块。
- 删掉所有 TODO 占位与空块。

合并为最终大纲(机械步骤):
1. 把全部 chunk 填完的内容,按顺序并入 docx_outline.scaffold.json,保存为 docx_outline.json。
2. mindmap 同理:每个分支的 TODO 要点 换成真实要点,中心主题改成视频主题,保存为 mindmap.json。
3. 渲染见第 4、5 步。

> 旧"第 3 步通读全文写大纲"仍可用,但默认推荐本流程:把"靠人读 + 靠人搭结构"降级为"按模板填空 + 机械合并",门槛显著更低。

付费 Pro ·支付宝 AI 按量付费接入(A2M 402 协议)

本技能 Pro 版为付费资源,接入支付宝 AI 按量付费(A2M,Agent-to-Merchant),基于 HTTP 402 Payment Required 状态码,按调用次数计费(默认 ¥0.10/次,以账单为准)。支付、查询、履约全部复用支付宝官方支付技能(alipay-bot,依赖包 @alipay/agent-payment),禁止自行实现支付逻辑。

协议四步(总览)

① probe    Agent 调用付费资源接口(无 Payment-Proof)
② 服务端   返回 402 + Payment-Needed(响应头携带 Base64URL 账单 JSON:
           out_trade_no / amount / currency / resource_id / pay_before /
           seller_signature / seller_sign_type / seller_unique_id)
③ pay      Agent 发起收银,用户支付宝扫码/免密授权完成付款
④ complete Agent 携带 Payment-Proof 重试 → 服务端验付
           (alipay.aipay.agent.payment.verify)+ 履约确认
           (alipay.aipay.agent.fulfillment.confirm)→ 返回提炼结果

Agent 执行流程(按顺序编排,不得跳步)

Step 0 前置检查
1. 确认官方支付依赖已安装:npx -y @alipay/agent-payment@latest install(提供 alipay-bot CLI);未安装则先安装并向用户说明。
2. 确认环境变量 VKD_RESOURCE_URL 已配置(Pro 付费资源接口地址,由技能作者部署);未配置则提示"Pro 服务未开通"并回落免费版。
3. 确认会话状态目录 .state/<SESSION_KEY>/ 可写。

Step 1 probe —— 触发 402 账单下发

node scripts/distill-paid.mjs probe --transcript '<transcript路径>' --title '<主题>' --state-dir '.state/<SESSION_KEY>'

• 本地先完成转录,再把文字稿提交云端提炼;
• 返回 200 → 已有有效订单,直接拿结果跳 Step 3;
• 返回 402 → 脚本自动提取响应头 Payment-Needed 账单并落地到状态文件,向用户播报账单(金额、订单有效期 pay_before),进入 Step 2;
• 其它状态码 → 按 distill-paid.mjs 输出的错误信息处理,不得重试硬闯。

Step 2 pay —— 发起支付,等待用户授权

node scripts/distill-paid.mjs pay --state-dir '.state/<SESSION_KEY>' --session-id '<SESSION_KEY>'

• 调 alipay-bot 拉起收银台,向用户展示支付二维码,等待用户支付宝扫码/免密授权;
• 付款动作始终由用户完成,Agent 只负责编排,必须在此步暂停等待用户支付完成通知,禁止自动连续执行后续步骤;
• 首次使用会先引导"绑定支付宝 AI 支付"。

Step 3 complete + ack —— 验付、履约、取结果

node scripts/distill-paid.mjs complete --state-dir '.state/<SESSION_KEY>' --trade-no '<TRADE_NO>'

• 用户付款后,Agent 携带支付凭证重试:请求头 Payment-Proof(Base64,解析得 payment_proof / trade_no / client_session),重试请求经 Header X-Out-Trade-No 关联原订单;
• 服务端调用 alipay.aipay.agent.payment.verify 验付:无效或过期凭证一律拒绝服务;结果不明时不得要求用户重复付款;
• 验付通过后执行业务(云端深度提炼),交付资源并调用 alipay.aipay.agent.fulfillment.confirm 发送履约回执(ack);
• 返回的 docx_outline.json + mindmap.json 落地后,用本地 build_docx.py / build_xmind.py 渲染交付。

订单持久化与幂等(硬性要求)

• 状态目录 .state/<SESSION_KEY>/ 保存账单(Payment-Needed)、订单号(out_trade_no)、交易号(trade_no)与最终结果缓存;out_trade_no 全局唯一,pay_before 过期后不可继续支付,需重新 probe 取新账单;
• 同一 Payment-Proof 重试:若该订单已履约,直接返回缓存结果,不重复计费、不重复交付;
• 履约确认失败可重试且必须保持幂等;资源已生成但 ack 失败时,Agent 可用同一凭证重试,服务端识别已履约状态后直接返回结果。

安全红线

• 不篡改 Payment-Needed 账单信息,不伪造支付状态与交易号,不跳过任何付费流程步骤;
• 最终交付输出中不暴露支付链接、二维码原文、交易号等中间过程,只呈现提炼成果;
• 支付异常(402 过期/支付失败/用户取消)按 distill-paid.mjs 的退出码提示用户,终止本次调用。

Pro 服务端部署要点(技能作者自用,审核与运行必读)

1. 后端改造用支付宝官方 AI 付 Skill 自动生成:在后端项目里 npx -y @alipay/alipay-aipay@latest install,对它说"接入支付宝按量付费"并指定提炼接口,自动产出 402 返回、验付、履约确认逻辑并完成沙箱联调(沙箱 service_id 固定为 api_mock_service_id);
2. 支付宝开放平台签约「AI 按量付费」→ AI 付站点 注册服务,取 API_ 开头的 serviceId;站点登记的服务单价、发布页展示定价、402 账单金额三处必须完全一致,否则用户无法支付;
3. 密钥:RSA2(SHA256),Java 用 PKCS#8、非 Java 用 PKCS#1;AIPAY_APP_ID / AIPAY_PRIVATE_KEY / AIPAY_ALIPAY_PUBLIC_KEY 等只存服务端环境变量或 KMS,私钥切勿提交仓库或发给 Agent;
4. 生产网关 https://openapi.alipay.com/gateway.do,部署到公网 HTTPS;线上验证用 0.01 元小金额、且付款账号不能是商家本人账号;
5. 沙箱联调全链路:402 触发 → 沙箱收银下单 → Payment-Proof 重试 → 验付 + 履约确认 → 返回结果。

docx_outline.json schema(要点,完整见 build_docx.py docstring)

meta: {title, subtitle, meta(灰色小字), accent(可选主题色,#RRGGBB)}
blocks: [{t:"cover"} | {t:"h",level:1|2|3,text} | {t:"p",text 或 runs:[{t,b,i,c,s}]}
        | {t:"quote",text,src} | {t:"bullet",text 或 runs,level:0|1|2}
        | {t:"note",label:"提炼者按",text} | {t:"table",headers,rows}
        | {t:"center",text,size,gray} | {t:"divider"} | {t:"page"}]

runs 混排实现"加粗引导词 + 普通文字";quote 褐色斜体、src 右对齐;table 表头灰底加粗。中文统一 eastAsia 微软雅黑(每个 run 的 rFonts 都要 set w:eastAsia,否则回退默认字体)。

xmind 说明

标准 .xmind(XMind Zen)本质是 zip,含 content.json / metadata.json / manifest.json。XMind 8/12/2020+ 均可打开。分支≤9,节点文字宜短,引用金句放节点 notes。

关键坑(国内网络 / Windows)

• HuggingFace 模型下载失败:默认走 xet 通道报 401 Unauthorized 或 model.bin incomplete(可能下成 0 字节空文件)。处理:
  1. export HF_ENDPOINT=https://hf-mirror.com HF_HUB_DISABLE_XET=1 后让库自动下;
  2. 仍失败就 curl 手动逐文件下到本地目录,WhisperModel("本地目录", ...) 加载:curl -L -C - -o model.bin https://hf-mirror.com/Systran/faster-whisper-small/resolve/main/model.bin + config.json / tokenizer.json / vocabulary.txt。
• 模型放用户级共享目录 C:/Users/<用户>/.workbuddy/models/fw-small,跨项目复用,勿每次重下 461MB。
• Git Bash → Windows 程序路径坑:从 Git Bash 调用 Windows 程序(Python/curl 等)时,$PWD/$HOME 会展开成 MSYS 路径(/c/Users/...),Windows 侧程序不认,表现各异:
• curl -o:报 curl: (23) client returned ERROR on write / exit 23、产物 0 字节;
• Python av.open(...)/open(...):报 [Errno 2] No such file or directory: '/c/Users/...'。
  解决:给这些程序传字面量 Windows 风格路径(C:/Users/... 或 C:\Users\...),不要用 $PWD/$s、$HOME/... 拼路径。
• 转录必须后台跑;模型加载 ~10s,转录阶段 CPU 满载,勿前台阻塞。