Skip to content

wtctl 0.5.0

Choose a tag to compare

@ysamtme ysamtme released this 14 Oct 23:01
· 44 commits to main since this release

Три темы. Скрипты на команде wtctl и SDK: неполный ответ даёт код выхода 3, SDK перебирает строки запроса методом queryRows, его имена описаны по-русски в подсказках редактора и в справочнике docs/sdk-reference.md, в docs/cli.md — рецепты для PowerShell. Локальные файлы клиента: сохранённые результаты и журнал записей держатся в пределах размера и срока. Ошибки: точнее коды, исходы записи и подсказки, тексты без английских слов. Скрипт, который брал из точки входа wtctl HcmRuntime, LogReader или withHcm, нужно поправить: см. «Несовместимые изменения».

Несовместимые изменения:

  • Убраны пять низкоуровневых операций, которые повторяли другие: native.lds.openSession и web.lds.openSession — вместо них native.session.open и web.session.open; native.lds.closeSession и web.lds.closeSession — вместо них native.session.close и web.session.close; native.spxml.call — вместо неё native.rpc.call. Вызов убранного ID отвечает UNKNOWN_OPERATION. Ответ *.session.* содержит ещё поле profile. В wtctl/protocol у NativeSession убрано поле spxml: это был тот же объект, что rpc.
  • В SDK убрано поле status у операций: оно у всех было implemented и ничего не значило. Его больше нет в ответе getNativeOperations(), listHcmOperations() и describeHcmOperation() и в типе OperationDefinition; убраны фильтр status у listHcmOperations() и флаг --status у wtctl api list.
  • В SDK у LogReader убраны поля-константы с английскими пояснениями: semantics и consistency у ответа read(), severityDetection и lineNumbers у search(), semantics у follow(). Их нет и в типах LogReadData, LogSearchData, LogFollowData. В ответы logs.* они и раньше не попадали.
  • Команда wtctl завершается с кодом 3, когда ответ не поместился в outputLimitBytes и сохранён локально: в stdout прежний JSON с ok:true, meta.truncated и meta.resultId, но данных в нём только начало. Раньше код был 0, и скрипт мог принять начало за весь ответ. Скрипт, который считает ошибкой любой ненулевой код, теперь остановится и на таком ответе: дочитать его — wtctl result read или wtctl result export, получить сразу целиком — --output ФАЙЛ, с ним код 0. Операция при коде 3 выполнена: запись или код на сервере повторять не нужно.
  • Точка входа wtctl отдаёт только то, что описано для вызывающего: HcmClient, withHcmClient, loadConfig, unwrap, getCleanupError, HcmError, HcmOperationError, HcmStoredResultError, HcmCleanupError, listHcmOperations, describeHcmOperation и типы аргументов и ответов. Убраны HcmRuntime, NativeGateway, getNativeOperations, LogReader, LogReadUnavailableError, RpcCatalog, withHcm, parseFileExists, parseServerInfo, configExample и типы HcmSdkRuntime, NativeConfig, NativeOperation, LogFile, LogEvent, LogListData, LogReadData, LogSearchData, LogFollowData. Убран HcmClient.fromRuntime; конструктор HcmClient в типах принимает только подключение, поля runtime в типах нет. NativeGateway и getNativeOperations по-прежнему есть в wtctl/native. Вместо withHcm — withHcmClient, вместо LogReader — client.listLogs, readLog, searchLogs, followLog.
  • Поле verification в ответе objects.delete — server или catalog, как другие значения протокола клиента. Раньше было server acknowledgement и catalog absence. Тип DeletedObjectData.verification в SDK — "server" | "catalog".

