Project Code Intelligence

Интеллект репозитория и доказательства безопасности изменений для агентов кодирования.

Project Code Intelligence (PCI) индексирует Git-репозитории и предоставляет агентам кодирования структурированные доказательства для исследований, рефакторинга, сопровождения и работы по безопасности. Агенты могут искать по концепции или идентификатору, проверять кандидатные связи, оценивать радиус поражения изменения, находить повторяющиеся формы реализации и запрашивать результаты статического анализа перед редактированием кода.

PCI не является автономным рецензентом, а его граф — не граф вызовов компиляторного уровня. Он сужает область поиска и предоставляет доказательства; агент по-прежнему проверяет важные выводы в исходном коде.

С чем он помогает

Исследование и ориентация

• Поиск точных идентификаторов, имён файлов, ключей конфигурации и известных строк.

• Поиск по поведению, когда соответствующие имена неизвестны.

• Просмотр языков репозитория, ролей файлов, снимков, покрытия парсером и свежести индекса.

• Получение ограниченных записей с путями, диапазонами строк, метаданными и фрагментами исходного кода.

• Работа с несколькими репозиториями через именованные коллекции и фильтры репозиториев.

Более безопасные изменения

• Поиск кандидатных вызывающих, вызываемых, ссылок, тестов и связей на уровне модулей.

• Проверка доказательств радиуса поражения перед удалением, переименованием или изменением символа.

• Выявление сигналов точек входа, осиротевших элементов и покрытия тестами.

• Внедрение близлежащих доказательств в поддерживаемых агентов кодирования при добавлении или удалении определений.

Сопровождение и избыточность

• Поиск групп функций, повторяющих мотив формы вызова.

• Ранжирование кандидатов на избыточность по сходству, оценке стоимости абстракции и вероятной чистой ценности.

• Проведение аудита репозитория на устаревшие индексы, дублирующиеся имена, кандидатов на избыточность и статические находки.

Безопасность и статический анализ

• Приём отчётов SARIF вместе с записями исходного кода.

• Поиск нормализованных находок по инструменту, правилу, уровню, состоянию базовой линии или пути.

• Получение диагностики, потоков кода и метаданных запуска без необходимости разбирать агентом сырые артефакты SARIF.

Related MCP server: Graft

Как это работает

pci index разбирает файлы репозитория в ограниченные записи, извлекает метаданные и кандидатные связи и сохраняет снимки в Postgres/pgvector. Семантические эмбеддинги необязательны: лексический поиск и большинство структурных доказательств остаются доступными с --no-embed.

pci mcp предоставляет доступ к индексу через локальный MCP-сервер stdio. Агенты кодирования используют его инструменты, ориентированные на фильтры, для обнаружения вероятно релевантного кода, а затем читают и проверяют живой исходный код перед действием.

Архитектура локального развёртывания по умолчанию:

• Postgres/pgvector: Docker или Podman Compose.

• Сервисы эмбеддингов для Linux: модули Podman Quadlet, управляемые пользовательским systemd.

• Эмбеддинги на Apple Silicon: нативный сервис MLX.

• Интеграция с агентами: MCP-сервер stdio с опциональными хуками для доказательств изменений.

Удалённые Postgres и OpenAI-совместимые конечные точки эмбеддингов поддерживаются, когда такой компромисс осознан.

Быстрый старт

Установите CLI из клона:

uv tool install /path/to/project-code-intelligence
export PATH="$HOME/.local/bin:$PATH"

Запустите встроенную базу данных и лучший доступный локальный бэкенд эмбеддингов:

pci doctor --start
pci doctor

Индексируйте Git-репозиторий:

cd /path/to/repo
pci index .

Установите конфигурацию MCP для вашего агента кодирования:

pci mcp install --target codex

Поддерживаемые цели включают claude, codex, opencode, pi, vscode, copilot, cline и zed. См. docs/MCP_SETUP.md для настройки под конкретного клиента, ограничения проекта и обработки учётных данных.

Для лексического поиска без эмбеддингов:

pci doctor --start-db
pci index --no-embed .

Основные инструменты агента

Запустите pci audit для отчёта о доказательствах по всему дереву.

Доказательства, а не вердикты

PCI намеренно различает более сильные индексированные факты и приблизительные или эвристические доказательства.

