Understand-Anything Phase 2 实现计划：为知识图谱构建“智能层”——Schema 校验、模糊搜索、过期检测与 /understand-chat-平芜编程栈

Understand-Anything Phase 2 实现计划：为知识图谱构建“智能层”——Schema 校验、模糊搜索、过期检测与 /understand-chat

【免费下载链接】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 2（Intelligence）实施计划展开，完整解析该计划的目标、架构与技术选型，并逐一深入 10 个任务的上下文、代码设计与验证手段。读完后，你将理解该项目如何从“能画出图”进化为“能回答问题的图”：加载即校验的 Zod Schema、基于 Fuse.js 的模糊搜索引擎、基于 Git diff 的图谱过期检测与增量合并、启发式 + LLM 双通道的架构分层推断，以及驱动终端问答的/understand-chatSkill 与上下文构建器。所有关键结论均可在仓库源码与测试中复核。

1. 计划总览：目标、架构与技术栈

Phase 2 的官方目标（Goal）是为系统添加"Intelligence"层，包含五大能力：

增强搜索（enhanced search）；
图谱过期检测（staleness detection）；
架构分层自动推断（layer auto-detection）；
/understand-chatSkill 命令；
具备上下文感知问答能力的 Dashboard 聊天面板。

架构上，计划声明在现有 monorepo（packages/core、packages/dashboard）基础上新增packages/skill包：

Core 获得搜索引擎、过期检测、分层检测；Dashboard 获得自动布局、增强搜索体验与聊天面板；Skill 包提供/understand-chatClaude Code 命令。

技术栈在既有基础上增加三个依赖：fuse.js（模糊搜索）、zod（Schema 校验）、@dagrejs/dagre（图布局）。值得注意的是，计划开篇要求实现方使用superpowers:executing-plans子技能"逐任务执行"，即每个任务都遵循"写失败测试 → 验证失败 → 实现 → 验证通过 → 提交"的 TDD 节奏。下文按任务顺序展开，并结合仓库当前源码说明每个任务落地的实际形态（注意：源码位于 understand-anything-plugin/ 插件目录下的对应 workspace 包中）。

2. Task 1：Zod Schema 校验——加载即验证的知识图谱

2.1 问题背景

计划指出：改造前loadGraph只做JSON.parse()、不做任何校验，损坏或不兼容的图谱文件会"静默地产出坏数据"。该任务被标记为基础性任务——Phase 2 所有功能都依赖正确的图谱数据。

2.2 测试先行：五类校验场景

计划要求先写失败测试（schema.test.ts 即由此演化而来），覆盖：

合法图谱通过校验（version+project+nodes+edges+layers+tour完整结构）；
缺少必填字段被拒绝，且result.errors非空；
节点类型非法（如invalid_type）被拒绝；
边类型非法（如fake_edge）被拒绝；
weight超出[0, 1]范围时校验失败。

2.3 Schema 设计

计划中的KnowledgeGraphSchema由六个子 Schema 组成，全部基于 zod：

EdgeTypeSchema：z.enum([...])，计划版本枚举了 18 种边类型（imports、exports、contains、inherits、implements、calls、subscribes、publishes、middleware、reads_from、writes_to、transforms、validates、depends_on、tested_by、configures、related、similar_to）；
GraphNodeSchema：id、type（file/function/class/module/concept 五种）、name、summary、tags必填，filePath、lineRange（二元组）、complexity（simple/moderate/complex）、languageNotes可选；
GraphEdgeSchema：source/target、类型枚举、direction（forward/backward/bidirectional）、weight限定min(0).max(1)；
LayerSchema、TourStepSchema、ProjectMetaSchema（name、languages、frameworks、description、analyzedAt、gitCommitHash）。

核心 API 为validateGraph(data: unknown): ValidationResult，内部使用KnowledgeGraphSchema.safeParse(data)，失败时把 zod issues 映射为path: message字符串数组。

2.4 接入持久化层

计划要求修改loadGraph，增加可选参数validate（默认true）：

