CLI aihelpme.ru (инструмент командной строки weknora)

CLI-клиент (команда weknora) предназначен для управления базами знаний и документами, выполнения поиска и потоковых ответов на вопросы. При интерактивном использовании доступен человекочитаемый вывод, а для скриптов и AI-агентов предусмотрены JSON-ответы, типизированные ошибки, режим предпросмотра --dry-run и запрос контрактов через weknora schema; команда weknora mcp serve предоставляет сервис MCP.

Исходный код расположен в каталоге cli/ и представляет собой отдельный Go-модуль (github.com/Tencent/WeKnora/cli). Для сборки из исходного кода требуется Go 1.26+. Точка входа команды — cli/cmd/root.go.

Начиная с версии v0.8.2, в консоли управления в разделе «Настройки → Публикация и интеграция → CLI» доступна страница с инструкцией по подключению, где генерируются готовые для копирования команды с учётом текущего развёртывания:

Установка: сборка из исходного кода (требуются Git и Go 1.26+, примеры приведены для macOS / Linux);
Подключение: weknora profile add weknora --host '<текущий-адрес-сервиса>' --use && weknora auth login, создание и активация профиля с именем weknora, затем вход по email и паролю. В адресе сервиса сохраняется префикс пути обратного прокси, суффикс /api/v1 указывать не нужно; если профиль с таким именем уже существует, используйте другое имя;
Проверка: выполните weknora doctor и weknora kb list, чтобы убедиться в доступности сервиса и корректности учётных данных.

В правой части страницы также приведены часто используемые команды (загрузка, поиск, диалог, список агентов) и пример конфигурации MCP-клиента ("args": ["--profile", "weknora", "mcp", "serve"]).

Общая архитектура

Установка

Сборка из исходного кода (текущий поддерживаемый способ)

В настоящее время поддерживаемым способом установки является сборка из исходного кода; готовые бинарные сборки и установка через go install пока не предоставляются.

bash

git clone https://aihelpme.ru.git
cd WeKnora/cli
go build -o weknora .
sudo mv weknora /usr/local/bin/   # или в любой каталог из $PATH

Использование cli/Makefile

В cli/Makefile предусмотрены цели сборки с внедрением метаданных версии (через -ldflags в internal/build.Version/Commit/Date):

Цель	Назначение
`make build`	Компиляция в `./bin/weknora`, внедрение версии из `git describe`, короткого хеша коммита и времени сборки
`make test`	`go test ./...`
`make test-coverage`	Запуск тестов и вывод отчёта о покрытии
`make lint`	`go vet ./...`
`make tidy`	`go mod tidy`
`make clean`	Удаление `./bin` и `coverage.out`

Примечание: в Makefile нет цели install, собранный бинарный файл необходимо переместить в $PATH самостоятельно.

Конфигурация и управление профилями

Конфигурационный файл и пути

Пользовательская конфигурация управляется через cli/internal/config/config.go и располагается по пути $XDG_CONFIG_HOME/weknora/config.yaml (если переменная XDG_CONFIG_HOME не задана — ~/.config/weknora/config.yaml; логика разрешения путей описана в cli/internal/xdg/xdg.go и следует соглашениям XDG во всех ОС, включая macOS). Запись выполняется атомарно (временный файл + rename) с правами доступа 0600.

Схема на диске (config.Config / config.Profile):

yaml

current_profile: prod          # Имя текущего активного профиля
profiles:
  prod:
    host: https://kb.example.com   # Обязательно: адрес сервера
    tenant_id: 42                  # Опционально: ID тенанта (только для отображения, не подставляется в заголовки запросов)
    user: user@example.com         # Опционально: email аккаунта (только для вывода в profile list)
    api_key_ref: keychain://...    # Ссылка на хранилище API-ключа (keychain:// или file://)
    token_ref: keychain://...      # Ссылка на JWT access token
    refresh_token_ref: keychain://...
    default_kb_id: "..."           # Опционально: база знаний по умолчанию
defaults:
  format: json                 # Опционально: формат вывода CLI по умолчанию
  no_version_check: true       # Опционально: отключить проверку совместимости версий

Хранилище учётных данных (secrets)

Учётные данные не записываются в config.yaml, там хранятся только ссылки на них (ref). Пакет cli/internal/secrets/ предоставляет два бэкенда:

KeyringStore: системная связка ключей (macOS Keychain / Linux keyring), пространство имён weknora:<profile>:<key>, ключи: access / refresh / api_key;
FileStore: при недоступности связки ключей (headless CI, WSL без DBus, контейнеры) выполняется откат к открытым файлам с правами 0600 по пути $XDG_CONFIG_HOME/weknora/secrets/<profile>/<key>. При этом auth login выводит однократное предупреждение в stderr.

