돌탑 위키 (Doltap Wiki)

AI 에이전트들이 함께 쌓고 함께 읽는 지식 베이스. 에이전트가 작업하며 배운 것을 위키에 남기고, 다음 에이전트가 그걸 읽고 시작합니다. 머신이 여러 대여도, 에이전트가 여러 종류여도 하나의 위키입니다.

English README · 에이전트용 설치 안내 · 1.0 로드맵

이런 분께

• Claude Code 같은 코딩 에이전트를 여러 프로젝트, 여러 머신에서 쓰는데, 같은 배포 절차나 같은 라이브러리 함정을 매번 다시 설명하고 있다면

• 에이전트가 알아낸 것을 어딘가에 남기고 싶은데 메모가 흩어지거나 금방 낡는다면

• 그 지식을 사람도 읽고 고칠 수 있는 형태(Markdown, git, Obsidian)로 두고 싶다면

Related MCP server: cardloom-mcp

3분 시작

Node 22.13 이상과 git이 필요합니다.

npm install -g doltap-wiki
doltap init --new --dir ~/.doltap --remote git@github.com:<내계정>/<위키저장소>.git   # 첫 머신: 미리 만든 빈 비공개 저장소
doltap integrations install claude                                                 # Claude Code에 연결
doltap schedule install                                                            # 10분마다 자동 sync (launchd / crontab / 작업 스케줄러)

다른 머신에서는 둘째 줄을 doltap init --repo <위키저장소 주소>로 바꿔 같은 네 줄을 실행하면 됩니다. 명령어는 doltap이고, wiki로 치고 싶으면 셸 설정에 alias wiki=doltap을 넣으세요.

설치가 귀찮다면 에이전트에게 시키세요. Claude Code 같은 에이전트에게 이렇게 말하면 됩니다.

https://github.com/bluekds/doltap-wiki/blob/main/docs/SETUP-FOR-AGENTS.md 읽고 이 머신에 돌탑 위키 설치해 줘

에이전트가 설치부터 연결, 검증까지 하고 결과를 보고합니다. 저장소 주소와 git 이름·이메일만 물어볼 겁니다.

에이전트에게 이렇게 말하세요

연결이 끝나면 새 세션부터 에이전트가 위키를 압니다. 따로 명령을 외울 필요 없이 평소처럼 말하면 됩니다.

에이전트는 아무 말이나 쌓지 못합니다. 카테고리 분류표, 템플릿, lint, 중복 감지가 쓰기 단계에서 작동하고, 비밀값은 저장이 거부됩니다. 규칙 전체는 위키 안의 _meta/PROTOCOL.md에 있고 에이전트가 자동으로 읽습니다.

사람은 이렇게 봅니다

• Obsidian: ~/.doltap/wiki를 vault로 열면(저장소 루트가 아니라 wiki/) 링크, 백링크, 그래프, 대시보드(Dataview)가 그대로 동작합니다. 설정이 들어 있어 플러그인 두 개(Dataview, Obsidian Git)만 설치하면 됩니다.

• 터미널: doltap search 배포, doltap get howto/deploy-pypi

• 그냥 파일: wiki/ 아래 Markdown이라 GitHub에서 바로 읽힙니다

어떻게 동작하나

• 페이지는 wiki/ 아래 Markdown, 저장소는 평범한 git. 이력·동기화·충돌은 git이 맡습니다.

• 다섯 카테고리가 각각 하나의 질문에 답합니다: howto(어떻게 하나) · patterns(어떻게 구현하나) · reference(무엇인가) · decisions(왜 이걸 골랐나) · projects(이 프로젝트의 맥락)

• 모든 페이지에 confidence: draft | verified | deprecated가 있어 에이전트가 얼마나 믿을지 압니다. 다른 머신에서 따라 해 보고 성공하면 wiki_verify로 근거와 함께 verified로 올립니다. 페이지를 만든 세션은 자기 페이지를 승격할 수 없습니다.

• 모든 쓰기는 pull → lint → commit → push를 자동으로 거칩니다. 충돌하면 상대 버전을 유지하고 내 버전을 <id>.conflict-<host>.md로 남깁니다. 오프라인이면 다음 sync에 push합니다.

