边车

运行时职责

sidecar 是桌面和本地开发集成共享的 Bun 后端。它打开 SQLite，提供存储库和域服务，提供架构定义的 HTTP API，并托管助手和工作流集成。 Tauri shell 启动打包的二进制文件并从机器可读的启动事件中发现其分配的端口。

apps/sidecar/src/layers.ts 组成所提供的 API、处理程序、授权、存储库和服务。付费结帐和人工智能模型等可选提供商通过其服务进行配置；它们的缺失不会将数据库记录转变为有效的外部集成。

进程和关闭协议

主 HTTP 服务器仅绑定 127.0.0.1, 带端口 0 因此操作系统选择一个可用的端口。 HTTP 空闲超时被禁用，以允许长时间的助理呼叫在流事件之间保持静默。在范围最终确定继续之前，将正常 HTTP 关闭配置为 500 毫秒。

API 的公共健康探测成功后，该进程会在标准输出上打印就绪事件。启动失败会打印错误事件并设置失败退出代码。操作日志以 JSON 形式发送到 stderr； stdout 是为父进程协议保留的。

{"event":"ready","port":53211}
{"event":"error","message":"Startup failure details"}

以换行符结尾的 stdin 消息 event: "shutdown"、stdin 关闭、SIGINT 或 SIGTERM 释放服务器范围。格式错误的父消息将被忽略，并且过大的不完整行将被丢弃。终结器停止拥有的服务并检查点/关闭 SQLite。仅中断终止被报告为干净退出。

所需配置

AppConfigService 读取一次进程配置 apps/sidecar/src/config.ts. CADCAMFUN_TOKEN 是所需的应用程序不记名令牌，并且 CADCAMFUN_DATA_DIR 是所需的应用程序数据目录。数据库路径是 <dataDir>/cadcamfun.db. CADCAMFUN_MIGRATIONS_DIR 是可选的并提供 SQL 迁移文件夹；如果没有它，数据库层将不会应用应用程序迁移。

桌面提供启动配置。对于直接开发，请在启动 shell 中提供这些配置名称，并从存储库根运行包的启动脚本：

bun run --filter @cadcamfun/sidecar start

sidecar 包定义了 start 和 typecheck 脚本。打包的二进制编译由存储库发布脚本拥有，而不是 sidecar-package build 命令。

可选配置

• CADCAMFUN_APP_URL 设置身份验证链接的基础； CADCAMFUN_DEBUG_LINKS 允许返回调试重置/魔法链接，默认为 false。
• CADCAMFUN_AI_HOST 是 nikcli （默认；聊天通过嵌入式对话主机运行）或 direct （仅限 AI SDK）。 CADCAMFUN_AI_OFFLINE （布尔值，默认 false）禁用可选的模型目录网络路径。 CADCAMFUN_AI_MINIMAX_BASE_URL 覆盖 MiniMax 的端点。
• STRIPE_SECRET_KEY 启用 Stripe 提供商； STRIPE_PRICE_BASIC, STRIPE_PRICE_PRO， 和 STRIPE_PRICE_ENTERPRISE 提供付费计划价格。 STRIPE_WEBHOOK_SECRET 签名 Webhook 验证需要。
• CRON_SECRET 提供 cron 路由秘密；如果没有它，本地应用程序可以调用该路由，而无需额外的 cron 秘密。 ADMIN_EMAIL 是遗留管理员身份检查；默认情况下，本地配置文件是其自身安装的管理员。
• OTEL_EXPORTER_OTLP_ENDPOINT 启用配置的 OTLP 遥测导出。如果没有端点，外部遥测导出将关闭。

所有这些名字都读在一处， AppConfigService;令牌和 Stripe 密钥作为编辑值保存，因此它们不会出现在日志中。 AI 提供商密钥通过凭证 API 和专用凭证文件进行管理。它们不会被读取为供应商 API 密钥环境设置 AppConfigService.

HTTP 访问和 API 发现

边车发布 /api/openapi.json 为其服务的合同并在受保护的组上使用不记名中间件。第二个可选会话标头选择代理帐户。本地配置文件在下创建或重用 local@cadcamfun.local，无需帐户登录即可保持安装可用。

CORS 承认 tauri://localhost, HTTP/HTTPS tauri.localhost，以及带有可选端口的 HTTP localhost 或 127.0.0.1 来源。其他来源不会收到允许的来源响应标头。 CORS 是一项浏览器策略；承载中间件仍然是受保护路由的访问控制。

