eka
7e2ea5a275
- catalog/developer-documentation-skill: submodule → NateBJones-Projects/developer-documentation-skill (v1.0.1, CC BY 4.0 / MIT) - README: раскладки репозиториев каталога и ручная установка скиллов
232 lines
9.9 KiB
Markdown
232 lines
9.9 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
|
||
```
|
||
|
||
## Быстрый старт
|
||
|
||
```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 автоматически).
|
||
|
||
### Раскладка репозитория и ручная установка
|
||
|
||
CLI `harness` понимает одну раскладку — `<репа>/skills/<name>/SKILL.md`.
|
||
Репозитории с другой структурой он показывает как `(no 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 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 |
|