API VEGA

Структурный порог качества для кодирующих агентов.

Topos измеряет сложность, связность и рискованные потоки данных, затем устанавливает вашему агенту конкретную цель — от SLOP до GOLD.

Установка и быстрое начало · Что Topos проверяет · Под капотом · Документация · Проблемы

Зачем Topos

Кодирующие агенты быстро генерируют рабочий код. Вопрос же посерьёзнее: остаётся ли полученный результат понятным, безопасным для изменений и хорошо интегрированным в остальной репозиторий. Качество — новая валюта.

Topos вычисляет этот сигнал из структуры программы — а не по итогам обзора LLM или мнения о стиле — и возвращает конкретные места сбоев и последующие шаги. Он достаточно быстр, чтобы находиться внутри цикла агента: измеряй, редактируй, проверяй, повторяй.

Тесты оценивают поведение. Topos проверяет, что реализация рассчитана на постоянные изменения.

Основан на теории категорий и работает на нативном движке на Rust.

Под капотом

Topos — автономная CLI на Rust и MCP-сервер. Анализ выполняется локально; ваш исходный код не отправляется внешнюю модель или хостинговый сервис анализа.

КомпонентРоль
tree-sitterРазбирает шесть языков и обеспечивает нативные представления AST, CFG, CPG, PDG и UAST.
GitNexusОбеспечивает граф зависимостей репозитория, оцениваемый COMPOSABLE (topos depgraph generate). Требуется npm install -g gitnexus@1.6.8.
SighthoundВстроен в MCP-сервер для дополнительных выводов по безопасности; нативные зондирования CPG остаются источником оценок SECURE.
GraphifyНеобязательное advisory обнаружение сирот и хрупких краёв через topos graphify / topos_refactor(target="graphify"); не влияет на медаль. Требуется pip install graphifyy.

Результат — единый контракт для агентов, охватывающий несколько структурных аспектов: одна метрика для оптимизации, явные доказательства для каждой ошибки и цикл верификации, который может отличить реальное улучшение от косметических изменений.

Установка и быстрое начало

Расширение MCP для VS Code

Откройте представление Extensions, найдите @mcp topos, выберите Topos и нажмите Install. Или смотрите здесь: Topos: MCP-регистр GitHub.

Затем включите режим агента:

Используйте Topos, чтобы найти в этом репозитории наихудшую структурную проблему, внесите одно целенаправленное улучшение и проверьте результат.

См. руководство по настройке агента для разрешений инструментов и устранения неполадок.

Другие клиенты MCP [Claude Code]

Запустите автономный MCP-сервер по требованию — без постоянной установки Topos или Python:

claude mcp add --transport stdio topos -- uvx topos-mcp

Настройка для Codex, Gemini CLI, Cursor, Windsurf, Antigravity и ручной JSON описана в руководстве по настройке агента.

Standalone CLI

curl -fsSL https://docs.krv.ai/topos/install.sh | bash

Предпочитаете Homebrew?

brew install krv-labs/tap/topos

На Homebrew 6+ эта команда автоматически добавляет репозиторий и доверяет только эту формулу. Если вы сначала выполните brew tap krv-labs/tap, запустите перед brew install topos команду brew trust --formula krv-labs/tap/topos.

Затем запустите:

topos evaluate . -r

Подсказка

Хотите GOLD? Запустите topos depgraph generate, если ваш агент ещё не сделал этого ранее (и повторите после больших структурных изменений), затем проведите оценку с добавленным CLI-флагом --gitnexus-dir .gitnexus.

Topos поддерживает Python, Rust, JavaScript, TypeScript, C++, и Go. CLI по умолчанию использует Python; для другого языка используйте --language rust|go|javascript|typescript|cpp. См. Installation для поддержки платформ и альтернативных путей установки.

Другие способы использования Topos

Что Topos проверяет

У каждого файла три независимые вердикты:

  • SIMPLE — избегает лишней сложности за счёт энтропии AST и сложности управления потоком.

  • COMPOSABLE — остаётся отделённым от репозитория с использованием структуры зависимостей модулей и инвалидности Мартина.

  • SECURE — избегает опасной доступности API и taint-путей в графе свойств кода.

Эти вердикты суммируются в одну запоминающуюся медаль качества, не скрывая, какая опора не выдержала:

МедальКритерий
🥇 GOLDПроходит все 3
🥈 SILVERПроходит 2 из 3
🥉 BRONZEПроходит 1 из 3
❌ SLOPНе проходит ни одного или не удаётся разобрать

Topos также возвращает ранжированную рекомендацию по переработке: места ошибок по метрикам, циклы управления потоком, зависимые ребра, узкие места процессов и дополнительные выводы Graphify. Рекомендации не скрывают, какая медаль была получена.

Как формируются медали Три столпа взаимоисключаемы и образуют восемь элементную евклидову сетку оценок; GOLD — их пересечение.

---
config:
  layout: dagre
  theme: neutral
---
graph BT
    SLOP["❌ SLOP<br/>No Medal"]
    SIMPLE["🥉 BRONZE<br/>Simple"]
    COMPOSABLE["🥉 BRONZE<br/>Composable"]
    SECURE["🥉 BRONZE<br/>Secure"]
    SC["🥈 SILVER<br/>S ∧ C"]
    SSc["🥈 SILVER<br/>S ∧ Sc"]
    CSc["🥈 SILVER<br/>C ∧ Sc"]
    IDEAL["🥇 GOLD<br/>Quality Code"]

    SLOP --> SIMPLE
    SLOP --> COMPOSABLE
    SLOP --> SECURE
    SIMPLE --> SC
    SIMPLE --> SSc
    COMPOSABLE --> SC
    COMPOSABLE --> CSc
    SECURE --> SSc
    SECURE --> CSc
    SC --> IDEAL
    SSc --> IDEAL
    CSc --> IDEAL

    style SLOP       fill:#f8d7da,stroke:#842029,color:#000
    style SIMPLE     fill:#cd7f32,stroke:#5c3a1e,color:#fff
    style COMPOSABLE fill:#cd7f32,stroke:#5c3a1e,color:#fff
    style SECURE     fill:#cd7f32,stroke:#5c3a1e,color:#fff
    style SC         fill:#c0c0c0,stroke:#4a4a4a,color:#000
    style SSc        fill:#c0c0c0,stroke:#4a4a4a,color:#000
    style CSc        fill:#c0c0c0,stroke:#4a4a4a,color:#000
    style IDEAL      fill:#ffd700,stroke:#856404,color:#000

Measures · Основы теории категорий

Распространение

Topos распространяется четырьмя способами:

  • GitHub Releases — исполняемая файл-форма CLI top os (macOS/Linux), через install.sh или прямую загрузку релиза.

  • PyPI — topos-mcp, тонкий бинарный пакет bin-wheel, включающий MCP-сервер (pip install topos-mcp / uvx topos-mcp), без runtime Python.

  • VS Code Marketplace — расширение Topos, включающее платформенные двоичные файлы.

  • Docker — образ контейнера для размещения Glama и других MCP-регистров.

Структура Crate и детали адаптеров: docs.krv.ai/topos/architecture.

Вклад

Topos используется внутри Krv Labs для управления выводом кода AI-агентов. Мы приветствуем баги, идеи и вклад.

Полная документация · Измерения и метрики · Инженерные заметки