Aleksey Shakhmatov
1df4ea1b72
git.codelab.vc is Gitea/Forgejo: raw path is /raw/branch/<ref>/, the GitLab-style /-/raw/main/ returned 404 so the one-command install was broken. The one-liner now also fetches the script from the stable channel (vetted), not main.
214 lines
13 KiB
Markdown
214 lines
13 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
|
||
```
|
||
|
||
Скрипт проверит Node.js (>= 20), поставит Pi (если нет), установит этот пакет, **спросит
|
||
твой профиль**, поставит нужные скилы и **интерактивно настроит окружение** (`TRACKER_URL`,
|
||
`JIRA_TOKEN`, `GITLAB_TOKEN`, ключ LLM-провайдера). Секреты вводятся скрыто и сохраняются в
|
||
`~/.config/pi-kit/env.sh` (`chmod 600`), который подключается из твоего `~/.zshrc`/`~/.bashrc`.
|
||
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`, `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 | — |
|
||
|
||
Сменить профиль позже: `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 [фокус]` | Ревью текущего диффа по стандартам Go (с фокусом, если задан) |
|
||
| `/rfc <тема>` | Черновик RFC по типовому шаблону |
|
||
| `/kit-config` | Показать действующие корпоративные значения и их источник (local/remote) |
|
||
| `/kit-doctor` | Health-check окружения (node, версия/канал, конфиг, env, токены) |
|
||
| `/kit-help` | Каталог возможностей: команды, скилы, guardrails |
|
||
|
||
### Скиллы
|
||
|
||
Подключаются автоматически, когда задача им соответствует:
|
||
|
||
- **jira-workflow** — работа с трекером (чтение тикетов, комментарии, ссылки на MR).
|
||
- **repo-map** — как ориентироваться в наших репозиториях.
|
||
- **docs-map** — как искать и куда писать документацию.
|
||
- **go-standards** — стандарты Go: структура сервиса, линтеры, тесты, коммиты/MR.
|
||
|
||
### Guardrails (встроенная защита)
|
||
|
||
- **protected-paths** — блокирует запись/редактирование секретов, ключей, `.git/`, прод-конфигов (по пути).
|
||
- **permission-gate** — переспрашивает перед опасными командами (`rm -rf`, force push,
|
||
push в `main`/`master`/`release-*`, тег `v*` (прод-деплой), прод-`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
|
||
│ ├── protected-paths.ts
|
||
│ └── permission-gate.ts
|
||
├── skills/ # SKILL.md-скиллы (jira-workflow/repo-map/docs-map/go-standards)
|
||
├── prompts/ # шаблоны команд (/bugfix, /feature, /review, /rfc)
|
||
└── install.sh # bootstrap для новых сотрудников
|
||
```
|
||
|
||
Формат: [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": "git.codelab.vc",
|
||
"trackerUrl": "TODO",
|
||
"docsUrl": "TODO",
|
||
"repoMap": "TODO: где какой код лежит",
|
||
"rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"],
|
||
"remoteConfigUrl": null
|
||
}
|
||
```
|
||
|
||
- Меняешь значение → правишь **только этот файл**. Скиллы и шаблоны на него ссылаются через
|
||
корпоративный контекст сессии, который инжектит `company-context.ts`.
|
||
- **`remoteConfigUrl`**: если указать URL, при старте сессии `company-context.ts` скачает свежий
|
||
конфиг (таймаут 2.5 с) и при успехе использует его вместо локального. Это позволяет менять
|
||
значения централизованно без `pi update`. При любой ошибке — молча берётся локальный файл.
|
||
- Тексты формулировок (не значения) правятся в `extensions/company-context.md` между
|
||
`{{плейсхолдерами}}` — можно доверить не-программистам.
|
||
- Проверить действующие значения и их источник: `/kit-config`.
|
||
|
||
### Как добавить скилл
|
||
|
||
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`.
|
||
|
||
### Как добавить шаблон-команду
|
||
|
||
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`).
|
||
|
||
### Релизы
|
||
|
||
Раскатка по каналам (`stable`/`beta`) и semver-тегам — процесс в [`RELEASING.md`](RELEASING.md).
|
||
`CHANGELOG.md` обновляется в каждом релизе. Аудит-endpoint — поле `auditEndpoint` в `config/company.json`.
|
||
|
||
### Локальная проверка перед MR
|
||
|
||
```bash
|
||
# из корня репозитория
|
||
pi install ./ # установить пакет из локальной папки
|
||
npm test # прогнать тесты guardrails
|
||
pi # запустить: расширения загрузятся, команды /bugfix и т.д. появятся
|
||
|
||
# опциональный строгий typecheck (нужны peer-типы Pi):
|
||
npm install
|
||
npm run typecheck
|
||
```
|
||
|
||
Минимальный чек-лист MR: расширения загружаются без ошибок; `/kit-config` показывает значения;
|
||
запись в `.env` реально блокируется; изменение `config/company.json` отражается в `/kit-config`
|
||
без других правок.
|