Repository navigation
wtctl 0.5.0
Три темы. Скрипты на команде 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: теперь все поля подключения, кроме адреса, учётных данных и прав, задаются и без файла, в том числе вenvMCP-сервера. Как и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называет методы SDKreadResultи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. В--orderdescи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.