当地发展

开发流程

完整的桌面开发会话运行 Rust shell、Bun sidecar 和 Vite。 shell 提供本机功能并监督 sidecar； Vite 提供 webview 资源和热重载。 bun run desktop:dev 在启动这些进程之前准备二进制和迁移资源。

为了更快地进行屏幕工作，请运行桌面 dev 单独的脚本。 App.tsx 仅在 Tauri 外部且仅在以下情况下选择内存中预览 API： VITE_SIDECAR_URL 缺席。不支持的 API 集合的预览失败预计会返回 501。使用实时 sidecar 实现持久性、授权、流式 AI 和服务器服务。

CADCAMFUN_TOKEN=local-development-token CADCAMFUN_DATA_DIR=/tmp/cadcamfun-development CADCAMFUN_MIGRATIONS_DIR="$PWD/packages/db/drizzle" bun --no-env-file apps/sidecar/src/main.ts

上面的令牌是一个孤立的本地开发过程的示例。选择你自己的价值。保持标准输入打开：关闭它会停止 sidecar。服务器打印一份 JSON ready 事件及其临时端口之后 /api/health 回应；日志转到 stderr。

VITE_SIDECAR_URL=http://127.0.0.1:43111 VITE_SIDECAR_TOKEN=local-development-token bun run --filter @cadcamfun/desktop dev

将端口 43111 替换为就绪事件端口，并在运行之前使用提供给该 sidecar 的令牌。 Vite 使用端口 1420，端口选择严格，匹配 Tauri 开发 URL。 sidecar 允许 HTTP localhost/loopback 上的浏览器 CORS 源和受支持的 Tauri 源；它仍然需要对受保护的路由进行适当的授权。

数据目录和迁移

边车打开 <CADCAMFUN_DATA_DIR>/cadcamfun.db。 Tauri 选择自己的应用程序数据目录并将其传递给子级。手动过程使用您提供的目录。即使这些数据库的文件名相同，它们也是独立的。

CLI 迁移脚本读取 DATABASE_URL 并以其他方式使用 ./data/cadcamfun.db 相对于其工作目录。根 db:migrate 跑进去 packages/db。为有意的 CLI 操作选择绝对文件 URL；不要从日志中显示的相对文件名推断目标。

DATABASE_URL=file:/tmp/cadcamfun-cli/cadcamfun.db bun run db:migrate

架构更改源于 packages/db/src/schema.ts。跑步 bun run db:generate，查看生成的迁移，并首先将其应用到隔离的数据库。边车使用 CADCAMFUN_MIGRATIONS_DIR 当提供时；打包构建将生成的目录作为资源暂存。

数据库层启用WAL和外键。当现有文件需要迁移时，升级路径会在其旁边创建一个备份 backups/ 并保留最新的五个匹配的自动备份。首次创建、未更改的架构和内存数据库不会创建升级备份。在手动恢复操作之前独立保存数据。

有针对性的检查

bun run --filter @cadcamfun/core typecheck
bun test packages/core
bun run --filter @cadcamfun/desktop typecheck
bun test apps/desktop/src/viewport
bun run --cwd packages/web check
bun run --cwd packages/web build

选择检查由边界改变。纯粹的几何变化需要几何断言； API 合约变更需要生成客户端检查和受影响的处理程序；持久性更改需要存储库和迁移测试； UI交互的改变需要相关的组件和运行时流程。根 test 脚本包括 packages, apps， 和 scripts.

本机 shell 检查运行自 apps/desktop/src-tauri 和 cargo clippy --all-targets -- -D warnings 和 cargo test。首先暂存目标 sidecar 和迁移，因为 Tauri 的构建上下文包含这些资源。操作系统集成测试可能需要本机桌面和钥匙串。

运行时配置

apps/sidecar/src/config.ts 拥有 sidecar 配置层。所需的输入是 CADCAMFUN_TOKEN 和 CADCAMFUN_DATA_DIR. CADCAMFUN_MIGRATIONS_DIR 选择迁移资源。默认的AI主机是 nikcli; CADCAMFUN_AI_HOST=direct 选择直接呼叫，并且 CADCAMFUN_AI_OFFLINE 支持离线/测试操作。

可选配置包括应用程序 URL 和开发身份验证链接、Stripe 凭证和价格标识符、管理员/cron 设置以及 OTEL_EXPORTER_OTLP_ENDPOINT。如果没有相关提供商配置，则无法计费；遥测导出在没有收集器端点的情况下关闭。仅提供流程所需的输入。

浏览器端点变量是Vite配置，而不是sidecar配置。伴随配对包含不同的令牌和 HTTPS 地址。独立的动作桥令牌有自己的范围和生命周期。请勿互相替换这些凭据。

使用显式进程配置或应用程序设置。示例 sidecar 命令禁用 Bun 的环境文件加载。切勿在日志或文档示例中打印实际令牌、模型密钥、配对链接或签名材料。

效果和资源所有权

