obsidian-clip-transcript

把 Obsidian 里的剪藏素材（视频 / 图文）转成结构化笔记：顶部知识卡片看板 + 正文分段整理 + YAML 标签；视频版额外带可点击时间戳跳回原片。图文版额外生成一个首页索引卡片墙（小正方形磁贴，封面 + 标题点击跳笔记）。

已确认的端到端流程（用户拍板，务必照此执行）

图文主流程：
小红书链接 → xhs-importer 插件自动导入到 00.收集箱 → 读取 md + 图片附件 → 转文字 → 结构化（YAML + 知识卡片 + 内容大纲 + 详细内容）→ 原位覆盖加工，不移动文件夹（"自动归档"= 留在 00.收集箱 原位） → 在 vault 根 看板.md 追加一张小正方形卡片（封面 + 标题）。

> 也可由用户直接给链接，你先去 00.收集箱 找剪藏原文，再走上面流程。触发后第一步必须先询问确认（见下）。

关键事实（已验证，踩坑沉淀）

• 转写：本地 faster-whisper（装于 default python env），CPU 可用；25 分钟中文约 30+ 分钟。
• ffmpeg：用 imageio_ffmpeg 自带的 windows 二进制，不要依赖系统 PATH。
• xhs-importer 插件：只下载图片到本地（命名 <笔记名>-0.jpg、-1.jpg…），视频保留为远程链接，且不做转写。小红书视频需用户单独提供。
• 封面路径约定：$VAULT/附件/XHS/<笔记名>-0.jpg（即 xhs-importer 下载的第一张图）。
• 时间戳跳转：必须本地视频文件 + Media Extended 插件（[[video.mp4#t=秒数]]）。远程链接无法跳秒。
• 中文/全角文件名在 Git Bash 下需先 ls 解析再 cp 到 ASCII 名，否则 ffmpeg 解析失败。
• 图文内容常存在图片中，md 文件里只有标题/封面/图片引用，必须读图提取文字。

沙箱 vs 本机抓取（2026-08-28 实测）

• 我的 Bash 默认跑在隔离沙箱里，出不了外网：B站/微信等直接超时或 getaddrinfo ENOTFOUND；访问你本机代理 127.0.0.1:7892 会被拒连（沙箱网络和你本机是隔离的）。
• 需要联网抓取（封面缩略图、网页正文）时，用 dangerouslyDisableSandbox: true 本机模式执行，走你本机网络。
• B站缩略图：本机直连 api.bilibili.com/x/web-interface/view?bvid=XXX 可通（代理反而不行），从返回 JSON 的 pic 字段拿缩略图 URL 再 curl -o 存到 附件/XHS/<笔记名>-0.jpg。
• 微信/公众号文章：本机 curl 直连微信常被拒（空响应/403）→ 改用 WebFetch 工具走服务端网络抓取正文，稳定可用。结论：公众号文章优先 WebFetch，别用本机 curl。

环境常量（Windows）

• PY=$HOME/.workbuddy/binaries/python/envs/default/Scripts/python.exe
• FFMPEG=$HOME/.workbuddy/binaries/python/envs/default/Lib/site-packages/imageio_ffmpeg/binaries/ffmpeg-win-x86_64-v7.1.exe
• 常用 vault 示例：F:/黄瓜BBQ（视频工作）、F:/实验库（小红书图文工作流）
• 视频存放：$VAULT/附件/XHS/<笔记名>/video.mp4
• 图文封面/图片：$VAULT/附件/XHS/<笔记名>-0.jpg ... -N.jpg
• 播放器兜底：$VAULT/附件/XHS/<笔记名>/player.html（接收 ?f=video.mp4&t=秒数，自动跳秒；Chrome 对 file:// 跨目录有限制，Firefox 正常）

前置准备与运行前检查清单（使用者对照）

核心流程一句话（请对照确认）

读取本地素材（文字 / 图片 / 视频）或直接甩链接（链接按网页形式读取文本与图片，公众号文章最典型）→ 转文字 + 结构化（YAML + 知识卡片 + 大纲 + 详述 + 公众号类额外保留「原文板块」）→ 自动归档到 Obsidian 对应文件夹（图文默认留在 00.收集箱 原位）→ 在 看板.md 生成总体笔记卡片墙。唯一例外：视频/音频链接无法自动抓取，必须先把文件存到本地再处理。（公众号文章抓取用 WebFetch；B站封面缩略图用本机模式直连，见「沙箱 vs 本机抓取」）

这一路你装过 / 改过的插件与设置（诚实复盘）

调试过程中先后动过这些，逐条说明哪些真必需、哪些已被淘汰：

运行前自检清单（开始处理前逐条过）

1. ☐ 目标 vault 已打开；若处理小红书，确认 xhs-importer 已装且导入目录是 00.收集箱。
2. ☐ 图文流：确认剪藏 md 与图片已落在 00.收集箱（xhs-importer 下载的图在 附件/XHS/<笔记名>-N.jpg）。
3. ☐ 视频流：确认视频已是本地文件；若要做时间戳跳转，确认 Media Extended 已装。
4. ☐ 看板.md 存在于 vault 根；若不存在，用 skill 的 references/看板模板.md 直接复制创建。
5. ☐ 渲染验证：打开 看板.md → 切到阅读模式 → 若样式没出来，完整重启 Obsidian；若用了 CSS 片段还需确认片段开关已开。
6. ☐ 再次提醒：本 skill 不依赖 Dataview，也没有 dashboard 插件，别再为卡片墙折腾这两个。

触发后第一步：询问确认

收到用户请求（如"把这个链接整理进 Obsidian""视频转文字稿""小红书图文转笔记"）时，先问一个确认问题：

> 是否需要我帮你把这份素材「转文字 + 结构化处理 + 生成知识卡片看板」后写入 Obsidian？
> - 视频类：还会生成带时间戳的跳转链接。
> - 图文类：会读取图片里的文字，整理成分段笔记并加入首页索引卡片墙。
> - 若只想要纯文字稿/原文搬运，也可单独指定。

等用户明确说"是""整理""生成""写"等确认词后再继续，避免默认加工。

视频处理流程

1. 定位/创建目标笔记（先 Read 再 Write/Edit，覆盖 stub 或追加）。
2. 视频准备：若路径含中文/全角，先 SRC=$(ls /c/.../video_*.mp4 | head -1); cp "$SRC" "$DEST/video.mp4"；ffmpeg 提取 16k 单声道 wav："$FFMPEG" -y -i "$VID" -ar 16000 -ac 1 -c:a pcm_s16le audio.wav。
3. 转写：faster-whisper（按长度选 small/medium），输出 transcript.json（segments: start/end/text；顶层 language/text）。后台跑，轮询 transcript.json 出现。
4. 结构化：断句 + 按静音/语义分段 + 归为若干小节 + 校正识别硬伤。生成带 ## 小节 的 markdown。
5. 时间戳对齐：在 transcript.json segments 中为每个小节首句找首次出现位置 → 得到 mm:ss 与秒数。
6. 写看板：笔记顶部插入「知识卡片看板」：Mermaid mindmap（概念树）+ 每节一张 > [!abstract| 节名 · mm:ss] 卡片（核心句 + 关键词 + [[附件/XHS/<名>/video.mp4#t=秒数|▶ mm:ss 视频原处]]）。顶部内嵌 ![[附件/XHS/<名>/video.mp4]] 作为跳转目标。
7. 写入笔记（覆盖 stub 或追加），保存。
8. 校验：grep 链接数、标题数是否齐全。

图文/剪藏处理流程

1. 定位/读取素材：在 vault 的 00.收集箱（或用户指定）中找到刚剪藏的 md 文件与图片附件；读取 md 正文和全部图片。
2. 转文字：
   - 若 md 里已有完整文字（部分网页剪藏会带正文），直接提取。
   - 若正文在图片中（小红书图文常见），用视觉逐张读图，把图中文字全部转写出来。
3. 结构化：按原帖逻辑分段，提炼每个要点的「作用 / 操作步骤 / 为什么有效 / 小贴士」，生成小标题和要点清单。
4. 生成知识卡片看板：笔记顶部插入 Mermaid 概念脑图 + 10 张左右 > [!abstract] 速查卡片（方法名 + 核心句 + 关键词 + 操作/效果）。
5. 写入 Obsidian（原位覆盖，不移动文件夹）：加工后留在 00.收集箱 原位覆盖 stub/原剪藏文件。YAML 严格包含字段（供卡片墙使用）：
   - title、created、xhslink、tags: [小红书]
   - cover: 附件/XHS/<笔记名>-0.jpg（首图全路径，卡片墙的封面来源，必须有）
   - type: 图文、summary（一句话重点，供卡片墙/检索）、source（原文链接兜底）
6. 更新首页索引卡片墙（见下一节）：往 $VAULT/看板.md 追加一张 > [!card]。
7. 校验：grep 封面引用、标签、看板.md 是否可索引到新笔记。

公众号/网页文章处理流程（2026-08-28 新增）

1. 抓取正文：用户甩公众号链接 → 用 WebFetch 指向该链接，提取：标题、公众号名/作者、发布日期、完整正文（保留小标题结构）、图片链接、核心要点。公众号/微信本机 curl 常被拒，优先 WebFetch。
2. 写笔记：写入 00.收集箱（或用户指定），笔记名取文章标题。YAML 含 title / created / source(原文链接) / author / publisher / publish_date / type: 公众号文章 / tags / summary / cover。
3. 结构：
   - 顶部「知识卡片看板」：Mermaid mindmap + 若干张 > [!abstract] 速查卡（核心命题、分节要点）。
   - 内容大纲（小标题即锚点）+ 每节详述（保留关键引文/数据/表格）。
   - ⭐ 结尾必须保留「原文板块」（## 原文板块）：用 > [!quote] 引用 = 完整原文，供用户对照阅读。结构化整理在上、原文在下，二者并存，不要用摘要/改写替代原文。
   - 底部附「原文链接」markdown 链接直达。
   - 可加「延伸思考」小节（对比任务/案例应用/文献追踪）。
4. 归档：原位写入 00.收集箱，不移动。
5. 看板：往 看板.md clear 行前追加一张 > [!card]（公众号卡通常无封面图，放纯文字卡；有封面则 ![[附件/XHS/<笔记名>-0.jpg|158]]）。
6. 校验：grep 原文板块标题、[!abstract] 卡片数、看板可索引。

首页索引卡片墙（最终稳定方案）

> ⚠️ 这是整条链路里踩坑最多、最该固化的环节。 旧版 Dataview 0.5.68 对 dv.image / dv.span("![[]]") / dv.embed 支持都不稳定，动态渲染图片必然封面空白。最终方案：完全放弃 DataviewJS，改用 Obsidian callout 静态卡片墙 + 原生 ![[封面|158]] 嵌入，已验证可用。

文件位置

• $VAULT/看板.md：卡片墙本体（含内嵌 <style>，无需开启任何插件即可渲染）
• $VAULT/.obsidian/snippets/dashboard-cards.css：同款 CSS 片段（双保险，需在 设置→外观→CSS片段 手动开启 dashboard-cards）

卡片格式（每张一个 > [!card]，写到 clear 行之前）

> [!card]
> ![[附件/XHS/示例笔记-0.jpg|158]]
> <span class="col-title">[[示例笔记|示例笔记标题]]</span>
> <span class="col-tag">小红书 · 标签</span>

• 封面：![[附件/XHS/<笔记名>-0.jpg|158]]（原生嵌入，旧 Dataview 也能渲染）
• 标题：用 <span class="col-title"> 包一个 [[笔记路径|显示标题]] 的 wiki 链接，点击跳笔记
• 标签：<span class="col-tag"> 包一行小字
• 文件末尾必须保留一行 <div style="clear: both;"></div>（清除 float，防止卡片墙后面的内容错位）

⚠️ 卡片标题链接跳转（2026-08-28 踩坑修复）

• 用裸文件名链接最稳：[[文件名|显示标题]]，不要在方括号里加父目录前缀（如 [[00.收集箱/文件名|...]]）。
• 因为 callout > 缩进块里，「父目录前缀 00.收集箱/ + 含 ——(EM DASH/全角短横) 的文件名」这种组合 Obsidian 很容易解析失效 → 点不跳。
• Obsidian 按唯一文件名解析裸链接，跨目录也能匹配，是卡片墙标题链接的首选写法。
• 若某张卡始终跳不动，先删父目录前缀改裸文件名；仍不行再考虑重命名笔记去掉特殊字符（——→-）并同步更新卡链接。

完整模板

直接复制本 skill 的 references/看板模板.md 作为 看板.md 初版（已含内嵌样式 + 示例卡片 + clear 行）。references/dashboard-cards.css 是同一份 CSS 片段，供写入 .obsidian/snippets/ 做双保险。

新增素材时

在 看板.md 的 <div style="clear: both;"></div> 之前 插入一段 > [!card]（格式同上），封面取该笔记 cover 字段的首图。不要改写其他卡片。

渲染必要条件（用户常漏，务必提醒）

1. 阅读模式（Ctrl/Cmd+E 切到预览）才会渲染样式与封面；源码/实时预览模式看到的是原始代码。
2. 首次启用或改过 CSS 后，完整重启 Obsidian（彻底退出再打开）清缓存，否则样式不生效。
3. 若开了 .obsidian/snippets/dashboard-cards.css，需到 设置 → 外观 → CSS 片段 里把 dashboard-cards 开关打开。内嵌 <style> 那份不依赖这个开关。

绝对不要做（从 7 次失败中提炼）

1. ❌ 不要在旧版 Dataview 上用 DataviewJS 渲染图片卡片（dv.image/dv.span("![[]]")/dv.embed 全都会封面空白）。→ 用静态 > [!card] + 原生 ![[封面|158]]。
2. ❌ 不要用 app.vault.getResourcePath / getAbstractFileByPath 等 vault API（旧 Dataview 没有，会整段报错）。
3. ❌ 不要用 inline-block 做横向排列（旧版不生效）；横向用 float: left + 末尾 clear: both。
4. ❌ 不要默认加工用户没确认的素材（流程第一步必须询问）。
5. ❌ 不要移动/另建归档目录——用户定义的"自动归档"= 在 00.收集箱 原位覆盖。
6. ❌ 卡片不要做成"书脊/横向大卡"，用户最终选定 158×158 小正方形磁贴（封面占满卡顶 + 下方标题 + 标签）。
7. ❌ 卡片标题链接不要在 wiki 链接里加父目录前缀（[[00.收集箱/xx|xx]]），尤其对含 —— 的文件名会点不跳；用裸文件名链接。公众号笔记必须保留「原文板块」，不要用摘要替代原文。

注意事项

• 后台进程在非交互回合结束可能被杀；要么前台等，要么确认进程存活后轮询 transcript.json。
• Media Extended 内部链接时间戳默认可能需在设置开启；embed ![[video#t=]] 始终可用。
• 大体积视频入 vault 会增大库；如用户介意，改存 vault 外并改绝对路径链接。
• 图文图片 OCR 靠视觉，字非常密或分辨率低时可能漏字；必要时提醒用户核对关键术语。
• 卡片标题链接用裸文件名 [[文件名|别名]]；带父目录前缀或含 —— 的文件名易点不跳，修不动就考虑给笔记重命名去特殊字符。
• 需要联网时（封面/公众号正文）别用默认沙箱，走 dangerouslyDisableSandbox:true 本机模式；公众号正文优先 WebFetch。
• 用户为技术小白：给出步骤时尽量具体、可复制，关键决策先确认再落地。