graph-arch

Graphendatenbank-gesteuertes Code-Architektur-Managementsystem – mit Neo4j wird ein dreischichtiger Abhängigkeitsgraph aus „Anforderungen / Code-Modulen / Daten" gepflegt. Agent-Entwicklung füllt ihn automatisch, Änderungsauswirkungen lassen sich per Klick abfragen, und reaktive Hooks koordinieren mehrere Agents.

Ein-Satz-Konfigurationsanweisung für KI: „Lies diese README und führe die Installation und Konfiguration dieses Projekts gemäß dem Kapitel ‚Schnellstart' durch."

Was ist dieses Projekt?

Bestehende Tools können nicht beantworten: „Wenn ich eine Datenstruktur ändere, welche Stellen müssen alle aktualisiert werden?" – Die IDE kennt nur Code-Importe, das Build-System nur Compile-Abhängigkeiten, Data Lineage nur Datenpipelines. Dieses Projekt bringt Code, Daten, Tools und Anforderungen in einen einzigen Graphen:

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

• Auswirkungsanalyse: Bei Änderung eines beliebigen Knotens liefert eine einzige Cypher-Abfrage alle nachgelagerten Knoten

• Starke Gate-Kontrolle: Agent deklariert Graphänderungen (Intent-Request) → Git-Commit löst Review-Prüfung aus → erst nach Bestehen wird in den Graphen geschrieben, bei Fehlschlag kommt nicht einmal der Commit durch

• Reaktive Hooks: Graphänderungen werden gemäß Abonnement an relevante Agents verteilt; ohne Änderungen konvergiert die Ausbreitung natürlich

• Desktop-Anwendung: Visualisierung der Graphdaten + Ansicht laufender Aufgaben

Designdetails siehe docs/design-v1.1.md, Programmstruktur siehe docs/architecture.md.

Related MCP server: codemap

Schnellstart

Voraussetzungen

• Windows 10/11 (Git Bash verfügbar)

• Python ≥ 3.11 (mit python --version bestätigen)

• Optional: OpenAI-kompatible LLM-API (für Review-/Nachtwartungs-Agent, zeigt standardmäßig auf http://localhost:8642/v1, kann in der Konfiguration geändert oder übersprungen werden)

Ein-Satz-Konfiguration (der KI überlassen)

Sag zu einem beliebigen KI-Assistenten nach dem Klonen dieses Projekts:

„Lies README.md, führe den Installationsprozess aus dem Schnellstart aus und schließe die Konfiguration dieses Projekts ab."

Der einzige Kernbefehl, den die KI ausführen soll:

python setup/setup.py

Dieses Skript führt die folgenden Schritte vollautomatisch aus (bei jedem Fehlschritt wird eine klare Anleitung zur manuellen Übernahme ausgegeben):

Geschätzte Dauer: Erstmals ca. 5–15 Minuten (abhängig von der Downloadgeschwindigkeit von JDK + Neo4j, zusammen ~380 MB). Fortsetzen nach Unterbrechung: Jeder Skriptschritt ist idempotent; nach Behebung eines Fehlers einfach erneut ausführen, bereits abgeschlossene Schritte werden automatisch übersprungen.

Manuelle Einzelschritte (falls das Ein-Klick-Skript nicht verwendet werden soll)

# 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"

Desktop-Anwendung (Visualisierung + Aktivitätsüberwachung)

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

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

Funktionen:

• Graphvisualisierung: Färbung nach Schicht (Anforderungen/Module/Daten), Klick auf Knoten zeigt Details (Zusammenfassung, Zeiger, Status, Nachbarschaft)

• Aktivitätsbereich: Ausstehende Intent-Requests, Aufgabenwarteschlange, aktueller Changelog-Stream, Liste veralteter (stale) Knoten

• Automatische Aktualisierung alle 5 Sekunden

Anbindung an Agent-Harness

WorkBuddy

setup.py hat ~/.workbuddy/mcp.json automatisch geschrieben. Nach Neustart von WorkBuddy erscheinen im Tool-Verzeichnis:

submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks

Hermes

Falls Hermes MCP unterstützt: Ebenso diesen Server registrieren (python -m graph_arch.mcp_server, Arbeitsverzeichnis ist das Repository-Root). Falls nur OpenAI-Function-Calling unterstützt wird: Die Tool-Definitionen finden sich im Docstring von src/graph_arch/mcp_server.py und können direkt in das OpenAI-Tools-Format überführt werden.

Workflow-Anweisungen für Agents (in System-Prompt einfügen oder als Skill anlegen)

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

Verzeichnisstruktur

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/

Konfigurationshinweise (config/settings.yaml)

Git-Hooks installieren (im Ziel-Code-Repository)

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

Danach lösen Push/Merge in diesem Repository Review-Prüfung und Graph-Zusammenführung aus.

Fehlerbehebung

Lizenz

MIT (nach Bedarf anpassbar)