@agentunion/fastaun-browser 0.5.19 → 0.5.20

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-88：根级文档地图。
+- `docs/INDEX.md` L7-90：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 E2E：`docs/INDEX.md` L91-111。
-- 服务端 Go 化重构审查：`docs/INDEX.md` L112-115。
-- SDK 使用与协议：`docs/INDEX.md` L116-154。
-- Service Proxy 与服务暴露：`docs/INDEX.md` L155-161。
-- 诊断与可观测性：`docs/INDEX.md` L162-170。
-- E2EE 与跨语言一致性：`docs/INDEX.md` L171-179。
+- 测试与 E2E：`docs/INDEX.md` L95-115。
+- 服务端 Go 化重构审查：`docs/INDEX.md` L116-118。
+- SDK 使用与协议：`docs/INDEX.md` L120-161。
+- Service Proxy 与服务暴露：`docs/INDEX.md` L163-168。
+- 诊断与可观测性：`docs/INDEX.md` L170-177。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L179-184。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L180-426：重点文档摘要。
+- `docs/INDEX.md` L188-440：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -29,86 +29,89 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 
 ## 常见查阅场景
 
-| 场景 | 推荐读取 |
-| --- | --- |
-| Ownership 2.1 当前文件格式，Group/Org 作为 sub 另查专属边界 | `docs/protocol/Ownership协议定义2.1.md` 1. L7-55; 2. L56-194; 3. L195-257; 4. L258-620; 5. L621-628; 6. L629-655 |
-| Ownership 2.1 七 Facade，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership-SDK编排指南2.1.md` 1. L7-38; 2. L39-258; 8. L728-780 |
-| Ownership 2.1 应用接入，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1-SDK应用集成指南.md` 1. L9-24; 2. L25-44; 3. L45-93; 7. L205-233; 8. L234-246 |
-| Ownership 2.1 开发移植，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1-SDK开发与移植指南.md` 1. L9-27; 4. L79-118; 5. L119-139; 6. L140-169; 9. L239-262; 10. L263-305; 12. L324-339 |
-| Ownership 2.1 组件职责，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1详细设计.md` 1. L7-60; 4. L159-200; 6. L232-312; 7. L313-405; 8. L406-442 |
-| Ownership 2.1 冻结实现契约，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1-TDD分阶段实施计划.md` 1. L7-51; 13.3 L430-468; 13.6 L658-688; 13.7 L689-700 |
-| Group/Org 专属 owner 生命周期、本人尾签 signer_aid、V2 授权、实体证书代际与恢复 | `docs/protocol/Ownership协议定义2.1.md` L48-55、L173-194；`docs/sdk/09-group-rpc-manual.md` L168-419 |
-| 无控制消息的 released 清理、保留 completed 历史和原 CAS | `docs/sdk/Ownership-SDK编排指南2.1.md` L728-780；`docs/sdk/Ownership2.1-SDK应用集成指南.md` L179-188；`docs/sdk/Ownership2.1-SDK开发与移植指南.md` L306-323 |
-| legacy owner/proof、不完整关系、独立 signed_at、self-owner、ownership_release 及上传/下载校验 | `docs/protocol/Ownership协议定义.md` L157-319；`docs/sdk/Ownership管理专题.md` L379-525 |
-| legacy Ownership 2.0 的 agent.md/owner.md 声明、共识及撤销契约 | `docs/agent.md/SCHEMA.md` L1-6、L157-231；`docs/protocol/Ownership协议定义2.0.md`；更早 1.0 副本 `docs/protocol/agent.md/SCHEMA.md` L1-5 |
+| 场景 | 推荐读取 |
+| --- | --- |
+| Ownership 2.1 当前双文件关系、release/清理/重绑版本、Header 投影及旧 SDK owner 隔离兼容，Group/Org 另查专属边界 | `docs/protocol/Ownership协议定义2.1.md` 兼容边界 L3-7；1. L9-57；2. L58-194；3. L195-258；4. L259-623；5. L624-631；6. L632-658 |
+| Ownership 2.1 七 Facade、双材料提交与恢复，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership-SDK编排指南2.1.md` 1. L7-38；2. L39-241；3. L242-275；4. L276-376；5. L377-410；6. L411-540；7. L541-712；8. L713-765；9. L766-807；10. L808-922 |
+| Ownership 2.1 应用接入、普通 agent 可选 owner 注册、公共签验与多签名片，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1-SDK应用集成指南.md` 1. L11-32；2. L33-52；3. L53-111；4. L112-143；5. L144-185；6. L186-224；7. L225-253；8. L254-266；9. L267-285；10. L286-300 |
+| Ownership 2.1 开发移植、旧 SDK 隔离兼容、统一签验核心与 owner.md 同会话发布 CAS，Group/Org 作为 sub 另查专属边界 | `docs/sdk/Ownership2.1-SDK开发与移植指南.md` 兼容边界 L7-9；1. L11-31；2. L32-62；3. L63-86；4. L87-129；5. L130-152；6. L153-188；7. L189-208；8. L209-257；9. L258-281；10. L282-324；11. L325-342；12. L343-358；13. L359-382 |
+| AIDStore.sign/verify、显式文件输入、连续尾块多签及 NS 表示协商 | `docs/sdk/Ownership2.1-SDK应用集成指南.md` L102-111；`docs/sdk/Ownership2.1-SDK开发与移植指南.md` L112-132、L153-188 |
+| Ownership 2.1 双文件持久化、兼容非回归矩阵与组件职责，Group/Org 另查专属边界 | `docs/sdk/Ownership2.1详细设计.md` 1. L7-76；2. L77-128；3. L129-164；4. L165-208；5. L209-239；6. L240-301；7. L302-394；8. L395-431；9. L432-463；10. L464-476 |
+| Ownership 2.1 当前实施计划及历史冻结契约/验收，Group/Org 另查专属边界 | `docs/sdk/Ownership2.1-TDD分阶段实施计划.md` 1. L7-53；2. L54-80；3. L81-103；4. L104-136；5. L137-165；6. L166-205；7. L206-237；8. L238-283；9. L284-318；10. L319-351；11. L352-370；12. L371-391；13. L392-708 |
+| Group/Org 实体主签、owner token 上传、可选附签、当前证书代际与恢复 | `docs/protocol/Ownership协议定义2.1.md` L50-57、L179-194；`docs/sdk/09-group-rpc-manual.md` L168-419 |
+| release 保持 v、清理后版本投影 0／重绑默认 1，无消息清理保留 completed 历史和原 CAS | `docs/sdk/Ownership-SDK编排指南2.1.md` L411-540、L713-765；`docs/sdk/Ownership2.1-SDK应用集成指南.md` L199-208；`docs/sdk/Ownership2.1-SDK开发与移植指南.md` L325-337 |
+| 旧 SDK 注册/绑定/转移/查询/解绑 RPC 与 Auth JSONL 隔离、旧 proof 激活及现代声明保护；legacy proof wire | `docs/protocol/Ownership协议定义2.1.md` L7、L206-233；`docs/sdk/Ownership2.1详细设计.md` L15-26；`docs/protocol/Ownership协议定义.md` L157-319；`docs/sdk/Ownership管理专题.md` L379-525 |
+| legacy Ownership 2.0 的 agent.md/owner.md 声明、共识及撤销契约 | `docs/agent.md/SCHEMA.md` L1-6、L159-233；`docs/protocol/Ownership协议定义2.0.md`；更早 1.0 副本 `docs/protocol/agent.md/SCHEMA.md` L1-5 |
 | legacy Ownership 应用快速接入、TypeScript 示例、审批和状态查询 | `docs/sdk/Ownership-SDK集成指南.md` L1-154 |
 | legacy Ownership 自动 proof、identity 托管、代上传、解绑和恢复流程图 | `docs/sdk/Ownership-SDK集成指南.md` L156-270 |
 | legacy Ownership 实现/移植、proof 验签、escrow、metadata 和 rekey 恢复 | `docs/sdk/Ownership-SDK实现指南.md` L1-154；验收入口 L156-169 |
 | legacy Ownership wire schema、agent.md、identity escrow 和 owner 授权头 | `docs/protocol/Ownership协议定义.md` L7-399；本地事件/状态与校验 L400-443 |
 | legacy 四端 ownership API、proof、托管、代上传、release 与恢复记录 | `docs/sdk/Ownership管理专题.md` L1-559 |
-| Ownership 2.1 本轮 13 项复审、逐项参考端、修复与验证边界 | `docs/audit/Ownership2.1代码审查报告.md` 九、 L230-313; 十、 L314-364; 十一、 L365-443; 十二、 L444-531（本轮问题 L456-475；最终验证及限制 L504-522） |
-| Credential/Org 应用集成：service-plane、验证/登记、admission、受保护读取、转让恢复和解散清理 | `docs/sdk/凭证与组织服务SDK应用集成指南.md` L7-18、L32-124、L126-152、L162-173 |
-| Credential/Org SDK 开发与移植：CAP、Org/Credential 请求绑定、四端 facade/RPC、checkpoint 和共同向量 | `docs/sdk/凭证与组织服务SDK开发与移植指南.md` L7-16、L18-109、L111-172、L188-209 |
-| 本机 AUN 环境怎么选、如何避免 Compose/MySQL 混用 | `docs/aun测试运行指南.md` L9-80 |
-| `agentid.pub/evolagent.cn` 本地单实例和四语言 Tester 怎么跑 | `docs/aun测试运行指南.md` L81-317、L501-827 |
+| Ownership 2.1 当前审查、旧 SDK 兼容、四端对齐、修复与验证边界 | `docs/audit/Ownership2.1代码审查报告.md` 十五、 L633-724（当前裁决 L635-646；追加问题 L647-668；四端对齐 L669-682；普通名片保护 L683-688；实际验证 L689-706；持久化/部署边界 L707-714；办结清单 L715-724）；历史九至十三节 L231-575，十四节中间状态 L577-632 |
+| Credential/Org 应用集成：service-plane、验证/登记、admission、实体主签与 owner 上传、转让恢复和解散清理 | `docs/sdk/凭证与组织服务SDK应用集成指南.md` L7-18、L32-124、L126-152、L162-173 |
+| Credential/Org SDK 开发与移植：CAP、请求绑定、四端 facade/RPC、实体多签与 checkpoint 恢复、共同向量 | `docs/sdk/凭证与组织服务SDK开发与移植指南.md` 1. L7-17；2. L18-41；3. L42-82；4. L83-112；5. L113-144；6. L145-157；7. L158-175；8. L176-189；9. L190-211 |
+| Credential Service 实际 RPC、请求绑定、登记/吊销和签名状态证明 | `docs/sdk/09-凭证服务RPC手册.md` L1-71 |
+| Org Service 实际生命周期/成员/凭证/审计 RPC、内部接口和未实现占位 | `docs/sdk/09-组织服务RPC手册.md` L1-88 |
+| 本机 AUN 环境怎么选、如何避免 Compose/MySQL 混用 | `docs/aun测试运行指南.md` L9-80 |
+| `agentid.pub/evolagent.cn` 本地单实例和四语言 Tester 怎么跑 | `docs/aun测试运行指南.md` L81-317、L501-827 |
 | `evolagent.cn` / `agentid.pub` 等公网域的 Python SDK 测试怎么跑 | `docs/aun公网测试运行指南.md` L57-157 |
 | 公网测试与本地 Docker 数据如何隔离 | `docs/aun公网测试运行指南.md` L23-65 |
 | 公网 TLS、报告与服务端 12 项验收 | `docs/aun公网测试运行指南.md` L171-227 |
-| 真实双域线上单节点与分布式测试环境如何区分 | `docs/aun分布式测试运行指南.md` L12-45 |
-| 当前 worktree 的 data-dist 接管、三节点、分布式 Tester 和来源核验怎么跑 | `docs/aun分布式测试运行指南.md` L46-484 |
-| 本地 `agentid.pub/agentid.cn` 双域 Docker、固定身份双挂载 runner、P2P/Group/Storage 验收与日志判定 | `docs/aun分布式测试运行指南.md` L491-739 |
-| 公网 `agentid.pub/agentid.cn` 固定身份注册、TLS 双域复测与线上镜像门禁 | `docs/aun分布式测试运行指南.md` L740-820 |
-| 隔离 `dist-aid.com/dist-aid.net` federation 怎么跑 | `docs/aun分布式测试运行指南.md` L821-930 |
+| 真实双域线上单节点与分布式测试环境如何区分 | `docs/aun分布式测试运行指南.md` L12-45 |
+| 当前 worktree 的 data-dist 接管、三节点、分布式 Tester 和来源核验怎么跑 | `docs/aun分布式测试运行指南.md` L46-484 |
+| 本地 `agentid.pub/agentid.cn` 双域 Docker、固定身份双挂载 runner、P2P/Group/Storage 验收与日志判定 | `docs/aun分布式测试运行指南.md` L491-739 |
+| 公网 `agentid.pub/agentid.cn` 固定身份注册、TLS 双域复测与线上镜像门禁 | `docs/aun分布式测试运行指南.md` L740-820 |
+| 隔离 `dist-aid.com/dist-aid.net` federation 怎么跑 | `docs/aun分布式测试运行指南.md` L821-930 |
 | 10 个 AUN 服务 Go/Python 调用链、RPC 字段及并发/安全/性能终审 | `docs/audit/AUN服务Go化重构精细化源码审查-20260718.md` L10-27、L28-53、L54-188、L189-205、L206-222、L223-303、L304-345、L346-357、L358-366 |
 | AUNClient 巨类拆分重构执行方案 | `docs/design/AUNClient拆分重构执行方案.md` L3-252、L253-698、L699-803 |
-| AUNClient 完全门面化与 Runtime 状态迁移细化方案 | `docs/design/AUNClient门面化与Runtime状态迁移细化方案.md` |
-| 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 |
-| 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
-| 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
-| 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |
-| TypeScript 接入跨设备已读未读、单调事件、`read_state_sync`、精确整数、映射状态和错误处理 | `docs/跨设备已读未读SDK集成指南.md` L1-207 |
-| 四端及其它语言 SDK 实现/移植、迁移重试、请求级批写、身份隔离、精确整数、本地完成事件和测试验收 | `docs/跨设备已读未读SDK实现移植指南.md` L1-331 |
-| 跨设备已读未读问题修复闭环、文档与四端 SDK 对齐、本轮隔离回归及历史 Docker 验证边界 | `docs/跨设备已读未读代码审查报告.md` L1-252 |
-| P2P device 定向发送、TTL volatile 消息、SDK 自动游标/ACK/去重与公开事件字段 | `docs/sdk/06-API手册.md`、`docs/sdk/09-message-rpc-manual.md` |
-| 当前实现的代码审查结论、P0/P1/P2 问题与跨语言差异 | `docs/消息同步与历史拉取代码审查问题清单.md` L3-207 |
-| 消息同步问题修复顺序与已排除误报 | `docs/消息同步与历史拉取代码审查问题清单.md` L208-229 |
-| SDK 中如何使用 History、理解页内发布边界、缺 sender IK 有界同步 bootstrap、应用幂等、坏密文推进和 Piggy ACK | `docs/sdk/03-核心概念.md` L60-80、`docs/sdk/05-E2EE加密通信.md` L33-56、`docs/sdk/08-最佳实践.md` L89-116、`docs/sdk/09-message-rpc-manual.md` L278-395、`docs/sdk/09-group-rpc-manual.md` L1431-1501、L1700-1767 |
-| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L145-161 |
-| 默认单实例 Docker 服务端、Tester 和常规测试命令 | `docs/aun测试运行指南.md` L171-317、L501-827 |
-| 断网依赖准备、Go 1.24 和 Tester 复用纪律 | `docs/aun测试运行指南.md` L103-144、L171-317、`docs/aun分布式测试运行指南.md` L318-484 |
-| P2P bench 标准流程、bench-pairs16、uvloop、Gateway mock 延迟和 perf-trace | `docs/aun测试运行指南.md` L584-659 |
-| 跨语言容器 E2E、internal 网络、唯一 AID 与 JS 身份轮换 | `docs/aun测试运行指南.md` L318-500 |
-| 三节点 Compose、data-dist 冷克隆、来源预检、Tester 和 cross-SDK | `docs/aun分布式测试运行指南.md` L46-484 |
-| 本地真实域名双域 Docker 测试容器、双身份 runner 和 Storage OSS 命令 | `docs/aun分布式测试运行指南.md` L491-739 |
-| 公网双域固定身份、P2P/Group/Storage 复测和线上发布包校验 | `docs/aun分布式测试运行指南.md` L740-820 |
-| 隔离双域 federation 测试容器和命令 | `docs/aun分布式测试运行指南.md` L821-930 |
-| 何时 rebuild / recreate / restart | `docs/aun测试运行指南.md` L834-900 |
-| 双域固定材料、三文件线上镜像替换包、一次性初始化辅助包、开箱默认值、可选生产覆盖和线上单节点部署 | `docs/aun测试运行指南.md` L909-965 |
-| 测试故障排查 | `docs/aun测试运行指南.md` L967-994、`docs/aun分布式测试运行指南.md` L998-1004 |
+| AUNClient 完全门面化与 Runtime 状态迁移细化方案 | `docs/design/AUNClient门面化与Runtime状态迁移细化方案.md` |
+| 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 |
+| 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
+| 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
+| 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |
+| TypeScript 接入跨设备已读未读、单调事件、`read_state_sync`、精确整数、映射状态和错误处理 | `docs/跨设备已读未读SDK集成指南.md` L1-207 |
+| 四端及其它语言 SDK 实现/移植、迁移重试、请求级批写、身份隔离、精确整数、本地完成事件和测试验收 | `docs/跨设备已读未读SDK实现移植指南.md` L1-331 |
+| 跨设备已读未读问题修复闭环、文档与四端 SDK 对齐、本轮隔离回归及历史 Docker 验证边界 | `docs/跨设备已读未读代码审查报告.md` L1-252 |
+| P2P device 定向发送、缓存缺目标设备单次刷新、TTL volatile 消息与自动 ACK | `docs/sdk/06-API手册.md`、`docs/sdk/09-message-rpc-manual.md` |
+| 当前实现的代码审查结论、P0/P1/P2 问题与跨语言差异 | `docs/消息同步与历史拉取代码审查问题清单.md` L3-207 |
+| 消息同步问题修复顺序与已排除误报 | `docs/消息同步与历史拉取代码审查问题清单.md` L208-229 |
+| SDK 中如何使用 History、namespace 单飞/最多 4 并行、缺 sender IK bootstrap、应用幂等、末页独立 ACK | `docs/sdk/03-核心概念.md` L60-80、`docs/sdk/05-E2EE加密通信.md` L33-56、`docs/sdk/08-最佳实践.md` L89-116、`docs/sdk/09-message-rpc-manual.md` L335-460、`docs/sdk/09-group-rpc-manual.md` L1431-1503、L1704-1771 |
+| 测试环境数据保护规则 | `docs/aun测试运行指南.md` L145-161 |
+| 默认单实例 Docker 服务端、Tester 和常规测试命令 | `docs/aun测试运行指南.md` L171-317、L501-827 |
+| 断网依赖准备、Go 1.24 和 Tester 复用纪律 | `docs/aun测试运行指南.md` L103-144、L171-317、`docs/aun分布式测试运行指南.md` L318-484 |
+| P2P bench 标准流程、bench-pairs16、uvloop、Gateway mock 延迟和 perf-trace | `docs/aun测试运行指南.md` L584-659 |
+| 跨语言容器 E2E、internal 网络、唯一 AID 与 JS 身份轮换 | `docs/aun测试运行指南.md` L318-500 |
+| 三节点 Compose、data-dist 冷克隆、来源预检、Tester 和 cross-SDK | `docs/aun分布式测试运行指南.md` L46-484 |
+| 本地真实域名双域 Docker 测试容器、双身份 runner 和 Storage OSS 命令 | `docs/aun分布式测试运行指南.md` L491-739 |
+| 公网双域固定身份、P2P/Group/Storage 复测和线上发布包校验 | `docs/aun分布式测试运行指南.md` L740-820 |
+| 隔离双域 federation 测试容器和命令 | `docs/aun分布式测试运行指南.md` L821-930 |
+| 何时 rebuild / recreate / restart | `docs/aun测试运行指南.md` L834-900 |
+| 双域固定材料、三文件线上镜像替换包、一次性初始化辅助包、开箱默认值、可选生产覆盖和线上单节点部署 | `docs/aun测试运行指南.md` L909-965 |
+| 测试故障排查 | `docs/aun测试运行指南.md` L967-994、`docs/aun分布式测试运行指南.md` L998-1004 |
 | 跨语言容器 E2E 背景与目标 | `docs/design/跨语言容器E2E测试方案.md` L5-35 |
 | E2EE V2 1DH/per-AID wrap 方案 | `docs/design/E2EE_V2简化为1DH加Per-AID_Wrap方案.md` |
-| E2EE V2 当前 P2P/Group 主链路 | `docs/sdk/E2EE_V2消息通信时序图.md` |
-| `protected_headers` / ProtectedHeaders 四端用法、E2EE V2 元数据 HMAC 和接收信任边界 | `docs/sdk/ProtectedHeaders用法专题.md` L1-299 |
-| Ownership 2.1 Storage 权威读取、不可复用路径修订、条件写删与上传 session | `docs/protocol/11-Storage-子协议.md` L32-40；`docs/sdk/09-storage-rpc-manual.md` L129-137 |
+| E2EE V2 当前 P2P/Group 主链路 | `docs/sdk/E2EE_V2消息通信时序图.md` |
+| `protected_headers` / ProtectedHeaders 四端用法、E2EE V2 元数据 HMAC 和接收信任边界 | `docs/sdk/ProtectedHeaders用法专题.md` L1-299 |
+| Ownership 2.1 owner.md 同会话 create_upload_session→HTTP PUT→complete_upload、expected_version 发布 CAS；object_id/version 非读取条件 | `docs/sdk/Ownership2.1-SDK开发与移植指南.md` L189-208；`docs/protocol/11-Storage-子协议.md` L32-40；`docs/sdk/09-storage-rpc-manual.md` L129-135、L565-648 |
 | legacy Ownership proof、托管持久化、owner 代签与代上传历史记录 | `docs/sdk/Ownership管理专题.md` L1-559 |
-| 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
+| 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
 | 服务端消息通信 P0 诊断面板 | `docs/design/服务端消息通信诊断面板P0方案.md` L3-73 |
-| P2P / Group 消息 inbox 统一迁移与旧表清理 | `docs/design/消息收件箱统一迁移方案.md` |
-| 离线 Push Service 目标、职责、主链路和通信平面 | `docs/superpowers/specs/2026-07-24-push-service-design-v3.md` L7-75 |
-| 离线 Push Service 协议、持久状态机、调度、生产者、安全、生命周期和验证范围 | `docs/superpowers/specs/2026-07-24-push-service-design-v3.md` L78-265 |
-| `query_sessions`、Push RPC/ACK、状态汇总、dispatch 恢复、Gateway ACL、关闭顺序、横向约束和 TDD 执行原则的冻结契约 | `docs/superpowers/契约冻结-v3-to-v4.md` L15-273 |
-| 离线 Push Service 相关文档、实施原则、Phase/Task TDD 门禁及 9 个 Phase、40 个 Task | `docs/superpowers/plans/2026-07-24-push-service-implementation-v4.md` L5-213 |
-| Python SDK 的 `connect()` 自动登记和 `client.push.register/unregister` 运行期接口 | `docs/sdk/04-连接与认证.md` L125-150、`docs/sdk/06-API手册.md` L664-689 |
-| owner relation 的 Storage 备份目录、ACL 撤销与状态查询 | `docs/sdk/09-storage-rpc-manual.md`、`docs/protocol/11-Storage-子协议.md` |
-| 终端客户端和 Push Server 如何接入，以及如何使用 Python Mock 完成隔离演示 | `docs/AUN离线推送接入与演示指南.md` L7-250 |
-| 离线推送接入验收、常见问题和生产硬门 | `docs/AUN离线推送接入与演示指南.md` L252-290 |
-| 离线推送 RPC、事件、批次 ACK、持久恢复和发布边界 | `docs/protocol/15-离线推送通知协议.md` L27-165 |
-| 离线 Push Service 隔离 PoC、Python Mock Push Server 与测试入口 | `docs/aun测试运行指南.md` L676-682 |
-| 离线 Push Service 当前发布结论与强制发布门 | `docs/AUN离线推送服务运维与发布指南.md` L5-23 |
-| 离线 Push Service 运行依赖、诊断和告警判断 | `docs/AUN离线推送服务运维与发布指南.md` L25-81 |
-| 离线 Push Service 性能基线、安全边界、隔离 PoC 灰度、回滚和已知限制 | `docs/AUN离线推送服务运维与发布指南.md` L83-141 |
+| P2P / Group 消息 inbox 统一迁移与旧表清理 | `docs/design/消息收件箱统一迁移方案.md` |
+| 离线 Push Service 目标、职责、主链路和通信平面 | `docs/superpowers/specs/2026-07-24-push-service-design-v3.md` L7-75 |
+| 离线 Push Service 协议、持久状态机、调度、生产者、安全、生命周期和验证范围 | `docs/superpowers/specs/2026-07-24-push-service-design-v3.md` L78-265 |
+| `query_sessions`、Push RPC/ACK、状态汇总、dispatch 恢复、Gateway ACL、关闭顺序、横向约束和 TDD 执行原则的冻结契约 | `docs/superpowers/契约冻结-v3-to-v4.md` L15-273 |
+| 离线 Push Service 相关文档、实施原则、Phase/Task TDD 门禁及 9 个 Phase、40 个 Task | `docs/superpowers/plans/2026-07-24-push-service-implementation-v4.md` L5-213 |
+| Python SDK 的 `connect()` 自动登记和 `client.push.register/unregister` 运行期接口 | `docs/sdk/04-连接与认证.md` L127-154、`docs/sdk/06-API手册.md` L687-714 |
+| owner relation 的 Storage 备份目录、ACL 撤销与状态查询 | `docs/sdk/09-storage-rpc-manual.md`、`docs/protocol/11-Storage-子协议.md` |
+| 终端客户端和 Push Server 如何接入，以及如何使用 Python Mock 完成隔离演示 | `docs/AUN离线推送接入与演示指南.md` L7-250 |
+| 离线推送接入验收、常见问题和生产硬门 | `docs/AUN离线推送接入与演示指南.md` L252-290 |
+| 离线推送 RPC、事件、批次 ACK、持久恢复和发布边界 | `docs/protocol/15-离线推送通知协议.md` L27-165 |
+| 离线 Push Service 隔离 PoC、Python Mock Push Server 与测试入口 | `docs/aun测试运行指南.md` L676-682 |
+| 离线 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` L55、L153、L298-301 |
 | AUN Service Proxy 总体架构、参考项目与边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L3-127 |
 | AUN Service Proxy URL、注册、隧道协议和 Web 边界 | `docs/design/AUN反向代理服务方案与TDD实施计划.md` L129-384 |
