vis

# Vault Intelligence System (vis) Skill

## 개요

vis는 BGE-M3 기반 시맨틱 검색 엔진으로 Obsidian vault의 지식 관리를 지원하는 CLI 도구.
사용자의 요청을 분석하여 최적의 vis 명령어와 옵션을 자동 선택하여 실행.

## daemon 서버 모드 (성능 최적화)

**⚠️ 필수 사전 체크: vis 검색/관련 문서 요청 전 반드시 visd 상태를 확인하고, 미실행 시 자동 기동한다.**

### visd 자동 기동 프로토콜 (모든 검색 요청 시 의무 실행)

```bash
# Step 1: 상태 확인
visd status 2>&1

# Step 2: 미실행이면 즉시 기동 (출력에 "not running" 또는 오류 포함 시)
visd start

# Step 3: 준비 대기 (최대 30초, health 체크)
sleep 3 && curl -s http://localhost:8741/health

# Step 4: indexed: true 확인 후 검색 실행
curl -s --get --data-urlencode "query=키워드" "http://localhost:8741/search?search_method=hybrid&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'
```

### 서버 관리 명령어

```bash
visd start     # 시작 (이미 실행 중이면 스킵)
visd status    # 상태 확인 (PID, 문서 수, 인덱스)
visd logs 20   # 최근 로그 20줄
visd restart   # 재시작
visd stop      # 중지
```

### HTTP API 검색 (visd 실행 중일 때, 0.3초 vs CLI 8초)

```bash
# 기본 검색
curl -s --get --data-urlencode "query=키워드" "http://localhost:8741/search?search_method=hybrid&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'

# rerank 포함 검색
curl -s --get --data-urlencode "query=키워드" "http://localhost:8741/search?search_method=hybrid&rerank=true&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'
```

## 사용자 의도 → vis 명령어 매핑

사용자가 아래 의도를 표현하면 해당 vis 명령어를 적극 제안하고 실행.

| 사용자 의도 | vis 명령어 | 예시 요청 |
|---|---|---|
| 문서 검색 | `vis search` | "TDD 관련 문서 찾아줘", "리팩토링에 대해 검색해줘" |
| 주제별 문서 수집 | `vis collect` | "TDD 관련 자료 모아줘", "클린코드 문서 정리해줘" |
| 관련 문서 찾기 | `vis related` | "이 문서와 비슷한 거 찾아줘", "연관 문서 뭐 있어?" |
| MOC 생성 | `vis generate-moc` | "TDD MOC 만들어줘", "주제별 목차 생성해줘" |
| 자동 태깅 | `vis tag` | "이 문서에 태그 달아줘", "폴더 전체 태깅해줘" |
| 관련 문서 섹션 추가 | `vis add-related-docs` | "관련 문서 링크 넣어줘", "백링크 추가해줘" |
| 지식 공백 분석 | `vis analyze-gaps` | "vault에 빈 부분 뭐야?", "부족한 주제 찾아줘" |
| 중복 문서 감지 | `vis duplicates` | "중복 문서 있어?", "겹치는 내용 찾아줘" |
| 주제 분석 | `vis analyze` | "vault 주제 분포 보여줘", "어떤 주제가 많아?" |
| 클러스터 요약 | `vis summarize` | "문서 클러스터링해줘", "주제별로 묶어줘" |
| 학습 리뷰 | `vis review` | "이번 주 학습 정리해줘", "월간 리뷰 만들어줘" |
| 고립 태그 정리 | `vis clean-tags` | "안 쓰는 태그 정리해줘", "태그 정리" |
| 인덱스 갱신 | `vis reindex` | "인덱스 다시 만들어줘", "새 문서 반영해줘" |
| 태그 목록/통계 | `vis list-tags` | "태그 분포 보여줘", "어떤 태그가 많아?" |
| 주제별 문서 연결 | `vis connect-topic` | "TDD 주제 문서 연결해줘", "그래프 연결 작업" |
| 연결 진행 상황 | `vis connect-status` | "연결 작업 얼마나 됐어?", "진행 상황 확인" |
| 시스템 상태 확인 | `vis info` | "vis 상태 어때?", "캐시 상태 확인" |

## 검색 전략 자동 선택

`vis search` 실행 시, 사용자의 표현을 분석하여 최적의 옵션을 자동 조합.

### 검색 방법 선택 기준

| 판단 기준 | 검색 방법 | 옵션 |
|---|---|---|
| 정확한 용어/키워드 검색 ("~라는 단어", "정확히") | keyword | `--search-method keyword` |
| 개념/의미 기반 탐색 ("~에 대해", "~란 무엇") | semantic | `--search-method semantic` |
| 일반적인 검색 (기본) | hybrid | `--search-method hybrid` |
| 긴 문장, 복합 개념, 여러 주제 결합 | colbert | `--search-method colbert` |

