@agentunion/fastaun 0.5.20 → 0.5.22

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

@@ -21,8 +21,8 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 
 | 环境 | 服务端 Compose | 域名 | 持久化数据 | project / 网络 | 主要容器 |
 | --- | --- | --- | --- | --- | --- |
-| agentid.pub 本地单实例 | 根 `docker-compose.yml` + `agentid.pub/docker-compose.yml` + `agentid.pub/local.env` | `agentid.pub` | `docker-deploy/data` | `kite-single` / `kite-single_kite-net` | `kite-app`、`kite-mysql`、`kite-redis` |
-| agentid.cn 本地跨域对端 | 根 `docker-compose.yml` + `agentid.cn/docker-compose.yml` + `agentid.cn/local.env` | `agentid.cn` | `docker-deploy/data-agentid-cn` | `kite-agentid-cn-local` / `kite-agentid-cn-local_kite-net` | `kite-agentid-cn-local-*` |
+| agentid.pub 本地单实例 | 根 `docker-compose.yml` + `agentid.pub/docker-compose.yml` + `agentid.pub/local.env` | `agentid.pub` | 应用 `docker-deploy/data`；MySQL 命名卷 `org-pub-mysql-logical14-20261023-015854-855e` | `kite-single` / `kite-single_kite-net` | `kite-app`、`kite-mysql`、`kite-redis` |
+| agentid.cn 本地跨域对端 | 根 `docker-compose.yml` + `agentid.cn/docker-compose.yml` + `agentid.cn/local.env` | `agentid.cn` | 应用 `docker-deploy/data-agentid-cn`；MySQL 独立 bind `data-agentid-cn/mysql-repaired-20260903-v2` | `kite-agentid-cn-local` / `kite-agentid-cn-local_kite-net` | `kite-agentid-cn-local-*` |
 | 三节点分布式 | `D:\modelunion\kite\docker-deploy\docker-compose.distributed.yml` | `dist-agentid.pub` | `D:\modelunion\kite\docker-deploy\data-dist` | `kite-main-dist-worktree` / `kite-main-dist-worktree_kite-distributed-net` | `kite-main-dist-*` |
 | 本地真实域名双域 Docker | 两套上述单节点 Compose 均叠加 `docker-compose.agentid-federation.yml` | `agentid.pub`、`agentid.cn` | 两域各自固定数据根 | 两个独立 project，共享 `kite-agentid-federation-net` | `kite-app`、`kite-agentid-cn-local-app` 及各自 MySQL/Redis |
 | 隔离双域 federation | `D:\modelunion\kite\docker-deploy\federation-test\docker-compose.yml` | `dist-aid.com`、`dist-aid.net` | `D:\modelunion\kite\docker-deploy\federation-test\data-dist` | `kite-main-dist-federation` / `kite-main-dist-federation_federation-net` | `main-dist-federation-*`、`main-dist-client-*` |
@@ -47,7 +47,7 @@ Tester 和 cross-SDK 都不是服务端环境：
 
 | 路径 | 实际用途 | 本地测试约束 |
 | --- | --- | --- |
-| `docker-deploy/data-agentid-pub/docker-compose.yml` | 历史 `agentid.pub` 生产迁移清单 | 不得启动；当前固定数据真源是 `docker-deploy/data` |
+| `docker-deploy/data-agentid-pub/docker-compose.yml` | 历史 `agentid.pub` 生产迁移清单 | 不得启动；当前应用材料在 `docker-deploy/data`，MySQL 使用下文指定的命名卷 |
 | `docker-deploy/data-aun-pub/docker-compose.yml` | `aun.pub` 独立服务器部署材料 | 不纳入默认 `agentid.pub` 测试 |
 | `docker-deploy/evolagent.cn/`、`docker-deploy/data-evolagent-cn/docker-compose.yml` | 历史域部署材料 | 只保留历史线索；当前本地跨域对端是 `agentid.cn`，不得启动这些旧入口 |
 | `docker-deploy/app/docker-compose.yml` | 生产包展开目录或本机临时副本 | 不作为源码 worktree 的测试真源 |
@@ -55,7 +55,7 @@ Tester 和 cross-SDK 都不是服务端环境：
 
 ### 默认单实例测试前强制核验
 
