Skip to content

wtctl 0.6.0

Choose a tag to compare

@ysamtme ysamtme released this 16 Oct 07:39
· 20 commits to main since this release

Файлы любого размера: 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 с незаданной переменной записывает подключение и предупреждает об этом в next.
  • У пропущенного шага execute в ответе check сказано, где подключению включают право execute.
  • В changes ответа objects.patch нет полей, которым записано то же значение, в том числе ID в другой записи и логическое значение, которое сервер хранит как 0 или 1. Раньше пустая правка отвечала noop:true и строками с одинаковыми before и after, а is_dismiss:false у поля со значением 0 уходил на сервер как изменение.