Obsidian 노트

운영 컨텍스트

${OBSIDIAN_VAULT:-$HOME/workspace/notes}에 위치한 로컬 볼트를 사용합니다. 이 볼트는 사용자 소유의 지식 베이스이자 마크다운 코드베이스로 취급합니다. 관련 없는 편집 내용은 보존하고, 요청하지 않은 대량 재작성은 피하며, 노트 파일명과 링크는 Obsidian 친화적으로 유지합니다.

이 볼트는 일반적으로 에이전트의 작업 공간 루트이므로, 일반적인 노트 작업에는 내장 파일 도구(Codex: read/apply_patch; DSH 및 pi: read/edit/write)를 사용할 수 있습니다. 볼트 외부의 항목에 대해서는 쓰기 전에 물어보십시오.

이 스킬은 Codex, pi, DSH에서 공유하는 하나의 번들입니다. 현재 에이전트에 맞는 기본 디렉터리를 선택한 후, 아래 모든 명령에서 $HELPER를 사용하십시오:

# DSH (표준 소스 복사본)
export SKILL_DIR="$HOME/.dsh/skills/obsidian-notes"
# Codex
# export SKILL_DIR="$HOME/.codex/skills/obsidian-notes"
# pi
# export SKILL_DIR="$HOME/.pi/agent/skills/obsidian-notes"

export HELPER="$SKILL_DIR/scripts/obsidian_notes.py"
python3 "$HELPER" --help

현재 셸에서 SKILL_DIR을 내보낸 적이 없다면, 명령마다 다시 내보내거나 이 스킬에 대해 하네스가 보고하는 스킬 기본 디렉터리로 scripts/obsidian_notes.py를 확인하십시오. python3을 사용하십시오(헬퍼는 표준 라이브러리만 사용합니다. python3이 없으면 python으로 대체).

확정적인 CRUD, 인덱싱, 로깅, 정적 분석(lint), Base 및 Canvas 작업에는 이 번들 헬퍼를 선호합니다. 헬퍼는 기본값으로 볼트를 사용하며, 볼트 외부의 경로는 거부합니다.

유용한 경우 로컬 Obsidian 앱이나 obsidian:// URI 스킴을 사용하여 노트를 엽니다. Linux Flatpak에서 앱 ID는 md.obsidian.Obsidian입니다. 일반적으로 PATH에 obsidian 바이너리는 없습니다.

이 스킬은 kepano/obsidian-skills의 패턴(Obsidian Flavored Markdown, Bases, JSON Canvas, CLI 사용법, 깔끔한 웹 추출)의 로컬 볼트 특화 상위 집합입니다. 이러한 도메인을 하나의 워크플로우로 유지하여 볼트 작업이 ${OBSIDIAN_VAULT:-$HOME/workspace/notes}로 범위가 제한되도록 합니다.

지식 베이스 모델

더 큰 지식 작업을 위해 세 계층 모델을 사용하십시오:

원시 소스: 사용자가 제공한 기사, PDF, 클리핑, 회의 노트, 스크린샷 또는 녹취록입니다. 사실의 근원으로 취급하며, 명시적으로 요청하지 않는 한 다시 쓰거나 삭제하지 마십시오.
위키 노트: 에이전트가 요약, 종합, 상호 연결 및 업데이트를 통해 생성하고 유지 관리할 수 있는 구조화된 마크다운 페이지입니다.
스키마: 이 스킬과 技术/00-System/ 아래의 볼트 로컬 규칙 노트, Obsidian 가이드 폴더를 포함합니다. 사소하지 않은 변경 전에 볼트 사용법, 분류 체계 및 Obsidian 규칙에 대한 노트를 검색하십시오.

먼저 읽어볼 가치가 있는 볼트 로컬 스키마 노트: AGENTS.md (볼트 루트, 볼트 전체 규칙), 技术/AGENTS.md (技术/ 로컬 규칙), 技术/00-System/目录结构说明.md, 技术/00-System/全局维护规则.md, 技术/00-System/分类与标签规范.md, 技术/00-System/知识库使用说明.md, 技术/00-System/文档模板说明.md, 技术/10-个人效率与环境/Obsidian/Obsidian知识管理使用规范.md.

