# @mvideo/pi-kit Корпоративный пакет для терминального кодинг-агента [Pi](https://pi.dev): шаблоны задач, guardrails и скиллы со знанием того, где у нас код, трекер и документация. Все корпоративные значения (адреса, правила) живут в одном файле — `config/company.json`. В коде, скиллах и шаблонах адресов нет. --- ## Для сотрудника ### Установка (одной командой) ```bash curl -fsSL https://git.codelab.vc/ai/pi-kit/raw/branch/stable/install.sh | bash ``` Скрипт проверит `git` и Node.js (>= 20) — оба обязательны: git нужен для `pi install git:...`, Node для Pi. Затем поставит Pi (если нет), установит этот пакет, **спросит твой профиль**, поставит нужные скилы и **интерактивно настроит окружение** (`TRACKER_URL`, `CONFLUENCE_URL`, `JIRA_TOKEN`, `CONFLUENCE_TOKEN`, `GITLAB_TOKEN`, ключ LLM-провайдера). Секреты вводятся скрыто и сохраняются в `~/.config/pi-kit/env.sh` (`chmod 600`), который подключается из твоего `~/.zshrc`/`~/.bashrc`. Установщик просит подтвердить дефолтные URL сервисов (из `config/company.json`) и при запросе каждого токена показывает короткую справку, где его получить. Pi провайдер-агностичен — модель/провайдера пакет не навязывает, каждый выбирает свой (Anthropic, OpenAI, OpenRouter, …). Пропустить интерактивную настройку окружения: `PI_KIT_SETUP_ENV=0`. Значения потом можно поменять прямо в `~/.config/pi-kit/env.sh` или перезапустив `./install.sh`. Профиль можно задать заранее (для CI/неинтерактивной установки): ```bash PI_KIT_PROFILE=backend curl -fsSL https://git.codelab.vc/ai/pi-kit/raw/branch/stable/install.sh | bash ``` ### Профили и скилы Общее для всех: команды `/bugfix /feature /review /rfc /kit-config /kit-doctor /kit-help`, guardrails, скиллы `jira-workflow`, `confluence`, `repo-map`, `docs-map`, и публичные `grill-me`, `grill-with-docs`, `code-review`, `diagnosing-bugs`, `simplify` (упрощение кода). Дополнительно по профилю: | Профиль | Языковые стандарты | Доп. публичные скилы | |---|---|---| | `frontend` | typescript | frontend-design | | `backend` | go, rust, python | — | | `qa` | python, typescript | — | | `mobile` | kotlin, swift | — | | `pm` | — | — (бандл `pm-task-spec`) | Профиль `pm` — для продакт-менеджеров: подключает скилл **`pm-task-spec`** (доведение сжатой постановки задачи до структурированной, пригодной для передачи в разработку) без языковых стандартов кода. Сменить профиль позже: `PI_KIT_PROFILE=frontend ./install.sh` (или перезапусти установку). Либо вручную (канал `stable` по умолчанию): ```bash pi install git:git.codelab.vc/ai/pi-kit@stable ``` ### Обновление и каналы ```bash pi update --extensions ``` Установка идёт по **каналу** — движущемуся git-ref: `stable` (проверенные релизы, по умолчанию) или `beta` (обкатка). `pi update --extensions` следует за твоим каналом. Сменить канал: `PI_KIT_CHANNEL=beta ./install.sh` (или закрепиться на теге: `PI_KIT_CHANNEL=v1.2.3`). Процесс релизов — в [`RELEASING.md`](RELEASING.md). ### Команды | Команда | Что делает | |---|---| | `/bugfix <тикет>` | Прочитать тикет → воспроизвести → падающий тест → починить → линтеры/тесты → описание MR | | `/feature <тикет>` | Прочитать тикет → план в `PLAN.md` и остановка на согласование → реализация с тестами | | `/review [фокус]` | Ревью текущего диффа по стандартам кода профиля (с фокусом, если задан) | | `/rfc <тема>` | Черновик RFC по типовому шаблону | | `/kit-config` | Показать действующие корпоративные значения и их источник (local/remote) | | `/kit-doctor` | Health-check окружения (node, версия/канал, конфиг, env, токены; подсветит незаполненные поля) | | `/kit-help` | Каталог возможностей: команды, скилы, guardrails | ### Нативные инструменты (Jira / Confluence / GitLab) Вместо MCP-моста и bash-скриптов работа с корпоративными API реализована как **нативные инструменты pi** (`pi.registerTool`) — агент вызывает их напрямую. URL берутся из `config/company.json`, токены — из `env.sh`. | Область | Инструменты | |---|---| | Jira | `jira_issue_get`, `jira_issue_create`, `jira_issue_update`, `jira_issue_comment`, `jira_issue_transition`, `jira_search`, `jira_link_mr` | | GitLab | `gitlab_mr_create`, `gitlab_pipeline_status`, `gitlab_code_search` | | Confluence | `confluence_search`, `confluence_page_get`, `confluence_page_create` | Разбирают их скиллы `jira-workflow` и `confluence`; логика вынесена в чистые модули `extensions/lib/{jira,gitlab,confluence}.ts` (unit-тестируются). ### Скиллы Подключаются автоматически, когда задача им соответствует: - **jira-workflow** — работа с трекером через нативные инструменты `jira_issue_*` (чтение, создание/обновление, комментарии, переходы, JQL-поиск, привязка MR). - **confluence** — поиск/чтение/создание страниц через `confluence_search`, `confluence_page_*`. - **repo-map** — как ориентироваться в наших репозиториях (если карта не заполнена — скилл скажет об этом и не будет выдумывать). - **docs-map** — как искать и куда писать документацию. - **pm-task-spec** — постановка задачи продакт-менеджером: выявляет слабые места, опрашивает по ключевым доменам и выдаёт готовую структурированную постановку (подключается по профилю `pm`). - **Языковые стандарты** — `-standards` для `go`/`rust`/`python`/`typescript`/`kotlin`/`swift`: структура, линтеры, тесты, коммиты/MR. Подключаются **по профилю** (см. таблицу выше), промпты команд ссылаются на них обобщённо (`-standards`), а не на конкретный язык. ### Guardrails (встроенная защита) - **protected-paths** — блокирует запись/редактирование секретов, ключей, `.git/`, прод-конфигов (по пути). - **permission-gate** — переспрашивает перед опасными командами (`rm -rf`/`rm -r -f`, force push, push в `main`/`master`/`release-*`, тег `v*` (в т.ч. через `refs/tags/` — прод-деплой), `git reset --hard`, `git clean`, прод-`kubectl`, `docker system prune`, `sudo`). - **secret-scanner** — блокирует запись контента, похожего на секрет (по содержимому). - **commit-guard** — требует Conventional Commits и сканирует сообщение коммита на секреты. - **llm-redaction** — вырезает секреты из payload перед отправкой в LLM. - **audit-log** — локальный аудит срабатываний в `~/.config/pi-kit/audit.jsonl` (опц. endpoint). --- ## Для мейнтейнера > ⚠️ **Supply-chain-критичный репозиторий.** Пакет исполняет код на машинах всех > разработчиков. **Любые изменения — только через MR с обязательным ревью.** Прямой push > в защищённые ветки запрещён. ### Устройство пакета ``` pi-kit/ ├── package.json # манифест: секция "pi" + Pi-библиотеки в peerDependencies ("*") ├── config/company.json # ЕДИНЫЙ источник правды: gitHost, trackerUrl, docsUrl, repoMap, rules, remoteConfigUrl ├── extensions/ # TS-расширения (guardrails + нативные инструменты + контекст) │ ├── company-context.ts + company-context.md # контекст сессии + /kit-config │ ├── jira-tools.ts gitlab-tools.ts confluence-tools.ts # нативные инструменты API │ ├── protected-paths.ts │ ├── permission-gate.ts │ ├── secret-scanner.ts commit-guard.ts llm-redaction.ts audit-log.ts │ ├── kit-cli.ts # /kit-doctor, /kit-help │ └── lib/ # общий код (jira, gitlab, confluence, secrets, audit, company-config) ├── skills/ # SKILL.md-скиллы (jira-workflow/confluence/repo-map/docs-map/pm-task-spec + -standards) ├── prompts/ # шаблоны команд (/bugfix, /feature, /review, /rfc) ├── test/ # guardrails.test.ts + api.test.ts (node) + shell/uninstall shell-тесты ├── install.sh # bootstrap для новых сотрудников (дефолты URL из company.json + справки по токенам) └── uninstall.sh # полное удаление кита (с подтверждением) ``` Формат: [packages](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md), [extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md), [skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md), [prompt-templates](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/prompt-templates.md). ### Конфигурация — единственный файл `config/company.json`: ```json { "gitHost": "gitlab.tech.mvideo.ru", "trackerUrl": "https://jira.mvideo.ru", "docsUrl": "https://wiki.mvideo.ru", "repoMap": "TODO: где какой код лежит", "rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"], "remoteConfigUrl": null, "auditEndpoint": null } ``` > Значения выше — текущие действующие; в этом файле хранится **единственный** источник правды > (адрес самого репозитория pi-kit — `git.codelab.vc` — к нему отношения не имеет, он живёт > только в `install.sh`). - Меняешь значение → правишь **только этот файл**. Скиллы и шаблоны на него ссылаются через корпоративный контекст сессии, который инжектит `company-context.ts`. - **`remoteConfigUrl`**: если указать URL, при старте сессии `company-context.ts` скачает свежий конфиг (таймаут 2.5 с) и при успехе использует его вместо локального. Это позволяет менять значения централизованно без `pi update`. При любой ошибке — молча берётся локальный файл. - Тексты формулировок (не значения) правятся в `extensions/company-context.md` между `{{плейсхолдерами}}` — можно доверить не-программистам. - Проверить действующие значения и их источник: `/kit-config`. - Пока какие-то поля не заполнены (`TODO`/пусто) — `/kit-doctor` предупредит, а скиллы `repo-map`/`docs-map` не будут выдумывать и попросят уточнить. Заполнение — шаг к реальной полезности кита: без карты репозиториев скиллы работают «вхолостую». ### Как добавить скилл 1. Создай `skills//SKILL.md` с фронтматтером: ```yaml --- name: my-skill # a-z, 0-9, дефисы; ≤ 64 символов description: ... # ЧЁТКО: что делает и КОГДА применять (по этому триггерится) --- ``` 2. Вспомогательные файлы — в `scripts/`, `references/`, `assets/` внутри папки скилла. 3. **Никаких секретов и URL в тексте** — только ссылки на корпоративный контекст сессии и переменные окружения. ### Профили и гейтинг скилов `install.sh` спрашивает профиль (или берёт `PI_KIT_PROFILE`) и делает две вещи: 1. **Гейтит наши скилы** — переписывает запись пакета в `~/.pi/agent/settings.json` в object-форму `{"source": "...", "skills": ["skills/go-standards", ...]}`, чтобы грузились только скилы профиля. Prompts и расширения не гейтятся (их ключи опущены → грузятся все). 2. **Ставит публичные скилы** через `npx skills add --skill --global` в `~/.agents/skills/` (Pi читает эту папку). Чужой код в наш репо не вендорится. Чтобы поменять маппинг профиль→скилы — правь блок `case "$PROFILE"` и `COMMON_PUBLIC_SKILLS` в `install.sh`. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному профилю в этом `case`. Профили: `frontend`, `backend`, `qa`, `mobile`, `pm`. ### Как добавить шаблон-команду 1. Создай `prompts/.md` — имя файла станет командой `/`. 2. Фронтматтер: `description`, `argument-hint`. 3. Плейсхолдеры — **Pi-native**: `$1`, `$2`, `$ARGUMENTS`/`$@`, `${1:-default}` (⚠️ не `{{...}}` — их Pi в шаблонах команд не подставляет). ### Как добавить/менять расширение - Файл в `extensions/*.ts`, `export default function (pi: ExtensionAPI) {}`. - В шапке каждого расширения — блок: **что делает / как настроить / как отключить**. - Пути к файлам пакета резолвь через `import.meta.url`, не через `cwd`. - Общий код расширений — в `extensions/lib/*.ts` (не `index.ts` → Pi не грузит как расширение). - Pi-библиотеки — только в `peerDependencies` (`"*"`), не бандлить. - Guardrails/секреты покрыты тестами — `npm test` (`test/guardrails.test.ts` + `test/shell.test.sh`). ### Релизы Раскатка по каналам (`stable`/`beta`) и semver-тегам — процесс в [`RELEASING.md`](RELEASING.md). `CHANGELOG.md` обновляется в каждом релизе. Аудит-endpoint — поле `auditEndpoint` в `config/company.json`. ### Локальная проверка перед MR ```bash # из корня репозитория pi install ./ # установить пакет из локальной папки npm test # прогнать тесты guardrails и shell-скриптов pi # запустить: расширения загрузятся, команды /bugfix и т.д. появятся # опциональный строгий typecheck (нужны peer-типы Pi): npm install npm run typecheck ``` > ⚠️ `npm test` требует **Node.js ≥ 22.6** (type-stripping). Для сотрудников в `install.sh` > достаточно Node ≥ 20 — это требование тест-харнеса мейнтейнеров, не установки. Минимальный чек-лист MR: расширения загружаются без ошибок; `/kit-config` показывает значения; запись в `.env` реально блокируется; изменение `config/company.json` отражается в `/kit-config` без других правок.