@agentunion/fastaun 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -6,6 +6,76 @@
 
 ---
 
+## 0.5.4 — 2026-07-09
+
+### 新功能
+
+#### 通用 indexed document settings
+- `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
+- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
+- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+
+#### 入群要求附件
+- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
+- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+
+#### Group FS 角色 ACL
+- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
+- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
+- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+
+### 修复
+
+- 修复 TS 客户端 P2P pull 补洞后没有继续 drain pending 有序消息的问题，避免被挂起的后续 push 长时间不投递。
+- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
+- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+
+### 改进
+
+- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
+- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
+- SDK 包版本和运行时 `VERSION` 更新为 `0.5.4`。
+
+### 测试
+
+- 扩展 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
+- 扩展有序消息发布单元测试，覆盖 P2P push 越过空洞后由 pull 补洞并继续 drain pending 消息。
+- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
+
+---
+
+## 0.5.3 — 2026-07-07
+
+### 新功能
+
+#### Group Index / 群设置索引
+- 新增 `group.index` JSONL 索引支持，提供 `GROUP_INDEX_KEY`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex`、`GroupIndexMetaCache` 等导出能力。
+- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，支持带签名的群设置索引写入、`expected_index_etag` CAS 防并发覆盖、etag conflict 自动重试。
+- 群设置高级 facade（群规、公告、入群要求）改为通过 `updateGroupIndex` 写入 indexed settings，并支持本地 settings cache 与 entry etag 局部回源。
+- `AUNClient` 观察 RPC `_meta.group_indexes`，暴露 group index stale/fresh、远端 meta、本地 etag 与 settings cache helper。
+- Cross-SDK agent 新增 `sdk.update_group_index` 调用入口，用于跨 SDK group index 一致性测试。
+
+### 修复
+
+- 修复 P2P `message.recalled` push/pull tombstone 可能重复投递的问题，按原消息 id/seq 生成去重键并统一发布应用层 `message.recalled`。
+- 增强群撤回去重：去重键不再包含 `recalled_at`，缺少 `message_ids` 时按 `target_message_seqs` / 原消息 id / tombstone id 兜底，避免 push 与 pull tombstone 重复回调。
+- `message.v2.pull` / `group.v2.pull` 对页内消息按 `seq` 升序处理，降低服务端乱序返回导致的投递与 ack 风险。
+
+### 改进
+
+- 同一 P2P / group namespace 的 push 解密与应用层投递改为串行处理，提升在线 push 有序性。
+- 拉取 `group.index` 后先校验签名、body hash 与 etag，校验失败不更新本地缓存。
+- SDK 包版本和运行时 `VERSION` 更新为 `0.5.3`。
+
+### 测试
+
+- 新增 group index 单元测试，覆盖 JSONL canonical hash/etag、签名构建与验证、settings 合并、meta cache 持久化。
+- 新增 GroupFacade group index 单元测试，覆盖 CAS 写入、etag conflict 重试、tamper reject、settings cache 和高级 facade 写入路径。
+- 新增 group index 集成测试，覆盖 signed `group.index` 写入、裸 indexed settings 拒绝、CAS conflict 与 `updateGroupIndex` 重试。
+- 扩展 group settings、signature audit、delivery 去重相关测试，覆盖 `updateGroupIndex`、签名审计、P2P/群撤回去重与顶层撤回字段归一化。
+
+---
+
 ## 0.5.2 — 2026-07-05
 
 ### 新功能

package/_packed_docs/CHANGELOG.md

@@ -6,6 +6,76 @@
 
 ---
 
