Процессы в пакете¶

Процесс (Process, папка processes/) — дело со стадиями, шагами людей и скиллов, сроками, согласованиями и исходом, записанное данными; исполняет его движок процессов ядра. Страница — короткий вход для автора пакета: что лежит в пакете рядом с процессом, как его проверять и тестировать, как выпускать новые версии при живых делах. Сам язык процессов описан в разделе Процессы.

Куда идти за подробностями¶

Тема	Статья
язык: стадии, шаги `human`, `approve`, `call`, `listen`, `fork`, `try`, данные, старт и корреляция, таймеры, таблицы решений, компенсации	Процессы
выражения CEL: переменные, функции календаря и времени, лимиты	Выражения
формат тестов процессов, заглушки, replay, пробный прогон, план ядра	Сценарии и план ядра
память: проекция дела, `recall`, `remember`, регламенты, уроки	Процессы и база знаний
все поля схемы процесса, календаря и теста	Схема пакета

Процесс в составе пакета¶

Процесс редко живёт один. Рядом с ним в пакете лежит всё, на что он ссылается:

access-requests/
├── package.yaml
├── processes/access-requests.yaml    # kind: Process
├── agents/access-requests-process.yaml  # личность процесса
├── roles/access-requests-owner.yaml  # владелец процесса и адрес шагов
├── task-types/access-review.yaml     # тип задачи шага human
├── skills/access.grant.yaml          # скилл шага call
├── calendars/<ключ>.yaml             # свой календарь, если нужен
├── schemas/<имя>.yaml                # схема данных: data: {$ref: ../schemas/<имя>.yaml}
└── tests/access-requests.test.yaml   # сценарии дела

Поле процесса	На что ссылается	Если ссылка не замкнута
`identity: {agent: <ключ>}`	агент-личность вида `service` или `agent`: от его имени дело заводит задачи, approvals и вызовы скиллов	`unknown_agent`; без `identity` — `process_identity_required`
`owner`	цепочка назначения — кому задачи о самом процессе	без владельца — предупреждение `process_owner_missing`
`human.taskType`	тип задачи шага	`unknown_task_type`
`call.skill`	скилл `имя@версия`	`unknown_skill`; неполный вход — `skill_input_missing`
`calendar`, `cal.*`	календарь	`unknown_calendar`
`assign` шагов	роли	в тесте — `intent_failed unknown_role`, если роль не объявлена и у неё нет держателей в `given.principals`
`workspaceId`	пространство работы процесса	задаётся только переменной установки `${NAME}`

Ссылки проверяет код ядра в package-sdk check: объект должен быть в пакете, его requires или — при проверке с --server — в каталоге стенда.

package-sdk add process <ключ> создаёт процесс-заготовку, а вместе с ним — агента <ключ>-process, роль <ключ>-owner и тест, если их ещё нет. Ключ процесса поэтому не длиннее 55 символов: ключ агента рядом — до 63.

Права личности — ровно то, что исполняют шаги процесса: tasks.read, tasks.write (задачи шагов), approvals.manage (согласования), skills.invoke (скиллы), observations.write (запись в память), events.read (корреляция событий). Права агента не шире прав того, кто применяет пакет.

Сроки (SLA)¶

Срок шага или всего дела — поле due: у шагов human, approve, call, recall, listen и у процесса целиком (spec.due). Это длительность ISO 8601, момент от данных ({at: …}) или рабочие дни и часы по календарю ({workdays: …}, {workhours: …}), с порогом предупреждения warnBefore. Рабочие часы объявляет поле workingHours календаря.

spec:
  calendar: ru
  due: {workdays: 5, warnBefore: {workdays: 1}}   # срок дела целиком
  stages:
    - id: review
      steps:
        - id: review
          human:
            taskType: invoice-review
            due: {workhours: 8, warnBefore: {workhours: 2}}

