ИИ-помощник

Ассистентские услуги

@cadcamfun/ai обеспечивает доступ к модели, события диалога, каталог действий, подсказки, навыки, сборку контекста и интеграцию с хостом. Механизм диалога по умолчанию встроен в nikcli; AI SDK v7 обеспечивает прямые текстовые, потоковые вызовы и вызовы со структурированным выводом. Sidecar внедряет обработчики для мутаций проекта, библиотек, истории и хранилища приложений.

Чат может проверять и изменять проект с помощью зарегистрированных действий. Генерация заголовков без сохранения состояния, анализ конструкции, рекомендации по параметрам, оптимизация G-кода и сводки предложений по дизайну возвращают рекомендации или структурированный вывод; эти методы обслуживания не сохраняют изменения проекта. Прежде чем полагаться на них, просмотрите сгенерированные рекомендации по обработке с помощью детерминированной CAM и проверки.

Разговоры и управление сеансом

POST /api/ai/chat/stream генерирует типизированные события для текста, рассуждений, состояния поворота/шага, вызовов и результатов инструментов, диагностики, вопросов, запросов разрешений, повторных попыток, изменений контекста, целей, завершения и ошибок. Идентификаторы клиентских сеансов привязаны к хост-сессиям и сверяются с их проектом. Сохраните идентификатор сеанса, чтобы продолжить тот же разговор.

POST /api/ai/sessions/state восстанавливает состояние занятости, накопленный текст и информацию о задачах после отключения потока. /api/ai/chat/queue допускает продолжение активного разговора; /api/ai/chat/abort останавливает поворот и связанных с ним рабочих. Удаление сеанса отменяет и присоединяет его дочерние элементы перед удалением сеанса узла.

/api/ai/sessions/control поддерживает статус, подробную проверку контекста, уплотнение, консолидацию памяти, отмену задач, решения о разрешениях, а также ответы или отклонение ожидающих вопросов. Запросы проверяются по родительскому диалогу и его дочерним сеансам. На вопрос, который больше не находится на рассмотрении, нельзя ответить, повторно используя его старый идентификатор.

Прямые вызовы модели повторяют временные сбои поставщика с той же кривой, что и nikcli: первая задержка составляет 2 секунд и удваивается при каждой попытке, собственная задержка поставщика retry-after заголовок учитывается, и без него задержка никогда не превышает 30 секунд. По умолчанию запрос выполняет не более пяти вызовов, включая первый; тот retryAttempts настройка может переопределить это (packages/ai/src/retry.ts, direct-model.ts). Когда соединение с моделью прерывается в середине поворота, цикл чата возобновляется до пяти раз с той же паузой 2–30 секунд и просит модель продолжить, не повторяя выполненные шаги.

Поставщики и учетные данные

GET /api/ai/providers перечисляет метаданные поставщика и настроенное состояние; GET /api/ai/models открывает каталог выбора модели с дополнительными configuredOnly=true. Чтения каталога встроенного хоста кэшируются на одну минуту. Конфигурация и политика влияют на то, какие поставщики будут перечислены и доступны для использования.

Установите учетные данные с помощью PUT /api/ai/credentials и удалите их с помощью DELETE /api/ai/credentials/:provider. Ключи не должны быть пустыми, а предоставленный базовый URL-адрес должен быть HTTP или HTTPS. Фабрика прямых моделей поддерживает Anthropic, OpenAI, MiniMax и шлюз AI. Для других идентификаторов провайдеров для прямых вызовов требуется базовый URL-адрес, совместимый с OpenAI. Встроенный хост использует собственный каталог поставщиков и маршрутизацию.

Сайдкар сохраняет учетные данные по адресу <dataDir>/ai/credentials.json используя временный файл, режим только для владельца 0600 и переименуйте. Отсутствующий или поврежденный файл считается пустым. Неудачная постоянная запись оставляет ключ доступным для текущего процесса, но не гарантирует, что он выдержит перезапуск. Ответы о состоянии раскрывают состояние конфигурации, а не необработанные ключи.

Полномочия представлены с помощью Redacted внутри служб и распространяется на хост через приемник учетных данных с заданной областью. Закрытие области очищает копию хоста. Изменения учетных данных обновляют версию, используемую для различения кэшированных результатов без сохранения состояния.

