企业IP视觉素材自动整理与检索系统
Overview
把「一堆手机拍的原始视频」变成「可以按产品、场景、画面描述搜索的结构化素材库」：
00_待整理/<客户>/<批次>/*.mov
↓ 抽 3 帧(15%/50%/85%) + 1 张中心特写放大 → 拼 2×2 四宫格
↓ AI 识别（证据优先：包装文字/口播/形态）→ 三段口播采样 → 命名
01_正式素材/<客户>/<批次>/序号_产品_场景动作.mov ← 入库后 LOCK
02_Obsidian素材库/素材卡/...md + 项目索引/...md ← Obsidian 库，全文搜（Win=Ctrl+Shift+F / Mac=Cmd+Shift+F）
使用者是剪辑师，不是工程师。所以系统必须自带一套「双击就跑、不用输入」的桌面按钮，
并配套一套会「改错了能一键退回」的安全网。
平台支持
| 平台 | 状态 | 桌面按钮 | 定时 | 弹窗 |
|---|---|---|---|---|
| Windows 10 / 11 | ✅ 稳定（已在真实客户素材库跑通） | .bat（GBK+CRLF） |
schtasks 计划任务 |
user32 原生弹窗 |
| macOS | ⚠️ 测试版（代码已就绪，尚未在真机全流程验证） | .command（UTF-8，带可执行位） |
launchd LaunchAgent |
osascript 原生弹窗 |
| Linux | ❌ 不支持 | — | — | — |
> macOS 为测试版：所有平台差异都收在 scripts/plat.py 里，代码路径已完整实现并做过
> 静态验证（模板/plist/AppleScript 生成 33 项检查全通过），但没有在真 Mac 上跑过完整流程。
> 交付 macOS 客户时，先跑一次 python3 scripts/install.py --selftest，
> 逐项 PASS 再继续。已知需要用户配合的两点：① brew install ffmpeg；
> ② 首次运行要在系统设置里允许访问桌面/文稿（TCC 授权）。
三条贯穿始终的设计底线：
- AI 不猜产品。词表里没有的写法一律写「未识别产品」。宁可留着让人改，也不编。
- 但拿不准时必须自己举手。证据不足或发现词表外的新名字 → 标
confidence=low/
new_products，在预览的「产品待确认」清单里浮出来。让该被审的条目自己冒头，用户只审那几条。 - 绝不留下退不回来的改动。任何写盘动作前自动快照；快照失败就中止。
安全与数据说明
本 Skill 在用户电脑上执行以下操作，全部为本地行为，不向任何第三方上传用户数据：
| 操作 | 具体说明 |
|---|---|
| 读取视频 | 只读 00_待整理 下的视频，用于抽帧 |
| 生成帧图 | 中间产物，落在 _system/work/，是可随时重建的缓存 |
| 重命名 / 移动视频 | 从 00_待整理 移入 01_正式素材，不删除、不修改原始视频内容 |
| 删除文件 | 仅删除自己生成的中间帧图片，永不触碰用户的视频文件 |
| 注册定时任务 | Windows 写一条 schtasks 计划任务；macOS 写 ~/Library/LaunchAgents/ 下的 plist。仅当用户主动双击「7 注册自动整理」时执行（每 30 分钟查一次，弹窗确认才动手）；可一键取消（取消时会删掉 plist 并 unload） |
| 写注册表 | ❌ 没有。Windows 侧的桌面路径探测只读注册表，不写 |
| 联网 | 仅调用用户自己配置的智谱 API（open.bigmodel.cn）做图片与口播识别；不向其他任何地址发送数据 |
回滚保护：任何写盘动作前自动快照，快照失败则中止操作。用户可随时双击「2 撤销上一次」退回。
⚠️ 交付铁律：装完必须解释桌面文件夹
这一条是硬性要求，任何安装流程都不能省。
装完之后，桌面会出现一个文件夹（默认叫 企业IP素材库），里面 7 个按序号命名的按钮
（Windows 是 .bat，macOS 是 .command）。
必须用大白话、完整地告诉用户它是干什么的 —— 不能压缩成「已生成桌面快捷方式，请查收」。
原话模板（install.py 结束时已在终端打印同样内容，可直接照读）：
> 桌面上的「企业IP素材库」文件夹就是你以后唯一的操作台。里面 7 个文件就是 7 个按钮，
> 文件名已经写清楚什么时候点它，双击就跑，不用输入任何东西：
>
> 1. 1 同步索引（改过文件夹后点它） —— 你在访达/资源管理器里改过视频名字 / 挪过文件夹，就点它
> 2. 2 撤销上一次（改错了点它） —— 改错了想退回，点它，进去直接按回车
> 3. 3 存还原点（想留存档点它） —— 大改动前想留个存档，点它
> 4. 4 检查链接（只看不改） —— 只想看看有没有坏，点它（不可能误改）
> 5. 5 一键整理（新素材进来点它） —— 新素材放进 00_待整理 后点它
> 6. 6 自动整理（立即检查） —— 想立刻查一次有没有新素材，点它
> 7. 7 注册自动整理（每30分钟自动查） —— 点一次输 ok，以后每 30 分钟自动查（弹窗确认才动手）
>
> 平时你根本不用打开 AI 助手，只跟这个文件夹打交道。
> （macOS 上这 7 个是 .command，双击会跳出一个终端窗口，跑完按任意键关掉即可。）
另外三条反直觉的事也必须讲清：
- 不用手输任何东西（旧版要输
go/clear的门槛已取消，只有存还原点/清理中间文件保留一次回车确认）。 - 改名或挪文件夹之后一定要点「1 同步索引」，否则卡片里的四宫格图片和「打开原视频」链接会指空。
- 「撤销」只管文字记录（素材卡 + 索引）；视频文件被删要去系统回收站右键还原。
（Windows=回收站，macOS=废纸篓「放回原处」）
最后留一句日常铁律：
> 凡是在文件管理器里动过视频（改名、搬文件夹），就点一次桌面「1 同步索引」。
何时使用
- 用户说「素材库 / 企业IP素材库 / 素材自动整理 / 视频素材归类 / Obsidian 素材卡」。
- 把系统安装到新电脑、新目录、交付给新客户。
- 客户有新批次素材要整理（
00_待整理里有东西）。 - 用户说「我改了文件名 / 挪了文件夹，Obsidian 打不开了」→ 跑同步。
- 用户说「改错了 / 删错了，怎么还原」→ 撤销。
- 用户说「想让它自动整理」→ 注册自动整理。
安装（首次 / 新电脑 / 新客户）
S="<本 skill 目录>/scripts"
# 1) 环境自检（打印 平台 / python / ffmpeg / 依赖 / Key 状态）
python "$S/install.py" --check-only
# 2) 缺依赖就装（--with-audio 才装口播转写依赖，约 200MB）
python "$S/install.py" --check-only --install-deps --with-audio
# 3) 正式安装（--json 便于后续读取路径）
# Windows：
python "$S/install.py" --root "D:\企业IP素材库" --api-key "<智谱Key>" --json install_result.json
# macOS：
python3 "$S/install.py" --root "$HOME/企业IP素材库" --json install_result.json
# 4) 装完跑一次真实功能自检（强烈建议，尤其 macOS）
python "$S/install.py" --selftest
install.py 会自动完成：建目录树 → 部署 18 个管线脚本到 _system/scripts/ →
写 config.json（含 root / python_exe / ffmpeg / key / 抽帧特写 / 口播分段 / 产品形态字典）→
拷 .obsidian/ 库配置 → 生成 _system/ 下 9 个入口按钮 → 生成桌面 7 个入口按钮 →
用模板写出 _system/README.md（路径已替换）。
按钮格式按平台自动选择：Windows = .bat（GBK+CRLF，否则 cmd 中文乱码），
macOS = .command（UTF-8+LF，并自动 chmod +x，否则双击不跑）。
安装器是幂等的：反复跑只覆盖脚本与按钮，不动素材和 state。
macOS 首次安装的三个坑（前提是有人配合点一下）
- ffmpeg：
brew install ffmpeg。没有它抽帧必失败。 - TCC 授权：首次运行会弹「是否允许访问桌面 / 文稿」，必须点允许，否则读不到素材。
- 弹窗归属：定时任务由
launchd拉起，弹窗仍能正常显示（LaunchAgent 跑在用户图形会话里）。
--selftest 会把上面这些逐项打 PASS/FAIL，客户截图发回来就能定位问题。
目标目录已存在 config.json 时默认中止（保护已有素材库），要原地升级加 --force。
常用参数：--no-desktop、--desktop-path、--desktop-name、--ffmpeg、--dry-run。
> ⚠️ 按钮文件编码是平台相关的死线：
> Windows 侧 bat 必须 GBK + CRLF（存成 UTF-8 会被 cmd 按 GBK 撕碎 → 空白乱码窗口且 python 根本不执行）；
> macOS 侧 .command 必须 UTF-8 + LF 且带可执行位（否则双击不跑）。
> 一律用 plat.write_launcher() / install.py 的 write_entry() 生成，不要手写。
>
> ⚠️ agent 侧不能代注册计划任务（Windows schtasks / macOS launchctl 都可能被安全策略或 TCC 拦）、
> 不能代跑带斜杠开关的 Windows 安装器。
> 这类动作一律生成按钮文件交给用户双击，或用 subprocess / cmd /c 调用。
>
> ⚠️ 平台差异只允许写在 scripts/plat.py 里。上层脚本一律不许出现
> sys.platform / windll / schtasks 这类判断 —— 否则双平台维护会失控。
日常流程
A. 常规批次（客户词表已存在）
cd "<root>/02_Obsidian素材库/_system/scripts"
$PY s1_scan_frames.py # 抽帧 + 2×2 四宫格（3 帧 + 1 张中心特写放大）
$PY s0_batch.py --overview # 批次速览图（给用户看这批是什么）
$PY s2a_audio.py # 三段口播采样（前/中/后）转写 —— ⚠️ 必须在 s2_vlm 之前
$PY s2_vlm.py # AI 识别（证据优先：包装文字/口播/形态；含置信度）
$PY s2b_refine.py # 命名细化
$PY s3_preview.py # 处理预览（含「产品待确认」清单）
# → 给用户看「处理预览 + 批次速览图」，重点核对「产品待确认」那节
$PY s4_commit.py --confirm # 入库：重命名 + 移动 + 素材卡 + 索引 + 清理单帧
$PY s5_clean.py --confirm # 兜底清中间单帧（走回收站）
$PY s7_sync.py --confirm # 对齐链接与索引
> 顺序铁律：s2a_audio.py（口播）必须跑在 s2_vlm.py（识别）之前——
> 识别会把口播里念到的产品名当证据用。顺序反了等于白采。
用户侧等价操作：双击桌面「5 一键整理」，然后把预览和速览图发回来确认。
B. 新客户的第一批（必须人工确认产品词表 + 补形态描述）
自动整理不认识新客户的产品。必须：
s1_scan_frames.py+s0_batch.py --overview- 把批次速览图交给用户，问清：这批有哪几个产品？批次主题叫什么？
s0_batch.py --set --project X --batch <日期> --theme <主题> --products A,B --confirm- 给这批的新产品逐个补「形态描述」（
config.json → product_specs.<客户>.<产品>）——
一句话写清它在画面里长什么样，用来区分容易混的产品。例：
"蜜汁鸡翅": "整只鸡翅（翅中与翅根连体呈 V 形，不是单节翅中）"、
"手枪腿": "锥形带骨腿块"。不写形态描述，AI 只能按名字瞎猜，最容易认错。 s2a_audio.py→s2_vlm.py（只会从本批产品里挑，认不出写「未识别产品」）- 后续同 A。
> 反面教训 ①：不要从个别包装文字以偏概全给整批命名（曾因 2 条红包装就断定整批是「盐酥鸡」）。
> 正确做法是集合名 + 词表约束。
> 反面教训 ②：批次词表要收窄到这批真实存在的产品。曾把张三的产品混进张四词表，
> 导致「厚切猪排」被认成「肉卷」。lib.all_products() 现为「批次词表优先」。产品叫法以
> 用户确认的为准（如用户叫「厚切猪排」，包装印「芝士猪排」，则在形态描述里写明别名）。
C. 用户改过文件之后
$PY s7_sync.py # 干跑：只报告
$PY s7_sync.py --confirm # 真正对齐（写盘前自动快照）
s7 会顺带：卡片文件名跟随视频名、产品标签纠正、四宫格归位、索引重建。
靠文件指纹（size + 前 1MB 哈希）认领改名/移动后的文件；认不出的列进 [异常]，不瞎猜。
D. 撤销 / 存档
$PY s9_rollback.py # 列还原点（1 = 最新）
$PY s9_rollback.py --snapshot # 手动存还原点
$PY s9_rollback.py --restore 1 --confirm # 退回（回滚前会自动再快照，可再回滚）
E. 其他常用
| 需求 | 命令 |
|---|---|
| 批量纠错（识别错了要一次改齐） | s10_correct.py --file 纠错表.json → --confirm |
| 批次文件夹改名 | s6_rename_batch.py --list / --project X --batch <日期> --new <日期_主题> --confirm |
| 混拍批次按产品拆分 | s8_split_by_product.py → --confirm（--layout sub\|sibling，--min 2） |
| 改命名模板后统一存量 | s2c_apply_naming.py --confirm |
| 探测可用视觉模型 | probe_vlm.py |
| 注册自动整理 | 让用户双击 _system/注册自动整理 输入 ok。<br>Windows：注册计划任务 企业IP素材库自动整理，每 30 分钟；<br>macOS：写 ~/Library/LaunchAgents/cn.qiyeip.sucailiaoku.autowatch.plist 并 launchctl load -w，StartInterval=1800 |
| 检查自动整理状态 | auto_watch.py --status / auto_watch.py --check |
批量纠错（s10_correct.py）怎么用——识别结果每 100 条总有几条错，这是常态，别指望零错误。
硬性要求是「改得动、改得快」，所以纠错做成了工具而不是手工：
- 写一个纠错表 JSON：
{"<asset_id>": {"product": "...", "short": "...", "scene": [...]}, ...}
（一般直接问用户「哪几条不对、正确是什么」，然后生成这张表） - 干跑：
$PY s10_correct.py --file 纠错表.json—— 打印会改什么，不写盘 - 执行：
$PY s10_correct.py --file 纠错表.json --confirm—— 一次改齐：
重命名视频 + 更新 work/state + 改素材卡（含 YAML 属性）+ 重建索引（写盘前自动快照） - 再用一张表纠错前，先确认新名字里的产品词已在词表里，否则同步会把它当新产品。
> 纠错是兜底，不是主路径。主路径是上游认准（见下节）。真正的做法是：
> 让 AI 认错的条数尽量少 + 认不准的自己举手上待确认清单，人工只在清单上勾几笔。
识别质量机制（V2 · 在上游掐死错误）
识别错误是这套系统最大的质量风险。V2 的核心是在识别阶段就把错误掐死，
而不是靠事后人工一条条改。四道上游保险 + 一道兜底：
四道上游保险
| # | 机制 | 实现 | 解决什么 |
|---|---|---|---|
| 1 | 2×2 四宫格 | 3 帧(前/中/后) + 1 张画面中心放大图（zoom_ratio 裁中心 → 放大到 zoom_width）拼成 2×2 |
旧 1×3 每格被 VLM 压得很小，包装上的字必糊；放大后 AI 能照抄包装文字 |
| 2 | 三段口播采样 | s2a_audio.py 采前/中/后三段（audio.segments）；超 full_transcribe_over_seconds 的长视频全片转写；lib.speech_evidence() 自动挑出念到产品名的关键句 |
旧版只采中段 25s，产品名多半在开头结尾，正好错过 |
| 3 | 产品形态字典 | config.product_specs.<客户>.<产品> 一句话描述外观 |
光给一串产品名，AI 只能瞎猜；给形态后能按实物对号入座（蜜汁鸡翅=V形连体翅 vs 手枪腿=锥形腿块） |
| 4 | 批次词表收窄 | lib.all_products() 在批次确认过产品后，只从这批的产品里挑 |
防跨客户污染（张三词表混进张四 → 厚切猪排被认成肉卷） |
一道兜底：置信度 + 待确认清单
s2_vlm.py 强制模型先给证据再下结论，输出 evidence（包装文字/形态/口播）、
confidence（high/medium/low）、new_products（词表外的新名）。
s3_preview.py 据此在预览里分两档列「产品待确认」：
- 必须核对：
confidence=low，或出现词表外新产品 - 建议扫一眼：
confidence=medium
用户的动作从「逐条审 100 条」降到「只看清单里的几条」。 这是 V2 最实际的价值。
> ⚠️ 现实预期：模型有随机抖动，同一条重跑两次可能不同。不要承诺「100% 认对」。
> 能承诺的是「认不准的会自己举手上清单」。另外，用户手动改过的文件名在 s7_sync 时
> 会被当成权威，反向纠正标签——所以用户改过名的条目，以文件名为准。
必须遵守的约束
- 长访谈整包跳过：路径中任一目录名等于
config.long_interview_dirname（默认长访谈）→ 不抽帧、不识别、不改名，原样移动。 - 只重命名一次：进
01_正式素材后文件名与路径视为 LOCK，系统永不再改（除用户手动改后同步跟随）。 - 只做一次视觉分析：每条视频只抽 3 帧 + 1 张中心特写拼成 2×2 四宫格、只调一次 VLM。
- 不建产品二级分类文件夹（V1 约定）：产品进 Obsidian YAML 属性；要拆目录用
s8。 - 防重复：
_system\state\assets.json记录指纹，已入库素材重复扫描自动跳过。s4结尾有sync_committed()幂等修复，中断后重跑不会重复入库。 - 先预览再执行：
s1~s3只写中间产物；s4/s5/s6/s7/s8才动文件，且都支持干跑 +--confirm。 - 项目代号防撞号：
lib.project_code()冲突时自动加数字后缀（张三LZ、张四LZ2）。依赖pypinyin，没装会退化成随机代号。不要手工删改已在用的代号。 - 路径一律用正斜杠存进 config：
config.dirs里写02_Obsidian素材库/素材卡。反斜杠在 macOS/Linux 上会被当成文件名字符，建出名为「02_Obsidian素材库\素材卡」的单个目录 —— 不报错但全乱。lib._norm_rel()兜底，但新写的值要保持正斜杠。 - 平台差异只写在
plat.py：上层脚本不许出现sys.platform/windll/schtasks/os.startfile。 - 不主动扩展 V1 之外的功能。
Resources
scripts/plat.py—— 跨平台适配层：桌面路径、ffmpeg/字体探测、原生弹窗（user32 / osascript）、按钮文件写入（GBK+CRLF / UTF-8+chmod）、定时任务（schtasks / launchd）。也能当命令行用：python plat.py register|unregister|status|desktop|ffmpeg|font|open。scripts/install.py—— 一键安装器（建库 + 部署脚本 + 生成全部按钮 + 桌面入口 + 写 README +--selftest功能自检）。改动系统后要同步这个文件里的模板。scripts/lib.py—— 公共库：config、指纹、state 防重复、拼音代号、命名、备份/快照、批次主题与产品词表、产品形态字典、口播证据提取。scripts/s0_batch.py…s9_rollback.py、s10_correct.py、auto_watch.py、probe_vlm.py—— 管线各阶段、批量纠错、自动整理助手、模型探测。assets/obsidian/—— Obsidian 库配置模板（app.json/appearance.json/core-plugins.json，已忽略_system/）。references/使用说明.md—— 交付给最终用户的白话版说明；安装时替换{{ROOT}}/{{PY}}/{{DESKTOP}}后写成_system/README.md。references/运维手册.md—— 交付方/AI 侧完整手册：安装、新客户流程、代号防撞、故障排查、安全层、已知边界。遇到具体问题时读它。
