lemoncloud-io/doki / projects/knowledge-viewer/config/skills/knowledge-viewer-open
knowledge-viewer-open
Unverified"뷰어로 보여줘 <경로>"·"<문서> 렌더해서 보여줘"·"볼트 뷰어 열어줘"·"knowledge viewer"· "지도로 보여줘 <경로>"·"연결 그래프 보여줘" 같은 요청에 볼트 읽기 뷰어(projects/knowledge-viewer)를 띄우고 요청한 문서를 브라우저 패널에서 연다. 서버는 launch.json 항목 knowledge-viewer(8778)로 올리고, 주소는 /v/<path>?agent=claude&src=local#<anchor>. "PR #n 보여줘 [경로]"·"PR n 리뷰 모드로 열어줘"면 src=pr:<n> 으로 그 PR 의 볼트를 연다. 뷰어에 등록된 앱을 열 때는 GET /api/apps 의 title 로 id 를 찾아 앱 화면 /apps/<id> 를 연다. 원본 문서를 고치지 않는다. private/는 로컬 기본값으로 보이고, 숨기는 것은 사용자가 시킬 때만이다.
knowledge-viewer-open (볼트 뷰어 열기)
볼트 문서를 위키링크·역링크·호버 미리보기가 있는 화면으로 보여 주는 스킬이다. 앱(서버·SPA)의
구조와 실행 명령은 projects/knowledge-viewer/README.md § Current Context가 정본이고, 이 스킬은
띄워서 여는 절차만 갖는다.
트리거
- "뷰어로 보여줘 wiki/INDEX.md" · "이 문서 렌더해서 보여줘" · "볼트 뷰어 열어줘" · "knowledge viewer"
- 경로를 말하지 않으면
wiki/INDEX.md를 연다. 문서 이름만 말하면 볼트에서 경로를 찾아 연다. - 앵커가 붙는 말("… 의 '설정' 절")이면 슬러그를
#뒤에 붙인다. - "지도로 보여줘 wiki/INDEX.md" · "연결 그래프 보여줘" — 그 문서를 중심으로 한 연결 지도(그래프 뷰)를
연다. 경로를 말하지 않으면
wiki/INDEX.md가 중심이다. § 절차 5의 주소에&view=graph를 붙인다 (§ 주소 계약). 반경·2D·전체 보기를 말하면depth·mode·all질의 인자로 옮긴다. - "PR #n 보여줘 [경로]" · "PR n 리뷰 모드로 열어줘" — PR 리뷰 모드. § 절차 1~4는 같고, 5의 주소만 다르다.
에이전트 모드는 트리와 오른쪽 열(PR 상세 패널)을 그리지 않으므로 바뀐 파일은 API 로 고른다.
- (a) 경로를 말했으면 →
http://127.0.0.1:8778/v/<path>?agent=claude&src=pr:<n>#<anchor>로navigate. - (b) 경로가 없으면 →
GET http://127.0.0.1:8778/api/pr/<n>/changes를 읽는다. JSON 의files[]에서path가.md로 끝나고status가D가 아닌 첫 항목을 골라 (a)처럼 연다. 그런 파일이 없으면 "이 PR 에 바뀐 md 가 없다"고 알리고 끝낸다. - (c) 실패(
gh미로그인·origin원격 없음·없는 PR) → 본문 자리에 사유가 안내 문구(p.notice)로 뜬다./api/pr/<n>/changes는 503 과error한 줄을 준다. 그 사유를 그대로 사용자에게 전한다. - (d) 사람이 PR 상세 패널·트리 배지를 보려면 같은 주소에서
agent=claude를 뺀 주소를 연다. 패널 머리줄의 닫기(×,data-action="exit-pr")는 같은 문서를 main 소스로 돌려 연다.
- (a) 경로를 말했으면 →
- 등록된 앱이 있으면 — "<앱 이름> 열어줘"처럼 뷰어 앱을 말할 때 — 앱 화면
/apps/<id>를 연다. § 절차 1~4는 같고, 5의 주소만 다르다.- id 는
GET http://127.0.0.1:8778/api/apps의apps[]에서title로 찾는다. 맞는 앱이 없으면 그렇게 알리고 끝낸다. - 에이전트가 읽을 때 →
http://127.0.0.1:8778/apps/<id>?agent=claude. 사람에게 보일 때는agent를 뺀다(기존 규칙). - 화면 상태는 앱 해시다. 뷰어는 해시를 앵커로 읽지 않는다.
ready: false면reason을 그대로 전한다. - 볼트가 앱별 여는 말·단독 실행 안내를 자기 스킬로 두었으면(볼트 확장 층
projects/knowledge-viewer/ext/) 그 스킬이 이 절차를 쓴다.
- id 는
하지 않는 것
- 원본 md를 수정하지 않는다. 뷰어는 읽기 전용이다.
private/를 임의로 숨기지 않는다. 로컬 기본값은 표시이고(사용자 결정 2026-10-23), 숨김(--hide-private)은 사용자가 시킬 때만이다.- Artifact로 게시하지 않는다. 볼트 문서는 내부 자료이고 이 뷰어는 로컬 전용이다.
- 기존 서버 프로세스를 죽이지 않는다. 포트 충돌은 § 폴백 A로 푼다.
절차
- 볼트 루트 확인.
VAULT_DIR또는 현재 작업 디렉터리(VAULT_RULES.md·wiki/·projects/가 있는 곳). 열 파일이 볼트 안에 있는지 확인한다. 볼트 밖 파일은 열지 않는다. - 개인 주소(설정한 사람만). 볼트에
projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs가 없으면 3으로 간다. 있으면 볼트 루트에서 부른다.--path에는 5의/v/…경로를 질의·#앵커째 넣는다.
JSON 한 줄node projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs url --app knowledge-viewer \ --path '<5의 /v/… 경로 — 질의·#앵커 포함>' --fallback http://127.0.0.1:8778{"url":"…","via":"name"|"fallback","reason":"…"}이 나온다(이름이 여럿이면"candidates":[…]도). 이 도구는 그 사람의 기계 로컬 파일만 읽는다. 이름은 사람마다 다르다. 스킬과 커밋하는 문서에는 이름을 적지 않는다.via가fallback이면 3으로 간다. 지금 절차 그대로다.via가name이면 후보마다 같은 볼트인지 견준다. 후보는candidates(있으면 그 순서)이고, 없으면url하나다.--path는 주소마다 그대로 붙어 있다. 상시 서버는 볼트마다 하나이고 볼트 루트 하나(그 볼트의 주 체크아웃)만 낸다. 워크트리 세션은 자기 작업 트리를 봐야 한다(src=local은 에이전트가 고친 것이다).
그 서버node projects/knowledge-viewer/config/app/same-vault.ts '<후보 주소>'/api/info의rootId와 이 세션 볼트 루트(VAULT_DIR, 정식 경로)의rootId를 견준다.rootId는 볼트 루트 폴더의 지문이다(경로가 아니다). JSON 한 줄{"same":…,"port":…,"reason":"…"}이 나온다.same이true인 첫 후보로navigate한다. 남은 후보는 견주지 않는다. 3·4는 건너뛴다. 그 사람의 상시 서버가 답한다. 5의tabs_select와 6의 확인은 같다. PR (b)처럼 경로를 API 로 고르면 먼저--path /v/로 출처를 정하고, API 도 그 출처에 묻는다.- 모든 후보가
same: false면(다른 폴더,rootId없음, 못 읽음) 이름을 쓰지 않는다. 3부터 그대로 한다. 어느 후보의port가 3의 포트(기본 8778)와 같으면 그 포트는 상시 서버 것이다. 그때는 § 폴백 A처럼 다른 포트 항목으로 띄운다. 같은 포트로preview_start하면 작업 트리가 아니라 상시 서버의 폴더가 보인다.
- launch.json 항목.
.claude/launch.json은 기계 로컬(gitignored)이다.knowledge-viewer항목이 없으면 추가한다.{ "name": "knowledge-viewer", "runtimeExecutable": "node", "runtimeArgs": ["projects/knowledge-viewer/config/app/start.ts"], "port": 8778 } - 서버 올리기.
preview_start {name: "knowledge-viewer"}. 이미 떠 있으면 재사용된다. 시작할 때 볼트 전체를 색인하므로(이 볼트에서 약 14초) 서버가 주소를 찍기까지 시간이 걸린다.http://127.0.0.1:8778/api/tree?dir=가 200을 줄 때까지 기다린다(최대 60초, 1~2초 간격 폴링). - 열기.
navigate→http://127.0.0.1:8778/v/<path>?agent=claude&src=local#<anchor>(앵커가 없으면#…생략).src=local을 명시한다. 화면은src가 없으면main(origin/master)을 보이는데, 이 스킬은 에이전트가 고친 작업 트리를 보여야 한다. PR 리뷰 모드면src=pr:<n>이다(§ 트리거).localhost가 아니라127.0.0.1로 연다. 화면과/api는127.0.0.1에서만 열리고,localhost요청은/·/v/*가 302로 넘어가며/api는 404다. 이어서tabs_select로 탭을 앞으로 가져온다. 패널이 숨김 상태면 "패널 표시를 켜 달라"고 한 줄 덧붙인다. - 확인.
read_console_messages onlyErrors가 비어 있고 본문이 보이면 끝이다. 사용자에게 주소 한 줄을 알린다. 문서 안 요소는data-vault-path속성으로 집을 수 있다.
주소 계약
| 열 대상 | 주소 | 비고 |
|---|---|---|
| md 문서 | /v/<path>#<slug> | 슬러그는 제목의 github-slugger 값 |
| html 산출물 | /v/<path>#<안쪽 라우트> | 에이전트 모드에서는 원본 주소로 자동으로 건너뛴다. local은 localhost:8778/raw/<path>#…, src=main·src=pr:<n>은 git 포트 localhost:8779/raw/@main/<path>#…·localhost:8779/raw/@pr/<n>/<path>#… |
| 프로젝트 뷰어(viewer.yml) | /v/<project>/config/viewer.yml#/p/<페이지>/<항목> | 통합 보기 — 셸 화면을 iframe 없이 이 화면 안에 그린다(빌드 불필요). 해시는 셸 라우트(#/glossary/<용어>·#/docs·#/search/<질의>), #L12는 원문. 사람 모드만이고 에이전트 모드는 원문이다 |
| 폴더 | /v/<dir>/README.md | 폴더 색인이 없으면 트리에서 연다 |
| 홈 | / 또는 /v/ | wiki/INDEX.md |
| 연결 지도(3D) | /v/<path>?view=graph | 그 문서가 중심. 질의 인자 depth=1|2|3(반경), mode=2d|3d, all=1(볼트 전체) |
| 연결 지도(텍스트 목록) | /v/<path>?agent=claude&src=local&view=graph | 같은 데이터의 목록. 항목에 data-vault-path가 붙는다. 지도 데이터는 소스와 무관하게 작업 트리 색인이고, src는 항목 링크가 싣는다 |
| 소스 | ?src=local|main|pr:<n> | 화면 기본은 main. 이 스킬은 local, PR 리뷰는 pr:<n>. html 원본은 /raw/@main/<path>·/raw/@pr/<n>/<path> 접두(local 은 접두 없음) |
| 질의 순서 | ?agent=claude&src=…&view=graph&depth=…&mode=…&all=1 | 기본값(src=main·view=doc·depth=2·mode=3d)은 쓰지 않는다 |
| 앱 화면 | /apps/<id>?agent=claude#<앱 해시> | 가운데 열 전체가 앱이다. 등록된 앱과 그 id 는 GET /api/apps 가 준다. 해시는 앱 것이다. 앱 API 는 /api/apps/<id>/…(토큰 필요) — 스킬이 직접 부르지 않는다. 목록은 GET /api/apps |
?agent=claude는 에이전트 모드다. 검색 상자가 숨고data-vault-path가 붙으며, iframe 안은 읽을 수 없으므로 html은 원본 주소(/raw/)로 연다.- html은 사람 모드에서 샌드박스 iframe(
allow-scripts allow-same-origin allow-popups)으로 열린다. iframe 출처는localhost이고/raw/만 받는다. git 소스(main·pr:<n>)의 html은 git 포트 (기본 주 포트 + 1 = 8779) 출처에서 열린다. 그 출처는/raw/@main/…·/raw/@pr/<n>/…만 낸다. - 경로의 공백·한글은
encodeURI로 인코딩한다. - 연결 지도는 3D 라이브러리를 늦게 불러온다. 에이전트가 위치를 집어야 하면
agent=claude로 연다(캔버스 대신 텍스트 목록이 나온다). 사람에게 보여 줄 때는agent=claude를 뺀다.
폴백
- A. 8778 포트가 다른 프로세스에 잡혀 있다 —
knowledge-viewer-2항목을--port 8780으로 등록한다. 기존 프로세스는 죽이지 않는다. git 소스 출처 포트는 8781이 된다. 8779(git 포트)만 잡혀 있어도 서버는 시작하지 않는다. 그때는--git-port <빈 포트>를 더한다.
이때 주소의 포트도 8780으로 바꾼다. (8770은 macOS{ "name": "knowledge-viewer-2", "runtimeExecutable": "node", "runtimeArgs": ["projects/knowledge-viewer/config/app/start.ts", "--port", "8780"], "port": 8780 }sharingd가 쓰므로 기본값으로 쓰지 않는다.) - B.
node_modules나dist가 없다 — 첫 실행에서start.ts가 의존성을 설치하고 빌드한다. 평소보다 오래 걸린다고 사용자에게 한 줄 알린다. 설치에 실패하면 출력의 오류를 그대로 전한다. - C. 브라우저 패널 도구가 없다 — 서버를 터미널로 띄우는 명령
(
node projects/knowledge-viewer/config/app/start.ts)과 주소http://127.0.0.1:8778/v/<path>를 알려 주고 끝낸다. - D. 문서가 안 열린다(404) — 서버가
--hide-private(또는KNOWLEDGE_VIEWER_HIDE_PRIVATE=1)로 떠 있으면private/아래가 숨겨진다. 사용자가 원하면 그 플래그 없는 항목으로 다시 띄운다. 시키지 않았으면 이유만 알린다.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |