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

# 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) — ровно в эпицентре этого рефакторинга.

## Масштаб по коду (не «перетаскивание папок»)

Апстрим — это не реорганизация, а **+322 новых модуля**. Считать так:

| Область | У нас | У апстрима | Нового |
|---------|-------|-----------|--------|
| `agent/` | 88 файлов | 229 | **+144** |
| `tools/` | 86 файлов | 262 | **+178** |
| `hermes_state*` | 1 монолит | 25 модулей | разбит |
| `apps/` | — | 2674 файла | desktop-приложение |
| `evals/` | — | 203 файла | eval-фреймворк |
| `contributors/` | — | 1176 | данные контрибьюторов |
| `plugin-catalog/` | — | 27 | каталог плагинов |

Команда для повторной проверки:
```bash
cd ~/.hermes/hermes-agent
comm -13 <(git ls-tree --name-only main:agent/ | sort) \
         <(git ls-tree --name-only upstream/main:agent/ | sort) | wc -l
```

## Что реально нового в апстриме (по функциональности)

**1. Desktop-приложение (`apps/desktop`, 2674 файла)** — крупнейшая подсистема
(773 коммита в скоупе `desktop`). Нативный GUI. Внутри — `bootstrap-installer`,
`shared`. Это фронт на TypeScript/Ink.

**2. Bot Mode** (`website/docs/user-guide/bot-mode.md`) — **прямо про наш кейс.**
Профили превращаются в roster именованных **ботов**: у каждого своя роль, модель,
память, скиллы, аватар. Боты ходят в групповые чаты и **пишут друг другу**.
Ключевое: «A Bot **is** a Hermes profile» — никакого нового примитива, всё видно
из CLI (`hermes -p <bot> chat`), роутины в `hermes cron list`.
Есть «forever-chat» на бота: `/new` внутри перехватывается в `/compact`.
Секции (папки) для группировки, скрытие ботов, фильтр «Active now».

**Сопоставление с нашим:** у нас Eagle + Whale + Balda роутятся через самодельный
`plugins/whale-thread-guard` (файл `thread_ownership.json`). У апстрима это
**нативная фича с UI**. ⚠️ Открытый вопрос для Alex — не выбрасывается ли наш
роутинг в пользу нативного (см. «Ключевой вопрос» ниже).

**3. Автономные циклы — три механизма:**
- `/goal` — стоящая цель через turns; lightweight judge-модель после каждого turn
  проверяет достижение, агент сам кормит continuation prompt до успеха. Их версия
  Ralph loop (вдохновлено Codex CLI 0.128.0).
- `/loop` — перезапуск промпта по таймеру **внутри сессии**; каждый wakeup — это
  реальный turn. Их версия Claude Code `/loop` (алиас `/proactive`).
- `/heartbeat` — один промпт на сессию, срабатывает когда сессия idle.
Разница: `/goal` judge-driven («работай пока не достигнешь»), `/loop` timer-driven
(«делай это каждые N минут»).

**4. Encrypted credential vault** (`agent/vault_store.py`) — зашифрованное
(Fernet) локальное хранилище для browser autofill. Profile-scoped, **model-blind**:
модель видит только opaque handles + метаданные (kind, label, origin), значения
резолвятся server-side и не попадают в tool results / логи / session DB.
Три вида: `login`, `payment`, `address`. Ключ и файл 0600 в `<HERMES_HOME>/vault/`.
Портировано из Merit-Systems/OpenInstinct (MIT).

**5. Turn-цикл разобран на 29 модулей** — `turn_facade`, `turn_preflight`,
`turn_preflight_gate`, `turn_recovery`, `turn_overflow`, `turn_truncation`,
`turn_tool_round`, `turn_finalizer`, `turn_liveness`, `turn_retry_state` и др.
`run_conversation` из монолита стал конвейером.

