From b405fb52d0c697636d21d2e7ece8f6b641289eb2 Mon Sep 17 00:00:00 2001 From: Ivan Oparin Date: Thu, 27 Aug 2026 07:47:14 +0400 Subject: [PATCH] docs: describe shipping CLI utilities in a skill per supported language Add docs/authoring-cli-commands.md: the two placements (embedded build roots and external build repositories), the go-v1 admission matrix derived from the validation code, schema-8 module roots with the containment rule and its error identifier, script commands and the script-worker-v1 refusal, one worked example per supported path with live csk output, and an honest paragraph on planned languages. Link it from the README, the CLI reference, and the authoring guide. --- LOGBOOK.md | 19 +++ README.md | 1 + docs/authoring-cli-commands.md | 206 +++++++++++++++++++++++++++++++++ docs/cli.md | 2 + docs/skill-authoring.md | 2 + 5 files changed, 230 insertions(+) create mode 100644 docs/authoring-cli-commands.md diff --git a/LOGBOOK.md b/LOGBOOK.md index 24a55c7..5323dee 100644 --- a/LOGBOOK.md +++ b/LOGBOOK.md @@ -2853,3 +2853,22 @@ prevent, proven red rather than argued. Takeaway for the next pin move: when reporting corpus-pin evidence, cite a run whose skip count shows the corpus consumers were reached. A full-suite pass with the roots unset proves nothing about them. + +## 2026-08-27 TASK-260827-1r6mer: authoring CLI utilities documentation and compiler admission rules + +Created `docs/authoring-cli-commands.md` in Russian following `docs/prose-style.md` to describe how skill authors deliver CLI utilities. Documented: +1. Placement choices: built-in `build_roots` vs external `build_repositories`. +2. Compiler admission matrix from `src/csk`: `go-v1` (built-in) and `go-repository-v1` (external), fixed build policy (`FIXED_GO_BUILD_POLICY`), rejections (`cgo_required`, `go_pgo_forbidden`, `go_test_input_forbidden`, `go_assembly_forbidden`, `vendor_dependency_missing`, `vendor_metadata_inconsistent`), macOS/Windows platform restriction, and schema 8 `modules`. +3. Script commands: shebang resolution, shim creation in `.agents/bin/`, schema 8 `execution_policy: "script-worker-v1"` rejection with `script_execution_policy_unsupported`. +4. Three minimal working examples (`go-v1`, `go-repository-v1`, `script`) verified with `.venv/bin/csk skill check`. +5. Planned languages (Kotlin, Swift, Rust) error identification: `error: skill.spec_invalid agent-skill.json: Command '' field 'driver' must be 'go-v1' or 'go-repository-v1'`. + +## 2026-08-27 TASK-260827-1r6mer: rework of authoring CLI utilities documentation per review verdict RUN-260827-11a12f + +Reworked `docs/authoring-cli-commands.md` and associated task outputs to address review verdict RUN-260827-11a12f: +1. Synchronized files between main repo `/Users/iv/Developer/Wildberries/cocoaskills` and story worktree `.temp/STORY-260824-3rzqxr/worktree`. +2. Replaced fabricated Linux refusal string with the two actual code strings: `rc5-native-control-inventory-v1 covers exactly macOS and Windows` (`src/csk/builds/go_v1.py:445`) for `go-v1`, and `go-repository-v1 is supported only on macOS and Windows; Linux qualification is deferred` (`src/csk/installer.py:1475`) for `go-repository-v1`. +3. Inverted the schema 8 `modules` rule: stated that declared module directories MUST be disjoint from `build_roots` and `runtime_roots` (raising `build_module_root_containment_invalid`), and documented nearest `go.mod` placement rule (`_validate_nearest_go_module`). +4. Separated `go-v1` as the single compiled driver for internal build roots (`SUPPORTED_BUILD_DRIVERS = {"go-v1"}`) from `go-repository-v1` for external repositories managed by installer layer. +5. Fixed CGO policy terminology (`cgo: False`, refusal `cgo_required`), named `go_generator_forbidden`, explained `allows_go_generate = vendored`, and cleaned up Russian prose style (removed literal translation "первого партийного кода"). +6. Executed all 8 example skills against `.venv/bin/csk skill check` and recorded literal command outputs, exit codes, stdout, and stderr in outcome resource `TASK-260827-1r6mer_results.md`. diff --git a/README.md b/README.md index 90049b6..64c1127 100644 --- a/README.md +++ b/README.md @@ -315,6 +315,7 @@ csk shell-init # Генерирует или устанав - [`ARCHITECTURE.md`](ARCHITECTURE.md): описание внутренней архитектуры, схемы работы конвейера установки, формата хранилищ и модели безопасности. - [`SECURITY.md`](SECURITY.md): политика безопасности, границы изоляции и рекомендации по настройке. - [`docs/skill-authoring.md`](docs/skill-authoring.md): руководство по структурированию пакетов скиллов, объявлению команд и настройке манифеста `agent-skill.json`. +- [`docs/authoring-cli-commands.md`](docs/authoring-cli-commands.md): руководство по поставке CLI-утилит в скиллах (Go, скрипт-команды, ограничения компилятора и планируемые языки). - [`docs/troubleshooting.md`](docs/troubleshooting.md): диагностика ошибок установки, миграция со старых версий и решение частых проблем. - [`CHANGELOG.md`](CHANGELOG.md): история релизов и список изменений по версиям. diff --git a/docs/authoring-cli-commands.md b/docs/authoring-cli-commands.md new file mode 100644 index 0000000..94c7728 --- /dev/null +++ b/docs/authoring-cli-commands.md @@ -0,0 +1,206 @@ +# Поставка CLI-утилит в скиллах CocoaSkills + +Авторы скиллов поставляют CLI-утилиты двух видов: компилируемые команды на Go и скрипт-команды. Этот документ описывает два способа размещения утилит, матрицу допуска компилятора `csk`, правила оформления скрипт-команд, минимальные примеры конфигураций и статус планируемых языков. + +## 1. Размещение утилит + +Скилл поставляет утилиту через один из двух путей размещения. + +Встроенные исходные тексты живут в каталогах `build_roots` внутри репозитория скилла. Этот путь подходит для утилит собственного кода скилла, создаваемых и сопровождаемых вместе с инструкциями скилла. Установщик копирует каталоги `build_roots` во временное окружение сборки и удаляет их из финального контекста агента. + +Внешний билд-репозиторий объявляется в секции `build_repositories` манифеста `agent-skill.json`. Скилл ссылается на отдельный Git-репозиторий с фиксированным `locked_commit` или тегом `tag`. Этот путь подходит для крупных или общих утилит, разрабатываемых независимо от скилла. + +Таблица сравнения путей размещения: + +| Критерий | Встроенные `build_roots` | Внешний `build_repositories` | +| :--- | :--- | :--- | +| Исходный код | Внутри репозитория скилла | В отдельном Git-репозитории | +| Драйвер команды | `go-v1` | `go-repository-v1` | +| Клонирование при сборке | Не требуется | Клонируется по SSH или HTTPS | +| Привязка версии | Вместе с коммитом скилла | Явное поле `locked_commit` | +| Изоляция контекста промпта | `build_roots` исключаются из контекста | Код репозитория не попадает в контекст | + +## 2. Матрица допуска и ограничения компилятора + +Менеджер `csk` собирает бинарные файлы через два раздельных механизма в зависимости от источника утилиты. + +### Разделение компилируемых путей + +Единственным компилируемым драйвером для изолированного воркера сборки является `go-v1` (`SUPPORTED_BUILD_DRIVERS = {"go-v1"}`). Воркер собирает исполняемые файлы из каталогов `build_roots` внутри пакета скилла. + +Внешние билд-репозитории обслуживаются драйвером `go-repository-v1`. Этот драйвер обрабатывается напрямую слоем установщика (`src/csk/installer.py`), который клонирует репозиторий и передает сборку изолированному воркеру. + +### Ограничения сборки и проверки исходного кода + +Драйвер `go-v1` применяет фиксированную политику сборки `FIXED_GO_BUILD_POLICY`: + +- Зависимости поставляются строго через каталог `vendor/` и файл `vendor/modules.txt`. Сборка исполняется с флагом `-mod=vendor`. При отсутствии каталога сборка завершается отказом `vendor_dependency_missing`. +- Сетевой доступ при сборке полностью запрещен (`network: "none"`). +- Среда Go берется из системного `GOROOT`. Версия компилятора проходит валидацию идентичности тулчейна. +- Взаимодействие с C отключено (`cgo: False`, отказ `cgo_required`). +- Профилирование PGO запрещено (файл `default.pgo` вызывает отказ `go_pgo_forbidden`). +- Кодогенераторы не запускаются в собственном коде скилла (`allows_go_generate = vendored`). Директива `//go:generate` в коде скилла вызывает отказ `go_generator_forbidden`. В зависимости в каталоге `vendor/` директива инертна. +- Тестовые файлы `*_test.go` исключаются из контекста сборки (вызов `go list` не должен выбирать тестовые пакеты, отказ `go_test_input_forbidden`). +- Ассемблерный код `.s` в собственном коде скилла запрещен (отказ `go_assembly_forbidden`). +- Внешняя линковка запрещена (`link_mode: "internal"`). + +### Поддержка платформ и отказы Linux + +Сборка компилируемых команд поддерживается только на macOS (`darwin`) и Windows (`win32`). + +На операционной системе Linux менеджер `csk` отклоняет установку компилируемого скилла до старта процессов сборки. Вызовы происходят в разных точках кода и возвращают разные сообщения: + +- Для встроенных исходников `go-v1` функция `inventory_platform()` в `src/csk/builds/go_v1.py` вызывает исключение `GoV1Error` с кодом `CODE_CONTROL_UNAVAILABLE` и текстом: `rc5-native-control-inventory-v1 covers exactly macOS and Windows`. +- Для внешних репозиториев `go-repository-v1` слой установщика в `src/csk/installer.py` вызывает исключение `InstallError` с текстом: `go-repository-v1 is supported only on macOS and Windows; Linux qualification is deferred`. + +### Модульные корни схемы 8 + +Манифест схемы 8 позволяет объявить массив `modules` для команды с драйвером `go-v1`. + +Объявленные пути модулей обязаны быть изолированными. Поле `modules` не может пересекаться или содержать пути из `build_roots` и `runtime_roots`. Функция `_reject_overlaps` в `src/csk/builds/module_roots.py` проверяет пересечение в обе стороны и отклоняет пересекающиеся пути с кодом `build_module_root_containment_invalid`. + +Корень сборки `build_root` обязан напрямую содержать файл `go.mod`. Проверка `_validate_nearest_go_module` в `src/csk/skillspec.py` запрещает вложенные модули между `build_root` и `source_dir` и возвращает отказ вида `commands..source_dir intervening module /go.mod is below build root `. + +## 3. Скрипт-команды и политики исполнения + +Скрипт-команда выполняет готовый сценарий без этапа компиляции Go. + +### Допустимые интерпретаторы и резолв шимов + +Обычные скрипт-команды используют системные интерпретаторы host-машины через строчку шебанга (`#!/usr/bin/env python3`, `#!/bin/sh`, `#!/usr/bin/env bash`). + +При установке `csk` копирует файлы скриптов из `runtime_roots` в каталог `~/.cocoaskills/runtime///`. + +Менеджер создаёт исполняемый шим в `.agents/bin/` (или `~/.cocoaskills/bin/` для глобальной установки): + +- На POSIX-системах (macOS, Linux) создается исполняемый скрипт-лончер `#!/bin/sh` либо символическая ссылка. +- На Windows создается `.cmd` скрипт-лончер (`@echo off`, `set "PATH=..."`, `call ...`). + +### Схема 8: execution_policy и rejection + +Манифест схемы 8 позволяет объявить параметры `execution_policy` и `interpreter` для скрипт-команды. + +Допустимым значением `execution_policy` является `script-worker-v1`. Допустимыми значениями `interpreter` являются `python3-v1` и `node-v1`. Указание одного из полей требует указания второго. + +В текущей версии `csk` изолированный воркер скриптов не реализован (`SCRIPT_EXECUTION_POLICIES_IMPLEMENTED` равен пустому множеству). При попытке установить скилл с `execution_policy: "script-worker-v1"` менеджер отвергает установку с ошибкой `script_execution_policy_unsupported`: + +```text +error: skill.script_execution_policy_unsupported agent-skill.json: script_execution_policy_unsupported: this manager does not implement the selected script execution policy, so it refuses to install (script-worker-v1). The command is not downgraded to a declared-only shim. +``` + +Сообщение подтверждает отказ от автоматического понижения утилиты до обычного шима. + +## 4. Минимальные примеры конфигураций + +Приведенные ниже примеры демонстрируют минимальную конфигурацию манифеста для каждого поддерживаемого пути поставки утилит. + +### 4.1. Встроенная go-v1 утилита + +Манифест `agent-skill.json` объявляет корень сборки `src` и команду `my-tool`: + +```json +{ + "schema_version": 8, + "capabilities": {}, + "build_roots": ["src"], + "commands": { + "my-tool": { + "type": "build", + "driver": "go-v1", + "source_dir": "src/cmd/my-tool" + } + } +} +``` + +Файлы утилиты располагаются в репозитории скилла следующим образом: + +```text +skill-go-example/ + SKILL.md + agent-skill.json + src/ + go.mod + cmd/ + my-tool/ + main.go + vendor/ + modules.txt +``` + +Команда `csk install` компилирует бинарный файл `my-tool` и публикует шим `.agents/bin/my-tool`. + +### 4.2. Внешняя go-repository-v1 утилита + +Манифест `agent-skill.json` объявляет внешний Git-репозиторий в секции `build_repositories`: + +```json +{ + "schema_version": 8, + "capabilities": {}, + "build_repositories": { + "infra-tools": { + "git": "git@github.com:org/infra-tools.git", + "tag": "v1.2.0", + "locked_commit": { + "object_format": "sha1", + "hex": "a1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e" + } + } + }, + "commands": { + "infra-cli": { + "type": "build", + "driver": "go-repository-v1", + "repository": "infra-tools", + "target": "infra-cli" + } + } +} +``` + +Адрес `git` при работе по HTTPS обязателен с суффиксом `.git`. Настройка аутентификации SSH и HTTPS описана в документе [Внешние билд-репозитории](external-build-repositories.md). + +### 4.3. Скрипт-команда + +Манифест `agent-skill.json` объявляет корень исполняемых файлов `scripts` и скрипт-команду `my-script`: + +```json +{ + "schema_version": 8, + "capabilities": {}, + "runtime_roots": ["scripts"], + "commands": { + "my-script": { + "type": "script", + "unix_path": "scripts/my-script.py", + "win_path": "scripts/my-script.cmd" + } + } +} +``` + +Скрипты располагаются в репозитории скилла следующим образом: + +```text +skill-script-example/ + SKILL.md + agent-skill.json + scripts/ + my-script.py + my-script.cmd +``` + +Установщик `csk` копирует скрипты в окружение runtime и создает шим `.agents/bin/my-script`. + +## 5. Планируемые языки + +Языки Kotlin (`kotlin`), Swift (`swift-v1`) и Rust (`rust`) не реализованы в компиляторе `csk`. + +Указание недопустимого значения в поле `driver` вызывает отказ валидации при запуске `csk skill check`: + +```text +error: skill.spec_invalid agent-skill.json: Command '' field 'driver' must be 'go-v1' or 'go-repository-v1' +``` + +Диагностика `skill.spec_invalid` подтверждает разрешение только драйверов `go-v1` и `go-repository-v1`. diff --git a/docs/cli.md b/docs/cli.md index 2a2e4d1..c81b26d 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -334,6 +334,8 @@ csk skill check /path/to/skill Команда проверяет валидность файлов скилла и выводит список ошибок или предупреждений. +Подробные требования к манифестам, компилируемым утилитам и скрипт-командам описаны в документах [Поставка CLI-утилит](authoring-cli-commands.md) и [Руководство по созданию скиллов](skill-authoring.md). + ## Группа: Global и Hybrid Команды группы управляют скиллами пользовательского уровня и правилами гибридного связывания. diff --git a/docs/skill-authoring.md b/docs/skill-authoring.md index b5dbfbd..d395637 100644 --- a/docs/skill-authoring.md +++ b/docs/skill-authoring.md @@ -440,6 +440,8 @@ Script-команда может выбрать закрытую политик ## 5. Корни сборки и скомпилированные команды +Подробное руководство по поставке компилируемых и скриптовых CLI-утилит смотрите в документе [Поставка CLI-утилит](authoring-cli-commands.md). + Скиллы схемы 7 могут также выбирать зафиксированный внешний источник Git с закрытой формой команд `go-repository-v1`. Пакет объявляет идентичность и точный commit; пакет не может передавать вспомогательные скрипты Git, учетные данные, хуки, аргументы сборки, переменные окружения, пути вывода или настройки подписи. Внешний репозиторий содержит отдельный дескриптор `skill-build.json`. Смотрите [Внешние репозитории сборки](external-build-repositories.md) для полных примеров и правил жизненного цикла. Этот режим с поддержкой исходного кода работает на macOS и Windows; Linux не входит в квалифицированный набор платформ. Поле `build_roots` задает каталоги только с исходным кодом. csk проверяет и хэширует их, но не копирует в установленный контекст промпта или хранилище runtime скриптов.