关键约定

架构约定

网络：所有 HTTP 请求统一走 Rust

• 通用请求：lib/services/http_ffi.dart（HttpFfiService），适用于小 / 中响应
• 大文件下载：lib/services/downloader.dart（Downloader.downloadFile），流式写盘
• 禁止在新增 API 服务中使用 package:http（仅测试用例保留）
• 本地回环 HTTP 服务端（OAuth 回调、MCP 服务端）例外，使用 dart:io HttpServer

数据库：所有远程数据库操作统一走 Rust

• 通过 lib/services/db_client_ffi.dart（DbClientFfi）调用 xmc_db_client 的 db_request 入口
• 覆盖 MySQL / MariaDB / PostgreSQL / Redis 的连接测试、浏览、查询、管理
• 禁止在 Dart 侧新增数据库客户端依赖
• remote_db_service.dart 是唯一业务入口

状态管理

• 统一走 lib/state/（Provider），不在 widget 内直接持有全局状态

持久化

• 统一用 SQLite（instance_store.dart、node_store.dart、trash_store.dart、ai_settings.dart 等），设置存 settings 表
• 无 SharedPreferences

文件组织

• 新增页面放 lib/screens/，新增 API 服务放 lib/services/
• 命名遵循现有 *_api_service.dart / *_provider.dart 模式
• 全局暗色主题，UI 组件参考 lib/utils/apple_widgets.dart

编译约定

Rust 修改后必须重编译

修改 Rust 代码后，必须先重新编译并复制动态库到平台目录（Windows windows/runner/、Linux linux/、macOS macos/），否则运行的是旧动态库。

新增 crate 需同步更新 7 处

1. rust/Cargo.toml 的 members
2. build_rust.bat / build_rust.sh
3. linux/CMakeLists.txt
4. windows/runner/CMakeLists.txt
5. macos/Runner.xcodeproj/project.pbxproj（dylib 复制 + 签名脚本）
6. .github/workflows/build-and-test.yml
7. .github/workflows/package.yml（⚠️ 极易漏改）

FFI 集成测试

test/*_ffi_test.dart 需要动态库已编译并复制到 windows/runner/ 或项目根目录（build_rust.bat 会复制到两处）；本地回环 HTTP 测试（http_ffi 等）用 dart:io HttpServer 自起服务，无需外部依赖。

禁止事项

• 勿编辑 rust/target/、build/、dist/ 等生成目录
• 勿在 Dart 侧引入新的 HTTP 客户端 / 数据库客户端依赖