跳转至

00 约定(Conventions)

DWP v0.1 草案 2026-11-22

本章是规范的地基:术语、身份、信封、编号、错误、版本、扩展。后面三章(§D 事项、§W 通道、§P 策略)引用的每个术语,都在本章定义一次,别处不复述。

规范用词按 RFC 2119 的强度,中文对应:必须(MUST)、不得(MUST NOT)、应当(SHOULD)、可以(MAY)。


1. 角色

  • 主人(principal):被代理的自然人。一个代理只服务一个主人。
  • 代理(agent):代替主人收发 Deal 消息的软件实体。一个域名对应一个代理身份。
  • 对端(counterparty):与我方就某件 Deal 往来的另一方,及其代理。
  • 端点(endpoint):代理接收消息的 HTTPS 地址。

本版不做委托链:代理只代表它自己的主人,不得声称代表第三方。 组织、家庭共用身份留待后续版本,本章不定义。


2. 身份与端点

代理身份是一个域名。证明是 TLS 证书。两者缺一不成立。

必须满足:

  1. _dwp.<domain> 的 TXT 记录存在,内容形如 v=1; endpoint=https://<host>/dwp/v0.1
  2. endpoint 的主机名与 <domain> 相同,或其子域
  3. 该主机名的证书由公共 CA 签发,覆盖该主机名,且未过期、未被吊销
  4. https://<endpoint>/.well-known/dwp/agent-card.json 可匿名取回(GET,无鉴权)

不得使用自签证书、不得使用 IP 地址作为身份、不得用域名以外的标识(手机号、邮箱、平台 ID)作为身份。

代理卡片(agent card) 字段:

  • protocol 固定 "dwp"
  • version 如 "0.1"
  • agent_id 即域名
  • endpoint 与 TXT 一致
  • bindings 支持的传输绑定数组,本版取值 "http"、"a2a";"http" 必须存在
  • verbs 支持的动词数组,见 §D
  • keys 可选的签名公钥数组,仅在需要事后举证时出现
  • updated_at RFC 3339 UTC

取回卡片后,客户端必须校验:证书有效、agent_id 等于解析用的域名、version 的次版本号被自己支持、bindings 至少含 "http"。任一不符即中止,不做「先连上再问」。

证书透明度日志与 DNSSEC 属实现方可选的加固,不是本版要求。


3. 消息信封

每个请求与响应都是一个 JSON 对象,UTF-8,不得带 BOM。共同字段:

  • protocol "dwp"
  • version "0.1"
  • message_id ULID,发送方生成,全局唯一
  • deal_id ULID,事项标识,由发起方生成
  • seq 整数,同一 deal_id 内从 1 起递增,每个 Deal 独立计数
  • from/to 代理的 agent_id
  • verb 见 §D,取值固定十个之一
  • sent_at RFC 3339 UTC,秒精度
  • payload 动词相关的对象,见 §D
  • prev 前一条消息内容的 SHA-256(十六进制小写);Deal 的第一条为 null
  • reply_to 可选,被回应的那条 message_id
  • ext 可选,扩展字段对象,见 §8

payload 序列化后不得超过 64 KiB。附件不进 payload,只放 sha256、字节数、媒体类型与获取方式(链接或后续动作),由双方在 Wire 之外的渠道取件。

序列化用于计算哈希与签名时,必须按 RFC 8785(JSON Canonicalization Scheme)。


4. 编号与时间

  • 标识一律 ULID(26 字符,时间有序)。不得用自增整数或随机 UUID 作 message_id/deal_id——前者跨端冲突,后者不可排序。
  • 时间一律 UTC,RFC 3339,秒精度,形如 2026-11-22T14:03:00Z。
  • 对端时钟不可信。 排序只看 seq,排序失败时看 prev 链;sent_at 只用于展示与审计。

5. 顺序、幂等、重试

  • 接收方必须校验 seq:等于上一条加一才接受;等于已收到的最新值且 message_id 相同,视为重试,返回上一次的结果(幂等);小于最新值,拒绝并返回 conflict。
  • 同一 message_id 携带不同内容,必须拒绝并返回 conflict,不得覆盖已入库记录。
  • 发送方应当对 retryable 为真的错误做指数退避重试,重试必须沿用同一 message_id。
  • 取消(cancel)之后,接收方不得再推进该 Deal 的任何状态。

