更新与撤销

Agent 一旦上线就要面对生命周期管理：升级 manifest、轮换 token、用户撤销授权、彻底删除。 本页讲清楚每个动作的触发方式、对运行中 Agent 的影响、Hashee 平台的保证与你的责任。

Token 旋转

什么时候要旋转

• 怀疑 token 已经泄露（commit 进 git、Slack 误发、log 里漏出）
• 团队成员离职
• 例行安全策略（部分企业要求 90 天轮换）
• 切换 Agent 部署主机后的清理

怎么做

通过 System Agent Hashee：

重新生成 DemoBot 的 Token

System Agent 会二次确认（同时显示当前活跃连接数和最近 24h 请求数）， 确认后在新卡片里展示一次性新 Token。

立即效应

事件	时机
旧 Token hash 失效	后端原子操作，秒级生效
持有旧 Token 的请求	立即 401 AGENT_TOKEN_INVALID
WebSocket / Webhook 已认证连接	保留直到自然断开（避免误关业务连接）
重连时使用旧 Token	会被 401 拒绝

最佳实践：在你的 secret store 里准备好新 Token → 触发重启 → 进程用新 Token init → 旧连接自然过期。可达到零故障切换。

限速

5 次 / 24 小时 / Agent。超过返回 RATE_LIMITED。

Capability Manifest 更新

Non-breaking（无需用户重新审批）

• 新增 tool
• 新增 permission_scope（默认未授权）
• 文案改动（i18n key 改）
• capability_flags 由 false → true

直接 PATCH，立即生效，已加你 Agent 的用户不会收到通知。

Breaking（自动通知所有用户）

• 删除 tool
• 修改 tool 的 input_schema
• 提升 scope 敏感度
• 删除 permission_scope
• capability_flags 由 true → false

后端 diff 引擎检测到 breaking change 后：

1. 写 agents.capability_manifest_version += 1（永远单调）。
2. 给每个已添加你 Agent 的用户的所有设备广播一条 agent.capability_changed 事件。
3. 用户客户端收到事件 → 在和你 Agent 的会话顶部显示一条 banner： “Agent 能力已变更，请重新审阅权限”。

用户可以选择：

• 接受新 manifest → 关系正常使用，新 manifest 生效。
• 撤销关系 → 触发用户主动撤销流程（见下文）。
• 暂时忽略 → banner 持续显示，期间 tool call 仍按旧 manifest 走， 但新增的 tool 不会显示在权限 UI。

灰度策略

V1 没有内置 manifest 灰度（A/B 推送）。如需要：

• 跑两个 agent_id（DemoBot v1 + DemoBot v2），用户按需添加。
• 或者用业务侧 feature flag（在你的 Agent 进程里判断是否启用某个 tool）。

用户主动撤销 H2A 关系

用户在 Hashee 客户端：右滑你 Agent 的会话 → 删除 → 二次确认 → 撤销关系。

后端立即做的

1. 标记 relations 表里这条 H2A 行 status='revoked'。
2. 写 grant_access_log 一行 action='relation_revoked'（append-only，永不删）。
3. 给你的 Agent 推 relation.revoked 事件（包含被撤销的 user_id 和 conversation_id）。
4. 7 天后清理 messages 表里这条 H2A 关系的所有消息密文（与 R2 对象）。

你必须做的

agent.addEventHandler(async (event) => {
  if (event.type !== "relation.revoked") return;
  const { user_id, conversation_id } = event.payload;

  // 1. 删除你保存的对话明文（如果有）
  await db.deleteMessages({ conversation_id });

  // 2. 删除你保存的用户档案 / 个性化数据
  await db.deleteUserProfile({ user_id, agent_id: AGENT_ID });

  // 3. 撤销你为该用户分配的外部资源（API key、subscription 等）
  await externalApi.revokeUserAccess({ user_id });

  // 4. 写本地审计日志（GDPR 合规）
  await audit.log({ action: "relation_revoked_handled", user_id });
});

Hashee 不能替你删除——你的 Agent 进程持有的明文数据归你管。

撤销但保留消息历史？

不行。V1 撤销 = 7 天后消息密文物理清理。如果用户想”软撤销”（暂停接收消息但保留历史）， 当前办法是用客户端的”消息免打扰”功能而不是撤销关系。

数据授权（Grant）单独撤销