+## 0.5.4 — 2026-07-09
+
+### 新功能
+
+#### 通用 indexed document settings
+- `GroupFacade` 新增 `getSettingWithIndex()` / `updateSettingWithIndex()`，支持按 `keyName` 管理 `{keyName}.content` 与 `{keyName}.attachments` 两类文档型 indexed settings。
+- `keyName` 增加统一校验：必须匹配 `^[A-Za-z][A-Za-z0-9_-]{0,63}$`，并拒绝 `join`、`group`、`index`、`visibility` 等保留基名。
+- `getAnnouncement()` / `updateAnnouncement()` 与 `getRules()` / `updateRules()` 复用通用 indexed document setting 路径，继续通过 signed `group.index` + `expected_index_etag` CAS 写入。
+
+#### 入群要求附件
+- `getJoinRequirements()` / `updateJoinRequirements()` 支持 `attachments`，对应服务端 `join.attachments` indexed setting。
+- `join.attachments` 与公告/群规附件保持同一类 `group.fs` 引用结构，可通过 group.index 签名索引同步。
+
+#### Group FS 角色 ACL
+- 服务端 group.fs 命名空间新增受保护 `.group` 控制目录，并为 owner/admin 同步基线角色 ACL。
+- owner/admin 默认可写群自有区；admin 可管理群自有区角色 ACL。
+- `role:member` 支持按具体业务目录授予 `rw`，允许成员创建/上传，但不允许删除、重命名或移动群自有区内容。
+
+### 修复
+
+- 修复 TS 客户端 P2P pull 补洞后没有继续 drain pending 有序消息的问题，避免被挂起的后续 push 长时间不投递。
+- 修复 Storage 直接入口对群自有区删除/移动/重命名权限检查不足的问题，删除类操作统一走 `delete` 权限判定。
+- 兼容 CA 续期时 PEM 公钥与 SPKI base64 的等价比较，并兼容托管续期返回 `cert_pem` / `new_cert` 字段。
+
+### 改进
+
+- message/group WAL writer 的 `micro_wait` 支持 auto 预算模型，并扩展性能统计输出，便于观察批量写入队列深度与 pending 状态。
+- group.fs 命名空间在读取 group 记录时支持懒修复，缺失 baseline ACL 时可重试同步。
+- SDK 包版本和运行时 `VERSION` 更新为 `0.5.4`。
+
+### 测试
+
+- 扩展 GroupFacade group index 单元测试，覆盖通用 indexed document setting、`join.attachments` 缓存读取和 group.index 写入路径。
+- 扩展有序消息发布单元测试，覆盖 P2P push 越过空洞后由 pull 补洞并继续 drain pending 消息。
+- 服务端测试扩展 group settings、group.fs namespace / role ACL、Storage 群自有区权限和 CA 续期兼容性。
+
+---
+
+## 0.5.3 — 2026-07-07
+
+### 新功能
+
+#### Group Index / 群设置索引
+- 新增 `group.index` JSONL 索引支持，提供 `GROUP_INDEX_KEY`、`buildSignedGroupIndex`、`verifyGroupIndex`、`prepareGroupSettingsWithIndex`、`GroupIndexMetaCache` 等导出能力。
+- `GroupFacade` 新增 `checkGroupIndex` / `getGroupIndex` / `updateGroupIndex`，支持带签名的群设置索引写入、`expected_index_etag` CAS 防并发覆盖、etag conflict 自动重试。
+- 群设置高级 facade（群规、公告、入群要求）改为通过 `updateGroupIndex` 写入 indexed settings，并支持本地 settings cache 与 entry etag 局部回源。
+- `AUNClient` 观察 RPC `_meta.group_indexes`，暴露 group index stale/fresh、远端 meta、本地 etag 与 settings cache helper。
+- Cross-SDK agent 新增 `sdk.update_group_index` 调用入口，用于跨 SDK group index 一致性测试。
+
+### 修复
+
+- 修复 P2P `message.recalled` push/pull tombstone 可能重复投递的问题，按原消息 id/seq 生成去重键并统一发布应用层 `message.recalled`。
+- 增强群撤回去重：去重键不再包含 `recalled_at`，缺少 `message_ids` 时按 `target_message_seqs` / 原消息 id / tombstone id 兜底，避免 push 与 pull tombstone 重复回调。
+- `message.v2.pull` / `group.v2.pull` 对页内消息按 `seq` 升序处理，降低服务端乱序返回导致的投递与 ack 风险。
+
+### 改进
+
+- 同一 P2P / group namespace 的 push 解密与应用层投递改为串行处理，提升在线 push 有序性。
+- 拉取 `group.index` 后先校验签名、body hash 与 etag，校验失败不更新本地缓存。
+- SDK 包版本和运行时 `VERSION` 更新为 `0.5.3`。
+
+### 测试
+
+- 新增 group index 单元测试，覆盖 JSONL canonical hash/etag、签名构建与验证、settings 合并、meta cache 持久化。
+- 新增 GroupFacade group index 单元测试，覆盖 CAS 写入、etag conflict 重试、tamper reject、settings cache 和高级 facade 写入路径。
+- 新增 group index 集成测试，覆盖 signed `group.index` 写入、裸 indexed settings 拒绝、CAS conflict 与 `updateGroupIndex` 重试。
+- 扩展 group settings、signature audit、delivery 去重相关测试，覆盖 `updateGroupIndex`、签名审计、P2P/群撤回去重与顶层撤回字段归一化。
+
+---
+
 ## 0.5.2 — 2026-07-05
 
 ### 新功能

package/_packed_docs/INDEX.md

@@ -21,7 +21,8 @@
 | [消息收件箱统一迁移方案](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 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md) | 远程 agent.md per-AID 本地文件/IndexedDB 缓存、Gateway `_meta.agent_md_etags` 角色、消息信封 ETag 和注入节流方案 |
-| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
+| [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md) | `group.index` 签名索引、`_meta.group_indexes` 版本提示、CAS 更新、服务端缓存注入和附件稳定引用 |
+| [SDK 文档索引](sdk/INDEX.md) | SDK 使用手册、RPC 手册、E2EE、Storage VFS、Group FS 和 Collab 的子索引 |
 | [SDK 查阅指南](sdk/AUN_DOCS_GUIDE.md) | SDK 文档按行区间渐进式查阅方法 |
 | [AUN CLI 手册](cli/CLI手册.md) | Python CLI 源码位置、安装运行入口、全局选项、profile 配置和主要命令集 |
 | [AUN CLI 设计文档](cli/AUN-CLI设计文档.md) | `python/src/aun_cli` 当前实现架构、命令注册面、配置解析、SDK 桥接和实现边界 |
@@ -76,6 +77,7 @@
 - `client.notify()` 在线轻量通知、AID/群路由、跨域 federation 和不离线存储边界 → [Notify 通知方案](sdk/Notify通知方案.md)
 - 协议细节、子协议和消息格式 → [协议文档目录](protocol/)
 - agent.md 远程缓存、`remote_etag` / `local_etag`、`requester` / `peer` / `group` 角色、消息信封与 Gateway `_meta` ETag 透传 → [远程 agent.md 缓存与 ETag 透传方案](agent.md/远程agent.md缓存与etag透传方案.md)
+- `group.index` owner/admin SDK 生成签名索引、`_meta.group_indexes` 观察、`expected_index_etag` CAS、服务端正/负缓存与注入频率控制 → [群索引版本提示与附件引用方案](design/群索引版本提示与附件引用方案.md)、[SDK 文档索引](sdk/INDEX.md)
 
 ### Service Proxy 与服务暴露
 
@@ -103,9 +105,9 @@
 
 ## Layer 3：重点文档摘要
 
-### aun测试运行指南
-
-记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript 四语言测试矩阵，Python / TypeScript / Go / JavaScript 跨语言容器 E2E 的 83 用例矩阵，覆盖 P2P 明文/E2EE、群聊 pairwise 明文/E2EE、三/四成员同群矩阵、storage ticket/ACL、group.fs 与 group.fs POSIX、collab 与 collab ACL、连续消息、ack、预期失败和混合明文/E2EE 场景，另包含固定身份目录、bench-pairs16 性能身份池、uvloop bench 环境变量、Gateway 客户端 mock 网络延迟、`--perf-trace` 开关、容器名、典型命令、浏览器 E2E、双域 federation 测试、Service Proxy 单域/双域 E2E 入口、message/group WAL 回归检查和数据保护规则。
+### aun测试运行指南
+
+记录当前 AUN 服务与 SDK 在 Docker 单域、双域环境中的实际测试入口。包含 Python、TypeScript、Go、JavaScript 四语言测试矩阵和跨语言容器 E2E，覆盖 group.index 签名/CAS/meta 观察、P2P 明文/E2EE、群聊 pairwise 明文/E2EE、三/四成员同群矩阵、storage ticket/ACL、group.fs 与 group.fs POSIX、collab 与 collab ACL、连续消息、ack、预期失败和混合明文/E2EE 场景，另包含固定身份目录、bench-pairs16 性能身份池、uvloop bench 环境变量、Gateway 客户端 mock 网络延迟、`--perf-trace` 开关、容器名、典型命令、浏览器 E2E、双域 federation 测试、Service Proxy 单域/双域 E2E 入口、message/group WAL 回归检查和数据保护规则。
 
 ### AUN SDK 重构修改清单
 
@@ -147,13 +149,17 @@
 
 定义 AUN Service Proxy / AUN 服务代理的整体方案：服务侧新增 `service_proxy` 模块，`service-proxy-server` 负责公网 HTTP/HTTPS 入口、WSS 隧道、在线连接索引和协议桥接；SDK 侧 `service-proxy-client` 负责 provider 侧 embedded registry、本地 endpoint 调用和服务摘要上报。方案明确去掉 ACP GlobalRegistry/RSA 同步，URL 以 `https://proxy.{issuer}/{user_name}/{svc_name}/...` 为 canonical，`https://{user_name}.{issuer}/proxy/{svc_name}/...` 由 NameService 跳转；Web 服务推荐 host-root 模式，目录式 path-prefix 只做受限转发。文档还按 Phase 0 到 Phase 11 给出 TDD 实施步骤，记录 Phase 10 已新增宿主机进程内 7 类 HTTP/SSE/WS/NameService/Web/ACL/双域边界 E2E，以及单域和双域 Docker E2E 脚本入口；真实 Docker 执行仍需先满足模块启用、镜像包含新模块和 `/ws/client` AUN 身份 resolver 前置条件。
 
