grayhook
c12a3717cd
Explain idle vs mid-turn delivery with pi-auto-compact and how to use debug snapshots when last compaction shows none incorrectly. Co-authored-by: Cursor <cursoragent@cursor.com>
92 lines
5.3 KiB
Markdown
92 lines
5.3 KiB
Markdown
# pi-skill-reinject
|
||
|
||
Pi Coding Agent extension: отслеживает вызванные skills и повторно инжектит их после auto compaction.
|
||
|
||
**Статус:** реализовано (v1)
|
||
|
||
## Установка
|
||
|
||
```bash
|
||
# из клона репозитория
|
||
pi -e ./src/index.ts
|
||
|
||
# или абсолютный путь
|
||
pi -e ~/Documents/repos/pi-auto-reinjection/src/index.ts
|
||
```
|
||
|
||
Для постоянной установки укажите путь к `src/index.ts` в `~/.pi/agent/settings.json` → `extensions` (нужен весь каталог `src/`, не один файл). См. [Pi extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md).
|
||
|
||
По умолчанию extension **выключен**. Включение:
|
||
|
||
```text
|
||
/skill-reinject on # эта сессия
|
||
/skill-reinject global on # навсегда (~/.pi/agent/settings.json)
|
||
```
|
||
|
||
## Команда `/skill-reinject`
|
||
|
||
```text
|
||
/skill-reinject # статус (enabled, delivery, tracked, pending)
|
||
/skill-reinject on | off | reset # session override
|
||
/skill-reinject global on | off # глобальный default
|
||
/skill-reinject list | clear # tracked skills
|
||
/skill-reinject now # принудительный re-inject (debug)
|
||
/skill-reinject integration auto|defer|immediate|off
|
||
```
|
||
|
||
Алиасы: `/sr`, `/skills-reinject`. Footer status: `on·N` / `off·N`.
|
||
|
||
Полный синтаксис и настройки — [SPEC.md §7](./SPEC.md#7-команда-skill-reinject).
|
||
|
||
## Как это работает
|
||
|
||
Pi хранит в контексте только описания skills; полный `SKILL.md` теряется при compaction. Extension отслеживает вызванные skills (`/skill:name`, skill-блоки, `read` на `SKILL.md` при `trackReadPaths: true`) и после **auto** compaction повторно инжектит отсутствующие в kept window блоки — тем же форматом, что `/skill:name`.
|
||
|
||
## Skills via `--skill` and discovery paths
|
||
|
||
| Источник skill | Трекинг | Re-inject после compact |
|
||
|----------------|---------|-------------------------|
|
||
| Discovery (`~/.pi/agent/skills`, `.pi/skills`) | Да | По имени в resourceLoader |
|
||
| CLI `--skill /path/to/SKILL.md` | Да (`slash` / skill-блок) | Да, если `SKILL.md` ещё на диске по `tracked.filePath` |
|
||
| `--resume` без повторного `--skill` | Восстанавливается из state entry / rescan | Да при `requireRegistered: false` (default) |
|
||
|
||
По умолчанию `skillReinject.requireRegistered` — **`false`**: tracked skill re-injectится с диска, даже если `resourceLoader` его не знает (типично для `--skill` вне discovery paths). Уведомление: `re-injected "<name>" from disk`.
|
||
|
||
Строгий режим — только skills из resourceLoader:
|
||
|
||
```json
|
||
{
|
||
"skillReinject": {
|
||
"requireRegistered": true
|
||
}
|
||
}
|
||
```
|
||
|
||
Полезно при `--no-skills` или осознанном отключении skill через `pi config`, когда re-inject с диска нежелателен.
|
||
|
||
## Совместимость с pi-auto-compact
|
||
|
||
Рассчитан на совместную работу с [@capyup/pi-auto-compact](https://github.com/capyup/pi-auto-compact). При обнаружении команды `auto-compact` re-inject идёт через `defer`:
|
||
|
||
- **Idle** (turn boundary): очередь на `before_agent_start` — в том же turn, что follow-up pi-auto-compact, без гонки `sendUserMessage`.
|
||
- **Mid-turn** (`!isIdle`, после tool result): немедленная доставка через `sendMessage` с `deliverAs: "steer"` — skill попадает в контекст до следующего LLM-вызова без user prompt.
|
||
|
||
Если `/skill-reinject` показывает `last compaction: none` после auto compact — включите `"debug": true` в `skillReinject` и смотрите notify `skill-reinject [session_compact]`: поля `compactionSource`, `sourceInferred`, `deliveryBranch`, `isIdle`.
|
||
|
||
**Coexistence с Pi default auto-compaction:** оба механизма могут сработать в одной сессии. При использовании pi-auto-compact можно отключить встроенный compaction Pi (`"compaction.enabled": false` в settings) или оставить оба — skill-reinject отработает после каждого **auto** compaction. Extension не отключает чужой compaction; при первом обнаружении обоих механизмов показывает одноразовый hint.
|
||
|
||
## Разработка
|
||
|
||
```bash
|
||
npm run typecheck # tsc --noEmit
|
||
npm test # vitest
|
||
```
|
||
|
||
## Документация
|
||
|
||
- [SPEC.md](./SPEC.md) — полное ТЗ
|
||
- [Pi extensions](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md)
|
||
- [Pi skills](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/skills.md)
|
||
- [Pi compaction](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/compaction.md)
|
||
- [pi-auto-compact](https://github.com/capyup/pi-auto-compact)
|