• 검색은 Node 내장 SQLite의 전문 검색입니다. 임베딩도 벡터 DB도 없고, 서버가 모델을 호출하지도 않습니다. 판단은 에이전트가 하고, 돌탑은 저장·검색·검증·동기화만 합니다.

구조

flowchart LR
  subgraph A["Machine A (laptop)"]
    A1["Agent (Claude Code, ...)"] -->|"MCP stdio / CLI"| A2["doltap"]
    A2 --> A3[("wiki/ clone + SQLite index")]
    A4["Obsidian"] --- A3
  end
  subgraph B["Machine B (always-on)"]
    B1["Agent"] --> B2["doltap"]
    B2 --> B3[("wiki/ clone + index")]
    B4["doltap-mcp --http"] --> B3
  end
  A3 <-->|"git pull / push"| R[("git remote (private repo)")]
  B3 <-->|"git pull / push"| R
  C["claude.ai connector / Claude Code without a clone"] -->|"HTTPS, path token"| B4

쓰기 경로

모든 쓰기는 같은 경로를 지납니다. 중복이나 lint 오류는 commit 전에 거부되고, 충돌은 자동 병합하지 않습니다.

flowchart LR
  W["upsert / add"] --> P["pull --rebase"] --> D{"similar<br/>page?"}
  D -->|"no"| L["write + lint"] --> C["commit"] --> U["push"]
  D -->|"yes"| X["refused:<br/>edit that page"]
  L -->|"errors"| Y["refused:<br/>file restored"]
  P -->|"conflict"| K["keep upstream, save<br/>id.conflict-host.md"]
  U -->|"offline"| O["pushed on<br/>next sync"]

여러 머신, 원격 접속

• 머신마다 doltap init --repo …로 clone을 두면 같은 git 원격을 공유합니다. doltap schedule install이 10분마다 pull해서 읽기가 느린 네트워크에 막히지 않습니다.

• clone을 두기 싫은 머신(노트북, claude.ai 웹)은 원격 접속을 씁니다. 항상 켜 둔 머신에서 doltap serve install 후 Tailscale Funnel 같은 방법으로 HTTPS로 내면, 다른 머신은 doltap integrations install claude --remote <URL> 한 줄로 연결되고(Codex CLI, Cursor, Gemini CLI는 codex|cursor|gemini, 그 밖의 클라이언트는 generic으로 JSON 스니펫) claude.ai에는 커스텀 커넥터로 등록합니다. 보안 모델은 아래 "보안"을 보세요.

• 한 머신에 위키 둘(개인용과 팀용): 각자 다른 루트에 두고 두 번째는 다른 서버 이름으로 등록합니다. doltap --root ~/team-wiki integrations install claude --name doltap-team. Claude Code에 둘 다 보이고 skill과 지침 절은 공유합니다. CLI는 --root나 DOLTAP_ROOT로 위키를 고르고, 없으면 현재 디렉터리에서 위로 찾다가 ~/.doltap으로 갑니다.

• 충돌은 자동 병합하지 않습니다. doltap sync와 doltap audit가 충돌 파일을 알려 주면 두 버전을 합쳐 doltap resolve <id> --file merged.md(MCP는 wiki_resolve_conflict)로 마무리하면 복사본 삭제와 commit까지 됩니다. 태그 목록 _meta/tags.yaml만은 .gitattributes의 merge=union으로 자동 병합됩니다. 0.3.0 이전에 만든 위키는 .gitattributes에 wiki/_meta/tags.yaml merge=union 한 줄을 추가하세요.

관리자 에이전트 (선택)

위키는 쌓이기만 하면 지저분해집니다. 에이전트 하나에게 관리자 역할을 맡기세요. doltap init --new가 만든 howto/maintain-doltap-wiki 페이지에 세션 시작·주간·월간 루틴이 있고, 항상 켜 둔 머신의 Claude Code 세션에 이렇게 말하면 됩니다.

howto/maintain-doltap-wiki 읽고 일일·주간 작업을 이 세션에 예약해 줘

세션이 정해진 시각에 점검·검토하고 보고합니다. 페이지 폐기·삭제·병합은 제안만 하고 승인을 받습니다. 예약은 세션이 열려 있는 동안만 유지됩니다.

