Skip to content

USER_GUIDE.md

Latest commit

 

History

History
273 lines (210 loc) · 21.3 KB

USER_GUIDE.md

File metadata and controls

273 lines (210 loc) · 21.3 KB
Raw

Руководство пользователя (Telegram)

Первый запуск

  1. Отправьте /start — короткая сводка (репо, агент, режим) и кнопки.
  2. Репозиторий:
    • если на сервере задан DEFAULT_REPO_URL — у нового пользователя (первый /start) репо подставится автоматически;
    • иначе в Mini App → Репо → Войти через GitHub → выбрать репозиторий (закрепится как активный);
    • или вручную любой HTTPS GitHub URL через бота / форму на вкладке Репо: 
      /repo add https://github.com/you/repo
      Ветка по умолчанию — dev (или DEFAULT_BRANCH на сервере). Явно: 
      /repo add https://github.com/you/repo dev
    • Cursor должен иметь доступ к выбранному репо в Cursor Settings → GitHub.
  3. /do — кодить сразу в выбранной базовой ветке; /ask — спросить; /plan или /task — сначала план, затем ожидание approve владельца и выполнение (AUTO_APPROVE_PLANS=true убирает кнопки и сразу enqueue DO).
  4. Отправьте текст, голосовое или фото/скриншот.

Без активного репозитория бот не примет промпт.

Режимы работы

Режим Команда Иконка Поведение
Чат /ask ❓ Ответ без правок кода, свободным тоном под Telegram. Опросник A/B/C — только если без выбора нельзя спланировать реализацию.
План /plan, /task 📋 Read-only исследование, затем owner approve → DO (AUTO_APPROVE_PLANS, по умолчанию выкл).
Действие /do ⚡ Сразу пишет в выбранную базовую ветку (dev и т.п.). Для main/master — изолированная ветка + PR. Merge/deploy по-прежнему запрещены.
  • /mode — текущий режим и inline-кнопки переключения.
  • /new — новый слот агента (старые сохраняются), режим сбрасывается в чат.

Токены Cursor (mt / mt2 / mt3)

Если на сервере задан хотя бы один доп. ключ (CURSOR_API_KEY_MT2 и/или CURSOR_API_KEY_MT3), под кнопками моделей появляется ряд 🔑 mt / 🔑 mt2 / 🔑 mt3 — только для заполненных ключей. Переключение аккаунта Cursor, от которого запускаются агенты.

  • Выбор сохраняется per-user и применяется к новым агентам.
  • Токен фиксируется за агентом при первом запуске: уже созданный агент продолжит работать на своём токене (Cursor не позволяет резюмить агента другим ключом). Чтобы задача ушла на новый токен — создайте нового агента: /new.
  • Текущий токен виден в /status и /start (строка «Токен»).

Команды

Видимое меню / в Telegram — компактное; /help и /mode работают как алиасы (/help = /start, /mode = /status), но не показаны в меню, чтобы не дублировать пункты.

Команда Описание
/start Инструкция и статус (алиас: /help)
/ask, /plan, /do, /task Чат / план→approve→do / действие (сразу write) / задача через план
/status Режим, модель, токен, active run, диагностика Cursor (/status refresh)
/agents Список слотов; /agents sync — audit drift (только owner, без DELETE)
/new Новый слот агента (до AGENT_SLOTS_MAX)
/repo Список репозиториев; /repo alias — переключить; /repo add … — добавить
/remember текст Сохранить заметку в память (активное репо); скрыта из меню /, но работает
/memory Последние записи памяти активного репо (как кнопка «Память»); скрыта из меню /, но работает
/memory запрос Семантический поиск по памяти
/cancel Отменить run и очистить очередь
/jobs Durable очередь и статусы задач
/approvals Ожидающие owner decisions (план и рискованные действия; по умолчанию нужны)
/rollback Откат прода на предыдущий (или указанный) SHA — только owner, с кнопкой подтверждения
/dashboard Mini App: голос, агенты, репо, чаты Cursor, очередь

Модель Cursor

  • В Telegram: presets + динамические модели из каталога Cursor (короткие fingerprint в callback). Во время run — только «Отменить»; смена модели через /status.
  • В Mini App (Голос / Работа): тот же каталог; users.cursor_model_key (+ опционально cursor_model_params) применяется к следующему run.
  • Usage (in/out/total) показывается в footer run, job cards и dashboard; квоты не режутся.
  • Удаление слота: cancel → archive remote → удалить локально. Permanent Cursor DELETE — только owner после явного confirm (не из обычного delete).

Сообщения во время активного run ставятся в durable очередь (Postgres + ARQ). Отправка из Mini App во время busy run тоже ставит задачу в очередь. /status показывает реальную очередь и active run. Если Cursor уже закончил в облаке, а Telegram «завис» — reconciler догоняет статус и обновляет сообщение.

Репозитории

/repo                          — список с кнопками
/repo myalias                  — сделать активным
/repo add alias https://github.com/org/repo [branch]