服务组涵盖设计资源、制造生成和验证、精确 CAD、库、成本、AI、VCS/工作流程、事件、配套控制、身份、组织、通知、文件、插件、计费、分析、候补名单、MCP 和本地状态。有关方法和有效负载的详细信息，请参阅正在运行的 OpenAPI 文档。

代理帐户标头是 x-session-token。如果没有它，或者使用未验证为现有用户的会话令牌的令牌，请求将充当本地配置文件（src/http/authorization.ts).

来源组织

main.ts 启动作用域服务器和父协议。 config.ts 耗材配置， layers.ts 电线依赖性， startup.ts 共享就绪状态和环回端口， shutdown.ts 读取父关闭消息，以及 observability.ts 配置可选遥测。

http/ 将经过验证的请求映射到服务。 repos/ 将资源映射到 Drizzle 查询和资源访问规则。 services/ 协调跨资源行为，以及 plugins/ 包含工作主机和浏览器引导程序实现。

处理程序组

处理程序按资源分组：项目、图纸、组件、刀具路径和附加功能、刀具路径生成器、精确的 CAD、材料/工具/机器配置及其存储路径、库、成本、文件、组织、通知、用户/身份验证、计费、分析、候补名单、MCP、各种应用程序服务、键值状态、AI、VCS、事件和配套管理。

entity-io.ts 共享实体导入/导出助手。 authorization.ts 应用应用程序和范围桥凭据。处理程序声明的有效负载已经通过模式解码；服务级别验证仍然检查引用、所有权、证据一致性和领域约束。

领域服务组成

AI 服务提供绘图和 CAM 操作、参数化/精确检查、项目上下文、内存、工作日志和插件工具。 cam-program.ts 重新运行捕获的制造请求并在保存期间验证本地证据。历史服务应用快照、受保护分支规则、GitHub 传输和工作流执行。

其他服务拥有文件存储、成本计算、本地配置文件和代理用户状态、令牌签名/撤销、桥接凭证、支付、通知、实时事件和伴随生命周期。效果层拥有自己的资源，因此关闭会按依赖顺序释放它们。

存储库边界

存储库使用共享 Database.query 用于持久性和类型化存储故障的服务。它们解码存储的 JSON 并强制执行特定于资源的访问或提供授权帮助程序。 HTTP 处理程序将域/存储故障转换为其声明的响应错误；几何计算留在 @cadcamfun/core.

插件集成

普通工人主机位于 plugins/host.ts。生产助手插件服务加载显式启用 ai:tool 来自应用程序插件目录的扩展。浏览器 ZIP 安装程序和引导 API 使用自己的清单和存储路径。看 插件 在选择扩展格式或假设功能已连接之前。

配套 HTTPS 网关

配套网关是一个单独的选择加入 HTTPS 侦听器，可以恢复之前启用的设置。它为网络客户端绑定 IPv4，提供保留在下的生成证书 <dataDir>/companion，并使用范围可撤销的设备令牌。配对提供证书指纹，以便移动设备可以固定桌面。

网关检查显式路由允许列表，并使用应用程序令牌将允许的请求转发到环回 API。配对的手机永远不会收到该应用程序令牌。允许列表不包括凭据管理、插件安装、文件管理和计费。撤销设备或禁用网关会删除其网络访问权限。

准备和诊断

就绪事件表示服务器层构建后本地HTTP健康探测成功。这并不意味着模型提供者已接受请求、配置了结帐或每个可选网络服务均可访问。通过这些服务自己的状态和结果端点来诊断这些服务。

对于启动错误，保留协议消息和相关的 stderr 事件，检查配置和迁移，并检查数据目录的可访问性。切勿将启动不记名令牌或提供商凭证内容粘贴到诊断输出中。

数据所有权

持久数据包括 SQLite 数据库和迁移备份、文件存储、AI 凭证/配置状态、身份验证秘密和撤销记录、插件资产和配套证书。备份或传输安装时保护整个应用程序数据目录。 Sidecar拥有连接生命周期；客户端既不拥有 SQLite 句柄，也不拥有主要不记名令牌的发行。

启动一次性本地实例

在专用终端的存储库根目录中运行这些命令。目录是新的，令牌是在本地生成的而不打印它，迁移是显式的，并且直接/离线 AI 模式避免了为此启动检查导入嵌入式对话主机。 openssl 在此 shell 示例中提供随机启动令牌。

