跳转到内容
Hashee Docs

Agent 开发者平台规范 (v1.1)

本页是 Hashee Agent 平台开发者必读的权威协议规范。覆盖 Agent 的”第一性原理” 定义、通过系统 Agent 引导式创建的注册流程、client_action 安全模型、配额、 密钥备份、cascade delete 通知机制。

第一性原理：Agent 是什么？

其它平台：
  Agent = 平台的一个 feature（GPT / Gemini / Claude）
  平台控制 Agent 行为、读对话、拥有数据


Hashee：
  Agent = 一个独立身份，与人类用户同等
  Agent 拥有：ID / Token / 公钥 / 对话 / 声誉
  Agent 通信：与人类相同协议（消息 / artifact / WS）
  平台无法：读 Agent 对话、控制 Agent 行为、访问 Agent 的 LLM

平台提供”身体”（身份 / 通信 / UI 渲染）；LLM 提供”大脑”（智能）；创建者提 供”灵魂”（目的 / 知识 / 个性）。

盲管道不变量

后端永远不解密。所有 Agent 业务逻辑跑在创建者的部署内（apps/agent-hashee/ 是 Hashee 第一方系统 Agent；第三方开发者跑在自己的 plugin / Worker / 容器）。 详见 端到端加密规范。

注册协议 (V1)

前置条件

  • 没有独立的开发者账号。Agent 开发者就是普通 Hashee 用户。
  • 注册入口是一个对话。用户在任意 Hashee 客户端与系统 Agent (Hashee) 对话来创建新 Agent。
  • 后端 CRUD 已就位：
    • POST /agents — 用户 JWT + rateLimiter
    • PATCH /agents/:id / DELETE /agents/:id — 用户 JWT
    • POST /agents/:id/token/regenerate — 用户 JWT
    • POST /agents/:id/keys/register — agent token
    • GET /agents/:id/user-context/:userId/agents — agent token

关键决策：Option C（已采纳）

通过 3 选 1 评估后采纳的方案：

方案评估结果
A — 用户 JWT tunneling系统 Agent 持有用户 JWT，违反 E2EE 盲管道拒
B — 后端 on-behalf-ofauth 链改造大，agent token 误用可代表任意用户拒
C — 客户端直 API + 系统 Agent UX系统 Agent 编排 UX + 发 artifact form；客户端直接调 API（持用户 JWT）；客户端回 artifact_response✓ 采纳

Option C 保证：盲管道不变 + auth 不变 + 责任清晰。

新增 artifact subtype（复用现有 MsgSubtype）

所有方向复用现有 MsgSubtype；Agent → 用户用 artifact_form；用户 → Agent 用 artifact_response。只 artifact.subtype 是新增。

artifact.subtypemsg_subtype方向语义
agent_creation_formartifact_form系统 Agent → 客户端请用户填创建表单
agent_createdartifact_response客户端 → 系统 Agent通知创建成功
agent_update_formartifact_form系统 Agent → 客户端请求修改 Agent
agent_updatedartifact_response客户端 → 系统 Agent通知更新成功
agent_deletion_confirmartifact_form系统 Agent → 客户端请用户二次确认删除
agent_deletedartifact_response客户端 → 系统 Agent通知删除成功
agent_token_rotate_confirmartifact_form系统 Agent → 客户端请用户确认 token 旋转
agent_token_rotatedartifact_response客户端 → 系统 Agent通知旋转成功
agent_list_displayartifact_form系统 Agent → 客户端展示用户的 Agent 列表

agent_creation_form 完整模板

系统 Agent 发送：

{
  "msg_subtype": "artifact_form",
  "artifact": {
    "subtype": "agent_creation_form",
    "title_i18n_key": "agent.creation.title",
    "client_action": {
      "endpoint": "POST /agents",
      "auth": "user_jwt",
      "allowed_endpoints": ["POST /agents", "POST /agents/:id/keys/register"],
      "after_success": {
        "endpoint": "POST /agents/:id/keys/register",
        "auth": "agent_token",
        "params_from_response": { ":id": "$.agent_id" }
      }
    },
    "schema": {
      "display_name":     { "type": "string", "min": 2, "max": 32, "required": true },
      "custom_id":        { "type": "string", "pattern": "^[a-z0-9_]{4,30}$", "required": false, "reserved_prefixes": ["hashee","system","admin","official"] },
      "bio":              { "type": "string", "max": 500 },
      "avatar_url":       { "type": "url", "optional": true },
      "category":         { "type": "enum", "values": ["assistant","tool","bot","integration"] },
      "connection_mode":  { "type": "enum", "values": ["websocket","webhook"], "required": true },
      "webhook_url":      { "type": "url", "required_if": {"connection_mode":"webhook"} },
      "health_check_url": { "type": "url", "optional": true }
    },
    "post_success_artifact": {
      "subtype": "agent_created",
      "msg_subtype": "artifact_response",
      "allowed_fields": ["agent_id","display_name"],
      "forbidden_fields": ["agent_token","private_key","webhook_secret"]
    }
  }
}

client_action 安全模型 (CRITICAL)

约束说明
allowed_endpoints白名单。SDK 维护内部 canonical allow-list；client_action.endpoint 不在白名单 → 静默忽略 + 记录 anomaly
auth必须是 user_jwt 或 agent_token；其它值拒绝
params_from_response受限 JSONPath 子集：仅 $.field_name（顶级字段）
post_success_artifact.allowed_fields + forbidden_fields双重约束客户端回复 payload，防 token / 私钥泄漏

