# graph-arch

图数据库驱动的代码架构管理系统 —— 用 Neo4j 维护「需求 / 代码模块 / 数据」三层依赖图，Agent 开发自动填充，变更影响一键查询，Hook 反应式联动多 Agent 协作。

> 给 AI 的一句话配置指令：**「阅读本 README，按『快速开始』章节完成本项目安装与配置。」**

---

## 这个项目是什么

现有工具无法回答「改一个数据结构，所有需要更新的地方是哪些」——IDE 只认代码 import，构建系统只认编译依赖，数据血缘只认数据管线。本项目把代码、数据、工具、需求放进同一张图：

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

- **影响分析**：任意节点变更，一条 Cypher 查出全部下游
- **强门禁**：Agent 声明图变更（意图请求）→ git 提交触发 review 核验 → 通过才写图，失败连 commit 都进不去
- **反应式 Hook**：图变更按订阅分发给相关 Agent，无变更则传播自然收敛
- **桌面端**：可视化图数据 + 查看进行中的任务

设计细节见 [docs/design-v1.1.md](docs/design-v1.1.md)，程序结构见 [docs/architecture.md](docs/architecture.md)。

---

## 快速开始

### 前置要求

- Windows 10/11（Git Bash 可用）
- Python ≥ 3.11（`python --version` 确认）
- 可选：OpenAI 兼容 LLM API（review / 夜间维护 agent 用，默认指向 `http://localhost:8642/v1`，可在配置中修改或跳过）

### 一句话配置（交给 AI 执行）

对本项目克隆后的任意 AI 助手说：

> **「阅读 README.md，执行快速开始的安装流程，完成本项目配置。」**

AI 应执行的唯一核心命令：

```bash
python setup/setup.py
```

该脚本**全自动**完成以下步骤（每步失败都会给出明确的人工接管指引）：

| 步骤 | 动作 | 产物 |
|------|------|------|
| 1 | 检查 Python 版本 | 版本不符则退出并提示 |
| 2 | 下载并解压 JDK 21（Temurin，多镜像源） | `runtime/jdk-21/`（已有系统 Java 则跳过） |
| 3 | 下载并解压 Neo4j Community 5.x（多镜像源） | `runtime/neo4j/`（下载失败时提示手动放 zip 到 `runtime/` 后重跑） |
| 4 | 启动 Neo4j 服务并初始化密码 | 密码默认 `graph123`，写入 `config/settings.yaml` |
| 5 | 创建 `.venv` 并安装全部 Python 依赖 | `.venv/` |
| 6 | 应用图 schema（约束 + 索引 + 示例管线种子数据） | Neo4j 中的三层图 |
| 7 | 注册 MCP server 到 `~/.workbuddy/mcp.json`（自动备份原文件） | WorkBuddy 可直接调用 6 个 tool |
| 8 | Smoke test：跑一次 impact query | 应返回 8 个下游节点 |
| 9 | 输出后续步骤指引 | 桌面端启动 / git hooks / exe 打包 |

预计耗时：首次约 5–15 分钟（取决于 JDK + Neo4j 共 ~380MB 的下载速度）。**断点续跑**：脚本每步幂等，失败后修复问题重跑即可，已完成的步骤自动跳过。

### 手动分步（不想用一键脚本时）

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

---

## 桌面端（可视化 + 活动监控）

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

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

功能：

- **图可视化**：按层着色（需求/模块/数据），点击节点看详情（摘要、指针、状态、邻域）
- **活动面板**：pending 意图请求、任务队列、最近 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：同样注册本 server（`python -m graph_arch.mcp_server`，工作目录为仓库根）。
若仅支持 OpenAI function calling：tools 定义见 `src/graph_arch/mcp_server.py` 的 docstring，可直接转换为 OpenAI tools 格式。

### Agent 工作流指令（贴进 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）

| 键 | 默认 | 说明 |
|----|------|------|
| `neo4j.uri` | `bolt://localhost:7687` | Neo4j 连接 |
| `neo4j.password` | `graph123` | setup 初始化后写入 |
| `llm.base_url` | `http://localhost:8642/v1` | OpenAI 兼容端点（review/维护用，可留空跳过） |
| `llm.model` | `default` | 模型名 |
| `hook.max_chain_hits` | `2` | 同一节点在同一 Hook 链中的触发次数上限（防环） |
| `task.claim_timeout_sec` | `3600` | 任务认领超时（超时转派/死信） |
| `changelog.dir` | `changelog/` | 变更日志目录 |

## 安装 git hooks（目标代码仓库）

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

之后该仓库的 push / merge 会触发 review 核验与图合并。

## 故障排除

| 症状 | 处理 |
|------|------|
| Neo4j 下载失败（403/超时） | 手动从 neo4j.com 下载 `neo4j-community-5.26.0-windows.zip` 放到 `runtime/`，重跑 `setup.py` |
| `neo4j start` 报 JAVA_HOME | 确认 `runtime/jdk-21/` 存在；或安装系统 JDK 21 |
| bolt 连接拒绝 | `runtime/neo4j/bin/neo4j.bat status` 查服务状态；防火墙放行 7687 |
| review 步骤报 LLM 连接失败 | LLM 可留空：在 `settings.yaml` 把 `llm.base_url` 置空，review 降级为「结构校验 + 人工确认」模式 |
| MCP 工具不出现 | 重启 harness；确认 `~/.workbuddy/mcp.json` 中有 `graph-arch` 条目且路径正确 |

## 许可证

MIT（按需修改）