48 lines
3.5 KiB
Markdown
48 lines
3.5 KiB
Markdown
---
|
||
name: confluence
|
||
description: Используй, когда нужно найти или написать документацию в корпоративном Confluence — поискать страницы, прочитать содержимое, создать новую страницу. Применяй при вопросах «где документация», «есть ли дока по», «помогить найти в вики», «создай страницу», а также в команде /rfc.
|
||
---
|
||
|
||
# Работа с документацией (Confluence)
|
||
|
||
Скилл покрывает поиск и создание страниц в корпоративной вики. Адрес и токен берутся
|
||
автоматически — ничего не хардкодь и не спрашивай.
|
||
|
||
## Откуда адрес и токен
|
||
|
||
- **Адрес** — из `docsUrl` в `config/company.json` (в контекст сессии его инжектит
|
||
расширение `company-context`). Можно переопределить переменной `CONFLUENCE_URL`.
|
||
- **Токен** — `CONFLUENCE_TOKEN` (personal access token). Задаётся в
|
||
`~/.config/pi-kit/env.sh`. Не подставляй его в команды и не логируй.
|
||
|
||
## Инструменты
|
||
|
||
Доступны как нативные инструменты pi (регистрирует `extensions/confluence-tools.ts`):
|
||
|
||
- **`confluence_search`** — поиск страниц по CQL-запросу.
|
||
Примеры CQL:
|
||
- `text = "деплой"` — по тексту;
|
||
- `title = "RFC"` — по заголовку;
|
||
- `space = TECHRUN AND type = page` — в конкретном пространстве;
|
||
- сложное: `(text = "kubernetes" OR title = "k8s") AND space = SRE`.
|
||
- **`confluence_page_get`** — получить страницу по ID (с `expandBody` — вернуть текст).
|
||
- **`confluence_page_create`** — создать страницу в пространстве (body — HTML в Storage
|
||
format или обычный текст; укажи `parentId` для вложенности).
|
||
|
||
## Соглашения
|
||
|
||
- **Сначала ищи, потом создавай.** Прежде чем писать новую страницу — `confluence_search`
|
||
по теме, чтобы не дублировать существующую.
|
||
- **Храни адреса страниц** в ответах — верни URL созданной/найденной страницы пользователю.
|
||
- Если инструмент вернул ошибку «проверь токен» — попроси пользователя проверить
|
||
`CONFLUENCE_TOKEN`, не выдавай сам токен.
|
||
- Ключи пространств (`spaceKey`) — реальные значения посмотри через `confluence_search`; если
|
||
запросили создать страницу, а пространство неизвестно — уточни у пользователя.
|
||
|
||
## Полезное
|
||
|
||
- Для RFC/ADR часто нужен свежий поиск в пространстве архитектуры — используй
|
||
`confluence_search` с `space =` нужного пространства. Если карта документации
|
||
(`docs-map`) ещё с TODO — не выдумывай пространства, спроси пользователя или начни с
|
||
поиска, чтобы определить реальные.
|