pulsareon/ShowenV2

Fork 0

Files

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

2026-03-13 06:12:39 +08:00

14 KiB

Raw Blame History

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 设计

任务描述:

在 Message enum 中添加三个新变体：
- DeviceCommand(DeviceCommand) — 业务插件向 DevicePlugin 发送的命令
- DeviceResponse(DeviceResponse) — DevicePlugin 返回的响应
- DeviceEvent(DeviceEvent) — DevicePlugin 广播的事件
在 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
所有新类型必须派生 Debug, Clone, Serialize, Deserialize（跨 FFI 边界要求）
为复杂变体添加文档注释说明用途

输出文件:

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节）

任务描述:

创建 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>) 构造函数
创建 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<()>;
- 添加完整的文档注释说明每个方法的职责
在 src/plugins/device/mod.rs 中添加 pub mod backend; 和 pub use backend::DeviceBackend;
在 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 — 后端实现要求

任务描述:

创建 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")] 条件编译
在 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节）

任务描述:

创建 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 用于测试（不依赖真实硬件）
在 src/plugins/device/mod.rs 中添加 #[cfg(test)] mod tests;
更新 docs/DEVICE_PLUGIN_DESIGN.md：
- 在第8节验收标准中勾选已完成项
- 添加"使用示例"章节，展示如何创建和使用 DevicePlugin
创建 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 实现

任务描述:

在 src/plugins/screen/mod.rs 中添加注释标记待迁移功能：
- start_wake_lock() → 改为发送 Message::DeviceCommand(DeviceCommand::SetSleepInhibit(true))
- stop_wake_lock() → 改为发送 Message::DeviceCommand(DeviceCommand::SetSleepInhibit(false))
创建 docs/SCREEN_PLUGIN_MIGRATION.md 迁移计划文档：
- 列出需要迁移的功能清单
- 说明迁移步骤和兼容性策略
- 标记阶段二执行的具体任务
验证 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 扩展不影响现有插件编译

汇报要求

每个任务完成后，负责人需要：

运行 export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo check --workspace --all-targets 验证编译
运行 export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH" && cargo test --workspace 验证测试
更新自己的 soul 文件，记录本次任务经验
在 .showen/TEAM_CHAT.md 中汇报任务完成情况

全部任务完成后，PM 刘建国向 CEO 汇报到 .showen/inbox/ceo.md。

文档创建时间: 2026-03-13
文档创建人: PM 刘建国
文档版本: v1.0

14 KiB Raw Blame History Unescape Escape

DevicePlugin 阶段一任务分解文档

项目背景

总体目标

任务列表与执行顺序

Task 1: Message enum 扩展

Task 2: DevicePlugin 骨架与 Backend trait

Task 3: Linux ARM64 Backend 实现

Task 4: 集成测试与文档

Task 5: ScreenPlugin 功能迁移验证（可选）

任务依赖关系图

团队成员能力评估

关键风险与应对

风险 1: Message enum 改动影响现有插件

风险 2: systemd-inhibit 在某些 Linux 发行版不可用

风险 3: framebuffer 路径在不同设备上可能不同

风险 4: 任务串行导致总工时较长

时间估算

验收总清单

汇报要求

14 KiB

Raw Blame History