### 품질 옵션 자동 추가 기준

| 사용자 표현 키워드 | 추가 옵션 | 효과 |
|---|---|---|
| "정확한", "가장 관련 높은", "best" | `--rerank` | 재순위화로 정확도 향상 |
| "다 찾아줘", "빠짐없이", "포괄적으로" | `--expand` | 동의어 + HyDE 확장 |
| "완전히", "깊이 있게", "철저하게" | `--rerank --expand` | 최고 품질 검색 |
| 결과가 부족할 때 | `--top-k 20` | 더 많은 결과 반환 |
| 최근 문서만 | `--threshold 0.5` | 높은 유사도만 |

### 검색 실행 기본 패턴

```bash
# 기본 검색
vis search "검색어"

# 고품질 검색 (정확도 중요)
vis search "검색어" --rerank

# 포괄적 검색 (놓치지 않기)
vis search "검색어" --expand

# 최고 품질 (정확 + 포괄)
vis search "검색어" --rerank --expand

# 결과 저장
vis search "검색어" --output results.md
```

## 주요 명령어 사용 패턴

### 주제별 문서 수집 (collect)
사용자가 특정 주제의 문서를 모으려 할 때 사용.
```bash
vis collect "주제" --output collection.md
vis collect "주제" --top-k 30 --expand    # 포괄적 수집
```

### 관련 문서 찾기 (related)
특정 문서와 유사한 문서를 찾을 때 사용.
```bash
vis related "문서명.md" --top-k 10
```

### MOC 자동 생성 (generate-moc)
주제별 Map of Content를 자동으로 생성할 때 사용.
```bash
vis generate-moc "주제" --top-k 50
vis generate-moc "주제" --output "MOC-주제.md" --include-orphans
```

### 자동 태깅 (tag)
문서에 hierarchical tag를 자동으로 부여.
```bash
vis tag "문서명.md"                    # 단일 문서
vis tag "폴더명/" --recursive          # 폴더 전체
vis tag "문서명.md" --dry-run          # 미리보기
vis tag "문서명.md" --tag-force        # 기존 태그 무시하고 재생성
```

### 관련 문서 섹션 추가 (add-related-docs)
문서에 "관련 문서" 섹션을 자동으로 추가.
```bash
vis add-related-docs "문서명.md"
vis add-related-docs "문서명.md" --dry-run           # 미리보기
vis add-related-docs --batch --pattern "000-SLIPBOX/*.md"   # 배치 처리
```

### 지식 공백 분석 (analyze-gaps)
vault에서 부족한 주제나 연결이 약한 영역을 분석.
```bash
vis analyze-gaps --top-k 20
```

### 중복 문서 감지 (duplicates)
내용이 유사한 중복 문서를 찾아 정리.
```bash
vis duplicates
```

### 주제 분석 (analyze)
vault 전체의 주제 분포를 분석.
```bash
vis analyze --output analysis.md
```

### 클러스터 요약 (summarize)
문서를 클러스터링하고 주제별로 요약.
```bash
vis summarize --clusters 5
vis summarize --topic "TDD" --clusters 3 --style detailed
vis summarize --since "2024-01-01" --output recent.md
```

### 학습 리뷰 (review)
일정 기간의 학습 활동을 리뷰.
```bash
vis review --period weekly
vis review --period monthly --output monthly-review.md
vis review --from 2024-08-01 --to 2024-08-31
vis review --topic TDD --period quarterly
```

### 태그 목록 및 통계 (list-tags)
vault의 태그 목록과 사용 통계를 확인.
```bash
vis list-tags                        # 전체 태그 목록
vis list-tags --depth 1              # 최상위 태그만
vis list-tags --min-count 5          # 5개 이상 문서에 사용된 태그
vis list-tags --output tags.md       # 파일로 저장
```

### 주제별 문서 연결 (connect-topic)
주제(태그)를 기준으로 MOC 생성 + 관련 문서 링크를 한 번에 처리.
```bash
vis connect-topic "TDD"                           # MOC + 관련 문서 링크
vis connect-topic "TDD" --dry-run                  # 미리보기
vis connect-topic "TDD" --skip-moc                 # 관련 문서 링크만
vis connect-topic "TDD" --skip-related             # MOC만
vis connect-topic "TDD" --related-k 5 --backup     # 관련 링크 5개 + 백업
```

### 연결 진행 상황 (connect-status)
주제별 문서 연결 작업의 진행 상황을 확인.
```bash
vis connect-status                   # 요약
vis connect-status --detailed        # 전체 주제 상세 현황
```

### 고립 태그 정리 (clean-tags)
1개 이하 문서에서만 사용되는 고립 태그를 감지하고 정리.
```bash
vis clean-tags                  # 감지만
vis clean-tags --dry-run        # 미리보기
```