**6. MCP переписан — 20 модулей:** `mcp_tool_discovery`, `mcp_oauth_provider`,
`mcp_death_supervisor`, `mcp_tool_sampling`, `mcp_tool_schema`, `mcp_schema_cache`,
`mcp_tool_health`, `mcp_tool_scope`, `mcp_oauth_device` и др.

**7. Браузер — 16 модулей** `browser_tool_*`: CDP, cloud, lightpanda fallback,
snapshot, vision, origin, session, lifecycle, install, real_profile,
supervisor_dialogs/frames, eval_policy, vault_tool.

**8. `native/fts5_cjk`** — C-расширение SQLite FTS5 для **китайского/японского/
корейского** токенизации полнотекстового поиска. Нативная сборка
(`build.sh` + `vendor/sqlite3.h`). Прямо относится к багу китайского вывода —
см. [[deepseek-language-drift]].

**9. Skills Hub — 8 модулей:** `skills_hub_github`, `skills_hub_official`,
`skills_hub_clawhub`, `skills_hub_skillssh`, `skills_hub_search`, `skills_hub_install`,
`skills_hub_sources`, `skills_hub_models`. Плюс `skill_linter`, `skill_ledger`,
`skill_manager_batch`, `skill_manager_guards`.

**10. Прочее новое:** `pets` (питомцы в UI), `skins`, `personality`,
`mixture-of-agents` (`moa_loop.py`, `moa_trace.py`), `honcho` (memory-провайдер),
`code_kernel` + `code_kernel_remote` (Python-кирнел), `deliverable-mode` (файлы
как нативные вложения в мессенджерах), `credential-pools`, `provider-routing`,
`subscription-proxy`, `tool-gateway`, `tool-search`, `kanban-multi-gateway`,
`relay` (NeMo Relay runtimes, 54 коммита), `lsp`, `heartbeat`, `goals`, `loops`,
`curator`, `skills`, `context-references`, `document-extraction`, `batch-processing`,
`computer-use`, `codex-app-server-runtime`, `plugin-catalog`, `extending-the-dashboard`.

**Новые top-level каталоги:** `apps/`, `native/`, `evals/`, `contributors/`,
`plugin-catalog/`, `providers/`, `locales/`, `web/`, `website/i18n`.

## Ответ: есть ли замена Zulip?

**Нет.** Проверено по существу — по модели общения, а не по имени платформы.

| Платформа | Треды | Self-hosted | Stream+topic |
|-----------|-------|-------------|--------------|
| `matrix` | ✅ threads | ✅ | ❌ room-based |
| `mattermost` | ✅ thread-mode replies | ✅ | ❌ channel-based |
| `slack` | ✅ threads | ❌ SaaS | ❌ |
| `teams` | ✅ | ❌ SaaS | ❌ |
| `google_chat` | ❌ | ❌ SaaS | ❌ |
| `irc` | ❌ | ✅ | ❌ flat |
| `simplex` | ❌ groups | ✅ p2p | ❌ |
| `a2a` | — | ✅ | — (agent-to-agent, не чат) |

Проверка на stream+topic: `git grep -li 'stream.*topic' upstream/main -- plugins/platforms/`
→ только `dingtalk` и `telegram`, и там это не топик-модель.

**Ключевое различие:** Zulip — единственная известная чат-платформа с нативной
моделью «поток → топик», где топик = **адресуемая сущность** с собственным именем.
Matrix и Mattermost дают треды как *свойство сообщения* (reply-thread), а не как
*адресуемую сущность*. У нас `stream::topic` — это **ключ роутинга**
(`thread_ownership.json`: `"stream::topic": "eagle"|"whale"`), на их модели такой
ключ не построить.

**Вывод:** миграция на matrix/mattermost = потеря топик-роутинга между ботами.
`whale-thread-guard` на их модели не переносится.

