Agentic Wiki Skills
中文 | English
本项目为 AI 编程助手（如 Gemini/Antigravity 和 Claude Code）提供了一套智能体技能（Agentic Skills），使其能够自动化地将学术论文（PDF 和 LaTeX）摄入、编译、整理，并查询为一个兼容 Obsidian 的 Markdown 知识库。
🌟 项目展示
以下是由本 AI 自动化流水线完全生成并维护的知识库效果展示：
一张自动生成的密集语义图，展示了物理和数学概念。
后台嵌入引擎自动注入的深层语义关联视图。
利用本地 OCR 和 Pandoc，直接从排版混乱的 PDF 中编译出的整洁文献卡片。
从 LaTeX 源码中完美提取并格式化的数学证明和引理。
1. 核心功能
将其加载到您的 AI 助手后，您可以通过输入一系列显式且确定性的斜杠命令 (/wiki_xxx) 来直接命令 AI 助手执行以下操作：
- 摄入 (Ingest)：将重度数学公式的 PDF（通过高保真云端版面分析 API 或本地 OCR）和 LaTeX 源码转换为 Markdown。
- 编译 (Compile)：将数学定义、定理和概念提取为一张张相互链接的 Obsidian 独立卡片。
- 去重与链接 (Deduplicate & Link)：自动发现重复概念，物理合并去重，并使用本地向量嵌入实现相关卡片的语义双链关联。
- 交互式问答 (Interactive Q&A)：与您的整个知识库对话，AI 将严格使用本地关系图谱、SQL 查询和正则检索来回答您——保证零幻觉，并附带精确文献引用。
- 自愈与公式纠错 (Auto-Healing & Math Correction)：智能 Linter 自动检测并修复失效链接，修复 LLM 产生的 YAML 元数据反斜杠转义错误，并基于 pdflatex 校验 LaTeX 数学公式的语法正确性。
2. 系统依赖
部署技能前，请确保您的系统安装了以下运行时依赖。
2.1 Python 依赖
需要 Python 3.10+。全局安装以下 Python 包：
pip install -r requirements.txt
提示：建议使用虚拟环境以避免依赖冲突：
python -m venv .venv
.\.venv\Scripts\activate # Windows
# source .venv/bin/activate # Linux/macOS
pip install -r requirements.txt
2.2 系统级外部程序
本流水线依赖一些外部工具，必须将它们添加到系统的 PATH 环境变量中：
- Poppler-utils (
pdftoppm & pdfimages) — 用于渲染 PDF 页面和提取图表。
- Windows (Scoop):
scoop install poppler
- Windows (Choco):
choco install poppler
- macOS (Homebrew):
brew install poppler
- Linux (APT):
sudo apt-get install poppler-utils
- Ripgrep (
rg) — 提供极速的多文件引用映射和 wikilink 重构。
- Windows (Scoop):
scoop install ripgrep
- Windows (Choco):
choco install ripgrep
- macOS (Homebrew):
brew install ripgrep
- Linux (APT):
sudo apt-get install ripgrep
- Pandoc — 用于自动摄入并将 LaTeX (
.tex) 文档转换为 Markdown。(注：本仓库已为 Windows 用户内置了 pandoc-crossref，无需额外安装)
- Windows (Scoop):
scoop install pandoc
- Windows (Choco):
choco install pandoc
- macOS (Homebrew):
brew install pandoc
- Linux (APT):
sudo apt-get install pandoc
- TeX /
pdflatex（推荐） — 为摄入过程中的深度数学语义校验（双下标、括号不匹配、错误分隔符）提供支持。可选但推荐：若缺少 pdflatex，系统会自动回退到基于 pylatexenc 的轻量结构校验。
- Windows (Scoop):
scoop install miktex
- Windows (Choco):
choco install miktex
- macOS (Homebrew):
brew install --cask mactex-no-gui
- Linux (APT):
sudo apt-get install texlive-latex-extra
2.3 Ollama 本地模型
离线图像转录与语义链接依赖于后台运行的 Ollama 服务：
ollama pull glm-ocr
ollama pull qwen3-embedding:0.6b
3. 安装与部署
安装脚本会将 skills/ 和 bin/ 并列复制到目标目录，并一并复制 requirements.txt、.env.example 和 config.yaml。每个技能都相对自身定位辅助脚本，因此任意目标目录都可用——只需选择您的 AI 工具用于发现技能的目录：
| AI 工具 | 常见目标目录 |
|---|
| Claude Code | ~/.claude（用户全局级）或 <project>/.claude |
| Gemini / Antigravity | <project>/.agents 或 ~/.gemini |
Windows
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install.ps1 # 交互式询问目标目录，或：.\install.ps1 -Target <dir>
Linux / macOS
bash install.sh # 交互式询问目标目录
bash install.sh ~/.claude # 或直接以参数传入
4. 学术文献处理完整生命周期流程
当智能体技能（Skills）成功加载到您的 AI 助手后，您可以通过在助手的聊天 UI 中直接输入显式的斜杠命令 (/wiki_xxx)，来管理文献从摄入到研究问答的完整生命周期：
📥 第 1 阶段：基建与初始化
- 创建中央枢纽 (Central Hub)
- 面临场景：您需要搭建一个中央枢纽目录来注册、路由和管理多个不同主题的知识库。
- 直接输入斜杠命令：在您想要作为中央枢纽的父目录下（例如通用路径
~/KnowledgeHub）打出：/wiki_hub_init。
- 预期效果：自动生成
topics/ 文件夹和 wikis.json 中央注册表文件。
- 创建主题工作区 (Topic Workspace)
- 面临场景：您准备开始一个新的学术研究主题（例如量子计算
quantum-computing），需要为其创建独立的存储库。
- 直接输入斜杠命令：在 Hub 目录下新建并进入子文件夹（例如
~/KnowledgeHub/topics/quantum-computing），并在聊天 UI 中打出：/wiki_init。
- 预期效果：瞬间在该目录下生成标准的主题工作区目录结构（
raw/、wiki/、inbox/、output/），自动创建默认配置文件（config.md、log.md、_index.md），并将该主题自动注册到中央 Hub 路由中。
📄 第 2 阶段：文献摄入与数字化
- 处理待摄入文献
- 面临场景：您在主题工作区的
inbox/ 目录下放置了待处理的原始学术论文（PDF 或 LaTeX 源码）。
- 直接输入斜杠命令与配置：
- 预期效果：自动解析 PDF 的排版及数学公式，转化为纯净的 Markdown 格式输出到
raw/articles/ 或 raw/papers/ 中。
🔬 第 3 阶段：深度编译与核心概念提取
- 卡片编译
- 面临场景：
raw/ 下已生成转换好的原始 Markdown 论文，您需要将其抽取为文献笔记与单独的概念卡片。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_compile。
- 预期效果：自动从文献中提取所有数学定义、定理和核心概念，以独立卡片形式存入
wiki/concepts/，同时在 wiki/references/ 下建立正式的文献索引卡片。
- 知识库语义挖掘
- 面临场景：您希望对已编译的文献卡片做深度扫描，以确保没有任何关键的定理、引理或数学公式被遗漏。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_enrich。
- 预期效果：AI 深度检查文献文本，自动补挖遗漏的公式或概念，并在
wiki/concepts/ 下自动生成新的补充卡片。
🔗 第 4 阶段：关联、校验与语义规范化
- 计算语义嵌入与构建双链
- 面临场景：您需要让知识库中的卡片根据语义相似度自动产生关联，发现概念间隐藏的交集。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_semantic_link。
- 预期效果：调用 Ollama 向量模型计算所有概念卡片的相似度，自动在卡片底部注入美观的
[[相关概念|别名]] 双链。若概念相似度 $\ge 0.95$，还会在底层执行无人值守的物理去重合并。
- 标签规范化 (Map-Reduce)
- 面临场景：随着文献的增多，碎片化、单复数、同义词标签变得杂乱无章。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_tag_sync。
- 预期效果：运行 Map-Reduce 清洗全库的元数据标签，将混乱的标签降维合并为干净的本体论 (Ontology) 标准标签白名单。
- 概念去重与物理归并
- 面临场景：知识库中存在同义但不同名的冗余卡片，需要合并以保持图谱的高纯净度。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_concept_sync。
- 预期效果：物理合并同义概念文件，合并 frontmatter 别名，并自动重定向和重构全库所有受影响的
[[双链]] 引用。
- 死链自愈与格式校验
- 面临场景：您想要对工作区进行全面体检，修补断裂的死双链或校验 LaTeX 公式语法。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_lint。
- 预期效果：全局自愈断裂的双链（通过 Alias 路由映射接驳到新概念文件），自动转义 YAML frontmatter 中因 LLM 幻觉产生的不合规反斜杠，并校验公式语法。
- 关系图谱数据库索引更新
- 面临场景：在手动或自动修改完卡片关系后，需要更新底层关系图谱缓存。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_graph_index。
- 预期效果：重新扫描全库的双链拓扑结构，更新
output/graph.db SQLite 数据库，以便 AI 助手后续能够进行高性能的图关系查询。
💬 第 5 阶段：问答、知识审查与论文综述
- 严格文献引用问答
- 面临场景：您想针对整个文献库进行深度问答，并要求其给出绝对真实的推导与文献出处。
- 直接输入斜杠命令：在聊天 UI 中打出
/wiki_ask 并跟随问题，例如：/wiki_ask "A 理论与 B 定理在多维空间的映射关系是什么？"。
- 预期效果：AI 组合执行关系图谱 SQL 查询和向量 RAG 混合检索，返回带有严谨
[[wikilinks]] 文献引用的解答，杜绝虚假幻觉。
- 理论矛盾审查
- 面临场景：您想找出不同学术论文之间在公式推导、假设前提或实验结论上的学术矛盾或物理不一致。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_audit。
- 预期效果：多视角智能体协作审计，输出一份格式优雅的审查报告，精准点出不同论文之间的潜在矛盾。
- 自动文献综述撰写
- 面临场景：您需要针对某个复杂的研究方向，基于知识库撰写一份高度专业化、引用详实的学术综述报告。
- 直接输入斜杠命令：在聊天 UI 中打出
/wiki_research 并跟随您的综述研究主题。
- 预期效果：并行启动专业文献调研智能体，自动生成一份极具深度且引用完备的学术综述论文，输出到
output/ 目录下。
🧹 第 6 阶段：多主题长期维护与归档
- 工作区归档与恢复
- 面临场景：某个研究主题已经阶段性结束，您希望将其物理归档以保持当前工作区轻量化。
- 直接输入斜杠命令：在聊天 UI 中打出：
/wiki_hub_manager。
- 预期效果：自动将选定的主题目录安全地迁移/解包到
topics/.archive/ 目录下，并自动同步更新 Hub 中央路由注册表 wikis.json。可随时通过同一命令一键还原。
5. Obsidian 知识库集成与关系图谱净化指南
为了在 Obsidian 中获得极致的图谱可视化和沉浸式科研体验，请在 Obsidian 中直接打开具体的主题工作区目录（例如 ~/KnowledgeHub/topics/quantum-computing），不要打开 Hub 根目录。
⚙️ 一键排除非知识类系统文件（净化关系图与全局搜索）
因为主题工作区内包含自动生成的索引地图、智能体操作日志、项目配置等，您需要将它们在 Obsidian 的全局搜索和关系图谱中隐藏，从而只展示最纯粹的数学/物理文献卡片与核心概念图谱。
- 打开 Obsidian，进入 设置 (Settings) -> 档案与链接 (Files and links)。
- 找到 排除档案 (Excluded files) 配置项。
- 点击“添加新规则”，粘贴并启用以下两个正则表达式：
-
排除非知识类元数据与日志 Markdown 文件：
/(?:^|/)(?:_index|log|config|uncompiled-source-coverage)\.md$/
(本条规则能瞬间在 Obsidian 中隐去所有子目录及根目录下自动生成的目录大地图、Agent 执行日志、主题配置及文献未编译待办列表)。
-
排除系统点号文件夹、Agent 运行时、scratch、inbox 与 raw 目录：
/^\..*|(?:^|/)(?:scratch|inbox|raw)(?:/|$)/
(本条规则将显式隐藏如 .agents/ 运行时、.git/ 仓库元数据、.backup/ 自动备份、以及任意 scratch、inbox 和 raw 目录，保证知识图谱的绝佳美感)。
配置完成后，Obsidian 的全局搜索、反向链接和 Graph View 关系图谱将变得极其空灵干净，只保留由双链优雅交织的学术卡片网络。