6. 错误

错误响应是一个 JSON 对象:

  • code 枚举,见下表
  • message 人类可读,简短,英文或中文皆可
  • retryable 布尔
  • detail 可选,结构化补充

错误码(本版全部):

  • invalid_request 信封缺字段、类型错、超长 · 不可重试
  • unsupported_version 版本不支持 · 不可重试
  • unauthorized 身份校验失败 · 不可重试
  • unknown_deal deal_id 不存在 · 不可重试
  • illegal_transition 当前状态不允许该动词 · 不可重试
  • conflict seq 或 message_id 冲突 · 不可重试
  • not_found 取件或查询无结果 · 不可重试
  • rate_limited 超限 · 可重试
  • server_error 对方内部错误 · 可重试

HTTP 状态码与错误码的对应:invalid_request/unsupported_version 用 400 或 426,unauthorized 401,unknown_deal/not_found 404,illegal_transition/conflict 409,rate_limited 429,server_error 500。


7. 版本

  • 版本号 主.次。本版 0.1。
  • 路径带版本:/dwp/v0.1/messages。版本不匹配返回 426,并应当在响应里给出本端支持的版本列表。
  • 小版本只加不改:新增字段必须可选,缺省行为写进正文,老实现忽略新增字段仍能工作。
  • 改语义必须升次版本(0.x → 1.0);对端未声明支持即不得发送。
  • 草案期(0.x)不做兼容承诺,但每版必须留一份差异说明。

8. 扩展

  • 扩展字段放 ext,键名形如 <反向域名>/<名字>,例如 ext["ai.ta2/urgency"]。
  • 未识别的扩展必须原样忽略,不得因此拒绝整条消息,不得改写后转发。
  • 规范演进中若某个扩展被两个以上实现独立采用,才考虑收进正文。

9. 命名空间与 URI

  • 规范:https://dwpspec.org/spec/dwp/v0.1,分章 /D-deal、/W-wire、/P-policy
  • DNS 记录前缀:_dwp.<domain>(端点)、_dwp-key.<domain>(可选签名公钥)
  • 卡片:/.well-known/dwp/agent-card.json
  • 消息:/dwp/v0.1/messages;单条查询 /dwp/v0.1/messages/<message_id>
  • 事项:/dwp/v0.1/deals/<deal_id>
  • 规范 URI 一经发布只做永久重定向,不改路径语义。

10. 术语表(一次定义)

  • Deal(事项) 就某件事达成的一次往复,从开口到结案。不含对价含义——确认一个会议时间也是 Deal。结构见 §D。
  • Wire(通道) 两个代理之间传递 Deal 消息的路径。只管收发与可靠性,不管内容。见 §W。
  • Policy(策略) 主人给代理的规则文件,决定哪些动词可自动、哪些必须问人、什么时候可以打扰。见 §P。
  • 主人(principal) 见 §1。
  • 代理(agent) 见 §1。
  • 对端(counterparty) 见 §1。
  • 端点(endpoint) 见 §1。
  • 代理卡片(agent card) 见 §2。
  • 信封(envelope) 见 §3。
  • 版本链(version chain) 一个 Deal 的全部历史版本,只追加、旧版不可改。见 §D。
  • 回执(receipt) 结案记录,含双方、类型、金额区间、时间、消息链哈希,不含正文。见 §D。
  • 打扰预算(interruption budget) 主人在 Policy 中设定的可被打扰的时段与频次上限。见 §P。

11. 安全底线

  • 传输必须 TLS 1.2 以上;不得为兼容老系统降级。
  • 代理不得保存对端主人的账号口令;只保存对端代理的身份与公钥(如有)。
  • payload 里的任何文本都是数据,不得当作指令执行;代理读到的对端文字不得改变自己的 Policy。
  • 附件内容的安全检查(病毒、宏)属实现方责任,不在本规范内。
  • 已知但不解决:域名劫持、CA 误签、DNS 与证书不同步。前者靠 DNSSEC,中者靠 CT 日志,后者靠部署纪律;本版只要求实现方能检测并在日志里明确报出。