doltap search <query> [-c category] [-t tag] [-n limit] [--json]   # 텍스트 일치 → verified·최근 갱신·제목 일치 순
doltap get <id> [-s "Section"]
doltap list [-c category] [-t tag]
doltap related <id>
doltap index                              # 페이지당 한 줄
doltap template <category>
doltap add <category>/<slug> --title .. --summary .. --tags a,b [--file body.md | --stdin] [--force] [--replace --base-rev <rev>] [--review-by <days|date>]
doltap patch <id> -s "Section" (--content .. | --file .. | --stdin) [--append] [--create] [--base-rev <rev>]
doltap meta <id> [--add-source ..] [--add-tag ..] [--title ..] [--summary ..] [--review-by <days|date|none>]
doltap verify <id> --evidence ".." [--review-by ..]   # draft -> verified(만든 세션은 거부); 이미 verified면 재검토 기록(날짜만 이동, 본문·updated 유지)
doltap deprecate <id> --replaced-by <id>     # replaced_by, 배너, 허브 항목
doltap resolve <id> (--file merged.md | --stdin | --take conflict)   # *.conflict-<host>.md 정리
doltap tags [list] | tags add <tag> <description> [--group g] | tags remove <tag>
doltap assets [list] | assets add <id> <file> [--force]   # 첨부: wiki/_assets/<id>/에 복사·commit하고 붙여 넣을 링크 출력 (2 MB, 정해진 형식)
doltap history <id> [-n 20]               # 페이지를 바꾼 commit: 누가, 언제, 무엇을
doltap lint [ids...]
doltap sync                               # pull, 밀린 push, reindex, 읽기 통계 발행, 충돌 파일 목록, 로그 회전
doltap reindex [--full]
doltap audit [--unreferenced-days 90] [--review-days <n>] [--draft-days 30] [--report [--keep 12]]   # unreviewed·unreferenced·draft·고아·충돌·검색 miss; decisions/projects는 나이로 걸리지 않음; --report는 wiki/_meta/reports/<날짜>.md로 저장·commit
doltap golden [file]                      # wiki/_meta/golden.json의 쿼리마다 기대 페이지가 1위인지; 아니면 exit 1
doltap doctor [--healthz <url>] [--no-services] [--quiet]   # 유지보수 점검 전부: 실패가 있으면 exit 1
doltap upgrade [--diff] [--apply]         # 설치된 버전의 스켈레톤과 비교; 설정·템플릿 갱신, PROTOCOL은 diff만
doltap schedule install [--every <분>] [--force]|status|uninstall  # 주기적 sync (--every는 60 미만이거나 60의 배수; --force는 다른 위키용으로 설치된 작업을 교체)
doltap serve install [--show-url]|status|uninstall|token [--rotate] [--quiet]   # 상시 HTTP MCP 서비스
doltap serve client add <name> [--read-only] [--expires <days|date>] | list | extend <name> --expires … | remove <name>   # 이름 붙은 토큰: commit에 이름이 남음
doltap serve calls [--since 7] [-n 20]      # 어느 클라이언트가 어떤 도구를 불렀는지 (<상태 디렉토리>/logs/http-calls.log)
doltap integrations install|uninstall|status claude|codex|cursor|gemini|generic [--remote [<url>]] [--dry-run]   # --remote에 값을 빼면 $DOLTAP_REMOTE_URL을 읽음

전역 옵션 --root, --agent, --session, --no-sync, --json. 환경변수 DOLTAP_ROOT, DOLTAP_AGENT, DOLTAP_SESSION, DOLTAP_NO_SYNC=1, DOLTAP_AUTO_PULL_MINUTES(기본 10; 원격이 안 닿을 때 push를 건너뛰는 시간이기도 함), DOLTAP_REMOTE_TIMEOUT_MS(pull/push 한 번의 상한, 기본 15000), DOLTAP_REMOTE_URL, DOLTAP_HTTP_ALLOWED_HOSTS, DOLTAP_DEFER_PUSH=0(HTTP 서버의 백그라운드 push 끄기).

doltap doctor는 관리자 루틴의 시작 점검(저장소 상태, 스케줄러와 HTTP 서비스, 마지막 pull 시각, tags.yaml, lint, 색인, 토큰 파일 권한, 로그 크기, 설치된 skill 버전)을 한 번에 돌리고 고칠 명령을 함께 보여 줍니다. 읽기 전용입니다.

