coding-standards.md

代码规范

状态：Accepted

1. Rust 基线

• 使用 Rust 2024；提交前通过 rustfmt 和 clippy -D warnings，不要手工对抗格式化结果。
• 公共领域类型使用语义名称和 newtype，避免跨层传递无含义的 String、tuple 或 JSON value。
• 模块保持单一职责；优先私有实现和最小 public API。公共 API 应有说明约束与错误语义的文档。
• 产品代码不保留 cargo 模板函数、空泛 utils 模块或无追踪 ID 的 TODO。
• TODO 格式：TODO(P0-ID): 原因与完成条件；不得用 TODO 代替错误处理或安全校验。

2. 依赖与 crate 边界

• 遵守 ../architecture/workspace-and-crates.md。core 只含纯逻辑；shell 负责组合，不承载 可复用领域实现；服务依赖接口而非 UI；平台分支不泄漏到业务 crate。
• 直接依赖统一放在根 workspace；关闭不需要的 default features，并解释大型依赖的 feature 选择。
• guest/host 类型以 WIT 语义为准；内部领域类型与生成绑定之间使用显式转换层。
• UI 组件、State/Event schema 与 Rust/TypeScript 类型以 UI schema 单一源为准；不得在 SDK、runtime 或 renderer 手写同名平行类型。Slint property/类型不得进入插件公开 API。
• 禁止循环依赖、通过重新导出掩盖反向依赖，或复制类型绕开依赖规则。

3. 错误与不变量

• library 使用有上下文的枚举错误（通常 thiserror）；应用边界负责记录和用户可理解的呈现。
• 对不受信任输入返回可分类错误，不泄漏路径、凭证、内存或宿主内部结构。
• 生产代码不得用 unwrap、expect、panic! 处理 I/O、解析、权限、平台和插件失败。
• 仅真正不可能被外部输入破坏的不变量可断言，并在附近解释不变量来源。
• 降级必须显式返回能力/原因并记录一次结构化事件，不能静默吞错。

4. 异步、UI 与并发

• Slint/winit 事件循环只做短时状态变更；I/O、SQLite、WASM 与网络进入后台 runtime。
• 跨线程消息要有界；定义背压、取消、超时和宿主关闭行为。禁止同步 channel 无限等待。
• UI 更新通过 Slint 事件循环回投；不要在 callback 内 block_on、持锁调用插件或执行阻塞文件操作。
• 每个 plugin instance 是有界串行 actor；不得为提升吞吐并发进入同一 guest Store。State Patch 在 worker 上限流、解析、完整 schema 校验并原子提交，主线程只应用已验证状态。
• 测试修改环境变量、时钟或全局状态时必须隔离并恢复；并行测试不得互相污染。

5. 安全与 unsafe

• unsafe 只允许在 floatile-platform 的最小模块/表达式中，每处写清可检查前提的 // SAFETY: 注释，并用安全 API 封装；调用方不能继续承担隐含前提。
• manifest、路径和 archive 先规范化再访问；拒绝绝对路径、..、链接逃逸、重复条目和超额解压。
• UI IR、State Patch、event payload、assets 与 config 在分配/解析前先做字节、数量、深度和频率上限； P0/MVP 不接受第三方 .slint、HTML、脚本 entrypoint 或 native library。
• 权限判断与执行不可分离到可被替换的两个公开步骤，避免 check/use 竞态和绕过。
• 日志禁止记录 token、Cookie、Authorization、存储值、原始插件配置或用户文件内容。
• 资源限制必须有失败测试：fuel、内存、队列、定时器、存储、包大小和调用频率。

6. 可观测性

• 使用结构化 tracing 字段，不拼接机器可查询的数据；常用字段为 plugin_id、instance_id、 capability、decision、reason，敏感字段只记录已脱敏摘要。
• 错误只在拥有处理责任的边界记录一次；下层返回上下文，上层决定日志级别，避免重复刷屏。
• 性能路径的 span/metric 必须低基数；不得将用户输入直接用作 metric label。

7. 测试

• 纯逻辑写单元测试；crate 边界和持久化写集成测试；平台与 UI 行为写带环境记录的验收测试。
• 每个安全检查至少覆盖允许、拒绝、边界和资源耗尽；拒绝测试同时断言宿主存活与审计结果。
• 测试名称描述行为与条件。测试应确定性运行，不依赖公网、用户主目录、执行顺序或真实时钟。
• bug 修复先增加可复现回归测试。平台不可在本机运行时，保留未验证说明并依靠对应平台 CI/实测。

8. 完成定义

代码格式化、lint、测试通过；需求/ADR/安全/WIT/平台矩阵按变更联动更新；失败和降级路径已测试； 变更说明包含实际命令和环境；没有把设计预期写成实测结论。

9. 跨平台与编码

• 所有文本文件统一 LF + UTF-8（无 BOM），由根 .gitattributes 强制；不要依赖本机 core.autocrlf/core.eol 或编辑器隐式转换。新增脚本前先确认其 eol 规则已写入 .gitattributes（.sh/.ps1/.bat 按执行环境约定），并同步 CI 矩阵。
• 禁止把换行符、编码或路径分隔符写进被追踪内容；使用 std::path 与平台 API 组合路径， 不拼接 "/" 或 "\\" 字面量。
• 文件名与目录名大小写保持一致（macOS/Windows 文件系统大小写不敏感，避免提交后无法检出）； 同一目录不得出现仅大小写不同的文件。
• 平台差异（OS、显示协议、路径、环境变量）收敛在 floatile-platform，其余 crate 按能力矩阵 降级，不得以 OS 名称猜测行为。Windows 下使用文件系统时注意路径长度、大小写与保留名差异。