TESTING.md
TESTING.md
Claude Code 通知系统测试指南
测试环境准备
1. Master 端部署(本地机器)
npm install
npm run dev
验证服务启动:
curl http://localhost:8079/health
预期响应:
{
"status": "ok",
"timestamp": "2026-01-27T10:30:00.000Z"
}
2. Agent 端安装(远程机器)
# 复制安装脚本到远程机器
scp agent/install.sh user@remote:/tmp/
# SSH 到远程机器
ssh user@remote
# 运行安装脚本
bash /tmp/install.sh
安装过程中:
- 输入 Master 服务地址(或使用默认值)
- 等待健康检查完成
- 选择
y自动更新 settings.json
手动测试
测试 1: 健康检查
目的: 验证 Master 服务可达
curl http://localhost:8079/health
预期结果:
- HTTP 状态码: 200
- 返回 JSON 包含
status: "ok"
测试 2: 手动发送通知
目的: 验证通知功能正常工作
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{
"title": "测试项目",
"message": "这是一条测试通知",
"cwd": "project",
"type": "question"
}'
预期结果:
- HTTP 状态码: 200
- macOS 显示系统通知
- 通知标题: "测试项目"
- 通知内容: "这是一条测试通知"
- 通知声音: Ping
测试 3: 测试不同通知类型
目的: 验证不同类型的通知使用不同的声音
# 错误通知 (Basso 声音)
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"错误测试","message":"发生错误","project":"/test","cwd":"test","type":"error"}'
# 成功通知 (default 声音)
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"成功测试","message":"操作成功","project":"/test","cwd":"test","type":"success"}'
# 信息通知 (default 声音)
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"信息测试","message":"普通信息","project":"/test","cwd":"test","type":"info"}'
预期结果:
- 每个请求都返回 200
- 错误通知使用 Basso 声音
- 其他通知使用默认声音
集成测试
测试 4: Claude Code 集成测试
目的: 验证 Claude Code 触发 AskUserQuestion 时自动发送通知
步骤:
- 在远程机器上进入任意项目目录:
cd ~/my-project
claude
- 向 Claude 提出一个需要提问的任务:
请帮我重构这个函数,但先问我想用什么设计模式
- 观察本地机器是否收到通知
预期结果:
- Claude 调用 AskUserQuestion 之前发送通知
- 本地机器显示系统通知
- 通知标题为项目名称 (如 "my-project")
- 通知消息描述了问题内容
- Master 服务日志显示收到请求
故障排查
问题 1: 无法连接到 Master 服务
症状: agent-install.sh 健康检查失败
排查步骤:
- 检查 Master 服务是否运行:
# 在本地机器上
curl http://localhost:8079/health
- 检查防火墙设置:
# macOS 检查防火墙
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
- 检查 Tailscale 连接:
# 在远程机器上
ping localhost
解决方案:
- 确保 Master 服务已启动 (
npm run dev) - 确保 Tailscale 连接正常
- 检查 IP 地址是否正确
问题 2: Claude 没有发送通知
症状: 使用 Claude Code 时,AskUserQuestion 触发但没有收到通知
排查步骤:
- 检查 hooks 配置是否正确:
# 在远程机器上
cat ~/.claude/settings.json | grep -A 10 "AskUserQuestion"
- 检查 Claude Code 是否加载了 hooks:
# 查看 Claude Code 启动日志
# 应该看到 "Loading hooks..." 相关信息
- 手动测试通知接口:
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"test","message":"test","project":"/test","cwd":"test","type":"question"}'
解决方案:
- 重新运行
agent-install.sh并选择自动更新配置 - 检查 settings.json 格式是否正确(有效的 JSON)
- 重启 Claude Code 会话
问题 3: macOS 不显示通知
症状: Master 服务收到请求但系统不显示通知
排查步骤:
- 检查 macOS 通知权限:
系统设置 -> 通知 -> Node
确保允许通知
- 测试 node-notifier 是否正常:
# 发送测试通知
curl -X POST http://127.0.0.1:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"测试","message":"测试消息","project":"/test","cwd":"test","type":"info"}'
- 检查 Master 服务日志:
# 查看是否有通知发送错误
解决方案:
- 启用 Node 的通知权限
- 检查"勿扰模式"是否开启
- 重启 Master 服务
- 确保 node-notifier 已正确安装:
npm install
问题 4: settings.json 自动更新失败
症状: agent-install.sh 报告更新失败
排查步骤:
- 检查 Python 是否安装:
python3 --version
- 手动验证 JSON 格式:
cat ~/.claude/settings.json | python3 -m json.tool
- 检查文件权限:
ls -la ~/.claude/settings.json
解决方案:
- 安装 Python 3
- 修复 settings.json 的 JSON 格式错误
- 调整文件权限:
chmod 644 ~/.claude/settings.json - 使用手动配置方式
性能测试
测试 5: 通知延迟测试
目的: 验证通知的响应时间
time curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d '{"title":"延迟测试","message":"测试消息","project":"/test","cwd":"test","type":"info"}'
预期结果:
- 请求响应时间 < 100ms
- 通知显示延迟 < 500ms
测试 6: 并发通知测试
目的: 验证系统处理多个并发通知的能力
for i in {1..5}; do
curl -X POST http://localhost:8079/notify \
-H "Content-Type: application/json" \
-d "{\"title\":\"并发测试 $i\",\"message\":\"消息 $i\",\"project\":\"/test\",\"cwd\":\"test\",\"type\":\"info\"}" &
done
wait
预期结果:
- 所有请求都成功返回 200
- 所有通知都正常显示
- 无请求丢失或错误
验收标准
系统通过验收需要满足以下所有条件:
功能性
- ✓ Master 服务能够正常启动并监听指定端口
- ✓
/health端点返回正确的健康状态 - ✓
/notify端点能够接收并处理通知请求 - ✓ macOS 系统通知能够正常显示
- ✓ 不同类型的通知使用不同的声音
集成性
- ✓ agent-install.sh 能够成功安装并配置 hooks
- ✓ 健康检查能够正确验证 Master 服务连接
- ✓ 自动配置功能能够正确更新 settings.json
- ✓ Claude Code 触发 AskUserQuestion 时自动发送通知
可靠性
- ✓ Master 服务即使通知失败也返回 200 (fire-and-forget)
- ✓ 配置更新失败时能够恢复备份
- ✓ 网络异常时有明确的错误提示
性能
- ✓ 通知请求响应时间 < 100ms
- ✓ 能够处理并发通知请求
- ✓ 系统资源占用合理
部署检查清单
Master 端(本地机器)
- Node.js 已安装(v18+)
- 依赖已安装(
npm install) - 服务能够启动(
npm run dev) - 健康检查通过(
curl http://localhost:8079/health) - macOS 通知权限已启用
- 防火墙配置正确
Agent 端(远程机器)
- Python 3 已安装
- curl 已安装
- Tailscale 连接正常
- agent-install.sh 执行成功
- ~/.claude/settings.json 配置正确
- 健康检查通过
验证步骤
- 手动测试通知接口
- 在远程机器上启动 Claude Code
- 触发 AskUserQuestion 场景
- 确认本地机器收到通知