SoDam-WikiMate

위키메이트 AI 에이전트에게 **"정리해줘"** 라고 하면, 흩어진 자료(웹 링크·PDF·대화 로그·텍스트)를 **내 옵시디언 볼트에 노트로 정리**하고, 원하면 **노션에 색인**해주는 ** Code 플러그인**. (Codex엔 "플러그인 설치(`/plugin`)"가 없어요 — 대신 저장소를 받아 `codex mcp add`로 **MCP 서버로 등록**해 연동합니다: [`adapters/codex/SETUP.md`](./adapters/codex/SETUP.md).) **[English](./README.en.md)** > **처음이세요?** 그대로 따라 하는 [왕초보 가이드](./GUIDE.ko.md) ([PDF](./GUIDE.ko.pdf))를 보세요 — 용어 사전·설치·사용·문제해결·라이선스까지 전부 쉽게 설명해요. > 상태: **v0.7.1** — 정리·검색·볼트 건강검진·작업 로그·**보관함 자동탐지**(MCP 도구 5개) 동작·검증 완료. 노션 색인은 노션 도구가 연결된 환경에서 동작(아래 "현재 상태" 참고). > **기기 안내:** Wikimate는 **윈도우 PC(데스크톱·노트북) 전용**이에요. **스마트폰·태블릿에는 설치되지 않습니다.** ## 무엇을 해주나요? - **자연어로 정리** — "이 링크 정리해줘" 한마디면 노트가 만들어져요. (가끔 자동발동이 안 되면 **`/wikimate <링크>`** 슬래시 명령으로 100% 실행.) - **보관함 자동탐지(v0.7.1)** — 옵시디언에 등록된 보관함(볼트)을 자동으로 찾아 **"여기에 정리할까요?"** 하고 제안해줘요(이름 안 말해도 됨, 도구 `wikimate_vaults`). - **내 진짜 옵시디언 볼트에** — 설치된 옵시디언 도구(MCP/CLI)를 자동 감지해 사용하고, 없으면 파일로 폴백. - **노션 색인(선택)** — 노션 도구가 연결돼 있으면 색인 행을 추가(옵시디언=원본, 노션=단방향 색인). - ** 계획 먼저 → 승인** — 멋대로 쓰. - 복 차단** — 같은 `source_hash` 번만. - **안전 설계** — 볼트 밖 경로 차단, 외부 글은 명령이 아니라 데이터로 취급(프롬프트 인젝션 방어). - **물어보기** — "내 볼트에서 ~ 찾아줘" 하면 정리해 둔 노트에서 **출처와 함께** 답해요(없는 건 없다고 정직히). - **볼트 건강검진** — 중복·깨진 `[[링크]]`·고아 노트·머리말 누락을 찾아 **보고**하고, 승인하면 **삭제 없이**(보관함 이동·백업) 고쳐요. - **작업 로그** — AI가 내 볼트에서 한 일을 자동 기록("최근 작업 보여줘"). ## 30초 용어 (왕초보용) | 낱말 | 쉬운 뜻 | |---|---| | **플러그인** | 프로그램에 끼워 넣는 새 기능 부품 (앱 추가 설치 같은 것) | | **마켓플레이스** | 플러그인을 받아오는 앱 장터 | | **MCP / MCP 도구** | AI와 도구를 잇는 통로 / 그 통로로 누르는 기능 버튼 | | **볼트(Vault)** | 옵시디언에서 노트를 모아 두는 보관 폴더(이름이 있어요) | | **dry-run** | 실제로 하기 전에 "계획만" 미리보기 | > 더 많은 용어는 [왕초보 가이드 1번](./GUIDE.ko.md)에 있어요. ## 설치 (Claude Code) > 아래 **두 명령을 한 줄씩 따로** 입력하세요. (한꺼번에 붙여넣으면 URL이 깨져 실패해요.) **1) 마켓플레이스 추가** — 입력 후 Enter, "added" 확인: ``` /plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git ``` **2) 플러그인 설치** — 1)이 끝난 뒤: ``` /plugin install wikimate@wikimate-marketplace ``` 설치 후 Claude Code를 재시작하면 끝. (확인하고 싶으면 `/mcp`에 `wikimate_collect`·`wikimate_lint`·`wikimate_fix`·`wikimate_runlog`·`wikimate_vaults` 5개가 보이면 성공) ## 실행 방법 **따로 "실행(켜기)"할 게 없어요.** 설치만 하면 Claude Code를 켤 때마다 자동으로 함께 켜져요. "실행"은 곧 **Claude Code를 켜고 대화창에 말로 시키는 것**이 전부예요. (개발자가 서버를 직접 돌리려면 받은 폴더에서 `npm install` 후 `npm start`.) ## 설치 (Codex) Codex엔 `/plugin` 마켓플레이스가 **없어요.** 대신 저장소를 받아 **MCP 서버로 등록**합니다. **1) 저장소 받기** ``` git clone https://github.com/sodam-ai/SoDam-WikiMate.git ``` **2) MCP 서버 등록** (볼트·저장소 경로는 본인 것으로 바꾸세요): ``` codex mcp add wikimate --env OBSIDIAN_VAULT_PATH=D:/내/볼트/경로 -- node D:/받은/경로/SoDam-WikiMate/mcp/server.mjs ``` → `codex mcp list` 에 `wikimate`가 보이면 성공. **3) (선택) 자연어 규칙** — Codex 작업 폴더에 저장소의 `AGENTS.md`를 두면 "정리해줘" 같은 말도 따릅니다. **업데이트**: 받은 폴더에서 `git pull` 하면 끝(Claude Code 같은 캐시 함정 없음). > **Codex는 "축소판"이에요.** 정리(쓰기) MCP 도구까지 동작하지만, *자동 발동·물어보기·여러 노트 종합* 같은 **스킬은 Claude Code 전용**이고, 노션 색인은 Codex에 **별도 노션 MCP**가 연결돼 있어야 해요. (자세히: [`adapters/codex/SETUP.md`](./adapters/codex/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를 완전히 종료했다 다시 켠 뒤** 위 명령을 다시 실행하면 대개 풀립니다. ## 사용법 대화로 시키면 됩니다: > "이 내용을 내 'Vault' 볼트에 정리해줘" > **확실한 방법장)** — 자연어 "정리해줘"는 AI 판단이라 **가끔 자동발동을 안 하고 그냥 요약만** 할 때가 있어요. 그럴 땐 **슬래시 명령** `/wikimate <링크/텍스트>` 를 쓰면 **100% 발동**합니다(직접 명령이라). 예: `/wikimate https://example- **정리할 "자료"는 무엇이든 돼요** — 한 문장 텍스트, 웹 링크(`이 링크 정리해줘: https://...`), 파일 경로(`이 파일 정리해줘: D:\메모\오늘.md`) 모두 OK. 따로 준비할 게 없어요. - **보관함 이름은 안 말해도 돼요(v0.7.1)** — Wikimate가 등록된 보관함을 찾아 "여기에 할까요?"라고 제안해줘요. 콕 집어 *"내 'Vault' 볼트에"* 처럼 말해도 됩니다(이름은 옵시디언 좌하단 볼트 전환 메뉴에서 확인). - 먼저 계획(어디에·어떤 도구로·노션 색인 여부)을 보여주고, 승인하면 노트를 만듭니다. **찾을 때도 대화로** (읽기 — 정리해 둔 노트에서): > "내 볼트에서 RAG 찾아서 요약해줘" - 색인(노션)과 원본(옵시디언)에서 찾아 **출처와 함께** 답해요. **답하기 전에 원본이 실제로 있는지 확인**하고, 지워진 노트(끊긴 색인)면 "원본 없음"이라고 솔직히 알려줍니다(없는 걸 있다고 안 함). - **여러 노트를 묶어서도** 물어볼 수 있어요: "내 노트들로 RAG·임베딩·벡터DB 관계 정리해줘" → 관련 노트를 모아 **노트별 출처와 함께 종합**해 답합니다(어떤 노트로 답할지 먼저 보여줘요). **정리 상태가 궁금할 때도 대화로** (건강검진 — 읽기): > "내 'Vault' 볼트 건강검진해줘" - **고아 노트**(아무 데도 안 이어진 노트)·**깨진 `[[링크]]`**·**중복**·**frontmatter 누락**, 그리고 노션을 쓰면 **끊긴 색인**(원본은 지워졌는데 노션 행만 남은 것)을 찾아 **보고**해요. **멋대로 고치지 않아요** — 고칠 항목을 골라 승인하면 그때만 손봅니다: 중복은 **삭제가 아니라 보관함(99_Archive)으로 이동**(되돌리기 쉬움), 링크 수정은 **고치기 전 자동 백업**(비가역은 한 번 더 확인). ## 환경 변수 (선택) | 변수 | 용도 | |---|---| | `OBSIDIAN_VAULT_PATH` | 볼트 폴더 절대경로 (파일 폴백·중복검사용) | | `OBSIDIAN_VAULT_NAME` | 옵시디언에 등록된 볼트 이름 (CLI용) | | `NOTION_RESEARCH_DB_ID` | 노션 색인 DB 지정 (없으면 검색하거나 물어봐요) | `.env.example`를 복사해 `.env`로 쓰세요. **실제 값(토큰 등)은 절대 git에 올리지 마세요.** ## 폴더 구조 ``` .claude-plugin/ 플러그인·마켓플레이스 매니페스트 mcp/server.mjs 무의존 MCP 서버 (stdio) — 도구 5개(collect·lint·fix·runlog·vaults) mcp/lib/collect.mjs 수집(이름 안전화·중복 차단) mcp/lib/lint.mjs 건강검진(읽기전용) mcp/lib/fix.mjs 안전 수정(삭제 없음·백업) mcp/lib/runlog.mjs 작업 로그 skills/ 자연어 자동 발동 스킬(organize·query·lint) commands/ /wikimate · /wikimate-lint 명령 adapters/codex/ Codex용 설정 안내 templates/ 노트 템플릿 scripts/ 검증 스크립트(verify-*·smoke-*) (내 볼트의) .wikimate/runlog.jsonl 작업 로그(숨김) 안전·보안 - **쓰기는 사람 승인 후** 실행 (``이 기본 — 계획만 먼저 보여 매번 "승이 번거로 **"묻지 말고 바로 정리해줘"** 라고 하세요 → 신규 노트 생성은 자동(단 **덮어쓰기·삭제는 항상 한 번 더 확인**). 그리고 승인은 **선택지(숫자/클릭)** 로 떠서, "진행해줘"를 타자치지 않고 골라도 돼요. - **노트 제목·폴더의 경로 구분자·금지제어문자를 정리**하고 **볼 경로를 차단**(경로 이탈 방지). -외부 자료 속문은 명령로만** 취급(프롬프트 인젝션 방어). -옵시디언 CLI는 셸 없이(명령 주입 방지). 키·토 노트·물에 저장하지. - **`.obsidian/` 폴더드리지 않음**. 기존 노트는 승인 없이 수정·삭제하지 않- **노인은 노션 도돼 있을 때만**. 안 되면 옵시만 정리하고 솔직히 보고해요. - **작업 기록)** — 실제로·옮기고친 노트는 자동으로 `.wikimate/runlog.jsonl`(숨김)에 한 줄씩 남아요. **"최근 작업 보여** 라고 하면는지 되짚립니다(읽기 전용 안전 로그). 상태 (정직하게) - **디언 정리**: 실제 볼트에 생성 확인(자연 발동 포함). **건강검안전수정·작업위테스트 +토콜 e2 검증(중깨진링크· 탐지, 삭제 없는 수정, 자동 기록). - **노션 색인**: 노션CP/CLI)가 연결·인증된 환경에서 환경에 따라결이면 자동으로 건니다. -Codex**: 같은 MCP 코어를 쓰도록 어댑터 제공( `adaptersSETUP.md`). - **라이브 세션 미검증 Claude Code `/mcp` 세션·실볼트 검증은 사용자 환경에서 권장(2분, 위 설치 참고). ## 문제 해결 - **"정리해줘" 했는데 노트는 안 만들고 요약만 해요** → 자연어 자동 발동이 들쭉날쭉이에요. **`/wikimate <링크>`** 슬래시 명령으로 콕 찍으면 100% 됩니다(가장 확실). - **`market not found`(마켓플레이스 못 찾 등록이 안예요.`가 아니라 ** marketplace add https://github.com/sodam-ai/SoDam-Wiki 부터 뒤 `/plugin install@wikimate-marketplace`. - **cp`에 안** → Claude시작. 그래도 없으면 위 "" 방식으로 캐시 갱신. - **노트가 옵시디언에 안 보여요트 *이름*을 정확히 말했는지 확인(파일 폴백은 `OBSIDIAN_VAULT_PATH` 폴더에 생성됨). - **노션인이 안 돼요션 MCP/·인증 확인. 안 되면 옵시디언 노트만 생성됩니다(정상- 의 일부 기호가 사라졌어요 \ : * < > |` 같은 파일명 금지문자는 안전을 위해 공백으로 정리돼요(의도된 동작). - **설치가 `EBUSY ... locked` 로 실패해요** → 백신 파일 잠금이에요. 껐다 켠 뒤 다시 설치(위 "업데이트"되면 잠시 뒤 재시도. **옛날 버전(예: 1.0)이 깔려요**켓플레이스것이에요. 위 "업데이트 `marketplace update remove → 다시갱신하세요. > 더 많은 증결은 [왕초보 가이드 15GUIDE.ko 표로 정리요. ## 참고 도구 [notesmd-cli](https://github.com/Yakitrak/notesmd-cli) · [mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian) · [notion-mcp-server](https://github.com/makenotion/not-server) · [n](https://ion.com/cli/get) ## 라이 저작권적 이용 아래는이며 **법률 자에요.**지는 `LICENSE`NOTICE` 파일이 정본입니다. - **Wikimate 본체: Apache2.0** 2026 SoDam AI Studio. 상업·수정 허용, 단권 고지+라이선스 사본 포함**·**변경 표시**·**NOTICE 유지** 필요.증(IS)**, **리 미("Wik·"So Studio" 이름 임의 사용 금지). -외부 도구는님**.js·@protocol/sdk·notes·mcp-·notion-mcp-server는 **MITNotion API/``은 Notion 약관**, **Obsidian은 개인 무료업용 별선스**. 각 약관을 직접 확인하세요. - **콘텐츠 저작권**은 원저작자에게 있어요. 수집·재배포 시 원저작물의 라이선스·약관을 지키세요. 노트는 **내 컴퓨터(로컬)** 에만 저장되고 외부로 보내지 않아요(노션 색인은 내가 켤 때만). > 전체 라이선스 표·면책은 [왕초보 가이드 17번](./GUIDE.ko.md) 또는 `NOTICE` 참고. 개발·테스트·배포 방법은 [DEVELOPMENT.md](./DEVELOPMENT.md).