Уровень модели по умолчанию: balanced, а запросы MiniMax переходят к https://api.minimax.io/v1 пока не CADCAMFUN_AI_MINIMAX_BASE_URL переопределяет это (packages/ai/src/models.ts). Каталог моделей взят из публичного доступа. https://models.dev/api.json конечная точка только тогда, когда кэшированный файл отсутствует и доступ к сети разрешен; учетные данные не отправляются, ответы ограничены 8 МиБ, а тело, в котором указано менее 20 поставщиков, отклоняется как усеченное.

Действия и разрешения

Каталог действий объявляет каждый идентификатор действия, схему параметров, эффект и путь выполнения. Действия, связанные с группой инструментов, за обязательным action поле. Хост проверяет входные данные инструмента, а обработчики дополнительных функций выполняют проверку домена и доступ к ресурсам перед сохранением изменений.

Режимы разрешений: approve, ask, и auto. Они влияют на то, как принимаются обычные вызовы инструментов; инструменты, содержащие деструктивные действия, сохраняют правило одобрения человеком в каждом режиме. Входной флаг, например confirm: true не заменяет этот запрос разрешения. Хост не предоставляет неограниченную оболочку или инструменты редактирования файлов вместо действий приложения.

Политика в <dataDir>/ai/policy.json ограничить использование поставщика, использование инструментов и доступ к мосту. Они загружаются конфигурацией сервиса; не предполагайте, что редактирование файла обновит уже работающую службу. Временные каталоги на уровне проекта и изолированная конфигурация nikcli позволяют отделить встроенный хост от состояния автономного агента пользователя.

Навыки включают в себя сборники CAD/CAM и инструкции, написанные пользователями. Они направляют использование существующих инструментов; добавление навыка не добавляет новый API мутации. Конечные точки HTTP навыков отображают, сохраняют и удаляют содержимое поддерживаемых навыков пользователя.

Зарегистрированные группы инструментов

Встроенные группы cad, cad_edit, cam, cam_edit, library, parts, library_edit, memory, memory_edit, research, vcs, vcs_edit, и agent. cam_verify предоставляет подмножество генерации и проверки, необходимое для роли проверяющего, без предоставления полного инструмента редактирования CAM.

Группировка инструментов сохраняет границы эффекта. Проверка геометрии только для чтения, поиск в библиотеке и вызов памяти отделены от изменений в этих ресурсах. Внедренный реестр также может поддерживать инструменты расширения; повторяющиеся идентификаторы отклоняются.

Откройте для себя текущий каталог

GET /api/ai/actions возвращает описания инструментов, имена и виды действий, а также схемы параметров JSON для внешних вызывающих объектов. Используйте его для обнаружения действий работающего приложения вместо копирования статического списка в клиент. POST /api/ai/actions/invoke принимает идентификатор проекта, идентификатор инструмента и входные данные, содержащие дискриминатор действий.

Записи встроенного каталога хранятся в packages/ai/src/actions. Примеры включают проверку CAD и параметрические проверки, редактирование CAD, планирование и производство CAM, поиск и обновление библиотеки, память проектов, исследования и предложения VCS. Вклад, требующий службы приложения, возвращает недоступный результат, если этот хост не предоставил свой обработчик.

API публичной интеграции

ACTION_CATALOGUE, ACTION_TOOL_IDS, EXPOSED_TOOL_IDS, actionById, toolKind, и runAction поддержка потребителей каталога. ToolHandlers — контракт на интеграцию сайдкара; ToolRegistry состоит из встроенных и расширяющих инструментов. AiService предоставляет разговоры, метаданные модели, одноразовые вызовы и операции сеанса.

assembleContext составляет контекст хода с совокупным бюджетом по умолчанию в 24,000 символов. Он упорядочивает постоянные требования, текущие наблюдения, снимки пользовательского интерфейса, память и вспомогательные ссылки, выполняет дедупликацию по идентичности и содержимому, а также записывает пропущенные или сокращенные источники. Этот бюджет контекста отделен от полного окна токена модели и порога сжатия хоста.

Справочная работа и доказательства

Планировщик времени выполнения позволяет выполнять четыре активных фоновых задачи и шестнадцать задач в очереди. Задачи принадлежат проекту и родительскому сеансу. Отмена сохраняет активное право собственности до тех пор, пока работник не остановится; остановка или удаление родительского элемента также останавливает связанную с ним работу. Восстановление рабочего процесса чтения ограничено двумя попытками, а прерванная работа по редактированию помечается как неопределенная, а не воспроизводится вслепую.

