# 论文 vs 代码一致性核查：GraphCogent

## 核查对象与方法

- 论文：arXiv:2508.12379 v2（cs.AI，2025-09-30）"GraphCogent: Mitigating LLMs' Working Memory Constraints via Multi-Agent Collaboration in Complex Graph Understanding"，Rongzheng Wang 等（第一作者单位 UESTC，通讯 Shuang Liang）。13 页 PDF。
- 代码：官方仓库 `https://github.com/RongzhengWang/GraphCogent`（main 分支，单提交 `df819af "new"`，2026-01-20；仓库创建于 2026-01-20）。
- 方法：
  1. `git clone --depth 1 https://github.com/RongzhengWang/GraphCogent.git "<工作目录>/workdir/p5-graphcogent"`（本地克隆约 936 MB，网络较慢转入后台完成）。
  2. `curl -sL -m 60 https://arxiv.org/pdf/2508.12379 -o /tmp/p5.pdf`，用 PyMuPDF 提取全文（68,535 字符）逐段比对；另下载 arXiv HTML 版交叉核对。
  3. 通过 GitHub API 获取仓库文件树（264 个条目），并逐个阅读框架代码、训练脚本、数据生成脚本、prompt 模板、README。
  4. 轻量运行：用 venv 安装 networkx/tqdm 后实际运行 `Graph4real_Trans/generation/sampling.py`（微型合成图）与 `merge.py`，验证数据生成管线可跑；推理框架（需 vLLM+Llama3.1-8B 权重+GPU）未运行，仅做静态检查。

## 论文关键声明清单

1. 框架含三大模块：Sensory Module（Sensory Agent 子图采样+标准化邻接表；Graph Verifier 数量一致性/正则校验/重试/合并）、Buffer Module（Buffer Agent 整合数据、转为 NetworkX/NumPy/PyG、建立数据索引）、Execution Module（Execution Agent 工具调用；Tool Creator 按需生成工具）（§4.2-4.4，Fig. 4，Algorithm 2）。
2. 采样为 biased random walk；滑动窗口默认 50 边/窗口、5% 重叠（§4.2）。
3. GEC（Graph Efficiency Coefficient）= Edit distance × 归一化 token 成本，用于选窗口粒度（Eq.1）。
4. 9 个 in-toolset 任务工具集；Execution Agent 经两阶段训练：Thinking Policy Initialization（TPI，DeepSeek-R1 生成 Think 轨迹）+ Capability-Margin Preference Optimization（CMPO：action-segment scoring、capability-aware hard negatives、K=8、margin、双阈值迟滞路由 Eq.10）。
5. Tool Creator 用 body-only 最大似然目标微调，直接操作 Buffer 预处理数据（§4.4.2）。
6. 全部 agent 用 Llama3.1-8B 骨干；SFT lr=1e-5、batch 4、5 epochs；CMPO lr=5e-6、batch 1+4 累积、5 epochs；温度 0.7、top_p=1（§4.4.3、附录 A）。
7. Graph4real 基准：4 域（Web=Google Web Graph、Social=SNAP Social Circles、Transportation=PeMS、Citation=Cora），三尺度 40/100/1000 节点，三种文本表示（邻接/符号/语言），21 任务 3 类，20 个 prompt 模板、每域 5 场景，DeepSeek-R1 生成，共 4200 问题（§3）。
8. 实验：每任务每尺度 500 测试实例；指标 accuracy（traffic flow 用 MAE）；基线 GPT-4o-2024-08-06、Claude-3.7-sonnet-20250219、DeepSeek-R1、Graph-Toolformer、GraphTool-Instruction（Llama3.1-8B）、GPT4o-FC、GraphTeam（GPT-4o-mini-2024-07-18）、GCoder（Llama3.1-8B）（§5.1）。
9. 报告数字：in-toolset 平均 98.5%（40 节点 99.1 / 100 节点 98.5 / 1000 节点 97.6）；token 比 GraphTeam 省 80%（in-toolset）/30%（out-toolset）（摘要、Table 1、Table 3）。
10. 公共基准：NLGraph、Talk like a Graph、GraphWiz、GraphArena、GraCoRe、GraphInstruct（§5.1）。

## 证据对照表

