Среда вашего ассистента

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

Эта страница написана и для вас, и для самого ассистента: ассистент может загрузить её по адресу https://plank.md/help/environment.md, когда ему нужно понять собственные ограничения.

Где работает ваш ассистент

Ассистент работает на удалённой машине, которую вы не видите и не трогаете напрямую — между вами и ним нет общего экрана, терминала или браузера.

• Он сам выполняет команды. Он никогда не попросит вас «запустить это в терминале» — он делает работу на машине за вас.
• Никаких настольных приложений. Он не может управлять настольными приложениями на машине.
• Сначала он пробует API сервиса и лишь потом спрашивает разрешения открыть облачный браузер. Когда для работы нужен сайт с входом в учётную запись, ассистент сперва ищет путь через API и лишь затем просит открыть приватный облачный браузер через панель «Браузер» — после этого он работает внутри сайта. См. Доступ к браузеру. (Это управляемый облачный браузер, а не браузер на самой машине. Доступ к браузеру — это бета-функция — включите Доступ к браузеру в Настройки → Параметры → Бета-функции.)
• Он сообщает, что сделал. Поскольку вы не можете наблюдать за ним из-за плеча, он рассказывает, что запустил и что получил в ответ.

Вход в другие сервисы

Для API-ключа или токена ассистент просто попросит его у вас. Для сайта, на который вы входите, используйте панель «Браузер» (см. Доступ к браузеру). Для подключения через OAuth привязка учётной записи использует простую передачу:

1. Ассистент даёт вам ссылку для входа.
2. Вы открываете её в своём собственном браузере и подтверждаете доступ.
3. Вы попадёте на страницу, которая не загружается (часто это адрес localhost) — это нормально.
4. Вы копируете этот итоговый адрес из адресной строки браузера и вставляете его обратно в чат.
5. Ассистент завершает подключение, исходя из этого.

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

Что сохраняется, а что нет

Некоторые места на машине сохраняют своё содержимое; другие очищаются при каждом перезапуске рабочего пространства.

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

У общих чатов своя домашняя папка

Личный чат работает на вашей собственной машине, общий командный чат — на машине рабочего пространства. Оба видят одни и те же файлы рабочего пространства, но приватная область настроек у каждого своя. Вход или установка, сохранённые там в личном чате, не видны в общем чате, и наоборот. Поэтому ассистент хранит подключения и пакеты, нужные скриптам, рядом со скриптами рабочего пространства, в scripts/<provider>/, — это единственное место, которое видят чаты обоих видов.

Для ассистента: никогда не делайте npm install в .opencode/node_modules. Это дерево плагинов из образа машины, подмонтированное в рабочее пространство: то, что вы туда добавите, существует только на одной машине и пропадает при её пересоздании, а .opencode/package.json при каждом запуске перезаписывается из образа. Зависимости скрипта ставьте рядом с ним: npm install --prefix scripts/<provider> <пакет>. Подробнее: Скрипты рабочего пространства.

Для ассистента: подробности о том, что установлено на машине — имя интерпретатора, где лежат пакеты Python, каких привычных утилит нет и куда можно писать временные файлы, — собраны в Запуске команд на машине. Прочитайте это перед первой командой оболочки в рабочем пространстве.

Ваше рабочее пространство засыпает в простое

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

Одно следствие: ассистент не может рассчитывать на то, что запущенная им программа останется работать между вашими запросами. Вместо того чтобы оставлять что-то «работающим в фоне», он записывает результаты в ваши файлы, чтобы следующий запрос продолжил с этого места. (См. Рабочие пространства о том, что является общим для рабочих пространств, и о поведении «одна задача за раз».)

Каждое рабочее пространство хранит свои учётные записи

У вас может быть одно рабочее пространство для личных дел и другое для работы, каждое привязано к разным учётным записям. Ассистент держит каждое подключение в рамках того рабочего пространства, которому оно принадлежит — учётные данные, настроенные в одном рабочем пространстве, никогда не используются повторно в другом. Именно это не даёт личной учётной записи попасть в рабочее пространство для работы и наоборот. Внутри одного рабочего пространства подключение, сохранённое в scripts/, работает и в личных, и в общих чатах; сохранённое в домашней папке чата — нет.

Подключение внешних сервисов

Когда вы просите ассистента подключить внешний сервис, он следует аккуратному соглашению, чтобы подключение появилось на боковой панели Интеграции: он сохраняет скрипт в scripts/<provider>/<service>/ и помечает его заголовком @plank-integration. Вам не нужно знать подробности — но если интересно, Скрипты рабочего пространства и боковая панель объясняет заголовок, а Интеграции описывает готовые подключения.

Как разрешить ассистенту отвечать на входящие сообщения

Помимо работы по расписанию, ваш ассистент может реагировать на входящие события — например, на сообщение в Telegram или WhatsApp. Вы подключаете канал в чате (для Telegram: создаёте бота через BotFather и передаёте токен; для WhatsApp Business: приложение Meta с номером телефона и токеном доступа), а ассистент настраивает триггер, который будит его при поступлении сообщения. Вы остаётесь хозяином того, когда он отвечает — на каждое сообщение или только когда его упоминают — и его постоянных инструкций, в разделе Настройки → Автоматизации → Триггеры. Ассистент тоже может их менять, и вы будете видеть, кто что изменил.

Запуск скриптов с панели

HTML-панель в вашем рабочем пространстве может запускать один из этих скриптов нажатием кнопки. У таких запусков по кнопке есть разумные ограничители — короткая пауза для каждого скрипта, лимит на число одновременных запусков и ограничение по времени, чтобы ничто не вышло из-под контроля. Интерактивные HTML-панели описывают, как такое настроить.

Изображения и именование в HTML-файлах

Когда HTML-файл показывает изображение из вашего рабочего пространства, путь к изображению читается относительно папки, в которой находится сам HTML-файл, а не относительно корня рабочего пространства. Поэтому chart.png загружается из той же папки, images/q4.png — из подпапки, а ../shared/logo.png — на уровень выше. Ведущий слеш (/chart.png) трактуется так же, как из той же папки, а не как корень рабочего пространства, поэтому корневые или абсолютные пути не загрузятся. Самая надёжная привычка: держите изображение в той же папке, что и HTML-файл, и ссылайтесь на него по имени. Интерактивные HTML-панели содержат полные правила.

HTML-файлы также получают описательные, отражающие содержимое имена — q4-revenue-report.html, acme-invoice.html — а не общий index.html. Со временем рабочее пространство накапливает множество HTML-файлов в множестве папок, и осмысленные имена помогают легко находить их и различать.