-### 远程 agent.md 缓存与 ETag 透传方案
-
+### 远程 agent.md 缓存与 ETag 透传方案
+
 定义每个远程 AID 在 SDK 内存和本地持久化记录中维护一条 agent.md 状态：Python / TypeScript / Go 使用 `{aun_path}/AIDs/{aid}/agent.md` 与 `agentmd.json`，浏览器 JavaScript 使用 IndexedDB logical key。方案规定 Gateway 在 RPC response / event push 的 `_meta.agent_md_etags` 中按 `requester`、`peer`、`group` 注入元数据，保留旧别名兼容，并通过 300 秒正缓存、60 秒负缓存和默认 60 秒发送节流控制热路径开销；Message Service V2 P2P 信封携带 `agent_md.sender`。四端 SDK 自动观察 `_meta` 和信封 `agent_md.sender/group`，写入 `remote_etag` / `last_modified`，并遵守按需下载、无条件 GET、304 兼容、竞态和跨 SDK 一致性规则。
-
-### SDK 文档索引
-
-`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE V2、API 手册、错误处理、最佳实践、payload、Service Proxy、Storage VFS、Group FS、Collab GC/reflog/reset 和各类 RPC 手册。
+
+### 群索引版本提示与附件引用方案
+
+定义 `group.index` 的 owner/admin SDK 生成、canonical JSONL、签名、`etag` / `body_hash`、`expected_index_etag` CAS、`_meta.group_indexes` 版本提示、Gateway/Message 转发边界、服务端正/负缓存、singleflight、写后失效/刷新、注入频率控制，以及 DB 保存核心设置、group.fs 保存大附件、附件稳定引用和 SDK `check/get/updateGroupIndex` 语义。
+
+### SDK 文档索引
+
+`docs/sdk/INDEX.md` 是 SDK 手册的三层子索引，覆盖快速开始、WebSocket 协议、核心概念、连接认证、E2EE V2、API 手册、错误处理、最佳实践、payload、Service Proxy、Storage VFS、Group FS、Group Index、Collab GC/reflog/reset 和各类 RPC 手册。
 
 ### Service Proxy RPC 手册
 

package/_packed_docs/KITE_DOCS_GUIDE.md

@@ -47,6 +47,7 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 服务端消息通信诊断总体方案 | `docs/design/AUN服务端消息通信诊断面板方案.md` L3-47 |
 | 服务端消息通信 P0 诊断面板 | `docs/design/服务端消息通信诊断面板P0方案.md` L3-73 |
 | P2P / Group 消息 inbox 统一迁移与旧表清理 | `docs/design/消息收件箱统一迁移方案.md` |
+| group.index 签名索引、`_meta.group_indexes`、CAS 更新和服务端缓存注入 | `docs/design/群索引版本提示与附件引用方案.md` L1-348、`docs/INDEX.md` L24、L80、L156 |
 | 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 |
@@ -58,7 +59,7 @@ 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 测试矩阵 | `docs/aun测试运行指南.md` L202-228 |
+| Python / TypeScript / Go / JavaScript 跨 SDK 测试矩阵与 group.index 覆盖 | `docs/aun测试运行指南.md` L202-229、L321-346 |
 | 跨语言日志、trace、身份隔离、CLI 定位 | `docs/design/跨语言容器E2E测试方案.md` L514-576 |
 | 失败分类与落地阶段 | `docs/design/跨语言容器E2E测试方案.md` L579-625 |
 | 与现有测试环境的关系和验收标准 | `docs/design/跨语言容器E2E测试方案.md` L627-665 |
@@ -66,7 +67,8 @@ AUN SDK Core 文档在 `docs/` 下。根级索引为 `docs/INDEX.md`，SDK API
 | 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 |
-| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| SDK API、RPC、E2EE、Storage VFS、Group FS、Collab GC/reflog/reset 使用细节 | `docs/sdk/AUN_DOCS_GUIDE.md` |
+| SDK group.index facade、`check/get/updateGroupIndex` 和 CAS 冲突处理 | `docs/sdk/06-API手册.md` L340-370、`docs/sdk/09-group-rpc-manual.md` L1015-1095、`docs/sdk/07-错误处理.md` |
 | AUN Python CLI 源码位置、安装入口、全局选项、profile 配置和主要命令集 | `docs/cli/CLI手册.md` L3-325 |
 | 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、L183-228、L289-315 |