[Architecture] 核心契约：.graphspec/ 里面的数据长什么样？(Schema V1 脑暴)

[TatsukiMeng]

背景

前两个 Discussion 明确了我们要“按需加载”且“只读展示 JS/TS 项目”。
现在进入技术硬骨头：当我们在 macOS 终端运行 graphspec init 后，.graphspec/ 目录下生成的数据格式，就是连接 CLI 引擎、本地前端页面、以及未来 AI Agent (MCP) 的唯一契约。

讨论点：如何设计这个 JSON/YAML？

1. 数据的颗粒度问题
我们是存完整的 AST（抽象语法树），还是只存高维度的 Node（节点）和 Edge（边）？
考虑到要让未来的 AI 能够轻松读懂（Token 不能爆炸），我倾向于只存轻量级的元数据。

2. 核心 Interface 草案（请大家 Review 找茬）：

// 这是我的初步构想，大家看看哪里不够用？
interface GraphNode {
  id: string;          // 例如: 'src/components/Button.tsx'
  type: 'module' | 'component' | 'service';
  name: string;
  dependencies: string[]; // 依赖的其他节点 ID
  metadata: {
    description?: string; // 未来留给 AI 生成摘要的坑位
    linesOfCode: number;
  }
}

3. 前后端交互方式 本地的 React 页面怎么拿到这份数据？

• 方案 A：最简单暴力，CLI 扫描完直接吐出一个 data.js 注入到前端页面里，前端纯静态。
• 方案 B：CLI 启动一个本地 Express/Koa 服务器，前端通过 API 增量拉取数据（利于后期渐进式披露）。

请回复：

技术同学请重点 review 上面的 Interface 草案，指出它的缺陷（比如：怎么表达循环依赖？怎么表达外部 npm 包依赖？）。

---

🤖 给 AI 的 Prompt（用于生成结构建议）：

"你现在是 GraphSpec 的首席架构师。请阅读上面的 TypeScript 接口草案和业务诉求（需要支持渐进式披露、未来要接入 MCP）。请指出这个基础数据结构设计的 3 个致命缺陷，并给出一个更合理、更具扩展性的 TypeScript Schema 定义。"

[TatsukiMeng]

基于文件依赖树

• 入口
• 每个文件对应一个 node

filenode

• id(str_int)
• path()
• type( types，interfaces，或者 controller，handler，或者 pkg other ... 或者 service、models)
• name
• desc
• deps(father/son)
• meta

有的文件可能只是 types，interfaces，或者 controller，handler，或者 pkg other ...

基于 domain(偏业务)

（UML）展示数据流、函数依赖关系

modulenode

• id(str_int)
• type(预留)
• path()
• name
• desc
• deps(father/son)
• children(子图)
• meta

deps

传什么数据

业务模型

[TatsukiMeng]

这份基础数据结构设计非常轻量，出发点很好，但如果要支撑未来的“渐进式披露”以及作为 AI Agent (MCP) 的标准契约，现有的 GraphNode 草案存在以下 3 个致命缺陷：

核心接口草案的 3 个致命缺陷

1. 关系（Edge）的语义与维度丢失
   单纯使用 dependencies: string[] 只能表达“A 认识 B”，无法表达“A 为什么认识 B”。AI 和前端无从得知这是一个运行时的函数调用、一个纯类型导入（import type）、还是对外部 NPM 生态的依赖。这种设计也无法有效记录或预警循环依赖（通常需要明确的边指向和权重）。
2. 缺乏层级与作用域边界（无法支持渐进式披露）
   当前的结构过于扁平化。面对几千个文件的中大型项目，扁平的节点列表会让前端渲染崩溃，也会瞬间耗尽 AI 的 Token 上下文。缺少“容器（Container）”或“子图（Subgraph）”的概念，前端无法实现“先查看高层级模块，点击后再展开查看内部文件”的渐进式交互。
3. 物理视图与逻辑视图的强耦合
   将物理路径（id: 'src/...'）与逻辑角色（type: 'service'）直接绑定在一个节点上是不严谨的。在实际的 JS/TS 项目中，一个物理文件可能导出多个不同类型的逻辑实体，或者一个庞大的 Domain/Service 会跨越多个文件夹。物理依赖树（File Tree）和业务逻辑图（Domain Graph）需要分离或具备清晰的映射层。

---

关于前后端交互方式的抉择

为了实现架构目标，方案 B（CLI 启动本地服务器，增量拉取）是绝对的必选项。

方案 A（注入全量静态 JS）只适合轻量级的一次性分析报告。由于 GraphSpec 旨在接入 MCP 并支持渐进式披露，你需要一个可以随时响应局部查询（如：GET /api/graph/module?id=auth）的网关。在 macOS 的开发环境中，通过 CLI 拉起一个基于本地守护进程的极轻量级服务（如基于 Hono 或原生 HTTP 模块，而非沉重的 Express）是非常符合开发者习惯的。

