@agentunion/fastaun 0.5.26 → 0.5.28

package/CHANGELOG.md

@@ -6,6 +6,83 @@
 
 ---
 
+## 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 实际代码增量及当前工作区变更。
+
+### 新功能
+
+#### 语义凭证与消息证据
+
+- 在 `client.credential` 平铺语义原件／确认元数据签验、登记、修订、读取、状态、撤销及增量撤销列表，管理调用自动绑定实际目标与请求；普通 `aun-cap/1` 保留原接口，按输入字段分流。
+- 支持 `aun-cap/semantic-1` 的纯语义与混合凭证、`text`／`message_ref` 正文、来源链和多受众修订；公开签名字节类型、严格 JSON／canonical 规则及各签名域工具。
+- 新增 `buildPackage`／`verifyPackage`、`buildRequest`／`verifyRequest` 和 `buildDecisionInput`，分别核验来源链、当前状态与认证请求绑定；业务接受、模型三态、后置条件和额度事务由应用端口接入。
+- 新增消息归档、`EvidenceRef` 创建／解析与正文验真，保存原始信封及解密明文字节，结合原收件身份、群收件证明、历史发送者证书和可信解析器核验正文及附件材料。
+- 支持 online／bounded 状态策略、UsageContract／UsageRef、额度分配证明与 `prepareUsage`／`commitUsage`／`abortUsage` 协调回执；online 查询和分配状态使用严格小于 30 秒的单调计时，bounded TTL 最长 300 秒。
+- 将已观察状态序号、撤销记录、分 scope 分页进度、请求／nonce 绑定与分配状态保存到当前身份 metadata；旧证明在 facade 重建后须取得新计时依据，身份或连接换代使旧异步结果失效。
+
+#### Gateway 迁移
+
+- 协商 `gateway_migrate_v1` 并处理 `gateway.migrate`，核对当前连接、身份、设备、slot、迁移序号及同发行域的 WSS 目标；迁移期间暂停新 RPC／notify 和后台任务，收束在途请求并保存水位。
+- 首选迁移目标，失败后重新发现候选并沿原会话重认证；取消、超时和连接换代停止旧尝试，迁移完成后恢复正常收取。
+
+### 修复
+
+- 统一当前证书、状态证明、请求绑定、成员及 Ownership 材料的五分钟时间容错；历史签署时点仍按证书原始有效期核验，本地缓存与查询耗时继续使用各自 TTL。
+- 长连接认证后立即执行普通凭证撤销同步，随后按小时补拉；短连接跳过后台撤销扫描，续期和原提交检查点保留原身份／实际发送约束。
+- 本地身份与 token 存储初始化时补置缺失的内置根证书，保留已有根；Node WebSocket 收到消息同样刷新活性，连续三次静默心跳超时后终止半开连接。
+- 组织首次创建的名片上传使用已确认创建结果及当前实体证书，支持 NS 尚无实体投影时的受限初始上传；实体权威查询明确区分初始缺失与不完整状态。
+- 首次群创建／绑定后名片上传使用本次返回的群证书及 owner 上下文，兼容 NS 实体投影尚未建立的初始状态。
+- 组织转让完成后的名片上传及原待办重试绑定本次结果中的新 owner／实体证书，避免继续使用转让前的权威投影。
+
+### 测试与版本
+
+- 补充语义协议、facade、消息证据、持久恢复及迁移定向回归，并接入四 SDK 场景运行器；包配置、锁文件、运行时 `VERSION` 与消息 `sdk_version` 统一为 `0.5.27`。
+- 接入流程和场景对照见 [SDK 应用指南](../docs/sdk/凭证与组织服务SDK应用集成指南.md#4-语义凭证接入)，实现差异及已执行验证范围见 [parity 0.5.27](../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)。
+
+## 0.5.26 — 根证书打包修正
+
+### 打包
+
+- npm 包的 `files` 白名单纳入 `src/certs/root.crt`，随 `@agentunion/fastaun` 分发内置根证书，供安装后的根证书发现路径读取。
+- 本节记录根证书随包分发修正；实际代码变更统一归入 `0.5.27`。
+
 ## 0.5.25 — 未发布
 
 > 基线：已提交的 `0.5.24`（`47c59687`）；本节整理截至 2026-10-25 工作区的 Node.js SDK 增量。

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,83 @@
 
 ---
 
+## 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 实际代码增量及当前工作区变更。
+
+### 新功能
+
+#### 语义凭证与消息证据
+
+- 在 `client.credential` 平铺语义原件／确认元数据签验、登记、修订、读取、状态、撤销及增量撤销列表，管理调用自动绑定实际目标与请求；普通 `aun-cap/1` 保留原接口，按输入字段分流。
+- 支持 `aun-cap/semantic-1` 的纯语义与混合凭证、`text`／`message_ref` 正文、来源链和多受众修订；公开签名字节类型、严格 JSON／canonical 规则及各签名域工具。
+- 新增 `buildPackage`／`verifyPackage`、`buildRequest`／`verifyRequest` 和 `buildDecisionInput`，分别核验来源链、当前状态与认证请求绑定；业务接受、模型三态、后置条件和额度事务由应用端口接入。
+- 新增消息归档、`EvidenceRef` 创建／解析与正文验真，保存原始信封及解密明文字节，结合原收件身份、群收件证明、历史发送者证书和可信解析器核验正文及附件材料。
+- 支持 online／bounded 状态策略、UsageContract／UsageRef、额度分配证明与 `prepareUsage`／`commitUsage`／`abortUsage` 协调回执；online 查询和分配状态使用严格小于 30 秒的单调计时，bounded TTL 最长 300 秒。
+- 将已观察状态序号、撤销记录、分 scope 分页进度、请求／nonce 绑定与分配状态保存到当前身份 metadata；旧证明在 facade 重建后须取得新计时依据，身份或连接换代使旧异步结果失效。
+
+#### Gateway 迁移
+
+- 协商 `gateway_migrate_v1` 并处理 `gateway.migrate`，核对当前连接、身份、设备、slot、迁移序号及同发行域的 WSS 目标；迁移期间暂停新 RPC／notify 和后台任务，收束在途请求并保存水位。
+- 首选迁移目标，失败后重新发现候选并沿原会话重认证；取消、超时和连接换代停止旧尝试，迁移完成后恢复正常收取。
+
+### 修复
+
+- 统一当前证书、状态证明、请求绑定、成员及 Ownership 材料的五分钟时间容错；历史签署时点仍按证书原始有效期核验，本地缓存与查询耗时继续使用各自 TTL。
+- 长连接认证后立即执行普通凭证撤销同步，随后按小时补拉；短连接跳过后台撤销扫描，续期和原提交检查点保留原身份／实际发送约束。
+- 本地身份与 token 存储初始化时补置缺失的内置根证书，保留已有根；Node WebSocket 收到消息同样刷新活性，连续三次静默心跳超时后终止半开连接。
+- 组织首次创建的名片上传使用已确认创建结果及当前实体证书，支持 NS 尚无实体投影时的受限初始上传；实体权威查询明确区分初始缺失与不完整状态。
+- 首次群创建／绑定后名片上传使用本次返回的群证书及 owner 上下文，兼容 NS 实体投影尚未建立的初始状态。
+- 组织转让完成后的名片上传及原待办重试绑定本次结果中的新 owner／实体证书，避免继续使用转让前的权威投影。
+
+### 测试与版本
+
+- 补充语义协议、facade、消息证据、持久恢复及迁移定向回归，并接入四 SDK 场景运行器；包配置、锁文件、运行时 `VERSION` 与消息 `sdk_version` 统一为 `0.5.27`。
+- 接入流程和场景对照见 [SDK 应用指南](../docs/sdk/凭证与组织服务SDK应用集成指南.md#4-语义凭证接入)，实现差异及已执行验证范围见 [parity 0.5.27](../python/CHANGES_FOR_PARITY.md#v0527--相对于-v0525-基线的变更未发布)。
+
+## 0.5.26 — 根证书打包修正
+
+### 打包
+
+- npm 包的 `files` 白名单纳入 `src/certs/root.crt`，随 `@agentunion/fastaun` 分发内置根证书，供安装后的根证书发现路径读取。
+- 本节记录根证书随包分发修正；实际代码变更统一归入 `0.5.27`。
+
 ## 0.5.25 — 未发布
 
 > 基线：已提交的 `0.5.24`（`47c59687`）；本节整理截至 2026-10-25 工作区的 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/跨域测试及完成定义 |
@@ -38,9 +40,10 @@
 | [Ownership SDK 编排指南 2.1](sdk/Ownership-SDK编排指南2.1.md) | 历史编排方案；持久任务、自动恢复及一次性决定已由当前两份指南中的无状态流程替代 |
 | [Ownership 2.1 SDK 应用集成指南](sdk/Ownership2.1-SDK应用集成指南.md) | 应用侧 TS 接线与审批；双向绑定、释放、转移、两个 local 编排及显式重试的流程图与示例，以 NS 当前归属为准 |
 | [Ownership 2.1 SDK 开发与移植指南](sdk/Ownership2.1-SDK开发与移植指南.md) | SDK 内部签验、NS 验收、Storage 条件发布、消息处理、两／三身份本地编排及文件 CAS；不维护 Ownership 任务或 WAL |
-| [凭证与组织服务 SDK 应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md) | TS 示例与凭证登记／验证、成员申请／邀请、续期、撤销同步和组织 rekey／finalize 转让流程图 |
-| [凭证与组织服务 SDK 开发与移植指南](sdk/凭证与组织服务SDK开发与移植指南.md) | TS 内部示例与 Verify、双层请求摘要、登记最终化、撤销快照和实体 checkpoint 流程图；跨语言契约与验收 |
-| [凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md) | Credential Service 实际注册 RPC、状态 proof、登记、吊销和吊销列表 |
+| [凭证与组织服务 SDK 应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md) | §3结构化完整链路；§4语义流程图、TS 示例及 E01—E36 场景对照 |
+| [凭证与组织服务 SDK 开发与移植指南](sdk/凭证与组织服务SDK开发与移植指南.md) | §3结构化委托／完整Verify；§4语义契约；§6.5—§6.6普通proof／CRL恢复 |
+| [凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md) | 旧版及六语义RPC、修订CAS／额度协调、签名CRL与十错误码 |
+| [语义凭证示例与验证](../examples/semantic-credential/示例使用指南.md) | E01—E36配置、CN／本地aid.com、真实浏览器／普通凭证冷恢复及证据边界 |
 | [组织服务 RPC 手册](sdk/09-组织服务RPC手册.md) | Org Service 生命周期、成员、受保护查询、审计/授权及内部/未实现方法 |
 | [Ownership 2.1 详细设计](sdk/Ownership2.1详细设计.md) | agent.md 兼容非回归原则与审查矩阵、旧 SDK owner RPC/JSONL 隔离、SDK／NS／Storage 职责；关系事实依赖`sub_aid/agent.md` 与 owner_aid 规范路径的 `owner.md`，普通名片和其 Storage 副本独立 |
 | [Ownership 2.1 TDD 分阶段实施计划](sdk/Ownership2.1-TDD分阶段实施计划.md) | 历史分阶段计划、冻结契约、HTTP 428 与错误分类、共同向量及四 SDK 实际验收范围 |
@@ -56,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 权限的最新决策 |
@@ -66,9 +70,10 @@
 | [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) | 以 Python 实现为主线的 v0.3.3 至 v0.5.24 跨语言对齐清单；0.5.24 覆盖 Ownership 无持久任务／WAL、两个 local 编排、快照一致性及语言边界，区分三端发布 0.5.23／Go 指定 0.5.22 基线与已有验证证据 |
-| [AUN CLI 手册](cli/CLI手册.md) | Python CLI 源码位置、安装运行入口、全局选项、profile 配置和主要命令集 |
+| [四 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胶水开发 |
 | [AUN Storage 架构设计](<aun-fs/AUN Storage架构设计.md>) | Storage SDK VFS、控制面/数据面分离、下载 ticket / AID Bearer 边界、当前 access token getter、类 Linux 权限、mount/symlink、服务端分层和 direct backend 上传下载 |
 | [AUN Storage SDK 存储分层设计](<aun-fs/SDK存储分层设计.md>) | Python SDK StorageVFS / StorageLowLevel 接口契约、返回类型、错误映射和跨语言对齐要求 |
 | [AUN Storage CLI-fs 命令设计](<aun-fs/CLI-fs命令设计.md>) | `aun fs` 命令语义、寻址规则、输出格式、CLI 工程改造和端到端场景 |
@@ -109,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)
@@ -132,12 +138,15 @@
 - 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)
-- Credential/Org 应用接入：凭证登记验证、成员入组／续期、撤销同步和组织转让的 TS 示例／流程图 → [应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md)
-- Credential/Org SDK 移植：共同签验、两层请求摘要、登记最终化、撤销快照及实体恢复 → [开发与移植指南](sdk/凭证与组织服务SDK开发与移植指南.md)
-- Credential Service 服务端 RPC、签名状态 proof 和吊销列表 → [凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md)
+- Credential/Org 应用接入：结构化约束、委托、登记、完整Verify与状态／CRL；语义原件、请求与业务验收 → [应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md)§3—§4
+- Credential/Org SDK 移植：结构化链、完整Verify与可信proof／CRL；语义四SDK契约与独立持久状态 → [开发与移植指南](sdk/凭证与组织服务SDK开发与移植指南.md)§3—§4／§6.5—§6.6
+- Credential/Org CLI：23个凭证命令、CN／跨域、申请／邀请、续期／转让及TS开发对照 → [CLI专题](cli/凭证与组织服务CLI开发与使用指南.md)
+- Credential Service旧版及六语义RPC、CAS／协调、签名CRL和十错误码 → [凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md)
+- 凭证／语义凭证CN测试、E01—E36配置与证据范围 → [示例指南](../examples/semantic-credential/示例使用指南.md)§3—§5；本地CN↔aid.com见分布式指南文末专项
 - Org Service 生命周期、成员、受保护查询、内部接口和未实现占位 → [组织服务 RPC 手册](sdk/09-组织服务RPC手册.md)
 - 旧 SDK owner 注册、绑定、转移、查询和解绑的隔离 RPC/Auth JSONL 兼容 → [当前协议兼容边界](protocol/Ownership协议定义2.1.md)；legacy proof、托管、代签和代上传记录 → [Ownership 管理专题](sdk/Ownership管理专题.md)
 - legacy 应用接入与旧 SDK 自动编排 → [Ownership SDK 集成指南](sdk/Ownership-SDK集成指南.md)
@@ -148,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.24 的 Ownership 简化、本地双／三身份编排、resolve 快照修复、语言与服务端兼容边界、真实发布基线及验证证据；旧 0.5.22 记录保留为历史快照 → [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)
+- 四 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>)
@@ -224,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 和前端未读数计算。
@@ -408,9 +425,9 @@ Group/Org 作为 sub 时不进入这些通用任务或审批；以其为 sub 误
 
 ### 凭证与组织服务 SDK 指南
 