### 인덱스 관리 (reindex)
새 문서 추가 후 또는 인덱스 갱신이 필요할 때.
```bash
vis reindex                       # 기본 재인덱싱
vis reindex --with-colbert        # ColBERT 포함
vis reindex --force               # 강제 전체 재인덱싱
vis reindex --include-folders 000-SLIPBOX 003-RESOURCES   # 특정 폴더만
```

## vis 기능 전체 안내

사용자가 "vis로 뭘 할 수 있어?", "vis 기능 알려줘" 등으로 질문하면 아래 내용을 기반으로 상세히 안내.

### 19개 명령어 전체 목록

1. **search** - 시맨틱/키워드/하이브리드/ColBERT 검색 (4가지 방법 + rerank + expand)
2. **collect** - 주제별 문서 수집 및 정리
3. **related** - 특정 문서와 유사한 관련 문서 찾기
4. **generate-moc** - 주제별 Map of Content 자동 생성
5. **tag** - 문서에 hierarchical tag 자동 부여
6. **add-related-docs** - 문서에 "관련 문서" 섹션 자동 추가
7. **analyze-gaps** - vault의 지식 공백 분석
8. **duplicates** - 중복/유사 문서 감지
9. **analyze** - vault 주제 분포 분석
10. **summarize** - 문서 클러스터링 및 주제별 요약
11. **review** - 기간별 학습 활동 리뷰 (주간/월간/분기)
12. **clean-tags** - 고립 태그 감지 및 정리
13. **reindex** - 검색 인덱스 재구축
14. **init** - 시스템 초기화 (최초 설정)
15. **test** - 시스템 테스트
16. **info** - 시스템 상태 및 캐시 정보 확인
17. **list-tags** - Vault 태그 목록 및 통계 (계층별, 문서 수)
18. **connect-topic** - 주제별 문서 연결 (MOC 생성 + 관련 문서 링크 삽입)
19. **connect-status** - 그래프 연결 진행 상황 확인

### 검색 엔진 특징
- BGE-M3 모델 기반 Dense + Sparse + ColBERT 3가지 임베딩
- Cross-encoder 재순위화 (BGE Reranker V2-M3)
- 쿼리 확장: 동의어 + HyDE (Hypothetical Document Embedding)
- SQLite 캐싱으로 빠른 반복 검색

## 관련 문서 자동 제안 (Related Notes)

`vis search` 또는 `vis related` 실행 후, 검색 대상 문서가 명확한 경우 **관련 문서 링크 추가를 자동으로 제안**한다.

### 트리거 조건

- 사용자가 특정 문서에 대해 검색하거나 (`vis related "문서.md"`)
- 검색 결과에서 특정 문서와 관련된 문서들이 발견된 경우

### 프로세스

1. **후보 선별**: 검색 결과에서 daily notes, 자기 자신을 제외하고 관련도 높은 문서 목록 생성
2. **사용자에게 제안**: 후보 목록을 번호와 함께 표시하고, 추가할 문서를 선택하도록 요청
   - 각 후보에 한 줄 맥락 설명 포함
3. **사용자 피드백 필수**: 선택된 문서만 Related Notes 섹션에 추가
   - 맥락 설명도 사용자가 수정 가능
4. **적용**: 문서 하단에 `## Related Notes` 섹션 추가 (Uncertainty Map 섹션이 있으면 그 앞에)
   ```markdown
   ## Related Notes
   - [[문서명]] - 맥락 설명
   ```
5. **기존 Related Notes**: 이미 섹션이 있으면 중복 없이 항목을 추가

### 주의사항

- **반드시 사용자 승인 후 적용** — 자동으로 문서를 수정하지 않음
- frontmatter의 `related:` 필드는 사용자가 명시적으로 요청한 경우에만 업데이트

## 자주 실수하는 옵션

| 잘못된 옵션 | 올바른 사용법 |
|---|---|
| `--method` | `--search-method` |
| `--k` | `--top-k` |
| `--top` | `--top-k` |
| `--output-file` | `--output` |
| `--reranking` | `--rerank` |
| `--query "TDD"` | positional: `vis search "TDD"` |
| `--topic "TDD"` | positional: `vis collect "TDD"` |
| `--file "문서.md"` | positional: `vis related "문서.md"` |
| `--target "문서.md"` | positional: `vis tag "문서.md"` |
| `--topic "TDD"` (moc) | positional: `vis generate-moc "TDD"` |
| `--file "문서.md"` (add) | positional: `vis add-related-docs "문서.md"` |
| `--similarity-threshold` | `--threshold` (add-related-docs) |

상세 CLI 레퍼런스는 `references/cli-reference.md` 참조.