存储库将 Effect 固定到 4.0.0-rc.112。服务使用 Context.Service，实现是通过层提供的，操作返回类型化的效果。使用已安装的 effect/ai-docs/src 更改此 API 时的文档，包括其不稳定的 HTTP 模块。

在边界处解码外部输入。将外部异常映射到类型化错误，保留稳定的错误标签，并让作用域层拥有数据库句柄、工作线程、流和服务器资源。 sidecar 的关闭流程处理父关闭事件、stdin 关闭和运行时中断；日志和协议标准输出有不同的目的地。

核心 CAD/CAM 计算在计算热路径中保持简单函数。在边界处包装验证不需要将每个几何操作放入效果中。使用核心几何单位约定并在适当的边缘执行显示/导出转换。绘图角度使用弧度；一些特征参数和 CAM 旋转轴值明确使用度数。

启动故障排除

• Vite端口占用： 释放端口 1420 或停止现有的开发服务器；严格端口模式不会默默地选择另一个端口。
• 启动不断重试： 检查 sidecar 就绪/错误输出和迁移路径。应用程序重新解析端点，同时保留其连接预算。
• 服务器立即退出： 检查所需的配置以及启动进程是否关闭了标准输入。
• 缺少的项目： 确认数据目录、API端点以及应用程序是否使用假客户端。
• 401 回复： 验证客户端正在使用当前进程的令牌而不是之前启动的令牌。
• 浏览器预览中的 501： 为该 API 集合使用真正的 sidecar。
• 本机上下文构建失败： 为正确的目标暂存 sidecar 二进制文件和迁移资源。

文档和配套开发

bun run --cwd packages/web start astro 独自运营。 bun run --cwd packages/web dev 启动 Astro 以及本地 Studio API。文档检查验证路由索引；该构建验证 Astro 编译和预渲染。

对于 iOS， bun run --cwd apps/mobile start 为自定义开发客户端启动 Metro。 bun run --cwd apps/mobile ios 构建/运行本机应用程序； build 仅导出 JavaScript。本机固定需要本地 Swift 模块，并且无法在 Expo Go 中运行。

bun scripts/build.ts --help 列出发布管道的选项。 --only=resources 无需重建即可重新进行迁移，并且 --dry-run 打印计划而不写任何内容。

流程配置参考

布尔输入由 Effect 配置解码，而不是任意字符串的真实性。使用明确的真/假值。未知的 AI 主机文字无法解码。在创建流程之前提供配置；更改父终端变量不会更新已经运行的 sidecar。

针对显式数据库使用 Studio

本地 Studio API 侦听环回端口 4396。其路径优先级为 CADCAMFUN_DB， 然后 DATABASE_URL 与一个 file: 删除前缀，然后删除存储库根目录 data/cadcamfun.db。这与数据库包的默认 CLI 工作目录路径不同。它仅打开现有数据库，不会自动创建/迁移数据库。

DATABASE_URL=file:/tmp/cadcamfun-studio/cadcamfun.db   bun run db:migrate

CADCAMFUN_DB=/tmp/cadcamfun-studio/cadcamfun.db   bun run --cwd packages/web dev

第一个命令初始化文件。第二个启动 Studio 加上 Astro 沿着这条路。新迁移的模式不仅仅因为存在而包含用户/密码会话； Studio 登录需要合适的帐户。其经过身份验证的请求使用 Studio 会话 cookie，并在没有有效会话的情况下返回 401。

当文件丢失时，Studio API 将返回带有所选路径的 503。当 Astro 在没有配套 Studio 进程的情况下运行时，代理 /studio/api 请求无法到达端口 4396。文档页面本身可以通过以下方式开发 packages/web start 无需启动 Studio。

实施锚点： packages/web/script/dev.ts, script/studio-server.ts, astro.config.mjs, packages/db/src/migrate.ts， 和 apps/sidecar/src/config.ts.

可重复的开发循环

1. 选择一次性 sidecar 数据目录和显式迁移文件夹。
2. 在交互式终端中启动 sidecar 并记录其就绪事件中的端口。
3. 使用匹配的 URL/令牌在另一个终端中启动 Vite，或使用其受监督的 sidecar 打开本机应用程序。
4. 重现一项操作并检查其响应和持续状态。
5. 对于后端更改，请重新启动 sidecar，更新浏览器端点（如果其端口发生更改），然后重复该操作。
6. 使用其正常中断或父关闭路径停止进程，以便资源最终确定。

sidecar 会短暂耗尽 HTTP 范围、检查 WAL，并在正常范围关闭时关闭 SQLite。终止没有该路径的进程可能会中断正在进行的工作。源代码编辑不会替换已由 Tauri 监督的已编译二进制文件；测试编译行为时重建 sidecar。

对于编译运行时验证， scripts/smoke-sidecar.ts 可以使用隔离的主目录/数据目录和离线 AI 运行选定的二进制文件。它衡量准备/健康/行动行为并执行核心工作。没有 --binary 它首先编译一个临时可执行文件，因此要计划构建成本；其结果与源代码级测试是分开的。

哪个进程在哪里运行

按更改类型的内循环

在 3D