codegraph/docs/archify/codegraph-explore-nl-query.json

{
  "schema_version": 2,
  "diagram_type": "workflow",
  "meta": {
    "title": "CodeGraph 如何消化自然语言查询",
    "locale": "zh-CN",
    "quality_profile": "showcase",
    "views": [
      {
        "id": "query-to-symbols",
        "label": "查询怎么变成符号",
        "focus": ["question", "explore", "parse_query", "tokens", "find"],
        "note": "一段自然语言先进工具，再筛出符号形状的词，最后落到精确匹配的节点。"
      },
      {
        "id": "symbols-to-path",
        "label": "符号怎么连成调用链",
        "focus": ["find", "disambig", "synth", "flow"],
        "note": "候选节点经过重载消歧，再骑着合成边找出最长的一条调用链。"
      },
      {
        "id": "path-to-answer",
        "label": "调用链怎么变成答案",
        "focus": ["budget", "assemble", "answer"],
        "note": "在预算内装配逐字源码与影响半径，返回的源码可直接当作已 Read。"
      }
    ]
  },
  "lanes": [
    { "id": "agent", "label": "智能体侧" },
    { "id": "tool", "label": "MCP 工具层" },
    { "id": "resolve", "label": "查询与符号解析" },
    { "id": "graph", "label": "图上检索与装配" }
  ],
  "phases": [
    { "id": "p_tokens", "label": "取符号", "fromCol": 0, "toCol": 2 },
    { "id": "p_graph", "label": "落到图上", "fromCol": 3, "toCol": 4, "variant": "emphasis" },
    { "id": "p_out", "label": "装配输出", "fromCol": 5, "toCol": 5, "variant": "dashed" }
  ],
  "groups": [
    { "id": "g_parse", "label": "字符串到符号", "lane": "resolve", "fromCol": 1, "toCol": 2 },
    { "id": "g_resolve", "label": "符号到节点", "lane": "resolve", "fromCol": 3, "toCol": 4 },
    { "id": "g_graph", "label": "图上找路", "lane": "graph", "fromCol": 3, "toCol": 4 }
  ],
  "mainPath": ["question", "explore", "tokens", "find", "flow", "assemble"],
  "semanticChecks": {
    "allowedRoots": ["question", "budget", "synth"],
    "allowedTerminals": ["answer"],
    "requiredEdges": [
      { "from": "question", "to": "explore" },
      { "from": "flow", "to": "assemble" }
    ],
    "requiredPaths": [{ "from": "question", "to": "assemble" }]
  },
  "nodes": [
    {
      "id": "question",
      "lane": "agent",
      "col": 0,
      "type": "external",
      "label": "自然语言提问",
      "sublabel": "X 怎么走到 Y",
      "width": 128
    },
    {
      "id": "answer",
      "lane": "agent",
      "col": 5,
      "type": "backend",
      "label": "直接作答",
      "sublabel": "不再 Read / Grep",
      "width": 128
    },
    {
      "id": "explore",
      "lane": "tool",
      "col": 1,
      "type": "backend",
      "label": "codegraph_explore",
      "sublabel": "默认唯一的工具",
      "tag": "等价于 Read",
      "width": 140
    },
    {
      "id": "budget",
      "lane": "tool",
      "col": 4,
      "type": "backend",
      "label": "输出预算",
      "sublabel": "随仓库规模缩放",
      "width": 128
    },
    {
      "id": "parse_query",
      "lane": "resolve",
      "col": 1,
      "type": "backend",
      "label": "parseQuery",
      "sublabel": "抽出结构化过滤",
      "width": 128
    },
    {
      "id": "tokens",
      "lane": "resolve",
      "col": 2,
      "type": "backend",
      "label": "flowTokens",
      "sublabel": "只留符号形状的词",
      "tag": "最多 16 个",
      "width": 128
    },
    {
      "id": "find",
      "lane": "resolve",
      "col": 3,
      "type": "database",
      "label": "findAllSymbols",
      "sublabel": "精确匹配，不猜",
      "width": 128
    },
    {
      "id": "disambig",
      "lane": "resolve",
      "col": 4,
      "type": "backend",
      "label": "重载消歧",
      "sublabel": "同名时怎么选",
      "width": 128
    },
    {
      "id": "synth",
      "lane": "graph",
      "col": 3,
      "type": "messagebus",
      "label": "合成边",
      "sublabel": "动态分发的跳板",
      "width": 128
    },
    {
      "id": "flow",
      "lane": "graph",
      "col": 4,
      "type": "backend",
      "label": "调用链搜索",
      "sublabel": "最长链优先",
      "tag": "少于 2 个符号就不搜",
      "width": 128
    },
    {
      "id": "assemble",
      "lane": "graph",
      "col": 5,
      "type": "backend",
      "label": "源码装配",
      "sublabel": "逐字源码与半径",
      "width": 128
    }
  ],
  "edges": [
    {
      "id": "q-explore",
      "from": "question",
      "to": "explore",
      "label": "原始 query 文本",
      "variant": "emphasis",
      "role": "main"
    },
    {
      "id": "explore-tokens",
      "from": "explore",
      "to": "tokens",
      "label": "整串交给解析",
      "role": "main"
    },
    {
      "id": "explore-parse",
      "from": "explore",
      "to": "parse_query",
      "label": "同一条 query",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "tokens-find",
      "from": "tokens",
      "to": "find",
      "label": "符号 token",
      "role": "main"
    },
    {
      "id": "parse-find",
      "from": "parse_query",
      "to": "find",
      "label": "kind / path 收窄",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "find-flow",
      "from": "find",
      "to": "flow",
      "label": "候选节点",
      "role": "main"
    },
    {
      "id": "find-disambig",
      "from": "find",
      "to": "disambig",
      "label": "同名多个",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "disambig-flow",
      "from": "disambig",
      "to": "flow",
      "label": "留下连得上的",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "synth-flow",
      "from": "synth",
      "to": "flow",
      "label": "骑合成边过边界",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "flow-assemble",
      "from": "flow",
      "to": "assemble",
      "label": "调用链 + 源码",
      "role": "main"
    },
    {
      "id": "budget-assemble",
      "from": "budget",
      "to": "assemble",
      "label": "调用 / 输出上限",
      "variant": "dashed",
      "role": "branch"
    },
    {
      "id": "assemble-answer",
      "from": "assemble",
      "to": "answer",
      "label": "视为已读，直接作答",
      "variant": "emphasis",
      "role": "return",
      "width": 1.2
    }
  ],
  "cards": [
    {
      "dot": "cyan",
      "title": "查询侧的三个前提",
      "items": [
        "query 是一袋符号，不是一段散文",
        "英文虚词撞名也不会被选中",
        "符号 token 少于 2 个就不搜链"
      ]
    },
    {
      "dot": "emerald",
      "title": "解析侧不猜",
      "items": [
        "精确匹配，绝不静默换成模糊命中",
        "重载按类名或实际连接消歧",
        "合成边也参与找路，接口能走到实现"
      ]
    },
    {
      "dot": "violet",
      "title": "输出侧一次给全",
      "items": [
        "调用链、逐字源码、影响半径一次给全",
        "调用次数与输出随仓库规模缩放",
        "返回源码可直接当作已 Read"
      ]
    }
  ]
}