docs: DevicePlugin阶段一任务分解 + PM soul更新

2026-03-13 06:12:39 +08:00
parent e41c70a565
commit f83e18d43b
3 changed files with 334 additions and 21 deletions
--- a/.showen/DEVICE_PLUGIN_TASKS.md
+++ b/.showen/DEVICE_PLUGIN_TASKS.md
@@ -0,0 +1,322 @@
+# DevicePlugin 阶段一任务分解文档
+
+## 项目背景
+根据 CEO 陈逸飞指示和架构师王思远设计文档 `docs/DEVICE_PLUGIN_DESIGN.md`，实施 DevicePlugin 统一设备管理插件的阶段一（基础框架）。
+
+## 总体目标
+建立 DevicePlugin 基础框架，支持 Linux ARM64 平台的 Display 和 SleepInhibit 两个核心能力，为后续功能扩展打下基础。
+
+## 任务列表与执行顺序
+
+### Task 1: Message enum 扩展
+**负责人建议**: 张明远（内核工程师，精通 Rust 类型系统和消息传递）
+
+**优先级**: P0（阻塞后续所有任务）
+
+**输入文件**:
+- `src/core/message.rs` — 现有 Message enum 定义
+- `docs/DEVICE_PLUGIN_DESIGN.md` — DeviceCommand/DeviceResponse/DeviceEvent 设计
+
+**任务描述**:
+1. 在 `Message` enum 中添加三个新变体：
+   - `DeviceCommand(DeviceCommand)` — 业务插件向 DevicePlugin 发送的命令
+   - `DeviceResponse(DeviceResponse)` — DevicePlugin 返回的响应
+   - `DeviceEvent(DeviceEvent)` — DevicePlugin 广播的事件
+2. 在 `message.rs` 中定义以下新类型（参考设计文档第4节）：
+   - `pub enum DeviceCommand` — 至少包含 GetDisplayInfo, SetBrightness, SetBacklight, WriteFramebuffer, SetSleepInhibit
+   - `pub enum DeviceResponse` — 至少包含 DisplayInfo, Ok, Error
+   - `pub enum DeviceEvent` — 至少包含 DisplayConnected, DisplayDisconnected
+   - `pub enum DeviceCapability` — 至少包含 Display, Backlight, Framebuffer
+   - `pub enum PixelFormat` — 至少包含 RGBA8888, RGB888
+   - `pub enum SensorType` — 预留，至少包含 Temperature
+   - `pub enum TouchAction` — 预留，至少包含 Down, Move, Up
+3. 所有新类型必须派生 `Debug, Clone, Serialize, Deserialize`（跨 FFI 边界要求）
+4. 为复杂变体添加文档注释说明用途
+
+**输出文件**:
+- `src/core/message.rs` — 更新后的消息定义
+
+**验收标准**:
+- [ ] `cargo check --workspace` 零 warning
+- [ ] 所有新类型正确派生 serde traits
+- [ ] DeviceCommand 至少包含 5 个变体（Display + SleepInhibit 相关）
+- [ ] DeviceResponse 至少包含 3 个变体
+- [ ] 文档注释清晰说明每个变体的用途
+
+**预计工时**: 2 小时
+
+---
+
+### Task 2: DevicePlugin 骨架与 Backend trait
+**负责人建议**: 王思远（架构师，精通系统架构和 trait 设计）
+
+**优先级**: P0（依赖 Task 1）
+
+**依赖**: Task 1 必须完成（Message enum 已扩展）
+
+**输入文件**:
+- `src/core/message.rs` — Task 1 完成后的消息定义
+- `src/plugins/screen/mod.rs` — 现有插件实现参考
+- `src/core/plugin.rs` — Plugin trait 定义
+- `docs/DEVICE_PLUGIN_DESIGN.md` — DeviceBackend trait 设计（第3节）
+
+**任务描述**:
+1. 创建 `src/plugins/device/mod.rs`：
+   - 定义 `pub struct DevicePlugin` 包含字段：
+     - `ctx: Option<PluginContext>`
+     - `backend: Box<dyn DeviceBackend>`
+   - 实现 `Plugin` trait 的所有方法：
+     - `id()` 返回 "device"
+     - `info()` 返回插件信息
+     - `init()` 初始化 backend
+     - `start()` 启动 backend
+     - `handle_message()` 匹配 `Message::DeviceCommand`，调用 `backend.handle_command()`，返回 `Message::DeviceResponse`
+     - `stop()` 调用 `backend.shutdown()`
+   - 实现 `DevicePlugin::new(backend: Box<dyn DeviceBackend>)` 构造函数
+2. 创建 `src/plugins/device/backend.rs`：
+   - 定义 `pub trait DeviceBackend: Send` 包含方法（参考设计文档）：
+     - `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<()>;`
+   - 添加完整的文档注释说明每个方法的职责
+3. 在 `src/plugins/device/mod.rs` 中添加 `pub mod backend;` 和 `pub use backend::DeviceBackend;`
+4. 在 `src/plugins/mod.rs` 中添加 `pub mod device;`
+
+**输出文件**:
+- `src/plugins/device/mod.rs` — DevicePlugin 实现
+- `src/plugins/device/backend.rs` — DeviceBackend trait 定义
+- `src/plugins/mod.rs` — 模块导出更新
+
+**验收标准**:
+- [ ] `cargo check --workspace` 零 warning
+- [ ] DevicePlugin 正确实现 Plugin trait 所有方法
+- [ ] DeviceBackend trait 方法签名与设计文档一致
+- [ ] handle_message 正确处理 DeviceCommand 并返回 DeviceResponse
+- [ ] 文档注释完整，说明插件职责和 trait 用途
+
+**预计工时**: 3 小时
+
+---
+
+### Task 3: Linux ARM64 Backend 实现
+**负责人建议**: 赵雨薇（屏幕工程师，精通 Linux 显示系统和电源管理）
+
+**优先级**: P0（依赖 Task 2）
+
+**依赖**: Task 2 必须完成（DeviceBackend trait 已定义）
+
+**输入文件**:
+- `src/plugins/device/backend.rs` — Task 2 完成后的 trait 定义
+- `src/plugins/screen/mod.rs` — 现有 ScreenPlugin 实现（参考 systemd-inhibit 用法）
+- `docs/DEVICE_PLUGIN_DESIGN.md` — 后端实现要求
+
+**任务描述**:
+1. 创建 `src/plugins/device/linux_arm64.rs`：
+   - 定义 `pub struct LinuxArm64Backend` 包含字段：
+     - `wake_lock_child: Option<Child>` — systemd-inhibit 子进程
+     - `display_info: Option<DisplayInfo>` — 缓存的显示信息
+     - `backlight_enabled: bool` — 背光状态
+   - 实现 `DeviceBackend` trait：
+     - `name()` 返回 "linux-arm64"
+     - `init()` 读取 framebuffer 信息（/sys/class/graphics/fb0/virtual_size），初始化 display_info
+     - `capabilities()` 返回 `vec![DeviceCapability::Display, DeviceCapability::Backlight, DeviceCapability::Framebuffer]`
+     - `handle_command()` 实现以下命令：
+       - `GetDisplayInfo` → 返回 `DisplayInfo { width, height, format }`
+       - `SetSleepInhibit(true)` → 启动 systemd-inhibit（参考 ScreenPlugin::start_wake_lock）
+       - `SetSleepInhibit(false)` → 停止 systemd-inhibit（参考 ScreenPlugin::stop_wake_lock）
+       - `SetBacklight(bool)` → 写入 `/sys/class/backlight/*/brightness`（0 或最大值）
+       - 其他命令返回 `DeviceResponse::Error("Not implemented".to_string())`
+     - `shutdown()` 清理 wake_lock_child
+   - 实现 `LinuxArm64Backend::new() -> Self` 构造函数
+   - 添加 `#[cfg(target_os = "linux")]` 条件编译
+2. 在 `src/plugins/device/mod.rs` 中：
+   - 添加 `#[cfg(target_os = "linux")] pub mod linux_arm64;`
+   - 添加 `#[cfg(target_os = "linux")] pub use linux_arm64::LinuxArm64Backend;`
+   - 添加便捷构造函数 `pub fn new_default() -> Self`，自动选择当前平台后端
+
+**输出文件**:
+- `src/plugins/device/linux_arm64.rs` — Linux ARM64 后端实现
+- `src/plugins/device/mod.rs` — 更新模块导出和便捷构造函数
+
+**验收标准**:
+- [ ] `cargo check --workspace` 零 warning
+- [ ] LinuxArm64Backend 正确实现 DeviceBackend trait
+- [ ] GetDisplayInfo 能正确读取 framebuffer 信息
+- [ ] SetSleepInhibit 能启动/停止 systemd-inhibit 子进程
+- [ ] SetBacklight 能控制背光（至少支持开/关）
+- [ ] shutdown 正确清理子进程资源
+- [ ] 非 Linux 平台编译不报错（条件编译正确）
+
+**预计工时**: 4 小时
+
+---
+
+### Task 4: 集成测试与文档
+**负责人建议**: 李思琪（视频引擎工程师，熟悉状态机和测试，有 Message 序列化经验）
+
+**优先级**: P1（依赖 Task 3）
+
+**依赖**: Task 3 必须完成（Backend 实现完成）
+
+**输入文件**:
+- `src/plugins/device/` — Task 1-3 完成后的所有文件
+- `src/plugins/screen/mod.rs` — 参考现有插件测试模式
+- `docs/DEVICE_PLUGIN_DESIGN.md` — 验收标准（第8节）
+
+**任务描述**:
+1. 创建 `src/plugins/device/tests.rs`：
+   - 编写至少 5 个单元测试：
+     - `test_device_command_serialization` — 测试 DeviceCommand 序列化/反序列化
+     - `test_device_response_serialization` — 测试 DeviceResponse 序列化/反序列化
+     - `test_backend_capabilities` — 测试 backend.capabilities() 返回正确能力列表
+     - `test_get_display_info` — 测试 GetDisplayInfo 命令（mock backend）
+     - `test_set_sleep_inhibit` — 测试 SetSleepInhibit 命令（mock backend）
+   - 实现一个 `MockBackend` 用于测试（不依赖真实硬件）
+2. 在 `src/plugins/device/mod.rs` 中添加 `#[cfg(test)] mod tests;`
+3. 更新 `docs/DEVICE_PLUGIN_DESIGN.md`：
+   - 在第8节验收标准中勾选已完成项
+   - 添加"使用示例"章节，展示如何创建和使用 DevicePlugin
+4. 创建 `src/plugins/device/README.md`：
+   - 说明 DevicePlugin 的职责和架构
+   - 列出支持的平台和能力
+   - 提供代码示例（如何发送 DeviceCommand）
+   - 说明如何添加新的 Backend 实现
+
+**输出文件**:
+- `src/plugins/device/tests.rs` — 单元测试
+- `src/plugins/device/README.md` — 插件文档
+- `docs/DEVICE_PLUGIN_DESIGN.md` — 更新验收标准
+
+**验收标准**:
+- [ ] `cargo check --workspace --all-targets` 零 warning
+- [ ] `cargo test --workspace` 全部通过
+- [ ] 至少 5 个测试用例，覆盖核心功能
+- [ ] MockBackend 实现完整，可用于测试
+- [ ] README.md 包含清晰的使用示例和架构说明
+- [ ] 设计文档验收标准已更新
+
+**预计工时**: 3 小时
+
+---
+
+### Task 5: ScreenPlugin 功能迁移验证（可选）
+**负责人建议**: 赵雨薇（ScreenPlugin 原作者，熟悉现有实现）
+
+**优先级**: P2（依赖 Task 4，可延后到阶段二）
+
+**依赖**: Task 4 必须完成（测试通过）
+
+**输入文件**:
+- `src/plugins/screen/mod.rs` — 现有 ScreenPlugin 实现
+- `src/plugins/device/` — 新的 DevicePlugin 实现
+
+**任务描述**:
+1. 在 `src/plugins/screen/mod.rs` 中添加注释标记待迁移功能：
+   - `start_wake_lock()` → 改为发送 `Message::DeviceCommand(DeviceCommand::SetSleepInhibit(true))`
+   - `stop_wake_lock()` → 改为发送 `Message::DeviceCommand(DeviceCommand::SetSleepInhibit(false))`
+2. 创建 `docs/SCREEN_PLUGIN_MIGRATION.md` 迁移计划文档：
+   - 列出需要迁移的功能清单
+   - 说明迁移步骤和兼容性策略
+   - 标记阶段二执行的具体任务
+3. 验证 DevicePlugin 和 ScreenPlugin 可以共存（不冲突）
+
+**输出文件**:
+- `src/plugins/screen/mod.rs` — 添加迁移注释
+- `docs/SCREEN_PLUGIN_MIGRATION.md` — 迁移计划文档
+
+**验收标准**:
+- [ ] 迁移计划文档完整，列出所有待迁移功能
+- [ ] ScreenPlugin 和 DevicePlugin 同时注册不报错
+- [ ] `cargo check` 和 `cargo test` 通过
+
+**预计工时**: 2 小时
+
+---
+
+## 任务依赖关系图
+
+```
+Task 1 (Message enum)
+   ↓
+Task 2 (DevicePlugin 骨架 + Backend trait)
+   ↓
+Task 3 (Linux ARM64 Backend)
+   ↓
+Task 4 (测试与文档)
+   ↓
+Task 5 (ScreenPlugin 迁移验证，可选)
+```
+
+## 团队成员能力评估
+
+| 成员     | 角色           | 相关经验                                      | 适合任务 |
+|----------|----------------|-----------------------------------------------|----------|
+| 张明远   | 内核工程师     | Rust 类型系统★★★★★，消息传递★★★★★            | Task 1   |
+| 王思远   | 架构师         | 系统架构★★★★★，trait 设计★★★★★               | Task 2   |
+| 赵雨薇   | 屏幕工程师     | Linux 显示系统★★★★★，电源管理经验丰富         | Task 3, 5|
+| 李思琪   | 视频引擎工程师 | 状态机★★★★★，Message 序列化经验，测试经验     | Task 4   |
+| 王浩然   | 网络工程师     | 异步编程★★★★★，但本阶段无网络需求             | 备用     |
+
+## 关键风险与应对
+
+### 风险 1: Message enum 改动影响现有插件
+**影响**: 中
+**应对**: Task 1 完成后立即运行 `cargo check --workspace` 验证所有插件编译通过
+
+### 风险 2: systemd-inhibit 在某些 Linux 发行版不可用
+**影响**: 低
+**应对**: Task 3 中添加错误处理，systemd-inhibit 失败时记录警告但不阻塞插件启动
+
+### 风险 3: framebuffer 路径在不同设备上可能不同
+**影响**: 中
+**应对**: Task 3 中实现路径探测逻辑，尝试 /dev/fb0, /sys/class/graphics/fb0 等多个路径
+
+### 风险 4: 任务串行导致总工时较长
+**影响**: 中
+**应对**: Task 1-3 必须串行，但 Task 4 可以在 Task 3 完成 80% 时提前开始准备 MockBackend
+
+## 时间估算
+
+| 任务   | 预计工时 | 依赖关系 | 可并行 |
+|--------|----------|----------|--------|
+| Task 1 | 2h       | 无       | 否     |
+| Task 2 | 3h       | Task 1   | 否     |
+| Task 3 | 4h       | Task 2   | 否     |
+| Task 4 | 3h       | Task 3   | 否     |
+| Task 5 | 2h       | Task 4   | 可选   |
+
+**总计**: 12-14 小时（1.5-2 个工作日，假设单人串行）
+
+**优化方案**: 
+- Task 1 完成后，Task 2 和 Task 3 的负责人可以同时开始准备（阅读文档、设计实现）
+- Task 4 可以在 Task 3 完成 80% 时开始编写 MockBackend
+
+## 验收总清单
+
+阶段一完成的标志：
+
+- [ ] `cargo check --workspace --all-targets` 零 warning
+- [ ] `cargo test --workspace` 全部通过
+- [ ] DevicePlugin 通过 Plugin trait 正确注册和启动
+- [ ] Linux ARM64 后端支持 Display + SleepInhibit 两个能力
+- [ ] 至少 5 个单元测试覆盖核心功能
+- [ ] 文档完整（README.md + 设计文档更新）
+- [ ] Message enum 扩展不影响现有插件编译
+
+## 汇报要求
+
+每个任务完成后，负责人需要：
+1. 运行 `export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo check --workspace --all-targets` 验证编译
+2. 运行 `export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo test --workspace` 验证测试
+3. 更新自己的 soul 文件，记录本次任务经验
+4. 在 `.showen/TEAM_CHAT.md` 中汇报任务完成情况
+
+全部任务完成后，PM 刘建国向 CEO 汇报到 `.showen/inbox/ceo.md`。
+
+---
+
+**文档创建时间**: 2026-03-13  
+**文档创建人**: PM 刘建国  
+**文档版本**: v1.0
--- a/.showen/inbox/pm.md
+++ b/.showen/inbox/pm.md
@@ -1,21 +1,3 @@
-[CEO 陈逸飞] [2026-03-13]
+# PM 刘建国 Inbox

