# dsh-arckep

[English](README.md) | Русский

Показывает **баланс и расход вашего аккаунта [arckep.ru](https://arckep.ru)** прямо в веб-окне
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH): небольшой значок с
балансом в шапке сессии и в нижней части боковой панели, панель с подробностями и страница
настроек для ключа API.

> **Неофициальный плагин.** Его сделало сообщество. Он не создан DeepSeek, не одобрен ими и никак
> с ними не связан. arckep.ru — сторонний сервис, к которому подключается плагин; нужен ваш
> собственный аккаунт и ключ API на arckep.ru.

## Что вы получите

- **Значок** в шапке открытой сессии: баланс в виде `1 234,50 ₽`. Он становится «предупреждающим»,
  когда баланс ниже вашего порога (по умолчанию 100 ₽) или по прогнозу денег хватит меньше чем
  на 3 дня. Клик открывает панель.
- **Значок в боковой панели**: тот же баланс (иконка и сумма) внизу боковой панели, над «Settings»,
  поэтому он виден и на пустом стартовом экране; правила предупреждения те же. Клик открывает ту же
  панель. Его можно отключить в Настройки → Arckep.
- **Панель**: баланс (с пометкой для корпоративного кошелька), расход за сегодня / 7 дней /
  30 дней, пять самых дорогих моделей, «хватит примерно на N дн.», «обновлено N мин назад» и кнопка
  «Обновить».
- **Настройки → Arckep**: поле для ключа (после сохранения очищается и лишь показывает, что ключ
  задан), «Сохранить» / «Удалить ключ», переключатель «считать расход только по этому ключу»,
  интервал опроса (по умолчанию 300 с, минимум 60 с), порог предупреждения, «показывать баланс в
  боковой панели» и язык интерфейса.
- Интерфейс на русском и английском по языку DSH (русский, если язык определить нельзя;
  английский для других языков DSH). Сам DSH поставляется с английским и китайским, поэтому
  русскоязычный пользователь может переключить плагин на русский в Настройки → Arckep. Цвета
  берутся из темы DSH, поэтому светлая и тёмная темы работают.
- Если arckep.ru недоступен, на экране остаются последние удачные цифры с пометкой
  «данные устарели».

Значок в шапке есть, только пока открыта сессия. Значок в боковой панели от сессии не зависит. Когда
боковая панель свёрнута в узкую рейку, он показывает только иконку рубля (сумма — при наведении или
фокусе), поэтому ничего не переносится и не обрезается. Оба значка делят одно состояние и одну
панель: одновременно открыта только одна панель, обновление в одном месте сразу видно в другом, а
второй значок не делает лишних запросов.

## Требования