-每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
+每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单核对 Issuer CA 指纹、12 个服务 AID 和原始数据库材料的 `server-uuid`；当前运行库还必须单独核对挂载类型与来源，不能把材料目录校验当作运行库校验：
 
 ```powershell
 $domain = 'agentid.pub' # 校验本地跨域对端时改为 agentid.cn
@@ -65,7 +65,7 @@ docker compose --env-file "$domain\local.env" --project-directory . `
   -f docker-compose.yml -f "$domain\docker-compose.yml" config --quiet
 ```
 
-启动后再核对运行态。下面以 `agentid.pub` 为例；`agentid.cn` 对应前缀是 `kite-agentid-cn-local`，数据根是 `data-agentid-cn`：
+启动后再核对运行态，沿用上面选择的 `$domain`：
 
 ```powershell
 function Resolve-DockerBindSource([string]$source) {
@@ -74,20 +74,28 @@ function Resolve-DockerBindSource([string]$source) {
   }
   [IO.Path]::GetFullPath($source)
 }
-$containers = docker inspect kite-app kite-mysql kite-redis |
-  ConvertFrom-Json
+$names = if ($domain -eq 'agentid.pub') { @('kite-app','kite-mysql','kite-redis') } else { @('kite-agentid-cn-local-app','kite-agentid-cn-local-mysql','kite-agentid-cn-local-redis') }
+$project = if ($domain -eq 'agentid.pub') { 'kite-single' } else { 'kite-agentid-cn-local' }
+$containers = docker inspect $names | ConvertFrom-Json
 $badProject = $containers | Where-Object {
-  $_.Config.Labels.'com.docker.compose.project' -ne 'kite-single'
+  $_.Config.Labels.'com.docker.compose.project' -ne $project
 }
 if ($badProject) { throw "混入错误 project: $($badProject.Name -join ', ')" }