-[应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md) 用 TS 与流程图说明登记验证、申请／邀请、续期、代表调用、撤销同步和组织转让；[移植指南](sdk/凭证与组织服务SDK开发与移植指南.md) 定义共同签验、请求摘要、回执、持久快照、rekey checkpoint 和跨语言验收。
+[应用集成指南](sdk/凭证与组织服务SDK应用集成指南.md)§3 L21-304以图与TS示例覆盖结构化约束、委托、登记、完整Verify、状态／CRL和恢复；§4 L305-763覆盖语义签发、正文、构包、状态、CAS、额度与恢复，附 E01—E36 对照；§5—§7 L764-954说明组织流程。[移植指南](sdk/凭证与组织服务SDK开发与移植指南.md)§3 L51-209定义结构化链与完整Verify，§4 L210-525定义语义四SDK契约，§6.5—§6.6 L651-894给出普通proof与CRL可信适配。
 
-[凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md)与[组织服务 RPC 手册](sdk/09-组织服务RPC手册.md)按两个服务当前 dispatcher 描述实际方法、请求用途和受限/未实现边界。
+[凭证服务 RPC 手册](sdk/09-凭证服务RPC手册.md)保留旧版方法，L81-187列六语义方法和十错误码；[组织服务 RPC 手册](sdk/09-组织服务RPC手册.md)继续描述Org当前dispatcher及受限／未实现边界。实际CN配置和证据强度见[语义凭证示例](../examples/semantic-credential/示例使用指南.md)§5，区分固定模型、本地双域与发布验收。
 
 ### AUN SDK 0.5.6 更新日志
 
