Files

90 lines
7.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 客户端主动消息与授权卡片
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 验收均待执行。自动通知不包含定时任务、后台扫描或持续推送;仅在既有授权动作触发,或客户端/工具明确调用时发送。