文档
人工智能助手
项目范围的对话、键入的 CAD/CAM 操作、显式权限以及由应用程序管理的提供商凭据。
从英文自动翻译。 查看英文原文
助理服务
@cadcamfun/ai 提供模型访问、对话事件、操作目录、提示、技能、上下文组装和主机集成。默认的对话引擎是嵌入的nikcli； AI SDK v7 提供直接文本、流式传输和结构化输出调用。 sidecar 注入项目突变、库、历史和应用程序存储的处理程序。
聊天可以通过注册的操作检查和更改项目。无状态标题生成、设计分析、参数建议、G代码优化和设计建议摘要返回建议或结构化输出；这些服务方法不会保存项目编辑。在依赖之前，通过确定性 CAM 和验证查看生成的加工建议。
对话和会话控制
POST /api/ai/chat/stream 发出文本、推理、转弯/步骤状态、工具调用和结果、诊断、问题、权限请求、重试、上下文更改、目标、完成和错误的键入事件。客户端会话标识符绑定到主机会话并根据其项目进行检查。保留会话 ID 以继续相同的对话。
POST /api/ai/sessions/state 在断开流后恢复繁忙状态、累积文本和任务信息。 /api/ai/chat/queue 承认正在进行的对话的后续行动； /api/ai/chat/abort 停止转弯及其相关工作人员。删除会话会在删除主机会话之前取消并加入其子会话。
/api/ai/sessions/control 支持状态、详细上下文检查、压缩、内存整合、任务取消、权限决策以及回答或拒绝待决问题。根据父会话及其承认的子会话检查请求。不再悬而未决的问题无法通过重用其旧标识符来回答。
直接模型调用重试瞬态提供程序故障，其曲线与 nikcli 相同：第一次延迟为 2 秒，每次尝试加倍，这是提供程序自己的延迟 retry-after header is honoured, and without such a header the delay never exceeds 30 seconds. By default a request makes at most five calls, including the first;这 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 网关。其他提供商 ID 需要 OpenAI 兼容的基本 URL 才能直接调用。嵌入式主机使用自己的提供者目录和路由。
sidecar 将凭证保存在 <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 MiB，并且列出少于 20 个提供者的正文将因被截断而被拒绝。
操作和权限
动作目录声明每个动作标识符、参数模式、效果和执行路径。工具将所需的相关操作分组 action 场地。主机验证工具输入，而 sidecar 处理程序在持久更改之前执行域验证和资源访问检查。
权限模式有 approve, ask， 和 auto。它们影响普通工具调用的接受方式；包含破坏性行为的工具在每种模式下都保留了人类批准规则。输入标志，例如 confirm: true 不取代该权限请求。主机不会公开不受限制的 shell 或文件编辑工具来替代应用程序操作。
政策 <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 接受项目 ID、工具 ID 和包含操作鉴别器的输入。
内置目录条目维护在 packages/ai/src/actions。示例包括 CAD 检查和参数检查、CAD 编辑、CAM 规划和制造、库查找和更新、项目内存、研究和 VCS 建议。当主机未提供其处理程序时，需要应用程序服务的贡献将返回不可用的结果。
公共集成 API
ACTION_CATALOGUE, ACTION_TOOL_IDS, EXPOSED_TOOL_IDS, actionById, toolKind， 和 runAction 支持目录消费者。 ToolHandlers 是 sidecar 集成合约； ToolRegistry 组成内置和扩展工具。 AiService 提供对话、模型元数据、一次性调用和会话操作。
assembleContext 使用 24,000 个字符的默认总预算组成回合上下文。它对长期需求、当前观察结果、UI 快照、内存和支持参考进行排序，按身份和内容进行重复数据删除，并记录遗漏或截断的来源。此上下文预算与模型的完整令牌窗口和主机压缩阈值分开。
背景工作和证据
运行时调度程序允许四个活动后台任务和十六个排队任务。任务由项目和父会话拥有。取消保留主动所有权，直到工人停止；停止或删除父级也会停止其关联的工作。读取工作者的恢复仅限于两次尝试，而中断的编辑工作则被标记为不确定而不是盲目重播。
辅助工具的成功是要检验的结果。 CAD 操作可以返回部分几何诊断； 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 客户端。
开始和恢复对话
通过正在运行的 sidecar 和配置的模型，此请求将打开一个对话，而无需注入存储的工作区上下文。放 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.
处理事件而不丢失状态
| 事件 | 消费者行为 |
|---|---|
delta / reasoning | 附加 text 到匹配会话的文本或推理通道。 |
tool_call / tool_result | 关联方式 callId;检查 ok 并独立于助手文本保留诊断信息。 |
permission_request | 显示请求并回复其请求/会话 ID 以及 once, always， 或者 reject. |
question_request | 保留其请求 ID 和问题；通过会话控制为每个问题发送一个答案数组。 |
done | 使用最终的 text 以及可选用法作为完整的响应；不要将整个最终文本附加到已经积累的增量中。 |
error | 展示 message 和 config, provider, aborted， 或者 internal 分类。 |
heartbeat | 保持连接处于活动状态，而不添加内容或声明回合完成。 |
会话控件仅接受该对话或其子会话中待处理的权限/问题 ID。问题需要非空答案；单选问题拒绝多个选定值，而不允许自定义答案的问题仅接受其列出的选项标签。
来源： 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 MiB。文本附件最多接受 2、000、000 个字符，最多还包含 6、000 个字符的内嵌文本。不受支持的文件会产生拒绝原因，而不是默默消失。
文本附件保存在导入工具的项目范围内存存储中：每个项目最多 32 个名称和 8、000、000 个字符，最多 32 个存储项目中的 000、000、64 个字符。重复使用名称会替换其以前的文本。重新启动服务不会保留此附件存储。 PDF 功能不匹配由提供者转换报告给模型。
用户技能名称是由连字符连接的小写字母/数字单词，最多 64 个字符。描述和正文限制分别为 300 和 20,000 个字符；最多可以加载 50 个用户技能。无法通过用户技能 API 删除内置技能。已保存的技能 live result表示主机重载是否生效。
来源： packages/ai/src/attachments.ts, packages/ai/src/skills/user.ts， 和 apps/sidecar/src/http/ai.ts.
诊断助手故障
- 未配置型号： 检查
/api/ai/status和/api/ai/providers，然后为列出的提供商设置密钥。配置的标志证明存储的密钥存在，而不是供应商接受它。 - 未知的提供商或无效的 URL： 使用公布的提供商 ID 和 HTTP(S) 基本 URL。非内置直接提供程序除了其密钥之外还需要兼容的端点。
- 会话无法访问： 使用原始项目/帐户/会话身份进行恢复。不要为现有的主持人会话创建替换项目 ID。
- 一个回合无限期地等待： 在重试重复提示之前检查会话控制状态是否有待处理的权限或问题。使用显式中止来取消轮次并加入其工作人员。
- 一个工具部分改变了模型： 检查其
tool_diagnostic， 包括mutationApplied，然后读取当前绘图。在不检查其结果的情况下重试编辑操作可能会重复几何图形。
工具结果和类型化的失败保留失败的阶段。成功的工具后的提供者错误不会回滚这些项目突变。确定性 CAM 和历史检查仍然可以与模型答案分开使用。
助理端点参考
所有辅助路线都位于 /api/ai 并需要应用程序不记名令牌。独立 nikcli 的桥接令牌仅打开操作列表和调用路线，并且仅针对其项目。
| 路线 | 目的 |
|---|---|
POST /api/ai/chat/stream | 开始流转；响应是辅助事件的 SSE 流。 |
POST /api/ai/chat/queue | 将繁忙会话的后续消息排队。 |
POST /api/ai/chat/abort | 中止正在运行的会话。 |
POST /api/ai/permission/reply | 回答权限请求： once, always， 或者 reject. |
POST /api/ai/sessions/state, /sessions/control, /sessions/remove | 读取会话状态、控制会话、删除会话。 |
GET /api/ai/status, /models, /providers, /agents, /prompts | 发现：准备情况、模型目录、提供者及其配置状态、专家代理、及时建议。 |
PUT /api/ai/credentials, DELETE /api/ai/credentials/:provider | 存储或清除提供商凭据。 |
GET/PUT /api/ai/skills, DELETE /api/ai/skills/:name | 列出、保存和删除用户技能。 |
GET /api/ai/actions, POST /api/ai/actions/invoke | 操作目录和直接调用（也由 nikcli 桥使用）。 |
GET/POST /api/ai/bridge/tokens, DELETE /api/ai/bridge/tokens/:id | 发布、列出和撤销作用域桥接令牌。 |
POST /api/ai/completion | 单次完成： prompt, systemPrompt, model, temperature;回报 text 和 model. |
POST /api/ai/title | 对话摘录的标题。 |
POST /api/ai/design-analysis | 建议与 confidence, priority （低/中/高），以及 kind （优化/警告/严重）。 |
POST /api/ai/machining-parameters | Cutting speed (m/min), feed (mm/min), depth of cut (mm), stepover (%), coolant (flood/mist/none), engagement (conventional/climb), and warnings. |
POST /api/ai/gcode-optimization | 优化的 G 代码，包含每行更改和原因、预计时间和刀具寿命节省以及注释。 |
POST /api/ai/design-suggestions | 下一步建议，包括标题、理由和下一步。 |
POST /api/ai/analyze-gcode | 问题（代码、行和消息的错误/警告/信息）和统计数据：行、快速和剪切移动、工具更改和边界。 |
POST /api/ai/gcode, /toolpath-analysis, /feedback, /proxy | G 代码操作、刀具路径见解、反馈和提供者代理。 |
模型支持的分析回复是类型化形状的模型输出。诸如加工参数之类的值是针对刀具数据和机器限制进行审查的建议，而不是经过验证的切削数据。
流媒体请求字段
| 场地 | 价值观 | Effect |
|---|---|---|
message | 细绳 | 本轮用户的消息。 |
sessionId | 细绳 | 继续现有会话；省略开始一个新的。 |
projectId | 细绳 | 项目轮次使用其上下文和工具。 |
drawingId | 细绳 | 本轮可能会作用的图画。在允许转弯之前，会根据项目对其进行检查，并且转弯的工具仅作用于该绘图，而不作用于其他任何东西。 |
mode | general, cad, cam, gcode, toolpath | 回合焦点。 |
permissionMode | auto, ask, approve | 如何请求工具权限。 |
agent | 细绳 | 专业代理名称来自 /api/ai/agents. |
attachments | [{ name, mime?, data, encoding?: "base64" | "text" }] | 最多 5 个附件：图片最多为 5 MB，PDF 最多为 10 MB，文本最多为 2、000、000 个字符（最多 6、000 个字符的文本文件也会写入邮件中）。 |
context, includeContext | 字符串、布尔值 | 额外的上下文文本以及是否包含组装的项目上下文。 |
model | 型号选择器 | 覆盖本回合的配置模型。 |
限制和默认值
| 限制 | 价值 |
|---|---|
| 组装上下文预算 | 24,000 个字符；不适合的块将被标记截断，而将被剪切到低于 400 个字符的块将被省略 |
| 项目背景文件 | 最多 8,000 个存储字符，2,000 发送到模型 |
| 项目记忆/用户习惯 | 每个 1,500 个字符 |
| 项目笔记 | 当项目上下文未引用时，90 天后进行修剪 |
| 工具输出发送到模型 | 24,000 个字符 |
| 每次调用创建的元素 | 40 |
| 输出代币 | 32,000 最大 |
| 心跳 | 直播期间每 5 秒一次 |
| 精确的几何动作 | 60秒预算；准确报告 1.5 秒 |
| 内核职位 | 120秒截止时间，包括工作人员开始时间 |
| 后台任务 | 4 个处于活动状态，16 个已排队，2 个读取工作线程尝试，已解决的任务保留 7 天 |
| 自动延续 | 每个请求 50； 5 连接恢复，延迟时间为 2–30 秒 |
| 直接调用重试 | 5 调用，包括第一个调用； 2 s 加倍为 30 s，尊重 retry-after |
| 用户技能 | 50 技能；名称最多为 64 个字符（小写单词由连字符连接），描述最多为 300，正文最多为 20，000 |
| 网络搜索获取 | 每个响应 256 KB |
| 桥接代币 | 默认为 30 天，最多 365 天 |
阅读结果，而不是文字
工具的结果是 tool_result 和 tool_diagnostic 事件。在相信助理对其所做操作的总结之前，请先检查是否应用了突变。
完整的动作目录
助理通过 83 个系列中的 13 声明的操作进行操作。每个操作都声明其结果模式及其 效果：除了阅读打开的文档之外，它会改变或达到什么目的。阅读家庭（cad, cam, library, memory, research, vcs) 大多没有影响；他们的 _edit 对应方改变持久状态。效果列在括号中。
| 家庭 | 数数 | 动作（效果） |
|---|---|---|
cad | 20 | describe, check, relations, grep, vision （界面）， inspect_elements, inspect_layers, inspect_search, inspect_property, drawing, parametric_validate, parametric_inspect, parametric_test, parametric_dfm, parametric_exact, exact, assembly, parametric_fastener, parametric_recipe, parametric_from_element |
cad_edit | 12 | add （绘画）， add_entities （绘画）， modify （绘画）， transform （绘画）， group （绘画）， delete （绘画）， editor （界面+绘图）， import （绘画）， parametric_create （绘画）， parametric_update （绘画）， parametric_recipe_create （绘画）， parametric_convert （绘画） |
cam | 14 | plan_check, review, machine, operations, suggest, compare_setups, analyze, stock, vision （界面）， chain_suggest, materials, cutting_data, manufacture, chain_status |
cam_edit | 6 | manufacture （操作+程序）， create （手术）， update （手术）， generate （程序）， verify （报告）， stock_set （库存） |
library | 5 | component_list, lookup_component, lookup_material, lookup_tool, lookup_machine_config |
parts | 3 | save （成分）， insert （绘画）， delete （成分） |
library_edit | 5 | upsert_material （图书馆）， upsert_tool （图书馆）， upsert_machine_config （图书馆）， set_default （图书馆）， delete （图书馆） |
memory | 2 | recall, context_read |
memory_edit | 2 | remember （记忆）， context_update （语境） |
research | 2 | search （外部的）， read_attachment |
vcs | 3 | status, diff, list_pull_requests |
vcs_edit | 5 | start_change （历史）， commit （历史）， restore （历史+图画）， open_pull_request （历史）， run_workflows （工作流程） |
agent | 4 | start （任务）， list, read, cancel （任务） |
| Effect | 意义 |
|---|---|
drawing, component, operation, program, stock, report | 持久的设计或制造数据 |
library, memory, context | 图书馆记录、项目内存、工作空间上下文 |
history, workflow | 版本控制和工作流程运行 |
task | 委托调度程序（后台代理） |
interface | 屏幕上的编辑器或视口；不执着 |
external | 网络（网络研究） |
读取操作可能只有 interface 或 external;每一篇文章都至少有一个持久的效果。效果是根据每个操作声明的，并且永远不会从实现它的工具中推断出来。
行动呼吁如何结束
| 结果 | 什么时候 |
|---|---|
succeeded | 该操作执行了所要求的操作。包括具有负面结果的读取，例如失败的检查。 |
partial | 部分答案或批次： complete: false, omitted > 0,非空 skipped，或一个 nextOffset 到页面 |
refused | 什么也没做： ok: false 有错误或标签（无效输入、被拒绝、不可用、无事可做） |
conflict | 该文件继续说道： ActionConflict 或状态 stale/conflict。重试之前再次检查。 |
cancelled | ActionInterrupted |
uncertain | ActionUncertain：写入可能已提交，但无法读取其答案。通过检查进行核对；切勿盲目重试。 |
写入与绘图修订绑定在一起。提交的写入返回一个 ActionCommitted 收据与 previousRevision 和 revision;写反对陈旧的 expectedRevision 回报 ActionConflict 与两者 expectedRevision 和 actualRevision。同一分类（actionOutcome）由主机、代码模式、桌面和桥共享。
{
"ok": false,
"_tag": "ActionConflict",
"actionId": "cad_edit.modify",
"projectId": "…", "drawingId": "…",
"expectedRevision": 41, "actualRevision": 42,
"message": "…"
}