263 lines
18 KiB
Markdown
263 lines
18 KiB
Markdown
# @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`. Дополнительно по профилю:
|
||
|
||
| Профиль | Языковые стандарты | Доп. публичные скилы |
|
||
|---|---|---|
|
||
| `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`).
|
||
- **Языковые стандарты** — `<lang>-standards` для `go`/`rust`/`python`/`typescript`/`kotlin`/`swift`:
|
||
структура, линтеры, тесты, коммиты/MR. Подключаются **по профилю** (см. таблицу выше),
|
||
промпты команд ссылаются на них обобщённо (`<lang>-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 + <lang>-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/<name>/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 <repo> --skill <name> --global` в
|
||
`~/.agents/skills/` (Pi читает эту папку). Чужой код в наш репо не вендорится.
|
||
|
||
Чтобы поменять маппинг профиль→скилы — правь блок `case "$PROFILE"` и `COMMON_PUBLIC_SKILLS`
|
||
в `install.sh`. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному
|
||
профилю в этом `case`. Профили: `frontend`, `backend`, `qa`, `mobile`, `pm`.
|
||
|
||
### Как добавить шаблон-команду
|
||
|
||
1. Создай `prompts/<name>.md` — имя файла станет командой `/<name>`.
|
||
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`
|
||
без других правок.
|