323 lines
14 KiB
Markdown
323 lines
14 KiB
Markdown
# 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
|