준수해야 할 알려진 볼트 규칙:

내용은 중국어로 작성됩니다. 노트는 YAML 프론트매터가 있는 마크다운이며, 최소한 tags와 related를 포함하고, 일반적으로 title/aliases/created/updated/type/status/source를 포함합니다.
루트 폴더는 AI/ (주 지식 베이스, 번호가 매겨진 섹션) 및 开发/, 日记/, 零星想法/, 项目/입니다.
분류가 불확실한 것은 98-待整理에 속합니다. 폐기된 콘텐츠는 99-归档에 속합니다. 실제로 필요한 경우에만 해당 폴더를 만드십시오.
기존의 가치 있는 노트를 덮어쓰는 것보다 업데이트하는 것을 선호합니다. 안전한 병합이 불가능하면 "待合并" 접미사로 새 파일을 만드십시오.

사소하지 않은 작업의 경우 관련 스키마 노트를 먼저 읽으십시오. 목표는 지식 복합(compounding knowledge)입니다. 향후 세션이 처음부터 동일한 컨텍스트를 다시 발견하지 않도록 기존 페이지, 링크, 인덱스 항목 및 로그를 업데이트하십시오.

워크플로우

사용자 요청에서 작업을 명확히 하십시오: 생성, 읽기, 업데이트, 삭제, 검색, 수집(ingest), 쿼리, 정적 분석(lint), 정리, 열기, Base 생성, Canvas 생성, 웹 소스 클리핑, 또는 Obsidian 동작 디버깅.
변경하기 전에 기존 노트를 검사하십시오:
- Bash에서 rg 또는 에이전트 자체 콘텐츠/경로 검색 도구를 사용하여 콘텐츠 및 경로를 검색하십시오.
- 볼트 범위 경로에는 헬퍼의 search, read 또는 list 명령을 사용하십시오.
- 구조, 분류 체계 또는 장기 유지 관리가 중요한 경우 볼트 스키마 노트를 읽으십시오.
- 앱 구성이 중요한 경우에만 .obsidian/을 확인하십시오.
Obsidian 의미를 보존하십시오:
- 내부 참조에는 [[대상 노트]] 또는 [[대상 노트|별칭]]과 같은 위키 링크를 사용하십시오.
- 사용자가 정확한 참조를 필요로 하는 경우 [[대상 노트#제목]] 및 [[대상 노트#^블록-id]]와 같은 제목 링크와 블록 링크를 사용하십시오.
- 안정적인 분류에는 프론트매터의 태그를 사용하십시오. 인라인 #태그는 본문의 일부인 경우에만 사용하십시오.
- 메타데이터, 날짜, 별칭, 상태, 출처, 프로젝트, 영역, 모델, 호스트 및 다음 작업을 위해 YAML 프론트매터를 유지 관리하십시오.
- 구조화된 필드에는 Obsidian Properties 및 Bases 호환 프론트매터를 선호하십시오. 사용자가 명시적으로 Dataview 쿼리, 인라인 필드 또는 Dataview 대시보드를 요청하는 경우에만 status:: active와 같은 Dataview 인라인 필드를 사용하십시오.
- 볼트 콘텐츠를 포함할 때는 상대 포함 ![[file.png]] 또는 ![[Note#Heading]]을 선호하십시오.
- 시각적 강조가 필요한 콘텐츠(요약, 경고, 예시, 결정, 할 일, 질문)에만 콜아웃을 사용하십시오.
에이전트의 패치/편집 도구(Codex: apply_patch; DSH 및 pi: edit)로 범위가 제한된 편집을 하거나, 전체 노트 생성 또는 교체에는 write/헬퍼를 사용하십시오. 편집하거나 교체하기 전에 파일을 읽으십시오.
지속적인 변경의 경우 인덱스를 업데이트하거나 재생성하고 로그 항목을 추가하십시오.
편집 후 변경된 파일을 읽고, 링크/검색 결과를 확인하고, .base 또는 .canvas 파일이 있으면 유효성을 검사하고, 선택적으로 Obsidian에서 노트를 열어 확인하십시오.

노트 품질 규칙

새 노트의 경우, 단순한 마크다운 덤프가 아니라 Obsidian 내에서 유용한 노트를 만드십시오:

대상 폴더에 명확한 반대 규칙이 없는 한 YAML 프론트매터로 시작하십시오.
개념에 다른 이름이 있는 경우 aliases를 포함하십시오.
가능한 경우 기존 볼트 분류 체계와 일치하는 tags를 포함하십시오.
노트가 무엇인지 설명하는 간결한 첫 번째 문단을 추가하십시오.
백링크가 가능하도록 제목이 있는 섹션을 추가하십시오.
관련 기존 노트에 대한 위키 링크가 있는 ## 相关链接 또는 ## Links를 추가하십시오. 대상 폴더에서 이미 사용하는 현지화된 제목과 일치시키십시오. 번호가 매겨진 AI/ 폴더는 ## 相关链接을 사용하고, 프로젝트 노트는 둘 중 하나를 사용할 수 있습니다.
기본적으로 YAML 프론트매터에 구조화된 필드를 배치하여 Obsidian Properties 및 Bases가 편집, 정렬 및 필터링할 수 있도록 하십시오. 사용자가 Dataview 인라인 필드를 요청하지 않는 한 동일한 필드를 프론트매터와 key:: value로 본문에 중복하지 마십시오.
프로젝트 또는 작업 노트의 경우 실행 가능한 상태 및 다음 단계 필드를 포함하십시오.
상시 지식 노트의 경우 주장을 출처 노트 및 관련 개념에 연결하십시오.

새 노트 템플릿을 만들거나, 노트 구조를 수리하거나, 프론트매터, 태그, 백링크, Dataview, 인덱스 파일, 로그 및 소스 수집을 사용하는 방법을 결정할 때는 references/obsidian-patterns.md($SKILL_DIR 아래)를 읽으십시오.

Obsidian 마크다운 기능

노트를 Obsidian 내에서 더 유용하게 만드는 경우 다음 구문 기능을 사용하십시오:

위키링크: [[노트]], [[노트|별칭]], [[노트#제목]], [[노트#^블록-id]], [[#동일 노트 제목]].
포함: ![[노트]], ![[노트#제목]], ![[image.png|300]], ![[document.pdf#page=3]], ![[Canvas.canvas]], ![[View.base#View Name]].
콜아웃: > [!note], > [!warning] 제목, > [!todo]- 접힘, 콘텐츠를 위한 중첩 인용 줄 포함.
주석: %%숨겨진 텍스트%% 또는 에이전트 전용 주석에 대한 블록 주석(렌더링되지 않음).
강조/수학/다이어그램: ==강조==, 인라인 $수학$ , 블록 $$수학$$, 펜스 mermaid.
각주: [^1] 참조, 정의 및 인라인 각주.

노트를 과도하게 포맷하지 마십시오. Obsidian 확장이 탐색, 검색 또는 렌더링을 개선할 때까지 일반 마크다운을 선호하십시오.

Bases

사용자가 데이터베이스와 같은 노트 보기, 작업 목록, 읽기 목록, 프로젝트 대시보드, 필터링된 인덱스 또는 속성 기반 테이블/카드/목록/지도를 원할 때 .base 파일을 사용하십시오.

Base 파일은 YAML입니다. 다음을 중심으로 구축하십시오:

filters: 전역 및 보기별 표현식(예: file.hasTag("project"), file.inFolder("Daily Notes"), status == "active").
formulas: 계산된 필드(예: 마감까지 남은 일수, 상태 레이블, 예상 단어 수 또는 파생된 링크).
properties: 노트, 파일 및 수식 필드의 표시 이름 및 구성.
summaries: Average, Sum, Min, Max, Latest, Checked, Empty, Filled, Unique와 같은 집계 수식.
views: 명시적인 order가 있는 table, cards, list 또는 map 보기.

규칙:

필터 및 수식 표현식을 인용하십시오. 특히 :, #, 대괄호, 비교 연산자 또는 중첩 인용부호가 포함된 경우.
큰따옴표가 포함된 수식은 작은따옴표로 감싸십시오: 'if(done, "Yes", "No")'.
날짜 빼기는 기간을 반환합니다. 숫자 함수 전에 .days, .hours 등에 접근하십시오.
선택적 속성은 if(property, expression, fallback)으로 보호하십시오.
편집 후 유효성 검사: python3 "$HELPER" validate-base "Dashboards/Projects.base".

JSON Canvas

사용자가 시각적 맵, 연구 보드, 순서도, 종속성 맵, 프로젝트 개요 또는 캔버스를 요청할 때 .canvas 파일을 사용하십시오.

Canvas 파일은 최상위 nodes 및 edges 배열이 있는 JSON입니다:

노드는 id, type, x, y, width 및 height가 필요합니다.
노드 유형은 text, file, link 및 group입니다.
에지는 id, fromNode 및 toNode가 필요합니다. 선택적 측면은 top, right, bottom, left입니다.
고유한 16자 소문자 16진수 ID를 생성하십시오.
JSON 문자열 값에는 실제 줄 바꿈을 사용하고, 텍스트에 해당 문자를 표시해야 하는 경우가 아니면 리터럴 \n을 사용하지 마십시오.
노드 사이에 50-100px 간격을 두고, 그리드에 정렬하며, 그룹 노드는 하위 항목을 포함할 수 있을 만큼 충분히 크게 유지하십시오.
편집 후 유효성 검사: python3 "$HELPER" validate-canvas "Maps/Topic.canvas".

웹 클리핑 및 소스 추출

사용자가 볼트에 수집할 URL을 제공하는 경우:

로컬 defuddle 명령이 존재하는 경우 defuddle parse <url> --md를 선호하십시오. 읽을 수 있는 마크다운을 추출하고 탐색 클러터를 제거합니다.
defuddle는 여기에 기본 설치되어 있지 않습니다. 먼저 확인하고, 없으면 에이전트의 웹 가져오기/검색 도구를 사용한 후, 내구성 있는 사실과 링크만 볼트에 저장하십시오.
이미 원시 마크다운을 가리키는 URL에는 Defuddle을 사용하지 마십시오.
소스 URL, 작성자/날짜(가능한 경우), 검색 날짜 및 처리 상태를 프론트매터에 보존하십시오.
긴 소스의 경우, 전체 기사를 위키 계층에 덤프하는 대신 소스 요약 노트를 만들고 내구성 있는 개념/프로젝트/엔터티 노트를 업데이트하십시오.

Obsidian CLI 및 앱

Obsidian이 실행 중이고 obsidian 명령을 사용할 수 있는 경우, 앱 인식 작업에 사용하십시오:

obsidian help
obsidian read file="My Note"
obsidian search query="term" limit=10
obsidian property:set name="status" value="done" file="My Note"
obsidian backlinks file="My Note"
obsidian daily:append content="- [ ] Follow up"

플러그인 또는 테마 디버깅의 경우, 코드 변경 후 앱 인식 명령을 선호하십시오:

obsidian plugin:reload id=my-plugin
obsidian dev:errors
obsidian dev:console level=error
obsidian dev:screenshot path=screenshot.png
obsidian dev:dom selector=".workspace-leaf" text

CLI가 설치되지 않았거나 Obsidian이 실행 중이 아닌 경우, 볼트 파일 작업과 obsidian:// URI 스킴으로 대체하십시오. 헬퍼의 open 명령은 이미 Flatpak 앱 및 URI 대체를 처리합니다:

python3 "$HELPER" open "技术/00-System/index.md"

수집(ingest), 쿼리 및 정적 분석(lint)

사용자가 소스를 제공하거나 외부 아티팩트에서 지식을 추가하도록 요청하는 경우 수집 동작을 사용하십시오:

소스를 읽고 내구성 있는 사실, 결정, 개념, 엔터티, 미해결 질문 및 모순을 식별하십시오.
새 페이지를 만들기 전에 기존 페이지에 대해 볼트를 검색하십시오.
나중에 유용할 경우에만 소스 요약 노트를 만드십시오.
새 소스 페이지만 업데이트하지 말고 관련 기존 개념/프로젝트/엔터티 노트를 업데이트하십시오.
새 지식이 기존 노트에서 도달 가능하도록 백링크 및 related 항목을 추가하십시오.
수집된 내용과 변경된 페이지를 설명하는 로그 항목을 추가하십시오.

볼트에서 답변할 때 쿼리 동작을 사용하십시오:

가능한 경우 인덱스/스키마 노트를 먼저 읽으십시오.
답변하기 전에 관련 노트를 검색하고 읽으십시오.
답변에서 로컬 노트를 위키 링크 또는 경로로 인용하십시오.
답변이 내구성 있는 종합을 생성하는 경우, 이를 노트로 다시 작성하거나 기존 노트를 업데이트하도록 제안하십시오.

유지 관리를 위해 정적 분석(lint) 동작을 사용하십시오:

누락된 프론트매터, 누락된 관련 섹션, 고아 노트, 중복 제목, 오래된 주장, 잘못된 링크 및 페이지가 없는 중요한 개념을 확인하십시오.
광범위한 정리를 수행하기 전에 집중된 수리 계획을 보고하는 것을 선호하십시오.
요청된 정리의 경우 소규모 배치로 링크 및 메타데이터를 수리하고 패스를 기록하십시오.

헬퍼 명령

헬퍼는 기본값으로 ${OBSIDIAN_VAULT:-$HOME/workspace/notes}를 사용하며(--vault로 재정의 가능), 볼트 외부의 경로는 거부합니다. 전체 명령 목록은 python3 "$HELPER" --help를 실행하십시오.

# 제목 및 내용 검색
python3 "$HELPER" search "query"

# 상대 경로로 노트 읽기
python3 "$HELPER" read "AI/example.md"

# 노트 생성(상위 폴더 포함)
python3 "$HELPER" create "AI/example.md" --title "Example" --tags project,active --body $'# Example\n\n...'

# 검사 후 노트 교체
python3 "$HELPER" update "AI/example.md" --body "...full markdown..."

# 사용자가 명시적으로 요청한 경우에만 삭제
python3 "$HELPER" delete "AI/old-note.md" --yes

# Obsidian에서 노트 열기
python3 "$HELPER" open "AI/example.md"

# Base 생성 및 유효성 검사
python3 "$HELPER" create-base "技术/00-System/active-projects.base" --name "Active Projects"
python3 "$HELPER" validate-base "技术/00-System/active-projects.base"

# Canvas 생성 및 유효성 검사
python3 "$HELPER" create-canvas "AI/Maps/project-overview.canvas"
python3 "$HELPER" validate-canvas "AI/Maps/project-overview.canvas"

# 技术/00-System/index.md에서 위키 스타일 인덱스 재생성
python3 "$HELPER" index

# 로그 항목 추가
python3 "$HELPER" log "refactored 技术/00-System index, merged duplicate notes"

감사(Audit)

감사는 볼트 전체 문제를 찾고 로그에 기록하는 헬퍼의 패스(pass)입니다. --verbose 플래그를 사용하여 stdout에서 각 문제를 볼 수 있습니다:

python3 "$HELPER" audit --verbose

감사는 다음을 확인합니다:

존재하지 않는 내부 링크(위키 링크가 존재하지 않는 대상을 가리킴)
사용되지 않는 파일(다른 노트에서 링크되지 않은 노트)
중복 제목
오래된 프론트매터
누락된 기대 필드
잠재적 체계적 문제

(참고: 감사는 아직 빌드 중입니다. 전체 기능을 보려면 --help를 사용하여 도움말을 확인하십시오.)

Obsidian 노트 관리