wehub/egonex-ai--understand-anything

Fork 0

Files

T

wehub-resource-sync f99f140950

CI / ci (ubuntu-latest) (push) Has been cancelled

Details

CI / ci (windows-latest) (push) Has been cancelled

Details

docs: make Chinese README the default

2026-07-13 09:43:22 +00:00

19 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Understand Anything

将任何代码库、知识库或文档转化为交互式知识图谱，供你探索、搜索和提问。
兼容 Claude Code、Codex、Cursor、Copilot、Gemini CLI 等工具。

理解一切代码。理解每一个人。
AI 应该帮助人，而不是取代人。

来自 Egonex 的开源项目
原作者 Lum1104。

你刚加入一个新团队。代码库有 20 万行。你该从何入手？

Understand Anything 是一个 Claude Code 插件，它通过多智能体管道分析你的项目，构建包含每个文件、函数、类和依赖关系的知识图谱，然后提供一个交互式仪表盘供你以可视化方式探索。告别盲目阅读代码，开始纵览全局。

目标不是用一个图谱来震撼你，让你惊叹代码库有多复杂——而是用这个图谱悄悄教会你，每一块代码是如何组合在一起的。

✨ 功能特性

Note

想跳过阅读？ 试试我们的在线演示或访问主页——一个完全交互式的仪表盘，你可以在浏览器中平移、缩放、搜索和探索。

探索结构图谱

以交互式知识图谱的形式浏览你的代码库——每个文件、函数和类都是一个可点击、搜索和探索的节点。选中任意节点即可查看通俗易懂的摘要、关系说明和导览。

理解业务逻辑

切换到领域视图，查看你的代码如何映射到真实业务流程——领域、流程和步骤以水平图谱形式呈现。

分析知识库

将 /understand-knowledge 指向一个 Karpathy 风格的 LLM 维基，即可获得带有社区聚类的力导向知识图谱。确定性解析器从 index.md 中提取维基链接和分类，然后 LLM 代理发现隐含关系、提取实体并呈现断言——将你的维基转化为一个可导航的互联思想图谱。

🧭 导览

按依赖顺序自动生成的架构漫游。以正确的顺序学习代码库。

🔍 模糊与语义搜索

按名称或按含义查找任何内容。搜索"哪些部分处理认证？"即可在图谱中得到相关结果。

📊 变更影响分析

在提交之前查看你的改动会影响系统的哪些部分。了解代码库中的连锁影响。

🎭 角色自适应界面

仪表盘根据你的身份自动调整详细程度——初级开发、产品经理还是高级用户。

🏗️ 分层可视化

按架构层自动分组——API、Service、Data、UI、Utility——附带彩色图例。

📚 语言概念

12 种编程模式（泛型、闭包、装饰器等）在出现之处附带上下文解释。

🚀 快速开始

1. 安装插件

/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything

使用本地模型？ 出于隐私或企业环境需求，你可以将平台指向本地模型提供商（如 Ollama），按照其集成指南更换模型提供商。

2. 分析你的代码库

/understand

多智能体管道扫描你的项目，提取每个文件、函数、类和依赖关系，然后构建知识图谱并保存到 .ua/knowledge-graph.json。（已有 .understand-anything/ 目录的项目会继续使用它——它作为数据目录保持不变，因此无需迁移。）

关于 Token 用量的提醒： 初始的 /understand 会分析整个代码库，在大型项目上可能消耗大量 Token。我们建议在 Token 套餐/订阅下运行，或使用本地模型（见上文）进行初始化。后续运行默认是增量的——仅重新分析变更过的文件——因此消耗的 Token 要少得多。

本地化输出： 使用 --language 以你偏好的语言生成内容：

# 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. 探索仪表盘

/understand-dashboard

一个交互式 Web 仪表盘将打开，你的代码库以图（graph）的形式可视化——按架构层用不同颜色编码，支持搜索和点击。选择任意节点即可查看其代码、关联关系以及通俗易懂的英文解释。

4. 持续学习

# 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（原生）

/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：

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）：

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 技能分析此项目）

支持的 <platform> 值：gemini、codex、opencode、pi、openclaw、antigravity、vibe、vscode、hermes、cline、kimi、trae、nanobot、kiro
后续更新：./install.sh --update
卸载：./install.sh --uninstall <platform>

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

copilot plugin install Egonex-AI/Understand-Anything:understand-anything-plugin

Kiro CLI / IDE

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) — Go / Java / Python / Node 参考项目，已提交图。

需要提交的内容： .ua/ 中的所有内容，除了 intermediate/ 和 diff-overlay.json（这些是本地临时文件）。（旧项目使用 .understand-anything/——如果存在该目录，则在下方命令中替换目录名。）

.ua/intermediate/
.ua/diff-overlay.json

保持更新： 启用 /understand --auto-update——这是一个 post-commit 钩子（hook），可增量修补图，确保每次提交都附带匹配的图。或者在发布前手动重新运行 /understand。

大型图（10 MB 以上）： 使用 git-lfs 进行追踪。

git lfs install
git lfs track ".ua/*.json"
git add .gitattributes .ua/

无需 Claude Code 即可查看仪表盘

一旦图已生成并提交，团队中的任何人都可以通过一条命令打开它——无需 Claude Code、无需 LLM、无需 API 密钥。仅需 Node.js（>= 18）：

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——我们很乐意在此展示。

🤝 参与贡献

欢迎贡献！以下是如何开始的步骤：

Fork 本仓库
创建功能分支（git checkout -b feature/my-feature）
运行测试（pnpm --filter @understand-anything/core test）
提交你的更改并创建 Pull Request

对于重大变更，请先提交 Issue 以便我们讨论方案。

别再盲目读代码。开始理解一切。

Star 历史

感谢所有使用和贡献的人——知道这个项目能为他人节省时间，就是它值得构建的原因。

19 KiB Raw Permalink Blame History Unescape Escape