При смене репо активный слот переключается на новый URL; Cursor-агент сбрасывается (новый диалог) — агент привязан к репозиторию.

Если сервер в строгом режиме (REPOSITORY_POLICY_JSON с непустым списком), добавить можно только URL и ветки из списка сервера. Сообщение об ошибке скажет, чего не хватает: репозиторий не разрешён или ветка не разрешена. Пустой {"repositories":[]} — открытый режим (любой HTTPS GitHub URL; запись в main/master всё равно запрещена). Рекомендуемый дефолт для личного пульта — открытый режим + закрепление через GitHub OAuth.

В Mini App на вкладке Репо: Войти через GitHub → список ваших репо → тап закрепляет URL и делает его активным (нужны GITHUB_OAUTH_CLIENT_ID / GITHUB_OAUTH_CLIENT_SECRET на сервере).

Агенты (несколько сессий Cursor)

До 8 именованных слотов на пользователя (лимит AGENT_SLOTS_MAX на сервере):

/agents                        — список с кнопками
  • Кнопка «Агенты» в /start и /status — тот же список.
  • + Новый агент — новый слот со случайным коротким именем из пула (Лиса, Якорь, Компас…); предыдущие слоты не архивируются.
  • После первого осмысленного сообщения авто-имя заменится на ваш текст (не [Instruction] и не «привет»).
  • Переименовать: кнопка ✏️ в списке или /agents rename Метрика — баг с отчётом (для активного).
  • Удалить: кнопка 🗑 (с подтверждением) или /agents delete (удаляет активного). Последнего агента удалить нельзя.
  • В Mini App (вкладка Работа): переключение слотов, переименование, + Новый агент, удаление — те же операции, что в Telegram.
  • Переключение слота — resume сохранённого cursor_agent_id в Cursor (история диалога сохраняется).
  • /new — то же, что «+ Новый агент», плюс сброс режима в чат.
  • Каждый слот помнит своё репо; при активации слота активное репо в /repo синхронизируется.

Память

  • Автоматически: каждый завершённый run сохраняется в память.
  • Вручную: /remember dev — основная ветка для фич.
  • Recall: в режимах ask/plan топ-K релевантных записей подмешиваются в промпт.
  • Список: кнопка «Память» и /memory без аргументов — последние записи активного репо.
  • Поиск: /memory как деплоить на прод — семантический поиск по активному репо.

В списке памяти кнопки ↻ #id — повторить промпт из истории (для всех видимых записей); PR — ссылка если был.

Текст, голос, фото

Текст

Обычное сообщение (не команда) → промпт в текущем режиме.

Голос

В чате Telegram: голос транскрибируется и сразу уходит в текущий режим (VOICE_REQUIRE_CONFIRM=true вернёт кнопку «Проверьте расшифровку»). Бот не отвечает голосовым в чате.

Вкладки Mini App: Работа (агенты, текстовый composer, скрины, очередь), Голос, Лента, Апрувы, Репо.

На Работе к запросу можно прикрепить скрины (PNG/JPEG/WebP/GIF) — кнопка Скрин или вставка из буфера (Ctrl+V). Без текста уйдёт дефолтный промпт «Разбери скриншот…». Картинки уходят в тот же durable job, что и текст (Cursor vision). Пока агент занят, новый запрос встаёт в очередь (счётчик «в очереди N»).

На Голосе: переключатель Спросить / План / Сделать; realtime STT → задача (без экрана подтверждения при VOICE_REQUIRE_CONFIRM=false). Устные ответы — разговорный TTS-брифинг после завершения (или «План готов — глянь и скажи, делать или нет» при awaiting_approval). Без метрик control room в речи; mid-run TTS выключен по умолчанию (VOICE_MILESTONE_TTS=false). Пока идёт run, можно отправить ещё задачу — она в очередь. Голос не одобряет план сам — approve только у владельца (вкладка Апрувы или /approvals).

Каждый ask/plan/do получает situation brief в промпт (очередь, approve, слот/репо) — для агента, не для озвучки пользователю.