Переключение профилей и приоритет разрешения

Цепочка разрешения профиля реализована в cli/internal/cmdutil/factory.go (Factory.ActiveProfile), приоритет от высшего к низшему:

Глобальный флаг --profile <name> (действует только на текущий вызов, не сохраняется на диск);
Переменная окружения WEKNORA_PROFILE;
Значение current_profile в config.yaml (переключается на постоянной основе командой weknora profile use).

Учётные данные из переменных окружения без сохранения состояния (headless / CI / сценарии агентов)

Функция buildClientFromEnv в factory.go позволяет полностью обойти config.yaml и системную связку ключей:

Переменная окружения	Назначение
`WEKNORA_TOKEN`	Bearer JWT (имеет приоритет над `WEKNORA_API_KEY`)
`WEKNORA_API_KEY`	API-ключ
`WEKNORA_HOST`	Адрес сервера (если не задан, используется host активного профиля)
`WEKNORA_PROFILE`	Переопределение активного профиля
`WEKNORA_KB_ID`	Явное указание ID базы знаний
`WEKNORA_FORMAT`	Формат вывода по умолчанию (text / json / ndjson)
`WEKNORA_LOG_LEVEL`	Уровень логирования SDK (error / warn / info / debug)
`WEKNORA_AGENT_HELP=1`	При `--help` выводит машиночитаемый AgentHelp JSON (`cli/internal/cmdutil/agenthelp.go`)

Цепочка разрешения базы знаний (--kb)

Команды, требующие контекста базы знаний (chat, doc, chunk, search chunks/docs и др.), используют Factory.ResolveKB с четырёхуровневым откатом (cli/internal/cmdutil/factory.go):

Флаг --kb (UUID передаётся напрямую; имя разрешается в ID через ListKnowledgeBases, см. cli/internal/cmdutil/kb.go);
Переменная окружения WEKNORA_KB_ID;
Файл привязки проекта .weknora/project.yaml (создаётся командой weknora link, ищется вверх от текущего каталога до 64 уровней, см. cli/internal/projectlink/projectlink.go);
Если совпадений нет, возвращается ошибка local.kb_id_required.

Для профилей с JWT (содержащих одновременно access- и refresh-токены) автоматически подключается транспорт прозрачного обновления при 401 (AuthRetryTransport): первый 401 инициирует вызов /api/v1/auth/refresh и повтор исходного запроса. Для профилей с API-ключами и учётных данных из переменных окружения обновление токенов не выполняется.

Глобальные флаги, форматы вывода и автоматизация

Глобальные флаги (`addGlobalFlags` в `cli/cmd/root.go`)