@@ -418,15 +435,21 @@ Group/Org 作为 sub 时不进入这些通用任务或审批；以其为 sub 误
 
 ### 四 SDK 版本对齐变更清单
 
-`python/CHANGES_FOR_PARITY.md` 以 Python SDK 历史实现为主线记录 Go / TypeScript / JavaScript 的对齐要求。v0.5.24 对照 Python／TS／JS 已发布 0.5.23，Go 按指定对照 0.5.22 提交，覆盖移除 Ownership 任务与恢复、两个 local API 的专属 slot 短连接、注册当次绑定、NS 事实与 Stage／CAS、resolve 快照一致性、返回值及兼容接口差异。三端已发布的证书／Credential 缓存不重记为新增，Go 较早基线增量另列；核验四端 local、交互、cross33 断点及六项边界的已有证据，不等同全量发布回归。旧 0.5.22 及更早记录保留为历史快照。
+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 手册
 
-面向 CLI 使用者，说明 Python CLI 位于 `D:\modelunion\kite\aun-sdk-core\python\src\aun_cli`，安装后入口为 `aun`，也可通过 `python -m aun_cli` 运行。文档列出全局选项、`~/.aun/cli.toml` profile 配置、身份、P2P 消息、群组、`aun group fs`、`aun fs`、对象存储、Collab、agent.md、keys、诊断和 bench 命令集；其中 Storage VFS 覆盖 `touch/du/quota/getfacl`，Group FS 覆盖 `setfacl/getfacl` 角色 ACL，并给出常用示例和退出码。
+面向CLI使用者，列出入口、profile、身份、消息、群组、Storage／Group FS、Collab、agent.md、keys、诊断和bench；L312-347列credential 23命令、structured完整Verify、实际请求context、语义target、签名原字节、online刷新与结构化错误退出；L349-355列组织材料衔接和SDK编排。
 
 ### AUN CLI 设计文档
 
