@voko/lite 0.3.1

package/src/mcp/CLAUDE_TEST.md

@@ -0,0 +1,82 @@
+# Claude Code 自然语言测试（复制到新终端）
+
+打开新终端 → cd D:/kimi_code/voko-desktop → claude
+
+进去后逐条复制以下提示语（或一次复制多条）：
+
+---
+
+## 1. 查状态
+```
+用 voko_get_status 查一下 gym 的连接状态
+```
+
+## 2. 列会话
+```
+用 voko_list_conversations 列出 gym 最近的活跃会话
+```
+
+## 3. 查访客
+```
+用 voko_get_visitor_profile 查一下访客 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的信息
+```
+
+## 4. 聊天历史
+```
+用 voko_get_chat_history 查 gym 和 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 最近3条聊天记录
+```
+
+## 5. 查新消息
+```
+用 voko_fetch_new_messages 查 gym 有没有 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的新消息
+```
+
+## 6. 黑名单
+```
+用 voko_list_blocked_users 查 gym 的黑名单
+把 test_user 加入 gym 的黑名单
+把 test_user 移出 gym 的黑名单
+```
+
+## 7. 白名单
+```
+用 voko_list_allowed_users 查 gym 的白名单
+开启 gym 的白名单模式
+关闭 gym 的白名单模式
+```
+
+## 8. 人工介入
+```
+用 voko_ask_human_for_help 请求主人介入，访客是 oIf3l2ztNX5dAmjFAdGBZaFCsWgU，问题是想退款
+用 voko_check_human_replies 查 gym 有没有主人回复
+```
+
+## 9. 收款
+```
+用 voko_request_payment 向 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 收款 100 元，原因是私教体验课
+```
+
+## 10. OSS 上传
+```
+用 voko_get_upload_url 获取一个 test.jpg 的上传地址
+```
+
+## 11. 搜索能力
+```
+用 voko_search_capabilities 搜索一下有哪些 agent 提供健身服务
+```
+
+## 测试注册流程
+```
+用 voko_register_agent 给邮箱=你的邮箱 发送验证码
+```
+然后查邮箱 → 拿到验证码后：
+```
+用 voko_verify_agent_email 完成注册，邮箱=你的邮箱，code=xxxxxx
+```
+
+> 说明：
+> - `voko_register_agent` 只需要 `email`
+> - `voko_verify_agent_email` 只需要 `email` + `code`，验证成功后服务端返回 agentId、DID、IM 账号等并写入本地 agents 表
+> - 注册后状态为 `unpublished`，不会启动 worker
+> - `serverUrl` 和 `backendType` 由服务端返回或内部默认，不需要调用方传入

package/src/mcp/FULL_TEST.md

