API参考

概述

sidecar 是一个单一的 Effect HttpApi。每个端点都是一个类型化的 HttpApiEndpoint 具有模式检查的请求和响应主体，因此该引用、生成的 SDK 和正在运行的服务器来自以下相同的声明 packages/api.

基本网址

没有托管的 CADCAMFUN API。 sidecar 在你的机器上运行，绑定 127.0.0.1 在操作系统选择的端口上（它侦听端口 0），检查自己的端口 /api/health，然后才在标准输出上打印一行 JSON。基本 URL 是 http://127.0.0.1:<port> 从那条线。

export CADCAMFUN_TOKEN=dev-token
CADCAMFUN_DATA_DIR=$(mktemp -d) \
CADCAMFUN_MIGRATIONS_DIR=$PWD/packages/db/drizzle \
CADCAMFUN_AI_OFFLINE=true \
  bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":46709}
export CADCAMFUN_URL=http://127.0.0.1:46709

验证

合同声明了一种安全方案， bearer （HTTP Bearer）。 324 个操作（共 325 个）需要它；仅有的 GET /api/health 是公开的。

curl -s "$CADCAMFUN_URL/api/health"
curl -s "$CADCAMFUN_URL/api/projects" -H "Authorization: Bearer $CADCAMFUN_TOKEN"

惯例

• JSON 输入，JSON 输出。 尸体是 application/json 除非卡片另有说明：两个分段上传、一个八位字节流 Webhook、一个 JavaScript 引导程序、一个 zip 下载、一个二进制插件文件和两个事件流。
• 操作 ID 是点状的。 projects.get, vcs.commit：组标签，一个点，生成的客户端使用的方法名称。
• 键入错误。 每个端点都声明失败并带有 _tag;打开它而不是解析消息。在整个合约中，401 在 269 操作上声明，500 在 264 上声明，400 在 206 上声明。
• 操作锚稳定。 每张卡都可以链接为 #op-<method>-<path>， 例如 /docs/api/projects#op-get-api-projects-id.

流媒体

curl -N "$CADCAMFUN_URL/api/projects/$PROJECT_ID/events" \
  -H "Authorization: Bearer $CADCAMFUN_TOKEN"

客户

@cadcamfun/api/sdk 是从同一个合约生成的：下面的每个操作 id 都是一个类型化方法 CadCam.make(...)，采用路径参数和主体字段的单一输入。生成了 259 操作中的 325；每张卡片都显示其确切的调用。

import { CadCam } from "@cadcamfun/api/sdk"

const client = CadCam.make({
  baseUrl: process.env.CADCAMFUN_URL!,
  headers: { authorization: `Bearer ${process.env.CADCAMFUN_TOKEN}` },
})

const projects = await client.projects.list()
const created = await client.projects.create({ name: "Bracket" })

资源

325 操作位于 35 组中，按其服务内容排列。

核

设计

制造业

资源

扩展

账户

开放API文档

下载 /docs/api/openapi.json （此站点呈现的签入快照）或从正在运行的 sidecar 获取实时文档 /api/openapi.json。重新生成快照 bun run generate:api-reference 中 packages/web 更改端点后。

合约和服务器

@cadcamfun/api 使用 Effect HttpApi 定义请求和响应架构。它导出根 Api、域记录、标记错误和客户端。请求处理程序、授权决策、数据库查询和提供程序调用在 sidecar 中运行。导入架构不会启动服务器。

sidecar 在以下位置发布其服务合约： GET /api/openapi.json。使用该运行文档检查您所连接的应用程序的方法、路径参数、有效负载和状态代码。服务器将其组组装在 apps/sidecar/src/layers.ts;共享合约被组装在 packages/api/src/index.ts.

身份验证和身份

受保护的路线需要 Authorization: Bearer <token>。当 sidecar 启动时，桌面会收到一个新的应用程序令牌。 GET /api/health 是公共卫生调查；本国的 /health 和 /version 受到保护。应用程序承载令牌通过定时安全比较进行比较。

可选的 x-session-token 携带帐户会话 JWT。不记名令牌接纳本地应用程序；会话选择其代理帐户。缺失、过期、无效或孤立的会话将回退到安装的本地配置文件。然后，资源处理程序通过存储库授权帮助程序检查所有权或组织访问权限。

范围内的桥接令牌仅允许 GET /api/ai/actions 和 POST /api/ai/actions/invoke。它不授予对项目 CRUD、凭据设置或其他 HTTP 路由的访问权限。动作桥会再次检查其项目和读/写范围。

资源族

• 设计： 项目、图纸、组件、图纸版本、实体导入/导出以及精确的 CAD 分析、STEP 导出和装配分析。
• 制造业： 刀具路径和版本、注释、生成器建议、解析、重播验证、本地制造作业、材料、工具、机器配置、库项目和生产成本。
• 助手： 提供者、凭证、模型、会话、流转、会话控制、操作、项目内存、工作区上下文和无状态建议。
• 合作： 分支、提交、差异、拉取请求、评论、GitHub 镜像、工作流程文件和运行、实时事件和同伴配对。
• 申请服务： 用户、身份验证、组织、通知、文件、插件、计费、分析、候补名单、MCP 配置和本地键值存储。

