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:
2026-09-12 23:05:42 +08:00
parent 3ed73bc127
commit 37ccb33ba0
6 changed files with 31845 additions and 0 deletions
File diff suppressed because one or more lines are too long
+393
View File
@@ -0,0 +1,393 @@
{
"schema_version": 1,
"diagram_type": "architecture",
"meta": {
"title": "CodeGraph Architecture",
"locale": "en",
"quality_profile": "showcase",
"repository": {
"url": "https://github.com/colbymchenry/codegraph",
"provider": "github",
"link_mode": "web",
"revision": "3ed73bc127323e63153bf6ec8354afa82ce36aaf"
},
"views": [
{
"id": "indexing",
"label": "Indexing a repository",
"focus": [
"repo",
"watcher",
"orchestrator",
"sqlite"
],
"note": "Source files become symbols, edges and files in one local SQLite index."
},
{
"id": "resolution-and-query",
"label": "Resolution and query",
"focus": [
"sqlite",
"resolver",
"graph",
"context"
],
"note": "Stored symbols are resolved into a graph, then traversed into context."
},
{
"id": "consumption",
"label": "Consumption surfaces",
"focus": [
"context",
"mcp",
"cli",
"viewer",
"agents"
],
"note": "One engine, three read-only surfaces, with MCP as the agent path."
}
]
},
"layout": {
"mode": "grid",
"cols": 6,
"cellW": 175,
"cellH": 64,
"gapX": 25,
"gapY": 54
},
"components": [
{
"id": "repo",
"type": "external",
"label": "Source Codebase",
"sublabel": "any supported language",
"row": 0,
"col": 0,
"size": [
145,
64
]
},
{
"id": "watcher",
"type": "backend",
"label": "File Watcher",
"sublabel": "native FS events",
"row": 1,
"col": 1,
"sources": [
{
"path": "src/sync/watcher.ts"
}
],
"size": [
145,
64
]
},
{
"id": "orchestrator",
"type": "backend",
"label": "Extraction",
"sublabel": "tree-sitter AST",
"tag": "29 wasm grammars",
"row": 0,
"col": 1,
"sources": [
{
"path": "src/extraction/tree-sitter.ts"
},
{
"path": "src/extraction/parse-worker.ts"
}
],
"size": [
145,
64
]
},
{
"id": "sqlite",
"type": "database",
"label": "SQLite Index",
"sublabel": "nodes · edges · files",
"tag": "WAL + FTS5",
"row": 0,
"col": 2,
"sources": [
{
"path": "src/db/schema.sql"
},
{
"path": "src/db/sqlite-adapter.ts"
}
],
"size": [
145,
64
]
},
{
"id": "resolver",
"type": "backend",
"label": "Reference Resolver",
"sublabel": "imports · names · frameworks",
"row": 0,
"col": 3,
"sources": [
{
"path": "src/resolution/import-resolver.ts"
},
{
"path": "src/resolution/name-matcher.ts"
}
],
"size": [
145,
64
]
},
{
"id": "graph",
"type": "backend",
"label": "Graph Query",
"sublabel": "callers · callees · impact",
"row": 0,
"col": 4,
"sources": [
{
"path": "src/graph/queries.ts"
},
{
"path": "src/graph/traversal.ts"
}
],
"size": [
145,
64
]
},
{
"id": "context",
"type": "backend",
"label": "Context Builder",
"sublabel": "markdown / JSON",
"row": 0,
"col": 5,
"sources": [
{
"path": "src/context/index.ts"
},
{
"path": "src/context/formatter.ts"
}
],
"size": [
145,
64
]
},
{
"id": "viewer",
"type": "frontend",
"label": "Browser Viewer",
"sublabel": "read-only JSON API",
"row": 1,
"col": 3,
"sources": [
{
"path": "src/ui-server/index.ts"
},
{
"path": "ui/src/App.svelte"
}
],
"size": [
145,
64
]
},
{
"id": "cli",
"type": "backend",
"label": "CLI",
"sublabel": "init · index · query",
"row": 1,
"col": 4,
"sources": [
{
"path": "src/bin/codegraph.ts"
}
],
"size": [
145,
64
]
},
{
"id": "mcp",
"type": "backend",
"label": "MCP Server",
"sublabel": "codegraph_explore · node",
"row": 1,
"col": 5,
"sources": [
{
"path": "src/mcp/tools.ts"
},
{
"path": "src/mcp/server-instructions.ts"
}
],
"size": [
145,
64
]
},
{
"id": "agents",
"type": "external",
"label": "AI Agents",
"sublabel": "Claude Code · Cursor · Codex",
"row": 2,
"col": 5,
"size": [
145,
64
]
}
],
"boundaries": [
{
"kind": "region",
"label": "CodeGraph engine — local-first, no server",
"wraps": [
"orchestrator",
"sqlite",
"resolver",
"graph",
"context"
]
}
],
"connections": [
{
"id": "repo-to-orchestrator",
"from": "repo",
"to": "orchestrator",
"label": "source files",
"variant": "emphasis",
"labelAt": [
213,
158
]
},
{
"id": "watcher-to-orchestrator",
"from": "watcher",
"to": "orchestrator",
"label": "incremental sync",
"variant": "dashed"
},
{
"id": "orchestrator-to-sqlite",
"from": "orchestrator",
"to": "sqlite",
"label": "parsed symbols & edges",
"labelAt": [
413,
158
]
},
{
"id": "sqlite-to-resolver",
"from": "sqlite",
"to": "resolver",
"label": "stored symbols",
"labelAt": [
613,
158
]
},
{
"id": "resolver-to-graph",
"from": "resolver",
"to": "graph",
"label": "resolved edges",
"labelAt": [
740,
158
]
},
{
"id": "graph-to-context",
"from": "graph",
"to": "context",
"label": "traversal results",
"labelAt": [
940,
158
]
},
{
"id": "context-to-mcp",
"from": "context",
"to": "mcp",
"label": "context payload",
"labelAt": [
1113,
158
]
},
{
"id": "context-to-cli",
"from": "context",
"to": "cli",
"label": "markdown / JSON",
"variant": "dashed"
},
{
"id": "graph-to-viewer",
"from": "graph",
"to": "viewer",
"label": "read-only JSON API",
"variant": "dashed"
},
{
"id": "agents-to-mcp",
"from": "agents",
"to": "mcp",
"label": "MCP tool calls"
}
],
"cards": [
{
"dot": "cyan",
"title": "Deterministic extraction",
"items": [
"Symbols and edges come from the AST, never LLM summaries",
"29 tree-sitter grammars, with heavy parsing off the main thread",
"Re-indexing the same source produces the same graph"
]
},
{
"dot": "emerald",
"title": "One local index",
"items": [
"SQLite with WAL and FTS5 under .codegraph/",
"Node's built-in node:sqlite — no native build step",
"Per project, and it never leaves the machine"
]
},
{
"dot": "violet",
"title": "Graph to answer",
"items": [
"Import, name, framework and dynamic-dispatch resolution",
"Callers, callees, impact radius and named-symbol flow",
"Three read-only surfaces: MCP server, CLI, browser viewer"
]
}
]
}
@@ -0,0 +1,548 @@
{
"schemaVersion": 1,
"ok": true,
"command": "visual-check",
"evidenceKind": "automated-browser",
"status": "pass",
"visualReview": "pending",
"artifact": {
"path": "/Users/james/github/codegraph/docs/archify/codegraph-architecture.html",
"sha256": "2f64f514f5f5b46e3c9c5ff96a8cac198c557f2a3879bfe77d60ae7a486aa892",
"bytes": 817256
},
"state": {
"detail": "read",
"motion": "still"
},
"chrome": {
"status": "available",
"executable": "/Users/james/Library/Caches/ms-playwright/chromium-1228/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
},
"diagnostics": [],
"containment": {
"status": "pass",
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1376,
"diagramWidth": 1346,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1536,
"diagramWidth": 1506,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1856,
"diagramWidth": 1826,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1920,
"diagramWidth": 1870,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"readability": {
"status": "pass",
"minimumProjectedNodeTextPx": 6,
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1376,
"diagramWidth": 1346,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1536,
"diagramWidth": 1506,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1856,
"diagramWidth": 1826,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1920,
"diagramWidth": 1870,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"viewerChrome": {
"status": "pass",
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1376,
"diagramWidth": 1346,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1536,
"diagramWidth": 1506,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1856,
"diagramWidth": 1826,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1920,
"diagramWidth": 1870,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"captures": {
"status": "pass",
"screenshots": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1376,
"diagramWidth": 1346,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light",
"file": "codegraph-architecture.visual-check.1440x900.light.png"
},
{
"width": 1440,
"height": 900,
"theme": "dark",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1376,
"diagramWidth": 1346,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "dark",
"file": "codegraph-architecture.visual-check.1440x900.dark.png"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1920,
"diagramWidth": 1870,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light",
"file": "codegraph-architecture.visual-check.2048x1320.light.png"
},
{
"width": 2048,
"height": 1320,
"theme": "dark",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1920,
"diagramWidth": 1870,
"viewBoxWidth": 1255,
"minimumProjectedNodeTextPx": 8.1,
"minimumProjectedNodeText": "imports · names · frameworks",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "dark",
"file": "codegraph-architecture.visual-check.2048x1320.dark.png"
}
],
"contactSheet": "codegraph-architecture.visual-check.html"
},
"sidecars": {
"receipt": "codegraph-architecture.visual-check.json",
"contactSheet": "codegraph-architecture.visual-check.html"
}
}
File diff suppressed because one or more lines are too long
@@ -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"
]
}
]
}
@@ -0,0 +1,548 @@
{
"schemaVersion": 1,
"ok": true,
"command": "visual-check",
"evidenceKind": "automated-browser",
"status": "pass",
"visualReview": "pending",
"artifact": {
"path": "/Users/james/github/codegraph/docs/archify/codegraph-explore-nl-query.html",
"sha256": "34ea6122ebd2681ee9d0638f2b7337e36e4dd7298079e1a219feaa2091e84895",
"bytes": 818359
},
"state": {
"detail": "read",
"motion": "still"
},
"chrome": {
"status": "available",
"executable": "/Users/james/Library/Caches/ms-playwright/chromium-1228/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"
},
"diagnostics": [],
"containment": {
"status": "pass",
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 992,
"diagramWidth": 962,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.645941278065631,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1023,
"diagramWidth": 993,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.860103626943006,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1161,
"diagramWidth": 1131,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 7.813471502590674,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1522,
"diagramWidth": 1472,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 8,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"readability": {
"status": "pass",
"minimumProjectedNodeTextPx": 6,
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 992,
"diagramWidth": 962,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.645941278065631,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1023,
"diagramWidth": 993,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.860103626943006,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1161,
"diagramWidth": 1131,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 7.813471502590674,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1522,
"diagramWidth": 1472,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 8,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"viewerChrome": {
"status": "pass",
"viewports": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 992,
"diagramWidth": 962,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.645941278065631,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1600,
"height": 1000,
"theme": "light",
"innerWidth": 1600,
"innerHeight": 1000,
"scrollWidth": 1600,
"scrollHeight": 1000,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1023,
"diagramWidth": 993,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.860103626943006,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 1920,
"height": 1080,
"theme": "light",
"innerWidth": 1920,
"innerHeight": 1080,
"scrollWidth": 1920,
"scrollHeight": 1080,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1161,
"diagramWidth": 1131,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 7.813471502590674,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1522,
"diagramWidth": 1472,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 8,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light"
}
]
},
"captures": {
"status": "pass",
"screenshots": [
{
"width": 1440,
"height": 900,
"theme": "light",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 992,
"diagramWidth": 962,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.645941278065631,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light",
"file": "codegraph-explore-nl-query.visual-check.1440x900.light.png"
},
{
"width": 1440,
"height": 900,
"theme": "dark",
"innerWidth": 1440,
"innerHeight": 900,
"scrollWidth": 1440,
"scrollHeight": 900,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 992,
"diagramWidth": 962,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 6.645941278065631,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 51,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "dark",
"file": "codegraph-explore-nl-query.visual-check.1440x900.dark.png"
},
{
"width": 2048,
"height": 1320,
"theme": "light",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1522,
"diagramWidth": 1472,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 8,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "light",
"file": "codegraph-explore-nl-query.visual-check.2048x1320.light.png"
},
{
"width": 2048,
"height": 1320,
"theme": "dark",
"innerWidth": 2048,
"innerHeight": 1320,
"scrollWidth": 2048,
"scrollHeight": 1320,
"overflowX": false,
"overflowY": false,
"ok": true,
"readerWidth": 1522,
"diagramWidth": 1472,
"viewBoxWidth": 1158,
"minimumProjectedNodeTextPx": 8,
"minimumProjectedNodeText": "X 怎么走到 Y",
"minimumProjectedNodeTextDetail": "context",
"minimumRequiredNodeTextPx": 6,
"readabilityOk": true,
"hasLegend": true,
"hasNavigationDock": true,
"legendDockIntersectionArea": 0,
"dockStageIntersectionArea": 0,
"dockStageGap": 10.21875,
"requiredDockStageGap": 10,
"viewerChromeStageOk": true,
"viewerChromeReserve": 41,
"viewerChromeActive": true,
"viewerChromeOk": true,
"resolvedTheme": "dark",
"file": "codegraph-explore-nl-query.visual-check.2048x1320.dark.png"
}
],
"contactSheet": "codegraph-explore-nl-query.visual-check.html"
},
"sidecars": {
"receipt": "codegraph-explore-nl-query.visual-check.json",
"contactSheet": "codegraph-explore-nl-query.visual-check.html"
}
}