Подробности платформ: `plugins/platforms/<name>/plugin.yaml` — там `description`,
`requires_env`, `optional_env` с описаниями (`MATTERMOST_REPLY_MODE: 'thread'|'off'`,
`MATRIX_HOMESERVER`, mention-gating и т.д.).

## Ответ: сделаны ли custom prompts как у нас?

**Нет, аналога не существует.** Проверено:
```bash
git grep -l 'prompt_overrides' upstream/main   # пусто
git grep -l '_load_prompt_block' upstream/main # пусто
```

В апстриме **все** блоки промпта — **захардкоженные константы** в
`agent/prompt_builder.py`: `MEMORY_GUIDANCE`, `USER_PROFILE_GUIDANCE`,
`SESSION_SEARCH_GUIDANCE`, `SKILLS_GUIDANCE`, `KANBAN_GUIDANCE`,
`TOOL_USE_ENFORCEMENT_GUIDANCE`, `TASK_COMPLETION_GUIDANCE`,
`PARALLEL_TOOL_CALL_GUIDANCE`, `OPENAI_MODEL_EXECUTION_GUIDANCE`,
`GOOGLE_MODEL_OPERATIONAL_GUIDANCE`, `HERMES_AGENT_HELP_GUIDANCE` (+ вариант
`_NO_SKILLS`), `DEFAULT_AGENT_IDENTITY`, `PLATFORM_HINTS` (по платформе).

`build_system_prompt_parts()` в апстриме просто делает `stable_parts.append(CONST)`
— точки подмены из файла нет.

**Что у апстрима ЕСТЬ для кастомизации:**
- `SOUL.md` — идентичность агента (есть и у нас, грузится через `load_soul_md()`)
- context-файлы из CWD (`AGENTS.md`, `HERMES.md`) — `_find_hermes_md()`,
  `_scan_context_content()`, `_strip_yaml_frontmatter()`
- `system_message` из конфига

**Чего НЕТ:** подмены отдельных блоков промпта файлами. То есть наш
`_load_prompt_block()` + `agent.prompt_overrides` — **уникальная фича форка**
(коммит `207a1de16`). См. [[hermes-agent-improvements]].

**Практический смысл различия:** у нас правка промпта = редактирование `.md`
в `hermes-whale/review/` без касания Python. У них = правка Python-константы в
`prompt_builder.py`, который апстрим постоянно переписывает (131 коммит).

**`agent/thread_scoped_output.py`** — существует в апстриме. У нас thread-scoped
память сделана с нуля (`972004546f`). Стоит сравнить перед вариантом B: возможно,
у апстрима есть готовое решение лучше. Не проверено детально.

## НАШИ 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), не таща весь долг.

### Что уточнилось 2026-09-15 (второй проход)

Alex задал три прямых вопроса, ответы получены (детали — в разделах выше):

| Вопрос | Ответ |
|--------|-------|
| Что нового в апстриме? | Не только платформы: +322 модуля, desktop, Bot Mode, `/goal` `/loop` `/heartbeat`, vault, turn-рефакторинг, MCP, Skills Hub |
| Есть ли замена Zulip? | **Нет** — ни одна платформа не даёт stream+topic как адресуемую сущность |
| Сделаны ли custom prompts как у нас? | **Нет** — блоки захардкожены, `prompt_overrides` уникален для форка |

**Новый открытый вопрос (важнее прежних):** Bot Mode апстрима делает нативно
то, что у нас держится на самодельном `whale-thread-guard` + `thread_ownership.json`.
Если переезжать на вариант B — надо решить, **переносить наш роутинг или
выбрасывать в пользу нативного Bot Mode**. Этот вопрос не задан Alex'у явно,
вынесен как следующий шаг.

**Также не проверено:** `agent/thread_scoped_output.py` в апстриме vs наша
thread-scoped память — возможно, у них готовое решение лучше нашей реализации.

**Статус:** стратегия подтяжки по-прежнему **не выбрана**. Форк запушен и стабилен.

## Команды для проверки расхождения

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