Understand Anything + Codex 使用教程：在云服务器上为大型代码仓库生成中文知识库

现在用 Codex 这类 AI Coding Agent 写代码已经非常方便。对于一个规模不大的项目，我们通常可以直接让 AI 搜索相关代码、理解几个文件，然后完成修改。但当项目逐渐扩大到几百甚至上千个文件以后，问题就不再只是“代码怎么写”了。AI 在真正开始修改之前，往往还要先寻找入口、梳理模块关系、理解类之间的依赖，再逐渐建立对项目的认识。每换一个任务，这些工作又可能重新做一遍。
Understand Anything，下面简称 UA，提供了另一种思路：先对整个代码仓库进行一次结构化分析，把项目中的文件、代码实体、模块关系和架构信息整理成 Knowledge Graph，再让 Codex 基于这份知识库理解项目。
这篇文章主要介绍我前两天实践项目中实际跑通的一套使用方式：在 Linux 云服务器上部署 Understand Anything，用 Codex 调用 UA 为 RD-Agent 生成中文知识库，然后通过 understand-chat 使用这份知识库辅助代码定位和开发。这里我不会把 UA 描述成“自动修复 Bug 的工具”。更准确地说，它承担的是代码库理解和导航的角色。真正准备修改代码时，仍然要回到真实源码，并通过测试验证结果。
一、云服务器环境与项目准备
本文所有操作都在一台 Linux 云服务器上完成。我使用的是阿里云ECS，系统为Ubuntu 22.04，配置为4vCPU 16G。后面的路径、终端以及命令也都是Linux 、环境。
我先进入服务器上已有的实验目录：cd /root/AI-Experiment
为了让这次操作和其他项目隔离开，又单独创建了一个 UA-RD-Agent-Experiment 目录，然后进入该目录：
mkdir UA-RD-Agent-Experiment
cd UA-RD-Agent-Experiment
接下来直接克隆本文用于演示的大型项目 RD-Agent：
git clone https://github.com/microsoft/RD-Agent.git
克隆结束后，通过 ls 可以看到当前目录下已经出现 RD-Agent，进入项目后再次查看目录，就能看到 rdagent、docs、test、README.md、pyproject.toml 等典型的项目文件。
随后我为 RD-Agent 准备了独立 Python 环境，并安装了当前项目。从截图中也可以看到后续终端已经进入 (.venv) 环境，并开始执行 RD-Agent 的 editable install。这样后面 Codex 真正修改源码时，可以直接在项目环境中运行和验证代码。

RD-Agent 环境准备完成以后，我继续确认服务器上的 Node.js 和 npm。截图中实际得到的版本分别为：
node -v
输出：
v22.23.2
以及：
npm -v
输出：
10.9.8
随后直接克隆 Understand Anything：
git clone https://github.com/Egonex-AI/Understand-Anything.git
这一步完成后，服务器中就同时存在了我们真正要分析的 RD-Agent，以及用于生成知识库的 Understand Anything。

PS：如果自己的服务器上没有 Node.js 或 pnpm，需要先完成相应环境安装。本文这次实际操作开始时两者已经存在，所以这里不额外展开安装命令。
二、安装并构建 Understand Anything
进入 Understand Anything 项目以后，首先安装项目依赖：
pnpm install
Understand Anything 本身是一个基于 Node.js 和 TypeScript 开发的项目，因此需要先安装它依赖的各种 JavaScript/TypeScript 库。这里使用项目本身指定的 pnpm 作为包管理器，执行 pnpm install 后，pnpm 会自动读取项目配置并安装 UA 运行和构建所需要的依赖。
从实际输出中还能看到安装结束时执行了：@understand-anything/core ... build tsc 最后出现：Done in 14.6s。说明安装阶段顺利完成。

依赖安装结束后继续执行：
pnpm build
这个过程会进一步构建 Understand Anything 中的多个组件。从截图能够看到 homepage、viewer、core、dashboard 等模块依次参与构建，最后重新回到 Shell。


