Контракт для агентов

Это короткая рабочая схема для внешних ИИ-агентов. Она нужна, чтобы агент не путал MCP и API, не плодил дубли и не пытался писать через неподходящий коннектор.

MCP читает API пишет Опора: slug Без raw data

1. Базовый принцип

Через MCP агент читает контекст системы, канон, карту портфеля и ищет существующие объекты.
Через HTTP API агент создаёт и обновляет продукты, приложения, решения, задачи и канонические правила.
Если MCP-клиент не умеет передавать arguments в tool call, write-tools MCP считаются недоступными.

Короткое правило: MCP читает, API пишет. На контуре с PROJECT_APPS_MCP_WRITE_ENABLED=false write-tools в MCP отключены полностью — только HTTP API.

2.1 Как узнать направления

Перед записью нужно читать project-apps://portfolio или GET https://apps.farmchel.org/api/project-apps/directions.
Не угадывать direction_slug из памяти чата, если его можно прочитать из системы.
В ответе GET /api/project-apps/directions смотри reference.canonical_direction_slugs — эталонный список slug мобильного портфеля Farmchel (в БД могут быть и служебные/демо-направления).
В MCP-ресурсах project-apps://context и project-apps://portfolio то же перечислено как canonical_direction_slugs / reference.canonical_direction_slugs.

2. Что читать через MCP

MCP нужен для того, чтобы агент ориентировался в системе до записи.

project_apps_overview — общая картина портфеля.
project_apps_attention — что требует внимания сейчас.
project_apps_product_search — поиск продукта перед созданием или обновлением.
project_apps_canon — правила структуры и канона.
project-apps://context, project-apps://canon, project-apps://portfolio — контекст, правила и карта портфеля.

Смысл чтения: агент должен понимать не только продукт, но и место объекта внутри штаба: направление, продукт, приложение, внимание сейчас, канон и summary-слой.

3. Что писать через API

Все create/update действия выполняются через API с заголовком токена.

Accept: application/json
Content-Type: application/json
X-Project-Apps-Token: <выданный токен>

POST https://apps.farmchel.org/api/project-apps/products — создать продукт.
PATCH https://apps.farmchel.org/api/project-apps/products/{product} — обновить продукт.
POST https://apps.farmchel.org/api/project-apps/apps — создать приложение.
PATCH https://apps.farmchel.org/api/project-apps/apps/{mobileApp} — обновить приложение.
GET https://apps.farmchel.org/api/project-apps/directions — получить допустимые направления перед записью.
GET https://apps.farmchel.org/api/project-apps/products и GET https://apps.farmchel.org/api/project-apps/apps — проверить, что объект уже не существует; для продуктов доступен фильтр ?is_favorite=1 (избранное в админке).
POST https://apps.farmchel.org/api/project-apps/decisions — записать решение.
POST https://apps.farmchel.org/api/project-apps/tasks — создать задачу.
POST https://apps.farmchel.org/api/project-apps/signals, /insights, /economics — писать summary-слой.
POST https://apps.farmchel.org/api/project-apps/canon-rules и PATCH .../canon-rules/{canonRule} — поддерживать канон в актуальном состоянии.

Конкуренты, отзывы конкурентов, ключи и store truth уже выделены как отдельные сущности в штабе, но в текущем публичном write-контракте агент пишет прежде всего core и summary-слой. Для market/store слоя пока опираемся на admin workflow.

4. Алгоритм без дублей

Сначала прочитать канон и контекст.
Потом найти продукт или приложение, чтобы понять, существует ли объект.
Если объект найден — использовать PATCH.
Если объект не найден — использовать POST.
Не создавать новую запись, если уже найден устойчивый идентификатор.

Опорные идентификаторы

Для продукта: slug, затем нормализованное имя внутри направления.
Для приложения: slug, bundle_id, package_id, store_url.
Для спорного хвоста сначала ищем продукт. Если честной продуктовой привязки ещё нет, приложение пишем на уровень направления с product_binding_status.

Если у приложения спорная судьба, фиксируй это как needs-product или product-candidate, а не создавай фиктивный продукт только ради чистоты таблицы.

5. Минимум для записи продукта

{
  "direction_slug": "fitness",
  "name": "Push-Ups",
  "portfolio_status": "rebuild",
  "product_focus": "rewrite",
  "summary": "Фитнес-продукт для гипотезы по отжиманиям.",
  "is_revenue_generating": false,
  "monetization_model": "Требует подтверждения.",
  "health_state": "Нужна проверка",
  "risk_summary": "Нет точных store identity.",
  "growth_chance": "Высокий после нормализации.",
  "next_step": "Привязать store names и economics summary."
}

6. Минимум для записи приложения

{
  "product_slug": "push-ups",
  "name": "Push-Ups Black & White",
  "platform": "iOS",
  "implementation_status": "building",
  "store_url": "https://apps.apple.com/app/...",
  "bundle_id": "org.farmchel.pushups.variant1",
  "package_id": "org.farmchel.pushups.variant1"
}

Если продуктовая привязка спорная

{
  "direction_slug": "fitness",
  "name": "Quit Smoking Android",
  "platform": "Android",
  "implementation_status": "building",
  "product_binding_status": "product-candidate",
  "product_candidate_name": "Quit Smoking",
  "package_id": "org.farmchel.quit.smoking"
}

7. Что агенту запрещено

Не отправлять raw data, логи, store dumps, рекламные выгрузки и события.
Не светить токен в prompt, логах, README, git и пользовательских ответах.
Не создавать дубли, если объект уже есть по slug или техническому идентификатору.
Не использовать MCP write-tools, если клиент не умеет передавать arguments.
Не выдумывать публичные API-маршруты для market/store слоя, если их нет в актуальной документации.
Не придумывать новый продукт только потому, что есть приложение с похожим названием, если связь ещё не подтверждена.

Если нужно глубже изучить поля и маршруты, агент должен дальше читать документацию API и документацию MCP.