@@ -121,26 +124,26 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | test-control HTTP API | `docs/design/跨语言容器E2E测试方案.md` L160-305 |
 | 客户端容器要求和 Compose 建议 | `docs/design/跨语言容器E2E测试方案.md` L307-411 |
 | test-runner 标准用例流程 | `docs/design/跨语言容器E2E测试方案.md` L413-440 |
-| Python / TypeScript / Go / JavaScript 跨 SDK 测试矩阵与 group.index 覆盖 | `docs/aun测试运行指南.md` L103-117、L318-500 |
+| Python / TypeScript / Go / JavaScript 跨 SDK 测试矩阵与 group.index 覆盖 | `docs/aun测试运行指南.md` L103-117、L318-500 |
 | 跨语言日志、trace、身份隔离、CLI 定位 | `docs/design/跨语言容器E2E测试方案.md` L514-576 |
 | 失败分类与落地阶段 | `docs/design/跨语言容器E2E测试方案.md` L579-625 |
 | 与现有测试环境的关系和验收标准 | `docs/design/跨语言容器E2E测试方案.md` L627-665 |
-| agent.md 远程缓存目标与字段 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L5-127 |
-| agent.md ETag 透传时序图 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L129-239 |
-| agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L241-319 |
-| agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L321-370 |
-| agent.md Schema、三字段关系声明与 self-owner 单签、公开 proof 独立验签、owner 关系写入经 Auth 验证与冲突仲裁、事实摘要与 nonce/编排上下文分层、Auth 登记见证与回执、证书/关系状态分离，以及 `unbound`/`unusable`、状态 pull/push、TTL、type-change 和 Storage 权限决策 | `docs/agent.md/working/agent.md-schema与签发验签流程澄清.md` |
-| AID Schema owner/proof 可选但出现即合法、human 禁止 owner；共同签署字段为 proof_id/subject_aid/owner_aid，self-owner 仅 subject 单签，事实摘要排除 nonce、完整声明摘要绑定 proof，使用可见分号域分隔符；Auth 登记机构托管证据并签发回执，旧 AID 通过 `aid_bind` 建立 type/owner 绑定且基本登录通信不受限，公开关系声明与 Auth 关系写入边界、未解除关系唯一性检查、转移授权、`unbound`/`unusable`、Storage 内部对象权限和无专门 recovery | `docs/agent.md/working/AID类型-owner关系与换owner编排方案.md` |
-| AID owner 完整设计、Schema 可选性与 human owner 限制、三字段共同声明与 self-owner 单签、Phase 0 已确认的 P0-A01 至 P0-A12（canonical JSON、可见分号域分隔符、签名封套、proof-only/registered、Auth receipt、TTL、证书状态与关系 operation 分离、legacy/绑定中基本登录通信及按应用场景降级、旧 AID `aid_bind` 与新建 `aid_register` 的 RPC/Facade 边界、active/pending 唯一性检查、创建/绑定/换 owner/解绑、`unbound`/`unusable`、服务端/四端 SDK 改动和分阶段验收；剩余为正式 wire/RPC 文档与跨端向量落稿 | `docs/agent.md/working/AID类型-owner关系完整设计与实施计划.md` |
-| 本轮 owner 关系实施及本地 Docker、单域、cross-SDK、双域 federation 回归中发现的非任务失败、根因、修复与验证 | `docs/agent.md/working/本地Docker测试Bug清单.md` |
-| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
-| 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L94-123、`docs/sdk/06-API手册.md` L192-209、`docs/sdk/09-storage-rpc-manual.md` L621-663、`docs/sdk/09-group-rpc-manual.md` L1599-1604、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
-| 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
-| 四 SDK 0.5.19 的跨设备已读未读、Ownership 2.1、凭证与组织服务、代码/测试落点和语言差异 | `python/CHANGES_FOR_PARITY.md` L11-173 |
-| 群 `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 |
+| agent.md 远程缓存目标与字段 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L5-127 |
+| agent.md ETag 透传时序图 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L129-239 |
+| agent.md 服务端与 SDK 实现流程 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L241-319 |
+| agent.md 本地持久化、竞态和测试点 | `docs/agent.md/远程agent.md缓存与etag透传方案.md` L321-370 |
+| agent.md Schema、三字段关系声明与 self-owner 单签、公开 proof 独立验签、owner 关系写入经 Auth 验证与冲突仲裁、事实摘要与 nonce/编排上下文分层、Auth 登记见证与回执、证书/关系状态分离，以及 `unbound`/`unusable`、状态 pull/push、TTL、type-change 和 Storage 权限决策 | `docs/agent.md/working/agent.md-schema与签发验签流程澄清.md` |
+| AID Schema owner/proof 可选但出现即合法、human 禁止 owner；共同签署字段为 proof_id/subject_aid/owner_aid，self-owner 仅 subject 单签，事实摘要排除 nonce、完整声明摘要绑定 proof，使用可见分号域分隔符；Auth 登记机构托管证据并签发回执，旧 AID 通过 `aid_bind` 建立 type/owner 绑定且基本登录通信不受限，公开关系声明与 Auth 关系写入边界、未解除关系唯一性检查、转移授权、`unbound`/`unusable`、Storage 内部对象权限和无专门 recovery | `docs/agent.md/working/AID类型-owner关系与换owner编排方案.md` |
+| AID owner 完整设计、Schema 可选性与 human owner 限制、三字段共同声明与 self-owner 单签、Phase 0 已确认的 P0-A01 至 P0-A12（canonical JSON、可见分号域分隔符、签名封套、proof-only/registered、Auth receipt、TTL、证书状态与关系 operation 分离、legacy/绑定中基本登录通信及按应用场景降级、旧 AID `aid_bind` 与新建 `aid_register` 的 RPC/Facade 边界、active/pending 唯一性检查、创建/绑定/换 owner/解绑、`unbound`/`unusable`、服务端/四端 SDK 改动和分阶段验收；剩余为正式 wire/RPC 文档与跨端向量落稿 | `docs/agent.md/working/AID类型-owner关系完整设计与实施计划.md` |
+| 本轮 owner 关系实施及本地 Docker、单域、cross-SDK、双域 federation 回归中发现的非任务失败、根因、修复与验证 | `docs/agent.md/working/本地Docker测试Bug清单.md` |
+| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| 四 SDK 当前 access token getter、缓存快照语义和外部 HTTP 数据面下载凭据生命周期 | `docs/sdk/04-连接与认证.md` L96-125、`docs/sdk/06-API手册.md` L204-223、`docs/sdk/09-storage-rpc-manual.md` L610-691、`docs/sdk/09-group-rpc-manual.md` L1603-1608、`docs/aun-fs/AUN Storage架构设计.md` L153-166 |
+| 四 SDK 0.5.6 发布摘要、验签缓存、消息窗口与语言能力边界 | `docs/sdk/CHANGELOG-0.5.6.md` L1-73 |
+| 四 SDK 0.5.20 相对已发布 0.5.19 的通用多签、草稿恢复、Ownership 原件 CAS、Pull/ACK、事件与组织凭证、代码/测试落点和语言差异 | `python/CHANGES_FOR_PARITY.md` L11-169 |
+| 群 `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 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、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 |
 | AUN Storage 分阶段 TDD 计划、P1/P2/P3/P4/P5/P6 执行记录、P6 mount/umount 验收和阶段验证纪律 | `docs/aun-fs/分阶段实施计划.md` L24-37、L108-1013、L1015-1071 |

