本文件作用于整个仓库。目标是让每次变更都保持可运行、可验证,并维护插件安全边界和平台差异隔离。
以下规则优先于具体任务流程;完整事实源为 CONTRIBUTING.md。
main是正式版本分支,只接收通过发布门禁的 release PR 或紧急 hotfix;dev是主要开发与集成 分支。禁止直接在main或dev上开发、提交或 push。- 普通任务从最新
dev创建独立分支并通过 PR 合回dev。Agent 分支使用agent/<topic>;人工 分支使用feat/、fix/、refactor/、test/、docs/、ci/或chore/前缀。 - 一个分支只承载一个需求、修复或治理目标。依赖升级单独成分支;不得夹带无关重构、格式化或 其他协作者的修改。
- 所有 Git 修改操作(创建/切换分支、暂存、提交、rebase、删除分支、合并、交付)前都要检查
git status、git branch --show-current与相关 diff,不假设共享工作区的分支或文件状态;新建分支 显式指定基线,不得依赖当前 HEAD。发现不属于当前任务的修改、预期外的分支/提交或并发写入时必须 保留并避让,不得覆盖、回滚或带入提交。 - Agent 未经用户明确授权不得创建或切换分支、stage、commit、push、rebase、merge 或改写历史。 获准提交时只能暂存本任务文件,不得使用宽泛暂存把已有修改一起提交。
- 只有独立可审查、可回退、workspace 可编译且相关测试通过的完整步骤才可提交。半迁移 API、失败
测试、缺失联动文档/绑定/审计或必须写成
WIP的状态应继续开发,不得进入共享历史。 - 每个 commit message 必须包含 subject、空行和有实际内容的 body,并按
CONTRIBUTING.md记录Refs:、Tests:、Unverified:。commit message 的任何位置都不得包含Co-authored-by:;匹配 大小写不敏感。 - 禁止改写共享分支历史或直接 force-push。任务 PR 合入
dev默认 squash merge;发布通过dev → main的 release PR 使用 merge commit,合并后在main打版本标签;hotfix 从main分出、合回main后必须通过 PR 同步到dev。任务分支合并后删除,dev永久保留。
- 先读
CONTRIBUTING.md和docs/README.md,再按任务类型读取其中标出的事实源。 - 实现变更时使用
.agents/skills/develop-floatile;独立验证、审计或验收时使用.agents/skills/verify-floatile。 - 检查工作区状态,保留用户已有变更;不要顺手改无关代码。
- 明确该任务对应的需求、验收项和受影响 crate。没有对应需求时,先更新需求或 ADR。
- 涉及插件平台长期能力、Instance、Connection、Operation 或 capability 演进时,先读
docs/product/plugin-platform-roadmap.md,并用其中的PP-Mx/PP-Gx标明任务归属。
- 插件的宿主能力必须全部经过
PermissionBroker;默认无权限,拒绝也必须审计。 wit/是 host/guest 接口的唯一源。不得手写两套绑定或在 WIT 外暴露宿主句柄。- OS API、窗口系统分支和平台
unsafe只允许出现在floatile-platform。 floatile-core保持纯领域模型与纯逻辑,不做 I/O、不依赖 runtime/UI/platform。floatile-sdk面向wasm32-wasip2guest,不得依赖任何宿主 crate。- Slint 主线程不得阻塞 I/O、等待 Tokio 或同步执行不受信任 wasm。
- 不受信任输入包括 manifest、zip 路径、UI IR、WASM、assets、插件配置、State Patch、事件 payload
和 WIT 参数;校验后再使用。ADR-0001 下 P0/MVP 不接受第三方
.slint。 - 许可 ADR 未通过前不得创建可对外分发的产物或放宽 license gate。
- 改 WIT:同步 API 文档、
floatile-plugin-api、floatile-sdk、TypeScript adapter、runtime 适配、 版本与契约测试。 - 改 UI schema/组件/State/Event:同步 Rust/TypeScript SDK、CLI、runtime、shell renderer、
uiApiVersion、文档示例与双语言 contract vectors;不得手写两套语义。 - 改权限:同步能力注册表、manifest 校验、Broker、审计脱敏和恶意插件测试。
- 改平台能力:先改 platform trait/probe,再改上层降级行为、平台矩阵和平台测试证据。
- 改持久化:新增前向 migration;禁止修改已发布 migration;补升级与回滚失败测试。
- 改 crate 依赖方向、线程模型、安全边界或包格式:同步架构文档;不可逆决策新增 ADR。
- 遵循
docs/development/coding-standards.md;依赖统一声明在根Cargo.toml。 - 文本文件统一 LF + UTF-8(无 BOM),由
.gitattributes强制;不得提交 CRLF 或依赖本机core.autocrlf/core.eol的隐式转换。涉及脚本、CI 矩阵或编码的变更必须同步该规则。 - 生产代码不使用
unwrap/expect/panic!处理可恢复错误;测试中的使用必须局部、清晰。 unsafe必须最小作用域并写// SAFETY:,且只在floatile-platform中出现。- 每次交付至少运行与变更相称的检查;默认完整门禁见
docs/development/workflow.md。 - 不把“能编译”等同于 P0 验收。平台、性能、安全结论必须附环境与日志/数据,未实测写
未验证。 - 不删除失败测试来通过门禁;修复原因或明确记录经批准的例外及到期条件。