-描述当前 `python/src/aun_cli` 实现，而不是早期设想。文档覆盖 Typer 根应用、命令模块目录、`adapter.CLISession` 对 AIDStore/AUNClient 的生命周期桥接、Gateway discovery 边界、profile 解析顺序、命令注册表、各命令组职责、错误码映射和当前未实现命令边界。
+描述当前 `python/src/aun_cli` 实现，而不是早期设想。文档覆盖Typer、CLISession、Gateway discovery、profile、命令注册及职责；§7.9补齐credential facade映射、online／离线验真、文件输出与SEMANTIC错误映射，保留未实现命令边界。
+
+### 凭证与组织服务 CLI 开发与使用指南
+
+L5-121定义TS运行器、profile、三种凭证模式及23命令；L124-298说明结构化约束、委托、绑定、完整Verify与状态／CRL；L299-591说明语义原件、验收、证据、修订撤销及UsageRef；L592-798说明组织创建、申请／邀请、受保护查询、续期、转让与解散；L799-869对照CLI／TS SDK接口、错误恢复和E2E场景。
 
 ### AUN Storage 架构设计
 

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：再读目标文档章节
 
@@ -56,9 +56,14 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | legacy Ownership wire schema、agent.md、identity escrow 和 owner 授权头 | `docs/protocol/Ownership协议定义.md` L9-401；本地事件/状态与校验 L402-445 |
 | legacy 四端 ownership API、proof、托管、代上传、release 与恢复记录 | `docs/sdk/Ownership管理专题.md` L1-559 |
 | Ownership 2.1 历史格式更正、reset、任务兼容与验证记录 | `docs/audit/Ownership2.1代码审查报告.md` L1431-1470；当前不再维护 Ownership 任务／WAL，接入见两份现行指南 |
