wehub/lum1104--understand-anything

Fork 0

Files

T

wehub-resource-sync b3fc95c601

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:39:33 +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 Wiki)，即可获得带有社区聚类的力导向知识图谱。确定性解析器从 index.md 中提取维基链接和分类，然后 LLM 智能体发现隐式关系、提取实体并梳理出论断——将你的 Wiki 转化为一个可导航的互联思想图谱。

🧭 引导式导览

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

🔍 模糊与语义搜索

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

📊 差异影响分析

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

🎭 角色自适应界面

仪表盘根据你的身份调整细节级别——初级开发者、PM 还是高级用户。

🏗️ 分层可视化

按架构层自动分组——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/ 目录的项目会继续使用它——它会作为数据目录保留，因此无需迁移。）

注意令牌消耗： 首次运行 /understand 会分析整个代码库，在大型项目上可能消耗大量令牌。建议在令牌套餐/订阅计划下运行，或使用本地模型（见上文）进行初始化。后续运行默认是增量式的——仅重新分析已更改的文件——因此消耗的令牌要少得多。

本地化输出： 使用 --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）的形式可视化你的代码库——按架构层级（architectural layer）颜色编码，支持搜索和点击。选中任意节点即可查看其代码、关联关系以及简明英文解释。

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."

支持的 <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 设置 → 插件，将 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 代理已写入 ~/.kiro/agents/understand.json，因此重启 IDE 后两者即可使用。

如需个人技能（跨所有项目可用），请使用 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`

📦 与团队共享图谱

图谱本质就是 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 钩子，会增量修补图谱，确保每次提交都附带匹配的图谱。或者在发布前手动重新运行 /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

终端会打印一个带令牌的 URL（http://127.0.0.1:5173/?token=…），并在浏览器中打开完整的交互式仪表盘。项目目录（默认：当前目录）必须包含已提交的数据目录（.ua/，或旧版的 .understand-anything/）。所有内容均从本地磁盘只读提供——不涉及 LLM 调用，数据不会离开你的机器。

改用克隆的仓库？先 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）、函数/类定义、调用点（call sites）、继承关系。在扫描阶段预解析为 importMap，并传递给文件分析器（file-analyzers），使其无需从源码重新推导导入关系。相同输入 → 相同输出，每次运行结果一致。同时支持基于指纹的变更检测，用于增量更新。
LLM（语义分析） —— 读取解析后的结构及原始源码，产出解析器无法提供的内容：简明英文摘要、标签、架构层级分配、业务领域映射、引导式导览（guided tours）、语言概念标注。

这种分工使得图谱在结构层面可复现（相同代码始终产生相同的边），同时在语义层面捕捉意图（文件的用途，而不仅仅是它导入了什么）。

多智能体流水线（Multi-Agent Pipeline）

/understand 命令编排了 5 个专用智能体，/understand-domain 则额外添加第 6 个：

智能体	职责
`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