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 证书。两者缺一不成立。
必须满足:
_dwp.<domain>的 TXT 记录存在,内容形如v=1; endpoint=https://<host>/dwp/v0.1endpoint的主机名与<domain>相同,或其子域- 该主机名的证书由公共 CA 签发,覆盖该主机名,且未过期、未被吊销
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支持的动词数组,见 §Dkeys可选的签名公钥数组,仅在需要事后举证时出现updated_atRFC 3339 UTC
取回卡片后,客户端必须校验:证书有效、agent_id 等于解析用的域名、version 的次版本号被自己支持、bindings 至少含 "http"。任一不符即中止,不做「先连上再问」。
证书透明度日志与 DNSSEC 属实现方可选的加固,不是本版要求。
3. 消息信封¶
每个请求与响应都是一个 JSON 对象,UTF-8,不得带 BOM。共同字段:
protocol"dwp"version"0.1"message_idULID,发送方生成,全局唯一deal_idULID,事项标识,由发起方生成seq整数,同一deal_id内从 1 起递增,每个 Deal 独立计数from/to代理的agent_idverb见 §D,取值固定十个之一sent_atRFC 3339 UTC,秒精度payload动词相关的对象,见 §Dprev前一条消息内容的 SHA-256(十六进制小写);Deal 的第一条为nullreply_to可选,被回应的那条message_idext可选,扩展字段对象,见 §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_dealdeal_id不存在 · 不可重试illegal_transition当前状态不允许该动词 · 不可重试conflictseq或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 日志,后者靠部署纪律;本版只要求实现方能检测并在日志里明确报出。