-| Credential/Org 应用 TS 与登记、入组、续期、撤销、转让图 | `docs/sdk/凭证与组织服务SDK应用集成指南.md` 1. L5-10；2. L11-14；3. L15-74；4. L75-172；5. L173-214；6. L215-247；7. L248-257；8. L258-263；9. L264-266 |
-| Credential/Org 移植 TS 与 Verify、请求摘要、持久状态／实体恢复图 | `docs/sdk/凭证与组织服务SDK开发与移植指南.md` 1. L5-15；2. L16-44；3. L45-76；4. L77-144；5. L145-186；6. L187-213；7. L214-225；8. L226-231；9. L232-242 |
-| Credential Service 实际 RPC、请求绑定、登记/吊销、持久幂等结果恢复和签名状态证明 | `docs/sdk/09-凭证服务RPC手册.md` L1-73 |
+| Credential/Org结构化约束、委托、完整Verify、状态／CRL及语义接入 | `docs/sdk/凭证与组织服务SDK应用集成指南.md` 结构化§3 L21-304；语义§4 L305-763；组织§5—§7 L764-954 |
+| Credential/Org结构化链、可信proof／CRL适配及语义四SDK契约 | `docs/sdk/凭证与组织服务SDK开发与移植指南.md` 结构化§3 L51-209；语义§4 L210-525；普通proof／CRL §6.5—§6.6 L651-894 |
+| Credential Service旧版及六语义RPC、params/result、CAS／协调、CRL与十错误码 | `docs/sdk/09-凭证服务RPC手册.md` 普通接口L1-80；语义公共约定L81-97；六RPC L98-169；错误L170-187 |
+| 语义凭证四语言示例、E01—E36及286组配置证据、模型／留存边界 | `examples/semantic-credential/示例使用指南.md` 场景L3-10；材料L11-36；真实runner／CLI／续跑L37-59；职责L60-75；验证L76-94 |
+| CLI credential 23命令、params/context/kind/domain、原字节及错误退出；组织材料衔接 | `docs/cli/CLI手册.md` L312-355；实现设计见`docs/cli/AUN-CLI设计文档.md` §7.9 |
+| Credential/Org CLI流程图与TS使用、SDK胶水开发 | `docs/cli/凭证与组织服务CLI开发与使用指南.md` 入口／23命令L5-121；凭证L122-591；组织L592-798；开发／错误／E2E L799-869 |
+| CN凭证／语义凭证独立运行及普通凭证四阶段冷恢复 | `docs/aun测试运行指南.md` L1243-1269 |
+| 语义凭证本地CN↔aid.com双权威12组专项 | `docs/aun分布式测试运行指南.md` L1453-1466 |
 | Org Service 实际生命周期/成员/凭证/审计 RPC、补偿冲突与换钥修复、内部接口及未实现占位 | `docs/sdk/09-组织服务RPC手册.md` L1-90 |
 | 本机 AUN 环境怎么选、如何核对 MySQL 命名卷/bind 与避免 Compose 混用 | `docs/aun测试运行指南.md` L9-100 |
 | `agentid.pub/agentid.cn` 本地单实例和四语言 Tester 怎么跑 | `docs/aun测试运行指南.md` L101-369、L586-1074 |
@@ -77,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 |
@@ -121,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 |
@@ -150,10 +157,11 @@ 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.24 的无持久任务 Ownership、两个 local 编排、快照修复、语言／NS 边界及已有验证记录；三端对照发布 0.5.23，Go 对照指定 0.5.22 | `python/CHANGES_FOR_PARITY.md` L13-147；旧 0.5.22 历史记录 L150-305，读缓存与测试块⑦/⑧ L235-305 |
+| 四 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-333 |
-| AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-265 |
+| AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-378 |
+| AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-279 |
 | AUN Storage 架构、SDK VFS、direct backend 数据面、类 Linux 权限和 mount/symlink | `docs/aun-fs/AUN Storage架构设计.md` L16-47、L74-120、L153-166、L192-237、L298-324 |
 | AUN Storage SDK VFS / LowLevel 接口契约和错误映射 | `docs/aun-fs/SDK存储分层设计.md` L20-112、L169-317 |
 | AUN Storage CLI `aun fs` 命令语义和输出格式 | `docs/aun-fs/CLI-fs命令设计.md` L26-61、L89-207、L279-399 |