export function loadGraph( baseDir: string, options?: { validate?: boolean } ): KnowledgeGraph | null { const graphPath = path.join(baseDir, '.understand-anything', 'knowledge-graph.json'); if (!fs.existsSync(graphPath)) return null; const data = JSON.parse(fs.readFileSync(graphPath, 'utf-8')); if (options?.validate !== false) { const result = validateGraph(data); if (!result.success) { throw new Error(`Invalid knowledge graph: ${result.errors?.join('; ')}`); } return result.data as KnowledgeGraph; } return data as KnowledgeGraph; }

这个设计的取舍值得注意：默认开启校验、保留关闭开关，既防止坏数据流入下游功能，又为调试或迁移场景留了后门。

2.5 源码演进：从"拒绝"到"分层修复"

查看当前 schema.ts 可以看到，落地实现远比计划版本复杂——这正体现了"计划是骨架、实现长出了血肉"。几个关键演进：

边类型从 18 种扩展到 38 种，覆盖 9 大类（Structural、Behavioral、Data flow、Dependencies、Semantic、Infrastructure、Schema/Data、Domain、Knowledge），以支持非代码节点（服务、表、流水线、领域流、知识库条目等）；
引入别名归一化：NODE_TYPE_ALIASES（如func/method→function、interface→class）、EDGE_TYPE_ALIASES（如extends→inherits）、COMPLEXITY_ALIASES（low→simple）、DIRECTION_ALIASES（to→forward）——这些都是 LLM 生成图谱时的高频"漂移"写法；
四级容错流水线（见validateGraph实现，schema.ts#L563-L727）：
- Tier 1sanitizeGraph：空值归一（null→ 空数组/删除可选字段）、枚举字段小写化；
- Tier 2autoFixGraph：缺失字段自动补默认值并记录 issue（如缺type补file、缺weight补0.5、越界 weight 夹紧到[0,1]）；
- Tier 3 逐条校验 nodes/edges/layers/tour，坏条目丢弃并记录而非整体失败，同时做引用完整性检查（边的 source/target 必须存在于 nodes 中）；
- Tier 4 致命错误：输入非对象、必备集合非数组、project元数据缺失、无有效节点。
返回结构升级为ValidationResult { success, data?, issues, fatal?, errors? }，其中issues携带level: auto-corrected | dropped | fatal分级信息。

这种"能修则修、该丢则丢、致命才拒"的策略，与计划中"weight 越界直接 fail"的严格取向明显不同——从源码结构看，这是后续接入 LLM 生成图谱（非确定性输出）后的务实妥协。loadGraph的接线也确已落地：persistence/index.ts 第 5 行导入validateGraph，第 110 行与第 187 行分别在加载路径上调用它。

3. Task 2：基于 Fuse.js 的增强搜索引擎

3.1 从子串匹配到模糊匹配

计划指出：原 Dashboard store 只有"大小写不敏感子串搜索（name/summary/tags）"，而 Phase 2 需要模糊匹配 + 相关性打分。方案是把可复用的SearchEngine放进 core（dashboard 和 skill 共用），底层用 Fuse.js 驱动。

3.2 测试矩阵

计划给出了 9 个用例，覆盖：空查询返回空、精确名匹配、模糊名匹配（"auth contrl"命中AuthenticationController）、summary 字段搜索、tags 搜索、名称匹配优先于摘要匹配（'auth'查询时auth.ts排在utils.ts（其 summary 含 "auth"）之前）、返回带score数值的结果、updateNodes重建索引、按节点类型过滤。这些用例即 search.test.ts 的来源。

3.3 索引配置与评分权重

计划中的SearchEngine核心是 Fuse 选项与搜索流程：

private createIndex(nodes: GraphNode[]): Fuse<GraphNode> { return new Fuse(nodes, { keys: [ { name: 'name', weight: 0.4 }, { name: 'tags', weight: 0.3 }, { name: 'summary', weight: 0.2 }, { name: 'languageNotes', weight: 0.1 }, ], threshold: 0.4, includeScore: true, ignoreLocation: true, }); }

