[English](../../README.md) | [简体中文](README.zh-CN.md) | [繁體中文](README.zh-TW.md) | [한국어](README.ko.md) | [Deutsch](README.de.md) | [Español](README.es.md) | [Français](README.fr.md) | [Italiano](README.it.md) | [Dansk](README.da.md) | [日本語](README.ja.md) | [Polski](README.pl.md) | [Русский](README.ru.md) | [Bosanski](README.bs.md) | [العربية](README.ar.md) | [Norsk](README.no.md) | [Português (Brasil)](README.pt-BR.md) | [ไทย](README.th.md) | [Türkçe](README.tr.md) | [Українська](README.uk.md) | [বাংলা](README.bn.md) | [Ελληνικά](README.el.md) | [Tiếng Việt](README.vi.md)
# Mercury CLI
Mercury CLI (mercury-cli.ai, npm-пакет `mercury-tech-cli`) запускає ШІ-агентів для написання коду у вашому терміналі, всередині ваших git-репозиторіїв на macOS, Linux і Windows.
Сайт: [mercury-cli.ai](https://mercury-cli.ai) · Репозиторій: [github.com/Whq02/MercuryCLI](https://github.com/Whq02/MercuryCLI) (`Whq02/MercuryCLI`) · npm: `mercury-tech-cli`
Агент читає і редагує файли, виконує shell-команди, покроково проходить тести та налагоджувачі й перевіряє результати. Ви обираєте провайдера моделей, саму модель і те, що агенту дозволено робити:
- **Кілька сесій у Concourse та ізольовані worktrees:** запускайте кілька сесій поруч у Session Concourse (`/concourse`) і доручайте паралельну роботу crewmates (напарникам, `Crewmate`) від різних провайдерів в ізольованих робочих копіях `git worktree` з орендою файлів проєкту, щоб паралельні агенти не перезаписували роботу одне одного.
- **22 провайдерів моделей, `/llmhost` і `/localsetup`:** тримайте всіх 22 провайдерів підключеними одночасно (OpenAI, Anthropic, Google Gemini, DeepSeek, Moonshot/Kimi, Z.AI/GLM, OpenRouter, Hugging Face, xAI/Grok, Meta/Muse, Mistral, Nous Portal, OpenCode Zen, Qwen, MiniMax, Together AI, Cohere, Groq, Cerebras, Fireworks AI, Melious AI, OrcaRouter) і перемикайте провайдерів та моделі прямо в чаті. Відкрийте `/llmhost`, щоб обрати модель, перевірити її квантизацію, розподіл `conversations × context` і рівень міркувань, а також запустити її на орендованому GPU (Runpod, Vast.ai або Lambda), на власному комп’ютері (`mercury host`) або на наявному сервері. Запустіть локальну модель на TensorFold за допомогою `/tensorfold` ([docs/TENSORFOLD.md](../TENSORFOLD.md)), або виконайте `/localsetup`, щоб встановити чи підключити Ollama разом із LM Studio, vLLM і llama.cpp.
- **Гібридна RAG-пам’ять проєкту Mneme:** використовує семантичну модель ембедингів BGE на 118 МБ, що працює на пристрої (`bge-base-en-v1.5`), ранжування слів за BM25, відстеження цитувань, закріплені правила дослівно, стартовий контекст з урахуванням гілки, перевірки суперечностей під час запису, нотатки передачі між сесіями та граф у браузері, що відкривається командою `/memory page`.
- **Інструменти компілятора, AST і налагодження DAP:** підключає аналіз коду через LSP та рефакторинги з попереднім переглядом (`LspRead`, `LspRename`, `LspMoveSymbol`, `LspMoveFile`, `LspCodeAction`, `LspFormat`), структурний пошук і переписування за AST tree-sitter для 57 мов (`AstSearch`, `AstEdit`), вбудований налагоджувач за Debug Adapter Protocol (`Debug`) з адаптерами (`debugpy`, `js-debug`, `lldb`, `gdb`, `dlv`) для покрокового налагодження тестів, що падають, на Python, Node, Go і Rust, а також постійні комірки `Eval` на Python і JavaScript.
- **`WebSearch` без ключів і `WebFetch` у markdown:** шукає через нативний пошук провайдера, ключі Brave або Tavily, офіційні API (Stack Exchange, npm, PyPI, crates.io, GitHub, Hacker News, Wikipedia), SearXNG і DuckDuckGo без ключа, а також завантажує публічну документацію в markdown у межах бюджету виклику 38 000 символів.
- **Керування комп’ютером, голосове введення Whisper, планування Saturn і мости до редакторів:** керує застосунками робочого столу (`Computer`), розшифровує голосове диктування push-to-talk на пристрої за допомогою Whisper (`/voice`), планує повторювані або одноразові сесії через Saturn (`/saturn`) і підключається до VS Code через Agent Client Protocol (`mercury acp`) разом з Unity, Blender, Godot та Aseprite.
- **Генерація відео (`Video`):** надсилайте промпти та довідкові файли проєкту до налаштованого генератора MiniMax ([docs/VIDEO.md](../VIDEO.md)) і зберігайте згенерований MP4 та необов’язковий PNG-кадр попереднього перегляду на 1-й секунді у вашому проєкті.
Mercury використовується для розробки самого Mercury: кілька сесій і моделей працюють над довгими завданнями. Найважче відстежувати цю роботу: що ще виконується, що змінилося і що потребує рішення. Кожна сесія під час завершення пише власну нотатку передачі, а наступна читає її один раз під час запуску разом із моїми закріпленими правилами, і це запобігає «отруєнню» контексту між сесіями.

Mercury має відкритий вихідний код за ліцензією Apache License 2.0, як і SDK у [sdk/](../../sdk/) та [sdk-py/](../../sdk-py/).
## Встановлення
Архіви релізів доступні для Mac на Apple silicon та Intel, Linux x64 і arm64, а також Windows x64 і arm64. Встановіть `git` окремо: кожен архів містить Node і ripgrep, тож окремо встановлювати Node не потрібно.
Оберіть один спосіб встановлення:
```sh
curl -fsSL https://mercury-cli.ai/install | sh # macOS та Linux (x64 і arm64)
irm https://mercury-cli.ai/install.ps1 | iex # Windows (x64 і arm64), у PowerShell 7
brew install Whq02/mercury/mercury # Homebrew: macOS та Linux x64
npm install -g mercury-tech-cli # npm; `bun install -g mercury-tech-cli` — той самий пакет
mise use -g npm:mercury-tech-cli # mise, через npm-пакет
```
Адреси для встановлення ведуть приблизний підрахунок запитів скриптів за джерелами та днями UTC (завершені встановлення не враховуються); лічильник не зберігає IP-адреси, рядок user-agent або cookie.
Відкрийте новий термінал або виконайте рядок `export PATH=…`, який виводить інсталятор оболонки, потім перевірте командою `mercury --version` і запустіть `mercury` із репозиторію, щоб почати [перший запуск](#перший-запуск). У PowerShell у Windows, а також після встановлення через Homebrew, npm, bun або mise команда `mercury` працює в тому самому терміналі.
Способи встановлення, оновлення та перевірка релізу
### Чим відрізняються способи встановлення
Інсталятори для shell та PowerShell завантажують найновіший реліз для вашої платформи, перевіряють його SHA-256 за `SHA256SUMS.txt`, розпаковують його і запускають власну команду архіву `mercury install`.
І формула Homebrew, і npm-пакет прив’язані до конкретного релізу та публікуються знову після тегу, тому можуть відставати від найновішого релізу. Команди Homebrew використовують повне ім’я tap `Whq02/mercury/mercury` (просто `mercury` у `homebrew-core` — інша програма). npm-пакет `mercury-tech-cli` — лаунчер, який завантажує закріплений за ним реліз; mise встановлює той самий пакет. `mercury install --uninstall` видаляє встановлений реліз і командну обгортку, але зберігає вашу конфігурацію та сесії (якщо ви встановлювали npm-лаунчер, виконайте також `npm uninstall -g mercury-tech-cli`).
Встановлення Mercury виконується в каталозі користувача й не потребує прав адміністратора. Команду встановлення можна безпечно запускати повторно.
### Шляхи встановлення
Версії релізів зберігаються в каталозі конфігурації за шляхом `~/.mercury/versions/` (`%USERPROFILE%\.mercury\versions` у Windows). Команда `mercury` встановлюється в `~/.local/bin` у macOS та Linux або в `%LOCALAPPDATA%\Mercury\bin` у Windows.
`mercury install` один раз додає каталог команди до PATH: захищений рядок у файлі запуску shell або запис у користувацький PATH Windows. Новий термінал підхоплює зміну автоматично.
### Оновлення
Використовуйте `mercury update` з будь-яким способом встановлення.
Для встановлення через інсталятор shell або PowerShell чи через `mercury install` команда оновлює Mercury на місці. `--check` перевіряє наявність оновлень, `--status` показує статус оновлення, а `--rollback` повертає попередню версію, яка лишається на диску.
Для Homebrew команда запитує підтвердження перед запуском `brew upgrade Whq02/mercury/mercury`. Типова відповідь — ні; введіть `y`, щоб підтвердити. Mercury показує вивід команди в міру його надходження і перевіряє встановлену версію після завершення. Використовуйте `--yes`, щоб пропустити запит у скриптах.
npm-лаунчер використовує ту саму структуру релізів, що й інсталятори, і передає кожен запуск встановленому релізу. Тому `mercury update` оновлює npm-встановлення на місці через власний канал оновлень Mercury. `npm update -g mercury-tech-cli` змінює лише реліз, який пакет встановлює під час першого запуску. Це стосується й mise.
`--check` читає той самий список релізів для кожного способу встановлення і підказує, як оновити ваше встановлення. Коли оновлення доступне, на головному екрані один раз у правому нижньому куті з’являється `vX.Y.Z available · mercury update`, а в чаті те саме сповіщення залишається до оновлення. Щоб приховати обидва, задайте `MERCURY_UPDATE_NOTICE=0`.
Запити встановлення та оновлення анонімно завантажують публічний список релізів і архіви; їх можна виконувати без облікового запису й токена. Якщо анонімний запит відхилено, Mercury звертається до GitHub CLI (`gh`), у якому виконано вхід.
Після оновлення Mercury перевіряє, чи команда у вашому PATH вказує на оновлене встановлення. Якщо має пріоритет інше встановлення або оновленої команди немає в PATH, Mercury пояснює проблему та спосіб її виправити. `mercury health` повідомляє про ту саму проблему.
### Перевірка релізу
Перед активацією релізу Mercury перевіряє його архів за `SHA256SUMS.txt`. Також він вимагає, щоб корисне навантаження було підписане ключем релізу Mercury зі списку довірених ключів, вбудованого в програму, перш ніж підготувати оновлення. Відхилений підпис залишає чинне встановлення без змін.
Використовуйте `--allow-unsigned`, щоб прийняти непідписане корисне навантаження. Mercury і далі відхиляє невідомі ключі підпису, пошкоджені блоки підпису та змінений вміст. Результат команди та її локальний запис показують, що ви дозволили непідписане корисне навантаження.
Архіви випусків підписані. Виконайте `mercury health`, щоб перевірити підпис установленого випуску.
Архів без підпису випуску позначається як непідписаний. Встановлення й оновлення відхиляють його, якщо не вказати `--allow-unsigned`.
[docs/TRUST.md](../TRUST.md) пояснює результати перевірки та те, як перевірити архів вручну. [docs/TERMINAL-RUNTIME.md](../TERMINAL-RUNTIME.md) описує перевірку під час запуску.
### Примітки щодо платформ
Архіви релізів існують для кожної платформи з наведеного вище переліку. Будь-яка інша машина збирається з вихідного коду.
Доступні архіви випусків для Intel Mac.
## Вимоги
Архіви релізів містять Node 24 LTS. Лаунчер, `mercury install` і `mercury update` використовують цей вбудований runtime; `git` — єдина окрема вимога для самого релізу.
Щоб зібрати з вихідного коду, потрібно:
- **Node 24 LTS** у підтримуваному діапазоні `>=24.20.0 <25`. `.node-version` фіксує патч-версію, яка використовується для збирання і входить до архівів релізів.
- **bun 1.4.4** для збирання. У релізи він не входить.
- **git**. У Windows запускайте PowerShell 7 всередині Windows Terminal або терміналу VS Code. Див. [docs/INSTALL-WINDOWS-FROM-SOURCE.md](../INSTALL-WINDOWS-FROM-SOURCE.md).
Мінімальна версія Node містить виправлення nodejs/node#56645. Нижче за 24.20.0 headless-команди `run`, які викликають інструмент, аварійно завершуються під час виходу у Windows.
Лаунчери обирають Node в такому порядку: явний бінарний файл `MERCURY_NODE`, вбудований runtime, потім сумісне встановлення Node у PATH. Якщо runtime немає, лаунчер повідомляє про помилку.
### Shell у Windows
Архіви релізів містять bash-сумісний рушій shell Mercury (`brush`). У Windows він типово обслуговує інструмент Bash: знаходить програму `.cmd` або `.bat`, наприклад `npm`, за іменем без розширення через PATHEXT, передає `%VAR%` і `^` пакетному файлу без змін, запускає програму, задану відносним шляхом після `cd`, і зберігає стан shell між викликами. Git for Windows `bash.exe` не потрібен; якщо його встановлено, `MERCURY_SHELL_ENGINE=system` або значення `system` у `/config` у пункті Shell engine запускає інструмент Bash лише через `bash.exe`.
Прочитайте рядок `shell` у перевірці стану, щоб дізнатися, яка оболонка активна і чому: вбудований рушій (типово у Windows або якщо його ввімкнено закріпленням чи налаштуванням) або Git Bash, коли рушій вимкнено або його пакет відсутній.
У macOS і Linux типово використовується системна оболонка. Щоб запускати інструмент Bash і там на вбудованому рушії зі збереженням стану shell, задайте `MERCURY_SHELL_ENGINE=brush` або оберіть `brush` у `/config` у пункті Shell engine.
Збірка з вихідного коду без пакета рушія або Git for Windows усе одно запускається, але інструмент Bash недоступний. Інструмент PowerShell лишається доступним, а діагностика `shell` пояснює, як відновити підтримку Bash.
## Збірка з вихідного коду
Mercury збирається за допомогою bun і працює на Node 24 LTS. Встановіть [вимоги до збирання з вихідного коду](#вимоги), зокрема bun 1.4.4:
```sh
curl -fsSL https://bun.com/install | bash -s -- bun-v1.4.4 # macOS та Linux
powershell -c "& ([scriptblock]::Create((irm https://bun.com/install.ps1))) -Version 1.4.4" # Windows, у PowerShell 7
bun --version # 1.4.4
```
Потім у клоні цього репозиторію:
```sh
bun run setup # один раз; bun install + вендорні пакети
bun run build.ts # записує dist/mercury.mjs + dist/manifest.json
node dist/mercury.mjs --version
node dist/mercury.mjs
node dist/mercury.mjs health --json
```
### Підтримка терміналу
Повноекранному інтерфейсу потрібен справжній TTY, але мінімального розміру термінала немає. Повна розкладка починається від 100 стовпців на 26 рядків; менші вікна використовують компактну розкладку.
Mercury використовує 24-бітний колір, якщо термінал оголошує підтримку через `COLORTERM=truecolor` або його розпізнано як iTerm2, Ghostty, WezTerm, Kitty, Windows Terminal або VS Code. Інші термінали використовують 256 кольорів, зокрема Terminal від Apple у macOS 15 і старіших.
Рядок Terminal color у перевірці стану показує визначену глибину кольору та причину. Задайте `MERCURY_TRUECOLOR=1` для термінала, який підтримує справжній колір, але не оголошує цього, або `MERCURY_TRUECOLOR=0`, щоб примусово використовувати 256 кольорів.
### Додаткові компоненти
`setup` завантажує вбудовані пакети можливостей: pyright, debugpy, js-debug, додаткові граматики, Node runtime для платформи та brush. Якщо завантаження не вдалося, цей пакет пропускається, а збірка та відповідні інструменти повідомляють про відсутній компонент. Команда `bun install` сама по собі дає збірку без цих пакетів.
Щоб зібрати підтримку голосу, запустіть `setup` із встановленим Rust. Це збирає `native/voice`. Додайте cmake, щоб зібрати також `native/whisper`. Із встановленим Rust `setup` також збирає аддон драйвера робочого столу (`native/desktop`), через який працює інструмент `Computer`. За наявності Rust `setup` збирає й локальний аддон ембедингів (`native/embed`, `bun run scripts/vendor/build-embed.ts`) і завантажує модель BGE на 118 МБ (`bun run scripts/vendor/fetch-embed-models.ts --default`); без cargo пакет пропускається, setup про це повідомляє, а пошук у пам’яті Mneme працює лише за збігом слів. Кожен архів релізу містить пакет ембедингів, зібраний для його платформи; у Linux і Windows обчислення виконує векторизоване ядро, тож Recall за змістом триває приблизно десяту частку секунди (кілька сотих на macOS, де використовується Accelerate). Якщо в нативній збірці бракує інструментів, setup її пропускає, а перевірка стану повідомляє про відсутній аддон. Рушій shell для Windows теж збирається на вашій машині, бо в upstream немає бінарного файлу для Windows.
Див. [Shell у Windows](#shell-у-windows) і [docs/TERMINAL-RUNTIME.md](../TERMINAL-RUNTIME.md) про рушій shell `brush`.
Збірка пише лише в `dist/`. Конфігурація й сесії зберігаються в `~/.mercury` або в каталозі, заданому `MERCURY_CONFIG_DIR`, і створюються під час першого запуску. У Windows запускайте `node dist\mercury.mjs` напряму.
### Встановлення збірки з вихідного коду як команди
`scripts/ops/deploy-runtime.sh` публікує збірку з чистого дерева в нову папку `/runtime/builds/` і спрямовує на неї `runtime/current` (`runtime/dist` — давніша назва того самого посилання). `scripts/ops/deploy-launcher.sh` встановлює лаунчер у `/bin/mercury`. Додайте цей каталог до PATH; для zsh:
```sh
echo 'export PATH="$HOME/.mercury/bin:$PATH"' >> ~/.zshrc
```
Лаунчер завершується помилкою, якщо runtime відсутній. Він не переключається на іншу збірку. Вибір Node відбувається в порядку з розділу [Вимоги](#вимоги). Для встановлення релізу виконайте `mercury install` або `mercury update`: вони не змінюють робочі копії вихідного коду; див. [Оновлення](#оновлення).
[AGENTS.md](../../AGENTS.md) — короткий посібник зі збирання та запуску. [BUILD-NOTES.md](../../BUILD-NOTES.md) докладніше описує збирання.
## Перший запуск
Під час першого інтерактивного запуску оберіть оформлення, потім увійдіть до провайдера. Екран показує попередній перегляд змін теми, поки ви переглядаєте варіанти. Типова тема — True Black; інші варіанти — тема oasis dark і тема Black and white, яка не фарбує взагалі: використовуються власні колір тексту й фон термінала, тож так Mercury виглядає в терміналі без кольору. Змінити це можна пізніше командою `/appearance`.
Також можна вибрати «sign in later», щоб оглянути програму без підключення облікового запису. Якщо ключ провайдера у вашому середовищі вже виконує вхід для провайдера, крок входу не пропонується. Далі крок Guardrails нагадує перевіряти правки й команди Mercury, а також те, що прочитане може містити інструкції для моделі. У терміналі, який Mercury вміє налаштовувати (Terminal.app, родина VS Code, Alacritty, Zed), крок Terminal keys може налаштувати комбінації клавіш для нового рядка в налаштуваннях самого терміналу (у Terminal.app на macOS він призначає `Option+Enter` для нового рядка й вимикає звуковий сигнал термінала в усіх профілях, що набуває чинності після перезапуску Terminal.app; у родині VS Code, Alacritty та Zed записує `Shift+Enter` для нового рядка). Крок вимкнений, доки ви його не оберете, і резервна копія зберігається.
Далі Mercury запитує, чи довіряєте ви відкритій папці. Нічого, що запитує конфігурація робочого простору, не виконується, доки ви не надасте цієї довіри. Довіра поширюється на весь репозиторій; відмова завершує роботу Mercury. Див. [docs/TRUST.md](../TRUST.md).
Звичайний інтерактивний запуск відкриває головний екран. У ньому десять пунктів меню; пункт Continue Last Session з’являється лише після того, як з’явиться історія сесій:
- **New Session in \** запускає нову сесію в поточній папці.
- **Continue Last Session** повертає до вашого останнього чату.
- **Boot Menu** налаштовує майбутні сесії, зокрема motion і crewmates.
- **MCPs & Skills** обирає, що завантажуватиме наступна сесія. Див. [docs/KIT.md](../KIT.md).
- **Agents** створює та редагує агентів.
- **Health Check** перевіряє встановлення.
- **Saturn Scheduler** планує сесії. Див. [docs/SATURN.md](../SATURN.md).
- **Logins** підключає облікові записи провайдерів.
- **Session Concourse** відкриває список сесій поточного проєкту.
- **Sessions · Projects** дає змогу обрати сесію або репозиторій.
Пункти меню відкриваються поверх головного екрана, а `Esc` повертає до обраного пункту. Список сесій відкривається на окремому екрані, його також можна відкрити через `Shift+→`. Аргумент із промптом, `--continue` або `--resume` одразу переводить до чату.
### Motion та crewmates
У розділі Performance меню Boot Menu є налаштування Motion: `auto`, `full`, `reduced` або `off`. Воно керує анімацією простою в інтерфейсі й доступне також у `/config`.
У розділі Agents перемикач Crewmates визначає, чи отримують нові сесії інструмент Crewmate. Вимкнення перемикача прибирає цей інструмент; спроби запустити роботу цього типу повертають те саме пояснення. У сесії `/crewmates on|off` змінює це налаштування з наступного ходу.
## Щоденний цикл: Session Concourse, git worktrees і crewmates
### Запуск сесії та ізоляція worktrees
Натисніть `Enter` на пункті New Session, щоб створити сесію в поточній папці з типовою моделлю. Mercury відкриває чат і водночас додає його до списку сесій. Позаду меню Mercury тримає готовий процес, щоб скоротити роботу під час запуску.
Запуск іншої сесії не зупиняє попередню: можна залишити завдання виконуватися й працювати деінде. Запустіть із `--worktree [name]` (або попросіть у чаті `worktree`, щоб виконати `EnterWorktree`), щоб сесія отримала власну гілку й робочу копію в `.mercury/worktrees/`. Паралельні crewmates також можуть працювати в ізольованих worktrees і узгоджувати спільні файли через оренду файлів проєкту; див. [Що всередині](#що-всередині-rag-память-mneme-lsp-ast-для-57-мов-налагоджувач-dap-веб-пошук-і-мости) і [docs/CREW.md](../CREW.md).
### Робота в чаті
Опишіть завдання звичайними словами. Агент читає, редагує, запускає й перевіряє код у межах обраного режиму дозволів. Виклики інструментів з’являються під час виконання — компактними картками або з повним виводом. Вигляд обирають у `/config` у пункті Tool output; налаштування зберігається для наступних запусків.
Використовуйте `/model` і `/effort`, щоб налаштувати сесію. `/permissions` визначає, що може виконуватися без підтвердження, а що має спершу запитати.
Переглядайте зміни через `/diff` — за джерелом, файлом і фрагментом (hunk). `! ` виконує shell-команду прямо в чаті з живим виводом останніх рядків. `/runs` показує запущені shell-процеси та crewmates (`/tasks` відкриває ту саму дошку), а `/crewmates` відкриває живий вигляд Crew. Між ходами `/clear` зберігає поточний чат і відкриває нову сесію, а `/restart` переносить чат на щойно встановлену збірку Mercury. `/title` дає чату назву, а `/help` виводить список доступних команд.
### Перехід між екранами
`Shift+←` і `Shift+→` перемикають між екранами, доступними зараз. Під час нового запуску доступні головний екран і список сесій. Екран чату додається, коли сесія отримує фокус, і зникає, коли закривається останній чат. Підказки клавіш показують лише доступні переходи.
Закриття всіх чатів повертає вас на головний екран. Використовуйте `--chat`, щоб залишити лише головний екран і чат, без списку сесій. `--concourse-off` зберігає цей вибір для майбутніх запусків; `--concourse-on` або `/config` знову вмикає його.
### Керування сесіями в Session Concourse
Відкрийте список сесій командою `/concourse` або через `Shift+→` з головного екрана. Спершу показуються запущені сесії поточного проєкту, далі збережені чати, які не запущені, — від найновіших до старих.
Кожна запущена сесія має комірку NOW з її поточною активністю. Оберіть рядок і натисніть `Enter`, щоб повернутися до чату, поки інші сесії продовжують працювати. Сесія, що впала, лишається у списку сесій як NEEDS YOU з причиною, доки ви її не звільните.
[docs/SESSIONS.md](../SESSIONS.md) описує життєвий цикл сесії.
## Провайдери та моделі: входи, `/localsetup` і `/llmhost`
Щоб підключити провайдера, використовуйте `/logins`. Команда відкриває той самий каталог входів, що й під час налаштування. Далі підключеними слотами провайдерів керує `/accounts`.
- **OpenAI:** підписка ChatGPT або ключ API.
- **Anthropic:** підписка Claude, вхід у Console або ключ API.
- **OpenRouter:** доступ до каталогу через OAuth або ключ API; запити до моделей забороняють збір даних і завжди вимагають, щоб провайдер підтримував усі параметри запиту. `/config → OpenRouter routing policy` задає варіанти резервного маршруту та режиму нульового зберігання даних; оберіть open, щоб пом’якшити політику й передати маршрутизацію OpenRouter.
- **Google Gemini:** Sign in with Google, ключ API або власний клієнт OAuth. Sign in with Google запускає Gemini за квотою тарифу, наявного в обліковому записі Google (безкоштовний обліковий запис, Google AI Pro або Google AI Ultra), через власний клієнт Antigravity від Google: промпт, схеми інструментів і результати інструментів надсилаються на кінцеву точку Code Assist від Google під цим клієнтом і обліковим записом, у який виконано вхід, а `/model` показує список моделей, які Google надає обліковому запису. Ключ API або власний клієнт OAuth натомість виставляють рахунок проєкту Cloud.
- **Hugging Face:** вхід за кодом пристрою або токен Hub.
- **Kimi (Moonshot):** вхід за кодом пристрою або ключ API.
- **GLM (Z.AI):** ключ підписки GLM Coding Plan або загальний ключ API з оплатою за використання. `/logins zai` зберігає будь-який із них і фіксує тариф; `ZAI_API_KEY` також працює, а `ZAI_KEY_PLAN=coding|general` називає тариф (якщо не задано, Mercury читає його зі списку моделей самого ключа).
- **DeepSeek:** ключ API з платформи DeepSeek (`/logins deepseek` або `DEEPSEEK_API_KEY`).
- **xAI (Grok):** увійдіть за своєю підпискою Grok (SuperGrok / X Premium) або вставте ключ API через `/logins xai`.
- **Meta (Muse):** Sign in with Meta (підписка Muse Code, код пристрою в браузері) або ключ Model API з оплатою за використання. Sign in with Meta обмінює код пристрою через OIDC-кінцеві точки Meta (`https://auth.meta.com/oidc/device/authorization/` і `/oidc/device/token/`) під публічним client id Muse Code, один раз надсилає отриманий токен облікового запису на `https://api.meta.ai/muse-code/key`, щоб випустити API-ключ підписки (а також під час обмежених читань `/usage` для рівня тарифу та вікон використання), і на кожен запит до моделі надсилає на `https://api.meta.ai/v1` лише випущений ключ. Вставлений ключ Model API або `MODEL_API_KEY` / `META_API_KEY` тарифікується за використанням.
- **Qwen:** ключ QwenCloud (Token Plan або оплата за використання) чи ключ Alibaba Cloud Model Studio (оплата за використання, Token Plan або Coding Plan), який перевіряється на власній кінцевій точці перед збереженням; ключ тарифу виводить моделі цього тарифу, першою — Qwen3.8 Max.
- **MiniMax:** ключ Open Platform або ключ підписки M Plan.
- **Together AI** і **Cohere:** ключ API.
- **Groq**, **Cerebras** і **Fireworks AI:** ключ API; ключ будь-якої родини також може надходити з команди, заданої в `credentials.keyCommands.`.
Mistral, Nous Portal і OpenCode Zen також підключаються через `/logins`: усього 22 родин провайдерів із входом. Локальні сервери моделей (Ollama, LM Studio, vLLM і llama.cpp) та власні кінцеві точки, сумісні з OpenAI, працюють без входу до провайдера. Виконайте `/localsetup`, щоб встановити чи запустити Ollama, завантажити модель, яка вміщується в пам’ять, задати вікно контексту або підключити запущений сервер LM Studio, vLLM чи llama.cpp ([docs/LOCAL-SETUP.md](../LOCAL-SETUP.md)). Кожен провайдер використовує власний протокол, облікові дані та обробку помилок, а запити ніколи не переходять до іншого провайдера. Див. [docs/ENGINES.md](../ENGINES.md).
`/llmhost` показує моделі, які можна розмістити, і де кожну з них можна запустити просто зараз: на GPU, орендованому у Runpod, Vast.ai або Lambda, на вашому комп’ютері чи збереженому SSH-комп’ютері (`mercury host`), або на наявному сервері моделей. На сторінці кожної моделі видно варіанти квантизації, розподіл пам’яті GPU між паралельними розмовами (`conversations × context`) і типовий рівень міркувань (його для кожного запиту змінює `/effort`). Оренда GPU потребує явного підтвердження погодинної ціни, а налаштування триває у фоні, якщо закрити спливне вікно. На Runpod ви також можете налаштувати якість, розподіл контексту та міркування до оренди або на вже запущеному поді (`Tune`), тримати ваги на томі зі швидким завантаженням і задати перевірку наявності GPU кожні 5 секунд. Оренди Vast.ai і Lambda з’явилися у 1.0.0-beta.40 і перевірені за опублікованими API постачальників на фікстурах (живі запуски оренди не виконувалися). Див. [docs/LLM-HOST.md](../LLM-HOST.md).
Нові сесії використовують провайдера, якого ви підключили останнім, і найновішу модель, доступну цьому обліковому запису. Моделі, яких обліковий запис не може використовувати, пропускаються. Якщо в цього провайдера немає придатної моделі, Mercury перевіряє наступного за часом підключення провайдера. Цей вибір відбувається на початку сесії; помилка запиту в наявній сесії лишається за її провайдером.
`/model` пояснює вибір. Слово родини вибирає найновішу модель цієї родини: `/model grok`, `/model deepseek`, `/model kimi` або `/model glm`. Якщо жоден провайдер не підключений, головний екран і `/model` направляють до `/logins`. `/defaultprovider` дозволяє явно зробити провайдера найостаннішим вибором.
Доступ до провайдерів і далі залежить від власних умов провайдера та його доступності. Ліцензія Mercury їх не замінює.
## Headless CLI: `mercury run`, Docker і JSON-RPC-раннер
Та сама збірка працює без інтерактивного інтерфейсу. `node dist/mercury.mjs --help` перелічує всі прапорці.
`mercury run ""` запускає промпт без термінального інтерфейсу:
```sh
mercury run "Summarise this repository." --format text
mercury run "Summarise this repository." --format json
mercury run "Summarise this repository." --format rows
```
- `text` виводить відповідь; причина невдалого ходу потрапляє в stderr.
- `json` виводить останній рядок `outcome` як один JSON-об’єкт.
- `rows` виводить по одному JSON-об’єкту на рядок: спочатку `session`, потім `turn` та його рядки `text`, `reasoning`, `tool_call`, `tool_result` і `step`, а завершує все рядок `outcome`. Очікування, прогрес інструментів, фонові завдання та сповіщення мають власні рядки. Кожен рядок містить `seq`, `timestamp` і `session_id`; рядки всередині ходу також містять його номер `turn`. `seq` нумерує потік цього запуску з 1; `turn` рахує ходи сесії, тому запуск, що продовжує збережену розмову (`-c`, `-r`, `--fork`), нумерує свій хід після вже наявних у ній ходів, а його рядок `session` називає розмову, яку продовжує, у полі `resume_of`.
Типи рядків виводу за їх полем `type`:
- `session`: відкривальний рядок: `version`, `build` (перші дванадцять шістнадцяткових символів дерева, з якого зібрано бандл, як їх виводить `mercury daemon status`; відсутній, якщо поруч із бандлом немає маніфесту), `resume_of` (у продовженому запуску — ідентифікатор сесії розмови, яка продовжується; збігається з `session_id`, якщо запуск не був форком), `cwd`, `model`, `mode`, а також `tools`, `mcp_servers`, `commands`, `agents`, `skills` і `extensions`, які є в сесії, і `tools_withheld` (присутній, коли правило заборони приховує інструмент за його коротким іменем: у кожному записі — `tool`, `rule` і `source`).
- `turn`: хід, що має стан `started` або `waiting`, із його `turn_id`; `model`, `message_ids` і кількість `agents`, коли вони відомі.
- `text`: завершений текстовий блок: `message_id`, `block`, `text` і його `phase` (`commentary` або `final_answer`).
- `reasoning`: завершений блок міркувань: `message_id`, `block`, `text` або `redacted: true`.
- `tool_call`: виклик інструмента: `call_id`, `tool`, `input`, разом із його `message_id` і `block`.
- `tool_result`: результат виклику: `call_id`, `status` (`ok`, `error`, `aborted` або `refused`) і `output`. Виклик, який модель оформила настільки погано, що його відхилили ще до виконання (невідомий інструмент, аргументи, що не є коректним JSON або не відповідають схемі інструмента), усе одно отримує свою пару: рядок `tool_call` з аргументами в тому вигляді, в якому вони надійшли (`{}`, якщо вони не були об’єктом), і рядок `tool_result` зі статусом `refused`, де `output` містить причину; далі йде виправлювальне `notice`. Такий виклик ніколи не виконувався і не є відмовою.
- `tool_update`: прогрес інструмента, що виконується: `call_id`, `tick`, `source` (`shell`, `powershell`, `mcp` або `eval`) і ті з полів `line`, `elapsed_s`, `lines`, `bytes`, `budget_ms`, `progress` і `total`, які повідомляє виклик. Виклик shell або PowerShell оновлюється в міру надходження виводу (команда, що нічого не виводить, не оновлюється), виклик MCP — коли його сервер повідомляє про прогрес, а виклик Eval — поки виконується його комірка; жоден інший інструмент не оновлюється; виклик Browser або Crewmate мовчить до отримання результату.
- `step`: один виклик моделі головного потоку: `message_id`, `model`, `usage` і `stop`, якщо модель повідомила, чому зупинилася.
- `outcome`: результат ходу, описаний нижче.
- `close`: нотатка, яку залишають для наступної сесії під час закриття: `state` (`stored`, `skipped` або `none`), `note_chars` і `usage` викликів моделі, які її записали, — щоб читач, який підсумовує витрати усіх рядків, отримав підсумок із результату ходу. Коли промпт передано аргументом, нотатку запитують усередині останнього ходу, і `close` іде перед `outcome` цього ходу; з `--input rows` вона йде за останнім `outcome`, коли stdin закривається.
- `wait`: очікування моделі: `state` (`first_byte`, `retry`, `silence`, `loading` або `done`) з показниками, які несе цей стан, як-от `since_ms`, `attempt` і `of`, `delay_ms`, `reason` та `http_status`.
- `heartbeat`: потік моделі подав ознаку життя щонайменше через секунду без розпізнаної події: надійшли байти, які не дали рядка. Рядок більше нічого не містить і з’являється не частіше ніж раз на секунду; частота залежить від форми потокової передачі провайдера, тож потік, який ніколи не робить пауз між подіями, їх не видає.
- `compaction`: стискання контексту — `started`, `progress` або `ended`: `trigger` (`manual`, `auto` або `overflow`), `stage`, `fill`, `summary_tokens` і наприкінці `exit` (`landed`, `cancelled` або `failed`).
- `mode`: режим дозволів змінився: `mode`.
- `rate_limit`: стан ліміту провайдера: `status` (`allowed`, `warning` або `rejected`), `window`, `resets_at`, `utilization` і поля перевитрати.
- `task`: фонове завдання — `started`, `progress` або `ended`: `task_id`, `task_type`, `description`, `usage`, `summary`, `status` (`completed`, `failed` або `stopped`) і `output_file`, щойно вони стають відомими.
- `notice`: `warning` або `error` для читача: `text` і `code`, наприклад `input_refused`.
- `command_output`: вивід слеш-команди, який не дійшов до моделі: `command` і `text`.
- `mission_updated`: журнал завдань сесії змінився; прочитайте його знову.
- `samples_updated`: зразки сесії змінилися; прочитайте їх знову.
`--partial` з `--format rows` додає рядки `block_start`, `text_delta`, `reasoning_delta`, `tool_input_delta` і `retracted`. Дельти належать до `message_id` і `block`; рядок `retracted` скасовує дельти цього повідомлення. Завершений рядок тексту або інструмента містить повне значення.
Результат ходу містить `schema`, `turn_id`, `status`, `steps`, `wall_ms`, `usage`, `models` і `denials`, а також `answer` у разі завершення та `error` (`message`, `class`, необов’язковий `detail`) у разі збою. `stop`, `api_ms`, `cost_usd`, запитаний вивід `structured` і `notices` додаються, коли вони доступні. `wall_ms` — час ходу від початку до кінця. `api_ms` — сума тривалостей кожного запиту до моделі, зробленого в ході (включно з повторами та запитами crewmates, що йшли паралельно з головним потоком), тому він може перевищувати `wall_ms`, коли запити перекривалися. `cost_usd` — вартість ходу в доларах США за запитами з відомою ціною, незалежно від статусу: запит, який Mercury не може оцінити (немає тарифу у файлі, у відповіді не вказано вартості), нічого до неї не додає і лишає свою модель у `models` без власного `cost_usd`; поле відсутнє, лише якщо в ході нічого не оцінено. За входу за підпискою Claude запити Anthropic не мають ціни в доларах, тож ні вони, ні рядок не містять `cost_usd`; витрати при цьому зберігаються. У витратах указано `input_tokens` (включно з кешованими токенами), `cached_input_tokens`, `cache_write_input_tokens`, `output_tokens` і, коли вони є, `reasoning_output_tokens`, підсумовані за головним потоком та crewmates. `models` розбиває використання токенів за моделями. `steps` рахує лише виклики моделі головного агента; виклики моделі, зроблені crewmates, з’являються як власні рядки `step` з позначкою `parent_call_id`.
Статус — один із таких: `completed`, `blocked`, `refused`, `failed`, `interrupted`, `turn_limit`, `budget_limit`, `time_limit`, `schema_unmet` або `loop_stopped`. Запуск із `--max-time` (у секундах або `10m`, `1h`) завершується зі статусом `time_limit` на наступному кроці, щойно минає час; виклик моделі чи раунд інструментів, що тривають, не переривається. Завершений запуск виходить із кодом 0, інші результати — із кодом 1, а помилка використання — із кодом 2. SIGINT і SIGTERM завершують із кодами 130 і 143 після того, як результат перерваного ходу записано. Відхилений виклик інструмента перелічується в `denials`. Якщо відмова була запитом, на який ніхто не зміг відповісти (запуск без хоста в режимі, що запитує підтвердження, `--mode dontAsk`, або запит хоста, який сплив), і жоден наступний виклик інструмента в ході не виконався успішно, запуск отримує статус `blocked`: відповідь зберігається, `error` називає інструмент і спосіб продовжити (`--allowed-tools`, інший `--mode` або хост, який відповідає на запити), а запуск завершується з кодом 1. Якщо наступний виклик інструмента в тому самому ході виконується успішно, хід відновлюється, завершується статусом `completed` (код 0) і видає попереджувальне `notice` (`" was not approved; the run continued with other tools."`). Відмова, на яку ви відповіли (через правило заборони, хук або хост, який сказав «ні»), лишає завершений хід завершеним. Виклик `AskUserQuestion`, на який ніхто не відповів, також завершує запуск статусом `blocked`, а питання цитується в `error`. Mercury визначає результат за записаними запитами запуску, а не за текстом відповіді, тож питання, яке є лише у відповіді, дає статус `completed`. Невідома слеш-команда отримує статус `refused` з тим самим реченням, що й інтерактивний екран (`Unknown command: /name · /help lists commands`), і завершується з кодом 1.
`--input rows` вимагає `--format rows` і читає по одному вхідному об’єкту в рядку:
```sh
printf '%s\n' '{"type":"prompt","content":"Summarise this repository."}' | mercury run --input rows --format rows
```
Типи вхідних даних: `prompt` із `content` (текст або блоки text/image), `shell` із `command` і `note` із `to` (ідентифікатор агента) та `content`. Кожен приймає необов’язковий `id`; рядки prompt і shell також приймають `priority` (`now`, `next` або `later`), `sent_at` і `origin`. Відхилена форма вхідних даних створює `notice` із кодом `input_refused`; некоректний JSON завершує запуск. Ці рядки несуть лише вхідні дані; відповіді на запити дозволів передаються протоколом раннера, описаним нижче.
Використовуйте `mercury run -` або передайте текст у `mercury run` через конвеєр, щоб прочитати весь промпт зі stdin. Поряд з аргументом-промптом текст із конвеєра додається як відокремлений контекст: конвеєр читається, доки не закриється або не замовкне на одну секунду, тож потік, який безперервно надходить, читається до кінця, а конвеєр, що лишився відкритим і мовчить, не затримує запуск. Без промпту, коли stdin — термінал, `run` виводить довідку з використання і завершується з кодом 2.
`--mode ` вибирає режим дозволів. `--sovereign` запускає без запитів дозволів, а `--allow-sovereign` робить цей режим доступним для подальшого перемикання. Політика дозволів і правила заборони діють як і раніше. Користувач root, який переходить у режим sovereign, отримує одне сповіщення в stderr; запуск триває.
Використовуйте `-c`, щоб продовжити останню розмову, `-r`, щоб відновити за ID, назвою або через вибір, `-w`, щоб запустити в керованому worktree, і `--lean` для мінімальної сесії. У `run` немає хоста, який відповідав би на запити дозволів: його правила дозволів і режим визначають, що може виконуватися, а виклик, якому потрібне підтвердження, відхиляється.
### Headless-образ
`Dockerfile` у корені репозиторію збирає образ Linux x64 для CI та серверів. Його точка входу — `mercury`, а типова команда — `run`, тож образ виконує один промпт над змонтованим деревом і завершується з кодом цього запуску:
```sh
docker build -t mercury .
docker run --rm -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" -v "$PWD":/work mercury run "Summarise this repository." --format text
docker run --rm mercury --version
```
В образі є бандл, його Node 24 runtime (у `PATH`), вбудовані інструменти пошуку, shell, налагоджувача, мов і зображень, `git` та сховище сертифікатів; початкового екрана й процедури входу немає. Образ працює від непривілейованого користувача `mercury`, а його каталог конфігурації міститься всередині контейнера (`MERCURY_CONFIG_DIR`), `/work` — робочий каталог. Колір і миша визначаються власним розпізнаванням терміналу, а `--user 0` запускає від root із тим самим сповіщенням sovereign, що описане вище.
Ключ провайдера передається як змінна середовища, у тих самих написаннях, які продукт читає скрізь: `ANTHROPIC_API_KEY` або `ANTHROPIC_AUTH_TOKEN`, `OPENAI_API_KEY`, `GEMINI_API_KEY` або `GOOGLE_API_KEY`, `XAI_API_KEY` (і `XAI_MANAGEMENT_API_KEY` для його лічильника використання), `DEEPSEEK_API_KEY`, `MOONSHOT_API_KEY`, `ZAI_API_KEY`, `OPENROUTER_API_KEY`, `HF_TOKEN`, `MISTRAL_API_KEY` (і `MISTRAL_ADMIN_API_KEY` для лічильника організації), `NOUS_API_KEY`, `OPENCODE_API_KEY`, `MINIMAX_API_KEY`, `TOGETHER_API_KEY` або `TOGETHER_AI_API_KEY`, `COHERE_API_KEY` або `CO_API_KEY`, `GROQ_API_KEY`, `CEREBRAS_API_KEY`, `FIREWORKS_API_KEY`, `DASHSCOPE_API_KEY`, `MODEL_API_KEY` або `META_API_KEY`, `MERCURY_COMPAT_API_KEY` для власної кінцевої точки, сумісної з OpenAI, і `MERCURY_LOCAL_API_KEY` для локального сервера. Без ключа запуск одним рядком повідомляє про відмову і завершується з кодом 1. `docker run -i … mercury run -` читає промпт зі stdin.
### Розміщення сесії
`mercury runner` обслуговує сесію для хоста через stdio: JSON-RPC 2.0, одне повідомлення в рядку. Хост першим надсилає `initialize` і чекає відповіді, перш ніж передавати роботу:
```json
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocol":1,"host":{"name":"my-host","version":"1.0.0"},"capabilities":{"holds_asks":true,"elicitation":false,"partial_rows":false}}}
```
Ім’я та версія хоста передаються в `host`; `capabilities` оголошує `holds_asks`, `elicitation` і `partial_rows`. Кожен `id` запиту — додатне ціле число: запит з будь-яким іншим `id` отримує відповідь `-32600` з `id: null`, тож нумеруйте запити від 1.
`queue/add` приймає той самий об’єкт промпту, shell або note, що й вхідні рядки вище. Вивід надходить у сповіщеннях `row`. `session/facts` читає стан сесії; `session/set_mode` змінює режим дозволів одразу; `session/set_model` і `session/set_effort` змінюють модель та рівень effort, а зміна, зроблена під час ходу, утримується до його завершення: відповідь містить `at: "turn_end"`, потім `session/applied` повідомляє про неї. `turn/interrupt` зупиняє хід; закрийте stdin, щоб завершити сесію.
Запити дозволів надходять як `permission/request` із `kind: "tool"` або `kind: "network"`. Хост відповідає `outcome: "allow"` або `outcome: "deny"`; allow може містити змінені `input` і правила `rules`. Відкликаний запит надсилає `$/cancel_request` з його `request_id`. `holds_asks` передає хосту володіння таймером запиту. Питання MCP використовує `elicitation/request` лише тоді, коли хост оголошує `elicitation`; інакше на нього відповідають `cancel`.
Невідомий метод отримує відповідь `-32601`, неправильні параметри — `-32602`, `id`, що не є додатним цілим, — `-32600`, а запит до ініціалізації — `-32002`. Відмова за правилом — `-32010`: речення в `error.message` і причина в `error.data.kind`, наприклад `mode`, `model`, `effort` або `claim`. Раннер відповідає на некоректний рядок `-32700` і продовжує роботу; три некоректні рядки поспіль його завершують.
### Інші команди
Доступні команди включають:
- **`mercury health`**: діагностичний звіт, він же сертифікат стану. `--json` повертає повний звіт, `--deep` запускає глибоку інвентаризацію, а `--fix` виконує керовані виправлення.
- **`mercury auth login []|list|status []|logout []|mint`**: вхід (`login []`), перелік родин провайдерів (`list`), перевірка, чи виконано вхід в обліковий запис (`status []`), вихід (`logout []`) або випуск довгоживучого токена Anthropic (`mint`).
- **`mercury models [--json]`**: виводить моделі, доступні підключеним обліковим записам (ті самі відомості, що й `mercury://models`).
- **`mercury mcp`**: керування серверами MCP за допомогою `add`, `import`, `list`, `get`, `remove`, `trust-reset` і `serve`.
- **`mercury extensions`**: встановлення розширень і керування їхніми джерелами. Дії: `list`, `sources`, `add`, `remove`, `refresh`, `install`, `trust`, `enable`, `disable`, `update`, `uninstall`, `fence`, `unfence`, `inspect` і `scaffold`.
- **`mercury roster`**: виводить інвентар агентів.
- **`mercury usage`**: виводить компактний рядок показників, який показує екран `/usage`; `--json` виводить повне показання: вікна кожного підключеного провайдера з використаним обсягом і часом скидання, показники та кредити, які він заявив, кожен із джерелом і давністю, а також витрати сесії за моделями, зчитані так, як їх зчитує екран (зчитувач кожного підключеного провайдера опитується один раз, як під час відкриття).
- **`mercury daemon run|status|stop|restart`**: запускає, перевіряє, зупиняє або перезапускає фоновий демон. Його сесійні слоти — це дочірні процеси `mercury runner`; демон надсилає їм промпти та обробляє їхні запити дозволів.
- **`mercury sessions list`** (також просто `mercury sessions`): виводить збережені сесії цього проєкту, від найновіших: ідентифікатор, час останнього запису, розмір, `live`, коли демон зараз обслуговує сесію, а також її назву або перший промпт; `--all` читає всі проєкти, `--limit ` обмежує список. Ідентифікатор — це те, що повторно відкриває `mercury --resume `, і те, що видаляє `sessions delete`.
- **`mercury sessions delete `**: навмисно видаляє одну збережену сесію — її транскрипт і записи, що лежать поруч (квитанції, знімок для відновлення), — після запитання; `--yes` пропускає запитання для скриптів. Сесію, яку демон зараз обслуговує, відхиляють, а на невідомий ідентифікатор виводиться підказка на список (`/sessions` у Mercury). Збережені сесії інакше ніколи не видаляються самі.
- **`mercury host [status|start|stop|restart|logs|uninstall|add|recipes]`**: запускає локальний або SSH-комп’ютер як сервер моделей для всіх сесій, що використовують спільний каталог конфігурації (`compat/box-/`), із перевіреним локальним сховищем ваг або підтвердженим завантаженням. Див. [docs/LLM-HOST.md](../LLM-HOST.md).
- **`mercury lsp list`** і **`mercury lsp install `**: каталог мовних серверів, де кожен сервер або встановлений (з бінарним файлом), або відсутній (із вказівкою, як його встановити); `install` показує спосіб встановлення сервера, запитує підтвердження, виконує саме його (`--yes` пропускає запитання для скриптів) і повідомляє, куди потрапив бінарний файл. Невідомий сервер відхиляється з переліком. Mercury ніколи не встановлює мовний сервер сам; відкриття файлу запускає лише вже встановлений сервер.
- **`mercury acp`**: обслуговує редактор через Agent Client Protocol, з дочірнім процесом runner для кожної сесії. `mercury bridge install` встановлює розширення VS Code; `mercury bridge status` перевіряє його; `mercury bridge uninstall` видаляє його.
- **`mercury godot run|check|capture|frames|profile|tour|jobs|cancel|result`**: керує завданнями рушія для проєкту Godot у поточному каталозі. Mercury запускає набори тестів на власних headless-воркерах із заморожених копій проєкту. Сервіс містить шлюз компіляції, захоплення, статистику кадрів, завершені профілі, доступ до черги завдань, скасування та результати за ID. Див. [docs/VULCAN-GODOT-TOOLS.md](../VULCAN-GODOT-TOOLS.md).
- **`mercury image `**: показує зображення в терміналі.
- **`mercury install`** і **`mercury update`** (псевдонім `upgrade`): встановлення або оновлення архівів релізів; з `--json` документ виводиться в stdout незалежно від вердикту, а код виходу показує, чи завершилася команда помилкою. Див. [Встановлення](#встановлення).
- **`mercury version`** і **`mercury help [command]`**: виводять рядок версії або сторінку довідки, те саме, що `--version` і `--help`; жодна з них не запускає сесію.
## Що всередині: RAG-пам’ять Mneme, LSP, AST для 57 мов, налагоджувач DAP, веб-пошук і мости
- **Гібридна RAG-пам’ять проєкту Mneme.** Mneme увімкнено за замовчуванням: вона зберігає факти кожного проєкту в простих markdown-сторінках за темами (`Retain`, `Recall`, `Reflect`, `Correct`). Recall поєднує семантичну модель ембедингів BGE на 118 МБ, що працює на пристрої (`bge-base-en-v1.5` `q8_0`, MIT, входить до кожного архіву релізу, зібрана для його платформи; див. [Додаткові компоненти](#додаткові-компоненти)), з пошуком слів BM25 зі стемінгом, урахуванням давності та відстеженням цитувань через reciprocal rank fusion (`k = 60`). Закріплені правила (`pin: true`) завантажуються дослівно на закріплену полицю і змінюються лише за вашим словом. На початку сесії Mercury оцінює незакріплені факти та попередні нотатки за вашою поточною гілкою, нещодавно зміненими файлами та нотаткою передачі попередньої сесії в межах окремого ліміту запуску (`memory.startLimit`, типово 4 000 символів). Перевірки суперечностей під час запису перехоплюють зміну полярності, заперечення та переставлені числа до того, як зберігається суперечливий факт. Наприкінці кожна сесія записує власними словами нотатку передачі для сторінки входу наступної сесії, а також необов’язковий запис журналу сесії. `/memory` відкриває центр пам’яті, а `/memory page` малює бібліотеку у вашому браузері як граф із вузлами та ребрами. Див. [docs/MNEME.md](../MNEME.md).
- **LSP-аналіз коду, переписування AST для 57 мов, налагоджувач DAP і комірки `Eval`.** Читання з якорями та атомарні правки кількох файлів (`ChangeSet`); запити до мовного сервера (`LspRead`) і рефакторинги з попереднім переглядом перед застосуванням (`LspRename`, `LspMoveSymbol`, `LspMoveFile`, `LspCodeAction`, `LspFormat`); пошук за синтаксичним деревом і переписування (`AstSearch`, `AstEdit`) з метазмінними `$NAME` і `$$$NAME` за 57 граматиками в архівах релізів (16 у кожній збірці `bun install` і 41 у пакеті граматик); постійні комірки коду на Python (`python3`) і JavaScript (ES-модуль Node) (`Eval`); а також налагоджувач за Debug Adapter Protocol (`Debug`), який керує `debugpy`, `js-debug`, `lldb`, `gdb`, `dlv`, `netcoredbg`, `rdbg`, адаптером налагодження Dart SDK, `kotlin-debug-adapter`, адаптером налагодження elixir-ls і Godot. В інструменті `Test` операція `debug` покроково переводить тест, що падає, на Python (`pytest`, `unittest`), JavaScript/TypeScript (`node-test`, `vitest`, `jest`), Go (`go test`) або Rust (`cargo test`) прямо в сесію `Debug`. Див. [docs/LANGUAGE-SERVICE.md](../LANGUAGE-SERVICE.md), [транзакції змін](../CHANGE-TRANSACTIONS.md), [структурні шаблони](../STRUCTURAL-PATTERNS.md), [комірки коду](../EVAL.md) і [налагоджувач](../DEBUGGER.md).
- **`WebSearch` без ключів і `WebFetch` у markdown.** `WebSearch` проходить один каскад: спершу нативний пошук провайдера в реальному часі, якщо модель сесії його підтримує (`ProviderSearch`), далі збережені ключі Brave або Tavily, далі офіційні API, які обираються за формою запиту (Stack Exchange, npm, PyPI, crates.io, пошук коду GitHub, Hacker News Algolia, Wikipedia), далі налаштовані JSON-API SearXNG (`MERCURY_SEARCH_SEARXNG_INSTANCES`) і наостанок вилучення сторінок DuckDuckGo без ключа (увімкнено за замовчуванням; вимикається в `/config` або через `MERCURY_SEARCH_KEYLESS=0`). Кожна відповідь лишається в межах 2 000 токенів і називає джерело, яке відповіло. `WebFetch` читає публічні сторінки як markdown власними словами сторінки в межах бюджету виклику 38 000 символів (сторінку, якій потрібен браузер, читає розміщений читач `r.jina.ai`, якщо тільки не задано `MERCURY_FETCH_READER=0`; адреса приватної мережі йому ніколи не надсилається). Див. [docs/ENGINES.md](../ENGINES.md).
- **Агенти, crewmates від різних провайдерів (`Crewmate`), worktrees і оренда файлів.** Два вбудовані агенти (`mercury-crew` для делегованої роботи будь-якого виду та `mercury-scout` для розвідки лише на читання) існують поряд із визначеннями агентів, які ви створюєте в `/agents`. Запускайте crewmates на будь-якому провайдері, до якого ви ввійшли, ізолюйте паралельну роботу в робочих копіях `git worktree` (`isolation: "worktree"`), узгоджуйте спільні файли через оренду файлів проєкту всередині процесу (`mcp__mercury__lease_take`, `mcp__mercury__lease_release`, `mcp__mercury__lease_list`), а скеровувати чи відновлювати crewmates за іменем або ідентифікатором можна через `SendMessage` і `ResumeCrewmate`. Стежте за crewmates у `/crewmates` і `/runs`. Див. [docs/CREW.md](../CREW.md).
- **Керування комп’ютером на робочому столі.** Увімкнено за замовчуванням, коли доступний нативний драйвер робочого столу. Інструмент `Computer` робить знімки екрана та керує мишею і клавіатурою в застосунку на передньому плані. Mercury перевіряє застосунок за назвою та ідентичністю перед дією і запитує схвалення, якщо тільки ваші правила дозволів, надання для сесії, налаштування доступу або режим дозволів уже не дозволяють дію; зупиняється на `Esc`; дозволяє керувати робочим столом лише одній сесії водночас і не зберігає знімки екрана у файлі збереженої розмови. Щоб прибрати інструмент, задайте `MERCURY_COMPUTER_USE=0`. Див. [docs/COMPUTER-USE.md](../COMPUTER-USE.md).
- **Голосове введення Whisper на пристрої (`/voice`).** `/voice on` завантажує англійську мовну модель на 60 МБ (`base.en-q5_1`) під час першого використання, перевіряє її контрольну суму SHA-256 і вмикає диктування; `/voice off` його вимикає. Утримуйте пробіл 1 с, щоб говорити, і відпустіть, щоб зупинити, або виконайте просто `/voice`, щоб почати й зупинити запис, коли голос увімкнено. Whisper розпізнає мовлення на пристрої, тож аудіо з голосом ніколи не залишає комп’ютер; `MERCURY_WHISPER_MODEL` обирає `tiny.en-q5_1`, `small.en-q5_1`, багатомовну `base-q5_1` або локальний файл `.gguf`. Див. [docs/VOICE.md](../VOICE.md).
- **Розклад cron і сесій Saturn (`/saturn`).** Заплануйте промпт для наявної сесії (`CronCreate`, `CronList`, `CronDelete`, `ScheduleWakeup`, `/loop`) або заплануйте запуск нової сесії на заданий час. Розклади можуть виконуватися один раз або повторюватися. Див. [docs/SATURN.md](../SATURN.md).
- **Мости до VS Code (ACP), Unity, Blender, Godot і Aseprite.** `mercury acp` підключається до редакторів, які підтримують Agent Client Protocol. Розширення VS Code (`mercury bridge install`) запускає Mercury в редакторі через цей протокол: чат, сесії, агенти, артефакти та рев’ю, а виділення й діагностика редактора додаються до кожного промпту. Окремі інтеграції, які вмикаються за бажанням, підключаються до запущених редакторів Unity (`MERCURY_UNITY=1`), Blender (`MERCURY_BLENDER=1`) і Godot (`MERCURY_GODOT_TOOLS=1`), а також дають пакетний доступ до Aseprite (`MERCURY_ASEPRITE=1`). Див. [Unity](../UNITY-BRIDGE.md), [Blender](../BLENDER-BRIDGE.md), [Godot](../VULCAN-GODOT-TOOLS.md) і [Aseprite](../ASEPRITE-BRIDGE.md).
- **Розширення.** У кожного розширення один маніфест. Джерела додаються з URL git, локальної папки або архіву та затверджуються за хешем їхніх contributions. Див. [docs/EXTENSIONS.md](../EXTENSIONS.md).
- **MCPs & Skills.** Налаштування для кожного репозиторію: що завантажують сесії, з іменованими пресетами та елементами керування, які можна змінювати під час сесії. Див. [docs/KIT.md](../KIT.md).
- **Діагностика.** Перевірка стану та `/health` створюють звіт, підкріплений діагностичними даними, з вердиктом `certified`, `caution` або `fault` і перевіреними виправленнями. Див. [docs/HEALTH-CERTIFICATE.md](../HEALTH-CERTIFICATE.md).
- **Довіра та дозволи.** Довіра до робочого простору, правила та режими дозволів, а також команди, які кожна сесія відхиляє. Див. [docs/TRUST.md](../TRUST.md).
- **Apollo Mode**, інтерв’ю зі специфікації: відповідайте на запитання агента, щоб доповнити специфікацію, за якою він побудує прототип. Див. [docs/APOLLO-MODE.md](../APOLLO-MODE.md).
- **Відновлення.** Атомарна публікація, журналювані операції та узгодження під час запуску. Див. [docs/DURABILITY.md](../DURABILITY.md).
Прапорці виконання визначено в `src/substrate/flagRegistry.ts`; вони доступні як налаштування `MERCURY_*` і відображаються за запитом. Сумісність інтеграцій описано в [docs/COMPATIBILITY.md](../COMPATIBILITY.md). Повний індекс документації — [docs/README.md](../README.md).
## Слеш-команди
`/help` виводить список доступних інтерактивних команд. Для нечіткого пошуку команд використовуйте `/palette`. Таблиця нижче групує вбудовані команди, увімкнені за замовчуванням, за категоріями, які використовує `/help`; актуальний список також містить `/samples` у категорії `current work`, коли увімкнено Samples (`MERCURY_SAMPLES=1` або рядок Samples у Boot Menu), а також будь-які навички та команди розширень.
| Розділ | Команди |
| --- | --- |
| current work | `/run` `/runs` `/workbench` `/diff` `/mission` (/goal) |
| crew & delegation | `/agents` `/crewmates` `/crew` `/daemon` `/saturn` `/seats` `/kill` `/unkill` |
| session & context | `/clear` `/compact` `/context` `/rewind` `/sessions` `/concourse` `/rename` `/title` `/contract` `/export` `/copy` `/usage` `/realms` `/restart` |
| memory & goals | `/memory` `/console` |
| model & effort | `/model` `/effort` `/submodels` `/advise` `/caching` `/tensorfold` |
| git & review | `/review` `/audit` |
| health & introspection | `/health` `/verify` `/trace` `/capabilities` `/lsp` |
| config & setup | `/config` `/jev` `/localsetup` `/llmhost` `/permissions` `/hooks` `/mcp` `/extensions` `/skills` `/browser` `/orient` `/keybindings` `/keys` `/vim` `/mouse` `/keysetup` `/bootmenu` `/voice` |
| appearance & cockpit | `/appearance` `/critter` `/palette` `/zen` `/browse` |
| account & app | `/logins` `/logout` `/accounts` `/defaultprovider` `/update-notes` `/feedback` `/help` `/exit` |
| Команда | Що робить |
| --- | --- |
| `/imagesetup` | Налаштувати локальні моделі зображень і відео. |
| `/llmhost` | Обрати модель для оренди на Runpod, Vast.ai або Lambda, запустити її на власному комп’ютері або підключити наявний сервер. |
| `/tensorfold` | Запустити локальну модель на TensorFold: встановити рушій, завантажити модель, розгорнути її на цьому Mac, відкрити до неї доступ у мережі або орендувати для неї GPU і перемкнутися на неї, усе на одному екрані. |
| `/restart` | Перенести цей чат на встановлену збірку Mercury; запущені спостереження та фонові shell-процеси зупиняються. |
| `/mcp` | Переглянути сервери, увійти, переглянути інструменти та параметри кожного сервера, перепідключити або перемкнути сервер для цього чату. |
`/mouse off` повертає вказівник терміналу для нативного виділення та копіювання тексту. Налаштування зберігається і відображається в `/config` як Mouse capture.
У рядку використання (usage) навички обов’язковий аргумент починається з `<…>`. Наприклад, `/update-config` і `/debug` потребують аргумента. Надішліть таку команду без аргумента, і ви отримаєте її опис та рядок використання; хід не починається. Якщо вибрати її в автодоповненні та натиснути Enter, у полі лишиться `/name `, готовий до додавання аргумента. `/loop` не потребує обов’язкового аргумента і запускається одразу.
## Повідомлення про проблему
Для короткого звіту скористайтеся [формою для тестувальників](https://mercury-cli.ai/report) або командою `/bug --short ` у Mercury. Форма запитує вашу ОС, що ви пробували і що зламалося; дамп перевірки стану не потрібен.
Виконайте `/bug ` у Mercury, щоб переглянути звіт перед надсиланням через GitHub CLI (`gh`), у який ви ввійшли. Без `gh` Mercury зберігає локальну чернетку в каталозі конфігурації та вказує на сторінку issues репозиторію.
Ви також можете відкрити задачу напряму за шаблоном bug, provider/model або feature request. Додайте вивід `--version`, ОС, термінал і точні кроки. Звітам про помилки та провайдерів також потрібен вивід `mercury health --json`, або `node dist/mercury.mjs health --json` для збірки з вихідного коду. Текстова копія екрана з помилкою теж допомагає.
Про проблеми безпеки повідомляйте приватно через вкладку Security репозиторію. Не відкривайте їх у публічних issues. Див. [SECURITY.md](../../SECURITY.md). [CONTRIBUTING.md](../../CONTRIBUTING.md) описує issues, pull request-и і перевірки.
## Ліцензія
Mercury CLI поширюється за ліцензією Apache License 2.0 (`Apache-2.0`) у [LICENSE.md](../../LICENSE.md). TypeScript- та Python-SDK у [sdk/](../../sdk/) і [sdk-py/](../../sdk-py/) (`mercury-cli-sdk` у npm і PyPI) також поширюються за Apache License 2.0 (`Apache-2.0`), кожен за власним файлом LICENSE ([sdk/LICENSE](../../sdk/LICENSE) і [sdk-py/LICENSE](../../sdk-py/LICENSE)).
Використання назви й торговельних марок Mercury регулюється [політикою торговельних марок](../../TRADEMARKS.md). Стороннє ліцензоване програмне забезпечення, що входить до складу, перелічено в [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md).