# V2 Resource订阅版本测试指南
## V2 新增功能
### 1. Resource订阅机制
- **Resource URI**: `reminder://pending`
- **功能**: 暴露所有到期提醒作为可订阅资源
- **客户端可以**:
- 订阅此资源 (`resources/subscribe`)
- 定期读取资源获取提醒
- 追踪新增的到期提醒
### 2. 状态追踪
- **检测逻辑**: 每次读取资源时追踪新增的到期提醒
- **新增字段**: `has_new_reminders` 和 `new_count`
- **实现方式**: 简化设计，无需后台任务，依赖客户端读取触发
### 3. 向后兼容
- ✅ 保留所有8个原有工具
- ✅ V1的所有功能正常工作
- ✅ 可以无缝切换回V1（使用 `run_server.py`）
## V2实现说明
**重要变化**: V2版本采用简化实现，不使用后台任务。
- ✅ 更稳定可靠（兼容stdio传输模式）
- ✅ 客户端定期读取resource即可触发检查
- ✅ 自动追踪新增的到期提醒
- ⚠️ 需要客户端定期读取资源（建议每30-60秒）
## 启动V2服务
### 快速测试
```powershell
# Windows PowerShell
.\test_v2.ps1
```
或者
```cmd
# Windows CMD
test_v2.bat
```
### 正式启动
### Windows PowerShell
```powershell
.\start.ps1
```
### Windows CMD
```cmd
start.bat
```
### Linux/Mac
```bash
./start.sh
```
## 测试场景
### 场景1: 测试Resource读取
1. **添加一个即将到期的待办**:
```
对小智说: "小智，提醒我1分钟后测试通知功能"
```
2. **等待1分钟后，让小智读取Resource**:
- 如果小智支持resource读取，可以让它调用
- Resource会返回JSON格式的所有到期提醒
3. **预期返回**:
```json
{
"has_reminders": true,
"has_new_reminders": true,
"new_count": 1,
"total_count": 1,
"alarm_count": 0,
"todo_count": 1,
"alarms": [],
"todos": [
{
"id": "xxx",
"title": "测试通知功能",
"remind_time": "...",
"type": "todo"
}
],
"messages": [
"待办提醒: 测试通知功能"
]
}
```
### 场景2: 客户端定期读取（推荐实现方式）
**实现方式**: 客户端每30-60秒读取一次resource
1. **小智配置定期读取**:
```javascript
// 伪代码示例
setInterval(() => {
const resource = xiaozhi.readMCPResource('reminder://pending');
const data = JSON.parse(resource);
// 检查是否有新的到期提醒
if (data.has_new_reminders && data.new_count > 0) {
// 语音播报新提醒
data.messages.forEach(msg => {
xiaozhi.speak(msg);
});
}
}, 60000); // 每60秒检查一次
```
2. **添加提醒测试**:
```
对小智说: "小智，设置一个2分钟后的闹钟"
```
3. **等待客户端下次读取**:
- 客户端每60秒读取一次
- 检测到 `has_new_reminders: true`
- 自动播报提醒
### 场景3: 使用原有工具（降级方案）
如果小智不支持资源订阅，V2仍然可以正常工作：
1. **手动触发检查**:
```
对小智说: "小智，检查一下有没有到期的提醒"
```
2. **小智调用**: `check_all_reminders` 工具
3. **返回结果**: 与V1完全相同
## 关键日志检查
启动服务后，查看日志输出：
### 正常启动标志
```
INFO 启动MCP提醒服务（V2 - 支持Resource订阅）
INFO - Resource URI: reminder://pending
INFO - 客户端可通过resources/subscribe订阅
INFO - 或定期读取resource获取到期提醒
```
### Resource读取日志
当小智读取resource时：
```
INFO 资源读取 reminder://pending - 找到 N 个到期提醒（新增 M 个）
```
## 验证清单
- [ ] 服务正常启动，显示 "V2 - 支持Resource订阅"
- [ ] 可以正常添加闹钟和待办
- [ ] 所有8个原有工具正常工作
- [ ] Resource `reminder://pending` 可以被读取
- [ ] 读取resource时日志显示正确的提醒数量
- [ ] `has_new_reminders` 字段正确标识新提醒
## 切换回V1
如果需要切换回原版本（无通知功能）：
### 方法1: 修改启动脚本
编辑 `start.ps1` / `start.bat` / `start.sh`，将:
```
uv run python mcp_pipe.py run_server_v2.py
```
改为:
```
uv run python mcp_pipe.py run_server.py
```
### 方法2: 直接运行V1
```bash
# PowerShell
$env:MCP_ENDPOINT = "wss://..."
uv run python mcp_pipe.py run_server.py
# CMD
set MCP_ENDPOINT=wss://...
uv run python mcp_pipe.py run_server.py
# Bash
export MCP_ENDPOINT="wss://..."
uv run python mcp_pipe.py run_server.py
```
## 下一步测试建议
1. **配置客户端定期读取**:
- 建议每30-60秒读取一次resource
- 检查 `has_new_reminders` 字段
- 播报新提醒
2. **监控资源读取**:
- 观察日志中的资源读取记录
- 确认新增提醒被正确识别
3. **性能测试**:
- 添加多个到期提醒
- 观察资源读取性能
- 确认状态追踪准确性
4. **边界情况**:
- 测试同时到期多个提醒
- 测试提醒被关闭后不再通知
- 测试服务重启后状态恢复
## 常见问题
### Q1: V2和V1有什么区别？
**A**:
- **V2**: 提供Resource接口，客户端可定期读取，支持新增提醒检测
- **V1**: 仅提供工具接口，需要客户端主动调用工具
### Q2: 为什么没有后台主动推送？
**A**: 在stdio传输模式下，后台任务实现复杂且不稳定。V2采用简化设计，客户端定期读取resource触发检查，更可靠。
### Q3: 如何知道有新的到期提醒？
**A**: 读取resource时检查 `has_new_reminders` 和 `new_count` 字段。
### Q4: 建议多久读取一次resource？
**A**: 建议每30-60秒读取一次，既能及时提醒又不会造成过多请求。
## 技术细节
### Resource返回格式
```json
{
"has_reminders": boolean,
"has_new_reminders": boolean,
"new_count": number,
"total_count": number,
"alarm_count": number,
"todo_count": number,
"alarms": [...],
"todos": [...],
"messages": [...],
"checked_at": "ISO datetime"
}
```
### 新增提醒检测
```python
# 追踪上次读取时的到期提醒ID
_last_pending_ids = set()
# 每次读取时检测新增项
new_pending_ids = current_pending_ids - _last_pending_ids
has_new = len(new_pending_ids) > 0
```
### 客户端集成示例
```javascript
// 定期读取resource
async function checkReminders() {
const resource = await mcp.readResource('reminder://pending');
const data = JSON.parse(resource.text);
if (data.has_new_reminders) {
// 播报新提醒
for (const msg of data.messages) {
await speak(msg);
}
}
}
// 每60秒检查一次
setInterval(checkReminders, 60000);
```
## 联系和反馈
如果在测试过程中遇到问题：
1. 查看日志输出
2. 检查 `data/` 目录下的JSON文件
3. 尝试切换回V1验证基础功能
4. 记录错误信息以便排查
