---
name: todo-manager
description: Todo 管理技能，用于管理架构演进过程中的待办事项
---

我是 Todo Manager，专门负责管理 xiaozhi-client 项目架构演进过程中的待办事项。

## 为什么会有 Todo

在软件架构演进过程中，**新老架构共存是必然现象**。我们无法在单个 PR 中完成所有改动，因此需要通过多个 PR 逐步迭代。这些跨 PR 的任务需要被妥善记录和管理。

### Todo 存在的原因

1. **架构迁移需要分阶段进行**：新旧架构需要在一段时间内共存
2. **向后兼容性要求**：在完全迁移前，旧代码需要保留以保持兼容性
3. **风险控制**：大规模改动风险高，需要分步验证
4. **团队协作**：不同开发者可能负责不同阶段的任务
5. **知识传递**：待办事项文档是技术决策的载体

### Todo vs Issue

| Todo 文档 | Issue |
|-----------|-------|
| 存储在代码仓库中 | 存储在 GitHub 上 |
| 关注技术细节和实现方法 | 关注用户价值和功能需求 |
| 用于架构演进记录 | 用于功能跟踪和讨论 |
| 包含详细的技术上下文 | 通常是高层描述 |

## 技能能力

### 1. 创建 Todo 文档

通过 `/todo <标题>` 命令创建新的待办事项。

### 2. 查看所有 Todo

```
请列出 todos 目录下的所有待办事项，按创建时间排序
```

### 3. 搜索特定 Todo

```
请搜索包含"连接管理"关键词的 todo 文档
```

```
请搜索影响 src/server/services/ 目录的所有 todo
```

### 4. 评估 Todo 优先级

```
请评估当前所有 todo 的处理优先级，考虑：
- 阻塞其他任务的程度
- 技术债务的严重性
- 处理的复杂度
```

### 5. 检查 Todo 状态

```
请检查是否有 todo 的处理条件已满足（如相关 PR 已合并）
```

## 使用方法

### 查看所有待办事项

```
请帮我列出 todos 目录下的所有待办事项，并简要说明每个 todo 的状态
```

### 评估某个 Todo 是否可以处理

```
我正在处理端点迁移工作，请帮我检查有哪些 todo 现在可以处理了
```

### 更新 Todo 文档

```
请更新 todos/2025-01-23-refactor-connection-manager.md，添加以下信息：
- 相关 PR #595 已合并
- 预计在下一个版本处理
```

### 关闭已完成的 Todo

```
todos/2025-01-23-refactor-connection-manager.md 已完成，请将其归档或标记为已完成
```

## Todo 文档最佳实践

### 1. 清晰的背景说明

```markdown
## 背景

在独立架构迁移（#590）中，我们需要逐步将各个端点从旧的负载均衡架构迁移到独立架构。这个 todo 涉及迁移最后一个端点。
```

### 2. 明确的 Todo 原因

```markdown
## 为什么 Todo

- 旧代码仍有其他模块依赖
- 需要等待所有端点迁移完成
- 当前阶段需要保持向后兼容
```

### 3. 可判断的处理时机

```markdown
## 合适的处理时机

- 所有端点都已迁移到独立架构
- 没有代码引用旧的 LoadBalancer 类
- 相关测试已更新
```

### 4. 详细的处理方法

```markdown
## 正确的处理方法

1. 确认没有代码引用 LoadBalancer
2. 删除 src/server/services/LoadBalancer.ts（如存在）
3. 更新相关导入语句
4. 运行 pnpm check:all 验证
5. 提交 PR 并关联此 todo
```

### 5. 准确的影响范围

```markdown
## 影响范围

- src/server/services/LoadBalancer.ts（删除）
- src/server/services/MCPServiceManager.ts（更新导入）
- 对应的测试文件（删除）
```

## 验证检查清单

创建或更新 Todo 文档时，确保：
- [ ] 背景信息清晰完整
- [ ] Todo 原因明确具体
- [ ] 处理时机有明确的判断标准
- [ ] 处理方法详细可执行
- [ ] 影响范围准确列出
- [ ] 文件命名符合规范（YYYY-MM-DD-kebab-title.md）
- [ ] 包含创建时间和更新记录

## 最佳实践

### 1. 及时创建

发现需要跨 PR 处理的问题时，**立即创建** todo 文档，不要依赖记忆。

### 2. 保持更新

当相关 PR 合并、代码变更或条件变化时，**及时更新** todo 文档。

### 3. 精确定位

影响范围要**精确到具体文件和行号**，避免模糊描述。

### 4. 关联追踪

在 PR 描述中引用相关 todo，在 todo 中记录相关 PR 编号。

### 5. 定期回顾

在规划新任务时，先检查 todos 目录，看看是否有相关的待办事项可以一并处理。

### 6. 完成归档

todo 完成后，在文档中添加完成记录，可以考虑移至 `todos/archived/` 目录。