Understand Anything 在 Qoder 中的完整使用指南

电子工匠2026-07-21 10:37

一句话总结： Understand Anything 是一个多平台兼容的 AI 编程助手技能，它通过 Tree-sitter 静态分析 + LLM 语义理解的双引擎架构，将任何代码库转化为可交互的知识图谱，让你从"盲读代码"进化到"全景理解"。

目录

  1. [什么是 Understand Anything](#什么是 Understand Anything)

  2. 核心架构：双引擎驱动

  3. [在 Qoder 中的安装与配置](#在 Qoder 中的安装与配置)

  4. 八大技能命令详解

  5. 知识图谱数据结构

  6. 团队协作：共享知识图谱

  7. 进阶用法与最佳实践

  8. 常见问题与排错

什么是 Understand Anything

当你接手一个 20 万行代码的新项目时，你会从哪里开始？

Understand Anything 正是为了解决这个痛点而生的开源项目。它采用多 Agent 流水线架构，扫描项目中的每一个文件、函数、类和依赖关系，最终生成一份完整的 知识图谱（Knowledge Graph） ------以 JSON 格式保存在项目根目录的 .understand-anything/ 文件夹中。

这份知识图谱不仅仅是一堆节点和连线的集合，它包含了：

  • 每个代码单元的中文摘要：函数做什么、类负责什么、文件的核心职责

  • 架构层级分类：自动将代码划分为 API 层、Service 层、Data 层、UI 层等

  • 依赖关系网络：import、调用、继承等关系的完整图谱

  • 引导式学习路径（Tour）：按依赖顺序编排的代码学习路线

  • 业务域建模：业务领域、流程、步骤的结构化提取

支持平台一览

Understand Anything 不仅限于 Qoder，它同时支持 16+ 个 AI 编程平台：

平台 安装方式
Qoder Skill 文件直接调用
Claude Code 插件市场安装
Cursor 自动发现 .cursor-plugin/
VS Code + Copilot 自动发现 .copilot-plugin/
Codex / Gemini CLI 一键安装脚本
Trae / Cline / Kiro 一键安装脚本

核心架构：双引擎驱动

Understand Anything 的精髓在于它的 Tree-sitter + LLM 混合分析 架构。这不是简单的"把代码丢给 AI"，而是让确定性工具和语义智能各司其职。

Tree-sitter（确定性引擎）

Tree-sitter 是一个增量解析库，它将源代码解析为具体语法树（CST），提取出结构化的事实：

  • 导入/导出关系：谁引用了谁

  • 函数/类定义：名称、参数、返回值

  • 调用站点：哪些函数被调用了

  • 继承关系：类的层级结构

这些结构信息是完全确定性的------同样的代码永远产出同样的结果。它还驱动了基于指纹的变更检测，让增量更新成为可能。

LLM（语义智能引擎）

LLM 负责做 Tree-sitter 做不到的事情：

  • 生成自然语言摘要（"这个函数负责验证用户登录凭证"）

  • 打语义标签 （authentication、validation、database）

  • 分配架构层级（Service 层、Data 层）

  • 生成引导式学习路线（先理解 A，再理解 B）

  • 提取业务域知识（支付流程、用户注册流程）

多 Agent 流水线

/understand 命令编排 5 个专业 Agent 协同工作：

Agent 职责
project-scanner 发现文件，检测语言和框架
file-analyzer 提取函数、类、导入；生成图谱节点和边
architecture-analyzer 识别架构层级
tour-builder 生成引导式学习路线
graph-reviewer 验证图谱完整性和引用一致性

另外，/understand-domain 会额外调用 domain-analyzer 提取业务域知识，/understand-knowledge 则调用 article-analyzer 分析 Wiki 知识库。

文件分析器并行运行（最多 5 个并发，每批 20-30 个文件），并支持增量更新------只重新分析自上次运行以来变更的文件。

在 Qoder 中的安装与配置

前置条件

  • Node.js >= 22（推荐 v24）

  • pnpm >= 10

  • 目标项目最好是一个 Git 仓库

安装步骤

项目源码已下载到本地后，需要完成以下配置：

1. 安装依赖并构建核心包

复制代码 
cd Understand-Anything-main
pnpm install
pnpm --filter @understand-anything/core build

2. 设置系统链接

Understand Anything 的 Skill 文件需要被 Qoder 发现。在 Qoder 中，Skill 是通过阅读 SKILL.md 文件来执行的，因此你需要确保：

  • 插件目录通过 Junction 链接到 ~/.understand-anything-plugin

  • 技能目录链接到 ~/.agents/skills/ 下

安装完成后，目录结构如下：

复制代码 
~/.understand-anything-plugin → 插件目录（Junction）
~/.agents/skills/
├── understand/          → 核心分析技能
├── understand-chat/     → 问答技能
├── understand-dashboard/→ 仪表盘技能
├── understand-diff/     → 差异分析技能
├── understand-explain/  → 深度解释技能
├── understand-onboard/  → 入职指南技能
├── understand-domain/   → 领域建模技能
└── understand-knowledge/→ Wiki 分析技能

验证安装

在 Qoder 中输入以下指令测试安装是否成功：

复制代码 
请阅读 C:/Users/<你的用户名>/.agents/skills/understand/SKILL.md 并告诉我这个技能的作用

如果 Qoder 能正确读取并描述技能内容，说明安装配置完成。

八大技能命令详解

Understand Anything 提供了 8 个核心技能，覆盖从代码分析到团队协作的完整场景。

1. /understand --- 核心分析引擎

作用： 扫描整个代码库，生成完整的知识图谱 JSON。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand/SKILL.md 并按照其中的指令分析当前项目

参数选项：

参数 说明
--full 强制完整重建，忽略现有图谱
--auto-update 启用提交时自动更新图谱
--no-auto-update 禁用自动更新
--review 运行完整 LLM 图谱审查
--language <lang> 指定输出语言（zh、ja、ko 等）
<路径> 分析指定目录而非当前目录

中文输出示例：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand/SKILL.md 并按照其中的指令分析当前项目，使用 --language zh 参数

分析过程：

执行后，你会看到类似的进度输出：

复制代码 
[Phase 1/7] Scanning project...
Phase 1 complete. Found 247 files across 3 languages.
[Phase 2/7] Analyzing files (12 batches)...
Analyzing batch 1/12 (files: src/index.ts, src/app.ts, ...)
Analyzing batch 2/12 (files: src/auth/login.ts, ...)
...
[Phase 3/7] Building architecture layers...
[Phase 4/7] Generating guided tours...
[Phase 5/7] Reviewing graph...
[Phase 6/7] Saving knowledge graph...
[Phase 7/7] Launching dashboard...

生成的文件：

复制代码 
.understand-anything/
├── knowledge-graph.json    ← 主知识图谱文件（核心产出）
├── config.json             ← 配置（语言偏好、自动更新开关等）
└── intermediate/           ← 中间产物（可忽略，会自动清理）

Token 使用提醒： 首次分析大型项目会消耗较多 Token。建议在 Token 订阅计划下运行，或使用本地模型。后续运行默认增量更新，只分析变更文件，Token 消耗大幅减少。

2. /understand-dashboard --- 可视化仪表盘

作用： 启动一个基于 React + Vite 的 Web 仪表盘，将知识图谱渲染为可交互的图形界面。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-dashboard/SKILL.md 并按照指令启动仪表盘

仪表盘功能：

  • 交互式图谱浏览：拖拽、缩放、平移

  • 按架构层级着色：API 层、Service 层、Data 层等颜色区分

  • 模糊 + 语义搜索：按名称或含义搜索节点

  • 节点详情面板：点击任意节点查看摘要、关系、源代码

  • 文件浏览器：树形结构浏览所有文件节点

  • 代码查看器：直接在仪表盘中查看源代码

技术细节：

仪表盘通过 Vite 开发服务器启动，使用 GRAPH_DIR 环境变量指向项目的知识图谱。启动后会生成一个带 Token 的 URL（如 http://127.0.0.1:5173?token=xxx），Token 是访问图谱数据的必需凭证。

3. /understand-chat --- 智能代码问答

作用： 基于知识图谱回答关于代码库的任何问题。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-chat/SKILL.md，然后回答：支付流程是怎么工作的？

工作原理：

  1. 检查知识图谱是否存在

  2. 读取项目元数据（名称、语言、框架）

  3. 在图谱中搜索与问题相关的节点（按名称、摘要、标签匹配）

  4. 追踪相关节点的 1-hop 子图（上下游依赖）

  5. 结合层级上下文，给出精确回答

优势： 与普通的代码问答不同，/understand-chat 基于预先构建的知识图谱回答问题，能精确引用文件路径、函数名称、依赖关系，而不是"幻觉式"的回答。

4. /understand-diff --- 变更影响分析

作用： 分析当前 Git 变更对系统的影响，在提交前了解"涟漪效应"。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-diff/SKILL.md 并分析当前的代码变更影响了哪些模块

分析维度：

维度 说明
变更组件 直接修改了哪些文件/函数（附摘要）
影响组件 通过依赖链可能受波及的模块
影响层级 触及了哪些架构层，是否有跨层影响
风险评估 基于复杂度、跨层边数、影响范围综合评估

额外产出： 分析完成后会生成 diff-overlay.json，在仪表盘中可以可视化展示变更和受影响的节点。

5. /understand-explain --- 深度代码解释

作用： 对指定文件、函数或类进行深入解释。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-explain/SKILL.md 并解释 src/auth/login.ts

支持的目标格式：

  • 文件路径：src/auth/login.ts

  • 函数标记：src/auth/login.ts:verifyToken

  • 类名：UserService

解释内容覆盖：

  • 在架构中的角色（属于哪一层，为什么存在）

  • 内部结构（包含的函数、类）

  • 外部连接（导入什么、被谁调用、依赖什么）

  • 数据流（输入 → 处理 → 输出）

  • 设计模式和值得注意的复杂度

6. /understand-onboard --- 新人入职指南

作用： 从知识图谱自动生成新团队成员的上手指南。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-onboard/SKILL.md 并生成入职指南

生成的指南包含：

  1. 项目概览：名称、语言、框架、描述

  2. 架构层级：每层的名称、描述、关键文件

  3. 核心概念：重要的设计模式和决策

  4. 引导式路线：按依赖顺序编排的学习步骤

  5. 文件地图：每个关键文件的职责（按层级组织）

  6. 复杂度热点：需要谨慎对待的区域

生成后可保存为 docs/ONBOARDING.md 并提交到仓库。

7. /understand-domain --- 业务领域建模

作用： 提取业务域知识------领域、业务流程、处理步骤------并生成交互式水平流程图。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-domain/SKILL.md 并提取业务领域模型

两种运行模式：

模式 条件 说明
派生模式 已有知识图谱 从现有图谱推导域知识（低成本）
轻量扫描 无知识图谱 执行轻量级文件扫描 + 入口点检测

使用 --full 参数可强制重新扫描。

产出文件： .understand-anything/domain-graph.json，在仪表盘中以水平流程图形式展示。

8. /understand-knowledge --- Wiki 知识库分析

作用： 将 Karpathy 模式的 LLM Wiki 知识库转化为可交互的知识图谱。

在 Qoder 中使用：

复制代码 
请阅读 C:/Users/<用户名>/.agents/skills/understand-knowledge/SKILL.md 并分析 ~/path/to/wiki

什么是 Karpathy 模式 Wiki？

这是一种三层知识库结构：

  • Raw Sources：原始文档（论文、文章、数据文件）

  • Wiki ：LLM 生成的 Markdown 文件，使用 [[target]] 语法互相引用

  • Schema：配置文件（CLAUDE.md 等）

分析流程：

  1. DETECT --- 检测目录是否符合 Karpathy Wiki 模式

  2. SCAN --- 确定性提取 Wikilinks、标题、分类

  3. ANALYZE --- LLM Agent 发现隐含关系、提取实体和观点

  4. MERGE --- 合并确定性结果 + LLM 分析结果

  5. SAVE --- 保存验证后的图谱

知识图谱数据结构

理解知识图谱的 JSON 结构，有助于你更好地使用各项技能。

复制代码 
{
  "project": {
    "name": "my-project",
    "description": "项目描述",
    "languages": ["TypeScript", "Python"],
    "frameworks": ["React", "Express"],
    "analyzedAt": "2026-07-20T10:00:00Z",
    "gitCommitHash": "abc123"
  },
  "nodes": [
    {
      "id": "file:src/auth/login.ts",
      "type": "file",
      "name": "login.ts",
      "filePath": "src/auth/login.ts",
      "summary": "处理用户登录认证的核心模块",
      "tags": ["authentication", "security"],
      "complexity": 7,
      "languageNotes": "使用 TypeScript 泛型和 async/await"
    }
  ],
  "edges": [
    {
      "source": "file:src/auth/login.ts",
      "target": "file:src/db/users.ts",
      "type": "imports",
      "direction": "outgoing",
      "weight": 0.8
    }
  ],
  "layers": [
    {
      "id": "layer-api",
      "name": "API 层",
      "description": "HTTP 路由和请求处理",
      "nodeIds": ["file:src/routes/...", "..."]
    }
  ],
  "tour": [
    {
      "order": 1,
      "title": "入口点",
      "description": "从 main.ts 开始理解应用启动流程",
      "nodeIds": ["file:src/main.ts", "..."]
    }
  ]
}

节点类型一览：

分类 类型
代码节点 file、function、class、module、concept
非代码节点 config、document、service、table、endpoint、pipeline、schema、resource
域/知识节点 domain、flow、step、article、entity、topic、claim、source

边类型一览：

imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites

团队协作：共享知识图谱

知识图谱本质上就是一个 JSON 文件------提交一次，团队成员就能跳过分析流水线。

提交到 Git

复制代码 
# .gitignore 中排除中间产物
.understand-anything/intermediate/
.understand-anything/diff-overlay.json

提交 .understand-anything/ 目录下的其他文件即可。

启用自动更新

复制代码 
请阅读 .../understand/SKILL.md 并按照指令分析当前项目，使用 --auto-update 参数

这会创建一个 post-commit hook，每次提交时增量更新图谱，确保图谱与代码始终同步。

大型图谱（10 MB+）

对于超大项目，建议使用 Git LFS：

复制代码 
git lfs install
git lfs track ".understand-anything/*.json"
git add .gitattributes .understand-anything/

进阶用法与最佳实践

指定子目录分析

对于大型 monorepo，可以只分析特定子目录：

复制代码 
请阅读 .../understand/SKILL.md 并分析 src/frontend 目录

多语言输出

--language 参数支持的语言：

代码 语言
en 英语（默认）
zh 简体中文
zh-TW 繁体中文
ja 日语
ko 韩语
ru 俄语

语言偏好会保存在 config.json 中，后续增量更新自动复用。

推荐的 .understandignore

虽然 Understand Anything 会自动遵循 .gitignore，但对于特殊场景，可以在分析时排除不必要的目录：

  • node_modules/

  • dist/ / build/

  • .next/ / .nuxt/

  • 测试 fixture 数据

  • 自动生成的代码

工作流集成建议

复制代码 
1. 项目初始化 → /understand --language zh    # 首次完整分析
2. 日常开发    → /understand                   # 增量更新（自动检测变更）
3. 提交前      → /understand-diff             # 了解变更影响
4. 遇到问题    → /understand-chat             # 基于图谱的精准问答
5. 深入研究    → /understand-explain <文件>   # 某个模块的深度解析
6. 新人入职    → /understand-onboard          # 自动生成上手指南
7. 业务梳理    → /understand-domain           # 提取业务域模型

常见问题与排错

Q: 首次分析消耗大量 Token 怎么办？

这是正常现象。首次分析需要遍历所有文件并调用 LLM 生成摘要。后续增量更新只分析变更文件，Token 消耗会大幅减少。建议：

  • 使用 Token 订阅计划运行首次分析

  • 使用本地模型（如通过 Ollama）降低成本

  • 对大型 monorepo，使用子目录参数分而治之

Q: 仪表盘启动后显示 "Access Token Required"？

确保使用带 ?token= 参数的完整 URL 访问。Qoder 会在启动时输出完整 URL，复制粘贴即可。

Q: 知识图谱文件太大，Git 操作变慢？

  • 启用 Git LFS 追踪 .understand-anything/*.json

  • 排除 intermediate/ 目录

  • 对于超大型项目，考虑使用子目录分析

Q: 分析中途失败怎么办？

重新运行即可。Understand Anything 会检测已有的中间状态，从断点处继续（增量更新机制）。

Q: 如何更新 Understand Anything 版本？

复制代码 
# 如果使用 Git 克隆安装
cd Understand-Anything-main
git pull
pnpm install
pnpm --filter @understand-anything/core build

总结

Understand Anything 不只是一个代码可视化工具------它是一个 AI 驱动的代码理解系统。

场景 使用的技能 价值
接手新项目 /understand + /understand-dashboard 快速建立全局认知
日常开发 /understand-diff 提交前了解影响范围
遇到问题 /understand-chat 基于图谱的精准回答
深入某模块 /understand-explain 架构 + 代码 + 数据流全景
团队扩张 /understand-onboard 自动生成入职文档
业务理解 /understand-domain 业务流程可视化
知识管理 /understand-knowledge Wiki → 知识图谱

在 Qoder 中使用 Understand Anything，你获得的不只是一张好看的图谱，而是一个 可以持续维护、团队共享、不断进化的代码知识库。

停止盲读代码，开始理解一切。

相关推荐
猫先生Mr.Mao8 小时前
具身智能之OneTwoVLA详解：如何统一推理与行动
ai·论文解读·具身智能·vla·onetwovla
带刺的坐椅8 小时前
Solon TeamAgent 协作协议：从 SEQUENTIAL 流水线到 HIERARCHICAL 主管团队
java·ai·llm·agent·solon
doiito8 小时前
【RUST AI】把 TTS 搬进浏览器：kokoroi-rs 的 WASM 实践
ai·rust·架构设计
亮亮在江湖9 小时前
YOLO训练 vs LlamaFactory训练 完整区分
ai
wabs6669 小时前
关于文献【RL/SFT】
ai·文献
ofoxcoding9 小时前
Seedance 2.0 与 Wan 2026 视频生成 API 成本效率深度对比分析
网络·人工智能·ai·音视频
码农杂谈00079 小时前
组织管理视角深度解读：时尚集团GEA智能体案例——AI重构创意行业的组织资产与人力博弈
ai·gea·context资产
wuyuanshun9 小时前
LangGraph原理逻辑-LangGraph接入MCP（三）
人工智能·ai
hhzz9 小时前
CNN图像分类入门：基于TensorFlow+Keras的CIFAR-10数据集全流程实战
图像处理·计算机视觉·ai·cnn·大模型
热门推荐
012026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片02GitHub 镜像站点03如何新建文件夹？ 电脑新建文件夹的4种方法04AI科技热点日报 | 2026年07月01日05幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南06国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）07【AI前线观察】2026年国产开源大模型全面横评：从 DeepSeek V4 到 Kimi K3，谁才是开发者的最优选择？08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路092026 年 AI 大模型 & AI 编程工具实战全总结102026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？