Metadata-Version: 2.4
Name: tg-use
Version: 0.1.1
Summary: Руки для агент-харнеса: тестирование Telegram-ботов через web.telegram.org (CLI без LLM)
Author: axisrow
License-Expression: MIT
Project-URL: Homepage, https://github.com/axisrow/tg-use
Requires-Python: <4.0,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: browser-use>=0.13.8
Dynamic: license-file

# 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` — только «руки»: чтение состояния, клики по кнопкам, артефакты,
   прогон записанных сценариев. Логика «куда кликать дальше» живёт в скилле
   (`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`.

## Установка

Из клона:

```sh
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`).

## Логин

```sh
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)`).

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

| Команда | Что делает |
|---|---|
| `tg-use.py login` | headed-браузер с persistent-профилем; адрес → `~/.tg-use-cdp` |
| `tg-use.py open <@bot>` | открыть чат бота: поиск webk по username + клик по результату, guard по peer-id в hash; без отправок |
| `tg-use.py state` | JSON: текст последнего сообщения бота + подписи кнопок |
| `tg-use.py click "<label>"` | нажать inline-кнопку, вернуть новое состояние; отсутствие кнопки/реакции = ошибка (exit 1) |
| `tg-use.py save [--from id --button label] [--bot @name]` | дописать состояние/ребро в `artifacts/flow.json` + `artifacts/flow.md` (Mermaid) |
| `tg-use.py test scenario.json` | шаги `{"do": {"send"/"click"}, "expect": {"contains"/"regex"}}` → `artifacts/report.json`; падение = exit 1 |

Дальше — по скиллу `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:*)`), категории остались описанием цены ошибки,
а не спросом харнеса.
