# Пакеты автора: цикл, секции, коды > Как собрать пакет агента китом, загрузить его в свою песочницу и проверить в Бот-тесте; из чего он состоит и какими кодами дверь называет ошибку. Пакет автора — агент, его навыки и знания, шаги-код и сценарии одним архивом. Коннектор описывает связь компании с её системой; пакет описывает, как отвечает клиентам сам агент. Пакет ставится только в песочницу автора: у компании загрузки пакета нет. ## Цикл Команды — те же пакета проверки, что в [Быстром старте](https://www.zengi.ai/developers/quickstart): скачать его и сверить сумму нужно до первого запуска. Аргументы команд — `node dala-connector-kit.mjs --help`. - **`init`** — кладёт шаблон пакета: агент, навык, знание, шаг с примером, кейс передачи человеку. Шаблон проходит `check` как есть: правьте его, а не пишите пакет с нуля. - **`check`** — правила двери локально, без базы; примеры шага-кода выполняются локально дважды. Имя пакета, версии, роли и библиотеки `check` не судит: их судит дверь при загрузке. - **`pack`** — собирает zip-архив пакета, не больше 2 МБ. - **Загрузка.** В кабинете песочницы (код компании `sbx-…`), в разделе «Пакеты», владелец нажимает «Загрузить пакет». Дверь проверяет архив теми же правилами, что `check`, плюс правилами имени и версий, ставит пакет и включает его в этой песочнице одним действием. - **Бот-тест.** Откройте «Бот-тест» песочницы и говорите с агентом пакета: его тон, его навыки и знания, расчёт его шага-кода. `catalog --packages` печатает глаголы каталога платформы и чтения шага, на которые пакет может ссылаться. Новая версия своего пакета — загрузка архива ещё раз: прежняя версия снимается, новая ставится с новым согласием. Версия в `package.json` — больше всех уже загруженных. ## Секции Пакет в файлах — `format: "0.2"` (с папками `skills/` и `knowledge/`). Раскладка: ```text my-package/ package.json голова и оглавление секций agents/.json агент пакета agents/.md инструкции агента skills/manifest.json библиотека навыков пакета skills/<навык>/SKILL.md knowledge/.md знание: заголовок навыка, свободный текст без сумм с валютой code/.json шаг-код: схемы, чтения, примеры code/.js текст шага scenarios/.json ``` - `package.json` — голова: `format`, `id`, `version`, `capabilities` — список `{ref, module_id, start_mode}`, `steps`, `needs` и оглавление секций: `agents`, `code`, `scenarios`. - `agents/.json` и `agents/.md` — агент пакета и его инструкции. Агент с ролью «отвечает клиентам» — ровно один: «Включить» ставит его на клиентский канал песочницы. Вместе с ним `agent_extension` не допускается. - `skills/manifest.json` и `skills/<навык>/SKILL.md` — собственная библиотека навыков пакета. Её публикует и закрепляет сама загрузка: отдельно публиковать нечего. - `knowledge/.md` — знания агента в той же библиотеке: заголовок навыка (`name`, `description`, `metadata` с разделом «Знания» и `required: нет`) и свободный текст, кроме сумм с валютой: цену называет каталог или шаг расчёта, а телефон и адрес знанию можно. Знание едет в ход после навыков и первым уходит, если бюджета хода не хватает; поэтому у него только `required: нет`, иначе — `knowledge_required`. Раздел «Знания» — только у `knowledge/`: навык из `skills/` с ним и знание с другим разделом — `knowledge_section_reserved`. Каждое знание названо в оглавлении `skills/manifest.json`. - `code/.json` и `code/.js` — шаг-код: схемы, чтения, примеры и необязательный `start_mode`. Исполняется только на отдельном исполнителе авторов, в вашей песочнице; не ответил исполнитель — примеры шага не проверены, версия не публикуется. - `scenarios/.json` — сценарии агента, ключ файла — адрес агента. Нужен хотя бы один с `checks.outcome.status: "escalated"` — передача человеку: без него дверь ответит `evals_missing`. **Режимы.** `start_mode` способности и шага — не выше потолка: меньшего из потолка каталога и потолка установки (запись и выход наружу у автора — не выше `approval`). После «Включить» режимы из манифеста записывает `set-mode`, и только в песочнице; режим выше потолка — `start_mode_above_ceiling`. **Чего пакету автора нельзя.** Документы процесса (граф v1) публикует только платформа: дверь ответит `process_graph_publisher`. ## Коды Кит и дверь называют ошибку одним кодом. Слова ниже печатает код платформы, а не рука: страница с дверью не разойдётся. **Правила проверки пакета** - `schema_invalid` — манифест не той формы - `capability_unknown` — глагол не из каталога платформы — запросить глагол: [/developers/packages#request-verb](https://www.zengi.ai/developers/packages#request-verb) - `handover_missing` — процесс с клиентом без исхода «к человеку» (escalated) - `evals_missing` — процесс без сценария - `role_unknown` — роль своего агента пакета ни из реестра ролей, ни из roles манифеста - `role_conflict` — роль уже в реестре с другой подписью, описанием или признаком: реестр только дописывается, ключ не переименовывается - `agent_unknown` — ведущий процесса или запуска — не свой агент пакета - `skill_unknown` — набор навыков или навык не опубликован в каталоге платформы - `module_unknown` — модуль не из каталога платформы или не объявлен нуждой пакета - `ref_immutable` — адрес процесса уже в реестре с другим документом: адрес неизменяем — правленый документ публикуется новым адресом - `ref_stale` — новый адрес процесса не старше всех адресов его ключа в реестре - `process_ref_taken` — ключ процесса занят другим пакетом реестра - `start_mode_above_ceiling` — режим способности или шага выше потолка: каталог ∩ потолок установки (запись автора — не выше approval) - `process_graph_publisher` — документ процесса (граф v1) публикует только платформа: процесс автора — делом (PW-S1) - `client_facing_conflict` — агент «отвечает клиентам» у пакета автора — один и без agent_extension: «Включить» ставит его на канал песочницы - `code_module` — код шага — один скрипт без import, require, import(), перехвата исключений и async - `code_examples` — пример шага не сошёлся с ожидаемым итогом (или примеров нет) - `code_impure` — два прогона примера дали разный итог: шаг не чист - `code_ref` — адрес шага — не адрес своего пакета `<пакет>.<существительное>.<глагол>@<ревизия>` - `code_publisher` — код автора исполняется только в его песочнице, на отдельном исполнителе: у компании и из /admin секция code автора не публикуется - `code_ref_immutable` — адрес шага уже в реестре с другим кодом: один адрес — один код, правленый шаг публикуется новой ревизией **Файлы и архив** - `archive_invalid` — архив не наш или повреждён: zip без сжатия, только файлы пакета, не больше 2 МБ - `format_unsupported` — формат файлов пакета не поддерживается (нужен format 0.1 или 0.2; skills/ — только у 0.2) - `secret_in_file` — в файле — значение формы ключа: секреты в пакет не кладут - `tenant_authored` — часть помечена «правлено компанией»: в чужую компанию она не ставится - `knowledge_section_reserved` — раздел «Знания» — только у файлов knowledge/.md: навык из skills/ его не берёт, у знания другого раздела нет - `knowledge_required` — знание — только «required: нет»: «всегда» вытеснило бы навыки из бюджета хода — знание едет после них - `version_stale` — версия не старше опубликованных: новая версия пакета — старше всех - `version_conflict` — эта версия уже опубликована с другим содержимым: версия неизменяема **Отказы загрузки** - `not_owner` — Загружает пакет только владелец песочницы. - `package_upload_sandbox_only` — Пакет автора загружается только в песочницу (sbx-…): у компании загрузки нет. - `package_id_taken` — Имя пакета занято другой песочницей или платформой: выберите другое имя в package.json. - `package_tenant_inactive` — Песочница не активна — загружать в неё нельзя. - `package_quota_names` — У песочницы исчерпан предел имён пакетов: новое имя не заводится — загружайте новые версии своих пакетов. - `package_quota_versions` — У имени пакета исчерпан предел версий: новая версия не публикуется. - `package_upload_rate` — Слишком много загрузок за час — повторите позже. - `actor_missing` — Нет учётки сессии: загрузка без подписи того, кто её нажал, не идёт. - `uninstall_failed` — Прежнюю версию пакета не удалось снять — новая не поставлена. Снимите её на вкладке и повторите. - `author_failed` — Не удалось записать установку пакета — повторите позже. - `window_missing` — Окна автора в базе нет (Docs/sql/op-s1e-author-sandbox.sql) — это окно владельца платформы. - `check_failed` — проверка архива не прошла — не записано ничего - `archive_too_large` — архив больше 2097152 байт — пакет текст, а не медиа; тело не дочитано - `executor_unavailable` — Исполнителя шагов-кода нет или он не ответил — примеры шага не проверены, версия не опубликована. - `package_installed` — У компании уже стоит другая версия этого пакета — обновление версии отдельным актом. - `package_name_taken` — У компании уже есть агент, фоновый запуск или процесс с этим именем не от этой установки — пакет не поставлен. - `package_library_foreign` — Библиотека чужого пакета: её закрепляет только песочница — владелец имени пакета. - `package_awaiting_connection` — Пакету нужно подключение, которого у компании ещё нет или оно не готово. ## Запросить глагол Дверь ответила `capability_unknown`: глагола нет в каталоге платформы. Пакет ссылается на действие, которого платформа пока не умеет. Возьмите подходящий глагол из `catalog --packages` или запросите новый — его добавляет платформа, а не пакет; пока его нет, шаг, которому он нужен, в пакет не кладите. Что отправить платформе: - **Глагол словами** — что он делает, одной строкой. - **Вид** — `query` (читает и отвечает), `command` (меняет данные платформы) или `egress` (доставляет наружу). - **Зачем он агенту** — какой вопрос клиента или шаг сценария без него не закрыть.