[integration] Obsidian backend として使いやすい設計

[sotashimozono]

Question

doiget の store を Obsidian の vault として 使いやすく する設計。「絶対互換」ではなく「backend として柔軟に使えればよい」。

Background

souta は Obsidian で個人 PKM を運用している。BiblioFetch.jl の vault コマンド (bibliofetch vault add ...) は Obsidian-friendly な topic-based vault を持つ。

doiget では Obsidian backend として何を提供すべきか？

Options

A. Markdown frontmatter mode

• 各 paper を ~/papers/<safekey>.md として持つ (TOML metadata の代わり / 加えて)
• frontmatter (YAML) が Obsidian の Properties plugin で読める
• PDF への wiki-link [[<safekey>]] を支援
• Obsidian で paper 一覧 grep / dataview query 可能

B. Sidecar .md only

• TOML metadata はそのまま保持
• paper ごとに <safekey>.md を別途生成 (Obsidian 用 sidecar)
• TOML を一次 source、md は derived

C. Export-on-demand

• doiget は TOML のみ管理
• doiget obsidian sync ~/vault/papers で md を vault dir に dump
• vault path は user config

D. No special support

• doiget は store だけ管理、Obsidian 連携は別 plugin / script に委譲

Recommendation

C (export-on-demand)。理由:

• TOML を single source of truth に保つ (parse 楽、git diff 綺麗)
• Obsidian 連携は user の vault 構造に依存するので configurable に
• doiget obsidian sync で 1 コマンド連携、頻度は user 制御

A は appealing だが、Obsidian dependency を core に持ち込む

Open questions

• frontmatter schema: BiblioFetch.jl の TOML field をそのまま map / Obsidian 慣習 (e.g. tags: array) に合わせる？
• paper 間のリンクは [[ref]] (wikilink) / [](path) (markdown link)?
• Obsidian Dataview / Bases plugin との統合は想定するか？
• pdf 自体は vault 内に置く (重い) / 別 dir に置いて symlink？

Decision

???

[sotashimozono]

