把轻量、可组合、受控的 Widget 带到你的桌面。
一个面向 Windows、macOS 与 Linux 的跨平台桌面浮动组件宿主，使用 Rust、Slint 与 WASM Component Model 构建。
English · 简体中文
Important
Floatile 当前处于 P0 技术可行性验证阶段，尚未发布可供日常使用的稳定版本。 本文中的 🧪 和 🗺️ 项目代表开发中或规划能力，不是已完成承诺。现阶段的目标是用可复现证据 验证跨平台窗口与沙箱插件链路，并如实暴露平台限制。
Floatile 希望提供一块始终在桌面上的轻量画布：时钟、系统状态、倒计时、开发工具或第三方 Widget 可以自由布局，却不能绕过宿主直接读取文件、访问网络、执行命令或控制原生窗口。
- 像桌面的一部分：透明、无边框、置顶的浮动窗口，并为平台不支持的能力提供明确降级。
- 编辑与展示分离：编辑模式负责拖拽、缩放与配置；展示模式隐藏宿主控件并按能力启用点击穿透。
- 插件默认不可信：计划以 WASM Component Model 隔离插件，所有宿主能力统一经过
deny-by-default
PermissionBroker。 - 跨平台但不假装一致：能力由运行时探测驱动；尤其在 Wayland 下会报告限制，而不是静默失败。
- 为插件作者和 AI Agent 设计：Rust/TypeScript 共用
State / View / Event / Context模型；WIT、 UI schema、权限和诊断各自单源生成，CLI 隐藏 Wasmtime、Slint 与打包细节。
状态图例：✅ 已有基础实现 · 🧪 正在开发/等待完整验证 · 🗺️ 规划中
| 能力 | 状态 | 当前说明 |
|---|---|---|
| Rust workspace 与领域基础类型 | ✅ | 12 个 Rust crate、两个 WASM fixture、固定工具链与基础 CI 已建立 |
| 原生参考时钟 | ✅ | 可运行的 Slint 时钟，每秒更新，用作窗口与性能基线 |
| 透明、无边框、置顶窗口 | 🧪 | Windows、Linux X11 与 macOS 已有运行证据；X11 无合成器时显式降级为不透明，Wayland 待实测 |
| 窗口拖拽 | 🧪 | Windows、Linux Xvfb 与 VMware Xfce/Xorg 已运行验证；macOS/Wayland 待交互实测 |
| 平台能力探测与降级 | 🧪 | Windows 原生探测、X11 compositor/SHAPE/EWMH/RandR 实探测与 macOS 探测（点击穿透/置顶/显示器/指标/热键）已落地；Wayland 仅有显式协议降级 |
| 编辑/展示模式、缩放与多屏布局 | 🧪 | Edit/Show、点击穿透联动和拖拽缩放已在 Windows 与 Linux X11 子路径落地；平台无关的主屏降级/原屏回归已实现，Canvas 接入及真实多屏/DPI/热插拔仍待验证 |
| SQLite 持久化 | 🧪 | layout schema v2、audit schema v3 与 plugin instance schema v4 已落地；实例 CRUD 支持受限 Config、desired state、generation、重启恢复与不复用 ID；真实多屏/热插拔实机验证待做 |
| 持久化插件实例 | 🧪 | floatile instance create/list/get/configure/start/stop/delete 已打通同包多实例 CRUD，Config 在 CLI 和运行恢复时共用随包 schema 复验；shell 后台监督器会动态对齐 desired state，独立启停/重启窗口并隔离单实例失败。实际动态多窗口 Xvfb/真机证据与 observed-state 管理界面待续 |
| 统一 UI + WASM Widget | 🧪 | ADR-0001/0002 的 UI IR、renderer、运行时窗口、Wasmtime actor、Broker 与 Rust SDK 已落地并通过 Clock/恶意输入测试；ADR-0003 的 TypeScript runtime spike 为 no-go（StarlingMonkey 资源门失败、QuickJS 契约门失败），TypeScript SDK 与 F11 仍未完成 |
| Permission Broker 与审计 | 🧪 | deny-by-default、scope/配额、clock/log/timer/storage/metrics/theme、恶意插件 fixture 与脱敏 SQLite 审计已实现；插件 private KV 仍为进程内存储，真实容量数据待补 |
| 插件 SDK 与打包 CLI | 🧪 | Rust SDK 与 new/validate/build/install/dev/test/schema/instance 已实现，实例命令提供稳定 JSON 结果/错误 code；dev 目前只 watch+build，真实窗口 preview、inspect/run 与全命令 JSON 契约待做 |
| 三平台与性能验收 | 🗺️ | 指标仅为目标值，目前不代表已达到或已验证 |
权威进度与验收范围请查看需求基线和 P0 验收标准；P0 之后的平台北极星、领域模型与里程碑见 插件平台长期演进路线。
- 透明、无边框、Always-on-top 的 Widget 窗口（🧪）
- Edit / Show 双模式与按平台能力启用的点击穿透（🧪 Windows 与 Linux X11 已实测，其他平台按能力降级）
- 拖拽（🧪）、缩放（🧪）、层级管理和逻辑像素布局（🗺️）
- 多显示器、DPI 缩放、热插拔恢复和显式降级记录（🧪 逻辑与持久化已接入 shell，Xvfb 实测；真实多屏实机验证待做）
- 内建参考时钟（✅）与后续插件化时钟示例（🗺️）
- 统一 Floatile UI IR + WASM Component Model + 版本化 WIT 契约（🗺️）
- Wasmtime fuel、内存上限、调用频率与生命周期预算（🗺️）
- 所有宿主能力必须通过
PermissionBroker，默认拒绝（🗺️） - 存储、计时器、指标与日志能力的 scope、配额和脱敏审计（🗺️）
- 对 manifest、归档路径、UI IR、WASM、assets、配置、State Patch 与 WIT 参数进行不可信输入校验（🗺️）
- Rust/TypeScript 使用同一
State / View / Event / Context与组件语义（🗺️） - 构建期 JSX/Rust View →
widget.ftui；插件作者不写 WIT、manifest 生成物或 Slint（🗺️） floatile new/dev/check/test/preview/build/inspect与稳定--jsonAgent 接口（🗺️）- 原生、Rust WASM 与 TypeScript WASM 时钟参考实现（原生 ✅，插件版 🗺️）
插件市场、签名/自动更新、自定义主题/主题编辑器、凭证托管、网络 Broker、跨插件通信和 Sidecar 不在 P0 范围内；它们属于后续阶段的候选能力。
- 已安装
rustup - 可用的桌面图形环境
- Linux 需要满足 Slint/winit 后端的系统依赖；透明效果还取决于显示协议与合成器
仓库通过 rust-toolchain.toml 自动选择 Rust 1.97.1，并安装 wasm32-wasip2 target。
git clone https://github.com/powercess/floatile.git
cd floatile
rustup show
cargo run -p floatile-shell --locked当前程序会启动一个参考时钟浮窗。平台能力尚在开发中，因此窗口透明、置顶或拖拽行为可能按环境 降级；日志会显示探测结果。时钟目前按 UTC 秒数展示，尚未接入本地时区。
查看更详细日志：
RUST_LOG=debug cargo run -p floatile-shell --lockedcargo fmt --all -- --check
cargo check --workspace --all-targets --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --all-targets --lockedflowchart TB
Shell["floatile-shell<br/>画布 · 模式 · 生命周期"]
Runtime["floatile-runtime<br/>实例 Actor · State · Wasmtime（已实现）"]
UI["Floatile UI Renderer<br/>widget.ftui → Slint（开发中）"]
Broker["PermissionBroker<br/>授权 · 配额 · 审计（已实现）"]
Services["floatile-services<br/>计时器 · 存储 · 指标（已实现）"]
Store["floatile-store<br/>SQLite（开发中）"]
Platform["floatile-platform<br/>唯一的 OS / 窗口系统边界"]
Plugin["Widget Plugin<br/>widget.ftui + plugin.wasm（开发中）"]
Contract["UI schema + WIT<br/>双 SDK 单一语义（开发中）"]
Shell --> Runtime
Shell --> UI
Shell --> Platform
Runtime --> Plugin
Plugin <--> Contract
Runtime --> Broker
Broker --> Services
Services --> Store
Services --> Platform
插件不能获得宿主原生句柄；所有未来宿主能力都必须经过 Broker。Slint 主线程只运行事件循环， 后台 I/O 与不可信 WASM 计划交给 Tokio/Wasmtime，并通过有界消息通道回投 UI。
| 层级 | 技术 | 状态/用途 |
|---|---|---|
| 语言与工具链 | Rust 2024 · Rust 1.97.1 | ✅ 固定 patch 工具链与 lockfile |
| UI 与窗口 | Slint 1.17 · winit 0.30 | 🧪 参考时钟和基础窗口属性已接入 |
| 插件 UI | Floatile UI IR v1 | 🧪 IR 类型、组件 registry 与 State/Event schema 校验已实现；renderer/CLI 联动待做 |
| 插件 ABI | WIT · WASM Component Model · wasm32-wasip2 |
🧪 ADR-0001 目标契约与双端 bindings 已迁移并通过 wasm-tools validate |
| 插件运行时 | Wasmtime 47 + wasmtime-wasi p2 | 🧪 异步组件调用、fuel/内存限制与空 WASI 上下文（零 ambient） |
| 异步运行时 | Tokio | 🧪 runtime/services 已接入，承载后台 I/O，避免阻塞 Slint 主线程 |
| 持久化 | SQLite · rusqlite (bundled) | 🧪 layout schema v2 与恢复元数据；插件 KV 与审计日志 🗺️ |
| 数据与错误 | serde · serde_json · thiserror | ✅/🧪 逐阶段接入契约与错误模型 |
| 可观测性 | tracing · tracing-subscriber | ✅ 基础日志；结构化审计 🗺️ |
| 工程质量 | rustfmt · Clippy · Cargo test · cargo-deny · GitHub Actions | ✅ 三系统 CI 配置 |
完整版本策略与选型边界见技术栈文档。
| Crate | 职责 | 当前阶段 |
|---|---|---|
floatile-core |
纯领域模型、ID、坐标与权限类型 | 🧪 |
floatile-platform |
平台能力探测与全部 OS 窗口差异 | 🧪 |
floatile-shell |
桌面宿主、画布、模式与应用编排 | 🧪 |
floatile-plugin-api |
WIT host bindings 与契约类型 | 🧪 |
floatile-ui-schema |
guest-safe UI IR、组件与 State/Event schema 单源 | 🧪 |
floatile-runtime |
实例 actor、State、预算与 Wasmtime 执行 | 🧪 |
floatile-services |
经 Broker 授权的宿主服务 | 🧪 |
floatile-store |
SQLite、migration 与事务 | 🧪 |
floatile-sdk |
WASI guest SDK + 作者层（Widget/View/Context/derive State） | 🧪 |
floatile-cli |
插件包校验、构建与开发工具 | 🧪 |
crate 之间的依赖规则不是建议，而是安全与可移植性边界。详情见 Workspace 与 crate 边界。
| 平台 | 目标 | 当前证据 |
|---|---|---|
| Windows | 透明、置顶、点击穿透、编辑/展示模式 | 透明/置顶/点击穿透 API 与编辑/展示模式、拖拽、缩放已有实测（2026-08-13，DWM） |
| macOS | 透明、置顶、点击穿透、编辑/展示模式 | 探测、无边框置顶窗口、布局持久化与恢复已实测（2026-08-17，macOS 15.7.5）；穿透/拖拽/缩放交互待人工复核 |
| Linux X11 | 依赖合成器的透明窗口与窗口管理器能力 | Xvfb/Openbox/picom 与 VMware Xfce/Xorg 证据已记录；物理多屏/DPI/热插拔待验证 |
| Linux Wayland | 能力分级并明确降级，不承诺与 X11 完全一致 | headless weston 协议层已验证显式降级；真实桌面会话待验证 |
这里的“目标”不是兼容性声明。真实平台证据只记录在 平台能力矩阵中。
- S1 · 浮窗基线（进行中）：参考时钟、透明/无边框/置顶、拖拽和真实平台探测
- S2 · 桌面交互（进行中）：Edit/Show、点击穿透和缩放已在 Windows/Linux X11 子路径落地；真实多屏与 DPI 仍待验证
- S3 · 布局持久化（进行中）：monitor-local 恢复算法、SQLite v2、shell 启动恢复/保存与显示器变化重恢复已落地；真实多屏/热插拔实机验证与多实例编排待做
- S4 · 插件契约（架构完成、契约已迁移）：ADR-0001、统一 UI、WIT、manifest 与双 SDK 架构；WIT/bindings/clock 已迁移到统一 lifecycle 并 validate 通过
- S5 · 沙箱运行时（进行中）：UI schema/renderer、runtime actor、State Patch、Wasmtime、Broker、CLI 包校验、Rust SDK 与恶意插件测试已落地；TypeScript runtime 在 ADR-0003 资源/契约门 no-go，等待后继候选
- P0 验收（规划中）：Windows/macOS/X11/Wayland 证据、性能数据、风险复盘与许可 ADR
路线图会随验证证据调整。某项技术不可行但被准确记录和降级，同样是 P0 的有效产出。 面向开发者平台的 PP-M0 至 PP-M10 长期路线独立维护在 插件平台长期演进路线，不会用未来规划覆盖本节的 P0 状态。
Floatile 欢迎问题报告、设计讨论、文档改进和小而完整的实现。不过项目仍处在架构与许可收敛期， 开始编码前请先阅读：
- 贡献指南——分支、提交、测试与 PR 规则
- 项目需求基线——P0 范围、需求 ID 与非目标
- 插件平台长期演进路线——平台原则、领域模型与 PP-M0 至 PP-M10
- 文档索引——各领域的权威事实源
- 开发与验证流程——本地门禁与证据要求
普通变更应从最新 dev 创建单一目标分支，并通过 PR 合回 dev。安全、WIT、平台、持久化或
crate 边界变更需要同步相应契约、测试和架构文档。
- 插件平台长期演进路线
- P0 技术设计
- P0 验收标准
- 技术栈与版本策略
- 插件权限模型
- Manifest v1
- WIT API v1
- Floatile UI IR v1
- 插件系统架构
- Rust/TypeScript SDK 与开发体验
- ADR-0001：统一插件 UI
- 架构风险清单
当前插件安全边界仍在设计和实现中，请勿运行来源不明的 WASM、UI IR、assets 或插件包。P0/MVP
插件不接受第三方 .slint。发现安全问题时，
请不要公开披露可利用细节；在专用安全联系渠道建立前，请通过仓库所有者的私密联系方式报告。
Warning
仓库当前标记为 PROPRIETARY，且 Slint 分发许可仍待法务与商业路线决策。Floatile 目前不是
已获许可对外分发的开源软件。在许可分析完成并形成 ADR 前，
不得发布二进制、SDK 或 .floatile 包，也不得自行添加开源 LICENSE。
如果 Floatile 的方向对你有吸引力，欢迎留下一个 ⭐ 并关注 P0 的验证进展。