346 lines
22 KiB
Markdown
346 lines
22 KiB
Markdown
<h1 align="center">Understand Anything</h1>
|
||
|
||
<p align="center">
|
||
<strong>Превращай любую кодовую базу, базу знаний или документацию в интерактивный граф знаний, который можно исследовать, искать в нём и задавать вопросы.</strong>
|
||
<br />
|
||
<em>Работает с Claude Code, Codex, Cursor, Copilot, Gemini CLI и другими.</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="https://trendshift.io/repositories/23482" target="_blank"><img src="https://trendshift.io/api/badge/repositories/23482" alt="Lum1104%2FUnderstand-Anything | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="../README.md">English</a> | <a href="README.zh-CN.md">简体中文</a> | <a href="README.zh-TW.md">繁體中文</a> | <a href="README.ja-JP.md">日本語</a> | <a href="README.ko-KR.md">한국어</a> | <a href="README.es-ES.md">Español</a> | <a href="README.tr-TR.md">Türkçe</a> | <a href="README.ru-RU.md">Русский</a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#-быстрый-старт"><img src="https://img.shields.io/badge/Быстрый_старт-blue" alt="Quick Start" /></a>
|
||
<a href="https://github.com/Lum1104/Understand-Anything/blob/main/LICENSE"><img src="https://img.shields.io/badge/Лицензия-MIT-yellow" alt="License: MIT" /></a>
|
||
<a href="https://docs.anthropic.com/en/docs/claude-code"><img src="https://img.shields.io/badge/Claude_Code-8A2BE2" alt="Claude Code" /></a>
|
||
<a href="#codex"><img src="https://img.shields.io/badge/Codex-000000" alt="Codex" /></a>
|
||
<a href="#vs-code--github-copilot"><img src="https://img.shields.io/badge/Copilot-24292e" alt="Copilot" /></a>
|
||
<a href="#copilot-cli"><img src="https://img.shields.io/badge/Copilot_CLI-24292e" alt="Copilot CLI" /></a>
|
||
<a href="#gemini-cli"><img src="https://img.shields.io/badge/Gemini_CLI-4285F4" alt="Gemini CLI" /></a>
|
||
<a href="#opencode"><img src="https://img.shields.io/badge/OpenCode-38bdf8" alt="OpenCode" /></a>
|
||
<a href="https://understand-anything.com"><img src="https://img.shields.io/badge/Сайт-d4a574" alt="Homepage" /></a>
|
||
<a href="https://understand-anything.com/demo/"><img src="https://img.shields.io/badge/Демо-00c853" alt="Live Demo" /></a>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="../assets/hero.png" alt="Understand Anything — Превратите любую кодовую базу в интерактивный граф знаний" width="800" />
|
||
</p>
|
||
|
||
<p align="center">
|
||
<strong>💬 <a href="https://discord.gg/pydat66RY">Присоединяйтесь к сообществу в Discord →</a></strong>
|
||
<br />
|
||
<em>Задавайте вопросы, делитесь тем, что вы построили, получайте помощь от сообщества.</em>
|
||
</p>
|
||
|
||
---
|
||
|
||
**Вы только что присоединились к новой команде. Кодовая база — 200 000 строк. С чего вообще начинать?**
|
||
|
||
Understand Anything — это [плагин для Claude Code](https://code.claude.com/docs/en/plugins-reference#plugins-reference), который анализирует ваш проект с помощью мультиагентного пайплайна, строит граф знаний из всех файлов, функций, классов и зависимостей, а затем предоставляет интерактивную панель, чтобы исследовать всё это визуально. Хватит читать код вслепую. Пора увидеть общую картину.
|
||
|
||
> **Цель — не граф, который поражает сложностью вашей кодовой базы, а граф, который ненавязчиво объясняет, как все части складываются вместе.**
|
||
|
||
---
|
||
|
||
## ✨ Возможности
|
||
|
||
> [!NOTE]
|
||
> **Хотите пропустить чтение?** Попробуйте [живое демо](https://understand-anything.com/demo/) на нашем [сайте](https://understand-anything.com/) — полностью интерактивная панель, по которой можно перемещаться, масштабировать, искать и исследовать прямо в браузере.
|
||
|
||
### Исследуйте структурный граф
|
||
|
||
Перемещайтесь по своему коду как по интерактивному графу знаний — каждый файл, функция и класс является узлом, который можно кликнуть, найти и изучить. Выберите любой узел, чтобы увидеть понятные описания, связи и пошаговые обзоры.
|
||
|
||
### Понимайте бизнес-логику
|
||
|
||
Переключитесь на доменное представление и увидите, как ваш код отображается на реальные бизнес-процессы — домены, потоки и шаги, выстроенные в виде горизонтального графа.
|
||
|
||
### Анализируйте базы знаний
|
||
|
||
Направьте `/understand-knowledge` на [LLM-вики в стиле Карпати](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) и получите force-directed граф знаний с кластеризацией по сообществам. Детерминированный парсер извлекает wikilinks и категории из `index.md`, а LLM-агенты находят неявные связи, извлекают сущности и выявляют утверждения — превращая вашу вики в навигируемый граф взаимосвязанных идей.
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
<h3>🧭 Пошаговые обзоры</h3>
|
||
<p>Автоматически создаваемые экскурсии по архитектуре, упорядоченные по зависимостям. Изучайте кодовую базу в правильном порядке.</p>
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
<h3>🔍 Нечёткий и семантический поиск</h3>
|
||
<p>Находите что угодно по имени или по смыслу. Поищите «какие части отвечают за авторизацию?» и получите релевантные результаты по всему графу.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
<h3>📊 Анализ влияния изменений</h3>
|
||
<p>Смотрите, какие части системы затрагивают ваши изменения, ещё до коммита. Понимайте каскадные эффекты по всей кодовой базе.</p>
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
<h3>🎭 UI, адаптирующийся к роли</h3>
|
||
<p>Панель подстраивает уровень детализации под пользователя — junior-разработчика, PM или продвинутого пользователя.</p>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%" valign="top">
|
||
<h3>🏗️ Визуализация слоёв</h3>
|
||
<p>Автоматическая группировка по архитектурным слоям — API, Service, Data, UI, Utility — с цветовой легендой.</p>
|
||
</td>
|
||
<td width="50%" valign="top">
|
||
<h3>📚 Концепции языка</h3>
|
||
<p>12 шаблонов программирования (дженерики, замыкания, декораторы и т.д.) объясняются в контексте там, где они встречаются.</p>
|
||
</td>
|
||
</tr>
|
||
</table>
|
||
|
||
---
|
||
|
||
## 🚀 Быстрый старт
|
||
|
||
### 1. Установите плагин
|
||
|
||
```bash
|
||
/plugin marketplace add Lum1104/Understand-Anything
|
||
/plugin install understand-anything
|
||
```
|
||
|
||
### 2. Проанализируйте кодовую базу
|
||
|
||
```bash
|
||
/understand
|
||
```
|
||
|
||
Мультиагентный пайплайн сканирует ваш проект, извлекает каждый файл, функцию, класс и зависимость, а затем строит граф знаний и сохраняет его в `.understand-anything/knowledge-graph.json`.
|
||
|
||
**Локализованный вывод:** используйте `--language`, чтобы генерировать контент на нужном языке:
|
||
|
||
```bash
|
||
# Генерация контента на русском (описания узлов графа знаний и UI панели)
|
||
/understand --language ru
|
||
|
||
# Поддерживаемые языки: en (по умолчанию), zh, zh-TW, ja, ko, ru
|
||
```
|
||
|
||
Параметр `--language` влияет на:
|
||
- Резюме и описания узлов в графе знаний
|
||
- Подписи, кнопки и подсказки UI панели
|
||
- Объяснения в пошаговых обзорах
|
||
|
||
### 3. Откройте панель
|
||
|
||
```bash
|
||
/understand-dashboard
|
||
```
|
||
|
||
Открывается интерактивная веб-панель с визуализацией вашей кодовой базы в виде графа — с цветовой кодировкой по архитектурным слоям, поиском и кликабельными узлами. Выберите любой узел, чтобы увидеть его код, связи и описание простым языком.
|
||
|
||
### 4. Продолжайте учиться
|
||
|
||
```bash
|
||
# Задайте любой вопрос о кодовой базе
|
||
/understand-chat How does the payment flow work?
|
||
|
||
# Проанализируйте влияние ваших текущих изменений
|
||
/understand-diff
|
||
|
||
# Подробно разберитесь с конкретным файлом или функцией
|
||
/understand-explain src/auth/login.ts
|
||
|
||
# Сгенерируйте онбординг-гайд для новых членов команды
|
||
/understand-onboard
|
||
|
||
# Извлеките знания о бизнес-доменах (домены, потоки, шаги)
|
||
/understand-domain
|
||
|
||
# Проанализируйте LLM-вики в стиле Карпати
|
||
/understand-knowledge ~/path/to/wiki
|
||
|
||
# Перезапускайте когда угодно — по умолчанию инкрементально (только изменённые файлы)
|
||
/understand
|
||
|
||
# Установите post-commit хук для автоматических инкрементальных обновлений
|
||
/understand --auto-update
|
||
|
||
# Огромный монорепозиторий? Ограничьте анализ подкаталогом
|
||
/understand src/frontend
|
||
```
|
||
|
||
---
|
||
|
||
## 🌐 Установка на разных платформах
|
||
|
||
Understand-Anything работает с несколькими платформами AI-разработки.
|
||
|
||
### Claude Code (нативно)
|
||
|
||
```bash
|
||
/plugin marketplace add Lum1104/Understand-Anything
|
||
/plugin install understand-anything
|
||
```
|
||
|
||
### Установка одной командой (Codex / OpenCode / OpenClaw / Antigravity / Gemini CLI / Pi Agent / Vibe CLI / VS Code Copilot / Hermes / Cline / KIMI CLI)
|
||
|
||
**macOS / Linux:**
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash
|
||
# или передайте платформу, чтобы пропустить интерактивный выбор:
|
||
curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash -s codex
|
||
```
|
||
|
||
**Windows (PowerShell):**
|
||
```powershell
|
||
iwr -useb https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.ps1 | iex
|
||
```
|
||
|
||
Установщик клонирует репозиторий в `~/.understand-anything/repo` и создаёт нужные симлинки для выбранной платформы. После установки перезапустите свой CLI/IDE.
|
||
|
||
- Поддерживаемые значения `<platform>`: `gemini`, `codex`, `opencode`, `pi`, `openclaw`, `antigravity`, `vibe`, `vscode`, `hermes`, `cline`, `kimi`
|
||
- Обновление: `./install.sh --update`
|
||
- Удаление: `./install.sh --uninstall <platform>`
|
||
|
||
### Cursor
|
||
|
||
Cursor автоматически обнаруживает плагин через `.cursor-plugin/plugin.json` при клонировании этого репозитория. Ручная установка не требуется — просто склонируйте и откройте в Cursor.
|
||
|
||
Если автообнаружение не сработало, установите вручную: откройте **Cursor Settings → Plugins**, вставьте `https://github.com/Lum1104/Understand-Anything` в поле поиска и добавьте оттуда.
|
||
|
||
### VS Code + GitHub Copilot
|
||
|
||
VS Code с GitHub Copilot (v1.108+) автоматически обнаруживает плагин через `.copilot-plugin/plugin.json` при клонировании этого репозитория. Ручная установка не требуется — просто склонируйте и откройте в VS Code.
|
||
|
||
Для персональных skills (доступных во всех проектах) запустите `install.sh` выше с платформой `vscode`.
|
||
|
||
### Copilot CLI
|
||
|
||
```bash
|
||
copilot plugin install Lum1104/Understand-Anything:understand-anything-plugin
|
||
```
|
||
|
||
### Совместимость с платформами
|
||
|
||
| Платформа | Статус | Способ установки |
|
||
|----------|--------|----------------|
|
||
| Claude Code | ✅ Нативно | Marketplace плагинов |
|
||
| 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` |
|
||
|
||
---
|
||
|
||
## 📦 Поделитесь графом с командой
|
||
|
||
Граф — это просто JSON. **Зафиксируйте его один раз, и коллеги смогут пропустить весь пайплайн.** Полезно для онбординга, ревью PR и подхода docs-as-code.
|
||
|
||
> **Пример:** [GoogleCloudPlatform/microservices-demo (форк)](https://github.com/Lum1104/microservices-demo) — мультиязыковой проект (Go / Java / Python / Node) с уже зафиксированным графом.
|
||
|
||
**Что коммитить:** всё содержимое `.understand-anything/`, *кроме* `intermediate/` и `diff-overlay.json` (это локальные временные файлы).
|
||
|
||
```gitignore
|
||
.understand-anything/intermediate/
|
||
.understand-anything/diff-overlay.json
|
||
```
|
||
|
||
**Держите граф в актуальном состоянии:** включите `/understand --auto-update` — post-commit хук будет инкрементально обновлять граф, так что каждый коммит сопровождается соответствующим графом. Либо запускайте `/understand` вручную перед релизами.
|
||
|
||
**Большие графы (10 МБ+):** храните через **git-lfs**.
|
||
|
||
```bash
|
||
git lfs install
|
||
git lfs track ".understand-anything/*.json"
|
||
git add .gitattributes .understand-anything/
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 Под капотом
|
||
|
||
### Гибрид Tree-sitter + LLM
|
||
|
||
Детерминированную работу делает статический анализ, семантическое понимание — LLM:
|
||
|
||
- **Tree-sitter (детерминированно)** — парсит исходный код в конкретное синтаксическое дерево и извлекает структурные факты: import'ы, export'ы, определения функций/классов, точки вызова, наследование. На фазе сканирования заранее разрешается в `importMap` и передаётся file-analyzer'ам, чтобы они не выводили import'ы из исходника заново. Одинаковый ввод всегда даёт одинаковый вывод; это же лежит в основе fingerprint'ов для инкрементальных обновлений.
|
||
- **LLM (семантически)** — читает разобранную структуру вместе с исходным текстом и производит то, что не способны парсеры: понятные человеку резюме, теги, назначение архитектурных слоёв, отображение бизнес-доменов, ведомые туры, заметки о концепциях языка.
|
||
|
||
Именно благодаря этому разделению граф воспроизводим со стороны структуры (один и тот же код всегда даёт одни и те же рёбра) и одновременно улавливает намерение со стороны семантики (для *чего* существует файл, а не только что он импортирует).
|
||
|
||
### Мультиагентный пайплайн
|
||
|
||
Команда `/understand` оркестрирует 5 специализированных агентов, а `/understand-domain` добавляет шестого:
|
||
|
||
| Агент | Роль |
|
||
|-------|------|
|
||
| `project-scanner` | Обнаружение файлов, определение языков и фреймворков |
|
||
| `file-analyzer` | Извлечение функций, классов, импортов; создание узлов и рёбер графа |
|
||
| `architecture-analyzer` | Определение архитектурных слоёв |
|
||
| `tour-builder` | Генерация пошаговых обучающих обзоров |
|
||
| `graph-reviewer` | Проверка полноты и целостности ссылок графа (по умолчанию выполняется inline; используйте `--review` для полного ревью с участием LLM) |
|
||
| `domain-analyzer` | Извлечение бизнес-доменов, потоков и шагов процессов (используется командой `/understand-domain`) |
|
||
| `article-analyzer` | Извлечение сущностей, утверждений и неявных связей из статей вики (используется командой `/understand-knowledge`) |
|
||
|
||
Анализаторы файлов работают параллельно (до 5 одновременно, 20–30 файлов на батч). Поддерживаются инкрементальные обновления — повторно анализируются только файлы, изменившиеся с прошлого запуска.
|
||
|
||
---
|
||
|
||
## 🎥 Сообщество
|
||
|
||
Обзорное видео от сообщества, созданное **Better Stack**.
|
||
|
||
<p align="center">
|
||
<a href="https://www.youtube.com/watch?v=VmIUXVlt7_I"><img src="https://img.youtube.com/vi/VmIUXVlt7_I/maxresdefault.jpg" alt="Обзорное видео от сообщества Better Stack — нажмите, чтобы посмотреть на YouTube" width="480" /></a>
|
||
<br />
|
||
<em><a href="https://www.youtube.com/watch?v=VmIUXVlt7_I">Смотреть на YouTube →</a></em>
|
||
</p>
|
||
|
||
Сделали видео, статью или руководство? Откройте issue или PR — с удовольствием добавим сюда.
|
||
|
||
---
|
||
|
||
## 🤝 Вклад в проект
|
||
|
||
Будем рады вашим контрибьюшенам! Как начать:
|
||
|
||
1. Сделайте форк репозитория
|
||
2. Создайте ветку для фичи (`git checkout -b feature/my-feature`)
|
||
3. Запустите тесты (`pnpm --filter @understand-anything/core test`)
|
||
4. Закоммитьте изменения и откройте pull request
|
||
|
||
Для крупных изменений сначала откройте issue, чтобы можно было обсудить подход.
|
||
|
||
---
|
||
|
||
<p align="center">
|
||
<strong>Хватит читать код вслепую. Начните понимать всё.</strong>
|
||
</p>
|
||
|
||
## История звёзд
|
||
|
||
<a href="https://www.star-history.com/?repos=Lum1104%2FUnderstand-Anything&type=date&legend=top-left">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&theme=dark&legend=top-left" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&legend=top-left" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/image?repos=Lum1104/Understand-Anything&type=date&legend=top-left" />
|
||
</picture>
|
||
</a>
|
||
|
||
<p align="center">
|
||
<em>Спасибо всем, кто пользовался проектом и вкладывался в него — знание того, что это экономит людям время, и было главной причиной, ради которой стоило его делать.</em>
|
||
</p>
|
||
|
||
<p align="center">
|
||
Лицензия MIT © <a href="https://github.com/Lum1104">Lum1104</a>
|
||
</p>
|