@agentunion/fastaun 0.5.27 → 0.5.28

package/CHANGELOG.md

@@ -6,6 +6,42 @@
 
 ---
 
+## 0.5.28 — 未发布
+
+### 新功能
+
+#### 分类控制消息
+
+- 按服务端协商的 `message_classes_v1` 区分 `normal`、`control` 和 `sdk_control`，控制流按类别、peer／群及持久／volatile 范围隔离游标；加密保护头绑定类别、SDK 控制协议和版本，SDK 控制正文只供内部消费，不进入应用事件、History 或发送正文回包。
+- 内部消费或应用交付完成后，先持久保存游标和待确认 ACK，再按扫描证明 ACK；响应丢失恢复原 ACK，证明失效时重新扫描续证，身份或连接换代阻止旧页面提交。
+
+#### Owner 名片变更通知
+
+- 上传提交与通知 outbox 同锁保存，以固定 `message_id` 重试加密的 `aun.agent_md.changed` v1 SDK 控制消息；同目录的 AIDStore 提交可唤醒通知。Owner 下载验签并 fresh 核对当前归属与 ETag 后，可靠发布 `agent_md_changed`，支持离线／重启和 group／org 清单恢复，应用处理失败保留原事件。
+
+#### 风控响应
+
+- 在可信 WSS 握手协商风控能力及 `ECDSA-P256-SHA256` 签名键后，验证目标与签名：SEC1 未压缩公钥 65 字节，UTF-8 canonical JSON 去掉 `signature` 后做 SHA-256 并保留合法 Unicode 字符，P1363 `r || s` 签名 64 字节，接受合法 high-S／low-S，公钥与签名均为无填充 base64url。持久保存状态并发送 `gateway.risk_ack`；公开 `riskState`／`risk_state_changed`，原始指令内部消费。旧 Ed25519 风控键不再接受，仅含旧键的本地记录恢复返回 `risk_state_unavailable`，不自动迁移。
+- RPC 与 HTTP 在网络发送前执行风险门控，普通名片与 Ownership HTTP 使用独立 scope；HTTP 429 的等待时间仅限制同服务路由，4029 断开按服务端等待时间延后重连。服务端控制和限流策略依赖配套服务能力。
+
+### 修复
+
+#### agent.md 上传与下载校验
+
+- 上传候选显式执行上传 schema 校验：除 `human`、`group`／`org` 外，必须同时包含 `owner` 和有效的 Ownership 声明；不完整的历史 `ownership_proof` 及非法关系整数字段在上传前拒绝。
+- `human` 在上传和下载时均禁止包含 `owner`、`ownership`、`ownership_proof` 或 `ownership_release` 字段。
+- `group`／`org` 的上传 schema 仅检查 `owner` 字段存在；实际归属关系继续由 group／org 专属服务确认，不通过通用 Ownership 2.1 声明建立共识。
+- 普通 AID 下载允许没有 Ownership 声明，保留已有历史兼容和签名校验；现代实体名片继续执行原有读取校验，不将上传要求套用于下载。
+
+#### Ownership 共识刷新
+
+- 公开 `checkOwnershipConsensus()` 首轮结果不是 `consensus` 时，调用既有 fresh 入口，以 `Cache-Control: no-cache` 完整重查一次并返回第二轮结果；覆盖 `released`、`unbound`、`single_sided`、`invalid`、`unavailable` 和 `not_applicable`。首轮已达共识时保持原查询行为，第二轮仍未达共识时不循环重查。
+
+### 测试与版本
+
+- 补充分类控制流、Owner 通知恢复、风控响应、上传／下载 schema 和实际 HTTP 请求头回归；共识查询覆盖全部非共识状态、`single_sided` 刷新为 `consensus`、共识不额外刷新及单次重查上限。
+- 包配置、锁文件、运行时 `VERSION`、认证元数据及消息信封的 `sdk_version` 统一为 `0.5.28`；四端差异与验证范围见 [parity 0.5.28](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。
+
 ## 0.5.27 — 未发布
 
 > 基线：`0.5.25` 源码快照 `133067c80`；本节整理截至 2026-10-29 的 Node.js SDK 实际代码增量及当前工作区变更。

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,42 @@
 
 ---
 
+## 0.5.28 — 未发布
+
+### 新功能
+
+#### 分类控制消息
+
+- 按服务端协商的 `message_classes_v1` 区分 `normal`、`control` 和 `sdk_control`，控制流按类别、peer／群及持久／volatile 范围隔离游标；加密保护头绑定类别、SDK 控制协议和版本，SDK 控制正文只供内部消费，不进入应用事件、History 或发送正文回包。
+- 内部消费或应用交付完成后，先持久保存游标和待确认 ACK，再按扫描证明 ACK；响应丢失恢复原 ACK，证明失效时重新扫描续证，身份或连接换代阻止旧页面提交。
+
+#### Owner 名片变更通知
+
+- 上传提交与通知 outbox 同锁保存，以固定 `message_id` 重试加密的 `aun.agent_md.changed` v1 SDK 控制消息；同目录的 AIDStore 提交可唤醒通知。Owner 下载验签并 fresh 核对当前归属与 ETag 后，可靠发布 `agent_md_changed`，支持离线／重启和 group／org 清单恢复，应用处理失败保留原事件。
+
+#### 风控响应
+
+- 在可信 WSS 握手协商风控能力及 `ECDSA-P256-SHA256` 签名键后，验证目标与签名：SEC1 未压缩公钥 65 字节，UTF-8 canonical JSON 去掉 `signature` 后做 SHA-256 并保留合法 Unicode 字符，P1363 `r || s` 签名 64 字节，接受合法 high-S／low-S，公钥与签名均为无填充 base64url。持久保存状态并发送 `gateway.risk_ack`；公开 `riskState`／`risk_state_changed`，原始指令内部消费。旧 Ed25519 风控键不再接受，仅含旧键的本地记录恢复返回 `risk_state_unavailable`，不自动迁移。
+- RPC 与 HTTP 在网络发送前执行风险门控，普通名片与 Ownership HTTP 使用独立 scope；HTTP 429 的等待时间仅限制同服务路由，4029 断开按服务端等待时间延后重连。服务端控制和限流策略依赖配套服务能力。
+
+### 修复
+
+#### agent.md 上传与下载校验
+
+- 上传候选显式执行上传 schema 校验：除 `human`、`group`／`org` 外，必须同时包含 `owner` 和有效的 Ownership 声明；不完整的历史 `ownership_proof` 及非法关系整数字段在上传前拒绝。
+- `human` 在上传和下载时均禁止包含 `owner`、`ownership`、`ownership_proof` 或 `ownership_release` 字段。
+- `group`／`org` 的上传 schema 仅检查 `owner` 字段存在；实际归属关系继续由 group／org 专属服务确认，不通过通用 Ownership 2.1 声明建立共识。
+- 普通 AID 下载允许没有 Ownership 声明，保留已有历史兼容和签名校验；现代实体名片继续执行原有读取校验，不将上传要求套用于下载。
+
+#### Ownership 共识刷新
+
+- 公开 `checkOwnershipConsensus()` 首轮结果不是 `consensus` 时，调用既有 fresh 入口，以 `Cache-Control: no-cache` 完整重查一次并返回第二轮结果；覆盖 `released`、`unbound`、`single_sided`、`invalid`、`unavailable` 和 `not_applicable`。首轮已达共识时保持原查询行为，第二轮仍未达共识时不循环重查。
+
+### 测试与版本
+
+- 补充分类控制流、Owner 通知恢复、风控响应、上传／下载 schema 和实际 HTTP 请求头回归；共识查询覆盖全部非共识状态、`single_sided` 刷新为 `consensus`、共识不额外刷新及单次重查上限。
+- 包配置、锁文件、运行时 `VERSION`、认证元数据及消息信封的 `sdk_version` 统一为 `0.5.28`；四端差异与验证范围见 [parity 0.5.28](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。
+
 ## 0.5.27 — 未发布
 
 > 基线：`0.5.25` 源码快照 `133067c80`；本节整理截至 2026-10-29 的 Node.js SDK 实际代码增量及当前工作区变更。

package/_packed_docs/INDEX.md

@@ -23,6 +23,8 @@
 | [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md) | AUNClient 完全门面化、ClientRuntime 单一状态源和四端分批迁移步骤 |
 | [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md) | Forward A/T/H 窗口、Group 成员可见性下界、Tail/History RPC、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和跨 SDK 验收门禁 |
 | [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md) | `message.send` 秒级 TTL 钳制、持久/volatile 双游标、按 device 收件箱、隐藏 slot lease/ACK、文件 epoch、消息调试计数器与 payload type 分类、多实例/跨域和四 SDK 测试矩阵 |
+| [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md) | 待实施：三类消息、固定优先级、Gateway 设备能力权威与 TTL 回源缓存、独立 SEQ / cursor、旧 SDK 降级及 Owner 名片感知 |
+| [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) | 待实施：服务端强制限制、SDK 能力与柔性响应、旧端断连暂封、版本化恢复、控制台解封及验收 |
 | [跨设备已读未读方案](跨设备已读未读方案.md) | 同一 AID 多设备按话题同步已读位置；服务端按 message ID 公共顺序汇总，返回汇总 message ID 及当前设备 seq 映射，支持 P2P/Group、批量和部分会话上报 |
 | [跨设备已读未读详细设计](跨设备已读未读详细设计.md) | RPC、单条/显式空值边界、紧凑状态表、晚到位置持久回填、Group canonical 与权限版本、owner 事件路由及四端补偿 |
 | [跨设备已读未读实施计划](跨设备已读未读实施计划.md) | 按 TDD 分阶段落地服务端、状态缓存与异步批写、Gateway、四端 SDK、单域/E2E/cross-SDK/跨域测试及完成定义 |
@@ -57,6 +59,7 @@
 | [服务端消息通信诊断面板 P0 方案](design/服务端消息通信诊断面板P0方案.md) | aun-console 消息通信页的服务端可观察 P0 诊断面板 |
 | [消息收件箱统一迁移方案](design/消息收件箱统一迁移方案.md) | P2P `message_inbox` 与群消息 `group_inbox` 的统一读模型、后台回填和旧表清理方案 |
 | [AUN 反向代理服务方案与 TDD 实施计划](design/AUN反向代理服务方案与TDD实施计划.md) | AUN Service Proxy、service_proxy 服务模块、SDK service-proxy-client、URL 路由、隧道协议、Web 边界和分阶段 TDD 落地计划 |
+| [agent.md / owner.md 当前权威规范（Ownership 2.1）](protocol/Ownership协议定义2.1.md) | 当前文件结构、签名、Ownership 2.1 关系与 owner 锁；[agent.md Schema](agent.md/SCHEMA.md) 是 legacy 2.0，[协议内 Schema](protocol/agent.md/SCHEMA.md) 是 legacy 1.0 |
 | [agent.md Schema（legacy 2.0）](agent.md/SCHEMA.md) | 历史 Ownership 2.0 双文件声明与撤销格式；当前 2.1 文件、关系版本和 owner 锁见协议定义 2.1 |
 | [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
 | [agent.md Schema 与签发/验签流程澄清记录](agent.md/working/agent.md-schema与签发验签流程澄清.md) | working 讨论记录：当前 Schema、内嵌签名实现、三字段关系声明与 self-owner 单签、公开 proof 独立验签、owner 关系写入经 Auth 验证及冲突仲裁、事实摘要与 nonce/编排上下文分层、Auth 登记见证与回执、证书/关系状态分离，以及 `unbound`/`unusable`、状态 pull/push、TTL、type-change 和 Storage 权限的最新决策 |
@@ -67,7 +70,7 @@
 | [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、P2P peer 能力/游标、完整 pending peers/快照、need_render、50k 内存去重/应用持久幂等、四端门面、RPC、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md) | 以 0.5.5 为基线的四 SDK 发布汇总；覆盖首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 和语言能力边界 |
-| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)；[0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.27 跨语言对齐清单；0.5.27 对照 0.5.25 源码，覆盖语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、组织及 CLI，区分四端落点和已有验证范围 |
+| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)；[0.5.28 应用指南](sdk/0.5.28-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md) | 以 Python 实现为主线的 v0.3.3 至 v0.5.28 跨语言对齐清单；0.5.28 覆盖 agent.md 校验、共识 fresh、分类控制消息、Owner 通知和风控，列出四端落点与验证边界 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI入口、profile及主要命令；credential 23命令、组织入口、文件／上下文、原字节和错误退出 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
 | [凭证与组织服务 CLI 开发与使用指南](cli/凭证与组织服务CLI开发与使用指南.md) | 流程图＋TS示例；真实CLI调用、凭证全流程、组织材料衔接与SDK胶水开发 |
@@ -111,6 +114,7 @@
 - AUNClient 完全门面化、Runtime 状态归属、状态写入收口和四端分批实施 → [AUNClient 门面化与 Runtime 状态迁移细化方案](design/AUNClient门面化与Runtime状态迁移细化方案.md)
 - P2P/Group Message 的 A/T/H、Tail/History、页内唯一有序发布、应用层跨页幂等排序、三 Pull Gate、缺 sender IK 有界同步 bootstrap、永久页内 Gap、坏密文推进和分布式验收门禁 → [消息同步与历史拉取改造方案](消息同步与历史拉取改造方案.md)
 - P2P `message.send` TTL 内存缓存、持久/volatile 游标、device 收件箱、隐藏 slot lease/ACK、服务 epoch、消息调试计数器与 payload type 分类、跨 SDK/双域验收 → [P2P 消息 TTL 内存缓存方案](design/P2P消息TTL内存缓存方案.md)
+- 三类控制消息、设备能力持久化 / TTL 回源、SEQ / cursor 隔离、旧 SDK 投影及 agent.md Owner 感知 → [控制消息与设备能力协商方案](控制消息与设备能力协商方案.md)
 - 同一 AID 多设备按会话话题同步已读位置、message ID 公共顺序汇总、当前设备 seq 映射、P2P/Group 批量上报与查询 → [跨设备已读未读方案](跨设备已读未读方案.md)
 - 跨设备已读未读 RPC、状态表、请求级提交、混合域部分提交、SDK 缓存及本地完成事件契约 → [跨设备已读未读详细设计](跨设备已读未读详细设计.md)
 - 跨设备已读未读 TDD 阶段、状态缓存与批写、测试矩阵、断点续跑、兼容审查和完成定义 → [跨设备已读未读实施计划](跨设备已读未读实施计划.md)
@@ -134,6 +138,7 @@
 - 0.5.24 应用接入、消息持久处理、Ownership 文件验收和两个 local 场景、resolve 与文件缓存、凭证组织和升级 → [应用集成指南](sdk/0.5.24-SDK应用集成指南.md)
 - 0.5.24 SDK 分层、消息提交、Ownership／Stage／CAS、local 身份隔离、缓存新鲜度、跨端差异及 Rust 核查 → [开发与移植指南](sdk/0.5.24-SDK开发与移植指南.md)
 - Python / TS / Go / JS SDK 使用手册，P2P peer 能力、共享 seq/隔离游标、轻量 pending peers/可选整体估计快照、目录/Pull逐页next_pending_seq持续提示/每N次FIFO、peer ACK/slot 公共 S、need_render/页内渲染计数、50k 内存去重/应用持久幂等，以及 Python PushFacade → [SDK 文档索引](sdk/INDEX.md)、[Message RPC](sdk/09-message-rpc-manual.md)、[服务协议](protocol/06-服务协议.md#63-点对点消息-message)
+- SDK 风控能力、内部控制消费、RPC/HTTP 门控、断线等待、旧端兼容、服务端执行与 Console 解封 → [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md)
 - Ownership 2.1 agent.md/owner.md 关系、原格式兼容、普通 agent.md 独立、release 保持当前版本、清理后版本投影为 0／重绑默认 1、响应 Header 只投影校验结果、普通 agent owner 可选及旧 SDK 隔离兼容 → [协议定义 2.1](protocol/Ownership协议定义2.1.md)、[详细设计](sdk/Ownership2.1详细设计.md)
 - Ownership 2.1 应用接入：双向绑定、释放、转移、两个 local 编排、审批和显式重试的 TS 示例／流程图 → [应用集成指南](sdk/Ownership2.1-SDK应用集成指南.md)
 - Ownership 2.1 SDK 移植：文件签验、NS 验收、条件发布、通用消息交付、本地编排和文件 CAS → [开发与移植指南](sdk/Ownership2.1-SDK开发与移植指南.md)
@@ -152,7 +157,7 @@
 - 四 SDK resolve 的 opts/输入输出、frontmatter 全字段与类型、按需 ownership 共识及 owner.md 缓存 → [resolve 规格](sdk/06-API手册.md#resolve-输入与输出)、[连接与认证](sdk/04-连接与认证.md)
 - 按主题和行区间查 SDK 文档 → [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md)
 - 四 SDK 0.5.6 发布摘要、首次签名者回源、可信缓存提交、消息窗口、语言能力边界 → [AUN SDK 0.5.6 更新日志](sdk/CHANGELOG-0.5.6.md)
-- 四 SDK 0.5.27 相对 0.5.25 源码的语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错、组织及 CLI 变更；四端差异与已有验证范围 → [0.5.27 应用指南](sdk/0.5.27-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md)；实现对照见 [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)
+- 四 SDK 0.5.28 的 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控，以及四端差异和验证范围 → [0.5.28 应用指南](sdk/0.5.28-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)；实现对照见 [parity](../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.27 历史指南与 parity 保留原版本基线和记录。
 - Python CLI 源码位置、安装运行入口、全局选项、profile 配置、身份/消息/群组/Storage/Group FS/Collab/诊断等命令用法 → [AUN CLI 手册](cli/CLI手册.md)
 - Python CLI 当前实现架构、`main.py` 命令注册、`CLISession` SDK 桥接、配置解析和实现边界 → [AUN CLI 设计文档](cli/AUN-CLI设计文档.md)
 - Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、direct backend 上传下载和服务端分层 → [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>)
@@ -228,6 +233,14 @@
 
 定义 P2P `message.send` 的秒级 `ttl` 语义：`ttl <= 0` 走原持久化路径，正数钳制到 1-3600 秒并进入不写数据库/WAL 的 volatile 通道。方案规定持久/volatile 独立游标、按 device 的内存收件箱、slot 隐藏的 lease/ACK、服务模块数据目录中的递增 epoch 文件、消息调试页的 volatile 计数器与 payload type 分类、重启丢失和多实例/跨域约束，并给出 Python/Go 服务端、四 SDK、单域、cross-SDK、E2E 与双域验收矩阵。
 
+### 控制消息与设备能力协商方案
+
+[控制消息与设备能力协商方案](控制消息与设备能力协商方案.md) 是待实施的跨服务设计：`message_class=sdk_control/control/normal`，优先级依次递减，TTL 沿用 volatile / persistent 语义；Gateway 权威能力、Message / Group 缓存失效与回源、三流 SEQ / ACK、版本往返投影、Owner 加密通知和上线对账。包含改动范围、TDD 顺序、兼容矩阵及真实测试证据边界。
+
+### 风控响应与 SDK 协同方案
+
+[风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) 优先定义待实施的响应闭环：服务端先限制，支持 `risk_test_v1` 的连接协同装闸与回执，未支持端触发风险后断连暂封。规定可信作用域、RPC/托管 HTTP、签名快照与时间/版本、唯一重连、持久处罚和递增规则；Console 展示证据与各入口执行状态，带权限/CAS 解封并防止迟到策略复活。包含四 SDK、跨实例、旧端和受控公网验收；不表示识别算法或机制已上线。
+
 ### 跨设备已读未读方案
 
 定义同一 AID 多设备的业务已读状态模型。P2P `seq` 按设备隔离，设备按应用传入的 `topic_key` 保存最后已读 `message_id`；服务端依据消息公共顺序汇总各设备状态，查询只返回汇总 message ID 及其在当前设备上的 seq 映射。方案覆盖 P2P/Group、AID/话题/Group 过滤查询、单条/批量/部分会话上报、在线变更事件、定向消息边界、四端 SDK 和前端未读数计算。
@@ -422,6 +435,8 @@ Group/Org 作为 sub 时不进入这些通用任务或审批；以其为 sub 误
 
 ### 四 SDK 版本对齐变更清单
 
+0.5.28 [应用指南](sdk/0.5.28-SDK应用集成指南.md)：身份／消息接入 §2—§3 L18-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、Owner 通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](sdk/0.5.28-SDK开发与移植指南.md)：上传／下载 schema §1 L7-36、非一致共识 fresh §2 L37-62、分类控制消息 §3 L63-108、Owner outbox §4 L109-121、风控 §5 L122-134、移植矩阵 §6 L135-146。对应实现及验证边界见 `python/CHANGES_FOR_PARITY.md` 0.5.28 章节。0.5.27 及更早版本保留原基线和执行记录。
+
 0.5.27 [应用指南](sdk/0.5.27-SDK应用集成指南.md)：身份／连接／消息迁移 §2—§3 L30-133，结构化 §4 L134-192／语义 §5 L193-349，组织与缓存 §6—§7 L350-388，升级 §8 L389-408；[开发与移植指南](sdk/0.5.27-SDK开发与移植指南.md)：字节／签名 §2 L38-84，结构化 §3 L85-123／语义 §4 L124-297，组织 §5 L298-334，迁移交付 §6 L335-383，平台与回归 §7—§8 L384-410。 `python/CHANGES_FOR_PARITY.md` 以 Python SDK 实现为主线记录 Go / TypeScript / JavaScript 对齐要求。0.5.27 L15-132 统一对照 0.5.25 源码提交，覆盖结构化／语义凭证、消息证据、online／bounded、Usage 持久恢复、Gateway 迁移、时间容错、组织和 CLI；列出各端实现落点、存储差异及已有验证范围。0.5.26 仅记 TypeScript 根证书打包修正；0.5.25 及更早章节保留原基线和执行记录。
 
 ### AUN CLI 手册

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -8,20 +8,20 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ### Step 1：先读根级 Layer 1
 
-- `docs/INDEX.md` L7-96：根级文档地图。
+- `docs/INDEX.md` L7-103：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L101-121。
-- 服务端 Go 化重构审查：`docs/INDEX.md` L122-125。
-- SDK 使用与协议：`docs/INDEX.md` L126-175。
-- Service Proxy 与服务暴露：`docs/INDEX.md` L176-182。
-- 诊断与可观测性：`docs/INDEX.md` L183-191。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L192-198。
+- 测试与 E2E：`docs/INDEX.md` L106-127。
+- 服务端 Go 化重构审查：`docs/INDEX.md` L128-131。
+- SDK 使用与协议：`docs/INDEX.md` L132-184。
+- Service Proxy 与服务暴露：`docs/INDEX.md` L185-191。
+- 诊断与可观测性：`docs/INDEX.md` L192-200。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L201-209。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L201-481：重点文档摘要。
+- `docs/INDEX.md` L210-502：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -82,6 +82,8 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | A/T/H、Tail/Forward、Group 成员可见性下界、History、缺 sender IK 有界同步 bootstrap、页内唯一有序发布、应用层跨页幂等排序、Pull Gate 与兼容边界 | `docs/消息同步与历史拉取改造方案.md` L7-375 |
 | 消息同步 TDD、Gateway、兼容性和分布式 E2E 门禁 | `docs/消息同步与历史拉取改造方案.md` L434-750 |
 | P2P 消息 `ttl` 秒级钳制、volatile 双游标、device 收件箱、隐藏 slot lease/ACK、epoch 文件、消息调试计数器与 payload type 分类和四 SDK/双域测试方案 | `docs/design/P2P消息TTL内存缓存方案.md` L1-369 |
+| 三类消息优先级、Gateway 设备能力、TTL 缓存回源、独立 SEQ / cursor、旧 SDK 降级及 Owner 名片感知（待实施） | [控制消息方案](控制消息与设备能力协商方案.md)：规则 L5-65；能力与兼容 L66-169；流与调度 L170-279；Owner / 跨域 L280-325；改动与验收 L326-417 |
+| 服务端风控强制执行、SDK 能力/门控/回执、旧端断连暂封和控制台解封（待实施） | [风控响应方案](风控响应与SDK协同方案.md)：原则/能力 L5-99；策略/服务端响应 L100-200；SDK/递增处置 L201-252；持久状态/控制台 L253-309；场景/实施/验收 L310-381 |
 | 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
 | 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
 | 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |
@@ -126,7 +128,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 离线 Push Service 当前发布结论与强制发布门 | `docs/AUN离线推送服务运维与发布指南.md` L5-23 |
 | 离线 Push Service 运行依赖、诊断和告警判断 | `docs/AUN离线推送服务运维与发布指南.md` L25-81 |
 | 离线 Push Service 性能基线、安全边界、隔离 PoC 灰度、回滚和已知限制 | `docs/AUN离线推送服务运维与发布指南.md` L83-141 |
-| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L65、L174、L319-322 |
+| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L66、L176、L325-328 |
 | AUN Service Proxy 总体架构、参考项目与边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L3-127 |
 | AUN Service Proxy URL、注册、隧道协议和 Web 边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L129-384 |
 | AUN Service Proxy 服务列表注册、双注册和 wakeup 路由 | `docs/sdk/09-proxy-rpc-manual.md` L1-226、`docs/protocol/06-服务协议.md` L43-204 |
@@ -155,6 +157,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 四 SDK Storage / Group FS 默认读缓存、省略策略或 TTL 默认 60 秒、显式限制、SHA 无正文免计次与 owner.md 普通/权威读取 | `docs/sdk/09-storage-rpc-manual.md` L129-170；`docs/sdk/06-API手册.md` L497-510；`docs/sdk/09-group-rpc-manual.md` L1586-1620 |
 | 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L96-125、`docs/sdk/06-API手册.md` L327-346、`docs/sdk/09-storage-rpc-manual.md` L690-734、`docs/sdk/09-group-rpc-manual.md` L1612-1618、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
 | 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
+| 四 SDK 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知与风控；四端实现及验证边界 | `docs/sdk/0.5.28-SDK应用集成指南.md`：接入／消息 L5-95、凭证／组织 L96-137、Storage／Ownership L138-186、通知 L187-201、风控／升级 L202-228；`docs/sdk/0.5.28-SDK开发与移植指南.md`：校验 L7-36、共识 L37-62、wire L63-108、outbox L109-121、风控 L122-134、移植 L135-146；parity 当前 L15-99 |
 | 四 SDK 0.5.27 对照 0.5.25 源码的凭证、消息证据、状态／Usage、Gateway 迁移、时间容错、组织与 CLI；0.5.26 仅为 TS 根证书打包修正 | `docs/sdk/0.5.27-SDK应用集成指南.md`：身份连接／消息 L30-133、结构化 L134-192、语义 L193-349、组织缓存 L350-388、升级 L389-408；`docs/sdk/0.5.27-SDK开发与移植指南.md`：字节 L38-84、结构化 L85-123、语义 L124-297、组织 L298-334、迁移 L335-383、平台回归 L384-410；`python/CHANGES_FOR_PARITY.md` 当前 L15-132；历史 0.5.25 L133-201、0.5.24 L202-338、0.5.22 L339-496，读缓存块⑦ L424-464／版本测试块⑧ L465-496 |
 | 群 `mention_mode` 提及过滤、Agent 自主行为、SDK group.index facade 和 CAS 冲突处理 | `docs/protocol/10-Group-子协议.md`、`docs/protocol/13-Agent行为规范.md`、`docs/sdk/09-group-rpc-manual.md`、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-378 |

package/_packed_docs/sdk/AUN_DOCS_GUIDE.md

@@ -61,7 +61,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | - | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 同步、Stage/CAS、撤销续期、缓存、服务依赖及 Rust 清单 |
 | - | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前消息接线、无任务 Ownership、两个 local 编排、缓存和凭证组织 |
 | - | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | 消息提交、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度与语言差异 |
-| - | [0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md)；0.5.27 CHANGELOG：[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) | 对照 0.5.25 源码的凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错与 CLI；实现差异和验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布) L15-132 |
+| - | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | 0.5.28 agent.md 上传／下载校验、共识 fresh、分类控制消息、Owner 通知与风控；四端实现和验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) |
 | - | [agent.md 与 group.index 的 ETag 观察与同步机制](agent.md与group.index的ETag观察与同步机制.md) | 服务端 ETag 来源、四 SDK 被动观察、agent.md 下载触发、group.index 显式 pull 与 CAS |
 | - | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源、下载提交前验签、消息窗口、显式 change-seed 与语言能力边界 |
 | 01 | [快速开始](01-快速开始.md) | 安装、三主体模型、最小示例 |
@@ -103,7 +103,7 @@ Group 的成员 block/status、暂停群权限和两阶段群主转让，以及
 | 实现、移植或审查 0.5.22 SDK，查看 Stage/CAS、配套服务修复、读缓存及 Rust 验收清单 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) |
 | 接入或升级 0.5.24，查看当前消息、无任务 Ownership、两个 local 场景、缓存及凭证组织 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) |
 | 实现、移植或审查 0.5.24，核对提交／ACK、NS 事实、远端 CAS、local 身份隔离和缓存新鲜度 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) |
