docs: add README for employees and maintainers (in Russian)
- employee: one-command install, update, command table, skills, guardrails - maintainer: package layout, single-file config + remoteConfigUrl, how to add skill/prompt/extension, MR-only supply-chain rule, local verification
This commit is contained in:
154
README.md
Normal file
154
README.md
Normal file
@@ -0,0 +1,154 @@
|
|||||||
|
# @mvideo/pi-kit
|
||||||
|
|
||||||
|
Корпоративный пакет для терминального кодинг-агента [Pi](https://pi.dev): шаблоны задач,
|
||||||
|
guardrails и скиллы со знанием того, где у нас код, трекер и документация.
|
||||||
|
|
||||||
|
Все корпоративные значения (адреса, правила) живут в одном файле — `config/company.json`.
|
||||||
|
В коде, скиллах и шаблонах адресов нет.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Для сотрудника
|
||||||
|
|
||||||
|
### Установка (одной командой)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://git.codelab.vc/ai/pi-kit/-/raw/main/install.sh | bash
|
||||||
|
```
|
||||||
|
|
||||||
|
Скрипт проверит Node.js (>= 20), поставит Pi (если нет), установит этот пакет и подскажет,
|
||||||
|
какие переменные окружения нужны (`ANTHROPIC_API_KEY` / ключ прокси, `TRACKER_URL`, `JIRA_TOKEN`).
|
||||||
|
|
||||||
|
Либо вручную:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pi install git:git.codelab.vc/ai/pi-kit
|
||||||
|
```
|
||||||
|
|
||||||
|
### Обновление
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pi update --extensions
|
||||||
|
```
|
||||||
|
|
||||||
|
Пакет установлен без версионного ref, поэтому обновление всегда тянет актуальный `main`.
|
||||||
|
|
||||||
|
### Команды
|
||||||
|
|
||||||
|
| Команда | Что делает |
|
||||||
|
|---|---|
|
||||||
|
| `/bugfix <тикет>` | Прочитать тикет → воспроизвести → падающий тест → починить → линтеры/тесты → описание MR |
|
||||||
|
| `/feature <тикет>` | Прочитать тикет → план в `PLAN.md` и остановка на согласование → реализация с тестами |
|
||||||
|
| `/review [фокус]` | Ревью текущего диффа по стандартам Go (с фокусом, если задан) |
|
||||||
|
| `/rfc <тема>` | Черновик RFC по типовому шаблону |
|
||||||
|
| `/kit-config` | Показать действующие корпоративные значения и их источник (local/remote) |
|
||||||
|
|
||||||
|
### Скиллы
|
||||||
|
|
||||||
|
Подключаются автоматически, когда задача им соответствует:
|
||||||
|
|
||||||
|
- **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/*`, прод-`kubectl`, `docker system prune`, `sudo`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Для мейнтейнера
|
||||||
|
|
||||||
|
> ⚠️ **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 в тексте** — только ссылки на корпоративный контекст сессии и
|
||||||
|
переменные окружения.
|
||||||
|
|
||||||
|
### Как добавить шаблон-команду
|
||||||
|
|
||||||
|
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`.
|
||||||
|
- Pi-библиотеки — только в `peerDependencies` (`"*"`), не бандлить.
|
||||||
|
|
||||||
|
### Локальная проверка перед MR
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# из корня репозитория
|
||||||
|
pi install ./ # установить пакет из локальной папки
|
||||||
|
pi # запустить: расширения загрузятся, команды /bugfix и т.д. появятся
|
||||||
|
|
||||||
|
# опциональный строгий typecheck (нужны peer-типы Pi):
|
||||||
|
npm install
|
||||||
|
npm run typecheck
|
||||||
|
```
|
||||||
|
|
||||||
|
Минимальный чек-лист MR: расширения загружаются без ошибок; `/kit-config` показывает значения;
|
||||||
|
запись в `.env` реально блокируется; изменение `config/company.json` отражается в `/kit-config`
|
||||||
|
без других правок.
|
||||||
Reference in New Issue
Block a user