OpenHarness

        ___
       /   \
      (     )        ___  ___  ___ _  _ _  _   _ ___ _  _ ___ ___ ___
       `~w~`        / _ \| _ \| __| \| | || | /_\ | _ \ \| | __/ __/ __|
       (( ))       | (_) |  _/| _|| .` | __ |/ _ \|   / .` | _|\__ \__ \
        ))((        \___/|_|  |___|_|\_|_||_/_/ \_\_|_\_|\_|___|___/___/
       ((  ))
        `--`

ИИ-агент для программирования в вашем терминале. Работает с любой LLM — бесплатные локальные модели или облачные API.

Английский | Китайский (упрощённый)

---

Содержание

• Быстрый старт
• Почему OpenHarness?
• Терминальный интерфейс
• Инструменты (44)
• Слэш-команды
• Режимы разрешений
• Хуки
• Контрольные точки и откат
• Роли агентов
• Фоновый режим и CI/CD
• Cybergotchi
• MCP-серверы
• Провайдеры
• Аутентификация
• Обновление
• Оценки
• Частые вопросы
• Установка
• Разработка
• Вклад
• Сообщество

---

Быстрый старт

npm install -g @zhijiewang/openharness
oh

Вот и всё. OpenHarness автоматически обнаруживает Ollama и начинает чат. API-ключ не нужен.

Python SDK: также есть официальный Python SDK для управления oh из Python-программ (ноутбуки, пакетные скрипты, ML-конвейеры). Установите с помощью pip install openharness-sdk после установки npm (дистрибутив PyPI называется openharness-sdk, так как неуточнённое имя занято), затем from openharness import query. См. python/README.md.

TypeScript SDK: управляйте oh из Node.js (расширения VS Code, приложения Electron, скрипты сборки) с помощью @zhijiewong/openharness-sdk — npm install @zhijiewong/openharness-sdk, затем import { query, OpenHarnessClient, tool } from "@zhijiewong/openharness-sdk". Повторяет поверхность Python SDK (потоковые события, сеансы с сохранением состояния, пользовательские инструменты, обратный вызов разрешений, возобновление сеанса). См. packages/sdk/README.md.

oh init                               # interactive setup wizard (provider + cybergotchi)
oh                                    # auto-detect local model
oh --model ollama/qwen2.5:7b         # specific model
oh --model gpt-4o                     # cloud model (needs OPENAI_API_KEY)
oh --trust                            # auto-approve all tool calls
oh --auto                             # auto-approve, block dangerous bash
oh -p "fix the tests" --trust         # headless mode (single prompt, exit)
oh run "review code" --json           # CI/CD with JSON output

Команды внутри сессии:

/rewind                               # undo last AI file change (checkpoint restore)
/roles                                # list agent specializations
/vim                                  # toggle vim mode
Ctrl+O                                # flush transcript to scrollback for review

Почему OpenHarness?

Большинство ИИ-агентов для программирования привязаны к одному провайдеру или стоят от 20 долларов в месяц. OpenHarness работает с любой LLM — запускайте бесплатно с Ollama на своей машине или подключайтесь к любому облачному API. Каждое изменение ИИ фиксируется в git и может быть отменено с помощью /undo.

Терминальный интерфейс

OpenHarness оснащён последовательным терминальным рендерером, вдохновлённым режимом по умолчанию Ink/Claude Code. Завершённые сообщения выводятся в собственный буфер прокрутки (прокручиваемый), а живая область (потоковая передача, индикатор, ввод) перезаписывается на месте с помощью относительного перемещения курсора.

Горячие клавиши

Клавиша	Действие
Enter	Отправить запрос
Alt+Enter	Вставить новую строку (многострочный ввод)
↑ / ↓	Перемещение по истории ввода
Ctrl+C	Отменить текущий запрос / выйти
Ctrl+A / Ctrl+E	Перейти к началу / концу ввода
Ctrl+O	Переключить разворачивание блока размышлений
Ctrl+K	Переключить разворачивание блока кода в сообщениях
Tab	Автодополнение слэш-команд / путей к файлам / циклическое переключение вывода инструментов
/vim	Переключить режим Vim (обычный / вставки)

Прокрутка обрабатывается встроенной полосой прокрутки терминала. Завершённые сообщения попадают в буфер прокрутки терминала. Используйте поиск в вашем терминале (например, Ctrl+Shift+F в VS Code) для поиска по истории разговора.

Возможности

• Рендеринг Markdown — заголовки, блоки кода, жирный шрифт, курсив, списки, таблицы, цитаты, ссылки
• Подсветка синтаксиса — ключевые слова, строки, комментарии, числа, типы (JS/TS/Python/Rust/Go и более 20 языков)
• Сворачиваемые блоки кода — блоки длиннее 8 строк автоматически сворачиваются; Ctrl+K для разворачивания всех
• Сворачиваемое мышление — блоки мышления сворачиваются в однострочное резюме после завершения; Ctrl+O для разворачивания
• Shimmer-спиннер — анимированный индикатор с меткой этапа (Thinking, Running <Tool>, Calling <server>:<tool>, Running N tools) и сменой цвета (пурпурный → жёлтый через 30 сек → красный через 60 сек)
• Отображение вызовов инструментов — предпросмотр аргументов, потоковый вывод в реальном времени, сводки результатов (количество строк, затраченное время), разворачивание/сворачивание по Tab. Цвет имени инструмента зависит от категории (инструменты чтения — голубые, изменяющие — жёлтые, исполняющие — пурпурные, MCP-инструменты — зелёные)
• Богатый вывод инструментов — JSON-файлы отображаются как цветное статическое дерево (сворачивание на глубине 3, обрезка строк); markdown-файлы отображаются с полным стилизованным форматированием (заголовки, блоки кода, таблицы) вместо простого разбиения по строкам. Рендерер выбирается на основе поля outputType, добавляемого FileReadTool / WebFetchTool, с эвристическим запасным вариантом для инструментов без этого поля
• Вложенные вызовы инструментов — когда Agent или ParallelAgents порождает внутренние вызовы (Read, Bash, Edit), дочерние элементы отображаются с отступом под родительским. ParallelAgents показывает обёртки Task для каждой задачи, так что дочерние вызовы группируются по задачам, а не плоско под общим родителем. Ограничение глубины отступа — 3 уровня, с маркером сворачивания … (N more level)
• Символ переноса многострочного ввода — каждая не последняя строка многострочного ввода заканчивается тусклым символом ↵ для визуального обозначения переноса
• Запросы разрешений — рамка с цветовой индикацией риска, жирные цветные клавиши Yes/No/Diff, подсвеченные инлайн-диффы
• Строка состояния — имя модели, количество токенов, стоимость, индикатор использования контекста (настраивается через конфиг)
• Предупреждение о контексте — жёлтое предупреждение при превышении 75% окна контекста
• Встроенная прокрутка терминала — завершённые сообщения уходят в историю; используйте прокрутку и поиск вашего терминала
• Многострочный ввод — Alt+Enter для новых строк; автоматическое определение вставки добавляет переносы строк
• Автодополнение — слэш-команды и пути файлов с описаниями; Tab для циклического перебора
• Автодополнение путей файлов — Tab дополняет пути с индикаторами [dir]/[file]
• Браузер сессий — /browse для интерактивного просмотра и возобновления прошлых сессий
• Компаньон-маскот — анимированный Cybergotchi в нижнем колонтитуле (переключение через /companion off|on)

Темы

oh --light                    # light theme for bright terminals
/theme light                  # switch mid-session (saved automatically)
/theme dark                   # switch back

Настройка темы сохраняется в .oh/config.yaml и действует между сессиями.

Настраиваемая строка состояния

Настройте формат строки состояния в .oh/config.yaml:

statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'

Доступные переменные: {model}, {tokens} (вход ↑ выход ↓), {cost} ($X.XXXX), {ctx} (индикатор использования контекста). Пустые секции автоматически сворачиваются.

Инструменты (44)

Инструмент	Риск	Описание
Базовые
Bash	высокий	Выполнение команд оболочки с потоковым выводом в реальном времени (анализ безопасности AST)
PowerShell	высокий	Выполнение команд PowerShell (нативные сценарии Windows)
Read	низкий	Чтение файлов с указанием диапазонов строк, поддержка PDF
ImageRead	низкий	Чтение изображений/PDF для мультимодального анализа
Write	средний	Создание или перезапись файлов
Edit	средний	Правки с поиском и заменой
MultiEdit	средний	Атомарные многофайловые правки (все успешны или ни одна)
Glob	низкий	Поиск файлов по шаблону
Grep	низкий	Регулярный поиск содержимого с контекстными строками
LS	низкий	Вывод содержимого каталога с размерами
Веб
WebFetch	средний	Получение содержимого URL (защита от SSRF)
WebSearch	средний	Поиск в интернете
ExaSearch	средний	Нейронный веб-поиск через Exa (требуется EXA_API_KEY)
RemoteTrigger	высокий	HTTP-запросы к вебхукам/API
Задачи
TaskCreate	низкий	Создание структурированных задач
TaskUpdate	низкий	Обновление статуса задачи
TaskList	низкий	Список всех задач
TaskGet	низкий	Получение деталей задачи
TaskStop	низкий	Остановка выполняемой задачи
TaskOutput	низкий	Получение вывода задачи
TodoWrite	низкий	Управление чек-листом задач сессии (совместимо с Claude Code)
Агенты
Agent	средний	Запуск подагента (с специализацией роли)
ParallelAgent	средний	Запуск нескольких агентов с DAG-зависимостями
SendMessage	низкий	Обмен сообщениями между агентами
AskUser	низкий	Задать вопрос пользователю с вариантами ответов
Планировщик
CronCreate	средний	Планирование повторяющихся задач
CronDelete	средний	Удаление запланированных задач
CronList	низкий	Список всех запланированных задач
ScheduleWakeup	низкий	Самостоятельное регулирование темпа следующей итерации /loop (с учётом кэша)
Планирование
EnterPlanMode	низкий	Вход в структурированный режим планирования
ExitPlanMode	низкий	Выход из режима планирования
Конвейеры
Pipeline	средний	Выполнение последовательности задач с передачей вывода между шагами
Интеллект кода
Diagnostics	низкий	Диагностика кода на основе LSP
NotebookEdit	средний	Редактирование Jupyter-блокнотов
Память и поиск
Memory	низкий	Сохранение/список/поиск постоянных воспоминаний
Skill	низкий	Вызов навыка из .oh/skills/
ToolSearch	низкий	Поиск инструментов по описанию
SessionSearch	низкий	Поиск предыдущих сессий для релевантного контекста
MCP
ListMcpResources	низкий	Список ресурсов подключённых MCP-серверов
ReadMcpResource	низкий	Чтение конкретного MCP-ресурса по URI
Git-рабочие деревья
EnterWorktree	средний	Создание изолированного git-рабочего дерева
ExitWorktree	средний	Удаление git-рабочего дерева
Процесс
KillProcess	высокий	Остановка процессов по PID или имени
Monitor	средний	Запуск фоновой команды и потоковая передача каждой строки вывода обратно агенту

Инструменты с низким риском только для чтения одобряются автоматически. Инструменты со средним и высоким риском требуют подтверждения в режиме ask. Используйте --trust или --auto, чтобы пропустить запросы.

Слэш-команды

Зарегистрировано более 80 команд. Наиболее часто используемые сгруппированы ниже; полный список см. в /help в сессии. Псевдонимы: /q выход, /h помощь, /c коммит, /m модель, /s статус.

Сессия:

Команда	Описание
/clear	Очистить историю разговора
/compact	Сжать разговор для освобождения контекста
/export	Экспортировать разговор в markdown
/copy [n]	Скопировать N-й последний ответ ассистента в системный буфер обмена
/history [n]	Список недавних сессий; /history search <термин> для поиска
/browse	Интерактивный браузер сессий с предпросмотром
/resume <id>	Возобновить сохранённую сессию
/fork	Создать ответвление текущей сессии

Git:

Команда	Описание
/diff	Показать незакоммиченные git-изменения
/undo	Отменить последний AI-коммит
/commit [сообщение]	Создать git-коммит
/log	Показать недавние git-коммиты

Информация:

Команда	Описание
/help	Показать все доступные команды (по категориям)
/cost	Показать стоимость сессии и использование токенов
/status	Показать модель, режим, git-ветку, MCP-серверы
/config	Показать конфигурацию
/files	Список файлов в контексте
/model <имя>	Переключить модель в середине сессии
/memory	Просмотр и поиск воспоминаний
/doctor	Запуск диагностических проверок состояния
/hooks	Список загруженных хуков, сгруппированных по событиям
/reload-plugins	Горячая перезагрузка плагинов, навыков, хуков и подключений MCP-серверов без перезапуска сессии

Настройки:

Команда	Описание
/theme dark\|light	Переключить тему (сохраняется в конфигурации)
/vim	Переключить режим Vim
/companion off\|on	Переключить видимость компаньона
/keys	Показать сочетания клавиш
/keybindings	Открыть ~/.oh/keybindings.json в $EDITOR (создаёт стартовый файл, если отсутствует)

ИИ:

Команда	Описание
/plan <задача>	Войти в режим планирования
/review	Проверить недавние изменения кода
/summarize	Суммировать текущий разговор
/recap	Краткое резюме сессии одним предложением (легче, чем /summarize)

Питомец:

Команда	Описание
/cybergotchi	Покормить, погладить, отдохнуть, статус, переименовать или сбросить вашего компаньона

Режимы разрешений

Управление тем, насколько агрессивно OpenHarness автоматически одобряет вызовы инструментов:

Режим	Флаг	Поведение
ask	--permission-mode ask	Запрашивать подтверждение для операций со средним/высоким риском (по умолчанию)
trust	--trust	Автоматически одобрять всё
deny	--deny	Разрешать только операции с низким риском только для чтения
acceptEdits	--permission-mode acceptEdits	Автоматически одобрять правки файлов, запрашивать для Bash/WebFetch/Agent
plan	--permission-mode plan	Режим только для чтения — блокировать все операции записи
auto	--auto	Автоматически одобрять всё, блокировать опасный bash (анализ AST)
bypassPermissions	--permission-mode bypassPermissions	Одобрять всё безоговорочно (только для CI)
Bash-команды анализируются легковесным AST-парсером, который обнаруживает деструктивные шаблоны (rm -rf, git push --force, curl | bash и т.д.) и соответствующим образом корректирует уровень риска.

Установите постоянно в .oh/config.yaml: permissionMode: 'acceptEdits'

Хуки

Запускайте shell-скрипты автоматически при ключевых событиях сессии, добавив блок hooks в .oh/config.yaml:

hooks:
  - event: sessionStart
    command: "echo 'Session started' >> ~/.oh/session.log"

  - event: preToolUse
    command: "scripts/check-tool.sh"
    match: Bash   # optional: only trigger for this tool name

  - event: postToolUse
    command: "scripts/after-tool.sh"

  - event: sessionEnd
    command: "scripts/cleanup.sh"

Типы событий (всего 27 — соответствует стабильному API Claude Code):

Событие	Когда срабатывает	Может блокировать?
sessionStart	Начало сессии	—
sessionEnd	Окончание сессии	—
turnStart	Начало хода агента верхнего уровня (после принятия пользовательского запроса)	—
turnStop	Окончание хода агента верхнего уровня (зеркально отражает Stop из Claude Code)	—
userPromptSubmit	До того, как пользовательский запрос достигнет LLM	да — decision: deny
userPromptExpansion	Слэш-команда создаёт расширенный запрос (аудит-трейл)	—
preToolUse	Перед каждым вызовом инструмента	да — код выхода 1 / decision: deny
postToolUse	После успешного выполнения инструмента	—
postToolUseFailure	После того, как инструмент выбросил исключение или вернул isError: true	—
postToolBatch	Один раз после того, как весь набор вызовов инструментов за ход завершился, перед следующим вызовом модели	—
permissionRequest	Когда инструменту требуется одобрение (между preToolUse и запросом)	да — decision: allow\|deny\|ask
permissionDenied	Когда вызов инструмента отклонён (хук / пользователь / headless / политика)	—
fileChanged	После того, как инструмент изменил файл	—
cwdChanged	После изменения рабочей директории	—
subagentStart	Создан субагент	—
subagentStop	Субагент завершил работу	—
preCompact	Перед сжатием разговора	—
postCompact	После сжатия разговора	—
configChange	.oh/config.yaml изменён во время сессии	—
notification	Отправлено уведомление	—
taskCreated	TaskCreate сохраняет новую задачу	—
taskCompleted	TaskUpdate переводит задачу в состояние completed	—
worktreeCreate	EnterWorktreeTool создаёт изолированный git worktree	—
worktreeRemove	ExitWorktreeTool удаляет git worktree	—
elicitation	MCP-сервер запрашивает ввод пользователя через elicitation/create	да — decision: allow\|deny
elicitationResult	После того, как ответ на элицитацию был определён (аудит-трейл)	—
instructionsLoaded	loadRulesAsPrompt пересобрал системный промпт с учётом действующих правил	—

Установите disableAllHooks: true в .oh/config.yaml, чтобы глобально отключить выполнение хуков, сохраняя определения на диске для аудита.

Живая интроспекция: выполните /hooks в сессии, чтобы увидеть, какие хуки загружены, сгруппированные по событиям.

Переменные окружения, доступные скриптам хуков:

Переменная	Описание
OH_EVENT	Тип события (sessionStart, preToolUse и т.д.)
OH_TOOL_NAME	Имя вызываемого инструмента (только для событий инструментов)
OH_TOOL_ARGS	JSON-кодированные аргументы инструмента (только для событий инструментов)
OH_TOOL_OUTPUT	JSON-кодированный вывод инструмента (только postToolUse)
OH_TOOL_INPUT_JSON	Полный JSON-ввод инструмента (только для событий инструментов)
OH_SESSION_ID / OH_MODEL / OH_PROVIDER / OH_PERMISSION_MODE	Текущий контекст сессии
OH_COST / OH_TOKENS	Текущая стоимость и общее количество токенов
OH_FILE_PATH	Путь к изменённому файлу (только fileChanged)
OH_NEW_CWD	Новая рабочая директория (только cwdChanged)
OH_TURN_NUMBER / OH_TURN_REASON	Контекст границы хода (turnStart / turnStop)

Используйте match, чтобы ограничить хук конкретным именем инструмента (например, match: Bash срабатывает только для инструмента Bash). Поддерживаются подстроки, глоб (Cron*) и шаблоны /regex/flags.

Установите jsonIO: true для хука command, чтобы использовать структурированный JSON-ввод/вывод — харнесс отправляет {event, ...context} в stdin и читает {decision, reason, hookSpecificOutput} из stdout. HTTP-хуки принимают ту же форму ответа. Полную документацию см. в docs/hooks.md.

Киберготчи

OpenHarness поставляется с компаньоном в стиле тамагочи, который живет на боковой панели. Он реагирует на вашу сессию в реальном времени — празднует серии, жалуется, когда инструменты выходят из строя, и голодает, если вы его игнорируете.

Вырастите одного:

oh init        # wizard includes cybergotchi setup
/cybergotchi   # or hatch mid-session

Команды:

/cybergotchi feed      # +30 hunger
/cybergotchi pet       # +20 happiness
/cybergotchi rest      # +40 energy
/cybergotchi status    # show needs + lifetime stats
/cybergotchi rename    # give it a new name
/cybergotchi reset     # start over with a new species

Потребности со временем убывают (голод быстрее всего, счастье медленнее). Кормите и гладьте своего готчи, чтобы он был счастлив. Эволюция — ваш готчи эволюционирует на основе жизненных этапов: - Этап 1 (✦ пурпурный): 10 сессий или 50 коммитов - Этап 2 (★ жёлтый + корона): 100 выполненных задач или серия из 25 инструментов

18 видов на выбор: утка, кошка, сова, пингвин, кролик, черепаха, улитка, осьминог, аксолотль, кактус, гриб, чонк, капибара, гусь и другие.

MCP-серверы

Подключите любой MCP-сервер (Model Context Protocol), отредактировав .oh/config.yaml:

provider: anthropic
model: claude-sonnet-4-6
permissionMode: ask
mcpServers:
  - name: filesystem
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ghp_...

MCP-инструменты появляются рядом со встроенными инструментами. /status показывает подключённые серверы.

Промпты MCP-серверов как слэш-команды — серверы, которые предоставляют prompts/list (например, GitHub, Sentry, Linear), автоматически отображают свои промпты как слэш-команды /<server>:<prompt>. Аргументы используют синтаксис key=value с кавычками:

/github:summarize-pr repo=acme/widget pr=42
/sentry:triage-issue issue=ABC-123 severity="high priority"

Обязательные аргументы, объявленные шаблоном промпта, вызывают ошибку использования, если они отсутствуют (без вызова модели). Выполните /reload-plugins, чтобы заново обнаружить промпты после изменения конфигурации MCP.

Удалённые MCP-серверы (HTTP / SSE)

mcpServers:
  - name: linear
    type: http
    url: https://mcp.linear.app/mcp
    headers:
      Authorization: "Bearer ${LINEAR_API_KEY}"

Полную справку см. в docs/mcp-servers.md. Настройку OAuth 2.1 (автоматически срабатывает при 401; доступны команды /mcp-login и /mcp-logout) см. в docs/mcp-servers.md.

Реестр MCP-серверов — просмотр и установка из курируемого каталога:

/mcp-registry              # browse all available servers
/mcp-registry github       # show install config for a specific server
/mcp-registry database     # search by category

Категории: файловая система, git, база данных, API, поиск, продуктивность, инструменты разработки, ИИ.

Интеграция с Git

OpenHarness автоматически коммитит изменения ИИ в git-репозиториях:

oh: Edit src/app.ts                    # auto-committed with "oh:" prefix
oh: Write tests/app.test.ts

• Каждое изменение файла ИИ коммитится автоматически
• /undo откатывает последний коммит ИИ (только коммиты OH, никогда ваши)
• /diff показывает, что изменилось
• Ваши незакоммиченные файлы в безопасности — они коммитятся отдельно перед изменениями ИИ

Контрольные точки и откат

Каждое изменение файла автоматически сохраняется в контрольной точке перед выполнением. Если что-то пошло не так:

/rewind           # restore files from the last checkpoint
/undo             # revert the last AI git commit

Контрольные точки хранятся в .oh/checkpoints/ и охватывают FileWrite, FileEdit и Bash-команды, изменяющие файлы.

Циклы проверки

После каждого изменения файла (Edit, Write, MultiEdit) OpenHarness автоматически запускает соответствующие языку команды линтинга/проверки типов и передаёт результаты обратно в контекст агента. Это самый эффективный паттерн инженерии харнесса — исследования показывают улучшение качества в 2-3 раза за счёт автоматической обратной связи.

Автоопределение — если в вашем проекте есть tsconfig.json, .eslintrc*, pyproject.toml, go.mod или Cargo.toml, правила проверки определяются автоматически. Настройка не требуется.

Пользовательские правила через .oh/config.yaml:

verification:
  enabled: true       # default: true (auto-detect)
  mode: warn          # 'warn' appends to output, 'block' marks as error
  rules:
    - extensions: [".ts", ".tsx"]
      lint: "npx tsc --noEmit 2>&1 | head -20"
      timeout: 15000
    - extensions: [".py"]
      lint: "ruff check {file} 2>&1 | head -10"

Агент видит [Verification passed] или [Verification FAILED] с выводом линтера после каждого изменения, что позволяет самокоррекцию.

Консолидация памяти

При завершении сессии OpenHarness автоматически удаляет устаревшие воспоминания, используя временное затухание:

• Воспоминания, не использованные более 30 дней, теряют 0,1 релевантности за каждый период в 30 дней
• Воспоминания с релевантностью ниже 0,1 удаляются навсегда
• Обновлённые оценки релевантности сохраняются в файлы памяти

Это поддерживает систему памяти в актуальном и релевантном состоянии. Настройка в .oh/config.yaml:

memory:
  consolidateOnExit: true   # default: true

Планировщик задач (Cron)

Создавайте повторяющиеся задачи, которые автоматически выполняются в фоновом режиме:

# Via slash commands
/cron list                    # show all scheduled tasks
/cron create "check-tests"    # create a new task (interactive)
/cron delete <id>             # remove a task

Синтаксис расписания: every 5m, every 2h, every 1d

Исполнитель cron проверяет каждые 60 секунд наличие задач и запускает их через подзапросы. Результаты сохраняются в ~/.oh/crons/history/.

Роли агентов

Отправляйте специализированных субагентов для целевых задач:

/roles            # list all available roles

Роль	Описание	Инструменты
code-reviewer	Поиск ошибок, проблем безопасности, проблем стиля	Только чтение
test-writer	Создание модульных и интеграционных тестов	Чтение + Запись
docs-writer	Написание документации и комментариев	Чтение + Запись + Редактирование
debugger	Систематическое расследование ошибок	Только чтение + Bash
refactorer	Упрощение кода без изменения поведения	Все файловые инструменты + Bash
security-auditor	OWASP, инъекции, секреты, сканирование CVE	Только чтение + Bash
evaluator	Оценка качества кода и запуск тестов (только чтение)	Только чтение + Bash + Диагностика
planner	Разработка пошаговых планов реализации	Только чтение + Bash
architect	Анализ архитектуры и проектирование структурных изменений (передаёт редактору)	Только чтение
editor	Применяет план архитектора как правки кода, без повторного планирования	Read + Edit + Write + MultiEdit + Bash
migrator	Систематические миграции и обновления кодовой базы	Все файловые инструменты + Bash

Каждая роль ограничивает субагента только его предлагаемыми инструментами. Вы также можете явно передать allowed_tools:

Agent({ subagent_type: 'evaluator', prompt: 'Run all tests and report results' })
Agent({ allowed_tools: ['Read', 'Grep'], prompt: 'Search for all TODO comments' })

Архитектор → Редактор (экономия при многофайловых правках)

Для крупных изменений, затрагивающих несколько файлов, запустите двухэтапный процесс architect → editor. Архитектор (мощная модель) читает кодовую базу и выводит структурированный план; редактор (быстрая модель) применяет его механически, без повторного планирования. Когда настроен modelRouter, OH автоматически направляет роль architect на ваш уровень powerful, а роль editor — на уровень fast — типичная экономия затрат составляет 30-50% при многофайловых правках по сравнению с выполнением обоих этапов на мощной модели.

Agent({ subagent_type: 'architect', prompt: 'Plan a migration from option A to option B across src/' })
# Hand the resulting plan to:
Agent({ subagent_type: 'editor', prompt: '<paste plan>' })

Изоляция разрешений субагента

Каждый вызов Agent принимает переопределение permission_mode, которое сужает режим разрешений родителя (никогда не ослабляет его). Полезно при работе в режиме trust, когда вы хотите, чтобы проверка/аудит субагента оставался строго только для чтения:

Agent({ subagent_type: 'code-reviewer', prompt: '...', permission_mode: 'plan' })
Agent({ subagent_type: 'security-auditor', prompt: '...', permission_mode: 'deny' })

Если запрашивается менее ограничительный режим (например, родитель — ask, субагент запрашивает trust), система автоматически ограничивает до родительского — модель никогда не сможет использовать субагента для обхода этапов одобрения пользователем.

Роли только для чтения по умолчанию автоматически получают режим plan. code-reviewer, evaluator, security-auditor, architect и planner поставляются с permissionMode: 'plan' — запустите их под любым родителем, и они будут статически только для чтения, без необходимости переопределения permission_mode. Агенты, определенные в Markdown-файлах .oh/agents/*.md, могут установить собственное значение по умолчанию с помощью frontmatter permissionMode: plan (или permission-mode: plan).

Безголовый режим

Запуск одного запроса без интерактивного интерфейса — идеально для CI/CD и скриптов:

# Chat command with -p flag (recommended)
oh -p "fix the failing tests" --model ollama/llama3 --trust
oh -p "review src/query.ts" --auto --output-format json

# Run command (alternative)
oh run "fix the failing tests" --model ollama/llama3 --trust
oh run "add error handling to api.ts" --json    # JSON output

# Pipe stdin
cat error.log | oh run "what's wrong here?"
git diff | oh run "review these changes"

# Hard cap on session cost — agent halts at the threshold with reason: "budget_exceeded"
oh run "review the diff" --model claude-sonnet-4-6 --max-budget-usd 0.50
oh session --model gpt-4o --max-budget-usd 5

Флаги CLI для CI / SDK

Флаг	Действие
--bare	Пропускает необязательные действия при запуске (определение проекта, плагины, память, навыки, MCP). Системный промпт — только базовая основа использования инструментов. Более быстрый запуск в репозиториях с множеством файлов CLAUDE.md / RULES.md.
--debug [категории]	Включает категоризированные журналы отладки. --debug без аргументов включает все; --debug mcp,hooks фильтрует. Использует переменную окружения OH_DEBUG как запасный вариант.
--debug-file <путь>	Добавляет строки отладки в файл вместо stderr. Использует OH_DEBUG_FILE как запасный вариант.
--mcp-config <путь>	Загрует MCP-серверы из внешнего JSON-файла (в дополнение к .oh/config.yaml).
--strict-mcp-config	При использовании с --mcp-config полностью игнорирует MCP-серверы из .oh/config.yaml.
--system-prompt-file <путь> / --append-system-prompt-file <путь>	Файловые варианты --system-prompt / --append-system-prompt.
--no-session-persistence	Не записывает сессию в ~/.oh/sessions/ для эфемерных CI-запусков.
--fallback-model <модель>	Запасная модель, используемая, когда основная завершается с ошибкой, которую можно повторить. ЗАМЕНЯЕТ fallbackProviders из .oh/config.yaml для этого запуска.
--permission-prompt-tool <mcp_tool>	Делегирует решения о разрешениях инструментов настроенному MCP-инструменту (например, mcp__myperm__check).
--init / --init-only	Запускает интерактивный мастер настройки перед / вместо команды.

Все флаги работают как с oh run, так и с oh session. Полный список см. в oh run --help и oh session --help.

Структурированный вывод с --json-schema

Ограничивает вывод модели схемой JSON. Полезно для CI-скриптов, которые программно разбирают вывод модели без эвристик на основе регулярных выражений:

oh -p "output {\"ok\": true, \"count\": 3} as JSON" \
  --trust \
  --json-schema '{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"}},"required":["ok","count"]}'

Поведение: - stdout: проверенный JSON (одной строкой), только если он соответствует схеме. - stderr: структурированные ошибки при неудаче, а также необработанный вывод модели для отладки. - Коды выхода: 0 — допустимо, 2 — некорректная схема, 3 — вывод модели не является JSON, 4 — JSON не соответствует схеме.

Поддерживаемые ключевые слова: type, properties, required, items, enum. Для более полной проверки передайте вывод через специальный валидатор.

GitHub Action для проверки PR

OpenHarness включает встроенный GitHub Action для автоматической проверки кода:

# .github/workflows/ai-review.yml
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: ./.github/actions/review
        with:
          model: 'claude-sonnet-4-6'
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Код выхода 0 при успехе, 1 при неудаче.

Провайдеры

# Local (free, no API key needed)
oh --model ollama/llama3
oh --model ollama/qwen2.5:7b

# Cloud
OPENAI_API_KEY=sk-... oh --model gpt-4o
ANTHROPIC_API_KEY=sk-ant-... oh --model claude-sonnet-4-6
OPENROUTER_API_KEY=sk-or-... oh --model openrouter/meta-llama/llama-3-70b

# llama.cpp / GGUF
oh --model llamacpp/my-model

# LM Studio
oh --model lmstudio/my-model

llama.cpp / GGUF (локально, без Ollama)

Для прямой поддержки GGUF через llama-server, без накладных расходов Ollama. Часто быстрее для больших моделей.

Предварительные требования: - Установите llama.cpp: brew install llama.cpp или скачайте с github.com/ggml-org/llama.cpp - Загрузите модель GGUF (например, с HuggingFace)

Запустите llama-server:

llama-server --model ./your-model.gguf --port 8080 --alias my-model

Настройка через oh init: - Запустите oh init и выберите "llama.cpp / GGUF" при запросе

Или настройте вручную в .oh/config.yaml:

provider: llamacpp
model: my-model
baseUrl: http://localhost:8080
permissionMode: ask

Запуск:

oh
oh --model llamacpp/my-model
oh models                    # list available models

ACP (Agent Client Protocol)

Общайтесь по Agent Client Protocol через stdin/stdout, чтобы редакторы, поддерживающие ACP — Zed, JetBrains через плагин ACP, Cline, OpenCode — могли управлять openHarness как базовым агентом. Не требуется специального расширения IDE:

oh acp                                          # uses provider/model from .oh/config.yaml
oh acp --provider anthropic --model claude-sonnet-4-6

Настройте интеграцию ACP вашего редактора для запуска oh acp в качестве команды агента. События обновления сеанса (текстовые фрагменты, вызовы инструментов, результаты инструментов) автоматически транслируются из потокового протокола openHarness; запросы разрешений в настоящее время используют собственный поток openHarness, а не путь ACP requestPermission (отмечено для последующего улучшения). Пакет @agentclientprotocol/sdk является optionalDependency — если он не установился, oh acp завершается с понятной подсказкой по установке, а не молча выходит.

Аутентификация

Управление учетными данными, независимое от провайдера. Локальным LLM (Ollama / llama.cpp / LM Studio) не требуется аутентификация — настройте их через oh init.

oh auth login [provider] [--key <value>]   # store API key for a provider
oh auth logout [provider]                   # clear stored API key
oh auth status                              # show stored providers + env-var overrides

[provider] по умолчанию соответствует вашему настроенному провайдеру по умолчанию. --key передает значение напрямую; в противном случае OH запрашивает (TTY) или читает из stdin (через конвейер).

Разрешение ключей на основе скриптов (apiKeyHelper)

Избегайте хранения ключей в открытом виде / в зашифрованном хранилище, подключив вспомогательный скрипт (1Password, pass, vault, облачный менеджер секретов). Настроенная команда выполняется при получении учетных данных с установленным OH_PROVIDER, а её обрезанный stdout становится ключом.

# .oh/config.yaml
apiKeyHelper: 'op read "op://Personal/Anthropic/key"'

Приоритет разрешения: переменная окружения → зашифрованное хранилище → apiKeyHelper → устаревшая конфигурация в открытом виде.

Обновление

oh update                    # detects how OH was installed (npm-global / npx / local clone) and prints the right upgrade command

Иерархия конфигурации

Конфигурация загружается слоями (более поздние переопределяют более ранние):

1. Глобальная ~/.oh/config.yaml — провайдер, модель, тема по умолчанию для всех проектов
2. Проектная .oh/config.yaml — настройки для конкретного проекта
3. Локальная .oh/config.local.yaml — личные переопределения (в .gitignore)

Установите провайдера по умолчанию один раз глобально:

# ~/.oh/config.yaml
provider: ollama
model: llama3
permissionMode: ask
theme: dark
language: zh-CN        # optional — respond in this language (code stays as-is)
outputStyle: default   # optional — "default", "explanatory", "learning", or a custom name

Затем конфигурации для каждого проекта нуждаются только в отличиях:

# .oh/config.yaml
model: codellama   # override just the model

Стили вывода

Меняйте "личность" агента, не затрагивая его основные инструкции. Встроенные:

• default — стандартный ассистент по разработке ПО (без предисловия)
• explanatory — добавляет раздел ## Insights после каждой задачи, объясняющий почему агент сделал свой выбор
• learning — оставляет 1–3 маркера TODO(human) в стратегических точках, чтобы вы сами написали обучающие части

Создавайте свои стили как markdown-файлы с YAML-преамбулой. Сохраняйте в .oh/output-styles/<name>.md (проект) или ~/.oh/output-styles/<name>.md (пользователь). Проектный стиль перекрывает пользовательский, пользовательский — встроенный.

---
name: code-review
description: Focused code review mode
---

Review rigorously. For every function, ask: is the logic correct, is error handling complete, are there edge cases ignored?

Активируйте с помощью outputStyle: code-review в .oh/config.yaml.

Правила проекта

Создайте .oh/RULES.md в любом репозитории (или запустите oh init):

- Always run tests after changes
- Use strict TypeScript
- Never commit to main directly

Правила автоматически загружаются в каждую сессию.

openHarness также читает любые из следующих файлов с инструкциями проекта, если они присутствуют (аддитивно, от родительских к дочерним):

• CLAUDE.md (соглашение Anthropic) — и иерархические CLAUDE.md из родительских каталогов, плюс ~/.claude/CLAUDE.md для общепользовательского уровня
• AGENTS.md (стандарт agents.md для кросс-инструментов, используется Codex / Cursor / Copilot / Cline / Aider) — аналогичный обход от родителей к детям
• CLAUDE.local.md (личные переопределения, игнорируемые Git)

Если в репозитории уже есть AGENTS.md, настроенный для другого агента, openHarness использует его без изменений — шаг миграции не требуется.

Навыки и плагины

Навыки

Навыки — это markdown-файлы с YAML-преамбулой, которые добавляют переиспользуемое поведение:

---
name: deploy
description: Deploy the application to production
trigger: deploy
tools: [Bash, Read]
---

Run the deploy script with health checks...

Расположение (поиск в порядке): 1. .oh/skills/ — навыки уровня проекта 2. ~/.oh/skills/ — глобальные навыки (доступны во всех проектах)

Навыки автоматически срабатывают, когда сообщение пользователя содержит ключевое слово-триггер, или могут быть вызваны явно с помощью /skill deploy.

Плагины

Плагины — это npm-пакеты, которые объединяют навыки, хуки и MCP-серверы:

{
  "name": "my-openharness-plugin",
  "version": "1.0.0",
  "skills": ["skills/deploy.md", "skills/review.md"],
  "hooks": {
    "sessionStart": "scripts/setup.sh"
  },
  "mcpServers": [
    { "name": "my-api", "command": "npx", "args": ["-y", "@my-org/mcp-server"] }
  ]
}

Сохраните как openharness-plugin.json в корне вашего npm-пакета. Установите с помощью npm install, и openHarness обнаружит его автоматически в node_modules/.

Оценки

oh evals запускает оценки, совместимые с SWE-bench-Lite, для любого провайдера, локально, с обязательными ограничениями стоимости. Полезно для измерения реальной производительности исправления ошибок вместо синтетических бенчмарков.

# Run a custom pack with a $5 total cap, 2 parallel agents
oh evals run my-pack --max-cost-usd 5 --concurrency 2

# Run a specific instance
oh evals run my-pack --max-cost-usd 1 --instance django__django-11551

# Random sample of 3
oh evals run my-pack --max-cost-usd 2 --sample 3

# Resume a partial run that hit its cost cap
oh evals run my-pack --max-cost-usd 10 --resume 2026-05-05T14-30-00

# List installed packs
oh evals list-packs

# Show summary of a past run
oh evals show 2026-05-05T14-30-00

Вывод находится в ~/.oh/evals/runs/<run-id>/:

• results.json — полные данные по каждой задаче: стоимость, количество ходов, длительность, статус тестов, сообщение об ошибке.
• predictions.json — можно отправить в таблицу лидеров SWE-bench на https://www.swebench.com/.
• transcripts/<instance_id>.jsonl — дословный вывод подпроцесса stream-json для каждой задачи.

Контракт подключаемого пакета (pack.json + instances.jsonl + fixtures/<id>/) позволяет создавать пакеты для любого тестового набора. Хелпер scripts/build-evals-pack.mjs превращает репозиторий, совместимый с SWE-bench-Lite, в фикстуру на основе заданного base_commit; см. CONTRIBUTING.md.

В комплекте поставляется пакет swe-bench-lite-mini (10 отобранных экземпляров, готовых к запуску из коробки) в версии v2.40.2.

Как это работает

graph LR
    User[User Input] --> REPL[REPL Loop]
    REPL --> Query[Query Engine]
    Query --> Provider[LLM Provider]
    Provider --> LLM[Ollama / OpenAI / Anthropic]
    LLM --> Tools[Tool Execution]
    Tools --> Permissions{Permission Check}
    Permissions -->|Approved| Execute[Run Tool]
    Permissions -->|Blocked| Deny[Deny & Report]
    Execute --> Response[Stream Response]
    Response --> REPL

Часто задаваемые вопросы

Работает ли он офлайн? Да. Используйте Ollama с локальной моделью — интернет или API-ключ не нужны.

Сколько это стоит? Бесплатно. OpenHarness лицензирован под MIT. Вы используете свой API-ключ (BYOK) для облачных моделей или используете Ollama бесплатно.

Это безопасно? Да. 7 режимов разрешений контролируют, что могут делать инструменты. Bash-команды анализируются AST-парсером, который блокирует деструктивные шаблоны (rm -rf, curl | bash и т.д.). Каждое изменение файла сохраняется в контрольной точке и может быть отменено с помощью /rewind.

Можно ли использовать его в CI/CD? Да. Используйте oh -p "prompt" --auto для безголового выполнения или встроенное GitHub Action для проверки PR.

Поддерживает ли он мой язык/фреймворк? Да. OpenHarness не зависит от языка — он читает, пишет и выполняет код на любом языке. Подсветка синтаксиса охватывает более 20 языков.

Как он соотносится с Claude Code? ~95% паритета функций для случаев использования CLI. Главное преимущество: работает с ЛЮБОЙ LLM (не только Anthropic) и лицензирован под MIT. См. Почему OpenHarness? выше.

Установка

Требуется Node.js 18+.

# From npm
npm install -g @zhijiewang/openharness

# From source
git clone https://github.com/zhijiewong/openharness.git
cd openharness
npm install && npm install -g .

Разработка

npm install
npx tsx src/main.tsx              # run in dev mode
npx tsc --noEmit                  # type check
npm test                          # run tests

Добавление инструмента

Создайте src/tools/YourTool/index.ts, реализующий интерфейс Tool со схемой ввода Zod, зарегистрируйте его в src/tools.ts.

Добавление провайдера

Создайте src/providers/yourprovider.ts, реализующий интерфейс Provider, добавьте случай в src/providers/index.ts.

Участие в разработке

См. CONTRIBUTING.md.

Сообщество

Присоединяйтесь к сообществу OpenHarness, чтобы получить помощь, поделиться своими рабочими процессами и обсудить будущее AI-агентов для кодирования!

Платформа	Детали и ссылки
🟣 Discord	Присоединяйтесь к нашему Discord-серверу, чтобы общаться с разработчиками и получать поддержку в реальном времени.
🔵 Feishu / Lark	Отсканируйте QR-код ниже, чтобы сотрудничать с сообществом:
🟢 WeChat	Отсканируйте QR-код ниже, чтобы присоединиться к нашей группе WeChat:

Лицензия

MIT