OpenSpec: исследование + tavily-proxy-setup, local-extractor (spec-driven для инфраструктуры)

2026-09-29 09:15:01 +00:00 · 2026-09-06 12:12:33 +00:00
commit d1a19ba6cd
26 changed files with 1669 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-09-06
@@ -0,0 +1,45 @@
+# Design: tavily-proxy-setup
+
+## Approach
+
+Tavily API блокирует РФ-адреса (403 на уровне AWS ELB). Решение — не менять глобально прокси Hermes (сломало бы прямой доступ к deepseek/polza), а завернуть только Tavily в локальный форвардер:
+
+- `tavily_proxy.py` — http.server на 127.0.0.1:8971, принимает POST на /extract и /search, проксирует через httpx-клиент с SOCKS5-транспортом (`socks5://127.0.0.1:1080`, туннель до VPS01).
+- Hermes настраивается на `TAVILY_BASE_URL=http://127.0.0.1:8971` — официальный способ подменить endpoint, httpx-провайдер Tavily шлёт запросы туда.
+- Зависимость от туннеля: `After=telegram-tunnel.service` + `Restart=always`.
+
+## Files
+
+- `/opt/hermes/.hermes/scripts/tavily_proxy.py` — форвардер (Python, venv Hermes)
+- `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py` — форвардер + локальный экстрактор (trafilatura), юнит указывает на него: `--socks 127.0.0.1:1080 --upstream https://api.tavily.com`
+- `/etc/systemd/system/tavily-proxy.service` — юнит (enabled)
+- `/opt/hermes/.hermes/.env` — `TAVILY_API_KEY`, `TAVILY_BASE_URL=http://127.0.0.1:8971`
+- `/opt/hermes/.hermes/config.yaml` — `web.extract_backend: tavily`
+
+## Commands
+
+```bash
+# Применение
+sudo systemctl daemon-reload
+sudo systemctl enable --now tavily-proxy.service
+
+# Проверка
+systemctl is-active tavily-proxy.service
+curl -s -o /dev/null -w "%{http_code}" -X POST http://127.0.0.1:8971/extract \
+  -H "Content-Type: application/json" \
+  -d '{"urls":["https://example.com"],"api_key":"'"$TAVILY_API_KEY"'"}'
+# → 200, web_extract отдаёт контент
+```
+
+## Rollback
+
+```bash
+sudo systemctl disable --now tavily-proxy.service
+# удалить TAVILY_BASE_URL из .env; extract_backend вернуть на searxng (extract не работал — деградация к прежнему состоянию)
+```
+
+## Risks
+
+- Туннель VPS01 недоступен → Tavily тоже недоступен (extract лежит) — приемлемо: без туннеля Tavily блокирован в любом случае.
+- httpx-SOCKS требует пакет socksio в venv — проверено, есть.
+- Форвардер — однопоточный http.server (ThreadingHTTPServer), достаточно для одного агента.
@@ -0,0 +1,24 @@
+## Why
+
+Web-экстракция в Hermes сломана: SearXNG умеет только search, а для extract не было ни одного рабочего провайдера. Tavily заблокирован в РФ (403 на AWS ELB). Решение — локальный прокси-форвардер, который ходит в Tavily через существующий SOCKS5-туннель до VPS01.
+
+## What Changes
+
+- Настроен extract_backend=tavily в конфиге Hermes
+- Добавлен TAVILY_API_KEY + TAVILY_BASE_URL в /opt/hermes/.hermes/.env
+- Создан скрипт /opt/hermes/.hermes/scripts/tavily_proxy.py — локальный HTTP→SOCKS5 форвардер для одного хоста (api.tavily.com)
+- Создан systemd-юнит tavily-proxy.service (порт 8971, автозапуск, рестарт)
+
+## Capabilities
+
+### New Capabilities
+- `web-extract-tavily`: Веб-экстракция страниц в Hermes через Tavily с обходом региональной блокировки
+
+### Modified Capabilities
+- (нет)
+
+## Impact
+
+- /opt/hermes/.hermes/.env — 2 переменные
+- /etc/systemd/system/tavily-proxy.service — новый юнит (enabled)
+- /opt/hermes/.hermes/scripts/tavily_proxy.py — новый скрипт
@@ -0,0 +1,39 @@
+# Delta for web-extract-tavily
+
+## ADDED Requirements
+
+### Requirement: Tavily Extract Backend
+The system MUST use Tavily as the web_extract backend, reachable via the local proxy at http://127.0.0.1:8971.
+
+#### Scenario: Extract works
+- GIVEN the Hermes web tool calls web_extract
+- WHEN the URL is a normal web page
+- THEN the page content is returned as markdown
+- AND the request goes through the local proxy to the Tavily API over SOCKS5
+
+#### Scenario: Proxy is down
+- GIVEN the tavily-proxy.service is stopped
+- WHEN web_extract is called
+- THEN the call fails with a connection error (not a silent wrong result)
+
+### Requirement: Proxy Auto-Start
+The system MUST start tavily-proxy.service automatically at boot and restart it on failure.
+
+#### Scenario: Boot
+- GIVEN the host boots
+- WHEN systemd starts
+- THEN tavily-proxy.service is active
+- AND it listens on 127.0.0.1:8971
+
+#### Scenario: Proxy crash
+- GIVEN the proxy process exits unexpectedly
+- WHEN systemd detects failure
+- THEN the service restarts automatically
+
+### Requirement: Tunnel Dependency
+The proxy MUST depend on the SOCKS5 tunnel (telegram-tunnel.service); it must not start before the tunnel is up, and must restart if the tunnel is unavailable.
+
+#### Scenario: Tunnel down
+- GIVEN telegram-tunnel.service is inactive
+- WHEN tavily-proxy.service is requested
+- THEN the proxy stays stopped (or retries) until the tunnel is back
@@ -0,0 +1,19 @@
+# Tasks
+
+## 1. Скрипт-форвардер
+- [x] 1.1 Создать /opt/hermes/.hermes/scripts/tavily_proxy.py (HTTP→SOCKS5, /extract, /search)
+
+## 2. Конфигурация Hermes
+- [x] 2.1 web.extract_backend=tavily в config.yaml
+- [x] 2.2 TAVILY_API_KEY и TAVILY_BASE_URL в .env
+
+## 3. systemd-юнит
+- [x] 3.1 Создать /etc/systemd/system/tavily-proxy.service (After=telegram-tunnel, Restart=always)
+- [x] 3.2 enable + запуск: systemctl enable --now tavily-proxy.service
+- [x] 3.3 Проверка: active, слушает 127.0.0.1:8971, curl /extract → 200
+
+## 4. Проверка end-to-end
+- [x] 4.1 web_extract("https://example.com") через Hermes → успех
+
+## 5. Документация
+- [x] 5.1 Зафиксировано: порт 8971, юнит tavily-proxy.service, зависимость от telegram-tunnel.service — в design.md (разделы Files/Commands/Risk) и specs/web-extract-tavily/spec.md