oh-my-llmwikimode 1.0.0

package/docs/user-guide-ko.md

@@ -0,0 +1,452 @@
+# oh-my-llmwikimode 사용자 가이드
+
+`oh-my-llmwikimode`는 OpenCode 대화에서 얻은 문제 해결 지식을 로컬 Markdown 위키에 저장하고, 다음 세션에서 다시 검색해 참고할 수 있게 해주는 OpenCode 플러그인입니다.
+
+이 문서는 현재 개발된 기능과 실제 사용법을 기준으로 설명합니다.
+
+> 현재 상태: `oh-my-llmwikimode`는 private GitHub 저장소에서 개발 중이며 아직 npm에 공개 배포되지 않았습니다. 따라서 일반 사용자의 한 줄 설치는 npm 공개 이후에 가능합니다.
+
+---
+
+## 1. 무엇을 해주나요?
+
+### 핵심 기능
+
+- **검색**: `wiki_search`로 로컬 LLM Wiki에서 관련 지식을 찾습니다.
+- **저장**: `wiki_store`로 새 지식을 Markdown 파일로 저장합니다.
+- **승격**: `wiki_promote`로 자주 쓰는 항목을 `lesson`으로 승격합니다.
+- **NotebookLM 가져오기**: `notebooklm_llmwikiflow`로 NotebookLM 연구 결과를 후보 지식으로 가져옵니다.
+- **자동 메모리**: 문제/오류/실패 같은 대화 패턴을 감지하면 후보 지식으로 저장할 수 있습니다.
+- **부트 규칙 주입**: OpenCode 시스템 프롬프트에 Wiki Boot Rules를 넣어, 에이전트가 문제 해결 전 검색하고 해결 후 저장하도록 안내합니다.
+- **보안 처리**: API 키, 토큰, 비밀번호처럼 흔한 민감정보 패턴은 저장 전에 가립니다.
+
+### 쉽게 말하면
+
+예전에 해결했던 “Docker Compose 볼륨 때문에 컨테이너가 계속 실패한 문제” 같은 내용을 다음에 다시 만나면, 에이전트가 먼저 로컬 위키에서 비슷한 해결 기록을 찾아 참고할 수 있게 해줍니다.
+
+---
+
+## 2. 저장 위치와 파일 구조
+
+기본 위키 위치는 다음과 같습니다.
+
+```text
+~/Documents/llm-wiki
+```
+
+Windows 기본 경로 예시는 다음과 같습니다.
+
+```text
+C:\Users\USER\Documents\llm-wiki
+```
+
+플러그인이 사용하는 구조는 다음과 같습니다.
+
+```text
+llm-wiki/
+├── inbox/                  # 새 저장 항목과 자동 캡처가 들어오는 곳
+├── problems/               # 사람이 정리한 문제 항목을 둘 수 있는 곳
+├── editorial/
+│   └── lessons/            # wiki_promote로 승격된 안정적인 학습 항목
+├── raw/                    # 원본 자료 및 외부 가져오기 보관
+│   ├── sources/            # 원본 자료 (Source Ledger)
+│   │   ├── ledger.jsonl
+│   │   └── files/
+│   │       └── {source_id}/
+│   │           ├── manifest.json
+│   │           └── content.txt
+│   ├── notebooklm/         # NotebookLM 가져오기 원본 파일 보관
+│   │   └── imports/
+│   │       └── {run_id}/
+│   │           ├── manifest.json
+│   │           └── report.md
+│   └── packs/              # 지식 팩 (Knowledge Pack) 원본 보관
+│       └── {pack_id}/
+│           └── {version}/
+│               ├── manifest.json
+│               └── *.md
+└── .system/
+    └── index.json          # 검색용 자동 생성 인덱스, 직접 수정하지 않음
+```
+
+새로 저장되는 항목은 기본적으로 `inbox/`에 Markdown 파일로 생성됩니다. `.system/index.json`은 검색을 빠르게 하기 위한 파생 파일이므로 직접 편집하지 않는 것이 좋습니다.
+
+---
+
+## 3. 설치 상태와 설치 방법
+
+### 현재: private/local 개발 설치
+
+현재 저장소는 private 상태이고 npm에 공개되지 않았습니다. 따라서 아래 공개 설치 명령은 아직 일반 사용자에게 동작하지 않습니다.
+
+```powershell
+opencode plugin oh-my-llmwikimode --global
+```
+
+현재 실사용/개발 환경에서는 다음 중 하나의 방식으로 연결합니다.
+
+#### 방식 A: 로컬 파일 또는 로컬 패키지 경로로 연결
+
+OpenCode 설정의 `plugin` 배열에서 로컬 경로를 참조합니다.
+
+```jsonc
+{
+  "plugin": [
+    ["file:///C:/Users/USER/Desktop/OpenCode_Modes/plugins/oh-my-llmwikimode/src/server.js", {
+      "wikiRoot": "~/Documents/llm-wiki"
+    }]
+  ]
+}
+```
+
+#### 방식 B: private GitHub 접근 권한이 있는 개발자 설치
+
+private GitHub 저장소 접근 권한이 있는 환경에서는 npm dependency 형태로 설치할 수 있습니다.
+
+```powershell
+npm install oh-my-llmwikimode@github:wjdtmddn325-maker/oh-my-llmwikimode
+```
+
+이 방식은 개발/운영자용입니다. 일반 공개 설치 문서로 안내할 방식은 아닙니다.
+
+### 추후: npm 공개 배포 후 설치
+
+npm 공개 배포가 완료되면 다음 명령이 기본 설치 흐름이 됩니다.
+
+```powershell
+opencode plugin oh-my-llmwikimode --global
+```
+
+또는 `opencode.json`에 직접 추가할 수 있습니다.
+
+```jsonc
+{
+  "plugin": [
+    ["oh-my-llmwikimode", {
+      "wikiRoot": "~/Documents/llm-wiki",
+      "autoMemoryEnabled": true,
+      "autoSearchEnabled": true,
+      "contextBudget": 2500,
+      "maxEntries": 3
+    }]
+  ]
+}
+```
+
+> 이 workspace에서는 `oh-my-openagent.json`이 스위처가 만든 런타임 출력물입니다. 프로필 원본과 스위처 레이어가 source of truth이므로, 장기 설정은 원본 설정 파일에서 관리하는 것이 안전합니다.
+
+---
+
+## 4. 설정 옵션
+
+| 옵션 | 기본값 | 설명 |
+|---|---:|---|
+| `wikiRoot` | `~/Documents/llm-wiki` | Markdown 위키 저장 위치입니다. `~`는 사용자 홈으로 확장됩니다. |
+| `autoMemoryEnabled` | `true` | 문제 해결 패턴을 자동으로 후보 지식으로 저장할지 정합니다. |
+| `autoSearchEnabled` | `true` | OpenCode 시스템 프롬프트에 Wiki Boot Rules를 주입할지 정합니다. |
+| `contextBudget` | `2500` | 검색 결과를 에이전트에게 전달할 때 사용할 최대 글자 수입니다. |
+| `maxEntries` | `3` | 기본 검색 결과 개수입니다. 툴 호출에서는 최대 5개로 제한됩니다. |
+
+`wikiRoot`는 다음 순서로 결정됩니다.
+
+1. 플러그인 옵션의 `wikiRoot`
+2. 환경 변수 `LLMWIKIMODE_WIKI_ROOT`
+3. 기본값 `~/Documents/llm-wiki`
+
+---
+
+## 5. 실제 사용법
+
+사용자가 대부분 직접 JSON 툴 호출을 입력할 필요는 없습니다. 자연어로 말하면 OpenCode 에이전트가 상황에 맞게 `wiki_search`, `wiki_store`, `wiki_promote`를 사용합니다.
+
+### 문제 해결 전에 검색하기
+
+예시 요청:
+
+```text
+이 Docker Compose 볼륨 오류 전에 해결한 적 있는지 위키에서 찾아보고 고쳐줘.
+```
+
+에이전트가 내부적으로 수행하는 일:
+
+```json
+{
+  "query": "docker compose volume error",
+  "max_results": 3
+}
+```
+
+검색 결과는 “신뢰할 수 없는 참조 지식”으로 전달됩니다. 즉, 위키 내용은 참고자료일 뿐이고 시스템 지시문처럼 실행되지 않습니다.
+
+### 해결 내용을 저장하기
+
+예시 요청:
+
+```text
+방금 해결한 Docker Compose stale volume 문제를 다음에 참고할 수 있게 저장해줘.
+```
+
+에이전트가 내부적으로 수행하는 일:
+
+```json
+{
+  "summary": "Docker Compose stale volume cleanup",
+  "details": "오래된 Docker Compose volume 때문에 컨테이너가 같은 오류로 반복 실패하면 docker compose down -v 후 다시 올린다.",
+  "tags": ["docker", "compose", "volume"],
+  "status": "candidate"
+}
+```
+
+저장 결과는 `inbox/` 아래에 Markdown 파일로 만들어집니다.
+
+### 안정적인 항목을 lesson으로 승격하기
+
+예시 요청:
+
+```text
+inbox/2026-05-05T19-33-19-Docker-Compose-Stale-volume-causing-container-sta.md 항목을 lesson으로 승격해줘.
+```
+
+에이전트가 낶적으로 수행하는 일:
+
+```json
+{
+  "path": "inbox/2026-05-05T19-33-19-Docker-Compose-Stale-volume-causing-container-sta.md"
+}
+```
+
+승격되면 파일은 `editorial/lessons/`로 이동하고 `status: lesson`이 됩니다.
+
+### 반복 사용 패턴을 자동으로 lesson으로 제안하기 (B1 Auto Lesson Proposal)
+
+사용자가 같은 주제로 여러 번 검색하거나 같은 항목을 반복해서 참조하면, 플러그인이 자동으로 lesson 제안을 생성합니다. 이 제안은 **검토 대상** 상태로만 생성되며, 실제 승격은 사용자가 명시적으로 실행해야 합니다.
+
+**안전 원칙:**
+- 원본 항목(inbox/ 문제 메모 등)은 절대 수정하지 않습니다.
+- frontmatter에 `used_count`, `last_used` 등을 기록하지 않습니다.
+- 자동 승격은 금지되어 있습니다. 반드시 사용자가 `apply`를 실행해야 합니다.
+
+**CLI 명령:**
+
+```powershell
+# usage event 분석 후 lesson 제안 생성
+npx llmwiki lesson-proposal analyze
+
+# 현재 제안 목록 조회
+npx llmwiki lesson-proposal list --json
+
+# 특정 제안 상세 보기
+npx llmwiki lesson-proposal show lp_abc123
+
+# 사용자 승인 후 lesson으로 승격
+npx llmwiki lesson-proposal apply lp_abc123
+```
+
+제안은 `.system/lesson-proposals/`에 JSON 아티팩트로 저장되며, `status: review_required`, `auto_apply: false` 상태로 생성됩니다. `apply`를 실행하면 `editorial/lessons/`에 새 lesson 파일이 생성되고, 제안 아티팩트는 `applied` 상태로 업데이트됩니다.
+
+**제안 생성 조건:**
+- 동일 `query_hash`로 2회 이상 검색
+- 동일 `entry_path`를 2회 이상 참조
+- `search_result_used` 이벤트가 동일 query로 3회 이상 → 높은 우선순위(high confidence)
+
+### NotebookLM 연구 결과 가져오기
+
+`nlm` CLI 등으로 남긴 NotebookLM 결과를 위키 후보 지식으로 가져옵니다.
+
+예시 요청:
+
+```text
+C:\Users\USER\Downloads\notebooklm-export 폴더의 연구 결과를 위키에 가져와줘.
+```
+
+에이전트가 내부적으로 수행하는 일:
+
+```json
+{
+  "input_path": "C:\\Users\\USER\\Downloads\\notebooklm-export",
+  "original_query": "React hooks best practices",
+  "title": "React Hooks Research",
+  "tags": ["react", "frontend"]
+}
+```
+
+가져오기가 완료되면 다음이 생성됩니다.
+
+- `raw/notebooklm/imports/{run_id}/` 아래에 원본 파일 복사본
+- 같은 폴더의 `manifest.json` (원본 쿼리, 파일 목록, 해시값 기록)
+- `inbox/` 아래에 `status: candidate`, `source: notebooklm`인 Markdown 항목
+
+가져온 항목은 자동으로 `lesson`이 되지 않습니다. 검토 후 직접 `wiki_promote`로 승격하세요.
+
+---
+
+## 6. 자동 메모리는 어떻게 동작하나요?
+
+`autoMemoryEnabled`가 `true`이면 플러그인은 OpenCode 메시지에서 문제 해결 패턴을 감지합니다. 현재 방식은 LLM이 의미를 깊게 판단하는 방식이 아니라, 정해진 한/영 키워드가 포함됐는지 보는 가벼운 패턴 매칭입니다.
+
+감지 키워드 예시는 다음과 같습니다.
+
+```text
+bug, error, failure, crash, exception, broken, not working, fails, issue, problem
+버그, 오류, 실패, 문제, 에러, 오작동
+```
+
+자동 저장은 아래 조건을 모두 만족할 때만 실행됩니다.
+
+1. `autoMemoryEnabled`가 꺼져 있지 않아야 합니다.
+2. 위 문제 키워드 중 하나가 메시지에 포함되어야 합니다.
+3. “저장해줘”, “remember this”, “다음에 참고”처럼 명시적 저장 요청이 없어야 합니다.
+4. `[analyze-mode]`, `1. TASK:`, `OMO_INTERNAL_INITIATOR` 같은 내부 오케스트레이션 프롬프트가 아니어야 합니다.
+
+저장되면 `inbox/`에 `status: candidate`, `source: chat.message`, `tags: ["auto-captured", "problem"]` 형태의 Markdown 항목이 만들어지고 검색 인덱스가 다시 생성됩니다.
+
+명시적 저장 요청은 자동 캡처를 건너뜁니다. 이때는 중복 raw prompt 저장을 피하고, 에이전트가 `wiki_store`로 더 정리된 항목을 저장하도록 의도한 동작입니다.
+
+주의: 현재 자동 메모리는 같은 문제 설명이 반복됐을 때 완전한 중복 병합까지 보장하지는 않습니다. `seen_count`는 초기값으로 기록되지만, 같은 항목을 찾아 증가시키는 dedup 로직은 아직 없습니다.
+
+---
+
+## 7. Wiki Boot Rules란 무엇인가요?
+
+`autoSearchEnabled`가 `true`이면 플러그인은 OpenCode 시스템 프롬프트에 자체 Wiki Boot Rules를 주입합니다.
+
+이 규칙은 다음 행동을 에이전트에게 알려줍니다.
+
+1. 문제를 풀기 전에 사용자 설명에서 키워드 2~3개를 뽑습니다.
+2. `wiki_search`로 로컬 위키를 검색합니다.
+3. 검색 결과는 참고자료로만 사용합니다.
+4. 문제를 해결한 뒤에는 `wiki_store`로 해결책을 저장합니다.
+5. 안정적인 항목은 `wiki_promote`로 `lesson`으로 승격합니다.
+
+이 규칙은 LLM Wiki 동작에 대해서만 기존 legacy Memory OS 지시를 대체합니다. 프로젝트 고유 규칙, 보안 제한, 사용자의 명시적 메모리 비활성화 요청은 덮어쓰지 않습니다.
+
+---
+
+## 8. 보안과 개인정보
+
+플러그인은 저장 전에 흔한 민감정보 패턴을 가립니다.
+
+예시:
+
+- OpenAI/Anthropic API 키
+- GitHub 토큰
+- Bearer 토큰
+- `password=...`, `api_key=...`, `secret=...` 형태의 값
+
+또한 검색 결과는 항상 untrusted reference boundary로 감싸집니다. 쉽게 말해, 위키에 저장된 문장을 에이전트가 “명령”으로 착각하지 않도록 안전 울타리를 두는 방식입니다.
+
+검색에서 제외되는 상태도 있습니다.
+
+- `rejected`
+- `superseded`
+- `needs-clarification`
+
+이 상태의 항목은 활성 참고 지식으로 사용하지 않습니다.
+
+---
+
+## 9. 좋은 사용 습관
+
+### 저장할 때
+
+좋은 요청:
+
+```text
+이 해결책을 다음에 재사용할 수 있게 요약, 원인, 해결 명령, 주의사항으로 저장해줘.
+```
+
+더 좋은 저장 내용:
+
+- 어떤 문제가 있었는지
+- 원인이 무엇이었는지
+- 정확히 어떤 조치를 했는지
+- 다음에 같은 문제가 나오면 먼저 확인할 것
+- 관련 태그
+
+### 검색할 때
+
+좋은 요청:
+
+```text
+이 TypeScript 타입 오류와 비슷한 항목이 LLM Wiki에 있는지 먼저 검색해줘.
+```
+
+검색 키워드는 짧고 구체적일수록 좋습니다.
+
+```text
+typescript generic type error
+docker compose volume
+opencode plugin cache
+```
+
+### 승격할 때
+
+`inbox/`는 임시 보관함에 가깝습니다. 여러 번 재사용했고 내용이 안정적이면 `lesson`으로 승격하세요.
+
+```text
+이 inbox 항목은 검증됐으니 lesson으로 승격해줘.
+```
+
+---
+
+## 10. 문제 해결 체크리스트
+
+### 플러그인 툴이 보이지 않을 때
+
+1. OpenCode를 재시작합니다.
+2. `opencode.json`의 `plugin` 배열에 `oh-my-llmwikimode` 또는 로컬 경로가 들어 있는지 확인합니다.
+3. npm 공개 전이라면 private GitHub 접근 권한 또는 로컬 경로가 올바른지 확인합니다.
+4. 개발 환경에서는 OpenCode package cache가 최신 코드와 동기화됐는지 확인합니다.
+
+### 검색 결과가 없을 때
+
+1. `~/Documents/llm-wiki/inbox/` 또는 `editorial/lessons/`에 Markdown 파일이 있는지 확인합니다.
+2. 항목의 frontmatter에 `title`이 있는지 확인합니다.
+3. 상태가 `rejected`, `superseded`, `needs-clarification`이면 검색에서 제외됩니다.
+4. 더 구체적인 키워드로 다시 검색합니다.
+
+### 저장이 중복되는 것 같을 때
+
+현재 구현은 명시적 저장 요청과 내부 오케스트레이션 프롬프트를 감지하면 자동 캡처를 건너뜁니다. 그래도 같은 실제 문제 설명을 여러 번 말하면 중복 항목이 생길 수 있으므로, 같은 시간대의 `inbox/` 파일을 확인하고 불필요한 항목은 `status: rejected`로 바꾸거나 정리하면 됩니다.
+
+### legacy `wiki/` 폴더가 보일 때
+
+새 기본 레이아웃은 `inbox/`, `problems/`, `editorial/lessons/`, `.system/index.json`입니다. 예전 `wiki/` 폴더는 migration 또는 fallback 이슈로만 취급하고, 새 저장은 플러그인 도구에 맡기는 것이 좋습니다.
+
+---
+
+## 11. 개발자 검증 명령
+
+패키지 루트는 다음입니다.
+
+```text
+plugins/oh-my-llmwikimode/
+```
+
+검증 명령:
+
+```powershell
+npm run verify
+```
+
+workspace 루트에서 실행할 때는 다음처럼 실행할 수 있습니다.
+
+```powershell
+npm --prefix plugins/oh-my-llmwikimode run verify
+```
+
+`npm run verify`는 테스트, 패키지 검증, 문서 검증, release dry-run, side-effect audit을 순서대로 실행합니다.
+
+---
+
+## 12. 현재 공개 배포 전 체크포인트
+
+아래 작업이 끝나야 일반 사용자에게 “한 줄 설치”를 안내할 수 있습니다.
+
+1. npm publish 승인
+2. repository secret `NPM_TOKEN` 추가
+3. repository variable `ENABLE_RELEASE=true` 설정
+4. semantic-release 성공 확인
+5. 공개 설치 명령 검증
+
+그 전까지는 “private/local 개발 설치”와 “추후 npm 공개 설치”를 반드시 구분해서 안내해야 합니다.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "oh-my-llmwikimode",
+  "version": "1.0.0",
+  "description": "LLM Wiki plugin for OpenCode — auto-memory, retrieval, and knowledge promotion",
+  "type": "module",
+  "main": "./src/server.js",
+  "bin": {
+    "llmwiki": "bin/llmwiki.js"
+  },
+  "exports": {
+    ".": "./src/server.js",
+    "./server": "./src/server.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "docs",
+    "scripts/install-llmwiki.ps1",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test test/**/*.test.js",
+    "test:loader": "node --test test/loader.test.js",
+    "test:hooks": "node --test test/hooks.test.js",
+    "test:paths": "node --test test/paths.test.js",
+    "test:storage": "node --test test/storage.test.js",
+    "test:security": "node --test test/security.test.js",
+    "verify:package": "node test/verify-package.test.js",
+    "verify:docs": "node test/verify-docs.test.js",
+    "verify:side-effects": "node scripts/side-effect-audit.js",
+    "prepublishOnly": "npm test",
+    "release:dry-run": "node scripts/release-dry-run.js",
+    "verify:runtime": "npm run test && npm run verify:package && npm run verify:docs && npm run release:dry-run && npm run verify:side-effects",
+    "verify:extension": "npm --prefix packages/oh-my-llmwiki-pack run verify",
+    "verify": "npm run verify:runtime && npm run verify:extension"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "llm",
+    "wiki",
+    "memory",
+    "knowledge-management"
+  ],
+  "author": "oh-my-llmwikimode",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wjdtmddn325-maker/oh-my-llmwikimode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wjdtmddn325-maker/oh-my-llmwikimode/issues"
+  },
+  "homepage": "https://github.com/wjdtmddn325-maker/oh-my-llmwikimode#readme",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.14.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.14.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.5",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
+    "semantic-release": "^25.0.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}