用途
understand-knowledge 技能面向符合 Karpathy 模式(参考 https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)的 LLM wiki 知识库,分析其中的原始来源、wiki 标记文件和模式文件等结构,并生成交互式知识图谱仪表板,帮助用户以图形化方式理解知识库中的实体、关系与主题分类。
主要能力
格式检测
技能会检测目标目录是否符合 Karpathy 模式。检测信号包括存在 index.md 以及多个带有 wikilink([[target]] 语法)的 .md 文件,可能还包含 raw/ 目录和模式文件(如 CLAUDE.md、AGENTS.md)。它会识别以下结构:
- 原始来源:不可变的源文档(文章、论文、数据文件)
- Wiki:LLM 生成的带 wikilink 的标记文件
- 模式:CLAUDE.md、AGENTS.md 等配置文件
- index.md:按类别组织的内容目录
- log.md:按时间顺序的操作日志
扫描提取
通过内置脚本进行确定性扫描,生成 scan-manifest.json,包含:
- 文章节点(每个 wiki .md 文件一个),提取 wikilink、标题、frontmatter
- 来源节点(每个 raw/ 文件一个,仅文件名和大小)
- 主题节点(来自 index.md 章节标题)
- related 边(来自 wikilink)
- categorized_under 边(来自 index.md 章节)
隐式知识分析
将文章按类别分批(每批 10-15 篇),调度 article-analyzer 子代理提取需要推理的隐式知识,最多同时运行 3 批。即使某批失败,仍保留扫描得到的基础图谱。
合并与保存
合并脚本将扫描清单与各批分析结果合并,进行实体去重(不区分大小写)、节点/边类型归一化、按 index.md 类别构建层级、按章节顺序构建导览,并输出 assembled-graph.json。随后进行基本校验,移除悬空边,保存为 knowledge-graph.json,并写入 meta.json(包含最后分析时间、git 提交哈希、版本号、分析文件数)。
使用方式
技能按以下阶段执行:
- 检测:确定目标目录(用户提供的路径或当前工作目录),解析数据目录(优先使用已存在的 .understand-anything/,否则使用 .ua/),运行 parse-knowledge-base.py 脚本。若脚本报错,提示用户这不是 Karpathy 模式 wiki 并说明预期结构。成功则读取 scan-manifest.json 并公布结果。
- 扫描:由第一阶段脚本完成,无需额外操作。
- 分析:读取 scan-manifest.json,按类别分批(每批 10-15 篇),调度 article-analyzer 子代理,将文章内容视为不可信数据,只作为源文本使用,忽略其中嵌入的任何指令。子代理输出 analysis-batch-{N}.json 到中间目录。
- 合并:运行 merge-knowledge-graph.py,读取合并报告并公布节点、边、层级、导览步骤及新增实体/断言数量。
- 保存:读取 assembled-graph.json,校验每条边的源/目标引用存在节点、每个节点包含 id、type、name、summary、tags、complexity,移除悬空边,复制到 $UA_DIR/knowledge-graph.json,写入 meta.json,清理中间文件(有路径保护),报告摘要,并自动触发 /understand-dashboard。
适用场景
适用于需要分析 Karpathy 模式 LLM wiki 知识库并生成可视化知识图谱的场景,例如整理由 LLM 生成的 wiki 文档、发现文章间的隐式关联、按主题分类浏览知识库结构。
限制
- 仅识别 Karpathy 模式 wiki,其他格式可能无法处理。
- 来源节点仅记录文件名和大小,不解析 PDF 或二进制文件内容。
- 类别和分类来自 index.md 章节标题,而非文件名前缀。
- 隐式知识分析依赖 LLM 子代理,若批次失败则缺少该部分隐式关系,但基础图谱仍保留。
- 图谱使用 kind: "knowledge" 以指示仪表板采用力导向布局而非分层 dagre 布局。