| 声明 | 代码证据（文件:行号） | 判定 |
|---|---|---|
| 三模块 Sensory/Buffer/Execution 框架 | README.md:16-19 文字描述三模块；`GraphCogent/run.py:225-281` 实现三阶段流水线 graph_extraction→task_discrimination→task_reasoning；pics/method.jpg 与论文 Fig.4 一致 | 部分一致：流水线为 3 阶段，但无独立 Buffer 模块实现（全仓库无 NetworkX→NumPy→PyG 转换与数据索引代码，graph_extractor 只返回 nx.Graph） |
| Sensory Agent：子图采样+标准化邻接表（含加权/无权双正则模板） | `GraphCogent/modules/graph_extractor.py:46-64`（parse_graph 正则解析 (node1,node2,weight)）、:72-118（process_subgraph，调用 vLLM 做转换）；窗口分块实际在数据生成端 `Graph4real_Trans/generation/sampling.py:154-166`（按 granularity=50 硬切块） | 部分一致：转换+正则解析在；但滑动窗口/5% 重叠无实现（分块不重叠），且 graph_extractor 直接消费预分块输入，不做窗口采样 |
| Graph Verifier：数量一致性+格式校验+失败重试+合并去重 | `graph_extractor.py:93-103`（allowed_min/max 数量校验+retry）、:105（nx.compose 合并） | 部分一致：数量校验+重试在；无独立格式合规检查与"set-union 去重"显式实现 |
| biased random walk 采样 | `Graph4real_Trans/generation/sampling.py:81-124`（random_walk_sampling 用 `random.choice(neighbors)` 均匀随机选邻居；四个域脚本 diff 为空） | 不一致：代码为普通（均匀）随机游走，无任何 bias 实现 |
| GEC 选窗口粒度 | 全仓库 grep `GEC|margin|hysteresis` 无匹配 | 不一致：GEC 未实现（粒度 50 仅作为数据生成参数写死） |
| Execution Agent：9 个 in-toolset 工具 | `GraphCogent/modules/task_discriminator.py:11-15`（9 工具名列表）；config.json:9（prompt 内 9 工具描述）；reasoning_prompt.txt:37-64 | 一致：9 个工具与论文 Table 1 任务一一对应 |
| 工具调用（tool calling）真实执行 | `task_reasoner.py:200-218`：已知任务仅让 LLM 输出 API_Input 文本，返回 "final_answer"，无任何 NetworkX 工具函数被调用 | 不一致：仓库无工具集实现，无真实 tool execution |
| Tool Creator 生成任务专用工具、直接操作 Buffer 数据 | `task_reasoner.py:159-198`（handle_unknown_task）+ `label_prompts.json`（node_class/link/euler_path/default 四类模板）；但 `label_prompts.json:5,10,15,20` 的 code_template 用 `Gen()` 随机生成 1000 节点图，而非使用已抽取的真实图 | 不一致：有代码生成路径，但用随机图替代 Buffer 预处理数据；且 Tool Creator 微调代码（§4.4.2 body-only 目标）完全缺失 |
| TPI（DeepSeek-R1 生成 Think 轨迹） | `GraphCogent_train/Think_generation.py:21-73`（--model deepseek-r1 调 OpenAI 兼容 API 生成轨迹）；reasoning_prompt.txt（Thought/Tool_name 格式） | 一致 |
| CMPO（action-segment 打分、参考策略 hard negatives、margin、双阈值迟滞路由） | `GraphCogent_train/DPO_construction.py:55-77`：最多 10 次抽样，取首个 NULL 为 chosen、首个非 NULL 为 rejected——无 action-segment 打分、无参考策略似然选负样本、无 margin；`llama3_lora_dpo.yaml:9-14`（stage: dpo, pref_loss: sigmoid, pref_beta 0.1）；推理端无 Eq.10 阈值路由 | 不一致：实现为普通 DPO 数据构造+DPO 训练，非论文 CMPO；K=8 对应 NUM_TRIALS=10 |
| 训练设置（lr、epochs、batch） | `llama3_lora_sft.yaml:30-35`（lr 1e-5、epochs 3、batch 2×8 累积）；`llama3_lora_dpo.yaml:32-35`（lr 5e-6、epochs 5、batch 1×4 累积） | 部分一致：lr 一致；SFT epochs=3 与论文 5 不符，SFT batch 配置（2×8）与论文 batch 4 不符；DPO 超参与 CMPO 相同但方法不同 |
| 推理超参 temperature=0.7、top_p=1 | `graph_extractor.py:28-32`、`task_discriminator.py:30-34`、`task_reasoner.py:74-78` | 一致 |
| 全部 agent 用 Llama3.1-8B | config.json:4,8,12（三处 model_path 指向 Llama 系/微调产物；含 `llama3.1_lora_dpo+grpo2` 路径，GRPO 论文未提及） | 基本一致（GRPO 痕迹存疑） |
| Graph4real 4 域数据源 | 目录 Graph4real_{Trans,Social,Web,Citation}；Cora 原始数据在（cora.cites 5,429 行=标准 Cora）；Social 有 SNAP `1912.edges`（Facebook ego 网络，6,0050 行）；Trans 有 `adj_matrix_node.txt`（3 列带权边表，87 万行，格式类似 PeMS） | 部分一致：3/4 域有原始数据；Graph4real_Web 无 data 目录（Google Web Graph 未发布），PeMS 来源无法从文件确认 |
| 三尺度 40/100/1000 节点 | `Graph4real_Trans/task_middle/Shortest_Path.json` 全部实例 Node_List=100；仓库仅 task_middle（中间尺度），无 40/1000 节点数据 | 不一致：仅发布 100 节点尺度 |
| 每任务每尺度 500 测试实例 | 实测 task_middle：每任务 400 实例（Edge_Count/Triangle_Count 为 397）×9 任务×4 域≈14,376 条；sampling/ 目录为 1000 条/任务 | 不一致：400≠500，且无多尺度 |
| 21 任务×3 类、4200 问题 | 发布数据仅 9 个 in-toolset 任务（task_middle 每域 9 文件）；out-toolset 任务（PageRank、Link Prediction、Max Flow、Traffic Flow、Node Classification 等 Table 2 的 12 项）数据与评测全无；sampling.py:131-143 会生成 Maxflow/Euler_Path 但未发布 | 部分一致：9/21 任务数据在；4200 与实测 14,376（9 任务版）不符，21 任务版无法验证 |
| 20 个 prompt 模板、每域 5 场景、DeepSeek-R1 生成任务 | `Graph4real_Trans/prompt_template/` 仅 9 个模板/域；`task_generator.py:7`（GPT_MODEL="deepseek-r1"）、:69-75（5 个交通场景，与 README.md:188-192 一致） | 部分一致：DeepSeek-R1 与 5 场景一致；模板数量 9/域≠论文 20 |
| 三种文本表示（邻接/符号/语言） | 发布 task 的 question 为邻接边表（"The edges are: [[u,v,w],...]"）；sampling.py:155 生成语言式 "Node X is connected to Node Y with weight W"；符号表示（0→1）无生成代码 | 部分一致 |
| 评测指标 accuracy+MAE、eval 脚本 | README.md:235 提到 `eval.py`，但仓库无此文件（tree 中 GraphCogent/ 仅 config/label_prompts/run/modules）；无任何结果文件、log | 无法验证：评测脚本缺失 |
| 报告数字 98.5%/97.6%/token-80%/30% | 仓库无结果复现材料；README.md:30-33 仅复述摘要数字 | 无法验证 |
| 基线 GraphTeam/GCoder/GraphTool-Ins/Graph-TF | 仅 `Baseline_Test/gpt4o_fc.py`；其余基线无代码 | 部分一致：仅 GPT4o-FC 基线在 |
| GPT4o-FC 基线用 GPT-4o-2024-08-06 | `Baseline_Test/gpt4o_fc.py:7` 默认 `GPT_MODEL='gpt-4o-mini-2024-07-18'`（注释中列有 gpt-4o-2024-08-06 选项） | 不一致/存疑：默认 mini，非论文表 7 的 GPT-4o-2024-08-06 |
| 推理输入格式与发布数据匹配 | `task_discriminator.py:38`、`task_reasoner.py:167,208` 读取 `translated_question` 键，而 task_middle JSON 只有 `question` 键 | 不一致：框架与发布数据键名不匹配，直接运行会 KeyError |
| README 可用性 | README.md:250 命令路径 `Evaluation/run.py`/`Evaluation/config.json` 与实际 `GraphCogent/run.py` 不符；`bash.sh:5-6,19-20` 引用 `Graph4real__Trans`（双下划线）与 `Graph4real/generation/...` 实际目录不符；`process_json_files.py:40` 同样硬编码 `Graph4real__Trans/ques` | 部分一致：多处路径笔误，示例命令无法照抄运行 |
| 安全/卫生 | `task_generator.py:10-11`、`gpt4o_fc.py:17-19` 硬编码第三方 API key（api.holdai.top 中转站）并提交进仓库；config.json:4-13 硬编码他人机器路径 `/home/data2t1/tempuser/...` | 注意项：存在泄露的凭据与机器特定路径 |

