> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/Egonex-AI/Understand-Anything) · [上游 README](https://github.com/Egonex-AI/Understand-Anything/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
Understand Anything
将任何代码库、知识库或文档转化为交互式知识图谱，供你探索、搜索和提问。
兼容 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等工具。
理解一切代码。 理解每一个人。
AI 应该帮助人，而不是取代人。
English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Türkçe | Русский
来自 Egonex 的开源项目
原作者 Lum1104。
---
**你刚加入一个新团队。代码库有 20 万行。你该从何入手？**
Understand Anything 是一个 Claude Code 插件，它通过多智能体管道分析你的项目，构建包含每个文件、函数、类和依赖关系的知识图谱，然后提供一个交互式仪表盘供你以可视化方式探索。告别盲目阅读代码，开始纵览全局。
> **目标不是用一个图谱来震撼你，让你惊叹代码库有多复杂——而是用这个图谱悄悄教会你，每一块代码是如何组合在一起的。**
---
## ✨ 功能特性
> [!NOTE]
> **想跳过阅读？** 试试我们的在线演示或访问主页——一个完全交互式的仪表盘，你可以在浏览器中平移、缩放、搜索和探索。
### 探索结构图谱
以交互式知识图谱的形式浏览你的代码库——每个文件、函数和类都是一个可点击、搜索和探索的节点。选中任意节点即可查看通俗易懂的摘要、关系说明和导览。
### 理解业务逻辑
切换到领域视图，查看你的代码如何映射到真实业务流程——领域、流程和步骤以水平图谱形式呈现。
### 分析知识库
将 `/understand-knowledge` 指向一个 Karpathy 风格的 LLM 维基，即可获得带有社区聚类的力导向知识图谱。确定性解析器从 `index.md` 中提取维基链接和分类，然后 LLM 代理发现隐含关系、提取实体并呈现断言——将你的维基转化为一个可导航的互联思想图谱。
🧭 导览
按依赖顺序自动生成的架构漫游。以正确的顺序学习代码库。
|
🔍 模糊与语义搜索
按名称或按含义查找任何内容。搜索"哪些部分处理认证？"即可在图谱中得到相关结果。
|
📊 变更影响分析
在提交之前查看你的改动会影响系统的哪些部分。了解代码库中的连锁影响。
|
🎭 角色自适应界面
仪表盘根据你的身份自动调整详细程度——初级开发、产品经理还是高级用户。
|
🏗️ 分层可视化
按架构层自动分组——API、Service、Data、UI、Utility——附带彩色图例。
|
📚 语言概念
12 种编程模式（泛型、闭包、装饰器等）在出现之处附带上下文解释。
|
---
## 🚀 快速开始
### 1. 安装插件
```bash
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
```
> **使用本地模型？** 出于隐私或企业环境需求，你可以将平台指向本地模型提供商（如 Ollama），按照其集成指南更换模型提供商。
### 2. 分析你的代码库
```bash
/understand
```
多智能体管道扫描你的项目，提取每个文件、函数、类和依赖关系，然后构建知识图谱并保存到 `.ua/knowledge-graph.json`。（已有 `.understand-anything/` 目录的项目会继续使用它——它作为数据目录保持不变，因此无需迁移。）
> **关于 Token 用量的提醒：** 初始的 `/understand` 会分析整个代码库，在大型项目上可能消耗大量 Token。我们建议在 Token 套餐/订阅下运行，或使用本地模型（见上文）进行初始化。后续运行默认是增量的——仅重新分析变更过的文件——因此消耗的 Token 要少得多。
**本地化输出：** 使用 `--language` 以你偏好的语言生成内容：
```bash
# Generate Chinese content (知识图节点描述和 Dashboard UI)
/understand --language zh
# Supported languages: en (default), zh, zh-TW, ja, ko, ru
```
在项目的**首次运行**时——如果你没有传入 `--language` 且尚未存储语言——`/understand` 会检测你当前使用的语言。如果不是英语，它会请求你确认（或覆盖）后再生成；英语对话不受影响。你的选择会保存到 `.ua/config.json`，并在后续每次运行中复用。
`--language` 参数影响：
- 知识图谱中的节点摘要和描述
- 仪表盘 UI 标签、按钮和工具提示
- 导览解释
### 3. 探索仪表盘
```bash
/understand-dashboard
```
一个交互式 Web 仪表盘将打开，你的代码库以图（graph）的形式可视化——按架构层用不同颜色编码，支持搜索和点击。选择任意节点即可查看其代码、关联关系以及通俗易懂的英文解释。
### 4. 持续学习
```bash
# Ask anything about the codebase
/understand-chat How does the payment flow work?
# Analyze impact of your current changes
/understand-diff
# Deep-dive into a specific file or function
/understand-explain src/auth/login.ts
# Generate an onboarding guide for new team members
/understand-onboard
# Extract business domain knowledge (domains, flows, steps)
/understand-domain
# Analyze a Karpathy-pattern LLM wiki knowledge base
/understand-knowledge ~/path/to/wiki
# Re-run anytime — incremental by default (only re-analyzes changed files)
/understand
# Auto-update on every commit via a post-commit hook
/understand --auto-update
# Scope to a subdirectory (for huge monorepos)
/understand src/frontend
```
---
## 🌐 多平台安装
Understand-Anything 支持跨多个 AI 编程平台使用。
### Claude Code（原生）
```bash
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
```
### 一行安装（Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI / Trae / Nanobot / Kiro）
**macOS / Linux：**
```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash
# or skip the prompt by passing the platform:
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
```
**Windows（PowerShell）：**
```powershell
iwr -useb https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.ps1 | iex
```
安装程序会将仓库克隆到 `~/.understand-anything/repo`，并为所选平台创建正确的符号链接。之后请重启你的 CLI/IDE。
> **关于调用技能（skills）的说明：** 调用前缀因平台而异。大多数平台使用斜杠命令（`/understand`），但 **Codex 改用 `$`**——输入 `$understand`，而非 `/understand`。如果你的平台两种前缀都不识别，直接用自然语言询问即可：*"Use the understand skill to analyze this project."（使用 understand 技能分析此项目）*
- 支持的 `` 值：`gemini`、`codex`、`opencode`、`pi`、`openclaw`、`antigravity`、`vibe`、`vscode`、`hermes`、`cline`、`kimi`、`trae`、`nanobot`、`kiro`
- 后续更新：`./install.sh --update`
- 卸载：`./install.sh --uninstall `
### Cursor
当此仓库被克隆后，Cursor 会通过 `.cursor-plugin/plugin.json` 自动发现插件。无需手动安装——只需克隆并在 Cursor 中打开即可。
如果自动发现未生效，请手动安装：打开 **Cursor 设置 → 插件（Plugins）**，将 `https://github.com/Egonex-AI/Understand-Anything` 粘贴到搜索框中，然后从那里添加。
### VS Code + GitHub Copilot
当此仓库被克隆后，VS Code 配合 GitHub Copilot（v1.108+）会通过 `.copilot-plugin/plugin.json` 自动发现插件。无需手动安装——只需克隆并在 VS Code 中打开即可。
如需个人技能（personal skills，在所有项目中可用），请使用 `vscode` 平台运行上述 `install.sh`。
### Copilot CLI
```bash
copilot plugin install Egonex-AI/Understand-Anything:understand-anything-plugin
```
### Kiro CLI / IDE
```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s kiro
```
安装后：
- **Kiro CLI**：`kiro-cli chat --agent understand "Analyze this project"`
- **Kiro IDE**：技能通过符号链接到 `~/.kiro/skills/`，且 `understand` 代理（agent）被写入 `~/.kiro/agents/understand.json`，因此重启 IDE 后两者均可用。
如需个人技能（personal skills，在所有项目中可用），请使用 `kiro` 平台运行上述 `install.sh`。
### 平台兼容性
| 平台 | 状态 | 安装方式 |
|----------|--------|----------------|
| Claude Code | ✅ 原生 | 插件市场 |
| Cursor | ✅ 支持 | 自动发现 |
| VS Code + GitHub Copilot | ✅ 支持 | 自动发现 |
| Copilot CLI | ✅ 支持 | 插件安装 |
| Codex | ✅ 支持 | `install.sh codex` |
| OpenCode | ✅ 支持 | `install.sh opencode` |
| OpenClaw | ✅ 支持 | `install.sh openclaw` |
| Antigravity | ✅ 支持 | `install.sh antigravity` |
| Gemini CLI | ✅ 支持 | `install.sh gemini` |
| Pi Agent | ✅ 支持 | `install.sh pi` |
| Vibe CLI | ✅ 支持 | `install.sh vibe` |
| Hermes | ✅ 支持 | `install.sh hermes` |
| Cline | ✅ 支持 | `install.sh cline` |
| KIMI CLI | ✅ 支持 | `install.sh kimi` |
| Trae | ✅ 支持 | `install.sh trae` |
| Nanobot | ✅ 支持 | `install.sh nanobot` |
| Kiro CLI / IDE | ✅ 支持 | `install.sh kiro` |
---
## 📦 与团队共享图（Graph）
图就是 JSON——**提交一次，团队成员即可跳过流水线（pipeline）**。适用于新人入职（onboarding）、PR 审查以及文档即代码（docs-as-code）等场景。
> **示例：** [GoogleCloudPlatform/microservices-demo](https://github.com/GoogleCloudPlatform/microservices-demo)) — Go / Java / Python / Node 参考项目，已提交图。
**需要提交的内容：** `.ua/` 中的所有内容，*除了* `intermediate/` 和 `diff-overlay.json`（这些是本地临时文件）。（旧项目使用 `.understand-anything/`——如果存在该目录，则在下方命令中替换目录名。）
```gitignore
.ua/intermediate/
.ua/diff-overlay.json
```
**保持更新：** 启用 `/understand --auto-update`——这是一个 post-commit 钩子（hook），可增量修补图，确保每次提交都附带匹配的图。或者在发布前手动重新运行 `/understand`。
**大型图（10 MB 以上）：** 使用 **git-lfs** 进行追踪。
```bash
git lfs install
git lfs track ".ua/*.json"
git add .gitattributes .ua/
```
### 无需 Claude Code 即可查看仪表盘
一旦图已生成并提交，团队中的任何人都可以通过一条命令打开它——无需 Claude Code、无需 LLM、无需 API 密钥。仅需 Node.js（>= 18）：
```bash
npx https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz /path/to/analyzed/project
```
终端会打印一个带 token 的 URL（`http://127.0.0.1:5173/?token=…`），并在浏览器中打开完整的交互式仪表盘。项目目录（默认：当前目录）必须包含已提交的数据目录（`.ua/`，或旧版 `.understand-anything/`）。所有内容均以只读方式从本地磁盘提供服务——不调用 LLM，数据不会离开你的机器。
如果是从克隆副本（clone）操作？先 `pnpm install && pnpm --filter @understand-anything/core build`，然后 `GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard` 即可通过 Vite 开发服务器实现相同效果。
---
## 🔧 底层原理
### Tree-sitter + LLM 混合方案
静态分析与 LLM 各司其职：
- **Tree-sitter（确定性）**——将源码解析为具体语法树（concrete syntax tree），并提取结构化事实：导入（imports）、导出（exports）、函数/类定义、调用点、继承关系。在扫描阶段预解析为 `importMap`，并传递给文件分析器，使其无需从源码重新推导导入关系。相同输入 → 相同输出，每次运行结果一致。同时还支持基于指纹的变更检测，用于增量更新。
- **LLM（语义）**——读取解析后的结构以及原始源码，产出解析器无法完成的内容：通俗英文摘要、标签、架构层分配、业务领域映射、导览指南（guided tours）、语言概念标注。
正是这种分工，使得图在结构层面可复现（相同代码始终产生相同边），同时在语义层面捕捉意图（一个文件*用于什么*，而不仅仅是它导入了什么）。
### 多代理流水线（Multi-Agent Pipeline）
`/understand` 命令协调 5 个专用代理（agent），而 `/understand-domain` 会额外添加第 6 个：
| 代理（Agent） | 职责 |
|-------|------|
| `project-scanner` | 发现文件，检测语言和框架 |
| `file-analyzer` | 提取函数、类、导入；生成图节点和边 |
| `architecture-analyzer` | 识别架构层 |
| `tour-builder` | 生成导览学习路径 |
| `graph-reviewer` | 验证图的完整性和引用完整性（默认内联运行；使用 `--review` 进行完整 LLM 审查） |
| `domain-analyzer` | 提取业务领域、流程和处理步骤（由 `/understand-domain` 使用） |
| `article-analyzer` | 从 wiki 文章中提取实体、声明和隐式关系（由 `/understand-knowledge` 使用） |
文件分析器可以并行运行（最多 5 个并发，每批 20–30 个文件）。支持增量更新——只重新分析自上次运行以来发生变化的文件。
---
## 🎥 社区内容
由 **Better Stack** 制作的社区演示视频。
在 YouTube 上观看 →
如果你制作了视频、博客文章或教程，欢迎提交 Issue 或 PR——我们很乐意在此展示。
---
## 🤝 参与贡献
欢迎贡献！以下是如何开始的步骤：
1. Fork 本仓库
2. 创建功能分支（`git checkout -b feature/my-feature`）
3. 运行测试（`pnpm --filter @understand-anything/core test`）
4. 提交你的更改并创建 Pull Request
对于重大变更，请先提交 Issue 以便我们讨论方案。
---
别再盲目读代码。开始理解一切。
## Star 历史
感谢所有使用和贡献的人——知道这个项目能为他人节省时间，就是它值得构建的原因。
MIT 许可证 © Yuxiang Lin 和 Infinite Universe, Inc.