- DSH **0.2.0-rc.2** или новее с веб-интерфейсом (`dsh web`). DSH — это превью для разработчиков,
  его интерфейсы плагинов ещё меняются, см. [Совместимость](#совместимость). Сам DSH требует
  Node.js 22.19+ (или 24+); у плагина других требований нет.
- Профиль DSH с веб-приложением (поставляемый профиль `web` подходит).
- Ключ API arckep.ru с доступом **`balance:read`**.

## Установка

```sh
dsh plugin --profile web add dsh-arckep
dsh web
```

(`web` — имя профиля; если у вас свой профиль, подставьте его.) Сборки и скриптов установки нет,
поэтому ничего дополнительно разрешать или собирать не нужно. В npm пакет есть начиная с версии 0.1.2.

Чтобы поставить прямо из GitHub или зафиксировать коммит или тег:

```sh
dsh plugin --profile web add github:gmen1057/dsh-arckep
dsh plugin --profile web add github:gmen1057/dsh-arckep#<коммит-или-тег>
```

Проверить, что слой подключён: `dsh --profile web --dump-config` (ищите блок `# == dsh-arckep`).
Удалить плагин: `dsh plugin --profile web remove dsh-arckep`.

### Настольное приложение

У DSH Desktop свой профиль `desktop`. По документации DSH: запустите приложение один раз,
**полностью закройте его**, выполните `dsh plugin --profile desktop add dsh-arckep`
(командой `dsh`, которая идёт вместе с приложением) и снова откройте приложение.
Для профиля `desktop` команда `dsh --profile desktop --dump-config` отказывает («managed exclusively
by the Electron application»), поэтому единственная проверка — значок внизу боковой панели (или в шапке открытой сессии).
Автор плагина в настольном приложении не проверял.

## Как задать ключ

1. На arckep.ru откройте **Настройки → API** и создайте ключ. Нужен доступ к **балансу**
   (`balance:read`). У новых ключей он есть по умолчанию; безопаснее всего завести отдельный ключ
   только с этим доступом.
2. В DSH откройте **Настройки → Arckep**, вставьте ключ и нажмите **Сохранить**. Поле очистится, а
   страница напишет «Ключ задан».

Можно вместо этого экспортировать `ARCKEP_API_KEY` перед запуском DSH. Действует правило DSH:
переменная окружения важнее сохранённого ключа, и страница настроек показывает такой ключ как
доступный только для чтения.

## Настройки

| Настройка | По умолчанию | Где хранится |
|---|---|---|
| Ключ API | нет | хранилище ключей DSH (`ARCKEP_API_KEY`), см. «Приватность» |
| Показывать баланс в боковой панели | вкл. | этот браузер |
| Считать расход только по этому ключу | выкл. | этот браузер |
| Интервал опроса | 300 с (минимум 60 с) | этот браузер |
| Предупреждать, когда баланс ниже | 100 ₽ | этот браузер |
| Язык интерфейса | как в DSH | этот браузер |

Три настройки отображения выше языка можно задать и «по умолчанию» для всей установки: переопределите строку `arckep` в
`cordis.patch.yml` своего профиля (`$DSH_HOME/profiles/<профиль>/cordis.patch.yml`):

```yaml
- id: arckep
  config:
    refreshSeconds: 600
    warnBelowRub: 300
    keyOnly: false
```

То, что пользователь изменил в Настройки → Arckep, перекрывает эти значения в его браузере.

## Как это работает

- К arckep.ru обращается **сервер** DSH, а не браузер. Браузер разговаривает только с DSH.
- Запросы делаются, только пока открыта и видна страница DSH, и только если сохранённый ответ
  старше интервала опроса. Фоновых таймеров на сервере нет.
- Один запрос за раз, таймаут 10 с, перенаправления не выполняются. После ошибок следующая
  автоматическая попытка откладывается на 30 с, 60 с, 120 с … до 30 минут (и на `Retry-After`
  при HTTP 429).
- 401 (неверный ключ) и 403 (нет доступа) автоматически не повторяются; после исправления ключа
  нажмите «Обновить».
- Расход берётся из `GET /api/v1/usage`. Если на сервере arckep.ru такого адреса ещё нет
  (HTTP 404), плагин продолжает показывать баланс и без всяких ошибок скрывает блок расхода.
  Время от времени он пробует снова.

## Приватность и безопасность

- Плагин обращается **только к `https://arckep.ru`**: `GET /api/v1/balance` и
  `GET /api/v1/usage?days=30&key_only=...`. Хост и схема https проверяются в коде; перенаправление
  (любой ответ 3xx) считается ошибкой и не выполняется.
- **Никакой телеметрии, аналитики и сторонних запросов.** Плагин не пишет собственных файлов;
  единственное, что сохраняет DSH, — ключ в своём хранилище. Настройки отображения лежат в
  `localStorage` вашего браузера.
- Ключ уходит в заголовке `Authorization: Bearer` на arckep.ru и больше никуда. Он никогда не
  попадает в `cordis.patch.yml`, в адрес запроса, в журналы, в тексты ошибок и в то, что
  отправляется браузеру; браузер узнаёт лишь, задан ли ключ и откуда он.
- Четыре маршрута плагина живут на собственном защищённом канале `/api` самого DSH, поэтому их
  защищают проверки Host/Origin и cookie браузерной сессии DSH. Запросы, меняющие состояние,
  дополнительно требуют JSON-тип содержимого и запрос с того же источника.
- **Помните, где лежит ключ.** Локальное хранилище ключей DSH — файл в `$DSH_HOME`
  (`~/.dsh/.credentials.yaml`, права 600). Инструменты, которые запускает агент DSH, работают под
  тем же пользователем ОС и могут его прочитать. Это свойство DSH, а не плагина. Ограничьте ущерб:
  заведите ключ только с `balance:read` и отзовите его на arckep.ru, если подозреваете утечку.
- Стандартные переменные прокси, которые учитывает DSH (см. руководство DSH по сетевому прокси),
  действуют и здесь, потому что плагин использует обычный `fetch` хоста. Работу через прокси я не
  проверял.

О найденных уязвимостях сообщайте приватно, см. [SECURITY.md](SECURITY.md).

## Если что-то не так

| Что вы видите | Что это значит |
|---|---|
| «arckep.ru не принял ключ (401)» | ключ неверный или отозван; вставьте новый |
| «У ключа нет нужного доступа (balance:read)» | создайте ключ с доступом «баланс» |
| «Нет связи с arckep.ru» / «не ответил за 10 секунд» | проблема сети; последние цифры остаются с пометкой «устарели» |
| «Расход пока недоступен на стороне arckep.ru» | на сервере нет адреса `/usage` (пока); баланс при этом работает |
| значка нет совсем | посмотрите внизу боковой панели, над «Settings» (значок в шапке есть только при открытой сессии). Если в Настройках есть страница Arckep, проверьте, что включено «Показывать баланс в боковой панели»; если такой страницы нет, плагин не загружен: ищите блок `# == dsh-arckep` в `dsh --profile web --dump-config` |
| «Ключ задан переменной окружения» | уберите `ARCKEP_API_KEY`, чтобы управлять ключом в Настройках |
| установка не удалась, DSH пишет «git-hosted plugins build on install via their prepare script…» | эта подсказка выводится при **любой** неудачной установке с адресом `github:`. У dsh-arckep нет скриптов установки, `allowBuilds` не нужен; читайте настоящую ошибку pnpm выше подсказки |
| установка не удалась из-за `minimumReleaseAge` | pnpm 11 по умолчанию не берёт пакеты, опубликованные меньше 24 часов назад, и проверяет все пакеты из lockfile профиля, а не только новый. В сообщении названы слишком свежие пакеты; если это другие плагины, виноваты они. Повторите позже или поставьте плагин из GitHub (`github:gmen1057/dsh-arckep#v0.1.2`) |

## Совместимость

DSH — **превью для разработчиков**: его интерфейсы плагинов могут меняться между выпусками, а этот
плагин опирается на слоты веб-клиента (`conversation.session.header.utilities`,
`sidebar.footer.action`, `settings.section`) и на `ctx.connection.fetch` и `ctx.credentials`
хоста.

| Версия DSH | Статус |
|---|---|
| 0.2.0-rc.2 (`latest`) | проверено: ставится (из локальной папки, tarball и git-адреса), загружается, значки в шапке и в боковой панели, панель, настройки, хранение ключа, отключение/включение на лету |
| 0.2.1-alpha.2 (`alpha`) | проверено: ставится из tarball, загружается, значки в шапке и в боковой панели, панель, настройки, хранение ключа |

Проверялся только веб-интерфейс (`dsh web`). У TUI нет веб-клиента, он не поддерживается;
настольное приложение автор не проверял (порядок установки для него описан выше).

## Разработка

```sh
npm ci
npm run check      # проверка синтаксиса и манифеста
npm test           # node --test, без сети
node scripts/mock-arckep.mjs 39100                      # локальная заглушка API
DSH_ARCKEP_TEST_ORIGIN=http://127.0.0.1:39100 dsh web   # направить DSH на заглушку
```

`DSH_ARCKEP_TEST_ORIGIN` нужна только для разработки. Она принимается лишь тогда, когда указывает
на loopback-адрес по обычному http с портом от 1024 (например, `http://127.0.0.1:39100`); любое
другое значение игнорируется и попадает в журнал. Через настройки плагина её задать нельзя, так
что файл профиля не может перенаправить ключ. В обычной работе её не задавайте.

Клиентская часть (`lib/client.js`) — один рукописный файл в формате «ленивого CommonJS»,
которым DSH загружает клиентские модули, поэтому для установки из GitHub сборка не нужна.

## Благодарности

Публичные плагины [dsh-cost-meter](https://github.com/Han-1413141/dsh-cost-meter) и
[dsh-web-billing](https://github.com/bpc-oss/dsh-web-billing) помогли разобраться, как устроен
веб-плагин DSH (слоты, хранилище ключей, формат клиентских модулей). Код оттуда не копировался.

## Лицензия

[MIT](LICENSE) © 2026 gmen1057