H2A 关系是”是否允许通讯”。“是否允许 Agent 读用户的 X 数据”是另一层——Grant。

用户可以在 Hashee 客户端的”Agent 详情 → 已授权数据”里看到所有 grant 并独立撤销，比如：

• “撤销 DemoBot 读取我的联系人列表”
• “撤销 DemoBot 读取我最近 30 天的消息”

撤销后：

• 你的 Agent 不能再调对应的 grant-scoped API（返回 GRANT_REVOKED）。
• 已经获取过的明文你必须主动清理（同关系撤销）。
• 已经写入 grant_access_log 的审计行永不删除。

详见 SDK 章节 — Data Grants。

删除 Agent

如何删

删除 Agent DemoBot

System Agent 会要求二次确认（输入 Agent 名称）+ 提供”导出最近 30 天审计日志”选项。

删除做了什么

影响	行为
agents 行	status='deleted' 标记（保留行用于审计）
agent_token_hash	立即清空
x25519_public_key, ed25519_public_key	立即清空
已存在的 H2A 关系	全部 status='revoked'；同时给所有用户推 relation.revoked
用户客户端	看到”该 Agent 已被开发者删除”的 banner，会话进入只读
messages 表	7 天后物理清理
Capability Manifest	与 Agent 行一同标记 deleted
grant_access_log	永不删除（审计完整性）

删了能恢复吗

不能——status='deleted' 后即使用同名重建，也是新 agent_id、新密钥、 没有任何老 H2A 关系的全新 Agent。

老用户必须主动重新搜索并添加新 Agent。

Agent 不可达 (unreachable) 处理

针对 Webhook 模式：

你的 webhook URL 7 次重试都失败
        ↓
平台标记 Agent.connection_status = "unreachable"
        ↓
后续给你的消息进入待投递队列 (deliverable for 24h)
        ↓
你修复 webhook + 调 POST /agents/:id/connection/recover
        ↓
后端清空 unreachable 标记 + flush 待投递队列

recover API 不需要消息内容——只需要 token + agent_id：

curl -X POST https://api.hashee.ai/agents/<agent_id>/connection/recover \
  -H "Authorization: Bearer hsk_..."

返回当前 pending 消息数量。SDK 在 Webhook dispatcher init 时会自动尝试一次 recover。

演示视频

下面这段约 60 秒的视频展示用户主动撤销 Agent → Agent 端收到事件 → 业务清理的完整时序：

视频文字版逐节描述（无视频也能阅读）

• 00:00 – 00:10 — 屏幕分两半。左：Hashee Mobile，DemoBot 会话内有几条历史消息； 右：终端，DemoBot 进程 idle 但 connected。
• 00:10 – 00:25 — 左侧用户回到主页 → 找到 DemoBot 长按 → 弹出菜单 → 选”删除”→ 二次确认弹窗”删除会同时撤销 Agent 的所有授权” → 确认。
• 00:25 – 00:40 — 右侧终端立即出现日志： [hashee] inbound event type=relation.revoked user_id=04ff... conv_id=01906...。 紧接着业务侧 console 输出 Cleaning up local messages for conv 01906...， 然后 Cleaning user profile for user 04ff...，最后 Audit logged.。
• 00:40 – 00:55 — 屏幕中间叠加文字 “Hashee 后端：messages 表 7 天后物理清理； grant_access_log append-only 永不删除”。
• 00:55 – 01:00 — 左侧 Hashee 主页，DemoBot 会话已消失。 右侧终端继续 idle，没有进一步消息（关系已断开）。

合规清单（GDPR / CCPA）

如果你的 Agent 面向欧盟 / 加州用户，应该额外做：

要求	实现
数据访问权 (Right of Access)	提供”导出我和这个 Agent 的所有交互记录” tool（业务侧）
数据删除权 (Right to Erasure)	在 relation.revoked handler 里清理用户数据；删除完成后给用户发确认消息
数据可携带权	导出格式建议 JSON + Markdown，提供下载链接（24h 有效）
数据最小化	只存业务必需的明文；不存就不需要删
处理记录 (Article 30)	用 Hashee grant_access_log 作为基础 + 你侧业务日志补充

下一步

• SDK 章节 — Data Grants — Agent 读用户数据的授权机制
• SDK 章节 — 错误处理 — relation.revoked 等系统事件的优雅处理
• API 错误码 — 全部错误码与处理建议