papayu/docs/CLAUDE_AND_AGENT_SYNC.md

Claude и синхронизация с агентом (Claude Code / Cursor)

Настройка PAPA YU для работы с Claude и автоматической синхронизации состояния с IDE-агентом (Cursor, Claude Code и т.п.).

---

1. Использование Claude как LLM

PAPA YU вызывает OpenAI-совместимый API. Claude можно подключить двумя способами.

Вариант A: OpenRouter (рекомендуется)

OpenRouter даёт единый API для разных моделей, включая Claude. Формат запросов совпадает с OpenAI.

1. Зарегистрируйтесь на openrouter.ai.
2. Создайте API-ключ.
3. Задайте переменные окружения:

export PAPAYU_LLM_API_URL="https://openrouter.ai/api/v1/chat/completions"
export PAPAYU_LLM_API_KEY="sk-or-v1-ваш-ключ"
export PAPAYU_LLM_MODEL="anthropic/claude-3.5-sonnet"

Или для Claude 3 Opus:

export PAPAYU_LLM_MODEL="anthropic/claude-3-opus"

4. Запуск: npm run tauri dev (или через start-with-openai.sh, подставив эти переменные в .env.openai).

Кнопка «Предложить исправления» будет вызывать Claude через OpenRouter.

Вариант B: Прямой API Anthropic

Нативный API Anthropic (Messages API) использует другой формат запросов. В текущей версии PAPA YU его поддержка не реализована — используйте OpenRouter (вариант A).

---

2. Мульти-провайдер: сбор от нескольких ИИ и оптимальное решение

Чтобы агент собирал ответы от нескольких ИИ (Claude, OpenAI и др.), анализировал их и выдавал один оптимальный план, задайте переменную PAPAYU_LLM_PROVIDERS — JSON-массив провайдеров.

Формат PAPAYU_LLM_PROVIDERS

[
  { "url": "https://api.openai.com/v1/chat/completions", "model": "gpt-4o-mini", "api_key": "sk-..." },
  { "url": "https://openrouter.ai/api/v1/chat/completions", "model": "anthropic/claude-3.5-sonnet", "api_key": "sk-or-v1-..." }
]

• url — OpenAI-совместимый endpoint.
• model — имя модели.
• api_key — опционально; если не указан, используется PAPAYU_LLM_API_KEY.

Запросы к провайдерам выполняются параллельно. Результаты объединяются в один план.

Агрегация

• Без агрегатора (по умолчанию): планы объединяются в Rust: действия по одному пути дедуплицируются, итог — один план с объединённым списком действий.
• С агрегатором-ИИ: задайте PAPAYU_LLM_AGGREGATOR_URL (и при необходимости PAPAYU_LLM_AGGREGATOR_KEY, PAPAYU_LLM_AGGREGATOR_MODEL). ИИ-агрегатор получит все планы и вернёт один оптимальный в том же JSON-формате.

Пример (одна строка в .env.openai):

# Мульти-провайдер: Claude + OpenAI, без отдельного агрегатора
export PAPAYU_LLM_PROVIDERS='[{"url":"https://openrouter.ai/api/v1/chat/completions","model":"anthropic/claude-3.5-sonnet","api_key":"sk-or-v1-..."},{"url":"https://api.openai.com/v1/chat/completions","model":"gpt-4o-mini","api_key":"sk-..."}]'

# Опционально: отдельная модель для слияния планов
# PAPAYU_LLM_AGGREGATOR_URL=https://api.openai.com/v1/chat/completions
# PAPAYU_LLM_AGGREGATOR_KEY=sk-...
# PAPAYU_LLM_AGGREGATOR_MODEL=gpt-4o-mini

Если PAPAYU_LLM_PROVIDERS задан и не пустой, обычный одиночный вызов PAPAYU_LLM_API_URL не используется для планирования — вместо него выполняется мульти-провайдерный сценарий.

---

3. Автоматическая синхронизация с агентом (Claude Code / Cursor)

Идея: после каждого анализа PAPA YU записывает краткое состояние в файл проекта. Агент в IDE (Cursor, Claude Code) может читать этот файл и учитывать контекст.

Включение записи sync-файла

Задайте переменную окружения:

export PAPAYU_AGENT_SYNC=1

После каждого успешного анализа в корне проекта (путь, который вы анализировали) создаётся или обновляется файл:

<путь_проекта>/.papa-yu/agent-sync.json

Содержимое (пример):

{
  "path": "/Users/you/project",
  "updated_at": "2026-02-08T12:00:00Z",
  "narrative": "Я проанализировал проект...",
  "findings_count": 3,
  "actions_count": 5
}

• path — путь к проекту.
• updated_at — время последнего анализа (ISO 8601).
• narrative — краткий человекочитаемый вывод.
• findings_count / actions_count — число находок и действий. (При необходимости можно расширить полями report_md_preview и др.)

Как использовать в Cursor / Claude Code

1. Правило в Cursor
   В .cursor/rules или в настройках можно добавить правило: «Перед правками проверяй .papa-yu/agent-sync.json в корне проекта — там последний анализ PAPA YU (narrative, findings_count, actions_count). Учитывай это при предложениях.»

2. Чтение из кода/скрипта
   Агент или скрипт может читать ./.papa-yu/agent-sync.json и использовать поля для контекста или логики.

3. Обратная связь (по желанию)
   Можно вручную создать .papa-yu/agent-request.json с полем "action": "analyze" и путём — в будущих версиях PAPA YU сможет обрабатывать такие запросы (сейчас только запись sync-файла реализована).

---

4. Онлайн-взаимодействие

• LLM уже работает онлайн: запросы к OpenRouter/OpenAI идут по HTTPS.
• Синхронизация с агентом — локальная: файл .papa-yu/agent-sync.json на диске; Cursor/Claude Code читает его локально.
• Расширение (будущее) — опциональный локальный HTTP-сервер в PAPA YU (например, 127.0.0.1:3939) с эндпоинтами POST /analyze, GET /report для вызова из скриптов или агента. Пока достаточно файловой синхронизации.

---

5. Краткий чеклист

Шаг	Действие
1	Задать PAPAYU_LLM_API_URL, PAPAYU_LLM_API_KEY, PAPAYU_LLM_MODEL (OpenRouter + Claude).
2	При необходимости задать PAPAYU_AGENT_SYNC=1 для записи .papa-yu/agent-sync.json.
3	Запустить PAPA YU, выполнить анализ проекта.
4	В Cursor/Claude Code добавить правило или логику чтения .papa-yu/agent-sync.json.

---

Snyk Code и Documatic: для дополнения анализа кода (Snyk) и структурирования архитектуры (Documatic) см. docs/SNYK_AND_DOCUMATIC_SYNC.md.

См. также docs/OPENAI_SETUP.md, env.openai.example.