日常工作知识库

Appearance

CodeGraph 交互式代码脑图与 SpecFlow 可视化架构演进方案 ​

文档版本：v0.10.0
发布日期：2026-08-06
适用场景：SpecFlow 规范仓静态文档站 (VitePress) 交互升级、Agent 极速代码拓扑理解、复杂大中型工程依赖脑图可视化

📌 一、 问题的产生：静态 Mermaid 的“高密度密集死角” ​

在复杂中大型前端/后端工程中（例如物理扫描出的 63 个核心代码节点与 94 条物理依赖链路），静态 HTML/SVG 图引擎（如默认 Mermaid Flowchart）在固定宽度的页面容器中渲染时，面临以下痛点：

  1. 画面挤压密集：节点过多导致图形被强行缩放成极小的像素矩形，文字被挤压成黄线/黄块，完全丢失可读性；
  2. 缺乏交互能力：静态图片无法鼠标滚轮放大缩小、无法按住拖拽画布，更无法在选中某一节点时单独高亮其关联依赖链；
  3. 分层感不强：缺少力导向自动弹开算法，无法按 VueView / ApiClient / UIComponent 进行动态分组高亮。

🛠️ 二、 @specflow/cli@0.10.0 交互式 CodeGraph 脑图引擎突破 ​

在最新的 @specflow/cli@0.10.0 版本中，SpecFlow CodeGraph 引擎进行了重磅交互升级：

💡 核心交互特性 ​

  1. 🔍 无级缩放与拖拽 (Pan & Zoom)： 支持鼠标滚轮自由放大缩小，鼠标按住画布任意平移，解决微观细节查看与宏观全景俯瞰的矛盾；
  2. 🤹 力导向物理布局 (Force-Directed Mindmap)： 引入 D3.js 物理力学模拟（Charge & Collision Force），节点间会自动弹开，天然避免重叠；
  3. 🎨 语义化颜色拓扑：
    • 🔵 VueView（蓝色）：Vue 页面/视图组件
    • 🟢 ApiClient（绿色）：后端接口通讯层
    • 🟠 UIComponent（橙色）：通用 UI 可复用组件
    • 🟡 RouterConfig / UtilityModule（黄色/紫色）：路由与工具函数
  4. 💡 悬浮高亮关联链路 (Hover Connection Highlight)： 鼠标悬浮在任意节点上时，非关联节点自动淡化，只高亮该节点直接 import 或被调用的上下游链路！

🌐 三、 美事在线文档与本地 VitePress 站点的融合 ​

在 npm run docs:dev 启动本地站点时，用户可以直接访问： http://localhost:6060/architecture/codegraph.html

顶部一键查看全屏、可随意放大、拖拽与筛选的交互式 CodeGraph 代码脑图！

知识库沉淀路径：/Users/jinqicheng/Desktop/58work/knowledge-base/site/specflow/interactive-codegraph-mindmap-architecture.md