-$mysqlSource = (($containers | Where-Object Name -eq '/kite-mysql').Mounts |
-  Where-Object Destination -eq '/var/lib/mysql').Source
-$expected = (Resolve-Path .\data\mysql).Path
-if ((Resolve-DockerBindSource $mysqlSource) -ine $expected) { throw "MySQL 数据根错误: $mysqlSource" }
+$mysqlMount = (($containers | Where-Object Name -eq "/$($names[1])").Mounts |
+  Where-Object Destination -eq '/var/lib/mysql')
+if ($domain -eq 'agentid.pub') {
+  if ($mysqlMount.Type -ne 'volume' -or $mysqlMount.Name -ne 'org-pub-mysql-logical14-20261023-015854-855e') { throw 'PUB MySQL 命名卷错误' }
+  docker volume inspect $mysqlMount.Name --format '{{.Mountpoint}}'
+} else {
+  $expected = (Resolve-Path .\data-agentid-cn\mysql-repaired-20260903-v2).Path
+  if ($mysqlMount.Type -ne 'bind' -or (Resolve-DockerBindSource $mysqlMount.Source) -ine $expected) { throw "CN MySQL 数据根错误: $($mysqlMount.Source)" }
+}
 ```
 
 Docker Desktop 可能把 Windows bind source 返回为 `/run/desktop/mnt/host/<盘符>/...`；上面的归一化用于避免把当前 worktree 误判成外部目录。
 
+PUB 当前命名卷的数据在 Docker Desktop 的 Linux 引擎内，`docker volume inspect org-pub-mysql-logical14-20261023-015854-855e` 显示的 Mountpoint 为 `/var/lib/docker/volumes/org-pub-mysql-logical14-20261023-015854-855e/_data`，不是 Windows 外部挂载目录。2026-10-23 从隔离恢复副本完整逻辑导出并导入该干净卷，28 个库、491 张表、2,291,976 行的结构、行数和 checksum、账户权限、消息库四个索引及冷启动核验通过，固定身份和新增业务记录一致。PUB 当前使用 MySQL 8.0.44，域 Compose 设置 `--innodb-purge-threads=1`，本轮合成 purge 负载及冷启动已通过；CN 也已按用户授权设置为 1，正常重启及参数读回通过。这是本地恢复配置，根因尚未确认。此前 25 个废弃故障及诊断卷已按用户授权删除，本轮旧故障卷仍保留，完整逻辑导出和日志保留在 `docker-deploy/test-artifacts/org-20261021/`。原 `docker-deploy/data/mysql` 不得再启动或覆盖；PUB 的域 Compose 命名卷覆盖才是运行真源，不得根据旧 `AUN_MYSQL_DATA_ROOT` 值改回目录挂载。
+
 如果机器上还残留旧 `kite-single` 混合容器，只执行一次 `docker compose --env-file NUL -f docker-compose.yml down` 清理旧容器，不能加 `-v`。不得删除 MySQL/AID 目录，也不得通过 `setup_aids.py` 或清库掩盖环境选错。
 
 ## 当前单实例验收基线
@@ -136,7 +144,7 @@ JS 的真实 E2E 统一使用 `js/tests/e2e-browser`，不要把浏览器 E2E
 - `docker-compose.yml` 是可直接上线的服务端清单，禁止把 SDK Tester、测试源码挂载或测试数据目录加回该文件；服务端与 `docker-compose.testers.yml` 必须分别启动，不能合并为同一个 Compose project。
 - 分布式与双域测试统一按分布式指南运行，主指南不维护第二套 federation 命令。
 - Windows Git Bash 运行 `docker exec` / `docker run` 且命令里包含容器内绝对路径（如 `/tests/...`、`/test/...`、`/workspace/...`）时，统一在命令前加 `MSYS_NO_PATHCONV=1`，避免 Git Bash 把容器路径错误改写成宿主机路径。
-- 默认单实例 Python Tester 使用 `AUN_TEST_AUN_PATH=/data/aun-fixed-agentid-pub`，对应宿主机 `docker-deploy/data/extended-acceptance/group-management`；这里的 Alice/Bobb/Charlie 证书与 `data/mysql` 中的活动记录配套。
+- 默认单实例 Python Tester 使用 `AUN_TEST_AUN_PATH=/data/aun-fixed-agentid-pub`，对应宿主机 `docker-deploy/data/extended-acceptance/group-management`；这里的 Alice/Bobb/Charlie 证书与 PUB 当前命名卷中从原库逻辑导入的活动记录配套。
 - **所有语言 SDK 的集成/E2E 测试必须串行运行**。即使各 Tester 使用独立本地数据目录，测试仍会复用服务端固定 AID、群、游标和消息状态；并行运行会造成相互污染。推荐按 Python → TypeScript → Go → JavaScript 的顺序依次运行。
 - 如果改了 `extensions/services` 下的服务端代码，必须重新 build Docker 镜像并重启对应容器。
 - 如果只改了各语言 SDK 源码或测试脚本，测试容器/宿主机通常都是目录挂载或直接读取，通常不需要 rebuild 镜像，直接重跑即可。
@@ -324,7 +332,7 @@ docker exec kite-python-sdk-tester sh -lc '
 - 容器内：`/data/aun-fixed-agentid-pub`
 - 宿主机：`D:\modelunion\kite\docker-deploy\data\extended-acceptance\group-management`
 
-`docker-compose.testers.yml`、默认单实例固定 AID 测试脚本和本文档都必须以这条路径为唯一真源。`data/sdk-tester-aun/single-domain/persistent` 中的同名 Alice/Bobb/Charlie 是旧证书，不能与当前 `data/mysql` 组合使用；否则登录会返回 `certificate mismatch with server record`。
+`docker-compose.testers.yml`、默认单实例固定 AID 测试脚本和本文档都必须以这条路径为唯一真源。`data/sdk-tester-aun/single-domain/persistent` 中的同名 Alice/Bobb/Charlie 是旧证书，不能与当前 PUB 命名卷中的活动记录组合使用；否则登录会返回 `certificate mismatch with server record`。
 
 如果历史目录中还残留 `single-domain/AIDs/...`，应视为旧格式脏数据，不再继续复用，也不要把其中的文件和 `persistent` 目录混拷。
 
@@ -547,6 +555,24 @@ docker logs cross-sdk-go
 docker logs cross-sdk-js
 ```
 
