tg-use

tg-use — тестировщик/копировщик Telegram-ботов через web.telegram.org (клиент /k/). CLI-«руки» + скилл для агент-харнесов: мозг — модель харнеса, CLI обращений к внешним моделям не содержит вовсе.

Два режима работы browser-use

browser-use умеет работать двумя способами, и разница принципиальная:

1. Browser Harness CLI + скилл — наш путь, рекомендуемый. Браузер подключается к харнесу (Claude Code, Codex, OpenCode…), и решения принимает модель харнеса. Наш tg-use.py — только «руки»: чтение состояния, клики по кнопкам, артефакты, прогон записанных сценариев. Логика «куда кликать дальше» живёт в скилле (.claude/skills/tg-use/SKILL.md), а не в коде.
2. Встроенный агент Agent(task=..., llm=...) со своим LLM-циклом — в этом проекте так не делаем. Этот режим дублирует мозг харнеса вторым (медленным и ломким) контуром: ключи, endpoint'ы, таймауты, fallback-модели. Был использован в v1 до 2026-09-20 и отвергнут владельцем вместе с z.ai-конфигом.

Правило: использовать browser-use skill install, а не писать своего агента. В CLI нет ни одного обращения к внешней модели — проверяется test_skeleton.py.

Установка

Из клона:

pip3 install -r requirements.txt          # в прокси-окружении: env -u ALL_PROXY -u all_proxy pip3 ...
python3 -m playwright install chromium
browser-use skill install                 # подключить браузер к харнесу

Из PyPI (Python ≥3.11): pipx install tg-use — те же команды без python3 tg-use.py: tg-use login, tg-use open <@bot>, tg-use state, …; tg-use skill-install ставит скилл агенту (команды в нём переписываются на tg-use).

Логин

python3 tg-use.py login   # откроется окно с QR — отсканируй телефоном один раз

Сессия сохраняется в ~/.tg-use-agent-profile (= пароль от аккаунта) — повторный запуск подхватит её без QR. При первом запуске macOS спросит доступ к «Chromium Safe Storage»: вводи пароль входа и жми «Разрешать всегда» — это шифрование cookies, без него сессия не переживёт перезапуск.

Browser Harness из коробки цепляется к обычному Chrome с его родным профилем и наш изолированный профиль не даёт, поэтому профильный запуск остаётся за CLI: login держит Chromium на нашем профиле и пишет его адрес в ~/.tg-use-cdp; state/click/save/test подключаются к этому живому браузеру. Харнес может работать с тем же окном через browser-use (BU_CDP_URL=$(cat ~/.tg-use-cdp)).

Команды (руки; «куда кликать дальше» решает харнес)

Дальше — по скиллу .claude/skills/tg-use/SKILL.md: малый обход (глубина ≤2, до ~5 состояний) и прогон сценариев. Безопасность: темп 2–3 c между действиями, только диалоги с ботами, скраб токенов в выводе, PNG не сохраняем.

Тесты и категории

Граница категорий — цена ошибки. unit: offline-скрипты, безопасный дефолт — python3 test_skeleton.py && python3 test_crawl.py && python3 test_hands.py. state/open — live_read (чтение/открытие чата без отправок); click/save — live_write (обратимые действия в диалоге с ботом); test/login — live_write_danger (необратимая отправка боту / полный доступ к аккаунту). Гейты — в .claude/settings.json: владелец 2026-09-20 разрешил все подкоманды целиком (Bash(python3 tg-use.py:*)), категории остались описанием цены ошибки, а не спросом харнеса.