词元星图TokenAtlas
返回案例库

精选案例 · 知识库与文档 / 科研阅读与计算

面向当前科研 vault 的 skills 协议

作者： universechen

该文档定义了一套用于增强 Obsidian 科研 vault 研究上下文的 Claude Code skills 协议，包含 Entry、Retrieval、Material、Object 四层技能：start-my-day 和 conf-papers 组织阅读入口，paper-search 只读检索，paper-ingest 下载 PDF 并调用 MinerU 云端 API 解析，paper-analyze 在 References/ 下生成或补全论文卡片。…

案例速读

README 系统定义了从入口、召回、材料获取到对象沉淀的完整工作流，分层清晰，每个 skill 的职责、执行流程、写入边界明确；包含 uv 强制规则、查重策略、图片引用规范等详细约束，可操作性强且维护成本低。适合需要结构化论文管理的研究者参考或直接采用。 建议从 「面向当前科研 vault 的 skills 协议」、「目录职责」、「Skill 分层」、「Entry：研究入口」 进入正文，先确认真实任务和模型辅助过程。

  • 重点看 Skill 分层结构与目录职责定义（.claude/skills/、.research/、.claude/lib/）、uv run 标准执行模式与依赖管理、MinerU 云端 API 调用流程与 fallback 策略。结合 知识库与文档 / 科研阅读与计算 / Obsidian vault / research workflow 和「researchers、Obsidian users、academic knowledge workers」，它更适合作为任务检索后的精读材料。
  • 正文目录和原始材料仍然是判断依据；导读只帮助你更快定位阅读重点。
首读入口
目录职责
读者
researchers、Obsidian users、academic knowledge workers
复用
Skill 分层结构与目录职责定义（.claude/skills/、.research/、.claude/lib/）
结构
12 个目录入口

原文内容

面向当前科研 vault 的 skills 协议

这套 skills 服务于当前 Obsidian 科研知识库，而不是独立的论文管理项目或普通代码仓库。

核心目标是增强研究上下文：

  • 在 Daily/ 中留下时间锚点与阅读入口
  • 在 References/ 中维护稳定对象卡片
  • 在 Clippings/ 中保留外部材料与摘录
  • 在 Attachments/ 中保存需要被笔记长期引用的附件
  • 在 .research/ 中统一管理 skill 运行产物、缓存、日志和中间索引

目录职责

  • .claude/skills/<skill-name>/SKILL.md：Claude Code 可发现的 skill 定义。
  • .claude/skills/<skill-name>/scripts/：该 skill 的入口脚本与专属逻辑。
  • .claude/skills/README.md：本组科研 skills 的总协议，不是独立 skill。
  • .claude/lib/：跨 skill 共享 Python 模块；共享 helper 只保留一份，不在各 skill 目录下重复维护副本。
  • .research/：skill 运行产物目录，默认不承载长期知识内容。

Skill 分层

Entry：研究入口

  • start-my-day：围绕今天的 Daily/ 组织阅读入口。
  • conf-papers：围绕会议、年份或专题组织阅读入口。

Retrieval：上下文召回

  • paper-search：只读检索论文卡片、剪藏、Daily 与项目上下文。

Material：材料获取与解析

  • paper-ingest：下载论文 PDF，调用 MinerU 官方云端 API，并把 Markdown、结构化结果与 fallback 产物统一写入 .research/paper-ingest/。

Object：稳定对象沉淀

  • paper-analyze：基于 paper-ingest 产物生成或补全 References/ 下的论文对象卡片。

Python / uv 运行规则

所有脚本必须通过 uv run 执行。不得直接运行 python scripts/xxx.py。

如果 uv 不可用，应停止并提示用户安装或配置 uv，不要降级为直接运行 Python。

跨 skill 复用的 Python helper 统一放在 .claude/lib/；新增共享逻辑时优先收敛到这里，而不是在多个 scripts/ 目录中复制粘贴。

标准形式：

uv run --with PyYAML --with requests python .claude/skills/<skill-name>/scripts/<script>.py [args...]

各 skill 的具体依赖见对应 SKILL.md。

产物落点

运行产物

运行产物统一写入 .research/：

  • .research/start-my-day/
  • .research/conf-papers/
  • .research/paper-ingest/
  • .research/paper-analyze/

.research/.gitkeep 用于保留目录，其他运行产物默认由 .gitignore 忽略。

知识内容

知识内容仍写入 vault 的稳定区域：

  • 时间锚点、当天阅读入口 → Daily/
  • 外部材料、网页摘录、论文摘录 → Clippings/
  • 稳定对象卡片（论文、作者、会议等） → References/
  • 被笔记长期引用的附件 → Attachments/

论文解析与图片引用规则

paper-ingest 默认把论文解析产物放入：

.research/paper-ingest/<paper-key>/

其中长期可复用的主文本、结构化结果和 fallback 图片都通过 manifest.json 统一索引。若笔记正文需要长期引用图片，必须先将目标图片从 outputs.image_dir 或 fallback 目录复制到 Attachments/，再使用：

![[Attachments/<filename>]]

不要在稳定笔记中直接嵌入 .research/... 路径。

查重与写入边界

任何可能创建或补全笔记的 skill，必须先检查既有上下文：

  1. References/
  2. Clippings/
  3. Daily/
  4. 项目与会议上下文

已有稳定对象时优先补全，不新建重复卡片。只有旧记录但没有稳定对象时，说明来源并谨慎链接。完全无记录时，明确说明“未检索到既有记录”。

元数据与链接规则

  • 优先使用当前 vault 已存在的中文字段。
  • 日期统一使用 YYYY-MM-DD。
  • 论文卡片整体结构优先遵守 Templates/论文模板.md；若通用约定、skill 示例与模板不一致，以目标模板和现有目标笔记结构为准。
  • vault 内部笔记统一使用 [[wikilink]]。
  • 长期附件统一使用 ![[Attachments/...]]。
  • 外部来源统一使用标准 Markdown 链接 [text](url)。

各 skill 定位

start-my-day

为当天 Daily/ 生成论文阅读入口、推荐概览与后续阅读建议。运行产物写入 .research/start-my-day/。

在整个 vault 中搜索论文对象、相关剪藏和研究上下文。严格只读，不创建 .research/ 产物，也不修改笔记。

paper-ingest

下载论文 PDF，调用 MinerU 官方云端 API，统一管理 .research/paper-ingest/<paper-key>/ 下的 Markdown、结构化结果与 fallback 图片产物。它只负责材料获取、解析与归档，不写稳定论文卡片。

paper-analyze

在 References/ 中生成或补全论文对象卡片。论文卡片是知识内容；图谱、索引等运行产物写入 .research/paper-analyze/，全文证据优先来自 paper-ingest 产物；缺少 ingest 产物时，应先触发 paper-ingest。

conf-papers

围绕会议、年份或主题生成阅读入口。运行产物写入 .research/conf-papers/，稳定论文对象仍由 paper-analyze 处理。
返回顶部