docs: user-facing OpenCode usage README (RU/EN)
Copy-ready for arka-ai.ru agentic helpers: one-liner, API key, /models, default model, catalog refresh, GUI env caveat.
This commit is contained in:
ixoblakp committed
1 parent
d9015902b0
commit
6e0dc4d02b
1 file changed
+164
-25
@@ -1,48 +1,187 @@
|
|||||||
# Arka public artifacts
|
# OpenCode и модели Arka AI
|
||||||
|
|
||||||
Public, anonymous files for Arka AI. Private product code stays in other Gitea
|
Arka AI — OpenAI-совместимый API (`https://api.arka-ai.ru/v1`). В каталоге models.dev его нет, поэтому в свежем OpenCode провайдера **Arka-AI** и списка моделей нет, пока не поставить плагин.
|
||||||
repos.
|
|
||||||
|
|
||||||
## OpenCode Arka-AI provider
|
Одна команда ставит плагин, skill и (по желанию) ключ. Каталог чат-моделей подтягивается сам (~116 из ~216; без TTS/картинок/видео/эмбеддингов). Снимок каталога обновляется каждый день в **05:00 по Москве**.
|
||||||
|
|
||||||
`arka-ai.ru` is not in models.dev. One command installs the OpenCode provider
|
Нужен [API-ключ Arka AI](https://arka-ai.ru/docs/account/api-keys). Секрет ключа показывается **один раз** при создании.
|
||||||
plugin, companion skill, and (optional) API key:
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Быстрый старт
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh | bash
|
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh | bash
|
||||||
```
|
```
|
||||||
|
|
||||||
With a key and a default model:
|
Скрипт спросит `ARKA_API_KEY` (можно оставить пустым и задать позже).
|
||||||
|
|
||||||
|
Ключ и модель по умолчанию сразу:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh \
|
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh \
|
||||||
| bash -s -- --key "$ARKA_API_KEY" --set-default DeepSeek-V4-Pro
|
| bash -s -- --key "$ARKA_API_KEY" --set-default DeepSeek-V4-Pro
|
||||||
```
|
```
|
||||||
|
|
||||||
Then open a **new shell** and restart opencode. `/models` should list **Arka-AI**
|
Дальше:
|
||||||
(~116 chat models).
|
|
||||||
|
|
||||||
The installer is offline and idempotent. It does not call `api.arka-ai.ru`.
|
1. Откройте **новый терминал** (чтобы подхватился `export ARKA_API_KEY`).
|
||||||
`python3` is required only with `--set-default`.
|
2. Перезапустите OpenCode.
|
||||||
|
3. Команда `/models` — в списке должен быть провайдер **Arka-AI** и чат-модели.
|
||||||
|
|
||||||
### Files
|
Если OpenCode запущен из GUI / иконки / сокета, а не из login-shell, переменная из `~/.bashrc` до него может не дойти. Задайте `ARKA_API_KEY` в том окружении, откуда стартует OpenCode, или введите ключ в интерактивном приглашении установщика.
|
||||||
|
|
||||||
|
### Что ставится
|
||||||
|
|
||||||
|
| Куда | Что |
|
||||||
|
|------|-----|
|
||||||
|
| `~/.config/opencode/plugins/arka-ai.ts` | Плагин провайдера **Arka-AI** |
|
||||||
|
| `~/.config/opencode/skills/arka-provider/SKILL.md` | Skill: как обновить каталог и сменить модель |
|
||||||
|
| `~/.bashrc` (или первый из `.zshrc` / `.profile`) | `export ARKA_API_KEY=…`, если ключ передали |
|
||||||
|
| `~/.config/opencode/opencode.json` | Только при `--set-default`: `"model": "Arka-AI/<id>"`. Существующий конфиг **не затирается**. |
|
||||||
|
|
||||||
|
Установщик **офлайн** и идемпотентный: сеть не трогает, повторный запуск перезаписывает плагин и skill каноническими копиями.
|
||||||
|
|
||||||
|
`python3` нужен только с `--set-default`. Отдельный `bun` на машине не нужен — у OpenCode свой runtime.
|
||||||
|
|
||||||
|
### Модель по умолчанию
|
||||||
|
|
||||||
|
Идентификаторы — как в каталоге, с префиксом провайдера:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"model": "Arka-AI/DeepSeek-V4-Pro"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Примеры: `Arka-AI/DeepSeek-V4-Pro`, `Arka-AI/qwen3.8-max`, `Arka-AI/kimi-k3`, `Arka-AI/MiniMax-M3`, `Arka-AI/GLM-5.3`, `Arka-AI/deepseek-v4-flash-0731`.
|
||||||
|
|
||||||
|
Их всегда оставляем в списке, даже если фильтр чат-моделей их бы отсёк.
|
||||||
|
|
||||||
|
### Обновить каталог
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -f ~/.cache/opencode/arka-ai-models.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Перезапустите OpenCode. Плагин сначала берёт публичный снимок
|
||||||
|
`https://git.arka-ai.ru/arka/public/raw/branch/main/catalog.json`
|
||||||
|
(без ключа), при ошибке — живой `https://api.arka-ai.ru/v1/models`. Локальный кэш живёт 24 часа. Конфиг OpenCode на лету не перечитывается.
|
||||||
|
|
||||||
|
Список моделей (ключ не нужен):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sS https://git.arka-ai.ru/arka/public/raw/branch/main/catalog.json | python3 -m json.tool
|
||||||
|
```
|
||||||
|
|
||||||
|
Вызовы моделей идут на `https://api.arka-ai.ru/v1` с `ARKA_API_KEY`.
|
||||||
|
|
||||||
|
### Если что-то не так
|
||||||
|
|
||||||
|
| Симптом | Что проверить |
|
||||||
|
|---------|----------------|
|
||||||
|
| После `/models` нет Arka-AI | Есть ли `~/.config/opencode/plugins/arka-ai.ts`; экспортирован ли `ARKA_API_KEY` **в процессе OpenCode**; открыт ли новый шелл |
|
||||||
|
| Каталог не меняется | `rm -f ~/.cache/opencode/arka-ai-models.json` и рестарт |
|
||||||
|
| Ошибка импорта плагина | Снова запустить установщик — он вернёт канонический файл |
|
||||||
|
| `curl` отдаёт HTML, не скрипт | Нужен путь `/raw/branch/main/…`, не страница репозитория |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# OpenCode and Arka AI models
|
||||||
|
|
||||||
|
Arka AI is an OpenAI-compatible API at `https://api.arka-ai.ru/v1`. It is not in models.dev, so a fresh OpenCode install has no **Arka-AI** provider until you add the plugin.
|
||||||
|
|
||||||
|
One command installs the plugin, a companion skill, and (optionally) your API key. The chat catalog loads on OpenCode start (~116 of ~216 models; TTS, image, video, and embeddings are filtered out). The published catalog snapshot refreshes daily at **05:00 Europe/Moscow**.
|
||||||
|
|
||||||
|
You need an [Arka AI API key](https://arka-ai.ru/docs/account/api-keys). The secret is shown **once** at creation.
|
||||||
|
|
||||||
|
## Quick start
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh | bash
|
||||||
|
```
|
||||||
|
|
||||||
|
The script prompts for `ARKA_API_KEY` (blank is allowed; set it later).
|
||||||
|
|
||||||
|
Key and default model in one go:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -fsSL https://git.arka-ai.ru/arka/public/raw/branch/main/install-arka-provider.sh \
|
||||||
|
| bash -s -- --key "$ARKA_API_KEY" --set-default DeepSeek-V4-Pro
|
||||||
|
```
|
||||||
|
|
||||||
|
Then:
|
||||||
|
|
||||||
|
1. Open a **new shell** so `export ARKA_API_KEY` is picked up.
|
||||||
|
2. Restart OpenCode.
|
||||||
|
3. Run `/models` — you should see provider **Arka-AI** and the chat models.
|
||||||
|
|
||||||
|
If OpenCode is started from a GUI, dock icon, or socket rather than a login shell, `~/.bashrc` may not reach it. Set `ARKA_API_KEY` in that process environment, or type it at the installer prompt.
|
||||||
|
|
||||||
|
### What the installer writes
|
||||||
|
|
||||||
| Path | Role |
|
| Path | Role |
|
||||||
|------|------|
|
|------|------|
|
||||||
| `install-arka-provider.sh` | Self-extracting installer (the one-liner) |
|
| `~/.config/opencode/plugins/arka-ai.ts` | **Arka-AI** provider plugin |
|
||||||
| `plugins/arka-ai.ts` | Provider plugin source (embedded in the installer) |
|
| `~/.config/opencode/skills/arka-provider/SKILL.md` | How to refresh the catalog and change the default model |
|
||||||
| `skills/arka-provider/SKILL.md` | Companion skill source (embedded in the installer) |
|
| `~/.bashrc` (else first existing `.zshrc` / `.profile`) | `export ARKA_API_KEY=…` when a key is given |
|
||||||
| `catalog.json` | Filtered chat catalog, refreshed daily at **05:00 Europe/Moscow** from `https://api.arka-ai.ru/v1/models` |
|
| `~/.config/opencode/opencode.json` | Only with `--set-default`: `"model": "Arka-AI/<id>"`. An existing config is **not** replaced. |
|
||||||
|
|
||||||
Forced keep-list: `DeepSeek-V4-Pro`, `deepseek-v4-flash-0731`, `qwen3.8-max`,
|
The installer is **offline** and idempotent: no network calls; re-running overwrites plugin and skill with the canonical copies.
|
||||||
`kimi-k3`, `MiniMax-M3`, `GLM-5.3`.
|
|
||||||
|
|
||||||
Inference uses `ARKA_API_KEY` against `https://api.arka-ai.ru/v1`. Listing the
|
`python3` is required **only** with `--set-default`. You do not need `bun` on the host — OpenCode ships its own runtime.
|
||||||
catalog does not require a key.
|
|
||||||
|
|
||||||
After install:
|
### Default model
|
||||||
|
|
||||||
1. New shell so `ARKA_API_KEY` is exported (GUI/desktop launches may need the
|
Use catalog ids with the provider prefix:
|
||||||
key set in that session, not only `~/.bashrc`).
|
|
||||||
2. Restart opencode, run `/models`.
|
```json
|
||||||
3. Refresh later: `rm -f ~/.cache/opencode/arka-ai-models.json` and restart.
|
{
|
||||||
|
"model": "Arka-AI/DeepSeek-V4-Pro"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Examples: `Arka-AI/DeepSeek-V4-Pro`, `Arka-AI/qwen3.8-max`, `Arka-AI/kimi-k3`, `Arka-AI/MiniMax-M3`, `Arka-AI/GLM-5.3`, `Arka-AI/deepseek-v4-flash-0731`.
|
||||||
|
|
||||||
|
Those ids stay visible even if the chat filter would drop them.
|
||||||
|
|
||||||
|
### Refresh the catalog
|
||||||
|
|
||||||
|
```bash
|
||||||
|
rm -f ~/.cache/opencode/arka-ai-models.json
|
||||||
|
```
|
||||||
|
|
||||||
|
Restart OpenCode. The plugin fetches the public snapshot
|
||||||
|
`https://git.arka-ai.ru/arka/public/raw/branch/main/catalog.json`
|
||||||
|
(no key), then falls back to live `https://api.arka-ai.ru/v1/models`. Local cache TTL is 24 hours. OpenCode does not hot-reload config.
|
||||||
|
|
||||||
|
Inspect the published list (no key):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -sS https://git.arka-ai.ru/arka/public/raw/branch/main/catalog.json | python3 -m json.tool
|
||||||
|
```
|
||||||
|
|
||||||
|
Inference still uses `ARKA_API_KEY` against `https://api.arka-ai.ru/v1`.
|
||||||
|
|
||||||
|
### Troubleshooting
|
||||||
|
|
||||||
|
| Symptom | Check |
|
||||||
|
|---------|--------|
|
||||||
|
| No Arka-AI after `/models` | `~/.config/opencode/plugins/arka-ai.ts` exists; `ARKA_API_KEY` is set **in the OpenCode process**; you opened a new shell |
|
||||||
|
| Models look stale | `rm -f ~/.cache/opencode/arka-ai-models.json` and restart |
|
||||||
|
| Plugin import error | Re-run the installer to restore the canonical file |
|
||||||
|
| `curl` returns HTML | Use `/raw/branch/main/…`, not the repo page |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## This repository
|
||||||
|
|
||||||
|
Public, anonymous files. Private product code lives in other Gitea repos.
|
||||||
|
|
||||||
|
| File | Role |
|
||||||
|
|------|------|
|
||||||
|
| `install-arka-provider.sh` | Self-contained installer (the one-liner) |
|
||||||
|
| `plugins/arka-ai.ts` | Plugin source (embedded in the installer) |
|
||||||
|
| `skills/arka-provider/SKILL.md` | Skill source (embedded in the installer) |
|
||||||
|
| `catalog.json` | Filtered chat catalog, refreshed daily at 05:00 Europe/Moscow |
|
||||||
|
| `README.md` | This page — copy the Russian or English section into arka-ai.ru «агентные помощники» / agentic helpers |
|
||||||
Reference in new issue
Block a user