Repository navigation
Releases
wtctl 0.7.0
files.delete и files.list работают в wt_data и trash, когда сервер хранит эти папки в базе данных: файл, записанный files.write, виден в списке и удаляется тем же вызовом, что в веб-админке. Кроме того, исправлены исходы записи: native.physicalDocuments.createFromXml после сброса сессии не создаёт второй документ, objects.patch и objects.delete с id и url разных объектов отвечают отказом, а не правят объект по url, а 0x… считается ID только у целых полей формы. Значения заголовков авторизации и cookie в тексте ошибки закрываются целиком, а MCP-сервер без настроек проверяет первый вызов по его аргументам. Скрипты, которые правят документ объекта через files.write, нужно сверить с разделом «Несовместимые изменения».
Несовместимые изменения:
files.deleteиfiles.writeв любой папке отклоняют адрес документа объекта (x-local://<папка>/objects/<14 hex>/<2 hex>.xml):FILE_IS_DOCUMENT, исходnot_sent. Подсказка называетobjects.delete,objects.patchиnative.lds.putDoc. Раньше запись по такому адресу меняла документ, но не строку каталога.files.readчитает документ по адресу, как прежде.native.physicalDocuments.createFromXmlвыполняет runtime (HcmClient, CLI, MCP-сервер);NativeGatewayизwtctl/nativeеё больше не перечисляет и не вызывает. Вwtctl/protocolостаётсяsession.physicalDocuments.createFromXml.
Добавлено:
files.deleteудаляет файлы вwt_dataиtrash, если сервер хранит эти папки в базе данных (DB-STORE-HOOKв его настройках), — тем же вызовом, что веб-админка, под правомwrite. Раньше там был отказFILE_NOT_DELETABLEдо отправки. ТеперьFILE_NOT_DELETABLEс исходомindeterminateозначает, что по адресу остался файл или пустая папка на диске сервера: с диска сервер по адресу ничего не удаляет. Адрес длиннее 256 знаков в такой папке —INVALID_ARGUMENTдо отправки.files.listвwt_dataиtrash, если сервер хранит эти папки в базе данных, показывает и файлы из базы: файл — с размером, «папку» — если в базе есть адреса глубже неё. Файл с копией в базе и на диске — одна строка, размер — копии из базы, которую отдаётfiles.read.FOLDER_NOT_FOUND— только если по адресу нет ни папки на диске, ни файлов в базе. Раньше список показывал только диск: файла, записанногоfiles.write, в нём не было, а папка с одними такими файлами отвечалаFOLDER_NOT_FOUND.
Изменения:
web.resources.getImageиnative.resources.getImageпринимают ID ресурса и в записи0x…, в которой его отдают каталоги, и сами переводят его в десятичную запись для сервера. Раньше такой ID отклонялся с «значение записано неверно».files.deleteв папке данных сначала проверяет адрес не длиннее 256 знаков: если по нему ничего нет, ответ —FILE_NOT_FOUNDс исходомnot_sent, на сервер ничего не уходит. В папке в базе данных подсказка говорит, что вложенных папок там нет и файлы удаляются по одному. Раньше в обычной папке данных сервер отвечал отказом HTTP 500.
Исправления:
native.physicalDocuments.createFromXmlпосле сброса сессии сервером входит заново и повторяет только отклонённый запрос: документ записывается один раз, ответ —okс его ID. Раньше клиент повторял всю операцию и создавал второй документ, а если сессию открыл сам вызов — отвечалnot_sentпри записанном документе. Если после записи войти заново не удалось, исход —indeterminate, иdetails.urlназывает адрес документа.- Отказ отправленного
rpc.callдаётUNKNOWN_RPC_TARGETиnot_sent, только когда библиотека прочитана целиком и функции в ней нет или такой библиотеки нет на сервере. Если файл библиотеки прочитать не удалось или он лежит в базе данных, остаётся ошибка сервера и исходindeterminate: функция могла выполниться. - Запись и код с исходом
indeterminateпосле обрыва соединения, таймаута или потери связи подсказывают проверить, прошла ли запись, прежде чем повторять; у таймаута — ещё увеличитьtimeoutMsподключения. Раньше подсказка советовала повторить. - Шаг записи в
runtime.batch, который отказал до отправки из-за неразрешимой$ref, получаетmutationOutcome:"not_sent". objects.get,objects.patchиobjects.deleteсidиurlразных объектов отвечаютTARGET_MISMATCHдо записи и у документов без<id>или с пустым<id>, как у штатных справочников:idсверяется с ID в адресе документа. Если и адрес ID не называет, сверить нечем — тожеTARGET_MISMATCH. Раньше такой вызов правил и удалял объект поurl, а отвечал с ID изid. Сообщение называет ID объекта из документа или адреса.objects.createиobjects.patchбезformUrlберут форму, которую сервер объявляет для типа, какschema.get. Объекты типов тестирования (assessmentи других), форма которых лежит внеx-local://wtv, создаются безformUrl; раньше создание отказывало.0x…и десятичная запись считаются одним ID только у целых полей формы. У строкового поля значения сравниваются как есть:objects.patchс ключом[code=0x1F]не трогает элемент с ключом31, замена31на0x1Fзаписывается, условиеruntime.queryсо значением"0x10"ищет строку. Вcontainsзначение всегда строка. Раньше0x…превращалось в число у любого поля. Если форму прочитать не удалось, ID узнаётся по виду значения, как прежде.- Временный отказ чтения формы, файла языка, переводов названий типов и документа с настраиваемыми полями не запоминается: следующий вызов читает их заново. Раньше после такого отказа MCP-сервер не видел восстановления сервера до перезапуска.
runtime.check(hcm_check,wtctl check) отвечает на шагеqueryfailedс причиной «база данных отвергла запрос; причина — в логе spxml_unibridge», если база отвергла пробный запрос. Раньше такой шаг считался пройденным.schema.types, если документ с настраиваемыми полями прочитать не удалось, не показывает в строкахcustomFieldsи называет это вnotes. Раньше у всех типов былоcustomFields: 0.hcm_scriptс файлом не в UTF-8 отвечаетmcp.file_unreadable«Файл с кодом должен быть текстом UTF-8.» и ничего не отправляет на сервер, какwtctl exec --input-file. BOM в начале файла убирается. Раньше кириллица файла в Windows-1251 молча превращалась в знаки U+FFFD и уходила на сервер, а BOM оставался в коде.- Значения заголовков
Authorization,Proxy-Authorization,CookieиSet-Cookieв тексте ошибки сервера — вdetails.scriptError, сообщении и SOAP Fault — закрываются до конца строки. Раньше закрывалось только первое слово: отAuthorization: Bearer …оставался токен, отCookie— все пары после первой. - MCP-сервер, запущенный без настроек, с первого вызова проверяет инструмент по эффекту вызова с его аргументами:
hcm_api_readсnative.lds.loadDocиtryLock:trueотвечаетmcp.effect_mismatchи ничего не отправляет на сервер. Раньше первый вызов после появления настроек проверялся без аргументов, и блокировка проходила через инструмент чтения в обход одобрения записи в приложении. Одновременные первые вызовы такого сервера создают одно подключение, а не по одному на вызов; при закрытии сервера оно закрывается. - Превью сохранённого ответа
runtime.batchпомещается вoutputLimitBytes: вpreview.results— сводки первых шагов, пока помещаются, а подсказка говорит, сколько их из всех, как у спискаitems. Раньше превью пакета из многих шагов перечисляло все шаги и бывало больше предела. - Сохранённый ответ пакета из одного шага читается по шагам и выгружается в
jsonlодной строкой. Раньшеresults.exportсformat:"jsonl"отвечалINVALID_RESULT_FORMAT. Шаг больше страницыresults.readназван вblockedItem, и ответ называет списокresults. - XML-аргумент
rpc.callиnative.*, который начинается с декларации<?xml …?>, как документ, прочитанный черезfiles.read, уходит внутри SOAP без неё; во вложении (native.lds.putDoc) и в загружаемом файле декларация остаётся как есть. Декларация в другом месте аргумента —INVALID_ARGUMENTдо отправки, исходnot_sent. Раньше декларация попадала внутрь SOAP, и сервер получал неверный XML. Вwtctl/protocolдекларацию не в начале так же отклоняетrawXml(). maxResponseBytesв параметрах отдельного вызоваwtctl/protocolдействует у всех SOAP-вызовов (lds,rpc, фоновые задачи) и у страницы/admin: меньший предел отклоняет большой ответ,Infinityснимает предел клиента. Раньше у этих вызовов работал только предел клиента.rpc.listиrpc.describeчитают файл библиотеки в той кодировке, которую выбирает сервер: по метке порядка байтов, иначе поencodingв объявлении<?xml …?>, иначе как UTF-8. Библиотека в Windows-1251 с кириллицей больше не попадает вskipped.rpc.describeфункции из библиотеки, файл которой прочитать не удалось, отвечает «Библиотеку … прочитать не удалось, описания функции … нет.» и подсказывает, чтоrpc.callвызывает функцию и без описания. Раньше сообщение говорило, что такой библиотеки на сервере нет.schema.getиschema.types, если файл языка прочитать не удалось, не показывают заголовков, которые берутся из него, и говорят об этом одним примечанием вnotes: «Файл языка … прочитать не удалось: заголовков из него в ответе нет.» Примечание есть и у пустого ответа поискаschema.types: тип мог не найтись по такому заголовку. Заголовки, записанные в форме, и переводы названий типов остаются. Раньше вместо заголовка показывался ключ (title: "const=c_person"),schema.typesискал по нему и примечания не давал.- CLI называет пропущенную или неизвестную команду так, как её набрали, и перечисляет, какие есть, в порядке справки:
wtctl serverотвечает «Не указана команда после wtctl server: есть info.»,wtctl object foo— «Команды wtctl object foo нет: есть get, create, patch, delete.»,wtctl srever— «Команды wtctl srever нет.» с подсказкой «Похожие: server.». Раньше ответ был «Неизвестная команда server.», будто нет самой командыserver, аwtctl result fooиwtctl rpc fooотвечали «Не хватает аргументов команды.».wtctl help sreverотв...
wtctl 0.6.0
Файлы любого размера: files.write пишет их путём настольной админки и сверяет после записи, files.read сохраняет файл сервера на диск, а своих пределов размера ввода, кода и загрузки у клиента больше нет. Кроме того, точнее стали ошибки и подсказки: отказ загрузки по политике сервера — UPLOAD_REFUSED, сбой части загрузки не выдаётся за недоступный сервер, отказы по именам предлагают похожие, hcm_types видит каталоги базы trash. Настройки приложений и скрипты, которые работают с инструментами логов, objects.patch или schema.types, нужно сверить с разделом «Несовместимые изменения».
Несовместимые изменения:
- Инструменты MCP
hcm_log_readиhcm_log_followназываютсяhcm_logs_readиhcm_logs_follow, какhcm_logs_list,hcm_logs_searchи командыwtctl logs …. Вызов по старому имени отвечаетmcp.unknown_tool, подсказка называет новое имя. Разрешение, выданное в приложении по старому имени инструмента, нужно выдать заново. objects.patchотклоняетremoveс путём, которому в документе ничего не соответствует:PATCH_PATH_MISSING, сообщение называет путь, ничего не записано, даже если другие пути вызова нашлись. Сpreview:true— тот же отказ. Раньше такой путь молча пропускался, и опечатку в ключе элемента было не отличить от «удалять нечего». Скрипт, который удаляет элемент, не зная, есть ли он, должен сначала прочитать объект.beforeиafterу структуры вchangesответаobjects.patch— объект с полями первого уровня; вложенные структуры и списки по-прежнему названы, а не скопированы. Раньше это была строка с именами полей:"{collaborator_id}". Предпросмотр удаления элемента списка показывает его ключ и поля.- В ответе
schema.types(hcm_types,wtctl types) нет поляcatalogsс числом каталогов: каталоги без своего типа объекта теперь перечислены в самом списке и входят вtotal. В SDK у строкtypesполяtypeиcustomFieldsнеобязательные. - Если сервер не сообщил списки папок,
files.writeтребует праваexecuteдля любой папки: без списков клиент не отличает папку данных от папки кода. Раньше такая запись шла с однимwrite.
Добавлено:
-
Загрузка (
web.pages.uploadFile,web.pages.uploadChunk,wtctl file upload), которую сервер отклонил по своей политике загрузки, отвечаетUPLOAD_REFUSED. Подсказка называет, какие имена обычно принимает загрузка, и что файл по своему адресу записываетfiles.write. У загрузки частями в сообщении текст отказа сервера; на загрузку одним запросом сервер текст в ответе не передаёт, только пишет в свой лог. Раньше отказ былPLATFORM_HTTPс HTTP 415 или 500 без причины. -
schema.typesперечисляет после типов каталоги без своего типа объекта (group_collaborators,event_collaborators,trash_docsи другие) строками{catalog}безtype, и поиск находит их по имени. Строки таких каталогов строит сервер, документов у них нет; искать в них можно черезhcm_query. Раньше ответ давал только их число, а имя называл, только когда поиск находил его или тип с тем же началом имени. -
files.writeпринимаетfile— полный путь к файлу на компьютере, где работает клиент (у MCP-сервера — где он запущен). Файл читается с диска частями, содержимое не идёт через вызов, и память клиента не растёт с размером файла.wtctl files write АДРЕС --input-file ФАЙЛпередаёт операции путь, в SDK —writeFile({ url, file }). -
files.readсfileсохраняет файл сервера на диск байт в байт, текст или двоичный, любого размера: файл не проходит через ответ,maxResponseBytesна него не действует, и память клиента не растёт с размером файла. Ответ —{bytes, file}с полным путём. Существующий файл заменяется только сoverwrite:true, иначеFILE_EXISTS; недочитанный файл под своим именем не появляется. В CLI —wtctl files read АДРЕС --to ФАЙЛ [--overwrite], в SDK —readFile({ url, file, overwrite }). -
Предпросмотр
objects.patchназывает вserverFilledполя правки, которые сервер заполняет сам при сохранении документа, напримерposition_nameу сотрудника: записанное значение он, скорее всего, заменит. Клиент узнаёт такие поля по коду формы, поэтому список бывает и лишним, и неполным.READ_BACK_MISMATCHпо такому полю называет причину и поле, которое менять вместо него:position_idвместоposition_name.
Изменения:
files.writeпишет файл любого размера в любую папку данных и папку кода, в том числе вwt_dataиtrash, тем же способом, что настольная админка. Запись в папку кода больше не идёт через код на сервере, но по-прежнему требует праваexecute: файл там — код сервера. Пределы 750 КБ текста и 580 КБ двоичных данных убраны, запись больше не отвечаетFILE_TOO_LARGE.- После записи
files.writeчитает файл с сервера и сверяет с отправленным:confirmedзначит, что на сервере ровно отправленные байты, а расхождение —READ_BACK_MISMATCH. Прерванная запись отвечаетindeterminateс сообщением, что файл на сервере может быть пустым или недописанным и запись можно повторить целиком. Если файл записан, а прочитать его для сверки не удалось (например, истёкtimeoutMs), ответ — тожеindeterminate, но сообщение говорит именно это: содержимое на сервере не проверено. files.readполучает файл потоком байт, а не в base64 внутри XML: ответ приходит быстрее, и клиенту нужно меньше памяти. БезfileпределmaxResponseBytesсчитается по размеру самого файла, а файл больше предела отвечаетFILE_TOO_LARGEс подсказкой сохранить его черезfile. Раньше такой файл отвечалPLATFORM_PROTOCOL«Ответ сервера не соответствует ожидаемому виду».- У клиента нет своих пределов размера. Ввод команды
wtctl(--input-file,--stdin,--params-file) больше 8 МБ, код для выполнения больше 1 МБ и загрузкаweb.pages.uploadFileбольше 8 МБ проходят; ошибкиSCRIPT_TOO_LARGEбольше нет, аmaxResponseBytesзагрузку не ограничивает. Размер ограничивают сервер, память и диск компьютера иtimeoutMs: см. раздел «Размер файлов и данных» вdocs/configuration.md. - Запись
files.writeв сотни мегабайт идёт втрое быстрее, а код на сервере в мегабайт уходит вдвое быстрее: клиент не проверяет заново XML, который собрал сам, и быстрее проверяет большие строки. SCRIPT_FAILEDставит исходnot_sentтолько на отказ разбора кода в том виде, в каком его присылают 2025.1 и 2025.2; любая другая ошибка в коде —indeterminate. Подсказка приindeterminateговорит, что код, который только читал, можно повторить, а код, который менял данные, — сначала проверить.- Отказы по именам типов, каталогов и операций предлагают похожие имена и при опечатке в одну букву. У
INVALID_FILTER_OPERATORпоявилась подсказка, аrpc.list, скрыв функции, которые вызываются только из кода на сервере, подсказываетall:true. - Подсказка отказа обрезается на 1000 знаках вместо 500, обрезанные сообщение и подсказка кончаются многоточием. Превью сохранённого ответа показывает столько элементов списка, сколько помещается, а подсказка говорит, сколько из них показано: «первые 40 из 1000».
Исправления:
schema.types(hcm_types) называет каталог и у типов, каталог которых лежит в базеtrash:user_data—user_datas,active_web_template,profiling_record.schema.getпо такому типу отмечает поля каталогаquery:true. Раньше у них не было поляcatalog, а гайд говорил, что каталога нет вовсе.- Отказ
files.deleteвwt_dataиtrash(FILE_NOT_DELETABLE) больше не говорит, что сервер там не удаляет файлы: файл, который записалfiles.write, сервер хранит не на диске, и клиент не отличает его от файла на диске. Сообщение — «В папке wt_data файлы и папки не удаляются.», подсказка советует писать временные файлы вshare. - Сбой части загрузки на сервере (
web.pages.uploadChunk, HTTP 501–503) больше не выдаётся за недоступный сервер. Ответ —PLATFORM_HTTP«Сервер не записал часть файла (HTTP 502).» или, на последней части, «Сервер не собрал файл из частей (HTTP 503).», подсказка — повторить загрузку целиком. Текст сервера не показывается: в нём бывают пути сервера. mcp.invalid_argumentsназывает лишний аргумент: «Аргументы не подходят инструменту: лишний аргумент query.», несколько — «лишние аргументы query, foo». Вdetails.validationу этой причины —keysс именами. Раньше сообщение было общим, а у причины был пустойpath.- Подсказка
WRITE_DISABLEDиEXECUTE_DISABLEDу копии подключения в SDK ({ ...loadConfig(), timeoutMs }) называет подключение и где включить право, как у самого подключения; раньше подсказка была общей. Фраза «MCP-сервер видит правку после перезапуска» осталась только у MCP-сервера: в CLI и SDK её больше нет. files.readбезfileдержит в памяти меньше копий файла: у файла 64 МБ пик памяти клиента — около 300 МБ, раньше около 500 МБ. Ответ и сохранённый результат прежние.files.writeбольше 2 МБ в папку данных записывал обрезанный файл и отвечалconfirmed.- Запись
files.writeвwt_dataне доходила до сервера: ответ былconfirmed, аfiles.readотдавал прежнее содержимое. - Файл в сотни мегабайт
files.readне читал и с большимmaxResponseBytes: клиенту не хватало памяти. - Двоичные данные
{base64}примерно от 3 МБ в загрузке (web.pages.uploadFile,web.pages.uploadChunk) и вnative.lds.putUrlотвечалиINTERNAL_ERROR: проверка base64 в клиенте переполняла стек. - Время запроса, истёкшее посреди ответа сервера, называется таймаутом с подсказкой про
timeoutMs. Раньше ответ говорил, что соединение оборвалось. - Отказ диска при сохранении файла на этом компьютере (
results.export,files.readсfile) — нет прав, места или путь не годится — отвечаетFILE_SAVE_FAILEDс кодом системы. Раньше ответ былINTERNAL_ERRORс подсказкой, что это дефект клиента. - Подключение с
usernameEnvилиpasswordEnv, чья переменная не задана или пуста, отклоняется сINVALID_CONFIG, и сообщение называет переменную. Раньше ответ говорил «не задан пароль», а без обеих переменных подключение открывалось без учётных данных.config init --password-envс нез...
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идут в по...
wtctl 0.4.0
Все тексты клиента — по-русски. Имена инструментов, команд, операций и аргументов, коды ошибок и ответы операций не менялись.
Изменения:
- Описания низкоуровневых операций в
api list,api describeи инструментахhcm_api_*написаны по-русски; раньше они были английскими. У пяти операций вapi describeпоявилось полеdetailsс полным описанием. Страницаapi listвмещает на несколько карточек меньше: её предел считается в байтах. - Сообщения ошибок клиента, шлюза и слоя протокола и сообщения CLI написаны по-русски. Коды ошибок, условия отказов и исходы записи прежние: программе нужно сравнивать
error.code, а не текст. - Комментарии в объявлениях типов пакета (
.d.ts) написаны по-русски. - Описание пакета в
package.jsonнаписано по-русски; английская строка в начале README убрана. - Внутреннее устройство клиента: каждая операция описана одним определением вместе со своим обработчиком, runtime держит только конвейер вызова. Тип ответа методов SDK сверяется с обработчиком операции при сборке. На проверенных серверах ответы CLI и MCP-сервера совпали с 0.3.1.
wtctl 0.3.1
Исправление исхода записи и переработка внутреннего устройства клиента без изменения операций.
Исправления:
- Запись, которую сервер принял, а проверочное чтение отклонил отказом во входе, даёт
indeterminate, а неnot_sent; подсказка говорит, что запрос на запись уже ушёл и что запись нужно проверить, прежде чем повторять. Отказ во входе на первом же запросе по-прежнему даётnot_sent.
Изменения:
- Внутреннее устройство клиента переработано: все запросы к серверу идут через один модуль, исход записи считает один модуль, ответ собирает один модуль. Операции, их аргументы и ответы прежние: на серверах 2025.1.1171 — 2025.2.1535 ответы CLI и MCP-сервера совпали с ответами 0.3.0.
- В типах пакета у конструктора
HcmRuntimeпоявился необязательный второй параметр — способ обращения к серверу. Без него всё работает как раньше.
wtctl 0.3.0
Чистка операций по итогам прогона на проверенных серверах и уточнение прав.
Несовместимые изменения:
- Убраны шесть операций, которые отказывали на всех проверенных серверах:
native.lds.getModDeletedObjects,native.lds.createDoc,web.pages.createDoc,web.pages.getIcon,web.experimental.getUiTemplate,web.lifecycle.logout2. - Убраны операции больших полей:
native.lds.loadLargeField,native.lds.putLargeField,native.lds.deleteLargeField,web.spxml.putLargeField,web.spxml.putLargeFieldFromUrl. На проверенных серверах полей с адресомx-db-obj://нет, и ни одна из этих операций ни разу не отработала. - Убрана группа
native.experimental.spxml(восемь операций): она повторялаweb.spxml.*. Вместо неё —web.spxml.callMethodAsync,getAsyncMethodStatus,killAsyncMethod,getBackgroundTasksByName,getDoc,putDoc. native.lds.getNewObjectIdтребует праваwriteи вызывается черезhcm_api_write: каждый вызов расходует ID.files.deleteв папкахwt_dataиtrashотказывает до отправки (FILE_NOT_DELETABLE): сервер там файлы и папки по адресу не удаляет. В 0.2.2 запрос уходил, и операция отвечалаREAD_BACK_MISMATCH.wtctl/protocol: убраны методы и типы ушедших операций и классNativeExperimentalSpXmlApi.
Изменения:
rawRequestс методом GET или HEAD считается чтением и не требует правwriteиexecute; признакunsafe: trueнужен по-прежнему.- MCP SDK обновлён до 1.31.0.
wtctl 0.2.2
Исправления:
files.deleteпроверяет адрес после ответа сервера. В папках базы сервераwt_dataиtrashсервер отвечает на удаление файла и пустой папки как на успешное, а файл остаётся: раньше операция отвечалаdeleted:trueс исходомconfirmed, теперь —READ_BACK_MISMATCHс исходомindeterminate. Проверено на 2025.1.1333 — 2025.2.1535; в остальных папках данных удаление работает как раньше.
Документация:
- Гайд по файлам и страница совместимости:
wt_dataиtrashсервер читает через память. Файл и папка там по адресу не удаляются, а после перезаписи файлаfiles.readможет отдать прежнее содержимое.
wtctl 0.2.1
Несовместимые изменения:
- Убраны операции
web.spxml.getLargeFieldиnative.experimental.spxml.getLargeField. На сервере 2025.2.1535 вызов с адресомx-db-obj://типа, у которого нет хранилища больших полей, завершал процесс сервера. Операция числилась чтением и не требовала правwriteиexecute; ни на одном проверенном сервере она не отработала. В версиях до 0.2.1 её лучше не вызывать. wtctl/protocol: убраны методыgetLargeFieldи типGetLargeFieldRequest.
Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно.
wtctl 0.2.0
Файлы сервера: запись и удаление в любой папке, куда сервер принимает файлы, и список папки. Убраны операции, которые не работали.
Несовместимые изменения:
- Операции с файлом по адресу убраны:
native.lds.loadUrl,native.lds.putUrl,native.lds.deleteUrl,native.lds.unlockUrl,web.lds.deleteUrl,web.pages.copyUrl. Вместо них —files.read,files.write,files.delete,files.list; копия файла — чтение и запись по новому адресу. - Команды
wtctl file get,file put,file deleteубраны: их заменяютwtctl files read,files write,files delete.wtctl file uploadосталась. - Убраны 16 операций, на всех проверенных серверах они отвечали отказом или не использовались: группа
legacy.xhttp(9 операций),legacy.session.open,legacy.session.close,legacy.experimental.rawRequest,native.lds.eval,web.lds.eval,native.experimental.readDirectory,web.pages.putUrl. Профильlegacyубран целиком. - Ключи подключения
installationIdиinstallationIdFile, переменныеWTCTL_INSTALLATION_IDиWTCTL_INSTALLATION_ID_FILEубраны; оставшиеся в файле подключений ключи игнорируются. wtctl/protocol: убраныLegacySession,XHttpBinaryResponse, типыLegacyCatalogKeyиXHttpResult, методы клиентаopenLegacySessionиwithLegacySession, вид ошибкиxhttp-result, методыNativeLdsApi.unlockUrl,WebLdsApi.deleteUrl,WebPageApi.copyUrl. У двоичного результата больше нет поляrecords.
Новое:
files.writeиfiles.deleteработают в любой папке, куда сервер принимает файлы. Путь клиент выбирает до отправки, по спискам папок самого сервера: в папке данных (share,wt_dataи других) хватает праваwrite; в папке кода (wt,wtv,customи других) файл записывает и удаляет код на сервере, нужныwriteиexecute; в остальные папки запрос не отправляется.files.deleteв папке данных удаляет и пустую папку.files.list— один уровень папки: файлы с размером и вложенные папки;searchоставляет имена с заданной частью. Нужно правоexecute.server.infoназывает папки подключённого сервера:dataFolders,codeFolders.- CLI:
wtctl files write,files delete,files list. SDK:writeFile,deleteFile,listFiles. - Страница docs/compatibility.md: что отличается между версиями сервера и базами, что не работает ни на одном проверенном сервере, что не проверено.
Исправления:
- Синтаксическая ошибка во всём коде для сервера даёт исход
not_sent: такой код сервер не выполняет. Раньше подсказка говорила то же, а исход былindeterminate. files.deleteпо адресу без файла в папке кода отвечаетFILE_NOT_FOUND.results.exportс путём к папке вместо файла отвечаетINVALID_ARGUMENT, а не внутренней ошибкой.
Прочее:
scripts/generate-native-registry.mjs --checkсверяетsrc/native/generated.tsс кодом протокола; проверка входит вnpm run verify.
Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно.
wtctl 0.1.2
Только тексты, код не менялся.
- Гайд по файлам:
native.lds.putUrlиnative.lds.deleteUrlработают только в папках данных сервера. Как положить и удалить файл в папке кода и получить список папки кодом на сервере. docs/security.md:writeбезexecute— не запрет на код: объекты с кодом, например агенты сервера, сервер запускает сам.- README: что проверено на файловой базе.
Плагин, установленный с GitHub, получает эту версию сразу. Пакет в npm обновляется отдельно и может её пропустить.