Успех инструмента Assistant — это результат проверки. Операции САПР могут возвращать частичную диагностику геометрии; Артефакты CAM имеют свои собственные претензии и уровни выпуска; Службы истории обеспечивают соблюдение защищенных ветвей. Текст разговора, задание, помеченное как выполненное, и результат геометрической проверки описывают разные доказательства.

Контекст проекта, отправляемый в модель, ограничен бюджетом: сохраненный документ контекста проекта может содержать до 8,000 символов, из которых 2,000 достигают приглашения, причем 1,500 символов каждый соответствует памяти проекта и привычкам пользователя. Примечания к проекту старше 90 дней, на которые не ссылается контекст проекта, удаляются после завершения сеанса (packages/ai/src/project-context.ts).

Выбор времени выполнения

CADCAMFUN_AI_HOST выбирает nikcli по умолчанию или direct. Прямой путь использует вызовы AI SDK без встроенного цикла инструментов постоянного агента и специального планировщика. Операции без сохранения состояния используют службу прямой модели, даже если встроенный хост включен.

Каталоги XDG хоста и дополнительное переопределение домашнего адреса находятся в папке <dataDir>/ai/nikcli. Загрузка конфигурации проекта и несвязанные унаследованные настройки агента отключаются или очищаются перед импортом SDK. Его рабочая область представляет собой рабочий каталог приложения для каждого проекта, а не исходный каталог пользователя.

Автономный доступ к nikcli

@cadcamfunv2/cadcamfun-nikcli-plugin подключает автономный nikcli к работающему приложению. Настройте его url, tokenи по умолчанию projectIdили используйте CADCAMFUN_URL, CADCAMFUN_TOKEN, и CADCAMFUN_PROJECT. Предоставьте токен моста с определенной областью действия, выданный приложением для внешнего доступа.

Токены моста ограничены одним проектом и доступны только для чтения или чтения/записи. По умолчанию они составляют 30 дней, разрешают 1–365 дней, могут быть внесены в список и отозваны, а их секрет раскрывается только при их выпуске. Они допускают только два маршрута действия моста. Политика может еще больше сузить видимые инструменты и действия.

Плагин извлекает каталог из приложения и преобразует его схемы в аргументы инструмента nikcli. Деструктивные действия отвергаются даже при наличии флажка подтверждения, а незавершенный процесс agent инструмент делегирования исключен. Инструменты расширения плагинов с возможностью записи не доступны через этот внешний мост. HTTP 401 сообщает об отклонении токена; отказы в действиях возвращают читаемые результаты ошибок.

Карта реализации

service.ts владеет операциями ИИ, связанными с приложениями; direct-model.ts владеет вызовами AI SDK; credentials.ts владеет ключевым состоянием; nikcli/ владеет изоляцией, сессиями, политиками, контекстом и воркёрами; actions/ и tools/ собственные определения возможностей и адаптеры. Сайдкар services/ai.ts обработчики и хранилище проектов проводов. packages/nikcli-plugin владеет внешним HTTP-клиентом.

Начать и восстановить разговор

При работающем сопровождении и настроенной модели этот запрос открывает диалог без внедрения сохраненного контекста рабочей области. Набор CADCAMFUN_URL к обнаруженному базовому URL-адресу обратной связи и CADCAMFUN_TOKEN к его текущему токену приложения. Идентификатор сеанса, указанный ниже, выбирается клиентом; сохраните его для последующих действий.

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"message":"Explain the difference between G0 and G1.","sessionId":"inspection-demo","includeContext":false,"mode":"gcode"}' \
  "$CADCAMFUN_URL/api/ai/chat/stream"

Для поворота проекта также укажите его реальный projectIdи, необязательно, drawingId принадлежащие этому проекту. Чертеж привязывает инструменты поворота к этому рисунку. Повторное использование сеанса под другим проектом или учетной записью запрещено.

curl --fail-with-body \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"sessionId":"inspection-demo"}' \
  "$CADCAMFUN_URL/api/ai/sessions/state"

Возвращенный busy, text, необязательный events, и tasks восстановить вид; воспроизведение этих сохраненных событий не приводит к повторному запуску инструментов. Чтобы остановить работу, отправьте явное прерывание. Закрытие потока само по себе не присоединяется к работникам диалога.

Источник: packages/api/src/groups/ai.ts, apps/sidecar/src/http/ai.ts, и packages/ai/src/service.ts.

Обрабатывайте события без потери состояния

Элементы управления сеансом принимают только ожидающие идентификаторы разрешений/вопросов в этом разговоре или его дочерних сеансах. Вопрос требует непустых ответов; вопрос с одним выбором отклоняет несколько выбранных значений, а вопрос, который запрещает пользовательские ответы, принимает только указанные метки вариантов.