export CADCAMFUN_DATA_DIR="$(mktemp -d /tmp/cadcamfun-docs.XXXXXX)"
export CADCAMFUN_TOKEN="$(openssl rand -hex 32)"
export CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle"
export CADCAMFUN_AI_HOST=direct
export CADCAMFUN_AI_OFFLINE=1
bun run --filter @cadcamfun/sidecar start

读取就绪事件的端口而不是假设固定的数字。服务运行时保持标准输入打开；来自已结束的输入源的管道要求其关闭。使用SIGTERM或关闭协议来释放数据库。一次性目录在退出后仍然可供检查。

使用客户端 shell 中已提供的连接 URL 及其令牌，将公共活动与受保护的访问进行比较：

curl --fail-with-body "$CADCAMFUN_URL/api/health"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/version"
curl --fail-with-body -H "Authorization: Bearer $CADCAMFUN_TOKEN" "$CADCAMFUN_URL/api/projects"

来源： apps/sidecar/src/main.ts, config.ts, shutdown.ts， 和 test/process.test.ts.

日志和可选的遥测

Stderr JSON 日志和 stdout 就绪/错误事件有不同的使用者。启动器应该解析完整的 stdout 行并分别转发或保留 stderr。准备就绪后失败的请求是应用程序错误，而不是第二个启动事件。

什么时候 OTEL_EXPORTER_OTLP_ENDPOINT 已配置， ObservabilityLive 设置跨度/日志的批处理和定期指标导出。它附加 /v1/traces, /v1/metrics， 和 /v1/logs 删除尾部斜杠后到提供的收集器底座。提供集电极底座，例如 http://collector:4318，而不是已经带有后缀的信号 URL。

资源服务名称是 cadcamfun-sidecar 它的版本来自应用程序配置。标准 OpenTelemetry 资源环境设置由 SDK 处理。网络导出是可选的，而在未配置收集器时本地 stderr 仍然可用。

来源： apps/sidecar/src/observability.ts 和 main.ts.

识别失败边界

真实流程生命周期测试涵盖 EOF、拆分关闭 JSON 行和 SIGTERM，然后重新启动同一数据目录并验证持久项目。他们还会在退出后检查 WAL。这建立了源进程的生命周期行为；打包的外壳和特定于机器的交付仍然需要自己的验证。

来源： apps/sidecar/test/process.test.ts, src/http/authorization.ts, src/layers.ts， 和 src/services/companion.ts.

详细启动顺序

1. shell 生成一个 32 个随机字节的启动令牌，十六进制编码为 64 个字符，并使用以下命令启动 sidecar CADCAMFUN_TOKEN, CADCAMFUN_DATA_DIR， 和 CADCAMFUN_MIGRATIONS_DIR.
2. AppConfigService 读取所有设置一次。缺少必需的设置导致启动失败 error 事件。
3. 数据库层打开 <dataDir>/cadcamfun.db，启用 WAL 模式和外键，并应用迁移目录中的迁移。
4. 各层组成：数据库、存储库、服务、HTTP 处理程序。每个资源都由一个层拥有，因此关闭以相反的依赖顺序释放它。
5. HTTP 服务器绑定 127.0.0.1 在端口 0 上，操作系统选择一个空闲端口。
6. 公共卫生途径正在探索中。只有在它回答之后才是 {"event":"ready","port":N} 写入标准输出。
7. shell 等待该行最多 60 秒，并且最多重新启动 sidecar 一次。网络视图最多等待 125 秒 get_sidecar_endpoint，然后连接。

认证模型

签名令牌使用 HS256 与发行者 cadcamfun。已撤销的令牌验证为 invalid，未知或伪造的令牌将被撤销忽略。签名密钥在每次安装时生成一次并存储在数据目录中，因此重新启动之前发出的链接仍会在之后进行验证。

数据目录中包含哪些内容

在 sidecar 停止时或在对 WAL 设置检查点的关闭之后备份整个目录。仅限复印 cadcamfun.db 而 sidecar 运行可能会错过仍在 WAL 文件中的最近写入。

准备线，已捕获

CADCAMFUN_TOKEN=t CADCAMFUN_DATA_DIR="$(mktemp -d)" \
CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" \
CADCAMFUN_AI_HOST=direct CADCAMFUN_AI_OFFLINE=true \
bun --no-env-file apps/sidecar/src/main.ts
# stdout: {"event":"ready","port":43461}

该端口由操作系统在每次启动时选择。该行是迁移和层准备就绪后的第一个标准输出，因此看到它的客户端可以立即调用 API。保持 stdin 打开：关闭它是关闭信号。

在 3D