# 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 память (наша фича)