peach-wiki
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesepeach-wiki — LLM Wiki 지식 관리
peach-wiki — LLM Wiki 知识管理
Andrej Karpathy의 LLM Wiki 패턴을 적용한 단일 스킬.
코드 프로젝트와 옵시디언 노트 모두 동일한 구조()로 관리한다.
docs/wiki/基于Andrej Karpathy的LLM Wiki模式打造的单一技能。
代码项目与Obsidian笔记均采用相同结构()进行管理。
docs/wiki/자동 감지 로직
自动检测逻辑
스킬 호출 시 현재 디렉토리를 감지하여 모드를 결정한다.
.obsidian 존재 → 옵시디언 모드 (DRIFT 없음)
.git 존재 → code 모드 (DRIFT 활성)
둘 다 존재 → code 모드 우선
둘 다 없음 → 일반 모드 (DRIFT 없음, wiki는 정상 동작)감지 명령:
bash
ls -d .obsidian 2>/dev/null && echo "OBSIDIAN=true" || echo "OBSIDIAN=false"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"调用技能时,会检测当前目录以确定模式。
存在.obsidian → Obsidian模式(无DRIFT)
存在.git → 代码模式(DRIFT激活)
两者均存在 → 优先代码模式
两者均不存在 → 普通模式(无DRIFT,wiki可正常运行)检测命令:
bash
ls -d .obsidian 2>/dev/null && echo "OBSIDIAN=true" || echo "OBSIDIAN=false"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"wiki 저장 위치 (모든 프로젝트 동일)
wiki存储位置(所有项目一致)
[프로젝트 루트 또는 옵시디언 보관소]/
└── docs/wiki/
├── WIKI-AGENTS.md ← 운영 규칙 (세션 시작 시 먼저 읽기)
├── wiki-index.md ← 전체 위키 카탈로그
├── wiki-log.md ← 작업 타임라인 (append-only)
├── concepts/ ← 아키텍처 패턴·도메인 개념
├── entities/ ← 모듈·서비스·컴포넌트·인물·프로젝트
├── synthesis/ ← 데이터 흐름·의사결정·트레이드오프
├── sources/ ← 원본 문서 요약 (옵시디언 모드)
└── diagrams/ ← Mermaid 다이어그램[项目根目录或Obsidian仓库]/
└── docs/wiki/
├── WIKI-AGENTS.md ← 运行规则(会话开始时优先读取)
├── wiki-index.md ← 完整wiki目录
├── wiki-log.md ← 操作时间线(仅追加)
├── concepts/ ← 架构模式·领域概念
├── entities/ ← 模块·服务·组件·人物·项目
├── synthesis/ ← 数据流·决策·权衡
├── sources/ ← 原始文档摘要(Obsidian模式)
└── diagrams/ ← Mermaid图表오퍼레이션 선택
操作选择
사용자 요청을 보고 아래 5개 중 하나를 실행한다.
根据用户请求,从以下5种操作中选择执行。
INIT — 최초 설정
INIT — 初始设置
docs/wiki/WIKI-AGENTS.md当不存在时执行。
docs/wiki/WIKI-AGENTS.md1. preflight
1. 预检
bash
undefinedbash
undefined모드 감지
模式检测
ls -d .obsidian 2>/dev/null && echo "MODE=para" || echo "MODE=code"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"
ls -d .obsidian 2>/dev/null && echo "MODE=para" || echo "MODE=code"
ls -d .git 2>/dev/null && echo "GIT=true" || echo "GIT=false"
프로젝트 인덱스명 확정 (이후 모든 qmd 명령에 사용)
确定项目索引名称(后续所有qmd命令均使用)
QMD_INDEX=$(basename $(pwd))
echo "QMD_INDEX=$QMD_INDEX"
QMD_INDEX=$(basename $(pwd))
echo "QMD_INDEX=$QMD_INDEX"
qmd 상태 확인 (named index 기준)
检查qmd状态(基于命名索引)
qmd --index "$QMD_INDEX" status 2>/dev/null
- qmd 미설치 시:qmd가 미설치 상태입니다.
wiki는 동작하지만 qmd 설치 시 토큰 절약 + 검색 정확도가 크게 향상됩니다.
설치: npm install -g @tobilu/qmd
→ 설치 권고 후 wiki 생성은 계속 진행
- qmd 설치됨 → 해당 인덱스의 컬렉션 등록 여부 확인:
```bash
qmd --index "$QMD_INDEX" collection listqmd --index "$QMD_INDEX" status 2>/dev/null
- 未安装qmd时:当前未安装qmd。
wiki可正常运行,但安装qmd后可大幅提升Token节省效率与搜索准确率。
安装命令:npm install -g @tobilu/qmd
→ 提示安装后继续创建wiki
- 已安装qmd → 检查对应索引的集合是否已注册:
```bash
qmd --index "$QMD_INDEX" collection list2. qmd 컬렉션 등록 (qmd 설치 시)
2. qmd集合注册(已安装qmd时)
--index "$QMD_INDEX"~/.cache/qmd/$QMD_INDEX.sqlite~/.config/qmd/$QMD_INDEX.yml미등록 컬렉션이면 등록:
bash
undefined必须始终使用模式。
该标志会将数据库()与配置()与默认索引完全分离,不会影响其他项目·个人Obsidian集合。
--index "$QMD_INDEX"~/.cache/qmd/$QMD_INDEX.sqlite~/.config/qmd/$QMD_INDEX.yml若集合未注册则进行注册:
bash
undefinedcode 모드
代码模式
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.{ts,vue,md,sql,py,go,js}"
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.{ts,vue,md,sql,py,go,js}"
옵시디언 모드
Obsidian模式
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.md"
qmd --index "$QMD_INDEX" collection add . --name "$QMD_INDEX" --mask "**/*.md"
컨텍스트 설명 추가 (검색 품질 핵심)
添加上下文说明(搜索质量核心)
qmd --index "$QMD_INDEX" context add "qmd://$QMD_INDEX/" "프로젝트 한 줄 설명"
qmd --index "$QMD_INDEX" context add "qmd://$QMD_INDEX/" "项目一行说明"
인덱싱 (해당 인덱스의 컬렉션만 처리됨)
索引处理(仅处理对应索引的集合)
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed
> **격리 원리**: `--index` 지정 시 해당 인덱스에 등록된 컬렉션만 처리된다.
> 기본 `index.sqlite`에 등록된 다른 프로젝트·para 컬렉션은 전혀 영향받지 않는다.
> (공식 문서: "Use separate index for different knowledge base")
> **주의**: `--index` 없이 plain `qmd update/embed`를 실행하면 기본 인덱스의
> 전체 컬렉션(CloudStorage 경로 포함)이 처리된다. 반드시 `--index`를 붙여라.qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed
> **隔离原理**:指定`--index`时,仅处理该索引下注册的集合。
> 默认`index.sqlite`中注册的其他项目·para集合不会受到任何影响。
> (官方文档:"Use separate index for different knowledge base")
> **注意**:若不添加`--index`直接执行`qmd update/embed`,会处理默认索引的全部集合(包括CloudStorage路径)。请务必添加`--index`。3. 기존 wiki 마이그레이션
3. 现有wiki迁移
기존 위키 폴더 감지:
bash
ls -d .wiki 2>/dev/null && echo "기존 .wiki/ 발견"
ls -d 5-Wiki 2>/dev/null && echo "기존 5-Wiki/ 발견"발견 시 사용자에게 확인:
기존 [.wiki/ 또는 5-Wiki/]가 발견되었습니다.
docs/wiki/로 이동합니까? (기존 폴더는 백업 후 이동)
[Y/n]승인 시:
- 기존 폴더를 로 복사
docs/wiki/ - 기존 폴더 이름에 접미사 추가 (안전 백업)
.bak - wiki-index.md, WIKI-AGENTS.md 경로 업데이트
检测现有wiki文件夹:
bash
ls -d .wiki 2>/dev/null && echo "发现现有.wiki/"
ls -d 5-Wiki 2>/dev/null && echo "发现现有5-Wiki/"发现后向用户确认:
发现现有[.wiki/或5-Wiki/]。
是否移动至docs/wiki/?(现有文件夹将备份后移动)
[Y/n]用户确认后:
- 将现有文件夹复制至
docs/wiki/ - 为现有文件夹名称添加后缀(安全备份)
.bak - 更新wiki-index.md、WIKI-AGENTS.md的路径
4. docs/wiki/ 생성
4. 创建docs/wiki/
→ 기반으로 WIKI-AGENTS.md 생성
→ wiki-index.md, wiki-log.md 초기화
→ concepts/, entities/, synthesis/, sources/, diagrams/ 폴더 생성
references/WIKI-AGENTS-템플릿.md→ 基于生成WIKI-AGENTS.md
→ 初始化wiki-index.md、wiki-log.md
→ 创建concepts/、entities/、synthesis/、sources/、diagrams/文件夹
references/WIKI-AGENTS-템플릿.md5. AGENTS.md에 wiki 참조 규칙 추가
5. 在AGENTS.md中添加wiki参考规则
자리에프로젝트명실제 값을 삽입한다. (예:$QMD_INDEX,tang)peach-www
대상 프로젝트의 AGENTS.md에 아래 섹션 추가 ( → 실제 프로젝트명으로 치환):
프로젝트명undefined将替换为프로젝트명的实际值(例如:$QMD_INDEX、tang)peach-www
在目标项目的AGENTS.md中添加以下章节(将替换为实际项目名称):
프로젝트명undefinedwiki 참조 (필수)
wiki参考(必填)
코드 생성·분석 전 아래 순서를 따른다.
- 으로 wiki + 소스 통합 검색
qmd --index 프로젝트명 query "키워드" -c 프로젝트명 - qmd 미설치 시 → 관련 페이지 직접 Read
docs/wiki/wiki-index.md - 도 없으면 기존 방식대로 진행
docs/wiki/
代码生成·分析前请遵循以下顺序:
- 使用进行wiki + 源码联合搜索
qmd --index 项目名 query "关键词" -c 项目名 - 未安装qmd时,直接阅读→ 查找相关页面
docs/wiki/wiki-index.md - 若也不存在,则按原有方式进行
docs/wiki/
qmd 인덱스 (필수)
qmd索引(必填)
이 프로젝트의 qmd 인덱스명:
모든 qmd 명령에 을 붙인다.
plain 는 다른 프로젝트 인덱스를 오염시킬 수 있으므로 금지.
프로젝트명--index 프로젝트명qmd update/embed# 검색
qmd --index 프로젝트명 query "키워드" -c 프로젝트명
# 인덱스 갱신
qmd --index 프로젝트명 update && qmd --index 프로젝트명 embedundefined本项目的qmd索引名称:
所有qmd命令均需添加。
禁止直接执行,否则可能污染其他项目索引。
项目名--index 项目名qmd update/embed# 搜索
qmd --index 项目名 query "关键词" -c 项目名
# 更新索引
qmd --index 项目名 update && qmd --index 项目名 embedundefined6. 프로젝트 개요 페이지 생성
6. 创建项目概览页面
docs/wiki/entities/project-overview.md创建(了解项目结构后)
docs/wiki/entities/project-overview.md7. 사람에게 첫 ingest 영역 확인
7. 向用户确认首个ingest范围
8. wiki-log.md 기록
8. 记录至wiki-log.md
INGEST — Raw Source → 위키 추가
INGEST — 原始资源→添加至wiki
트리거: "ingest", "wiki에 추가", "문서화해줘", 파일/모듈 언급
触发关键词:"ingest"、"添加至wiki"、"帮我文档化"、提及文件/模块
절차
流程
-
소스 파악 — qmd 1순위, Read fallback:bash
# qmd 사용 가능 시 (1순위) — named index 필수 qmd --index "$QMD_INDEX" query "모듈명 또는 키워드" -c "$QMD_INDEX" # qmd 미사용 시 (fallback) # 직접 파일 Read -
요약 확인 — 핵심 3~5줄 요약 후 사람에게 확인
-
wiki 페이지 생성/업데이트:
- code: 모듈 → , API →
entities/module-이름.md, DB →entities/api-이름.mdentities/schema-이름.md - para: 노트 → , 인물 →
sources/YYYY-MM-DD-제목.md, 프로젝트 →entities/이름.mdentities/project-이름.md
- code: 모듈 →
-
concepts/ 업데이트 — 아키텍처 패턴, 도메인 개념 반영
-
related_files 경로 검증 (code 모드):
- qmd URI와 실제 파일 경로가 다를 수 있음 (하이픈 vs dot 등)
- related_files에 넣기 전 또는
ls으로 실제 존재 확인Glob - 존재하지 않는 경로는 제외하거나 정확한 경로로 수정
-
diagrams/ 생성 (필요 시) — Mermaid로 흐름 시각화
-
wiki-index.md 갱신 + wiki-log.md 기록
-
qmd 반영 (qmd 설치 시):
- 반드시 패턴 사용 — 다른 인덱스 오염 방지
--index "$QMD_INDEX" - 새 파일 추가·이동·대량수정:
bash
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed - 소규모 텍스트 수정:
bash
qmd --index "$QMD_INDEX" update - 변경 없으면 실행하지 않음
- 가 세션에 없으면:
$QMD_INDEX로 재선언QMD_INDEX=$(basename $(pwd))
- 반드시
-
确定资源 — 优先使用qmd,无则直接读取:bash
# 可使用qmd时(优先)——必须使用命名索引 qmd --index "$QMD_INDEX" query "模块名或关键词" -c "$QMD_INDEX" # 无法使用qmd时(备选) # 直接读取文件 -
确认摘要 — 提取3~5行核心内容摘要后向用户确认
-
创建/更新wiki页面:
- 代码模式:模块→,API→
entities/module-名称.md,数据库→entities/api-名称.mdentities/schema-名称.md - Obsidian模式:笔记→,人物→
sources/YYYY-MM-DD-标题.md,项目→entities/名称.mdentities/project-名称.md
- 代码模式:模块→
-
更新concepts/ — 反映架构模式、领域概念
-
验证related_files路径(代码模式):
- qmd URI与实际文件路径可能存在差异(如连字符vs点)
- 添加至related_files前,使用或
ls确认文件实际存在Glob - 不存在的路径需排除或修正为正确路径
-
创建diagrams/(必要时)——用Mermaid可视化流程
-
更新wiki-index.md + 记录至wiki-log.md
-
同步至qmd(已安装qmd时):
- 必须使用模式——防止污染其他索引
--index "$QMD_INDEX" - 新增文件/移动文件/大量修改:
bash
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed - 小规模文本修改:
bash
qmd --index "$QMD_INDEX" update - 无变更时无需执行
- 若会话中未设置,则重新声明:
$QMD_INDEXQMD_INDEX=$(basename $(pwd))
- 必须使用
페이지 형식
页面格式
yaml
---
tags: [wiki, entities|concepts|synthesis|sources|diagrams]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [소스 파일 경로]
related_files: [직접 연관된 파일] # code 모드
---yaml
---
tags: [wiki, entities|concepts|synthesis|sources|diagrams]
created: YYYY-MM-DD
updated: YYYY-MM-DD
sources: [源文件路径]
related_files: [直接关联的文件] # 代码模式
---제목
标题
한 줄 요약
一行摘要
핵심 내용
核心内容
연결된 위키 페이지
关联wiki页面
- [[관련 페이지]]
- [[相关页面]]
원본 소스
原始资源
경로/파일명
---路径/文件名
---QUERY — 위키 기반 질문 답변
QUERY — 基于wiki的问答
트리거: "어떻게 동작해?", "흐름 설명해줘", "~와 ~의 관계", "~에 대해 정리"
미선언 시:$QMD_INDEX로 재선언QMD_INDEX=$(basename $(pwd))
触发关键词:"它是如何工作的?"、"讲解流程"、"与的关系"、"整理一下~"
若未声明,则重新声明:$QMD_INDEXQMD_INDEX=$(basename $(pwd))
절차
流程
-
qmd 통합 검색 (1순위):bash
qmd --index "$QMD_INDEX" query "질문 내용" -c "$QMD_INDEX" -
wiki Read (fallback 또는 보강):
- 읽기 → 관련 페이지 파악
docs/wiki/wiki-index.md - 관련 위키 페이지 읽기
-
인용 포함 답변 — 출처: 파일 경로 (+ 줄 번호)
-
가치 있는 답변 → 위키에 환류 제안:
이 답변을 docs/wiki/synthesis/YYYY-MM-DD-주제.md로 저장할까요? -
wiki-log.md 기록
-
qmd联合搜索(优先):bash
qmd --index "$QMD_INDEX" query "问题内容" -c "$QMD_INDEX" -
读取wiki(备选或补充):
- 读取→ 定位相关页面
docs/wiki/wiki-index.md - 读取相关wiki页面
- 读取
-
带引用的回答 — 标注来源:文件路径(+行号)
-
建议将有价值的回答回流至wiki:
是否要将该回答保存至docs/wiki/synthesis/YYYY-MM-DD-主题.md? -
记录至wiki-log.md
DRIFT — git 변경 감지 후 위키 갱신
DRIFT — 检测git变更后更新wiki
트리거: "wiki 업데이트해줘", "변경사항 반영해줘"
code 모드(.git 존재)에서만 활성화.
미선언 시:$QMD_INDEX로 재선언QMD_INDEX=$(basename $(pwd))
触发关键词:"更新wiki"、"反映变更"
仅在代码模式(存在.git)下激活。
若未声明,则重新声明:$QMD_INDEXQMD_INDEX=$(basename $(pwd))
절차
流程
-
변경 파일 목록 추출:bash
git diff --name-only HEAD~1 # 마지막 커밋 git diff --name-only # 미커밋 변경 -
영향받은 위키 페이지 파악:
- 변경 파일의 를 가진 위키 페이지 검색
related_files
- 변경 파일의
-
위키 페이지 업데이트 — 변경 내용 반영,날짜 갱신
updated -
qmd 반영 (qmd 설치 시):bash
qmd --index "$QMD_INDEX" update -
새 모듈 감지 → 자동 INGEST 제안
-
wiki-log.md 기록
-
提取变更文件列表:bash
git diff --name-only HEAD~1 # 最后一次提交 git diff --name-only # 未提交的变更 -
定位受影响的wiki页面:
- 搜索包含变更文件的wiki页面
related_files
- 搜索包含变更文件
-
更新wiki页面 — 反映变更内容,更新日期
updated -
同步至qmd(已安装qmd时):bash
qmd --index "$QMD_INDEX" update -
检测新模块 → 建议自动执行INGEST
-
记录至wiki-log.md
LINT — 위키 점검
LINT — wiki检查
트리거: "wiki 점검", "lint", "문서 정합성 확인"
触发关键词:"检查wiki"、"lint"、"确认文档一致性"
점검 항목
检查项
- 드리프트 탐지 (code 모드): git log vs wiki updated 날짜 비교
- 고아 페이지: wiki-index.md에 없는 페이지
- 깨진 소스 링크: 삭제된 파일 참조 여부
- 모순: 같은 주제에 대해 다른 설명
- 미문서화 항목: 소스에는 있는데 위키 페이지 없는 것
- 템플릿 드리프트: WIKI-AGENTS.md가 최신 템플릿과 차이 여부
- 漂移检测(代码模式):对比git log与wiki的updated日期
- 孤立页面:未在wiki-index.md中列出的页面
- 失效源链接:是否引用已删除的文件
- 矛盾内容:同一主题存在不同描述
- 未文档化项:源码中存在但wiki无对应页面的内容
- 模板漂移:WIKI-AGENTS.md与最新模板是否存在差异
리포트 형식
报告格式
undefinedundefined[YYYY-MM-DD] lint | [프로젝트명]
[YYYY-MM-DD] lint | [项目名]
- 드리프트 위험: N개 페이지
- 고아 페이지: N개
- 깨진 링크: N개
- 미문서화: [목록]
- 권고: [조치 목록]
---- 漂移风险:N个页面
- 孤立页面:N个
- 失效链接:N个
- 未文档化:[列表]
- 建议:[操作列表]
---핵심 원칙
核心原则
- Raw Source는 절대 수정 금지 — 읽기만 (코드, 옵시디언 노트 모두)
- 하위에만 쓰기 — LLM 전용 공간
docs/wiki/ - qmd 1순위: 설치되어 있으면 항상 qmd query로 먼저 검색 (토큰 절약)
- 복리 효과: Ingest할수록 교차참조가 깊어지고 Query 품질이 높아짐
- 언어: 한국어 (코드·기술 용어는 영어 유지)
- 링크: Obsidian 형식 (para), 파일 경로 (code)
[[파일명]]
- 禁止修改原始资源 — 仅可读取(代码、Obsidian笔记均适用)
- 仅可写入docs/wiki/下 — LLM专用空间
- 优先使用qmd:若已安装,始终优先使用qmd query搜索(节省Token)
- 复利效应:Ingest次数越多,交叉引用越深入,Query质量越高
- 语言:韩语(代码·技术术语保留英文)
- 链接:Obsidian格式(Obsidian模式)、文件路径(代码模式)
[[文件名]]
qmd 주요 명령 참조
qmd主要命令参考
모든 명령에를 붙인다.--index "$QMD_INDEX"로 세션 시작 시 선언.QMD_INDEX=$(basename $(pwd))
bash
undefined所有命令均需添加。 会话开始时通过--index "$QMD_INDEX"声明。QMD_INDEX=$(basename $(pwd))
bash
undefined상태 확인
状态检查
qmd --index "$QMD_INDEX" status
qmd --index "$QMD_INDEX" collection list
qmd --index "$QMD_INDEX" status
qmd --index "$QMD_INDEX" collection list
하이브리드 검색 (권장)
混合搜索(推荐)
qmd --index "$QMD_INDEX" query "키워드" -c "$QMD_INDEX"
qmd --index "$QMD_INDEX" query "关键词" -c "$QMD_INDEX"
키워드 검색
关键词搜索
qmd --index "$QMD_INDEX" search "키워드" -c "$QMD_INDEX"
qmd --index "$QMD_INDEX" search "关键词" -c "$QMD_INDEX"
파일 경로만 출력
仅输出文件路径
qmd --index "$QMD_INDEX" query "키워드" -c "$QMD_INDEX" --files
qmd --index "$QMD_INDEX" query "关键词" -c "$QMD_INDEX" --files
특정 파일 읽기
读取特定文件
qmd --index "$QMD_INDEX" get "qmd://$QMD_INDEX/경로/파일.md"
qmd --index "$QMD_INDEX" get "qmd://$QMD_INDEX/路径/文件.md"
인덱스 갱신 (대량 변경)
更新索引(大量变更)
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed
qmd --index "$QMD_INDEX" update && qmd --index "$QMD_INDEX" embed
인덱스 갱신 (소규모 수정)
更新索引(小规模修改)
qmd --index "$QMD_INDEX" update
undefinedqmd --index "$QMD_INDEX" update
undefined