Источник: packages/api/src/ai-events.ts, packages/ai/src/nikcli/session-controls.ts, и packages/ai/src/heartbeat.ts.

Вложения и навыки пользователя

Каждый запрос в чат принимает до пяти вложений. Поддерживаются изображения PNG, JPEG, WebP и GIF с ограничением 5 MiB для каждого; PDF-файлы имеют ограничение в размере 10 МБ. Текстовые вложения принимают до 2,000,000 символов, при этом тексты длиной до 6,000 символов также включаются в строку. Неподдерживаемые файлы вызывают причину отклонения, а не исчезают молча.

Текстовые вложения хранятся в хранилище в памяти проекта для инструментов импорта: не более 32 имен и 8,000,000 символов для каждого проекта и 32,000,000 символов в не более чем 64 сохраненных проектах. Повторное использование имени заменяет его предыдущий текст. При перезапуске службы это хранилище вложений не сохраняется. Преобразование поставщика сообщает модели о несоответствии возможностей PDF.

Названия навыков пользователей представляют собой слова из строчных букв и цифр, соединенные дефисами, но не более 64 символов. Ограничения описания и тела составляют символы 300 и 20,000 соответственно; Можно загрузить не более 50 навыков пользователя. Встроенные навыки нельзя удалить через API навыков пользователя. Сохраненный навык live результат указывает, вступила ли в силу перезагрузка хоста.

Источник: packages/ai/src/attachments.ts, packages/ai/src/skills/user.ts, и apps/sidecar/src/http/ai.ts.

Диагностика сбоев помощника

• Нет настроенной модели: проверять /api/ai/status и /api/ai/providers, затем установите ключ для указанного поставщика. Настроенный флаг доказывает, что сохраненный ключ существует, а не что поставщик принял его.
• Неизвестный провайдер или неверный URL: используйте объявленный идентификатор поставщика и базовый URL-адрес HTTP(S). Невстроенному прямому поставщику помимо ключа требуется совместимая конечная точка.
• Сеанс недоступен: восстановиться, используя исходный идентификатор проекта/учетной записи/сеанса. Не придумывайте заменяющий идентификатор проекта для существующего сеанса хоста.
• Очередь ждет бесконечно: проверьте состояние управления сеансом на наличие ожидающих разрешений или вопросов, прежде чем повторять повторный запрос. Используйте явное прерывание, чтобы отменить ход и присоединиться к его работникам.
• Инструмент частично изменил модель: проверить его tool_diagnostic, включая mutationApplied, затем прочитайте текущий рисунок. Повторная попытка редактирования без проверки его результата может привести к дублированию геометрии.

Результаты инструмента и типизированные ошибки сохраняют этап, на котором произошел сбой. Ошибка провайдера после успешных инструментов не откатывает эти мутации проекта. Детерминированные проверки CAM и истории остаются доступными отдельно от ответа модели.

Справочник по конечной точке Ассистента

Все вспомогательные маршруты находятся под /api/ai и требуется токен носителя приложения. Токен моста для автономного nikcli открывает только список действий и маршруты вызова и только для его проекта.

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

Поля запроса потоковой передачи

Ограничения и значения по умолчанию

Полный каталог действий

Помощник действует посредством 83 объявленных действий в 13 семействах. Каждое действие объявляет свою схему результата и ее эффекты: что он меняет или достигает помимо чтения открытого документа. Читай семьи(cad, cam, library, memory, research, vcs) в основном не имеют эффекта; их _edit аналоги меняют постоянное состояние. Эффекты указаны в скобках.

Действие чтения может иметь только interface или external; каждая запись называет по крайней мере один постоянный эффект. Эффекты объявляются для каждого действия и никогда не выводятся из инструмента, который его реализует.

Как заканчивается призыв к действию

Записи привязаны к версии чертежа. Зафиксированная запись возвращает ActionCommitted квитанция с previousRevision и revision; запись против устаревшего expectedRevision возвращает ActionConflict с обоими expectedRevision и actualRevision. Та же классификация (actionOutcome) используется хостом, кодовым режимом, рабочим столом и мостом.

{
  "ok": false,
  "_tag": "ActionConflict",
  "actionId": "cad_edit.modify",
  "projectId": "…", "drawingId": "…",
  "expectedRevision": 41, "actualRevision": 42,
  "message": "…"
}

Через 3Д