Участие в сообществе HagiTask

Для кого: Для авторов и сопровождающих задач сообщества HagiTask.

Предварительные требования:

Клонирован репозиторий hagitask-community-packages, установлены Node.js/npm.
Есть возможность инициализировать вложенный checkout hagitask в этом репозитории.
Есть опыт работы с JSON, Markdown и Git Pull Request.

Эта страница содержит полный порядок действий для участников сообщества. README репозитория Community Packages ограничивается описанием ответственности репозитория и справкой по каталогам и командам.

Ответственность репозиториев и процесс публикации

Community Packages — основной источник определений задач сообщества. Участники редактируют data/<taskId>/; HagiTask поддерживает общую схему пакетов; HagiTask Site считывает конкретный коммит Community Packages, нормализует данные и создаёт:

/index.json: компактный каталог для поиска задач.
/tasks/<taskId>.json: документ с полным набором ресурсов и сведениями о совместимости.
/packages/<taskId>.zip: архив для установки задачи приложением.

Эти JSON- и ZIP-файлы создаются автоматически: не создавайте и не изменяйте их вручную в Community Packages. Архив включает весь каталог data/<taskId>/, поэтому добавленные в него ресурсы также публикуются в составе пакета.

1. Подготовка схемы и репозитория

В репозитории Community Packages выполните:

git submodule update --init --recursive
npm install

Авторитетный источник общей схемы пакетов находится в repos/hagitask/schemas/task-preset-plugin/; Community Packages использует его через вложенный checkout. Не копируйте и не изменяйте схему в Community Packages или HagiTask Site.

2. Создание пакета задачи

Размещайте новую задачу в data/<taskId>/. Значение taskId должно быть стабильным, уникальным, состоять из строчных букв и соответствовать формату kebab-case. Оно всегда должно в точности совпадать с taskPresetId в manifest.json: переименование каталога изменит опубликованные URL подробностей и архива.

Среди опубликованных канонических ID:

Отображаемое название	`taskId`
UI Master	`ui-master`
AgentsMD	`claude-md-update`
Last 30 Days	`last30days`
Ponytail	`ponytail`
Goal	`goal`
OpenSpec Spec Compress	`openspec-spec-compress`

agentsmd и portytail — лишь понятные человеку псевдонимы, а не ID задач в протоколе.

data/<taskId>/
  manifest.json
  frontend/
    panel.json
    commands.json                 # требуется только при наличии каталога команд
  backend/
    task-preset.json
    prompts.json
    templates/<locale>/
      system.md
      user.hbs
  locales/
    en-US.json
    zh-CN.json
  store-page/
    index.en-US.md
    index.zh-CN.md

Обязательны manifest.json, frontend/panel.json, backend/task-preset.json, backend/prompts.json, файлы locale на английском и китайском языках, две страницы магазина и шаблоны промптов для каждого объявленного языка. Добавляйте commands.json, только если пакет действительно содержит каталог команд.

Как файлы влияют на каталог

Исходный файл	Результат публикации
`version` в `manifest.json`	Версия в каталоге и подробностях
`owner` в `manifest.json`	Издатель
`localization` в `manifest.json`	Загружаемый клиентом пакет локализации
`requirements` в `backend/task-preset.json`	Требования задачи и производные сведения о совместимости
`title` / `summary` страницы магазина	Название, краткое и полное описание на разных языках
`catalog` / `tags` английской страницы магазина	Категория и теги

Если на английской странице нет catalog, категория берётся из первого тега, а при отсутствии тегов используется General. Только catalog и tags английской страницы участвуют в формировании категорий каталога.

3. Ссылки на схему и заполнение ресурсов

Сохраняйте соответствующее поле $schema в каждом JSON-файле, используя публичный URL схемы:

https://tasks.hagicode.com/schemas/task-preset-plugin/<schema>.schema.json

Соответствие файлов схемам указано в hagitask/schemas/task-preset-plugin/. В manifest.json необходимо объявить ID задачи, версию, издателя, пакет локализации и пути к ресурсам интерфейса и серверной части. Во всех файлах locale должен быть одинаковый набор ключей.

Во frontmatter файлов store-page/index.en-US.md и index.zh-CN.md должны быть как минимум locale, slug, title и summary. Размещайте catalog и tags на английской странице: сайт публикации использует её для формирования категорий и тегов.

4. Версионирование и проверка

При каждом изменении уже опубликованного содержимого обновляйте version в manifest.json согласно правилам семантического версионирования. Не используйте старый номер версии повторно, иначе метаданные каталога и хеш пакета станут неоднозначными.

Запустите существующую проверку:

npm run validate

Валидатор проверяет канонический ID, схему, объявления ресурсов, полноту локализации, шаблоны промптов и frontmatter страниц магазина. При ошибке исправляйте исходные файлы в data/<taskId>/, а не /index.json, /tasks/<taskId>.json или /packages/<taskId>.zip: эти файлы HagiTask Site создаёт при каждой публикации.

Проверка запускается для Pull Request, меняющих содержимое пакетов, и при отправке изменений в main; ошибка проверки блокирует объединение пакета.

Для дополнительной проверки контракта публикации выполните в checkout hagitask-site:

npm install
npm run typecheck
npm run build
npm run stage:schemas
npm run verify

При сборке сайт повторно нормализует данные и проверяет схему публикации. Успешная сборка означает, что созданные каталог и подробности соответствуют контрактам community-index-v1 и community-task-detail-v1.

5. Отправка Pull Request

Отправляйте Pull Request в hagitask-community-packages, а не в hagitask-site или hagitask. После объединения HagiTask Site обновит ссылку на конкретный коммит Community Packages и заново создаст индекс, подробности и ZIP-архивы.

Репозиторий hagitask отвечает за общую схему и встроенные шаблоны. Если необходимо изменить сам контракт формата пакетов, предложите отдельное изменение схемы в репозитории HagiTask. Community Packages поддерживает только исходные данные в data/, а сайт публикует только созданные из них результаты.

Если проверка не прошла

Исправьте исходные файлы в data/<taskId>/, на которые указывает ошибка:

Ошибка схемы пакета: исправьте соответствующий JSON; не удаляйте $schema и не ослабляйте проверку.
Отсутствует ресурс или locale: обновите manifest, locale, шаблон промпта или страницу магазина, чтобы объявления соответствовали реальным файлам.
Ошибка схемы подробностей каталога или архива: проверьте исходный пакет и входные данные нормализации сайта; не исправляйте созданный JSON вручную.

Если проблема в самом контракте схемы, предложите изменение в репозитории HagiTask, а не копируйте схему в этот репозиторий.

Следующий шаг: Установка HagiTask или Использование HagiTask.