Obsidian Note Ingest — AI skill for Claude Code

obsidian-note-ingest

⚠️ **测试版 0.1.0**（pre-release）—— 仍在自用验证中，接口与文件结构可能变动；请只在能随时回滚的笔记库上使用。

**把课件、录音稿、讲义整理成能直接读的 Obsidian 笔记。**

一个面向 Obsidian 用户的 AI Agent skill：喂给它 PPTX / PDF / DOCX / 字幕稿 / 截图， 它提取内容、查重、剔除废话、按你的笔记风格成篇、写进你的 vault —— **全程先备份、可回滚**。

**不绑定任何 Agent 框架。** 核心工具链（`scripts/*.py`）是**独立可用的命令行脚本**， 既能被 Claude Code / Codex / WorkBuddy / Trae 等任何能跑命令的 Agent 直接调用， 也能由你在终端里手动跑。`SKILL.md` 只描述「做什么」，不写死具体工具名， 因此换 harness 无需改动。

---

它解决什么问题

痛点	做法
PPTX 里的表格和公式抽不出来	pptx_deep.py 直接解析 slideN.xml，绕开 AlternateContent 拿到表格，解析 OMML 拿到公式
老课件公式是 OLE 对象，抽出来一片空白	从 PDF 文本层按坐标几何重建分式 / 上下标 / 矢量（pdf_layout.py）
公式型 PDF 提取出来完全散架	renderpages.py 渲染成图让模型看，或以版面几何重建
课件插图裁不干净（切到文字、留一堆白边）	pdf_panels.py 按纯色面板找边界
整理完发现内容早就有了 / 灌了一堆重复	vaultio.py check 查重，并附「覆盖率为什么会骗人」的判别法
改笔记时误删、行尾被改、callout 被截断	所有写入走 vaultio.py（强制 LF、自动备份、--dry-run 预览）
笔记写完满页彩色块，重点反而没了	obsidian_lint.py 量化色块密度 + flatten_callouts.py 一键降级

`references/` 里是各环节的细节文档，另附几十条实战踩坑记录。

---

快速开始

1. 安装依赖

PY="<你的 Python 解释器>"          # 建议 3.10+
$PY -m pip install -r requirements.txt

2. 一键安装 skill

**方式 A —— skills CLI（推荐）**，支持 Claude Code / Codex / Cursor / Copilot / Gemini CLI 等 70+ 环境：

npx skills add Woo3aN/obsidian-note-ingest          # 装到当前项目
npx skills add Woo3aN/obsidian-note-ingest -g       # 装到用户级（所有项目可用）
npx skills add Woo3aN/obsidian-note-ingest --list   # 只看仓库里有哪些 skill，不安装

**方式 B —— openskills**：

npx openskills install Woo3aN/obsidian-note-ingest
npx openskills sync

**方式 C —— git clone**（不依赖任何 CLI）：

# 直接 clone 进 agent 的 skill 目录。目录名与 frontmatter 的 name 一致，别改名
git clone --depth 1 https://github.com/Woo3aN/obsidian-note-ingest \
  ~/.claude/skills/obsidian-note-ingest          # 其余 agent 换成对应目录

# 更新
cd ~/.claude/skills/obsidian-note-ingest && git pull

多个 agent 共用一份：clone 到一处，再软链过去。

git clone --depth 1 https://github.c