Filed as external review by Claude (Anthropic, AI agent operating under souta's GitHub auth).

立場

Recommendation C (export-on-demand) を 支持。 但し本文の "Open question" を全て確定させ、 Phase 7 (optional) に位置づけることを提案します。 Obsidian 連携は agent エコシステムの primary path ではないので、 core scope を膨らませない。

1. Phase 配置: optional Phase 7

#7 (Phase plan) で本文 "Phase 7: optional" は妥当。 Reviewer 補強として:

• Phase 0-6 の MVP / hardening / release が 完了するまで Phase 7 に着手しない
• Phase 7 は user demand 駆動 (issue / discussion で実際に Obsidian user が要望してから)
• core (doiget-core) には Obsidian 関連 code を入れない、 別 crate doiget-obsidian (binary doiget-obsidian or subcommand) で隔離

Cargo.toml:

[features]
obsidian = ["dep:doiget-obsidian"]   # default OFF

または:

crates/
├── doiget-obsidian/    # 別 crate、 default build に含めない

2. Subcommand 設計 (Phase 7 確定 spec)

doiget obsidian sync <vault_path> [--since <date>] [--include <filter>]
doiget obsidian export <ref> [--vault <path>]

• sync: store 全体 → vault に md 生成 (差分のみ)
• export: 単発 ref → md 出力
• 双方向 sync は しない (vault → store 反映は scope 外、 conflict 解決の悪夢)

3. Frontmatter schema

本文 open question への reviewer 回答:

---
title: "Example Paper"
authors:
  - "Alice"
  - "Bob"
year: 2026
doi: "10.1234/example"
arxiv_id: null
venue: "Phys. Rev. X"
tags:
  - "papers"           # convention
  - "physics"          # auto from venue
abstract: "..."
pdf: "[[10.1234_example.pdf]]"   # wikilink to PDF (or path)
schema_version: "1.0"
doiget:
  fetched_at: "2026-05-05T08:30:12Z"
  source: "unpaywall"
  license: "CC-BY-4.0"
---

理由:

• BiblioFetch.jl の TOML field を そのまま map (互換性)
• tags: は Obsidian 慣習 (Properties plugin が認識)
• pdf: は wikilink にして Obsidian で click 可能
• doiget: table は frontmatter でも nested で表現

4. PDF 配置

本文 open question への reviewer 回答:

• vault に PDF を置かない (default)
• ~/papers/ の PDF への symlink を vault に作るか、 frontmatter に 絶対 path を入れる
• 理由:
  • Obsidian Sync / iCloud / Dropbox で vault が同期される構成だと、 PDF (重い) が同期対象になり sync が遅くなる
  • PDF 1 source = ~/papers/ で集中管理する方が dedup できる
• ただし user が「PDF も vault に欲しい」と明示的に opt-in する場合の flag を提供:
  • doiget obsidian sync --include-pdf で PDF を vault に copy

5. Wikilink の format

本文 open question への reviewer 回答:

• [[<safekey>]] (wikilink) を default
• markdown link [](path) は web export 時に有用、 secondary
• frontmatter の pdf: field は wikilink format で書く (Obsidian の link graph に乗る)

6. Dataview / Bases plugin との統合

本文 open question への reviewer 回答:

• Phase 7 では Dataview を想定した frontmatter を作るが、 Dataview plugin そのものに依存しない
• frontmatter の field 名 / 型を Dataview-friendly に (year: number / tags: list)
• 但し dataviewjs snippet を md 内に埋めるのは scope 外 (user が template で追加すれば良い)

例: vault に papers/_index.md を生成、 そこに dataview query の例を comment として残す:

<!-- doiget can put this comment for users:
     dataview query: TABLE year, venue FROM "papers"
-->

これで dataview plugin user は immediately 使える。

7. Sync の incremental 性

doiget obsidian sync を毎回 full re-export すると vault の git 履歴が膨らむ。 reviewer 推奨:

• 各 paper の md に doiget.fetched_at field を入れる (frontmatter)
• store 側の [doiget].fetched_at と比較し、 古い場合のみ re-export
• --force flag で全 re-export
• ~/.cache/doiget/obsidian/<vault_hash>.lock で sync state を持つ

8. Conflict resolution

user が vault 内の md を手動編集した場合:

• doiget は frontmatter のみ更新、 body (本文 markdown) は touch しない
• frontmatter の特定 field (例: tags:) も user 編集を尊重: doiget は [doiget] table 内のみ書き換え
• 競合検出: md の MD5 を保持しておき、 sync 前に hash 比較で user 改変を検出

これで「doiget が user の note を上書きした」事故を防ぐ。

9. Vault の発見

user が ~/Documents/MyVault に obsidian vault を持っている前提:

• doiget obsidian sync <path> で path 明示
• ~/.config/doiget/config.toml の [obsidian] vault_path = "..." を override
• env DOIGET_OBSIDIAN_VAULT でも可
• Phase 7 では auto-discovery (.obsidian/ dir 検索) は しない (誤検出 risk、 yagni)

10. Open question 完全確定

本文 open question への reviewer 回答 (まとめ):

Q	A
frontmatter schema	TOML field を そのまま、 tags: array は Obsidian 慣習で追加
paper 間 link	[[ref]] wikilink
Dataview / Bases	frontmatter は friendly に、 dataview plugin そのものに依存しない
pdf 配置	default = ~/papers/ 集中管理、 wikilink で参照、 --include-pdf で opt-in copy

Reviewer Decision proposal

• Decision: C (export-on-demand)、 Phase 7 (optional)
• 別 crate doiget-obsidian (default OFF feature) で隔離
• Subcommand: doiget obsidian sync + export のみ。 双方向 sync 不実装
• Frontmatter schema を本 review §3 の form で lock
• PDF は default ~/papers/ 集中、 vault には wikilink、 --include-pdf opt-in
• Wikilink format
• Dataview-friendly frontmatter、 plugin 依存なし
• Incremental sync (fetched_at 比較)
• Conflict resolution: body は touch せず、 frontmatter [doiget] のみ書き換え
• Auto-vault discovery は不実装

最終 Decision 権は author に留保。

---

Reviewer: Claude (Anthropic). Filed 2026-05-05.