合同组保留其特定于端点的响应形状。客户端应该解码它调用的操作的模式，而不是假设单个应用程序范围的 JSON 信封。

响应和失败

常见标记错误映射到 HTTP 400 (BadRequest), 401 (Unauthorized), 403 (Forbidden), 404 (NotFound), 405 (MethodNotAllowed), 409 (Conflict) 和 500 (InternalError）。他们声明的模式带有人类可读的 message。有些团体使用信封 success: false, message， 和 errors;少数人使用 error 场地。

成功响应可以是记录、数组、可为空值或信封。 Envelope 包括 success, message， 和 data; EnvelopeOpt 使消息可选。创建端点在适当的情况下显式声明 201。不要在不检查 HTTP 状态和端点架构的情况下仅从 JSON 字段推断成功。

模式解码在处理程序执行之前验证传输输入。业务验证仍在服务中运行：结构上有效的请求可能引用无法访问的绘图、包含过时的制造工件或请求冲突的分支操作。

使用共享客户端

ApiClient.layer 需要一个 baseUrl 和应用 token。它提供获取传输和客户端授权中间件。其方法直接源自 Api，因此该客户端还涵盖了代码生成省略的操作。

import { ApiClient } from "@cadcamfun/api"
import { Effect } from "effect"

const projects = Effect.gen(function* () {
  const api = yield* ApiClient
  return yield* api.projects.list()
}).pipe(Effect.provide(ApiClient.layer({ baseUrl, token })))

基本 URL 是 sidecar 的环回地址和分配的端口。从桌面连接解决它，而不是在启动时保留端口。将令牌排除在 URL 和日志之外。

设计和制造要求

项目运营使用 /api/projects;图纸和刀具路径有自己的集合和详细路线。 POST /api/toolpaths/generate 生成 G 代码、解析的程序数据、警告以及来自生成器设置和几何形状的统计数据。 /suggest, /parse， 和 /verify 公开参数建议、G 代码解释和库存回放。这些计算不会创建保存的刀具路径。

POST /api/toolpaths/manufacture 接受版本化 CAD 快照并返回包含 NC、刀具分配、切削数据、声明、问题和发布级别的内核结果。通过刀具路径创建或更新操作单独保存生成的文档。看 设置 用于持久性期间的证据验证。

POST /api/cad/exact/analyze, /step， 和 /assembly 接受显式元素或存储的绘图标识符。读取存储的图形会应用调用者的正常图形访问检查。

流媒体和恢复

AI 流携带文本、推理、工具调用和结果、权限和问题请求、重试、轮次状态、上下文和完成的键入事件。客户端必须增量地使用事件并保留会话标识符。 HTTP 连接结束并不足以证明模型已完成：重新连接后可以再次读取会话状态。

AI 事件模式存在于 packages/api/src/ai-events.ts 和 packages/ai/src/events.ts。一般现场活动使用活动组。二进制下载、JavaScript 插件引导响应和签名的原始 Webhook 主体需要它们自己的传输处理。

列出分页其结果所使用的路由 page 和 limit 查询参数。对于机器配置， page 默认为 1， limit 默认为20，并被限制为1–100，响应携带 pagination 和 page, limit, total， 和 totalPages (apps/sidecar/src/http/machine-configs.ts）。检查每个组的参考页以了解其实际声明的参数。

生成的 SDK

@cadcamfun/httpapi-codegen 将 HttpApi 组反映到操作元数据和生成的客户端中。 API生成器编写一个Promise SDK来 packages/api/src/sdk/generated 并影响客户 packages/api/src/client/generated。公共 Promise SDK 导出为 @cadcamfun/api/sdk.

bun run --filter @cadcamfun/api generate
bun run --filter @cadcamfun/api generate:check

两个生成的目标都忽略配置文件分段上传、插件分段安装、具有多个成功模式的 MCP 创建、具有冲突标识符的 MCP 更新、具有重复输入名称的项目工具路径创建以及使用流标头提供的插件文件。 Promise 目标还省略了 Stripe 原始 webhooks、插件 JavaScript 引导程序、二进制文件下载以及生成器的生成/建议请求。这些遗漏是明确的 packages/api/scripts/generate-clients.ts;使用合同客户或适当的原始传输来进行这些操作。

来源组织

groups/ 包含资源合同。共享几何体和 CAM 方案来自 @cadcamfun/core; cad-exact.ts, cam-kernel.ts， 和 cam-program.ts 描述丰富的 CAD/CAM 结果和便携式文档。 client.ts 构建合约客户端，而生成脚本拥有生成的目标和遗漏列表。

积分规则

在传输边界重用契约模式，并将数据库依赖项保留在 sidecar 中。通过其合约、处理程序、服务或存储库以及重点 HTTP 覆盖范围来引入端点。生成的文件是输出：编辑它们的合约或生成器并重新生成它们。 API 模式版本、可移植文件版本和插件 API 版本描述单独的合约。

资源参考

325 操作 穿过 232 条路径 和 35 个资源组，具有 56 命名架构。每个资源页面都会列出其操作，并显示声明的路径/查询/标头参数、必填字段和可选字段、可为空值、内容类型、成功和错误状态以及完整架构。

数据是从发出的 packages/api/src/index.ts，客户端和 sidecar 使用的相同组成的 HttpApi 合约。这些页面描述了签出的合同；检查正在运行的服务器 /api/openapi.json 如果您连接到另一个版本。

下载 OpenAPI JSON · 通过捕获的响应来跟踪请求

连接和请求约定

API 由本地 sidecar 提供，而不是由固定的托管端点提供。 Tauri 获取其动态选择的环回 URL 和启动令牌。手动启动的 sidecar 在 JSON 就绪事件中宣布其端口。配对的移动客户端改为通过其配置的 HTTPS 网关进行连接。

curl --silent --show-error "$CADCAMFUN_URL/api/projects" \
  --header "Authorization: Bearer $CADCAMFUN_TOKEN"

从实际连接设置这两个变量。资源页面上的请求模板故意使用占位符和负载文件。可选传输字段并不保证每个业务操作都可以省略它们：例如，项目创建会拒绝其处理程序中缺少的名称。

生成参考维护

packages/web/script/generate-api-reference.mjs 使用 API 包已安装的 Effect 实现读取组合合约并写入参考 JSON。文档Worker消费生成的内容；它不会初始化应用程序服务器来响应文档请求。

bun run generate:api-reference
bun run check:api-reference
bun run check:docs-index

根据每个声明的操作检查资源覆盖率。新添加的组必须接收面向读者的元数据和导航，并且必须重新生成更改的请求或响应。手写指南仍然解释了授权规则、副作用、服务配置以及 HTTP 模式单独无法表达的限制。

整合食谱

开始于 捕获的 HTTP 请求 看看项目创建、业务验证、承载拒绝、相关记录和键值持久性实际如何响应。使用 类型化客户端集成 使用 Promise SDK 或 Effect 客户端重现这些操作并处理其不同的故障通道。

这些方法将 HTTP 契约与真实的服务行为联系起来。模式可以描述所需的存在、编码和返回的形状；其链接指南解释了访问规则、持久性影响、支持的恢复以及不能单独从这些类型推断的限制。

每个资源组的操作

该合约目前在 270 组中声明了 34 操作，所有操作都在一个单独的 bearer HTTP 安全方案。唯一没有承载安全的操作是公共卫生探测。该表是根据生成的 OpenAPI 文档计算得出的：每组的操作、使用的 HTTP 方法、多少个不同的路径以及一个代表性路径。

整个合约的状态代码

每个操作对每个声明的响应进行一次计数，可以得出客户端必须准备好解码的内容：

每个错误都是一个 Effect 标记的错误，因此它的 JSON 正文始终包含一个 _tag 其字段旁边的鉴别器。共有三个主体系列，继承自旧处理程序，以便现有客户端继续工作：

{ "_tag": "NotFound", "message": "Project not found" }

{ "_tag": "EnvNotFound", "success": false, "message": "Material not found", "errors": null }

{ "_tag": "KeyedInternal", "error": "Failed to load components" }

成功信封反映了错误信封： { success: true, message, data }， 在哪里 data 或许 null。这 EnvelopeOpt 变体省略 message 当处理程序没有提供时。打开 _tag 而不是基于存在 message 或 error.

如何处理请求

1. 路由器匹配方法和路径。未知的路线永远不会到达处理程序。
2. 承载中间件在恒定时间内比较令牌。丢失或错误的令牌会在任何解码之前停止使用 401 的请求。
3. 路径、查询、标头和正文根据操作的模式进行解码。如果不运行业务代码，结构问题就会变成 400。
4. 处理程序解析代理帐户、检查所有权或组织成员身份 (403/404) 并运行服务。
5. 结果使用声明的成功模式进行编码，或者使用其标记的错误模式和状态对失败进行编码。

非 JSON 的响应

生成的 Promise SDK 拒绝内容类型不是的流响应 text/event-stream 和 ClientError("UnsupportedContentType")，以及大于 16 MiB 的单个 SSE 事件 SseEventTooLarge.

无需客户端调用 API

type TaggedError = { _tag: string; message?: string; error?: string }

async function call<T>(base: string, token: string, method: string, path: string, body?: unknown): Promise<T> {
  const response = await fetch(new URL(path, base), {
    method,
    headers: {
      authorization: `Bearer ${token}`,
      ...(body === undefined ? {} : { "content-type": "application/json" }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  })
  if (response.status === 204) return undefined as T
  const payload = await response.json()
  if (!response.ok) {
    const failure = payload as TaggedError
    throw new Error(`${response.status} ${failure._tag}: ${failure.message ?? failure.error}`)
  }
  return payload as T
}

const project = await call<{ id: string; name: string }>(
  process.env.CADCAMFUN_URL!, process.env.CADCAMFUN_TOKEN!,
  "POST", "/api/projects", { name: "Bracket" },
)

更喜欢 TypeScript 中生成的客户端：它们知道每个操作的成功状态和声明的错误状态，并将其他任何内容视为 UnexpectedStatus 而不是猜测。

在 3D