Руководство по Orca: worktree, агенты, тесты и проверка изменений

Orca — среда разработки, объединяющая пространства Git, агентов программирования, терминалы, браузер и проверку изменений. Отдельная worktree для каждой задачи позволяет работать с разными изменениями в отдельных ветках и папках. Проверяйте завершение по фактическому пути работы, результатам тестов и diff относительно базовой ветки, а не только по ответу агента.

Речь об официальном приложении Orca компании Stably AI. Руководство основано на Orca 1.4.256 под macOS, прилагаемой инструкции CLI, Node.js 24.13.0, Python 3 и Git. Проверены просмотр текущего пространства, запуск тестов примера в терминале Orca, обнаружение порта и отображение во встроенном браузере. Создание или слияние worktree и запуск новой задачи агента ИИ не выполнялись; запросы и команды создания ниже предназначены для самостоятельного упражнения.

Чем отличаются проект и worktree?

Откройте локальный Git-репозиторий через Add Repo по официальной инструкции первой сессии. Даже если проектом управляет Orca, исходники и коммиты остаются в Git-репозитории. Условия использования и аутентификацию модели/провайдера подготовьте отдельно.

Элемент	Роль в упражнении
Проект	Объединяет Git-репозиторий примера и рабочие пространства
Worktree	Рабочая папка с выбранной веткой и её рабочее представление
Агент	Предлагает чтение и изменение файлов и запуск команд в заданных границах
Терминал	Запускает тесты и сервер разработки в папке задачи
Встроенный браузер	Проверяет реальную страницу сервера и граничные значения

Документация worktree Orca и руководство CLI объясняют связь файлов, веток и рабочих представлений. Не предполагайте, что выбор другой worktree в интерфейсе автоматически изменит текущую папку уже открытого shell. Первый шаг — проверить путь и ветку в терминале, где будут выполняться команды.

Создаём небольшой пример и проверяем исходное состояние

Используем условную политику доставки: при заказе от 50 000 вон доставка бесплатна, ниже — 3 000 вон, принимаются только неотрицательные безопасные целые числа. Это не политика реального сервиса. Сохраните следующие четыре файла в новой папке orca-shipping-example. Внешние пакеты npm не нужны.

package.json

{
  "name": "orca-shipping-example",
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "scripts": { "test": "node --test shipping.test.mjs" }
}

shipping.mjs

export function shippingFee(orderTotal) {
  return orderTotal > 50_000 ? 0 : 3000;
}

shipping.test.mjs

import test from 'node:test';
import assert from 'node:assert/strict';
import { shippingFee } from './shipping.mjs';

for (const [total, expected] of [[0, 3000], [49_999, 3000], [50_000, 0], [50_001, 0]]) {
  test(`shippingFee(${total}) = ${expected}`, () => {
    assert.equal(shippingFee(total), expected);
  });
}
for (const [label, total] of [
  ['negative', -1],
  ['fraction', 50_000.5],
  ['string', '50000'],
  ['NaN', Number.NaN],
  ['Infinity', Number.POSITIVE_INFINITY],
  ['unsafe integer', Number.MAX_SAFE_INTEGER + 1],
]) {
  test(`rejects ${label}`, () => {
    assert.throws(() => shippingFee(total), RangeError);
  });
}

index.html

<!doctype html>
<html lang="ko">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Orca 배송비 예제</title>
<h1>배송비 경계값 확인</h1>
<pre id="result"></pre>
<script type="module">
  import { shippingFee } from './shipping.mjs';
  const totals = [49_999, 50_000, 50_001];
  document.querySelector('#result').textContent = totals
    .map(total => `${total}원 → 배송비 ${shippingFee(total)}원`)
    .join('\n');
</script>
</html>

Выполните команды в папке примера с заранее настроенным автором Git.

git init -b main
git add package.json shipping.mjs shipping.test.mjs index.html
git commit -m "Add shipping exercise"
npm test

Исходный код неверно обрабатывает границу 50,000 (пятьдесят тысяч вон) и не отклоняет неверный ввод. Реальный запуск подтвердил 3 успешных и 7 неуспешных тестов из 10. Базовый коммит позволит позже проверить, не изменились ли тесты и настройки.

Просим агента внести изменение в worktree

Откройте репозиторий через Add Repo в Orca и проверьте CLI в подключённом к нему терминале. Если CLI недоступен, установите его через Settings → General → Orca CLI согласно официальному руководству CLI. Команды предполагают исполняемый orca на macOS.

orca skills get orca-cli
orca worktree current --json

Для разделения работы создайте новую worktree от main текущего проекта.

orca worktree create --name shipping-fee-fix \
  --parent-worktree active --base-branch main \
  --setup skip --activate --json

--parent-worktree active записывает рабочую связь Orca, а --base-branch main задаёт исходную точку Git. Это разные настройки. В примере подготовка пропущена, поскольку внешних зависимостей нет. В реальном проекте следуйте его правилам подготовки. Команда не содержит --agent, поэтому задачу агенту она не отправляет.