到这里，Understand Anything 本身已经能够在服务器上正常工作。接下来真正重要的不是继续研究 UA 源码，而是回到 RD-Agent 项目，让 Codex 使用 UA 提供的 Skill 为这个大型仓库建立知识库。
三、让 Codex 为代码仓库生成中文 Knowledge Graph
我重新进入 RD-Agent 项目后启动 Codex。从截图里可以看到，此时 Codex 的工作目录已经是：
~/AI-Experiment/UA-RD-Agent-Experiment/RD-Agent
也就是说，接下来 UA 分析的就是这个 RD-Agent 仓库，而不是刚才的 Understand Anything 源码目录。
在 Codex 中选择：
$understand-anything:understand
然后给出本次任务要求（这里用chatgpt替你生成，对新手来说能达到更好的效果）：
请为当前 RD-Agent 项目生成 Understand Anything 中文知识库。

要求：

1. 分析整个代码仓库
2. 使用中文生成描述
3. 创建完整 knowledge graph
4. 保留分析过程
5. 完成后输出：

• 分析文件数量
• 节点数量
• 关系数量
• 项目架构分层
  这一点很值得注意：understand 的作用是生成或者更新知识库。我们不是让 Codex 自己临时搜索几个文件，而是明确要求它调用 UA，对当前整个仓库进行分析。同时，达到UA知识库中文字描述改为中文，只需要向codex提出要求使用中文生成描述即可，无需其他操作。
  

下面可以看到：“请为当前 RD-Agent 项目生成 Understand Anything 中文知识库。”
为了让最终生成的自然语言摘要使用中文，UA 在项目中创建了：
.ua/config.json
其中写入：
{
"outputLanguage": "zh"
}
**zh **就代表中文。
这一点从实际执行过程里可以直接看到：Codex 先读取 understand Skill，检查当前仓库和 Git 状态，然后创建 .ua/config.json，随后继续生成 .understandignore。

.understandignore 可以理解为 UA 在分析代码仓库时使用的一份排除规则。对于大型项目来说，仓库里往往还包含测试、文档、脚本、缓存或者其他辅助文件，UA 会根据分析策略判断哪些内容应该进入知识图谱。完成这些准备工作以后，UA 会先进行一次预检。实际输出中包括当前 Git Commit、Node.js、pnpm、Understand Anything 插件是否可用，以及 .understandignore 是否已经生成。这一步结束时，Codex并没有直接继续，而是明确提示检查 .understandignore，确认后再开始整个仓库扫描。

确认继续以后，UA 开始正式扫描项目。Phase 1 的结果显示，它发现了：837 个文件，19 种语言
随后开始把这些文件分批交给分析流程进行结构提取和语义分析。

中间可以看到：Phase 1 完成：发现 837 个文件、19 种语言
这里也能比较直观地看出 UA 与“给每个文件写一句摘要”的区别。它在文件分析完成以后，还会继续合并节点和关系，再从项目整体结构上进行架构划分。
例如后续 Phase 4 中，它会基于文件级节点计算目录群组、跨组依赖、fan-in/fan-out 等信息，最终识别出 10 个中文架构层。

下方可以看到：识别出 10 个中文架构层。最终，这次 RD-Agent 分析得到：分析文件：837，知识图谱节点：2,299，关系：4,438，架构层：10，中文导览：11 步，校验问题：0而且整个 Knowledge Graph 已经通过结构校验。

这张结果图下面还能直接看到最终输出位置：
.ua/knowledge-graph.json
.ua/intermediate
.ua/intermediate/scan-result.json
.ua/intermediate/final-review.json
所以完成这一步以后，真正意义上的代码知识库已经生成了。
四、Knowledge Graph 到底是什么？
生成完成后，我又查看了 .ua 目录。截图中可以看到：
config.json
fingerprints.json
intermediate
knowledge-graph.json
meta.json
在知识库其中最核心的文件是：
.ua/knowledge-graph.json
第一次接触UA的话，我觉得这里最值得讲清楚。因为如果只是说“它生成了一个知识图谱”，大家其实很难知道这个 Knowledge Graph 和普通 README、代码摘要究竟有什么区别。实际打开以后，文件开头类似这样：
{
"version": "1.0.0",
"project": {
"name": "rdagent",
"languages": [
...
],
"frameworks": [
"Docker",
"Flask",
"GitHub Actions",
"pytest"
],
"description": "RD-Agent 是一个面向研究与开发流程自动化的智能 Agent 项目...",
"analyzedAt": "2026-08-25T06:50:12.618Z",
"gitCommitHash": "6762f84f9bc0f5c6486c50a00e128a57ac6c3683"
}
}

