WorkGraph

WorkGraph indexa un espacio de trabajo seleccionado por el usuario sin mover ni subir sus archivos. Construye un grafo en capas Portfolio -> Area -> Project -> Artifact, lo expone a través de un navegador local, CLI y un servidor MCP de solo lectura, y opcionalmente puede generar una capa de navegación para Obsidian.

Comenzó como una herramienta personal de "vibe-coding" para navegar por un espacio de trabajo grande y mixto de investigación e ingeniería. La versión pública elimina suposiciones específicas de la máquina, manteniendo el flujo de trabajo que hizo útil al original: descubrimiento rápido entre proyectos, procedencia explícita y separación estricta entre archivos fuente, índices reconstruibles y memoria curada.

Qué hace

• Mapa jerárquico: pasa de todo el portafolio a un área, proyecto, documento, concepto, herramienta o flujo de trabajo.

• Búsqueda local: búsqueda FTS de SQLite sobre metadatos de proyectos y archivos de texto seleccionados.

• Enlaces explicables: distingue referencias explícitas a rutas de sugerencias de menor confianza basadas en conceptos compartidos.

• MCP de solo lectura: permite que Codex, Kimi, Reasonix u otro cliente MCP consulten el contexto del proyecto y el trabajo previo reutilizable.

• Capa opcional de Obsidian: genera páginas de navegación, índices de conceptos, espejos de memoria y un Canvas sin copiar el espacio de trabajo.

• Controles de privacidad: marca áreas completas de nivel superior como solo metadatos y redacta patrones comunes de credenciales del texto indexado.

• Sin servicio alojado: la interfaz web se vincula a loopback y usa activos de frontend incluidos; la indexación en tiempo de ejecución no necesita red ni API de modelos.

Related MCP server: ContextForge

Inicio rápido

Instalador de Windows

Descarga el último archivo fuente desde Releases, extráelo y luego ejecuta:

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

Las integraciones opcionales son explícitas:

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

El instalador crea un .venv local al proyecto, escribe config/workgraph.json, construye el primer índice y, opcionalmente, registra el servidor MCP. Los archivos de cliente existentes se respaldan antes de modificarlos.

Instalación manual

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

Abre http://127.0.0.1:8765/. En macOS o Linux, usa .venv/bin/python con los mismos comandos de módulo.

Modelo de espacio de trabajo

La convención predeterminada trata el primer nivel de directorio como un área y el segundo como un proyecto:

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

Los diseños más profundos o mixtos se pueden describir con project_layout.area_depths y project_layout.group_depths. Consulta config/workgraph.example.json y el sintético examples/demo-workspace.

Comandos diarios

.\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"

Herramientas MCP

work_map, project_context, related_projects, find_reuse, work_search y graph_stats son de solo lectura. El registro automático actualmente apunta a Codex, Kimi Code/Kimi Work y Reasonix en Windows:

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

Para otros clientes, registra este comando stdio:

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

Límites de confianza

• El espacio de trabajo sigue siendo la fuente de verdad; WorkGraph nunca mueve ni elimina archivos fuente.

• La base de datos SQLite y las páginas generadas de Obsidian son índices desechables.

• Las áreas sensibles exponen nombres de archivo y metadatos agregados, pero su contenido no se indexa.

• Las carpetas generadas como .git, .venv, node_modules y cachés de compilación se excluyen del análisis semántico.

• Los archivos binarios de oficina, PDFs, modelos y medios son solo metadatos en v0.1.

• Las aristas related_to son sugerencias de descubrimiento, no evidencia. Sigue las rutas fuente antes de confiar en una afirmación.

Lee el modelo de privacidad completo antes de indexar material confidencial.

Desarrollo

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

WorkGraph solo usa la biblioteca estándar en tiempo de ejecución. Cytoscape.js y Lucide están incluidos para la interfaz sin conexión; sus avisos están en THIRD_PARTY_NOTICES.md.

El desarrollo es dirigido por humanos y asistido por IA. El mantenedor es dueño de las decisiones arquitectónicas, los límites de privacidad, la verificación, los lanzamientos y todos los cambios aceptados; el código generado recibe los mismos requisitos de revisión y prueba que cualquier otra contribución.

Las contribuciones son bienvenidas a través de issues y pull requests enfocados. Consulta CONTRIBUTING.md, SECURITY.md y la hoja de ruta.

Licencia

Apache License 2.0. Consulta LICENSE.