wikigraph3d

KO | EN

gitlite — search

#react #typescript #golang #go #linux #macos #java #windows #awesome #cli #awesome-list #security #pytorch #mcp

(★ 10)

Point it at a folder of documents -> get a single 3D searchable knowledge-graph HTML file. No server, no API key.

wikigraph3d 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# wikigraph3d

문서 폴더 하나를 지정하면 **HTML 파일 하나**로 결과가 나옵니다 —
그 폴더 안 문서들이 서로 어떻게 연결돼 있는지 3D로 보여주는 검색 가능한 지식 그래프입니다.
기본 입구는 브라우저 GUI입니다. 설치 후 `wikigraph3d`를 실행하면 로컬 화면이 열리고,
거기서 폴더를 선택해 작업을 시작합니다.
Ollama를 쓰는 사람은 로컬 AI 검색과 문서 요약/태그를 선택적으로 붙일 수 있습니다.

## 제일 쉬운 시작: Windows 초보자용

Node.js가 설치되어 있는지 모르겠다면 PowerShell에서 아래 한 줄만 실행하세요.
Node.js/npm/npx 설치 여부를 확인하고, 없으면 Node.js LTS 설치를 도와준 뒤 `wikigraph3d` GUI를 엽니다.

```
powershell -ExecutionPolicy Bypass -NoProfile -Command "irm https://raw.githubusercontent.com/cdsassj00/wikigraph3d/master/scripts/start-wikigraph3d.ps1 | iex"
```

이 방식이 부담스럽다면 직접 설치해도 됩니다.

```
winget install --id OpenJS.NodeJS.LTS -e --source winget
npx --yes github:cdsassj00/wikigraph3d#master
```

환경 확인만 하고 싶을 때는 `--doctor`를 붙입니다. 이 명령은 GUI를 열거나 문서를 읽지 않고,
Node.js/npm/npx/Ollama 상태만 확인한 뒤 종료합니다.

```
npx --yes github:cdsassj00/wikigraph3d#master --doctor
```

## 이미 Node.js가 있는 사용자

```
npm install -g github:cdsassj00/wikigraph3d
wikigraph3d
```

브라우저에서 폴더 선택 버튼을 누르면 지원하는 문서를 읽고, 결과 그래프를 새 HTML로 열어줍니다.
개발자나 자동화용으로는 기존처럼 `wikigraph3d <폴더>` CLI도 계속 쓸 수 있습니다.

## 뭘 해주나요

1. **로컬 GUI를 엽니다** — 명령어에 폴더를 안 주면 `127.0.0.1`에서 브라우저 작업 화면이 뜹니다.
2. **폴더를 선택합니다** — `.md`, `.txt`, `.pdf`, `.docx`, `.pptx`를 하위 폴더까지 다 찾습니다.
3. **각 파일에서 텍스트를 추출**합니다 (전부 순수 JS로 처리 — 외부 서버로 업로드하지 않습니다).
4. **문서끼리 3가지 방식으로 자동 연결**합니다:
   - 마크다운에 `[[위키링크]]`(옵시디언 스타일) 문법을 이미 쓰고 있다면 그 링크
   - 같은 하위 폴더 안에 있는 문서끼리 (원형으로 얇게 연결 — "같이 정리해둔 것들"이 그래프에서도 뭉쳐 보이게)
   - 겹치는 핵심 단어가 많은 문서끼리 (자체 내장 TF-IDF 키워드 비교 — 별도 API나 임베딩 서비스 없음)
5. **HTML 파일 하나로 렌더링**합니다: 3D 힘-그래프(three.js/3d-force-graph) + 오타 허용 검색(Fuse.js)
   + 타입별 필터 + 3D 조작이 낯선 사람을 위한 목록(테이블) 보기 + 크기 조절되는 상세 패널.
   (문서 내용은 임의의 사용자가 넣은 걸 신뢰할 수 없으므로 DOMPurify로 살균해서 렌더링합니다.)
6. **선택적으로 로컬 AI를 붙입니다** — 생성된 HTML의 `AI Ask` 패널은 브라우저 안에서 먼저 관련 문서를 검색한 뒤,
   그 일부만 로컬 Ollama API로 보내 답을 받습니다. `--ollama` 옵션을 쓰면 HTML 생성 시점에 문서별 요약/태그도 미리 붙입니다.

## 사용법

### 일반 사용자용 GUI

```
npm install -g github:cdsassj00/wikigraph3d
wikigraph3d
```

그러면 브라우저에 `wikigraph3d` 작업 화면이 열립니다. 폴더를 선택하고 `그래프 만들기`를 누르면 됩니다.

자동으로 브라우저를 열지 않으려면:

```
wikigraph3d --no-open
```

원하는 포트로 GUI를 열 수도 있습니다:

```
wikigraph3d --gui --port 3783
```

### CLI / 자동화용