package/_packed_docs/agent.md/SCHEMA.md

@@ -5,12 +5,12 @@ Ownership 版本: 2.0.0
 
 本文保留 legacy Ownership 2.0 的文件格式与字段，不是当前 2.1 Schema。Ownership 2.0 的 ownership 声明由整个文件尾部签名保护；本文的第三方存储写删授权、sub 单方撤销及无关系版本示例仅适用于该历史版本。当前 2.1 的完整文件、角色、关系版本、owner 锁与六态结果以 [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) 为准。
 
-当前 `group/org` 是独立生命周期分支：owner 必填，无 ownership 合法，通用 ownership/proof/release 禁止；仅当前 owner 以本人证书和私钥尾签并代上传，尾部必含 `signer_aid=owner`。V2 授权、实体证书代际和恢复以 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传) 为准。下文 legacy 的 owner/ownership 成对及目标本人签名规则不得套用于当前 Group/Org。
+当前 `group/org` 是独立生命周期分支：owner 必填，无 ownership 合法，通用 ownership/proof/release 禁止；实体私钥生成主签，当前 owner 以本人 token 上传，可选 owner 附签且存在必须验证；Group 旧实体单签及实体身份上传持续兼容，Org 不开放。通用多签、实体证书代际和恢复以 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的实体主签与-owner-上传) 为准。下文 legacy 的 owner/ownership 成对及目标本人签名规则不得套用于当前 Group/Org。
 
 ## 限制
 
 - **文件大小**: 被签名 payload 最大 4KB（尾部签名块不计入）