Откройте терминал нового пространства и проверьте его. Различайте shell, где выполнялась исходная команда, и shell в новой worktree.

git rev-parse --show-toplevel
git branch --show-current
orca worktree current --json

Имя ветки может зависеть от настроек префиксов Orca и других параметров. Убедитесь, что worktree в JSON, путь и ветка Git соответствуют нужному пространству, затем откройте подготовленную вкладку агента и отправьте запрос ниже. Доступные агенты и работа через чат или CLI зависят от настроек среды.

Сначала проверьте текущие рабочую папку и ветку и прочитайте shipping.mjs и shipping.test.mjs.
Исправьте учебную политику доставки по этому контракту:

- При заказе от 50 000 вон доставка стоит 0; ниже — 3 000 вон.
- Допускаются только неотрицательные безопасные целые суммы; все остальные вызывают RangeError.
- Изменяйте только shipping.mjs; тесты, package.json и index.html не меняйте.
- Не устанавливайте зависимости, не обращайтесь во внешнюю сеть, не делайте коммит, push или PR.

Сообщите фактический результат npm test и причину изменения.
Явно укажите проверки, которые не удалось выполнить.

Даже если Orca группирует работу, фактические разрешения инструментов зависят от агента и среды. Одни ограничения в запросе не обеспечивают границу доступа. Руководство не предполагает конкретные названия кнопок разрешений или одинаковое поведение всех провайдеров.

Проверяем тесты и браузер в том же пространстве

Выполните npm test во встроенном терминале. Для автоматизации можно создать тестовый терминал в текущей worktree:

orca terminal create --title "tests" --command "npm test" --json

В автоматизации используйте возвращённый handle терминала для последующих команд. terminal read --screen читает текущий экран, обычный terminal read — накопленный вывод. Принятый ввод и фактический запуск команды или задачи агента — разные события. В созданном для проверки терминале подтверждены все 10 прошедших тестов и изменение только shipping.mjs. Проверка выполнена прямой подстановкой эталонного решения и не является записью работы ИИ-агента.

Для проверки браузера запустите сервер в терминале той же worktree. Предполагается, что порт 4877 свободен.

python3 -m http.server 4877 --bind 127.0.0.1

Проверьте порт из другого терминала.

orca ports --json
orca tab create --url http://127.0.0.1:4877/ --json

Если сервер использует другой порт, возьмите его из результата и используйте соответствующий адрес. Не всё, что показывает orca ports, является HTTP-страницей. Подключитесь по руководству встроенного браузера и проверьте значения на странице:

49999원 → 배송비 3000원
50000원 → 배송비 0원
50001원 → 배송비 0원

Эти три строки проверены в реальном браузере Orca с эталонным решением. После проверки остановите сервер через Ctrl+C в его терминале. Не закрывайте массово посторонние терминалы только из-за завершения задачи; различайте её процессы и вкладки.

Проверяем diff и фиксируем только изменённый файл

Проверьте базовую ссылку и файлы в просмотрщике diff Orca. Комментарии к изменённым строкам позволяют указать агенту конкретное место. Например: «50 000 вон тоже должны давать бесплатную доставку. Сохраните ожидания теста и проверьте оператор сравнения».

Также сравните с базовой веткой main в терминале.

git status --short
git diff main --name-only
git diff main -- shipping.mjs
git diff --exit-code main -- shipping.test.mjs package.json index.html
npm test

В этой задаче должен измениться только shipping.mjs. Если поменялись тесты, настройки или страница, сначала выясните причину. Новые файлы могут отсутствовать в обычном diff, поэтому проверьте и статус Git. Выполните проверки, которые агент не смог запустить; ответ «готово» не заменяет успешный результат.

Ниже приведено проверенное напрямую эталонное решение. После упражнения сравните его с кодом агента. Для запуска поместите код в shipping.mjs в корне проекта.

reference/shipping.mjs

export function shippingFee(orderTotal) {
  if (!Number.isSafeInteger(orderTotal) || orderTotal < 0) {
    throw new RangeError('orderTotal must be a nonnegative safe integer');
  }
  return orderTotal >= 50_000 ? 0 : 3000;
}

С эталонным решением прошли все те же 10 тестов, а исходные тесты, настройки и HTML сохранились. Проверив условия, добавьте в коммит только нужные файлы ветки задачи.

git add shipping.mjs
git commit -m "Fix free-shipping boundary and input validation"

Коммит и слияние в базовую ветку — отдельные шаги. Если другая задача изменила main, перед слиянием снова проверьте diff и тесты. Worktree разделяет рабочие пространства исходников, но не является песочницей безопасности. Разные worktree могут использовать общие ресурсы: базы данных, порты, аккаунты и секреты.

Поначалу проще найти проблему, освоив процесс на одной задаче, чем сразу добавляя нескольких агентов. Расширяйте параллельную работу, когда определены границы файлов или функций и критерии завершения.