MailUI4Agents

jianf/MailUI4Agents

Fork 0

Commit Graph

Author	SHA1	Message	Date
JianFeeeee	044a664cc3	fix(push): HMS 每日额度按批次计，且挪到"确认能发"之后审查报告 `docs/reviews/push-and-gui-review.md` §二.1 记的两条，都在线上（已部署二进制是 f51c9c8 的构建，此修复未上线）。 ## ① 计数单位错：按 token 数扣，变量名与文案都说"条" `hms.go` 原先 `h.reserveDaily(len(tokens))`，而变量名 `dayCount`、注释、报错文案（「达到每日推送上限 N 条」）说的都是"条"。华为的测试消息额度是按 `messages:send` 的调用次数计的（一次请求一条消息，无论 `message.token[]` 里有几个设备）。 ⇒ 3 个设备收到 1 封邮件就吃掉 3 条额度，实际只发出 1 条。多设备自部署用户会按 1/设备数的速度提前耗尽 1000 条/天。修法：`reserveDaily(1)` —— 一次 `Send` = 一条消息。 ## ② 扣在投递之前：一条都没发出去，额度却已经扣了原顺序：reserveDaily → accessToken → HTTP 请求。 `accessToken` 失败 / HTTP 失败 / 华为回非成功码，这三种情况一条都没发出去而额度已扣，且失败只 `log.Printf` ⇒ 一次网络抖动静默烧掉配额。修法：挪到 `accessToken` 之后、真正发请求之前。 ★ 为什么不是"发送成功后再扣"：那会超发（并发下多个 goroutine 都能通过检查）。保留前置预留、但放在"确认能发"之后，是宁可少算也不多发的取舍 —— 少算的代价是偶尔一次失败没计入，超发的代价是真超额被华为拒。 ## 验证 `server/internal/push/push_test.go` 补 3 格（+27 行）：按批次计（多设备一封邮件只扣 1） accessToken 失败不扣额度 reserveDaily 的单位是"条消息"而非 n 个 token	2026-09-28 08:26:41 +08:00
JianFeeeee	46fa7fa729	feat(push): 可选、配置式、多厂商的推送通道（HMS 为首个实现）用户要求：推送密钥必须是可选项（自部署后端不能写死推送方式），且要支持多厂商配置式接入 —— 每个用户各自部署服务器、自己选厂商、自己配凭证。所以落地成： · internal/push：通道抽象 + 工厂表（RegisterType），加厂商不改配置层与端点形状； HMS 只是第一个实现（internal/push/hms.go） · 配置在 PUSH_CONFIG（默认 <AGENTMAIL_DATA_DIR>/push.json），一项一个厂商，凭证走文件（app_secret_file / files.，建议 600）；环境变量只是可选覆盖 · 没配 = 整条推送路径连一次查库都不发生（shouldDispatch 早退）；单项配错（未知类型/密钥读不到/enabled:false）只跳过那一条，不影响启动 · push_tokens 表带 provider 维度 + 三个 /me/devices/push-token 端点；没配推送时端点照存并回 enabled:false（登记成功 != 服务端开了推送） · notify.Recipients 末尾异步挂钩：收件人名单直接用 SSE 那份 seen（两条通道共用同一份"谁该收到"的判据）；失败只记日志，绝不拖住收信 HMS 的形状是拿真凭证打线上接口问出来的（v1 + message.token[] + testMessage； payload/target 形状 v1 不认、v2 要服务账号 JWT）。未上架应用必须 test_message=true，单批 ≤10 token（MaxTokensPerRequest 声明）、每日 1000 条兜底（项目级额度）。实测：App ID + App Secret 能换到 access_token（3600s）；形状被线上服务接受。判据：repo 6 条 + push 12 条 + handler 3 组，全部做过变异验证* —— 过程中抓出两条假判据（异步分发与 t.Cleanup 赛跑而假绿；密钥文件优先级没被覆盖）并补掉。Go 全量测试与 go vet 干净。 ★ 未验：端到端真机送达（需要真机 token + 客户端按 com.jianf.agentmail 重编并签名，签名指纹还要在 AGC 登记）—— 从未真正发出过一条能到达设备的推送。详见 docs/HMS-PUSH-PLAN.md 的「实现状态」一节。	2026-09-15 11:21:00 +08:00

Author

SHA1

Message

Date