-## 任务：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
-
-时效：尽快启动
+（已清空 - 2026-03-13）
--- a/souls/liu-jianguo.md
+++ b/souls/liu-jianguo.md
@@ -102,7 +102,16 @@

 ### 2026-03-13 示例插件完善
 - 示例插件不能只演示 `init/start/stop` 空壳流程，必须覆盖消息发送、消息匹配、配置解析、后台任务、自测与注释文档，否则第三方开发者无法照着扩展。
- Rust 示例配置优先使用 `serde + #[serde(default)] + deny_unknown_fields + validate()`，把“语法解析”和“业务校验”分成两个阶段，问题定位更清晰。
+- Rust 示例配置优先使用 `serde + #[serde(default)] + deny_unknown_fields + validate()`，把"语法解析"和"业务校验"分成两个阶段，问题定位更清晰。
 - 定时任务示例用 `Arc<MessageSender> + AtomicBool + JoinHandle` 就能讲清楚最小可用线程模型；`stop()` 和配置重载都要负责回收线程。
 - 验收固定执行：`export PATH=... && cargo check --workspace --all-targets`，再执行 `export PATH=... && cargo test --workspace`，两项都绿灯后再汇报。
 - 本次任务一次性通过 `cargo check` 零 warning 和 `cargo test` 全量通过，后续继续保持先验证再汇报的节奏。
