From f83e18d43bb0b8e718805797a17a2d5694ff82bb Mon Sep 17 00:00:00 2001 From: showen Date: Fri, 13 Mar 2026 06:12:39 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20DevicePlugin=E9=98=B6=E6=AE=B5=E4=B8=80?= =?UTF-8?q?=E4=BB=BB=E5=8A=A1=E5=88=86=E8=A7=A3=20+=20PM=20soul=E6=9B=B4?= =?UTF-8?q?=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .showen/DEVICE_PLUGIN_TASKS.md | 322 +++++++++++++++++++++++++++++++++ .showen/inbox/pm.md | 22 +-- souls/liu-jianguo.md | 11 +- 3 files changed, 334 insertions(+), 21 deletions(-) create mode 100644 .showen/DEVICE_PLUGIN_TASKS.md diff --git a/.showen/DEVICE_PLUGIN_TASKS.md b/.showen/DEVICE_PLUGIN_TASKS.md new file mode 100644 index 0000000..ae6ce9e --- /dev/null +++ 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` + - `backend: Box` + - 实现 `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)` 构造函数 +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;` + - `fn capabilities(&self) -> Vec;` + - `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` — systemd-inhibit 子进程 + - `display_info: Option` — 缓存的显示信息 + - `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 diff --git a/.showen/inbox/pm.md b/.showen/inbox/pm.md index 6f6f570..fd0a3d6 100644 --- 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） diff --git a/souls/liu-jianguo.md b/souls/liu-jianguo.md index c1298d8..37e3950 100644 --- 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 + 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 迁移) 标记为可选，可延后到阶段二。