graph-arch

Система управления архитектурой кода на основе графовой базы данных — в Neo4j поддерживается трёхуровневый граф зависимостей «требования / модули кода / данные», автоматически наполняемый агентами разработки; влияние изменений можно оценить одним запросом, а реактивные Hook-и обеспечивают совместную работу нескольких агентов.

Одна фраза для настройки ИИ: «Прочитайте этот README и выполните установку и настройку проекта по разделу „Быстрый старт“»

Что это за проект

Существующие инструменты не могут ответить на вопрос «если изменить одну структуру данных, какие места нужно обновить» — IDE видит только импорты кода, система сборки — только зависимости компиляции, а data lineage — только конвейеры данных. Этот проект помещает код, данные, инструменты и требования в один и тот же граф:

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

• Анализ влияния: при изменении любого узла один запрос Cypher находит все нижестоящие узлы

• Строгий контроль: агент заявляет изменение графа (запрос намерения) → git-коммит запускает ревью-проверку → граф обновляется только после успешной проверки; при неудаче не проходит даже коммит

• Реактивные Hook-и: изменения графа рассылаются подписанным агентам; если изменений нет, распространение естественным образом сходится

• Десктоп-клиент: визуализация графа + просмотр текущих задач

Детали проектирования см. в docs/design-v1.1.md, структуру программы — в docs/architecture.md.

Related MCP server: codemap

Быстрый старт

Предварительные требования

• Windows 10/11 (подойдёт Git Bash)

• Python ≥ 3.11 (проверить командой python --version)

• Опционально: OpenAI-совместимый API LLM (для ревью / ночного агента обслуживания; по умолчанию указывает на http://localhost:8642/v1, можно изменить в конфигурации или пропустить)

Настройка одной фразой (выполняет ИИ)

Любому ИИ-ассистенту после клонирования проекта скажите:

«Прочитайте README.md, выполните установку по разделу „Быстрый старт“ и завершите настройку проекта.»

Единственная ключевая команда, которую должен выполнить ИИ:

python setup/setup.py

Этот скрипт полностью автоматически выполняет следующие шаги (при сбое на каждом шаге выдаются явные инструкции по ручному вмешательству):

Ожидаемое время: при первом запуске около 5–15 минут (зависит от скорости загрузки JDK + Neo4j, в сумме ~380MB). Возобновление с точки останова: каждый шаг скрипта идемпотентен — после исправления проблемы просто запустите его повторно, уже выполненные шаги будут автоматически пропущены.

Ручная установка по шагам (если не нужен скрипт одной командой)

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

Десктоп-клиент (визуализация + мониторинг активности)

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

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

Возможности:

• Визуализация графа: цветовая маркировка по слоям (требования/модули/данные); клик по узлу — детали (сводка, указатели, статус, соседние узлы)

• Панель активности: ожидающие запросы намерений, очередь задач, последние записи changelog, список устаревших (stale) узлов

• Автоматическое обновление каждые 5 секунд

Подключение к Agent Harness

WorkBuddy

setup.py автоматически записал конфигурацию в ~/.workbuddy/mcp.json. После перезапуска WorkBuddy в списке инструментов появятся:

submit_graph_intent / query_impact / query_context / claim_task / get_pending_intents / get_pending_tasks

Hermes

Если Hermes поддерживает MCP: зарегистрируйте этот сервер аналогично (python -m graph_arch.mcp_server, рабочая директория — корень репозитория). Если поддерживается только OpenAI function calling: определения инструментов см. в docstring файла src/graph_arch/mcp_server.py, их можно напрямую преобразовать в формат OpenAI tools.

Инструкции по рабочему процессу агента (вставьте в system prompt или оформите как skill)

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

Структура каталога

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/

Описание конфигурации (config/settings.yaml)

Установка git hooks (целевой репозиторий кода)

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

После этого push / merge в этом репозитории будут запускать ревью-проверку и слияние изменений в граф.

Поиск и устранение неисправностей

Лицензия

MIT (можно изменять по необходимости)