soft/AGENTS.md

Правила ведения каталога

Эти правила действуют для всего репозитория. Перед изменением метаданных сверяйся с schema/index.schema.json. Не добавляй поля, которых нет в схеме.

Структура

• Все категории и программы находятся внутри корневой папки catalog. catalog/index.yaml описывает корневую категорию.
• Каждая категория и каждая программа внутри catalog находятся в собственной папке и содержат ровно один файл index.yaml.
• Вложенность категорий не ограничена. Дочерние категории и программы определяются по файловой структуре и не перечисляются в индексе категории.
• Имя папки — стабильный идентификатор. Используй строчные латинские буквы, цифры, дефис и подчёркивание.
• В папке программы все загружаемые файлы находятся в files, а скриншоты — в img.
• Не создавай отдельные YAML-файлы или папки метаданных для версий. Все версии описываются в versions единственного index.yaml программы.
• Папки без index.yaml, например schema, files и img, не являются категориями.

YAML категории

Используй только следующие обязательные поля и сохраняй их порядок:

format: 1
type: category
name: Русское название категории
order: -10
description: Описание категории на русском языке.

order — необязательное целое число для сортировки соседних категорий. Меньшее значение выводится раньше, отсутствие поля равнозначно order: 0. При равных значениях категории сортируются по названию. Располагай order после name.

YAML программы

Поля программы располагай в следующем порядке:

1. format: 1 — обязательное поле.
2. type: program — обязательное поле.
3. name — обязательное официальное название программы.
4. summary — обязательное короткое описание программы на русском языке.
5. description — обязательное подробное описание на русском языке в формате Markdown.
6. homepage — необязательный URL домашней страницы.
7. source — необязательный URL исходного кода.
8. author — необязательное имя автора или название организации-разработчика.
9. screenshots — обязательный массив путей; используй [], если изображений нет.
10. versions — обязательный непустой массив версий.
11. additional_files — необязательный массив файлов, не привязанных к версии.

Новые версии добавляй в начало versions, от новых к старым. Каждая версия имеет такой вид:

- version: "1.2.0"
  status: current
  released: "2007-08-14"
  files:
      - path: files/program-1.2.0.zip
        description: Назначение файла на русском языке
        platform: win32
        size: 123456
        sha256: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Поля версии располагай в порядке version, status, released, description, files. Обязательны только version и непустой массив files. Необязательный status принимает current для актуальной версии и archived для устаревшей, сохранённой ради архива. Если статусы используются у программы, указывай их у всех её версий. Поле released добавляй только при наличии достоверной даты. Не переноси changelog в description версии и не добавляй это поле для полноты. Оно допустимо только в особом случае, когда нужно зафиксировать существенное ограничение, которое нельзя выразить номером версии или описанием конкретного файла.

Необязательное поле файла platform принимает одно из значений: win32, win64, dos, java или j2me. Для Windows разрядность входит в название платформы; отдельное поле architecture не используется.

Поля файла располагай в порядке path, description, platform, size, sha256. size содержит размер файла в байтах. Поля size и sha256 заполняются командой pnpm fill-metadata и вручную не редактируются.

Короткое описание

summary выводится рядом с названием программы в списке категории. Напиши естественное краткое описание, по которому понятно, что это за программа, для чего она нужна и с какими телефонами или форматами работает. Опирайся на полное описание и технический смысл программы, а не на единый шаблон. Не используй оценочные усилители вроде «комплексная», «универсальная», «мощная» или «полноценная».

Файлы, которые подходят ко всем версиям или существуют отдельно от релиза, помещай в additional_files, а не внутрь случайной версии:

additional_files:
  - path: files/manual.pdf
    description: Руководство пользователя

Текст и достоверность

• Названия категорий, описания программ, версий и файлов пиши на русском языке. Официальные названия продуктов и технологий не переводи.
• Сохраняй полноту исходного описания. Не сокращай перечень возможностей до общего пересказа и не удаляй значимые технические подробности.
• Содержимое каждого description интерпретируется как Markdown. Для длинного описания со списком используй литеральный блок |- и Markdown-списки; для обычного абзаца, перенесённого на несколько строк, используй >-. Не вставляй HTML-разметку.
• Не выдумывай даты, ссылки, возможности или платформы. Неизвестное необязательное поле лучше не добавлять.
• Сначала пытайся определить версию по странице, имени файла, README и метаданным бинарника. Если номер версии нигде не указан и достоверно получить его невозможно, используй каталоговое значение version: "1.0". Не выводи номер версии из даты сборки.
• Если источник содержит только текущую версию, добавляй только её. Не ищи более ранние архивы в Wayback Machine без отдельного указания пользователя.

Пути и файлы

• Все пути относительны папке программы и используют /.
• Путь загружаемого файла начинается с files/; путь скриншота — с img/.
• Абсолютные пути, .. и обратная косая черта запрещены.
• Каждый путь из YAML должен указывать на существующий файл.
• Один файл нельзя одновременно указывать в versions и additional_files.
• Для каждого добавленного файла указывай размер в байтах и SHA-256 в нижнем регистре.
• Архивы должны проходить через Git LFS согласно .gitattributes. Остальные файлы хранятся в обычном Git.

Стиль YAML

• Кодировка — UTF-8, окончания строк — LF, отступ — два пробела, табуляция запрещена.
• Версии и даты всегда заключай в двойные кавычки.
• Дата имеет формат YYYY-MM-DD, SHA-256 — ровно 64 шестнадцатеричных символа.
• Не используй YAML-теги, anchors, aliases и merge keys.
• Не допускай неизвестных полей и дубликатов в массивах.

Проверка

Перед завершением изменения:

1. Проверь синтаксис всех затронутых index.yaml безопасным YAML-парсером.
2. Проверь их по schema/index.schema.json валидатором JSON Schema Draft 2020-12, если он доступен.
3. Убедись, что все пути существуют, а их размеры и SHA-256 совпадают с метаданными. Для заполнения и обновления используй pnpm fill-metadata [путь], для проверки без изменения файлов — pnpm fill-metadata:check [путь].
4. Для каждого нового архива выполни git check-attr filter -- <путь> и убедись, что значение равно lfs.
5. Выполни git diff --check.