权重分配name 0.4 > tags 0.3 > summary 0.2 > languageNotes 0.1正是"名称匹配优先"测试用例能通过的机制原因；
threshold: 0.4控制模糊度（0 精确、1 最模糊）；
score语义为0 = 完美匹配，1 = 最差匹配（见SearchResult接口的注释）；
search(query, options?)支持types（按节点类型过滤）与limit（默认 50）；
updateNodes整体重建索引，服务图谱刷新场景。

3.4 源码现状：扩展搜索与 OR 分词

当前 search.ts 保持了计划的接口形态（SearchResult、SearchOptions、SearchEngine类、相同的键权重与threshold: 0.4），但有两处增强：

开启useExtendedSearch: true；
查询预处理为"空格分词后用|连接"——"auth contrl"变成"auth | contrl"，语义为任一 token 命中即可：

// 源码 search.ts const extendedQuery = trimmed.split(/\s+/).join(" | "); const rawResults = this.fuse.search(extendedQuery);

这使得多词口语化查询（如验证计划里"输入auth contrl应能命中AuthController"的验收项）的召回率显著提高。

4. Task 3：Dagre 自动布局——告别网格排布

4.1 问题与方案

计划描述：原 GraphView 用(index % 3) * 300的简单网格定位节点，对真实项目会产生"混乱的图"。方案是引入 dagre 分层布局（hierarchical layout）：节点自上而下流动，层级由边方向决定。

4.2 布局工具设计

计划给出的applyDagreLayout(nodes, edges, direction = 'TB')关键点：

固定节点尺寸NODE_WIDTH = 280、NODE_HEIGHT = 120（对应 layout.ts 中的导出常量）；
dagre 图参数：nodesep: 60（同层间距）、ranksep: 80（层间间距）、marginx/marginy: 20；
布局完成后把 dagre 返回的中心坐标换算为 React Flow 需要的左上角坐标：x: pos.x - NODE_WIDTH / 2, y: pos.y - NODE_HEIGHT / 2；
GraphView 接入四步：导入applyDagreLayout→ 从图谱数据构建无位置信息的 flow 节点/边 → 过一遍布局函数 → 用useMemo确保仅在图谱/搜索变化时重算。自定义节点、搜索高亮、选择、控件、minimap 等既有能力全部保留。

4.3 源码演进：从 dagre 到 ELK 的过渡期

当前 layout.ts 中applyDagreLayout已被标记为@deprecated，注释说明：

dashboard 的结构视图已全部改用 ELK（applyElkLayout），此 helper 保留一个发布周期作为 ELK 回归时的快速回退。

同时可见布局参数也做了规模化调整：节点数超过 50 时自动放大间距（nodesep: 80 / ranksep: 120），并支持nodeDimensions按节点传尺寸。同一文件还沉淀了 ELK 的默认布局选项（elk.direction: DOWN、elk.layered.crossingMinimization.strategy: LAYER_SWEEP、正交布线elk.edgeRouting: ORTHOGONAL等）。从源码结构看，Phase 2 的 dagre 布局是"布局可配置化"的第一步，后续被更强大的 ELK 分层布局取代——这与仓库中 graph-layout-scaling 设计文档的主题相呼应。

5. Task 4：过期检测与增量图谱合并

5.1 设计边界

计划明确划分了职责：本任务只构建"积木"——检测变更文件、把新节点/边合并进现有图谱；不调用 LLM 和 tree-sitter（那是 skill 层的编排工作）。自动同步流程为：读meta.json→ 与上次 hash 做 git diff → 仅重新分析变更文件 → 合并进现有图谱。

5.2 三个核心函数

getChangedFiles(projectDir, lastCommitHash)：执行git diff <hash>..HEAD --name-only（cwd: projectDir），按行拆分；git 出错时返回空数组（容错优先）。测试用例验证了命令形态git diff abc123..HEAD --name-only、无变更返回空、异常返回空三种情况。

isStale(projectDir, lastCommitHash)：封装为{ stale: changedFiles.length > 0, changedFiles }。

mergeGraphUpdate(existingGraph, changedFilePaths, newNodes, newEdges, newCommitHash)的合并规则：