---

GraphSpec 核心模型详细文档 (Schema Definition)

基于将物理视图（FileNode）与业务视图（ModuleNode）解耦的思路，以下是重构后具备高扩展性的 TypeScript Schema 定义：

/**
 * -----------------------------------------
 * 1. 基础枚举与公共定义
 * -----------------------------------------
 */

// 节点的基础物理分类
export enum FileNodeType {
  FILE = 'file',
  NPM_PACKAGE = 'npm_package', // 外部依赖
  EXTERNAL_GLOBAL = 'external_global', // 如 window, document
}

// 节点的基础逻辑/业务分类
export enum LogicNodeType {
  MODULE = 'module',       // 业务领域/子图
  COMPONENT = 'component', // UI 组件
  SERVICE = 'service',     // 业务服务
  TYPES = 'types',         // 纯类型定义
  CONTROLLER = 'controller',
  UNKNOWN = 'unknown',
}

// 边的类型：描述依赖的本质
export enum EdgeType {
  IMPORT_DEFAULT = 'import_default',
  IMPORT_NAMED = 'import_named',
  IMPORT_TYPE = 'import_type', // 仅类型依赖，运行时无关联
  DYNAMIC_IMPORT = 'dynamic_import', // 异步加载，利于按需分析
  DATA_FLOW = 'data_flow',     // UML 数据流向
  COMPOSITION = 'composition', // 包含关系 (父子)
}

/**
 * -----------------------------------------
 * 2. 关系（Edge）定义：将连线实体化
 * -----------------------------------------
 */
export interface GraphEdge {
  id: string;              // e.g., 'edge_src_to_dst'
  sourceId: string;        // 发起依赖的节点 ID
  targetId: string;        // 被依赖的节点 ID
  type: EdgeType;
  metadata?: {
    isCyclic?: boolean;    // 是否构成循环依赖
    importedNames?: string[]; // 具体引入了哪些变量/函数
  };
}

/**
 * -----------------------------------------
 * 3. 节点（Node）体系设计
 * -----------------------------------------
 */

// 基础节点
interface BaseNode {
  id: string;              // 唯一标识符，基于 hash 或标准化后的路径
  name: string;            // 节点展示名
  description?: string;    // 留给 AI Agent 自动生成的摘要坑位
}

// 物理文件节点 (基于文件依赖树)
export interface FileNode extends BaseNode {
  kind: 'file';            // 区分基类类型
  fileType: FileNodeType;
  path: string;            // 相对路径或 npm 包名
  extension: string;       // .ts, .tsx, .js
  exports: string[];       // 对外暴露的 API/变量名
  metadata: {
    linesOfCode: number;
    lastModified?: number;
    complexityScore?: number; // 预留给 AI 的圈复杂度评分
  };
}

// 业务模块节点 (基于 Domain 视图，支持子图)
export interface ModuleNode extends BaseNode {
  kind: 'module';          // 区分基类类型
  logicType: LogicNodeType;
  domain: string;          // 归属的业务领域，如 'UserAuth'
  childrenIds: string[];   // 包含的子节点 ID（可以是 FileNode 或下级 ModuleNode，实现渐进式披露）
  entryPoint?: string;     // 该模块的主入口节点 ID (如 index.ts 的 FileNode ID)
  metadata: {
    businessRule?: string; // AI 理解业务逻辑的切入点
    isPublicApi: boolean;  // 是否对外暴露为公共服务
  };
}

export type GraphNode = FileNode | ModuleNode;

/**
 * -----------------------------------------
 * 4. 根结构（Manifest）：输出的最终数据契约
 * -----------------------------------------
 */
export interface GraphManifest {
  version: string;         // Schema 版本号，保证向前兼容
  project: {
    name: string;
    rootPath: string;
    analyzedAt: string;    // ISO 8601 时间戳
  };
  nodes: Record<string, GraphNode>; // 拍平的节点字典，O(1) 查找，按需拉取
  edges: Record<string, GraphEdge>; // 拍平的边字典
}

改进优势解析

1. Record<string, Object> 字典结构：替代了嵌套数组。这极大地优化了前端的渲染逻辑，本地 HTTP 服务可以通过 ID 进行 O(1) 的快速查询和分页返回。
2. 独立的 GraphEdge 实体：剥离了节点内的 dependencies。现在你可以清晰地表达一个组件仅仅是导入了另一个文件的 interface（无运行时成本），或者明确标记出 isCyclic: true 供前端标红展示循环依赖。
3. ModuleNode 引入：通过 childrenIds 实现了树状/网状的聚合。前端首次请求只需拉取最高层级的 ModuleNode 及它们之间的关系，用户点击某个模块时，再去请求具体的 FileNode 数据，完美解决 Token 限制与渲染性能问题。

[TatsukiMeng]

点一个节点通过节点找到所有相关内容

[Misaka13906]

相当于 uml 图的结构化版本，定结构化的数据结构