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