Головна/Завдання/Частина 2/Шлях учасника

Шлях учасника частини 2: від токена до зіграного пакета

Що тут: кроки в тому порядку, в якому їх проходять, і чек-лист готовності до кінця частини 2. Правила світу - 01-rules.md, SDK - 03-sdk.md, провід - 04-protocol.md, наказ - 05-nakaz.md, локальний пакет - 06-local-pack.md.

Підсумок частини 2 - бот у вашому репозиторії, який грає у вас повний пакет із трьох партій проти двох суперників і проходить лінтер наказу. Як бота подають у залікові партії, визначає частина 4.

Що потрібно заздалегідь

• Node.js 24 або новіший і npm, що йде з ним.
• Бот пишеться на TypeScript або JavaScript і працює в Node.js, як шаблон: перевірки коду в оцінюванні працюють лише з цими мовами, і бот іншою мовою не проходить ворота допуску (01-rules.md, 3.1).
• git і ваш репозиторій, зареєстрований у частині 1.
• Токен мережі Зоря.нет із частини 1 (вхід у hub).

1Отримайте доступ до реєстру

Пакети конкурсу лежать у приватному реєстрі npm https://npm.zoria.net/. Доступ видає hub учасникові з підтвердженим репозиторієм (частина 1). Відповідь містить секрет, тому кладіть її поза репозиторієм:

curl -fsS -H "Authorization: Bearer $ZORIA_HUB_TOKEN" \
  https://zoria.net/api/v1/me/registry-token > ~/.zoria-registry.json

$ZORIA_HUB_TOKEN - ваш токен мережі Зоря.нет із частини 1. Токен має бути свіжим: вхід у hub діє добу (частина 1, вимога CL-22). Свіжий токен дає новий вхід - у вашому клієнті з частини 1 або POST /auth/login. Відповідь:

{
  "registry": "https://npm.zoria.net/",
  "scope": "@zoria",
  "username": "<ваш логін>",
  "token": "<токен читання>",
  "auth": "<base64 від логін:токен>",
  "npmrc": "@zoria:registry=https://npm.zoria.net/\n//npm.zoria.net/:_auth=${ZORIA_NPM_AUTH}\n"
}

Відмови: 401 authentication-required - токен hub прострочений або хибний, увійдіть знову; 403 registry-not-eligible - репозиторій ще не підтверджено або акаунт вимкнено; 404 - реєстр ще не відкрито. З прапорцем -f curl на відмові завершується помилкою (The requested URL returned error: 401), файл лишається порожнім, і наступний крок теж падає вголос. Без -f у файл ляже JSON помилки, у ZORIA_NPM_AUTH і в .npmrc - рядок undefined, а npm view відповість E404, ніби .npmrc немає. Якщо допуск знімуть, реєстр закриється для вас протягом 30 секунд; повернуть допуск - hub віддасть той самий токен.

2Налаштуйте npm

Секрет - у змінну середовища, конфіг - у корінь репозиторію:

export ZORIA_NPM_AUTH=$(node -p "require(process.env.HOME + '/.zoria-registry.json').auth")
node -p "require(process.env.HOME + '/.zoria-registry.json').npmrc" > .npmrc

ZORIA_NPM_AUTH тримайте в профілі оболонки або в секретах CI; значення в репозиторій не потрапляє. .npmrc із відповіді секрету не містить, його можна комітити. Перевірка з кореня репозиторію:

npm view @zoria/engine version

