session close: local-extractor tested+archived, gitverse repo+push, systemd stays forward

2026-09-29 09:15:01 +00:00 · 2026-09-06 12:49:07 +00:00
parent 0a89884245
commit 92bc13e363
9 changed files with 186 additions and 24 deletions
@@ -3,25 +3,24 @@
 Обновлено: 2026-09-06 (сессия @session:default/20260906_...)
 ## Текущее состояние
-Лаборатория spec-driven подхода (OpenSpec CLI 1.12.0) для задач настройки инфраструктуры Hermes/homelab. Цикл propose→apply→archive работает; 2 change заархивированы, 1 открыт. Tavily-прокси (web_extract) работает end-to-end. Локальный экстрактор написан, ждёт сетевых тестов.
+Лаборатория spec-driven подхода (OpenSpec CLI 1.12.0) для задач настройки инфраструктуры Hermes/homelab. Цикл propose→apply→archive работает; 3 change заархивированы. Tavily-прокси (web_extract) работает end-to-end в forward-режиме (решение по задаче 5: оставить как есть). Локальный экстрактор (trafilatura) написан и протестирован (2.2/2.3 зелёные), change заархивирован. Репозиторий создан на gitverse.ru, main запушен.
 ## Сделано
 - [x] OpenSpec CLI установлен (npm, 1.12.0), лаба инициализирована с --tools hermes (6 скиллов)
 - [x] config.yaml с инфраструктурным контекстом (systemd, docker, /opt/<svc>/, gitverse)
 - [x] change tavily-proxy-setup — ЗААРХИВИРОВАН (delta → specs/web-extract-tavily/spec.md)
 - [x] web_extract работает: Hermes → 8971 → SOCKS5-туннель → Tavily (HTTP 200, контент Example Domain)
- [x] change local-extractor — ОТКРЫТ (4/4 артефакта, валиден): trafilatura 2.2.0 в venv, local-режим в tavily_extract_proxy.py
+- [x] change local-extractor — ЗААРХИВИРОВАН: trafilatura 2.2.0, local-режим в tavily_extract_proxy.py, тесты 2.2/2.3 зелёные (example.com и github через --local; tavily.com — geo-блок из РФ — через --local-socks 127.0.0.1:1080, HTTP 200)
- [x] git-репо + README + remote origin → gitverse.ru (токен в obsidian)
+- [x] Репозиторий создан на gitverse.ru (kpa39l/openspec-lab), git push -u origin main выполнен
 - [x] systemd tavily-proxy.service — решение по задаче 5: ОСТАВЛЕН forward-режим (облачный Tavily через туннель) — рабочий провайдер без изменений
 ## В работе / Следующие шаги
- [ ] Сетевые тесты local-режима (tasks 2.2 example.com через --local, 2.3 через --local-socks) — требуют присутствия пользователя (внешние запросы блокируются)
+- (ничего — все 5 задач закрыты; лаба в стабильном состоянии)
 - [ ] После тестов: openspec archive local-extractor
 - [ ] Создать репозиторий на gitverse.ru и git push -u origin main (внешнее действие, ждёт подтверждения)
 ## Как запустить / проверить
 ```bash
 cd /opt/hermes/openspec-lab
-openspec validate local-extractor
+openspec validate  # все changes
 openspec status --change local-extractor
 # локальный экстрактор (тест)
 ./venv/bin/python .hermes/scripts/tavily_extract_proxy.py --port 8972 --local   # путь: /opt/hermes/.hermes/hermes-agent/venv/bin/python
@@ -31,12 +30,13 @@ systemctl status tavily-proxy   # порт 8971, forward через туннел
 ```
 ## Ключевые артефакты
- /opt/hermes/openspec-lab/openspec/changes/local-extractor/ — открытый change (4 артефакта)
+- /opt/hermes/openspec-lab/openspec/specs/web-extract-tavily/spec.md — main spec про forward-прокси
- /opt/hermes/openspec-lab/openspec/specs/web-extract-tavily/spec.md — main spec после archive
+- /opt/hermes/openspec-lab/openspec/specs/web-extract-local/spec.md — main spec про local-экстрактор (после archive local-extractor)
 - /opt/hermes/openspec-lab/openspec/changes/archive/2026-09-06-local-extractor/
 - /opt/hermes/.hermes/scripts/tavily_extract_proxy.py — прокси + local-режим
