目录一、Understand AnythingUA诞生的缘由1.1 痛点1主流AI编程工具Cursor/Claude/Copilot纯LLM读代码的致命短板1.1.1 文本化处理天生“结构失明”1.1.2 反复IO扫描Token消耗爆炸、效率极低1.1.3 无全局图谱视角只能局部理解1.1.4 冗余信息干扰推理1.2 痛点2传统静态分析IDE索引、Sonar、原生Tree-sitter的先天局限1.2.1 只有语法结构没有业务语义1.2.2 可视化图谱杂乱无意义1.2.3 缺少自然语言交互能力1.3 工程侧现实开发痛点UA诞生的落地驱动1.3.1 大型遗留仓库上手成本极高1.3.2 代码变更影响范围难以评估1.3.3 团队知识无法沉淀1.3.4 传统工具两者割裂没有混合方案1.4 UA的设计解决方案诞生核心思路二、Understand Anything 核心作用2.1 面向开发者快速读懂任意大型代码库降低上手与维护成本2.1.1 全局代码可视化建立系统整体认知2.1.2 新人快速入职导览核心特色功能2.1.3 精准评估代码变更影响范围2.1.4 自动沉淀团队代码知识资产2.1.5 遗留系统/老旧项目逆向梳理2.2 面向AI编程助手Cursor/Claude/Copilot/Gemini补齐AI全局理解短板2.2.1 提供全局代码大脑替代低效重复文件扫描2.2.2 大幅降低LLM Token消耗2.2.3 强力抑制LLM代码幻觉2.2.4 支持AI完成跨文件、跨模块复杂开发任务2.3 面向软件工程流程全流程辅助研发提效2.3.1 代码评审辅助2.3.2 架构治理2.3.3 缺陷根因排查2.3.4 教学培训三、设计思想及底层原理3.1 核心定位与底层设计总纲3.2 底层Tree-sitter 语法快速过滤层性能与准确性底座3.2.1 Tree-sitter 基础解析机制3.2.2 UA 基于 Tree-sitter Query 实现双向高速过滤核心优化逻辑3.2.2.1 正向提取捕获代码实体与关系骨架3.2.2.2 反向过滤剔除所有冗余干扰数据削减上层LLM Token3.2.3 全局索引构建与层输出产物3.3 中层多Agent图谱流水线语法结构 → 语义数据中转桥梁3.3.1 project-scanner 项目扫描Agent3.3.2 file-analyzer 文件图谱构建Agent3.3.3 graph-reviewer 图谱校验Agent3.3.4 architecture-analyzer 架构分层Agent3.3.5 tour-builder domain-analyzer 业务导览Agent3.4 上层LLM 三层递进式深层语义推理层3.4.1 LLM 输入强约束防幻觉、控成本核心规则3.4.2 三层递进推理逻辑3.4.2.1 Level 1 浅层单实体语义标注局部微观理解3.4.2.2 Level 2 中层架构分层推理模块中观理解3.4.2.3 Level 3 深层全局业务流程推理全局宏观理解UA核心价值3.4.3 双向约束校验机制抑制LLM幻觉核心3.5 完整端到端全流程运行链路3.5.1 仓库批量扫描纯Tree-sitter本地离线3.5.2 原始代码图谱构建无LLM参与3.5.3 浅层LLM推理实体标注架构分层3.5.4 深层LLM推理全局业务流程、变更影响域3.5.5 双向校验修正3.5.6 图谱持久化与交付输出3.5.7 增量更新机制3.6 分层架构各自能力边界与互补关系3.6.1 Tree-sitter 语法层能力边界3.6.2 LLM 语义推理层能力边界3.6.3 UA混合架构互补优势3.7 典型业务场景分层分工示例四、实战演示一、Understand AnythingUA诞生的缘由UA 是开源代码知识图谱引擎诞生本质是解决「纯LLM代码分析」与「传统静态语法分析」各自无法弥补的先天缺陷同时解决开发者阅读大型仓库、AI编程助手全局理解代码的工程痛点。1.1 痛点1主流AI编程工具Cursor/Claude/Copilot纯LLM读代码的致命短板1.1.1 文本化处理天生“结构失明”LLM只把代码当作字符串Token无法原生识别函数调用、类继承、模块导入、跨文件依赖只能靠关键词猜测代码关系极易编造不存在的调用链路幻觉大型项目改代码时常遗漏下游依赖引发线上故障。1.1.2 反复IO扫描Token消耗爆炸、效率极低AI分析项目会循环执行ls、cat、grep、跳转读取中型仓库上百次文件读取超长源码灌入上下文极易触发窗口溢出调用成本高、响应慢。1.1.3 无全局图谱视角只能局部理解LLM只能单次读取少量文件无法一次性掌握完整业务链路、分层架构新人、维护老系统时AI无法给出全局业务流程只能回答单段代码问题。1.1.4 冗余信息干扰推理注释、单元测试、Mock脚本、配置文件、废弃死代码全部混入上下文干扰模型判断业务核心逻辑。1.2 痛点2传统静态分析IDE索引、Sonar、原生Tree-sitter的先天局限1.2.1 只有语法结构没有业务语义只能输出“谁调用谁、类继承关系”等冰冷技术事实无法解释函数实现什么业务、模块属于哪个领域、分层是Controller还是Service、修改代码会影响哪些业务流程。1.2.2 可视化图谱杂乱无意义传统依赖图生成密密麻麻的“毛线球”节点仅展示连接关系无业务标签、无摘要、无分层视图开发者依然看不懂系统设计。1.2.3 缺少自然语言交互能力只能检索语法实体无法用自然语言提问“用户下单完整流程”“支付模块故障影响范围”不适合新人快速上手。1.3 工程侧现实开发痛点UA诞生的落地驱动1.3.1 大型遗留仓库上手成本极高20万行单体/微服务仓库、过期文档、核心开发离职开发者只能靠反复跳转、全局搜索摸索耗时数天才能理清一条业务链路。1.3.2 代码变更影响范围难以评估修改公共工具类、底层服务时人工排查所有调用方极易遗漏代码评审、上线风险无法量化。1.3.3 团队知识无法沉淀代码架构、业务流程散落在开发者脑中没有可共享、可检索、可视化的标准化代码知识库。1.3.4 传统工具两者割裂没有混合方案要么只做静态语法扫描要么只投喂源码给LLM没有工具把确定性语法过滤和LLM深层语义推理流水线结合。1.4 UA的设计解决方案诞生核心思路采用Tree-sitter底层确定性语法过滤 LLM上层语义推理分层架构1. Tree-sitter离线完成全部客观结构提取、冗余过滤生成零幻觉、可缓存的代码骨架图谱2. 仅将精简结构化数据送入LLM做业务、架构、流程等高阶推理3. 构建可交互可视化图谱打通开发者人工查阅与AI编程工具全局理解两大场景。二、Understand Anything 核心作用2.1 面向开发者快速读懂任意大型代码库降低上手与维护成本2.1.1 全局代码可视化建立系统整体认知自动生成结构图、业务域视图、分层架构视图区分接口层/服务层/数据层/中间件所有文件、类、函数作为图谱节点点击查看自然语言摘要、入参、调用链、所属业务域告别反复跳转文件支持缩放、拖拽、语义模糊搜索一键定位核心业务入口。2.1.2 新人快速入职导览核心特色功能内置tour-builder智能导览Agent基于代码依赖拓扑自动生成循序渐进的代码学习路线按业务流程顺序引导阅读替代过时README新人上手周期缩短70%以上。2.1.3 精准评估代码变更影响范围修改任意函数/文件后自动遍历Tree-sitter提取的全量调用关系结合LLM标注受影响业务模块、接口、定时任务、下游服务PR评审、上线前风险自查效率大幅提升。2.1.4 自动沉淀团队代码知识资产图谱可导出JSON持久化提交Git团队共享自动生成架构说明、业务模块文档解决“文档滞后、知识随人流失”问题支持中文自然语言输出。2.1.5 遗留系统/老旧项目逆向梳理无设计文档的存量系统一键扫描生成完整业务链路、模块边界快速梳理支付、鉴权、订单等核心领域流程。2.2 面向AI编程助手Cursor/Claude/Copilot/Gemini补齐AI全局理解短板2.2.1 提供全局代码大脑替代低效重复文件扫描AI不再循环调用工具读取文件直接查询UA预构建的知识图谱一次获取全仓库依赖、实体、分层信息减少90%工具调用次数。2.2.2 大幅降低LLM Token消耗Tree-sitter前置过滤注释、测试、冗余常量送入大模型的数据量削减60%~85%减少API成本、规避上下文溢出。2.2.3 强力抑制LLM代码幻觉底层依赖、调用关系、导入链路由Tree-sitter保证绝对准确LLM所有语义结论必须匹配语法树事实若描述关系冲突自动修正杜绝AI编造不存在的代码逻辑。2.2.4 支持AI完成跨文件、跨模块复杂开发任务基于全局图谱AI可独立完成全链路改造、架构重构、批量接口修改、故障根因分析解决传统AI只能处理单文件简单需求的局限。2.3 面向软件工程流程全流程辅助研发提效2.3.1 代码评审辅助自动解析PR改动对应的业务域、影响链路辅助评审人快速判断改动风险。2.3.2 架构治理自动识别循环依赖、分层混乱、跨层调用等架构异味辅助架构师优化模块边界。2.3.3 缺陷根因排查输入故障关键词图谱定位关联代码、完整调用链路快速定位底层问题。2.3.4 教学培训教学场景将真实项目转为可视化业务图谱帮助初学者理解工业级项目分层逻辑。三、设计思想及底层原理3.1 核心定位与底层设计总纲Understand Anything 是代码全局知识图谱分析引擎核心架构采用分层异构混合计算底层靠 Tree-sitter 做确定性静态语法解析、前置过滤与结构化索引无大模型、零幻觉、本地极速运行上层仅在清洗干净的语法结构数据之上使用 LLM 完成人类业务级语义推理。核心设计目标解决两大传统代码分析方案的固有缺陷1. 纯 LLM 直接读取源码把代码当纯文本处理无法精准识别跨文件调用、继承、导入关系极易编造不存在依赖幻觉全量源码灌入上下文造成 Token 爆炸、响应慢、成本高缺少全局代码拓扑视角。2. 仅 Tree-sitter / 传统静态分析工具只能输出语法层面的客观结构谁调用谁、类结构、导入关系无法理解业务含义、系统分层、端到端业务流程产出的依赖图只有冰冷符号不具备可读业务信息无法自然语言交互。UA 分层隔离原则结构事实全部由 Tree-sitter 兜底语义推理仅作为上层增强LLM 无权篡改底层语法提取的客观关系形成双向校验约束机制。整体流水线四层结构源码文件 → Tree-sitter 语法过滤层 → 多Agent图谱中转层 → LLM 多层语义推理层 → 带业务语义的代码知识图谱可视化问答3.2 底层Tree-sitter 语法快速过滤层性能与准确性底座3.2.1 Tree-sitter 基础解析机制Tree-sitter 是增量、多语言通用解析器输出 CST具体语法树区别于简化版 AST1. 并行词法语法解析原生支持 Java、TypeScript、Python、Go、C/C 等数十种开发语言线性源码文本转为结构化树形节点2. CST 保留完整原始信息包含注释、字符串字面量、函数、类、导入、函数调用、修饰符、代码行号等完整上下文不会丢失细节3. 增量解析能力文件仅局部修改时只重新解析变更片段无需全文件重解析适合大型仓库热更新4. 完全确定性同一代码多次解析语法树完全一致可缓存、可复现不存在随机性误差。3.2.2 UA 基于 Tree-sitter Query 实现双向高速过滤核心优化逻辑Tree-sitter 内置专用查询语言 QueryUA 内置预编译全语言匹配规则完全在内存语法树上完成筛选不操作原始文本不调用 LLM分为正向提取、反向过滤两条并行链路。3.2.2.1 正向提取捕获代码实体与关系骨架通过 Query 精准匹配语法节点批量抽取构建知识图谱所需全部实体与关联关系- 实体节点文件、类、接口、枚举、函数、全局变量、常量- 关联边导入 IMPORTS、函数调用 CALLS、类继承 EXTENDS、接口实现 IMPLEMENTS、文件包含 CONTAINS。(function_declaration name: (identifier) func_name parameters: (formal_parameters) func_params body: (block) func_body ) func_def3.2.2.2 反向过滤剔除所有冗余干扰数据削减上层LLM Token利用 Query 否定谓词 not-* 过滤无分析价值节点从源头减少送入大模型的数据量过滤范围1. 单行/多行注释、注释内伪代码、注释掉的废弃代码2. 单元测试、Mock 模拟文件、测试目录、测试常量3. 构建配置文件、第三方依赖声明、资源静态文本4. 从未被调用的孤立死代码、无业务逻辑的工具常量5. 字符串中形似函数/类的文本避免语法误识别。3.2.3 全局索引构建与层输出产物1. 构建全局 importMap 导入映射表一次性扫描全仓库所有导入语句记录文件间依赖上层无需重复推导2. 复用 QueryCursor 查询缓存避免重复编译匹配规则多进程并行解析仓库文件3. 层输出轻量化标准化 JSON 结构化数据仅保留客观代码结构事实无冗余文本。{ file_path: src/service/AuthService.java, is_test: false, class_list: [{name: AuthService, super_class: BaseService}], func_list: [{name: loginCheck, calls: [PasswordEncrypt.encrypt, UserMapper.selectUser]}], imports: [com.mapper.UserMapper, com.util.PasswordEncrypt] }该层输出相比原始源码数据体积压缩 60%~85%。3.3 中层多Agent图谱流水线语法结构 → 语义数据中转桥梁Tree-sitter 产出结构化实体数据后进入独立多智能体流水线完成基础图谱搭建、数据校验、任务分流是隔离底层语法层与上层LLM推理层的中间层全程分为 5 个串行专用 Agent3.3.1 project-scanner 项目扫描Agent接收批量文件结构化数据统一识别项目语言、生成文件变更指纹用于增量更新、整合全局导入索引、过滤不需要参与分析的目录如 test/、node_modules/。3.3.2 file-analyzer 文件图谱构建Agent将 Tree-sitter 提取的类、函数、调用关系转换为标准化图谱节点与有向依赖边搭建无语义标签的原始技术图谱。3.3.3 graph-reviewer 图谱校验Agent校验语法提取的依赖关系合法性剔除无关联孤立节点、修复断裂导入/调用链路保证底层图谱 100% 符合代码真实结构阻断语法层错误流向LLM。3.3.4 architecture-analyzer 架构分层Agent分流任务将完整基础图谱送入LLM执行浅层语义推理自动识别代码分层Controller/Service/Mapper/工具类/中间件、模块边界、循环依赖、跨层调用架构异味。3.3.5 tour-builder domain-analyzer 业务导览Agent分流任务聚合全仓库图谱数据送入LLM执行深层全局语义推理生成每个代码实体的自然语言摘要、划分业务域、生成新人代码学习导览路径、梳理端到端业务流程。3.4 上层LLM 三层递进式深层语义推理层Tree-sitter 仅能回答「代码结构是什么、存在哪些调用关系」客观事实LLM 基于清洗后的结构化语法数据回答「代码实现什么业务、系统如何分层、完整业务流程是什么」语义问题。3.4.1 LLM 输入强约束防幻觉、控成本核心规则UA 严格禁止向大模型投喂完整原始源码LLM 输入仅包含三类轻量化信息1. Tree-sitter 输出的标准化实体、调用依赖拓扑2. 仅保留核心业务逻辑的精简代码片段已剔除注释、测试代码3. 项目目录结构、框架特征SpringBoot/Vue/React等。3.4.2 三层递进推理逻辑3.4.2.1 Level 1 浅层单实体语义标注局部微观理解针对单个函数、类、接口做语义标注生成自然语言摘要与业务标签。- 输入函数签名、上下游调用关系、精简方法体- 输出loginCheck 函数用于校验用户账号密码调用加密工具处理明文密码并查询数据库匹配用户信息Tree-sitter 仅能拿到函数名与调用列表无法识别业务意图。3.4.2.2 Level 2 中层架构分层推理模块中观理解基于全仓库完整依赖图谱完成系统架构识别1. 自动划分接口层、业务服务层、数据持久层、通用工具层、第三方中间件封装层2. 识别模块边界、不合理循环依赖、跨层违规调用等架构问题Tree-sitter 仅能识别 A 导入 B无法区分 A 是接口、B 是数据库持久层。3.4.2.3 Level 3 深层全局业务流程推理全局宏观理解UA核心价值静态语法分析完全无法实现是LLM核心能力1. 梳理端到端完整业务链路例如「用户登录流程前端接口 → Auth服务 → 用户数据库 → 登录日志记录模块」2. 自动划分业务域鉴权、订单、支付、设备管理等3. 变更影响全域分析修改某个底层工具类自动关联所有受影响接口、定时任务、业务流程4. 自动生成项目学习导览、系统整体设计说明文档。3.4.3 双向约束校验机制抑制LLM幻觉核心推理完成后执行校验打通 Tree-sitter 底层结构与 LLM 语义结果双向约束1. 结构约束语义LLM 描述的调用、导入、继承关系必须与 Tree-sitter 语法树提取的客观数据完全匹配若LLM编造不存在依赖系统自动基于语法树修正语义结论并重新推理2. 语义增强结构将LLM生成的业务摘要、分层标签、业务域标识作为元数据附加到图谱节点/边上让纯技术依赖图拥有可读业务信息。3.5 完整端到端全流程运行链路3.5.1 仓库批量扫描纯Tree-sitter本地离线遍历项目目录增量解析全部源码通过Query双向过滤冗余内容构建全局导入索引输出轻量化结构化实体数据3.5.2 原始代码图谱构建无LLM参与多Agent流水线读取结构化数据生成基础节点与有向依赖边校验图谱结构完整性剔除无效数据3.5.3 浅层LLM推理实体标注架构分层向LLM输入精简语法数据为每个类、函数生成业务摘要划分系统分层与模块边界3.5.4 深层LLM推理全局业务流程、变更影响域聚合全仓库分层图谱与实体摘要全局推演完整业务链路、划分业务领域3.5.5 双向校验修正比对LLM语义结论与Tree-sitter底层语法结构修正冲突语义杜绝幻觉3.5.6 图谱持久化与交付输出存储完整混合知识图谱结构数据来自Tree-sitter语义标签来自LLM对外提供两种交互能力- Web可视化仪表盘图谱拖拽、检索、分层视图、业务流程可视化- 自然语言问答接口用户用自然语言查询代码架构、业务流程、改动风险3.5.7 增量更新机制文件修改后仅通过Tree-sitter增量重解析变更文件只重新执行对应局部LLM推理无需全库重新分析。3.6 分层架构各自能力边界与互补关系3.6.1 Tree-sitter 语法层能力边界✅ 优势解析速度快、无幻觉、支持增量、多语言统一解析、精准提取所有代码依赖关系、零API调用成本❌ 短板无任何业务理解能力无法解读代码意图、架构分层、业务流程产出依赖图可读性极低不支持自然语言交互。3.6.2 LLM 语义推理层能力边界✅ 优势理解自然语言、提炼业务意图、梳理全局流程、自动生成文档、区分架构分层❌ 短板纯文本输入易产生依赖幻觉、超长源码上下文溢出、调用成本高、无法精准定位跨文件代码实体。3.6.3 UA混合架构互补优势1. 底层Tree-sitter锁定全部客观代码事实从根源消除LLM编造依赖的问题2. 前置过滤大幅降低LLM输入Token数量降低API成本、提升响应速度3. 静态结构提供全局完整代码拓扑弥补LLM只能局部读取文件的短板4. LLM为冰冷语法图谱赋予业务语义解决传统静态分析看不懂、难上手的痛点5. 分层解耦可独立缓存Tree-sitter解析结果增量更新仅重算少量LLM任务适配数十万行大型单体、微服务仓库。3.7 典型业务场景分层分工示例用户查询需求执行处理层核心能力来源查询所有调用 encryptPwd 的函数、函数入参Tree-sitter语法层CST语法树Query检索毫秒级精准匹配userLogin 函数实现什么业务逻辑LLM浅层语义层基于Tree-sitter提取的函数上下文推理鉴权模块整体分层结构、模块边界LLM中层架构推理层全仓库完整依赖拓扑分析分层用户登录完整端到端业务执行链路LLM深层业务推理层全局图谱聚合多实体摘要推演流程修改AuthService评估全量业务影响范围混合协同层Tree-sitter查询全部调用方 LLM分析对应业务域四、实战演示可以直接在ai聊天框中输入安装Understand-Anything插件直接让ai指导安装装完插件就可以输入/understand ./src/main/java --language zh命令生成json知识图谱--full-linkage强制开启跨类引用、方法调用、继承、import 依赖链路解析.understand-anything知识图谱目录存储结构如下.understand-anything/ ├─ knowledge-graph.json # 【主结构图谱】build命令唯一输出当前gwm-dk-kss全量代码图谱 ├─ domain-graph.json # 【业务域图谱】仅执行 /understand-domain 才生成KSS业务流程、数字钥匙业务模型 ├─ meta.json # 项目元信息项目名、构建时间、源码路径、语言 ├─ diff-overlay.json # 增量变更临时缓存增量构建用 └─ intermediate/ # 中间AST缓存目录输入/understand-dashboard就可以打开可视化界面其他一些比较有趣的AI项目MaxKBhttps://github.com/1Panel-dev/MaxKBRAGFlowhttps://github.com/infiniflow/ragflowFlowiseAIhttps://github.com/FlowiseAI/FlowiseWeKnorahttps://github.com/Tencent/WeKnora