这里可以一项一项理解。
version是这份 Knowledge Graph 自身的数据格式版本。project表示这一部分描述的是整个项目级信息。name是UA识别到的项目名称，这里就是 rdagent。languages记录了仓库中识别出的语言和文件类别。从截图中可以看到 Python、JavaScript、TypeScript、Vue、YAML、Markdown、Dockerfile 等多种类型，因此 UA 并不是只分析 .py 文件，而是在理解整个软件仓库。frameworks则给出了项目中识别出的技术框架和基础设施，例如Docker、Flask、GitHub Actions和pytest。description 是 UA 对整个项目生成的自然语言摘要。因为前面设置了："outputLanguage": "zh"所以这里已经变成中文。analyzedAt 表示知识库生成时间，而 gitCommitHash 则非常重要，它记录了生成这份 Knowledge Graph 时对应的代码版本。换句话说，这份知识库不是脱离源码版本独立存在的。如果代码仓库后面发生了大量更新，而知识库仍然是旧 Commit 生成的，那么其中某些文件关系和摘要就可能不再准确。
继续往下看就进入真正的节点区域：
"nodes": [
例如第一个文件节点：
{
"id": "file:rdagent/app/CI/run.py",
"type": "file",
"name": "run.py",
"filePath": "rdagent/app/CI/run.py",
"summary": "实现 RD-Agent 研发自动化流程中的业务逻辑，包含11个类。",
"tags": [
"python",
"业务逻辑",
"agent"
],
"complexity": "complex"
}

这里的id是节点在 Knowledge Graph 中的唯一标识。file:表示它是一个文件节点，后面就是实际文件路径。type进一步说明节点类型，这里是 file。name 是文件名，而 filePath 则直接指向真实源码，也就是：rdagent/app/CI/run.py。这对 AI Coding 很重要，因为 Knowledge Graph 的作用不是让 Codex永远停留在摘要层面，而是先帮助它发现相关节点，然后根据 filePath 回到真实源码。summary是UA对节点生成的中文语义摘要，tags用来描述节点的性质，而complexity则是UA对该节点复杂程度的描述。
再向下还能看到 class 类型节点：
{
"id": "class:rdagent/app/CI/run.py:CIError",
"type": "class",
"name": "CIError",
"filePath": "rdagent/app/CI/run.py",
"summary": "...",
"complexity": "simple",
"lineRange": [
43,
57
]
}
这里 type 已经变成了 class。
而：
"lineRange": [
43,
57
]
进一步告诉我们这个类位于源文件的大致哪一段。因此更准确地说，knowledge-graph.json并不是“把源代码换一种格式再存一份”，而是在保存UA对项目结构的理解结果。文件、类等实体成为一个个节点，再通过各种关系组织起来，让AI能够从“项目级视角”查找和定位代码。
五、生成Knowledge Graph以后，怎么真正使用它？
前面我们使用的是：understand-anything:understand，它负责的是建立知识库。
当 .ua/knowledge-graph.json 已经存在以后，如果我们的目标只是理解项目、寻找代码或者分析某个Issue，就不应该每次都重新完整生成知识库，而应该切换到UA的Chat能力。
在我的实际执行记录中，Codex读取的是：
understand-anything:understand-chat skill
也就是 understand-chat。
真正工作时，我们并不需要人工把几千行 knowledge-graph.json 从头读到尾。更自然的方式是，让 understand-chat 基于已经生成好的知识库回答项目问题。
例如可以问：
当前仓库已经使用 Understand Anything 生成了项目知识库：
.ua/knowledge-graph.json
请先利用知识库理解当前问题涉及的项目架构、模块和代码关系，再读取真实源码进行核实。
为了保证正确性，在这套使用方式里，我认为Knowledge Graph只负责帮助定位，真实源码负责最终事实。也就是说，如果知识图谱告诉我们某个类与当前 Issue 有关，就根据它给出的路径去阅读实际代码，而不是只凭 summary 直接修改。
六、一个实际使用示例
最后用一个真实任务看一下这套流程究竟是怎样工作的。
我选择了RD-Agent的GitHub Issue #1430，并在Codex中明确告诉它当前仓库已经存在：
.ua/knowledge-graph.json
同时要求整个任务先利用这份知识库定位相关模块，再读取当前源码核实，然后复现问题、分析根因、修改代码、增加回归测试并检查最终 Diff。

随后 Codex读取：
Read SKILL.md (understand-anything:understand-chat skill)
并开始检查 .ua/knowledge-graph.json。
比较有意思的是，它首先核对了Knowledge Graph中记录的Commit和当前仓库HEAD是否一致，然后围绕：
DSTrace
get_sibling_exps
should_inject_diversity
DSProposalV2ExpGen
搜索知识图谱中的相关节点和关系，再进一步打开真实源码。

这张图其实最能体现UA的实际价值Codex不是完全从零搜索整个项目，而是先借助已经建立的Knowledge Graph缩小调查范围，再回到源码验证。
随后它成功复现：
KeyError: 0
并修改了两个文件。

图中可以看到：知识图谱与当前 HEAD 完全一致、KeyError: 0、Edited 2 files (+35 -2)
最终问题位于：
rdagent/scenarios/data_science/proposal/exp_gen/base.py
其中原来使用：
touched_node_set.remove(parent)
在多个节点共享同一个父节点的情况下，同一个 parent 可能被重复移除。第一次删除正常，第二次由于元素已经不存在，就会抛出 KeyError。
最终相应操作被改成：
touched_node_set.discard(parent)
同时新增针对共享父节点情况的回归测试。
后续 Codex继续执行 pytest、代码检查和 Diff 检查。
最终得到：
修复前：KeyError: 0
修复后：正常返回 ['B2']
pytest：2 passed
compileall：通过
git diff --check：通过

这个例子的重点其实并不是 remove() 改成 discard() 本身有多复杂，而是整个调查过程发生了变化：先通过 Knowledge Graph 理清与 Issue 相关的项目结构，再回到真实源码确定 Bug，最后完成修改和测试。
总结
Understand Anything 与 Codex 的组合，可以理解成在代码仓库和 AI Coding Agent 之间增加了一层项目级知识表示。
第一次接触陌生大型项目时，可以先使用understand对整个仓库进行分析，生成：.ua/knowledge-graph.json,如果希望知识库的自然语言内容使用中文，则可以像本文一样在 .ua/config.json 中让 outputLanguage 为 zh。知识库生成以后，日常理解项目时再使用understand-chat,让它根据现有Knowledge Graph查询相关模块、文件和代码实体。真正需要修改代码时，仍然回到真实源码确认实现，并通过测试验证最终修改。这套方式最值得记住的其实不是某一条命令，而是它背后的职责划分：
Understand Anything understand用来整理和沉淀大型代码库的结构化上下文，Understand Chat用来查询这份上下文，Codex负责真正的代码分析和修改，而源码与测试仍然是最终事实依据。对于几十个文件的小项目，这套流程未必比直接让 Codex 搜索代码更简单。但当仓库规模越来越大时，把“理解项目”这件事提前沉淀成一份可复用的知识图谱，会让后续 AI Coding 的导航和定位过程更加清晰。
正文之外：
PS 1：如果项目后续更新了很多代码，使用旧 Knowledge Graph 前最好留意其中的 gitCommitHash。本次 Issue 示例中，Codex也确实先检查了图谱 Commit 和当前 HEAD 是否一致，再继续使用知识库。
PS 2：本文这次环境已经具备 Node.js、pnpm、Python 和 Codex，所以没有展开这些工具各自的安装流程。不同服务器初始环境不同，如果缺少某个基础工具，需要先单独完成对应环境配置。
PS 3：UA 的 Knowledge Graph 适合做导航，但不建议把它当成源码的替代品。尤其代码已经变化时，最终实现细节一定以当前真实源码为准。
PS 4：UA还可以生成dashboard方便人去看项目架构、模块关系、节点信息、导览等，本文没有详细展示，大家可以自己尝试一下

最后dashboard界面如图，大家可以参考下