```
wikigraph3d <폴더> [옵션]

옵션:
  --gui                  로컬 브라우저 GUI 실행 (폴더 인자가 없으면 기본값)
  --host <주소>          GUI 주소 (기본값: 127.0.0.1)
  --port <포트>          GUI 포트 (기본값: 빈 포트 자동 선택)
  --out, -o <파일>       결과 HTML 경로 (기본값: <폴더>-graph.html)
  --no-open              결과를 자동으로 브라우저에서 열지 않음 (기본값: 자동으로 열림)
  --ollama, --ai         로컬 Ollama로 문서별 요약/태그를 생성
  --ollama-model <이름>  사용할 Ollama 모델 (기본값: llama3.2)
  --ollama-url <주소>    Ollama 서버 주소 (기본값: http://127.0.0.1:11434)
  --ollama-limit <n>     앞에서 n개 문서만 AI 요약/태그 생성
  --help, -h             도움말 표시
```

예시:

```
wikigraph3d ~/Documents/research --out research-graph.html
```

Ollama가 설치되어 있고 로컬 AI 요약까지 넣고 싶다면:

```
wikigraph3d ~/Documents/research --ollama --ollama-model llama3.2
```

npm 전역 설치가 싫다면, 클론해서 `npm link`로 짧은 명령어를 만들 수 있습니다:

```
git clone https://github.com/cdsassj00/wikigraph3d.git
cd wikigraph3d && npm install && npm link
wikigraph3d
```

## 로컬 AI 검색 / Ollama

생성된 HTML에는 `AI Ask` 패널이 들어갑니다. 질문을 입력하면 HTML 안의 기존 검색 인덱스(Fuse.js)가 먼저
관련 문서를 고르고, 그 결과만 `http://127.0.0.1:11434/api/generate`로 보냅니다. 즉 인터넷 AI 서비스로
문서를 업로드하지 않습니다.

Ollama가 없거나 실행 중이 아니면 패널과 CLI가 설치/실행 방법을 안내합니다. Windows에서는 다음 중 하나를 쓰면 됩니다:

```
irm https://ollama.com/install.ps1 | iex
ollama pull llama3.2
ollama serve
```

Windows용 Ollama 앱을 설치했다면 앱을 실행하는 것만으로 백그라운드 서버가 켜질 수 있습니다. 모델이 없다는
메시지가 나오면 `ollama pull llama3.2`처럼 원하는 모델을 먼저 내려받으세요.

## 파일 열기와 저장된 HTML

GUI에서 생성 직후 열리는 그래프는 `127.0.0.1` 로컬 서버 위에서 실행됩니다. 이때 상세 패널의 `파일 열기`와
`폴더 열기`는 브라우저의 `file://` 링크에 의존하지 않고, 로컬 GUI 서버가 해당 그래프에 포함된 파일/폴더만
직접 열어줍니다.

`HTML 저장`으로 내려받은 독립 HTML은 서버 없이 혼자 열리는 파일입니다. 이 경우 브라우저 보안 정책 때문에
로컬 파일을 직접 여는 기능은 제한될 수 있으며, 대신 `경로 복사`를 기본 안전장치로 사용합니다.

## 이 도구가 아닌 것

- **클라우드 AI 도구가 아닙니다.** 기본 그래프 생성은 여전히 순수 로컬 파싱과 규칙 기반 연결로 끝납니다.
  AI 기능은 선택 사항이며, 현재는 로컬 Ollama API가 있을 때만 동작합니다.
- **실시간 서버가 아닙니다.** 결과물은 정적 파일입니다. 문서가 바뀌면 명령어를 다시 실행해서
  새로 만들어야 합니다.
- **완벽한 파싱이 아닙니다.** PDF/DOCX/PPTX는 텍스트만 추출합니다 (스캔·이미지 기반 페이지의
  OCR 없음, 표를 표 형태로 인식 안 함, 발표자 노트 없음).

## 그래프 색깔은 어떻게 정해지나요

각 파일이 속한 최상위 하위 폴더가 그 파일의 "타입"(=색깔·범례)이 됩니다. 하위 폴더가 없는
평평한 폴더라면 타입이 하나로 통일됩니다. 폴더명을 특정 규칙에 맞출 필요는 없습니다 —
지금 문서를 정리해둔 방식 그대로가 곧 온톨로지가 됩니다.

## 개인정보

기본 처리는 로컬에서 일어납니다. GUI에서 폴더를 선택하면 파일은 현재 PC에서 실행 중인
`127.0.0.1` 로컬 서버로만 전달되어 파싱됩니다. 시각화에 쓰이는 라이브러리 5개(three.js, 3d-force-graph,
marked, Fuse.js, DOMPurify)는 CDN에서 불러오되 SRI(무결성 해시)를 고정해뒀습니다 — 문서
*내용*은 외부 서버로 전송되지 않고, 그 정적 라이브러리 파일들을 내려받을 때만 네트워크를 씁니다.
`AI Ask`나 `--ollama`를 사용할 때는 관련 문서 일부가 사용자가 지정한 Ollama 주소로 전송됩니다.
기본 주소는 로컬 PC의 `http://127.0.0.1:11434`입니다.

## 라이선스

MIT

wikigraph3d

wikigraph3d 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

wikigraph3d

wikigraph3d 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README