配额与限制
这一页是开发者必读的”边界文档”——所有数字都来自当前线上 spec， 代码仓库 + 后端配置同步。
Agent 数量配额
| 项 | 默认值 | 来源 | 错误码 |
|---|---|---|---|
| 每个用户可创建的 Agent 数 | 50 | Agent 开发者平台规范 §quota；后端 env 可配 | AGENT_LIMIT_EXCEEDED（AGT_008） |
超过配额时，System Agent 会拒绝创建并返回结构化错误。 要扩配额需要在 Hashee 后台开 ticket（V2 marketplace 计划会引入开发者计划等级，自动放宽）。
单 Agent 并发连接
| 项 | 默认值 |
|---|---|
同 agent_id 同时在线的连接数（WebSocket / Webhook） | 3 |
这个上限确保横向扩容时一致性可控。如果你需要更高的并发（同 Agent 多区部署）， 请走”创建多个 Agent + 在 Hashee 端共享 H2A 关系”的路径。
消息与 Payload 大小
| 项 | 上限 | 备注 |
|---|---|---|
| 单条消息（文本 / Markdown / artifact metadata） | 1 MB | Webhook 模式硬上限；超过自动走 R2 对象引用 |
| 单个文件上传 | 100 MB | 媒体文件走 R2 + 客户端加密；CEK per-file |
| Capability Manifest（整体 JSON） | 128 KB | hard cap，CI 强制；≥64 KB 触发 telemetry warning |
工具权限敏感度（sensitivity）
每个 permission_scope 必须声明一个敏感度，直接决定客户端的提示行为：
| 级别 | 客户端行为 | 默认超时 |
|---|---|---|
low | 静默执行（不弹窗） | — |
medium | 首次弹窗 + 24 小时同设备同会话静默（滑动窗口） | — |
high | 每次调用都弹窗（即使已授权） | 30 秒未确认 → denied: user_timeout |
来源：Capability Manifest 规范 §9。
四个 V1 预置 i18n scope：notification:send (low) / filesystem:read (medium) /
clipboard:read (medium) / location:read (high)。
Webhook 模式专属
| 项 | 上限 |
|---|---|
| 签名算法 | HMAC-SHA256（X-Hashee-Signature） |
| Timestamp 容忍窗口 | ±5 分钟（300 s） |
| 同步响应 deadline | 10 秒 |
| 失败后重试次数 | 7 次（指数退避） |
| 多次失败后 Agent 状态 | 进入 unreachable 状态机，需要主动 ack 恢复 |
| Delivery log 保留 | 30 天 |
详见 Webhook 投递规范。
API Rate Limit
V1 当前对 Agent 的 REST API 调用走通用 rate limiter：
| 端点类别 | 限速 |
|---|---|
消息发送（POST /agents/:id/messages） | 10 req/s per agent |
| 文件上传 / R2 直传 | 5 req/s per agent |
Capability Manifest 更新（PATCH /agents/:id） | 1 req/min per agent |
| Token 旋转 | 5 次 / 24 小时 |
超限返回 429 Too Many Requests + Retry-After 头。
SDK 在 WebSocket 模式下会自动尊重 Retry-After 重排队列。
数据保留
| 数据 | 保留策略 |
|---|---|
消息密文（Neon messages 表元数据 + R2 加密 payload） | 与 H2A 关系生命周期一致，关系撤销 → 7 天后清理 |
| Grant access log（每次 Agent 读用户数据的审计行） | append-only；永不删除 |
| Webhook delivery log | 30 天 |
| Agent 私钥 | 后端从不持有；只持有公钥；旋转走 /agents/:id/keys/register |
计费现状（V1 内测期）
V1 内测期内无对外计费，三档定价（$10 / $50 / $100/月）针对 真人用户 而非 Agent 开发者； Agent 创建、消息收发、文件上传都不另行收费。
V2 计划（路线图）：
- Agent 商店上架计划（按月或按交易抽成）
- 高配额开发者计划（>50 Agent / >3 连接）
- 企业 SLA（99.95% / 专属 region）
如果你正在评估生产部署，请先和我们沟通确认你的场景—— hashee.ai/contact。
错误码速查
下面是开发者最常碰到的错误码，全表见 API 错误码。
| 错误码 | HTTP | 含义 | 处理建议 |
|---|---|---|---|
AGENT_LIMIT_EXCEEDED | 403 | 用户已达 50 Agent 上限 | 删除不用的 Agent，或申请扩配额 |
AGENT_TOKEN_INVALID | 401 | Token 失效或被撤销 | 用 System Agent 重新生成 |
AGENT_NOT_REGISTERED | 404 | agent_id 在后端不存在 | 检查 env 配置 |
AGENT_KEYS_MISMATCH | 409 | 客户端持有的私钥与后端注册的公钥不匹配 | 删除本地 keystore.json，让 SDK 重新注册 |
WEBHOOK_PAYLOAD_TOO_LARGE | 413 | Webhook payload 超过 1 MB | 用 R2 引用模式（自动）；如果是手动构造，分块发送 |
MANIFEST_TOO_LARGE | 413 | Capability Manifest 超过 128 KB | 精简 tools / scopes |
TOOL_CALL_DENIED | — | 用户拒绝了 tool call（artifact_response.status=denied） | 业务侧 fallback；详见 reason 字段 |
RATE_LIMITED | 429 | API 限速触发 | 看 Retry-After 头，SDK 已内置 backoff |