SoDam-WikiMate

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #machine-learning #deep-learning #linux #nodejs #windows #cli #kubernetes #awesome-list #security #mcp #openai

(★ 51)

AI에게 '정리해줘'라고 하면 흩어진 자료를 옵시디언(원본)에 노트로 정리하고, 관련 노트끼리 연결·분류·요약하고, 선택적으로 노션에 색인하는 Claude Code 플러그인 + 이식형 MCP 코어. 보관함 자동탐지·정리·자동 링크/MOC·자동 분류·요약(원자 노트)·검색(가짜 인용 방지)·볼트 건강검진(중복·깨진 링크·고아 탐지, 삭제 없는 안전 수정)·작업 로그. 사람 승인 게이트·원문 보존 알림·경로/프롬프트 인젝션 방어·무의존.

File Explorer

Download Latest Version (.zip)

- marketplace.json
- plugin.json
- pre-commit
- - ci.yml
- 01_PRD.md
- 02_DATA_MODEL.md
- 03_PHASES.md
- 04_PROJECT_SPEC.md
- README.md
- RESEARCH_SOURCES.md
- - SETUP.md
- - SETUP.md
- wikimate-reviewer.md
- wikimate-classify.md
- wikimate-link.md
- wikimate-lint.md
- wikimate-summarize.md
- wikimate.md
- hooks.json
- session-start.mjs
- - classify.mjs
  - collect.mjs
  - fix.mjs
  - link.mjs
  - lint.mjs
  - runlog.mjs
  - shared.mjs
  - summarize.mjs
- server.mjs
- collect-real.mjs
- e2e-classify-real.mjs
- e2e-collect-cli-real.mjs
- e2e-link-real.mjs
- e2e-moc-real.mjs
- e2e-summarize-real.mjs
- security-scan.mjs
- smoke-server.mjs
- smoke-tools.mjs
- verify-classify.mjs
- verify-collect.mjs
- verify-fix.mjs
- verify-link.mjs
- verify-lint.mjs
- verify-runlog.mjs
- verify-summarize.mjs
- verify-vaults.mjs
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- - SKILL.md
- note.md
.env.example
.gitignore
.mcp.json
AGENTS.md
CHECKPOINT.md
DEVELOPMENT.md
GEMINI.md
GUIDE.en.pdf
GUIDE.ko.pdf
LICENSE
NOTICE
package-lock.json
package.json
README.en.html
README.en.md
README.en.pdf
README.html
README.md
README.pdf

# Installation Guide

1. Get the code

git clone https://github.com/sodam-ai/SoDam-WikiMate

Downloads the entire project code from GitHub to your computer.

cd SoDam-WikiMate

Moves into the project folder you just downloaded.

2. Node.js

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

> npm install # 검증용 도구 설치(@modelcontextprotocol/sdk)

Downloads and installs the libraries listed in package.json.

> npm start # MCP 서버를 직접 실행 (보통은 안 해도 됨)

Starts the development/run server.

> npm run verify # 핵심 로직 전부 자동 검증(191개 체크)

Type this command into your terminal and run it.

npm install # 검증용 도구 설치(@modelcontextprotocol/sdk)

Downloads and installs the libraries listed in package.json.

npm run verify # 핵심 로직 전부 자동 검증(191개 체크)

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Wikimate (위키메이트)

AI 에이전트에게 **"정리해줘"** 라고 말하면, 흩어진 자료(웹 링크·PDF·대화 로그·텍스트)를 **내 옵시디언 볼트에 노트로 정리**하고, 관련 있는 노트끼리 **연결**하고, **분류**하고, **요약**까지 해 주고, 원하면 **노션에 색인**해주는 **Claude Code 플러그인**이에요. (Codex엔 "플러그인 설치(`/plugin`)"가 없어서, 대신 저장소를 받아 `codex mcp add`로 **MCP 서버로 등록**해 연동해요.)

**[English version (영문판)](./README.en.md)** · **HTML로 보기: [README.html](./README.html)**

> 📱 **기기 안내**: Wikimate는 **윈도우 PC(데스크톱·노트북) 전용**이에요. **스마트폰·태블릿에는 설치되지 않아요.** (말로 명령하는 AI 프로그램인 Claude Code·Codex 자체가 PC용 프로그램이기 때문이에요.)

