Ассистент по комментариям¶

Результат¶

Когда клиент комментирует спецификацию, открытую ему по ссылке, Threadory готовит черновик ответа и — если замечание того требует — правку документа. Черновик проверяется в разделе Одобрения. Клиенту ничего не уходит и документ не меняется, пока участник команды не подтвердит.

Перед началом¶

Документ — нативный документ с действующей публичной ссылкой, и клиент оставил комментарий через эту ссылку.
У вас роль member или выше: и включение ассистента, и одобрение его черновиков требуют этой роли.

По умолчанию ассистент выключен и включается для отдельного документа, а не для всего проекта.

Шаги¶

Включите ассистент для документа — попросите MCP-клиент вызвать kb_set_document_assistant с doc_line документа и enabled: true (или вызовите PATCH /projects/{project_id}/documents/{doc_line}/assistant с телом {"enabled": true}).
Дождитесь комментария клиента. На каждый новый комментарий или ответ клиента ассистент готовит одно предложение. Он не отвечает:
в закрытом треде;
на короткий ответ вроде «спасибо» сразу после ответа команды;
на комментарии участников проекта.

Черновик готовится по версии, которую комментировал клиент. Предложение — только ответ, а причина указана в обосновании, если:

документ слишком сложен, чтобы менять его безопасно: в нём Markdown вне простого подмножества, которое правит ассистент (сноски, HTML, заголовки с форматированием, вложенные цитаты и т. п.). Это самая частая причина;
клиент комментировал более старую версию, чем текущая;
идёт работа над новым черновиком;
комментарий не привязан к разделу этой версии.

Правки предлагаются только внутри раздела, к которому относится комментарий. Внутренние заметки команды ассистенту не показываются.

Откройте Одобрения и выберите предложение «Reply to a reader on …». Оно помечено как внешнее (customer-facing): одобрение отправляет сообщение человеку вне команды, поэтому страница просит подтвердить. Уведомление в Telegram о таком предложении содержит только ссылку на веб-приложение — без кнопок Approve и Reject.
Прочитайте сводку: сначала предложенный ответ, затем правки (каждая — find → replace), и в конце комментарий клиента между строками BEGIN UNTRUSTED COMMENT TEXT и END UNTRUSTED COMMENT TEXT. Полные поля — reply_text, patch, rationale и confidence.
Выберите действие:
Approve — ответ публикуется в треде от вашего имени, клиент получает его письмом; правки, если есть, записываются новой черновой версией, которая закрывает тред;
Edit payload, затем Edit & approve — измените reply_text, список patch (null — отправить только ответ) или publish_status (draft или in_review) перед отправкой;
Reject — ничего не отправляется и не меняется.
Если правку к моменту одобрения уже нельзя применить — документ успел измениться, исправляемого текста больше нет или хранилище документов на время недоступно, — ничего пока не отправляется. Вместо этого в Одобрениях появляется второе предложение: «Reply only (the change could not be applied): …». В его сводке сказано, почему правка не применилась, и показан одобренный ответ. Одобрите его, чтобы отправить только ответ: документ не меняется, а добавленная в него правка игнорируется. Отклоните — не уйдёт ничего.

Проверка результата¶

В треде на странице документа виден ваш ответ, клиент видит его на публичной странице. Если в предложении были правки, у документа появился новый черновик (или версия на ревью) с заметкой «Addresses 1 comment (§…)», а тред отмечен закрытым в этой версии. Если вместо этого появилось предложение «Reply only …», ответ окажется в треде только после одобрения этого второго предложения; документ останется прежним.

Частые проблемы¶

Симптом	Вероятная причина	Что сделать
После комментария клиента нет предложения	Ассистент выключен для документа, тред закрыт, комментарий — короткое подтверждение или хранилище документов было на время недоступно — тогда ран завершается как `failed` (виден в списке ранов), и новый ран запустит только следующий ответ клиента	Проверьте `assistant_enabled` у документа; переоткройте тред, если нужен ответ; после упавшего рана ответьте на комментарий сами
Одобренный ответ не отправился	Правку не удалось применить (документ изменился, текст больше не совпадает или хранилище было недоступно), и ждёт предложение «Reply only (the change could not be applied): …»	Одобрите его в Одобрениях — ответ уйдёт без правки
По документу ассистент предлагает только ответы	В документе Markdown вне простого подмножества, которое правит ассистент	Внесите правку сами; ответы ассистент по-прежнему готовит
В очень длинном треде черновик упускает сказанное в начале	Тред сокращается до объёма, который ассистент может прочитать: остаются первый комментарий, тот, на который он отвечает, и последние сообщения, а пропуск помечается	Поправьте ответ перед одобрением или ответьте в треде сами
Черновик следует инструкциям из комментария	Текст клиента передаётся как данные, и ассистенту велено игнорировать инструкции в нём, но идеального фильтра нет	Отклоните предложение — без вашего одобрения ничего не уйдёт