日常工作知识库

Appearance

SpecFlow SDD 代码分析与架构图谱引擎设计与开源对比 ​

📌 一、 需求背景与痛点复盘 ​

在 SpecFlow 的 Spec-Driven AI 开发工作流（SDD）实施过程中，曾经出现过**“在纯前端 Vue 项目 (reimburse-pc) 中错生成 Java 代码”**的问题。

经排查，根因在于 CLI 早期采用了硬编码判别逻辑 (name.startsWith('fe-') || projectDir.includes('fe-'))，未真实索引与感知目标工程的物理技术栈与规范仓 (reimburse-pc-spec) 契约。

为了在 SDD 流水线中实现工程架构自动感知、Token 消耗极小化（85%+ 节省）、零成本高可用的目标，需要为 SpecFlow 设计一套可靠的代码分析与图谱资产引擎。

📌 二、 开源方案与自研技术路线对比 ​

针对代码图谱与依赖分析，我们对业界主流方案进行了对比评估：

评估维度方案 A：集成第三方 MCP 扩展
(codebase-memory-mcp / code-review-graph)		方案 B：重型 tree-sitter 编译自建方案 C：【推荐】 SpecFlow 轻量分层自研引擎
(dependency-cruiser + 纯 JS/Node 扫描)
物理依赖与稳定性❌ 依赖外部 MCP Server / C++ 原生库编译（如 better-sqlite3），在 Linux/Alpine Docker 环境下易崩溃。⚠️ WASM / Native C 绑定在不同 OS 下容易出现 Native Binding 丢失错误。✅ 100% Pure JS/Node.js 实现，零 Native 编译，跨 macOS、Windows、GitLab CI 物理保证 100% 高可用。
维护成本与锁入风险❌ 存在第三方 GitHub 仓库断更、破坏性变更和商业锁入风险。⚠️ 需要为 Vue / TS / Java 手写复杂 AST 解析规则，初始开发成本高。✅ 零第三方仓库锁入，核心数据结构与 schema 完全由 SpecFlow CLI 自主掌控。
** Token 节省与性能**✅ 可生成图谱，节省 80%+ Token。✅ 极快，节省 90%+ Token。✅ 秒级抽取 JSON 依赖拓扑图，AI Agent 只需读取 5KB 拓扑 JSON，物理节省 85%+ Token 开销。
技术栈覆盖能力适用于多语言。适用于多语言。✅ 前端使用 dependency-cruiser / es-module-lexer
✅ 后端使用纯 JS 规则与依赖识别 (Java/Go)。

📌 三、 SpecFlow 引擎架构设计 ​

SpecFlow 轻量分层自研引擎架构如下：

                    ┌──────────────────────────────────────────────┐
                    │      SpecFlow CLI 架构图谱自研引擎            │
                    └──────────────────────┬───────────────────────┘
                                           │
             ┌─────────────────────────────┴─────────────────────────────┐
             ▼                                                           ▼
┌──────────────────────────┐                               ┌──────────────────────────┐
│   前端 (Vue / TS / React)│                               │    后端 (Java / Go / Node)│
│  使用 dependency-cruiser │                               │  使用纯 JS 规则与结构提取 │
└────────────┬─────────────┘                               └────────────┬─────────────┘
             │                                                           │
             └─────────────────────────────┬─────────────────────────────┘
                                           ▼
                    ┌──────────────────────────────────────────────┐
                    │ 统一生成 SpecFlow 标准化 DAG 架构矩阵 (JSON)   │
                    │ 存储于: reimburse-pc-spec/analysis-manifest  │
                    └──────────────────────┬───────────────────────┘
                                           │
             ┌─────────────────────────────┴─────────────────────────────┐
             ▼                                                           ▼
┌──────────────────────────┐                               ┌──────────────────────────┐
│ 驱动 VitePress 渲染      │                               │ 驱动 AI Agent / SDDX     │
│  Mermaid 全景拓扑图      │                               │  精准定位文件，节省 Token  │
└──────────────────────────┘                               └──────────────────────────┘

核心资产输出范式 (Stored in reimburse-pc-spec) ​

  1. specflow.config.json（工程契约元数据）：
    json
    {
  "projectName": "reimburse-pc",
  "techStack": ["vue3", "typescript"],
  "anchorPath": "../reimburse-pc",
  "analyzerVersion": "1.0.0"
}
  2. analysis-manifest.json（代码依赖拓扑矩阵）：
    json
    {
  "projectName": "reimburse-pc",
  "scanTime": "2026-07-31T15:30:00Z",
  "modules": [
    {
      "id": "src/views/reimburse/index.vue",
      "type": "view",
      "label": "个人费用报销单主视图",
      "dependencies": ["src/api/reimburse.ts", "src/components/useDialog.vue"]
    }
  ]
}

📌 四、 用户体验说明：完全无感知使用 ​

终端开发者在后续使用 SpecFlow 时，体验是完全静默零感知的：

  1. 一键初始化 (specflow init)： 用户只需像往常一样运行 specflow init --name reimburse-pc-spec --anchor-path ../reimburse-pc，CLI 会在后台毫秒级完成技术栈检测与依赖拓扑提取，自动落盘 specflow.config.json 与 analysis-manifest.json。
  2. 零参数全闭环 (specflow sddx)： 运行 specflow sddx 时，CLI 自动读取关联规范仓契约，精确识别为 Vue 前端项目并准确生成 Vue 业务组件及单元测试，不再触发任何报错或语言误判。