WorkGraph

WorkGraph은 사용자가 선택한 작업 공간을 파일을 이동하거나 업로드하지 않고 인덱싱합니다. 계층형 Portfolio -> Area -> Project -> Artifact 그래프를 구축하고, 로컬 브라우저, CLI, 읽기 전용 MCP 서버를 통해 노출하며, 선택적으로 Obsidian 탐색 레이어를 생성할 수 있습니다.

대규모의 혼합 연구·엔지니어링 작업 공간을 탐색하기 위한 개인용 vibe-coded 도구로 시작했습니다. 공개 버전은 머신별 가정을 제거하면서 원본을 유용하게 만든 워크플로(빠른 교차 프로젝트 검색, 명시적 출처 추적, 소스 파일·재구축 가능한 인덱스·큐레이션된 메모리의 엄격한 분리)를 유지합니다.

기능

• 드릴다운 맵: 전체 포트폴리오에서 영역, 프로젝트, 문서, 개념, 도구, 워크플로로 이동합니다.

• 로컬 검색: 프로젝트 메타데이터와 선택된 텍스트 파일에 대한 SQLite FTS 검색.

• 설명 가능한 링크: 명시적 경로 참조와 신뢰도가 낮은 공유 개념 제안을 구분합니다.

• 읽기 전용 MCP: Codex, Kimi, Reasonix 또는 다른 MCP 클라이언트가 프로젝트 컨텍스트와 재사용 가능한 기존 작업을 쿼리할 수 있게 합니다.

• 선택적 Obsidian 레이어: 작업 공간을 복사하지 않고 탐색 페이지, 개념 인덱스, 메모리 미러, Canvas를 생성합니다.

• 개인정보 보호 제어: 최상위 영역 전체를 메타데이터 전용으로 표시하고 인덱싱된 텍스트에서 일반적인 자격 증명 패턴을 삭제합니다.

• 호스팅 서비스 없음: 웹 UI는 루프백에 바인딩되고 벤더링된 프런트엔드 자산을 사용합니다. 런타임 인덱싱에는 네트워크나 모델 API가 필요 없습니다.

Related MCP server: ContextForge

빠른 시작

Windows 설치 프로그램

Releases에서 최신 소스 아카이브를 다운로드하고 압축을 푼 다음 실행합니다:

.\scripts\Install-WorkGraph.ps1 -WorkRoot "D:\MyWorkspace" -Start

선택적 통합은 명시적입니다:

.\scripts\Install-WorkGraph.ps1 `
  -WorkRoot "D:\MyWorkspace" `
  -ObsidianVault "$HOME\Documents\My Vault" `
  -SensitiveArea Personal,Finance `
  -ConfigureClients `
  -Start

설치 프로그램은 프로젝트 로컬 .venv를 만들고, config/workgraph.json을 작성하고, 첫 번째 인덱스를 구축하고, 선택적으로 MCP 서버를 등록합니다. 기존 클라이언트 파일은 수정 전에 백업됩니다.

수동 설치

uv venv .venv
uv pip install --python .\.venv\Scripts\python.exe -e .
.\.venv\Scripts\python.exe -m workgraph.cli init --work-root "D:\MyWorkspace"
.\.venv\Scripts\python.exe -m workgraph.cli refresh
.\.venv\Scripts\python.exe -m workgraph.cli serve

http://127.0.0.1:8765/을 엽니다. macOS 또는 Linux에서는 동일한 모듈 명령과 함께 .venv/bin/python을 사용합니다.

작업 공간 모델

기본 규칙은 첫 번째 디렉터리 수준을 영역으로, 두 번째를 프로젝트로 취급합니다:

MyWorkspace/
├── Research/
│   ├── ClimateModel/
│   └── KnowledgeGraph/
├── Engineering/
│   ├── RobotArm/
│   └── CFDStudy/
└── Writing/
    └── OpenSourceGuide/

더 깊거나 혼합된 레이아웃은 project_layout.area_depths 및 project_layout.group_depths로 설명할 수 있습니다. config/workgraph.example.json 및 합성 examples/demo-workspace를 참조하세요.

일상 명령

.\scripts\Refresh-WorkGraph.ps1
.\scripts\Start-WorkGraph.ps1 -Open
.\scripts\Status-WorkGraph.ps1
.\scripts\Stop-WorkGraph.ps1

.\.venv\Scripts\python.exe -m workgraph.cli search "finite element OCR"
.\.venv\Scripts\python.exe -m workgraph.cli context "ClimateModel"
.\.venv\Scripts\python.exe -m workgraph.cli related "KnowledgeGraph"
.\.venv\Scripts\python.exe -m workgraph.cli reuse "document rendering"

MCP 도구

work_map, project_context, related_projects, find_reuse, work_search, graph_stats는 읽기 전용입니다. 자동 등록은 현재 Windows의 Codex, Kimi Code/Kimi Work, Reasonix를 대상으로 합니다:

.\.venv\Scripts\python.exe -m workgraph.cli configure-clients

다른 클라이언트의 경우 이 stdio 명령을 등록합니다:

<absolute path to python> -m workgraph.mcp --config <absolute path to workgraph.json>

신뢰 경계

• 작업 공간은 진실의 원천으로 유지됩니다. WorkGraph은 소스 파일을 이동하거나 삭제하지 않습니다.

• SQLite 데이터베이스와 생성된 Obsidian 페이지는 일회용 인덱스입니다.

• 민감한 영역은 파일 이름과 집계 메타데이터를 노출하지만, 해당 내용은 인덱싱되지 않습니다.

• .git, .venv, node_modules, 빌드 캐시와 같은 생성 폴더는 의미 분석에서 제외됩니다.

• 바이너리 오피스 파일, PDF, 모델, 미디어는 v0.1에서 메타데이터 전용입니다.

• related_to 엣지는 발견 힌트이지 증거가 아닙니다. 주장에 의존하기 전에 소스 경로를 따르세요.

기밀 자료를 인덱싱하기 전에 전체 개인정보 보호 모델을 읽으세요.

개발

.\.venv\Scripts\python.exe -m unittest discover -s tests -v
.\.venv\Scripts\python.exe -m compileall -q src tests

WorkGraph은 런타임 표준 라이브러리 전용입니다. Cytoscape.js와 Lucide는 오프라인 UI를 위해 벤더링되었으며, 해당 고지 사항은 THIRD_PARTY_NOTICES.md에 있습니다.

개발은 인간 주도 및 AI 보조 방식입니다. 관리자는 아키텍처 결정, 개인정보 보호 경계, 검증, 릴리스, 모든 승인된 변경 사항을 소유합니다. 생성된 코드는 다른 기여와 동일한 검토 및 테스트 요구 사항을 받습니다.

기여는 집중된 이슈와 풀 리퀘스트를 통해 환영합니다. CONTRIBUTING.md, SECURITY.md, 로드맵을 참조하세요.

라이선스

Apache License 2.0. LICENSE를 참조하세요.