@agentunion/fastaun-browser 0.5.3 → 0.5.6

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

@@ -0,0 +1,999 @@
+# AUN 默认单实例集成测试与 E2E 运行指南
+
+> 本文中的仓库根目录为 `D:\modelunion\kite`。单实例 Docker 环境位于
+> `D:\modelunion\kite\docker-deploy`，SDK 源码与测试位于
+> `D:\modelunion\kite\aun-sdk-core`。
+
+本文档说明默认 `agentid.pub` 单实例服务端、四语言 Tester、默认 cross-SDK、集成测试和 E2E 的运行方式，同时给出单实例生产包的构建与部署入口。三节点、本地 `agentid.pub/agentid.cn` 跨域 Docker 和隔离 `dist-aid.*` federation 统一见分布式指南。
+
+## 先选环境
+
+本机有多套 AUN Docker 环境。选择环境必须同时核对 **Compose 文件、域名、数据目录、Compose project、容器名和网络名**，不能只看 `kite-app` 是否正在运行。
+
+| 环境 | 服务端 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-*` |
+| 三节点分布式 | `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-*` |
+
+`agentid.pub` 与 `agentid.cn` 使用不同 project、容器名、私有网络、CA、服务 AID、MySQL 和 workspace。`agentid.cn` 的宿主机入口已改为 42xxx、MySQL 为 8406，因此两域可以并行；跨域测试时必须让两域同时叠加 federation overlay。该 overlay 只把两个 Kite 业务节点接入共享网络，MySQL 和 Redis 始终留在各自域内。
+
+Tester 和 cross-SDK 都不是服务端环境：
+
+| 测试运行面 | Compose | project / 网络 | 依赖的服务端 |
+| --- | --- | --- | --- |
+| agentid.pub 四语言 Tester | `docker-deploy/docker-compose.testers.yml` + `agentid.pub/local.env` | `kite-sdk-testers`，接入 `kite-single_kite-net` | agentid.pub 本地单实例 |
+| agentid.cn 四语言 Tester | `docker-deploy/docker-compose.testers.yml` + `agentid.cn/local.env` | `agentid.cn/local.env` 指定的独立 project，接入 `kite-agentid-cn-local_kite-net` | agentid.cn 本地单节点 |
+| 默认 cross-SDK | `aun-sdk-core/tests/cross-sdk/docker-compose.cross-sdk.yml` | 接入 internal `aun-cross-sdk-local` | 已额外接入该网络的默认 `kite-app` |
+| 分布式四语言 Tester | `D:\modelunion\kite\docker-deploy\docker-compose.distributed-testers.yml` | `kite-main-dist-sdk-testers`，接入 `kite-main-dist-worktree_kite-distributed-net` | 三节点分布式 |
+| 分布式 cross-SDK | `D:\modelunion\kite\aun-sdk-core\tests\cross-sdk\docker-compose.cross-sdk.distributed.yml` | `kite-main-dist-cross-sdk`，接入分布式网络 | 三节点分布式 |
+
+根目录 `docker-compose.yml` 是两域共用的单节点分布式控制模型，域目录中的同名文件只做域与宿主端口覆盖。单域命令必须同时显式传入根文件和对应域覆盖文件；跨域命令还必须叠加 `docker-compose.agentid-federation.yml`。不能只启动覆盖文件，也不能启动历史的 `evolagent.cn` 或 `data-evolagent-cn/docker-compose.yml`。
+
+本机还存在以下 Compose 材料，但都不是默认集成测试入口：
+
+| 路径 | 实际用途 | 本地测试约束 |
+| --- | --- | --- |
+| `docker-deploy/data-agentid-pub/docker-compose.yml` | 历史 `agentid.pub` 生产迁移清单 | 不得启动；当前固定数据真源是 `docker-deploy/data` |
+| `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 的测试真源 |
+| `docker-deploy/federation-test/docker-compose.yml` | 当前 worktree 的双域 federation | 只按分布式指南运行；不得引用相邻 worktree 的同名 Compose、`data-dist` 或 Tester |
+
+### 默认单实例测试前强制核验
+
+每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、10 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
+
+```powershell
+$domain = 'agentid.pub' # 校验本地跨域对端时改为 agentid.cn
+cd D:\modelunion\kite\docker-deploy
+python scripts\domain_materials.py validate "$domain\materials.json"
+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`：
+
+```powershell
+function Resolve-DockerBindSource([string]$source) {
+  if ($source -match '^/run/desktop/mnt/host/([A-Za-z])/(.*)$') {
+    $source = "$($Matches[1]):\$($Matches[2] -replace '/', '\')"
+  }
+  [IO.Path]::GetFullPath($source)
+}
+$containers = docker inspect kite-app kite-mysql kite-redis |
+  ConvertFrom-Json
+$badProject = $containers | Where-Object {
+  $_.Config.Labels.'com.docker.compose.project' -ne 'kite-single'
+}
+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" }
+```
+
+Docker Desktop 可能把 Windows bind source 返回为 `/run/desktop/mnt/host/<盘符>/...`；上面的归一化用于避免把当前 worktree 误判成外部目录。
+
+如果机器上还残留旧 `kite-single` 混合容器，只执行一次 `docker compose --env-file NUL -f docker-compose.yml down` 清理旧容器，不能加 `-v`。不得删除 MySQL/AID 目录，也不得通过 `setup_aids.py` 或清库掩盖环境选错。
+
+## 当前单实例验收基线
+
+单实例不是旧版“所有服务直接本地启动”的模式，而是分布式架构的单节点形态：一个 `control_master` 节点承载一个 Launcher，由 Launcher defer 启动 AUN 服务；控制中心、注册中心和配置中心是三个逻辑职责，物理上共同由 `aun_console` 的同一地址提供。
+
+| 文件 | 包含内容 | 使用场景 |
+| --- | --- | --- |
+| `docker-compose.yml` | `mysql`、`redis`、`kite` | 本地服务端和最小生产包的基础清单 |
+| `docker-compose.testers.yml` | Python、Go、TypeScript、JavaScript SDK Tester | 服务端启动后作为独立 Compose project 启动 |
+| `docker-compose.build.yml` | `kite`、`sdk-tester` 镜像构建定义 | 服务端或 Python Tester 镜像需要重建时 |
+
+当前验收口径：
+
+- `auth`、`ca`、`gateway`、`group`、`leaderboard`、`message`、`nameservice`、`service_proxy`、`storage`、`stream` 的默认 `module.md` 均启动 Go binary，不需要 Go overlay；Python 版本只用于人工回滚对照，不会在 Go 启动失败后自动接管。
+- 单节点默认拓扑为 `AUN_CLUSTER_ID=aun-local`、`AUN_NODE_ID=aun-local`、`AUN_NODE_ROLE=control_master`，控制、注册、配置三个 URL 默认都指向 `https://aun-console.agentid.pub:19876`。`aun_console.agentid.pub` 是服务 AID，不得当作需要 TLS 主机名校验的 DNS 地址。
+- 服务只有在 desired-state 为 `running` 且实际发送 `module.ready` 后才会注册；停止、未启动、未 ready 或不在 desired-state 中的服务不应出现在活动注册实例中。
+- 单实例不需要为每个服务或每次启动生成独立控制令牌。Compose 提供单节点控制面默认值，Launcher 负责本节点内服务生命周期与模块凭据。
+- 单实例共享同一个 MySQL 服务及 `host/port/user/password`，但每个持久化服务始终按自身历史库名确定默认数据库；`aun` 过去不是、以后也不会是公共默认库。Compose 不创建公共默认库，也不向应用注入 `KITE_DB_DATABASE` 或 `KITE_DB_DSN`；只有外部显式配置时才覆盖服务默认值。
+- 当前服务端不启动 Mail，也不包含 PostgreSQL 或 Mailpit 容器；`mail.disabled.module.md` 会覆盖 Mail manifest，Mail 测试不属于本单实例环境的默认验收范围。
+- 单实例 Storage 数据面默认使用原生 HTTPS：`https://storage.agentid.pub:9470`，复用既有证书与 CA bundle。
+- 不读取目录中的隐式 `.env`。本地域环境显式传入对应 `local.env`，无域基础命令使用 `--env-file NUL`；Linux 部署脚本只读取调用方显式导出的环境变量。
+- Python 全量验收仅跳过文件名包含 `mail` 或 `reconnect` 的测试。带 `if __name__ == "__main__"` 的脚本使用 `python <file>`，纯 pytest 文件使用 `python -m pytest -q <file>`；pytest 退出码 `5` 只表示未收集到用例，不能直接判定为服务失败。
+
+## 四语言测试矩阵
+
+当前回归口径覆盖 Python、TypeScript、Go、JavaScript 四种 SDK 形态：
+
+| 语言 | 默认单实例集成 / E2E | 双域集成 / E2E | 运行位置 |
+| --- | --- | --- | --- |
+| Python | `kite-python-sdk-tester` 容器内 `/tests/*.py` | 见分布式指南的 `main-dist-client-a` / `main-dist-client-b` | Docker 测试容器为主，少数 reconnect 脚本在宿主机 |
+| TypeScript | `kite-ts-tester` 容器内 `tests/integration`、`tests/e2e` | 见分布式指南的 `main-dist-federation-ts-tester` | Docker 测试容器为主，reconnect 由宿主机协调 |
+| Go | `kite-go-tester` 容器或临时 `golang:1.24-bookworm` 容器 | 见分布式指南的 `main-dist-federation-go-tester` | Docker 网络内运行，reconnect 由宿主机 marker 协调 |
+| JavaScript | `kite-js-tester` 容器内运行 Vitest 或 Playwright `tests/e2e-browser` | 当前无独立双域 JS 浏览器 E2E 标准命令 | 默认单实例优先使用带 Chrome 的 Docker Tester；宿主机 Playwright 可作为备选 |
+
+JS 的真实 E2E 统一使用 `js/tests/e2e-browser`，不要把浏览器 E2E 混入 `tests/integration`。`kite-js-tester` 已提供 Linux Chrome；宿主机运行时仍使用 `playwright.agentid-local.config.ts`。
+
+所有 Go 测试窗口统一使用 `golang:1.24-bookworm`，当前实测工具链为 `go1.24.13`。这只统一测试编译器，不改变 SDK 的最低兼容约束；`go/go.mod` 继续声明 `go 1.22`。
+
+## 基本原则
+
+- 不修改 `/etc/hosts`，统一使用 Docker network alias 做域名解析。
+- 不硬编码 `gateway_url`，Gateway 统一通过 `https://{issuer}/.well-known/aun-gateway` 或 `http://{issuer}/.well-known/aun-gateway` 发现。
+- 服务端对外返回的 URL 必须是 `{svc}.{issuer-domain}` 风格，不能出现 `127.0.0.1`、`localhost`、`0.0.0.0`、`::1`。
+- `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` 中的活动记录配套。
+- **所有语言 SDK 的集成/E2E 测试必须串行运行**。即使各 Tester 使用独立本地数据目录，测试仍会复用服务端固定 AID、群、游标和消息状态；并行运行会造成相互污染。推荐按 Python → TypeScript → Go → JavaScript 的顺序依次运行。
+- 如果改了 `extensions/services` 下的服务端代码，必须重新 build Docker 镜像并重启对应容器。
+- 如果只改了各语言 SDK 源码或测试脚本，测试容器/宿主机通常都是目录挂载或直接读取，通常不需要 rebuild 镜像，直接重跑即可。
+- `kite-python-sdk-tester` 使用预构建的 `aun-sdk-tester` 镜像（`Dockerfile.sdk-tester`），已内置所有 Python 测试依赖（含 `sqlcipher3`），`--force-recreate` 后无需手动安装。
+- 默认 Tester project 提供 `kite-python-sdk-tester`、`kite-go-tester`、`kite-ts-tester`、`kite-js-tester`；双域容器名和命令统一见分布式指南。
+- JavaScript 浏览器 SDK 的真实网络 E2E 优先进入 `kite-js-tester` 运行，也可以在宿主机用 Playwright 运行。
+- TS 测试容器使用独立 Docker volume 挂载 `/workspace/ts/node_modules`，避免宿主机 Windows `node_modules` 污染 Linux 容器。
+- TS/JS 使用各自独立的 Linux `node_modules` volume，不复用宿主机 Windows 原生模块。依赖准备与业务测试分阶段执行；业务测试阶段禁止访问外网，缺缓存时应停止并先完成离线依赖准备，不能让 `npm` 在测试过程中临时下载。
+- `kite-single_kite-net`、`kite-agentid-cn-local_kite-net`、`kite-agentid-federation-net` 和分布式业务网络都不是 `internal` 网络，清空代理变量也不等于物理断网。标准 Tester 依靠“复用既有容器、禁用安装器、只访问目标域名”保证业务测试不主动联网；需要硬隔离时使用本文的 `aun-cross-sdk-local` internal 网络或宿主机出站防火墙。
+- 如果改了 TS/JS 的 `package.json` 或 lockfile，必须先在允许的依赖准备环境更新对应 Linux volume，再进入断网业务测试阶段。
+- Go 优先使用仓库 `vendor` 或已有只读模块缓存；所有 Go 测试窗口统一为 `golang:1.24-bookworm`，业务测试阶段不得联网下载模块。
+- TS/Go 双域 reconnect 测试不是单纯 `docker exec` 一条命令，具体协调方式见分布式指南。
+- **测试过程必须输出即时调试信息**，以便观察执行进度和快速定位失败。各语言的做法：
+  - Python：`pytest` 加 `-v -s`（`-s` 禁止捕获 stdout/stderr），或直接 `python script.py`（脚本内 print 自动可见）。
+  - TypeScript：`vitest run` 默认输出即时日志；如需更详细，加 `--reporter=verbose`。
+  - Go：`go test -v`（`-v` 打印每个用例名称和 `t.Log` 输出）。
+  - JavaScript（Playwright）：默认 reporter 已输出即时进度；如需 stdout，加 `--reporter=list`。
+
+### 测试环境数据保护（最高优先级）
+
+**严格禁止未经用户明确同意的以下操作：**
+
+- **禁止删除或清空 AID 身份材料**：包括私钥（`*.key`）、证书（`*.crt`）、`key.json`、本地数据库（`*.db`）等。这些文件一旦丢失，对应 AID 将永久无法恢复。SDK 的 `key.json` 身份在构造 `AIDStore` 或 SDK 客户端时通过 `encryption_seed` / `seed_password` 显式传入 seed；身份目录不保存 seed，也不从 seed 文件恢复。Docker 服务身份直接只读挂载 `*.crt` 与 `*.key`，这条路径不需要 seed。
+- **禁止删除或清空持久化身份目录**：包括 `client-data/`、`data/sdk-tester-aun/`、`data/extended-acceptance/group-management/`、容器内 `/data/aun/` 和 `/data/aun-fixed-agentid-pub/` 下的任何 AID 子目录。
+- **禁止擅自执行数据库清理命令**：如 `DELETE FROM agentid_cert`、`DROP TABLE` 等。
+- **禁止擅自执行 `setup_aids.py` 重建身份**：除非用户明确要求。
+
+**可以安全执行的操作：**
+
+- 读取、查看身份文件和数据库记录（只读）
+- 运行已确认不会重建或覆盖固定身份的测试脚本
+- 查看容器日志和状态
+
+**原则：测试环境的固定身份是长期复用资产，不是一次性消耗品。任何涉及身份材料增删改的操作都必须先征得用户同意。**
+
+## 目录约定
+
+- 默认单实例 Docker 环境：`D:\modelunion\kite\docker-deploy`
+- 分布式和双域 Docker 环境：见 `docs/aun分布式测试运行指南.md`
+- AUN SDK Python 测试：`D:\modelunion\kite\aun-sdk-core\python\tests`
+- AUN SDK TypeScript 测试：`D:\modelunion\kite\aun-sdk-core\ts\tests`
+- AUN SDK Go 测试：`D:\modelunion\kite\aun-sdk-core\go`
+- AUN SDK JavaScript 测试：`D:\modelunion\kite\aun-sdk-core\js\tests`
+
+## 一次性准备
+
+首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 10 个默认 Go 服务 binary：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker compose --env-file NUL -f docker-compose.build.yml build kite sdk-tester
+```
+
+镜像构建属于独立依赖准备阶段。断网业务测试阶段如果本机没有完整基础镜像和构建缓存，不得临时执行构建并访问外网；应停止测试并先准备离线镜像。
+
+`aun-sdk-tester` 镜像（`Dockerfile.sdk-tester`）已内置所有 Python 测试依赖（含 `sqlcipher3`）。正常情况下，`kite-python-sdk-tester` 启动后即可直接运行测试，无需手动安装。
+
+构建后分别校验服务端和 Tester Compose。第一条只能列出 `mysql`、`redis`、`kite`；第二条只能列出四个 Tester，不能包含服务端服务：
+
+```powershell
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.yml -f agentid.pub/docker-compose.yml config --services
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.testers.yml config --services
+```
+
+如果只是重启默认服务容器 `kite`，而没有重建 Tester，不需要重新安装依赖。使用预构建的 `aun-sdk-tester` 镜像时，即使重新创建 Python Tester 也无需手动补依赖，因为依赖已烘焙在镜像中；TS/JS Tester 仍必须遵守后文的离线依赖准备规则。
+
+## 默认单实例环境
+
+### 启动服务端
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker image inspect docker-deploy-kite:latest mysql:8.0 redis:7-alpine | Out-Null
+if ($LASTEXITCODE -ne 0) { throw '默认服务端镜像未完成离线准备，停止测试' }
+python scripts\domain_materials.py validate agentid.pub\materials.json
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.yml -f agentid.pub/docker-compose.yml up -d
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.yml -f agentid.pub/docker-compose.yml ps
+```
+
+这一步只启动 `kite-mysql`、`kite-redis`、`kite-app`，不会启动任何 SDK Tester。`kite-app` 内部的 Launcher 按 desired-state defer 加载 AUN 服务，10 个已 Go 化服务使用 Go 版本启动。
+
+单节点三中心与数据库默认值在基础 Compose 中，域名、数据根、project 和节点标识由 `agentid.pub/local.env` 固定：
+
+| 配置 | 默认值或规则 |
+| --- | --- |
+| 控制中心 | `AUN_CONTROL_BASE_URL=https://aun-console.agentid.pub:19876` |
+| 注册中心 | `AUN_REGISTRY_BASE_URL=https://aun-console.agentid.pub:19876` |
+| 配置中心 | `AUN_CONFIG_BASE_URL=https://aun-console.agentid.pub:19876` |
+| MySQL 连接 | MySQL 容器不设置 `MYSQL_DATABASE`；应用只接收 `KITE_DB_HOST=mysql`、`KITE_DB_PORT=3306`、用户和密码，不创建或注入任何公共默认数据库，也不注入全局 `KITE_DB_DATABASE` / `KITE_DB_DSN` |
+| 服务默认数据库 | AUN Console `aun_dashboard`、AID Custody `aun_aid_custody`、Auth `aun_auth`、CA `aun_cert`、Group `aun_group`、Leaderboard `aun_leaderboard`、Message `aun_message`、NameService `aun_nameservice`、Storage `aun_storage`；服务专用配置或显式全局数据库配置可以覆盖，均未配置时使用这些历史默认值 |
+
+可以用以下命令检查服务发现、容器日志和默认 Go 进程：
+
+```powershell
+curl.exe -k https://localhost/.well-known/aun-gateway
+docker logs --tail 200 kite-app
+docker top kite-app | Select-String -Pattern "auth-go|ca-go|gateway-go|group-go|leaderboard-go|message-go|nameservice-go|service-proxy-go|storage-go|stream-go"
+```
+
+发现结果必须返回 `gateway.agentid.pub`，不能返回 loopback 地址。活动注册实例应与 desired-state 和实际 ready 服务一致；Mail 不应启动或注册。
+
+当前 `docker-compose.yml` 为 `kite` 服务配置的主要 network aliases 包括：
+
+- `agentid.pub`
+- `proxy.agentid.pub`
+- `aun_console.agentid.pub`
+- `gateway.agentid.pub`
+- `leaderboard.agentid.pub`
+- `stream.agentid.pub`
+- `storage.agentid.pub`
+- `group.agentid.pub`
+
+### 启动 SDK Tester
+
+在服务端已启动且默认单实例强制核验通过后，独立启动 Tester project。
+
+`docker-compose.testers.yml` 的 TS/JS entrypoint 只校验 Python 辅助依赖、Linux `node_modules` 和 Chrome，不执行 `apt-get`、`pip`、`npm` 或下载。当前机器使用 `aun-ts-sdk-tester:local`、`aun-js-sdk-tester:local` 以及两个固定依赖 volume；业务测试前先只读核验：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+$required = @('kite-python-sdk-tester', 'kite-go-tester', 'kite-ts-tester', 'kite-js-tester')
+$existing = docker ps -a --format '{{.Names}}'
+$missing = $required | Where-Object { $_ -notin $existing }
+if ($missing) { throw "Tester 尚未完成离线依赖准备，停止测试: $($missing -join ', ')" }
+docker image inspect aun-sdk-tester:latest golang:1.24-bookworm `
+  aun-ts-sdk-tester:local aun-js-sdk-tester:local | Out-Null
+docker volume inspect kite-sdk-testers_ts-tester-node-modules `
+  kite-sdk-testers_js-tester-node-modules | Out-Null
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.testers.yml start
+docker compose --env-file agentid.pub/local.env --project-directory . `
+  -f docker-compose.testers.yml ps
+```
+
+该文件声明独立 project `kite-sdk-testers`，只管理 `kite-python-sdk-tester`、`kite-go-tester`、`kite-ts-tester`、`kite-js-tester`，并通过 external `kite-single_kite-net` 接入已运行的默认服务端。不要把它和 `docker-compose.yml` 用多个 `-f` 合并，也不要把它打进生产包。
+
+首次依赖准备或依赖升级必须脱离断网业务测试阶段，重新制作本地 Tester 镜像并更新固定 Linux 依赖 volume。业务测试阶段即使执行 recreate 也只允许读取这些本地材料；任一依赖缺失时 entrypoint 以退出码 `70` 停止，不会联网自愈。
+
+当前默认单实例 `kite-python-sdk-tester` 环境变量：
+
+- `AUN_TEST_AUN_PATH=/data/aun-fixed-agentid-pub`
+- `AUN_DATA_ROOT=/data/aun`
+
+默认单实例固定身份的**唯一有效目录**是：
+
+- 容器内：`/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`。
+
+如果历史目录中还残留 `single-domain/AIDs/...`，应视为旧格式脏数据，不再继续复用，也不要把其中的文件和 `persistent` 目录混拷。
+
+### agentid.cn 本地跨域对端
+
+`agentid.cn` 是当前本地 `agentid.pub` 的跨域 Docker 对端，不再使用历史 `evolagent.cn`。先只读校验固定材料和独立端口覆盖；以下命令不会创建身份，也不会修改数据库：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+python scripts\domain_materials.py validate agentid.cn\materials.json
+docker image inspect docker-deploy-kite:latest mysql:8.0 redis:7-alpine | Out-Null
+if ($LASTEXITCODE -ne 0) { throw 'agentid.cn 服务端镜像未完成离线准备，停止测试' }
+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 指纹、10 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
+
+`agentid.cn` Tester 使用独立 project、容器名、网络和可写目录，不与 `agentid.pub` 共享 SDK 身份。单域测试可按该域 `local.env` 启动；真实双域测试不能只启动这个 Tester，完整拓扑、固定身份规则与验收顺序见分布式指南：
+
+```powershell
+$required = @(
+  'kite-agentid-cn-python-sdk-tester', 'kite-agentid-cn-go-tester',
+  'kite-agentid-cn-ts-tester', 'kite-agentid-cn-js-tester'
+)
+$existing = docker ps -a --format '{{.Names}}'
+$missing = $required | Where-Object { $_ -notin $existing }
+if ($missing) { throw "agentid.cn Tester 尚未完成离线依赖准备: $($missing -join ', ')" }
+docker compose --env-file agentid.cn/local.env --project-directory . `
+  -f docker-compose.testers.yml start
+```
+
+`agentid.cn` 使用 42xxx 宿主端口和 8406 MySQL 端口，可以与 `agentid.pub` 并行。跨域测试必须按分布式指南对两个 project 同时加载 federation overlay；只启动两个独立单域 project 并不构成跨域环境。
+
+### 跨语言容器 E2E（Python / TypeScript / Go / JavaScript）
+
+跨语言容器 E2E 使用独立 Compose overlay：
+
+```text
+D:\modelunion\kite\aun-sdk-core\tests\cross-sdk\docker-compose.cross-sdk.yml
+```
+
+该环境会启动五个测试容器：
+
+| 容器 | 作用 |
+| --- | --- |
+| `cross-sdk-python` | Python SDK 长连接客户端，暴露 test-control HTTP `:9001` |
+| `cross-sdk-ts` | TypeScript SDK 长连接客户端，暴露 test-control HTTP `:9001` |
+| `cross-sdk-go` | Go SDK 长连接客户端，暴露 test-control HTTP `:9001` |
+| `cross-sdk-js` | JavaScript SDK 长连接客户端，暴露 test-control HTTP `:9001` |
+| `cross-sdk-runner` | 统一 test-runner，调用各语言客户端的 test-control API 编排用例 |
+
+业务消息仍走 AUN Gateway：
+
+```text
+cross-sdk-python / cross-sdk-ts / cross-sdk-go / cross-sdk-js
+    -> kite-app/gateway
+    -> cross-sdk-python / cross-sdk-ts / cross-sdk-go / cross-sdk-js
+```
+
+测试控制命令走容器内 HTTP：
+
+```text
+cross-sdk-runner -> http://cross-sdk-python:9001
+cross-sdk-runner -> http://cross-sdk-ts:9001
+cross-sdk-runner -> http://cross-sdk-go:9001
+cross-sdk-runner -> http://cross-sdk-js:9001
+```
+
+前置条件：
+
+- agentid.pub 单实例已按本节域入口启动：`docker compose --env-file agentid.pub/local.env --project-directory . -f docker-compose.yml -f agentid.pub/docker-compose.yml up -d`
+- 已创建专用的 Docker internal 网络 `aun-cross-sdk-local`，并把 `kite-app` 以本地域名 alias 接入；不要复用名称相近但没有服务容器的普通 bridge 网络
+- 已有 `aun-sdk-tester:latest` 镜像
+- TS/JS 的 named volume 中已有可用的 `node_modules/.bin/tsc`；Compose 强制 npm offline，缓存缺失时应停止并在允许联网的依赖准备阶段单独补齐，不能在业务 E2E 期间临时访问 npm registry
+- Go 容器使用本仓库 `go/vendor`，默认不需要联网拉 Go 模块
+
+先创建并校验隔离网络。`internal=true` 是硬要求；它保证测试容器即使配置错误也没有公网出口。`kite-app` 每次被 `--force-recreate` 后都要重新执行连接步骤，因为手工附加的网络不会继承到新容器：
+
+```powershell
+$network = "aun-cross-sdk-local"
+$exists = docker network ls --filter "name=^$network$" --format "{{.Name}}"
+if (-not $exists) {
+    docker network create --driver bridge --internal $network
+}
+$internal = docker network inspect $network --format "{{.Internal}}"
+if ($internal -ne "true") {
+    throw "跨 SDK 测试网络必须是 internal=true: $network"
+}
+
+$networks = (docker inspect kite-app | ConvertFrom-Json)[0].NetworkSettings.Networks.PSObject.Properties.Name
+if ($networks -notcontains $network) {
+    docker network connect `
+      --alias kite-app `
+      --alias agentid.pub `
+      --alias gateway.agentid.pub `
+      --alias aun_console.agentid.pub `
+      --alias storage.agentid.pub `
+      --alias group.agentid.pub `
+      $network kite-app
+}
+$env:AUN_DOCKER_NETWORK = $network
+```
+
+每轮启动前显式生成四个唯一测试 AID。不要使用 Compose 中为历史兼容保留的 `cross-py.agentid.pub`、`cross-ts.agentid.pub`、`cross-go.agentid.pub` 默认值；这些固定名称可能与服务端已有证书冲突：
+
+```powershell
+$runId = Get-Date -Format "MMddHHmmss"
+$env:CROSS_SDK_PY_AID = "winpy-$runId.agentid.pub"
+$env:CROSS_SDK_TS_AID = "wints-$runId.agentid.pub"
+$env:CROSS_SDK_GO_AID = "wingo-$runId.agentid.pub"
+$env:CROSS_SDK_JS_AID = "winjs-$runId.agentid.pub"
+```
+
+Compose 在创建或重建 agent 容器时读取这些宿主机变量；`docker compose restart` 不会重新读取。变量变更后使用 `up --force-recreate`。Python、TypeScript、Go 的测试身份落在各自 `tests/cross-sdk/data/` 目录；JavaScript test agent 使用内存 IndexedDB，进程或容器重建后私钥即丢失，因此每次重建 JS agent 都必须换一个新的 `CROSS_SDK_JS_AID`，不能拿已登记证书的旧 AID 重新生成身份。
+
+启动 agent 前必须做 DNS 和 HTTPS discovery 预检，解析结果必须等于 `kite-app` 在该 internal 网络中的 IP。若解析成公网 IP（例如 `43.*`）或其他容器，立即停止；Compose 内的 `ensure-local-network.sh` 也会在 agent 启动前执行同一类保护并以退出码 `78` 拒绝运行：
+
+```powershell
+$networkInfo = (docker inspect kite-app | ConvertFrom-Json)[0].NetworkSettings.Networks.PSObject.Properties[$env:AUN_DOCKER_NETWORK].Value
+$env:EXPECTED_GATEWAY_IP = $networkInfo.IPAddress
+docker run --rm --network $env:AUN_DOCKER_NETWORK `
+  -e EXPECTED_GATEWAY_IP `
+  -e HTTP_PROXY= -e HTTPS_PROXY= -e ALL_PROXY= -e NO_PROXY=* `
+  aun-sdk-tester:latest python -c `
+  "import os,socket,ssl,urllib.request; ip=socket.gethostbyname('gateway.agentid.pub'); assert ip==os.environ['EXPECTED_GATEWAY_IP'], (ip,os.environ['EXPECTED_GATEWAY_IP']); r=urllib.request.urlopen('https://gateway.agentid.pub/.well-known/aun-gateway',context=ssl._create_unverified_context(),timeout=5); assert r.status==200; print('local gateway ok',ip,r.status)"
+```
+
+预检通过后再执行：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core
+docker image inspect aun-sdk-tester:latest node:22-bookworm golang:1.24-bookworm | Out-Null
+if ($LASTEXITCODE -ne 0) { throw 'cross-SDK 镜像未完成离线准备，停止测试' }
+docker compose -f tests/cross-sdk/docker-compose.cross-sdk.yml up --force-recreate --abort-on-container-exit --exit-code-from cross-sdk-runner
+```
+
+只定向验收 Tail / History / Forward、A/T/H、Push Tail、重启恢复和坏密文推进时，使用：
+
+```powershell
+$env:CROSS_SDK_CASES_BASENAME = "cases.message-windows.json"
+docker compose -f tests/cross-sdk/docker-compose.cross-sdk.yml up --force-recreate --abort-on-container-exit --exit-code-from cross-sdk-runner
+```
+
+该场景按 Python → TypeScript → Go → JavaScript 串行执行，不要并发启动多份 runner。身份和游标隔离使用上面的四个唯一 AID；不得通过删除本地身份目录或清库实现隔离。
+`cases.message-windows.json` 属于本地 Git 忽略测试材料。其 `history_e2ee` 默认应为 `true`；若为隔离已知 E2EE 收件超时而临时设为 `false`，报告只能作为 Tail / History / Forward 主线验收，不能据此宣称 E2EE 通过。
+
+当前用例配置：
+
+```text
+tests/cross-sdk/cases.single-domain.json
+```
+
+默认覆盖 group.index、消息、群聊、storage、group.fs、collab 等跨 SDK 场景：
+
+- `health_ready`
+- P2P 明文有向矩阵：Python / TS / Go / JS 四个 SDK 两两互发，覆盖 12 个方向
+- P2P E2EE 有向矩阵：Python / TS / Go / JS 四个 SDK 两两互发，覆盖 12 个方向
+- P2P E2EE 连续 3 条：Python -> TS、TS -> Python、Go -> Python
+- P2P 明文连续 5 条 + ack：Python -> TS、TS -> Python
+- P2P E2EE 双向 roundtrip + ack：Python <-> TS、Go <-> TS
+- P2P E2EE Unicode/换行消息 + ack：Python -> TS
+- P2P E2EE 预期失败：JS -> 缺失 AID，验证错误不会静默成功
+- 群聊明文 pairwise 有向矩阵：Python / TS / Go / JS 四个 SDK 两两建群互发，覆盖 12 个方向
+- 群聊 E2EE pairwise 有向矩阵：Python / TS / Go / JS 四个 SDK 两两建群互发，覆盖 12 个方向
+- 三成员同群明文矩阵：`group_plain_matrix_python_ts_go` 创建同一个群，拉入 Python / TS / Go 三个 SDK agent，每个 SDK 各发一条，其他两个 SDK 接收，覆盖 3x2 接收关系
+- 三成员同群 E2EE 矩阵：`group_e2ee_matrix_python_ts_go` 创建同一个群，拉入 Python / TS / Go 三个 SDK agent，每个 SDK 各发一条加密消息，其他两个 SDK 解密接收，覆盖 3x2 接收关系
+- 四成员同群明文矩阵：`group_plain_matrix_python_ts_go_js` 创建同一个群，拉入 Python / TS / Go / JS 四个 SDK agent，每个 SDK 各发一条，其他三个 SDK 接收，覆盖 4x3 接收关系
+- 四成员同群 E2EE 矩阵：`group_e2ee_matrix_python_ts_go_js` 创建同一个群，拉入 Python / TS / Go / JS 四个 SDK agent，每个 SDK 各发一条加密消息，其他三个 SDK 解密接收，覆盖 4x3 接收关系
+- storage 四语言互操作矩阵：`storage_ticket_matrix_python_ts_go_js` 覆盖四语言写入、ACL 授权读取、下载 ticket 和 URL 下载；`storage_acl_matrix_python_ts_go_js` 轮换 writer/reader，覆盖未授权读失败、只读 ACL 可读不可写、ACL 撤销后读失败
+- group.fs 四语言互操作矩阵：`group_fs_matrix_python_ts_go_js` 创建同一个命名群，拉入 Python / TS / Go / JS 四个 SDK agent；Python owner 以 group_aid 签名写群自有区，TS/Go/JS 读取；TS/Go/JS 各自写入 `memberdata/{aid}`，Python owner 读取，覆盖 group_aid 源根、下载和 memberdata 互操作
+- group.fs POSIX 矩阵：`group_fs_posix_matrix_python_ts_go_js` 覆盖 `mkdir/ls/find/stat/lstat/df/cp/mv/rm/mount/umount`、本地上传/下载、远端复制/移动/删除、成员 `memberdata/{aid}` 挂载/卸载，以及非 owner 写群自有区、写他人 memberdata 槽位的权限拒绝
+- group.index 四语言互操作矩阵：覆盖 owner/admin SDK 生成签名 `group.index`、`expected_index_etag` CAS push、`_meta.group_indexes` stale 观察、`getGroupIndex` 摘取、便利写入 `updateAnnouncement/updateRules/updateJoinRequirements` 走 `updateGroupIndex`、以及 etag 冲突后的重新读取与重试
+- collab 四语言互操作矩阵：`collab_matrix_python_ts_go_js` 覆盖 create/read/submit/history/get/diff/snapshot/merge/discover；`collab_acl_matrix_python_ts_go_js` 覆盖 collab root ACL 的读写边界、未授权读取失败、只读者提交失败、授权后读取成功、撤销后读取失败
+- 群聊明文连续 3 条 + ack：Python -> TS、Go -> TS
+- 群聊 E2EE 连续 3 条 + ack：TS -> Python
+- 群聊 E2EE 双向 roundtrip + ack：Python <-> TS、Go <-> Python
+- 群聊 E2EE 预期失败：JS 非成员向 Python 创建、TS 参与的群发送，验证错误不会静默成功
+- 同一个群内混合明文/E2EE 双向发送 + ack：Python <-> TS、Go <-> TS
+
+运行结果以本次生成的 `tests/cross-sdk/artifacts/results.json` 为准。注意：该文件会被不同 `CROSS_SDK_CASES_BASENAME` 覆盖，不能用旧产物反推当前默认用例全部通过。Compose 使用 `--abort-on-container-exit`，runner 结束后会停止各语言长连接客户端，客户端容器的停止退出码不作为测试结果判断依据。
+
+测试产物：
+
+| 路径 | 内容 |
+| --- | --- |
+| `tests/cross-sdk/artifacts/results.json` | 汇总结果 |
+| `tests/cross-sdk/artifacts/results.jsonl` | 每行一个用例结果，方便 CI 解析 |
+| `tests/cross-sdk/artifacts/logs/python/` | Python SDK 日志 |
+| `tests/cross-sdk/artifacts/logs/ts/` | TypeScript SDK 日志 |
+| `tests/cross-sdk/artifacts/logs/go/` | Go SDK 日志 |
+| `tests/cross-sdk/artifacts/logs/js/` | JavaScript SDK 日志 |
+| `tests/cross-sdk/data/python/` | Python 客户端独立 AUN 数据目录 |
+| `tests/cross-sdk/data/ts/` | TS 客户端独立 AUN 数据目录 |
+| `tests/cross-sdk/data/go/` | Go 客户端独立 AUN 数据目录 |
+| `tests/cross-sdk/data/js/` | JS 客户端独立 AUN 数据目录 |
+
+查看结果：
+
+```powershell
+Get-Content tests/cross-sdk/artifacts/results.json
+Get-Content tests/cross-sdk/artifacts/results.jsonl
+docker logs cross-sdk-runner
+docker logs cross-sdk-python
+docker logs cross-sdk-ts
+docker logs cross-sdk-go
+docker logs cross-sdk-js
+```
+
+清理测试容器：
+
+```powershell
+docker compose -f tests/cross-sdk/docker-compose.cross-sdk.yml down
+```
+
+不要加 `-v`，除非明确要删除 `cross-sdk-ts-node-modules`、`cross-sdk-js-node-modules`、`cross-sdk-go-cache` 等 volume 并让容器下次重新安装或重新编译缓存。`tests/cross-sdk/data/` 下保存的是跨语言测试客户端的独立身份和本地状态，排查问题时应保留。
+
+### 进入测试容器
+
+```powershell
+docker exec -it kite-python-sdk-tester sh
+docker exec -it kite-ts-tester bash
+docker exec -it kite-go-tester sh
+docker exec -it kite-js-tester bash
+```
+
+容器内约定：
+
+- SDK 源码：`/sdk/src`
+- 测试目录：`/tests`
+- `PYTHONPATH=/sdk/src`
+- 默认 agentid.pub 固定身份目录使用 `/data/aun-fixed-agentid-pub`
+- `kite-python-sdk-tester` 额外挂载 SDK 仓库根到 `/workspace/aun-sdk-core:ro`，并设置 `AUN_REPO_ROOT=/workspace/aun-sdk-core`、`PYTHONPATH=/sdk/src:/tests`；依赖仓库根脚本或测试 helper 的单元测试必须从这些显式路径读取，不能根据容器内 `/tests` 的父目录猜测仓库位置。
+- 四语言 Tester 都把 `aun-sdk-core/tests/contracts` 只读挂载到 `/contracts`，并设置 `AUN_CONTRACTS_ROOT=/contracts`；A/T/H 等跨 SDK 共享向量必须读取该路径。
+- `kite-ts-tester` 挂载 `D:\modelunion\kite\aun-sdk-core\ts -> /workspace/ts`
+- `kite-ts-tester` 的 `/workspace/ts/node_modules` 使用容器内独立 volume，与宿主机 Windows `node_modules` 隔离
+- `kite-ts-tester` 使用独立的数据目录（`/data/aun`），不与 Python `kite-python-sdk-tester` 共享身份数据。Python SDK 使用 SQLCipher 加密数据库，TS SDK 使用 better-sqlite3（无加密），两者的本地存储格式不兼容，共用会导致"数据库损坏"错误。
+- `kite-go-tester` 挂载 `D:\modelunion\kite\aun-sdk-core\go -> /workspace/go`
+- `kite-js-tester` 挂载 `D:\modelunion\kite\aun-sdk-core\js -> /workspace/js`，并使用独立的 `node_modules` volume 和 `/data/aun` 数据目录
+
+### 典型测试命令
+
+直接运行脚本：
+
+```powershell
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_stream.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/test_integration_auth_flow.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_message_ack.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_gap_fill.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_v2_p2p_e2ee.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_v2_multi_device.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_slot_id_separator.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_group_online_unread_chain.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_group_recall.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_group_index.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_group_index.py
+```
+
+其中默认单实例固定 AID 测试脚本由 Compose 显式传入 `AUN_TEST_AUN_PATH=/data/aun-fixed-agentid-pub`。不要退回 `AUN_DATA_ROOT/single-domain/persistent`；该旧目录的同名证书与当前 MySQL 活动记录不匹配。
+
+message / group 服务端改动后的最小 Docker 回归组合：
+
+```powershell
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_message_ack.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_gap_fill.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_v2_p2p_e2ee.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_v2_multi_device.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_slot_id_separator.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_group_online_unread_chain.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_group_recall.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_group_index.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_group_index.py
+docker exec -w /workspace/ts kite-ts-tester node_modules/.bin/vitest run tests/integration/message-gap.test.ts tests/integration/group-gap.test.ts
+```
+
+这组用例覆盖 message ack、P2P / group gap、V2 P2P E2EE、多设备、Group E2EE slot 隔离、在线 unread 链、recall、group.index 签名/CAS/meta 观察，以及 TS SDK gap 行为。
+
+group.index 相关改动的四语言最小回归：
+
+```powershell
+# Python
+docker exec kite-python-sdk-tester python -X utf8 -m pytest /tests/unit/test_group_index.py /tests/unit/test_group_index_facade.py -v --tb=short
+docker exec kite-python-sdk-tester python -X utf8 /tests/integration_test_group_index.py
+docker exec kite-python-sdk-tester python -X utf8 /tests/e2e_test_group_index.py
+
+# TypeScript
+docker exec -w /workspace/ts kite-ts-tester node_modules/.bin/vitest run tests/unit/group-index.test.ts tests/unit/group-index-facade.test.ts tests/integration/group-index.test.ts
+
+# Go
+docker exec -w /workspace/go kite-go-tester sh -lc "go test . -run 'GroupIndex|IntegrationGroupIndex' -count=1 -v"
+
+# JavaScript：容器内禁用 127.0.0.1 pin，改用 Docker DNS
+docker exec -w /workspace/js kite-js-tester npm run test:unit -- tests/unit/group-index.test.ts tests/unit/group-index-facade.test.ts
+docker exec -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -w /workspace/js kite-js-tester node_modules/.bin/playwright test --config=playwright.agentid-local.config.ts tests/e2e-browser/group-index.spec.ts --reporter=line
+```
+
+如果本轮同时修改了 `extensions/services/group`，先在 `D:\modelunion\kite\docker-deploy` 重新 build 并重启 `kite` 服务容器，再运行上述集成/E2E。
+
+message / group WAL 与异步批量写入当前默认开启，跑上述回归前不需要额外设置开关。若本轮改动涉及 WAL replay、批量 flush、ack/cursor 合并或 group fanout，除了看测试结果，还应按“故障排查”章节确认 `kite-app` 日志里 writer 已启动且没有批量写入异常。
+
+### P2P bench 标准流程
+
+bench 用于性能验证，不替代正确性回归。服务端代码或配置改动后，必须先把改动烘进 `docker-deploy-kite:latest` 并重建 `kite-app`，否则测到的可能是旧镜像：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker compose --env-file NUL -f docker-compose.build.yml build kite
+docker compose --env-file agentid.pub/local.env --project-directory . -f docker-compose.yml -f agentid.pub/docker-compose.yml up -d --force-recreate --no-deps kite
+docker logs --tail 160 kite-app
+```
+
+确认日志里关键参数已经生效，例如 message WAL writer 输出 `batch_size=500, max_batch_size=1000`，message `db_writer_shards=2`，`wal_max_pending=8000`，`ack_coalesce_window_ms=100`，P2P 活跃设备 L1/L2 热缓存为开启状态。如果只改 SDK bench 脚本，不需要重建服务镜像。
+
+P2P bench 应在 Docker 网络内运行，优先使用 `kite-python-sdk-tester` 容器和固定 32 对 bench AID，避免宿主机 DNS / 证书 / hosts 差异影响结果。发送前先 drain 接收端，避免历史积压污染本轮统计：
+
+```powershell
+$benchEnv = "AUN_DATA_ROOT=/data/aun/bench-pairs16 AUN_TEST_AUN_PATH=/data/aun/bench-pairs16 AUN_SDK_UVLOOP=1 AUN_BENCH_UVLOOP=1"
+$senders = (1..32 | ForEach-Object { "codexdocklane1782701503s{0:D2}.agentid.pub" -f $_ }) -join ","
+$receivers = (1..32 | ForEach-Object { "codexdocklane1782701503r{0:D2}.agentid.pub" -f $_ }) -join ","
+
+docker exec kite-python-sdk-tester bash -lc "$benchEnv python -X utf8 -m aun_cli --json bench e2e drain --receivers '$receivers' --limit 100 --max-pages 200"
+docker exec kite-python-sdk-tester bash -lc "$benchEnv python -X utf8 -m aun_cli --json bench e2e send --senders '$senders' --receivers '$receivers' --count 32000 --concurrency 32 --size 64 --drain-receivers --drain-limit 100 --drain-max-pages 200 --timeout-ms 5000"
+```
+
+这组 `codexdocklane1782701503s/rXX.agentid.pub` 是性能压测专用身份池，不使用默认单实例固定身份目录。身份材料当前在：
+
+- 容器内：`/data/aun/bench-pairs16`
+- 宿主机：`D:\modelunion\kite\docker-deploy\data\sdk-tester-aun\bench-pairs16`
+
+因此运行上述硬编码 32 对 AID 时，必须显式设置 `AUN_DATA_ROOT=/data/aun/bench-pairs16` 和 `AUN_TEST_AUN_PATH=/data/aun/bench-pairs16`。普通默认单实例固定身份测试使用 `/data/aun-fixed-agentid-pub`。
+
+加密是默认模式；明文对照才加 `--no-encrypt`。标准多进程压测使用 8 个独立 bench 进程，每个进程使用 4 对 AID、`--count 4000 --concurrency 4`，总计 32 对、32000 条。各进程的 sender/receiver 子集不能重叠：
+
+需要模拟更接近生产环境的 SDK <-> Gateway 网络 RTT 时，在重建/重启 `kite` 前给 Gateway 设置连接级单向延迟，例如：
+
+```powershell
+$env:AUN_GATEWAY_CLIENT_MOCK_NETWORK_DELAY_MS = "25-50"
+```
+
+该开关只包裹客户端 WebSocket 连接，不影响 Gateway 到内部服务的连接；未设置或设为 `0` / `off` 时关闭。它用于 bench 口径校准，不应作为生产默认值。
+
+```powershell
+$prefix = "p2p32-$(Get-Date -Format yyyyMMdd-HHmmss)"
+$benchEnv = "AUN_DATA_ROOT=/data/aun/bench-pairs16 AUN_TEST_AUN_PATH=/data/aun/bench-pairs16 AUN_SDK_UVLOOP=1 AUN_BENCH_UVLOOP=1"
+1..8 | ForEach-Object {
+  $start = ($_ - 1) * 4 + 1
+  $end = $_ * 4
+  $ps = ($start..$end | ForEach-Object { "codexdocklane1782701503s{0:D2}.agentid.pub" -f $_ }) -join ","
+  $pr = ($start..$end | ForEach-Object { "codexdocklane1782701503r{0:D2}.agentid.pub" -f $_ }) -join ","
+  Start-Job -ScriptBlock {
+    param($idx, $senders, $receivers, $prefix, $benchEnv)
+    docker exec kite-python-sdk-tester bash -lc "$benchEnv python -X utf8 -m aun_cli --json bench e2e send --senders '$senders' --receivers '$receivers' --count 4000 --concurrency 4 --size 64 --drain-receivers --drain-limit 100 --drain-max-pages 200 --timeout-ms 5000" |
+      Set-Content -Encoding utf8 "D:\modelunion\kite\docker-deploy\$prefix-$idx.json"
+  } -ArgumentList ($_ - 1), $ps, $pr, $prefix, $benchEnv
+}
+```
+
+`--perf-trace` 会聚合服务端 `send_perf` 阶段耗时，默认关闭。只有需要定位分阶段耗时时才在 bench 命令上显式打开；开启后应同步关注 `message/latest.log` 大小，避免 instrumentation 本身污染吞吐数据。
+
+bench 期间至少同时采集三类数据：
+
+```powershell
+docker stats --no-stream kite-app kite-mysql kite-redis
+docker logs --since 2m kite-app | Select-String "service_status_sample|recent_p2p_cache|v2_pull|WAL writer perf"
+docker exec kite-python-sdk-tester bash -lc "python -X utf8 -m aun_cli --json status"
+```
+
+结论里需要同时报告 RPS、send p99、delivery 覆盖、`ordered_gap_blocked`、recent P2P cache 的分子/分母、L1/L2 命中、DB fallback、以及 `v2_pull` 返回消息数。只看 RPS 容易漏掉 push 折叠、gap-fill pull 或 cache 统计异常。
+
+运行 pytest：
+
+```powershell
+docker exec kite-python-sdk-tester python -m pytest /tests/unit -q -p no:cacheprovider
+docker exec kite-python-sdk-tester python -m pytest /tests/test_integration_auth_flow.py -q -p no:cacheprovider
+```
+
+### Service Proxy 默认单实例 E2E
+
+Service Proxy 默认单实例 E2E 脚本入口：
+
+```powershell
+docker exec kite-python-sdk-tester python /tests/e2e_test_service_proxy_docker.py
+```
+
+当前脚本覆盖容器内 HTTP/SSE/WS provider、Python `ServiceProxyClient` embedded registry、NameService `/proxy/{svc}` 跳转、canonical `proxy.{issuer}` URL、HTTP GET/POST、SSE 和 WebSocket subprotocol。
+
+运行前置条件：
+
+- Docker 镜像包含 `extensions/services/service_proxy` 新模块。
+- `service_proxy` 模块已启用并启动，容器网络内 `http://proxy.agentid.pub:19890/health` 可访问。
+- `/ws/client` 已接入真实 AUN provider 身份认证 resolver；未接入时脚本会明确报认证前置失败。
+
+### 离线 Push Service 隔离 PoC
+
+Push PoC 使用 `docker-deploy/docker-compose.push-poc.yml` 叠加层、固定只读 PEM 身份和 Python Mock Push Server。Mock 直接使用当前工作区 Python SDK，不读取或创建 `.seed`，也不得修改既有 AID 身份材料。
+
+应用登记的推荐路径是 Python `connect()` 携带 `push_notify_aid/push_token`；SDK 建连后调用 `push.register`。运行期更新或注销使用 `client.push.register/unregister`。测试入口为 `python/tests/integration_test_push_service_poc.py`，覆盖 P2P、多设备、registration 更新、注销、聚合、频控、batch、ACK timeout/dedup、迟到 ACK 和迁移恢复等场景。
+
+该环境启用明文 token 仅用于隔离 PoC，不能作为生产发布证据。启动 Compose/Kite、重建镜像或变更固定身份前仍需遵守本指南的授权与数据保护规则；发布结论见 [AUN 离线推送服务运维与发布指南](AUN离线推送服务运维与发布指南.md)。
+
+### 特别说明：重连测试
+
+`python/tests/integration_test_reconnect.py` 需要直接执行这些宿主机命令：
+
+- `docker compose restart kite`
+- `docker network disconnect kite-single_kite-net kite-app`
+- `docker network connect kite-single_kite-net kite-app`
+
+所以它应在宿主机运行，而不是 `kite-python-sdk-tester` 容器内运行：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core\python
+python tests/integration_test_reconnect.py
+```
+
+运行前要确保宿主机能够解析 `gateway.agentid.pub`。推荐方式不是改 hosts，而是让测试进程也运行在 Docker 网络内；如果必须在宿主机直跑，请确保你已有等效域名解析方案。
+
+### TypeScript 集成 / E2E
+
+默认单实例提供常驻 `kite-ts-tester` 服务。业务测试只复用依赖已准备完成的容器；不得依赖 entrypoint 在本轮临时下载或修复依赖。
+
+集成测试：
+
+```powershell
+docker exec kite-ts-tester bash -lc "cd /workspace/ts && node_modules/.bin/vitest run tests/integration/group-e2ee.test.ts"
+```
+
+E2E 测试：
+
+```powershell
+docker exec kite-ts-tester bash -lc "cd /workspace/ts && node_modules/.bin/vitest run tests/e2e/v2-group.test.ts"
+```
+
+Gap 补洞测试（P2P + 群消息）：
+
+```powershell
+docker exec -w /workspace/ts kite-ts-tester node_modules/.bin/vitest run tests/integration/message-gap.test.ts tests/integration/group-gap.test.ts
+```
+
+gap 测试每次运行使用随机动态 AID + 临时目录，不依赖固定身份，也不需要 `AUN_TEST_AUN_PATH`。
+
+默认单实例 reconnect 集成测试当前由宿主机 Node 进程直接协调 `docker compose restart kite`，不适合放进临时 Docker 测试容器。宿主机必须已有完整 `node_modules`，缺失时停止，不在测试阶段执行安装：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core\ts
+if (-not (Test-Path node_modules/.bin/vitest.cmd)) { throw 'TS 宿主机依赖未准备，停止测试' }
+& .\node_modules\.bin\vitest.cmd run tests/integration/reconnect.test.ts
+```
+
+运行这条 reconnect 用例前，要确保宿主机本身能解析 `agentid.pub`、`gateway.agentid.pub`，否则请先准备等效域名解析方案。
+
+### JavaScript 集成 / 浏览器 E2E
+
+JS SDK 分两类测试：
+
+- `tests/integration`：Vitest + JS DOM，用于浏览器 SDK 的集成结构回归。
+- `tests/e2e-browser`：Playwright + 真实 Chrome，用于真实网络 E2E。浏览器版 JS SDK 的 E2E 统一使用这一类。
+
+默认单实例优先在 `kite-js-tester` 中执行。该容器使用独立 Linux `node_modules` volume；业务测试前必须已经完成 Google Chrome 和依赖准备：
+
+```powershell
+docker exec -w /workspace/js kite-js-tester npm run test:integration
+```
+
+容器内运行 Playwright 时必须设置 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1`，让 Chrome 使用 Docker DNS 解析 `*.agentid.pub`。否则本地配置会把域名固定到容器自己的 `127.0.0.1`：
+
+```powershell
+docker exec -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -w /workspace/js kite-js-tester npm run test:e2e
+```
+
+只跑一个 P2P E2EE 网络 smoke：
+
+```powershell
+docker exec -e AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1 -w /workspace/js kite-js-tester npm run test:e2e:smoke
+```
+
+宿主机 Playwright 仍可作为备选。宿主机模式不要设置 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN`，由 `playwright.agentid-local.config.ts` 将本地域名映射到已发布的容器端口。宿主机依赖缺失时停止，不在测试阶段安装：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core\js
+if (-not (Test-Path node_modules/.bin/playwright.cmd)) { throw 'JS 宿主机依赖未准备，停止测试' }
+npm run test:e2e
+npm run test:e2e:smoke
+```
+
+`playwright.agentid-local.config.ts` 在宿主机模式下：
+
+- 禁用 Chrome 继承系统代理，避免 `*.agentid.pub` 被代理到外网
+- 将 `*.agentid.pub` / `agentid.pub` 映射到 `127.0.0.1`
+- 忽略本地 Docker 测试证书错误
+
+如果没有使用这个本地配置，网络 E2E 常见失败是：
+
+```text
+gateway discovery failed for https://gateway.agentid.pub/.well-known/aun-gateway: TypeError: Failed to fetch
+```
+
+如果 discovery 已通过，但登录失败：
+
+```text
+AuthError: aid_login2_failed
+```
+
+并且服务端日志中出现：
+
+```text
+AID phase2 signature verification failed: sign_time ... before cert validity ...
+```
+
+说明运行 Chrome 的 Tester 或宿主机时间与服务端容器签发证书使用的 UTC 时间存在偏差。两者偏差过大时，刚创建的 AID 证书会被服务端判定为“签名时间早于证书生效时间”。先对齐 Docker/宿主机时间，再重跑浏览器 E2E。
+
+### Go 集成 / E2E
+
+默认单实例 Go 测试优先使用常驻 `kite-go-tester` 容器接入 `kite-single_kite-net`。
+
+常驻容器命令：
+
+```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 GroupE2E -count=1 -v"
+```
+
+如果需要用临时容器跑同一组用例，下面命令默认复用宿主机 `C:\go\pkg\mod` 作为只读模块缓存。Windows Git Bash 下运行时统一在命令前加 `MSYS_NO_PATHCONV=1`。
+
+集成测试：
+
+```powershell
+docker run --rm --network kite-single_kite-net `
+  -v D:\modelunion\kite\aun-sdk-core\go:/workspace/go `
+  -v C:\go\pkg\mod:/go/pkg/mod:ro `
+  -e HTTP_PROXY= -e HTTPS_PROXY= -e ALL_PROXY= -e NO_PROXY=* `
+  -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 Integration -count=1 -v"
+```
+
+E2E 测试：
+
+```powershell
+docker run --rm --network kite-single_kite-net `
+  -v D:\modelunion\kite\aun-sdk-core\go:/workspace/go `
+  -v C:\go\pkg\mod:/go/pkg/mod:ro `
+  -e HTTP_PROXY= -e HTTPS_PROXY= -e ALL_PROXY= -e NO_PROXY=* `
+  -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 GroupE2E -count=1 -v"
+```
+
+Go 当前还没有默认单实例 Docker reconnect 用例；默认单实例侧目前覆盖的是 `integration_test.go` 和 `e2e_group_test.go`。
+
+## 分布式与双域环境
+
+三节点 `dist-agentid.pub`、本地真实域名双域 `agentid.pub/agentid.cn`、隔离 federation `dist-aid.com/dist-aid.net`、分布式 Tester 和分布式 cross-SDK 的唯一运行说明见 [AUN 分布式测试运行指南](aun分布式测试运行指南.md)。
+
+主指南不再复制 federation 命令。不得继续使用旧的 `aid.com/aid.net`、`client-a/client-b`、`federation-kite-*` 或 `federation-test_federation-net`；当前权威名称均以分布式 Compose 的 `dist-*` 配置为准。
+
+## 何时需要 rebuild / recreate / restart
+
+默认 Go 服务不是独立 Docker 容器，而是 `kite-app` 内由 Launcher 管理的子进程。Go binary 在 `docker compose build kite` 时编译并复制进 `docker-deploy-kite:latest`；`docker compose restart kite` 只会重启原容器，不会编译源码、切换镜像或应用新的 Compose 配置。
+
+### 判断表
+
+| 变更或状态 | 需要执行 | 说明 |
+| --- | --- | --- |
+| Go 服务源码、`go.mod` / `go.sum`、`module.md`、数据库迁移代码 | rebuild `kite` 镜像，再 recreate `kite-app` | binary 和 manifest 都在镜像内 |
+| Launcher、Kernel、Python 服务端代码、`Dockerfile`、服务端依赖 | rebuild + recreate | 同样由 Dockerfile 复制进镜像 |
+| 镜像已经 rebuild，但运行容器仍引用旧 image ID | 只需 recreate | 不需要重复 build |
+| 只改 `docker-compose.yml` 的环境变量、端口、volume 或 command | recreate，不需要 rebuild | `restart` 不会应用容器配置变化 |
+| 只改注册/配置中心动态配置或 desired-state | 通常不需要 Docker 操作 | Launcher watch 负责收敛目标状态 |
+| binary 未变，只需重启一个 Go 服务 | 在控制中心将目标状态设为 `stopped`，再切回 `running` | 只重启 Launcher 子进程，不影响整个节点 |
+| Launcher、Kernel、AUN Console 或整个容器异常，代码和配置均未变化 | restart `kite` | 继续使用同一镜像和容器配置 |
+| 只改 SDK 源码或测试脚本 | 服务端无需 rebuild/restart | Tester 直接 bind mount SDK 与测试目录 |
+| 准备运行 `pack.bat` 发布 | rebuild → recreate → 回归 → pack | `pack.bat` 只保存现有镜像，不负责 build |
+
+服务进入 `stopped` 后不应继续注册；重新切到 `running` 后，必须等服务实际发送 `module.ready`，再确认注册状态恢复为活动。若修改的配置不支持热加载，也按这个 `stopped` → `running` 流程重启具体服务。
+
+### 判断运行容器是否使用当前镜像
+
+```powershell
+$runningImage = docker inspect kite-app --format '{{.Image}}'
+$latestImage = docker image inspect docker-deploy-kite:latest --format '{{.Id}}'
+$runningImage
+$latestImage
+$runningImage -eq $latestImage
+```
+
+结果为 `False` 表示必须 recreate。结果为 `True` 只证明容器使用当前 tag 对应的镜像，不能证明工作区最新源码已经 build；当前镜像没有记录 dirty worktree 的内容摘要，因此只要改过服务端源码，最可靠的做法仍是重新 build。
+
+### 服务端代码变更
+
+以下内容变更都属于服务端镜像变更：
+
+- `extensions/services/{auth,ca,gateway,group,leaderboard,message,nameservice,service_proxy,storage,stream}/go/`
+- 上述服务的 `module.md`、`module.go.md`、`module.py.md` 或 Python 回滚实现
+- `launcher/`、`kernel/`、其他 `extensions/services/` 代码
+- `Dockerfile`、服务端依赖或数据库迁移实现
+
+默认单实例标准更新命令：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker compose --env-file NUL -f docker-compose.build.yml build kite
+docker compose --env-file agentid.pub/local.env --project-directory . -f docker-compose.yml -f agentid.pub/docker-compose.yml up -d --force-recreate --no-deps kite
+docker logs --tail 200 kite-app
+```
+
+第二条命令已经完成容器替换，不需要再执行 `docker compose restart kite`。Go 服务的自动迁移在新服务进程启动时执行；只 restart 未重新 build 的旧容器，执行的仍是旧迁移代码。
+
+如果代码和容器配置都没有变化，只是 Launcher、Kernel 或整个容器运行异常，才使用：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker compose --env-file agentid.pub/local.env --project-directory . -f docker-compose.yml -f agentid.pub/docker-compose.yml restart kite
+```
+
+分布式或双域服务端镜像变更后的重建命令见分布式指南，不能套用默认单实例的容器名和网络。
+
+### SDK 或测试代码变更
+
+通常不需要操作服务端，因为 Tester 挂载 SDK 源码与测试目录。Go SDK 测试会在执行 `go test` 时重新编译；Python 测试直接读取挂载源码；TypeScript/JavaScript 直接读取各自 workspace。
+
+只有 Tester 自身发生这些变化时才处理 Tester：Python 测试镜像依赖变化需要在独立准备阶段 rebuild `sdk-tester`；TypeScript/JavaScript 的 `package.json` 或 lockfile 变化必须先在独立准备阶段更新 Linux 依赖 volume，再重新创建对应 Tester。回到业务测试阶段后只允许复用已验证的容器和依赖，不得让 entrypoint 临时安装。
+
+## 两个公网域的线上单节点部署材料
+
+线上形态沿用本地验收过的单节点分布式控制模型：一个 `control_master`、一个 Launcher、MySQL、Redis，以及由 Launcher/ AUN Console 管理的服务实例。`agentid.pub` 与 `agentid.cn` 必须使用独立数据根、Compose project、容器名和控制令牌。本地双域 Docker 是跨域发布前门禁，不等于线上部署。
+
+### 日常交付契约（严格 3 个文件）
+
+`agentid.pub/online/go/` 是当前线上 Go 服务端日常替换包，严格只有：
+
+- `kite-docker.tar.gz`：带 manifest 和 SHA-256 的 Kite 服务镜像包；
+- `docker-compose.yml`：独立可执行的单文件生产 Compose，不依赖第二份 YAML；
+- `unpack.sh`：只校验并 `docker load` 镜像，绝不启动或停止 Compose。
+
+`init.sql` 和其他稳定辅助材料不进入日常包。当前一次性辅助归档为 `agentid.pub/online/bootstrap-materials.tar.gz`（解包源目录是 `agentid.pub/online/bootstrap/`），其中的 `init.sql` 首次部署时解到日常包同一目录并长期保留；日常升级不得删除它。CA、AID、TLS、MySQL 数据和 workspace 也不进入任何镜像/代码包，必须由目标服务器已有或通过独立受控迁移提供。
+
+Push 已纳入 AUN Console 管理，生产 Compose 默认将 Push 目标状态保持为 stopped（当前 plaintext token 模式不允许在 production 启动）。即使 `aun_push` 尚不存在，Push 启动链也会在收到 MySQL 1049（未知数据库）时创建固定数据库并继续版本迁移；其他连接/认证错误直接失败。
+
+### 构建与生成日常包
+
+先在当前 `D:\modelunion\kite` worktree 构建并回归服务镜像；`pack.bat`（Windows）或 `pack.sh`（Linux）只保存现有 `docker-deploy-kite:latest`，不会替你 build：
+
+```powershell
+cd D:\modelunion\kite\docker-deploy
+docker compose --env-file NUL -f docker-compose.build.yml build kite
+.\pack.bat
+```
+
+打包器会把当前镜像保存为 `kite-docker.tar.gz`，在包内写入镜像 ID、创建时间和归档 SHA-256。把生成的 `kite-docker.tar.gz`、`agentid.pub\online\go\docker-compose.yml`、`agentid.pub\online\go\unpack.sh` 放入同一交付目录；三者必须来自同一源码/镜像构建批次，不能混用旧归档。
+
+### 首次安装与日常替换
+
+目标 Linux 主机先准备域专属材料（至少 CA、TLS、10 个服务 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`。然后执行：
+
+```bash
+tar -xzf bootstrap-materials.tar.gz
+docker compose down
+chmod +x unpack.sh
+./unpack.sh
+docker compose up -d
+docker compose ps
+```
+
+这就是日常升级的完整顺序：先停旧容器，再由 `unpack.sh` 校验并替换镜像，最后由同一份 `docker-compose.yml` 启动。`unpack.sh` 不执行 `docker compose up/down`，不删除卷，不修改数据库、证书或身份材料；MySQL/Redis 镜像由 `docker compose up -d` 按需拉取。首次空库启动时 `init.sql` 由 MySQL entrypoint 执行；既有库或后加库由对应服务的幂等启动迁移处理。
+
+如需使用其他数据目录或生产独立密钥，可在服务器创建一份不随日常包替换的 `.env` 进行可选覆盖；它不是 Compose 的运行前提：
+
+```dotenv
+AUN_SERVER_DATA_ROOT=/srv/aun/agentid.pub
+MYSQL_ROOT_PASSWORD=替换为既有数据库密码
+AUN_CONTROL_INTERNAL_TOKEN=替换为独立随机控制令牌
+AUN_SERVICE_PLANE_TOKEN=替换为独立随机服务面令牌
+```
+
+同一数据根首次启动后不得随意更改 MySQL 密码；同一集群各进程使用的控制令牌和服务面令牌必须保持一致。公网生产环境应覆盖内置默认密码与令牌，但无论是否覆盖，日常部署命令都保持不变。
+
+`agentid.cn` 必须使用另一份单文件 Compose、另一数据根和另一组令牌，不能把 `agentid.pub` 的三文件目录直接复用。没有完整域数据根时不得用空 MySQL 加现有证书直接启动，否则 `aun_cert` 中缺少激活记录会导致固定证书被判定为未激活。
+
+## 故障排查
+
+- 先看 Name Service 的 `/.well-known/aun-gateway` 是否能返回非 loopback 的 Gateway URL。
+- 再看测试容器内是否能解析 `gateway.{issuer}`、`stream.{issuer}`、`storage.{issuer}`、`group.{issuer}`。
+- 如果测试脚本拿到的是 `127.0.0.1` 或 `localhost`，优先视为服务端 URL 生成逻辑有 bug，而不是测试环境问题。
+- 如果固定 `alice.agentid.pub` 登录返回 `certificate_not_active`，先执行“默认单实例启动前强制核验”。本地证书有效但当前 `aun_cert.agentid_cert` 没有对应记录，通常说明 MySQL 数据目录或 Compose 来源选错；不得先清库、重建身份或重新签发证书。
+- 只有确认 Compose、MySQL 数据目录、Issuer 和固定身份目录完全配套后，才继续只读比对证书序列号、指纹和 lifecycle。任何补登记、导入、清理或重建都需要用户明确同意。
+- 如果改了服务端代码但测试结果没变化，通常是镜像没 rebuild 或容器没重启。
+- 本地 agentid.pub 服务容器是 `kite-app`，agentid.cn 是 `kite-agentid-cn-local-app`。`kite` 是 Compose service 名；restart/recreate 必须同时带对应域的 `local.env`、域覆盖和当前使用的 federation overlay。
+- message / group WAL 或批量写入相关改动后，先确认 WAL writer 已启动，再查错误日志：
+
+```powershell
+docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL enabled|WAL writer started|后台批量写入协程已启动"
+docker logs --since 30m kite-app 2>&1 | Select-String -Pattern "WAL 批量写入失败|批量写入失败|Traceback|Exception|Deadlock|Lock wait|OperationalError"
+```
+
+- 分布式或双域问题按分布式指南的环境预检检查，不复用默认单实例容器名。
+- TS 如果在 Linux 容器里直接使用宿主机 `node_modules`，优先怀疑原生模块 ABI 不匹配，而不是业务代码本身。
+- Go 如果在容器里跑测试时开始重新联网下载模块，优先检查 `C:\go\pkg\mod -> /go/pkg/mod` 的只读挂载和 `GOMODCACHE=/go/pkg/mod` 是否生效。
+- 默认服务端只看到 `mysql`、`redis`、`kite` 是正常基线；如果需要 agentid.pub Tester，单独检查 `docker compose --env-file agentid.pub/local.env --project-directory . -f docker-compose.testers.yml ps`。
+- `kite-js-tester` 内的 Playwright 如果访问了 `127.0.0.1` 而不是 Docker 服务，确认 `docker exec` 命令传入了 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1`。
+
+### 常见踩坑
+
+- **`ModuleNotFoundError: No module named 'sqlcipher3'`**：说明 Python Tester 镜像依赖准备不完整，应停止业务测试并在独立准备阶段重建 `aun-sdk-tester`。镜像使用 `sqlcipher3-binary`（自带预编译库，无需系统级 `libsqlcipher-dev`），不得在业务测试容器中临时执行 `pip install`。
+- **`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`。
+- **SDK `key.json` 身份私钥解密失败**：先核对 AID、身份目录，以及构造 `AIDStore` 或 SDK 客户端时传入的 `encryption_seed` / `seed_password` 是否与生成 `key.json` 时一致。不要在身份目录中查找或补建 seed 文件。Docker 服务的只读 PEM 身份不使用 seed，应核对证书、私钥、AID 主体和挂载路径。即使确认是临时 AID，删除或重建身份材料也必须先取得用户明确同意，固定身份材料不得改动。
+
+## 当前边界
+
+- `integration_test_reconnect.py` 仍是宿主机脚本，不适合放进测试容器。
+- `ts/tests/integration/reconnect.test.ts` 也是宿主机协调型测试，用于控制默认单实例 `docker compose restart kite`，不适合直接塞进临时测试容器。
+- Go 当前没有默认单实例 Docker reconnect 用例；分布式和双域 reconnect 覆盖见分布式指南。
+- 浏览器版 JS SDK 的真实浏览器 E2E 优先在 `kite-js-tester` 中运行，并设置 `AUN_TEST_DISABLE_LOCAL_DOCKER_PIN=1`；宿主机 Playwright 仍是支持的备选入口。
+- 其余默认单实例集成/E2E 应优先在同一 Docker 网络的 Tester 内运行，以保证与服务端网络环境一致。