-| 核查 0.5.27 的语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错、组织及 CLI 变更 | [应用指南](0.5.27-SDK应用集成指南.md)：身份／连接／消息迁移 §2—§3 L30-133，结构化 §4 L134-192／语义 §5 L193-349，组织与缓存 §6—§7 L350-388，升级 §8 L389-408；[开发与移植指南](0.5.27-SDK开发与移植指南.md)：字节／签名 §2 L38-84，结构化 §3 L85-123／语义 §4 L124-297，组织 §5 L298-334，迁移交付 §6 L335-383，平台与回归 §7—§8 L384-410。 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布) L15-132 及各端 CHANGELOG；统一对照 0.5.25 源码，0.5.26 仅记 TS 根证书打包修正 |
+| 核查 0.5.28 的 schema、共识、控制消息、Owner 通知与风控；回看 0.5.27 的历史增量 | [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)：接入与消息 §1—§3 L5-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：校验 §1 L7-36、共识 §2 L37-62、wire §3 L63-108、outbox §4 L109-121、风控 §5 L122-134、移植 §6 L135-146。 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L15-99；历史 0.5.27 指南及 parity 保留原基线 |
 | 0.5.24 应用按主题读：身份、消息、resolve、Ownership、文件缓存、凭证组织和升级 | `0.5.24-SDK应用集成指南.md` §2 L21-75、§3 L76-132、§4 L133-168、§5 L169-298、§6 L299-321、§7 L322-366、§9 L386-401；local bind L227-245、local transfer L246-267 |
 | 0.5.24 移植按主题读：消息提交、名片、观察、Ownership、缓存、PKI、凭证组织及语言差异 | `0.5.24-SDK开发与移植指南.md` §3 L32-84、§4 L85-92、§5 L93-122、§6 L123-217、§7 L218-245、§8 L246-261、§9 L262-297、§10 L298-325；Rust §11 L326-339、验收 §12 L340-354 |
 | 首次使用 SDK | [01-快速开始](01-快速开始.md) |