## 运行尝试记录

1. `git clone --depth 1`：成功（网络慢，约数分钟后完成；本地克隆 936 MB，含 4 域 JSON 数据）。
2. 论文 PDF 无法用系统工具渲染（无 poppler），改用 PyMuPDF 提取全文成功。
3. 轻量运行 A——数据生成 `sampling.py`：新建 venv（pip 安装 networkx 3.7、tqdm），用 15 条边的微型合成图运行 `--scale 8 --num_examples 2 --granularity 50`。首次运行失败：脚本不自动创建输出目录（`FileNotFoundError`，sampling.py:250 前无 makedirs）；手动 `mkdir` 后运行成功，产出 11 个任务 JSON（Cycle_Detection 等 9 个 + Maxflow + Euler_Path），结构与仓库发布数据一致（Node_List/Edges/Description/answer）。
4. 轻量运行 B——合并 `merge.py`：用步骤 3 的采样输出 + 手写 1 条 ques JSON 运行成功，产出 task_middle 格式 JSON（键：origin_question/question/type/background_type/Node_List/Edges/Edge_Count/Description/answer），merge2.py 会把模板中的 "123"/"321" 替换为真实节点号。验证了数据管线端到端可用（除 task_generator.py 需 API 未跑）。
5. 推理框架 `GraphCogent/run.py` 未运行：三阶段均需 vLLM 加载 Llama3.1-8B-Instruct 及其微调权重（config.json 指向 `/home/data2t1/tempuser/...` 不存在的本机路径）+ GPU；且如上所述发布数据缺 `translated_question` 键。按任务要求未下载大模型权重，仅静态核查。
6. 附加静态检查：`import vllm`/`import networkx` 在本机系统 Python 均不可用；requirements.txt（149 个固定版本依赖，含 torch 2.4.0、vllm 0.6.3.post1、torch-geometric 2.6.1）未安装。

