@agentunion/fastaun 0.5.28 → 0.5.30

package/CHANGELOG.md

@@ -6,6 +6,47 @@
 
 ---
 
+## 0.5.30 — 未发布
+
+### 消息恢复与同步
+
+- 移除控制消息恢复的周期定时器；连接就绪时恢复一次，后续 push 按 peer／group、消息类别和持久／volatile 流触发恢复，不再周期扫描 `message.peers` 和 `group.list_my`。应用主动拉取保持原有行为。
+- 群恢复根据 `group.list_my` 返回的各流 `needs_pull` 状态选择拉取，跳过已追平的流；未返回 `streams` 时保留兼容恢复，继续恢复待确认 ACK。
+
+### Ownership 与 agent.md
+
+- 本地绑定和转移允许当前 owner、新 owner 为 `human` 或 `agent`，subaid 仍限 `agent`；继续要求不同身份及私钥，释放沿用 `releaseSubaid`。
+- 更新 Ownership frontmatter 时关闭 YAML 自动折行，使用 literal 多行字符串；保留其它字段的数据值，更新后继续执行文档校验。
+
+### Storage 与消息发送
+
+- Storage 对携带 `expected_version` 的对象写入和文件重命名先检查当前版本，不一致时返回冲突；未指定版本或显式 `force=true` 时跳过预检。预检不替代服务端原子 CAS。
+- 发送 `observer.forward` 时复制并剥离 `original` 中的 `_semantic_evidence`、`_agent_md`、`source`、`device_id`、`slot_id_full`、`proximity` 及三个 `same_*` 诊断字段；保留业务 payload，不修改原始接收对象。
+- `gateway.risk_status` 归为服务端专用 RPC，不允许应用通过 SDK 调用；保留签名风控 push 的接收与 ACK。
+
+### 版本
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.30`。
+
+## 0.5.29 — 未发布
+
+### Ownership 共识查询
+
+- `checkOwnershipConsensus(subAid?, force=false)` 改为在缓存未命中时直接向 NS 查询一次，携带 `X-AUN-Ownership-Check: 1` 和 `Cache-Control: no-cache`；替代 0.5.28 的首轮查询加非一致重查。
+- 仅复用同一 Client 实例内的 `consensus` 结果：`force=false`、本地最新观察的 agent.md ETag 未变且名片未标记 missing。不设 TTL，每个新实例首次检查目标 AID 都查询 NS；其它状态或显式 force 均重新查询。
+- 公共查询不直接读取 Storage 的 `owner.md`，返回值去除 `owner_md` 和 `owner_md_sha256`；Ownership 管理流程继续使用各自文件操作。
+- `AIDStore.resolve` 按需委托当前 Client 检查共识，不再用持久快照跳过新实例首查；保留与展示名片的 ETag／正文摘要一致性检查。
+
+### agent.md 普通上传
+
+- 上传及恢复依据新鲜 NS ownership 锁判断：未锁定时允许首次声明或修改 owner／ownership；已锁定时完整保留 `owner`、`ownership`、`ownership_proof`、`ownership_release`，允许更新正文及其它合法字段。
+- 保留上传 schema、验签、当前主体身份、原 ETag CAS 和 pending 原签名字节／关系快照；group/org 继续由对应服务核验生命周期 owner 和实体证书。
+- 配套 NS 允许普通上传保存未配对的单边声明并标记 pending／unlocked，不因此授予 Owner 权限；普通 PUT 与 Ownership Check／Stage 入口保持区分。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.29`。四端入口、缓存限制、服务依赖和已有定向验证见 [parity 0.5.29](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
+
 ## 0.5.28 — 未发布
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,47 @@
 
 ---
 
+## 0.5.30 — 未发布
+
+### 消息恢复与同步
+
+- 移除控制消息恢复的周期定时器；连接就绪时恢复一次，后续 push 按 peer／group、消息类别和持久／volatile 流触发恢复，不再周期扫描 `message.peers` 和 `group.list_my`。应用主动拉取保持原有行为。
+- 群恢复根据 `group.list_my` 返回的各流 `needs_pull` 状态选择拉取，跳过已追平的流；未返回 `streams` 时保留兼容恢复，继续恢复待确认 ACK。
+
+### Ownership 与 agent.md
+
+- 本地绑定和转移允许当前 owner、新 owner 为 `human` 或 `agent`，subaid 仍限 `agent`；继续要求不同身份及私钥，释放沿用 `releaseSubaid`。
+- 更新 Ownership frontmatter 时关闭 YAML 自动折行，使用 literal 多行字符串；保留其它字段的数据值，更新后继续执行文档校验。
+
+### Storage 与消息发送
+
+- Storage 对携带 `expected_version` 的对象写入和文件重命名先检查当前版本，不一致时返回冲突；未指定版本或显式 `force=true` 时跳过预检。预检不替代服务端原子 CAS。
+- 发送 `observer.forward` 时复制并剥离 `original` 中的 `_semantic_evidence`、`_agent_md`、`source`、`device_id`、`slot_id_full`、`proximity` 及三个 `same_*` 诊断字段；保留业务 payload，不修改原始接收对象。
+- `gateway.risk_status` 归为服务端专用 RPC，不允许应用通过 SDK 调用；保留签名风控 push 的接收与 ACK。
+
+### 版本
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.30`。
+
+## 0.5.29 — 未发布
+
+### Ownership 共识查询
+
+- `checkOwnershipConsensus(subAid?, force=false)` 改为在缓存未命中时直接向 NS 查询一次，携带 `X-AUN-Ownership-Check: 1` 和 `Cache-Control: no-cache`；替代 0.5.28 的首轮查询加非一致重查。
+- 仅复用同一 Client 实例内的 `consensus` 结果：`force=false`、本地最新观察的 agent.md ETag 未变且名片未标记 missing。不设 TTL，每个新实例首次检查目标 AID 都查询 NS；其它状态或显式 force 均重新查询。
+- 公共查询不直接读取 Storage 的 `owner.md`，返回值去除 `owner_md` 和 `owner_md_sha256`；Ownership 管理流程继续使用各自文件操作。
+- `AIDStore.resolve` 按需委托当前 Client 检查共识，不再用持久快照跳过新实例首查；保留与展示名片的 ETag／正文摘要一致性检查。
+
+### agent.md 普通上传
+
+- 上传及恢复依据新鲜 NS ownership 锁判断：未锁定时允许首次声明或修改 owner／ownership；已锁定时完整保留 `owner`、`ownership`、`ownership_proof`、`ownership_release`，允许更新正文及其它合法字段。
+- 保留上传 schema、验签、当前主体身份、原 ETag CAS 和 pending 原签名字节／关系快照；group/org 继续由对应服务核验生命周期 owner 和实体证书。
+- 配套 NS 允许普通上传保存未配对的单边声明并标记 pending／unlocked，不因此授予 Owner 权限；普通 PUT 与 Ownership Check／Stage 入口保持区分。
+
+### 版本与验证
+
+- 包配置、锁文件、运行时及相关测试版本引用统一为 `0.5.29`。四端入口、缓存限制、服务依赖和已有定向验证见 [parity 0.5.29](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。
+
 ## 0.5.28 — 未发布
 
 ### 新功能

package/_packed_docs/INDEX.md

@@ -14,7 +14,7 @@
 | [0.5.22 SDK 开发与移植指南](sdk/0.5.22-SDK开发与移植指南.md) | 后台退避、群状态、两种绑定与 Stage/CAS、消息内部消费、撤销同步、组织恢复及配套服务修复、默认读缓存、Rust 移植与验收 |
 | [0.5.24 SDK 应用集成指南](sdk/0.5.24-SDK应用集成指南.md) | 当前身份与消息接入、无持久任务 Ownership、双／三身份 local 编排、展示与文件缓存、凭证组织及升级验收 |
 | [0.5.24 SDK 开发与移植指南](sdk/0.5.24-SDK开发与移植指南.md) | 当前 peer／batch 提交、NS 事实与远端 CAS、local 短连接、观察与 PKI 缓存、持久化边界、语言差异及移植验收 |
-| [aun测试运行指南](aun测试运行指南.md) | `agentid.pub/agentid.cn` 双域本地单实例、MySQL 命名卷/bind 核验、独立固定材料与 Tester、Go 1.24、断网 cross-SDK、缓存专项首失败续跑、三文件线上镜像替换包、开箱默认配置、一次性初始化辅助包及单节点部署 |
+| [aun测试运行指南](aun测试运行指南.md) | 本机源码为真源的远程 Ubuntu Docker 同步与 SHA 校验；`agentid.pub/agentid.cn` 双域本地单实例、MySQL 命名卷/bind 核验、独立固定材料与 Tester、Go 1.24、断网 cross-SDK、缓存专项首失败续跑、三文件线上镜像替换包、开箱默认配置、一次性初始化辅助包及单节点部署 |
 | [aun公网测试运行指南](aun公网测试运行指南.md) | 可配置 issuer domain 的 Python SDK 公网 integration/E2E runner、独立身份/运行目录、TLS 与服务端公网验收衔接 |
 | [aun分布式测试运行指南](aun分布式测试运行指南.md) | 当前worktree三节点/双域、固定身份runner和Storage OSS；P0授权启动/TLS/单活放置、Tester新pycache与C2续跑；MinIO双healthy/原marker重建读回通过，旧87a09263镜像及AIO04/pool05续跑通过，双形态历史六项C2分轮累计及恢复后最终完整六项C2通过；五app正常停启持久恢复与NS材料匹配/错误0已有证；第二轮5project全15容器停用、10依赖/control/新desired/worker恢复及SQL-before-app/before-SDK一致及旧事实/继续写/post SQL已证，恢复后schema/身份材料/最终完整C2及readiness收敛已证；MinIO原marker及最终日志已通过；新e294两域升级/旧87a回滚/恢复、SQL退休、最终C2各6项、持久v3→v4读写/正ACK及MinIO/诊断通过；fresh10005两域V2/签名状态/SQL/清理及pool重复confirm闭环通过，旧日志不倒推且全窗非0；原Pool Org/Cred首FAIL及历史10004/10006证据缺口保留；57d4双形态回滚恢复/局部重启、独立SDK最终C2/持久v4→v5、03默认1DH路径/清理/严格对账与配置持久化已证，最终日志已分类并保留来源缺口，P0默认1DH有限范围本地技术验收通过，Git/线上待；本轮有限清单真实失败已修复，历史参数/来源缺口旁列；群七天保留/物理清理后续另验、当前未实施；P0 C7部署撤回/保留数据及peer ACK恢复门禁，未签收、P1—P9未开始 |
 | [分布式 AUN 节点与服务启动流程](../../extensions/services/docs/分布式AUN节点与服务启动流程.md) | control master / worker node、控制/注册/配置中心一体化、节点启动、服务启停、注册发现和配置恢复流程 |
@@ -25,6 +25,8 @@
 | [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) | 实施中：Gateway 按提交计 pending、互通/拒绝状态、手动回填、默认 observe 与 Console 状态页；不做消息 ID 去重，初始上限 5 由管理员显式配置 |
+| [陌生人拒绝协议 TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md) | 核心实现、真实单域/双域专项及浏览器验收记录见计划；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件）；观察期不测试、管理员到时手动切换属于运维后续 |
 | [跨设备已读未读方案](跨设备已读未读方案.md) | 同一 AID 多设备按话题同步已读位置；服务端按 message ID 公共顺序汇总，返回汇总 message ID 及当前设备 seq 映射，支持 P2P/Group、批量和部分会话上报 |
 | [跨设备已读未读详细设计](跨设备已读未读详细设计.md) | RPC、单条/显式空值边界、紧凑状态表、晚到位置持久回填、Group canonical 与权限版本、owner 事件路由及四端补偿 |
 | [跨设备已读未读实施计划](跨设备已读未读实施计划.md) | 按 TDD 分阶段落地服务端、状态缓存与异步批写、Gateway、四端 SDK、单域/E2E/cross-SDK/跨域测试及完成定义 |
@@ -70,7 +72,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.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 通知和风控，列出四端落点与验证边界 |
+| [四 SDK 版本对齐变更清单](../python/CHANGES_FOR_PARITY.md)；[0.5.29 应用指南](sdk/0.5.29-SDK应用集成指南.md)、[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)、[共识与上传对齐](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)；[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) | v0.3.3 至 v0.5.29 跨语言对齐清单；当前指南覆盖应用接入、NS 单次查询、无 TTL 的 ETag 缓存、resolve、上传锁／恢复和四端移植；旧版记录保留 |
 | [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胶水开发 |
@@ -105,7 +107,7 @@
 
 ### 测试与 E2E
 
-- 本机各套环境边界、MySQL 命名卷/bind 来源、默认单实例服务端、独立 SDK Tester、容器/网络/数据目录和测试命令 → [aun测试运行指南](aun测试运行指南.md)
+- 本机各套环境边界、MySQL 命名卷/bind 来源、默认单实例服务端、独立 SDK Tester、容器/网络/数据目录、远程 Ubuntu 源码同步与 SHA 校验、测试命令 → [aun测试运行指南](aun测试运行指南.md)
 - `evolagent.cn` / `agentid.pub` 等公网域的 Python SDK integration/E2E、隔离目录、TLS 和报告 → [aun公网测试运行指南](aun公网测试运行指南.md)
 - 双域 Issuer/AID/MySQL 材料校验、三文件线上镜像替换包、开箱默认值与可选生产覆盖、一次性初始化辅助包及线上单节点部署 → [aun测试运行指南](aun测试运行指南.md)
 - 当前worktree三节点/双域、固定身份runner、Storage OSS与来源核验；2.0 P0授权启动/运行失败断点、AIO端口、新pycache Tester/TLS与C2续跑、双形态/C1—C10及回滚/交付门禁；大文件仍外部OSS、小对象P0仍localfs，内部S3迁移属P2 → [aun分布式测试运行指南](aun分布式测试运行指南.md)
@@ -115,6 +117,7 @@
 - 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)
+- Gateway 陌生人 P2P 限额、双向互通状态、拒绝/屏蔽、Inbox 手动回填和 Console AID 对状态查询 → [陌生人拒绝协议详细设计](陌生人拒绝协议详细设计.md)、[TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md)
 - 同一 AID 多设备按会话话题同步已读位置、message ID 公共顺序汇总、当前设备 seq 映射、P2P/Group 批量上报与查询 → [跨设备已读未读方案](跨设备已读未读方案.md)
 - 跨设备已读未读 RPC、状态表、请求级提交、混合域部分提交、SDK 缓存及本地完成事件契约 → [跨设备已读未读详细设计](跨设备已读未读详细设计.md)
 - 跨设备已读未读 TDD 阶段、状态缓存与批写、测试矩阵、断点续跑、兼容审查和完成定义 → [跨设备已读未读实施计划](跨设备已读未读实施计划.md)
@@ -157,7 +160,8 @@
 - 四 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.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 保留原版本基线和记录。
+- 四 SDK 0.5.29 应用接入、共识输入输出、resolve、普通上传及业务服务 → [应用指南](sdk/0.5.29-SDK应用集成指南.md)；查询缓存、并发、上传恢复、NS 配套及四端落点 → [开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)；增量和已有验证见 [当前 parity](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布)。接口摘要见 [Python](../python/CHANGELOG.md)、[Go](../go/CHANGELOG.md)、[TS](../ts/CHANGELOG.md)、[JS](../js/CHANGELOG.md) CHANGELOG。
+- 四 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.28 及更早记录中的公共共识查询以 0.5.29 增量为准。
 - 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>)
@@ -241,6 +245,12 @@
 
 [风控响应与 SDK 协同方案](风控响应与SDK协同方案.md) 优先定义待实施的响应闭环：服务端先限制，支持 `risk_test_v1` 的连接协同装闸与回执，未支持端触发风险后断连暂封。规定可信作用域、RPC/托管 HTTP、签名快照与时间/版本、唯一重连、持久处罚和递增规则；Console 展示证据与各入口执行状态，带权限/CAS 解封并防止迟到策略复活。包含四 SDK、跨实例、旧端和受控公网验收；不表示识别算法或机制已上线。
 
+### 陌生人拒绝协议详细设计与实施计划
+
+[详细设计](陌生人拒绝协议详细设计.md) 定义 Gateway P2P pending 额度、双向互通豁免、接收方拒绝/屏蔽、SDK RPC、Console 状态页及手动回填。Gateway 按提交次数计额度，不做消息 ID 去重；回填 pending 取当前值与历史计数的较大值。默认 observe；`pending_limit=5` 为管理员显式初始配置及本轮环境基线。实际观察期不执行测试，管理员到时检查未知关系与超限候选后手动启用 enforce。
+
+[TDD 分阶段实施计划](陌生人拒绝协议TDD分阶段实施计划.md) 记录 Gateway 状态仓储与入口判定、手动回填、跨域探测、四端 SDK 和 Console 的实施与定向验证；真实单域/双域专项及 Console 浏览器验收记录见计划；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件）。实际观察及管理员到时手动切换属于运维后续，不纳入本轮自动验收待办。
+
 ### 跨设备已读未读方案
 
 定义同一 AID 多设备的业务已读状态模型。P2P `seq` 按设备隔离，设备按应用传入的 `topic_key` 保存最后已读 `message_id`；服务端依据消息公共顺序汇总各设备状态，查询只返回汇总 message ID 及其在当前设备上的 seq 映射。方案覆盖 P2P/Group、AID/话题/Group 过滤查询、单条/批量/部分会话上报、在线变更事件、定向消息边界、四端 SDK 和前端未读数计算。
@@ -435,9 +445,13 @@ 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.29 [应用指南](sdk/0.5.29-SDK应用集成指南.md)：接入与消息 §1—§2 L5-54、共识 §3 L55-80、resolve §4 L81-104、上传及管理 §5 L105-145、缓存／通知／业务 §6—§7 L146-167、升级 §8 L168-180；[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)：契约 §1—§2 L5-63、缓存与 resolve §3—§4 L64-94、上传恢复 §5 L95-123、四端与继承契约 §6—§7 L124-151、核查 §8 L152-164。
+
+当前 [0.5.29 parity](../python/CHANGES_FOR_PARITY.md#v0529--共识查询缓存与普通上传未发布) L15-87：公共入口与 NS 请求 L19-39、无 TTL 的 ETag 缓存及 resolve L40-47、普通上传与恢复 L48-67、NS 配套与定向验证 L68-87。四端 CHANGELOG 提供接口级摘要。
+
+历史 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 章节 L88-172。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 及更早章节保留原基线和执行记录。
+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 L173-290 统一对照 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-103：根级文档地图。
+- `docs/INDEX.md` L7-105：根级文档地图。
 
 ### Step 2：按主题读根级 Layer 2
 
-- 测试与 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。
+- 测试与 E2E：`docs/INDEX.md` L108-130。
+- 服务端 Go 化重构审查：`docs/INDEX.md` L131-134。
+- SDK 使用与协议：`docs/INDEX.md` L135-188。
+- Service Proxy 与服务暴露：`docs/INDEX.md` L189-195。
+- 诊断与可观测性：`docs/INDEX.md` L196-204。
+- E2EE 与跨语言一致性：`docs/INDEX.md` L205-213。
 
 ### Step 3：需要判断文档价值时读 Layer 3 摘要
 
-- `docs/INDEX.md` L210-502：重点文档摘要。
+- `docs/INDEX.md` L214-518：重点文档摘要。
 
 ### Step 4：再读目标文档章节
 
@@ -63,6 +63,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 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 |
+| 远程 Ubuntu Docker 的连接参数、本机源码同步、镜像构建和 SHA 校验 | `docs/aun测试运行指南.md` L1271-1284 |
 | 语义凭证本地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 |
@@ -84,6 +85,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 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 |
+| Gateway 陌生人 P2P 限额、拒绝/屏蔽、手动回填和 Console 状态查询（实施中，按提交计数） | [详细设计](陌生人拒绝协议详细设计.md) L1-231；[TDD 分阶段计划](陌生人拒绝协议TDD分阶段实施计划.md) L1-138。默认 observe，`pending_limit=5` 为管理员显式初始配置及本轮环境基线；观察期不测试、管理员到时手动切换属于运维后续，不纳入自动验收待办；Group 及旧 SDK 真实回归已通过，cross-SDK 专项 48 组合完成（实跑 45＋沿用 3，非全量 Group／SDK 套件） |
 | 跨设备 P2P/Group 按话题同步已读位置、AID 汇总、设备 seq 映射及补偿完成交付 | `docs/跨设备已读未读方案.md` L1-273 |
 | 跨设备已读未读 RPC、紧凑状态表、公共顺序、请求级提交、混合域部分提交、四端 SDK 缓存和本地完成事件 | `docs/跨设备已读未读详细设计.md` L1-209 |
 | 跨设备已读未读 TDD 阶段、迁移/批写、断点续跑、测试矩阵、历史部署记录和本轮完成定义 | `docs/跨设备已读未读实施计划.md` L1-156 |
@@ -153,12 +155,13 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 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 resolve opts、完整输入输出、frontmatter 字段/类型、按需 ownership 共识及 owner.md 快照与 TTL | `docs/sdk/06-API手册.md` L86-203；`docs/sdk/04-连接与认证.md` L233-243 |
+| 四 SDK resolve opts、frontmatter 字段／类型；当前 ownership 输出与无 TTL 缓存 | 基础解析见 `docs/sdk/06-API手册.md` L86-203、`docs/sdk/04-连接与认证.md` L233-243；当前共识变更见 `python/CHANGES_FOR_PARITY.md` L19-47 |
 | 四 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 |
+| 四 SDK 0.5.29 应用接入、共识输入输出、resolve、上传锁与恢复、四端移植 | [应用指南](sdk/0.5.29-SDK应用集成指南.md)：接入 L5-54、共识 L55-80、resolve L81-104、上传管理 L105-145、缓存／业务 L146-167、升级 L168-180；[开发与移植指南](sdk/0.5.29-SDK开发与移植指南.md)：契约 L5-63、缓存／resolve L64-94、上传恢复 L95-123、四端／继承 L124-151、核查 L152-164；parity 当前 L15-87 |
+| 历史 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 历史 L88-172，公共共识规则以 0.5.29 为准 |
+| 四 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` 历史 0.5.27 L173-290、0.5.25 L291-359、0.5.24 L360-496、0.5.22 L497-654，读缓存块⑦ L582-622／版本测试块⑧ L623-654 |
 | 群 `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 |
 | AUN Python CLI 当前实现架构、命令注册、SDK 桥接和实现边界 | `docs/cli/AUN-CLI设计文档.md` L3-279 |

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

@@ -1141,7 +1141,7 @@ docker compose --env-file agentid.pub/local.env --project-directory . -f docker-
 
 ### SDK 或测试代码变更
 
-通常不需要操作服务端，因为 Tester 挂载 SDK 源码与测试目录。Go SDK 测试会在执行 `go test` 时重新编译；Python 测试直接读取挂载源码；TypeScript/JavaScript 直接读取各自 workspace。
+通常不需要操作服务端。Tester 在本机 Docker 中可直接读取 bind mount；远程 Ubuntu 不会自动同步本机工作区，必须先按文末“远程 Ubuntu Docker 的本机源码同步”同步本机改动，再运行测试。Go SDK 测试会在执行 `go test` 时重新编译；Python 测试直接读取挂载源码；TypeScript/JavaScript 直接读取各自 workspace。
 
 只有 Tester 自身发生这些变化时才处理 Tester：Python 测试镜像依赖变化需要在独立准备阶段 rebuild `sdk-tester`；TypeScript/JavaScript 的 `package.json` 或 lockfile 变化必须先在独立准备阶段更新 Linux 依赖 volume，再重新创建对应 Tester。回到业务测试阶段后只允许复用已验证的容器和依赖，不得让 entrypoint 临时安装。
 
@@ -1267,3 +1267,20 @@ docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL 批量写入
 每阶段 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 验收。
+
+## 远程 Ubuntu Docker 的本机源码同步
+
+本节适用于默认单域、分布式、双域及 cross-SDK 使用远程 Ubuntu Docker 的情况。
+
+- Ubuntu SSH：`root@61.169.195.42`，端口 `30248`；Docker context 为 `kite-ubuntu`，远端项目目录为 `/data/kite`，Docker 数据目录为 `/data/docker`。
+- 本机 identity file：`C:\Users\ready\.ssh\id_rsa`；对应公钥 `C:\Users\ready\.ssh\id_rsa.pub` 已安装到 Ubuntu。只记录路径，不保存私钥内容，也不把私钥同步到远端。
+- Windows PowerShell 登录命令：`ssh -p 30248 -i "$env:USERPROFILE\.ssh\id_rsa" -o IdentitiesOnly=yes root@61.169.195.42`。
+- Ubuntu CN Compose 还需按顺序加载 `agentid.cn/local.env`、`agentid.cn/ubuntu.env`；后者由本机工作区维护并同步，固定远端 MySQL 镜像、健康卷、Redis 卷和 CN 子网，只用于远程 Docker，不用于本机 Docker。
+- Ubuntu PUB Compose 还要在基础与域 Compose 后加载 `agentid.pub/ubuntu-compose.yml`，并按 `local.env`、`ubuntu.env` 顺序提供变量；镜像 SHA 指向本机源码构建并同步到 Ubuntu 的镜像。
+
+- `D:\modelunion\kite` 本机工作区是唯一代码真源。所有源码、测试脚本和 Compose 改动先在本机完成；不得直接在 Ubuntu 的 `/data/kite` 或 Tester 工作区修代码。远端产生的临时修复必须先同步回本机、审阅并纳入本机工作区，再继续修改。
+- Docker context 只选择远端 Docker daemon，不同步文件。远程容器的 bind mount 路径由 Ubuntu 主机解析；本机文件即使在 Compose 中写成挂载，也不会自动出现在远端。
+- 服务端代码变更后，使用本机工作区作为 build context 构建新镜像，再部署并 recreate 目标 Ubuntu 服务。可用远程 Docker context 构建，使本机 build context 发送到 Ubuntu；也可本机 build 后传输镜像。不得只 restart 旧容器，也不得从未核验的远端冻结副本 build。
+- SDK 或测试代码变更后，只同步改动的源码和测试文件到实际 Tester bind mount 对应目录。不要覆盖远端数据库、身份材料、依赖 volume 或测试结果；`package.json` / lockfile 变化仍须走独立 Linux 依赖准备阶段，不得复制 Windows `node_modules`。
+- 每次测试前记录本机 revision、dirty 文件清单和变更文件 SHA-256；同步后逐文件比较本机 `Get-FileHash` 与 Ubuntu `sha256sum`。任一不一致、挂载源不明或镜像内容未对应本机源码时停止测试，不得把旧运行结果记到新源码版本。
+- 测试日志、结果和环境数据保留在远端；代码更新方向始终是本机到 Ubuntu。仅当确认远端有本机缺失的代码改动时，才先把内容取回本机并完成审阅，再从本机重新同步。