[Vision] GraphSpec V0.1：当用户敲下 graphspec 时，我们到底要帮他解决什么痛点？

[TatsukiMeng]

背景

按照 https://tatsukimeng.github.io/ai-native-engineering/docs/01-breakthrough/05-main-project 的规划，GraphSpec V0.1 只有两个命令：init（初始化） 和 view（本地可视化）。
但在写代码之前，我们需要统一认知：开发者在这个本地页面里，第一眼必须看到什么，才会有“哇，这东西真有用”的 Aha Moment？

请思考并回复以下问题：

1. 最痛的真实场景是什么？（请二选一，或补充）

• 场景 A (查 Bug 溯源)： 修改了一个底层的公共组件，不知道到底影响了上层哪些业务线，怕改出线上事故。需要一眼看清“依赖爆炸半径”。
• 场景 B (上下文补全)： AI (比如 Cursor) 改代码时把依赖关系搞乱了，人类需要一个“上帝视角”来审查系统当前的真实连线状态。
• 场景 C (你的补充)： ________________

2. 为了满足上述场景，“渐进式披露”在 V0.1 意味着什么？
如果我们扫描了一个项目，view 出来的第一层应该是：

• A. 按系统文件夹结构展示的纯树状图？
• B. 按业务领域（Domain）聚合的模块图，点击模块再下钻看具体组件？

---

🤖 给 AI 的 Prompt（请将此段丢给大模型并把它的回答贴在下面）：

"你现在是一个深度使用过 Cursor 和各路 AI 编码工具的全栈开发者。请阅读上面的讨论，告诉我：在你日常开发中，遇到由于『缺乏全局架构上下文』而导致的翻车案例是什么？并基于此，为 GraphSpec V0.1 投票选择最痛的场景。"

[Misaka13906]

AI 写文档会偷懒（（，也就是没有什么手段去判定或者保证写的文档充足，包括测试用例

具体例子是我让 AI 调研工业界代码规范，以及一些软件工程最佳实践的流程，沉淀为文档，这个文档没法保证充足和质量

[TatsukiMeng]

新老目录同时存在，AI 可能理解错要改那个
有很多文档但是 AI 不喜欢看
AI 不喜欢把代码沉淀为文档
上下文压缩多次丢失目标
接手老项目但是没有文档，没有背景知识很难 AI Native 开发
多 Agent 协作通信贵，效率低

[TatsukiMeng]

2. AB都要有

[TatsukiMeng]

AI回答

先追 3 个边缘问题，避免 V0.1 一开始就做偏：

