[2026-09-15] eagle: family/how-to/truenas-infrastructure.md personal/tech/deepseek-language-drift.md personal/tech/hermes-agent-improvements.md personal/tech/hermes-fork-vs-upstream.md personal/tech/hermes-git-repo.md personal/tech/xray-reverse-tunnel-kraken-truenas.md

personal/tech/hermes-fork-vs-upstream.md

@@ -0,0 +1,213 @@
+# Hermes — апстрим vs наш форк
+
+**Дата:** 2026-09-15
+**Статус:** актуально — анализ расхождения сделан, **стратегия подтяжки НЕ выбрана**
+**Репо:** `~/.hermes/hermes-agent` (сабмодуль, форк `mallexxx/hermes-agent`)
+
+## Текущее решение: не принято
+
+На 2026-09-15 Alex'у представлены 3 варианта (A merge / B перенос на свежий
+апстрим / C заморозка). **Выбор не сделан.** Работа над подтяжкой не начата.
+Наш форк запушен и стабилен — можно спокойно решать.
+
+Открытый вопрос, определяющий выбор: **нужны ли нам вообще 24k коммитов
+апстрима?** Мы используем Hermes как Zulip-бота с webhook-флоу; апстрим растёт
+десктопом/TUI/платформами, которые нам не нужны. Точечный cherry-pick
+(security-фиксы, фиксы `agent/`, новые модели) может быть достаточен.
+
+## Масштаб расхождения
+
+| Метрика | Значение |
+|---------|----------|
+| Коммитов апстрима впереди | **24 407** |
+| Наших коммитов | 32 |
+| Common ancestor | `4ed63170e4` (2026-06-04) |
+| Дата последнего коммита апстрима | 2026-09-15 |
+| Наша версия | `0.15.1` |
+| Версия апстрима | `0.21.3` |
+| Файлов изменено апстримом | 12 634 |
+| Строк: +2 362 152 / −763 849 | |
+
+**Вывод:** это не «догнать на пару недель», а **~3.5 месяца и 24k коммитов**.
+Апстрим ушёл на мажорные версии вперёд (0.15 → 0.21).
+
+## Ремоуты
+
+| Remote | URL | Роль |
+|--------|-----|------|
+| `origin` | `git@github.com:mallexxx/hermes-agent.git` | наш форк |
+| `upstream` | `https://github.com/NousResearch/hermes-agent.git` | источник |
+
+## Главные изменения апстрима
+
+### 1. Платформы переехали из ядра в плагины ⚠️ КРИТИЧНО
+
+Апстрим **удалил** `telegram.py`, `slack.py`, `matrix.py`, `discord.py` из
+`gateway/platforms/` — теперь они живут в `plugins/platforms/`.
+
+**Состав `plugins/platforms/` у апстрима (19):**
+`a2a, buzz, dingtalk, discord, email, feishu, google_chat, homeassistant, irc,
+line, matrix, mattermost, ntfy, photon, raft, simplex, slack, sms, teams,
+telegram, wecom, whatsapp`
+
+**Наш `plugins/platforms/` (8):** `discord, google_chat, irc, line, mattermost,
+ntfy, simplex, teams`
+
+**⚠️ Zulip НЕТ ни в ядре апстрима, ни в `plugins/platforms/` апстрима.**
+Проверено: `git ls-tree -r upstream/main | grep -i zulip` → пусто.
+Zulip — **полностью наша разработка**:
+- `gateway/platforms/zulip.py` — не существует в апстриме
+- `tools/zulip_thread_tool.py` — не существует в апстриме
+
+Это значит: наш Zulip-адаптер живёт в **устаревшем месте** (`gateway/platforms/`),
+которое апстрим планомерно опустошает. При подтяжке его придётся переносить в
+`plugins/platforms/` — иначе он повиснет на api, которого больше нет.
+
+### 2. Смежные подсистемы
+
+Топ-скоупы по числу feat/refactor коммитов:
+
+| Скоуп | Коммитов | Что это |
+|-------|----------|---------|
+| `desktop` | 773 | Десктоп-приложение — крупнейшая новая подсистема |
+| `hermes_cli` | 607 | CLI переработан |
+| `gateway` | 412 | Ядро гейтвея |
+| `tools` | 339 | Инструменты |
+| `agent` | 217 | Ядро агента |
+| `cli` / `tui` / `tui_gateway` | 141/100/76 | TUI (Ink/React) |
+| `state` | 106 | Персистентность сессий |
+| `cron` | 91 | Планировщик |
+| `computer_use` | 86 | Управление десктопом |
+| `mcp` | 79 | MCP-клиент |
+| `relay` | 54 | Новая подсистема релея |
+
+Типы коммитов: `fix` 10 994, `refactor` 4 158, `feat` 2 113, `test` 1 836.
+
+**Читается так:** апстрим прошёл большую волну рефакторинга (4158) + массовый
+десктоп/TUI-фронт. Наши правки в `gateway/run.py` (13 коммитов) и
+`gateway/stream_consumer.py` (9) — ровно в эпицентре этого рефакторинга.
+
+## Наши 32 коммита
+
+Сгруппированы по темам:
+
+**Zulip-платформа (наша, в апстриме отсутствует):**
+- `b0f097a299` feat: add Zulip platform adapter (parallel to Discord)
+- `ce093b0a75` zulip: switch approval prompt emojis ✅/❌ → 👍/👎
+- `b1e36eb2d7` fix(zulip): lock→locked emoji name
+- `f39671ba97` fix(routing): pre_gateway_dispatch before session guard
+- `d4e98a8b07` / `ef69e76413` / `40149225af` / `ddc6aa7c46` webhook: zulip in
+  BUILTIN_DELIVER_PLATFORMS, session_chat_id из X-Chat-Id
+- `8255ea0c64` feat(zulip): session_search читает Zulip thread history
+- `049922d8cc` fix(session_search): dual Zulip+SQLite recall, FTS5 sanitization
+
+**Webhook no-edit streaming (наш флоу без редактирования сообщений):**
+- `fa271d2d19`, `ee41e8a847`, `9003d4cbbe` (revert), `1ac06d593a`, `9253fe52cc`,
+  `88cbb77b95`, `6c95153aa8`, `eb8dd7b5ed`, `a92840dcde`, `a08527e85c`,
+  `a88bec1762`, `5d3e95841b`, `ec9efce7e7`
+
+**Фичи профиля Whale:**
+- `972004546f` feat: thread-scoped memory + configurable memory instruction
+- `4ebad4f692` test: thread-scoped memory persistence, drift guard, snapshot
+- `da146da5fa` feat: configurable background review prompts and allowed toolsets
+- `207a1de16c` feat: load stable system-prompt blocks from config prompt_overrides
+
+**Прочее:**
+- `6e09a3704a` fix(approval): interrupt pending approvals on user message
+- `a17d02f31e` fix(api_server): tool.progress → plain-text chunks
+- `81f10c306f` approval: reaction emoji на webhook
+
+## Риск конфликтов при merge
+
+Dry-run `git merge-tree` → **16 конфликтных файлов, 160 конфликтных маркеров**.
+
+| Файл | Наших коммитов | Коммитов апстрима | Риск |
+|------|---------------|-------------------|------|
+| `gateway/run.py` | 13 | **974** | 🔴 экстремальный |
+| `cron/scheduler.py` | 1 | 307 | 🟠 |
+| `agent/agent_init.py` | 3 | 226 | 🟠 |
+| `gateway/platforms/base.py` | 2 | 208 | 🟠 |
+| `gateway/platforms/api_server.py` | 1 | 177 | 🟠 |
+| `agent/model_metadata.py` | 1 | 164 | 🟡 |
+| `tools/approval.py` | 1 | 147 | 🟡 |
+| `agent/prompt_builder.py` | 0 | 131 | auto-merge ok |
+| `gateway/stream_consumer.py` | 9 | 73 | 🟠 (наш файл, апстрим переписал) |
+| `agent/system_prompt.py` | 2 | 65 | 🟡 |
+| `gateway/platforms/webhook.py` | 7 | 59 | 🟠 |
+| `toolsets.py` | 2 | 62 | 🟡 |
+| `tools/session_search_tool.py` | 2 | 41 | 🟢 |
+| `tools/memory_tool.py` | 1 | 34 | 🟢 |
+| остальные | 1 | <30 | 🟢 |
+
+**Худший случай:** `gateway/run.py` — 974 коммита апстрима против наших 13.
+Это фактически переписывание файла. Конфликты там будут не «принять/отклонить
+строку», а разбор чужой новой архитектуры.
+
+## Стратегии подтяжки
+
+### Вариант A: merge (сейчас) — НЕ рекомендуется
+`git merge upstream/main` → 16 конфликтных файлов, ручной разбор 160 маркеров
+в горячих файлах. Оценка: **дни на `run.py` + `stream_consumer.py`**, риск
+потерять наши webhook/Zulip-правки.
+
+### Вариант B: перенос нашей функциональности на свежий апстрим (рекомендуется)
+Взять чистый `upstream/main` как новую базу, затем **перенести наши фичи
+патчами заново**:
+1. Сохранить наши diff'ы как patch-файлы (`git format-patch`)
+2. Форк от свежего апстрима
+3. Переносить по темам: Zulip-адаптер (в `plugins/platforms/`!), 3 фичи Whale
+   (thread-scoped memory, bg-review, prompt_overrides), webhook-стриминг
+4. Webhook-стриминг — вероятно **уже решён апстримом**, проверить перед переносом
+
+**Плюс:** результат на актуальной кодовой базе, без 24k коммитов долга.
+**Минус:** ручная работа по переносу, ~1-2 дня.
+
+### Вариант C: заморозить и жить на форке
+Принять, что мы отдельный продукт. Апстрим берём точечно (`git cherry-pick`
+отдельных фиксов безопасности). Дёшево сейчас, растёт долг потом.
+
+## Ключевой вопрос перед подтяжкой
+
+**Нужны ли нам вообще 24k коммитов апстрима?**
+Мы используем Hermes как **Zulip-бота с webhook-флоу**. Ядро апстрима
+прирастает десктопом, TUI и платформами (telegram/slack/...), которые нам
+не нужны. Реальная ценность от апстрима для нас:
+- фиксы безопасности (`tools/tirith_security.py`, approval)
+- фиксы багов в `agent/` (метаданные моделей, сжатие контекста)
+- поддержка новых моделей/провайдеров
+
+Это можно брать точечно (cherry-pick), не таща весь долг.
+
+## Команды для проверки расхождения
+
+```bash
+cd ~/.hermes/hermes-agent
+
+# Обновить инфу об апстриме
+git fetch upstream
+
+# Насколько отстали
+git rev-list --count main..upstream/main      # апстрим впереди
+git rev-list --count upstream/main..main      # мы впереди
+
+# Общий предок
+git merge-base main upstream/main
+
+# Изменения по нашим файлам
+git diff --name-only $(git merge-base main upstream/main)..main | sort -u
+
+# Насколько апстрим трогал конкретный файл
+git rev-list --count $(git merge-base main upstream/main)..upstream/main -- gateway/run.py
+
+# Dry-run merge (безопасно, не трогает рабочую копию)
+git merge-tree --write-tree --name-only main upstream/main
+
+# Есть ли файл в апстриме
+git cat-file -e upstream/main:gateway/platforms/zulip.py && echo yes || echo NO
+```
+
+## Связанное
+
+- [[hermes-git-repo]] — структура репо, .gitignore, что коммитить
+- [[hermes-whale-system-prompt]] — prompt_overrides (наша фича)
+- [[hermes-memory-architecture]] — thread-scoped память (наша фича)