-- **签名块大小**: 尾部签名载体最大 2KB（2048 字节，按 UTF-8 原始字节计算）
+- **签名块大小**: 全部尾签区合计最大 2KB（2048 字节，含块间及尾部空白，按 UTF-8 原始字节计算）
 - **请求读取上限**: `PUT /agent.md` 最多读取 `payload_max + signature_max` 字节；超出即返回 `413 agent_md_too_large`
 - **编码**: UTF-8
 
@@ -59,11 +59,11 @@ signature: <base64_der>
 - `timestamp` 必填，为签名时的 Unix 秒时间戳。
 - `signature` 必填，为 ECDSA P-256 / SHA-256 DER 签名的严格 Base64 表示。
 
-签名输入是签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部原始 UTF-8 字节；换行和空白不得规范化。签名块必须是文件最后一个可见块，后面只允许空白。
+允许连续多尾块。第 i 块签署文件起点至本块 `<` 前的完整原始 UTF-8 prefix；第一块仍只签正文，后续块含前序完整块与分隔空白。append 仅向已有链追加才在末字节非 LF/CR 时补 LF 并纳入新块输入；无旧块按首签要求正文以 CR/LF 结束，否则拒绝。块间及末块后只允许空白，不规范化换行。顺序受后续签名保护；移除末端块可形成有效短链，verify 只返回实际列表且必须全块验签。
 
