docs(archify): add CodeGraph architecture and query-handling diagrams
Two self-contained interactive diagrams under docs/archify/, each with its source spec and browser-evidence receipt. - codegraph-architecture: the extraction -> resolution -> query -> context pipeline, the local-first engine boundary, and the MCP / CLI / viewer consumption surfaces. 16 cited source references verified at the indexed revision. - codegraph-explore-nl-query: how codegraph_explore turns a natural-language query into symbols (parseQuery, flowTokens), resolves them to nodes with exact-only matching and overload disambiguation, finds the call path among them, and assembles a budgeted answer. Validation: both pass showcase validation with 9/9 artifact checks and no composition errors or warnings, and visual-check reports no viewport overflow at 1440x900, 1600x1000, 1920x1080, and 2048x1320.
This commit is contained in:
@@ -0,0 +1,283 @@
|
||||
{
|
||||
"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"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
Reference in New Issue
Block a user