+#### Storage / Group FS 读缓存专项
+
+[缓存矩阵](../tests/cross-sdk/cases.storage-cache.json) 包含 16 场景 × 4 SDK；须用[独立缓存 runner](../tests/cross-sdk/runner/run_storage_cache_e2e.py)，通用 runner 不负责这些缓存断言。保持上文的 AID、网络预检变量及四个 test-control 客户端在线，在 SDK 根目录执行；现有 Compose 只挂载通用 runner，下面额外挂载专项入口并选择缓存用例：
+
+```powershell
+$env:CROSS_SDK_CASES_BASENAME = 'cases.storage-cache.json'
+$env:CROSS_SDK_CLIENTS = 'python,ts,go,js'
+$cacheRunnerPath = (Resolve-Path tests/cross-sdk/runner/run_storage_cache_e2e.py).Path
+docker compose -f tests/cross-sdk/docker-compose.cross-sdk.yml run --rm --no-deps `
+  -v "${cacheRunnerPath}:/cross-sdk/runner/run_storage_cache_e2e.py:ro" `
+  -e ARTIFACT_DIR=/artifacts/storage-cache `
+  cross-sdk-runner python /cross-sdk/runner/run_storage_cache_e2e.py
+```
+
+在最后一行追加 `--list` 只列用例、不连接服务；追加 `--from 'ts/inline-hot'` 从指定 ID（包含该用例）续跑，也可向 runner 传入环境变量 `CROSS_SDK_CACHE_FROM`（Compose 使用 `-e CROSS_SDK_CACHE_FROM=ts/inline-hot`）。runner 首失败立即停止，每次结果独立写到 `tests/cross-sdk/artifacts/storage-cache/attempt-<时间>-<随机后缀>/`，保留失败 ID 和原产物再续跑；恢复通用矩阵时将 `CROSS_SDK_CASES_BASENAME` 改回目标清单。若在其他已具备 `aiohttp` 的环境直接运行，须配置可达的 `PY_CLIENT_URL`、`TS_CLIENT_URL`、`GO_CLIENT_URL`、`JS_CLIENT_URL`，并将 `CROSS_SDK_CASES` 指向缓存清单；未设置 `ARTIFACT_DIR` 时产物默认位于专项 runner 同级的 `artifacts/storage-cache/`。
+
+补充入口：[Python Storage 缓存 E2E](../python/tests/e2e_test_storage_cache.py)、[浏览器 Storage 测试中的读缓存组](../js/tests/e2e-browser/storage.spec.ts)。这些入口的存在不代表矩阵或浏览器全套已通过；本版静态待验差异见 [parity 块⑦](../python/CHANGES_FOR_PARITY.md#块⑦-storage--group-fs-默认读缓存)。
+
 清理测试容器：保持本轮 `CROSS_SDK_*_AID`、`AUN_DOCKER_NETWORK` 和
 `EXPECTED_GATEWAY_IP` 变量仍在当前 PowerShell 会话；若已换会话，先重新执行上面的 AID
 初始化与预检初始化块。Compose 必须先完成变量插值才能执行 `down`：
@@ -1203,7 +1229,7 @@ docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL 批量写入
 
 - **Python Tester 随机 `SIGSEGV` 或标准库对象损坏**：先运行“启动 SDK Tester”一节的 `pip check` 和 100 次导入探针，并记录镜像 ID、容器退出码和服务日志。该症状发生在 SDK/RPC 调用前，不能按服务端业务失败处理；确认镜像依赖和 Docker 运行态后，只 recreate Python Tester，固定身份和本地 SQLite 数据必须保留。SDK 0.5.6 不依赖 `sqlcipher3`；若 Tester 中仍安装该原生扩展，应重建镜像移除，而不是继续围绕它补系统依赖。
 - **`message.send does not accept delivery_mode`**：SDK 新版本要求 `delivery_mode` 在 `connect()` 时配置，不能在 `message.send` 参数中传入。测试脚本中的 `”delivery_mode”: {“mode”: “fanout”}` 应从 `message.send` 调用中移除，改到 `make_client()` 或 `connect()` 参数中。
-- **固定证书有效但登录报未激活**：这不是证书格式错误。先核对 MySQL 容器的 Compose project 和 `/var/lib/mysql` mount；agentid.pub 必须指向 `docker-deploy/data/mysql`，agentid.cn 必须指向 `docker-deploy/data-agentid-cn/mysql`。
+- **固定证书有效但登录报未激活**：这不是证书格式错误。先核对 MySQL 容器的 Compose project 和 `/var/lib/mysql` mount；agentid.pub 必须为 `Type=volume`、`Name=org-pub-mysql-logical14-20261023-015854-855e`，agentid.cn 必须为 `Type=bind`、来源 `docker-deploy/data-agentid-cn/mysql-repaired-20260903-v2`。不要重新启动旧 `data/mysql` 或更换固定身份。
 - **SDK `key.json` 身份私钥解密失败**：先核对 AID、身份目录，以及构造 `AIDStore` 或 SDK 客户端时传入的 `encryption_seed` / `seed_password` 是否与生成 `key.json` 时一致。不要在身份目录中查找或补建 seed 文件。Docker 服务的只读 PEM 身份不使用 seed，应核对证书、私钥、AID 主体和挂载路径。即使确认是临时 AID，删除或重建身份材料也必须先取得用户明确同意，固定身份材料不得改动。
 
 ## 当前边界