# Руководство по установке (dsh-prime-memory)

Плагин распространяется в виде **официального bundle-пакета DSH**: после установки слой `dsh.bundle` в `cordis.patch.yml` автоматически подключает запись плагина — вручную править конфигурацию профиля не нужно.

## Требования к окружению

- Node.js ≥ 22.16 (DSH 0.2.0-rc.1 и новее)
- Установленный DeepSeek Harness (далее — DSH), доступен `--profile web`

## Установка

Выберите любой способ вызова (префикс `npx` может заменить `dsh` в любой из команд ниже):

```bash
# Способ 1: запустить официальный CLI напрямую через npx (предустановка dsh не нужна; можно зафиксировать версию, например dsh-prime-memory@0.8.4)
npx -y @deepseek-ai/dsh plugin --profile web add dsh-prime-memory

# Способ 2: при установленном CLI dsh (dsh — это forwarding-обёртка pnpm; если pnpm нет, сначала npm i -g pnpm)
dsh plugin --profile web add dsh-prime-memory

# Альтернативные источники пакета: репозиторий GitHub / локальный путь (разработка и отладка; link: указывает на репозиторий, достаточно npm run build + перезапуска dsh)
dsh plugin --profile web add https://github.com/drscrewdriver/dsh-prime-memory
dsh plugin --profile web add /path/to/dsh-prime-memory
```

### Поручить установку агенту (рекомендуется)

Отправьте текущему агенту приведённое ниже сообщение целиком и без изменений (если он умеет выполнять команды терминала):

```text
Установи плагин dsh-prime-memory для web-профиля DeepSeek Harness.

Выполни только следующие две команды и не изменяй другие профили:
dsh plugin --profile web add dsh-prime-memory
dsh --profile web --dump-config

Когда dsh-prime-memory появится в выводе, сообщи мне результат установки.
Не закрывай и не перезапускай работающий DSH по своей инициативе; после установки напомни мне вручную перезапустить DSH Web Host.
```

## Обновление

```bash
# Обновить до последней версии
dsh plugin --profile web update dsh-prime-memory

# Обновить до конкретной версии
dsh plugin --profile web update dsh-prime-memory@0.8.11
```

Обновление заменяет только код плагина и артефакты в `dist/`; каталог данных `~/.dsh/memory/` не затрагивается.

## Проверка

После установки и перезапуска DSH Web Host проверьте:

1. **Появился каталог данных** — плагин успешно применён: в `~/.dsh/memory/` появляются каталоги `conversations/`, `records/`, `scenes/` и файл `memory.db`;
2. **В настройках появилась страница «Память»** и в строке ввода появился пилюльный переключатель режимов — клиентская половина готова;
3. Отправьте сообщение с личной информацией, дождитесь завершения дистилляции, затем спросите об этом в другом ходе беседы: в контексте должна появиться строка «Внедрение контекста · memory».

Необязательный smoke-тест (для разработки/диагностики):

```bash
npm run build
npx tsc src/smoke.ts --outDir dist-smoke --module nodenext --moduleResolution nodenext --target es2022 --strict --skipLibCheck --esModuleInterop
node dist-smoke/smoke.js
```

## Миграция / откат

- **Миграция со старой версии (до 0.5.0 пакет назывался `dsh-memory-plugin`)**: старый каталог данных несовместим с новым пакетом; сделайте резервную копию и удалите `~/.dsh/memory/` — при первом запуске новый плагин пересоздаст его. Существующие воспоминания нельзя перенести напрямую, потребуется повторная дистилляция.
- **Откат на старую версию**: после `dsh plugin --profile web remove dsh-prime-memory` переустановите по документации старой версии; каталог данных сохранится, но старая версия не распознаёт новую структуру — рекомендуется его очистить.

## Удаление

```bash
dsh plugin --profile web remove dsh-prime-memory
```

Данные остаются в `~/.dsh/memory/`; если они больше не нужны, удалите весь каталог вручную.

## Поиск и устранение неисправностей

| Симптом | Вероятная причина | Решение |
| --- | --- | --- |
| После установки в настройках нет страницы «Память» | DSH не перезапущен / bundle не подключён | Перезапустите DSH Web Host; командой `dsh --profile web --dump-config` убедитесь, что `dsh-prime-memory` присутствует |
| При перезапуске ошибка `duplicate loader entry id` | в patch одновременно присутствует ручной `insert:` и добавление bundle с тем же id | Удалите добавленный вручную элемент `insert:`; пакет уже содержит собственный слой bundle |
| Нет строки «Внедрение контекста · memory» | дистилляция не запускалась / припоминание отключено | Проверьте, что режим не off и `recall.enabled=true`; найдите `L1 阶段完成` в `memory.log` |
| Загрузка локальной модели эмбеддингов зависает | зеркало недоступно по прямому соединению | Задайте `embedding.proxy` для работы через прокси; либо замените `embedding.mirror` на официальный `huggingface.co` |
| Удалённый эмбеддинг отдаёт ошибку 401 | неверная apiKey / сервис без ключа, которому ключ передавать не нужно | Проверьте `embedding.apiKey`; для собственного сервиса без ключа оставьте apiKey пустой |

Подробнее см. [README.md](./README.md) и [CHANGELOG.md](./CHANGELOG.md).