package/_packed_docs/sdk/INDEX.md

@@ -14,7 +14,7 @@
 | [0.5.22 SDK 开发与移植指南](0.5.22-SDK开发与移植指南.md) | 后台退避 · 群状态 · 两种绑定与 Stage/CAS · 消息内部消费 · 撤销同步 · 组织恢复及配套服务修复 · 默认读缓存 · Rust 清单 |
 | [0.5.24 SDK 应用集成指南](0.5.24-SDK应用集成指南.md) | 当前身份与消息接入 · 无任务 Ownership · local 双／三身份编排 · resolve 与文件缓存 · 凭证组织 · 升级 |
 | [0.5.24 SDK 开发与移植指南](0.5.24-SDK开发与移植指南.md) | peer／batch 提交 · NS 事实与远端 CAS · local 短连接 · 观察与 PKI 缓存 · 持久化边界 · 语言差异和验收 |
-| [0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md)；0.5.27 CHANGELOG：[Python](../../python/CHANGELOG.md)、[Go](../../go/CHANGELOG.md)、[TS](../../ts/CHANGELOG.md)、[JS](../../js/CHANGELOG.md) | 对照 0.5.25 源码的语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错与 CLI；四端差异及验证范围见 [parity](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布) |
+| [0.5.28 应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；[0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md) | agent.md 上传／下载校验、非一致共识 fresh、分类控制消息、Owner 通知与风控；四端差异及验证边界见 [parity 0.5.28](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) |
 | [CHANGELOG-0.5.6](CHANGELOG-0.5.6.md) | **0.5.6 版本更新日志**：首次签名者回源 · 下载提交前验签 · 消息窗口 · 显式 change-seed · 语言能力边界 |
 | [01-快速开始](01-快速开始.md) | 安装 · 三主体模型 · 最小示例 · 多语言构造 |
 | [02-WebSocket协议](02-WebSocket协议.md) | 握手流程 · 严格布尔 peer 能力声明 · JSON-RPC 消息格式 · 裸 WebSocket 示例 |
@@ -76,7 +76,7 @@
 
 - 当前身份与消息接入、无任务 Ownership、两个 local 场景、名片及文件缓存、凭证组织与升级 → [应用集成指南](0.5.24-SDK应用集成指南.md)
 - 三主体分层、提交／ACK、NS 事实和远端 CAS、local 身份隔离、缓存新鲜度、语言差异与验收 → [开发与移植指南](0.5.24-SDK开发与移植指南.md)
-- 0.5.27 对照 0.5.25 源码的增量、四端实现落点和已有验证范围；0.5.26 仅记 TS 根证书打包修正 → [0.5.27 应用指南](0.5.27-SDK应用集成指南.md)、[开发与移植指南](0.5.27-SDK开发与移植指南.md)；实现差异见 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)
+- 0.5.28 agent.md 校验、共识 fresh、分类控制消息、Owner 通知、风控和四端验证边界 → [应用指南](0.5.28-SDK应用集成指南.md)、[开发与移植指南](0.5.28-SDK开发与移植指南.md)；实现差异见 [parity 当前章节](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布)。0.5.27 历史版本见对应旧指南与 parity。
 
 ### 身份与认证
 
