版本变化:从历史草案到正式 1.0

版本变化:从历史草案到正式 1.0

Poppy 的正式 1.0 于 2026-11-14 发布;此前的 0.1–0.4 是历史草案,各自固定在官方站点的 /docs/{版本}/spec 路径。理解版本之间的差异,主要不是为了考古,而是为了避开实现中最常见的一类错误:跨版本拼接字段。

版本线一览

版本关键变化
0.1–0.2早期草案,奠定发现文档与个人 Agent 会话的基本形态
0.3会话头与 OAuth 分离;企业自定义 scope
0.4多版本协商;按请求声明的扩展机制
1.0(正式)PAR 与 PS384 要求;Direct Sign-In 为主的登录路径;会话与账号两条线定形

本站内容与示例全部固定在正式 1.0;历史版本只在解释迁移时提及。

跨版本拼接是主要实现错误来源

典型症状与来源:

  • 用 0.2 的会话字段配合 1.0 的登录流程——会话头与 OAuth 在 0.3 已经分离,混用两个时代的语义会得到"看似登录成功但会话无效"的状态。
  • 从无版本入口读到未来版本——官方无版本入口会随时间指向新版本;固定 /docs/1.0/ 路径可避免你的实现被未来的规范变化静默影响。
  • 把扩展版本当正式版本——扩展(如 Mediated Sign-In)有独立生命周期,不随正式版本自动生效。

升级检查单

  1. 固定来源:把实现锚定到 /docs/1.0/ 与官方仓的固定 revision(本站核对基线为 65618532)。
  2. 逐项对照会话与账号:Poppy-Session 头、每请求新签 JWT、Poppy-Version、Direct Sign-In 的 PKCE 与 PAR、ES256/PS384。
  3. 处理撤销三语义:refresh token 撤销、会话停用、账号登出分别验证(见身份与授权)。
  4. 静态校验发现文档:官方 kit/company 的 JSON Schema 与 Validator 可用;通过静态校验不等于流程可用。

已登记的时间线

  • Mediated Sign-In 扩展计划于 2027-03-17 退役;使用该扩展的企业与 Agent 应在此前迁移。
  • 官方规范与文档采用 Apache-2.0 许可;版本间许可变化以官方仓为准。

版本差异的逐字段对照请直接读上游版本目录;本页提供的是选择版本与避坑的判断框架。

最后更新于