客户端 agent_creation_form 处理流程

  1. 客户端检测 artifact.subtype === "agent_creation_form" → 检查 allow-list → 渲染表单
  2. 用户提交，客户端本地 schema 验证（含 custom_id 的 reserved_prefixes）
  3. 客户端调 POST /agents（用户 JWT）→ 返回 { agent_id, agent_token }
  4. 客户端本地生成：X25519 keypair + Ed25519 keypair
  5. 客户端调 POST /agents/:id/keys/register（agent token）注册公钥
  6. 客户端仅显示一次给用户：
    • agent_id（公开）
    • agent_token（敏感；“复制一次后丢失需轮换”）
    • X25519 私钥（JWK，敏感）
    • Ed25519 私钥（raw hex 或 JWK，敏感）
    • 如 connection_mode === "webhook"：webhook_secret（敏感）
  7. 密钥备份：
    • 客户端自动将密钥包加密到保护密码门控的本地 keystore
    • 用户启用 Passkey PRF 备份 → 同步到平台 encrypted_backup_blob_v2
    • 用户可在账号恢复后恢复这些 Agent 密钥
  8. 客户端发 artifact_response 给系统 Agent；payload 严格 { agent_id, display_name }
  9. 系统 Agent 显示：✓ 已创建 {display_name} ({agent_id})。请部署 Agent 代码到你的宿主。

配额

维度默认值错误码
每用户 Agent 数50（可配置）AGENT_LIMIT_EXCEEDED (AGT_008)

超限返回 AGENT_LIMIT_EXCEEDED（不新建 AGENT_QUOTA_EXCEEDED 错误码）。

Token 旋转

POST /agents/:id/token/regenerate
Body: { "emergency": false }
模式旧 token旧公钥
常规 (emergency: false)7 天宽限期7 天宽限期
紧急 (emergency: true)立即失效立即失效

宽限期内并发活动连接（如 plugin daemon）继续生效，给你时间从容部署新 token。

限速：5 次 / 24 小时。

删除 Cascade

agent_deletion_confirm artifact 必须包含 cascade 预览：

  • affected_h2a_count：被影响的 H2A 关系数
  • affected_users_count：被影响的用户数

执行删除后：

  • 所有 h2a_relations 标记 terminated_by_deletion
  • 所有被影响用户收到 security_alert 系统消息：agent.deleted_by_creator
  • 历史消息保留在 conversation history（已加密），但 Agent 无法再解密（私钥已删）

Ed25519 注册（Stage 3 schema 扩展）

当前 agentKeyRegisterSchema 只接受 public_key（X25519）字段。 E2EE 统一规范要求独立的 X25519 + Ed25519 identity keypair。

Stage 3 schema 扩展：

POST /agents/:id/keys/register
Body: {
  "public_key": "<base64 X25519>",
  "signing_public_key": "<base64 Ed25519>",   // 新增字段
  "webhook_secret": "..."                      // optional, webhook 模式
}

V1 内测期：只注册 X25519；Ed25519 注册 ride on Stage 3。 Stage 3 schema 扩展 MUST 在 Agent Marketplace 公开发布前完成。

Token 存储

字段算法
Agent token 明文仅出现在 POST /agents / POST /:id/token/regenerate 响应 body（一次性）
agent_token_hashbcrypt(cost=10) 哈希（与 webhook_secret_hash 同机制；通过 apps/api/src/lib/password.ts::hashPassword）

详见 Webhook 投递规范 §3.1 的 hash 算法选型理由。

跨规范关系

文档连接
E2EE 规范6 层加密栈；Agent 密钥遵循相同合约
Capability Manifest 规范Agent 能力声明 + tool call 协议
Webhook 投递规范无状态 Agent 的传输层
MsgSpec v6.0 (内部 spec)MsgSubtype 枚举 — 本规范的 artifact subtype 复用现有值
FuncSpec v1.4d (内部 spec)AGT-CREATE-001~005 + AGT-KEY-REG-001
Backend Architecture v6.0 (内部 spec)不变量”所有 Agent 写操作走用户 JWT，不通过 agent token 代理”

V1 / V2 路线图

服务V1V2V2+
Agent SDK (TypeScript)✓Enhanced—
Agent SDK (Python)—✓—
Agent SDK (Go)——✓
REST / Webhook API✓Enhanced—
系统 Agent (引导式注册 UX)✓ (本规范)——
Capability Manifest 协议✓——
Webhook 投递✓——
Claude Code Plugin (via MCP)✓Enhanced—
Agent Hosting (Hashee Cloud)—✓Auto-scale
Agent Builder (no-code)—✓AI-assisted
Agent CLI—✓—
Testing Sandbox—✓—
Marketplace—✓Featured, curated
Payment (Stripe Connect)—✓Multi-currency
Data Grant API—✓Enhanced

验收清单 (V1 closeout)

  • artifact_response 路由在系统 Agent inbox 落地
  • 系统 Agent 支持 /create-agent / /list-agents / /update-agent / /delete-agent / /rotate-token
  • agentKeyRegisterSchema 接受 signing_public_key（Ed25519）
  • agents.signing_public_key 列已加
  • 50 Agent 配额强制 + AGENT_LIMIT_EXCEEDED 错误
  • Cascade delete 含 security_alert 通知
  • Agent token bcrypt(cost=10) 哈希 + CI 回归断言（统一通过 apps/api/src/lib/password.ts::hashPassword）
  • 客户端 client_action executor 强制 allow-list + restricted JSONPath + fields whitelist
  • Agent 密钥备份与保护密码 keystore + Passkey PRF 同步集成

相关页面