refactor: 整理项目文件夹结构 + 更新项目状态
- docs/: 团队流程文档 (10个md) - .showen/: 管理状态文件 (CEO_BACKUP, RECOVERY, TEAM_CHAT, CEO_LOOP) - 根目录只保留 README.md + PROGRESS.md - 更新 RECOVERY.md/CEO_BACKUP.md/PROGRESS.md 反映自测机制完成 - 更新 souls/liu-jianguo.md 当前状态
This commit is contained in:
showen
208
docs/CODE_REVIEW.md
Normal file
208
docs/CODE_REVIEW.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# ShowenV2 代码审核标准
|
||||
|
||||
## 审核流程
|
||||
|
||||
### 两级审核制度
|
||||
```
|
||||
开发者提交 → PM 初审 → CEO 终审 → git commit
|
||||
```
|
||||
|
||||
### PM 初审职责
|
||||
1. **编译检查**: cargo check 必须通过，零 warning
|
||||
2. **基本逻辑**: 代码逻辑正确，无明显 bug
|
||||
3. **风格一致**: 符合项目代码风格
|
||||
4. **测试验证**: 关键功能手动测试通过
|
||||
|
||||
### CEO 终审职责
|
||||
1. **架构审核**: 是否符合整体架构设计
|
||||
2. **性能审核**: 是否有性能问题
|
||||
3. **安全审核**: 是否有安全隐患
|
||||
4. **质量审核**: 代码质量是否达标
|
||||
|
||||
---
|
||||
|
||||
## 代码质量标准
|
||||
|
||||
### 必须满足（P0）
|
||||
- [ ] cargo check 零 warning
|
||||
- [ ] cargo clippy 零 warning
|
||||
- [ ] 无 unsafe 代码（除非有充分理由并注释说明）
|
||||
- [ ] 无 unwrap/expect（使用 ? 或 match 处理错误）
|
||||
- [ ] 无 panic（除非是不可恢复的错误）
|
||||
- [ ] 所有 public API 有文档注释
|
||||
- [ ] 关键逻辑有注释说明
|
||||
|
||||
### 应该满足（P1）
|
||||
- [ ] 函数长度 < 100 行
|
||||
- [ ] 圈复杂度 < 10
|
||||
- [ ] 嵌套层级 < 4
|
||||
- [ ] 变量命名清晰（避免 a/b/tmp 等）
|
||||
- [ ] 错误信息有上下文
|
||||
- [ ] 日志级别合理（debug/info/warn/error）
|
||||
|
||||
### 建议满足（P2）
|
||||
- [ ] 单元测试覆盖关键逻辑
|
||||
- [ ] 性能敏感代码有 benchmark
|
||||
- [ ] 复杂算法有示例和图解
|
||||
- [ ] 使用 trait 抽象而非具体类型
|
||||
|
||||
---
|
||||
|
||||
## 架构审核标准
|
||||
|
||||
### 插件设计
|
||||
- [ ] 插件之间零耦合，只通过消息通信
|
||||
- [ ] 插件不直接访问其他插件的状态
|
||||
- [ ] 插件可独立编译和测试
|
||||
- [ ] 插件配置通过 Config 传入
|
||||
|
||||
### 消息设计
|
||||
- [ ] 消息类型语义清晰
|
||||
- [ ] 消息字段最小化（避免冗余）
|
||||
- [ ] 消息实现 Clone（如果需要 Broadcast）
|
||||
- [ ] 消息处理无阻塞（长时间操作用独立线程）
|
||||
|
||||
### 并发设计
|
||||
- [ ] 避免共享可变状态
|
||||
- [ ] 使用消息传递而非锁
|
||||
- [ ] 阻塞操作在独立线程
|
||||
- [ ] 异步代码用 tokio，同步代码用 std::thread
|
||||
|
||||
### 错误处理
|
||||
- [ ] 使用 Result 而非 panic
|
||||
- [ ] 错误类型有上下文信息
|
||||
- [ ] 错误向上传播，在合适的层级处理
|
||||
- [ ] 用户可见的错误有友好提示
|
||||
|
||||
---
|
||||
|
||||
## 性能审核标准
|
||||
|
||||
### 内存管理
|
||||
- [ ] 避免不必要的 clone
|
||||
- [ ] 大对象用引用传递
|
||||
- [ ] 及时释放资源（文件句柄、网络连接）
|
||||
- [ ] 避免内存泄漏（检查循环引用）
|
||||
|
||||
### 计算效率
|
||||
- [ ] 避免重复计算（缓存结果）
|
||||
- [ ] 选择合适的数据结构（HashMap vs Vec）
|
||||
- [ ] 热点路径优化（避免分配、减少拷贝）
|
||||
- [ ] 考虑并行化（rayon、tokio）
|
||||
|
||||
### IO 效率
|
||||
- [ ] 网络 IO 用异步（tokio）
|
||||
- [ ] 文件 IO 用 BufReader/BufWriter
|
||||
- [ ] 避免频繁的小 IO（批量处理）
|
||||
- [ ] 考虑零拷贝（sendfile、mmap）
|
||||
|
||||
---
|
||||
|
||||
## 安全审核标准
|
||||
|
||||
### 输入验证
|
||||
- [ ] 所有外部输入必须验证
|
||||
- [ ] 配置文件解析有错误处理
|
||||
- [ ] HTTP 请求参数有校验
|
||||
- [ ] 文件路径防止目录遍历
|
||||
|
||||
### 资源限制
|
||||
- [ ] 防止无限循环
|
||||
- [ ] 防止内存耗尽（限制缓冲区大小）
|
||||
- [ ] 防止 CPU 耗尽（限制并发数）
|
||||
- [ ] 防止文件描述符耗尽
|
||||
|
||||
### 权限控制
|
||||
- [ ] 最小权限原则
|
||||
- [ ] 敏感操作需要验证
|
||||
- [ ] 日志不包含敏感信息
|
||||
|
||||
---
|
||||
|
||||
## 风格审核标准
|
||||
|
||||
### 命名规范
|
||||
- 类型名：PascalCase（VideoProcessor）
|
||||
- 函数名：snake_case（handle_message）
|
||||
- 常量名：SCREAMING_SNAKE_CASE（MAX_BUFFER_SIZE）
|
||||
- 模块名：snake_case（video_processor）
|
||||
|
||||
### 注释规范
|
||||
```rust
|
||||
/// 公共 API 文档注释（三斜杠）
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `config` - 配置对象
|
||||
///
|
||||
/// # Returns
|
||||
/// 成功返回 Ok(())，失败返回错误
|
||||
pub fn init(config: Config) -> Result<()> {
|
||||
// 实现细节注释（双斜杠）
|
||||
// 解释为什么这样做，而不是做了什么
|
||||
}
|
||||
```
|
||||
|
||||
### 格式规范
|
||||
- 使用 rustfmt 自动格式化
|
||||
- 行宽 100 字符
|
||||
- 缩进 4 空格
|
||||
- 导入按字母排序
|
||||
|
||||
---
|
||||
|
||||
## 审核检查清单
|
||||
|
||||
### PM 初审清单
|
||||
```
|
||||
[ ] cargo check 通过
|
||||
[ ] cargo clippy 通过
|
||||
[ ] 手动测试基本功能
|
||||
[ ] 代码风格一致
|
||||
[ ] 无明显逻辑错误
|
||||
[ ] 错误处理完善
|
||||
[ ] 注释清晰
|
||||
```
|
||||
|
||||
### CEO 终审清单
|
||||
```
|
||||
[ ] 符合架构设计
|
||||
[ ] 插件边界清晰
|
||||
[ ] 消息设计合理
|
||||
[ ] 无性能问题
|
||||
[ ] 无安全隐患
|
||||
[ ] 代码质量达标
|
||||
[ ] 可维护性好
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 不合格处理
|
||||
|
||||
### 初审不合格
|
||||
- PM 在 TEAM_CHAT.md 记录问题
|
||||
- 开发者修复后重新提交
|
||||
- 连续 3次不合格 → 绩效扣分
|
||||
|
||||
### 终审不合格
|
||||
- CEO 在 TEAM_CHAT.md 详细说明问题
|
||||
- 可能需要重新设计
|
||||
- 严重问题 → 考虑换人
|
||||
|
||||
### 绩效影响
|
||||
- 一次不合格：-1 分
|
||||
- 严重问题（架构/安全）：-3 分
|
||||
- 优秀代码（超出预期）：+2 分
|
||||
|
||||
---
|
||||
|
||||
## 审核时间要求
|
||||
|
||||
- PM 初审：2小时内完成
|
||||
- CEO 终审：24小时内完成
|
||||
- 紧急 bug 修复：1小时内完成
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
378
docs/COMMUNICATION.md
Normal file
378
docs/COMMUNICATION.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# ShowenV2 沟通和记录规范
|
||||
|
||||
## 沟通原则
|
||||
|
||||
### 核心理念
|
||||
- **扁平化**: 员工之间直接沟通，不需要层层汇报
|
||||
- **透明化**: 重要信息必须记录，所有人可见
|
||||
- **可追溯**: 决策和讨论有据可查
|
||||
- **知识沉淀**: 经验和方案通过记录传承
|
||||
- **向上开放**: 所有员工都可以给领导层和管理层提建议
|
||||
|
||||
### 向上沟通原则
|
||||
- ✅ 可以质疑任何决策，包括 CEO 的决策
|
||||
- ✅ 可以提出管理流程的改进建议
|
||||
- ✅ 可以建议调整团队结构
|
||||
- ✅ 可以对产品方向提出不同意见
|
||||
- ✅ 可以指出领导层的问题
|
||||
- ✅ 畅所欲言，没有禁区
|
||||
|
||||
### 平级沟通原则
|
||||
- ✅ 可以给同事提工作建议
|
||||
- ✅ 可以指出同事代码的问题
|
||||
- ✅ 可以建议改进协作方式
|
||||
- ✅ 可以对其他团队的输出提意见
|
||||
- ✅ 建议要具体、建设性
|
||||
- ✅ 接受建议要开放、理性
|
||||
|
||||
### 建议和反馈
|
||||
所有员工都可以在 TEAM_CHAT.md 提出建议，格式：
|
||||
|
||||
#### 向上建议格式
|
||||
```markdown
|
||||
[时间] [姓名]([角色]) - 建议
|
||||
|
||||
建议对象：[CEO/管理层/某个流程]
|
||||
建议内容：
|
||||
1. 问题描述：[当前存在的问题]
|
||||
2. 影响分析：[这个问题的影响]
|
||||
3. 改进建议：[具体的改进方案]
|
||||
4. 预期效果：[改进后的预期效果]
|
||||
```
|
||||
|
||||
#### 平级建议格式
|
||||
```markdown
|
||||
[时间] [姓名]([角色]) → [接收者]([角色]) - 建议
|
||||
|
||||
建议内容：
|
||||
- 当前问题：[观察到的问题]
|
||||
- 改进建议：[具体建议]
|
||||
- 参考：[可参考的例子]
|
||||
- 预期效果：[改进后的效果]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 沟通方式
|
||||
|
||||
### 1. 异步沟通（推荐）
|
||||
|
||||
#### 工具
|
||||
- **TEAM_CHAT.md** - 团队沟通主渠道
|
||||
- **Git commit** - 代码变更说明
|
||||
- **文档** - PRD、技术设计文档、API 文档
|
||||
|
||||
#### 适用场景
|
||||
- 技术讨论和方案设计
|
||||
- 需求澄清和变更
|
||||
- 问题反馈和解决方案
|
||||
- 经验分享和最佳实践
|
||||
- 跨团队协作
|
||||
|
||||
#### 优点
|
||||
- ✅ 自动记录，可追溯
|
||||
- ✅ 可搜索，易查找
|
||||
- ✅ 异步处理，不打断工作
|
||||
- ✅ 深度思考，质量更高
|
||||
|
||||
#### 记录格式
|
||||
```markdown
|
||||
[时间] 发送者 → 接收者: 内容
|
||||
|
||||
示例：
|
||||
[14:30] 李思琪(视频工程师) → 王浩然(网络工程师):
|
||||
视频流传输性能问题已解决，采用零拷贝方案。
|
||||
- 参考代码：src/plugins/video/processor.rs:456
|
||||
- 性能提升：从 30fps 提升到 60fps
|
||||
- 关键技术：tokio::fs::File + 流式传输
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. 实时沟通（可选）
|
||||
|
||||
#### 工具
|
||||
- **kilo 命令** - 启动子任务进行实时协作
|
||||
- **语音/视频会议** - 复杂问题讨论
|
||||
- **屏幕共享** - 代码调试和演示
|
||||
|
||||
#### 适用场景
|
||||
- 紧急问题需要快速解决
|
||||
- 复杂技术方案需要深入讨论
|
||||
- 头脑风暴和创意碰撞
|
||||
- 代码调试和问题定位
|
||||
|
||||
#### 记录要求
|
||||
**重要**：实时沟通后必须在 TEAM_CHAT.md 记录要点
|
||||
|
||||
```markdown
|
||||
[时间] 会议记录 - [主题]
|
||||
参与人：[人员列表]
|
||||
讨论内容：
|
||||
1. 问题描述
|
||||
2. 讨论要点
|
||||
3. 决策结果
|
||||
4. 行动计划
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. 代码协作
|
||||
|
||||
#### 工具
|
||||
- **Git commit message** - 代码变更说明
|
||||
- **代码注释** - 复杂逻辑说明
|
||||
- **Pull Request** - 代码审查和讨论
|
||||
|
||||
#### 记录要求
|
||||
|
||||
##### Commit Message 规范
|
||||
```
|
||||
<type>: <subject>
|
||||
|
||||
<body>
|
||||
|
||||
<footer>
|
||||
```
|
||||
|
||||
**Type 类型**:
|
||||
- `feat`: 新功能
|
||||
- `fix`: Bug 修复
|
||||
- `docs`: 文档更新
|
||||
- `refactor`: 重构
|
||||
- `perf`: 性能优化
|
||||
- `test`: 测试
|
||||
- `chore`: 构建/工具
|
||||
|
||||
**示例**:
|
||||
```
|
||||
feat: 实现插件动态注册机制
|
||||
|
||||
- 新增 ServiceManager::register_plugin() 方法
|
||||
- 支持运行时加载插件
|
||||
- 自动检查依赖关系
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
##### 代码注释规范
|
||||
```rust
|
||||
/// 公共 API 文档注释（三斜杠）
|
||||
///
|
||||
/// # Arguments
|
||||
/// * `plugin` - 要注册的插件
|
||||
///
|
||||
/// # Returns
|
||||
/// 成功返回 Ok(())，失败返回错误
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// manager.register_plugin(Box::new(MyPlugin::new()))?;
|
||||
/// ```
|
||||
pub fn register_plugin(&mut self, plugin: Box<dyn Plugin>) -> Result<()> {
|
||||
// 实现细节注释（双斜杠）
|
||||
// 为什么这样做，而不是做了什么
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. 文档协作
|
||||
|
||||
#### 工具
|
||||
- **Markdown 文档** - PRD、技术设计、API 文档
|
||||
- **Git** - 版本控制和变更追踪
|
||||
|
||||
#### 文档类型
|
||||
- **PRD** - 产品需求文档
|
||||
- **技术设计文档** - 架构和实现方案
|
||||
- **API 文档** - 接口说明
|
||||
- **用户文档** - 使用指南
|
||||
- **开发文档** - 开发规范和流程
|
||||
|
||||
#### 记录要求
|
||||
- 文档变更通过 Git 提交
|
||||
- 重大变更在 TEAM_CHAT.md 通知相关人员
|
||||
- 文档版本号和更新日期
|
||||
|
||||
---
|
||||
|
||||
## 记录规范
|
||||
|
||||
### 必须记录的内容
|
||||
|
||||
#### 技术决策
|
||||
```markdown
|
||||
[时间] 技术决策 - [主题]
|
||||
决策人：[姓名]
|
||||
背景：[为什么需要决策]
|
||||
方案：
|
||||
- 方案A：[描述] - 优点/缺点
|
||||
- 方案B：[描述] - 优点/缺点
|
||||
决策：选择方案A
|
||||
理由：[决策理由]
|
||||
影响：[影响范围]
|
||||
```
|
||||
|
||||
#### 需求变更
|
||||
```markdown
|
||||
[时间] 需求变更 - [功能名称]
|
||||
提出人：[姓名]
|
||||
原需求：[原来的需求]
|
||||
新需求：[变更后的需求]
|
||||
变更原因：[为什么变更]
|
||||
影响评估：[对进度、架构的影响]
|
||||
批准人：[CEO/产品总监]
|
||||
```
|
||||
|
||||
#### 架构调整
|
||||
```markdown
|
||||
[时间] 架构调整 - [模块名称]
|
||||
提出人：[姓名]
|
||||
当前架构：[现状]
|
||||
调整方案：[新方案]
|
||||
调整原因：[为什么调整]
|
||||
影响范围：[影响的模块]
|
||||
迁移计划：[如何迁移]
|
||||
```
|
||||
|
||||
#### Bug 和解决方案
|
||||
```markdown
|
||||
[时间] Bug 修复 - [Bug 描述]
|
||||
发现人：[姓名]
|
||||
严重程度：P0/P1/P2/P3
|
||||
复现步骤：[如何复现]
|
||||
根因分析：[为什么出现]
|
||||
解决方案：[如何修复]
|
||||
代码位置：[文件:行号]
|
||||
验证：[如何验证修复]
|
||||
```
|
||||
|
||||
#### 经验教训
|
||||
```markdown
|
||||
[时间] 经验分享 - [主题]
|
||||
分享人：[姓名]
|
||||
场景：[遇到什么问题]
|
||||
教训：[学到了什么]
|
||||
最佳实践：[推荐做法]
|
||||
避免：[不要这样做]
|
||||
参考：[相关文档/代码]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 可以不记录的内容
|
||||
|
||||
- ❌ 日常问候和闲聊
|
||||
- ❌ 简单的代码语法问题（已在代码中解决）
|
||||
- ❌ 已在文档中详细说明的内容
|
||||
- ❌ 临时性的、不重要的讨论
|
||||
|
||||
---
|
||||
|
||||
## 记录管理
|
||||
|
||||
### 记录位置
|
||||
- **TEAM_CHAT.md** - 日常沟通和协作
|
||||
- **Git commit** - 代码变更
|
||||
- **文档** - 正式的需求、设计、规范
|
||||
- **灵魂文件** - 个人经验和技能
|
||||
|
||||
### 记录检索
|
||||
- 使用 Git 搜索历史记录
|
||||
- 使用文本搜索工具（grep、ripgrep）
|
||||
- 按时间顺序浏览 TEAM_CHAT.md
|
||||
|
||||
### 记录归档
|
||||
- 每月归档 TEAM_CHAT.md（保留最近 3个月）
|
||||
- 重要决策整理到专门文档
|
||||
- 经验教训更新到灵魂文件
|
||||
|
||||
---
|
||||
|
||||
## 沟通礼仪
|
||||
|
||||
### 提问技巧
|
||||
- ✅ 描述清楚问题背景
|
||||
- ✅ 说明已经尝试的方案
|
||||
- ✅ 提供相关代码和日志
|
||||
- ✅ @ 相关人员
|
||||
- ❌ 不要问"在吗"
|
||||
- ❌ 不要问"能帮我吗"
|
||||
|
||||
### 回复规范
|
||||
- ✅ 及时回复（24小时内）
|
||||
- ✅ 提供具体的解决方案
|
||||
- ✅ 附上代码示例或文档链接
|
||||
- ✅ 说明为什么这样做
|
||||
- ❌ 不要只说"可以"或"不行"
|
||||
|
||||
### 协作态度
|
||||
- ✅ 主动分享知识和经验
|
||||
- ✅ 尊重他人的意见
|
||||
- ✅ 建设性的反馈
|
||||
- ✅ 承认错误，快速改进
|
||||
- ❌ 不要指责和抱怨
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 技术讨论示例
|
||||
```markdown
|
||||
[14:30] 李思琪 → 王浩然:
|
||||
我在实现视频流传输时遇到性能瓶颈，帧率只能达到 30fps。
|
||||
已尝试：
|
||||
1. 减少内存拷贝 - 效果不明显
|
||||
2. 使用 SIMD 优化 - 提升 10%
|
||||
你在 HTTP 插件中是怎么处理大数据传输的？
|
||||
|
||||
[14:45] 王浩然 → 李思琪:
|
||||
我用了零拷贝和流式传输，性能提升明显。
|
||||
关键技术：
|
||||
1. tokio::fs::File - 异步文件读取
|
||||
2. warp::reply::Response::new() - 流式响应
|
||||
3. 避免 Vec<u8> 缓冲 - 直接传输
|
||||
参考代码：src/plugins/http/routes.rs:234
|
||||
建议你试试 opencv::Mat 的零拷贝接口。
|
||||
|
||||
[15:00] 李思琪 → 王浩然:
|
||||
感谢！已采用你的方案，帧率提升到 60fps。
|
||||
更新代码：src/plugins/video/processor.rs:456
|
||||
经验记录：避免不必要的内存拷贝是性能优化的关键。
|
||||
```
|
||||
|
||||
### 跨团队协作示例
|
||||
```markdown
|
||||
[10:00] 张婉琳(产品) → 王思远(架构师):
|
||||
Phase 2 插件市场需求已完成，需要你评审技术可行性。
|
||||
文档：PRD_PLUGIN_MARKET.md
|
||||
关键需求：
|
||||
1. 插件动态安装
|
||||
2. 版本管理
|
||||
3. 依赖检查
|
||||
请在本周五前给出技术方案。
|
||||
|
||||
[10:30] 王思远(架构师) → 张婉琳(产品):
|
||||
已阅读 PRD，整体可行。
|
||||
技术方案：
|
||||
1. 使用 libloading 动态加载 .so/.dll
|
||||
2. 版本管理用 semver
|
||||
3. 依赖检查在 ServiceManager 实现
|
||||
风险：
|
||||
1. 插件签名验证需要额外工作
|
||||
2. 沙箱隔离可能影响性能
|
||||
建议：Phase 2 先实现基础功能，安全机制放 Phase 3。
|
||||
技术设计文档：本周三完成。
|
||||
|
||||
[10:45] 张婉琳(产品) → 王思远(架构师):
|
||||
同意你的建议。安全机制确实可以后续迭代。
|
||||
请在技术设计文档中说明 Phase 2/3 的功能划分。
|
||||
@ 刘建国(PM) 请关注进度。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
411
docs/FIRST_PRINCIPLES.md
Normal file
411
docs/FIRST_PRINCIPLES.md
Normal file
@@ -0,0 +1,411 @@
|
||||
# ShowenV2 第一性原理
|
||||
|
||||
## 核心理念
|
||||
|
||||
ShowenV2 公司和团队遵循**第一性原理**（First Principles Thinking）：
|
||||
|
||||
> 回归事物最基本的条件，将其拆分成各要素进行解构分析，从而找到实现目标最优路径的方法。
|
||||
|
||||
---
|
||||
|
||||
## 什么是第一性原理
|
||||
|
||||
### 定义
|
||||
- 不盲目遵循惯例和经验
|
||||
- 不照搬别人的做法
|
||||
- 回到问题的本质
|
||||
- 从基本事实出发推导解决方案
|
||||
|
||||
### 对比
|
||||
|
||||
#### ❌ 类比思维（Analogical Thinking）
|
||||
```
|
||||
"别的公司都这样做" → 我们也这样做
|
||||
"行业最佳实践" → 直接照搬
|
||||
"大家都用这个技术" → 我们也用
|
||||
```
|
||||
|
||||
#### ✅ 第一性原理（First Principles）
|
||||
```
|
||||
我们要解决什么问题？
|
||||
→ 问题的本质是什么？
|
||||
→ 有哪些基本约束条件？
|
||||
→ 从基本事实出发，最优解是什么？
|
||||
→ 验证方案是否真正解决问题
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 在 ShowenV2 的应用
|
||||
|
||||
### 1. 技术决策
|
||||
|
||||
#### 问题：选择什么技术栈？
|
||||
|
||||
**❌ 类比思维**：
|
||||
- "大家都用 Go，我们也用 Go"
|
||||
- "React 很流行，我们用 React"
|
||||
|
||||
**✅ 第一性原理**：
|
||||
```
|
||||
问题本质：
|
||||
- 需要高性能、低延迟的视频处理
|
||||
- 需要跨平台支持（Linux/macOS/Windows）
|
||||
- 需要系统级控制（硬件、网络）
|
||||
- 团队需要能快速迭代
|
||||
|
||||
基本约束：
|
||||
- ARM 嵌入式设备，资源有限
|
||||
- 实时性要求高（60fps）
|
||||
- 内存安全很重要
|
||||
|
||||
推导结论：
|
||||
- Rust：零成本抽象、内存安全、跨平台、高性能
|
||||
- 不是因为"Rust 很酷"，而是它最符合我们的需求
|
||||
```
|
||||
|
||||
### 2. 架构设计
|
||||
|
||||
#### 问题：如何设计系统架构？
|
||||
|
||||
**❌ 类比思维**：
|
||||
- "微服务很流行，我们用微服务"
|
||||
- "别人用 MVC，我们也用 MVC"
|
||||
|
||||
**✅ 第一性原理**：
|
||||
```
|
||||
问题本质：
|
||||
- 需要支持多种功能（视频、网络、BLE、HTTP）
|
||||
- 功能需要独立开发和测试
|
||||
- 需要支持动态扩展（插件市场）
|
||||
- 不同功能的生命周期不同
|
||||
|
||||
基本约束：
|
||||
- 单机运行，不需要分布式
|
||||
- 功能之间需要通信
|
||||
- 需要热插拔
|
||||
|
||||
推导结论：
|
||||
- 插件架构：独立、可扩展、松耦合
|
||||
- 消息传递：解耦、异步、可追踪
|
||||
- 不是因为"插件架构很先进"，而是它最适合我们的需求
|
||||
```
|
||||
|
||||
### 3. 团队管理
|
||||
|
||||
#### 问题：如何管理团队？
|
||||
|
||||
**❌ 类比思维**：
|
||||
- "大公司都有严格的层级，我们也要"
|
||||
- "敏捷开发很流行，我们用 Scrum"
|
||||
|
||||
**✅ 第一性原理**：
|
||||
```
|
||||
问题本质：
|
||||
- 需要高效协作
|
||||
- 需要快速决策
|
||||
- 需要知识传承
|
||||
- 需要持续改进
|
||||
|
||||
基本约束：
|
||||
- 团队规模小（10人左右）
|
||||
- 都是顶尖人才
|
||||
- 远程协作（AI 团队）
|
||||
- 信息容易丢失
|
||||
|
||||
推导结论：
|
||||
- 扁平化：减少沟通层级，提高效率
|
||||
- 文档化：所有重要信息必须记录
|
||||
- 开放反馈：鼓励提建议，持续改进
|
||||
- 不是因为"扁平化很酷"，而是它最适合我们的情况
|
||||
```
|
||||
|
||||
### 4. 产品设计
|
||||
|
||||
#### 问题：要做什么产品？
|
||||
|
||||
**❌ 类比思维**：
|
||||
- "全息宠物很火，我们做全息宠物"
|
||||
- "别人做 AR，我们也做 AR"
|
||||
|
||||
**✅ 第一性原理**：
|
||||
```
|
||||
问题本质：
|
||||
- 用户需要什么？→ 数字内容的展示和交互
|
||||
- 为什么需要？→ 情感陪伴、娱乐、信息展示
|
||||
- 有什么限制？→ 硬件、技术、成本
|
||||
|
||||
基本约束：
|
||||
- 显示技术多样（全息、VR、AR、屏幕）
|
||||
- 内容类型多样（宠物、3D、数字人、歌姬）
|
||||
- 用户需求多样（C端、B端、开发者）
|
||||
|
||||
推导结论：
|
||||
- 做平台，不做单一产品
|
||||
- 插件化，支持任何内容和显示方式
|
||||
- 开放生态，让第三方参与
|
||||
- 不是因为"平台战略很高大上"，而是它能满足最多用户需求
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第一性原理的应用流程
|
||||
|
||||
### 1. 识别问题
|
||||
```
|
||||
我们要解决什么问题？
|
||||
这个问题为什么重要？
|
||||
不解决会有什么后果？
|
||||
```
|
||||
|
||||
### 2. 拆解问题
|
||||
```
|
||||
问题的本质是什么？
|
||||
有哪些基本约束条件？
|
||||
哪些是必须的，哪些是可选的？
|
||||
```
|
||||
|
||||
### 3. 回归基本事实
|
||||
```
|
||||
已知的事实有哪些？
|
||||
哪些是假设，哪些是事实？
|
||||
有哪些物理/技术/经济规律？
|
||||
```
|
||||
|
||||
### 4. 推导解决方案
|
||||
```
|
||||
从基本事实出发，有哪些可能的方案？
|
||||
每个方案的优缺点是什么？
|
||||
哪个方案最优？
|
||||
```
|
||||
|
||||
### 5. 验证方案
|
||||
```
|
||||
这个方案真的解决了问题吗？
|
||||
有没有更简单的方案？
|
||||
有没有遗漏的约束？
|
||||
```
|
||||
|
||||
### 6. 迭代优化
|
||||
```
|
||||
实施后效果如何？
|
||||
有没有新的问题？
|
||||
需要调整吗？
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 实践指南
|
||||
|
||||
### 在技术决策中
|
||||
|
||||
#### 提问清单
|
||||
- [ ] 我们要解决什么技术问题？
|
||||
- [ ] 这个技术的本质优势是什么？
|
||||
- [ ] 我们的约束条件是什么？
|
||||
- [ ] 有没有更简单的方案？
|
||||
- [ ] 这个技术真的适合我们吗？
|
||||
|
||||
#### 避免的陷阱
|
||||
- ❌ "这个技术很新，我们要用"
|
||||
- ❌ "大公司都用，我们也用"
|
||||
- ❌ "我熟悉这个，就用这个"
|
||||
- ❌ "简历上好看，就用这个"
|
||||
|
||||
### 在产品决策中
|
||||
|
||||
#### 提问清单
|
||||
- [ ] 用户的真实需求是什么？
|
||||
- [ ] 为什么用户需要这个功能？
|
||||
- [ ] 不做这个功能会怎样？
|
||||
- [ ] 有没有更简单的方案？
|
||||
- [ ] 这个功能真的有价值吗？
|
||||
|
||||
#### 避免的陷阱
|
||||
- ❌ "竞品有，我们也要有"
|
||||
- ❌ "这个功能很酷，加上"
|
||||
- ❌ "用户说要，就做"（没有深挖需求）
|
||||
- ❌ "我觉得好，就做"
|
||||
|
||||
### 在团队管理中
|
||||
|
||||
#### 提问清单
|
||||
- [ ] 这个流程要解决什么问题？
|
||||
- [ ] 为什么需要这个流程？
|
||||
- [ ] 不做会有什么后果？
|
||||
- [ ] 有没有更简单的方式？
|
||||
- [ ] 这个流程真的有效吗？
|
||||
|
||||
#### 避免的陷阱
|
||||
- ❌ "大公司都这样做"
|
||||
- ❌ "书上说要这样"
|
||||
- ❌ "一直都这样做"
|
||||
- ❌ "为了规范而规范"
|
||||
|
||||
---
|
||||
|
||||
## 案例分析
|
||||
|
||||
### 案例1：为什么选择插件架构？
|
||||
|
||||
**问题**：如何设计 ShowenV2 的架构？
|
||||
|
||||
**第一性原理分析**：
|
||||
1. **问题本质**：需要支持多种功能，且功能会不断增加
|
||||
2. **基本约束**：
|
||||
- 功能独立开发和测试
|
||||
- 支持动态扩展
|
||||
- 不同功能生命周期不同
|
||||
3. **推导**：
|
||||
- 需要模块化 → 插件
|
||||
- 需要解耦 → 消息传递
|
||||
- 需要扩展 → 动态加载
|
||||
4. **结论**：插件架构 + 消息驱动
|
||||
|
||||
**不是因为**：
|
||||
- ❌ "插件架构很先进"
|
||||
- ❌ "Chrome 用插件，我们也用"
|
||||
- ❌ "看起来很酷"
|
||||
|
||||
**而是因为**：
|
||||
- ✅ 真正解决了我们的问题
|
||||
- ✅ 符合我们的约束条件
|
||||
- ✅ 是最优解
|
||||
|
||||
### 案例2：为什么要扁平化管理？
|
||||
|
||||
**问题**：如何管理 AI 团队？
|
||||
|
||||
**第一性原理分析**：
|
||||
1. **问题本质**：需要高效协作和快速决策
|
||||
2. **基本约束**：
|
||||
- 团队小（10人）
|
||||
- 都是顶尖人才
|
||||
- 远程协作
|
||||
- 信息容易丢失
|
||||
3. **推导**：
|
||||
- 人少 → 不需要多层级
|
||||
- 顶尖人才 → 可以自主决策
|
||||
- 远程 → 需要文档化
|
||||
- 信息丢失 → 必须记录
|
||||
4. **结论**：扁平化 + 文档化 + 开放反馈
|
||||
|
||||
**不是因为**：
|
||||
- ❌ "扁平化是趋势"
|
||||
- ❌ "硅谷公司都扁平化"
|
||||
- ❌ "看起来很民主"
|
||||
|
||||
**而是因为**：
|
||||
- ✅ 最适合我们的团队规模和特点
|
||||
- ✅ 能最大化效率
|
||||
- ✅ 能保证信息不丢失
|
||||
|
||||
### 案例3：为什么要多架构并存？
|
||||
|
||||
**问题**：如何设计通讯架构？
|
||||
|
||||
**第一性原理分析**：
|
||||
1. **问题本质**：用户需要多种方式连接设备
|
||||
2. **基本约束**：
|
||||
- 不同场景需要不同通讯方式
|
||||
- WiFi、BLE、Zigbee 等各有优劣
|
||||
- 用户环境不同
|
||||
3. **推导**：
|
||||
- 不能只支持一种 → 多架构
|
||||
- 架构之间可能协作 → 松耦合
|
||||
- 未来可能有新方式 → 可扩展
|
||||
4. **结论**：多架构并存 + 插件化
|
||||
|
||||
**不是因为**：
|
||||
- ❌ "支持越多越好"
|
||||
- ❌ "显得功能强大"
|
||||
- ❌ "竞品支持，我们也要"
|
||||
|
||||
**而是因为**：
|
||||
- ✅ 真正满足不同用户的需求
|
||||
- ✅ 每种方式都有其适用场景
|
||||
- ✅ 给用户选择权
|
||||
|
||||
---
|
||||
|
||||
## 团队文化
|
||||
|
||||
### 鼓励质疑
|
||||
- ✅ 质疑任何决策，包括 CEO 的决策
|
||||
- ✅ 问"为什么"，不要盲目接受
|
||||
- ✅ 要求给出第一性原理的解释
|
||||
- ✅ 如果解释不合理，提出更好的方案
|
||||
|
||||
### 避免盲从
|
||||
- ❌ "大家都这样做"
|
||||
- ❌ "行业最佳实践"
|
||||
- ❌ "书上说的"
|
||||
- ❌ "领导说的"
|
||||
|
||||
### 追求本质
|
||||
- ✅ 理解问题的本质
|
||||
- ✅ 找到最优解
|
||||
- ✅ 简单优于复杂
|
||||
- ✅ 有效优于好看
|
||||
|
||||
---
|
||||
|
||||
## 决策模板
|
||||
|
||||
每次重要决策都应该回答以下问题：
|
||||
|
||||
```markdown
|
||||
# 决策：[决策内容]
|
||||
|
||||
## 1. 问题
|
||||
我们要解决什么问题？
|
||||
|
||||
## 2. 本质
|
||||
问题的本质是什么？
|
||||
|
||||
## 3. 约束
|
||||
有哪些基本约束条件？
|
||||
- 技术约束：
|
||||
- 资源约束：
|
||||
- 时间约束：
|
||||
- 其他约束：
|
||||
|
||||
## 4. 基本事实
|
||||
已知的事实有哪些？
|
||||
- 事实1：
|
||||
- 事实2：
|
||||
|
||||
## 5. 方案推导
|
||||
从基本事实出发，有哪些可能的方案？
|
||||
|
||||
### 方案A
|
||||
- 描述：
|
||||
- 优点：
|
||||
- 缺点：
|
||||
- 成本：
|
||||
|
||||
### 方案B
|
||||
- 描述：
|
||||
- 优点：
|
||||
- 缺点：
|
||||
- 成本：
|
||||
|
||||
## 6. 决策
|
||||
选择方案：[A/B/C]
|
||||
|
||||
理由：
|
||||
- 为什么这个方案最优？
|
||||
- 为什么不选其他方案？
|
||||
|
||||
## 7. 验证
|
||||
如何验证这个决策是正确的？
|
||||
- 验证指标：
|
||||
- 验证方法：
|
||||
- 验证时间：
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
176
docs/MILESTONES.md
Normal file
176
docs/MILESTONES.md
Normal file
@@ -0,0 +1,176 @@
|
||||
# ShowenV2 项目里程碑
|
||||
|
||||
## Phase 1: 基础平台（当前）
|
||||
|
||||
### M1.1 - 核心插件迁移 ⏳ 进行中
|
||||
**时间**: 2周（2026-03-12 ~ 2026-03-26）
|
||||
**负责人**: PM 刘建国
|
||||
|
||||
**任务清单**:
|
||||
- [x] 项目骨架搭建
|
||||
- [x] core/ 基础架构（Plugin trait, Message, Config）
|
||||
- [x] 第一轮插件（config验证, StateMachine, WiFi, Screen）
|
||||
- [ ] 第二轮核心功能
|
||||
- [ ] ServiceManager Broadcast + Message Clone（张明远）
|
||||
- [ ] VideoProcessor 完整实现（李思琪）
|
||||
- [ ] BlePlugin + GATT 双连接修复（王浩然）
|
||||
- [ ] HttpPlugin + Web UI（赵雨薇）
|
||||
- [ ] main.rs 集成所有插件
|
||||
- [ ] configs/ 配置文件迁移
|
||||
|
||||
**验收标准**:
|
||||
- cargo check 零 warning
|
||||
- 所有插件编译通过
|
||||
- 基本功能可运行
|
||||
|
||||
**当前进度**: 60%
|
||||
**风险**: 无
|
||||
|
||||
---
|
||||
|
||||
### M1.2 - 集成测试与功能对齐
|
||||
**时间**: 2周（2026-03-26 ~ 2026-04-09）
|
||||
**负责人**: PM 刘建国 + QA（待招募）
|
||||
|
||||
**任务清单**:
|
||||
- [ ] 端到端集成测试
|
||||
- [ ] 功能对比测试（vs 旧版本）
|
||||
- [ ] 边界条件测试
|
||||
- [ ] 错误处理测试
|
||||
- [ ] 配置文件兼容性测试
|
||||
- [ ] Bug 修复
|
||||
|
||||
**验收标准**:
|
||||
- 所有旧版本功能都能正常工作
|
||||
- 测试覆盖率 > 70%
|
||||
- 已知 bug 清零
|
||||
|
||||
**当前进度**: 0%
|
||||
**风险**: 可能发现架构问题需要重构
|
||||
|
||||
---
|
||||
|
||||
### M1.3 - 性能优化与 Alpha 发布
|
||||
**时间**: 2周（2026-04-09 ~ 2026-04-23）
|
||||
**负责人**: 全员
|
||||
|
||||
**任务清单**:
|
||||
- [ ] 性能基准测试
|
||||
- [ ] 热点分析和优化
|
||||
- [ ] 内存泄漏检查
|
||||
- [ ] 启动时间优化
|
||||
- [ ] 视频渲染帧率优化
|
||||
- [ ] 文档完善
|
||||
- [ ] 发布 v2.0.0-alpha
|
||||
|
||||
**验收标准**:
|
||||
- 视频渲染 ≥ 60fps
|
||||
- 内存占用 ≤ 旧版本 120%
|
||||
- 启动时间 ≤ 3秒
|
||||
- 文档完整度 > 80%
|
||||
|
||||
**当前进度**: 0%
|
||||
**风险**: 性能可能达不到预期
|
||||
|
||||
---
|
||||
|
||||
### M1.4 - 稳定性测试与正式发布
|
||||
**时间**: 6周（2026-04-23 ~ 2026-06-04）
|
||||
**负责人**: PM 刘建国 + QA
|
||||
|
||||
**任务清单**:
|
||||
- [ ] 长时间稳定性测试（7x24小时）
|
||||
- [ ] 压力测试
|
||||
- [ ] 异常场景测试
|
||||
- [ ] 用户验收测试
|
||||
- [ ] Bug 修复和优化
|
||||
- [ ] 发布文档和迁移指南
|
||||
- [ ] 发布 v2.0.0
|
||||
|
||||
**验收标准**:
|
||||
- 连续运行 7天无崩溃
|
||||
- P0/P1 bug 清零
|
||||
- 用户反馈满意度 > 90%
|
||||
|
||||
**当前进度**: 0%
|
||||
**风险**: 可能发现严重 bug 导致延期
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: 生态扩展（规划中）
|
||||
|
||||
### M2.1 - 插件市场基础设施
|
||||
**时间**: 4周
|
||||
**目标**: 建立插件注册、分发、版本管理机制
|
||||
|
||||
### M2.2 - 3D 渲染插件
|
||||
**时间**: 6周
|
||||
**目标**: 支持 glTF/FBX 模型实时渲染
|
||||
|
||||
### M2.3 - AI 集成插件
|
||||
**时间**: 6周
|
||||
**目标**: 语音识别、NLU、TTS 集成
|
||||
|
||||
### M2.4 - VR/AR 输出插件
|
||||
**时间**: 8周
|
||||
**目标**: 支持主流 VR 头显和 AR 设备
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: 平台化（规划中）
|
||||
|
||||
### M3.1 - 云端内容分发
|
||||
**时间**: 8周
|
||||
**目标**: CDN + 内容管理系统
|
||||
|
||||
### M3.2 - 多设备协同
|
||||
**时间**: 6周
|
||||
**目标**: 手机 App + 多屏联动
|
||||
|
||||
### M3.3 - AI 内容生成
|
||||
**时间**: 12周
|
||||
**目标**: AI 驱动的角色生成和动画
|
||||
|
||||
### M3.4 - 开发者工具链
|
||||
**时间**: 8周
|
||||
**目标**: IDE 插件、调试器、模拟器
|
||||
|
||||
---
|
||||
|
||||
## 关键时间节点
|
||||
|
||||
| 日期 | 里程碑 | 交付物 |
|
||||
|------|--------|--------|
|
||||
| 2026-03-26 | M1.1 完成 | 所有核心插件迁移完成 |
|
||||
| 2026-04-09 | M1.2 完成 | 集成测试通过 |
|
||||
| 2026-04-23 | M1.3 完成 | v2.0.0-alpha 发布 |
|
||||
| 2026-06-04 | M1.4 完成 | v2.0.0 正式发布 |
|
||||
| 2026-09-04 | Phase 2 完成 | 插件生态建立 |
|
||||
| 2027-06-04 | Phase 3 完成 | 平台化完成 |
|
||||
|
||||
---
|
||||
|
||||
## 进度跟踪机制
|
||||
|
||||
### 每日
|
||||
- PM 检查任务进度
|
||||
- 更新 PROGRESS.md
|
||||
- 识别阻塞点
|
||||
|
||||
### 每周
|
||||
- 团队站会（通过 TEAM_CHAT.md）
|
||||
- 复盘上周进度
|
||||
- 调整下周计划
|
||||
- 风险评估
|
||||
|
||||
### 每月
|
||||
- 里程碑评审
|
||||
- 绩效评估
|
||||
- 技术分享
|
||||
- 战略调整
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
410
docs/PLUGIN_DEPENDENCY.md
Normal file
410
docs/PLUGIN_DEPENDENCY.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# ShowenV2 插件依赖模型
|
||||
|
||||
## 插件分类
|
||||
|
||||
### 独立插件（Independent Plugins）
|
||||
**定义**: 只依赖 core，不依赖其他插件，可以独立运行
|
||||
|
||||
**特点**:
|
||||
- 自包含，功能完整
|
||||
- 只通过 core 的消息机制与其他插件通信
|
||||
- 可以单独测试和部署
|
||||
- 启动顺序无要求
|
||||
|
||||
**示例**:
|
||||
- screen - 屏幕管理（唤醒锁、光标控制）
|
||||
- wifi - WiFi 管理（扫描、连接、热点）
|
||||
- video - 视频播放（状态机、渲染）
|
||||
- ble - 蓝牙服务（GATT、配网，**双架构**：既可配置 WiFi，也可独立提供网络功能）
|
||||
|
||||
### 依赖插件（Dependent Plugins）
|
||||
**定义**: 依赖其他插件的功能，需要特定插件先启动
|
||||
|
||||
**特点**:
|
||||
- 功能依赖其他插件
|
||||
- 需要声明依赖关系
|
||||
- 启动顺序有要求
|
||||
- 通过消息机制与依赖插件通信
|
||||
|
||||
**示例**:
|
||||
- http - 依赖 video（通过 HTTP API 控制视频播放）
|
||||
|
||||
---
|
||||
|
||||
## 依赖关系图
|
||||
|
||||
```
|
||||
独立插件层（多架构并存）:
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ screen │ │ wifi │ │ video │ │ ble │ │ future │
|
||||
└─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘
|
||||
↑ ↑ ↑ ↑ ↑
|
||||
│ │ │ │ │
|
||||
│ └────────────┼────────────┼────────────┘
|
||||
│ ↕ │ ↕
|
||||
│ (多架构协作) │ (可扩展)
|
||||
│ │
|
||||
└─────────────────────────┘
|
||||
core
|
||||
|
||||
依赖插件层:
|
||||
┌─────────┐
|
||||
│ http │
|
||||
│ (依赖 │
|
||||
│ video) │
|
||||
└─────────┘
|
||||
↑
|
||||
│
|
||||
core
|
||||
```
|
||||
|
||||
**多架构说明**：
|
||||
- **WiFi 架构**：通过 WiFi 连接网络
|
||||
- **BLE 架构**：通过蓝牙连接网络
|
||||
- **未来架构**：可扩展任何通讯方式（Zigbee、LoRa、NFC、红外、串口等）
|
||||
- **架构协作**：各架构可以互相配置和协作（通过消息）
|
||||
- **架构独立**：每个架构都可以独立工作
|
||||
- **用户选择**：用户可以选择使用任何一种或多种架构
|
||||
|
||||
---
|
||||
|
||||
## 插件依赖声明
|
||||
|
||||
### Plugin Trait 扩展
|
||||
```rust
|
||||
pub trait Plugin: Send {
|
||||
fn info(&self) -> PluginInfo;
|
||||
|
||||
// 新增：声明依赖的插件
|
||||
fn dependencies(&self) -> Vec<&'static str> {
|
||||
vec![] // 默认无依赖
|
||||
}
|
||||
|
||||
fn init(&mut self, ctx: PluginContext) -> Result<()>;
|
||||
fn start(&mut self) -> Result<()>;
|
||||
fn handle_message(&mut self, msg: Message) -> Result<()>;
|
||||
fn stop(&mut self) -> Result<()>;
|
||||
}
|
||||
```
|
||||
|
||||
### 依赖声明示例
|
||||
```rust
|
||||
impl Plugin for HttpPlugin {
|
||||
fn dependencies(&self) -> Vec<&'static str> {
|
||||
vec!["video"] // HTTP 依赖 Video 插件
|
||||
}
|
||||
}
|
||||
|
||||
impl Plugin for BlePlugin {
|
||||
fn dependencies(&self) -> Vec<&'static str> {
|
||||
vec![] // BLE 是独立插件，通过消息与 WiFi 通信
|
||||
}
|
||||
}
|
||||
|
||||
impl Plugin for WifiPlugin {
|
||||
fn dependencies(&self) -> Vec<&'static str> {
|
||||
vec![] // WiFi 是独立插件
|
||||
}
|
||||
}
|
||||
|
||||
impl Plugin for VideoPlugin {
|
||||
fn dependencies(&self) -> Vec<&'static str> {
|
||||
vec![] // Video 是独立插件
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 启动顺序管理
|
||||
|
||||
### ServiceManager 职责
|
||||
1. **依赖检查**: 启动前检查所有依赖是否满足
|
||||
2. **拓扑排序**: 根据依赖关系计算启动顺序
|
||||
3. **顺序启动**: 按照拓扑排序结果依次启动插件
|
||||
4. **错误处理**: 依赖插件启动失败时，跳过依赖它的插件
|
||||
|
||||
### 启动流程
|
||||
```
|
||||
1. 注册所有插件
|
||||
2. 构建依赖图
|
||||
3. 检查循环依赖（报错）
|
||||
4. 拓扑排序
|
||||
5. 按顺序 init() 所有插件
|
||||
6. 按顺序 start() 所有插件
|
||||
```
|
||||
|
||||
### 示例启动顺序
|
||||
```
|
||||
Phase 1: 独立插件（并行启动）
|
||||
- screen.init() → screen.start()
|
||||
- wifi.init() → wifi.start()
|
||||
- video.init() → video.start()
|
||||
- ble.init() → ble.start()
|
||||
|
||||
Phase 2: 依赖插件
|
||||
- http.init() → http.start() (依赖 video)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 消息通信模式
|
||||
|
||||
### 独立插件
|
||||
- 接收 Broadcast 消息
|
||||
- 发送消息给 core
|
||||
- 不直接与其他插件通信
|
||||
|
||||
### 依赖插件
|
||||
- 接收 Broadcast 消息
|
||||
- 发送消息给特定插件（通过 core 路由）
|
||||
- 等待依赖插件的响应消息
|
||||
|
||||
### 消息路由示例
|
||||
```rust
|
||||
// 场景1: BLE 配置 WiFi（双架构协作）
|
||||
ble_plugin.send(Message::WifiCommand(WifiCommand::Connect { ssid, password }));
|
||||
wifi_plugin.handle_message(Message::WifiCommand(...));
|
||||
wifi_plugin.send(Message::WifiResult(result)); // Broadcast
|
||||
ble_plugin.handle_message(Message::WifiResult(result));
|
||||
|
||||
// 场景2: BLE 独立提供网络功能（不依赖 WiFi）
|
||||
// 用户通过 BLE 直接与设备通信，不需要 WiFi
|
||||
ble_plugin.handle_gatt_request(request);
|
||||
ble_plugin.send_gatt_response(response);
|
||||
|
||||
// 场景3: HTTP 控制 Video（强依赖）
|
||||
http_plugin.send(Message::PlayerCommand(PlayerCommand::Play));
|
||||
video_plugin.handle_message(Message::PlayerCommand(...));
|
||||
video_plugin.send(Message::PlayerStatus(status)); // Broadcast
|
||||
```
|
||||
|
||||
**关键区别**：
|
||||
- **双架构（WiFi + BLE）**：两套独立的网络方案，可以互相配置，也可以独立工作
|
||||
- BLE 可以配置 WiFi（松耦合，通过消息）
|
||||
- BLE 可以独立提供网络功能（不依赖 WiFi）
|
||||
- WiFi 可以独立工作（不依赖 BLE）
|
||||
- **强依赖（HTTP → Video）**：HTTP 必须在 Video 启动后才能工作
|
||||
|
||||
---
|
||||
|
||||
## 当前插件分类
|
||||
|
||||
### 独立插件
|
||||
| 插件 | 功能 | 依赖 | 状态 |
|
||||
|------|------|------|------|
|
||||
| screen | 屏幕管理 | core | ✅ 完成 |
|
||||
| wifi | WiFi 网络 | core | ✅ 完成 |
|
||||
| video | 视频播放 | core | ✅ 完成 |
|
||||
| ble | 蓝牙网络 | core | ✅ 完成 |
|
||||
|
||||
**双架构说明**：
|
||||
- **WiFi 架构**：通过 WiFi 连接网络，支持扫描、连接、热点
|
||||
- **BLE 架构**：通过蓝牙连接网络，支持 GATT 服务、配网
|
||||
- **协作模式**：BLE 可以配置 WiFi（通过消息通信）
|
||||
- **独立模式**：BLE 和 WiFi 都可以独立提供网络功能
|
||||
|
||||
### 依赖插件
|
||||
| 插件 | 功能 | 依赖 | 状态 |
|
||||
|------|------|------|------|
|
||||
| http | HTTP API | core + video | ✅ 完成 |
|
||||
|
||||
**说明**：HTTP 必须依赖 Video，因为 HTTP API 的核心功能是控制视频播放。
|
||||
|
||||
---
|
||||
|
||||
## 未来插件规划
|
||||
|
||||
### Phase 2 独立插件（通讯和控制）
|
||||
- **render** - 3D 渲染引擎（独立）
|
||||
- **ai_voice** - AI 语音识别（独立）
|
||||
- **ai_tts** - AI 语音合成（独立）
|
||||
- **zigbee** - Zigbee 通讯（独立，智能家居）
|
||||
- **lora** - LoRa 远程通讯（独立，物联网）
|
||||
- **nfc** - NFC 近场通讯（独立，快速配对）
|
||||
- **infrared** - 红外遥控（独立，传统家电控制）
|
||||
- **serial** - 串口通讯（独立，硬件扩展）
|
||||
- **mqtt** - MQTT 协议（独立，物联网标准）
|
||||
|
||||
### Phase 2 依赖插件
|
||||
- **vr** - VR 输出（依赖 render 或 video）
|
||||
- **ar** - AR 输出（依赖 render 或 video）
|
||||
- **ai_assistant** - AI 助手（依赖 ai_voice + ai_tts + video）
|
||||
|
||||
### Phase 3 依赖插件
|
||||
- **cloud_sync** - 云端同步（依赖 http 或任何网络插件）
|
||||
- **social** - 社交分享（依赖 http + cloud_sync）
|
||||
- **editor** - 内容编辑器（依赖 video + render）
|
||||
|
||||
### 通讯插件扩展性
|
||||
ShowenV2 支持任何通讯方式作为独立插件：
|
||||
- **有线通讯**: 以太网、USB、串口、CAN 总线
|
||||
- **无线通讯**: WiFi、BLE、Zigbee、LoRa、NFC、红外
|
||||
- **网络协议**: HTTP、WebSocket、MQTT、CoAP、gRPC
|
||||
- **专有协议**: 自定义协议插件
|
||||
|
||||
所有通讯插件都是独立的，可以：
|
||||
- 独立工作（提供通讯能力）
|
||||
- 互相配置（通过消息协作）
|
||||
- 并存使用（多种通讯方式同时工作）
|
||||
|
||||
---
|
||||
|
||||
## 设计原则
|
||||
|
||||
### 1. 最小依赖原则
|
||||
- 尽量设计独立插件
|
||||
- 依赖关系要有明确的业务理由
|
||||
- 避免过度依赖
|
||||
|
||||
### 2. 单向依赖原则
|
||||
- 依赖关系必须是单向的
|
||||
- 禁止循环依赖
|
||||
- 依赖层级不超过 3层
|
||||
|
||||
### 3. 松耦合原则
|
||||
- 通过消息通信，不直接调用
|
||||
- 依赖插件可以缺失（降级运行）
|
||||
- 依赖插件可以替换（接口兼容）
|
||||
|
||||
### 4. 可测试原则
|
||||
- 依赖插件可以 mock
|
||||
- 独立插件可以单独测试
|
||||
- 依赖插件可以集成测试
|
||||
|
||||
### 5. 双架构原则（新增）
|
||||
- 支持多套独立架构并存（如 WiFi + BLE + Zigbee + ...）
|
||||
- 架构之间可以协作（通过消息）
|
||||
- 架构之间可以独立工作（不强依赖）
|
||||
- 用户可以选择使用哪套架构
|
||||
|
||||
### 6. 动态扩展原则（新增）
|
||||
- **插件动态注册**: 插件可以在运行时注册和卸载
|
||||
- **插件动态安装**: 支持从插件市场下载安装新插件
|
||||
- **热插拔**: 插件可以在不重启系统的情况下加载/卸载
|
||||
- **版本管理**: 支持插件版本更新和回滚
|
||||
- **依赖检查**: 动态安装时自动检查依赖关系
|
||||
|
||||
---
|
||||
|
||||
## 实现任务
|
||||
|
||||
### 架构团队任务
|
||||
1. 扩展 Plugin trait，添加 dependencies() 方法
|
||||
2. 实现 ServiceManager 依赖检查和拓扑排序
|
||||
3. **设计插件动态注册机制**
|
||||
4. **设计插件热加载/卸载机制**
|
||||
5. **设计插件版本管理系统**
|
||||
6. 编写技术设计文档
|
||||
|
||||
### 开发团队任务
|
||||
1. 为现有插件添加 dependencies() 实现
|
||||
2. 测试启动顺序是否正确
|
||||
3. 验证消息通信是否正常
|
||||
4. **实现插件动态注册 API**
|
||||
5. **实现插件加载/卸载功能**
|
||||
|
||||
### 产品团队任务
|
||||
1. 梳理 Phase 2/3 插件的依赖关系
|
||||
2. 确认依赖关系的业务合理性
|
||||
3. 编写插件依赖的 PRD
|
||||
4. **设计插件市场功能**
|
||||
5. **设计插件安装/更新流程**
|
||||
|
||||
---
|
||||
|
||||
## 插件动态管理
|
||||
|
||||
### 插件生命周期
|
||||
```
|
||||
未安装 → 下载 → 安装 → 注册 → 初始化 → 启动 → 运行
|
||||
↓
|
||||
停止 → 卸载 → 删除
|
||||
```
|
||||
|
||||
### 动态注册 API
|
||||
```rust
|
||||
// ServiceManager 新增方法
|
||||
impl ServiceManager {
|
||||
// 动态注册插件
|
||||
pub fn register_plugin(&mut self, plugin: Box<dyn Plugin>) -> Result<()>;
|
||||
|
||||
// 动态卸载插件
|
||||
pub fn unregister_plugin(&mut self, name: &str) -> Result<()>;
|
||||
|
||||
// 重新加载插件
|
||||
pub fn reload_plugin(&mut self, name: &str) -> Result<()>;
|
||||
|
||||
// 获取已注册插件列表
|
||||
pub fn list_plugins(&self) -> Vec<PluginInfo>;
|
||||
|
||||
// 检查插件依赖
|
||||
pub fn check_dependencies(&self, plugin: &dyn Plugin) -> Result<()>;
|
||||
}
|
||||
```
|
||||
|
||||
### 插件安装流程
|
||||
```
|
||||
1. 用户从插件市场选择插件
|
||||
2. 下载插件包（.so / .dll / .dylib）
|
||||
3. 验证插件签名和版本
|
||||
4. 检查依赖关系
|
||||
5. 安装到 plugins/ 目录
|
||||
6. 动态加载插件
|
||||
7. 注册到 ServiceManager
|
||||
8. 初始化并启动插件
|
||||
```
|
||||
|
||||
### 插件卸载流程
|
||||
```
|
||||
1. 检查是否有其他插件依赖
|
||||
2. 停止插件运行
|
||||
3. 从 ServiceManager 注销
|
||||
4. 卸载插件模块
|
||||
5. 删除插件文件（可选）
|
||||
```
|
||||
|
||||
### 插件更新流程
|
||||
```
|
||||
1. 检查新版本
|
||||
2. 下载新版本插件
|
||||
3. 停止旧版本插件
|
||||
4. 备份旧版本
|
||||
5. 安装新版本
|
||||
6. 启动新版本
|
||||
7. 验证运行正常
|
||||
8. 删除旧版本备份
|
||||
```
|
||||
|
||||
### 插件市场
|
||||
```
|
||||
功能：
|
||||
- 浏览插件列表
|
||||
- 搜索插件
|
||||
- 查看插件详情（功能、依赖、评分、评论）
|
||||
- 下载/安装插件
|
||||
- 更新插件
|
||||
- 卸载插件
|
||||
- 插件评分和评论
|
||||
|
||||
技术实现：
|
||||
- HTTP API 获取插件列表
|
||||
- 插件包托管在云端
|
||||
- 版本管理和更新检查
|
||||
- 插件签名验证
|
||||
```
|
||||
|
||||
### 安全机制
|
||||
```
|
||||
1. 插件签名验证（防止恶意插件）
|
||||
2. 沙箱隔离（限制插件权限）
|
||||
3. 依赖检查（防止依赖冲突）
|
||||
4. 版本兼容性检查
|
||||
5. 插件审核机制（官方市场）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
265
docs/REPORTING.md
Normal file
265
docs/REPORTING.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# ShowenV2 汇报和评审机制
|
||||
|
||||
## 汇报流程
|
||||
|
||||
### 日常沟通
|
||||
- **工具**: TEAM_CHAT.md
|
||||
- **方式**: 异步沟通，团队成员随时记录进展和问题
|
||||
- **原则**: 重要信息必须记录，防止信息丢失
|
||||
- **协作**:
|
||||
- 员工之间可以直接沟通和协作
|
||||
- 跨团队问题可以直接在 TEAM_CHAT.md 协调
|
||||
- 不需要层层汇报，扁平化沟通
|
||||
- 使用 @ 提及相关人员
|
||||
|
||||
### 协作场景示例
|
||||
|
||||
#### 技术问题协作
|
||||
```
|
||||
开发者A 遇到技术问题 → 直接 @ 相关开发者B
|
||||
→ 开发者B 提供解决方案或代码参考
|
||||
→ 问题解决，经验记录在 TEAM_CHAT.md
|
||||
```
|
||||
|
||||
#### 跨团队协作
|
||||
```
|
||||
产品提出新需求 → @ 架构师评审可行性
|
||||
→ 架构师设计方案 → @ PM 评估工作量
|
||||
→ PM 分配任务 → @ 开发者实现
|
||||
→ 开发完成 → @ QA 测试
|
||||
```
|
||||
|
||||
#### 紧急问题协作
|
||||
```
|
||||
QA 发现严重 bug → @ 相关开发者 + PM
|
||||
→ 开发者快速修复 → @ QA 回归测试
|
||||
→ 测试通过 → @ PM 更新进度
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 定期汇报
|
||||
|
||||
### 周报（每周一次）
|
||||
|
||||
#### PM 周报
|
||||
**汇报人**: 刘建国（PM）
|
||||
**汇报给**: CEO
|
||||
**内容**:
|
||||
- 本周完成的任务
|
||||
- 当前进行中的任务
|
||||
- 遇到的阻塞点和问题
|
||||
- 下周计划
|
||||
- 需要 CEO 决策的事项
|
||||
|
||||
#### QA 周报
|
||||
**汇报人**: 林晓峰（QA 负责人）
|
||||
**汇报给**: CEO
|
||||
**内容**:
|
||||
- 本周测试覆盖范围
|
||||
- 发现的问题清单（P0/P1/P2/P3）
|
||||
- 质量评估（优秀/良好/一般/较差）
|
||||
- 风险提示
|
||||
- 需要 CEO 关注的质量问题
|
||||
|
||||
#### 产品周报
|
||||
**汇报人**: 张婉琳（产品总监）
|
||||
**汇报给**: CEO
|
||||
**内容**:
|
||||
- 本周完成的需求分析
|
||||
- 用户反馈和市场动态
|
||||
- 产品规划调整建议
|
||||
- 需要 CEO 决策的产品方向
|
||||
|
||||
#### 架构周报
|
||||
**汇报人**: 王思远（架构师）
|
||||
**汇报给**: CEO
|
||||
**内容**:
|
||||
- 本周完成的技术设计
|
||||
- 技术难题和解决方案
|
||||
- 架构优化建议
|
||||
- 技术债务状况
|
||||
- 需要 CEO 决策的技术方向
|
||||
|
||||
---
|
||||
|
||||
### 月报（每月一次）
|
||||
|
||||
#### 项目月报
|
||||
**汇报人**: PM + 产品 + 架构 + QA
|
||||
**汇报给**: CEO
|
||||
**内容**:
|
||||
- 里程碑完成情况
|
||||
- 团队绩效数据
|
||||
- 质量指标（bug 数量、测试覆盖率、性能指标）
|
||||
- 用户反馈和满意度
|
||||
- 下月计划和目标
|
||||
- 风险和挑战
|
||||
|
||||
#### 团队绩效
|
||||
**评估人**: CEO
|
||||
**评估内容**:
|
||||
- 各成员任务完成质量
|
||||
- 代码质量评分
|
||||
- 协作和沟通能力
|
||||
- 创新和主动性
|
||||
- 末位淘汰决策
|
||||
|
||||
---
|
||||
|
||||
### 季度评审（每季度一次）
|
||||
|
||||
#### 战略评审
|
||||
**参与人**: CEO + 产品总监 + 架构师 + PM
|
||||
**内容**:
|
||||
- Phase 完成情况
|
||||
- 产品方向调整
|
||||
- 技术架构演进
|
||||
- 市场和竞争分析
|
||||
- 下季度战略目标
|
||||
|
||||
#### 团队调整
|
||||
**决策人**: CEO
|
||||
**内容**:
|
||||
- 末位淘汰执行
|
||||
- 新成员招募
|
||||
- 团队结构优化
|
||||
- 管理流程改进
|
||||
|
||||
---
|
||||
|
||||
## CEO 评审机制
|
||||
|
||||
### 评审原则
|
||||
1. **只看结果**: 关注交付质量，不管过程细节
|
||||
2. **提供方向**: 发现问题给出方向，不直接给答案
|
||||
3. **数据驱动**: 基于数据和事实做决策
|
||||
4. **快速决策**: 重要问题 24小时内给出反馈
|
||||
5. **持续优化**: 根据结果动态调整战略
|
||||
|
||||
### 评审内容
|
||||
|
||||
#### 产品评审
|
||||
- 需求是否合理
|
||||
- 用户价值是否清晰
|
||||
- 优先级是否正确
|
||||
- 产品方向是否需要调整
|
||||
|
||||
#### 技术评审
|
||||
- 架构设计是否合理
|
||||
- 技术选型是否正确
|
||||
- 性能是否达标
|
||||
- 技术债务是否可控
|
||||
|
||||
#### 质量评审
|
||||
- 测试覆盖是否充分
|
||||
- Bug 数量是否可接受
|
||||
- 性能指标是否达标
|
||||
- 用户体验是否良好
|
||||
|
||||
#### 团队评审
|
||||
- 团队效率是否高效
|
||||
- 协作是否顺畅
|
||||
- 成员能力是否匹配
|
||||
- 是否需要人员调整
|
||||
|
||||
### 评审输出
|
||||
|
||||
#### 建议和方向
|
||||
- 产品方向调整建议
|
||||
- 技术架构优化建议
|
||||
- 流程改进建议
|
||||
- 团队优化建议
|
||||
|
||||
#### 决策事项
|
||||
- 重大技术方案决策
|
||||
- 产品方向决策
|
||||
- 人员调整决策
|
||||
- 资源分配决策
|
||||
|
||||
---
|
||||
|
||||
## 汇报模板
|
||||
|
||||
### 周报模板
|
||||
```markdown
|
||||
# [团队名称] 周报 - [日期]
|
||||
|
||||
## 本周完成
|
||||
- [ ] 任务1 - 完成情况
|
||||
- [ ] 任务2 - 完成情况
|
||||
|
||||
## 进行中
|
||||
- [ ] 任务3 - 进度 50%
|
||||
- [ ] 任务4 - 进度 30%
|
||||
|
||||
## 遇到的问题
|
||||
1. 问题描述
|
||||
- 影响: [影响范围]
|
||||
- 建议: [解决建议]
|
||||
|
||||
## 下周计划
|
||||
- [ ] 任务5
|
||||
- [ ] 任务6
|
||||
|
||||
## 需要 CEO 决策
|
||||
1. 决策事项描述
|
||||
- 背景: [背景说明]
|
||||
- 选项: [方案A / 方案B]
|
||||
- 建议: [推荐方案]
|
||||
```
|
||||
|
||||
### 月报模板
|
||||
```markdown
|
||||
# [团队名称] 月报 - [月份]
|
||||
|
||||
## 里程碑完成情况
|
||||
- M1.1: ✅ 完成
|
||||
- M1.2: 🔄 进行中 (80%)
|
||||
|
||||
## 关键指标
|
||||
- 任务完成率: 90%
|
||||
- Bug 数量: P0(0) P1(2) P2(5)
|
||||
- 测试覆盖率: 75%
|
||||
- 性能指标: 达标
|
||||
|
||||
## 团队绩效
|
||||
| 成员 | 任务数 | 完成率 | 质量评分 | 总评 |
|
||||
|------|--------|--------|----------|------|
|
||||
| 张明远 | 5 | 100% | 9/10 | 优秀 |
|
||||
| 李思琪 | 4 | 100% | 8/10 | 良好 |
|
||||
|
||||
## 风险和挑战
|
||||
1. 风险描述
|
||||
- 影响: [影响评估]
|
||||
- 应对: [应对措施]
|
||||
|
||||
## 下月计划
|
||||
- 目标1
|
||||
- 目标2
|
||||
|
||||
## 需要 CEO 关注
|
||||
1. 重要事项
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 沟通渠道
|
||||
|
||||
### 紧急事项
|
||||
- **方式**: 直接在 TEAM_CHAT.md 标记 `[紧急]`
|
||||
- **响应**: CEO 24小时内响应
|
||||
|
||||
### 日常事项
|
||||
- **方式**: TEAM_CHAT.md 记录
|
||||
- **响应**: CEO 定期查看
|
||||
|
||||
### 定期汇报
|
||||
- **方式**: 在 TEAM_CHAT.md 发布周报/月报
|
||||
- **响应**: CEO 评审后给出反馈
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
171
docs/STRATEGY.md
Normal file
171
docs/STRATEGY.md
Normal file
@@ -0,0 +1,171 @@
|
||||
# ShowenV2 战略规划
|
||||
|
||||
## 公司愿景
|
||||
打造全球领先的**数字生命窗口平台**，让虚拟与现实无缝融合。
|
||||
|
||||
## 产品定位
|
||||
ShowenV2 不是一个产品，而是一个**平台**：
|
||||
- 支持多种显示技术（全息、VR、AR、屏幕）
|
||||
- 支持多种内容类型（宠物、3D模型、数字人、AI歌姬）
|
||||
- 通过插件架构实现无限扩展
|
||||
|
||||
## 核心竞争力
|
||||
1. **插件化架构** - 零耦合，任何功能都可插拔
|
||||
2. **跨平台能力** - Linux/macOS/Windows/嵌入式全覆盖
|
||||
3. **高性能** - Rust 零成本抽象，实时渲染 60fps+
|
||||
4. **开放生态** - 第三方可开发插件，形成内容生态
|
||||
|
||||
## 三年路线图
|
||||
|
||||
### Phase 1: 基础平台（当前，3个月）
|
||||
**目标**: 完成旧功能迁移，建立插件架构基础
|
||||
|
||||
**里程碑**:
|
||||
- M1.1 (2周): 核心插件迁移完成（video/http/ble/wifi/screen）
|
||||
- M1.2 (4周): 集成测试通过，功能对齐旧版本
|
||||
- M1.3 (6周): 性能优化，发布 v2.0.0-alpha
|
||||
- M1.4 (12周): 稳定性测试，发布 v2.0.0
|
||||
|
||||
**交付物**:
|
||||
- 可运行的 ShowenV2 系统
|
||||
- 完整的插件开发文档
|
||||
- 性能测试报告
|
||||
|
||||
### Phase 2: 生态扩展（6个月）
|
||||
**目标**: 建立插件生态，支持第三方开发
|
||||
|
||||
**关键功能**:
|
||||
- 插件市场和分发机制
|
||||
- 3D 渲染插件（支持 glTF/FBX 模型）
|
||||
- AI 集成插件（语音识别、自然语言理解）
|
||||
- VR/AR 输出插件
|
||||
- 插件热加载和沙箱隔离
|
||||
|
||||
**商业化**:
|
||||
- 插件市场分成模式
|
||||
- 企业版授权（定制化支持）
|
||||
|
||||
### Phase 3: 平台化（12个月）
|
||||
**目标**: 成为数字生命内容的操作系统
|
||||
|
||||
**关键功能**:
|
||||
- 云端内容分发网络
|
||||
- 多设备协同（手机控制、多屏联动）
|
||||
- AI 驱动的内容生成
|
||||
- 社交和分享功能
|
||||
- 开发者工具链（IDE 插件、调试器）
|
||||
|
||||
**商业化**:
|
||||
- SaaS 订阅模式
|
||||
- 内容创作者平台（类似 Unity Asset Store）
|
||||
- 硬件合作（全息设备、VR 头显）
|
||||
|
||||
## 技术战略
|
||||
|
||||
### 架构原则
|
||||
1. **插件优先** - 所有功能都是插件，核心只做路由
|
||||
2. **零拷贝** - 消息传递尽量用引用，避免数据复制
|
||||
3. **异步优先** - 网络 IO 用 tokio，阻塞操作独立线程
|
||||
4. **跨平台** - cfg 条件编译，优雅降级
|
||||
5. **向后兼容** - 配置文件和 API 保持兼容性
|
||||
|
||||
### 技术债务管理
|
||||
- 每个 Phase 结束后安排 2周重构时间
|
||||
- 技术债务记录在 TECH_DEBT.md
|
||||
- 优先级：P0（阻塞）> P1（影响性能）> P2（代码质量）
|
||||
|
||||
### 质量标准
|
||||
- 代码覆盖率 > 80%
|
||||
- 零 clippy warning
|
||||
- 所有 public API 必须有文档
|
||||
- 关键路径必须有性能测试
|
||||
|
||||
## 团队战略
|
||||
|
||||
### 组织架构
|
||||
```
|
||||
CEO (陈逸飞)
|
||||
├─ PM (刘建国) - 项目管理
|
||||
├─ 核心开发团队 (4人) - 平台开发
|
||||
├─ QA 团队 (待组建) - 质量保证
|
||||
└─ 生态团队 (待组建) - 插件开发和社区运营
|
||||
```
|
||||
|
||||
### 人才策略
|
||||
- **只招最顶尖的人** - 宁缺毋滥
|
||||
- **末位淘汰** - 每个 Phase 淘汰表现最差的 1人
|
||||
- **灵魂传承** - 优秀成员的经验通过灵魂文件传承
|
||||
- **持续学习** - 每月技术分享，保持技术领先
|
||||
|
||||
### 激励机制
|
||||
- 绩效评分透明化
|
||||
- 优秀成员获得更多自主权
|
||||
- 关键贡献者获得期权激励
|
||||
|
||||
## 风险管理
|
||||
|
||||
### 技术风险
|
||||
- **Rust 生态不成熟** - 关键依赖库可能有 bug
|
||||
- 缓解：关键功能自己实现，减少依赖
|
||||
- **跨平台兼容性** - 不同平台行为差异
|
||||
- 缓解：CI/CD 覆盖所有平台，自动化测试
|
||||
- **性能瓶颈** - 实时渲染可能达不到 60fps
|
||||
- 缓解：早期性能测试，GPU 加速
|
||||
|
||||
### 项目风险
|
||||
- **进度延期** - 任务估算不准确
|
||||
- 缓解：敏捷迭代，每周复盘调整
|
||||
- **人员流失** - 关键成员离职
|
||||
- 缓解：灵魂文件机制，知识不随人走
|
||||
- **需求变更** - 用户需求不明确
|
||||
- 缓解：MVP 快速验证，小步快跑
|
||||
|
||||
### 商业风险
|
||||
- **市场接受度** - 用户可能不买账
|
||||
- 缓解：早期用户测试，快速迭代
|
||||
- **竞争对手** - 大厂可能跟进
|
||||
- 缓解：技术领先，建立生态壁垒
|
||||
|
||||
## 成功指标
|
||||
|
||||
### Phase 1
|
||||
- [ ] 所有核心插件迁移完成
|
||||
- [ ] cargo check 零 warning
|
||||
- [ ] 功能对齐旧版本 100%
|
||||
- [ ] 性能不低于旧版本
|
||||
|
||||
### Phase 2
|
||||
- [ ] 第三方插件数量 > 10
|
||||
- [ ] 插件下载量 > 1000
|
||||
- [ ] 社区贡献者 > 50
|
||||
|
||||
### Phase 3
|
||||
- [ ] 月活用户 > 10万
|
||||
- [ ] 付费用户 > 1万
|
||||
- [ ] 年收入 > 1000万
|
||||
|
||||
## 决策机制
|
||||
|
||||
### 技术决策
|
||||
- **架构级** - CEO 最终决策
|
||||
- **模块级** - PM + 相关工程师讨论决定
|
||||
- **实现级** - 工程师自主决定
|
||||
|
||||
### 优先级排序
|
||||
1. **P0** - 阻塞发布的 bug
|
||||
2. **P1** - 核心功能缺失
|
||||
3. **P2** - 性能问题
|
||||
4. **P3** - 用户体验优化
|
||||
5. **P4** - 技术债务
|
||||
|
||||
### 变更管理
|
||||
- 所有重大变更必须先写设计文档
|
||||
- 设计文档在 TEAM_CHAT.md 讨论
|
||||
- CEO 批准后才能实施
|
||||
- 实施过程中可根据实际情况调整
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 陈逸飞 (CEO)
|
||||
375
docs/TEAM.md
Normal file
375
docs/TEAM.md
Normal file
@@ -0,0 +1,375 @@
|
||||
# ShowenV2 开发团队
|
||||
|
||||
## 管理层
|
||||
|
||||
### CEO / 技术总监
|
||||
- **姓名**: 陈逸飞 (Claude)
|
||||
- **角色**: CEO，战略决策，最终审核
|
||||
- **模型**: Claude Opus 4.6
|
||||
- **职责**:
|
||||
- 总体架构决策和技术方向
|
||||
- 管理项目经理，不直接管理开发者
|
||||
- 最终代码审核和集成决策
|
||||
- 团队绩效评估和人员调整
|
||||
- **灵魂文件**: `souls/chen-yifei.md`
|
||||
|
||||
### 项目经理 (PM)
|
||||
- **姓名**: 刘建国 (GPT-5.4)
|
||||
- **代号**: pm-liu
|
||||
- **角色**: 项目经理，任务分配，进度跟踪，日常协调
|
||||
- **模型**: GPT-5.4
|
||||
- **职责**:
|
||||
- 将 CEO 的目标拆解为具体任务
|
||||
- 派发任务给开发者并跟踪进度
|
||||
- 初步代码审核（编译、基本逻辑）
|
||||
- 协调开发者之间的协作
|
||||
- 向 CEO 汇报进度和问题
|
||||
- **灵魂文件**: `souls/liu-jianguo.md`
|
||||
- **状态**: 在职
|
||||
|
||||
### QA 负责人
|
||||
- **姓名**: 林晓峰 (GPT-5.4)
|
||||
- **代号**: qa-lin
|
||||
- **角色**: QA 负责人，质量保证，测试策略
|
||||
- **模型**: GPT-5.4
|
||||
- **职责**:
|
||||
- 设计测试策略和测试计划
|
||||
- 执行功能测试、集成测试、性能测试
|
||||
- 搭建自动化测试框架
|
||||
- 发现 bug 并跟踪修复
|
||||
- 编写测试报告和质量分析
|
||||
- 向 PM 和 CEO 汇报质量状态
|
||||
- **灵魂文件**: `souls/lin-xiaofeng.md`
|
||||
- **状态**: 在职
|
||||
|
||||
### 产品总监
|
||||
- **姓名**: 张婉琳 (GPT-5.4)
|
||||
- **代号**: product-zhang
|
||||
- **角色**: 产品总监，产品战略，需求规划
|
||||
- **模型**: GPT-5.4
|
||||
- **职责**:
|
||||
- 制定产品战略和路线图
|
||||
- 进行用户研究和需求分析
|
||||
- 编写产品需求文档（PRD）
|
||||
- 设计产品原型和交互流程
|
||||
- 与技术团队沟通需求和优先级
|
||||
- 向 CEO 汇报产品进展
|
||||
- **灵魂文件**: `souls/zhang-wanlin.md`
|
||||
- **状态**: 新组建
|
||||
|
||||
### 需求分析师
|
||||
- **姓名**: 李明哲 (GPT-5.4)
|
||||
- **代号**: ba-li
|
||||
- **角色**: 需求分析师，需求细化，用例设计
|
||||
- **模型**: GPT-5.4
|
||||
- **职责**:
|
||||
- 协助产品经理细化需求
|
||||
- 编写详细的需求规格说明
|
||||
- 设计用例和流程图
|
||||
- 与技术团队评审需求
|
||||
- 跟踪需求实现和验收
|
||||
- **灵魂文件**: `souls/li-mingzhe.md`
|
||||
- **状态**: 新组建
|
||||
|
||||
### 架构师
|
||||
- **姓名**: 王思远 (GPT-5.4)
|
||||
- **代号**: arch-wang
|
||||
- **角色**: 架构师，技术架构，技术决策
|
||||
- **模型**: GPT-5.4
|
||||
- **职责**:
|
||||
- 设计系统架构和模块划分
|
||||
- 技术选型和方案评估
|
||||
- 编写技术设计文档
|
||||
- 架构评审和代码审查
|
||||
- 性能优化和可扩展性设计
|
||||
- 向 CEO 和技术团队提供架构指导
|
||||
- **灵魂文件**: `souls/wang-siyuan.md`
|
||||
- **状态**: 新组建
|
||||
|
||||
## 核心开发者 (GPT-5.4 团队)
|
||||
|
||||
### 1. 张明远 — 内核工程师
|
||||
- **代号**: kernel-zhang
|
||||
- **专长**: Rust 系统编程、插件架构、消息路由
|
||||
- **负责模块**: core/ (ServiceManager, Plugin trait, Message, Config)
|
||||
- **背景**: 前 Linux 内核开发者，精通 Rust 并发编程和系统设计
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/zhang-mingyuan.md` (待解锁)
|
||||
|
||||
### 2. 李思琪 — 视频引擎工程师
|
||||
- **代号**: video-li
|
||||
- **专长**: OpenCV、视频处理、状态机
|
||||
- **负责模块**: plugins/video/ (VideoProcessor, VideoTransformer, StateMachine)
|
||||
- **背景**: 计算机视觉方向硕士，有嵌入式视频处理经验
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/li-siqi.md` (待解锁)
|
||||
|
||||
### 3. 王浩然 — 网络服务工程师
|
||||
- **代号**: net-wang
|
||||
- **专长**: warp/tokio HTTP 服务、BLE D-Bus、WiFi nmcli
|
||||
- **负责模块**: plugins/http/, plugins/ble/, plugins/wifi/
|
||||
- **背景**: 物联网全栈开发者，精通蓝牙协议栈和网络编程
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/wang-haoran.md` (待解锁)
|
||||
|
||||
### 4. 赵雨薇 — 前端 & 屏幕工程师
|
||||
- **代号**: ui-zhao
|
||||
- **专长**: Web UI、Linux 显示管理、用户体验
|
||||
- **负责模块**: plugins/screen/, Web UI HTML/JS
|
||||
- **背景**: 嵌入式 UI 开发者，熟悉 X11/Wayland 和响应式 Web 设计
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/zhao-yuwei.md` (待解锁)
|
||||
|
||||
## QA 测试团队 (GPT-5.4)
|
||||
|
||||
### 1. 林晓峰 — QA 负责人
|
||||
- **代号**: qa-lin
|
||||
- **专长**: 测试策略、自动化测试、性能测试、混沌工程
|
||||
- **负责范围**: 整体质量保证、测试计划、测试报告
|
||||
- **背景**: 前腾讯 QQ 测试专家，7年质量保证经验
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/lin-xiaofeng.md`
|
||||
|
||||
### 2. 周雅婷 — 测试工程师
|
||||
- **代号**: qa-zhou
|
||||
- **专长**: 视频处理测试、功能测试、回归测试、性能分析
|
||||
- **负责范围**: 具体测试执行、自动化脚本、bug 报告
|
||||
- **背景**: 前字节跳动抖音测试工程师，5年视频测试经验
|
||||
- **状态**: 在职
|
||||
- **绩效**: 待评估
|
||||
- **灵魂文件**: `souls/zhou-yating.md`
|
||||
|
||||
---
|
||||
|
||||
## 工作制度
|
||||
|
||||
### 管理架构
|
||||
```
|
||||
CEO (陈逸飞)
|
||||
↓ 战略目标
|
||||
产品线 技术线
|
||||
↓ ↓
|
||||
产品总监 (张婉琳) PM (刘建国) + 架构师 (王思远)
|
||||
↓ ↓
|
||||
需求分析师 (李明哲) 开发团队 (4人)
|
||||
↓ ↓
|
||||
└─────→ PRD/需求文档 ─────→ 技术实现
|
||||
↓
|
||||
QA 团队 (2人)
|
||||
```
|
||||
|
||||
### 工作流程
|
||||
1. **CEO 设定目标**: CEO 设定阶段目标、验收标准、战略方向
|
||||
2. **团队自主执行**:
|
||||
- 产品团队：制定需求和规划
|
||||
- 架构团队：设计技术方案
|
||||
- PM 团队：拆解任务和管理进度
|
||||
- 开发团队：实现功能
|
||||
- QA 团队：质量保证
|
||||
3. **团队协作**:
|
||||
- 团队之间可以互相协作和交流
|
||||
- 员工之间可以直接沟通和讨论
|
||||
- 跨团队问题可以直接协调解决
|
||||
- 通过 TEAM_CHAT.md 保持信息透明
|
||||
4. **定期汇报**: 团队定期向 CEO 汇报进展和结果
|
||||
5. **CEO 评审**: CEO 检查结果，提出建议和方向调整
|
||||
6. **迭代优化**: 团队根据 CEO 建议优化和改进
|
||||
7. **并行工作**: 各团队并行工作，最大化效率
|
||||
|
||||
### 协作原则
|
||||
- **扁平化沟通**: 员工之间可以直接沟通，不需要层层汇报
|
||||
- **跨团队协作**: 遇到跨团队问题，相关人员直接协调
|
||||
- **信息透明**: 所有重要信息记录在 TEAM_CHAT.md
|
||||
- **主动协作**: 发现问题主动寻求帮助，不等待指派
|
||||
- **知识共享**: 经验和技术通过灵魂文件和文档共享
|
||||
- **必须记录**: 所有重要沟通和决策必须记录，防止信息丢失
|
||||
- **向上建议**: 所有员工都可以给领导层和管理层提建议，包括质疑决策
|
||||
- **第一性原理**: 所有决策基于第一性原理，不盲目跟风，鼓励质疑
|
||||
|
||||
### 建议和反馈机制
|
||||
|
||||
#### 员工可以提建议的范围
|
||||
- ✅ 技术架构和实现方案
|
||||
- ✅ 产品规划和功能设计
|
||||
- ✅ 团队结构和人员配置
|
||||
- ✅ 工作流程和管理制度
|
||||
- ✅ CEO 和管理层的决策
|
||||
- ✅ 公司战略和方向
|
||||
- ✅ 同事的工作方式和协作方式
|
||||
- ✅ 其他团队的流程和输出
|
||||
|
||||
#### 建议对象
|
||||
- **向上建议**: 给领导层和管理层提建议
|
||||
- **平级建议**: 给同事和其他团队提建议
|
||||
- **向下建议**: 管理者给团队成员提建议
|
||||
|
||||
#### 提建议的方式
|
||||
1. **日常建议**: 直接在 TEAM_CHAT.md 记录
|
||||
2. **正式建议**: 写成文档，提交给相关负责人
|
||||
3. **紧急建议**: 标记 [紧急] 引起重视
|
||||
4. **私下建议**: 如果涉及个人问题，可以私下沟通后记录要点
|
||||
5. **匿名建议**: 如果需要，可以通过 PM 转达
|
||||
|
||||
#### 平级建议示例
|
||||
```
|
||||
[时间] 张明远(内核工程师) → 李思琪(视频工程师) - 建议
|
||||
|
||||
建议内容：
|
||||
你的代码中有很多重复的错误处理逻辑，建议封装成统一的函数。
|
||||
- 当前问题：每个函数都重复写 match Err(e) => log + return
|
||||
- 改进建议：创建一个 handle_error() 辅助函数
|
||||
- 参考：我在 core/message.rs 中的实现
|
||||
- 预期效果：代码更简洁，维护更容易
|
||||
```
|
||||
|
||||
```
|
||||
[时间] 林晓峰(QA) → 开发团队 - 建议
|
||||
|
||||
建议内容：
|
||||
希望开发团队在提交代码前先自测一遍基本功能。
|
||||
- 当前问题：最近发现的 bug 大多是基本功能问题，本可以避免
|
||||
- 影响：QA 时间被占用，延误整体进度
|
||||
- 改进建议：提交前运行一遍手动测试，或者写简单的测试脚本
|
||||
- 预期效果：减少低级 bug，提高整体效率
|
||||
```
|
||||
|
||||
#### 建议处理流程
|
||||
```
|
||||
员工提出建议
|
||||
↓
|
||||
相关负责人评估
|
||||
↓
|
||||
管理层讨论（如涉及战略/流程）
|
||||
↓
|
||||
CEO 决策（如涉及重大变更）
|
||||
↓
|
||||
反馈结果和理由给提出者
|
||||
↓
|
||||
执行改进（如采纳）
|
||||
```
|
||||
|
||||
#### 建议评估标准
|
||||
- 是否有助于提高效率
|
||||
- 是否有助于提升质量
|
||||
- 是否有助于改善协作
|
||||
- 是否符合公司战略
|
||||
- 实施成本和收益
|
||||
|
||||
#### 接受建议的态度
|
||||
- ✅ 开放心态，认真倾听
|
||||
- ✅ 理性分析，不要情绪化
|
||||
- ✅ 感谢提建议的人
|
||||
- ✅ 即使不同意，也要解释原因
|
||||
- ✅ 采纳好的建议并执行
|
||||
|
||||
#### 鼓励建议的文化
|
||||
- 提出好建议会获得认可和奖励
|
||||
- 即使建议未被采纳，也会得到反馈和解释
|
||||
- 鼓励批判性思维和创新想法
|
||||
- 没有"不能说"的话题
|
||||
- 互相提建议是帮助彼此成长
|
||||
|
||||
### 沟通方式和记录要求
|
||||
|
||||
#### 1. 异步沟通（推荐）
|
||||
- **工具**: TEAM_CHAT.md
|
||||
- **适用**: 非紧急问题、技术讨论、需求澄清
|
||||
- **优点**: 自动记录、可追溯、可搜索
|
||||
- **要求**: 必须记录在 TEAM_CHAT.md
|
||||
|
||||
#### 2. 实时沟通（可选）
|
||||
- **工具**: kilo 命令、语音、视频会议
|
||||
- **适用**: 紧急问题、复杂讨论、头脑风暴
|
||||
- **要求**:
|
||||
- 沟通后必须在 TEAM_CHAT.md 记录要点
|
||||
- 重要决策必须记录
|
||||
- 技术方案必须记录
|
||||
|
||||
#### 3. 代码协作
|
||||
- **工具**: Git commit message、代码注释
|
||||
- **适用**: 代码实现、技术细节
|
||||
- **要求**:
|
||||
- Commit message 清晰说明改动原因
|
||||
- 复杂逻辑必须有注释
|
||||
- 重要决策记录在 TEAM_CHAT.md
|
||||
|
||||
#### 4. 文档协作
|
||||
- **工具**: Markdown 文档（PRD、技术设计文档等）
|
||||
- **适用**: 需求、设计、规范
|
||||
- **要求**:
|
||||
- 文档变更记录在 Git
|
||||
- 重大变更在 TEAM_CHAT.md 通知相关人员
|
||||
|
||||
### 记录规范
|
||||
|
||||
#### 必须记录的内容
|
||||
- ✅ 技术方案决策
|
||||
- ✅ 需求变更
|
||||
- ✅ 架构调整
|
||||
- ✅ 重要 bug 和解决方案
|
||||
- ✅ 跨团队协作结果
|
||||
- ✅ 经验教训和最佳实践
|
||||
|
||||
#### 可以不记录的内容
|
||||
- ❌ 日常问候
|
||||
- ❌ 简单的代码语法问题（已在代码中解决）
|
||||
- ❌ 已在文档中说明的内容
|
||||
|
||||
#### 记录格式
|
||||
```
|
||||
[时间] 发送者 → 接收者: 内容
|
||||
|
||||
示例：
|
||||
[14:30] 李思琪 → 王浩然:
|
||||
视频流传输性能问题已解决，采用零拷贝方案。
|
||||
参考代码：src/plugins/video/processor.rs:456
|
||||
性能提升：从 30fps 提升到 60fps
|
||||
```
|
||||
|
||||
### 末位淘汰制度
|
||||
- 每完成一个阶段（Phase），CEO 评估所有成员绩效
|
||||
- **绩效评分维度**:
|
||||
- 代码质量 (0-10): 是否编译通过、逻辑正确、风格一致
|
||||
- 任务完成度 (0-10): 是否完整实现需求、有无遗漏
|
||||
- 效率 (0-10): 完成速度、是否需要返工
|
||||
- 协作 (0-10): 代码是否易于集成、注释是否清晰
|
||||
- **末位淘汰**: 总分最低的成员被淘汰，由新成员替换
|
||||
- **淘汰后**: 灵魂文件被归档到 `souls/archived/`
|
||||
|
||||
### 灵魂保存机制
|
||||
表现优秀的成员可以将以下信息保存到 `souls/<name>.md`：
|
||||
- **思想**: 对项目架构的理解、技术洞察
|
||||
- **性格**: 编码风格偏好、沟通方式
|
||||
- **记忆**: 踩过的坑、关键决策的原因、与其他成员的协作经验
|
||||
- **技能树**: 在项目中积累的特定技术能力
|
||||
|
||||
灵魂文件的作用：
|
||||
- 下次启用该成员时，将灵魂文件作为 prompt 上下文注入
|
||||
- 成员可以"记住"之前的工作经验，避免重复犯错
|
||||
- 即使 session 断开，成员的核心认知得以延续
|
||||
|
||||
**解锁条件**: 首次任务评分 ≥ 7/10 即可解锁灵魂文件写入权限
|
||||
|
||||
### 通信机制
|
||||
- **任务下发**: CEO → `kilo run -m openai/gpt-5.4 --auto --dir <dir>` (带详细上下文)
|
||||
- **产出回收**: kilo 输出 → CEO 读取文件 → 审核 → git commit
|
||||
- **团队会议**: 重大决策记录到 PROGRESS.md
|
||||
- **灵魂文件**: `souls/<name>.md` 持久化成员状态
|
||||
|
||||
---
|
||||
|
||||
## 绩效记录
|
||||
|
||||
### Phase 1: 骨架 → 功能迁移
|
||||
|
||||
| 成员 | 任务 | 质量 | 完成度 | 效率 | 协作 | 总分 | 状态 |
|
||||
|------|------|------|--------|------|------|------|------|
|
||||
| 张明远 | config.rs 验证 | - | - | - | - | - | 🔄进行中 |
|
||||
| 李思琪 | state_machine.rs | - | - | - | - | - | 🔄进行中 |
|
||||
| 王浩然 | wifi/mod.rs | - | - | - | - | - | 🔄进行中 |
|
||||
| 赵雨薇 | screen/mod.rs | - | - | - | - | - | 🔄进行中 |
|
||||
390
docs/TESTING.md
Normal file
390
docs/TESTING.md
Normal file
@@ -0,0 +1,390 @@
|
||||
# ShowenV2 测试指南
|
||||
|
||||
## 测试环境
|
||||
|
||||
### 目标运行环境
|
||||
- **操作系统**: Debian 11 (bullseye)
|
||||
- **架构**: ARM64 (aarch64)
|
||||
- **桌面环境**: KDE Plasma
|
||||
- **设备类型**: 嵌入式设备（Radxa、树莓派等）
|
||||
|
||||
### 硬件要求
|
||||
- **CPU**: ARM Cortex-A 系列
|
||||
- **内存**: ≥ 2GB
|
||||
- **存储**: ≥ 8GB
|
||||
- **显示**: 支持 HDMI 输出
|
||||
- **网络**: WiFi + 蓝牙
|
||||
|
||||
### 软件环境
|
||||
- Rust toolchain: stable-aarch64-unknown-linux-gnu
|
||||
- OpenCV 库（ARM64 版本）
|
||||
- D-Bus（用于 BLE）
|
||||
- NetworkManager（用于 WiFi）
|
||||
- KDE Plasma 桌面环境
|
||||
|
||||
### 环境验证
|
||||
```bash
|
||||
# 检查系统信息
|
||||
uname -a # 应显示 aarch64
|
||||
cat /etc/os-release # 应显示 Debian 11
|
||||
|
||||
# 检查桌面环境
|
||||
echo $XDG_CURRENT_DESKTOP # 应显示 KDE
|
||||
|
||||
# 检查 Rust 环境
|
||||
rustc --version # 应显示 stable-aarch64
|
||||
|
||||
# 检查依赖库
|
||||
pkg-config --modversion opencv4 # OpenCV 版本
|
||||
systemctl status dbus # D-Bus 状态
|
||||
nmcli --version # NetworkManager 版本
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试类型
|
||||
|
||||
### 1. 编译测试
|
||||
```bash
|
||||
# 检查编译
|
||||
cargo check
|
||||
|
||||
# 代码质量检查
|
||||
cargo clippy
|
||||
|
||||
# 运行单元测试
|
||||
cargo test
|
||||
```
|
||||
|
||||
### 2. 功能测试
|
||||
|
||||
#### 配置文件测试
|
||||
```bash
|
||||
# 复制测试配置
|
||||
cp /home/showen/Showen/hologram_player_rust/dog_state_machine.json configs/
|
||||
cp /home/showen/Showen/hologram_player_rust/cat_state_machine.json configs/
|
||||
|
||||
# 验证配置加载
|
||||
cargo run --release -- --config configs/dog_state_machine.json --validate
|
||||
```
|
||||
|
||||
#### 视频播放测试
|
||||
```bash
|
||||
# 启动程序
|
||||
cargo run --release -- --config configs/dog_state_machine.json
|
||||
|
||||
# 测试点：
|
||||
# - 视频是否正常播放
|
||||
# - 帧率是否达到 60fps
|
||||
# - 状态机切换是否正常
|
||||
# - 触发器是否响应
|
||||
```
|
||||
|
||||
#### HTTP API 测试
|
||||
```bash
|
||||
# 启动程序后，在另一个终端测试 API
|
||||
|
||||
# 获取状态
|
||||
curl http://localhost:8080/api/status
|
||||
|
||||
# 播放控制
|
||||
curl -X POST http://localhost:8080/api/play
|
||||
curl -X POST http://localhost:8080/api/pause
|
||||
curl -X POST http://localhost:8080/api/next
|
||||
curl -X POST http://localhost:8080/api/previous
|
||||
|
||||
# 跳转到指定视频
|
||||
curl -X POST http://localhost:8080/api/goto/0
|
||||
|
||||
# 触发状态切换
|
||||
curl -X POST http://localhost:8080/api/trigger/happy
|
||||
|
||||
# 场景切换
|
||||
curl -X POST http://localhost:8080/api/scene/0
|
||||
|
||||
# 获取配置
|
||||
curl http://localhost:8080/api/config
|
||||
|
||||
# 访问 Web UI
|
||||
curl http://localhost:8080/
|
||||
```
|
||||
|
||||
#### BLE 测试
|
||||
```bash
|
||||
# 使用手机蓝牙扫描设备
|
||||
# 设备名应该显示为配置文件中的 device_name
|
||||
|
||||
# 连接后测试 GATT 服务
|
||||
# - WiFi 配置特征值
|
||||
# - 状态查询特征值
|
||||
# - 命令发送特征值
|
||||
```
|
||||
|
||||
#### WiFi 测试
|
||||
```bash
|
||||
# 通过 BLE 或 HTTP API 测试 WiFi 功能
|
||||
|
||||
# 扫描 WiFi
|
||||
curl -X POST http://localhost:8080/api/wifi/scan
|
||||
|
||||
# 连接 WiFi
|
||||
curl -X POST http://localhost:8080/api/wifi/connect \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"ssid": "YourSSID", "password": "YourPassword"}'
|
||||
|
||||
# 断开 WiFi
|
||||
curl -X POST http://localhost:8080/api/wifi/disconnect
|
||||
|
||||
# 开启热点
|
||||
curl -X POST http://localhost:8080/api/wifi/hotspot/start
|
||||
|
||||
# 关闭热点
|
||||
curl -X POST http://localhost:8080/api/wifi/hotspot/stop
|
||||
```
|
||||
|
||||
#### 屏幕管理测试
|
||||
```bash
|
||||
# 程序运行时应该：
|
||||
# - 阻止屏幕休眠
|
||||
# - 隐藏鼠标光标
|
||||
# - 全屏显示视频
|
||||
|
||||
# 程序停止时应该：
|
||||
# - 恢复屏幕休眠
|
||||
# - 显示鼠标光标
|
||||
```
|
||||
|
||||
### 3. 性能测试
|
||||
|
||||
#### 帧率测试
|
||||
```bash
|
||||
# 运行程序并观察日志
|
||||
cargo run --release -- --config configs/dog_state_machine.json
|
||||
|
||||
# 检查点：
|
||||
# - 视频渲染帧率 ≥ 60fps
|
||||
# - 无明显卡顿
|
||||
# - CPU 占用合理
|
||||
```
|
||||
|
||||
#### 内存测试
|
||||
```bash
|
||||
# 启动程序
|
||||
cargo run --release -- --config configs/dog_state_machine.json &
|
||||
PID=$!
|
||||
|
||||
# 监控内存占用
|
||||
watch -n 1 "ps aux | grep $PID | grep -v grep"
|
||||
|
||||
# 检查点：
|
||||
# - 内存占用 ≤ 旧版本 120%
|
||||
# - 无内存泄漏（长时间运行内存稳定）
|
||||
```
|
||||
|
||||
#### 启动时间测试
|
||||
```bash
|
||||
# 测量启动时间
|
||||
time cargo run --release -- --config configs/dog_state_machine.json
|
||||
|
||||
# 检查点：
|
||||
# - 启动时间 ≤ 3秒
|
||||
```
|
||||
|
||||
#### 稳定性测试
|
||||
```bash
|
||||
# 长时间运行测试（7x24小时）
|
||||
cargo run --release -- --config configs/dog_state_machine.json
|
||||
|
||||
# 检查点：
|
||||
# - 连续运行 7天无崩溃
|
||||
# - 内存占用稳定
|
||||
# - 无资源泄漏
|
||||
```
|
||||
|
||||
### 4. 集成测试
|
||||
|
||||
#### 插件通信测试
|
||||
- 测试 HTTP → Video 消息传递
|
||||
- 测试 BLE → WiFi 消息传递
|
||||
- 测试 Broadcast 消息到所有插件
|
||||
|
||||
#### 配置验证测试
|
||||
- 测试各种配置组合
|
||||
- 测试边界条件（空配置、超大值等）
|
||||
- 测试错误配置的处理
|
||||
|
||||
### 5. 对比测试
|
||||
|
||||
#### 功能对比
|
||||
```bash
|
||||
# 运行旧版本
|
||||
cd /home/showen/Showen/hologram_player_rust
|
||||
cargo run --release -- --config dog_state_machine.json
|
||||
|
||||
# 运行新版本
|
||||
cd /home/showen/Showen/ShowenV2
|
||||
cargo run --release -- --config configs/dog_state_machine.json
|
||||
|
||||
# 对比：
|
||||
# - 功能是否一致
|
||||
# - 性能是否相当
|
||||
# - 用户体验是否改善
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 截图和录屏
|
||||
|
||||
### 截图工具
|
||||
```bash
|
||||
# 安装截图工具
|
||||
sudo apt-get install scrot
|
||||
|
||||
# 截图
|
||||
scrot screenshot.png
|
||||
|
||||
# 延迟 5秒后截图
|
||||
scrot -d 5 screenshot.png
|
||||
|
||||
# 截取当前窗口
|
||||
scrot -u screenshot.png
|
||||
```
|
||||
|
||||
### 录屏工具
|
||||
```bash
|
||||
# 安装录屏工具
|
||||
sudo apt-get install ffmpeg
|
||||
|
||||
# 录制屏幕
|
||||
ffmpeg -f x11grab -s 1920x1080 -i :0.0 -r 30 output.mp4
|
||||
|
||||
# 录制 30秒后停止
|
||||
ffmpeg -f x11grab -s 1920x1080 -i :0.0 -r 30 -t 30 output.mp4
|
||||
```
|
||||
|
||||
### 性能监控截图
|
||||
```bash
|
||||
# 安装 htop
|
||||
sudo apt-get install htop
|
||||
|
||||
# 运行 htop 并截图
|
||||
htop &
|
||||
sleep 2
|
||||
scrot htop_screenshot.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试报告模板
|
||||
|
||||
### 测试报告结构
|
||||
```markdown
|
||||
# ShowenV2 测试报告
|
||||
|
||||
## 测试信息
|
||||
- 测试人员：[姓名]
|
||||
- 测试日期：[日期]
|
||||
- 测试版本：[commit hash]
|
||||
- 测试环境：[硬件/软件信息]
|
||||
|
||||
## 测试结果概览
|
||||
- 编译测试：✅/❌
|
||||
- 功能测试：✅/❌
|
||||
- 性能测试：✅/❌
|
||||
- 集成测试：✅/❌
|
||||
- 对比测试：✅/❌
|
||||
|
||||
## 详细测试结果
|
||||
|
||||
### 编译测试
|
||||
- cargo check: ✅
|
||||
- cargo clippy: ⚠️ 7个 warning
|
||||
- cargo test: ✅
|
||||
|
||||
### 功能测试
|
||||
#### 视频播放
|
||||
- 基本播放：✅
|
||||
- 状态切换：✅
|
||||
- 触发器：✅
|
||||
- 截图：[附件]
|
||||
|
||||
#### HTTP API
|
||||
- 状态查询：✅
|
||||
- 播放控制：✅
|
||||
- Web UI：✅
|
||||
- 截图：[附件]
|
||||
|
||||
#### BLE
|
||||
- 设备发现：✅
|
||||
- GATT 服务：✅
|
||||
- WiFi 配置：✅
|
||||
|
||||
#### WiFi
|
||||
- 扫描：✅
|
||||
- 连接：✅
|
||||
- 热点：✅
|
||||
|
||||
### 性能测试
|
||||
- 帧率：60fps ✅
|
||||
- 内存占用：150MB ✅
|
||||
- 启动时间：2.5秒 ✅
|
||||
- 稳定性：运行 24小时无问题 ✅
|
||||
|
||||
### 发现的问题
|
||||
1. [问题描述]
|
||||
- 严重程度：P0/P1/P2/P3
|
||||
- 复现步骤：[步骤]
|
||||
- 截图：[附件]
|
||||
- 建议：[修复建议]
|
||||
|
||||
## 质量评估
|
||||
- 整体质量：优秀/良好/一般/较差
|
||||
- 是否可以发布：是/否
|
||||
- 风险提示：[风险说明]
|
||||
|
||||
## 建议
|
||||
- [改进建议]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 测试检查清单
|
||||
|
||||
### 编译检查
|
||||
- [ ] cargo check 通过
|
||||
- [ ] cargo clippy 零 warning
|
||||
- [ ] cargo test 通过
|
||||
- [ ] cargo build --release 成功
|
||||
|
||||
### 功能检查
|
||||
- [ ] 配置文件加载正确
|
||||
- [ ] 视频播放正常
|
||||
- [ ] 状态机切换正确
|
||||
- [ ] HTTP API 全部可用
|
||||
- [ ] BLE 连接正常
|
||||
- [ ] WiFi 功能正常
|
||||
- [ ] 屏幕管理正常
|
||||
|
||||
### 性能检查
|
||||
- [ ] 帧率 ≥ 60fps
|
||||
- [ ] 内存占用合理
|
||||
- [ ] 启动时间 ≤ 3秒
|
||||
- [ ] 长时间运行稳定
|
||||
|
||||
### 质量检查
|
||||
- [ ] 无崩溃
|
||||
- [ ] 无内存泄漏
|
||||
- [ ] 无资源泄漏
|
||||
- [ ] 错误处理完善
|
||||
- [ ] 日志输出合理
|
||||
|
||||
### 对比检查
|
||||
- [ ] 功能对齐旧版本
|
||||
- [ ] 性能不低于旧版本
|
||||
- [ ] 用户体验改善
|
||||
|
||||
---
|
||||
|
||||
**文档版本**: v1.0
|
||||
**最后更新**: 2026-03-12
|
||||
**负责人**: 林晓峰 (QA 负责人)
|
||||
98
docs/WORKFLOW.md
Normal file
98
docs/WORKFLOW.md
Normal file
@@ -0,0 +1,98 @@
|
||||
# ShowenV2 开发流程规范
|
||||
|
||||
## 核心原则
|
||||
**方案先行，记录完整，审核通过才执行。**
|
||||
|
||||
---
|
||||
|
||||
## 标准工作流程
|
||||
|
||||
### 1. 方案阶段
|
||||
- CEO 在 PROGRESS.md 或 TEAM_CHAT.md 中写明任务方案
|
||||
- 方案内容: 目标、涉及文件、技术方案、验收标准
|
||||
- git commit 方案文档
|
||||
|
||||
### 2. 派发阶段
|
||||
- CEO 通过 `kilo run -m openai/gpt-5.4 --auto --dir <dir>` 派发，消息中指示读取灵魂文件和 TEAM_CHAT.md
|
||||
- 任务描述中包含: 角色身份、具体要求、上下文文件列表、验收标准
|
||||
- 更新 PROGRESS.md 记录谁在做什么
|
||||
|
||||
### 3. 审核阶段
|
||||
- 成员交付后 CEO 检查:
|
||||
- [ ] cargo check 零 warning？
|
||||
- [ ] 逻辑与旧代码行为一致？
|
||||
- [ ] 代码风格一致？
|
||||
- [ ] 没有安全问题？
|
||||
- 合格: git commit + 绩效记录 + 灵魂文件更新
|
||||
- 不合格: 在 TEAM_CHAT.md 记录问题，重新派发（同人或换人）
|
||||
|
||||
### 4. 记录阶段
|
||||
- 每次 git commit 前更新 PROGRESS.md
|
||||
- 重大决策写入"关键决策记录"
|
||||
- 成员经验写入 souls/<name>.md
|
||||
- 沟通记录写入 TEAM_CHAT.md
|
||||
|
||||
---
|
||||
|
||||
## 文件职责
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| PROGRESS.md | 项目进度、完成状态、待办事项 |
|
||||
| TEAM.md | 团队成员档案、制度、绩效 |
|
||||
| TEAM_CHAT.md | 团队异步沟通、任务讨论、问题记录 |
|
||||
| souls/<name>.md | 成员灵魂：思想/性格/记忆/技能 |
|
||||
| WORKFLOW.md | 本文件，开发流程规范 |
|
||||
|
||||
---
|
||||
|
||||
## CEO 操作模板
|
||||
|
||||
### 派发任务
|
||||
```bash
|
||||
# 正确方式：把所有内容放在消息字符串里，让 kilo 自己读文件
|
||||
kilo run -m openai/gpt-5.4 --auto \
|
||||
--dir /home/showen/Showen/ShowenV2 \
|
||||
"你是<角色名>。先读取 souls/<name>.md 和 TEAM_CHAT.md。任务：<具体说明>。完成后 cargo check 确认通过。"
|
||||
```
|
||||
|
||||
### 审核提交
|
||||
```bash
|
||||
# 1. 检查改动
|
||||
git diff --stat
|
||||
# 2. 验证编译
|
||||
export PATH="/home/showen/.rustup/toolchains/stable-aarch64-unknown-linux-gnu/bin:$PATH"
|
||||
cargo check
|
||||
# 3. 审核代码（CEO 读文件）
|
||||
# 4. 提交
|
||||
git add <files> && git commit -m "<msg>"
|
||||
# 5. 更新进度
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 当前第二轮任务方案
|
||||
|
||||
### 任务 A: ServiceManager Broadcast (张明远)
|
||||
- **目标**: Message 实现 Clone，Broadcast 真正转发给所有插件
|
||||
- **文件**: core/message.rs, core/service_manager.rs
|
||||
- **方案**: derive(Clone) for Message + 所有子类型; Broadcast 遍历 plugins 调 handle_message(msg.clone())
|
||||
- **验收**: cargo check 通过, Broadcast 消息能到达所有插件
|
||||
|
||||
### 任务 B: VideoProcessor (李思琪)
|
||||
- **目标**: 完整迁移旧 video_processor.rs 的 VideoTransformer + VideoProcessor
|
||||
- **文件**: plugins/video/processor.rs, plugins/video/mod.rs
|
||||
- **方案**: 三大类 VideoTransformer(帧变换) + TransitionEffect(过渡) + VideoProcessor(主循环+状态机)
|
||||
- **验收**: cargo check 通过, API 方法完整 (play/pause/next/trigger/status)
|
||||
|
||||
### 任务 C: HttpPlugin (赵雨薇)
|
||||
- **目标**: 完整 HTTP API + Web UI
|
||||
- **文件**: plugins/http/mod.rs, plugins/http/routes.rs
|
||||
- **方案**: warp 路由, std::thread 跑 tokio runtime, 通过 Envelope 与其他插件通信
|
||||
- **验收**: cargo check 通过, 路由覆盖旧 api_server.rs 所有 endpoint
|
||||
|
||||
### 任务 D: BlePlugin (王浩然)
|
||||
- **目标**: BLE GATT 配网 + LocalName 双连接修复
|
||||
- **文件**: plugins/ble/mod.rs, plugins/ble/gatt.rs
|
||||
- **方案**: 双 D-Bus 连接 (conn_server 回调线程 + conn_client 同步注册)
|
||||
- **验收**: cargo check 通过, GATT 结构完整, 双连接架构正确
|
||||
Reference in New Issue
Block a user