按filePath移除属于变更文件的旧节点；
移除source 属于变更文件的旧边；
追加新节点与新边；
更新project.gitCommitHash与project.analyzedAt（当前时间 ISO 串）。

测试覆盖了：变更文件节点被替换（旧foo函数消失、新bar出现、b.ts不变、hash 更新）、旧 contains 边被移除且新 imports 边权重为 0.9、analyzedAt时间戳刷新。

5.3 源码演进：同步 → 异步新鲜度状态机

当前 staleness.ts 完整保留了计划的getChangedFiles/isStale/mergeGraphUpdate三个同步 API（测试 staleness.test.ts 对应验证），并在此之上新增了一套异步getGraphFreshness体系，把"二值 stale"升级为四态结果：

export type GraphFreshnessResult = | { status: 'fresh'; changedFiles: []; commitsBehind: 0; commitsAhead: 0; ... } | { status: 'dirty'; changedFiles: string[]; ... } // 仅工作区有未提交变更 | { status: 'stale'; relation: 'behind' | 'ahead' | 'diverged'; commitsBehind: number; commitsAhead: number; ... } | { status: 'unknown'; reason: GraphFreshnessUnknownReason; ... };

工程细节值得细读：

git 调用全部异步化（execFile封装的runGit，5 秒超时、4MB 缓冲区，staleness.ts#L70-L117），失败映射到明确的unknown原因（git-head-unavailable、graph-commit-unavailable、git-command-timeout等）；
monorepo 感知：所有 diff 都带 pathspec-- . :(exclude).understand-anything /** :(exclude).ua /**，排除兄弟项目改动与图谱产物本身；
关系判定用git merge-base --is-ancestor双向探测，区分图谱落后（behind）、领先（ahead）与分叉（diverged），并给出commitsBehind/commitsAhead计数（git rev-list --left-right --count）；
源码注释明确表态："unknown 与 fresh 刻意区分：读不到 Git 元数据时应温和告警而非宣称图谱是最新的"。

mergeGraphUpdate的实现也有一处关键修正：保留边的条件从"仅看 source"改为source 或 target 任一落在被删节点集即移除（staleness.ts#L472-L508），避免悬挂边。

6. Task 5：分层自动推断——启发式与 LLM 双通道

6.1 启发式通道：目录模式匹配

计划定义LAYER_PATTERNS：目录路径子串 → 分层信息的有序映射，"首个匹配胜出"（first match wins），未匹配文件归入 "Core" 层；仅type === 'file'的节点参与分层。计划中的分层包括 API Layer（route/controller/handler/endpoint）、Service Layer（service/usecase/business）、Data Layer（model/entity/schema/database/migration/repository）、UI Layer（component/view/page/screen/layout）、Middleware Layer、Utility Layer、Test Layer、Configuration Layer。

对应测试断言：src/routes/users.ts归入 API 层、src/models/user.ts归入 Data 层、无匹配文件落入通用层、层 ID 唯一、函数节点不出现在任何层里。

当前实现 layer-detector.ts 保留了整体思路，但匹配策略更严谨：matchFileToLayer把路径按/拆段后做段级等值或复数匹配（segment === pattern || segment === pattern + 's'），避免子串误伤（如文件名里恰好含 "api" 字母序列）；分层也扩展到了 External Services、Background Tasks 等 10 类。detectLayers还优化为单遍扫描（无路径的 file 节点在主循环中先行收集，最后并入 Core，保持插入顺序）。

6.2 LLM 增强通道：prompt 构建与响应解析

计划给出三个配套函数：

buildLayerDetectionPrompt(graph)收集全部文件路径，要求 LLM 只返回 JSON：

{ "layers": [ { "name": "Layer Name", "description": "What this layer does", "filePatterns": ["path/prefix/"] } ] }

规则：识别 3–7 个逻辑层、每层有清晰架构职责、filePatterns用路径前缀表达。

parseLayerDetectionResponse(response)做防御性解析：剥离 markdown 代码围栏、JSON.parse、校验layers数组、逐项类型归一；任何异常返回null。

applyLLMLayers(graph, llmLayers)把 LLM 结果物化为Layer[]：按filePatterns前缀匹配 file 节点（一个节点只归一个层）、未分配的落入 "Other" 层、过滤空层。

当前实现与计划高度一致，且解析器更宽容：既支持{"layers": [...]}对象也支持裸 JSON 数组（/\[[\s\S]*\]/提取），逐项校验name必须是字符串。这组"启发式保底 + LLM 增强"的双通道设计，是"有 LLM 更好、无 LLM 也能用"的典型工程取舍。

7. Task 6：Skill 包与 /understand-chat 命令

7.1 包脚手架

计划创建packages/skill（@understand-anything/skill，ESM + tsc + vitest，依赖 workspace 内的 core），这是首个 Claude Code skill 命令的载体。/understand-chat的定位是终端内问答：skill 读取持久化的.understand-anything/knowledge-graph.json，用当前 Claude 会话作为 LLM——不发起独立 API 调用，零额外成本。

7.2 context-builder：检索 + 一跳扩展 + 格式化

buildChatContext(graph, query, maxNodes = 15)的算法四步走：

用 core 的SearchEngine检索前maxNodes个相关节点；
沿边一跳扩展：命中节点的邻接节点全部纳入；
收集两端都在相关集合内的边；
收集包含相关节点的层。

返回ChatContext { projectName, projectDescription, languages, frameworks, relevantNodes, relevantEdges, relevantLayers, query }。

formatContextForPrompt把上下文渲染为 Markdown：项目头（名称/描述/语言/框架）→## Relevant Layers（每层### 名称 + 描述）→## Relevant Code Components（每节点：名称、类型、复杂度、文件路径、摘要、tags、languageNotes）→## Relationships（- 源 --[边类型]--> 目标 (描述)的边列表）。

计划中的测试（context-builder.test.ts 即其来源）用了一个 4 节点、2 边、2 层的样例图谱，断言：查询 "how does authentication work?" 能找到 auth 节点、上下文包含连接节点（db/connection、routes/api）、携带项目元数据、包含相关层；格式化文本包含login.ts、authentication与边类型imports。

当前实现 context-builder.ts 与计划几乎逐行对应（用nodeMap按扩展后 ID 有序收集节点是微小的工程优化），maxNodes默认 15 保持不变。

7.3 提示词模板

buildChatPrompt(graph, query)将系统指令与上下文拼接，指令要点：引用具体文件与函数；架构类问题要描述层级与关系；不确定就明说、不要猜。当前 understand-chat.ts 保留了同构的五条指令，输出格式改为以---分隔"指令 / 上下文 / 用户问题"三段，结尾以**User question:** ${query}收尾。

7.4 Skill 定义文件

计划中的 skill markdown（frontmatter 声明name: understand-chat、arguments: query）指令链：读图谱文件 → 不存在则提示先跑/understand→ 用图谱上下文回答${ARGUMENTS}→ 引用具体文件/函数/关系 → 有层则解释相关层 → 简洁但完整。

仓库中的正式落地是 skills/understand-chat/SKILL.md，在计划骨架上大幅扩充为可操作的工作流：声明图谱 JSON 的完整结构参考（project/nodes/edges/layers/tour 及各节点类型体系）、"高效读取"准则（先 Grep 再读、别把整个图谱倒进上下文）、数据目录解析（.ua/新目录与.understand-anything/遗留目录二选一）、以及与 Task 4 新鲜度逻辑同构的 Git 校验序列：

GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null) git rev-parse HEAD git diff --name-only "$GRAPH_COMMIT" HEAD -- . git diff --cached --name-only -- . git diff --name-only -- . git ls-files --others --exclude-standard -- .

其中-- .pathspec 是 monorepo 防误报的关键，"hash 不一致但项目内 diff 为空"不算过期——这与staleness.ts中PROJECT_PATHSPEC的排除策略一脉相承。

8. Task 7：Dashboard 搜索接入与 Store 集成

8.1 Store 改造

计划要求把 Zustand store 中的子串过滤替换为 core 的SearchEngine：setGraph时构造引擎并随 graph 一起存入 store；setSearchQuery时空查询清空结果，否则调用engine.search(query)得到带分数的SearchResult[]（store 中searchResults的类型从string[]升级为SearchResult[]）。

当前 store.ts 确认了这一接线：第 2 行import { SearchEngine } from "@understand-anything/core/search"，setGraph内new SearchEngine(graph.nodes)（L367），查询时engine.search(query)写入searchResults（L543）。源码注释还透露了后续方向：

当嵌入向量可用时，"semantic" 模式将改用SemanticSearchEngine。

8.2 UI 侧增强

SearchBar：显示带 "fuzzy" 标签的结果计数；前 5 名以下拉形式展示（名称 + 类型 + 分数）；点击结果选中节点并滚动定位；
GraphView 分数高亮：高亮强度随分数变化——分数越低（匹配越好）高亮越亮（亮黄色环），弱匹配则更暗；分数作为 data 传入 CustomNode 调整外观。

9. Task 8：Dashboard 聊天面板

9.1 设计要点

独立 Dashboard（无 Claude Code 会话）场景下，用户自备 Claude API key。聊天为上下文感知：自动带上当前选中节点的上下文与邻近图关系。计划要求安装@anthropic-ai/sdk，并流式渲染响应。

store 新增状态：apiKey、chatMessages: ChatMessage[]（role: 'user' | 'assistant'）、chatLoading，及setApiKey/sendChatMessage/clearChat。sendChatMessage的六步流程：取 store 中的 graph/selectedNodeId/apiKey → 用buildChatContext+formatContextForPrompt构建上下文 → 组装系统提示词 → 调用 Claude API → 流式更新消息列表 → 全程维护chatLoading。

9.2 组件规格

ChatPanel七大特性：API key 输入（一次性显示、存 zustand 并持久化到 localStorage）、user/assistant 分色的消息列表、输入框 + 发送按钮、选中节点时的 "Context: <节点名>" 指示器、调用中 loading 动画、自动滚动到最新消息、assistant 消息的基础 Markdown 渲染（粗体/代码块/列表）。布局示意图中展示了"选中auth/login.ts后提问 'How does auth work?'，助手回答可顺藤摸到routes/api.ts的调用链"的完整对话闭环，验收步骤即：填 key → 选节点 → 问 "what does this do?" 验证上下文回答 → 追问验证会话历史保持。

10. Task 9：分层可视化

计划要求图谱含layers时按层分组渲染：

store 增加showLayers: boolean与toggleLayers；
GraphView 开启分组时为每层创建 React Flow 的 group 节点（大号半透明背景矩形），层成员以parentId挂为子节点，各层配色可区分，层名作为 group 标签；showLayers关闭时正常渲染；
LayerLegend组件：Show/Hide Layers 切换按钮、带色点/名称/节点数的层列表、点击层名可过滤图谱到该层；
图例挂在 App.tsx 头部 SearchBar 旁；
验收依赖把packages/dashboard/public/knowledge-graph.json样例更新为含 layers 的数据。

11. Task 10：集成打磨——样例数据、构建验证与文档

11.1 富样例图谱

计划要求把knowledge-graph.json升级为能"压测"全部 Phase 2 特性的样例：15–20 个节点覆盖全部 5 种类型（file/function/class/module/concept）、20+ 条多类型边、4–5 个层（API/Service/Data/UI/Utility）、复杂度分布有变化、摘要与标签拟真——同时充当演示数据与手工测试夹具。仓库中现存的 knowledge-graph.json 即是该任务的产物。

11.2 全量构建验证命令

pnpm install pnpm --filter @understand-anything/core build pnpm --filter @understand-anything/skill build pnpm --filter @understand-anything/core test pnpm --filter @understand-anything/skill test pnpm dev:dashboard

并要求更新CLAUDE.md（补充 skill 包 build/test 命令与 Phase 2 特性清单）和README.md（特性描述与截图占位）。

12. 验证清单与任务依赖关系

12.1 十条验收清单

计划末尾给出端到端验证清单：

Schema 校验：加载损坏 JSON → 应以清晰错误信息抛出；
模糊搜索：输入auth contrl→ 应命中AuthController类目标；
自动布局：打开 dashboard → 节点应呈层级排布而非网格；
过期检测：调用isStale('/project', 'oldHash')→ 应检出变更；
分层推断：对含 routes/models/services 的项目调用detectLayers(graph)→ 应填充 layers；
/understand-chat：确认 skill 文件存在于packages/skill/.claude/skills/understand-chat.md（计划口径；当前仓库中对应物为understand-anything-plugin/skills/understand-chat/SKILL.md）；
聊天面板：填 key、选节点、提问 → 验证上下文感知回答；
分层可视化：开启分层开关 → 应出现彩色 group 节点；
全量测试：pnpm --filter @understand-anything/core test && pnpm --filter @understand-anything/skill test；
全量构建：pnpm -r build成功。

12.2 依赖图与可并行分组

Task 1 (zod schema) ─────────────────────────────┐ Task 2 (search engine) ──┬── Task 7 (dashboard │ Task 3 (dagre layout) ───┤ search + store) │ │ │ Task 4 (staleness) ──────┤ │ │ │ Task 5 (layers) ─────────┼── Task 9 (layer viz) ─┤ │ ├── Task 10 (polish) Task 6 (skill pkg) ──────┼── Task 8 (chat panel) ─┤ │ │ Task 7 ──────────────────┘ │ Task 8 ──────────────────────────────────────────┘ Task 9 ──────────────────────────────────────────┘

Task 1、2、3、4、5、6 相互独立（按 subagent-driven-dev 惯例仍串行执行）；
Task 7 依赖 Task 2 + 3；Task 8 依赖 Task 6；Task 9 依赖 Task 3 + 5；Task 10 依赖全部。

13. 小结：从计划到源码的落地轨迹

对照计划文档与当前仓库源码，可以梳理出一条清晰的演进轨迹：

计划任务	计划中的 API	当前源码状态
Task 1 Schema 校验	`KnowledgeGraphSchema`/`validateGraph`，越界即失败	schema.ts 扩展为 38 种边类型 + 四级容错（sanitize → autoFix → 逐条丢弃 → fatal），`loadGraph`默认校验已接线
Task 2 搜索引擎	Fuse.js，四键加权，threshold 0.4	search.ts 接口不变，新增 extended search 的 OR 分词，多词模糊召回更强
Task 3 自动布局	dagre`TB`布局，280×120 节点	layout.ts 保留 dagre（标记 deprecated 作回退），主布局迁移至 ELK，间距随规模自适应
Task 4 过期检测	`getChangedFiles`/`isStale`/`mergeGraphUpdate`	staleness.ts 三函数保留，另增四态`getGraphFreshness`（fresh/dirty/stale/unknown）+ monorepo pathspec + 超时保护
Task 5 分层推断	8 类目录模式 + LLM 三函数	layer-detector.ts 10 类模式、段级精确匹配、prompt/解析/apply 三件套齐备
Task 6 skill 包	context-builder + buildChatPrompt + skill md	context-builder.ts、understand-chat.ts 落地，SKILL.md 扩展为含新鲜度校验的完整工作流
Task 7 store 集成	`SearchEngine`进 Zustand	store.ts 已接线，并预留语义检索模式
Task 8–9 面板与分层可视化	ChatPanel、LayerLegend、group 节点	对应组件已存在于 dashboard 组件目录（如 LayerLegend.tsx）
Task 10 打磨	富样例、文档更新	knowledge-graph.json 已含 layers 等完整结构

这份计划文档的价值不止于"任务清单"：它明确了每个功能的职责边界（core 出算法积木、skill 负责 LLM 编排、dashboard 消费 API）、测试先行的实现节奏，以及依赖图驱动的并行策略——这三点解释了为何 Phase 2 的八大特性（模糊搜索、Schema 校验、过期检测、分层推断、/understand-chat、聊天面板、自动布局、分层可视化）能作为一组一致的能力落入同一个 monorepo。对后续维护者而言，docs/superpowers/plans/2026-03-14-phase2-implementation.md 与其上游设计文档 2026-03-14-understand-anything-design.md 是理解这些模块"为什么这样设计"的最佳入口。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考