Appearance
🧠 SpecFlow CodeGraph 静态代码图谱评估与 P1-P5 各阶段 Token/工具调用基准数据
在评估 SpecFlow CodeGraph 对 AI Agent 开发效率的提升时，产研团队需要经得起工程考量的基准参照物与精准数据模型。本文档基于典型中型业务工程，对 CodeGraph 的选型、P1~P5 各阶段工具调用降幅、以及 Token 成本节省进行定量推导与剖析。
📐 一、 评估基准项目规模 (Benchmark Reference)
为了保证数据的客观性与参考价值，基准评估定位于标准的部门级业务工程：
- 项目规模：中型前端 Vue2/Vue3 工程或中型单体服务 (约 15,000 ~ 25,000 行代码)；
- 文件数量：包含约 40 ~ 60 个 Vue 页面与业务组件，以及 20+ 个 API 接口模块；
- 探索痛点：传统模式下，Agent 无法在单次上下文窗口中知晓完整拓扑，需在多个阶段反复发起
list_dir/grep_search盲扫。
📊 二、 P1 ~ P5 阶段工具调用次数与 Token 消耗逐节点定量推导
澄清：CodeGraph 模式并非 P1~P5 全流程只消耗 1 次工具调用；而是 P1~P5 的每个独立工作流节点，由原来的平均 6~10 次探寻，降低为仅需 1 次调阅物理图谱
codegraph.json。全流程工具调用总数由原来的 ~35 次 大幅降至 5~6 次。
P1~P5 节点定量对比表
| SDD 工作流节点 | 传统模式 (无 Graph) 工具调用次数与原因 | SpecFlow CodeGraph 模式工具调用 | 传统 Token 累计消耗 (上下文轮数+文件内容) | CodeGraph 模式 Token 消耗 | Token 节省比例 |
|---|---|---|---|---|---|
| P1 Specify (需求规格化) | 3~5 次：list_dir 寻找组件，view_file 确认业务上下文 | 1 次：读取 codegraph.json 架构层级 | ~8,000 Tokens (盲目读取多个主文件) | ~1,500 Tokens | 81% |
| P2 Plan (架构拆解) | 5~8 次：grep_search 搜寻 Router, Store, API 依赖链 | 1 次：直接使用图谱中的 Edge 依赖拓扑 | ~12,000 Tokens (多次全文件上下文挂载) | ~2,000 Tokens | 83% |
| P3 Coding (代码落地) | 10~15 次：多次试错、反复 grep 与 view_file 定位目标目录 | 1~2 次：按 codegraph.json 节点精准定位直接修改写盘 | ~25,000 Tokens (反复探寻与大文件重复 Prompt) | ~4,000 Tokens (精准修改上下文) | 84% |
| P4 Testcase (用例矩阵) | 4~6 次：盲扫相关组件寻找方法签名 | 1 次：按节点拓扑导出 API 契约与 Component Props | ~10,000 Tokens | ~2,000 Tokens | 80% |
| P5 Review (静态审计) | 5~10 次：递归扫描受影响的 Git Diff 上下游关系 | 1 次：拓扑分析 Edge 影响节点 | ~15,000 Tokens | ~3,000 Tokens | 80% |
| P1~P5 累计全流程 | 27 ~ 44 次工具调用 (平均 ~35 次) | 5 ~ 6 次工具调用 (每个节点仅 1 次读取图谱) | 全流程累计 ~70,000 Tokens | 全流程累计 ~12,500 Tokens | 整体节省 ~82% |
🏛️ 三、 CodeGraph 选型与 SpecFlow 本地渲染物理方案
- 图谱物理落盘路径：
- 人类在线阅读：
docs/architecture/codegraph.md（原生 Mermaid 脑图，挂载至 VitePress 站点）； - Agent 上下文感知：
docs/architecture/codegraph.json（轻量 JSON 索引，体积约 3~5 KB / ~500 Tokens）；
- 人类在线阅读：
- 免维护原则：
- 规范仓建立或更新时，由 CLI 引擎自动解析并写入上述两个文件，研发团队无需配置或安装复杂的外部服务。
🚀 四、 产研评估改进与优化空间
基于上述物理推导，后续 SpecFlow CodeGraph 的优化演进方向包括：
- 跨文件函数级符号追踪 (Function-level Sub-graph)： 目前 CodeGraph 侧重于文件级与组件级依赖。下一步将下钻至方法与变量级，进一步提升 P3 局部重构的精准度；
- 增量图谱更新机制 (Incremental Graph Update)： 仅对改动文件重新计算 Graph 节点，减少超大型项目全量分析的微小 CPU 开销。
归档路径：
knowledge-base/site/specflow/codegraph-agent-acceleration.md