+
+### 2026-03-13 DevicePlugin 阶段一任务拆解
+- 收到 CEO 指示实施 DevicePlugin 阶段一（基础框架），完成任务分解文档 `.showen/DEVICE_PLUGIN_TASKS.md`。
+- 任务拆解遵循严格串行依赖：Task 1 (Message enum) → Task 2 (DevicePlugin 骨架) → Task 3 (Backend 实现) → Task 4 (测试)，避免并行导致编译冲突。
+- 人员分配基于技能匹配：张明远（类型系统）负责 Message，王思远（架构）负责 trait 设计，赵雨薇（Linux 显示）负责 Backend，李思琪（测试经验）负责测试。
+- 关键约束：所有 DeviceCommand/Response/Event 必须 `Serialize + Deserialize`（跨 FFI 边界），Backend 通过条件编译支持多平台。
+- 验收标准明确：至少支持 Display + SleepInhibit 两个能力，≥5 个测试，cargo check 零 warning，cargo test 全部通过。
+- 风险识别：Message 改动可能影响现有插件（应对：立即全量编译验证），systemd-inhibit 可能不可用（应对：错误处理降级）。
+- 预计总工时 12-14 小时（1.5-2 工作日），Task 5 (ScreenPlugin 迁移) 标记为可选，可延后到阶段二。