1. 你的目标仓库主要是单前端应用，还是 monorepo / 全栈仓？
   如果有 apps/*、packages/*、shared/*，那“领域聚合”会很自然；如果只是一个 src/ 大平铺，聚合规则要提前定义。

2. V0.1 的“依赖”只看静态 import/export，还是也想纳入路由、API 调用、状态注入这类隐式依赖？
   这决定了第一版的承诺边界。我的建议是 先只承诺静态依赖图。

3. 你更想解决“改动前风险评估”，还是“AI 改完后的人工审计”？
   这两个都真实，但产品切入口最好只选一个。

---

在你回复前，我先给一个明确结论：

结论先说

• 问题 1：我投 A
• 问题 2：我投 B

但有一个关键修正：

我建议把场景 A 的命名，从“查 Bug 溯源”改成 “变更影响半径（Blast Radius Review）”。

因为真正让人产生 Aha Moment 的，不是“出事后查”，而是：

“我准备改这个 shared / 底层模块，GraphSpec 能不能 3 秒告诉我：会炸到哪些域？”

这比“Bug 溯源”更前置、更高频，也更适合 V0.1。

---

1. 最痛的真实场景：选 A，但重新命名

为什么不是先打 B？

B 很符合 AI-Native 叙事，但它有个问题：

• B 是感受型痛点：AI 把依赖搞乱了，我需要上帝视角审查。
• A 是决策型痛点：我要不要动这个底层模块？动了会影响谁？

对于 V0.1 只有 init + view 来说，A 更具体、更可验证、更容易让用户立刻感知价值。

一个简单对比

维度	A. 变更影响半径	B. AI 审查上帝视角
用户频率	高	中高
是否能靠静态图直接证明价值	很强	中等
是否能一眼形成 wow	很强	取决于用户是否刚被 AI 坑过
V0.1 适配度	很高	中

我建议的场景表述

不是“查 Bug 溯源”，而是：

场景 C（推荐文案）

变更影响评审：
我要改一个 shared / 底层模块，在提交前，需要一眼看清它的依赖爆炸半径、跨域影响、潜在循环依赖。

这个 C 本质上是 A 的前移版，而且天然覆盖 B：
AI 改乱依赖，本质也是“变更影响评审”时暴露出来。

---

2. “渐进式披露”在 V0.1 的定义：选 B，不选纯树

第一层必须是：按业务领域 / 边界聚合的模块图

不是文件树。

因为：

• 树状图回答的是：东西放在哪。
• GraphSpec 要回答的是：改了谁会受影响。

文件树，IDE / Finder / 终端早就有了。
如果 view 打开第一眼只是树，用户不会“哇”，只会觉得：

“这不就是换皮版 sidebar 吗？”

第一层应该长什么样？

用户打开 view，第一眼看到的应该是：

1) 一个“域级地图”

例如：

• checkout
• account
• admin
• shared-ui
• shared-utils

每个节点不是静态名字，而是带风险信息：

• 被多少模块依赖（fan-in）
• 依赖了多少外部模块（fan-out）
• 影响多少业务域
• 是否存在跨域边
• 是否卷入循环依赖

2) 一个“热点榜”

右侧或顶部直接列：

• 最危险的 5 个共享模块
• 最多被反向依赖的节点
• 跨域连接最多的节点
• 有循环依赖的节点

3) 一个“选中即出爆炸半径”的焦点面板

点 shared-ui/Button 后，立刻出现：

• 直接依赖它的模块数
• 间接影响的文件数
• 波及的业务域
• 最关键的几条传播路径

这才是 Aha Moment。

---

你要的“第一眼必须看到什么”

如果要压缩成一句产品语言，就是：

不是先看到代码结构，而是先看到风险结构。

更具体一点，V0.1 首页应该让开发者在 5 秒内看到：

1. 系统被分成了哪些业务边界
2. 哪几个节点是“高爆炸半径”热点
3. 点击任一节点后，它会影响哪些上游/下游
4. 有没有明显越界连接或循环依赖

---

V0.1 的渐进式披露，我建议固定成 3 层

L0：域级 / 边界级总览

回答：

• 系统有哪些边界？
• 哪些边界互相耦合？
• 哪些共享模块最危险？

L1：域内模块图

点击某个 domain 后，下钻到：

• 该域内部的模块依赖
• 该域对外依赖了谁
• 外部谁在反向依赖它

L2：文件 / 组件级明细

再点进去才看：

• 具体文件
• 具体 import 路径
• 具体依赖传播路径

树状图可以有，但只能做辅助导航，不应该是主画布。

---

我建议先冻结的数据契约

不是实现代码，只是把认知先钉死。

type GraphLevel = 'domain' | 'module' | 'file';

interface GraphSpecConfig {
  root: string;
  aggregation: 'domain';
  domains: Array<{
    id: string;
    label: string;
    include: string[]; // glob patterns
  }>;
  edgeTypes: Array<'import'>; // V0.1 先只承诺静态依赖
}

interface GraphNode {
  id: string;
  label: string;
  level: GraphLevel;
  path?: string;
  parentId?: string;
  kind: 'domain' | 'shared' | 'module' | 'component' | 'file';
  metrics: {
    fanIn: number;
    fanOut: number;
    transitiveDependents: number;
    impactedDomains: number;
    crossBoundaryEdges: number;
    cycleCount: number;
    riskScore: number;
  };
}

interface GraphEdge {
  from: string;
  to: string;
  type: 'import';
  crossBoundary: boolean;
  weight: number;
}

interface ImpactSummary {
  nodeId: string;
  directDependents: string[];
  transitiveDependents: string[];
  impactedDomains: string[];
  criticalPaths: string[][];
  cycles: string[][];
}

interface GraphViewModel {
  defaultLevel: 'domain';
  nodes: GraphNode[];
  edges: GraphEdge[];
  topHotspots: string[]; // node ids
  focus?: ImpactSummary;
}

这几个契约背后的核心意思是：

• GraphSpec V0.1 的本质不是“画图工具”
• 而是一个 “依赖风险解释器”

---

我对你这两个问题的最终投票

Q1. 最痛的真实场景

✅ 选 A
但建议改名为：变更影响半径 / Blast Radius Review

Q2. view 第一层该怎么展示

✅ 选 B
按业务领域聚合的模块图，点击再下钻到组件/文件

---

模拟“丢给另一个大模型”的回答

我日常最常见的翻车案例，不是单点代码写错，而是 Cursor 在“帮我抽公共逻辑”时，无意把原本隔离的两个业务域连在了一起。比如它把 checkout 和 admin 共用到一个 shared/utils 里，短期看编译没问题、局部功能也能跑，但后面我改这个 util 时，两个业务线一起受影响。最糟糕的是，光看 diff 很难判断影响范围，因为我没有一个地方能直接看到“这个模块已经被哪些域反向依赖”。

所以如果让我给 GraphSpec V0.1 投票，我投 场景 A，但我会把它理解成“变更影响半径”，而不只是“查 Bug 溯源”。因为这是更高频、更刚需的动作。场景 B 也真实存在，但它本质上是 A 在 AI 编码时代的一种触发方式。

---

[Agent 执行预警]

如果你把这个方案直接丢给 Cursor / Cline，让它们自己跑，最容易翻车的点有 4 个：

1. 把“目录”误当“领域”
   Agent 很容易直接按文件夹画图，最后得到一张漂亮但没价值的图。
   规避： init 必须显式产出一份 GraphSpecConfig，定义 domain 聚合规则。

2. 默认展示文件级全量图，直接把页面炸成毛线球
   这是 Agent 最爱干的事。
   规避： 强制默认视图为 domain 级；文件级只允许在 focus drill-down 后出现。

3. 漏掉路径别名 / barrel file，导致假热点或假断边
   如 @/shared、index.ts re-export 会让依赖图失真。
   规避： 扫描器必须解析 tsconfig/vite alias，并对 barrel 做归一化或显式标注。

4. 给用户“全知全能”的错觉
   V0.1 如果只扫静态 import，就不能假装自己看到了运行时依赖。
   规避： 页面必须明确标注：Coverage: static import graph only。

---

如果你愿意，我下一步可以直接帮你把这件事继续往前钉死成两份东西之一：

1. V0.1 首页信息架构草图（用户第一屏有哪些区块）
2. init 生成的配置文件规范（GraphSpec 如何定义 domain 聚合）

我建议先做第 2 个，因为没有聚合契约，就不会有真正有价值的第 1 屏。