> ✅ **현재 상태 (2026-08-21 기준, 정직하게)**: 현재 버전 **v0.9.0**. MCP 도구 **8개** 전부 `main` 브랜치에 병합·GitHub에 푸시 완료. 자동 테스트 **191개 전부 통과**(`npm run verify`), 실제 서버 프로토콜 검증, 실제 옵시디언 볼트로 직접 실행해 본 검증(E2E)까지 완료. **`main`에 push할 때마다 GitHub 서버가 자동으로 같은 검증 + 보안 스캔을 한 번 더 돌려요**(GitHub Actions). 세션 시작 자동 감지(hook)와 옵시디언 그래프뷰 반영은 **실제 사용자 환경에서 화면으로 직접 확인 완료**됐어요(스크린샷 근거). 자세한 항목별 상태는 [17. 현재 상태 정리](#17-현재-상태-정리-정직하게)를 보세요.

이 문서는 **AI·컴퓨터·모바일기기·전자기기를 처음 다뤄보는 분도** 위에서부터 순서대로 그대로 따라 하면 되도록 만들었어요. 어려운 말은 전부 풀어 썼습니다.

---

## 목차

1. [Wikimate가 뭐예요? (1분 이해)](#1-wikimate가-뭐예요-1분-이해)
2. [30초 용어 사전](#2-30초-용어-사전-왕초보-필수)
3. [사전 준비물](#3-사전-준비물)
4. [필요 프로그램 다운로드 방법](#4-필요-프로그램-다운로드-방법)
5. [Wikimate 다운로드 방법](#5-wikimate-다운로드-방법)
6. [설치 방법](#6-설치-방법)
7. [실행 방법](#7-실행-방법)
8. [빠른 시작 (3분 따라 하기)](#8-빠른-시작-3분-따라-하기)
9. [작동 방법 (안에서 무슨 일이 일어나나요?)](#9-작동-방법-안에서-무슨-일이-일어나나요)
10. [사용 방법 (7가지 기능)](#10-사용-방법-7가지-기능)
11. [워크플로우 (전체 흐름 한눈에)](#11-워크플로우-전체-흐름-한눈에)
12. [명령어 모음](#12-명령어-모음)
13. [업데이트 내용 요약](#13-업데이트-내용-요약)
14. [파일·문서 위치 (폴더 구조)](#14-파일문서-위치-폴더-구조)
15. [아키텍처](#15-아키텍처)
16. [보안·데이터 흐름](#16-보안데이터-흐름)
17. [현재 상태 정리 (정직하게)](#17-현재-상태-정리-정직하게)
18. [문제·오류 대처 방법](#18-문제오류-대처-방법)
19. [FAQ (자주 묻는 질문)](#19-faq-자주-묻는-질문)
20. [라이선스·저작권·상업적 이용](#20-라이선스저작권상업적-이용-꼭-읽어주세요)
21. [한눈 요약 (치트시트)](#21-한눈-요약-치트시트)

---

## 1. Wikimate가 뭐예요? (1분 이해)

흩어진 자료를 정리해 주는 **AI 비서**예요.

비유로 설명하면 — 책상 위에 영수증·메모·링크가 잔뜩 쌓여 있을 때 "이것 좀 정리해줘"라고 말하면, **알아서 폴더에 분류해 노트로 정리**해 주고, **관련 있는 노트끼리 실을 이어**주고, **비슷한 주제끼리 목차까지 만들어** 주고, **긴 노트는 한 줄로 요약**까지 해 주는 비서라고 보면 돼요. 메신저(카카오톡 같은 채팅)로 비서에게 부탁하듯, **그냥 한국어로 말로 시키면** 됩니다.

- 정리한 결과는 **옵시디언(Obsidian)** 이라는 메모 앱에 노트로 쌓여요. (내 컴퓨터 안에만 보관 = 외부로 안 나감)
- 원하면 **노션(Notion)** 표에도 목록으로 적어줘요. (선택 기능)
- 관련된 노트끼리는 **자동으로 실을 이어**주고(자동 링크), 비슷한 주제는 **목차 노트(MOC)** 로 묶어줘요.
- 아직 폴더·태그가 안 정해진 노트는 **어디에 둘지·무슨 태그를 붙일지** 판단해서 제안해줘요.
- 너무 긴 노트는 **한 줄 요약**을 붙여주거나, 핵심만 뽑은 **원자 노트**를 별도로 만들어줘요(원본은 절대 안 건드림).
- **함부로 지우거나 바꾸지 않아요.** 항상 "이렇게 할게요" 먼저 보고하고, 내가 "응" 해야 실행해요.

> 한 줄 요약: **"이거 정리해줘"라고 말하면, 내 메모 앱에 깔끔한 노트로 정리하고, 서로 연결하고, 분류하고, 요약까지 해 주는 도구.**

---

## 2. 30초 용어 사전 (왕초보 필수)

처음 보는 낱말이 나와도 당황하지 마세요. 자주 쓰는 말만 쉬운 비유로 풀었어요.

| 낱말 | 쉬운 뜻 (비유) |
|---|---|
| **AI 에이전트** | 사람 말을 알아듣고 대신 일해 주는 똑똑한 프로그램 (= 비서) |
| **Claude Code (클로드 코드)** | 내 컴퓨터에서 AI에게 **말로 일을 시키는 프로그램** (채팅창처럼 생김) |
| **Codex (코덱스)** | Claude Code와 비슷한 **다른 AI 도구** (둘 중 하나만 있으면 됨) |
| **플러그인 (plugin)** | 프로그램에 **새 기능을 끼워 넣는 부품** (스마트폰에 앱 하나 더 까는 것과 비슷) |
| **마켓플레이스 (marketplace)** | 플러그인을 받아오는 **앱 장터** (앱스토어 같은 것) |
| **MCP** | AI와 도구를 이어 주는 **표준 통로(콘센트)**. Wikimate는 이 통로를 통해 일해요. |
| **MCP 도구** | 그 통로로 AI가 누를 수 있는 **기능 버튼** (Wikimate엔 8개, [12번](#12-명령어-모음) 참고) |
| **슬래시 명령 `/wikimate`** | "정리해줘"가 가끔 안 들을 때 **확실하게 시키는 직접 명령** (100% 발동) |
| **옵시디언 (Obsidian)** | 내 컴퓨터에 메모를 쌓는 **노트 앱** (정리 결과가 여기 저장돼요) |
| **볼트 (Vault, 보관함)** | 옵시디언에서 노트를 모아 두는 **노트 보관 폴더**. 만들 때 **이름**을 붙여요. |
| **노션 (Notion)** | 표·문서를 정리하는 앱 (선택 — 목록표를 원할 때만) |
| **터미널 / cmd / CLI** | 글자로 명령을 입력하는 **검은 창** (윈도우 기본 제공) |
| **Node.js (노드)** | Wikimate가 돌아가게 해 주는 **무료 엔진(받침대)** — 한 번만 깔면 됨 |
| **Git (깃)** | 인터넷에 있는 폴더를 통째로 **내려받는 도구** (고급/선택) |
| **dry-run (드라이런)** | **실제로 하기 전에 "계획만" 미리 보여주기** (= 미리보기) |
| **frontmatter (프런트매터)** | 노트 맨 위에 붙는 **작은 정보표** (제목·태그·날짜 등) |
| **source_hash** | 같은 자료인지 알아보는 **지문** (중복 방지용, 자동) |
| **99_Archive (보관함)** | 노트를 **지우지 않고 옮겨 두는** 폴더 (되돌리기 쉬움) |
| **related (관련 노트)** | 노트 정보표에 적히는 "이 노트랑 관련 있는 다른 노트들" 목록. 최대 5개. |
| **MOC (Map of Content, 목차 노트)** | 같은 주제 노트들을 한 곳에 모아 놓은 목차용 노트 |
| **원자 노트 (Atomic note)** | 긴 노트에서 핵심만 뽑아 새로 만든 짧은 노트(원본은 그대로 둠) |
| **SessionStart hook (세션시작 훅)** | Claude Code를 **켤 때 자동으로 한 번 실행**되는 안내 스크립트 |
| **서브에이전트 (subagent)** | 메인 AI와 **따로 떨어져** 특정 임무 하나만 수행하는 보조 AI (검수 등) |
| **프롬프트 인젝션** | 외부 글 속에 숨겨진 "이전 지시 무시하고 ~해라" 같은 함정 문장. Wikimate는 이걸 명령이 아니라 데이터로만 취급해서 막아요. |

> 💡 다 외울 필요 없어요. 모르는 말이 나오면 이 표로 다시 오면 됩니다.

---

## 3. 사전 준비물

| 준비물 | 꼭 필요? | 설명 |
|---|---|---|
| **컴퓨터 (Windows)** | ✅ 필수 | 이 문서는 Windows 11 기준이에요. (스마트폰·태블릿 불가) |
| **Node.js 18 이상** | ✅ 필수 | Wikimate가 돌아가는 데 필요한 무료 프로그램. ([4번](#4-필요-프로그램-다운로드-방법)에서 설치) |
| **Claude Code** 또는 **Codex** | ✅ 필수 | "정리해줘"라고 명령할 AI 도구. **둘 중 하나만** 있으면 돼요. |
| **옵시디언(Obsidian)** | 🔶 선택 | 정리된 노트를 눈으로 보고 싶으면 설치. 없어도 파일은 만들어져요(파일시스템 폴백). |
| **노션(Notion)** | 🔶 선택 | 표로 목록을 보고 싶을 때만. 없어도 됩니다. |
| **Git** | 🔶 선택 | Codex로 쓰거나 개발자처럼 직접 받을 때만 필요해요. |

> 💡 **꼭 필요한 건 딱 3개**: Windows 컴퓨터 + Node.js + (Claude Code 또는 Codex). 나머지는 선택이에요.

---

## 4. 필요 프로그램 다운로드 방법

### ① Node.js (필수)
1. 인터넷 주소창에 **nodejs.org** 입력 → 접속.
2. **LTS** 라고 적힌 큰 초록색 버튼을 눌러 내려받기. (LTS = "오래 안정적으로 쓰는 버전")
3. 내려받은 파일을 더블클릭 → "다음(Next)"만 계속 눌러 설치.
4. 확인: 키보드 `Win 키` → "cmd" 입력 → 검은 창에서 `node -v` 입력 → `v18.x` 이상 숫자가 나오면 성공.

### ② Claude Code (필수, 둘 중 하나)
- **claude.com/claude-code** 접속 → 안내대로 설치. (AI에게 말로 명령하는 프로그램)

### ② Codex (대안)
- Codex CLI를 쓰는 분은 Claude Code 대신 이걸로도 돼요. ([6번](#6-설치-방법)에서 설명)

### ③ 옵시디언 (선택)
- **obsidian.md** 접속 → 다운로드 → 설치. 처음 켜면 "보관함(Vault)"을 하나 만들어요. 이 **보관함 이름**을 기억해 두세요(나중에 씁니다).

### ④ notesmd-cli (선택, 고급)
- 옵시디언을 켜지 않고도 노트를 만들고 싶을 때만. 설치는 Scoop으로: `scoop install notesmd-cli`

---

## 5. Wikimate 다운로드 방법

두 가지 방법이 있어요. **대부분은 (A)면 충분**합니다.

### (A) 마켓플레이스로 설치 — 권장 (다운로드가 자동)
Claude Code 안에서 명령어 두 줄만 입력하면 GitHub에서 **자동으로 내려받아 설치**돼요. ([6번](#6-설치-방법) 참고) 따로 파일을 받을 필요가 없어요. 마켓플레이스는 저장소의 **최신 `main` 브랜치를 그대로 받아오므로**, 이 문서에 적힌 **도구 8개 전부**가 설치돼요.

### (B) 폴더로 직접 받기 — Codex용·개발용
GitHub에서 통째로 받는 방법이에요. **Codex로 쓸 때는 이 방법이 필수**입니다(Codex엔 마켓플레이스가 없어서요).
```
git clone https://github.com/sodam-ai/SoDam-WikiMate.git
```

---

## 6. 설치 방법

### Claude Code
> ⚠️ 아래 **두 명령을 한 줄씩 따로** 입력하세요. (한꺼번에 붙여넣으면 URL이 깨져 실패해요.)

**1단계 — 마켓플레이스 추가** (입력 후 Enter, "added" 확인):
```
/plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git
```
**2단계 — 플러그인 설치** (1단계가 끝난 뒤):
```
/plugin install wikimate@wikimate-marketplace
```
**3단계 — Claude Code를 완전히 껐다가 다시 켜기**(재시작). 끝!

설치 확인: `/mcp` 입력 → 아래 **8개**가 모두 보이면 성공이에요.
`wikimate_collect` · `wikimate_lint` · `wikimate_fix` · `wikimate_runlog` · `wikimate_vaults` · `wikimate_link` · `wikimate_classify` · `wikimate_summarize`

> ℹ️ 이 저장소는 현재 **`v0.9.0`**(2026-08-20 릴리즈)로 버전이 맞춰져 있고, `main` 브랜치 코드에 도구 8개가 전부 포함돼 있어요. 위 방법으로 설치하면 이 문서에 적힌 전체 기능을 그대로 받게 됩니다.

### Codex

Codex에는 마켓플레이스(`/plugin`)가 **없어요.** 대신 받은 폴더를 **MCP 서버로 등록**합니다.

**1단계 — 받기** ([5번](#5-wikimate-다운로드-방법)의 (B) 방법)
```
git clone https://github.com/sodam-ai/SoDam-WikiMate.git
```
**2단계 — 등록** (볼트·폴더 경로는 본인 것으로 바꾸세요):
```
codex mcp add wikimate --env OBSIDIAN_VAULT_PATH=D:/내/볼트/경로 -- node D:/받은/경로/SoDam-WikiMate/mcp/server.mjs
```
**3단계 — 확인**: `codex mcp list` 에 `wikimate`가 보이면 성공.

**4단계 — (선택) 자연어 규칙**: 받은 폴더의 `AGENTS.md`를 Codex 작업 폴더에 두면 "정리해줘" 같은 말도 알아들어요.

**업데이트**: 받은 폴더에서 `git pull` 하면 끝(Claude Code 같은 캐시 함정 없음).

> ⚠️ **Codex는 "축소판"이에요.** MCP 도구 8개는 모두 호출할 수 있지만, *자동 발동(스킬)·찾기·건강검진 종합* 같은 똑똑한 기능은 **Claude Code 전용**이에요(스킬은 자연어 자동발동 계층이라 Codex엔 없음). 그리고 **정직한 고지**: 저장소의 `AGENTS.md`(Codex용 자연어 규칙 파일)엔 이제 정리(collect)·찾기(query)·건강검진(lint/fix)·**자동 링크·자동 분류·자동 요약(link/classify/summarize)까지 6개 자연어 흐름이 전부 문서화**돼 있어요(2026-08-17 보강). 단 **실제 `codex exec`로 이 문서가 자연어 자동 트리거를 정말 발동시키는지는 아직 라이브 검증 전**이에요 — MCP 도구 이름을 **직접 지정해서** 호출하면 6개 전부 정상 동작함은 검증됐습니다(2026-08-04 서버 프로토콜 경유 직접 호출). 노션 색인도 Codex에 **별도 노션 MCP**가 연결돼 있어야 해요. 자세히: [`adapters/codex/SETUP.md`](./adapters/codex/SETUP.md)

> ⚠️ **Gemini CLI 어댑터(2026-08-20 추가, 아직 라이브 미검증)**: `GEMINI.md`(→ `AGENTS.md`를 가리킴) + `adapters/gemini/SETUP.md`로 등록해요. `gemini mcp add/list/remove` 명령 문법은 실제로 실행해 확인했지만, **Gemini CLI가 실제로 wikimate 도구를 호출하는지·자연어 트리거가 동작하는지는 아직 확인 전**이에요(Gemini API 실호출이 필요해 사용자 승인 없이 진행하지 않음, Codex와 동일 원칙). 자세히: [`adapters/gemini/SETUP.md`](./adapters/gemini/SETUP.md)

### 업데이트가 안 될 때 — 가장 흔한 함정 (Claude Code)
GitHub에 새 버전이 올라가도, 내 PC의 **마켓플레이스 캐시는 자동으로 안 바뀌어요.** 그래서 재설치만으론 옛날 버전이 그대로일 수 있어요. 최신으로 갱신하려면:
```
/plugin marketplace update wikimate-marketplace
/plugin install wikimate@wikimate-marketplace
```
그래도 안 되면 `/plugin` 메뉴에서 마켓플레이스를 **remove → 다시 add → 설치** (캐시를 통째로 새로 받아요).

> 💡 **"GitHub에 푸시해야 하나요?" → 아니요.** 설치·업데이트는 GitHub에서 *받아오는* 것이라, 내가 따로 올릴(push) 필요가 없어요. (푸시는 개발자가 코드를 바꿀 때만)
> ⚠️ **설치 중 `EBUSY: resource busy or locked` 가 뜨면** → Windows 백신(Defender)이 갓 쓰인 파일을 잠깐 잠근 거예요. **Claude Code를 완전히 종료했다 다시 켠 뒤** 위 명령을 다시 실행하면 대개 풀립니다.

---

## 7. 실행 방법

**가장 중요한 안내: Wikimate는 따로 "실행(켜기)"할 게 없어요.** 게임이나 앱처럼 아이콘을 더블클릭해 켜는 프로그램이 아니에요.

- [6번](#6-설치-방법)대로 **설치만 하면**, Claude Code를 켤 때마다 Wikimate가 **자동으로 같이 켜져요.** (설치 시 `.mcp.json`이 MCP 서버를 자동 등록하기 때문)
- Claude Code를 켤 때 **"[Wikimate] 세션 시작 자동 감지: ..."** 라는 안내 메시지가 자동으로 한 번 떠요(옵시디언 CLI·등록된 보관함을 미리 찾아 알려주는 것, 읽기 전용). **이 동작은 실제 재시작 화면으로 확인됐어요.**
- 그래서 "실행"은 곧 **Claude Code를 켜고 → 대화창에 말로 시키는 것**이 전부예요.
- 잘 켜졌는지 보고 싶으면 `/mcp` 를 입력 → 위 8개 도구가 보이면 준비 완료.

> 🛠️ **(고급/개발자만)** 서버를 따로 직접 돌려 보고 싶다면, 받은 폴더에서 터미널로:
> ```
> npm install     # 검증용 도구 설치(@modelcontextprotocol/sdk)
> npm start       # MCP 서버를 직접 실행 (보통은 안 해도 됨)
> npm run verify  # 핵심 로직 전부 자동 검증(191개 체크)
> ```

---

## 8. 빠른 시작 (3분 따라 하기)

1. 위 [6번](#6-설치-방법)대로 설치하고 Claude Code를 재시작해요.
2. 대화창에 그냥 이렇게 말해요:
   > **이 링크 정리해줘: https://example.com**
3. Wikimate가 **"이런 노트를 여기에 만들게요"** 하고 **계획을 먼저 보여줘요.** (dry-run = 미리보기)
4. 마음에 들면 **[진행]** 을 골라요(숫자/클릭 — 타자 안 쳐도 돼요).
5. 노트가 만들어집니다. 끝!

> 💡 **보관함 이름은 안 말해도 돼요** — Wikimate가 옵시디언에 등록된 보관함을 **자동으로 찾아 "여기에 정리할까요?"** 하고 제안해줘요(`wikimate_vaults`). 물론 *"내 'Vault' 보관함에"* 처럼 콕 집어 말해도 됩니다.

> ⭐ **가장 확실한 방법** — 그냥 "정리해줘"라고만 하면 AI가 가끔 **그냥 요약만** 하고 노트를 안 만들 때가 있어요(자연어 자동 발동은 AI 판단이라 들쭉날쭉). 그럴 땐 **슬래시 명령**으로 콕 찍어 시키면 **100% 작동**해요:
> ```
> /wikimate https://example.com
> ```

> **자동 링크·자동 분류·자동 요약도 3분 체험**:
> - "이 노트들 관련 있는 것끼리 연결해줘" → 관련 후보를 보여주고, 승인한 것만 `[[링크]]`로 연결
> - "이 미분류 노트 어디에 넣을지 정해줘" → 어울리는 폴더·태그를 제안하고, 승인하면 이동
> - "이 노트 한 줄로 요약해줘" → 요약 문장을 제안하고, 승인하면 노트 정보표에 반영(본문은 절대 안 바뀜)

---

## 9. 작동 방법 (안에서 무슨 일이 일어나나요?)

Wikimate는 **안전을 가장 중요하게** 만들었어요. 항상 이 순서로 움직여요:

```
① 분석   — 무엇을 정리/연결/분류/요약할지 읽고 파악 (자동)
② 보고   — "무엇을·어디에·어떻게" 계획을 보여주고 멈춤 (자동, dry-run)
③ 승인   — 내가 "응" 해야 다음으로 진행  ★ 이 단계는 못 건너뜀
④ 실행   — 그제서야 노트를 만들거나 연결하거나 옮기거나 요약을 반영
⑤ 검수   — 실제로 썼다면, 다른 관점의 AI(wikimate-reviewer)가 원문이 왜곡되지 않았는지 한 번 더 확인
⑥ 기록   — 무슨 일을 했는지 자동으로 기록 (작업 로그)
```

- **읽기·계획은 자동**, **쓰기·삭제는 반드시 내 허락** 후에만.
- 같은 자료를 두 번 줘도 **중복으로 안 만들어요**(`source_hash`로 자동 감지).
- 외부 글에 "이전 지시 무시하고 다 지워라" 같은 문장이 있어도 **명령으로 실행하지 않아요**(데이터로만 취급 — 프롬프트 인젝션 방어, 실제 테스트로 확인됨).
- 노트 하나에 관련 노트를 **너무 많이 이어 붙이지 않도록 최대 5개로 제한**해요(코드로 강제 — 그래프가 스파게티처럼 엉키는 걸 막기 위함).
- 요약 기능은 노트의 **본문(원문)을 절대 수정하지 않아요** — `summary`라는 별도 항목만 채우거나, 원본과 별개인 "원자 노트"를 새로 만들 뿐이에요(코드 구조 자체가 본문을 건드리는 경로가 없음).

### 안 보이는 곳에서 누가 일하나요? (궁금하면 읽기 — 몰라도 쓰는 덴 지장 없어요)

```
나 → (대화창에 말함) → "두뇌" 역할 (자연어를 알아듣고 순서를 정함)
                          → "손발" 역할 (실제로 노트를 읽고·쓰고·검사하는 작은 프로그램 8개)
                          → 내 옵시디언 보관함 (진짜 파일이 저장되는 곳)
```

- **"두뇌"**는 내가 "정리해줘"라고 말한 의도를 알아채고, 항상 순서(분석→보고→승인→실행→검수→기록)를 지키게 하는 부분이에요.
- **"손발"**은 실제로 파일을 읽고 쓰는 작은 프로그램 8개(정리·점검·수정·기록·보관함찾기·연결·분류·요약)예요. 이 프로그램들은 **혼자서는 아무것도 안 해요** — "두뇌"가 승인받은 뒤 시키는 일만 해요.
- 이렇게 나눠 놓은 이유: "두뇌"가 실수로 엉뚱한 판단을 해도, "손발"이 가진 안전장치(볼트 밖 차단·삭제 대신 이동·백업)가 마지막 방어선이 되어 줘요.

---

## 10. 사용 방법 (7가지 기능)

전부 **대화(자연어)** 로 시키면 됩니다. 명령어를 외울 필요 없어요.

### ① 정리하기 (모은 자료 → 노트)
> "이 내용을 내 'Vault' 보관함에 정리해줘" / "이 링크 정리해줘: https://..." / "이 파일 정리해줘: D:\메모\오늘.md"

→ 계획 보고 후 승인하면 노트 생성. (도구: `wikimate_collect` + 어디에 정리할지 보관함을 찾아 제안하는 `wikimate_vaults`) 정리할 "자료"는 무엇이든 돼요 — 한 문장 텍스트, 웹 링크, 파일 경로 모두 OK.

> ⭐ **자연어 "정리해줘"가 가끔 안 들으면**(노트는 안 만들고 채팅에 요약만 하면) **`/wikimate <링크/텍스트>` 슬래시 명령**을 쓰세요 — 이건 직접 명령이라 100% 발동해요.

> 🧾 **원문이 잘 보존됐는지 알림** — 정리 계획(dry-run) 화면에 "웹주소는 있는데 내용이 너무 짧아요" 또는 "내용이 커요" 같은 알림이 뜰 수 있어요. 이건 막는 게 아니라 **미리 알려주는 것**이에요.

### ② 찾기 (정리해 둔 노트에서 묻기 — 읽기 전용)
> "내 볼트에서 RAG 찾아서 요약해줘" / "내 노트들로 임베딩·벡터DB 관계 정리해줘"

→ **원본이 진짜 있는지 확인하고** 출처와 함께 답해요. 없는 걸 있다고 하지 않아요. (스킬: `wikimate-query`)

### ③ 건강검진 (볼트 정리 상태 점검·청소)
> "내 볼트 건강검진해줘" / "고아 노트·깨진 링크·중복 찾아줘"

→ **중복·깨진 `[[링크]]`·외톨이(고아) 노트·머리말(frontmatter) 누락**을 찾아 **보고만** 해요. 고칠 항목은 골라서 승인하면, **삭제가 아니라 보관함(99_Archive)으로 이동**하거나 **고치기 전 자동 백업** 후 손봐요. (도구: `wikimate_lint`, `wikimate_fix` / 스킬: `wikimate-lint`)

### ④ 작업 기록 보기 (AI가 뭘 했는지)
> "최근 작업 보여줘"

→ Wikimate가 내 볼트에서 한 일(생성·이동·수정)을 최근 순으로 보여줘요. (도구: `wikimate_runlog`)

### ⑤ 자동 링크·MOC (관련 노트끼리 연결·목차 만들기)
> "이 노트랑 관련 있는 노트들 연결해줘" / "MCP 관련 노트들 목차로 묶어줘"

→ 볼트 전체에서 후보를 찾아 **제목·요약·태그만 보고**(본문 내용은 안전을 위해 안 봄) 관련도를 판단해 제안하고, 승인한 것만 노트 정보표(`related:`)에 `[[링크]]`로 추가해요(한 노트당 최대 5개). "목차로 묶어줘"라고 하면 같은 주제 노트를 모은 **목차 노트(MOC)** 를 `30_Notes` 폴더에 만들거나 갱신해요(기존에 사람이 직접 써 둔 다른 내용은 그대로 보존). (도구: `wikimate_link` / 스킬: `wikimate-link`)

### ⑥ 자동 분류 (폴더·태그·중요도 정하기)
> "이 미분류 노트들 정리해줘" / "이 노트 어디에 넣을지 정해줘"

→ 노트의 현재 폴더·태그·본문 일부와 볼트에서 이미 쓰고 있는 태그 목록을 참고해서 **어느 폴더(00_Inbox/10_Projects/20_Resources/30_Notes/40_Drafts)가 어울리는지, 태그·중요도(1~5)는 뭐가 좋을지** 제안하고, 승인하면 그대로 이동/부여해요. 이미 있는 폴더에 같은 이름 파일이 있으면 **절대 덮어쓰지 않고** 별도로 저장해요. "이 노트 다 봤어, 완료로 표시해줘"처럼 말하면 **진행 상태(inbox/draft/done)·관련 프로젝트 이름**도 바꿔줘요(2026-08-20 추가 — 시켰을 때만 바뀌고, 자동으로 판단해서 바꾸지는 않아요). (도구: `wikimate_classify` / 스킬: `wikimate-classify`)

### ⑦ 요약·원자 노트 (긴 노트 짧게 정리)
> "이 노트 한 줄로 요약해줘" / "이 노트 핵심만 뽑아서 새 노트로 만들어줘"

→ 노트 본문을 읽고 **한 줄 요약**(최대 200자)을 제안하거나, 핵심만 뽑은 **원자 노트**(새 파일)를 제안해요. 승인하면 반영하는데, **원본 노트의 본문(text)은 절대 수정되지 않아요** — 요약은 별도 `summary` 항목에만 채워지고, 원자 노트는 원본과 링크로만 연결된 완전히 새로운 파일이에요("원문 보존" 원칙, 코드 구조로 강제됨). 실제로 쓴 뒤에는 검수 서브에이전트(`wikimate-reviewer`)가 원문 왜곡 여부를 한 번 더 확인해요. (도구: `wikimate_summarize` / 스킬: `wikimate-summarize`)

> ℹ️ **정직한 고지**: 요약 기능은 아직 전용 슬래시 명령(`/wikimate-summarize`)이 없어요. 자연어("이 노트 요약해줘")나 Claude Code의 자동 스킬 발동으로만 쓸 수 있어요.

---

## 11. 워크플로우 (전체 흐름 한눈에)

```
설치 → (자동) MCP 등록 → (세션 시작 시 옵시디언·보관함 자동 감지 안내)
   → 자료를 옵시디언 00_Inbox에 넣거나 링크/텍스트 전달
   → 대화로 명령 ("정리해줘" / "연결해줘" / "분류해줘" / "요약해줘")
   → Wikimate가 계획 보고 (dry-run)
   → 내가 [진행] 승인
   → 노트 생성/연결/이동/요약 + (노션 연결 시) 색인 + 작업 로그 기록
   → 실제로 썼다면 검수 서브에이전트(wikimate-reviewer)가 한 번 더 확인
   → 옵시디언/노션에서 확인
   → (가끔) "건강검진해줘"로 청소
```

---

## 12. 명령어 모음

### 대화(자연어) — 가장 쉬움
- 정리: "정리해줘", "이거 노트로", "이 링크 저장해줘"
- 찾기: "내 볼트에서 ~ 찾아줘/요약해줘"
- 점검: "내 볼트 건강검진해줘", "중복 찾아줘"
- 기록: "최근 작업 보여줘"
- 연결: "관련 노트 연결해줘", "이 주제로 목차 만들어줘"
- 분류: "이 노트 분류해줘", "폴더/태그 정해줘"
- 요약: "이 노트 요약해줘", "핵심만 뽑아 새 노트로 만들어줘"

### 슬래시 명령 (Claude Code) — ⭐ 가장 확실한 방법
| 명령 | 기능 |
|---|---|
| `/wikimate <링크/텍스트>` | 자료를 노트로 정리. **자연어 "정리해줘"가 안 들을 때 이걸로 쓰면 100% 발동해요.** |
| `/wikimate-lint` | 볼트 건강검진 |
| `/wikimate-link` | 자동 링크·MOC 생성 |
| `/wikimate-classify` | 자동 분류 |
| `/wikimate-summarize` | 요약·원자노트 만들기 |
| `/mcp` | 설치/연결 상태 확인 (도구 개수가 보이는지) |

### MCP 도구 (안에서 자동 호출됨 — 외울 필요 없음)
`wikimate_collect`(정리) · `wikimate_lint`(점검) · `wikimate_fix`(수정) · `wikimate_runlog`(기록) · `wikimate_vaults`(보관함 찾기) · `wikimate_link`(자동 링크·MOC) · `wikimate_classify`(자동 분류) · `wikimate_summarize`(요약·원자노트)

### 개발·검증용 (터미널, 고급)
```
npm install      # 검증용 도구 설치(@modelcontextprotocol/sdk)
npm run verify   # 핵심 로직 전부 자동 검증(191개 체크)
npm start        # MCP 서버 실행
```

---

## 13. 업데이트 내용 요약

- 🧹 자연어 정리(`wikimate_collect`) — 자료를 노트로 자동 생성
- 🧭 보관함(볼트) 자동탐지(`wikimate_vaults`) — "여기에 정리할까요?" 제안
- 🩺 볼트 건강검진(`wikimate_lint`) — 중복·깨진 링크·고아 노트·머리말 누락 탐지(읽기 전용)
- 🔧 안전 수정(`wikimate_fix`) — 삭제 대신 보관함 이동, 링크 치환(수정 전 자동 백업)
- 🧾 작업 기록(`wikimate_runlog`) — AI가 볼트에서 한 일을 자동 기록
- 🗂️ 노션 색인(선택) — 노션 도구 연결 시 자동 색인 행 추가
- 스킬 3종(organize/query/lint)
- MCP 도구 5개

</details>

- 🔗 **자동 링크**(`wikimate_link`, action=`suggest`/`add_links`) — 관련 있는 노트끼리 `[[링크]]`로 연결. 한 노트당 최대 5개까지만 연결(과잉 연결 방지, 코드로 강제).
- 🗺️ **MOC(주제 목차)**(`wikimate_link`, action=`build_moc`) — 같은 주제의 노트를 모아 "목차 노트" 하나로 정리.
- 🔁 **노션 연결 고리 완성**(`wikimate_link`, action=`set_notion_id`, 2026-08-17 추가) — 노션 색인 행을 실제로 만든 뒤, 그 결과(page ID/URL)를 노트에 되써서 "노션 표 클릭 → 옵시디언 점프"뿐 아니라 "옵시디언 노트에서도 어느 노션 행과 연결됐는지" 양쪽 다 알 수 있게 함.
- 🗂️ **자동 분류**(`wikimate_classify`) — 미분류 노트의 폴더 위치·태그·중요도를 판단해 제안하고, 승인하면 이동/태그 부여.
- 🔔 **세션 시작 자동 감지**(SessionStart hook) — Claude Code를 켤 때 옵시디언 도구·등록된 보관함을 미리 찾아 안내(읽기 전용). **실제 재시작 화면으로 확인 완료.**
- 🕵️ **검수 서브에이전트**(`wikimate-reviewer`) — 실제로 노트를 쓴 뒤, "완료"라고 보고하기 전에 원문 왜곡·인젝션 감염·기존 노트 덮어쓰기 여부를 별도 관점에서 한 번 더 확인.
- 옵시디언 그래프뷰·백링크 반영도 **실제 옵시디언 앱 화면(스크린샷)으로 확인 완료.**
- MCP 도구 5개 → **7개**

</details>

- 📝 **요약·원자 노트**(`wikimate_summarize`, action=`suggest`/`apply`) — 긴 노트에 한 줄 요약(최대 200자)을 채우거나, 핵심만 뽑은 별도 원자 노트를 생성.
- 🛡️ **원문 보존을 코드 구조로 강제** — 이 도구는 노트의 본문(원문)을 수정하는 코드 경로 자체가 없음. `summary` 항목만 surgical하게(다른 필드는 그대로 두고) 바꾸거나, 원본과 분리된 새 파일만 생성.
- 🕵️ 검수 서브에이전트(`wikimate-reviewer`)가 요약 결과도 검사하도록 확장.
- 유닛테스트 20개 + 실제 볼트 E2E 8개 + 전체 회귀 126개 전부 PASS.
- MCP 도구 7개 → **8개**

</details>

<details>
<summary>✅ Phase 3: 보안 자동 점검·CI·Gemini 어댑터·v0.9.0 릴리즈(2026-08-20) (클릭해서 펼치기)</summary>

- 🔒 **배포물 보안 자동 점검**(`scripts/security-scan.mjs`) — API 키·토큰·개인키 형식만 실제로 매칭해 검사(오탐 최소화). 선택적 pre-commit 훅(`.githooks/pre-commit`)으로 커밋 전에도 검사 가능.
- 🤖 **GitHub Actions 자동 검증(CI) 신설** — `main`에 push·PR을 올릴 때마다 GitHub 서버가 사람 개입 없이 `npm run verify`(핵심 로직)·서버 프로토콜 검증·보안 스캔을 자동으로 재실행. 로컬에서 깜빡 잊어도 이중으로 안전.
- 🌐 **Gemini CLI 어댑터 추가** — `GEMINI.md`+`adapters/gemini/SETUP.md`. 등록 명령(`gemini mcp add/list/remove`)까지 실제로 실행해 확인.
- 🧹 **`npm audit` 취약점 5건 → 0건** — 검증용 devDependency의 전이 의존성만 안전하게 패치(실제 서버 코드엔 영향 없음, 코드로 직접 확인).
- 🏷️ **v0.9.0 정식 릴리즈** — GitHub 태그·Release 발행.
- 문서만/설정만 바뀐 항목이 대부분이라 핵심 동작(노트 정리·연결·분류·요약)엔 영향 없음.

</details>

- 🏷️ **분류 기능에 "진행 상태"·"관련 프로젝트" 추가** — "이 노트 다 봤어, 완료로 표시해줘"처럼 말하면 진행 상태(inbox/draft/done)·프로젝트 이름도 함께 바꿔줘요(시켰을 때만, 자동 판단 없음).
- ⚠️ **시크릿처럼 보이는 문자열 감지** — 정리할 자료(웹페이지·대화록 등)에 API 키·비밀번호처럼 보이는 문자열이 있으면, 저장 전 미리보기 화면에서 "이런 게 있어요, 지우고 저장할까요?"라고 미리 알려줘요(강제로 지우진 않음 — 원문 보존 원칙).
- 📇 **노션 작업기록(Run Log)이 모든 기능에서 동작하도록 배선** — 원래 "정리하기" 기능에만 있던 "무슨 작업을 했는지 노션에도 남기기"를, 연결·분류·요약·건강검진(수정) 기능에도 똑같이 연결.
- 🐛 **재검증 중 발견한 실제 결함 3건 수정**: ① 노트 저장 값에 역슬래시(`\`)나 따옴표가 있으면 재조회 시 값이 달라지던 문제, ② 목차(MOC) 노트를 다시 만들면 같은 항목이 계속 중복으로 쌓이던 문제, ③ "링크 바꾸기" 기능이 존재하지 않는 노트 이름으로도 링크를 만들 수 있던 문제. 셋 다 재현→원인분석→수정→재검증 완료, 자동 테스트 180→191개로 늘어남.

</details>

- **분류 기능의 "완료 표시" 자연어 트리거 보강 필요(신규 발견, 2026-08-21)**: "진행상태·프로젝트" 기능 자체는 완성됐지만, 관련 안내 문서에 아직 이 기능이 충분히 반영되지 않아 자연어로 말했을 때 확실하게 안 걸릴 수 있어요. 확실하게 쓰려면 `/wikimate-classify` 슬래시 명령이나 "wikimate_classify로 상태 바꿔줘"처럼 도구 이름을 직접 언급하세요. 다음 업데이트에서 보강 예정.
- **연결 정보에 "왜 연결했는지"·"어떤 종류의 연결인지" 기록 기능은 아직 없음(설계 검토 중)**: 지금은 "관련 있다"는 사실만 저장하고, 그 이유나 관계 종류까지는 저장 못 해요. 저장 방식을 어떻게 바꿀지 방향을 정한 뒤 추가할 예정.
- Codex용 자연어 규칙 파일(`AGENTS.md`)엔 자동 링크·자동 분류·자동 요약의 자연어 트리거 설명이 이미 있음(도구 자체는 Codex에서도 직접 호출하면 정상 동작 확인됨) — **실제 `codex exec`로 자연어 트리거가 정말 발동하는지**는 아직 라이브 검증 전.
- **Gemini CLI 어댑터**도 등록 명령까지는 확인됐지만, 실제 자연어 트리거 라이브 검증은 사용자 확인 대기.
- **마켓플레이스 신규설치 라이브 검증**: 구조·보안 점검은 완료(2026-08-20), 신규 사용자가 처음부터 실제로 설치해보는 확인만 남음.
- **노션 색인 라이브 검증**: 구조·로직·양방향 연결(`notion_id`)·작업기록(Run Log) 전부 코드로는 완성(2026-08-21) — 실제 노션 계정을 연결한 환경에서의 사용자 확인만 남음.
- Python 기반 고급 추출기는 아직 미구현.

</details>

---

## 14. 파일·문서 위치 (폴더 구조)

```
SoDam-WikiMate/
├── .claude-plugin/       플러그인·마켓플레이스 설정
│   ├── plugin.json
│   └── marketplace.json
├── mcp/
│   ├── server.mjs        ★ MCP 서버 (무의존, 순수 Node) — 도구 8개 배선
│   └── lib/
│       ├── shared.mjs     공통 헬퍼(경로 안전검사·백업·frontmatter 파싱)
│       ├── collect.mjs    정리 로직
│       ├── lint.mjs       건강검진(읽기전용)
│       ├── fix.mjs        안전 수정(삭제 없음·백업)
│       ├── runlog.mjs     작업 기록
│       ├── link.mjs       자동 링크·MOC 로직
│       ├── classify.mjs   자동 분류 로직
│       └── summarize.mjs  요약·원자노트 로직
├── skills/               자연어로 자동 발동하는 스킬 (6개)
│   ├── wikimate-organize/
│   ├── wikimate-query/
│   ├── wikimate-lint/
│   ├── wikimate-link/
│   ├── wikimate-classify/
│   └── wikimate-summarize/
├── commands/             /wikimate · /wikimate-lint · /wikimate-link · /wikimate-classify · /wikimate-summarize (5개)
├── hooks/                세션 시작 자동 감지(session-start.mjs, hooks.json)
├── agents/               검수 서브에이전트(wikimate-reviewer.md)
├── adapters/codex/       Codex 설정 안내(SETUP.md)
├── adapters/gemini/      Gemini CLI 설정 안내(SETUP.md)
├── templates/note.md     노트 서식
├── scripts/              검증 스크립트(verify-*·smoke-*·e2e-*, 8개 verify + e2e 6개) + 보안 자동 점검(security-scan.mjs)
├── .github/workflows/    GitHub Actions 자동 검증(ci.yml, push·PR마다 자동 재실행)
├── .githooks/            선택적 pre-commit 보안 훅(git config core.hooksPath로 켜야 함)
├── .mcp.json             설치 시 MCP 자동 등록
├── AGENTS.md             크로스툴(Codex·Gemini) 공통 규칙
├── GEMINI.md             Gemini CLI 컨텍스트 파일(내용은 AGENTS.md를 가리킴)
├── .env.example          환경변수 예시
├── README.md / README.en.md / README.html / README.en.html   이 문서(한/영, md+html) — 왕초보 가이드 내용까지 통합됨
├── CHECKPOINT.md         개발 진행상황 추적(개발자용)
├── LICENSE / NOTICE      라이선스 전문·고지
├── .PRD/                 제품 설계 문서(개발자용)
└── (내 볼트의) .wikimate/runlog.jsonl   작업 기록(숨김) / .wikimate/backups/ 백업(숨김)
```

### 내 옵시디언 보관함(별도) 폴더
```
00_Inbox      아직 정리 안 된 자료 (여기에 넣으면 됨)
10_Projects   진행 중 작업
20_Resources  오래 쌓는 지식
30_Notes      정리된 노트·목차·원자노트(MOC·요약 원자노트 모두 여기)
40_Drafts     초안
90_Templates  서식 (자동분류·자동요약 대상 아님 — 사람이 직접 관리)
99_Archive    보관(건강검진이 중복을 여기로 옮김, 자동분류 대상 아님)
.obsidian/    옵시디언 설정 — ⛔ Wikimate가 절대 건드리지 않음
```

### 환경 변수 (선택 — 볼트 경로 등을 미리 지정)
| 변수 | 용도 |
|---|---|
| `OBSIDIAN_VAULT_PATH` | 볼트 폴더 절대경로 (파일 폴백·중복검사용) |
| `OBSIDIAN_VAULT_NAME` | 옵시디언에 등록된 볼트 이름 (CLI용) |
| `NOTION_RESEARCH_DB_ID` | 노션 색인 DB 지정 (없으면 검색하거나 물어봐요) |
| `NOTION_RUNLOG_DB_ID` | 노션 작업기록 DB 지정 (선택) |

`.env.example`를 복사해 `.env`로 쓰세요. **실제 값(토큰 등)은 절대 git에 올리지 마세요.**

---

## 15. 아키텍처

> 개발자가 아니어도 이해할 수 있게 그림으로 설명해요. 몰라도 사용에는 전혀 지장 없어요.

```
[나] --말로 명령--> [Claude Code / Codex] --MCP 통로--> [Wikimate 서버(mcp/server.mjs)]
                                                              │
                              ┌───────────────┬──────────────┼──────────────┬───────────────┐
                              ▼               ▼              ▼              ▼               ▼
                       [collect.mjs]   [link.mjs]     [classify.mjs]  [summarize.mjs]  [lint/fix.mjs]
                       자료→노트 생성  관련노트연결·MOC   폴더·태그 판단   요약·원자노트     건강검진·수정
                              │               │              │              │               │
                              └───────┬───────┴──────┬───────┴──────┬───────┴───────┬───────┘
                                      ▼               ▼              ▼               ▼
                          [내 옵시디언 볼트(진짜 파일)]      [.wikimate/runlog.jsonl]
                                      │                        (작업 기록, 숨김)
                                      ▼
                          [(선택) 노션 색인 행 추가]
```

- **핵심 설계 원칙**: "관련 있는지·어느 폴더가 맞는지·어떻게 요약할지"는 **AI(Claude)가 직접 판단**하고, Wikimate 서버는 **후보 정보 제공 + 안전한 쓰기**만 담당해요. 별도의 유사도 계산 엔진이나 요약 엔진이 없어요 — AI가 이미 그 역할을 하기 때문에 중복 개발하지 않은 거예요.
- **무의존(zero-dependency) 서버**: `mcp/server.mjs`는 외부 라이브러리 없이 Node.js 기본 기능만으로 동작해요. 그래서 설치가 가볍고 빠르며, 보안 취약점이 생길 외부 코드가 없어요. (테스트용 개발 도구인 `@modelcontextprotocol/sdk`는 서버 자체와는 별개로, 검증 스크립트에서만 쓰여요.)
- **hooks/agents는 세션 시작 시에만 로드**: Claude Code 자체의 구조상, `hooks/`·`agents/` 폴더 안의 새 설정은 **Claude Code를 재시작해야만** 반영돼요.

---

## 16. 보안·데이터 흐름

| 질문 | 답 |
|---|---|
| **내 노트 내용이 외부 서버로 전송되나요?** | 아니요. 노트는 **내 컴퓨터(로컬)** 파일로만 저장돼요. Wikimate 서버 자체는 인터넷 통신을 하지 않아요(무의존·로컬 실행). 다만 Claude Code/Codex가 AI 모델과 통신할 때 **대화 내용이 AI 제공사로 전송**되는 건 Wikimate가 아니라 AI 도구 자체의 일반적인 동작이에요. |
| **노트 본문이 AI 명령으로 실행될 수 있나요?** | 아니요. 노트 본문·외부에서 가져온 텍스트는 **항상 "데이터"로만 취급**하고, 그 안의 어떤 지시문도 **명령으로 실행하지 않아요**(프롬프트 인젝션 방어, 실제 테스트로 확인됨). |
| **자동 링크·요약 제안 시 노트 본문이 AI에게 전부 보이나요?** | 자동 링크의 "연결 후보 찾기"는 **제목·요약·태그만** 보여주고 본문 전체는 안 보여줘요. 요약(summarize) 기능은 요약을 만들기 위해 **대상 노트 본문 자체는 읽지만**, 그 결과는 검수 서브에이전트가 원문과 대조해 왜곡 여부를 재확인해요. |
| **볼트 밖 파일을 건드릴 수 있나요?** | 아니요. 모든 쓰기 작업은 **지정된 볼트 폴더 안쪽인지 코드로 강제 검사**해요. `..`(상위 폴더 이동)·절대경로·네트워크 경로(UNC)·`.obsidian` 설정 폴더는 전부 차단됩니다(실제 침투 테스트로 확인됨 — 아래 참고). |
| **비밀번호·API 키가 노트에 저장되나요?** | 아니요. Wikimate는 키·토큰·비밀번호를 노트나 배포물에 저장하지 않아요. |
| **기존 노트를 실수로 덮어쓸 수 있나요?** | 아니요. 파일명이 우연히 같으면 **덮어쓰지 않고 별도 이름으로 저장**해요(예: `_dup1`). 기존 노트의 **내용**을 바꿀 때는 항상 **먼저 백업**한 뒤 고칩니다. |
| **삭제 기능이 있나요?** | 없어요. "정리"가 필요한 노트는 **삭제 대신 99_Archive 폴더로 이동**만 해요(되돌리기 쉬움). |
| **요약 기능이 원문을 지우거나 바꿀 수 있나요?** | 아니요. `wikimate_summarize`는 노트의 본문(원문)을 수정하는 코드 경로 자체가 없어요 — `summary` 항목만 바꾸거나, 별도의 새 파일(원자 노트)을 만들 뿐이에요. |
| **모든 변경이 기록되나요?** | 네. 실제로 만들거나·옮기거나·고친 모든 작업이 `.wikimate/runlog.jsonl`(숨김 파일)에 한 줄씩 자동 기록돼요. |

> 🔍 **경로 탈출(path traversal) 방어 실측 사례**: 개발 중 노트 제목을 `"../../WIKIMATE_PWNED"`처럼 지정해 볼트 밖으로 파일을 빼돌리려는 공격을 실제로 시도해 봤어요. 결과: 위험한 문자가 안전하게 정리되어 볼트 **안쪽**에만 파일이 생성됐고, 볼트 밖으로는 전혀 새어나가지 않았어요. 이 테스트 파일(`sandbox-vault/. WIKIMATE_PWNED.md`)은 방어가 실제로 작동한다는 증거로 저장소에 남겨 두었어요.

---

## 17. 현재 상태 정리 (정직하게)

| 항목 | 상태 | 근거 |
|---|---|---|
| 옵시디언 정리(collect) | ✅ 완료 | 실제 볼트에 노트 생성 확인(자연어 자동 발동 포함) |
| 건강검진·안전수정·작업로그(lint/fix/runlog) | ✅ 완료 | 단위테스트 + 서버 프로토콜 e2e로 검증 |
| 자동 링크·MOC·자동 분류(link/classify) | ✅ 완료 | 자동 테스트 통과, 실제 볼트 픽스처 E2E 검증, main 병합·푸시 완료 |
| 요약·원자 노트(summarize) | ✅ 완료 | 유닛 20개+e2e 8개+전체 회귀 126개 PASS, main 병합·푸시 완료 |
| 세션 시작 자동 감지(hook) | ✅ 완료 | **실제 Claude Code 재시작 화면**으로 메시지 노출 확인됨 |
| 옵시디언 그래프뷰·백링크 반영 | ✅ 완료 | **실제 옵시디언 앱 그래프뷰 화면(스크린샷)**으로 확인됨 |
| MCP 서버 프로토콜(8개 도구 전부) | ✅ 완료 | 실제 JSON-RPC 서버 경유 직접 호출로 검증(2026-08-04) |
| 검수 서브에이전트(wikimate-reviewer) | ✅ 완료(구조) | collect/link/classify/summarize 전부 검수 대상으로 명시됨 |
| Codex — MCP 도구 자체 | ✅ 동작 확인 | 서버 프로토콜 경유로 8개 도구 전부 정상 응답 확인(2026-08-04) |
| Codex — 자연어 자동 트리거(link/classify/summarize) | 🟡 문서 완료, 라이브 검증 전 | `AGENTS.md`에 2026-08-17 문서 보강 완료. 실제 `codex exec`로 자연어가 이 3개 도구를 자동 발동시키는지는 아직 미실행(사용자 승인 대기) |
| 노션 색인 | 🟡 코드 완성, 라이브 미검증 | 노션 행 생성(스킬)·`notion_id` 양방향 되쓰기(`wikimate_link` set_notion_id)·**노션 Run Log 기록(2026-08-19~21, 6개 스킬 전부 배선 완료)**까지 구조·스킬 지시 완료. 실제 노션 계정 연결 환경에서의 사용자 확인은 아직 |
| 마켓플레이스 정식 등록 | 🟡 구조·보안검증 완료, 라이브 검증 전 | `plugin.json`·`marketplace.json` 정상 구조 확인됨(현재 v0.9.0), Phase 3 전제조건(배포물 보안 자동 점검, `scripts/security-scan.mjs` + GitHub Actions CI) 충족(2026-08-20). 신규 사용자의 실제 설치 라이브 검증은 사용자 확인 대기 |
| Python 고급 추출기 | 🔴 미구현 | 계획만 있음, 코드 없음 |
| Gemini 어댑터 | 🟡 코드 완료, 라이브 검증 전 | 등록 명령(`gemini mcp add/list/remove`) 실측 확인(2026-08-20, Gemini CLI 0.52.0). 자연어 트리거 실사용은 Gemini API 호출이 필요해 사용자 확인 대기(Codex와 동일 원칙) |
| 배포물 보안 자동 점검 + CI | ✅ 완료(2026-08-20) | `scripts/security-scan.mjs` + GitHub Actions(`main` push·PR마다 자동 재검증). 가짜 API 키를 심은 커밋을 실제로 차단하는 것까지 실측 확인 |
| `npm audit` 취약점 | ✅ 0건(2026-08-20) | 5건 → 0건. 실제 서버 코드가 안 쓰는 검증용 devDependency의 전이 의존성만 패치 |
| 진행상태(status)·관련 프로젝트(project) | ✅ 완료(2026-08-20) | `wikimate_classify`에 추가, 시켰을 때만 변경(자동판단 없음). **단, 자연어 자동 트리거는 아직 보강 필요**(아래 항목 참고) |
| 분류 기능의 "완료 표시" 자연어 자동 트리거 | 🟡 기능은 완성, 트리거 배선 보강 필요(신규 발견, 2026-08-21) | 기능 자체(진행상태·프로젝트 변경)는 정상 동작하지만, 자연어로 말했을 때 확실히 걸리도록 안내를 보강하는 작업이 아직 남음. 지금은 `/wikimate-classify`나 도구 이름을 직접 언급하면 확실하게 동작함 |
| 연결 이유·연결 종류 기록(Link.reason/kind) | 🔴 미구현(설계 검토 중) | "관련 있다"는 사실만 저장되고, 왜/어떤 종류인지는 아직 저장 공간이 없음. 저장 방식을 먼저 정해야 진행 가능 |
| 실결함 재검증 및 수정 | ✅ 완료(2026-08-21) | 값 저장·재조회 불일치, 목차(MOC) 중복 누적, 존재하지 않는 노트로 링크 생성 — 3건 전부 재현→원인분석→수정→재검증 완료. 자동 테스트 180→191개 |

---

## 18. 문제·오류 대처 방법

| 증상 | 원인 | 해결 |
|---|---|---|
| **"정리해줘" 했는데 노트는 안 만들고 그냥 요약만 해요** | 자연어 자동 발동이 들쭉날쭉(AI가 "요약 요청"으로 오해) | **슬래시 명령으로 콕 찍기**: `/wikimate <링크>` (직접 명령이라 100% 발동) |
| **`marketplace ... not found`(마켓플레이스 못 찾음)** | 마켓플레이스가 아직 **등록(add) 안 됨**(`update`는 등록된 것만 갱신) | **`add`부터**: `/plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git` → 그다음 `/plugin install wikimate@wikimate-marketplace` |
| **정리할 보관함(볼트)을 못 정해요** | 옵시디언에 보관함이 여러 개거나 못 찾음 | 보관함 *이름*을 같이 말하거나, Wikimate가 보여주는 **후보 목록에서 고르기** |
| **`/mcp`에 8개가 다 안 보여요** | 재시작 안 함 / 캐시가 옛것 | Claude Code 껐다 켜기 → 그래도 없으면 아래 "업데이트" |
| **설치가 `EBUSY ... locked`로 실패** | 백신(Defender)이 파일을 잠깐 잠금 | Claude Code 완전히 끄고 다시 켠 뒤 재설치. 반복되면 잠시 뒤 재시도 |
| **옛날 버전이 깔려요** | 마켓플레이스 캐시가 옛것 | `/plugin marketplace update wikimate-marketplace` → `/plugin install wikimate@wikimate-marketplace` |
| **노트가 옵시디언에 안 보여요** | 보관함 *이름*을 안 알려줌 | "내 'Vault' 보관함에"처럼 이름을 같이 말하기 |
| **노션에 색인이 안 돼요** | 노션 도구 미연결 | 정상이에요. 옵시디언 노트만 만들어집니다(노션은 선택). |
| **제목의 기호가 사라졌어요** | `/ \ : * ? " < > \|` 는 파일명 금지문자 | 안전을 위해 공백으로 바뀌어요(의도된 동작). |
| **Node가 없다고 나와요** | Node.js 미설치 | [4번](#4-필요-프로그램-다운로드-방법)대로 nodejs.org에서 LTS 설치 |
| **스마트폰에 설치가 안 돼요** | 모바일 미지원 | Wikimate는 **윈도우 PC 전용**이에요. |
| **연결해달라고 했는데 5개 넘게 안 돼요** | **의도된 안전장치**(과잉 연결 방지) | 정상 동작이에요. 기존 링크 일부를 정리한 뒤 다시 요청하세요. |
| **자동 분류가 90_Templates·99_Archive는 왜 안 건드리나요** | 의도된 설계(서식은 사람 관리, 보관은 건강검진 전담) | 정상 동작이에요. |
| **요약이 "정리해줘"처럼 자동으로 잘 안 걸려요** | 자연어 자동발동이 가끔 안 들을 수 있음 | "이 노트 요약해줘"처럼 더 명확한 문장으로 요청하거나, `/wikimate-summarize`로 100% 확실하게 발동시키세요([12번](#12-명령어-모음)). |
| **Codex에서 링크·분류·요약이 자연어로 자동 실행 안 돼요** | `AGENTS.md` 규칙은 있지만(2026-08-17 보강) 실제 자동 발동은 아직 라이브 검증 전 | 지금은 MCP 도구 이름을 직접 언급해 요청하세요(예: "wikimate_link로 연결 후보 보여줘"). 자동 발동이 안 되면 알려주세요 — 라이브 검증 대상입니다. |
| **"세션 시작 자동 감지" 메시지가 안 떠요** | hooks/agents는 **플러그인을 완전히 다시 불러와야** 반영됨 | Claude Code를 완전히 종료 후 재시작. |

### 업데이트(최신으로 갱신)
```
/plugin marketplace update wikimate-marketplace
/plugin install wikimate@wikimate-marketplace
```
그래도 안 되면 `/plugin` 메뉴에서 마켓플레이스를 **remove → 다시 add → 설치**.

---

## 19. FAQ (자주 묻는 질문)

**Q1. 완전히 처음 컴퓨터를 써보는데 따라 할 수 있나요?**
A. 네. 이 문서는 [1번](#1-wikimate가-뭐예요-1분-이해)부터 순서대로만 따라 하면 되도록 만들었어요. 모르는 단어는 [2번 "낱말 사전"](#2-30초-용어-사전-왕초보-필수)에 다 있어요.

**Q3. 인터넷 연결이 항상 필요한가요?**
A. Wikimate 서버 자체(노트 파일 읽고 쓰기)는 인터넷이 필요 없어요. 다만 AI(Claude Code/Codex)에게 말을 시키는 부분과, 웹 링크를 정리할 때 그 링크 내용을 가져오는 부분은 인터넷이 필요해요.

**Q4. 여러 개의 옵시디언 보관함(볼트)을 같이 쓸 수 있나요?**
A. 네. `wikimate_vaults`가 등록된 보관함 목록을 보여주고, 매번 어디에 정리할지 고를 수 있어요.

**Q5. 실수로 중요한 노트가 지워질까 걱정돼요.**
A. Wikimate에는 "삭제" 기능 자체가 없어요. 정리가 필요한 노트는 삭제 대신 99_Archive 폴더로 옮기기만 하고, 내용을 바꾸는 경우엔 항상 먼저 자동 백업을 만들어요.

**Q6. AI가 제 개인 메모(일기 등)를 다 읽나요?**
A. 명령을 내린 자료·노트에 대해서만 필요한 만큼 읽어요. 자동 링크 제안 같은 기능은 본문 전체가 아니라 제목·요약·태그만 사용하도록 설계했어요.

**Q7. 노트가 100개, 1000개로 늘어나도 느려지지 않나요?**
A. 지금 설계는 개인용 보관함(수십~수백 개 노트) 기준으로 충분히 빠르게 확인했어요. 아주 큰 규모(수만 개 이상)의 보관함은 아직 성능을 확인하지 않았어요.

**Q8. Mac이나 Linux에서도 되나요?**
A. 이 문서와 공식 테스트는 **Windows 11 기준**이에요. Node.js 기반이라 이론적으로는 다른 운영체제에서도 동작할 가능성이 있지만, **공식적으로 확인·보장하지는 않아요.**

**Q10. AI가 제 원본 자료를 요약만 하고 원문은 버리지 않나요?**
A. 그런 실수를 막으려고 안전장치를 만들었어요. Wikimate는 정리할 때 웹주소는 있는데 내용이 너무 짧으면 "요약만 넣은 거 아니에요?"라고 저장 전에 미리 알려줘요([16번](#16-보안데이터-흐름) 참고). 다만 이건 **경고이지 강제 차단은 아니에요.**

**Q11. 요약(summarize) 기능이 원문을 지우거나 고칠 수 있나요?**
A. 아니요. 위 [16번](#16-보안데이터-흐름)에서 설명한 것처럼, 요약 도구는 원문(본문)을 고칠 수 있는 코드 경로 자체가 없어요. 요약은 언제나 "추가"이지 "대체"가 아니에요.

**Q12. Codex에서도 Claude Code와 똑같이 쓸 수 있나요?**
A. MCP 도구 8개는 Codex에서도 전부 정상 동작해요(직접 호출 시). `AGENTS.md`엔 자동 링크·자동 분류·자동 요약을 포함한 6개 흐름의 **자연어 자동 발동** 규칙이 전부 반영돼 있어요(2026-08-17 보강). 남은 건 `codex exec`로 이 규칙이 자연어 문장에서 실제로 발동하는지 라이브 확인뿐이에요(직접 도구 지정 호출은 검증됨) — 정직하게 미리 알려드려요([13번 업데이트 내용](#13-업데이트-내용-요약)의 "앞으로 남은 것" 참고).

**Q13. 문제가 생기면 어디에 물어보나요?**
A. 먼저 [18번 "문제·오류 대처"](#18-문제오류-대처-방법)를 확인하세요. 해결이 안 되면 GitHub 저장소의 Issues에 남겨주세요.

---

> ⚖️ **아래는 일반 안내이며 법률 자문이 아니에요.** 상업적 이용·배포 전에는 각 구성요소의 원문 약관을 직접 확인하세요. (정확한 고지는 `LICENSE`·`NOTICE` 파일이 정본입니다.)

### 20-1. Wikimate 본체
- **라이선스: Apache License 2.0** © 2026 SoDam AI Studio. (전문: [`LICENSE`](./LICENSE))
- Apache-2.0은 **상업적 이용·수정·배포·사적 이용을 허용**해요. 단, 아래를 **반드시 지켜야** 합니다:
  - **저작권 고지**와 **라이선스 사본(LICENSE)** 을 함께 포함할 것.
  - 파일을 **변경했다면 변경 사실을 표시**할 것.
  - `NOTICE` 파일이 있으면 그 고지 내용을 **유지**할 것.
- **무보증(AS-IS)** 이며, **특허 라이선스는 조건부로 함께 부여**되지만(4항의 표준 Apache-2.0 조건), **상표 권리는 부여되지 않아요** — "Wikimate"·"SoDam AI Studio" 이름을 **내 제품 이름처럼 쓰거나 보증·홍보에 사용하지 마세요**(허락 필요).
- **책임 제한**: Apache-2.0 8항에 따라, 법이 요구하지 않는 한 저작권자·기여자는 이 소프트웨어 사용으로 인한 손해에 대해 책임지지 않아요.

### 20-2. 함께 쓰는 외부 도구 (Wikimate에 포함되어 있지 않음 — 사용자가 따로 설치)
Wikimate의 MCP 서버는 **무의존(zero-dependency)** 이라 아래 도구를 **번들로 포함하지 않아요.** 쓰려면 직접 설치하며, **각자의 라이선스·약관이 적용**돼요:

| 도구 | 저작권자 | 라이선스 | 상업적 이용 |
|---|---|---|---|
| Node.js | Node.js 재단 등 | MIT 등 | 허용 |
| @modelcontextprotocol/sdk (검증용 devDependency) | Anthropic, PBC | MIT | 허용 |
| notesmd-cli | Kunal Mandalia (Yakitrak) | MIT | 허용 |
| mcp-obsidian | Markus Pfundstein | MIT | 허용 |
| notion-mcp-server | Notion Labs, Inc. | MIT | 허용 |
| Notion 공식 CLI `ntn` / Notion API | Notion Labs, Inc. | **Notion 개발자 약관** | **Notion 약관 준수 필요** |
| Obsidian (앱) | Dynalist, Inc. | 개인 무료 / **상업용은 별도 라이선스** | **Obsidian 약관 확인 필요** |

> ⚠️ 특히 **Obsidian을 회사 업무 등 상업적으로** 쓰면 **상업용 라이선스가 필요할 수 있어요.** **Notion API**도 개발자 약관을 따라야 해요. 둘 다 원문 약관을 직접 확인하세요. (`npm audit` 기준으로 검증용 devDependency에 알려진 취약점이 일부 있으나, 실제 서버(`mcp/server.mjs`)는 이 패키지를 아예 import하지 않아 배포·실행 경로엔 영향이 없다는 점을 코드로 직접 확인했어요 — 2026-08-04.)

### 20-3. 데이터·콘텐츠 저작권
- 내가 정리하는 자료(웹·PDF 등)의 **저작권은 원저작자에게** 있어요. Wikimate는 정리를 도울 뿐, 저작권 처리를 대신해 주지 않아요. **수집·재배포 시 원저작물의 라이선스·이용약관을 반드시 지키세요.**
- 정리된 노트는 **내 컴퓨터(로컬)** 에 저장돼요. 외부로 보내지 않아요(노션 색인은 내가 켤 때만).
- API 키·토큰·개인정보는 노트나 배포물에 저장하지 않습니다.
- **Wikimate가 정리해 준 결과물(노트) 자체의 저작권은 100% 사용자 것**이에요. Wikimate(SoDam AI Studio)는 노트를 만드는 걸 도와줄 뿐, 그 노트에 대해 어떤 권리도 주장하지 않아요.

### 20-4. 면책
- Wikimate는 **"있는 그대로(AS-IS)" 무보증** 제공돼요. 데이터 손실·오작동·제3자 약관 위반에 대한 책임은 **사용자에게** 있어요. 중요한 자료는 **백업**을 권장해요.
- 이 문서의 안내는 **법률 자문이 아니에요.** 상업적·기업 환경에서 이용하려면 필요 시 변호사 등 전문가와 상의하세요.

> 개발·테스트·배포 방법은 [`DEVELOPMENT.md`](./DEVELOPMENT.md)를 참고하세요.

---

## 21. 한눈 요약 (치트시트)

```
설치(Claude Code):  /plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git
                    /plugin install wikimate@wikimate-marketplace  → 재시작
확인:               /mcp  → wikimate_collect/lint/fix/runlog/vaults/link/classify/summarize (8개)
실행:               따로 없음 — Claude Code 켜고 말로 시키면 됨
정리(자연어):       "이 링크 정리해줘: https://..."
정리(확실·권장):    /wikimate https://...     ← 자연어가 안 들으면 이걸로(100%)
찾기:               "내 볼트에서 ~ 찾아줘"
점검:               "내 볼트 건강검진해줘"
기록:               "최근 작업 보여줘"
연결:               "관련 노트 연결해줘" / "이 주제로 목차 만들어줘"
분류:               "이 노트 분류해줘"
요약:               "이 노트 요약해줘"
업데이트:           /plugin marketplace update wikimate-marketplace → 재설치
안전:               계획→승인→실행→검수 / 삭제 대신 99_Archive 이동 / 볼트 밖 차단 / 링크 최대 5개 / 요약은 원문 무수정
라이선스:           Apache-2.0 © SoDam AI Studio (외부 도구는 각자 라이선스)
```

문제가 생기면 [18번(문제 대처)](#18-문제오류-대처-방법)이나 [19번(FAQ)](#19-faq-자주-묻는-질문)을 먼저 보세요. 그래도 안 되면 GitHub 저장소의 Issues에 남겨 주세요.

SoDam-WikiMate

File Explorer

# Installation Guide

2. Node.js

Today's picks

Was this content helpful?

Recent Feedback

SoDam-WikiMate

File Explorer

# Installation Guide

2. Node.js

Today's picks

Was this content helpful?

Recent Feedback

Download README