Вход в Mini App

  • Основной способ: /dashboard внутри Telegram — вход по подписанному initData, без паролей.
  • С любого браузера/устройства: откройте HTTPS-сайт пульта → кнопка Telegram Login Widget / кнопка OAuth → подтвердите в Telegram → та же session cookie, что и у Mini App. Если виджет пустой — используйте «Открыть вход Telegram» (после подтверждения вернёт на сайт с сессией). Домен в BotFather /setdomain = host из WEBAPP_BASE_URL. (без www и без https://); на экране появится запасная ссылка «Открыть вход Telegram».
  • Доступ только для allowlist (OWNER / OPERATOR / VIEWER).
  • Passkey с UI снят; backend endpoints оставлены только как legacy.

Фото

  • Одно фото, альбом или текст + картинки подряд.
  • Альбомы без пересылки собираются в один run (пауза до MEDIA_GROUP_DELAY_SEC, по умолчанию 6 с).
  • Caption / отдельное текстовое сообщение = промпт; без текста — «Разбери скриншот…».
  • Бот ждёт ~PROMPT_COALESCE_SEC (по умолчанию 7 с) тишины после последнего текста/фото и склеивает их в один run — чтобы подпись не уехала без картинок.
  • До PHOTO_MAX_COUNT изображений за запрос (по умолчанию 5, лимит Cloud Agents API v1; лишние отклоняются с ошибкой, без тихого обрезания).
  • Поддерживаются JPEG, PNG, WebP, GIF (как photo или document).
  • PDF и DOCX — отдельный handler (текст извлекается в промпт).
  • Видео, стикеры, аудио и прочие вложения — ответ: «поддерживается: текст, голос, фото, PDF/DOCX».

Пересланные сообщения

Сценарий «контекст из другого чата»:

  1. Перешлите одно или несколько сообщений — бот собирает их в буфер (run не стартует).
  2. Напишите свой вопрос (текст или голосовое) — всё уходит одной задачей агенту.
  3. Если вопрос не написали — через 25 сек после последней пересылки контекст отправится автоматически: агент разберёт задачу по коду репозитория (причина, как починить или внедрить), а не только перескажет чат.
  • До 25 пересланных блоков в одной пачке; альбом = один блок.
  • До PHOTO_MAX_COUNT изображений в одном run (как для фото).
  • Видео, стикеры, PDF в пересылках пропускаются с пометкой в промпте.
  • /status показывает, сколько пересланных ждёт в буфере.
  • /cancel и /new очищают буфер пересылок.

Порядок: сначала пересылки, потом ваш вопрос. Если написать вопрос до пересылок — это отдельная задача.

Очередь и отмена

Текстовые задачи сохраняются в PostgreSQL в зашифрованном виде и отправляются в durable Redis/ARQ queue. Очередь восстанавливается после рестарта; один actor выполняет не более одного Cursor run одновременно.

Отмена:

  • /cancel или кнопка «Отменить» на сообщении run

  • Очищает очередь, буфер пересылок и пытается отменить активный run в Cursor

  • Ответ агента цитирует ваше последнее сообщение (reply), чтобы в длинном чате было видно связку вопрос → ответ.

  • Во время run — компактная клавиатура (только «Отменить»); режим и модель — через /status.

  • Ответ обновляется в одном сообщении (не спамит чат).

  • Если финальный ответ не помещается целиком, бот дополнительно отправляет полный .md-файл.

  • Пока агент работает: анимация «Подключаю агента», затем строка «Агент работает» со спиннером и индикатор «печатает» в Telegram.

  • Пока идёт run, в сообщении может быть видна разметка (##, **) — это нормально; после завершения текст форматируется для Telegram (жирный, код, ссылки).

  • Видны вызовы инструментов (🔧/🔄/✅).

  • По завершении — время, токены (итого), ссылка на PR (do), ссылка на агента в Cursor.

  • При ошибке — кнопка «Повторить».

Права доступа

  • viewer — read-only.
  • operator — read/plan/request write, без approve.
  • owner — approve/reject/revision и /rollback.
  • Роль проверяется server-side для Telegram, callback, API и worker.

Самосовершенствование BeachOps (opt-in)

По умолчанию выключено. Включение — в Mini App, не через .env на каждый раз:

  1. Откройте вкладку Апрувы → блок Самосовершенствование → Включить.
  2. Цель — активный репозиторий BeachOps (или SELF_IMPROVE_REPO_URL на сервере, если задан).
  3. Пока режим выключен, агент не получает safety-префикс «править сам control plane».
  4. Выкат: push агента в dev (или main) → зелёный CI → auto-deploy на прод. Прямой push в main агенту запрещён; база self-improve — dev. Откат: /rollback.

Опционально в .env: SELF_IMPROVE_REPO_URL, SELF_IMPROVE_BRANCHES=dev (дефолтная цель и ветки).

Типичные сценарии

Вопрос по коду (без правок)

/ask
Как устроена авторизация в middleware?

Спланировать фичу

/plan
Добавить эндпоинт /health с проверкой Postgres

План придёт в чат (длинный — ещё и файлом). Если агент задал уточняющие вопросы (A/B/C) — ответьте следующим сообщением, и он доделает план.

Реализовать в базовой ветке

/do
Реализуй /health как в плане выше

Агент коммитит в выбранную базовую ветку (dev и т.п.). Для базы main/master создаётся изолированная ветка + PR.

Через план (по умолчанию)

Отправьте задачу через /plan или /task. После плана владелец нажимает одноразовую «Одобрить»; дальше тот же write-path, что у /do:

/task
Реализуй /health как в плане выше

С AUTO_APPROVE_PLANS=true DO стартует сразу после плана, без кнопок.

Скриншот бага

Отправить фото с caption: «Почему эта кнопка не работает на мобилке?»

Запомнить контекст

/remember PROD: 185.244.49.94, деплой через deploy-to-prod.ps1