Відповідь - номер версії. E401 - змінну ZORIA_NPM_AUTH не виставлено або вона неправильна; E404 - у каталозі немає .npmrc з реєстром для @zoria, і npm шукав пакет у публічному реєстрі. Команди з @zoria/* запускайте лише там, де лежить цей .npmrc.

3Створіть бота

У корені вашого репозиторію:

npx @zoria/kit init bot
cd bot
npm install

init копіює шаблон у каталог bot і нічого не перезаписує. Мова шаблону і виводу команд zaria-kit - українська за замовчуванням, мова конкурсу; --lang en дає англійську. Вибір лягає в package.json полем zaria.lang, і всі команди в каталозі бота говорять цією мовою; разово її змінює прапорець --lang або змінна ZARIA_LANG. У каталозі:

bot/
  package.json    залежності @zoria/* і команди
  .npmrc          реєстр @zoria із посиланням на ZORIA_NPM_AUTH, без секрету
  .gitignore      node_modules, dist, records
  tsconfig.json
  nakaz.yaml      ваша грамота; зразок - копія minutes.yaml
  README.md       команди шаблону
  src/main.ts     провід: присяга, повернення, щоденник віри
  src/strategy.ts ваша стратегія; заглушка - дзеркало архетипу SDK
  src/jitter.ts   пауза повтору першого входу
  src/status.ts   внутрішній службовий порт голови; його вмикає частина 4

bot/.npmrc - той самий конфіг, що у відповіді hub: будь-яка збірка вашого бота ставить пакети з того самого реєстру за тією самою змінною ZORIA_NPM_AUTH.

4Зіграйте перший пакет

npm run play -- --fast

Команда збирає бота і грає пакет: три партії одного жереба, ваш бот по черзі сидить у вершинах A, B і C, два інші місця тримають дзеркальні голови архетипів SDK. Перед кожною партією бот запускається наново, як у заліку. --fast знімає паузу між тактами: пакет триває хвилини, а не пів години. Без --fast партія йде в темпі 500 мс на такт, як у заліку, - так міряють час на такт.

Наприкінці команда друкує частки і рахунок за партіями, а на диску лишається запис:

records/pack-2026-1200-<час>/
  match-1.runlog  match-2.runlog  match-3.runlog   журнали партій
  belief-1.ndjson belief-2.ndjson belief-3.ndjson  щоденники віри бота
  pack.json                                        частки, рахунки, статті рахунку

Рядки ваш слот вів наказ у заглушки - норма: вона мовчить, коли їй нема чого скомандувати, а порожній список команд - теж мовчання; після шести таких тактів слот веде грамота (01-rules.md, 23.2).

Склади, жереби, темп і читання запису - 06-local-pack.md.

5Напишіть свою стратегію

Уся ваша гра живе в src/strategy.ts. Заглушка - дзеркальна голова архетипу SDK: вона грає, але власних правил у неї немає, списуйте з неї контракт, а не тактику. Контракт - WireBot: маніфест, кадр спостереження кожен такт, відповідь кадром команд, вердикти (03-sdk.md). Провід, повернення після обриву, дедуплікація кадрів і перевірка пінів живуть у src/main.ts і connectBot; стратегія про мережу не знає.

Почніть із BlankBot з @zoria/sdk: він уже розбирає кадри, тримає останній кадр і чекає, що ви перевизначите think(). Числа світу беріть з маніфесту (manifest.cfg), а не з тексту правил.

Щоденник віри - що бот вважає правдою про світ такт за тактом - шаблон пише в belief-<партія>.ndjson поруч із записом пакета. Формат - BeliefFrame SDK (03-sdk.md).

6Напишіть наказ

Правте nakaz.yaml і ганяйте лінтер:

npm run lint:nakaz

Три ступені, зразки і словник - 05-nakaz.md. Подивитися грамоту в грі: npm run play -- --fast --bot nakaz - ваше місце веде лише грамота.

7Міряйте на багатьох жеребах

Один пакет - одна долина. Бота міряють пакетами:

npm run play -- --fast --packs 8 --seed 100

Вісім пакетів поспіль на жеребах 100-107; наприкінці - частки за пакетами і сума. Суперників змінює --vs (06-local-pack.md).

8Зсув світу

Зсув світу - нова версія пакетів @zoria/* з новим хешем рушія (01-rules.md, 1.4). Про зсув оголошують заздалегідь. Щоб його отримати:

npm update
npm run play -- --fast
npx zaria-kit version

version друкує хеш рушія і версії пакетів. Записів старого світу новий рушій не відтворює (04-protocol.md, 10.2); це норма, а не поломка.

9Коміт

Комітьте каталог bot/ цілком: package.json, package-lock.json, .npmrc (без токена), tsconfig.json, nakaz.yaml, src/. node_modules, dist і records - у .gitignore. Якщо хочете зберегти пакет-зразок у репозиторії - копіюйте його з records/ у свій каталог явно.

Чек-лист готовності до кінця частини 2

• [ ] npm view @zoria/engine version відповідає версією; ні token, ні auth з відповіді hub не лежать у репозиторії.
• [ ] npm run play -- --fast догравує пакет: три партії, ваш бот присягав у кожній, частки надруковано.
• [ ] pack.json не містить absent на вашому місці: бот присягав у кожній партії.
• [ ] Пакет у темпі 500 мс (npm run play) іде без епізодів наказу на вашому місці: бот відповідає вчасно і подає прийняту команду хоча б раз на 6 тактів.
• [ ] npm run lint:nakaz проходить усі три ступені без помилок.
• [ ] Бота написано на TypeScript або JavaScript, і він запускається командою node (поле zaria.bot у package.json).
• [ ] Бот сам рве провід, якщо хеш рушія вузла не збігається з його (src/main.ts робить це за ZARIA_ENGINE; за замовчуванням - хеш встановленого @zoria/engine).
• [ ] npx zaria-kit version у каталозі бота друкує хеш рушія 264a77c2a5405955f5aba04be240325d65cfe5d25269ae2f7c6a9fc7f4ff0e26.