Understand-Anything Phase 4 实现计划深解：三个高级 Skill 命令、插件注册表与语义搜索的落地路线

Understand-Anything Phase 4 实现计划深解三个高级 Skill 命令、插件注册表与语义搜索的落地路线【免费下载链接】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 仓库中的 Phase 4Advanced实现计划 2026-03-14-phase4-implementation.md 展开系统讲解该阶段如何为项目新增/understand-diff、/understand-explain、/understand-onboard三个高级 Skill 命令、面向社区的插件注册体系以及基于向量嵌入的语义搜索能力。读完后你将掌握每个任务的 TDD 实施步骤、核心算法涟漪效应分析、单组件上下文构建、余弦相似度检索的完整实现以及计划与当前仓库源码之间的实际落地差异从而理解这套“知识图谱 LLM 技能”架构的进阶设计。一、Phase 4 目标、架构与任务依赖该计划文档的开篇明确定义了 Phase 4 的目标Goal、架构Architecture与技术栈Tech Stack三个关键属性Goal新增 Advanced 层——三个新 skill 命令/understand-diff、/understand-explain、/understand-onboard、一个社区插件系统以及可选的基于 embedding 的语义搜索。Architecture在 skill 包中扩展三个 Claude Code skill 定义及配套的 core 工具在 core 中加入插件注册表以支持社区扩展将基于 embedding 的搜索作为现有 fuse.js 模糊搜索的升级路径。Tech Stack任务 1–5 不引入任何新依赖任务 6–7embedding 搜索引入一个向量相似度库或直接使用原始余弦计算。七个任务的依赖关系图在原文档中以如下结构给出是理解整个 Phase 4 编排的关键Task 1 (understand-diff) ─── (independent) Task 2 (understand-explain) ─── (independent) Task 3 (understand-onboard) ─── (independent) Task 4 (Plugin Registry Core) ───→ Task 5 (Plugin CLI Integration) Task 6 (Embedding Search Core) ───→ Task 7 (Embedding Dashboard)即任务 1、2、3、4、6 完全独立可以任意顺序并行实现只有任务 4→5注册表→配置发现与任务 6→7语义搜索核心→Dashboard 集成存在明确的先后依赖。需要注意的路径映射计划撰写时的包路径为packages/skill/与packages/core/而当前仓库已将其重组到插件工作区下——skill 侧源码位于 understand-anything-plugin/src/core 侧位于 understand-anything-plugin/packages/core/src/。本文在引用实现证据时会同时给出计划路径与当前仓库中的实际路径。二、任务 1/understand-diff —— 基于知识图谱的 PR/Diff 影响分析/understand-diff的核心价值在于把改了哪些文件这个扁平信息转换为哪些组件、哪些架构层、哪些关系被波及的结构化图谱分析。计划为该命令指定了四个交付文件新建packages/skill/src/diff-analyzer.ts当前仓库对应 diff-analyzer.ts新建packages/skill/src/__tests__/diff-analyzer.test.ts当前对应 diff-analyzer.test.ts新建 skill 定义packages/skill/.claude/skills/understand-diff.md当前对应 understand-diff/SKILL.md修改packages/skill/src/index.ts增加导出2.1 DiffContext 数据模型与 buildDiffContext 算法diff-analyzer.ts定义了一个DiffContext接口它是整个分析过程的结构化中间产物export interface DiffContext { projectName: string; changedFiles: string[]; changedNodes: GraphNode[]; // 直接变更的节点 affectedNodes: GraphNode[]; // 涟漪效应波及的节点 impactedEdges: GraphEdge[]; // 被波及的关系边 affectedLayers: Layer[]; // 受影响的架构层 unmappedFiles: string[]; // 图谱中尚未收录的文件 }buildDiffContext(graph, changedFiles)的算法分为四步这也是图谱化影响分析的核心逻辑完整实现见 diff-analyzer.ts第一步文件路径 → 直接变更节点的映射。遍历图谱节点凡node.filePath与变更文件路径一致的节点全部计入changedNodeIds映射失败的路径进入unmappedFiles提示这些新文件可能尚未被/understand收录需要重新分析。第二步吸收 contains 子节点。文件变更后其内部函数/类同样视为直接变更// Also include contains children of changed file nodes for (const edge of edges) { if (edge.type contains changedNodeIds.has(edge.source)) { changedNodeIds.add(edge.target); } }第三步1-hop 涟漪效应。遍历所有边若边的任一端点属于变更集合则该边计入impactedEdges另一端点计入受影响节点且自动去重不重复计入已变更节点for (const edge of edges) { const sourceChanged changedNodeIds.has(edge.source); const targetChanged changedNodeIds.has(edge.target); if (sourceChanged || targetChanged) { impactedEdges.push(edge); if (sourceChanged !changedNodeIds.has(edge.target)) { affectedNodeIds.add(edge.target); } if (targetChanged !changedNodeIds.has(edge.source)) { affectedNodeIds.add(edge.source); } } }第四步受影响层推导。任何包含变更或受影响节点的层都被判定为受影响层const allImpactedIds new Set([...changedNodeIds, ...affectedNodeIds]); const affectedLayers layers.filter((layer) layer.nodeIds.some((id) allImpactedIds.has(id)), );计划配套的测试用例diff-analyzer.test.ts 沿用同一组断言覆盖了全部关键行为识别直接变更节点、识别变更文件的 contains 子节点、通过边识别 1-hop 受影响节点如routes.ts调用了service.ts则routes.ts被判定受影响、识别受影响层Service Layer、处理图谱中不存在的文件进入unmappedFiles、处理空 diff以及受影响节点与变更节点严格不重叠的去重约束。2.2 formatDiffAnalysis面向 LLM 的结构化输出formatDiffAnalysis将DiffContext渲染为 LLM 可直接消费、人类也可读的 Markdown固定输出以下章节## Changed Components含每个变更节点的文件路径与复杂度、## Affected Components涟漪效应组件、## Affected Layers、条件性的## Impacted Relationshipssource --[type]-- target形式与## Unmapped Files。其中## Risk Assessment章节采用一组显式的风险规则这些阈值是计划文档明确定义的判断标准风险信号判定条件High complexity存在complexity complex的变更节点Cross-layer impact受影响层数大于 1Wide blast radius受影响节点数大于 5New/unmapped filesunmappedFiles非空提示可能需要重新分析Low risk以上四项均不满足时输出变更局部化、下游影响有限2.3 Skill 定义与当前仓库的演进计划中的 skill 定义要求 Agent读取.understand-anything/knowledge-graph.json不存在则提示先运行/understand→ 获取变更文件未提交改动用git diff --name-only功能分支用git diff main...HEAD --name-only或按 PR 号取 diff→ 对每个变更文件定位对应节点、连接节点与受影响层 → 输出 Changed/Affected/Layers/Risk 四段式分析。对照当前仓库中的 understand-diff/SKILL.md落地版本在计划基础上显著强化了三处数据目录解析UA_DIR$([ -d .understand-anything ] echo .understand-anything || echo .ua)优先复用旧的.understand-anything/否则使用新的.ua/图谱新鲜度校验读取project.gitCommitHash用git rev-parse --verify --end-of-options ${GRAPH_COMMIT_RAW}^{commit}解析后与git rev-parse HEAD比较并通过git diff --name-only $GRAPH_COMMIT HEAD -- .等命令检查项目范围内的提交与工作区改动——文档特别强调-- .pathspec 是必需的以免 monorepo 中兄弟项目的提交误判图谱过期Dashboard 联动分析完成后将结果写入$UA_DIR/diff-overlay.json包含baseBranch、generatedAt、changedFiles、changedNodeIds、affectedNodeIds供 Dashboard 可视化变更与受影响组件。构建与验证命令按计划为cd packages/skill pnpm build pnpm test当前仓库等价于在 understand-anything-plugin/ 工作区内执行 pnpm 脚本。三、任务 2/understand-explain —— 单组件深度剖析/understand-explain path与泛问式的/understand-chat不同它聚焦于对单个组件文件或函数做彻底解释。计划交付文件为explain-builder.ts、其测试、skill 定义以及 index 导出当前实现见 explain-builder.ts 与 understand-explain/SKILL.md。3.1 ExplainContext 与双格式路径匹配ExplainContext包含targetNode、childNodes、connectedNodes、relevantEdges、layer五组关键数据。buildExplainContext的路径解析支持两种格式匹配策略有明确的优先级// Check for path:function format (e.g. src/auth.ts:login) const colonIdx path.lastIndexOf(:); if (colonIdx 0 !path.includes(://)) { const filePath path.slice(0, colonIdx); const funcName path.slice(colonIdx 1); targetNode nodes.find((n) n.filePath filePath n.name funcName) ?? null; } // Fall back to file path match if (!targetNode) { targetNode nodes.find((n) n.filePath path) ?? null; }即先按path:function如src/auth.ts:login精确匹配该文件下、指定名称的节点匹配不上再回退为整个文件路径匹配。!path.includes(://)的细节用于排除 URL 形式的误判。路径完全未知时返回targetNode: null的空上下文。上下文构建随后完成三件事通过contains边收集子节点文件内的函数/类以目标节点 子节点为种子集做 1-hop 邻域扩展收集connectedNodes与relevantEdges用layers.find((l) l.nodeIds.includes(targetNode.id))定位该组件所属的架构层。3.2 formatExplainPrompt 的提示词结构formatExplainPrompt是面向 LLM 的深度剖析提示词生成器。找不到节点时输出# Component Not Found并给出三条排查建议尚未分析过——先运行/understand路径与图谱中不一致文件已删除或重命名。节点存在时提示词按如下固定结构组织头部元信息**Type:** / **Complexity:** / **File:** / **Lines:**与**Summary:**## Architectural Layer: 层名组件的架构归属与层描述## Internal Components子节点列表来自 contains 边## Connected Components一跳邻域组件## Relationships非 contains 边的src --[type]-- tgt — description关系列表## Language Notes可选的语言学背景说明## Instructions固定的五步解释指令——(1) 组件做什么、为何存在(2) 数据如何流经它输入→处理→输出(3) 与连接组件如何交互(4) 值得注意的模式、惯用法与设计决策(5) 潜在的坑或复杂区域。计划中的测试断言验证了关键行为按路径找到 file 节点、子节点包含login与verify、连接节点包含db.ts、层为Auth Layer、未知路径返回null目标、src/auth.ts:login形式的函数级定位以及not found提示文案的生成。当前仓库的 understand-explain/SKILL.md 在此之上补充了图谱结构参考节点类型划分为代码类 file/function/class/module/concept、非代码类 config/document/service/table/endpoint/pipeline/schema/resource、领域知识类 domain/flow/step/article/entity/topic/claim/sourceID 以类型前缀如file:path、function:path:name、先 Grep 再读取的上下文效率原则、与 diff skill 相同的图谱新鲜度校验流程并新增了第 7 步读取节点filePath处的真实源码文件——这是纯图谱查询之外的最后一环确保深度剖析建立在真实代码之上。四、任务 3/understand-onboard —— 团队入职指南生成/understand-onboard的目标是把知识图谱综合为一份可提交到仓库、可分享进 wiki 的入职指南当前实现见 onboard-builder.ts 与 understand-onboard/SKILL.md。buildOnboardingGuide(graph)的输出是一份独立 Markdown 文档章节顺序与生成逻辑如下项目概览# 项目名标题 描述引用 四行元信息表格Languages、Frameworks、Components: N nodes, M relationships、Last Analyzed## Architecture仅当layers非空逐层输出层名H3、层描述以及由layer.nodeIds反查节点名得到的Key components列表## Key Concepts仅当存在type concept节点每个概念以 H3 展开其 summary## Getting Started仅当tour非空按step.order编号输出每步标题与描述列出该步Files to look atfilePath — summary并可选输出 **Language Tip:** languageLesson语言小贴士## File Map所有 file 级节点整理为| File | Purpose | Complexity |三列表格## Complexity Hotspotscomplexity complex的节点清单提示新人重点关注的区域页脚注明文档由知识图谱 v 生成。计划中的测试覆盖了六个必含章节项目概览、语言/框架列表、架构层、关键概念、Getting Started、复杂度热点、File Map以及无 layers与无 tour两类退化图谱仍能正常生成完整文档的健壮性要求。当前仓库的 understand-onboard/SKILL.md 将生成流程具体化为对图谱 JSON 的高效读取策略先用 Grep 提取project段再取layers、tour全量数组读取文件级结构节点时刻意跳过函数级与类级节点以保持指南的高层视角复杂度热点从文件级节点中挑选最终建议把指南保存为docs/UA_ONBOARDING.md并提交给团队。这与计划初版保存到docs/ONBOARDING.md相比是文件名的演进。五、任务 4 与 5插件注册表与配置发现系统5.1 任务 4PluginRegistry核心计划指出AnalyzerPlugin接口已存在于packages/core/src/types.ts当时只有TreeSitterPlugin一个实现。任务 4 创建packages/core/src/plugins/registry.ts目标是发现、注册并管理分析器插件把文件扩展名映射到插件并提供统一的analyzeFile入口作为社区插件体系的地基。计划版本的核心数据结构与方法为export class PluginRegistry { private plugins: AnalyzerPlugin[] []; private languageMap new Mapstring, AnalyzerPlugin(); // 注册插件同一语言的后来注册者覆盖先前的later registration takes priority register(plugin: AnalyzerPlugin): void; // 按名称注销并重建 languageMap unregister(name: string): void; // 按语言名查找 getPluginForLanguage(language: string): AnalyzerPlugin | null; // 按文件扩展名查找 getPluginForFile(filePath: string): AnalyzerPlugin | null; // 统一分析入口无匹配插件时返回 null analyzeFile(filePath: string, content: string): StructuralAnalysis | null; resolveImports(filePath: string, content: string): ImportResolution[] | null; getPlugins(): AnalyzerPlugin[]; getSupportedLanguages(): string[]; }计划版本内嵌了一张EXTENSION_TO_LANGUAGE硬编码映射表ts/tsx→typescript、js/jsx→javascript、py→python、go→go、rs→rust、rb→ruby、java→java、kt→kotlin、cs→csharp、cpp/c、swift、php 等getPluginForFile先取扩展名、再查表、最后落到语言映射。配套的测试对应 plugin-registry.test.ts验证了注册/注销、按语言查找、不支持语言返回 null、按扩展名查找含 tsx、多语言插件python/go/rust、全部插件与语言列表、同名语言下后注册者胜出、analyzeFile正确委派、以及无插件时返回 null。当前仓库的落地版本 registry.ts 有一处关键架构演进不再使用硬编码扩展名表而是构造时注入LanguageRegistry默认LanguageRegistry.createDefault()getPluginForFile通过this.languageRegistry.getForFile(filePath)解析语言配置后查languageMap。从源码结构看这一改动把文件→语言的知识集中到语言注册表统一维护对应 languages/ 下的 40 余种语言配置插件注册表自身保持语言无关。此外当前实现还扩展了getLanguageForFile、extractCallGraph以及analyzeFileFull单次解析同时返回结构分析与调用图的快速路径插件不支持时返回 null 让调用方回退到分步调用——这些均是计划之外的后续增强。5.2 任务 5插件配置模式与发现机制任务 5 补充从项目.understand-anything/目录发现并配置插件的能力核心是配置解析函数当前实现见 discovery.tsexport interface PluginEntry { name: string; enabled: boolean; languages: string[]; options?: Recordstring, unknown; } export interface PluginConfig { plugins: PluginEntry[]; }parsePluginConfig(jsonString)的容错规则由计划中的测试完整定义当前仓库的 plugin-discovery.test.ts 与之一致合法 JSON 正常解析出条目含enabled: false的禁用项非法 JSON、空字符串一律回退到DEFAULT_PLUGIN_CONFIG缺少必填字段的条目缺name、缺languages被静默过滤enabled省略时默认trueoptions字段可选透传。解析器实现上先用类型守卫过滤条目要求name为非空字符串、languages为非空数组再映射为强类型PluginEntryserializePluginConfig则以两空格缩进 JSON 序列化回写。计划版本的默认配置是tree-sitter启用且仅覆盖[typescript, javascript]当前仓库的 discovery.ts 已演进为从builtinLanguageConfigs动态推导export const DEFAULT_PLUGIN_CONFIG: PluginConfig { plugins: [ { name: tree-sitter, enabled: true, languages: builtinLanguageConfigs .filter((c) c.treeSitter) .map((c) c.id), }, ], };即默认启用全部内置 tree-sitter 语言。这一演进的合理性从源码结构可以直接看出项目的语言配置languages/configs/ 下 40 余个语言定义已远超计划撰写时的 TypeScript/JavaScript 双语言规模静态默认值会迅速过期。六、任务 6 与 7Embedding 语义搜索与 Dashboard 集成6.1 任务 6SemanticSearchEngine核心计划文档明确了动机现有SearchEngine基于 fuse.js 做模糊关键词匹配而 embedding 搜索支持find code that handles authentication这类即便词面不出现也能命中的语义查询。模块边界被严格划定向量由外部调用 embedding API生成该模块只负责存储与余弦相似度检索并在无 embedding 时回退到既有SearchEngine。余弦相似度函数是全模块的数学基础当前实现见 embedding-search.tsexport function cosineSimilarity(a: number[], b: number[]): number { let dot 0, magA 0, magB 0; for (let i 0; i a.length; i) { dot a[i] * b[i]; magA a[i] * a[i]; magB b[i] * b[i]; } magA Math.sqrt(magA); magB Math.sqrt(magB); if (magA 0 || magB 0) return 0; // 零向量防御 return dot / (magA * magB); }计划的测试当前 embedding-search.test.ts 保持同样断言集用三节点 单位向量的构造验证相同向量相似度为 1、正交为 0、相似向量大于 0.9、零向量返回 0。SemanticSearchEngine的 API 面constructor(nodes: GraphNode[], embeddings: Recordstring, number[])内部以Map存储 node id → 向量hasEmbeddings()是否已加载任何向量作为能否启用语义模式的开关addEmbedding(nodeId, embedding)增量更新索引search(queryEmbedding, options?)SemanticSearchOptions支持三个参数——limit默认 10、threshold默认 0相似度下限、types节点类型过滤updateNodes(nodes)图谱重载后刷新节点列表。其中search有一个值得注意的接口约定细节计划文档原文强调// Convert similarity (0-1, higherbetter) to score (0-1, lowerbetter) // to match the SearchResult interface convention from fuse.js scored.push({ nodeId: node.id, score: 1 - similarity });语义搜索的相似度越大越好被转换为1 - similarity与 fuse.js 的SearchResult分数约定越小越好对齐从而让两种引擎在 Dashboard 侧可以无缝互换。当前仓库的落地版本在此基础上做了一次性能优化引入cosineSimilarityWithQueryMag(query, queryMag, vec)把查询向量模长的计算从逐节点循环中提升到循环之外查询向量在整个搜索过程中是不变量源码注释明确说明相同的算术、相同的顺序 → 位级一致的结果只是省掉每个节点的 magA 循环。这类优化不改变任何外部行为属于典型的检索热路径工程化处理。6.2 任务 7Dashboard 的 Fuzzy/Semantic 模式切换任务 7 把SemanticSearchEngine接入 DashboardSearchBar.tsx 与 store.ts计划给出的 store 扩展为// Add to interface searchMode: fuzzy | semantic; setSearchMode: (mode: fuzzy | semantic) void; // Add to implementation searchMode: fuzzy, setSearchMode: (mode) set({ searchMode: mode }),setSearchQuery需根据searchMode选择引擎——MVP 阶段两种模式共用 fuzzy 引擎预留 embedding 就绪后切换到SemanticSearchEngine的接口。SearchBar 则在搜索框旁渲染一个双按钮切换器div classNameflex items-center gap-1 bg-gray-700 rounded p-0.5 shrink-0 button onClick{() setSearchMode(fuzzy)} className{text-[10px] px-1.5 py-0.5 rounded transition-colors ${ searchMode fuzzy ? bg-gray-600 text-white : text-gray-400 hover:text-gray-300 }} Fuzzy /button button onClick{() setSearchMode(semantic)} className{text-[10px] px-1.5 py-0.5 rounded transition-colors ${ searchMode semantic ? bg-gray-600 text-white : text-gray-400 hover:text-gray-300 }} Semantic /button /div当前仓库中该切换器确实存在于 SearchBar.tsx且已进一步国际化——locales/en.ts 及 ja/ko/ru/zh/zh-TW 各语言文件均提供semantic词条如中文语义、日文セマンティック并在输入框旁以({searchMode})显示当前模式超出计划稿的细节但方向一致。七、验证清单与执行要点计划末尾的 Verification Checklist 定义了 Phase 4 全部完成后的验收标准逐条对照如下cd packages/core pnpm build pnpm test——全部通过存量 约 35 个新测试cd packages/skill pnpm build pnpm test——全部通过存量 14 约 25 个新测试cd packages/dashboard pnpm build——编译无错误三个 skill 定义文件齐备understand-diff.md、understand-explain.md、understand-onboard.md当前仓库中分别落地为 understand-diff/SKILL.md、understand-explain/SKILL.md、understand-onboard/SKILL.md插件注册表可用PluginRegistry.register()、getPluginForFile()、analyzeFile()parsePluginConfig()正确处理合法/非法 JSON语义搜索cosineSimilarity()数值正确、SemanticSearchEngine.search()返回有序结果、Dashboard 切换器可渲染并切换模式Phase 1 Phase 2 Phase 3 的既有功能全部不受影响回归约束。值得强调的是该计划的方法论特征每个任务都遵循统一的 TDD 步骤链——Step 1 先写失败测试并给出完整测试代码、Step 2 运行确认失败、Step 3 给出完整参考实现、Step 4 运行测试通过、Step 5 补 index 导出与 skill 定义、Step 6pnpm build pnpm test、Step 7 按明确的git add文件清单与feat(scope): ...提交信息提交。三个 skill 任务的提交信息分别为feat(skill): add /understand-diff command for PR/diff analysis、feat(skill): add /understand-explain command for deep-dive file analysis、feat(skill): add /understand-onboard command for team onboarding guidescore 侧为feat(core): add plugin registry for community analyzer plugins、feat(core): add plugin configuration and discovery system、feat(core): add embedding-based semantic search enginedashboard 侧为feat(dashboard): add fuzzy/semantic search mode toggle。八、计划与仓库现状的差异小结对照当前仓库源码Phase 4 的七个任务核心设计全部落地且存在若干可归纳的演进点对理解该项目计划→实现的迭代方式有参考价值计划稿2026-03-14当前仓库实现演进性质packages/skill/与packages/core/双包结构重组至 understand-anything-plugin/ 工作区skill 代码在src/core 在packages/core/目录重组逻辑不变注册表内嵌EXTENSION_TO_LANGUAGE硬编码表registry.ts 委托LanguageRegistry解析扩展名消除重复知识源默认插件语言固定为[typescript, javascript]discovery.ts 从builtinLanguageConfigs动态推导适应语言规模增长cosineSimilarity逐节点全量计算新增cosineSimilarityWithQueryMag提升查询模长计算热路径性能优化行为位级一致skill 存放于.claude/skills/*.md仅描述基本指令skills/ 下各SKILL.md补充图谱结构参考、$UA_DIR解析、新鲜度校验、diff-overlay 输出生产级健壮性增强总体而言Phase 4 计划的价值不止于待办清单它以 TDD 步骤、完整参考实现与验收清单的形式完整记录了从 diff 涟漪分析、单组件剖析、入职指南生成到插件体系与语义搜索的全部设计决策而当前仓库中的实现diff-analyzer.ts、explain-builder.ts、onboard-builder.ts 与 core 侧 plugins/、embedding-search.ts及其配套测试src/tests/、packages/core/src/tests/则提供了逐条可验证的落地证据两者相互印证构成理解 Understand-Anything 高级能力层设计与演进的完整闭环。【免费下载链接】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），仅供参考