文档
建筑学
跨桌面、边车、移动伴侣和文档站点的执行边界、请求流、持久性和扩展点。
从英文自动翻译。 查看英文原文
流程和信任边界
Tauri 拥有本机窗口集成、安全凭证命令、菜单、更新和 sidecar 生命周期。它的 webview 运行 SolidJS 应用程序。编译后的 Bun sidecar 打开数据库并提供 HTTP 服务 127.0.0.1 具有操作系统分配的端口。前端未打开 SQLite。
Sidecar 的入口点是 apps/sidecar/src/main.ts。它创建 HTTP 服务器、构建应用程序层、探测 /api/health，然后打印包含所选端口的 JSON 就绪事件。日志被路由到 stderr，因此 stdout 仍然可用于 shell 协议。
移动伴侣到达明确配对的桌面网关。其本机传输和设备凭据与桌面 Web 视图的环回连接是分开的。文档 Worker 是一个单独的部署，与用户桌面没有隐式连接。
库依赖项
@cadcamfun/core 包含 CAD、绘图和 CAM 计算。这取决于模式和边界整合的效果；算法循环是普通的 TypeScript。 @cadcamfun/api 导入核心类型和模式来声明 HTTP 输入、输出、错误和流。
@cadcamfun/db 拥有应用程序数据库服务、架构和迁移逻辑。 sidecar 将其与核心、API、AI、插件 SDK、VCS 和工作流程包相结合。其存储库使用数据库服务；处理程序委托给存储库和服务。
桌面导入两者 @cadcamfun/api 和 @cadcamfun/core。它在运行时通过 Effect 客户端使用 API，并使用 CAD/CAM 功能和视口中的核心几何体。 Mobile 依赖于 API 包并将伴随请求包装在其客户端中。独立的 nikcli 插件通过 HTTP 发现正在运行的应用程序的操作目录，而不是导入后端实现。
HTTP请求生命周期
- webview从native shell获取sidecar连接。
apps/desktop/src/app/client.ts构建具有不记名授权和可选帐户会话令牌的 Effect HttpApi 客户端。packages/api/src/client.ts为其他消费者提供可重用的合约客户端。apps/sidecar/src/layers.ts组装ServedApi、处理程序、授权、CORS 和共享服务层。- 处理程序验证合约输入、解析服务、执行计算或持久性，并返回声明的成功或错误表示。流端点保留其声明的流协议。
CORS 允许在开发中使用 Tauri 生产源和 HTTP 环回源。它不能取代授权。 API 公开了多种响应信封样式；消费者必须遵循每个端点的模式，而不是假设每个响应都具有相同的形状。
服务生命周期和存储
效果层获取应用程序范围内的数据库和共享服务。数据库层创建其父目录，启用 WAL 和外键，可选择应用迁移，并使用操作名称包装查询失败。最终化尝试截断 WAL 检查点并关闭 SQLite 句柄。
这 DatabaseLive 图层选择 dataDir/cadcamfun.db。必须提供迁移文件夹才能在启动时应用迁移。 AI凭证、插件状态、VCS对象、工作流程执行和文件存储通过各自的服务接口进行处理；存储详细信息在其模块页面上进行了描述。
当地工作室 packages/web/script/studio-server.ts 是一个额外的Bun过程。它直接打开已配置的现有应用程序数据库，并在环回端口 4396 上提供经过身份验证的概述数据。其开发代理和 cookie 会话独立于 Tauri sidecar 连接。
实时项目事件（拉取请求、提交、工作流运行和助理会话阶段）通过进程内事件服务发布。新订阅者首先接收最多 20 个最近的匹配事件，然后接收实时事件，可以选择按项目和事件类型进行过滤（apps/sidecar/src/services/live-events.ts).
延伸边界
有两个插件集成。应用程序插件 SDK 定义清单、功能、激活和主机合约。 nikcli 桥将注册的 CAD/CAM 操作公开给外部助手。通过 HTTP 注册表路由安装插件是与激活运行时主机中的模块不同的操作。
实时工作流解析和调度 packages/workflow。服务支持的步骤由 sidecar 层注册，而纯项目和 CAM 步骤可以使用其提供的输入运行。 VCS 在其库中计算对象哈希、差异、合并和 GitHub 传输操作； sidecar 服务将这些操作与项目持久性连接起来。
Web 文档助手检索呈现的文档，并可以在配置存储时发布指南工件。它回答文档问题；它不继承 CAD/CAM 应用程序的本地项目访问权限。
连接和凭证边界
| 凭据 | 目的 | 边界 |
|---|---|---|
| 应用程序不记名令牌 | 允许本地应用程序访问受保护的 sidecar 路由。 | 为 sidecar 启动生成/提供； webview通过native连接获取。 |
x-session-token | 选择已批准的应用程序背后的帐户。 | 缺席、无效、过期或孤立的会话将回退到本地配置文件。 |
| 配套设备令牌 | 允许单独配对的电话进入网关路由。 | 由单独的 HTTPS 网关及其方法/路径允许列表检查。 |
| AI桥代币 | 将单个项目允许的操作公开给外部代理。 | 允许两个操作桥端点并强制执行读取或读/写范围。 |
| 提供商 API 密钥 | 验证出站模型调用。 | 由 sidecar 凭证服务管理；不能替代应用程序授权。 |
| GitHub 令牌 | 执行请求的镜像操作。 | 为该调用提供了 x-github-token;不是项目快照数据。 |
授权是分层的。通过承载中间件并不能证明对特定图纸或项目的所有权；处理程序和存储库检查这些资源。同样，配对不会将手机变成不受限制的边车客户端。选择凭证之前，请咨询特定端点和伴随策略。
授权适配器是 apps/sidecar/src/http/authorization.ts。同伴和桥梁决策存在于它们自己的服务中。将这些路径分开可以撤销丢失的设备或集成令牌，而无需替换人工智能提供商的秘密。
故障隔离
就绪事件之前的失败属于sidecar初始化：配置、数据库升级、服务构建或HTTP启动。准备就绪后的失败可能特定于提供程序、文件系统操作、端点或客户端会话。 shell的生命周期和webview的连接重试预算是不同的；当重新启动更改侦听端口时检查两者。
断开连接的 AI 流不一定会停止其服务器端对话。在重新发送编辑指令之前恢复会话状态。失败的工作流不会回滚其触发提交。不成功的远程推送不会删除本地历史记录。这些区别防止处理网络故障，就好像持久操作从未发生过一样。
对于失败的 API 请求，记录其方法、路径、状态、端点 ID 和相关的非秘密标识符。比较跑步 /api/openapi.json 与 文档合同快照 当客户端和服务器版本不同时。避免使用之前启动的 sidecar 中的令牌进行故障排除。
按源路径的架构快照
| 区域 | 它住在哪里 | 首先要读什么 |
|---|---|---|
| 桌面外壳（生Rust） | apps/desktop/src-tauri/src/ | sidecar.rs （导师）， commands.rs, updater.rs, menu.rs, tray.rs, secrets.rs |
| 桌面用户界面 | apps/desktop/src/ | app/, features/ （cad、cam、ai、聊天、项目、刀具路径、插件……）、 viewport/, shared/ |
| 边车入口 | apps/sidecar/src/main.ts | 准备好握手，分层 layers.ts，配置在 config.ts |
| HTTP 处理程序 | apps/sidecar/src/http/ | 每组一个文件，例如 toolpath-generator.ts, ai.ts, kv.ts |
| 服务和存储库 | apps/sidecar/src/services/, repos/ | cam-program.ts, companion.ts, auth-tokens.ts, storage.ts |
| 合同 | packages/api/src/ | index.ts, groups/, errors.ts, client.ts |
| 核心 | packages/core/src/ | cad/history.ts, cad/sketch.ts, cam/kernel/, cam/post/ |
| 助手 | packages/ai/src/ | actions/, tools/, nikcli/, prompts/ |
| 贮存 | packages/db/src/ | index.ts, upgrade.ts, schema.ts |
| 历史 | packages/vcs/, packages/workflow/ | 存储库 API、合并、工作流程架构 |
| 伴侣 | apps/mobile/ | app/ 路线， lib/ 连接和配对 |
跟踪：从启动到第一次请求
- Tauri 启动，主管在
sidecar.rs生成一个随机令牌。 - 它产生
sidecar-<triple>和CADCAMFUN_TOKEN,CADCAMFUN_DATA_DIR和CADCAMFUN_MIGRATIONS_DIR. - sidecar 读取其配置，打开 SQLite（WAL，外键），根据需要进行备份和迁移，并构建其服务层。
- 它绑定
127.0.0.1在临时端口上并在标准输出上打印 JSON 就绪行。主管最多等待 60 秒。 - 主管发出
sidecar-status{ state: "ready", port };网络视图调用get_sidecar_endpoint为了{ baseUrl, token }. - 网络视图构建
ApiClient.layer({ baseUrl, token })并开始加载项目。
如果 sidecar 退出，supervisor 会重新启动它一次并宣布新端口；第二次失败会使状态保持在 failed。退出时，主管写入关闭行，等待 2 s，然后收获进程；当 WAL 范围关闭时，数据库层对 WAL 进行检查点。
Trace：制造请求
- CAM 工作区捕获绘图元素、库存和调用
POST /api/toolpaths/manufacture. - 承载中间件接受请求；身体被解码
CamKernelRequest. runKernelRequest中services/cam-program.ts来电cam.kernel.jobOfSnapshot;准备问题变成了400。cam.kernel.runJob计划或跟踪操作、计算切削数据、生成刀具路径、为机器语言发布 NC 并在体素库存上重播以评估索赔。- 结果被解码
CamKernelResult然后回来了。在客户端使用可移植文档保存刀具路径之前，不会存储任何内容，此时 sidecar 重新运行捕获的请求并进行比较。