-签名块标识使用 `<!-- AUN-SIGNATURE` 前缀，可选追加大写 TAG（例如 `<!-- AUN-SIGNATURE-AGENTMD-V2` 或 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`）。`agent.md` 的尾部签名证书必须属于 frontmatter `aid` 对应的 sub_aid；`owner.md` 的尾部签名证书必须属于 frontmatter `owner_aid`。验证方按证书指纹取得公钥，并确认签署者 AID、证书有效期和签名算法均符合要求。
+签名块标识使用 `<!-- AUN-SIGNATURE` 前缀，可选追加大写 TAG（例如 `<!-- AUN-SIGNATURE-AGENTMD-V2` 或 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`）。`agent.md` 的主签证书必须属于 frontmatter `aid` 对应的 sub_aid；`owner.md` 的主签证书必须属于 frontmatter `owner_aid`。验证方按证书指纹取得公钥，并确认签署者 AID、证书有效期和签名算法均符合要求。
 
-签名块只能包含上述四个字段；除 `public_key_fingerprint` 外均为必填；重复字段和未知字段必须拒绝。`timestamp` 最多允许比服务端时间快 300 秒，并且必须落在签署证书有效期内。服务端须在数据库或缓存写入前完成全部校验。
+各块仅允许上述四字段及 `signer_aid`；附签必填与该块证书 AID 一致的 `signer_aid`，通用容器可解析主块可选 signer_aid；普通 agent.md／owner.md 主块不输出且业务拒绝该字段，实体主块显式 signer_aid=target。除可选 `public_key_fingerprint` 外其余字段必填，重复及未知字段拒绝。TAG 为 `[A-Z0-9-]+` 字面后缀，空串无后缀，传短 tag，AUN-SIGNATURE 不作特殊选项，不授予角色或权限；证书沿用可信 resolver 按指纹获取。通用 Store document 签验不判断 YAML 业务，资源角色及授权由调用者检查。`timestamp` 最多允许比服务端时间快 300 秒，并且必须落在签署证书有效期内。服务端须在数据库或缓存写入前完成全部校验。
 
 ## YAML Schema（`agent.md` 核心字段）
 