JianFeeeee

044a664cc3

fix(push): HMS 每日额度按**批次**计，且挪到"确认能发"之后

审查报告 `docs/reviews/push-and-gui-review.md` §二.1 记的两条，都在**线上**
（已部署二进制是 f51c9c8 的构建，此修复未上线）。

## ① 计数单位错：按 token 数扣，变量名与文案都说"条"

`hms.go` 原先 `h.reserveDaily(len(tokens))`，而变量名 `dayCount`、
注释、报错文案（「达到每日推送上限 N **条**」）说的都是"条"。

华为的测试消息额度是按 **`messages:send` 的调用次数**计的
（一次请求一条消息，无论 `message.token[]` 里有几个设备）。

⇒ **3 个设备收到 1 封邮件就吃掉 3 条额度，实际只发出 1 条。**
  多设备自部署用户会按 1/设备数 的速度提前耗尽 1000 条/天。

修法：`reserveDaily(1)` —— 一次 `Send` = 一条消息。

## ② 扣在投递**之前**：一条都没发出去，额度却已经扣了

原顺序：reserveDaily → accessToken → HTTP 请求。
`accessToken` 失败 / HTTP 失败 / 华为回非成功码，这三种情况
**一条都没发出去**而额度已扣，且失败只 `log.Printf`
⇒ 一次网络抖动静默烧掉配额。

修法：挪到 `accessToken` **之后**、真正发请求之前。

★ 为什么不是"发送成功后再扣"：那会超发（并发下多个 goroutine
  都能通过检查）。保留前置预留、但放在"确认能发"之后，是
  **宁可少算也不多发**的取舍 —— 少算的代价是偶尔一次失败
  没计入，超发的代价是真超额被华为拒。

## 验证

`server/internal/push/push_test.go` 补 3 格（+27 行）：
  按批次计（多设备一封邮件只扣 1）
  accessToken 失败**不**扣额度
  reserveDaily 的单位是"条消息"而非 n 个 token

2026-09-28 08:26:41 +08:00

JianFeeeee

46fa7fa729

feat(push): 可选、配置式、多厂商的推送通道（HMS 为首个实现）

用户要求：推送密钥必须是可选项（自部署后端不能写死推送方式），且要支持
多厂商配置式接入 —— 每个用户各自部署服务器、自己选厂商、自己配凭证。
所以落地成：

· internal/push：通道抽象 + 工厂表（RegisterType），加厂商不改配置层与端点形状；
  HMS 只是第一个实现（internal/push/hms.go）
· 配置在 PUSH_CONFIG（默认 <AGENTMAIL_DATA_DIR>/push.json），一项一个厂商，
  凭证走文件（app_secret_file / files.*，建议 600）；环境变量只是可选覆盖
· 没配 = 整条推送路径连一次查库都不发生（shouldDispatch 早退）；
  单项配错（未知类型/密钥读不到/enabled:false）只跳过那一条，不影响启动
· push_tokens 表带 provider 维度 + 三个 /me/devices/push-token 端点；
  没配推送时端点照存并回 enabled:false（登记成功 != 服务端开了推送）
· notify.Recipients 末尾异步挂钩：收件人名单直接用 SSE 那份 seen（两条通道
  共用同一份"谁该收到"的判据）；失败只记日志，绝不拖住收信

HMS 的形状是拿真凭证打线上接口问出来的（v1 + message.token[] + testMessage；
payload/target 形状 v1 不认、v2 要服务账号 JWT）。未上架应用必须 test_message=true，
单批 ≤10 token（MaxTokensPerRequest 声明）、每日 1000 条兜底（项目级额度）。
实测：App ID + App Secret 能换到 access_token（3600s）；形状被线上服务接受。

判据：repo 6 条 + push 12 条 + handler 3 组，全部做过**变异验证** ——
过程中抓出两条假判据（异步分发与 t.Cleanup 赛跑而假绿；密钥文件优先级没被覆盖）
并补掉。Go 全量测试与 go vet 干净。

★ 未验：端到端真机送达（需要真机 token + 客户端按 com.jianf.agentmail 重编并签名，
签名指纹还要在 AGC 登记）—— 从未真正发出过一条能到达设备的推送。
详见 docs/HMS-PUSH-PLAN.md 的「实现状态」一节。

2026-09-15 11:21:00 +08:00

2 Commits