eka
da70365701
- грамматика: harness <объект> <действие> (skills / agents / mcp / catalog / hermes / opencode) - skills list теперь показывает каталог: что доступно к установке, с отметками ✓/· - skills installed — прежний вид «что реально стоит» (включая не из каталога) - фикс: установленные скиллы не находились — Path.rglob не разворачивает симлинки, перешёл на os.walk(followlinks=True) - в листинге каталога виден sha источника и признак «⚠ сдвинут» - README переписан под новую грамматику
257 lines
11 KiB
Markdown
257 lines
11 KiB
Markdown
# Harness 🛠️
|
||
|
||
**Универсальный менеджер скиллов, агентов, MCP-серверов и конфигов для Hermes и OpenCode.**
|
||
|
||
Репа-каталог, где живут ссылки на полезные skills, MCP-серверы, тулзы и агенты — с единым скриптом управления.
|
||
|
||
```
|
||
dev/harness/
|
||
├── agents/ # Определения агентов OpenCode (leader, fixer, devops, admin, ...)
|
||
├── catalog/ # Скиллы: git submodule'ы на внешние репы
|
||
│ ├── jakubkrehel-skills/ # → github.com/jakubkrehel/skills (11 скиллов UI)
|
||
│ └── developer-documentation-skill/ # → NateBJones-Projects/… (доки; ставится вручную)
|
||
├── scripts/
|
||
│ └── harness # Основной CLI-скрипт
|
||
└── README.md
|
||
```
|
||
|
||
## Грамматика
|
||
|
||
**Объект — первым, действие — вторым:** `harness <объект> <действие> [аргументы]`
|
||
|
||
| Объект | Что это | Действия |
|
||
|--------|---------|----------|
|
||
| `status` | среда целиком | — |
|
||
| `skills` | скиллы из каталога | `list`, `installed`, `install`, `remove` |
|
||
| `agents` | агенты (только OpenCode) | `list`, `install`, `remove` |
|
||
| `mcp` | MCP-серверы Hermes | `list`, `add`, `rm` |
|
||
| `catalog` | внешние репозитории каталога | `list`, `update` |
|
||
| `hermes` | сам Hermes | `config`, `restart`, `update` |
|
||
| `opencode` | сам OpenCode | `install`, `restart` |
|
||
|
||
```bash
|
||
./scripts/harness status
|
||
./scripts/harness skills list
|
||
./scripts/harness skills install jakubkrehel-skills better-ui --target all
|
||
./scripts/harness agents install leader
|
||
./scripts/harness mcp list
|
||
./scripts/harness catalog update
|
||
./scripts/harness hermes restart
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
```bash
|
||
./scripts/harness status # Обзор среды
|
||
./scripts/harness skills list # Что доступно в каталоге (+ отметки установки)
|
||
./scripts/harness skills installed # Что реально стоит у агентов
|
||
./scripts/harness agents list # Агенты: доступные в репо + установленные
|
||
./scripts/harness mcp list # MCP-серверы Hermes
|
||
./scripts/harness catalog list # Источники каталога
|
||
```
|
||
|
||
## `skills` — скиллы из каталога
|
||
|
||
### `skills list` — что доступно к установке
|
||
|
||
Показывает содержимое каталога и где скилл уже стоит. `✓` — установлено, `·` — нет.
|
||
|
||
```bash
|
||
./scripts/harness skills list
|
||
./scripts/harness skills list --target opencode
|
||
```
|
||
|
||
```
|
||
Доступно из каталога (/mnt/data/Agent/dev/harness/catalog)
|
||
✓ — установлено, · — нет
|
||
|
||
jakubkrehel-skills 11 скиллов 267330e
|
||
├─ better-ui hermes · opencode ✓
|
||
├─ better-colors hermes · opencode ·
|
||
...
|
||
```
|
||
|
||
Для git-источников показывается короткий sha; `⚠ сдвинут` — submodule ушёл вперёд
|
||
и это ещё не закоммичено.
|
||
|
||
### `skills installed` — что реально стоит
|
||
|
||
Полное дерево каталогов агента, включая скиллы не из каталога.
|
||
|
||
```bash
|
||
./scripts/harness skills installed
|
||
./scripts/harness skills installed --target hermes
|
||
```
|
||
|
||
### `skills install` / `skills remove`
|
||
|
||
```bash
|
||
# Один скилл
|
||
./scripts/harness skills install jakubkrehel-skills better-ui --target opencode
|
||
./scripts/harness skills install jakubkrehel-skills/better-ui --target all
|
||
|
||
# Все скиллы источника
|
||
./scripts/harness skills install jakubkrehel-skills --all --target opencode
|
||
|
||
# Удалить
|
||
./scripts/harness skills remove better-ui
|
||
./scripts/harness skills remove better-ui --target hermes
|
||
```
|
||
|
||
Скиллы ставятся **симлинками**:
|
||
|
||
| Агент | Куда ставится |
|
||
|-------|--------------|
|
||
| Hermes | `~/.hermes/skills/catalog/<name>/` |
|
||
| OpenCode | `~/.claude/skills/<name>/` |
|
||
| OpenCode | `~/.config/opencode/skills/<name>/` |
|
||
|
||
## `agents` — агенты (только OpenCode)
|
||
|
||
Источник — `harness/agents/*.md`. Имя агента = имя файла без `.md`.
|
||
|
||
```bash
|
||
./scripts/harness agents list
|
||
./scripts/harness agents list --scope global
|
||
./scripts/harness agents list --scope project --project ~/work/myrepo
|
||
|
||
./scripts/harness agents install leader # в ~/.config/opencode/agents/
|
||
./scripts/harness agents install --all --scope global
|
||
./scripts/harness agents install devops --scope project --project ~/work/myrepo
|
||
|
||
./scripts/harness agents remove leader
|
||
./scripts/harness agents remove 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`. Пользовательских определений агентов у него нет.
|
||
|
||
## `mcp` — MCP-серверы Hermes
|
||
|
||
```bash
|
||
./scripts/harness mcp list
|
||
|
||
# По URL (HTTP/SSE)
|
||
./scripts/harness mcp add my-server http://localhost:8000/mcp
|
||
|
||
# Командой (stdio)
|
||
./scripts/harness mcp add github npx \
|
||
--env GITHUB_TOKEN=ghp_xxx \
|
||
--arg -y --arg @modelcontextprotocol/server-github
|
||
|
||
./scripts/harness mcp rm my-server
|
||
```
|
||
|
||
`add` и `rm` сами перезапускают `hermes-gateway`, чтобы изменения подхватились.
|
||
|
||
## `catalog` — внешние репозитории
|
||
|
||
```bash
|
||
./scripts/harness catalog list # источники, содержимое, sha, признак «сдвинут»
|
||
./scripts/harness catalog update # git submodule update --remote / git pull для клонов
|
||
```
|
||
|
||
## `hermes` / `opencode` — сам агент
|
||
|
||
```bash
|
||
./scripts/harness hermes config # показать конфиг
|
||
./scripts/harness hermes config --set model.default=gpt-4o
|
||
./scripts/harness hermes config --set agent.max_turns=200
|
||
./scripts/harness hermes restart # systemctl --user restart hermes-gateway + webui
|
||
./scripts/harness hermes update # hermes update + рестарт сервисов
|
||
|
||
./scripts/harness opencode install # curl-установщик opencode.ai
|
||
./scripts/harness opencode restart # systemctl --user restart opencode + openchamber
|
||
```
|
||
|
||
`hermes config --set` меняет `~/.hermes/config.yaml` и перезапускает сервисы.
|
||
|
||
## Как добавить скилл в каталог
|
||
|
||
Каталог — это **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 skills list` покажет найденные скиллы, а
|
||
`harness catalog update` подтянет свежие коммиты во всех submodule'ах.
|
||
|
||
### Раскладка репозитория и ручная установка
|
||
|
||
CLI понимает одну раскладку — `<репа>/skills/<name>/SKILL.md`. Репозитории с другой
|
||
структурой (`SKILL.md` в корне, `.agents/skills/`, вложенные категории) он показывает
|
||
без списка скиллов, и такие скиллы ставятся вручную. Ограничение только у CLI: сам
|
||
OpenCode сканирует рекурсивно (`skills/**/SKILL.md`, а через `skills.paths` —
|
||
`**/SKILL.md` на любой глубине).
|
||
|
||
Пример — `developer-documentation-skill` держит `SKILL.md` в корне репы:
|
||
|
||
```bash
|
||
ln -s /mnt/data/Agent/dev/harness/catalog/developer-documentation-skill \
|
||
~/.agents/skills/developer-documentation
|
||
```
|
||
|
||
Альтернатива без симлинков — указать в конфиге OpenCode корень каталога:
|
||
|
||
```json
|
||
{ "skills": { "paths": ["/mnt/data/Agent/dev/harness/catalog"] } }
|
||
```
|
||
|
||
Тогда OpenCode найдёт все `SKILL.md` из каталога, в любой раскладке. Минус —
|
||
подхватывается всё содержимое разом, включая ненужное.
|
||
|
||
## Как добавить агента
|
||
|
||
Положить `.md` файл в `agents/` репозитория — и он сразу виден через `harness agents list`.
|
||
|
||
Формат — как у 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.
|
||
- **Агенты** — `<name>.md` с frontmatter (`description`, `mode`, ...); формат OpenCode.
|
||
|
||
## Совместимость
|
||
|
||
| Фича | 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 |
|