package-sdk check проверяет сроки без стенда: рабочие единицы без календаря (calendar срока или spec.calendar) — ошибка, workhours по календарю пакета без workingHours — ошибка, календарь срока не из пакета и не из requires — предупреждение.
В сценариях процесса состояние срока проверяет expect.sla: id шага или process → ok, warning, breached, paused; время двигает advance (см. Сроки в тестах).
Если новая версия процесса ставит, сдвигает или снимает сроки открытых дел, plan показывает это разделом deadlines: под процессом строка сроки: экземпляров N и по строке на дело — было → стало, с пометкой «уже просрочен» (см. План и применение).

Формы срока, события process.sla_* и их адресаты — в Сроках и SLA, рабочие часы — в Рабочих часах календаря.

Проверка и тесты¶

package-sdk check без стенда проверяет у процесса схему и ссылки пакета: типы задач, скиллы, календари, агентов identity и owner, шаги, которые называют complete.step и approve.step сценариев.
Язык процесса — типы всех выражений, неизвестные поля данных, входы и выходы шагов, достижимость шагов и стадий, тупики, перекрытия и пробелы таблиц решений — ядро проверяет первой частью ступени сценариев в package-sdk test (и в check --server, если ядро стенда это умеет). Находка печатается с файлом, строкой и подсказкой. Поэтому после правки процесса запускайте test, а не только check.
check не сверяет и то, что видно только при исполнении: observation шагов emit сценария (сценарий со старым видом наблюдения проходит check и падает в test), роли в fields.assignee правил (role:<slug> неизвестной роли — оценка failed: unknown_role в сценарии), skills.invoke агентов.
package-sdk test исполняет сценарии процесса движком ядра в памяти: виртуальное время, задачи и согласования в памяти, скиллы, агенты и память — заглушки из mocks, проверенные по схемам. Сценариям процессов база не нужна. Отчёт показывает покрытие элементов, переходов, строк таблиц решений и обработчиков.
Сценарий процесса завершает задачу шага напрямую. complete: {step} закрывает задачу human мимо гейта её типа: исходы approvalSchema — внешняя запись, completeTask в onSuccess — в сценарии процесса не исполняются. Если задача шага на стенде завершается только одобренным гейтом, покройте его отдельными сценариями subject: taskType (см. Работу).
package-sdk test --server <адрес> отправляет те же сценарии ядру стенда (POST /api/v1/packages:test, право packages.test): каталог стенда виден процессу, ничего не записывается.

Пример сценария — в быстром старте; формат — в Сценариях и плане ядра.

Внешняя запись из процесса¶

Шаг call может вызвать скилл внешней записи (sideEffects: external_write): основание такого вызова даёт сам экземпляр процесса. Опубликованная версия процесса называет версию скилла (call.skill — всегда имя@версия), так же как тип задачи называет свой execution; вызов идёт от личности процесса с её правом skills.invoke. Это основание даёт только движок: прямой вызов скилла той же личностью без решения человека — 403 skill_side_effect_not_authorized (обоснование — CP-ADR-0056, амендмент к §4; CP-ADR-0074, И3).

Основание живёт, пока открыт шаг, а не экземпляр. Ядро проверяет его, когда исполнитель забирает вызов: шаг уже закрыт — по timeout, повтору retry, catch или падению экземпляра — ожидающий вызов отменяется с причиной process_step_closed; экземпляр отменён — process_cancelled; приостановлен — вызов ждёт возобновления (process_suspended). Но вызов, который исполнитель уже забрал, не отзывается. Поэтому try с retry или коротким timeout вокруг external_write — осознанный выбор автора: если первый вызов выдан до таймаута, а шаг повторили, у повтора свой ключ идемпотентности, и во внешней системе может появиться вторая запись.

Рекомендация: ставьте внешнюю запись после решения человека — шагом call сразу за approve или исходом одобрения гейта типа задачи (см. Скиллы пакета), а таймаут шага давайте с запасом на ответ внешней системы. Сценарии процесса основание вызова не проверяют: скилл в них — заглушка, так что об этом правиле тесты не напомнят.

Правка файла процесса¶

