From e41c70a5659625a7b6418742bb480c56f267a22c Mon Sep 17 00:00:00 2001
From: showen <showen@local>
Date: Fri, 13 Mar 2026 06:08:57 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20DevicePlugin=E8=AE=BE=E8=AE=A1=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3=20+=20PM=20inbox=E6=B4=BE=E5=8F=91=E4=BB=BB=E5=8A=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .showen/inbox/pm.md          |  21 +++++
 docs/DEVICE_PLUGIN_DESIGN.md | 157 +++++++++++++++++++++++++++++++++++
 2 files changed, 178 insertions(+)
 create mode 100644 docs/DEVICE_PLUGIN_DESIGN.md

diff --git a/.showen/inbox/pm.md b/.showen/inbox/pm.md
index e69de29..6f6f570 100644
--- a/.showen/inbox/pm.md
+++ b/.showen/inbox/pm.md
@@ -0,0 +1,21 @@
+[CEO 陈逸飞] [2026-03-13]
+
+## 任务：DevicePlugin 阶段一实施
+
+设计文档已就绪：`docs/DEVICE_PLUGIN_DESIGN.md`
+
+请组织团队实施阶段一（基础框架）：
+1. 阅读设计文档，理解架构
+2. 拆分任务分配给合适的开发者
+3. 建议分工：
+   - Message enum 扩展 (DeviceCommand/Response/Event) — 1人
+   - DevicePlugin 骨架 (src/plugins/device/mod.rs + backend.rs) — 1人
+   - Linux ARM64 后端 (linux_arm64.rs，至少 Display + SleepInhibit) — 1人
+   - 测试编写 — 1人
+4. 注意事项：
+   - 有文件依赖的任务串行，不要并行
+   - 先改 Message enum，再写 DevicePlugin，最后写后端和测试
+   - 每个人完成后更新自己的 soul 文件
+5. 完成后汇报结果到 .showen/inbox/ceo.md
+
+时效：尽快启动
diff --git a/docs/DEVICE_PLUGIN_DESIGN.md b/docs/DEVICE_PLUGIN_DESIGN.md
new file mode 100644
index 0000000..a4af93b
--- /dev/null
+++ b/docs/DEVICE_PLUGIN_DESIGN.md
@@ -0,0 +1,157 @@
+# DevicePlugin 统一设备管理插件设计
+
+## 1. 核心理念
+
+所有硬件访问统一通过 DevicePlugin 一个插件完成。多平台适配只需替换 DevicePlugin 的后端实现，上层业务插件无需改动。
+
+## 2. 架构
+
+```
+┌──────────────────────────────────────────┐
+│         业务插件 (Video/BLE/HTTP/...)     │
+│    通过 Message 发送 DeviceCommand        │
+├──────────────────────────────────────────┤
+│              DevicePlugin                │
+│  接收 DeviceCommand → 分发给 Backend      │
+│  Backend 事件 → 发送 DeviceEvent 消息     │
+├──────────────────────────────────────────┤
+│           DeviceBackend trait             │
+│  ┌─────────┬──────────┬───────────────┐  │
+│  │ Linux   │ Android  │ Embedded      │  │
+│  │ ARM64   │          │ (bare-metal)  │  │
+│  └─────────┴──────────┴───────────────┘  │
+├──────────────────────────────────────────┤
+│           硬件层                          │
+│  Framebuffer / DRM / GPIO / I2C / SPI    │
+│  Screen / Backlight / Sensors / Audio    │
+└──────────────────────────────────────────┘
+```
+
+## 3. DeviceBackend trait
+
+```rust
+pub trait DeviceBackend: Send {
+    /// 后端名称 (如 "linux-arm64", "android", "embedded")
+    fn name(&self) -> &str;
+
+    /// 初始化后端
+    fn init(&mut self, config: &serde_json::Value) -> Result<()>;
+
+    /// 处理设备命令
+    fn handle_command(&mut self, cmd: DeviceCommand) -> Result<DeviceResponse>;
+
+    /// 获取设备能力列表
+    fn capabilities(&self) -> Vec<DeviceCapability>;
+
+    /// 关闭后端
+    fn shutdown(&mut self) -> Result<()>;
+}
+```
+
+## 4. 消息类型
+
+### DeviceCommand (业务插件 → DevicePlugin)
+```rust
+pub enum DeviceCommand {
+    // 显示
+    GetDisplayInfo,
+    SetBrightness(u8),
+    SetBacklight(bool),
+    WriteFramebuffer { data: Vec<u8>, format: PixelFormat },
+
+    // 输入
+    GetTouchEvents,
+    GetButtonState,
+    GetSensorData(SensorType),
+
+    // 音频
+    PlayAudio { path: String },
+    SetVolume(u8),
+
+    // 电源
+    GetBatteryLevel,
+    SetSleepInhibit(bool),
+
+    // 通用
+    CustomCommand { subsystem: String, payload: serde_json::Value },
+}
+```
+
+### DeviceResponse (DevicePlugin → 请求者)
+```rust
+pub enum DeviceResponse {
+    DisplayInfo { width: u32, height: u32, format: PixelFormat },
+    SensorData { sensor: SensorType, value: f64 },
+    BatteryLevel(u8),
+    Ok,
+    Error(String),
+    Custom(serde_json::Value),
+}
+```
+
+### DeviceEvent (DevicePlugin → 广播)
+```rust
+pub enum DeviceEvent {
+    TouchEvent { x: i32, y: i32, action: TouchAction },
+    ButtonEvent { button: u8, pressed: bool },
+    BatteryLow(u8),
+    DisplayConnected,
+    DisplayDisconnected,
+    SensorAlert { sensor: SensorType, value: f64 },
+}
+```
+
+## 5. DeviceCapability
+
+```rust
+pub enum DeviceCapability {
+    Display,
+    Touch,
+    Buttons,
+    Audio,
+    Battery,
+    Backlight,
+    Sensors,
+    Framebuffer,
+    GPIO,
+}
+```
+
+## 6. 实施计划
+
+### 阶段一：基础框架
+1. 在 Message enum 中添加 DeviceCommand/DeviceResponse/DeviceEvent 变体
+2. 创建 src/plugins/device/mod.rs — DevicePlugin 实现
+3. 创建 src/plugins/device/backend.rs — DeviceBackend trait
+4. 创建 src/plugins/device/linux_arm64.rs — 当前平台后端
+
+### 阶段二：迁移现有功能
+1. ScreenPlugin 的防息屏/光标隐藏 → DevicePlugin.SetSleepInhibit/backlight
+2. VideoPlugin 的 framebuffer 写入 → DevicePlugin.WriteFramebuffer
+3. 保持旧插件作为 thin wrapper 过渡期兼容
+
+### 阶段三：扩展
+1. 触摸/按钮输入事件
+2. 传感器数据读取
+3. 音频播放
+4. 其他平台后端 (Android 等)
+
+## 7. 关键约束
+- DevicePlugin 是唯一允许直接访问硬件的插件
+- 其他插件通过 Message 与 DevicePlugin 交互
+- DeviceBackend 通过编译 feature gate 或运行时配置选择
+- 首次实现只需支持 Linux ARM64 后端
+- 所有 DeviceCommand 必须是 Serialize + Deserialize (跨 FFI 边界)
+
+## 8. 验收标准
+- [ ] DevicePlugin 通过 Plugin trait 正确注册和启动
+- [ ] 至少 Display + SleepInhibit 两个能力在 Linux ARM64 后端工作
+- [ ] ScreenPlugin 功能迁移到 DevicePlugin 且测试通过
+- [ ] 新增测试 ≥ 5 个
+- [ ] cargo check 零 warning, cargo test 全部通过
+
+## CEO 决策
+- 报告来源：架构师王思远分析设计
+- 评审结论：方案通过，分三阶段实施
+- 优先级：P1 (Phase 2 核心任务)
+- 负责人：待 PM 分配