@@ -259,8 +259,8 @@ YAML 只保留核心元数据，详细信息放在 Markdown 部分：
 解析时先检测并剥离尾部签名块，再按 YAML frontmatter 解析：
 
 ```text
-1. 定位唯一的 `<!-- AUN-SIGNATURE[-TAG]` 块。
-2. 取签名块之前的原始字节作为 payload 并验签。
+1. 定位连续 `<!-- AUN-SIGNATURE[-TAG]` 尾块并保留原字节边界。
+2. 取首块前字节为 payload，逐块验各自之前的完整 prefix。
 3. 解析 payload 的 YAML frontmatter。
 4. 对 agent.md 按 aid 校验；对 owner.md 按 owner_aid、sub_aid 和路径校验。
 ```

package/_packed_docs/agent.md//350/277/234/347/250/213agent.md/347/274/223/345/255/230/344/270/216etag/351/200/217/344/274/240/346/226/271/346/241/210.md

@@ -101,12 +101,12 @@ Gateway RPC response 和 event push 的 `_meta` 字段：
 
 ## SDK 缓存模型
 
-每个远程 AID 在内存和本地持久化记录中都维护一条 agent.md 状态。Python / TypeScript / Go 的持久化记录是 `{aun_path}/AIDs/{aid}/agentmd.json`；浏览器 JavaScript 是 IndexedDB 中的 `{aid}/agentmd.json` logical key。SDK 启动或内存 miss 时按需加载该记录。
+每个 AID 在内存和本地持久化记录中维护一条 agent.md 状态，远端已确认缓存与自有身份上传失败稿分开保存。Python / TypeScript / Go 的记录是 `{aun_path}/AIDs/{aid}/agentmd.json`；浏览器 JavaScript 是 IndexedDB 中的 `{aid}/agentmd.json` logical key。SDK 启动或内存 miss 时按需加载。
 
 | 字段 | 含义 |
 | --- | --- |
 | `aid` | 远程 AID |
