Skip to content

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 소스로 돌려 연다.
  • 등록된 앱이 있으면 — "<앱 이름> 열어줘"처럼 뷰어 앱을 말할 때 — 앱 화면 /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/) 그 스킬이 이 절차를 쓴다.

하지 않는 것

  • 원본 md를 수정하지 않는다. 뷰어는 읽기 전용이다.
  • private/를 임의로 숨기지 않는다. 로컬 기본값은 표시이고(사용자 결정 2026-10-23), 숨김(--hide-private)은 사용자가 시킬 때만이다.
  • Artifact로 게시하지 않는다. 볼트 문서는 내부 자료이고 이 뷰어는 로컬 전용이다.
  • 기존 서버 프로세스를 죽이지 않는다. 포트 충돌은 § 폴백 A로 푼다.

절차

  1. 볼트 루트 확인. VAULT_DIR 또는 현재 작업 디렉터리(VAULT_RULES.md·wiki/·projects/가 있는 곳). 열 파일이 볼트 안에 있는지 확인한다. 볼트 밖 파일은 열지 않는다.
  2. 개인 주소(설정한 사람만). 볼트에 projects/local-nginx-proxy/config/local-nginx-proxy/render.mjs가 없으면 3으로 간다. 있으면 볼트 루트에서 부른다. --path에는 5의 /v/… 경로를 질의·#앵커째 넣는다.
    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
    
    JSON 한 줄 {"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하면 작업 트리가 아니라 상시 서버의 폴더가 보인다.
  3. launch.json 항목. .claude/launch.json은 기계 로컬(gitignored)이다. knowledge-viewer 항목이 없으면 추가한다.
    { "name": "knowledge-viewer", "runtimeExecutable": "node",
      "runtimeArgs": ["projects/knowledge-viewer/config/app/start.ts"], "port": 8778 }
    
  4. 서버 올리기. preview_start {name: "knowledge-viewer"}. 이미 떠 있으면 재사용된다. 시작할 때 볼트 전체를 색인하므로(이 볼트에서 약 14초) 서버가 주소를 찍기까지 시간이 걸린다. http://127.0.0.1:8778/api/tree?dir= 가 200을 줄 때까지 기다린다(최대 60초, 1~2초 간격 폴링).
  5. 열기. 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로 탭을 앞으로 가져온다. 패널이 숨김 상태면 "패널 표시를 켜 달라"고 한 줄 덧붙인다.
  6. 확인. 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 <빈 포트>를 더한다.
    { "name": "knowledge-viewer-2", "runtimeExecutable": "node",
      "runtimeArgs": ["projects/knowledge-viewer/config/app/start.ts", "--port", "8780"], "port": 8780 }
    
    이때 주소의 포트도 8780으로 바꾼다. (8770은 macOS 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/ 아래가 숨겨진다. 사용자가 원하면 그 플래그 없는 항목으로 다시 띄운다. 시키지 않았으면 이유만 알린다.
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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 319kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 319kUpdated Claude CodeCodexVerifiedInstall