graph-arch

Sistema de gestión de arquitectura de código impulsado por base de datos de grafos: mantiene un grafo de dependencias de tres capas de "requisitos / módulos de código / datos" con Neo4j. El desarrollo de agentes se completa automáticamente, el impacto de los cambios se consulta con un clic, y los hooks reactivos coordinan la colaboración de múltiples agentes.

Instrucción de configuración en una frase para la IA: «Lee este README y completa la instalación y configuración de este proyecto siguiendo la sección "Inicio rápido".»

Qué es este proyecto

Las herramientas existentes no pueden responder a la pregunta "si cambio una estructura de datos, ¿cuáles son todos los lugares que necesitan actualizarse?" — el IDE solo reconoce los imports de código, el sistema de compilación solo reconoce las dependencias de compilación, y el linaje de datos solo reconoce las canalizaciones de datos. Este proyecto coloca código, datos, herramientas y requisitos en un mismo grafo:

AI 运行 A ─PRODUCES→ 数据集 B ─→ 工具 C ─→ Excel D ─┐
                       └──→ 工具 E ─→ Excel F ─┴→ 工具 G ─→ Excel H ─→ 客户端/服务端

• Análisis de impacto: cualquier cambio en un nodo, una consulta Cypher revela todos los downstream

• Control de acceso estricto: el agente declara el cambio en el grafo (solicitud de intención) → el commit de git activa la verificación de revisión → solo se escribe en el grafo si se aprueba; si falla, ni siquiera el commit puede entrar

• Hooks reactivos: los cambios en el grafo se distribuyen a los agentes relevantes según suscripciones; si no hay cambios, la propagación converge naturalmente

• Escritorio: visualización de datos del grafo + visualización de tareas en curso

Los detalles de diseño se encuentran en docs/design-v1.1.md, y la estructura del programa en docs/architecture.md.

Related MCP server: codemap

Inicio rápido

Requisitos previos

• Windows 10/11 (Git Bash disponible)

• Python ≥ 3.11 (confirmar con python --version)

• Opcional: API LLM compatible con OpenAI (para el agente de revisión / mantenimiento nocturno; por defecto apunta a http://localhost:8642/v1, se puede modificar en la configuración u omitir)

Configuración en una frase (para que la ejecute la IA)

Dile a cualquier asistente de IA después de clonar este proyecto:

"Lee README.md, ejecuta el proceso de instalación de inicio rápido y completa la configuración de este proyecto."

El único comando central que debe ejecutar la IA:

python setup/setup.py

Este script completa automáticamente los siguientes pasos (cada fallo proporciona instrucciones claras de intervención manual):

Tiempo estimado: la primera vez unos 5–15 minutos (dependiendo de la velocidad de descarga de JDK + Neo4j, ~380MB en total). Reanudación de descargas: el script es idempotente en cada paso; si falla, corrige el problema y vuelve a ejecutarlo, los pasos completados se omiten automáticamente.

Pasos manuales (si no se quiere usar el script de un clic)

# 1. 依赖
python -m venv .venv && .venv/Scripts/pip install -e .

# 2. Neo4j（手动下载 zip 解压到 runtime/neo4j/，需要 JDK 21）
runtime/neo4j/bin/neo4j.bat install-service
runtime/neo4j/bin/neo4j.bat start

# 3. 初始化密码（首次默认 neo4j/neo4j，登录后强制改）
runtime/neo4j/bin/cypher-shell.bat -u neo4j -p neo4j \
  "ALTER CURRENT USER SET PASSWORD FROM 'neo4j' TO 'graph123';"

# 4. 应用 schema 与种子数据
.venv/Scripts/python -m graph_arch.setup_db

# 5. 注册 MCP（见下方「接入 Agent Harness」）

# 6. 验证
.venv/Scripts/python -c "from graph_arch.graph.queries import impact; \
  print(len(impact('data:dataset_b')), '个下游节点')   # 应输出 8"

Escritorio (visualización + monitoreo de actividad)

# 开发运行
.venv/Scripts/python desktop/main.py

# 打包为独立 exe（产物在 desktop/dist/）
.venv/Scripts/python desktop/build_exe.py

Funciones:

• Visualización del grafo: coloreado por capas (requisitos/módulos/datos), clic en un nodo para ver detalles (resumen, puntero, estado, vecindario)

• Panel de actividad: solicitudes de intención pendientes, cola de tareas, flujo de changelog reciente, lista de nodos obsoletos

• Actualización automática cada 5 segundos

Integración con el Agent Harness

WorkBuddy

setup.py ya escribe automáticamente en ~/.workbuddy/mcp.json. Después de reiniciar WorkBuddy, aparecen en el directorio de herramientas:

submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks

Hermes

Si Hermes es compatible con MCP: registra también este servidor (python -m graph_arch.mcp_server, directorio de trabajo en la raíz del repositorio). Si solo es compatible con OpenAI function calling: las definiciones de herramientas se encuentran en el docstring de src/graph_arch/mcp_server.py, que se pueden convertir directamente al formato de herramientas de OpenAI.

Instrucciones de flujo de trabajo del agente (pégalas en el system prompt o conviértelas en una skill)

开发工作流（必须遵守）:
1. 接到任何修改类任务，先调 query_context 加载目标节点邻域（摘要+指针+状态）
2. 若涉及已有数据结构/模块，必须调 query_impact 确认影响范围
3. 按指针从源头（git/文档/schema）加载细节后开工
4. 完成后必须 submit_graph_intent 声明图变更，再创建 git 提交
5. review 失败则按返回原因修正，重新提交

Estructura de directorios

graph-arch/
├── README.md                  # 本文件
├── pyproject.toml             # 包定义与依赖
├── docs/                      # 设计文档（v1.1）+ 结构文档
├── setup/setup.py             # 一键安装脚本
├── config/
│   ├── settings.yaml          # Neo4j/LLM/路径/超时（setup 自动生成）
│   ├── hooks.yaml             # Hook 规则注册
│   └── skill_routes.yaml      # skill 路由表（harness 层）
├── schema/                    # Cypher：约束 + 种子数据
├── src/graph_arch/
│   ├── graph/                 # client / writer / queries / merger
│   ├── hooks/                 # engine / cycle_guard / actions
│   ├── review/                # 核验协议 + LLM 调用
│   ├── tasks/                 # 任务队列 + 死信队列
│   ├── mcp_server.py          # 入口 1: MCP server（常驻）
│   ├── git_hook.py            # 入口 2: git hooks（pre-receive/post-merge）
│   ├── nightly.py             # 入口 3: 夜间维护（定时）
│   └── setup_db.py            # schema 初始化
├── desktop/                   # 桌面端（PySide6 + vis-network）
├── git-hooks/                 # 仓库钩子 + 安装脚本
├── changelog/                 # append-only 变更日志（JSONL）
├── runtime/                   # JDK / Neo4j（setup 下载，不入 git）
└── tests/

Configuración (config/settings.yaml)

Instalación de hooks de git (en el repositorio de código objetivo)

bash git-hooks/install.sh /path/to/your/code-repo

Después de esto, los push / merge de ese repositorio activarán la verificación de revisión y la fusión del grafo.

Solución de problemas

Licencia

MIT (modificable según sea necesario)