• Кандидатные рёбра связей не являются фактами графа вызовов с проверкой типов.

• Радиус поражения не может доказать, что изменение безопасно.

• Оценки избыточности не могут решить, должны ли две функции разделять абстракцию.

• Статические находки сохраняют ограничения своего исходного анализатора.

• Индекс может быть устаревшим после незакоммиченных или недавно закоммиченных изменений.

• Семантический поиск может пропустить релевантный код или вернуть правдоподобных соседей.

Проверяйте важных вызывающих и находки в живом исходном коде. Используйте прямое чтение файлов для известных путей и небольших ограниченных вопросов; PCI наиболее полезен, когда местоположение, имя или влияние ещё неизвестны.

Установка

Python CLI

Установите для текущего пользователя с помощью uv:

uv tool install /path/to/project-code-intelligence

Для редактируемой установки для разработки:

cd /path/to/project-code-intelligence
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Nix

На NixOS или другом Linux-хосте с включёнными flakes:

nix build
nix run . -- doctor --skip-db --embedding skip
nix develop

Установите постоянно в пользовательский профиль:

nix profile install .#project-code-intelligence

Закрытие Nix содержит CLI, MCP-сервер, зависимости Python и встроенные ресурсы Compose и Quadlet. Тяжёлые среды выполнения эмбеддингов для Linux остаются в контейнерах Podman, а не становятся нативными зависимостями Nix на хосте.

Локальная база данных

Запустите только встроенную базу данных Postgres/pgvector:

pci doctor --start-db

Установленный файл Compose материализуется в пользовательский кэш. Чтобы использовать собственную копию:

export PCI_COMPOSE_FILE=/path/to/docker-compose.yml
pci doctor --start-db

Локальный сервис эмбеддингов

CLI включает шаблоны сервисов; отдельного пакета эмбеддингов PCI нет. На Linux установите Podman и убедитесь, что systemctl --user работает, затем выполните:

pci doctor
pci doctor --start-embedding

PCI обнаруживает доступное оборудование, материализует только выбранный бэкенд в ~/.config/containers/systemd/, перезагружает пользовательский systemd и запускает его. Устаревшие модули PCI для других бэкендов эмбеддингов останавливаются и удаляются. Образы и модели по умолчанию загружаются при первом использовании.

Выберите бэкенд явно, когда это необходимо:

# AMD GPU
pci doctor --start-embedding --embedding-backend rocm

# NVIDIA GPU
pci doctor --start-embedding --embedding-backend cuda

# Portable CPU fallback
pci doctor --start-embedding --embedding-backend fastembed

# AMD Ryzen AI NPU (experimental)
pci doctor --start-embedding --embedding-backend lemonade

Доступные селекторы: auto, fastembed, lemonade, rocm, cuda и apple. PCI отклоняет запрошенный бэкенд, если его требуемое оборудование или среда выполнения недоступны. apple работает нативно, а не через Quadlet.

Чтобы запустить базу данных и явный бэкенд вместе:

pci doctor --start --embedding-backend rocm

Контейнеризованные бэкенды публикуют OpenAI-совместимую конечную точку по адресу http://127.0.0.1:18081/v1/embeddings по умолчанию. Запускайте один локальный бэкенд за раз, так как они используют эту конечную точку совместно.

Остановите сервисы эмбеддингов, не затрагивая базу данных:

pci doctor --stop-embedding

Удалите сгенерированные локальные сервисы, кэши и встроенный том базы данных:

pci doctor --clean

--clean разрушителен и запрашивает подтверждение перед удалением данных.

Удалённые эмбеддинги

Запустите только базу данных, затем настройте доверенного OpenAI-совместимого провайдера:

pci doctor --start-db
export PCI_ALLOW_REMOTE_EMBEDDING=1
export PCI_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
export PCI_EMBEDDING_ENDPOINT_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
pci doctor

Удалённые конечные точки получают текст, производный от исходного кода. Включайте их только тогда, когда это приемлемо для индексируемых репозиториев.

Индексация репозиториев

Индексируйте один репозиторий:

pci index /path/to/repo

Индексируйте несколько репозиториев как рабочее пространство:

cd /path/to/workspace
pci index service-api web-ui shared-lib