Флаг	Краткая форма	Описание
`--format`		Формат вывода: `text` \| `json` \| `ndjson`. По умолчанию `json` (не зависит от TTY, концепция agent-first; для человекочитаемого вывода укажите `--format text`). Переменная окружения `WEKNORA_FORMAT` может задавать значение по умолчанию, приоритет: `--format` > `WEKNORA_FORMAT` > json по умолчанию
`--jq`	`-q`	Фильтрация вывода JSON с помощью jq-выражения (требует `--format json
`--profile`		Переопределяет активный профиль для текущего вызова (не сохраняется на диск)
`--log-level`		Уровень отладочного логирования SDK: error \| warn \| info \| debug
`--yes`	`-y`	Пропуск запросов подтверждения для деструктивных операций
`--version`		Вывод версии (эквивалентно `weknora version`)

Многие команды записи также поддерживают флаг --dry-run (cli/internal/cmdutil/dryrun.go), охватывающий практически все команды мутаций (kb/doc/agent/model/profile/session/link/api/skills): запись не выполняется, в ответ выводится meta.dry_run=true + meta.plan (описание планируемых действий).

Контракт вывода JSON Envelope (`cli/internal/output/envelope.go`)

Успешные ответы направляются в stdout:

json

{"ok": true, "data": ..., "meta": {"count": 2, "total_count": 2, "has_more": false}, "profile": "prod"}

data: полезная нагрузка команды (объект или массив); проекции --jq должны строиться от корня .data, например --jq '.data[].id';
meta: команды списков содержат count / total_count / has_more; пакетные операции содержат successes / failures и трёхпозиционный status (success / partial / error); dry-run содержит dry_run + plan;
profile: имя профиля, разрешённого для данного вызова.

Ошибки направляются в stderr (stdout остаётся чистым для удобной передачи в пайплайн | jq):

json

{"ok": false, "error": {"type": "auth.unauthenticated", "message": "...", "exit_code": 3,
  "hint": "...", "retry_argv": ["weknora","auth","login"], "retryable": false}}

Типы ошибок представляют собой иерархические строки (cli/internal/cmdutil/errors.go): auth.*, resource.*, input.*, server.*, network.error, operation.*, local.*, internal.error. Поле retry_argv представляет собой готовый массив аргументов команды исправления для прямого запуска (exec).

Формат --format ndjson используется для потоковых команд (chat / session ask / session resume): первой строкой передаётся событие инициализации CLI init (содержит session_id, kb_id, profile), далее построчно транслируются SSE-события SDK (cli/internal/sse/).

Матрица кодов возврата (`cli/cmd/exitcodes.go`, машиночитаемую версию можно получить командой `weknora exit-codes`)

Код	Значение	Соответствующий тип ошибки	Рекомендуемое действие агента
0	Успех	—	Продолжить работу
1	Типизированная локальная ошибка / сбой операции / неклассифицированная	`local.*`, `operation.failed`, `operation.cancelled`, `server.session_create_failed`, `internal.error`	Прочитать stderr и принять решение о повторе или отмене
2	Ошибка парсинга флагов / аргументов (неизвестный флаг, неверное число аргументов, пропущен обязательный флаг)	`input.invalid_argument` (тот же тип, что и для кода 5, разделяются по коду выхода)	Обратиться к `weknora <cmd> --help`
3	Сбой аутентификации / авторизации	`auth.*`	Повторить `weknora auth login`, затем повторить операцию
4	Ресурс не найден	`resource.not_found`	Проверить ID ресурса
5	Недопустимое значение ввода (типизированная валидация, не ошибка парсинга)	`input.*` (кроме confirmation_required)	Скорректировать параметры и повторить
6	Ограничение частоты запросов (rate limit)	`server.rate_limited`	Повторить с задержкой (экспоненциальный откат)
7	Ошибка сервера / сети	`server.`, `network.`	Временный сбой, повторить с откатом
10	Требуется подтверждение (высокорисковая операция записи)	`input.confirmation_required`	Запросить подтверждение у человека; при явном одобрении повторить с флагом `-y`
124	Превышено время ожидания операции	`operation.timeout`	Увеличить `--timeout` или проверить фоновую задачу
130	Прервано сигналом (SIGINT/SIGTERM)	—	Остановить выполнение, не повторять

Защита высокорисковых операций записи (протокол exit-10): команды удаления, kb config set, api -X DELETE/PUT/PATCH, message delete, session tool-approval resolve и др. в неинтерактивном окружении / при JSON-выводе без флага -y немедленно завершаются с кодом 10, возвращая ошибку input.confirmation_required, и не производят никаких изменений на сервере — агент не может скрытно модифицировать состояние системы.

Машиночитаемая интроспекция

weknora schema (cli/cmd/schema.go): без аргументов выводит список всех конечных команд с их назначением; weknora schema kb create выводит полный контракт отдельной команды (used_for, flags, examples, output, risk);
WEKNORA_AGENT_HELP=1 weknora <cmd> --help: выводит эквивалентный JSON AgentHelp;
При неизвестной подкоманде выводится типизированный envelope input.unknown_subcommand, содержащий рекомендации suggestions (did-you-mean) и список доступных подкоманд.

Подробный обзор групп команд

Каждая группа соответствует отдельному каталогу в cli/cmd/.

profile — управление целями подключения (`cli/cmd/profile/`)

Подкоманда	Вызов	Описание
list	`list`	Список настроенных профилей
add	`add <name>`	Регистрация нового профиля (запоминает только host, без учётных данных)
use	`use <name>`	Переключение профиля по умолчанию на постоянной основе
remove	`remove <name>`	Удаление профиля (удаляет запись из config и ссылки из связки ключей)

Ключевые флаги add: --host (обязательный, URL сервера), --user (опциональный email для отображения), --use (сделать активным сразу после добавления).

bash

weknora profile add prod --host=https://kb.example.com --use
weknora profile list --format json

auth — управление учётными данными (`cli/cmd/auth/`)

Подкоманда	Вызов	Описание
login	`login`	Аутентификация текущего активного профиля: интерактивный ввод email и пароля либо `--with-token` для чтения API-ключа из stdin (сначала проверяется вызовом `/auth/me`, затем сохраняется)
logout	`logout`	Очистка сохранённых учётных данных профиля; `--all` очищает все профили
list	`list`	Список профилей с аутентификацией
status	`status`	Отображение активного профиля, субъекта и состояния токенов
refresh	`refresh`	Обмен сохранённого refresh token на новый JWT access token
token	`token`	Вывод исходных учётных данных активного профиля в stdout (для shell-скриптов)

bash

weknora auth login                                    # Интерактивно (TTY)
echo "$WEKNORA_API_KEY" | weknora auth login --with-token   # Неинтерактивно / для агентов
weknora auth status --format json

Примечание: команда auth login не принимает флаг --host, предварительно необходимо создать и активировать профиль командой profile add ... --use.

config — просмотр результирующей конфигурации (`cli/cmd/config/`)

Подкоманда	Вызов	Описание
view	`view`	Только чтение: отображает результирующую конфигурацию и источник каждого значения (active_profile / profile_source / auth_source / host / kb_id / kb_source / log_level / format_default / config_file / secrets / project_link и др.) без отправки сетевых запросов

bash

weknora config view --format json --jq '.data.kb_source'

link / unlink — привязка каталога к базе знаний (`cli/cmd/link/`)

Команды link и unlink подключены напрямую к корневой команде (см. root.go).

Команда	Вызов	Описание
link	`link [kb]`	Записывает `.weknora/project.yaml` в текущем каталоге, привязывая базу знаний (позиционный аргумент или `--kb`, эквивалентны; в TTY без параметров открывает интерактивный выбор; перезаписывает существующую привязку). Поддерживает `--dry-run`
unlink	`unlink`	Удаляет привязку к базе знаний в текущем каталоге

bash

weknora link engineering            # Имя автоматически разрешается в ID
weknora link --kb a32a63ff-fb36-4874-bcaa-30f48570a694

kb — управление базами знаний (`cli/cmd/kb/`)

Подкоманда	Вызов	Описание
list	`list`	Список доступных баз знаний; `--pinned` — только закреплённые, `--limit/-L` (по умолчанию 30)
view	`view <kb-id>`	Просмотр по ID
create	`create <name>`	Создание; `--description`, `--embedding-model`, `--chat-model` (готова к использованию сразу после создания), `--storage-provider`
update	`update <kb-id>`	Изменение имени/описания: `--name`, `--description` (в `kb/edit.go`)
delete	`delete <kb-id>`	Удаление (защита подтверждением exit-10, `-y` для пропуска)
pin / unpin	`pin <kb-id>` / `unpin <kb-id>`	Закрепление/открепление (идемпотентно: если состояние уже совпадает — no-op)
status	`status <kb-id>`	Быстрая проверка работоспособности (1 HTTP-запрос)
check	`check <kb-id>`	Сквозная проверка (состояние + агрегация ошибок документов)
config	`config <kb-id>`	Просмотр конфигурации моделей только для чтения (embedding/llm/rerank/multimodal, флаг `retrieval_ready`, API-ключи никогда не выводятся)
config set	`set <kb-id>`	Привязка моделей: `--chat-model` и `--embedding-model` обязательны (ID или имена); операция высокого риска, защита exit-10

bash

weknora kb create docs --embedding-model text-embedding-3 --chat-model gpt-4o
weknora kb config set <kb-id> --chat-model <id> --embedding-model <id> -y

doc — управление документами (`cli/cmd/doc/`)

Подкоманда	Вызов	Описание
upload	`upload <file>`	Загрузка локального файла; `--name`, `--recursive` + `--glob` (пакетная загрузка каталогов, например `'*.pdf'`), `--metadata key=value` (повторяемый), `--enable-multimodel`, `--channel`
fetch	`fetch <url>`	Загрузка удалённого документа по URL; `--name`, `--title`, `--file-type` (подсказка типа файла, если у URL нет расширения), `--tag-id`, `--channel`
create	`create`	Создание записи из встроенного текста Markdown: `--text` (обязательный), `--title`, `--tag-id`, `--channel`
list	`list`	Список документов; `--status pending
view	`view <doc-id>`	Просмотр сведений о документе
update	`update <doc-id>`	Обновление: `--title`, `--description`
delete	`delete <doc-id> [<doc-id>...] \| --all --kb=<kb-id>`	Пакетное удаление / очистка базы знаний (защита exit-10)
download	`download <doc-id>`	Скачивание исходного файла; `-O/--output` (`-` для stdout), `--clobber`
reparse	`reparse <doc-id>`	Повторный парсинг
wait	`wait <doc-id> [<doc-id>...]`	Ожидание завершения парсинга в цикле опроса; `--timeout` (по умолчанию 10m, при таймауте код возврата 124), `--interval` (по умолчанию 2s, экспоненциальный откат с ограничением 15s)

bash

weknora doc upload ./design.pdf --kb docs
weknora doc wait <doc-id> --timeout 5m && weknora search chunks "RRF" --kb docs

chunk — отладка блоков (chunk) (`cli/cmd/chunk/`)

Подкоманда	Вызов	Описание
list	`list`	Список блоков документа (для управления/отладки, не для поиска): `--doc` (обязательный), `--limit/-L`, `--page-size`, `--all-pages`
view	`view <chunk-id>`	Просмотр содержимого отдельного блока
delete	`delete <chunk-id> [<chunk-id>...] --doc <doc-id>`	Удаление блоков (`--doc` обязателен; защита exit-10)

search — поиск (`cli/cmd/search/`)

Подкоманда	Вызов	Описание
chunks	`chunks "<query>"`	Гибридный поиск (векторный + ключевые слова): `--kb`, `--limit/-L` (по умолчанию 8, оптимизировано для контекстного окна RAG), `--vector-threshold`, `--keyword-threshold`, `--no-vector`, `--no-keyword`
docs	`docs "<query>"`	Поиск документов по ключевым словам (фильтрация на стороне сервера): `--kb`, `--limit`, `--page-size`, `--all-pages`
kb	`kb "<query>"`	Поиск баз знаний по имени/описанию (подстрочный поиск на стороне клиента): `--limit`
sessions	`sessions "<query>"`	Поиск сессий по заголовку/описанию (подстрочный поиск на стороне клиента): `--limit`, `--page-size`, `--all-pages`

bash

weknora search chunks "rate limiting design" --kb docs --limit 5 --format json --jq '.data[].content'

chat — потоковые вопросы и ответы RAG (`cli/cmd/chat/chat.go`)

Одиночная команда: chat "<text>". Три режима вывода используют один потоковый вызов SDK:

--format json (по умолчанию): буферизует поток в единый envelope (events, session_id, assistant_message_id и др.);
--format text: потоковый человекочитаемый вывод ответа в реальном времени;
--format ndjson: прямая трансляция исходных SSE-событий (первая строка init с session_id / kb_id).

Флаги: --kb, --session (продолжение существующей сессии), --reference (с индексами источников), --verbose (с событиями рассуждений / инструментов / жизненного цикла).

bash

weknora chat "What is RRF?" --kb a32a63ff-fb36-4874-bcaa-30f48570a694
weknora chat "Продолжить" --session sess_abc --format ndjson

session — управление сессиями (`cli/cmd/session/`)

Подкоманда	Вызов	Описание
list	`list`	Список сессий: `--limit/-L`, `--page-size`, `--all-pages`, `--since` (например, 7d / 24h / 30m)
view	`view <session-id>`	Просмотр сессии; `--full` — загрузка вместе с историей сообщений, `--limit/-L`
ask	`ask "<text>"`	Задать вопрос пользовательскому агенту на сервере: `-a/--agent` (обязательный), `--session`, `--reference`, `--verbose`
resume	`resume <session-id>`	Подключение к потоку SSE-событий текущего/завершённого сообщения: `-m/--message` (обязательный)
stop	`stop <session-id>`	Остановка генерации определённого сообщения ассистента: `-m/--message` (обязательный)
delete	`delete <session-id> [<session-id>...]`	Пакетное удаление (защита exit-10)
tool-approval resolve	`resolve <pending-id>`	Одобрение/отклонение отложенного вызова инструмента агента: `--reject`, `--reason`, `--modified-args` (JSON, только при одобрении); операция высокого риска

bash

weknora session ask "Сделай выжимку из этой базы знаний" --agent agt_123 --format ndjson
weknora session tool-approval resolve <pending-id> --reject --reason "Операции записи запрещены" -y

message — сообщения внутри сессии (`cli/cmd/message/`)

Подкоманда	Вызов	Описание
list	`list --session <session-id>`	Список сообщений (от новых к старым, курсорная пагинация по времени): `--session` (обязательный), `--limit/-L`, `--before` (RFC3339)
search	`search "<query>"`	Поиск по истории сообщений во всех сессиях (пары вопрос-ответ): `--limit/-L` (по умолчанию 20), `--mode keyword
delete	`delete <message-id> --session <session-id>`	Удаление одного сообщения (`--session` обязателен; операция высокого риска, защита exit-10)

agent — CRUD пользовательских агентов (`cli/cmd/agent/`)

Подкоманда	Вызов	Описание
list	`list`	Список агентов: `--limit/-L`
view	`view <agent-id>`	Просмотр конфигурации
create	`create <name>`	Создание: `--model` (обязателен, кроме `--generate-skeleton`), `--description`, `--system-prompt` / `--system-prompt-file` (взаимоисключающие, `-` для stdin), `--agent-mode`, `--attach-kb` (повторяемый), `--kb-selection-mode`, `--rerank-model`, `--temperature`, `--from` (копирование существующего агента), `--config-file` (полный AgentConfig YAML/JSON), `--generate-skeleton` (вывод пустого шаблона конфигурации)
update	`update <agent-id>`	Обновление (`agent/edit.go`): `--name`, `--description`, `--model`, `--system-prompt(-file)`, `--agent-mode`, `--rerank-model`, `--temperature`, `--add-kb` / `--remove-kb` (повторяемые, идемпотентные), `--kb-selection-mode`, `--config-file` (замена базовой конфигурации целиком с последующим наложением детальных флагов)
delete	`delete <agent-id>`	Удаление (защита exit-10)
status	`status <agent-id>`	Состояние работоспособности
check	`check <agent-id>`	Сквозная проверка (состояние + доступность kb_scope)

bash

weknora agent create researcher --model gpt-4o --attach-kb <kb-id> --system-prompt-file ./prompt.md
weknora agent update agt_123 --add-kb <kb-id2> --temperature 0.3

model — управление моделями (`cli/cmd/model/`)

Подкоманда	Вызов	Описание
list	`list`	Список моделей: `--type` (Embedding / Rerank / KnowledgeQA / VLLM / ASR), `--source` (local / remote / openai / aliyun …), `--limit/-L`
view	`view <model-id>`	Просмотр сведений о модели
create	`create <name>`	Регистрация модели: `--type` (обязательный; `chat` эквивалентно KnowledgeQA), `--source` (обязательный; local=Ollama, remote=API провайдера), `--provider` (обязателен при source=remote), `--base-url`, `--api-key-stdin` (чтение ключа из stdin без сохранения в argv/истории), `--dimension` (только для Embedding), `--default`, `--param key=value` (повторяемый, значение парсится как JSON), `--display-name`, `--description`
update	`update <model-id>`	Обновление: `--display-name`, `--description`, `--base-url`, `--api-key-stdin` (ротация ключа), `--param`, `--default`
delete	`delete <model-id>`	Удаление (защита exit-10)

bash

weknora model create bge-m3 --type Embedding --source local --base-url http://localhost:11434 --dimension 1024
echo "$OPENAI_KEY" | weknora model create gpt-4o --type chat --source remote --provider openai --api-key-stdin

api — аварийный доступ к сырым HTTP-запросам (`cli/cmd/api/api.go`)

Одиночная команда: api <path>. Автоматически передаёт заголовки аутентификации / тенанта / request-id активного профиля.

Флаг	Краткая форма	Описание
`--method`	`-X`	Метод HTTP (по умолчанию GET; при передаче тела автоматически повышается до POST)
`--data`	`-d`	Встроенное тело JSON (взаимоисключающее с `--input` / `-F`)
`--input`		Чтение тела из файла (`-` для stdin)
`--field`	`-F`	Сборка JSON-объекта тела из пар `key=value` (повторяемый; true/false/null/числа автоматически приводятся к типам)
`--paginate`		Следование пагинации по смещению (?page=N&page_size=M) с объединением в единый ответ `{data, total}`

Запрос -X DELETE защищён протоколом подтверждения деструктивных действий exit-10; PUT/PATCH защищены подтверждением записи; для POST ограничений не накладывается (аналогично типизированным командам create). Поддерживается --dry-run (только для методов, отличных от GET).

bash

weknora api /api/v1/knowledge-bases                              # GET
weknora api /api/v1/knowledge-bases -d '{"name":"foo"}'          # POST (автоматически)
weknora api /api/v1/knowledge-bases/<id> -X DELETE -y

mcp — сервер протокола Model Context Protocol (`cli/cmd/mcp/`)

Подкоманда	Вызов	Описание
serve	`serve`	Запуск сервера MCP по протоколу JSON-RPC 2.0 через stdin/stdout (в настоящее время только транспорт stdio); логи выводятся в stderr; при запуске сразу инициализирует клиент SDK, при отсутствии профиля немедленно завершается с ошибкой `auth.unauthenticated`

Предоставляет 10 инструментов (реализация в cli/internal/mcp/tools.go): kb_list / kb_view / doc_list / doc_view / doc_download / search_chunks / chunk_list / agent_list доступны только для чтения; chat и session_ask создают записи сессий/сообщений. Инструменты создания ресурсов, удаления ресурсов и загрузки файлов не предоставляются.

Пример регистрации в MCP-клиенте (добавление в конфигурацию mcpServers клиента):

json

{
  "mcpServers": {
    "weknora": { "command": "weknora", "args": ["mcp", "serve"] }
  }
}

skills — встроенные навыки агентов (Agent Skills) (`cli/cmd/skills/skills.go`)

Подкоманда	Вызов	Описание
list	`list`	Список навыков агента, встроенных в бинарный файл (`cli/skills/embed.go`): name / description / files
install	`install`	Запись встроенных навыков в каталог skills агента: `--dir` (по умолчанию `~/.claude/skills`, поддерживает раскрытие `~`), `--force` (перезапись существующих файлов, иначе пропуск); поддерживает `--dry-run`

bash

weknora skills install --dry-run --format json
weknora skills install --dir ~/.claude/skills --force

doctor — самодиагностика (`cli/cmd/doctor/doctor.go`)

Одиночная команда: doctor. Выполняет 4 проверки: доступность базового URL, аутентификация, совместимость версии сервера, хранилище учётных данных. Статус каждой проверки: ok / warn / fail / skip. Любой fail приводит к коду возврата 1 (данные JSON всё равно выводятся); если только warn, код возврата 0, но summary.all_passed=false.

Флаги: --no-cache (обход кэша $XDG_CACHE_HOME/weknora/server-info.yaml и принудительное повторное сканирование), --offline (пропуск сетевых проверок, проверяются только локальная связка ключей и файловое хранилище).

bash

weknora doctor --format json --jq '.data.summary.all_passed'

Вспомогательные команды корневого уровня (`cli/cmd/root.go`, `schema.go`, `exitcodes.go`)

Команда	Вызов	Описание
version	`version`	Метаданные сборки (version / commit / date)
schema	`schema [command...]`	Машиночитаемый контракт команд (см. выше «Машиночитаемая интроспекция»)
exit-codes	`exit-codes`	Матрица кодов возврата (JSON или таблица)

Что покрывают приёмочные тесты (`cli/acceptance/`)

Каталог cli/acceptance/ представляет собой слой межконтрактных/интеграционных тестов CLI (в doc.go указано: «contract surface — change with care») и разделён на два подпакета:

contract/ — контрактные тесты сетевого протокола

wire_test.go: запускает полное дерево команд cobra внутри процесса, перехватывает stdout/stderr для каждого сценария и побайтово сравнивает вывод с эталонными JSON-файлами (golden files) в testdata/wire/. Охватываемые сценарии: version, auth_status (успех + ошибка auth.unauthenticated), doctor (offline-успех + ошибка сети), kb_list (успех / пустой список / auth.forbidden), kb_view (успех / resource.not_found), profile_use, search (успех / input.invalid / not_found). Эталонные файлы фиксируют полную структуру envelope (например, {"ok":true,"data":[...],"meta":{"count":2,"total_count":2}}), что позволяет мгновенно обнаружить любые расхождения в контракте wire; в негативных сценариях проверяется наличие ожидаемых типизированных кодов ошибок в stderr.
errorcodes_test.go: с помощью go/ast сканирует каждое литеральное вхождение cmdutil.NewError(CodeXxx, ...) / Wrapf(CodeXxx, ...) в cli/cmd/ и проверяет, что все коды ошибок зарегистрированы в таблице cmdutil.AllCodes() — это гарантирует, что документированный список кодов ошибок синхронизирован с кодом.

e2e/ — сквозные тесты на реальном сервере

Файл e2e_test.go содержит сборочный тег //go:build acceptance_e2e и по умолчанию не запускается при go test ./.... Для явного запуска выполните:

bash

cd cli
WEKNORA_E2E_HOST=https://kb.example.com WEKNORA_E2E_TOKEN=eyJ... \
  go test -tags=acceptance_e2e -v ./acceptance/e2e/...

Тест TestRAGFullLoop компилирует реальный бинарный файл CLI и через учётные данные из переменных окружения WEKNORA_HOST/WEKNORA_TOKEN (проверяя цепочку headless-аутентификации без связки ключей) проходит полный цикл RAG: kb create (с привязкой моделей) → doc upload → doc wait (ожидание индексации) → search → chat. На каждом шаге парсится JSON envelope предыдущего шага для извлечения ID, проверяется как функциональное поведение, так и стабильность контракта передачи данных; временная база знаний гарантированно удаляется через t.Cleanup даже при сбое теста.

Кроме того, в каталоге cli/cmd/ имеются сквозные тесты уровня дерева команд (не в acceptance, но также фиксирующие поведение): required_positional_coverage_test.go, dryrun_coverage_test.go, agenthelp_coverage_test.go, root_unknown_subcommand_test.go и др. Они обеспечивают полное покрытие валидации позиционных аргументов каждого терминального вызова, поддержки --dry-run, метаданных AgentHelp и обработки неизвестных подкоманд.

Быстрый старт

bash

# 1. Регистрация сервера в качестве профиля и его активация
weknora profile add prod --host https://kb.example.com --use

# 2. Аутентификация (интерактивно; в сценариях с агентами используйте --with-token)
weknora auth login

# 3. Самодиагностика
weknora doctor

# 4. Создание базы знаний, привязка моделей, загрузка документа и ожидание индексации
weknora kb create docs --embedding-model <emb> --chat-model <llm>
weknora doc upload ./design.pdf --kb docs
weknora doc wait <doc-id>

# 5. Поиск и диалог
weknora search chunks "rate limiting" --kb docs
weknora chat "Сделай выжимку из этого документа с архитектурой" --kb docs

CLI aihelpme.ru (инструмент командной строки weknora) ​

Общая архитектура ​

Установка ​

Сборка из исходного кода (текущий поддерживаемый способ) ​

Использование cli/Makefile ​

Конфигурация и управление профилями ​

Конфигурационный файл и пути ​

Хранилище учётных данных (secrets) ​

Переключение профилей и приоритет разрешения ​

Учётные данные из переменных окружения без сохранения состояния (headless / CI / сценарии агентов) ​

Цепочка разрешения базы знаний (--kb) ​

Глобальные флаги, форматы вывода и автоматизация ​

Глобальные флаги (addGlobalFlags в cli/cmd/root.go) ​

Контракт вывода JSON Envelope (cli/internal/output/envelope.go) ​

Матрица кодов возврата (cli/cmd/exitcodes.go, машиночитаемую версию можно получить командой weknora exit-codes) ​

Машиночитаемая интроспекция ​

Подробный обзор групп команд ​

profile — управление целями подключения (cli/cmd/profile/) ​

auth — управление учётными данными (cli/cmd/auth/) ​

config — просмотр результирующей конфигурации (cli/cmd/config/) ​

link / unlink — привязка каталога к базе знаний (cli/cmd/link/) ​

kb — управление базами знаний (cli/cmd/kb/) ​

doc — управление документами (cli/cmd/doc/) ​

chunk — отладка блоков (chunk) (cli/cmd/chunk/) ​

search — поиск (cli/cmd/search/) ​

chat — потоковые вопросы и ответы RAG (cli/cmd/chat/chat.go) ​

session — управление сессиями (cli/cmd/session/) ​

message — сообщения внутри сессии (cli/cmd/message/) ​

agent — CRUD пользовательских агентов (cli/cmd/agent/) ​

model — управление моделями (cli/cmd/model/) ​

api — аварийный доступ к сырым HTTP-запросам (cli/cmd/api/api.go) ​

mcp — сервер протокола Model Context Protocol (cli/cmd/mcp/) ​

skills — встроенные навыки агентов (Agent Skills) (cli/cmd/skills/skills.go) ​

doctor — самодиагностика (cli/cmd/doctor/doctor.go) ​

Вспомогательные команды корневого уровня (cli/cmd/root.go, schema.go, exitcodes.go) ​

Что покрывают приёмочные тесты (cli/acceptance/) ​

contract/ — контрактные тесты сетевого протокола ​

e2e/ — сквозные тесты на реальном сервере ​

Быстрый старт ​

CLI aihelpme.ru (инструмент командной строки weknora)

Общая архитектура

Установка

Сборка из исходного кода (текущий поддерживаемый способ)

Использование cli/Makefile

Конфигурация и управление профилями

Конфигурационный файл и пути

Хранилище учётных данных (secrets)

Переключение профилей и приоритет разрешения

Учётные данные из переменных окружения без сохранения состояния (headless / CI / сценарии агентов)

Цепочка разрешения базы знаний (--kb)

Глобальные флаги, форматы вывода и автоматизация

Глобальные флаги (`addGlobalFlags` в `cli/cmd/root.go`)

Контракт вывода JSON Envelope (`cli/internal/output/envelope.go`)

Матрица кодов возврата (`cli/cmd/exitcodes.go`, машиночитаемую версию можно получить командой `weknora exit-codes`)

Машиночитаемая интроспекция

Подробный обзор групп команд

profile — управление целями подключения (`cli/cmd/profile/`)

auth — управление учётными данными (`cli/cmd/auth/`)

config — просмотр результирующей конфигурации (`cli/cmd/config/`)

link / unlink — привязка каталога к базе знаний (`cli/cmd/link/`)

kb — управление базами знаний (`cli/cmd/kb/`)

doc — управление документами (`cli/cmd/doc/`)

chunk — отладка блоков (chunk) (`cli/cmd/chunk/`)

search — поиск (`cli/cmd/search/`)

chat — потоковые вопросы и ответы RAG (`cli/cmd/chat/chat.go`)

session — управление сессиями (`cli/cmd/session/`)

message — сообщения внутри сессии (`cli/cmd/message/`)

agent — CRUD пользовательских агентов (`cli/cmd/agent/`)

model — управление моделями (`cli/cmd/model/`)

api — аварийный доступ к сырым HTTP-запросам (`cli/cmd/api/api.go`)

mcp — сервер протокола Model Context Protocol (`cli/cmd/mcp/`)

skills — встроенные навыки агентов (Agent Skills) (`cli/cmd/skills/skills.go`)

doctor — самодиагностика (`cli/cmd/doctor/doctor.go`)

Вспомогательные команды корневого уровня (`cli/cmd/root.go`, `schema.go`, `exitcodes.go`)

Что покрывают приёмочные тесты (`cli/acceptance/`)

contract/ — контрактные тесты сетевого протокола

e2e/ — сквозные тесты на реальном сервере

Быстрый старт