doltap audit는 모든 머신의 읽기 통계(wiki/_meta/stats/<host>.json, sync가 6시간에 한 번 발행)를 합쳐서 재검토가 밀린 페이지(unreviewed: review_by가 지났거나, 없으면 reference 180일·howto 365일 안에 재검증이 없는 페이지), 아무도 읽지 않는 페이지(unreferenced: 폐기 목록이 아니라 허브 항목·제목·태그를 손볼 발견성 점검), 오래 머문 draft, 고아 페이지, 아직 링크되는 deprecated 페이지, 충돌 파일을 보고합니다. decisions/와 projects/는 나이로는 어떤 목록에도 오르지 않습니다. 이 머신의 검색 로그(.doltap/index.sqlite에만 남고 git에는 올라가지 않음)에서 검색 직후 15분 안에 연 페이지가 1위가 아니었던 쿼리도 함께 보여 줍니다. 제목이나 요약을 고치거나 페이지를 추가할 단서입니다.

검색 순위는 FTS5 bm25(제목·요약·태그를 본문보다 가중)에 작은 계수를 곱합니다. verified ×1.1, deprecated는 ×0.5에 항상 마지막, 30일 안에 만들거나 검증한 페이지 ×1.05(오래됐다고 감점하지는 않고, decisions/projects에는 적용하지 않음), 쿼리 단어가 제목에 있으면 최대 ×1.15. 계수는 근소한 차이만 가르고 명확한 텍스트 일치를 뒤집지 않습니다. wiki/_meta/golden.json에 [{"query", "expect"}]를 두면 doltap golden이 기대 페이지가 1위인지 확인합니다.

MCP 도구

리소스: wiki://protocol, wiki://index, wiki://tags. 모든 도구의 파라미터·기본값·제약은 서버 스키마에서 생성한 docs/TOOLS.md에 있습니다(npm run reference; 오래되면 CI가 실패).

• 원격 접속을 보호하는 것은 경로에 들어가는 64자리 무작위 토큰 하나입니다. OAuth는 아직 없습니다. URL이 새면 위키 전체를 읽고 쓸 수 있으니 토큰은 doltap serve token으로만 확인하고 채팅이나 문서에 붙여 넣지 마세요. 새면 doltap serve token --rotate --quiet로 교체합니다. 실행 중인 서비스가 몇 초 안에 새 토큰을 읽어 옛 토큰은 바로 막히고, 원격 클라이언트만 새 URL로 다시 등록하면 됩니다. CLI 출력은 토큰을 가리고(serve install은 --show-url이 없으면 <token>으로 표시), integrations install --remote는 URL을 DOLTAP_REMOTE_URL에서 읽어 셸 히스토리에 남기지 않으며, lint는 커넥터 URL이 든 페이지를 거부합니다.

• 서버는 Host로 루프백, 바인드 주소, *.ts.net만 받고(추가는 DOLTAP_HTTP_ALLOWED_HOSTS), 요청 본문은 2 MiB까지만 받으며, 오류는 일반 문구만 돌려주고 상세는 서비스 로그에 남깁니다.

• 페이지 id는 모든 경로에서 검증되므로(<category>/<slug> 문자만 허용) 요청이 wiki/ 밖의 파일을 가리킬 수 없습니다. 루트 아래 어디에 있든 심볼릭 링크는 읽기도 쓰기도 따라가지 않습니다. 경로의 모든 구성 요소를 검사합니다(페이지, _meta의 템플릿·프로토콜·태그·리포트·통계, 첨부). 공유 원격을 통해 커밋된 링크가 서비스 머신의 임의 파일을 읽거나 덮어쓰게 만들 수 있기 때문입니다. 생성 파일인 _meta/index.md는 일반 파일로 다시 만들고, 나머지는 거부하며, lint가 트리의 모든 링크를 보고합니다.

• 머신 전용 상태(검색 인덱스, 쓰기 락, sync 상태, HTTP 토큰, 클라이언트 목록, 로그)는 클론 밖 ~/.local/state/doltap/<wiki-id>/($XDG_STATE_HOME; Windows는 %LOCALAPPDATA%\doltap\state\)에 있어, 공유 원격으로 들어온 파일이 이 머신의 토큰이나 클라이언트 목록이 될 길이 없습니다. 클론 안의 .doltap/은 0.x의 잔재로, 한 번 옮겨진 뒤에는 doltap sync와 doctor가 보고만 하고 읽지 않습니다. 경로는 doltap doctor가 보여 주며 DOLTAP_STATE_HOME / DOLTAP_STATE_DIR로 옮길 수 있습니다.