PCI выводит имена коллекций и репозиториев из путей. MCP-клиенты фильтруют по этим логическим именам, а не по абсолютным путям файловой системы. Индексация инкрементальна: неизменённые файлы повторно используются, когда существуют совместимые снимки.

Отчёты SARIF, найденные в путях индексируемых репозиториев, автоматически загружаются. Сбросьте и пересоберите один репозиторий с помощью:

pci index --reset /path/to/repo

Используйте pci status для просмотра запусков индексации и pci index --help для параметров парсера, эмбеддингов, коллекций и базы данных.

MCP и хуки агента

Создайте учётные данные базы данных только для чтения с областью проекта и выведите конфигурацию MCP:

pci index --init-db --mcp-config codex .

Установите или удалите конфигурацию MCP без повторной индексации:

pci mcp install --target codex
pci mcp install --target codex --uninstall

Сгенерированная конфигурация клиента не содержит пароля базы данных. Учётные данные хранятся в каталоге конфигурации PCI пользователя с режимом 0600. Pi использует мост MCP в локальном для проекта .pi/extensions/. Cline требует --config-path, так как его файл настроек ограничен пользователем.

Опциональные хуки могут напоминать агенту об использовании индекса и внедрять доказательства рядом с правками, которые добавляют или удаляют определения:

pci hook install --target codex

Поддержка хуков и детали установки различаются в зависимости от клиента. Хуки — это помощь, а не механизм принуждения или корректности. См. docs/MCP_SETUP.md и docs/SYSTEM_PROMPT.md.

Конфиденциальность и безопасность

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

Не коммитьте и не распространяйте дампы базы данных, артефакты восстановления, вывод SARIF, кэши эмбеддингов, файлы моделей, векторные индексы, сгенерированные данные из частных репозиториев или локальные файлы учётных данных MCP. Они могут содержать фрагменты исходного кода, пути, символы, находки, метаданные и эмбеддинги, производные от исходного кода.

Коллекции организуют репозитории, но не являются границей безопасности. Используйте отдельные базы данных или пользователей базы данных, когда репозитории требуют более сильной изоляции. Учётные данные MCP с областью проекта ограничивают обычный доступ, но не заменяют безопасность хоста и базы данных.

Когда PCI подходит

PCI обычно помогает, когда:

• репозиторий или рабочее пространство велико или незнакомо;

• идентификаторы неизвестны в начале задачи;

• сгенерированные файлы делают широкие чтения дорогими или шумными;

• рефакторинг требует доказательств вызывающих, тестов и связей;

• работы по сопровождению требуют обнаружения повторяющихся шаблонов;

• статические находки необходимо сопоставлять с исходным кодом;

• несколько репозиториев должны быть доступны через один интерфейс.

Он может добавить мало ценности для небольшого знакомого репозитория, известного файла и диапазона строк или вопроса, на который отвечает одно ограниченное rg или чтение файла. Цель — не заменить стандартные инструменты разработчика, а улучшить неопределённое обнаружение и этапы планирования изменений вокруг них.

Сокращение токенов и затрат может быть полезным побочным эффектом, но PCI этого не обещает. Измеряйте, улучшает ли индекс реальные сеансы, с помощью docs/EVALUATING_VALUE.md и подсказки для ретроспективы сеанса.

Разработка

MCP-сервер использует stdio; Docker Compose предназначен для локальной базы данных, а не для размещения процесса MCP. Запустите полный шлюз разработки с помощью:

nix develop
make check

Для изменений в поведении приёма, базы данных или MCP также выполните:

docker compose up -d pgvector
make integration-smoke

См. CONTRIBUTING.md и AGENTS.md для соглашений проекта и мер защиты публикации.

Документация

• docs/MCP_SETUP.md — клиенты MCP, области действия, учетные данные и модель безопасности

• docs/PUBLIC_API.md — CLI, окружение, MCP и поверхности совместимости с Python

• docs/EVALUATING_VALUE.md — оценка PCI на реальных сессиях кодирования

• docs/SYSTEM_PROMPT.md — инструкции для агента по использованию PCI

• docs/SYSTEM_PROMPT_RATIONALE.md — обоснование дизайна промптов

• docs/SESSION_RETROSPECTIVE_PROMPT.md — промпт оценки в конце сессии

• .env.example — справочник по конфигурации окружения

• CONTRIBUTING.md — процесс разработки

Лицензия

MIT. См. LICENSE.