- /etc/systemd/system/tavily-proxy.service — юнит (forward)
+- /etc/systemd/system/tavily-proxy.service — юнит (forward, без изменений)
 - /opt/hermes/openspec-lab/.hermes/skills/openspec-*/ — Hermes-скиллы OpenSpec
 - gitverse: https://gitverse.ru/kpa39l/openspec-lab (remote origin: https://kpa39l:<TOKEN>@gitverse.ru/kpa39l/openspec-lab.git)
 ## Открытые вопросы
- Делать ли push на gitverse (нужен репозиторий + подтверждение)
+- (нет)
 - Переключать ли systemd на --local после успешных тестов (отказ от облачного Tavily) или оставить forward как основной
@@ -16,7 +16,12 @@
 | 2026-09-06 | trafilatura 2.2.0 в venv; local-режим в tavily_extract_proxy.py (--local, --local-socks) | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | systemd-юнит переведён на tavily_extract_proxy.py (forward-режим сохранён) | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | git-репо openspec-lab + README + remote gitverse (токен obsidian) | ✅ закрыта | @session:default/20260906_... |
-| 2026-09-06 | Тест local-режима 2.2 (example.com через --local) | 🔵 открыта | |
+| 2026-09-06 | Тест local-режима 2.2 (example.com через --local) | ✅ | @session:default/20260906_... |
-| 2026-09-06 | Тест local-режима 2.3 (страница через --local-socks) | 🔵 открыта | |
+| 2026-09-06 | Тест local-режима 2.3 (страница через --local-socks) | ✅ | @session:default/20260906_... |
-| 2026-09-06 | openspec archive local-extractor (после зелёных тестов) | 🔵 открыта | |
+| 2026-09-06 | openspec archive local-extractor (после зелёных тестов) | ✅ | @session:default/20260906_... |
-| 2026-09-06 | Создать репо на gitverse.ru, git push -u origin main | 🔵 открыта | |
+| 2026-09-06 | Создать репо на gitverse.ru, git push -u origin main | ✅ | @session:default/20260906_... |
 | 2026-09-06 | Тест 2.2: example.com + github.com через --local (HTTP 200, контент) | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | Тест 2.3: tavily.com (geo-блок из РФ) через --local-socks 127.0.0.1:1080 (HTTP 200) | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | openspec archive local-extractor (валиден, заархивирован, новая spec web-extract-local) | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | Репо создано на gitverse (kpa39l/openspec-lab, HTTP 201), push -u origin main OK | ✅ закрыта | @session:default/20260906_... |
 | 2026-09-06 | Решение по systemd (задача 5): оставить forward-режим — подтверждено пользователем | ✅ закрыта | @session:default/20260906_... |