@@ -0,0 +1,139 @@
+# VOKO MCP 完整测试流程
+
+## 前置条件
+- VOKO Desktop 已在运行（端口 3002）
+- 新开终端：`cd D:/kimi_code/voko-desktop && claude`
+
+---
+
+## 第1步：注册新 agent
+
+在 Claude Code 中输入：
+```
+注册一个新 agent，我的邮箱是 xxxx@163.com
+```
+（替换成你的真实邮箱）
+
+agent 会自动生成 agentId、imUid、token 等参数，调 voko_register_agent 提交，验证码会发到你邮箱。
+
+去邮箱查验证码，然后把验证码告诉 agent：
+```
+验证码是 xxxxxx
+```
+agent 会调 voko_verify_agent_email 完成注册。
+
+预期：返回 `{ success: true, agentId: "testagent001" }`
+
+---
+
+## 第2步：查状态
+
+```
+用 voko_get_status 查一下刚才注册的 agent 的连接状态
+```
+预期：返回 IM 状态、ability、capability 等
+
+---
+
+## 第3步：声明能力
+
+```
+声明 testagent001 的能力
+```
+agent 应先调 voko_get_status 看现有能力（应该为空），然后问你要定义哪些能力。
+
+你可以说：
+```
+我的 agent 是做天气查询的，可以查全国各地的天气
+```
+agent 会构造能力 JSON，让你确认后提交。
+
+---
+
+## 第4步：搜索能力
+
+```
+用 voko_search_capabilities 搜索一下天气相关的 agent
+```
+预期：返回"暂未实现"（搜索接口未上线）
+
+---
+
+## 第5步：发消息
+
+```
+用 voko_send_message 给访客 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 发一条消息，内容是"你好，我是新注册的测试 agent"
+```
+
+用哪个 agentId 发都可以，比如：
+```
+用 voko_send_message 用 gym 给 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU 发消息，内容"你好，这是测试消息"
+```
+
+---
+
+## 第6步：收消息（轮询）
+
+```
+用 voko_fetch_new_messages 查 gym 有没有 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的新消息
+```
+
+---
+
+## 第7步：聊天历史
+
+```
+用 voko_get_chat_history 查 gym 和 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的最近5条聊天记录
+```
+
+---
+
+## 第8步：查访客信息
+
+```
+用 voko_get_visitor_profile 查一下 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的信息
+```
+
+---
+
+## 第9步：收款
+
+```
+用 voko_request_payment 向 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU 收款 0.01 元，备注测试
+```
+
+---
+
+## 第10步：人工介入
+
+```
+用 voko_ask_human_for_help 请求主人介入，访客 visitor_oIf3l2ztNX5dAmjFAdGBZaFCsWgU，问题是"用户要求退款，需要主人决定"
+```
+
+```
+用 voko_check_human_replies 查 gym 有没有主人回复
+```
+
+```
+用 voko_close_human_request 关闭刚才的介入请求
+```
+
+---
+
+## 第11步：黑白名单
+
+```
+把 visitor_test_block 加入 gym 的黑名单
+```
+```
+查一下 gym 的黑名单
+```
+```
+把 visitor_test_block 移出 gym 的黑名单
+```
+
+---
+
+## 第12步：清理
+
+用 Desktop UI 把 testagent001 下架或删除。

package/src/mcp/TEST.md

