尧图网页设计 
Understand Anything 设计解析用 LLM 静态分析构建可交互代码知识图谱【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本文基于 Understand Anything 的设计文档设计规格完整拆解这个项目把任意代码库变成可探索、可搜索、可问答的知识图谱的整体架构包括 pnpm monorepo 的共享核心设计、知识图谱 JSON Schema 的字段定义与实现演进、基于 Git diff 的过期检测与增量更新机制、React 多面板 Dashboard 的技术选型以及 Claude Code Skill 命令体系。读完本文你将掌握该项目从设计到落地的完整脉络并能在源码层面验证每一项设计决策的实际实现。一、设计背景代码写得出却看不懂设计文档开篇点明了核心问题AI 编码工具让写代码变得容易但理解代码依然困难。初级开发者、非程序员产品经理、设计师甚至熟悉别的语言的资深工程师都难以看懂自己没写的、或者 AI 代写的代码库——而真正理解代码的只有 AI 本身。Understand Anything 的定位就是弥合这一鸿沟一个结合 LLM 智能与静态分析static analysis的开源工具为任意代码库生成一个多角色multi-persona的交互式理解仪表盘。它的运行形态是一个 Claude Code skill复用当前活跃的 AI 会话零额外成本并对外提供功能完整的 Web Dashboard。二、架构决策Monorepo 共享核心引擎设计文档将项目组织为一个 pnpm workspaces 管理的 monorepo其核心意图是skill 与 dashboard 共享同一个核心分析引擎core避免逻辑重复。原始设计目录结构如下understand-anything/ ├── packages/ │ ├── core/ # Shared analysis engine │ │ ├── analyzer/ # LLM tree-sitter analysis │ │ ├── graph/ # Knowledge graph builder schema │ │ ├── plugins/ # Plugin system for language analyzers │ │ └── persistence/ # JSON read/write, staleness detection │ ├── skill/ # Claude Code skill (5 commands) │ └── dashboard/ # React TypeScript multi-panel workspace ├── plugins/ # Built-in language analyzer plugins │ └── tree-sitter/ # Tree-sitter based multi-language analyzer ├── docs/ │ └── plans/ ├── package.json # Monorepo root (pnpm workspaces) ├── tsconfig.json └── .gitignore三项关键架构决策Key decisions在设计文档中明确列出Monorepopnpm workspaces——skill 和 dashboard 共享 core 分析引擎。当前仓库的 pnpm-workspace.yaml 与 understand-anything-plugin/pnpm-workspace.yaml 证实了这一组织方式dashboard 的 package.json 中通过understand-anything/core: workspace:*以工作区依赖方式引用核心引擎。JSON interchangeJSON 交换格式——知识图谱就是一个 JSON 文件skill 与 dashboard 都能读取不依赖数据库或私有格式。Committable auto-sync可提交 自动同步——图谱持久化在项目内数据目录中可以提交到 git并通过 git diff 自动检测过期staleness。从源码结构看当前仓库的目录布局在packages/core、packages/dashboard等核心划分上与设计文档一致见 understand-anything-plugin/packages并在此基础上扩展了languages/语言配置注册、plugins/extractors各语言静态提取器与plugins/parsers非代码文件解析器等模块。三、知识图谱 Schema系统的契约知识图谱是整个系统的交换格式设计文档给出了完整的 TypeScript 接口定义这也是 skill 生成、dashboard 消费两端共同遵守的契约interface KnowledgeGraph { version: string; project: ProjectMeta; nodes: GraphNode[]; edges: GraphEdge[]; layers: Layer[]; tour: TourStep[]; } interface ProjectMeta { name: string; languages: string[]; frameworks: string[]; description: string; // LLM-generated project summary analyzedAt: string; // ISO timestamp gitCommitHash: string; // For staleness detection } interface GraphNode { id: string; type: file | function | class | module | concept; name: string; filePath?: string; lineRange?: [number, number]; summary: string; // Plain-English description tags: string[]; // Searchable tags complexity: simple | moderate | complex; languageNotes?: string; // Language-specific explanations } interface GraphEdge { source: string; target: string; type: EdgeType; direction: forward | backward | bidirectional; description?: string; weight: number; // 0-1 importance } type EdgeType // Structural | imports | exports | contains | inherits | implements // Behavioral | calls | subscribes | publishes | middleware // Data flow | reads_from | writes_to | transforms | validates // Dependencies | depends_on | tested_by | configures // Semantic | related | similar_to; interface Layer { id: string; name: string; // e.g., API Layer, Data Layer description: string; nodeIds: string[]; } interface TourStep { order: number; title: string; description: string; // Markdown explanation nodeIds: string[]; // Nodes to highlight languageLesson?: string; // Optional language concept explanation }各字段的语义要点GraphNode是图谱的基本单元type区分文件、函数、类、模块与抽象概念summary是 LLM 生成的自然语言描述tags用于搜索complexity三档simple/moderate/complex供不同角色的视角做差异化展示languageNotes承载语言特定解释配合 Learn 模式。GraphEdge用type表达 5 类关系结构/行为/数据流/依赖/语义direction区分方向weight0–1表达关系强度。Layer把节点按逻辑分层如 API Layer、Data Layer支撑分层视图。TourStep是引导式项目导览的步骤序列languageLesson允许在用户自己的代码上下文中讲解语言概念。ProjectMeta.gitCommitHash是过期检测的锚点后续第五节详述。3.1 实现演进从 17 种边类型到 38 种、多类型图谱对比当前源码中的 Zod 校验实现 schema.ts可以观察到设计落地后的两处重要演进边类型扩展。设计文档定义了 17 种EdgeType实现中EdgeTypeSchema已扩展到38 个值、9 个类别新增了基础设施deploys、serves、provisions、triggers、Schema/数据migrates、documents、routes、defines_schema、业务域contains_flow、flow_step、cross_domain、知识图谱cites、contradicts、builds_on、exemplifies等与设计Figma四类。这说明图谱模型从纯代码库泛化到了基础设施、知识库与界面设计等多种kind。节点类型扩展与容错管线。设计文档中节点类型只有 5 种实现的GraphNodeSchema扩展到 26 种含config、service、table、endpoint、pipeline、domain、flow、article、page、component等。更关键的是由于节点主要由 LLM 生成schema 文件构建了一条四层容错管线sanitizesanitizeGraphnull 归一化为空数组/删除枚举字段转小写normalizenormalizeGraph把 LLM 常见的类型别名映射回规范类型如func/fn/method→functionstruct→classci→pipeline边别名如extends→inherits、invokes→callsauto-fixautoFixGraph缺type默认file缺complexity默认moderateweight缺失默认 0.5、字符串强转数字、越界值钳制到 [0,1]且每一步都记录可审计的GraphIssuevalidatevalidateGraph逐节点/边/Layer/TourStep 校验非法项被丢弃dropped而非整体失败同时做引用完整性检查——边的source/target必须存在于节点集合中layers/tour中悬空的nodeIds会被过滤。这套宽容输入、分级处理auto-corrected / dropped / fatal的策略是对LLM 产出必然带噪声这一现实的工程化应对相关行为有 schema.test.ts 覆盖。四、Dashboard多面板工作区设计文档用一张 ASCII 图定义了 Dashboard 的四象限布局┌─────────────────────────────────────────────────────────┐ │ Natural Language Search: communication layer │ ├──────────────────────┬──────────────────────────────────┤ │ │ │ │ GRAPH VIEW │ CODE VIEWER │ │ (React Flow) │ (Monaco Editor, read-only) │ │ │ │ │ Interactive node │ Source code syntax highlight │ │ graph. Click to │ LLM annotations inline. │ │ select. Search │ │ │ highlights. │ │ ├──────────────────────┼──────────────────────────────────┤ │ │ │ │ CHAT PANEL │ LEARN PANEL │ │ │ │ │ Context-aware QA │ Tour mode Contextual mode │ │ about selected │ Language lessons in context │ │ nodes / project. │ of YOUR code. │ └──────────────────────┴──────────────────────────────────┘设计文档给出的技术栈是React 18 TypeScript Vite、React Flow节点图可视化优于裸 D3、Monaco Editor与 VS Code 同款代码查看器、TailwindCSS、Zustand轻量状态管理。对照 dashboard/package.json实际依赖与设计选型基本吻合且版本前进React 已升至 19xyflow/react即 React Flow12.x、zustand5.x、TailwindCSS 4.x、Vite 6.x 均在列并新增了elkjs/d3-force/graphology Louvain 社区发现等布局算法依赖支撑大图的分层与聚类布局见 elk-layout.ts 与 louvain.ts。从源码结构看代码查看器最终采用了prism-react-renderer做语法高亮而非 Monaco组件为 CodeViewer.tsx。4.1 三种角色视角Persona Modes设计文档按读者身份定义了三种模式核心思路是同一份图谱不同的信息密度角色展示策略Non-technical非技术人员只呈现高层概念节点隐藏代码查看器放大 Learn 面板Junior dev初级开发者全部面板可见Learn 面板突出显示复杂度指示Experienced dev资深开发者代码查看器突出Chat 面板用于深入探讨4.2 自然语言搜索设计文档规定搜索作用于节点的tags、summary、name字段如可用则使用 embedding 相似度否则回退到关键词匹配命中后在图中高亮并过滤列表。源码中这一设计落地为两条路径关键词/模糊搜索search.ts 基于 Fuse.js 实现SearchEngine对四个字段加权name0.4、tags0.3、summary0.2、languageNotes0.1阈值 0.4并把空格分隔的查询词用|连接做 OR 匹配——即输入 auth contrl 能同时命中含任一 token 的节点。语义搜索embedding-search.ts 实现了余弦相似度计算含对查询向量范数预计算的优化路径对应设计 Phase 4 中可选增强的 embedding 语义检索。五、Skill 命令体系与 LLM 策略设计文档定义了 5 条 Claude Code Skill 命令命令说明/understand完整分析若图谱已存在则增量更新 打开 Dashboard/understand-chat query在终端内基于知识图谱进行问答/understand-diff分析当前 PR/diff——解释改动、受影响区域与风险/understand-explain path对特定文件或函数做深入解释/understand-onboard为团队成员生成结构化上手指南LLM 策略分三种场景在 Claude Code 内部运行时复用当前活跃会话零额外成本独立 Dashboard 场景下由用户提供 API key 驱动 Chat 功能而图谱浏览、搜索、Learn 模式完全离线工作基于预生成数据。对照当前仓库的 SKILL.md/understand命令的实装比设计文档更丰富支持参数包括--full强制全量重建忽略已有图谱--auto-update/--no-auto-update开启/关闭提交时自动更新图谱写入autoUpdate到配置--review运行完整的 LLM 图谱审查而非内联确定性校验--language lang以指定语言ISO 639-1 代码或友好名称生成全部文本内容--exclude patterns附加排除的 glob 模式支持 gitignore 语法与!取反直接传一个目录路径分析该目录而非当前工作目录。此外 SKILL.md 还规定了对 git worktree 的重定向逻辑若检测到PROJECT_ROOT位于 worktree通过对比git rev-parse --git-dir与--git-common-dir会把图谱输出重定向到主仓库根目录避免会话结束后 worktree 被销毁导致图谱丢失可用环境变量UNDERSTAND_NO_WORKTREE_REDIRECT1关闭。相关行为有 worktree-redirect.test.mjs 验证。5 个 skill 目录understand、understand-chat、understand-diff、understand-explain、understand-onboard及扩展的understand-dashboard、understand-knowledge等均可在 skills 目录 下找到各自的 SKILL.md。六、持久化与过期检测自动同步如何工作6.1 数据目录布局设计文档定义的持久化结构如下.understand-anything/ ├── knowledge-graph.json # The full graph (committable) ├── meta.json # Analysis metadata │ { │ lastAnalyzedAt: 2026-03-14T..., │ gitCommitHash: abc123, │ version: 1.0.0, │ analyzedFiles: 47 │ } ├── cache/ # Per-file analysis cache │ ├── src__index.ts.json │ └── src__auth__login.ts.json └── tours/ └── default-tour.json其中meta.json的gitCommitHash是增量更新的锚点cache/存放按文件键路径分隔符替换为__的分析缓存。需要注意当前实现中数据目录已重命名为更短的.ua/persistence/index.ts 的resolveUaDirName做了向后兼容——旧项目若已存在.understand-anything/则继续使用该目录读写新项目则使用.ua/无需迁移。同一文件中还有一个值得注意的隐私保护细节sanitiseFilePaths在写盘前把所有节点filePath从绝对路径转为相对路径项目外的绝对路径只保留文件名避免把开发者的家目录、用户名等布局信息泄露进可提交的 JSON。6.2 自动同步流程Auto-sync Flow设计文档定义了四步流程Skill 启动 → 读取meta.json→ 获取上次分析的 commit hash执行git diff last-hash..HEAD --name-only→ 得到变更文件列表若无变更 → 直接提供现有图谱若有变更 → 只重新分析变更文件 → 合并进现有图谱 → 更新 meta。源码 staleness.ts 忠实实现了这条链路并做了三层能力增强基础判定getChangedFiles正是同步流程第 2 步git diff hash..HEAD --name-onlyisStale据此返回{ stale, changedFiles }。精细的新鲜度模型getGraphFreshness把图谱状态细化为fresh/dirty无提交差异但工作区有未提交改动/stale/unknown含missing-graph-commit、git-command-timeout等 5 种原因码。stale还区分behind/ahead/diverged三种拓扑关系并给出commitsBehind/commitsAhead计数——通过git rev-list --left-right --count与merge-base --is-ancestor判定。所有 git 子命令都带 5 秒超时与 4MB 缓冲上限且用 pathspec 排除.ua/、.understand-anything/自身防止图谱文件自身的变更污染判定。相关测试见 staleness.test.ts 与 graph-freshness.integration.test.ts。增量合并mergeGraphUpdate实现同步流程第 4 步的具体合并算法——(1) 按filePath删除属于变更文件的旧节点(2) 删除source或target落在被删节点集合中的旧边(3) 追加新节点与新边(4) 更新project.gitCommitHash与analyzedAt。这种按文件整体替换的策略保证了增量更新与全量重建的语义一致性同时避免全图重算的成本。七、插件系统tree-sitter 静态分析 语言注册表设计文档给出的分析器插件接口interface AnalyzerPlugin { name: string; languages: string[]; analyzeFile(filePath: string, content: string): StructuralAnalysis; resolveImports(filePath: string, content: string): ImportResolution[]; extractCallGraph?(filePath: string, content: string): CallGraphEntry[]; }设计意图是结构靠 tree-sitter语义靠 LLMDay 1 的 tree-sitter 插件使用node-tree-sitter加载 TypeScript/JavaScript、Python、Go、Java、Rust、C/C 等语言文法提取函数/类边界、import/export 语句与调用点再与 LLM 分析结合得到语义理解未来开放社区插件做语言级深度分析。从当前源码结构看这一方向已显著扩展tree-sitter-plugin.ts 与 registry.ts 实现插件注册与发现plugins/extractors 下为 12 种语言C、C#、Dart、Go、Java、Kotlin、PHP、Python、Ruby、Rust、Scala、Swift、TypeScript提供独立提取器配套逐语言单测plugins/parsers 覆盖非代码文件Dockerfile、环境变量、GraphQL、JSON、Makefile、Markdown、Protobuf、Shell、SQL、Terraform、TOML、YAMLlanguages/language-registry.ts 维护语言 ID → 配置的注册表支持按文件扩展名与文件名如Makefile、docker-compose.yml两种方式解析languages/configs 下有 40 余种语言配置层级自动检测设计 Phase 2 第 13 项落地为 layer-detector.ts内置目录模式 → 层级名的启发式映射表routes/controller/api → API Layerservice/business → Service Layermodel/repository → Data Layercomponent/page/ui → UI Layerworker/queue/cron → Background Taskstest/spec → Test Layer 等先匹配先生效并支持 LLM 返回filePatterns做补充判定。八、实施阶段与验证标准设计文档把落地拆成四个阶段共 22 项任务Phase 1FoundationMVP——项目脚手架core 的图谱 schema JSON 持久化LLM 分析引擎基于 prompt 的逐文件分析tree-sitter 结构分析集成/understand命令Dashboard 基础应用 React Flow 图谱视图 Monaco 代码查看器。Phase 2Intelligence——图谱节点自然语言搜索/understand-chat终端问答Dashboard Chat 面板过期检测 增量更新层级自动检测。Phase 3Learn Mode——导览Tour生成点击即解释的上下文解释以用户代码为语境的特定语言课程三种角色模式。Phase 4Advanced——/understand-diff、/understand-explain、/understand-onboard三条命令社区插件系统基于 embedding 的语义检索可选增强。设计文档同时给出了 6 条端到端验证标准也是回归这套设计的实用清单Skill 分析在示例项目上运行/understand验证生成的knowledge-graph.json符合 schema增量更新修改一个文件后再次运行/understand验证只有变更文件被重新分析Dashboard打开本地开发服务Vite 默认端口 5173pnpm --filter understand-anything/dashboard dev即可启动验证图谱渲染、节点可点击、搜索可用Chat在聊天面板提问验证答案基于知识图谱生成Learn 模式启动 Tour验证能逐步走查整个项目Tree-sitter分析一个 TypeScript 文件验证函数边界与 import 关系同真实代码一致。设计文档建议的四类测试项目——小型 TypeScript 项目工具自身、Python Flask/Django API、Go 微服务、混合语言 monorepo——也覆盖了单语言、多框架、服务化与 monorepo 四种典型形态。九、小结这份 2026-03-14 的设计文档确立了 Understand Anything 的三个支柱以 JSON 知识图谱为单一事实来源schema 是契约且通过 sanitize/normalize/auto-fix/validate 四层管线消化 LLM 输出的噪声、以 Git 为同步时钟commit hash 锚定、diff 驱动增量、合并算法保证一致性、以多角色视角为出口同一份数据服务非技术人员、初级与资深开发者。对照当前仓库源码可以确认文档中的核心机制——git diff hash..HEAD的增量链路、mergeGraphUpdate的文件级替换合并、层级启发式检测、加权模糊搜索——都有明确的实现文件与测试用例支撑而边类型从 17 扩到 38 种、节点类型扩到 26 种、数据目录从.understand-anything/迁移到.ua/等演进则展示了这套设计在落地过程中从代码库分析向基础设施/知识/设计多 kind 图谱泛化的实际轨迹。对于想构建LLM 静态分析类代码理解工具的开发团队这套契约先行、宽容校验、Git 驱动增量的工程模式具备直接的参考价值。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Understand Anything 设计解析：用 LLM + 静态分析构建可交互代码知识图谱
Understand Anything 设计解析用 LLM 静态分析构建可交互代码知识图谱【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything本文基于 Understand Anything 的设计文档设计规格完整拆解这个项目把任意代码库变成可探索、可搜索、可问答的知识图谱的整体架构包括 pnpm monorepo 的共享核心设计、知识图谱 JSON Schema 的字段定义与实现演进、基于 Git diff 的过期检测与增量更新机制、React 多面板 Dashboard 的技术选型以及 Claude Code Skill 命令体系。读完本文你将掌握该项目从设计到落地的完整脉络并能在源码层面验证每一项设计决策的实际实现。一、设计背景代码写得出却看不懂设计文档开篇点明了核心问题AI 编码工具让写代码变得容易但理解代码依然困难。初级开发者、非程序员产品经理、设计师甚至熟悉别的语言的资深工程师都难以看懂自己没写的、或者 AI 代写的代码库——而真正理解代码的只有 AI 本身。Understand Anything 的定位就是弥合这一鸿沟一个结合 LLM 智能与静态分析static analysis的开源工具为任意代码库生成一个多角色multi-persona的交互式理解仪表盘。它的运行形态是一个 Claude Code skill复用当前活跃的 AI 会话零额外成本并对外提供功能完整的 Web Dashboard。二、架构决策Monorepo 共享核心引擎设计文档将项目组织为一个 pnpm workspaces 管理的 monorepo其核心意图是skill 与 dashboard 共享同一个核心分析引擎core避免逻辑重复。原始设计目录结构如下understand-anything/ ├── packages/ │ ├── core/ # Shared analysis engine │ │ ├── analyzer/ # LLM tree-sitter analysis │ │ ├── graph/ # Knowledge graph builder schema │ │ ├── plugins/ # Plugin system for language analyzers │ │ └── persistence/ # JSON read/write, staleness detection │ ├── skill/ # Claude Code skill (5 commands) │ └── dashboard/ # React TypeScript multi-panel workspace ├── plugins/ # Built-in language analyzer plugins │ └── tree-sitter/ # Tree-sitter based multi-language analyzer ├── docs/ │ └── plans/ ├── package.json # Monorepo root (pnpm workspaces) ├── tsconfig.json └── .gitignore三项关键架构决策Key decisions在设计文档中明确列出Monorepopnpm workspaces——skill 和 dashboard 共享 core 分析引擎。当前仓库的 pnpm-workspace.yaml 与 understand-anything-plugin/pnpm-workspace.yaml 证实了这一组织方式dashboard 的 package.json 中通过understand-anything/core: workspace:*以工作区依赖方式引用核心引擎。JSON interchangeJSON 交换格式——知识图谱就是一个 JSON 文件skill 与 dashboard 都能读取不依赖数据库或私有格式。Committable auto-sync可提交 自动同步——图谱持久化在项目内数据目录中可以提交到 git并通过 git diff 自动检测过期staleness。从源码结构看当前仓库的目录布局在packages/core、packages/dashboard等核心划分上与设计文档一致见 understand-anything-plugin/packages并在此基础上扩展了languages/语言配置注册、plugins/extractors各语言静态提取器与plugins/parsers非代码文件解析器等模块。三、知识图谱 Schema系统的契约知识图谱是整个系统的交换格式设计文档给出了完整的 TypeScript 接口定义这也是 skill 生成、dashboard 消费两端共同遵守的契约interface KnowledgeGraph { version: string; project: ProjectMeta; nodes: GraphNode[]; edges: GraphEdge[]; layers: Layer[]; tour: TourStep[]; } interface ProjectMeta { name: string; languages: string[]; frameworks: string[]; description: string; // LLM-generated project summary analyzedAt: string; // ISO timestamp gitCommitHash: string; // For staleness detection } interface GraphNode { id: string; type: file | function | class | module | concept; name: string; filePath?: string; lineRange?: [number, number]; summary: string; // Plain-English description tags: string[]; // Searchable tags complexity: simple | moderate | complex; languageNotes?: string; // Language-specific explanations } interface GraphEdge { source: string; target: string; type: EdgeType; direction: forward | backward | bidirectional; description?: string; weight: number; // 0-1 importance } type EdgeType // Structural | imports | exports | contains | inherits | implements // Behavioral | calls | subscribes | publishes | middleware // Data flow | reads_from | writes_to | transforms | validates // Dependencies | depends_on | tested_by | configures // Semantic | related | similar_to; interface Layer { id: string; name: string; // e.g., API Layer, Data Layer description: string; nodeIds: string[]; } interface TourStep { order: number; title: string; description: string; // Markdown explanation nodeIds: string[]; // Nodes to highlight languageLesson?: string; // Optional language concept explanation }各字段的语义要点GraphNode是图谱的基本单元type区分文件、函数、类、模块与抽象概念summary是 LLM 生成的自然语言描述tags用于搜索complexity三档simple/moderate/complex供不同角色的视角做差异化展示languageNotes承载语言特定解释配合 Learn 模式。GraphEdge用type表达 5 类关系结构/行为/数据流/依赖/语义direction区分方向weight0–1表达关系强度。Layer把节点按逻辑分层如 API Layer、Data Layer支撑分层视图。TourStep是引导式项目导览的步骤序列languageLesson允许在用户自己的代码上下文中讲解语言概念。ProjectMeta.gitCommitHash是过期检测的锚点后续第五节详述。3.1 实现演进从 17 种边类型到 38 种、多类型图谱对比当前源码中的 Zod 校验实现 schema.ts可以观察到设计落地后的两处重要演进边类型扩展。设计文档定义了 17 种EdgeType实现中EdgeTypeSchema已扩展到38 个值、9 个类别新增了基础设施deploys、serves、provisions、triggers、Schema/数据migrates、documents、routes、defines_schema、业务域contains_flow、flow_step、cross_domain、知识图谱cites、contradicts、builds_on、exemplifies等与设计Figma四类。这说明图谱模型从纯代码库泛化到了基础设施、知识库与界面设计等多种kind。节点类型扩展与容错管线。设计文档中节点类型只有 5 种实现的GraphNodeSchema扩展到 26 种含config、service、table、endpoint、pipeline、domain、flow、article、page、component等。更关键的是由于节点主要由 LLM 生成schema 文件构建了一条四层容错管线sanitizesanitizeGraphnull 归一化为空数组/删除枚举字段转小写normalizenormalizeGraph把 LLM 常见的类型别名映射回规范类型如func/fn/method→functionstruct→classci→pipeline边别名如extends→inherits、invokes→callsauto-fixautoFixGraph缺type默认file缺complexity默认moderateweight缺失默认 0.5、字符串强转数字、越界值钳制到 [0,1]且每一步都记录可审计的GraphIssuevalidatevalidateGraph逐节点/边/Layer/TourStep 校验非法项被丢弃dropped而非整体失败同时做引用完整性检查——边的source/target必须存在于节点集合中layers/tour中悬空的nodeIds会被过滤。这套宽容输入、分级处理auto-corrected / dropped / fatal的策略是对LLM 产出必然带噪声这一现实的工程化应对相关行为有 schema.test.ts 覆盖。四、Dashboard多面板工作区设计文档用一张 ASCII 图定义了 Dashboard 的四象限布局┌─────────────────────────────────────────────────────────┐ │ Natural Language Search: communication layer │ ├──────────────────────┬──────────────────────────────────┤ │ │ │ │ GRAPH VIEW │ CODE VIEWER │ │ (React Flow) │ (Monaco Editor, read-only) │ │ │ │ │ Interactive node │ Source code syntax highlight │ │ graph. Click to │ LLM annotations inline. │ │ select. Search │ │ │ highlights. │ │ ├──────────────────────┼──────────────────────────────────┤ │ │ │ │ CHAT PANEL │ LEARN PANEL │ │ │ │ │ Context-aware QA │ Tour mode Contextual mode │ │ about selected │ Language lessons in context │ │ nodes / project. │ of YOUR code. │ └──────────────────────┴──────────────────────────────────┘设计文档给出的技术栈是React 18 TypeScript Vite、React Flow节点图可视化优于裸 D3、Monaco Editor与 VS Code 同款代码查看器、TailwindCSS、Zustand轻量状态管理。对照 dashboard/package.json实际依赖与设计选型基本吻合且版本前进React 已升至 19xyflow/react即 React Flow12.x、zustand5.x、TailwindCSS 4.x、Vite 6.x 均在列并新增了elkjs/d3-force/graphology Louvain 社区发现等布局算法依赖支撑大图的分层与聚类布局见 elk-layout.ts 与 louvain.ts。从源码结构看代码查看器最终采用了prism-react-renderer做语法高亮而非 Monaco组件为 CodeViewer.tsx。4.1 三种角色视角Persona Modes设计文档按读者身份定义了三种模式核心思路是同一份图谱不同的信息密度角色展示策略Non-technical非技术人员只呈现高层概念节点隐藏代码查看器放大 Learn 面板Junior dev初级开发者全部面板可见Learn 面板突出显示复杂度指示Experienced dev资深开发者代码查看器突出Chat 面板用于深入探讨4.2 自然语言搜索设计文档规定搜索作用于节点的tags、summary、name字段如可用则使用 embedding 相似度否则回退到关键词匹配命中后在图中高亮并过滤列表。源码中这一设计落地为两条路径关键词/模糊搜索search.ts 基于 Fuse.js 实现SearchEngine对四个字段加权name0.4、tags0.3、summary0.2、languageNotes0.1阈值 0.4并把空格分隔的查询词用|连接做 OR 匹配——即输入 auth contrl 能同时命中含任一 token 的节点。语义搜索embedding-search.ts 实现了余弦相似度计算含对查询向量范数预计算的优化路径对应设计 Phase 4 中可选增强的 embedding 语义检索。五、Skill 命令体系与 LLM 策略设计文档定义了 5 条 Claude Code Skill 命令命令说明/understand完整分析若图谱已存在则增量更新 打开 Dashboard/understand-chat query在终端内基于知识图谱进行问答/understand-diff分析当前 PR/diff——解释改动、受影响区域与风险/understand-explain path对特定文件或函数做深入解释/understand-onboard为团队成员生成结构化上手指南LLM 策略分三种场景在 Claude Code 内部运行时复用当前活跃会话零额外成本独立 Dashboard 场景下由用户提供 API key 驱动 Chat 功能而图谱浏览、搜索、Learn 模式完全离线工作基于预生成数据。对照当前仓库的 SKILL.md/understand命令的实装比设计文档更丰富支持参数包括--full强制全量重建忽略已有图谱--auto-update/--no-auto-update开启/关闭提交时自动更新图谱写入autoUpdate到配置--review运行完整的 LLM 图谱审查而非内联确定性校验--language lang以指定语言ISO 639-1 代码或友好名称生成全部文本内容--exclude patterns附加排除的 glob 模式支持 gitignore 语法与!取反直接传一个目录路径分析该目录而非当前工作目录。此外 SKILL.md 还规定了对 git worktree 的重定向逻辑若检测到PROJECT_ROOT位于 worktree通过对比git rev-parse --git-dir与--git-common-dir会把图谱输出重定向到主仓库根目录避免会话结束后 worktree 被销毁导致图谱丢失可用环境变量UNDERSTAND_NO_WORKTREE_REDIRECT1关闭。相关行为有 worktree-redirect.test.mjs 验证。5 个 skill 目录understand、understand-chat、understand-diff、understand-explain、understand-onboard及扩展的understand-dashboard、understand-knowledge等均可在 skills 目录 下找到各自的 SKILL.md。六、持久化与过期检测自动同步如何工作6.1 数据目录布局设计文档定义的持久化结构如下.understand-anything/ ├── knowledge-graph.json # The full graph (committable) ├── meta.json # Analysis metadata │ { │ lastAnalyzedAt: 2026-03-14T..., │ gitCommitHash: abc123, │ version: 1.0.0, │ analyzedFiles: 47 │ } ├── cache/ # Per-file analysis cache │ ├── src__index.ts.json │ └── src__auth__login.ts.json └── tours/ └── default-tour.json其中meta.json的gitCommitHash是增量更新的锚点cache/存放按文件键路径分隔符替换为__的分析缓存。需要注意当前实现中数据目录已重命名为更短的.ua/persistence/index.ts 的resolveUaDirName做了向后兼容——旧项目若已存在.understand-anything/则继续使用该目录读写新项目则使用.ua/无需迁移。同一文件中还有一个值得注意的隐私保护细节sanitiseFilePaths在写盘前把所有节点filePath从绝对路径转为相对路径项目外的绝对路径只保留文件名避免把开发者的家目录、用户名等布局信息泄露进可提交的 JSON。6.2 自动同步流程Auto-sync Flow设计文档定义了四步流程Skill 启动 → 读取meta.json→ 获取上次分析的 commit hash执行git diff last-hash..HEAD --name-only→ 得到变更文件列表若无变更 → 直接提供现有图谱若有变更 → 只重新分析变更文件 → 合并进现有图谱 → 更新 meta。源码 staleness.ts 忠实实现了这条链路并做了三层能力增强基础判定getChangedFiles正是同步流程第 2 步git diff hash..HEAD --name-onlyisStale据此返回{ stale, changedFiles }。精细的新鲜度模型getGraphFreshness把图谱状态细化为fresh/dirty无提交差异但工作区有未提交改动/stale/unknown含missing-graph-commit、git-command-timeout等 5 种原因码。stale还区分behind/ahead/diverged三种拓扑关系并给出commitsBehind/commitsAhead计数——通过git rev-list --left-right --count与merge-base --is-ancestor判定。所有 git 子命令都带 5 秒超时与 4MB 缓冲上限且用 pathspec 排除.ua/、.understand-anything/自身防止图谱文件自身的变更污染判定。相关测试见 staleness.test.ts 与 graph-freshness.integration.test.ts。增量合并mergeGraphUpdate实现同步流程第 4 步的具体合并算法——(1) 按filePath删除属于变更文件的旧节点(2) 删除source或target落在被删节点集合中的旧边(3) 追加新节点与新边(4) 更新project.gitCommitHash与analyzedAt。这种按文件整体替换的策略保证了增量更新与全量重建的语义一致性同时避免全图重算的成本。七、插件系统tree-sitter 静态分析 语言注册表设计文档给出的分析器插件接口interface AnalyzerPlugin { name: string; languages: string[]; analyzeFile(filePath: string, content: string): StructuralAnalysis; resolveImports(filePath: string, content: string): ImportResolution[]; extractCallGraph?(filePath: string, content: string): CallGraphEntry[]; }设计意图是结构靠 tree-sitter语义靠 LLMDay 1 的 tree-sitter 插件使用node-tree-sitter加载 TypeScript/JavaScript、Python、Go、Java、Rust、C/C 等语言文法提取函数/类边界、import/export 语句与调用点再与 LLM 分析结合得到语义理解未来开放社区插件做语言级深度分析。从当前源码结构看这一方向已显著扩展tree-sitter-plugin.ts 与 registry.ts 实现插件注册与发现plugins/extractors 下为 12 种语言C、C#、Dart、Go、Java、Kotlin、PHP、Python、Ruby、Rust、Scala、Swift、TypeScript提供独立提取器配套逐语言单测plugins/parsers 覆盖非代码文件Dockerfile、环境变量、GraphQL、JSON、Makefile、Markdown、Protobuf、Shell、SQL、Terraform、TOML、YAMLlanguages/language-registry.ts 维护语言 ID → 配置的注册表支持按文件扩展名与文件名如Makefile、docker-compose.yml两种方式解析languages/configs 下有 40 余种语言配置层级自动检测设计 Phase 2 第 13 项落地为 layer-detector.ts内置目录模式 → 层级名的启发式映射表routes/controller/api → API Layerservice/business → Service Layermodel/repository → Data Layercomponent/page/ui → UI Layerworker/queue/cron → Background Taskstest/spec → Test Layer 等先匹配先生效并支持 LLM 返回filePatterns做补充判定。八、实施阶段与验证标准设计文档把落地拆成四个阶段共 22 项任务Phase 1FoundationMVP——项目脚手架core 的图谱 schema JSON 持久化LLM 分析引擎基于 prompt 的逐文件分析tree-sitter 结构分析集成/understand命令Dashboard 基础应用 React Flow 图谱视图 Monaco 代码查看器。Phase 2Intelligence——图谱节点自然语言搜索/understand-chat终端问答Dashboard Chat 面板过期检测 增量更新层级自动检测。Phase 3Learn Mode——导览Tour生成点击即解释的上下文解释以用户代码为语境的特定语言课程三种角色模式。Phase 4Advanced——/understand-diff、/understand-explain、/understand-onboard三条命令社区插件系统基于 embedding 的语义检索可选增强。设计文档同时给出了 6 条端到端验证标准也是回归这套设计的实用清单Skill 分析在示例项目上运行/understand验证生成的knowledge-graph.json符合 schema增量更新修改一个文件后再次运行/understand验证只有变更文件被重新分析Dashboard打开本地开发服务Vite 默认端口 5173pnpm --filter understand-anything/dashboard dev即可启动验证图谱渲染、节点可点击、搜索可用Chat在聊天面板提问验证答案基于知识图谱生成Learn 模式启动 Tour验证能逐步走查整个项目Tree-sitter分析一个 TypeScript 文件验证函数边界与 import 关系同真实代码一致。设计文档建议的四类测试项目——小型 TypeScript 项目工具自身、Python Flask/Django API、Go 微服务、混合语言 monorepo——也覆盖了单语言、多框架、服务化与 monorepo 四种典型形态。九、小结这份 2026-03-14 的设计文档确立了 Understand Anything 的三个支柱以 JSON 知识图谱为单一事实来源schema 是契约且通过 sanitize/normalize/auto-fix/validate 四层管线消化 LLM 输出的噪声、以 Git 为同步时钟commit hash 锚定、diff 驱动增量、合并算法保证一致性、以多角色视角为出口同一份数据服务非技术人员、初级与资深开发者。对照当前仓库源码可以确认文档中的核心机制——git diff hash..HEAD的增量链路、mergeGraphUpdate的文件级替换合并、层级启发式检测、加权模糊搜索——都有明确的实现文件与测试用例支撑而边类型从 17 扩到 38 种、节点类型扩到 26 种、数据目录从.understand-anything/迁移到.ua/等演进则展示了这套设计在落地过程中从代码库分析向基础设施/知识/设计多 kind 图谱泛化的实际轨迹。对于想构建LLM 静态分析类代码理解工具的开发团队这套契约先行、宽容校验、Git 驱动增量的工程模式具备直接的参考价值。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考