@@ -46,12 +46,29 @@ openspec init --tools hermes --force --no-animation   # в /opt/hermes/openspec-
 ```bash
 git init -b main && git add ... (НЕ git add -A — зависает; добавлять файлы поимённо)
 git -c user.name=... -c user.email=... commit -m "..."
-git remote add origin https://estorozhenko:<TOKEN>@gitverse.ru/estorozhenko/openspec-lab.git
+git remote add origin https://estorozhenko:<TOKEN>@gitverse.ru/estorozhenko/openspec-lab.git   # УСТАРЕЛО: логин kpa39l, см. ниже
 ```
 Токен: obsidian homelab/gitverse.ru.md (dc52c489...) и homelab/gitea.nixg.ru/«Токен для gitverse.ru.md» (a8c8f69e..., для зеркала gitea).
 - Питфол: `git add -A` зависал (блок сессии) — добавлять файлы явно поимённо.
 - Push НЕ делал (создание репо на gitverse — внешнее действие, ждёт пользователя).
 ### Сетевые тесты local-режима (2.2 / 2.3) — ЗЕЛЁНЫЕ
 Запуск: `/opt/hermes/.hermes/hermes-agent/venv/bin/python /opt/hermes/.hermes/scripts/tavily_extract_proxy.py --port 8972 --local`.
 - 2.2: `curl POST 127.0.0.1:8972/extract {"urls":["https://example.com"]}` → HTTP 200, 0.98s, `raw_content` = «This domain is for use in documentation examples...». GitHub: `https://github.com/` → HTTP 200, 0.84s, полный текст главной страницы. Хвост: процессы убиты, порт 8972 свободен.
 - 2.3: `--local-socks 127.0.0.1:1080` (туннель telegram-tunnel active) на `https://tavily.com/` (geo-блок из РФ) → HTTP 200, 3.7s, контент Tavily извлечён (302 → www.tavily.com → 200). Туннель подтверждён.
 - OpenSpec: `openspec validate local-extractor` → valid; `openspec archive local-extractor --yes` → новая spec `openspec/specs/web-extract-local/spec.md` (+3), change → archive/2026-09-06-local-extractor.
 ### GitVerse API (создание репозитория)
 - UI/SPA: `https://gitverse.ru/api/v1/...` отдаёт HTML (Next.js) — НЕ JSON. Старые ссылки /api/v1 из WALKTHROUGH не работают.
 - Правильный API: `https://api.gitverse.ru` (Gitea-совместимый: /user/repos, /repos/{owner}/{repo}/...)
 - Создание: `POST https://api.gitverse.ru/user/repos` с `Authorization: Bearer <токен>` + `Accept: application/vnd.gitverse.object+json;version=1` → HTTP 201, id 327605.
 - ВАЖНО: фактический логин аккаунта = **kpa39l** (не estorozhenko!). Remote пришлось поправить: `git remote set-url origin https://kpa39l:<TOKEN>@gitverse.ru/kpa39l/openspec-lab.git`. Репо: https://gitverse.ru/kpa39l/openspec-lab.
 - `git push -u origin main` → `* [new branch] main -> main`, tracking установлен.
 ### Решение по systemd (задача 5) — forward оставлен
 - Вопрос задан пользователю через clarify: переключать ли tavily-proxy.service на --local.
 - Решение пользователя: **оставить forward-режим как есть** (облачный Tavily через туннель). Юнит не менялся: ExecStart=... --port 8971 --socks 127.0.0.1:1080 --upstream https://api.tavily.com.
 ## Подводные камни (сводно)
 1. openspec init: нет --no-init-git.
 2. trafilatura.fetch_url не принимает timeout (2.2.0).