@@ -176,7 +176,9 @@ TypeScript 身份与消息接线、Ownership 审批恢复、resolve、默认缓
 
 定义消息 peer／batch／Gate、Ownership NS 事实和远端 CAS、Stage、local 专属 slot 与身份代际、展示及文件缓存、PKI 和 Credential 查询新鲜度、组织 checkpoint。列出四端兼容差异、Rust 核查与分层验收，不将已有专项证据等同完整发布验证。
 
-### 0.5.27 更新日志与跨端对齐
+### 0.5.28 更新日志与跨端对齐
+
+0.5.28 [应用指南](0.5.28-SDK应用集成指南.md)：身份／消息接入 §2—§3 L18-95、凭证／组织 §4—§5 L96-137、Storage／Ownership §6—§7 L138-186、Owner 通知 §8 L187-201、风控／升级 §9—§10 L202-228；[开发与移植指南](0.5.28-SDK开发与移植指南.md)：上传／下载 schema §1 L7-36、非一致共识 fresh §2 L37-62、分类控制消息 §3 L63-108、Owner outbox §4 L109-121、风控 §5 L122-134、移植矩阵 §6 L135-146。 [变更与对齐清单](../../python/CHANGES_FOR_PARITY.md#v0528--校验控制消息与风控未发布) L15-99 记录四端落点、已有测试入口及服务依赖／验收边界；本指南不把已有专项结果扩写为完整版本发布结论。
 
 0.5.27 [应用指南](0.5.27-SDK应用集成指南.md)：身份／连接／消息迁移 §2—§3 L30-133，结构化 §4 L134-192／语义 §5 L193-349，组织与缓存 §6—§7 L350-388，升级 §8 L389-408；[开发与移植指南](0.5.27-SDK开发与移植指南.md)：字节／签名 §2 L38-84，结构化 §3 L85-123／语义 §4 L124-297，组织 §5 L298-334，迁移交付 §6 L335-383，平台与回归 §7—§8 L384-410。 [变更与对齐清单](../../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布) L15-132 对照 0.5.25 源码，说明语义凭证、消息证据、状态／Usage 恢复、Gateway 迁移、时间容错、组织及 CLI；四端 CHANGELOG 提供接口级摘要，parity 列出实现落点、语言差异和已有验证范围。0.5.26 仅为 TypeScript 根证书打包修正，旧版本章节保留历史记录。
 

package/dist/agent-md-changes.d.ts

@@ -0,0 +1,42 @@
+import type { JsonObject } from './types.js';
+type OwnerFacts = {
+    status: string;
+    owner_aid: string | null;
+    agent_md_etag?: string;
+};
+export declare class AgentMdChangeCoordinator {
+    private readonly client;
+    private readonly options;
+    private timer;
+    private periodic;
+    private requested;
+    private running;
+    private closed;
+    private readonly refreshes;
+    private delivery;
+    private flushing;
+    private flushRequested;
+    constructor(client: any, options?: {
+        ownerResolver?: (aid: string, type?: string) => Promise<OwnerFacts>;
+        rosterLoader?: () => Promise<string[]>;
+    });
+    private identity;
+    private scope;
+    private readState;
+    private state;
+    private update;
+    handle(protocol: string, version: number, payload: JsonObject, senderAid: string): Promise<void>;
+    private markRefresh;
+    private owner;
+    refresh(aid: string): Promise<void>;
+    private refreshOnce;
+    deliverEvents(): Promise<void>;
+    flushNotifications(): Promise<void>;
+    private flushOnce;
+    private roster;
+    private storageRoster;
+    recover(): Promise<void>;
+    schedule(): void;
+    close(): void;
+}
+export {};