Процесс — обычный YAML, его можно править руками. Для мелких правок есть package-sdk edit: он меняет только то, что просили, и сохраняет комментарии, порядок ключей и стиль файла; невалидная правка не записывается.

Операция	Что делает
`add-step --file P --in <стадия или шаг> --step '<yaml>'`	добавить шаг
`add-stage --file P --stage '<yaml>'`	добавить стадию
`add-decision-row --file P --table ID --row '<yaml>'`	добавить строку таблицы решений
`add-form-field --file P --step ID --name F --schema '<yaml>'`	добавить поле формы шага
`rename --file P --from OLD --to NEW`	переименовать элемент: id, ссылки, тесты и карта миграции
`rename --package DIR --kind Process --from OLD --to NEW`	переименовать объект: файл, ключ и `renames` в манифесте
`set --file P --path '<путь>' --value '<yaml>'`	задать значение по пути

--dry-run печатает diff и ничего не пишет, --json — результат для программ.

Версии и живые дела¶

У процесса на стенде есть открытые дела, поэтому выпуск новой версии — не просто замена файла.

flowchart LR
    V1["v1 опубликована<br/>дела идут"] --> E["правка:<br/>spec.version: 2"]
    E --> P["plan: replay по журналу,<br/>судьба открытых дел"]
    P --> H{"человек<br/>читает план"}
    H -- да --> A["apply:<br/>v2 + перенос дел по карте"]
    H -- нет --> E

Версия неизменяема. spec.version — целое; правка процесса — это version: N+1. То же число с другим содержимым — 409 process_version_conflict.
Дело закреплено за версией. Без карты миграции открытые дела дорабатывают по своей версии, новые идут по новой.
Карта миграции переводит открытые дела явно:

spec:
  version: 2
  migrations:
    - from: 1
      to: 2
      policy: migrate            # pin — оставить дела на версии 1
      map: {review-request: review-access}   # старый id → новый

Удалённый элемент с открытыми делами без карты — ошибка плана migration_required: применение отказывает, пока не выбрана политика.
Переименование процесса целиком — renames в манифесте (см. Анатомию): план переносит процесс с историей версий, старый ключ новых дел не заводит.

План ядра для пакета с процессами показывает структурный diff, replay новой версии по журналам недавних дел (сколько решили бы иначе) и судьбу открытых дел по версиям (pin, migrate). Сколько дел брать в replay — plan --replay-limit (0–200, по умолчанию 50). Поле, которое на стенде правили в консоли, пакет не перетирает без явного решения. Подробно — в Плане и применении.

Вывод из оборота¶

Процесс и календарь выводятся из оборота списком retire файла установки:

spec:
  retire:
    Process: [access-intake]

Процесс: новые дела не стартуют, живые дорабатывают. План показывает, сколько живых дел доживёт.
Календарь выводится, только если на него не ссылается активный процесс (calendar_in_use).

Процесс и правила¶

Процесс стартует сам по наблюдению или событию (start.on) и сам собирает к делу последующие события (correlate, listen) — правило для этого не нужно. Когда выбрать процесс, а когда правило, — в Правилах в пакете.

Типичные проблемы¶

Симптом	Причина	Что делать
`process_identity_required`	у процесса нет `identity`	добавить агента-личность и `identity: {agent: …}`
`unknown_agent`, `unknown_task_type`, `unknown_skill`	ссылка не замкнута в пакете и его `requires`	объявить объект или добавить пакет в `requires`
`409 process_version_conflict` при плане	файл изменён без повышения `spec.version`	поднять версию
`migration_required`	у удалённого элемента есть открытые дела	добавить карту `migrations` или политику `pin`
`plan_stale` при применении	после плана изменились стенд, дела или файлы	построить план заново
ключ `on` старта прочитан как `true`	файл прочитан инструментом YAML 1.1	взять ключ в кавычки: `"on":`

См. также¶

Процессы — язык целиком
Сценарии и план ядра
Выражения
Процессы и база знаний
Анатомия пакета — версии, переименования, установка
Правила в пакете