mirror of
https://github.com/MemeMeow-Studio/MemeMeow.git
synced 2026-10-17 04:41:01 +08:00
infstellar
5ecda39843
- Implement tests for the ImageProcessingWorker to validate task deduplication and policy interactions. - Create tests for operation policy to ensure proper grant handling and error responses. - Add tests for reverse image provider response structure to validate empty and malformed results. - Develop comprehensive tests for scope resolution and service validation to ensure correct behavior in various scenarios.
82 lines
4.9 KiB
Markdown
82 lines
4.9 KiB
Markdown
# Agent callback 迁移与回滚
|
||
|
||
本文说明内部 Agent callback 从旧的“只凭 task id 和内网地址”迁移到服务身份、当前
|
||
Task claim 和目标图片三者共同授权后的部署顺序。callback 不是用户登录接口，也不是
|
||
operation grant；它只证明一次受控 Agent 执行可以调用指定的内部能力。
|
||
|
||
## 发布前检查
|
||
|
||
1. 为 API 配置 `MEMEMEOW_AGENT_CALLBACK_SECRET`。密钥必须是随机、非空且至少 16 字节；
|
||
空值、控制字符、过短值或 verifier 初始化失败都会让 callback fail-closed。
|
||
2. 确认 Agent executor 使用独立的 `MEMEMEOW_AGENT_EXECUTOR_TOKEN` 或 named volume
|
||
token。executor Bearer token、callback 根 secret、`SERPAPI_API_KEY`、数据库凭据和
|
||
operation grant 不得相互复用。
|
||
3. 先运行数据库迁移和 callback 拒绝回归，再启动 Agent 调度。Runner 只能拿到当前
|
||
`task_id`、claim generation/attempt、目标 SHA、允许 operation 和不晚于租约的短期
|
||
callback token。
|
||
4. 反向图片 Agent 只通过 `/internal/reverse-image/search` 薄客户端调用。`forbid` 不
|
||
读取缓存、不 acquire、不联系 provider；`auto` 仍须经过当前 callback 校验和
|
||
`analysis.reverse_image_search` acquire。SerpApi 密钥只留在 API。
|
||
|
||
旧的在途任务不补发宽权限 token。没有当前完整 claim 的任务应以
|
||
`agent_callback_invalid_execution` 或稳定任务失败收束，随后由显式重试创建新的 claim；
|
||
不能使用旧 `task_id`、旧 token 或新 request id 继续执行。
|
||
|
||
## 密钥轮换
|
||
|
||
轮换使用短暂双 key 验证窗口：
|
||
|
||
```text
|
||
MEMEMEOW_AGENT_CALLBACK_SECRET=<new-secret>
|
||
MEMEMEOW_AGENT_CALLBACK_VERIFICATION_KEYS=old-kid=<old-secret>
|
||
```
|
||
|
||
新 token 只用当前根 secret 签发，旧 key 只用于验证已经发出的短期 token。先部署能够
|
||
验证新旧 key 的 API，再滚动重启 Runner/executor 使其取得新 token；确认旧 token 的最大
|
||
租约窗口已结束后，删除 `MEMEMEOW_AGENT_CALLBACK_VERIFICATION_KEYS` 并再次重启 API。
|
||
不要把 secret 写入 `.env` 提交、任务 payload、结果 artifact、缓存、usage、日志或
|
||
OpenCode prompt。轮换期间仍以 PostgreSQL 当前 claim、owner、lease、attempt 和目标
|
||
SHA 为最终授权，验证窗口不会扩大 Task 或 operation 范围。
|
||
|
||
executor token 单独轮换：停止 API 和 executor，备份并保留任务/数据库，替换 named
|
||
volume 中的 0600 token，再先启动 executor 健康检查、后启动 API。不要把 token 复制到
|
||
checkout，也不要用 callback secret 替代 executor token。
|
||
|
||
## 旧任务收束
|
||
|
||
发布前停止新 Agent claim 后，按以下顺序处理旧执行：
|
||
|
||
- 让已持有有效 claim 的任务完成或在租约结束前取消；callback 认证失败不得触发 provider、
|
||
usage、缓存、Meme、向量或阶段写回。
|
||
- 对 `prepared` 且未发生副作用的任务可由恢复器 release；已经 commit、`external_started`
|
||
或结果未知的 attempt 保留计量事实，标记 `unknown_execution`，禁止自动重放。
|
||
- 旧 claim 重新认领时 generation 必须递增。旧 Runner 即使 token 尚未过期，也会因
|
||
generation/owner/lease 校验失败；用户主动重试才创建新的 job revision、Task、attempt
|
||
和 grant。
|
||
- 迁移完成后扫描日志、任务结果和 Agent 环境，确认没有根 secret、executor token、
|
||
provider secret、绝对宿主路径或其它 scope 字段。
|
||
|
||
## 禁用式回滚
|
||
|
||
callback 版本出现故障时，回滚步骤是“禁用 callback 和新 Agent 调度”，不是恢复无认证
|
||
路由：
|
||
|
||
1. 停止新的图片处理/Agent claim，保留 PostgreSQL Task、attempt、usage、grant 和结果
|
||
artifact；不要清空表或把未知执行改成可重试成功。
|
||
2. 让 `/internal/reverse-image/search` 与 `/internal/visual-search/match` 在没有完整
|
||
服务凭据和当前 claim 时继续返回稳定拒绝；网络隔离和端口隐藏不能替代认证。
|
||
3. 只在恢复到同时支持服务认证、当前 claim fencing、scope/目标 SHA 校验的版本后重新
|
||
开放 callback。旧任务由新 claim 或显式重试收束，不为旧执行恢复兼容旁路。
|
||
|
||
普通上传、已有缓存命中、本地视觉搜索和单图文本 embedding 不应因 callback 回滚而被
|
||
伪装为 Agent 成功。联网反向图片调用在 provider 已开始但结果未知时保持
|
||
`reverse_image_unknown_execution`；`auto` 任务可以继续离线分析，但不得把未知子调用
|
||
冒充整个 Agent Task 成功。
|
||
|
||
## 验收边界
|
||
|
||
本地可运行的验收应至少覆盖 callback 认证前拒绝大 body、旧 claim/跨 scope/目标替换、
|
||
同 request id 幂等、Agent 环境脱敏、反向图片 `forbid/auto` 和 provider unknown。真实
|
||
Compose、外部模型、视觉权重及供应商调用需要在具备 Docker、凭据和模型资源的 staging/
|
||
发布环境执行；缺少这些条件时保留对应 OpenSpec 任务未勾选。
|