@@ -60,10 +77,8 @@ git remote add origin https://estorozhenko:<TOKEN>@gitverse.ru/estorozhenko/open
 5. Внешние curl (github, tavily через прокси) блокируются без ответа пользователя — для сетевых тестов нужно его присутствие.
 6. Прокси Hermes глобально не трогать (deepseek/polza прямые).
 7. Tavily требует туннель; .env — бэкап перед правкой.
 8. gitverse.ru/api/v1/* → HTML (SPA). Только api.gitverse.ru отдаёт JSON; логин аккаунта kpa39l.
 ## Как продолжить (следующая сессия)
-1. Спросить/получить подтверждение на сетевые тесты 2.2/2.3 (или выполнить при пользователе).
+1. Все 5 задач закрыты (2.2/2.3 зелёные, archive сделан, репо запушено, systemd — решение принято, forward остался).
-2. Прогнать: curl POST 127.0.0.1:8972/extract (--local) на example.com и github-страницу; --local-socks для заблокированных.
+2. Лаба в стабильном состоянии. Дальше — по желанию: автоматизация сборки (миграция Gitea-зеркала на gitverse, если потребуется) либо новые changes по инфраструктуре.
 3. openspec validate + archive local-extractor.
 4. Создать репо на gitverse (UI/API), git push -u origin main.
 5. Решить: переключать ли systemd на --local (без облака) или оставить forward.
@@ -0,0 +1,2 @@
 schema: spec-driven
 created: 2026-09-06
@@ -0,0 +1,46 @@
 # Design: local-extractor
 ## Approach
 Расширить существующий `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py`:
 - В local-режиме (нет `--socks`) сервер НЕ проксирует в Tavily, а сам извлекает: для каждого URL делает HTTP-запрос (`httpx`, при `--local-socks` через SOCKS5-туннель) и конвертирует HTML → Markdown через `trafilatura` (включён в venv).
 - Формат ответа в точности повторяет Tavily `/extract`: `{"results":[{url,title,raw_content,metadata}], "failed_results":[{url,error}], "failed_urls":[...]}` — Hermes-провайдер (`plugins/web/tavily/provider.py:_normalize_tavily_documents`) обрабатывает его без изменений.
 - Режимы взаимозаменяемы через аргументы CLI:
  - `--socks 127.0.0.1:1080` — forward в Tavily (как сейчас в systemd)
  - `--local` или ничего — локальная экстракция
  - `--local-socks 127.0.0.1:1080` — локальная, но страницы через туннель
 - systemd-юнит указать на tavily_extract_proxy.py (уже сделано, forward-режим).
 ## Files
 - `/opt/hermes/.hermes/scripts/tavily_extract_proxy.py` — добавлены `_fetch_page`, `_extract_local`, `_extract_local_batch`, `--local-socks`
 - `/opt/hermes/.hermes/hermes-agent/venv/` — установлен trafilatura 2.2.0
 - `/etc/systemd/system/tavily-proxy.service` — ExecStart → tavily_extract_proxy.py (forward), `--socks 127.0.0.1:1080`
 ## Commands
 ```bash
 # Локальный режим (тест)
 python3 /opt/hermes/.hermes/scripts/tavily_extract_proxy.py --port 8972 --local
 curl -s -X POST http://127.0.0.1:8972/extract -H 'Content-Type: application/json' \
  -d '{"urls":["https://example.com"]}'   # → {"results":[...]}
 # Переключение systemd на local (когда решено отказаться от облака)
 # в /etc/systemd/system/tavily-proxy.service: ExecStart → ... --port 8971 --local
 # sudo systemctl daemon-reload && sudo systemctl restart tavily-proxy
 ```
 ## Rollback
 ```bash
 # Вернуть forward-режим:
 # ExecStart → ... --socks 127.0.0.1:1080 --upstream https://api.tavily.com
 sudo systemctl daemon-reload && sudo systemctl restart tavily-proxy
 ```
 ## Risks
 - trafilatura хуже Tavily на JS-heavy страницах (нет headless-браузера) — приемлемо для типовых статей/доков.
 - Локальная экстракция не обходит блокировки РФ сама по себе — нужен `--local-socks` через туннель для таких сайтов.
 - Fetch без туннеля из РФ на github может висеть — ограничение сети, не кода.
@@ -0,0 +1,23 @@
 ## Why
 Облачная веб-экстракция (Tavily API) зависит от внешнего сервиса и туннеля: если Tavily вводит планы, меняет лимиты или туннель падает — Hermes теряет web_extract. Нужен полностью локальный экстрактор страниц, который работает без облачного API и без туннеля, с тем же интерфейсом для Hermes.
 ## What Changes
 - Добавляется локальная экстракция в tavily_extract_proxy.py: режим `--local` (trafilatura) / `--local-socks`
 - Один и тот же эндпоинт POST /extract отдаёт контент локально, сохраняя Tavily-совместимый JSON (results[].url/title/raw_content)
 - Устанавливается библиотека trafilatura в venv Hermes
 - (пока) сохраняется forward-режим как основной; local-режим — как опция переключения
 ## Capabilities
 ### New Capabilities
 - `web-extract-local`: Локальная экстракция страниц через trafilatura с Tavily-совместимым интерфейсом
 ### Modified Capabilities
 - `web-extract-tavily` — добавляется реализация local-режима (не меняет требования: прокси-режим остаётся)
 ## Impact
 - /opt/hermes/.hermes/scripts/tavily_extract_proxy.py — добавлен local-режим
 - venv Hermes — установлен trafilatura (2.2.0)
@@ -0,0 +1,34 @@
 # Delta for web-extract-local
 ## ADDED Requirements
 ### Requirement: Local Extraction Mode
 The system MUST support extracting page content fully locally (no cloud API) from the same HTTP endpoint used by the Tavily provider.
 #### Scenario: Extract page locally
 - GIVEN tavily_extract_proxy.py runs with --local (or --local-socks)
 - WHEN a POST /extract with {"urls":["https://..."]} is sent
 - THEN the server fetches each URL, converts to markdown with trafilatura
 - AND returns Tavily-shaped JSON: {"results":[{"url","title","raw_content","metadata"}], "failed_results":[], "failed_urls":[]}
 #### Scenario: Page fails to fetch
 - GIVEN a URL is unreachable or returns HTTP >= 400
 - WHEN extraction is attempted
 - THEN the URL lands in failed_results with an error message
 - AND other URLs still process normally
 ### Requirement: SOCKS Support for Local Fetches
 The local extractor MUST be able to fetch through the SOCKS5 tunnel (--local-socks 127.0.0.1:1080) for sites blocked from RU IPs.
 #### Scenario: Fetch through tunnel
 - GIVEN --local-socks 127.0.0.1:1080 is set
 - WHEN page fetch happens
 - THEN the request is routed through the SOCKS5 tunnel
 ### Requirement: Backward Compatible Interface
 The local mode MUST NOT break the existing Tavily forward mode: the same port/endpoint keeps working for both.
 #### Scenario: Forward still works
 - GIVEN the service runs with --socks (forward mode)
 - WHEN POST /extract is sent
 - THEN the request is forwarded to api.tavily.com as before
@@ -8,8 +8,8 @@
 ## 2. Тест локального режима
 - [x] 2.1 Запуск `--port 8972 --local` → отвечает, отдаёт Tavily-совместимый JSON
- [ ] 2.2 example.com через --local → контент извлечён (заблокировано сетью, тест отложен)
+- [x] 2.2 example.com через --local → контент извлечён (HTTP 200, 0.98s; github.com тоже OK)
- [ ] 2.3 Страница через --local-socks 127.0.0.1:1080 (тест отложен — сетевые проверки требуют присутствия пользователя)
+- [x] 2.3 Страница через --local-socks 127.0.0.1:1080 (tavily.com — заблокирован из РФ, HTTPS 200, 3.7s)
 ## 3. Интеграция с systemd
 - [x] 3.1 Юнит переведён на tavily_extract_proxy.py (forward-режим — рабочий, сохраняет текущее поведение)
@@ -0,0 +1,37 @@
 # web-extract-local Specification
 ## Purpose
 TBD - created by archiving change local-extractor. Update Purpose after archive.
 ## Requirements
 ### Requirement: Local Extraction Mode
 The system MUST support extracting page content fully locally (no cloud API) from the same HTTP endpoint used by the Tavily provider.
 #### Scenario: Extract page locally
 - GIVEN tavily_extract_proxy.py runs with --local (or --local-socks)
 - WHEN a POST /extract with {"urls":["https://..."]} is sent
 - THEN the server fetches each URL, converts to markdown with trafilatura
 - AND returns Tavily-shaped JSON: {"results":[{"url","title","raw_content","metadata"}], "failed_results":[], "failed_urls":[]}
 #### Scenario: Page fails to fetch
 - GIVEN a URL is unreachable or returns HTTP >= 400
 - WHEN extraction is attempted
 - THEN the URL lands in failed_results with an error message
 - AND other URLs still process normally
 ### Requirement: SOCKS Support for Local Fetches
 The local extractor MUST be able to fetch through the SOCKS5 tunnel (--local-socks 127.0.0.1:1080) for sites blocked from RU IPs.
 #### Scenario: Fetch through tunnel
 - GIVEN --local-socks 127.0.0.1:1080 is set
 - WHEN page fetch happens
 - THEN the request is routed through the SOCKS5 tunnel
 ### Requirement: Backward Compatible Interface
 The local mode MUST NOT break the existing Tavily forward mode: the same port/endpoint keeps working for both.
 #### Scenario: Forward still works
 - GIVEN the service runs with --socks (forward mode)
 - WHEN POST /extract is sent
 - THEN the request is forwarded to api.tavily.com as before