273 lines
16 KiB
Markdown
273 lines
16 KiB
Markdown
# CodeBoarding Integration Idea
|
||
|
||
Дата проверки: 2026-05-03.
|
||
|
||
## Короткий вывод
|
||
|
||
CodeBoarding полезен для Agent Teams как опциональная визуализация архитектурного влияния агентских изменений. Он не выглядит как готовый embeddable real-time daemon для нашего Electron UI, но у него есть достаточная база для near real-time режима:
|
||
|
||
- baseline анализ через `codeboarding full --local <project>`;
|
||
- incremental анализ через `codeboarding incremental --local <project>`;
|
||
- partial обновление компонента через `codeboarding partial --local <project> --component-id <id>`;
|
||
- выходные артефакты в `.codeboarding/`, включая `analysis.json`, Markdown и Mermaid;
|
||
- method/component change tracking в VS Code extension.
|
||
|
||
Практичный продуктовый вариант: делаем CodeBoarding optional dependency, даём пользователю install/detect/setup в UI, запускаем full один раз, а дальше показываем live-ish overlay по изменениям агентов. Быструю подсветку делаем сами по git diff/task change ledger, а CodeBoarding incremental используем как более точный фоновый refresh.
|
||
|
||
## Что проверено
|
||
|
||
- GitHub repo: [CodeBoarding/CodeBoarding](https://github.com/CodeBoarding/CodeBoarding)
|
||
- Website: [codeboarding.org](https://www.codeboarding.org/)
|
||
- PyPI JSON: [pypi.org/pypi/codeboarding/json](https://pypi.org/pypi/codeboarding/json)
|
||
- Release: [v0.11.0](https://github.com/CodeBoarding/CodeBoarding/releases/tag/v0.11.0)
|
||
- VS Code Marketplace: [CodeBoarding extension](https://marketplace.visualstudio.com/items?itemName=Codeboarding.codeboarding)
|
||
- MCP repo: [CodeBoarding/CodeBoarding-MCP](https://github.com/CodeBoarding/CodeBoarding-MCP)
|
||
|
||
На момент проверки:
|
||
|
||
- Latest GitHub release: `v0.11.0`, published 2026-04-29.
|
||
- Latest PyPI version: `0.11.0`, requires Python `>=3.12,<3.14`.
|
||
- License: MIT.
|
||
- Repo активный: последний push был 2026-05-03.
|
||
- Основной стек CodeBoarding: Python CLI, static analysis, LSP, tree-sitter, LLM providers.
|
||
- Поддерживаемые языки из README/PyPI: Python, TypeScript, JavaScript, Java, Go, PHP, Rust, C#.
|
||
- LLM providers из README/PyPI: OpenAI, Anthropic, Google, Vercel AI Gateway, AWS Bedrock, Ollama, OpenRouter и другие.
|
||
|
||
## Что CodeBoarding умеет
|
||
|
||
Из README и CLI:
|
||
|
||
- генерирует high-level architecture diagrams;
|
||
- генерирует deeper component diagrams;
|
||
- пишет Markdown документацию в `.codeboarding/`;
|
||
- пишет Mermaid output, который удобно показывать в нашем Markdown/Mermaid viewer;
|
||
- умеет incremental updates, когда есть предыдущий analysis;
|
||
- умеет partial update одного component id;
|
||
- для private repos использует `GITHUB_TOKEN`;
|
||
- конфиг LLM ключей хранит в `~/.codeboarding/config.toml`, но env vars имеют приоритет.
|
||
|
||
Публичные команды CLI:
|
||
|
||
```bash
|
||
codeboarding full --local /path/to/repo
|
||
codeboarding incremental --local /path/to/repo
|
||
codeboarding partial --local /path/to/repo --component-id "1.2"
|
||
```
|
||
|
||
Установка из README/PyPI:
|
||
|
||
```bash
|
||
pipx install codeboarding --python python3.12
|
||
codeboarding-setup
|
||
codeboarding full --local /path/to/repo
|
||
```
|
||
|
||
Важно: `codeboarding-setup` скачивает language server binaries в `~/.codeboarding/servers/`. Node.js/npm нужен для Python, TypeScript, JavaScript и PHP language servers; если Node/npm не найден, CodeBoarding может скачать pinned Node runtime в `~/.codeboarding/servers/nodeenv/`.
|
||
|
||
## Real-time оценка
|
||
|
||
В VS Code Marketplace заявлено:
|
||
|
||
- `Realtime Component Change tracking` - можно видеть, в каких компонентах есть file edits.
|
||
- `0.11.0` - Git Commit Diff View, timeline slider, подсветка components/files/methods по recent commits.
|
||
- `0.11.0` - Faster Incremental Analysis, refresh переиспользует прошлые результаты и анализирует только затронутое.
|
||
- `0.10.0` - Method-Level Change Tracking.
|
||
- `0.10.0` - Real-time Method Updates.
|
||
- `0.10.2` - Smoother Real-time Updates.
|
||
|
||
Но в open-source CLI я не нашёл отдельного публичного `watch`/daemon режима. В коде есть incremental pipeline, worktree diff, `incrementalDelta`, method-level statuses, comments про IDE/wrapper integration и snapshot target refs, но публичный CLI остаётся командным.
|
||
|
||
Вывод: CodeBoarding позволяет сделать near real-time визуализацию, но real-time orchestration надо делать нам:
|
||
|
||
1. watcher ловит изменения файлов от агента;
|
||
2. debounce, например 2-10 секунд;
|
||
3. быстрый overlay строится по git diff/task change ledger и текущему `.codeboarding/analysis.json`;
|
||
4. CodeBoarding incremental запускается фоном реже или на завершение task;
|
||
5. UI обновляет Mermaid/architecture map и affected components.
|
||
|
||
## Что можно показать пользователю
|
||
|
||
Хорошо подходит:
|
||
|
||
- 🟢 новый файл попал в конкретный компонент;
|
||
- 🟡 метод или файл изменён внутри компонента;
|
||
- 🔴 файл/метод удалён;
|
||
- какие компоненты трогает конкретный агент;
|
||
- какие компоненты трогает конкретная task;
|
||
- архитектурный контекст рядом с code review;
|
||
- diff timeline по commits или task snapshots;
|
||
- Markdown/Mermaid docs прямо в нашем Project Editor/Review UI.
|
||
|
||
Сложно или рискованно:
|
||
|
||
- мгновенная перестройка диаграммы на каждый символ;
|
||
- точная визуализация rename/copy, потому что incremental pipeline сейчас может требовать full analysis для rename/copy;
|
||
- стабильная работа на очень больших репах без очереди, debounce и cancellation;
|
||
- full/incremental анализ без настроенного LLM provider;
|
||
- автоматическая установка Python 3.12/3.13 на всех OS без отдельного installer UX.
|
||
|
||
## Варианты интеграции
|
||
|
||
### 1. Optional CLI Runner + просмотр `.codeboarding/`
|
||
|
||
🎯 9 🛡️ 8 🧠 4
|
||
Примерно `250-450` строк.
|
||
|
||
Суть: в Settings/Integrations добавляем CodeBoarding detect/install/run. Первый MVP только запускает `full`/`incremental`, показывает статус, открывает `.codeboarding/analysis.json` и Markdown/Mermaid в существующем viewer.
|
||
|
||
Плюсы:
|
||
|
||
- быстро проверить реальную пользу;
|
||
- почти не вмешивается в team/review lifecycle;
|
||
- опирается на уже существующие Markdown/Mermaid возможности;
|
||
- безопаснее, потому что dependency optional.
|
||
|
||
Минусы:
|
||
|
||
- это не live UX;
|
||
- пользователь сам интерпретирует изменения;
|
||
- нет красивой связки с задачами агентов.
|
||
|
||
Когда выбирать: если хотим дешёвый probe перед большой фичей.
|
||
|
||
### 2. Live-ish Overlay поверх baseline анализа
|
||
|
||
🎯 9 🛡️ 8 🧠 5
|
||
Примерно `900-1400` строк.
|
||
|
||
Суть: CodeBoarding делает baseline `.codeboarding/analysis.json`. Дальше наш watcher/git status/task change ledger быстро мапит изменённые файлы на компоненты из baseline и подсвечивает affected components почти в реальном времени. CodeBoarding `incremental` запускается фоном по debounce, на завершение task или по кнопке refresh.
|
||
|
||
Плюсы:
|
||
|
||
- даёт пользователю ощущение real-time;
|
||
- не заставляет LLM работать на каждое маленькое изменение;
|
||
- хорошо ложится на агентские изменения и task review;
|
||
- можно показывать impact до завершения задачи.
|
||
|
||
Минусы:
|
||
|
||
- нужна собственная модель overlay state;
|
||
- baseline mapping может быть устаревшим до следующего incremental;
|
||
- для новых файлов компонент может определяться эвристикой до refresh.
|
||
|
||
Когда выбирать: лучший первый продуктовый вариант.
|
||
|
||
### 3. Architecture Review per Task
|
||
|
||
🎯 8 🛡️ 7 🧠 8
|
||
Примерно `1600-2500` строк.
|
||
|
||
Суть: связываем CodeBoarding с review flow. Для каждой task показываем impacted components, changed methods, old/new architecture map, summary риска и ссылки на файлы. Можно добавить отдельную вкладку в task detail или review dialog.
|
||
|
||
Плюсы:
|
||
|
||
- максимальная ценность для Agent Teams;
|
||
- помогает ревьюить AI-generated changes не только по diff, но и по архитектурному влиянию;
|
||
- можно использовать как сильный selling point.
|
||
|
||
Минусы:
|
||
|
||
- крупная фича;
|
||
- нужны тесты на task-change mapping, IPC, persistence и UI;
|
||
- есть риск перегрузить review screen.
|
||
|
||
Когда выбирать: после MVP и подтверждения, что карты реально помогают пользователям.
|
||
|
||
## Варианты установки optional dependency
|
||
|
||
### A. pipx install в user environment
|
||
|
||
🎯 8 🛡️ 7 🧠 4
|
||
Примерно `350-600` строк.
|
||
|
||
UI проверяет `python3.12`/`python3.13`, `pipx`, `codeboarding`. Если нет, предлагает install через `pipx install codeboarding --python python3.12`, затем `codeboarding-setup`.
|
||
|
||
Плюсы: соответствует README, изолированная среда, меньше конфликтов с системным Python.
|
||
|
||
Минусы: надо отдельно вести UX для отсутствующего Python/pipx.
|
||
|
||
### B. Скачать packaged binary из GitHub Release
|
||
|
||
🎯 7 🛡️ 7 🧠 6
|
||
Примерно `600-1000` строк.
|
||
|
||
У CodeBoarding release `v0.11.0` содержит assets для macOS/Linux/Windows. Можно скачивать бинарь под OS, проверять sha256 asset и хранить в app-managed tools dir.
|
||
|
||
Плюсы: меньше зависимости от Python/pipx у пользователя.
|
||
|
||
Минусы: нужно аккуратно делать download, checksum, permissions, updates, notarization/security prompts.
|
||
|
||
### C. Встроить Python package в наш app bundle
|
||
|
||
🎯 4 🛡️ 5 🧠 9
|
||
Примерно `1200-2200` строк.
|
||
|
||
Пакуем CodeBoarding и Python runtime вместе с приложением.
|
||
|
||
Плюсы: самый гладкий UX после установки.
|
||
|
||
Минусы: тяжёлый bundle, OS-specific packaging, LSP binaries, security/update burden. Для optional feature это слишком дорого.
|
||
|
||
Рекомендация: начать с A, потом рассмотреть B для packaged app.
|
||
|
||
## Как это ложится на нашу архитектуру
|
||
|
||
Так как фича пересекает main/preload/renderer и запускает внешний инструмент, её лучше делать по `docs/FEATURE_ARCHITECTURE_STANDARD.md`:
|
||
|
||
```text
|
||
src/features/codeboarding/
|
||
contracts/
|
||
core/
|
||
main/
|
||
adapters/
|
||
infrastructure/
|
||
preload/
|
||
renderer/
|
||
```
|
||
|
||
Основные части:
|
||
|
||
- contracts: DTO для status, install state, run request, run result, affected components;
|
||
- core: правила выбора режима `full`/`incremental`, debounce policy, overlay merge policy;
|
||
- main/infrastructure: binary detection, installer, command runner, output parser, `.codeboarding` reader;
|
||
- main/adapters/input: IPC handlers;
|
||
- preload: bridge;
|
||
- renderer: settings panel, project action, architecture map panel, task/review badges.
|
||
|
||
Надо использовать path validation и не давать CodeBoarding работать вне выбранного project root.
|
||
|
||
## MVP flow
|
||
|
||
1. Пользователь открывает project.
|
||
2. UI показывает “Enable CodeBoarding architecture map”.
|
||
3. App проверяет наличие `codeboarding`.
|
||
4. Если нет, предлагает install.
|
||
5. После install запускает `codeboarding-setup`.
|
||
6. Первый запуск: `codeboarding full --local <project>`.
|
||
7. App читает `.codeboarding/analysis.json`.
|
||
8. Показывает diagram/docs.
|
||
9. Когда агент меняет файлы, app быстро подсвечивает affected components по baseline mapping.
|
||
10. После debounce или завершения task запускает `codeboarding incremental --local <project>`.
|
||
11. Если incremental возвращает `requiresFullAnalysis`, UI предлагает full refresh.
|
||
|
||
## Риски
|
||
|
||
- 🟠 LLM keys: без provider key full/incremental может не пройти. Нужен понятный setup и read-only detect.
|
||
- 🟠 Performance: full analysis может быть долгим. Нужны cancellation, queue, progress, timeout.
|
||
- 🟠 Dirty worktree: incremental умеет работать с worktree, но target refs и snapshots надо использовать аккуратно.
|
||
- 🟠 Cost: LLM вызовы могут стоить денег. Нужен явный opt-in и возможно “run on task complete” вместо постоянного refresh.
|
||
- 🟡 Security: не отправлять код в неизвестный сервис. CodeBoarding заявляет local processing plus direct provider API calls, но UX должен прямо показывать выбранный provider.
|
||
- 🟡 Generated files: `.codeboarding/` не всегда надо коммитить. Нужно дать настройку ignore/commit.
|
||
- 🟡 MCP: CodeBoarding-MCP выглядит сырым, поэтому не стоит брать его как основную интеграцию.
|
||
|
||
## Рекомендация
|
||
|
||
Делать поэтапно:
|
||
|
||
1. MVP optional CLI runner и viewer.
|
||
2. Live-ish overlay на базе нашего task change ledger и CodeBoarding baseline.
|
||
3. Background incremental refresh.
|
||
4. Architecture Review per Task.
|
||
5. Только потом MCP/context tools для агентов.
|
||
|
||
Самое ценное для пользователя: видеть не “агент изменил 12 файлов”, а “агент сейчас меняет Auth Runtime Detection и это затрагивает Provider Connection + Team Provisioning”. CodeBoarding может дать основу для такой карты, но realtime UX должен быть нашим.
|