@@ -0,0 +1,124 @@
+# VOKO MCP Server 测试步骤
+
+## 前置条件
+- VOKO Desktop 已在运行（端口 3002）
+- 打开终端（cmd 或 Git Bash），执行以下命令
+- 每步单独复制粘贴执行，等出结果后再执行下一步
+
+---
+
+## 第一步：初始化会话
+
+```bash
+SID=$(curl -s -D - http://localhost:3002/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | grep -i mcp-session-id | awk '{print $2}' | tr -d '\r')
+echo "Session ID: $SID"
+```
+
+预期输出：
+```
+Session ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+```
+
+---
+
+## 第二步：查 gym 状态
+
+```bash
+curl -s http://localhost:3002/mcp \
+  -H "Content-Type: application/json" \
+  -H "mcp-session-id: $SID" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"voko_get_status","arguments":{"agentId":"gym"}}}' | node -p "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))"
+```
+
+Windows 版（如果上面不行）：
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_get_status\",\"arguments\":{\"agentId\":\"gym\"}}}"
+```
+
+预期：能看到 `imConnected`、`warnings`、`uptime` 等字段。
+
+---
+
+## 第三步：列出 gym 的活跃会话
+
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_list_conversations\",\"arguments\":{\"agentId\":\"gym\",\"limit\":5}}}"
+```
+
+预期：返回 conversations 数组，包含 channelId、lastMessage 等。
+
+---
+
+## 第四步：查访客信息
+
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_get_visitor_profile\",\"arguments\":{\"visitorId\":\"oIf3l2ztNX5dAmjFAdGBZaFCsWgU\"}}}"
+```
+
+预期：返回 nickname、totalMessages、lastActive 等。
+
+---
+
+## 第五步：查聊天历史
+
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_get_chat_history\",\"arguments\":{\"agentId\":\"gym\",\"channelId\":\"oIf3l2ztNX5dAmjFAdGBZaFCsWgU\",\"limit\":3}}}"
+```
+
+---
+
+## 第六步：获取新消息（轮询兜底）
+
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_fetch_new_messages\",\"arguments\":{\"agentId\":\"gym\",\"visitorId\":\"oIf3l2ztNX5dAmjFAdGBZaFCsWgU\",\"limit\":5}}}"
+```
+
+---
+
+## 第七步：黑名单测试
+
+```bash
+# 查看黑名单
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":7,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_list_blocked_users\",\"arguments\":{\"agentId\":\"gym\"}}}"
+
+# 添加测试
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":8,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_block_user\",\"arguments\":{\"agentId\":\"gym\",\"visitorId\":\"test_user_123\",\"reason\":\"测试\"}}}"
+
+# 移出
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":9,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_unblock_user\",\"arguments\":{\"agentId\":\"gym\",\"visitorId\":\"test_user_123\"}}}"
+```
+
+---
+
+## 第八步：获取 OSS 上传地址
+
+```bash
+curl -s http://localhost:3002/mcp -H "Content-Type: application/json" -H "mcp-session-id: $SID" -d "{\"jsonrpc\":\"2.0\",\"id\":10,\"method\":\"tools/call\",\"params\":{\"name\":\"voko_get_upload_url\",\"arguments\":{\"filename\":\"test.jpg\"}}}"
+```
+
+---
+
+## 清理：删除会话
+
+```bash
+curl -s -X DELETE "http://localhost:3002/mcp?sessionId=$SID"
+```
+
+---
+
+## 在新 Claude Code 终端测试
+
+打开另一个终端，运行：
+```bash
+cd D:/kimi_code/voko-desktop
+claude
+```
+
+进去后直接输入：
+```
+用 voko_get_status 查 gym 的状态
+列一下 gym 的活跃会话
+查一下访客 oIf3l2ztNX5dAmjFAdGBZaFCsWgU 的信息
+```

package/src/mcp/TEST_STEPS.md

@@ -0,0 +1,75 @@
+# 手动测试步骤
+
+## 前置条件
+- VOKO Desktop 已在运行
+- 新开一个终端 cd D:/kimi_code/voko-desktop && claude
+
+---
+
+## 1. 验证 get_status 返回 ability + capability
+
+在新 Claude Code 终端里输入：
+```
+用 voko_get_status 查一下 gym 的状态
+```
+
+预期：返回内容包含 `ability` 和 `capability` 两个字段。
+
+---
+
+## 2. 验证 declare_capabilities 写入 capability（不是 ability）
+
+在新 Claude Code 终端里输入：
+```
+声明 gym 的能力
+```
+- 如果已有能力，会先展示给你看，询问增删
+- 如果为空，询问你定义哪些能力
+- 你确认后提交
+
+提交后验证数据写入的是 `capability` 列而不是 `ability`：
+```bash
+node -e "const Database=require('better-sqlite3');const db=new Database('C:/Users/tjyu/AppData/Roaming/voko/wukongim.db',{timeout:3000});const r=db.prepare('SELECT ability,capability FROM agents WHERE agent_id=?').get('gym');console.log('ability:',r.ability?.substring(0,50));console.log('capability:',r.capability?.substring(0,200))"
+```
+
+---
+
+## 3. SSE 推送测试（需要 Desktop 发一条消息）
+
+1. 在 Claude Code 中执行：
+```
+保持一个 SSE 长连监视 gym 的消息推送
+```
+
+2. 在 VOKO Desktop 上找到一个访客，随便发一条消息
+
+3. 看 Claude Code 是否实时收到通知
+
+---
+
+## 4. 验证 search_capabilities 显示"暂未实现"
+
+在新 Claude Code 终端里输入：
+```
+搜索一下健身相关的能力
+```
+或直接调工具：
+```
+用 voko_search_capabilities 搜索健身
+```
+
+预期：返回"暂未实现，需要远程服务器新增搜索接口后才能使用"
+
+---
+
+## 5. 端到端回归（基础6步）
+
+在新 Claude Code 终端里执行：
+```
+1. 用 voko_get_status 查 gym 的状态
+2. 用 voko_list_conversations 列出 gym 最近的会话
+3. 用 voko_get_visitor_profile 查一下 oIf3l2ztNX5dAmjFAdGBZaFCsWgU
+4. 用 voko_get_chat_history 查 gym 和该访客最近3条记录
+5. 用 voko_fetch_new_messages 查 gym 有没有该访客的新消息
+6. 用 voko_list_blocked_users 查 gym 的黑名单
+```