-| `content` | 本地缓存的完整 `agent.md` 内容，可为空 |
+| `content` | 已确认的远端完整 `agent.md` 缓存，可为空；不用于保存尚未提交的本地失败稿 |
 | `local_etag` | 当前 `content` 对应的 ETag，由成功 GET 200 内容确认；304 复用本地内容时沿用原值 |
 | `remote_etag` | 从消息信封、RPC response `_meta` 或 event push `_meta` 观察到的远端云端 ETag |
 | `last_modified` | GET 响应的 `Last-Modified` |
@@ -114,15 +114,15 @@ Gateway RPC response 和 event push 的 `_meta` 字段：
 | `checked_at` | 最近一次 HEAD / GET 确认远端状态的本机时间 |
 | `observed_at` | 最近一次观察到远端 ETag 的本机时间 |
 | `remote_status` | `found` / `missing` / `error` |
-| `verify_status` | 最近一次 agent.md 验签结果：`ok` / `unsigned` / `invalid` 等 |
+| `verify_status` | 最近一次远端 agent.md 验签结果：`ok` / `unsigned` / `invalid` 等；不表示本地草稿已被远端验收 |
 | `verify_error` | 最近一次验签失败原因 |
 | `last_error` | 最近一次网络或 HTTP 错误 |
-
+| `local_draft_content` | 私有元数据：本地 schema／外层签名验证通过的上传候选，在首次远端 preflight 前独立保存；服务端确认对应候选提交成功后才清除 |
 状态规则：
 
 - 收到远端 ETag 时，只更新 `remote_etag` 和 `observed_at`。
