Add device-bound robot notifications and automatic OAuth cards
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
# 客户端主动消息与授权卡片
|
||||
|
||||
2026-10-28:本地功能实现。ECS 现网与 Windows 客户端尚未部署本次更新,真实消息卡片尚待验收。
|
||||
|
||||
## 实现内容
|
||||
|
||||
- 新接口 `POST /device/notifications`:文本消息、固定通知卡片、固定 OAuth 授权卡片。
|
||||
- 新工具 `work_notification`:Agent 按用户要求向本人机器人私聊发文本/通知卡片。
|
||||
- WorkClient 首次发起本人授权时,自动请求 ECS 给本人发送授权卡片;一笔授权事务仅自动尝试一次。
|
||||
- 发卡失败时保留原授权 URL,用户仍可直接打开授权,不阻断现有授权流程。
|
||||
- 现有机器人下发任务及回复原消息链路保持不变。
|
||||
|
||||
## 身份与隔离
|
||||
|
||||
请求包含 `host_id`、`request_id`、`binding_owner`、`kind`、`text`、`title`、`oauth_state`、`proof`。
|
||||
|
||||
`proof` 由设备私钥签名,覆盖设备、purpose=`work-notify-v1`、90 秒有效时间、随机 nonce、全部业务字段的 SHA256。nonce 在 Redis 中一次性消费,防止原包重放。
|
||||
|
||||
`binding_owner` 是本机保存的绑定身份声明,不是收件人参数。ECS 要求它与数据库中当前绑定用户完全一致,然后只使用数据库 owner 作为平台 `receive_id`。接口拒绝额外的 `receive_id`、`owner`、`url`、原始卡片 JSON 等参数。没有绑定、已解绑、吊销、过期或被篡改的请求拒绝处理。
|
||||
|
||||
应用凭据获取完成后,发请求前再次核对绑定。飞书发消息是外部操作,无法与数据库解绑做跨系统原子事务;已提交或已送达的消息不能因随后解绑而撤回。本功能不声称可以撤回在途消息。
|
||||
|
||||
授权卡片只引用 ECS 内存中“当前设备 + 当前用户”发起、尚未完成且未过期的 OAuth state;链接由 ECS 使用配置生成。卡片不包含 claim secret、user token 或 refresh token。回调沿用已有授权人匹配校验。
|
||||
|
||||
## 去重、限流与状态
|
||||
|
||||
数据库新增 `notifications` 表,主键 `(host_id, request_id)`,保存 owner、请求哈希、状态、平台 message_id 和创建时间,不保存正文、授权链接或 token。
|
||||
|
||||
- 同一请求用新的签名/nonce、相同 request_id 查询,返回 duplicate 与 previous_status,不重复发消息。
|
||||
- 同一 ID 换正文、换类型或换绑定用户,返回 409。
|
||||
- 每设备、每用户每分钟固定窗口最多 10 次新推送。
|
||||
- 发送使用稳定平台 uuid,额外利用平台幂等能力;本地数据库是主要去重依据,不依赖平台永久记住 uuid。
|
||||
- `sent`:平台明确返回 message_id;不等于用户已阅读或点击卡片。
|
||||
- `unknown`:平台没有给出明确结果,可能已经发送;不得换新 request_id 重发。
|
||||
- `inflight`:已有调用正在进行或上次进程在处理中退出;不自动重发。
|
||||
- `binding_changed`:发送前绑定变化,未调用发送接口。
|
||||
|
||||
服务重启后去重记录仍在;OAuth 待授权事务仍为原有内存设计,重启会丢失,用户需要重新发起授权。
|
||||
|
||||
## 新环境部署
|
||||
|
||||
使用本目录最新版源码按 README 初始化部署,connector 启动时自动创建新增表。应用需要允许机器人向可用范围内用户发送消息/卡片,平台可用范围和实际权限应单独验收。通知由机器人应用身份发送;日历/文档业务仍使用本人 user token。
|
||||
|
||||
现有 ECS 更新包只重建应用镜像并重启 connector,保留数据库、设备 CA、连接器密钥和 Compose override。先更新 ECS,再更新 PC。connector 重启会中断在途等待和内存 OAuth 事务,升级窗口先等待任务结束;不要自动重发执行状态未知的任务。当前更新包只接受与导出基线或本补丁一致的源码,版本不符会停止,不能强行覆盖。
|
||||
|
||||
```bash
|
||||
# 解压更新包后,在 ECS 执行;项目目录显式指定,不自动猜路径。
|
||||
sudo bash scripts/update-notifications-ecs.sh /实际部署目录/hainuo-relay
|
||||
```
|
||||
|
||||
若镜像构建或重启失败,保留脚本打印的镜像标签及源文件备份;不要继续应用 PC 补丁。恢复时先将备份的 connector.py/platform.py/oauth.py 放回源码目录,保留新增表不删;使用打印的旧镜像标签恢复 `hainuo-relay:0.1.0` 后,用相同 Compose override 重新创建 connector。新增 notifications.py 留在源码目录但旧入口不引用时不影响旧镜像;正式回滚应一并按备份及变更清单清理。
|
||||
|
||||
## PC 增量安装
|
||||
|
||||
PC 包不替换整份 work_client.py/work_tools.py,安装脚本只在已知入口中插入通知调用,并增加两个新模块。先退出本地原生 Agent;在安装包解压目录使用当前客户端 Python 执行:
|
||||
|
||||
```powershell
|
||||
& '客户端Python的绝对路径' .\scripts\apply_notification_client.py --relay-dir '当前客户端relay目录的绝对路径'
|
||||
# 上条仅检查;兼容后执行备份和写入:
|
||||
& '客户端Python的绝对路径' .\scripts\apply_notification_client.py --relay-dir '当前客户端relay目录的绝对路径' --apply
|
||||
```
|
||||
|
||||
脚本备份修改前文件,遇到未知实现停止;保留已安装的 TLS、日历和文档修复。完成后重启 Agent。设备目录和平台地址沿用现有配置,不需要重新注册或重新配对。
|
||||
|
||||
## 验收命令
|
||||
|
||||
在客户端当前 Python/代码环境执行(示例中的目录、地址按实际填写):
|
||||
|
||||
```powershell
|
||||
& '客户端Python的绝对路径' -m relay.notification_cli `
|
||||
--directory '设备目录的绝对路径' --url 'https://中继服务地址' `
|
||||
--request-id notify-test-a-20261028-001 --kind text --text 'A电脑主动通知测试'
|
||||
```
|
||||
|
||||
同一命令再次执行,应返回 duplicate,机器人只收到一次。使用 `--kind notice --title '测试通知' --text '通知内容'` 验收固定卡片。
|
||||
|
||||
授权卡片:运行 `--kind authorization`(其他参数仍填写);沿用当前有效待授权事务或新建事务,自动发卡一次,不输出领取密钥。该模式使用事务派生的稳定 ID,命令行 request-id 不参与授权卡片去重。CLI 不常驻轮询,授权后在客户端再调用 `work_authorization` 领取;原生 Agent 工具沿用已有后台轮询领取逻辑。
|
||||
|
||||
Agent 文本测试:让本机海诺调用 `work_notification`,传 `request_id`、`kind=text`、`text`,确认只进入本人机器人私聊。
|
||||
|
||||
两人两机分别测试:消息不交叉;相同 ID 不重复;A 解绑/吊销后拒绝;旧绑定客户端拒绝;B 正常使用不受影响。没有实际重新授权需求时,不删除用户 token 来强行触发授权卡片,可用独立测试设备或已有待授权事务验收。
|
||||
|
||||
## 当前验证边界
|
||||
|
||||
自动化覆盖了私有平台发送请求格式、两用户路由、签名篡改、证书身份、nonce 重放、过期、重复/并发、持久去重、限流、解绑/吊销、绑定变更、跨用户 OAuth、授权链接不含领取密钥、客户端自动发卡和旧服务回退。使用本地 HTTP/ASGI、FakeRedis 和平台桩,不代表私有化平台已完成真实卡片验收。
|
||||
|
||||
本轮完整回归:**79 passed,1 skipped**;其中新增 19 项通知及增量安装测试。跳过项为缺少真实 PostgreSQL 测试连接,其他测试没有连接真实 Work 平台。Shell 更新脚本通过 Bash 语法检查;PC 安装脚本已对当前开发源码做只读兼容检查,未修改正在运行的本机客户端。
|
||||
|
||||
ECS 升级、PC 安装、真实卡片兼容性及真实 PostgreSQL 验收均待执行。自动通知不包含定时任务、后台扫描或持续推送;仅在既有授权动作触发,或客户端/工具明确调用时发送。
|
||||
Reference in New Issue
Block a user