feat: harness — менеджер скиллов, агентов и MCP для Hermes и OpenCode

- scripts/harness: CLI (skills, agents, MCP, конфиг Hermes, рестарт, статус) - agents/: leader, fixer, researcher, tester + devops, admin - catalog/jakubkrehel-skills: submodule → github.com/jakubkrehel/skills - README: usage, форматы, таблица совместимости
2026-09-23 12:03:44 +05:00
parent 7970c3bb36
commit 13979a05ed
11 changed files with 1677 additions and 0 deletions
@@ -0,0 +1,207 @@
+# Harness 🛠️
+
+**Универсальный менеджер скиллов, агентов, MCP-серверов и конфигов для Hermes и OpenCode.**
+
+Репа-каталог, где живут ссылки на полезные skills, MCP-серверы, тулзы и агенты — с единым скриптом управления.
+
+```
+dev/harness/
+├── agents/               # Определения агентов OpenCode (leader, fixer, devops, admin, ...)
+├── catalog/              # Скиллы: git submodule'ы на внешние репы
+│   └── jakubkrehel-skills/  # submodule → github.com/jakubkrehel/skills (11 скиллов UI)
+├── scripts/
+│   └── harness           # Основной CLI-скрипт
+└── README.md
+```
+
+## Быстрый старт
+
+```bash
+./scripts/harness status            # Статус всей среды
+./scripts/harness list catalog      # Что есть в каталоге скиллов
+./scripts/harness list skills       # Установленные скиллы
+./scripts/harness list agents       # Агенты: доступные в репо + установленные
+./scripts/harness list mcp          # MCP-серверы Hermes
+```
+
+## Команды
+
+### Установка скиллов
+
+```bash
+# Установить скилл из каталога
+./scripts/harness install skill jakubkrehel-skills better-ui --target opencode
+./scripts/harness install skill jakubkrehel-skills better-ui --target hermes
+./scripts/harness install skill jakubkrehel-skills better-ui --target all
+
+# Можно писать через слэш
+./scripts/harness install skill jakubkrehel-skills/better-ui --target all
+
+# Все скиллы из репозитория разом
+./scripts/harness install skill jakubkrehel-skills --all --target opencode
+./scripts/harness install skill jakubkrehel-skills --all --target all
+```
+
+Скиллы ставятся симлинками в соответствующие директории:
+
+| Агент | Куда ставится |
+|-------|--------------|
+| Hermes | `~/.hermes/skills/catalog/<name>/` |
+| OpenCode | `~/.claude/skills/<name>/` |
+| OpenCode | `~/.config/opencode/skills/<name>/` |
+
+### Управление скиллами
+
+```bash
+./scripts/harness list skills                 # Все скиллы
+./scripts/harness list skills --target hermes # Только Hermes
+./scripts/harness remove skill better-ui      # Удалить отовсюду
+./scripts/harness remove skill better-ui --target hermes
+```
+
+### Агенты (только OpenCode)
+
+Источник — `harness/agents/*.md`. Имя агента = имя файла без `.md`.
+
+```bash
+# Список: что есть в репо + что уже установлено
+./scripts/harness list agents
+./scripts/harness list agents --scope global          # только глобальные
+./scripts/harness list agents --scope project --project ~/work/myrepo
+
+# Установить одного / всех
+./scripts/harness install agent leader                # в ~/.config/opencode/agents/
+./scripts/harness install agent --all --scope global  # всех, глобально
+./scripts/harness install agent devops --scope project --project ~/work/myrepo
+
+# Удалить
+./scripts/harness remove agent leader                 # отовсюду
+./scripts/harness remove agent leader --scope global
+```
+
+| `--scope` | Куда ставится |
+|-----------|--------------|
+| `global` (по умолчанию) | `~/.config/opencode/agents/<name>.md` |
+| `project` | `<project>/.opencode/agents/<name>.md` (по умолчанию — cwd) |
+
+Ставятся симлинками, так что правки в репе сразу видны OpenCode. Все агенты имеют
+`mode: all` (кроме `leader` — `primary`), чтобы лидер мог вызывать их как сабагентов.
+
+> **Hermes агентов не поддерживает** — только runtime-делегирование через
+> `delegate_task`. Пользовательских определений агентов у него нет, поэтому
+> `install agent` работает только для OpenCode.
+
+### MCP-серверы (Hermes)
+
+```bash
+# Добавить MCP по URL (HTTP SSE)
+./scripts/harness configure hermes mcp add my-server http://localhost:8000/mcp
+
+# Добавить MCP через команду (STDIO)
+./scripts/harness configure hermes mcp add github npx \
+  --env GITHUB_TOKEN=ghp_xxx \
+  --arg -y --arg @modelcontextprotocol/server-github
+
+# Список MCP
+./scripts/harness list mcp
+
+# Удалить MCP
+./scripts/harness configure hermes mcp rm my-server
+```
+
+### Конфигурация Hermes
+
+```bash
+# Посмотреть конфиг
+./scripts/harness configure hermes
+
+# Установить параметры
+./scripts/harness configure hermes --set model.default=gpt-4o
+./scripts/harness configure hermes --set model.provider=openai
+./scripts/harness configure hermes --set agent.max_turns=200
+```
+
+После изменения конфига скрипт автоматически перезапускает Hermes.
+
+### Установка/обновление бинарников
+
+```bash
+./scripts/harness install opencode   # curl-установщик opencode.ai
+./scripts/harness install hermes     # hermes update + рестарт сервисов
+```
+
+### Перезапуск
+
+```bash
+./scripts/harness restart hermes   # systemctl --user restart hermes-gateway + webui
+./scripts/harness restart opencode # systemctl --user restart opencode + openchamber
+```
+
+### Обновление каталога
+
+```bash
+./scripts/harness update catalog   # git pull во всех репах внутри catalog/
+```
+
+## Как добавить скилл в каталог
+
+Каталог — это **git submodule'ы**: в репе фиксируется ссылка на внешний репозиторий
+и точный коммит, а не копия файлов.
+
+```bash
+git submodule add https://github.com/user/skills-repo.git catalog/user-skills
+git commit -m "chore: add user-skills to catalog"
+```
+
+После этого `harness list catalog` покажет все найденные скиллы, а
+`harness update catalog` подтянет свежие коммиты во всех submodule'ах.
+
+Обычный клон (`git clone` внутрь `catalog/`) тоже работает — `update catalog`
+обновит его через `git pull`, но такой каталог не попадёт в коммит репы
+(вложенная репа не станет submodule автоматически).
+
+## Как добавить агента
+
+Положить `.md` файл в `agents/` репозитория — и он сразу виден через `harness list agents`.
+
+Формат — как у OpenCode:
+
+```markdown
+---
+description: "Что делает агент и когда его звать"
+mode: all            # primary | subagent | all
+temperature: 0.1
+steps: 100
+color: "#2563eb"
+permission:
+  task: deny
+  bash: allow
+  edit: allow
+---
+
+# Имя агента
+
+Тело промпта: роль, принципы, порядок работы, что НЕ делать, формат ответа.
+```
+
+- `mode: all` — можно и вызвать напрямую, и делегировать из `leader` (сабагент).
+- `mode: primary` — только как основной агент (Tab в UI). Такой агент **не** появится
+  в `task`-инструменте лидера: OpenCode фильтрует список сабагентов по `mode !== "primary"`.
+
+## Поддерживаемые форматы
+
+- **Скиллы** — `SKILL.md` с YAML frontmatter (`name`, `description`); родной формат OpenCode и Hermes.
+  Скиллы из `catalog/*/skills/<name>/SKILL.md` видны через `harness list catalog`.
+- **Агенты** — `<name>.md` с frontmatter (`description`, `mode`, ...); формат OpenCode.
+  Лежат в `agents/<name>.md`.
+
+## Совместимость
+
+| Фича | Hermes | OpenCode |
+|------|--------|----------|
+| Skills (SKILL.md) | ✅ `~/.hermes/skills/` | ✅ `~/.claude/skills/`, `~/.config/opencode/skills/` |
+| Agents | ❌ (только `delegate_task` в рантайме) | ✅ `~/.config/opencode/agents/`, `<project>/.opencode/agents/` |
+| MCP-серверы | ✅ `config.yaml mcp_servers` | 🟡 через `opencode.json` |
+| Plugins | ✅ `.hermes/plugins/` | ❌ (не поддерживает) |
+| Systemd service | ✅ gateway + webui | ✅ opencode + openchamber |
+| CLI install/update | `hermes update` | curl install script |