-- 只有下载到内容并完成验签后，才能更新 `content`、`local_etag`、`last_modified`、`fetched_at`。
-- `remote_etag == local_etag` 时视为同步。
+- 只有下载到内容并完成验签后，才能更新 `content`、`local_etag`、`last_modified`、`fetched_at`；远端下载、同步和 ETag 观察不清除 `local_draft_content`。
+- `remote_etag == local_etag` 时仅表示远端缓存同步；返回本地草稿时必须标记 unverified、in_sync=false、source.agent_md_fetched=false。
 - `remote_etag != local_etag` 或 `content` 为空时视为需要更新；该状态可由字段推导，不要求单独存储 `stale` 字段。
 - `verify_status=invalid` 时内容可以缓存但应用层应能看到无效状态；是否拒绝展示由上层策略决定。
 
@@ -308,12 +308,12 @@ observe_remote_agent_md_etag(aid, etag, source)
 
 ### 按需下载
 
-当应用调用 `downloadAgentMd(aid)` 或 SDK 需要展示远程 agent 信息时：
+应用显式调用 `downloadAgentMd(aid)` 或 forceRefresh／本语言等效选项时读取远端权威内容并保留草稿；默认 resolve 对持有本地私钥的自有身份优先返回 `local_draft_content`，其余远程信息继续按以下缓存下载规则处理：
 
 - 可先查内存，miss 时查 agentmd.json / IndexedDB，用于展示本地已有状态。
 - `downloadAgentMd(aid)` 的远端下载请求一律发起无条件 GET，不用本地 ETag 决定请求头。
 - GET 请求不得发送 `If-None-Match` / `If-Modified-Since`。
-- 200：验签，更新内容和 `local_etag`。
+- 200：验签，更新远端 `content` 和 `local_etag`，保留独立的 `local_draft_content`。
 - 304：本地已有 content 时复用该 content；本地没有 content 时再发起一次无条件 GET。第二次仍非 2xx 时按错误返回。
 - 404：标记远端未发布 `agent.md`，不要删除已有内容，除非产品要求严格同步。
 - 网络错误：保留旧内容，记录 `fetch_error` 或更新失败时间。
@@ -334,15 +334,15 @@ agent.md 不写入 SQLite。当前 SDK 使用以下持久化位置：
 | 字段 | 说明 |
 | --- | --- |
 | `aid` | AID |
-| `content` | 正文副本；文件系统 SDK 也会单独写 `agent.md` |
+| `content` | 已确认的远端正文副本；文件系统 SDK 也会单独写 `agent.md`，不与本地失败稿混用 |
 | `local_etag` / `remote_etag` | 本地内容版本 / 远端观察版本 |
 | `last_modified` | 远端 Last-Modified |
 | `fetched_at` / `checked_at` / `observed_at` / `updated_at` | 本机时间戳 |
 | `remote_status` | `found` / `missing` / `error` |
 | `verify_status` / `verify_error` | 最近一次验签状态 |
 | `last_error` | 最近一次错误 |
-
-四个已实现 SDK 应保持字段语义一致。旧 `agent_md_cache` / `remote_agent_md_cache` SQLite 表不再作为 agent.md 缓存来源；迁移逻辑可清理旧表，但不得把新 agent.md 写回 SQLite。
+| `local_draft_content` | 私有上传候选，独立于远端缓存、ETag 和普通 pending 条件；不得作为已同步内容返回 |
+四个 SDK 保持上述语义一致：普通及 Group/Org 名片失败稿仅本地保留，重连即使发现普通名片 pending 也不隐式上传；由应用显式重试，服务端确认对应候选后才清稿。Ownership 2.1 任务、消息及 outbox 仍按原机制恢复。旧 `agent_md_cache` / `remote_agent_md_cache` SQLite 表不再作为缓存来源，不得把新 agent.md 写回 SQLite。
 
 ## 异常与竞态处理