Добавлено:

  • Клиент сам удаляет старые сохранённые результаты, когда сохраняет новый: старше resultsMaxAgeDays (по умолчанию 7 дней), затем самые старые, пока результаты подключения больше resultsMaxBytes (1 ГБ). Результаты моложе часа остаются, поэтому предел приблизительный. Чтение удалённого результата отвечает RESULT_NOT_FOUND с подсказкой повторить запрос. Раньше папка результатов только росла.
  • Журнал записей mutations.jsonl не больше journalMaxBytes (10 МБ): переполненный файл становится mutations.1.jsonl, новые строки идут в новый файл. Журнал описан в docs/configuration.md.
  • 0 в resultsMaxBytes, resultsMaxAgeDays и journalMaxBytes снимает предел.
  • Переменные WTCTL_MAX_RESPONSE_BYTES, WTCTL_OUTPUT_LIMIT_BYTES, WTCTL_RESULTS_MAX_BYTES, WTCTL_RESULTS_MAX_AGE_DAYS и WTCTL_JOURNAL_MAX_BYTES: теперь все поля подключения, кроме адреса, учётных данных и прав, задаются и без файла, в том числе в env MCP-сервера. Как и WTCTL_TIMEOUT_MS, они действуют и при файле с разделом connections. Ошибка в значении называет поле и переменную. Число в переменной и в файле записывается только цифрами: 5e3 и пробелы вокруг числа больше не принимаются.
  • loadConfig({ settings }) в SDK задаёт те же поля кодом, с той же проверкой; settings сильнее переменных и файла. Адрес, учётные данные и права подключения из файла или переменных settings не меняет. settings с baseUrl — отдельное подключение без файла и переменных, права по умолчанию выключены.
  • wtctl object get, patch и delete принимают ID без типа: wtctl object get 0x… --fields login. Тип перед ID по-прежнему можно указать, тогда команда проверяет тип объекта.
  • У каждого имени, которое экспортирует wtctl, у методов HcmClient и у полей их аргументов и ответов в типах пакета есть описание по-русски: что делает метод, что значит поле, когда unwrap бросает. Его показывает подсказка редактора. Новые имена типов вместо безымянных: GetManyInput, GetManyData, RunAgentInput, FileListInput, ResultExportData, LogResetReason. docs/sdk.md перечисляет функции и классы пакета.
  • Справочник SDK docs/sdk-reference.md: каждая функция, метод HcmClient, ошибка и тип с аргументами, полями ответа и описанием — тот же текст, что в подсказке редактора. Таблица типов методов в docs/sdk.md заменена ссылкой на него.
  • client.queryRows(args) в SDK перебирает строки каталога или запроса XQuery одним for await: аргументы те же, что у query, страницы метод листает сам. Страница с incomplete:true бросает HcmOperationError с кодом QUERY_INCOMPLETE и подсказкой сервера, а не выглядит как конец данных. Большой ответ бросает HcmStoredResultError, как unwrap.
  • В docs/cli.md раздел «Скрипты»: выгрузка в CSV постранично в PowerShell с проверкой кода выхода, объект со списком и добавление элемента по ключу, перевод сотрудника в другое подразделение, код с параметрами из файла, какие значения приходят в ответе и что учесть в Windows PowerShell 5.1. Новый пример examples/export-csv.ps1; examples/sdk.mjs перебирает строки через queryRows. В docs/sdk.md — queryRows вместо своего цикла по страницам и раздел «Значения».
  • docs/installation.md описывает, как включить плагин в Claude Code только в отдельных проектах: --scope local и --scope project.
  • docs/compatibility.md: загрузка частями оставляет на сервере пустую папку filechunk/<fileId>, как и загрузка большого файла в админке.