package/_packed_docs/aun/345/210/206/345/270/203/345/274/217/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -4,7 +4,7 @@
 
 **AUN 分布式 2.0 入口：** [P0—P9 双形态验收与回滚](#aun-dist2)。该专节单独规定 2.0 的执行、证据与签收要求；以下历史单实例、三节点和双域章节保留各自适用范围，不代表 2.0 已通过。
 
-本轮跨域验收范围仅为本机 Docker 中的 `agentid.pub` ↔ `agentid.cn`。测试请求必须经本地 `kite-agentid-federation-net` 在两个本地 Kite 容器之间完成；本轮禁止运行公网测试入口、访问线上 `agentid.pub` / `agentid.cn` 服务或把公网结果计入结论。`dist-aid.com` / `dist-aid.net` 章节仅保留为独立环境参考，本轮不得启动或运行该隔离 federation，也不得将其结果计入本轮跨域结论。
+本文通用跨域章节的历史验收范围为本机 Docker 中的 `agentid.pub` ↔ `agentid.cn`，经本地 `kite-agentid-federation-net` 完成；公网与 `dist-aid.com/dist-aid.net` 的结果不能并入该历史结论。2026-10-29 凭证／语义凭证专项另使用本地 CN↔aid.com，见[文末专项](#语义凭证-cn-与-aidcom-专项)，不要求 PUB，也不代表上述其他环境已获启动或重建授权。
 
 本指南只认当前 worktree `D:\modelunion\kite`。当前分支已经包含完整的默认单实例、三节点分布式、两套双域环境、服务端源码和四语言 SDK；服务端镜像、Tester、Cross-SDK、`data-dist` 与部署包都必须从这个 worktree 生成和运行。
 
@@ -1449,3 +1449,18 @@ P0 可从现有代码、指南和部署文件开始；P1—P9 必须先取得上
 - [ ] P2 起 C8 双向形态切换通过；P1—P4/P8/P9 对应真实部署专项通过。
 - [ ] 失败、未执行、skip、缺覆盖、强退与受限项如实列明；任何必需项缺证据则阶段保持未完成。
 - [ ] 执行账本关联测试 ID、操作审计 ID、原始命令/日志、耗时、恢复/回滚和最终就绪记录；本阶段双形态验收、回滚、恢复目标版本及最终工作就绪全部通过后，仅将本阶段相关变更独立 commit 并普通 push，记录分支、远端、推送时间及结果，提交hash以Git记录和最终回复标识，不为回填自身hash新增提交，然后停止。用户线上运行后，由 Codex 审阅对应版本和运行窗口日志，记录审阅结论，再收到用户继续指令后才进入下一阶段。推送失败保留原提交重试，交付保持未完成，不重跑无影响的已通过验收。
+
+## 语义凭证 CN 与 aid.com 专项
+
+本专项使用本地 Docker 的 `agentid.cn` 与 `aid.com` 两个独立域，复用本轮已准备并验真的 CA、服务身份、MySQL／Redis 及 SDK store。它不是公网 aid.com，也不是上文 `dist-aid.com/dist-aid.net` federation；aid.net 未纳入本轮验证。不要以域名相近替换证书、服务 AID、project、网络或数据目录。
+
+| 验收维度 | 本轮覆盖 |
+| --- | --- |
+| 正文 | text、P2P message_ref 两条路径 |
+| 跨域角色 | remote-holder、remote-issuer、remote-business 三种角色安排 |
+| 登记权威 | credential.agentid.cn、credential.aid.com 分别作为真实权威，共 2×3×2＝12 组配置 |
+| 证据与入口 | [E35 场景索引](../examples/semantic-credential/scenarios.json)、[第二权威报告](../tests/cross-sdk/artifacts/semantic-cn-2f257acc/artifacts/federation-second-authority-v2-20261028/results.json)；按 verification 指向的各自报告和检查点核对 |
+
+运行仍使用同一 cross-SDK runner 和首败续跑机制。分别保存两域客户端地址、credential_service、业务 aud、可信根／历史证书和固定 policy，不将当前 holder 域自动当作所有材料的登记权威；显式跨域 SDK 参数见 [SDK 应用指南 §4](sdk/凭证与组织服务SDK应用集成指南.md#4-语义凭证接入)。本轮单域与冷恢复配置见[测试指南专项](aun测试运行指南.md#凭证与语义凭证-cn-专项)。
+
+来源核验继续检查 Compose label、镜像 ID、mount 和源版本；双方数据库和身份目录独立。若 aid.com 当前不可用，保留该配置为环境受阻，继续执行不依赖它的 CN 单域配置，不能静默回退 PUB、改为同域或计作通过。双域 12 组、节点迁移／重启、真实浏览器恢复各自留证，不据此宣布全部多节点／生产环境验收完成；结果边界见[示例指南 §5](../examples/semantic-credential/示例使用指南.md#5-本轮验证记录与边界)。

package/_packed_docs/aun/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -4,9 +4,9 @@
 > `D:\modelunion\kite\docker-deploy`，SDK 源码与测试位于
 > `D:\modelunion\kite\aun-sdk-core`。
 
-本文档说明默认 `agentid.pub` 单实例服务端、四语言 Tester、默认 cross-SDK、集成测试和 E2E 的运行方式，同时给出单实例生产包的构建与部署入口。三节点和本地 `agentid.pub/agentid.cn` 跨域 Docker 统一见分布式指南。
-
-本轮跨域验收范围仅为本地 `agentid.pub` ↔ `agentid.cn`。`dist-aid.com` / `dist-aid.net` 隔离 federation 不属于本轮跨域测试或验收结论。
+本文档说明默认 `agentid.pub` 单实例服务端、四语言 Tester、默认 cross-SDK、集成测试和 E2E 的运行方式，同时给出单实例生产包的构建与部署入口。三节点和本地 `agentid.pub/agentid.cn` 跨域 Docker 统一见分布式指南。
+
+本文通用跨域章节的历史验收范围为本地 `agentid.pub` ↔ `agentid.cn`，不含 `dist-aid.com/dist-aid.net`。2026-10-29 凭证／语义凭证专项使用 CN 单域和本地 CN↔aid.com，独立入口与证据见[文末专项](#凭证与语义凭证-cn-专项)，不依赖 PUB。
 
 ## 测试指南:
 D:\modelunion\kite\aun-sdk-core\docs\aun测试运行指南.md
@@ -191,7 +191,7 @@ JS 的真实 E2E 统一使用 `js/tests/e2e-browser`，不要把浏览器 E2E
 
 ## 一次性准备
 
-首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 12 个默认 Go 服务 binary：
+首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 12 个默认 Go 服务 binary：
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
@@ -349,7 +349,7 @@ docker compose --env-file agentid.cn/local.env --project-directory . `
   -f docker-compose.yml -f agentid.cn/docker-compose.yml config --quiet
 ```
 
-解析后的服务端数据源必须全部位于 `data-agentid-cn`。Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
+解析后的服务端数据源必须全部位于 `data-agentid-cn`。Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
 
 `agentid.cn` Tester 使用独立 project、容器名、网络和可写目录，不与 `agentid.pub` 共享 SDK 身份。单域测试可按该域 `local.env` 启动；真实双域测试不能只启动这个 Tester，完整拓扑、固定身份规则与验收顺序见分布式指南：
 
@@ -1039,7 +1039,7 @@ AID phase2 signature verification failed: sign_time ... before cert validity ...
 
 ```powershell
 docker exec kite-go-tester sh -lc "mkdir -p /workspace/go/.codex_gocache_linux /workspace/go/.codex_gotmp_linux && cd /workspace/go && /usr/local/go/bin/go test -tags integration . -run Integration -count=1 -v"
-docker exec kite-go-tester sh -lc "mkdir -p /workspace/go/.codex_gocache_linux /workspace/go/.codex_gotmp_linux && cd /workspace/go && /usr/local/go/bin/go test -tags integration . -run '^TestV2Group(SendAndPull|Ack|Bidirectional|EpochRotation)$' -count=1 -v"
+docker exec kite-go-tester sh -lc "mkdir -p /workspace/go/.codex_gocache_linux /workspace/go/.codex_gotmp_linux && cd /workspace/go && /usr/local/go/bin/go test -tags integration . -run '^TestV2Group(SendAndPull|Ack|Bidirectional|EpochRotation)$' -count=1 -v"
 ```
 
 如果需要用临时容器跑同一组用例，下面命令默认复用宿主机 `C:\go\pkg\mod` 作为只读模块缓存。Windows Git Bash 下运行时统一在命令前加 `MSYS_NO_PATHCONV=1`。
@@ -1067,14 +1067,14 @@ docker run --rm --network kite-single_kite-net `
   -e GOMODCACHE=/go/pkg/mod `
   -e GOCACHE=/workspace/go/.codex_gocache_linux `
   -e GOTMPDIR=/workspace/go/.codex_gotmp_linux `
-  golang:1.24-bookworm sh -lc "mkdir -p /workspace/go/.codex_gocache_linux /workspace/go/.codex_gotmp_linux && cd /workspace/go && /usr/local/go/bin/go test -tags integration . -run '^TestV2Group(SendAndPull|Ack|Bidirectional|EpochRotation)$' -count=1 -v"
+  golang:1.24-bookworm sh -lc "mkdir -p /workspace/go/.codex_gocache_linux /workspace/go/.codex_gotmp_linux && cd /workspace/go && /usr/local/go/bin/go test -tags integration . -run '^TestV2Group(SendAndPull|Ack|Bidirectional|EpochRotation)$' -count=1 -v"
 ```
 
 Go 当前还没有默认单实例 Docker reconnect 用例；默认单实例侧目前覆盖的是 `integration_test.go` 和 `e2e_group_test.go`。
 
 ## 分布式与双域环境
 
-三节点 `dist-agentid.pub`、本地真实域名双域 `agentid.pub/agentid.cn`、分布式 Tester 和分布式 cross-SDK 的唯一运行说明见 [AUN 分布式测试运行指南](aun分布式测试运行指南.md)。本轮跨域只执行其中的 `agentid.pub/agentid.cn` 专节。
+三节点 `dist-agentid.pub`、本地真实域名双域 `agentid.pub/agentid.cn`、分布式 Tester 和分布式 cross-SDK 的唯一运行说明见 [AUN 分布式测试运行指南](aun分布式测试运行指南.md)。本轮跨域只执行其中的 `agentid.pub/agentid.cn` 专节。
 
 主指南不再复制 federation 命令。不得继续使用旧的 `aid.com/aid.net`、`client-a/client-b`、`federation-kite-*` 或 `federation-test_federation-net`；当前权威名称均以分布式 Compose 的 `dist-*` 配置为准。
 
@@ -1175,7 +1175,7 @@ docker compose --env-file NUL -f docker-compose.build.yml build kite
 
 ### 首次安装与日常替换
 
-目标 Linux 主机先准备域专属材料（至少 CA、TLS、12 个服务 AID 和既有 MySQL 数据）。Compose 已内置可直接运行的默认值：数据根为当前目录的 `./data`，MySQL root 密码为 `root`，控制令牌为 `aun-local-control-token`，服务面令牌为 `aun-local-service-plane-token`；Issuer 固定为 `agentid.pub`。因此不创建 `.env`、不执行任何 `export`，`down` 和 `up` 也都能正常解析。
+目标 Linux 主机先准备域专属材料（至少 CA、TLS、12 个服务 AID 和既有 MySQL 数据）。Compose 已内置可直接运行的默认值：数据根为当前目录的 `./data`，MySQL root 密码为 `root`，控制令牌为 `aun-local-control-token`，服务面令牌为 `aun-local-service-plane-token`；Issuer 固定为 `agentid.pub`。因此不创建 `.env`、不执行任何 `export`，`down` 和 `up` 也都能正常解析。
 
 首次部署时，把 `bootstrap-materials.tar.gz` 解到三文件目录得到 `init.sql` 并长期保留，同时把 CA、TLS、AID 和既有运行数据放到 `./data/CA`、`./data/certs`、`./data/AIDs`、`./data/mysql`、`./data/redis` 与 `./data/kite-workspace`。然后执行：
 
@@ -1239,3 +1239,31 @@ docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL 批量写入
 - Go 当前没有默认单实例 Docker reconnect 用例；分布式和双域 reconnect 覆盖见分布式指南。
 - 浏览器版 JS SDK 的真实浏览器 E2E 优先在 `kite-js-tester` 中运行，并设置 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1`；宿主机 Playwright 仍是支持的备选入口。
 - 其余默认单实例集成/E2E 应优先在同一 Docker 网络的 Tester 内运行，以保证与服务端网络环境一致。
+
+## 凭证与语义凭证 CN 专项
+
+本专项按用户要求使用健康的 `agentid.cn` Docker 环境，PUB 数据库受阻不应成为单域前置条件。沿用现有 CN 服务身份、CA、数据库及 SDK 持久 store；不要通过 bootstrap、续签、重新注册或清库补齐测试环境。当前源码示例与 [scenarios.json](../examples/semantic-credential/scenarios.json)为入口，完整运行参数和业务适配见[示例指南 §3](../examples/semantic-credential/示例使用指南.md#3-真实场景运行与续跑)。
+
+| 项目 | 设置／核对 |
+| --- | --- |
+| 真实目标 | `credential.agentid.cn` 及 `{svc}.agentid.cn`，使用可信 CA 和 CN 固定身份 |
+| SDK agents | PYTHON_CLIENT_URL／TS_CLIENT_URL／GO_CLIENT_URL／JS_CLIENT_URL 指向已运行的真实 agent；仅运行某一子集时核对其实际角色依赖 |
+| 用例列表 | CROSS_SDK_CASES 选择同源 case 对象的完整字段，首败即停；正式清单与历史运行 ID 不同须按 verification 核对 |
+| 语义配置 | CROSS_SDK_SEMANTIC_CONFIG 指向真实 runner.json，CROSS_SDK_SOURCE_ROOT 为 aun-sdk-core 目录；host command、policy、authority 和证书必须配套 |
+| 语义续跑状态 | CROSS_SDK_SEMANTIC_STATE_DIR 固定保存原操作；ARTIFACT_DIR 为本次结果目录 |
+| 普通凭证目标 | case.credential_service 或 CROSS_SDK_CREDENTIAL_SERVICE；未指定时从签发者 AID 域推导，不再写死 PUB |
+
+运行命令为 `python -X utf8 aun-sdk-core/tests/cross-sdk/runner/run_cross_sdk_e2e.py`（仓库根目录）。已有源码／服务变更时按本指南部署要求核对制品，重建或重启前与同环境其他会话协调；本节不提供自动重建／覆盖身份的步骤。通过且不受修改影响的配置无需重跑。
+
+普通凭证冷恢复入口为 [cases.credential-cold.json](../tests/cross-sdk/cases.credential-cold.json)，使用同一 CN 配置、固定 CROSS_SDK_CREDENTIAL_COLD_STATE_DIR，按 CROSS_SDK_CREDENTIAL_COLD_MODE 分四次运行：
+
+| mode | 必须满足的阶段条件 |
+| --- | --- |
+| prepare | Python 签发并登记，TS／Go 保存完整原生凭证及初始撤销快照 |
+| revoke | 两 holder worker 已停止，使用原 issuer 撤销固定 CID，保留两 holder 的磁盘数据 |
+| restore | 启动原 holder worker，核对新 startup_uuid、原 AID／证书／store 和增量撤销同步 |
+| persisted | 再次重启原 holder，连接前已从磁盘恢复撤销证据；不重新签发、清 store 或替换身份 |
+
+每阶段 ARTIFACT_DIR 分别保存 results.json，四阶段共用同一 cold state；不省略停止／重启间隔直接循环四个 mode。相关操作只针对对应 SDK worker，不重启其他会话的服务或数据库。本轮四阶段通过证据见 [credential-cold-cn-20261029021605](../tests/cross-sdk/artifacts/semantic-cn-2f257acc/artifacts/credential-cold-cn-20261029021605/)。
+
+本轮 282 组语义＋4 组普通凭证配置、16 组组织关联、64 组主干、真实浏览器双 scope 恢复和时间／留存边界以[示例指南 §5](../examples/semantic-credential/示例使用指南.md#5-本轮验证记录与边界)为准。双域补充为本地 CN↔aid.com，见[分布式指南专项](aun分布式测试运行指南.md#语义凭证-cn-与-aidcom-专项)，不计作公网或 aid.net 验收。