MemeMeow/docs/agent-callback-migration.md

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 验证窗口：

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 任务未勾选。