Исправления:

  • У ошибок SDK в name имя класса: HcmStoredResultError, HcmOperationError, HcmCleanupError. Раньше у всех было HcmError. Подсказка HcmStoredResultError называет методы SDK readResult и exportResult и loadConfig({ settings: { outputLimitBytes } }), а не операции и инструменты MCP.
  • Сбой в коде самого клиента отвечает INTERNAL_ERROR. Раньше часть таких сбоев приходила как INVALID_ARGUMENT с английским сообщением движка JavaScript и подсказкой про аргументы, хотя аргументы были в порядке. Отказы по аргументам остались INVALID_ARGUMENT с прежними текстами. Подсказка у INTERNAL_ERROR говорит, что это дефект клиента и подбирать аргументы не нужно; то же сказано в теме гайда errors.
  • Отказы по аргументу, у которых был английский текст Node, получили русский: неверные path и headers у *.experimental.rawRequest, значение в params у execute.script, которое нельзя записать как JSON, нулевой символ в path у results.export. Неверный method у *.experimental.rawRequest отклоняется до запроса как INVALID_ARGUMENT, а не как PLATFORM_HTTP. objects.get по адресу файла не в UTF-8 отвечает INVALID_XML с подсказкой про files.read.
  • Неизвестный ID операции CLI и MCP-сервер называют в ошибке так, как его передали, а похожие на него — ID операций. Раньше в них подставлялись имена команд или инструментов: wtctl api call api.list отвечал «Операции wtctl api list нет». Ошибки, которые CLI получает до вызова операции, тоже называют команды CLI.
  • Подсказка TARGET_MISMATCH не говорит «Запись не отправлена»: так было и у objects.get, где записи нет, и после записи с исходом indeterminate. Подсказка CATALOG_MISMATCH у objects.delete тоже больше не говорит об исходе. Его сообщает mutationOutcome.
  • Отказы по аргументу, которые шлюз находит до отправки, у низкоуровневых операций записи и выполнения кода отвечают mutationOutcome: not_sent, а не indeterminate: недопустимый в XML символ у native.lds.* и web.lds.*, path, headers и method у *.experimental.rawRequest, dbName у native.physicalDocuments.createFromXml.
  • native.resources.getImage и web.resources.getImage не оставляют соединение, которое сервер закрывает после картинки. Раньше на только что запущенном сервере следующий запрос в это соединение обрывался: PLATFORM_HTTP «Соединение оборвалось». Так бывало на серверах 2025.1.1171 и 2025.1.1333.
  • objects.create с dbName, которого нет на сервере, отвечает INVALID_ARGUMENT до выдачи ID, исход — not_sent; подсказка называет базы сервера. Раньше сервер выдавал ID, запись отвечала HTTP 500 с исходом indeterminate, а подсказка говорила о значении поля.
  • wtctl query --fields id,fullname без кавычек работает в PowerShell: списки --fields, --ids, --order, --origin и --include делятся и по запятой, и по пробелу. Раньше PowerShell передавал id,fullname команде через обёртку npm как id fullname, и поиск отвечал INVALID_FIELDS. В --order desc и asc остаются при поле перед ними.
  • Поля строки ответа query идут в порядке fields. Раньше пустое поле, которое сервер в строке опускает, вставало в конец, и столбцы выгрузки перемешивались.
  • Подсказка WRITE_DISABLED и EXECUTE_DISABLED говорит, где подключению включить право: permissions.write или permissions.execute у подключения с таким-то именем в файле подключений (из --config или WTCTL_CONFIG, иначе путь показывает wtctl config path), переменная WTCTL_ALLOW_WRITE или WTCTL_ALLOW_EXECUTE у подключения из переменных, settings.permissions у подключения из loadConfig({ settings }). Раньше подсказка отсылала к «настройкам подключения». docs/configuration.md предупреждает, что config init --force создаёт подключение заново и теряет остальные его поля.
  • UNKNOWN_CONNECTION называет файл подключений и источник имени: --connection или аргумент connection, переменная WTCTL_CONNECTION, defaultConnection файла или имя default по умолчанию. Раньше имя из забытой WTCTL_CONNECTION было не отличить от выбранного. Ошибка в имени подключения тоже называет его источник.
  • docs/installation.md: MCP-сервер проекта в Claude Code до разрешения помечен в claude mcp list как Pending approval, а не Connected.
  • Примеры JSON в справке команд записаны как '{\"…\"}', как в docs/cli.md: в таком виде они работают и в Windows PowerShell 5.1.
  • Ошибки разбора командной строки (cli.invalid_input) называют справку той команды, где ошибка: wtctl help query, а не wtctl help <группа>. Неизвестный флаг назван по имени, рядом — похожий настоящий: «Неизвестный флаг --feilds», «Похожий: --fields». Значение флага не печатается. Подсказка про пароль в командной строке — только у флагов вроде --password и --token. Тексты ошибок переписаны без английских слов: например, удаление без --permanent объясняет, что корзины нет.
  • Подсказка READ_BACK_MISMATCH у objects.delete на сервере 2025.2 с MS SQL называет причину и выход: такой сервер не удаляет документы, пока после запуска или простоя не сохранён ни один документ, поэтому нужно сохранить любой документ (objects.patch с resave:true) и повторить удаление. Раньше это было сказано только в теме гайда objects. На других серверах подсказка прежняя.
  • У операций чтения в ошибке нет поля mutationOutcome: раньше часть отказов приходила с not_sent, хотя записи не было. RUNTIME_CLOSED у записи и выполнения кода отвечает not_sent; раньше исхода в нём не было.
  • Файл подключений, где connections, подключение или permissions — не объект, отвечает INVALID_CONFIG, а не INVALID_ARGUMENT.