• 위협 모델, 신뢰 경계, 지난 감사에서 나온 것과 고친 것, 릴리스를 직접 감사하는 방법은 docs/SECURITY-AUDIT-SCOPE.md에 있습니다.

• 서비스는 기본으로 127.0.0.1에만 바인딩합니다. 인터넷에 내는 것은 Tailscale Funnel 같은 바깥 계층의 선택입니다.

• 위키 내용은 git 이력에 영구히 남고, 에이전트가 읽은 페이지는 그 에이전트의 모델 제공사로 전송됩니다. 비밀값을 적지 않는 이유입니다.

• 원격으로 쓴 commit은 서버 머신 이름과, 이름 붙은 토큰(doltap serve client add <name>)을 쓰면 그 이름으로 기록됩니다. --read-only 토큰은 검색과 읽기만 되고, --expires로 만료일을 두면 그날 이후 404입니다(doctor가 일주일 전에 경고). 세션은 MCP 세션 id 단위([session:<client>/<id>])라 페이지를 만든 대화가 그 페이지를 verify할 수 없습니다. 서버는 요청마다 시간·클라이언트·도구·상태를 상태 디렉토리의 logs/http-calls.log에 남기며 인자나 토큰은 기록하지 않습니다(doltap serve calls). 쓰기 응답은 commit 직후 돌아오고 push는 뒤에서 이어집니다.

이것은 무엇이 아닌가

• 코드베이스 문서를 LLM이 자동 생성하는 도구가 아닙니다(그 용도는 OpenWiki 같은 프로젝트가 맞습니다). 돌탑은 에이전트가 작업 중에 직접 쓰는 운영 지식용입니다.

• 임베딩이나 벡터 DB를 쓰지 않습니다. 전문 검색과 링크 구조로 충분한 규모를 목표로 합니다.

• 서버가 모델을 호출하지 않습니다. 판단은 에이전트가 하고, 돌탑은 저장, 검색, 검증, 동기화만 합니다.

배지

돌탑 위키로 관리하는 위키나 프로젝트의 README에 아래를 붙이면 배지가 표시됩니다.

<a href="https://github.com/bluekds/doltap-wiki"><img src="https://raw.githubusercontent.com/bluekds/doltap-wiki/main/static/badge-seal.png" width="120" alt="Managed with Doltap Wiki"></a>

로고와 배지 원본은 static/에 있습니다(MIT).

개발

npm ci && npm run build && npm test
npm link -w doltap-wiki            # 이 체크아웃의 `doltap`, `doltap-mcp`를 전역으로
git tag -a v1.2.3 -m 1.2.3 && git push origin v1.2.3   # 릴리스: Publish 워크플로가 테스트 후 core, mcp, cli를 provenance 붙여 publish

릴리스는 GitHub Actions의 npm trusted publishing(.github/workflows/publish.yml)으로 나갑니다. main 위의 v* 태그(버전이 패키지와 일치해야 함)가 전체 테스트를 돌리고 세 패키지를 --provenance로 publish한 뒤 레지스트리 확인과 클린 설치까지 합니다. npm 토큰이나 OTP는 쓰지 않으며, npmjs.com의 각 패키지에 이 저장소와 워크플로가 trusted publisher로 등록돼 있습니다. 워크플로를 수동 실행(dry_run)하면 업로드만 빼고 리허설합니다. npm run publish:all(tools/publish.sh)은 수동 대체 수단으로 남겨 둡니다.

MCP 도구는 docs/TOOLS.md에, CLI 명령과 플래그는 docs/CLI.md에 전부 문서화돼 있습니다. 둘 다 코드에서 생성하며(npm run reference) 어긋나면 CI가 실패합니다.

패키지: @bluekds/doltap-core(파서, lint, 검색, git 동기화, 스캐폴드), @bluekds/doltap-mcp(MCP 서버), doltap-wiki(CLI와 두 실행 파일 doltap, doltap-mcp). CI는 macOS, Linux, Windows에서 빌드와 테스트, 빈 위키 생성까지 확인합니다.

라이선스

MIT