docs(api-tools): document native Jira/Confluence/GitLab tools, drop MCP references

This commit is contained in:
Aleksey Shakhmatov
2026-08-06 14:43:23 +03:00
parent 7804681356
commit c2f45da70c
2 changed files with 62 additions and 16 deletions
+19
View File
@@ -17,6 +17,16 @@
- Пример конфига в README приведён в соответствие с реальным `config/company.json`. - Пример конфига в README приведён в соответствие с реальным `config/company.json`.
### Added ### Added
- **Нативные инструменты** для Jira/Confluence/GitLab вместо MCP-моста и bash-скриптов:
`jira_issue_*` (get/create/update/comment/transition/search/link_mr),
`gitlab_mr_create`/`gitlab_pipeline_status`/`gitlab_code_search`,
`confluence_search`/`confluence_page_get`/`confluence_page_create`.
Логика — в чистых модулях `extensions/lib/{jira,gitlab,confluence,atlassian}.ts`
(unit-тесты `test/api.test.ts`), URL — из `config/company.json`, токены — из env.
- Новый скилл `confluence` (поиск/чтение/создание страниц wiki).
- `install.sh`: дефолтные URL сервисов берутся из `config/company.json` и предлагаются
с подтверждением/вводом; добавлены `CONFLUENCE_URL`/`CONFLUENCE_TOKEN` и короткие справки
«где взять токен» для Jira/Confluence/GitLab.
- `uninstall.sh` — полное удаление кита одной командой с подтверждением - `uninstall.sh` — полное удаление кита одной командой с подтверждением
(пакет+клон, публичные скилы, `~/.config/pi-kit` с токенами, блок в shell-rc; (пакет+клон, публичные скилы, `~/.config/pi-kit` с токенами, блок в shell-rc;
флаги `PI_KIT_UNINSTALL`/`PI_KIT_KEEP_CONFIG`/`PI_KIT_KEEP_SKILLS`); покрыт тестами флаги `PI_KIT_UNINSTALL`/`PI_KIT_KEEP_CONFIG`/`PI_KIT_KEEP_SKILLS`); покрыт тестами
@@ -27,6 +37,15 @@
- Audit-endpoint: повторные попытки POST (до 3, с backoff), по-прежнему best-effort. - Audit-endpoint: повторные попытки POST (до 3, с backoff), по-прежнему best-effort.
- Явная проверка версии Node в тестах: `npm test` требует ≥ 22.6 (type-stripping), - Явная проверка версии Node в тестах: `npm test` требует ≥ 22.6 (type-stripping),
документировано в README/RELEASING. документировано в README/RELEASING.
- Новый профиль `pm` — для продакт-менеджеров: добавляет скилл `pm-task-spec`
(доведение сжатой постановки задачи до структурированной, пригодной для передачи
в разработку) без языковых стандартов кода.
### Changed
- MCP-мост (`mcp-bridge.ts`, `config/mcp.json`, `docs/mcp.md`, команда `/mcp-status`,
опциональная зависимость `@modelcontextprotocol/sdk`) **удалён** как часть перехода на
нативные инструменты; bash-скрипты `skills/jira-workflow/scripts/*.sh` убраны.
- `jira-workflow` переписан на вызов нативных инструментов (без bash/MCP).
## [0.2.1] — 2026-07-16 ## [0.2.1] — 2026-07-16
+43 -16
View File
@@ -16,10 +16,14 @@ guardrails и скиллы со знанием того, где у нас код
curl -fsSL https://git.codelab.vc/ai/pi-kit/raw/branch/stable/install.sh | bash curl -fsSL https://git.codelab.vc/ai/pi-kit/raw/branch/stable/install.sh | bash
``` ```
Скрипт проверит Node.js (>= 20), поставит Pi (если нет), установит этот пакет, **спросит Скрипт проверит `git` и Node.js (>= 20) — оба обязательны: git нужен для `pi install git:...`,
твой профиль**, поставит нужные скилы и **интерактивно настроит окружение** (`TRACKER_URL`, Node для Pi. Затем поставит Pi (если нет), установит этот пакет, **спросит твой профиль**, поставит
`JIRA_TOKEN`, `GITLAB_TOKEN`, ключ LLM-провайдера). Секреты вводятся скрыто и сохраняются в нужные скилы и **интерактивно настроит окружение** (`TRACKER_URL`, `CONFLUENCE_URL`,
`JIRA_TOKEN`, `CONFLUENCE_TOKEN`, `GITLAB_TOKEN`, ключ LLM-провайдера). Секреты вводятся скрыто и
сохраняются в
`~/.config/pi-kit/env.sh` (`chmod 600`), который подключается из твоего `~/.zshrc`/`~/.bashrc`. `~/.config/pi-kit/env.sh` (`chmod 600`), который подключается из твоего `~/.zshrc`/`~/.bashrc`.
Установщик просит подтвердить дефолтные URL сервисов (из `config/company.json`) и при запросе
каждого токена показывает короткую справку, где его получить.
Pi провайдер-агностичен — модель/провайдера пакет не навязывает, каждый выбирает свой Pi провайдер-агностичен — модель/провайдера пакет не навязывает, каждый выбирает свой
(Anthropic, OpenAI, OpenRouter, …). (Anthropic, OpenAI, OpenRouter, …).
@@ -34,8 +38,8 @@ PI_KIT_PROFILE=backend curl -fsSL https://git.codelab.vc/ai/pi-kit/raw/branch/st
### Профили и скилы ### Профили и скилы
Общее для всех: команды `/bugfix /feature /review /rfc /kit-config /kit-doctor /kit-help /mcp-status`, Общее для всех: команды `/bugfix /feature /review /rfc /kit-config /kit-doctor /kit-help`,
guardrails, скилы `jira-workflow`, `repo-map`, `docs-map`, и публичные `grill-me`, `grill-with-docs`, guardrails, скиллы `jira-workflow`, `confluence`, `repo-map`, `docs-map`, и публичные `grill-me`, `grill-with-docs`,
`code-review`, `diagnosing-bugs`. Дополнительно по профилю: `code-review`, `diagnosing-bugs`. Дополнительно по профилю:
| Профиль | Языковые стандарты | Доп. публичные скилы | | Профиль | Языковые стандарты | Доп. публичные скилы |
@@ -44,6 +48,11 @@ guardrails, скилы `jira-workflow`, `repo-map`, `docs-map`, и публич
| `backend` | go, rust, python | — | | `backend` | go, rust, python | — |
| `qa` | python, typescript | — | | `qa` | python, typescript | — |
| `mobile` | kotlin, swift | — | | `mobile` | kotlin, swift | — |
| `pm` | — | — (бандл `pm-task-spec`) |
Профиль `pm` — для продакт-менеджеров: подключает скилл **`pm-task-spec`** (доведение
сжатой постановки задачи до структурированной, пригодной для передачи в разработку)
без языковых стандартов кода.
Сменить профиль позже: `PI_KIT_PROFILE=frontend ./install.sh` (или перезапусти установку). Сменить профиль позже: `PI_KIT_PROFILE=frontend ./install.sh` (или перезапусти установку).
@@ -75,16 +84,34 @@ pi update --extensions
| `/kit-config` | Показать действующие корпоративные значения и их источник (local/remote) | | `/kit-config` | Показать действующие корпоративные значения и их источник (local/remote) |
| `/kit-doctor` | Health-check окружения (node, версия/канал, конфиг, env, токены; подсветит незаполненные поля) | | `/kit-doctor` | Health-check окружения (node, версия/канал, конфиг, env, токены; подсветит незаполненные поля) |
| `/kit-help` | Каталог возможностей: команды, скилы, guardrails | | `/kit-help` | Каталог возможностей: команды, скилы, guardrails |
| `/mcp-status` | Статус MCP-серверов (Jira/Confluence/GitLab; по умолчанию выключены — см. `docs/mcp.md`) |
### Нативные инструменты (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** — работа с трекером (чтение тикетов, комментарии, ссылки и создание MR). - **jira-workflow** — работа с трекером через нативные инструменты `jira_issue_*`
(чтение, создание/обновление, комментарии, переходы, JQL-поиск, привязка MR).
- **confluence** — поиск/чтение/создание страниц через `confluence_search`, `confluence_page_*`.
- **repo-map** — как ориентироваться в наших репозиториях (если карта не заполнена — скилл - **repo-map** — как ориентироваться в наших репозиториях (если карта не заполнена — скилл
скажет об этом и не будет выдумывать). скажет об этом и не будет выдумывать).
- **docs-map** — как искать и куда писать документацию. - **docs-map** — как искать и куда писать документацию.
- **pm-task-spec** — постановка задачи продакт-менеджером: выявляет слабые места, опрашивает
по ключевым доменам и выдаёт готовую структурированную постановку (подключается по профилю `pm`).
- **Языковые стандарты** — `<lang>-standards` для `go`/`rust`/`python`/`typescript`/`kotlin`/`swift`: - **Языковые стандарты** — `<lang>-standards` для `go`/`rust`/`python`/`typescript`/`kotlin`/`swift`:
структура, линтеры, тесты, коммиты/MR. Подключаются **по профилю** (см. таблицу выше), структура, линтеры, тесты, коммиты/MR. Подключаются **по профилю** (см. таблицу выше),
промпты команд ссылаются на них обобщённо (`<lang>-standards`), а не на конкретный язык. промпты команд ссылаются на них обобщённо (`<lang>-standards`), а не на конкретный язык.
@@ -114,19 +141,18 @@ pi update --extensions
pi-kit/ pi-kit/
├── package.json # манифест: секция "pi" + Pi-библиотеки в peerDependencies ("*") ├── package.json # манифест: секция "pi" + Pi-библиотеки в peerDependencies ("*")
├── config/company.json # ЕДИНЫЙ источник правды: gitHost, trackerUrl, docsUrl, repoMap, rules, remoteConfigUrl ├── config/company.json # ЕДИНЫЙ источник правды: gitHost, trackerUrl, docsUrl, repoMap, rules, remoteConfigUrl
├── extensions/ # TS-расширения (guardrails + инъекция контекста) ├── extensions/ # TS-расширения (guardrails + нативные инструменты + контекст)
│ ├── company-context.ts + company-context.md # контекст сессии + /kit-config │ ├── company-context.ts + company-context.md # контекст сессии + /kit-config
│ ├── jira-tools.ts gitlab-tools.ts confluence-tools.ts # нативные инструменты API
│ ├── protected-paths.ts │ ├── protected-paths.ts
│ ├── permission-gate.ts │ ├── permission-gate.ts
│ ├── secret-scanner.ts commit-guard.ts llm-redaction.ts audit-log.ts │ ├── secret-scanner.ts commit-guard.ts llm-redaction.ts audit-log.ts
│ ├── mcp-bridge.ts # Jira/Confluence/GitLab MCP (по умолч. выкл.)
│ ├── kit-cli.ts # /kit-doctor, /kit-help │ ├── kit-cli.ts # /kit-doctor, /kit-help
│ └── lib/ # общий код (secrets, audit, company-config) │ └── lib/ # общий код (jira, gitlab, confluence, secrets, audit, company-config)
├── skills/ # SKILL.md-скиллы (jira-workflow/repo-map/docs-map + <lang>-standards) ├── skills/ # SKILL.md-скиллы (jira-workflow/confluence/repo-map/docs-map/pm-task-spec + <lang>-standards)
├── prompts/ # шаблоны команд (/bugfix, /feature, /review, /rfc) ├── prompts/ # шаблоны команд (/bugfix, /feature, /review, /rfc)
├── test/ # guardrails.test.ts (node) + shell/uninstall shell-тесты ├── test/ # guardrails.test.ts + api.test.ts (node) + shell/uninstall shell-тесты
├── docs/mcp.md # документация MCP-интеграций ├── install.sh # bootstrap для новых сотрудников (дефолты URL из company.json + справки по токенам)
├── install.sh # bootstrap для новых сотрудников
└── uninstall.sh # полное удаление кита (с подтверждением) └── uninstall.sh # полное удаление кита (с подтверждением)
``` ```
@@ -146,7 +172,8 @@ pi-kit/
"docsUrl": "https://wiki.mvideo.ru", "docsUrl": "https://wiki.mvideo.ru",
"repoMap": "TODO: где какой код лежит", "repoMap": "TODO: где какой код лежит",
"rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"], "rules": ["не коммитить секреты", "не пушить в main", "MR обязателен"],
"remoteConfigUrl": null "remoteConfigUrl": null,
"auditEndpoint": null
} }
``` ```
@@ -191,7 +218,7 @@ pi-kit/
Чтобы поменять маппинг профиль→скилы — правь блок `case "$PROFILE"` и `COMMON_PUBLIC_SKILLS` Чтобы поменять маппинг профиль→скилы — правь блок `case "$PROFILE"` и `COMMON_PUBLIC_SKILLS`
в `install.sh`. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному в `install.sh`. Языковой скилл добавляется как обычный (см. ниже) и подключается к нужному
профилю в этом `case`. Профили: `frontend`, `backend`, `qa`, `mobile`. профилю в этом `case`. Профили: `frontend`, `backend`, `qa`, `mobile`, `pm`.
### Как добавить шаблон-команду ### Как добавить шаблон-команду