如何用 Academic Research Skills 自带适配器把 Zotero、Obsidian 或 PDF 文件夹预载进 Material Passport？

如何用 Academic Research Skills 自带适配器把 Zotero、Obsidian 或 PDF 文件夹预载进 Material Passport【免费下载链接】academic-research-skillsAcademic Research Skills for Claude Code: research → write → review → revise → finalize项目地址: https://gitcode.com/GitHub_Trending/ac/academic-research-skills如果你已经维护了一个精选文献库Zotero 导出、Obsidian 笔记库或一个 PDF 文件夹希望在跑 Academic Research SkillsARS时让 Phase 1 文献检索 agent 先读你自己的库、再去外部数据库补齐而不是每次都从头检索ARS 提供了这条路径三个自带的参考 Python 适配器分别对应这三类语料源运行后各产出两个文件——带literature_corpus[]字段的passport.yamlMaterial PassportSchema 9和一个始终会写出的rejection_log.yaml。这条能力是 opt-in 的不供给语料时ARS 仍走原有纯外部数据库流程行为不变。适配器自 v3.6.4 随仓库发布v3.6.5 接上了消费端deep-research 的bibliography_agent与 academic-paper 的literature_strategist_agent。准备条件在 ARS 仓库根目录下操作适配器位于scripts/adapters/主文档是 SETUP 的适配器小节。安装适配器依赖文档说明依赖声明在requirements-dev.txtpip install -r requirements-dev.txt按你的语料源准备好输入Zotero需要 Better BibTeX 扩展。在 Zotero 中执行 File → Export Library → Format: Better CSL JSON得到 Better BibTeX JSON 文件例如~/zotero_export.json。适配器不调用 Zotero Web API只读这个本地导出文件。Obsidian一个 vault 目录例如~/ObsidianVault。PDF 文件夹一个目录路径例如/tmp/pdfs文件名需符合下述命名约定。注意ARS 本身不运行适配器代码。适配器在你的环境里读取你的数据、写出 YAML 文件ARS 只读这些文件。所以这条流程不要求你改动 ARS 的任何内部配置。运行对应语料源的适配器--passport和--rejection-log都是必选参数。下面三条命令分别对应三种语料源只运行与你的源匹配的那一条。Zotero读取 Better BibTeX JSON 导出python scripts/adapters/zotero.py \ --input ~/zotero_export.json \ --passport /tmp/passport.yaml \ --rejection-log /tmp/rejection_log.yaml输入是缺失必填字段title、authors、可解析的year、source_pointer的条目会带分类原因被拒收形如Spring 2024的季节性日期会按year_unparseable拒绝。文档示例路径/tmp/passport.yaml可替换为你自己的输出路径。Obsidian扫描 vaultpython scripts/adapters/obsidian.py \ --input ~/ObsidianVault \ --passport /tmp/passport.yaml \ --rejection-log /tmp/rejection_log.yaml_templates/和.obsidian/目录会被跳过[[wikilink]]不做解析会以字面文本留在user_notes中。带合法 YAML frontmatter 的笔记走 Convention ABibTeX 风格字段citekey:、authors:、year:、title:没有 frontmatter 的笔记走 Convention B文件名主干作citation_key正文进user_notesfrontmatter 是坏 YAML 时该笔记被拒收为invalid_field_format不会被静默改判为 Convention B。PDF 文件夹按文件名解析元数据python scripts/adapters/folder_scan.py \ --input /path/to/your/pdf/folder \ --passport /tmp/passport.yaml \ --rejection-log /tmp/rejection_log.yaml文件名解析支持两种约定加一个回退{Family}_{Year}_{title}.{ext}、{Family}{Year}{title}.{ext}或文件名中含{Year}和{Family}的松散形式。文件名解析不出 family 和 year 两个值的文件被拒收非 ASCII 文件名被拒收Unicode 支持是文档中列明的延后扩展项。符号链接会被跟随但拒收日志记录的是未解析路径以便区分子目录间的重名冲突。适配器失败时的行为按 适配器契约 的 fail-soft 约定单条条目有问题 → 写入 rejection log继续处理适配器级问题输入文件缺失、不可读、根级损坏→ 不写任何文件向 stderr 打印错误并以退出码 1 结束。不会产出半个 passport要么 passport 代表了对输入的完整扫描要么适配器明确失败。所以执行后如果发现passport.yaml没有生成应先处理 stderr 里的错误而不是去检查半截输出。验证适配器输出在进入 ARS 工作流之前文档要求先做三步验证。第一步用仓库自带的 schema 校验器检查两个产物python scripts/check_literature_corpus_schema.py \ --passport /tmp/passport.yaml \ --rejection-log /tmp/rejection_log.yaml校验器位于 scripts/check_literature_corpus_schema.py对应契约是 literature_corpus_entry.schema.json 和 rejection_log.schema.json。每条literature_corpus条目的必填字段为authors、citation_key、source_pointer、title、yearrejection_log中的reason使用封闭枚举如missing_required_field、invalid_field_format、year_unparseable、authors_unparseable、adapter_error等任何无法映射的输入必须出现在拒收日志里不允许静默丢弃。第二步确定性与坏数据检查同样来自适配器契约对同一输入跑两遍适配器去掉generated_at/obtained_at时间戳后 diff 输出任何非时间戳差异都是确定性 bug投喂一条已知坏条目确认它落入 rejection log 而不是让适配器崩溃或静默消失。第三步可选仓库维护者路径运行适配器的 pytest 覆盖pytest scripts/adapters/tests/ -v三个参考适配器的测试在 scripts/adapters/tests/CI 会在涉及scripts/adapters/**和 passport 契约的变更上运行它们。把 passport 交给 ARS 会话消费验证通过后的passport.yaml需要按运行传给 ARS 会话。SETUP.md 对这一步的说明是具体调用方式取决于你运行哪个 skill并明确用户提供的 Material Passport 路径是唯一发现锚点v3.6.8 设计轮次决策 R4-003没有固定的输出目录配置——每次运行都要显式指明 passport 位置。消费行为见 literature_corpus_consumers.mdliterature_corpus字段不存在、为空数组或非空数组时消费者的判定是字段缺失与[]等价都走纯外部数据库流程非空且能干净解析才进入corpus-first, search-fills-gap流程。v3.6.5 起接入的两个消费者deep-research 的 bibliography_agent 和 academic-paper 的 literature_strategist_agent。成功判定看 agent 输出的 Search Strategy 部分语料非空且可解析时会输出PRE-SCREENED FROM USER CORPUS:块包含Total entries scanned、Included、Excluded、Skipped等计数和对应的 citation_keys。语料可解析但 0 条通过筛选时块内还会带一条 zero-hit note文档列出的可能原因是语料相对当前 RQ 过时、RQ 已偏离原策展方向、适配器导出了与本 RQ 无关的条目。如果 passport 中的literature_corpus[]无法解析例如经过手工编辑或组装agent 不会中止而是在 Search Strategy Report 中输出[CORPUS PARSE FAILURE: cause]并回退到纯外部数据库流程。看到该标记即可确认预载语料没有生效。消费端还有几条硬约束值得知道corpus 条目不是预批准的与外部检索结果适用同一套 Inclusion/Exclusion 标准任何被跳过的条目必须在 PRE-SCREENED 块里记录原因消费者只读从不改写literature_corpus[]。限制与隐私边界Zotero 无实时同步自带适配器只读 Better BibTeX JSON 导出不调用 Zotero Web API。需要 live sync 时要按 契约第 8 节 自己写适配器zotero.py是文档指定的起点。文件名约定是硬约束folder_scan 解析不了就拒收非 ASCII 文件名一律拒收。隐私abstract和user_notes被 schema 标为 PRIVATE。文档明确说明如果你要公开分享 passport提交到公开仓库、放到网上自行负责移除或清空这两个字段——ARS 不强制执行消费者把它们当作可选字段省略不会导致失败。来源文档定位这三个参考适配器是starting points, not production toolsNotion、Readwise、Airtable、自定义 SQLite 等语料源需要你自己写适配器复用_common.py里的辅助函数make_citation_key、ensure_unique_citekey、parse_csl_name、write_passport、write_rejection_log等并按约定给每条条目设置obtained_via: other和清晰的adapter_name。按上述流程走完成功的最终状态是check_literature_corpus_schema.py校验通过、passport.yaml里literature_corpus[]非空、rejection_log.yaml列出了全部无法映射的条目随后在 ARS 会话中指定该 passport 路径agent 的 Search Strategy 输出里出现 PRE-SCREENED 块即表示预载语料已进入检索流程。需要扩展到其他语料源时从 适配器契约 第 8 节的自写适配器约定入手。【免费下载链接】academic-research-skillsAcademic Research Skills for Claude Code: research → write → review → revise → finalize项目地址: https://gitcode.com/GitHub_Trending/ac/academic-research-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考