사용법
에이전트와 CLI
Claude Code 같은 에이전트도 사람과 같은 규칙으로 문헌 노트를 다룹니다. 기본은 미리보기이고, 쓰기는 명시적으로 허락할 때만 합니다.
구조
명령줄 스크립트 scripts/ingest.mjs(저장소에 있음)는 실행 중인 Obsidian의 플러그인에 작업을 맡깁니다. 읽기만 하는 일은 Obsidian이 꺼져 있어도 인덱스 파일로 답합니다(--offline). 그래서 에이전트가 만든 노트도 사람이 명령 팔레트로 만든 노트와 똑같은 보존 규칙을 따릅니다.
flowchart LR AG["에이전트"] --> CLI["ingest.mjs"] CLI -->|"쓰기와 실시간 읽기"| OB["Obsidian의 CMDS Zotero"] CLI -->|"읽기만, Obsidian 꺼짐"| IX["인덱스 파일"] OB --> ZT["Zotero"] OB --> NT["문헌 노트"] %% @key: OB %% @aux: IX
자주 쓰는 액션
node scripts/ingest.mjs --vault "Research" --action recent --days 30
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026
node scripts/ingest.mjs --vault "Research" --action import --citekey Example2026 --apply
node scripts/ingest.mjs --vault "Research" --action pdf-text --citekey Example2026 --pages 1-3
node scripts/ingest.mjs --vault "Research" --action locate --citekey Example2026 --quote "quoted text"| 액션 | 하는 일 |
|---|---|
recent |
최근 읽은 논문과 노트 상태(none, behind, current, foreign, duplicate) |
import |
노트 만들기, 갱신. --apply가 없으면 미리보기만 함 |
pdf-text |
Obsidian에 든 pdf.js로 PDF 텍스트 추출. 스캔본이면 textLayer: none과 OCR 권고 |
locate |
인용문이 있는 쪽을 찾아 Zotero 리더 링크와 함께 돌려줌 |
annotations |
논문의 주석을 첨부별, 읽기 순서로. --color, --type, --tag, --today, --fresh |
citing |
그 논문을 인용한 노트를 줄 번호, 발췌와 함께. 예전 키도 셈 |
cites |
한 노트가 인용한 문헌. 참고문헌 제목 아래의 목록도 셈 |
resolve --stdin |
한 줄에 JSON 하나씩, 최대 500건을 한 번에 조회 |
그 밖에 info, identity, connection, diagnostics, refresh, reconcile이 있습니다. --help가 액션마다 받는 옵션을 보여 줍니다.
에이전트가 지키는 규칙
- 관리 구역을 직접 고치지 않습니다. 에이전트의 요약과 해석은
## Synthesis나## Notes에 씁니다. import는 쓰면 사람의 글이나 다른 플러그인의 노트를 해칠 수 있는 충돌이 있으면note-conflict로 거절합니다.- Zotero에서 실시간으로 읽지 못하면
--allow-stale없이는 쓰지 않습니다. - 읽기만 허락된 환경에서는
scripts/ingest-ro.mjs를 씁니다. 쓰기와--apply를 거절합니다. - PDF 텍스트 캐시(
.cmds-zotero/pdf-text/)는 논문 전문이므로 공유하지 않습니다.
References headings(설정 → Advanced)는 cites와 citing이 참고문헌 구역으로 볼 제목입니다. 기본값은 References, Bibliography, Works Cited, 참고 문헌, 참고 자료입니다. Word kit도 참고문헌 구역이 없는 원고에서 이 목록의 첫 제목을 씁니다.
전체 규약은 저장소의 에이전트 계약에 있습니다.