## 官方性确认

- 仓库 owner `RongzhengWang` 与论文一作 Rongzheng Wang 同名，且其早先工作 GraphTool-Instruction（KDD 2025）亦在该账号下（论文引用 [32] 自引一致）——判定为作者本人账号。
- README 标题与论文一致，且 pics/method.jpg 与论文 Figure 4 内容一致（Sensory/Buffer/Execution 三模块图）。
- 但 README.md:7 论文链接为 `Paper: [Added later]()`，全文无 arXiv:2508.12379 引用或 arxiv.org 链接（grep 无匹配）；README 顶部仍保留匿名投稿链接（anonymous.4open.science）。官方性：账号官方，但文档未正式引用论文版本。

## 结论

**部分一致（偏"框架对得上、关键机制与数据缺失"）**。仓库确为作者官方仓库，顶层设计（Sensory/Buffer/Execution 三模块概念、9 工具 in-toolset 任务、TPI 训练、DeepSeek-R1 生成任务、5 场景/域、温度 0.7/top_p 1、Llama3.1-8B 骨干）与论文对应；但存在系统性缺口：(1) 论文的多个核心机制在代码中缺失或被替换——GEC、biased random walk、5% 重叠滑动窗口、Buffer 模块（NetworkX/NumPy/PyG 转换与索引）、真实工具执行、CMPO（被普通 DPO 替代）、双阈值迟滞路由、Tool Creator 微调全部缺失或偏离；(2) 评测设置不对应——发布数据仅 100 节点×9 个 in-toolset 任务×400 实例/任务，与论文"三尺度、每任务每尺度 500 实例、21 任务 4200 问"不符，out-toolset 任务数据、eval.py 与全部报告数字均无法在仓库复现或验证；(3) 代码可用性差——框架读取 `translated_question` 键而发布数据无此键，README/bash.sh 多处路径笔误，硬编码他人机器路径与泄露的第三方 API key。

## 局限

- 论文 98.5%/97.6%/token 节省等数字无法验证不等于"造假"，只是仓库未发布评测脚本、模型权重与结果；模型权重（微调后的 agent 模型）未发布，故推理管线本身无法端到端复现。
- 克隆因网络限制为 depth-1 单提交（仓库本身也只有 1 个提交），无法核查历史版本是否曾含更多代码。
- 未运行 task_generator.py（需外部 API），DeepSeek-R1 生成问题环节仅静态确认。
- PDF 表格文字提取为线性文本，个别表格（Table 2/4/5/6）数字以文本流形式核对，未做结构化解析。