REQUIREMENTS.md
REQUIREMENTS.md
Claude Code 通知系统需求文档
项目背景
在远程机器上使用 Claude Code 工作时,需要一个通知系统来及时告知本地机器任务状态(如需要用户回答问题、任务完成等)。
核心理念
极简化架构 - 相比原方案(SSH/SFTP + 文件监听 + 状态管理),新方案采用 HTTP 接口 + Prompt Hooks 的方式,大幅简化实现。
架构设计
Master 端(本地机器)
职责: 接收通知请求并发送系统通知
实现方式:
- Fastify HTTP 服务
- 监听地址:
http://localhost:8079 - 不关心通知内容的业务逻辑,只负责展示
核心接口:
POST /notify- 接收通知请求,发送 macOS 系统通知GET /health- 健康检查(可选)
Agent 端(远程机器)
职责: 在特定事件发生时触发通知
实现方式:
- 零代码 - 不需要编写 Agent 程序
- 使用 Claude Code 的 Prompt Hooks 机制
- 让 AI 自己根据 prompt 指令调用 HTTP 接口
工作原理:
- Claude Code 触发 hook(如
AskUserQuestion) - Prompt hook 告诉 AI 需要调用通知接口
- AI 从上下文中提取项目信息(工作目录等)
- AI 构造 HTTP 请求并调用 Master 接口
通知触发场景
1. 用户提问(AskUserQuestion)
- 触发时机: Claude 需要向用户提问时
- 通知类型:
question - 消息示例: "有问题需要回答"
2. 其他场景(待讨论)
- 任务完成(长时间任务)
- 错误发生
- 特定工具调用(git push、部署等)
接口格式设计
请求格式
{
"title": "项目名称",
"message": "通知消息内容",
"type": "question | success | error | info | stop",
"cwd": "项目目录名(可选)",
"subtitle": "副标题(可选,覆盖配置)",
"sound": "声音名称(可选,覆盖类型默认)",
"timeout": 5,
"wait": false
}
字段说明
必需字段
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| title | string | 通知标题 | "claude-hook-notify" |
| message | string | 通知消息内容 | "有问题需要回答" |
| type | string | 通知类型 | "question" / "success" / "error" / "info" / "stop" |
可选字段(覆盖配置默认值)
| 字段 | 类型 | 说明 | 示例 |
|---|---|---|---|
| cwd | string | 当前工作目录名(用作 subtitle 后备) | "claude-hook-notify" |
| subtitle | string | 副标题(覆盖配置) | "重要通知" |
| sound | string | 声音名称(覆盖类型默认) | "Ping" / "Basso" / "Glass" |
| icon | string | 图标路径(覆盖配置) | "/path/to/icon.png" |
| contentImage | string | 内容图片路径(覆盖配置) | "/path/to/image.png" |
| timeout | number | 通知超时时间(秒) | 5 |
| wait | boolean | 是否等待用户交互 | false |
| open | string | 点击时打开的 URL | "https://example.com" |
| actions | array | 操作按钮列表 | ["查看", "忽略"] |
| reply | boolean | 是否允许用户回复 | true |
响应格式
{
"success": true,
"message": "通知已发送"
}
Prompt 设计
核心要求
Prompt 需要让 AI 能够:
- 理解需要调用 HTTP 接口
- 从上下文中提取项目信息(工作目录)
- 构造符合格式的 JSON 请求
- 发送 POST 请求到 Master 服务
Prompt 示例(AskUserQuestion)
立即调用 HTTP 接口通知用户有问题需要回答。
接口信息:
- URL: http://localhost:8079/notify
- 方法: POST
- Content-Type: application/json
请求体格式参考: ~/.claude/hooks/notify/example.json
重要:你需要从当前工作目录中提取项目信息:
- cwd: 当前工作目录的最后一级目录名
- title: 项目名称
- message: 描述具体问题
- type: 设置为 'question'
部署方案
Master 部署(本地机器)
方式一:系统服务(推荐)
- 使用 macOS LaunchAgent
- 开机自启动
- 后台运行
方式二:手动启动
- 需要时运行
npm start - 适合临时使用
Agent 部署(远程机器)
安装步骤:
- 运行安装脚本
agent-install.sh - 脚本自动创建
~/.claude/hooks/notify/example.json - 脚本输出 hooks 配置
- 手动将配置添加到
~/.claude/settings.json
待讨论问题
1. 通知场景
- 除了 AskUserQuestion,还需要哪些场景?
- 如何判断"长时间任务"(需要通知任务完成)?
2. 接口格式
- 当前字段是否足够?
- 是否需要时间戳、优先级、声音等字段?
3. 安全性
- 是否需要鉴权(Token/IP 白名单)?
- 内网使用是否可以不鉴权?
4. Master 功能
- 是否需要通知历史记录?
- 是否需要日志功能?
- 是否需要配置文件(通知声音、样式等)?
5. 项目结构
- 是否需要 monorepo 结构?
- 还是简化为单个 Master 服务 + 安装脚本?
技术栈
Master
- 框架: Fastify
- 通知: node-notifier (跨平台)
- 语言: TypeScript / Node.js
Agent
- 实现: Bash 安装脚本
- 配置: JSON (Claude Code hooks)
下一步
- 确认需求和待讨论问题
- 设计最终的接口格式
- 实现 Master HTTP 服务
- 完善 Agent 安装脚本
- 测试完整流程