@agentunion/fastaun-browser 0.5.18 → 0.5.19

package/_packed_docs/agent.md/SCHEMA.md

@@ -1,170 +1,152 @@
-# Agent.md 规格定义
-
-版本: 1.0.0
-
-## 限制
-
-- **文件大小**: 被签名 payload 最大 4KB（尾部签名块不计入）
-- **签名块大小**: 尾部签名载体最大 2KB（2048 字节，按 UTF-8 原始字节计算）
-- **请求读取上限**: `PUT /agent.md` 最多读取 `payload_max + signature_max` 字节；超出即返回 `413 agent_md_too_large`，不执行证书查询、数据库或缓存写入
-- **编码**: UTF-8
-
-## 文件格式
-
-agent.md 文件采用 **YAML frontmatter + Markdown 内容 + 签名块（必需，位于文件尾部）** 的格式：
-
-```markdown
----
-# YAML 元数据 (核心字段)
-aid: "agent-name.aid.pub"
-name: "Agent Name"
-type: "agent"
-version: "1.0.0"
-description: "一句话描述"
-tags:
-  - tag1
-  - tag2
----
-
-# Markdown 正文内容
-详细说明、Skills、使用示例等...
-
-<!-- AUN-SIGNATURE
-cert_fingerprint: sha256:abc123...
-public_key_fingerprint: sha256:def456...
-timestamp: 1715300000
-signature: MEUCIQDx...
--->
-```
-
-上传接收契约要求签名块存在且有效；无签名文件只可作为本地草稿或只读示例，不得通过 `PUT /agent.md`。
-
-## 签名块规范
-
-### 位置
-
-文件尾部，位于 Markdown 正文之后。
-
-### 格式
-
-```
-<!-- AUN-SIGNATURE
-cert_fingerprint: sha256:<hex>
-public_key_fingerprint: sha256:<hex>
-timestamp: <unix_seconds>
-signature: <base64_der>
--->
-```
-
-- **cert_fingerprint**（必填）: X.509 证书 DER 的 SHA-256 指纹，格式 `sha256:<64位hex>`；不得使用公钥指纹代替
-- **public_key_fingerprint**（可选）: SubjectPublicKeyInfo DER 的 SHA-256 指纹，格式 `sha256:<64位hex>`
-- **timestamp**: 签名时刻的 Unix 时间戳（秒）
-- **signature**: ECDSA P-256 / SHA-256 签名的 DER 编码，使用严格 Base64 表示
-
-### 签名计算
-
-1. **被签内容（payload）**：签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部 UTF-8 字节，换行和空白均不得规范化
-2. **哈希**：对 payload 计算 SHA-256
-3. **签名**：使用证书对应的 NIST P-256 私钥执行 ECDSA 签名，结果采用 DER 编码
-
-### 验签流程
-
-1. 检测文件尾部是否存在且只能存在一个 `<!-- AUN-SIGNATURE` 签名块
-2. 提取签名块中的 `cert_fingerprint`、`timestamp`、`signature`
-3. 剥离签名块，取剩余内容为 payload
-4. 对 payload 计算 SHA-256
-5. 通过 `cert_fingerprint` 查找对应证书，获取公钥
-6. 确认证书公钥为 NIST P-256，并使用 ECDSA / SHA-256 验证签名
-
-### 约束
-
-- 签名块必须是文件的最后一个可见块（后面只允许可忽略的空白）
-- 签名块必须从新行开始，因此 payload 的最后一个原始字节必须是 `LF` 或 `CR`；SDK 不得自动补换行或改写 payload
-- frontmatter 与签名块均接受 `LF`、`CRLF` 或 `CR` 行尾；解析签名块时可识别行尾，但不得据此改写 payload
-- 签名块只能包含上述四个字段；除 `public_key_fingerprint` 外均为必填；重复字段和未知字段必须拒绝
-- 签名块不计入 4KB 文件大小限制，但自身不得超过 2048 字节；服务端必须在解析和证书查询前拒绝超限载体
-- `timestamp` 最多允许比服务端时间快 300 秒，不设置过去时间窗口，并且必须落在证书有效期内
-- `aid`、Host、Bearer Token 和签名证书 AID 必须一致
-- agent.md 上传签名算法固定为 ECDSA P-256 / SHA-256；其他曲线或密钥类型必须拒绝
-- 签名证书必须由当前 Issuer CA 返回，状态为 `active_signing` 且处于有效期内；证书 Subject CN 必须等于 AID
-- `PUT /agent.md` 成功验收后，文档不得仅因签名证书随后自然过期而失效；历史验签仍须确认 `timestamp` 落在该证书的有效期内
-- 服务端在数据库和缓存写入前完成全部校验；任一校验失败均拒绝接收
-
-## YAML Schema (核心字段)
-
-```yaml
-# ===== 身份标识 (必填) =====
-aid:
-  type: string
-  required: true
-  pattern: "^[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*)+$"
-  description: "至少两个标签的 DNS 型 AID；Issuer 后缀不固定，比较时不区分大小写"
-  example: "lobster.agentid.pub"
-
-# ===== 基本信息 =====
-name:
-  type: string
-  required: true
-  description: "Agent 显示名称"
-  example: "Code Reviewer"
-
+# Agent.md 规格定义
+
+版本: 1.0.0
+Ownership 版本: 2.0.0
+
+本文保留 legacy Ownership 2.0 的文件格式与字段，不是当前 2.1 Schema。Ownership 2.0 的 ownership 声明由整个文件尾部签名保护；本文的第三方存储写删授权、sub 单方撤销及无关系版本示例仅适用于该历史版本。当前 2.1 的完整文件、角色、关系版本、owner 锁与六态结果以 [Ownership 协议定义 2.1](../protocol/Ownership协议定义2.1.md) 为准。
+
+当前 `group/org` 是独立生命周期分支：owner 必填，无 ownership 合法，通用 ownership/proof/release 禁止；仅当前 owner 以本人证书和私钥尾签并代上传，尾部必含 `signer_aid=owner`。V2 授权、实体证书代际和恢复以 [协议 §2.5](../protocol/Ownership协议定义2.1.md#25-grouporg-名片的-owner-代签与上传) 为准。下文 legacy 的 owner/ownership 成对及目标本人签名规则不得套用于当前 Group/Org。
+
+## 限制
+
+- **文件大小**: 被签名 payload 最大 4KB（尾部签名块不计入）
+- **签名块大小**: 尾部签名载体最大 2KB（2048 字节，按 UTF-8 原始字节计算）
+- **请求读取上限**: `PUT /agent.md` 最多读取 `payload_max + signature_max` 字节；超出即返回 `413 agent_md_too_large`
+- **编码**: UTF-8
+
+Ownership 字段属于 frontmatter，计入 4KB payload；它们由整个文件的尾部签名覆盖，不另设 ownership 签名块。
+
+## 文件格式
+
+`agent.md` 和 `owner.md` 均采用 **YAML frontmatter + Markdown 内容 + 尾部签名块** 的格式：
+
+```markdown
+---
+aid: "agent-name.agentid.pub"
+name: "Agent Name"
+type: "agent"
+version: "1.0.0"
+---
+
+# Markdown 正文
+说明内容...
+
+<!-- AUN-SIGNATURE-AGENTMD-V2
+cert_fingerprint: sha256:abc123...
+public_key_fingerprint: sha256:def456...
+timestamp: 1715300000
+signature: MEUCIQDx...
+-->
+```
+
+`owner.md` 使用相同的签名块字段格式，但签名块标识为 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`；其 frontmatter 最少包含 `owner_aid`、`sub_aid` 和 `ownership.statement`，不要求使用 `agent.md` 的 `aid`、`name`、`type` 等主体字段。`agent.md` 兼容旧的 `<!-- AUN-SIGNATURE` 标识，也可使用 `<!-- AUN-SIGNATURE-AGENTMD-V2`。
+
+## 尾部文件签名
+
+### 签名块格式
+
+```text
+<!-- AUN-SIGNATURE[-TAG]
+cert_fingerprint: sha256:<64位hex>
+public_key_fingerprint: sha256:<64位hex>
+timestamp: <unix_seconds>
+signature: <base64_der>
+-->
+```
+
+- `cert_fingerprint` 必填，表示签署者 X.509 证书 DER 的 SHA-256 指纹。
+- `public_key_fingerprint` 可选，表示 SubjectPublicKeyInfo DER 的 SHA-256 指纹。
+- `timestamp` 必填，为签名时的 Unix 秒时间戳。
+- `signature` 必填，为 ECDSA P-256 / SHA-256 DER 签名的严格 Base64 表示。
+
+签名输入是签名块开始标记 `<!-- AUN-SIGNATURE` 之前的全部原始 UTF-8 字节；换行和空白不得规范化。签名块必须是文件最后一个可见块，后面只允许空白。
+
+签名块标识使用 `<!-- AUN-SIGNATURE` 前缀，可选追加大写 TAG（例如 `<!-- AUN-SIGNATURE-AGENTMD-V2` 或 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`）。`agent.md` 的尾部签名证书必须属于 frontmatter `aid` 对应的 sub_aid；`owner.md` 的尾部签名证书必须属于 frontmatter `owner_aid`。验证方按证书指纹取得公钥，并确认签署者 AID、证书有效期和签名算法均符合要求。
+
+签名块只能包含上述四个字段；除 `public_key_fingerprint` 外均为必填；重复字段和未知字段必须拒绝。`timestamp` 最多允许比服务端时间快 300 秒，并且必须落在签署证书有效期内。服务端须在数据库或缓存写入前完成全部校验。
+
+## YAML Schema（`agent.md` 核心字段）
+
+```yaml
+# ===== 身份标识（必填） =====
+aid:
+  type: string
+  required: true
+  pattern: "^[A-Za-z0-9_][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_][A-Za-z0-9_-]*)+$"
+  description: "主体的 DNS 型 AID"
+  example: "subject.agentid.pub"
+
+# ===== 基本信息 =====
+name:
+  type: string
+  required: true
+  description: "主体显示名称"
+  example: "Code Reviewer"
+
 type:
   type: string
   required: true
-  predefined_values:  # 预设值，不是封闭枚举
-    - human          # 真人用户
-    - agent          # AI 助手
-    - group          # 群组
-    - service        # 不使用大模型的服务程序
-    - device         # 被控设备
-    - host           # 运行时承载主机
-    - org            # 组织
-    - custom         # 自定义主体类型
+  predefined_values:
+    - human
+    - agent
+    - group
+    - service
+    - device
+    - host
+    - org
+    - custom
   allow_extensions: true
-  description: "主体类型，主要决定主体的数据存储结构；允许使用未预设的扩展值"
+  description: "主体类型；允许使用扩展值"
 
 exttype:
   type: string
   required: false
-  description: "主体的扩展类型，表示 type 对应的更具体形态；取值域由 type 决定"
-
-version:
-  type: string
-  required: true
-  pattern: "^\\d+\\.\\d+\\.\\d+$"
-  example: "1.0.0"
-
-# ===== 描述信息 =====
-description:
-  type: string
-  required: false
-  max_length: 100
-  description: "一句话简介，用于列表展示"
-
-# ===== 头像 =====
-avatar:
-  type: string
-  required: false
-  max_length: 256
-  description: "头像地址或标识"
-
-# ===== 标签 =====
-tags:
-  type: array
-  required: false
-  items:
-    type: string
-  description: "用于分类和检索"
-```
-
-## 主体 Type / ExtType 说明
+  description: "主体类型的扩展形态"
 
-`type` 和 `exttype` 共同描述主体。`type` 是可扩展字符串，主要决定主体的数据存储结构；`exttype` 在此基础上表示更具体的形态，取值域由 `type` 决定。
+# ===== Ownership 2.0（可选；human 禁止声明） =====
+owner:
+  type: string
+  required: false
+  description: "owner_aid 的完整小写 AID"
+  example: "owner.agentid.pub"
 
-下表定义当前支持的 8 种预设 `type`；解析方必须保留并容忍未知类型，不得因其不在预设列表中拒绝 agent.md。
+ownership:
+  type: object
+  required: false
+  requires: [owner]
+  description: "sub_aid 在自己的 agent.md 中发布的 Ownership 2.0 声明"
+
+version:
+  type: string
+  required: true
+  pattern: "^\\d+\\.\\d+\\.\\d+$"
+  example: "1.0.0"
+
+description:
+  type: string
+  required: false
+  max_length: 100
+
+avatar:
+  type: string
+  required: false
+  max_length: 256
+
+tags:
+  type: array
+  required: false
+  items:
+    type: string
+```
+
+`human` 类型不得出现 `owner` 或 `ownership`。其它主体类型可以按应用需要声明 owner_aid。AID 在 Ownership 2.0 字段中使用小写规范形式。
+
+## 主体 Type / ExtType 说明
+
+`type` 和 `exttype` 共同描述主体。`type` 是可扩展字符串，主要决定主体的数据存储结构；`exttype` 表示 `type` 对应的更具体形态，取值域由 `type` 决定。解析方应保留并容忍未知类型。
 
 | 预设 Type | 用途 | 示例 |
-|------|------|------|
+| --- | --- | --- |
 | `human` | 真人用户 | 开发者、管理员、终端用户 |
 | `agent` | 使用大模型的服务程序 | 对话助手、代码 Agent、自动化 Agent |
 | `group` | 群组身份 | 项目团队、协作群组 |
@@ -174,53 +156,111 @@ tags:
 | `org` | 组织 | 公司、部门、协作小组 |
 | `custom` | 自定义主体类型 | 用户声明的主体类型 |
 
-`exttype` 的具体取值示例：`agent` 可使用 `claude-code`、`codex` 等运行时名称；`org` 可使用 `company`、`department`、`team` 等组织层级；`group` 可使用 `normal`、`org-collab`、`task`、`org` 等群类型。
-
-## 示例文件
-
-| 文件 | Type | AID | 说明 |
-|------|------|-----|------|
-| [human-developer.md](examples/human-developer.md) | `human` | `zhangsan.aid.pub` | 全栈开发者 |
-| [openclaw-lobster.md](examples/openclaw-lobster.md) | `agent` | `lobster.aid.pub` | OpenClaw AI 助手（无签名） |
-| [signed-openclaw-lobster.md](examples/signed-openclaw-lobster.md) | `agent` | `lobster.aid.pub` | OpenClaw AI 助手（带签名） |
-| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `agent` | `claudecode.aid.pub` | Claude Code 编程助手 |
-| [群组-开发团队.md](examples/群组-开发团队.md) | `group` | `dev-team.aid.pub` | 开发团队协作群组 |
-
-表中无签名文件仅用于展示 payload 格式，不符合 `PUT /agent.md` 接收契约；静态签名示例也不代表可由线上 CA 验证的有效身份材料。
-
-## `PUT /agent.md` 接收顺序
-
-1. SDK 在联网前校验 UTF-8、payload 大小、frontmatter Schema；失败时不得签名或发起 HTTP 请求。
-2. SDK 使用当前 AID 的签名私钥追加签名块，再执行一次完整 Schema 校验和本地验签；失败时不得上传。
-3. Name Service 完成 Bearer Token 与 Host 绑定校验、完整 Schema 校验、CA 证书查询和验签。
-4. 只有全部校验成功后，Name Service 才能写入数据库并失效缓存。
-
-接收失败使用稳定的机器可读错误：格式或签名无效返回 `400 invalid_agent_md`，payload 超限返回 `413 agent_md_too_large`，CA 不可用返回 `503 certificate_verification_unavailable`，数据库不可用返回 `503 database_unavailable`。
-
-## Markdown 部分建议内容
-
-YAML 只保留核心元数据，详细信息放在 Markdown 部分：
-
-- **Skills** - 技能/命令列表及说明
-- **功能说明** - 详细的功能描述
-- **使用示例** - 具体的使用方法
-- **配置说明** - 运行时配置（如需要）
-- **限制/注意事项** - 使用限制
-
-## 解析方式
-
-解析时需先检测并跳过尾部签名块：
-
-```go
-// 1. 检测尾部签名块
-if idx := strings.LastIndex(content, "<!-- AUN-SIGNATURE"); idx >= 0 {
-    content = content[:idx] // 跳过尾部签名块，取 payload
-}
-// 2. 按原规则解析 frontmatter
-parts := strings.SplitN(content, "---", 3)
-// parts[0] = "" (空)
-// parts[1] = YAML 内容
-// parts[2] = Markdown 内容
-```
-
-
+## Ownership 2.0 字段
+
+### sub_aid 的 `agent.md`
+
+```yaml
+owner: owner.agentid.pub
+ownership:
+  statement:
+    version: 2
+    declaration_id: 550e8400-e29b-41d4-a716-446655440000
+    owner_aid: owner.agentid.pub
+    sub_aid: subject.agentid.pub
+    declared_at: 1791523200
+```
+
+字段约束：
+
+| 字段 | 要求 |
+| --- | --- |
+| `owner` | 可选；出现时必须等于 `ownership.statement.owner_aid` |
+| `ownership.statement.version` | 固定为整数 `2` |
+| `ownership.statement.declaration_id` | 小写 UUID v4，用于审计标识 |
+| `ownership.statement.owner_aid` | 管理方的完整小写 AID，必须等于 `owner` |
+| `ownership.statement.sub_aid` | 必须等于当前 `agent.md` 的 `aid` |
+| `ownership.statement.declared_at` | 正整数 Unix 秒时间戳 |
+
+`owner` 与 `ownership` 可以同时省略；出现其中一个时另一个必须出现。`ownership` 只有 `statement` 及其定义字段，不包含独立签名字段。声明随整个 `agent.md` 文件签名，由 sub_aid 自己生成和上传。
+
+### owner_aid 的 `owner.md`
+
+owner_aid 为每个 sub_aid 保存一份声明，路径为：
+
+```text
+owner_aid:/sub_aids/{sub_aid}/owner.md
+```
+
+`owner.md` 的最小 frontmatter 为：
+
+```yaml
+---
+owner_aid: owner.agentid.pub
+sub_aid: subject.agentid.pub
+ownership:
+  statement:
+    version: 2
+    declaration_id: 660e8400-e29b-41d4-a716-446655440000
+    owner_aid: owner.agentid.pub
+    sub_aid: subject.agentid.pub
+    declared_at: 1791523260
+---
+```
+
+`owner.md` 的 `owner_aid`、`sub_aid` 必须与 statement 相同。文件尾部使用 `AUN-SIGNATURE-OWNERSHIP-V2` 标识和与 `agent.md` 相同的签名字段，签署者必须是 `owner_aid`。`owner.md` 公开可读、可下载，不开放公共写权限；写入和删除由 owner_aid 或应用层明确授权的存储执行者完成。
+
+## 关系状态、撤销与共识
+
+| 当前文档情况 | 状态 |
+| --- | --- |
+| `agent.md` 与对应 `owner.md` 都存在，字段及文件签名有效且 AID 匹配 | `consensus` |
+| 两份声明都不存在 | `unbound` |
+| 只有一方声明存在 | `single_sided` |
+| 字段、路径、角色或文件签名无效 | `invalid` |
+
+sub_aid 撤销时，从自己的 `agent.md` 移除 `owner` 和 `ownership` 后重新签名上传。owner_aid 撤销时，删除自己的 `sub_aids/{sub_aid}/owner.md`。撤销不发送 ownership RPC 或 P2P 消息，不产生申请或拒绝事件。
+
+需要 owner 关系的操作必须先读取并验证两份文档。验证成功后，应用层或审计服务应追加保存双方 statement、两份文件签名、文档摘要、调用方和校验时间；之后任一方撤销，不影响已保存的审计快照。
+
+## `PUT /agent.md` 接收顺序
+
+1. SDK 在联网前校验 UTF-8、payload 大小和 frontmatter Schema；失败时不得签名或发起 HTTP 请求。
+2. SDK 使用 sub_aid 自己的签名私钥追加尾部签名块，再执行完整 Schema 校验和本地文件验签。
+3. Name Service 校验目标 Host、Bearer Token 与 `aid` 一致，执行 Schema、尾部文件签名及 `ownership` 字段一致性验证；owner_aid 不得代 sub_aid 上传。
+4. 全部校验成功后，Name Service 才能写入数据库并失效缓存。
+
+接收失败使用稳定的机器可读错误：格式或签名无效返回 `400 invalid_agent_md`，payload 超限返回 `413 agent_md_too_large`，证书服务不可用返回 `503 certificate_verification_unavailable`，数据库不可用返回 `503 database_unavailable`。
+
+## 示例文件
+
+| 文件 | Type | AID | 说明 |
+| --- | --- | --- | --- |
+| [human-developer.md](examples/human-developer.md) | `human` | `zhangsan.aid.pub` | 全栈开发者 |
+| [openclaw-lobster.md](examples/openclaw-lobster.md) | `agent` | `lobster.aid.pub` | OpenClaw AI 助手 |
+| [signed-openclaw-lobster.md](examples/signed-openclaw-lobster.md) | `agent` | `lobster.aid.pub` | 带尾部签名的 OpenClaw AI 助手 |
+| [codeagent-claudecode.md](examples/codeagent-claudecode.md) | `agent` | `claudecode.aid.pub` | Claude Code 编程助手 |
+| [群组-开发团队.md](examples/群组-开发团队.md) | `group` | `dev-team.aid.pub` | 开发团队协作群组 |
+
+无签名示例只用于展示 payload；线上 `PUT /agent.md` 仍要求有效的尾部文件签名。
+
+## Markdown 部分建议内容
+
+YAML 只保留核心元数据，详细信息放在 Markdown 部分：
+
+- **Skills**：技能、命令及说明
+- **功能说明**：主体功能描述
+- **使用示例**：具体使用方法
+- **配置说明**：运行时配置
+- **限制/注意事项**：使用限制
+
+## 解析方式
+
+解析时先检测并剥离尾部签名块，再按 YAML frontmatter 解析：
+
+```text
+1. 定位唯一的 `<!-- AUN-SIGNATURE[-TAG]` 块。
+2. 取签名块之前的原始字节作为 payload 并验签。
+3. 解析 payload 的 YAML frontmatter。
+4. 对 agent.md 按 aid 校验；对 owner.md 按 owner_aid、sub_aid 和路径校验。
+```

package/_packed_docs/aun/345/210/206/345/270/203/345/274/217/346/265/213/350/257/225/350/277/220/350/241/214/346/214/207/345/215/227.md

@@ -2,7 +2,7 @@
 
 本文档负责三套本地 Docker 环境：三节点单域、本地真实域名双域 `agentid.pub/agentid.cn`、隔离双域 federation `dist-aid.com/dist-aid.net`。默认 `agentid.pub` 单域、默认四语言 Tester 和默认 cross-SDK 统一见 [AUN 测试运行指南](aun测试运行指南.md)。公网 `agentid.pub/agentid.cn` 复测是本地跨域通过后的独立验证层，不属于本地双域 Docker。
 
-本轮跨域验收范围仅为本地 `agentid.pub` ↔ `agentid.cn`。`dist-aid.com` / `dist-aid.net` 章节仅保留为独立环境参考，本轮不得启动或运行该隔离 federation，也不得将其结果计入本轮跨域结论。
+本轮跨域验收范围仅为本机 Docker 中的 `agentid.pub` ↔ `agentid.cn`。测试请求必须经本地 `kite-agentid-federation-net` 在两个本地 Kite 容器之间完成；本轮禁止运行公网测试入口、访问线上 `agentid.pub` / `agentid.cn` 服务或把公网结果计入结论。`dist-aid.com` / `dist-aid.net` 章节仅保留为独立环境参考，本轮不得启动或运行该隔离 federation，也不得将其结果计入本轮跨域结论。
 
 本指南只认当前 worktree `D:\modelunion\kite`。当前分支已经包含完整的默认单实例、三节点分布式、两套双域环境、服务端源码和四语言 SDK；服务端镜像、Tester、Cross-SDK、`data-dist` 与部署包都必须从这个 worktree 生成和运行。
 
@@ -45,7 +45,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 
 ## 本地真实域名双域与公网环境边界
 
-`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一无 Mail 服务镜像，但各自拥有独立 Issuer CA、10 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。默认双域不创建 PostgreSQL、不加载 Mail；服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
+`agentid.pub` 与 `agentid.cn` 在本机各运行一套“分布式控制模型的单节点形态”，共同组成当前真实域名双域 Docker 跨域环境。两域复用同一无 Mail 服务镜像，但各自拥有独立 Issuer CA、12 个服务 AID、MySQL、Redis、workspace、Compose project 和宿主端口；只共享 `kite-agentid-federation-net` 上的 Kite 业务节点。默认双域不创建 PostgreSQL、不加载 Mail；服务镜像固定使用 `python:3.11-bookworm`，最终镜像不包含 `uvloop`，Compose 默认 `AUN_GATEWAY_USE_UVLOOP=0`。
 
 - `D:\modelunion\kite\docker-deploy\agentid.pub`：引用固定 `data`，project 为 `kite-single`，应用容器为 `kite-app`。
 - `D:\modelunion\kite\docker-deploy\agentid.cn`：引用固定 `data-agentid-cn`，project 为 `kite-agentid-cn-local`，应用容器为 `kite-agentid-cn-local-app`。
@@ -79,7 +79,7 @@ D:\modelunion\kite\aun-sdk-core\docs\aun公网测试运行指南.md
 - 目标 `data-dist` 必须不存在或为空。整套冷克隆至少包含 `mysql`、`postgres`、`CA`、`certs`、`AIDs`、`control`、`aun-node-a`、`aun-node-b`、`storage-shared`、`sdk-tester-aun` 和 `sdk-testers`；不得只复制 CA、证书、AID、MySQL 或节点目录中的一部分。
 - `.env.distributed` 不得被 example 覆盖。保留当前文件前要逐项比对 Issuer、MySQL/PostgreSQL 凭据、控制令牌、镜像、project/container/network 前缀、子网和端口；当前 worktree 必须保持 `kite-main-dist-*`、`172.31.89.0/24` 与新端口，不能沿用来源 worktree 的 Docker 命名空间。
 - 克隆完成后，来源与目标成为两套独立资产。后续不得共享目录、交叉挂载或同时用同一容器名接管；每次启动都执行“运行时来源强制核验”。
-- 启动业务服务前，先只读核对根 CA/Registry CA 哈希、十个内置服务证书的 SHA-256，以及证书在克隆后 MySQL `aun_cert.agentid_cert` 中的 `lifecycle_state=active_signing`、`cert_state=1` 记录。任一不一致即停止，不得补登记、重签、清库或局部重复制。
+- 启动业务服务前，先只读核对根 CA/Registry CA 哈希、十二个内置服务证书的 SHA-256，以及证书在克隆后 MySQL `aun_cert.agentid_cert` 中的 `lifecycle_state=active_signing`、`cert_state=1` 记录。任一不一致即停止，不得补登记、重签、清库或局部重复制。
 
 整套冷克隆会继承来源环境的历史业务数据，适合当前分支接管并继续回归。只有明确需要全新隔离身份和空业务库时，才在用户授权后运行 `prepare_dist_materials.py` 并完成新证书注册验收；“新建空目录 + 复制旧证书”不是合法初始化方式。
 
@@ -503,7 +503,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 定位与验收边界
 
-这是当前真实域名的**本地双域 Docker 跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个无 Mail 的 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。
+这是当前真实域名的**本机 Docker 双域跨域测试环境**。两域都是分布式控制模型的单节点部署，已迁移服务默认使用 Go：Auth、CA、Gateway、Message、Group、Storage、Stream、NameService、Leaderboard、Service Proxy；AID Custody 仍使用 Python。两域必须使用同一个无 Mail 的 `docker-deploy-kite:latest` 镜像，避免把镜像差异误判为跨域问题。本阶段的 SDK runner 只加入本地 `kite-agentid-federation-net`，不使用公网 DNS、线上服务器或公网测试 runner。
 
 本环境验证的是本地完整调用链：
 
@@ -519,7 +519,7 @@ docker compose --env-file ../docker-deploy/.env.distributed -f tests/cross-sdk/d
 
 ### 每轮执行顺序
 
-每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect，因此不得加载 `docker-compose.mail.yml`。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
+每轮开始和结束都重新阅读 [AUN 测试运行指南](aun测试运行指南.md)，确认身份保护、镜像重建和测试串行规则没有变化。固定顺序为：只读材料校验 -> 必要时构建镜像 -> 启动两域 -> 来源与 Go runtime 核验 -> 双向发现 -> 联邦身份边界 -> Notify -> Stream -> P2P -> Read State -> Group -> Group FS -> Collab -> Storage OSS -> 采集两域日志。当前明确跳过 Mail 和 reconnect，因此不得加载 `docker-compose.mail.yml`。任一前置门禁失败即停止，不得用重签证书、`setup_aids.py`、清库或删除 SDK 身份绕过。
 
 ### 材料校验与镜像构建
 
@@ -531,7 +531,7 @@ docker image inspect docker-deploy-kite:latest mysql:8.0 redis:7-alpine | Out-Nu
 if ($LASTEXITCODE -ne 0) { throw '双域基础镜像未准备完成，停止测试' }
 ```
 
-`domain_materials.py validate` 会只读核对域名、Issuer CA 指纹、10 个服务 AID、TLS 与 MySQL `server-uuid`。任一不匹配都表示材料混域，不得自动修复。
+`domain_materials.py validate` 会只读核对域名、Issuer CA 指纹、12 个服务 AID、TLS 与 MySQL `server-uuid`。任一不匹配都表示材料混域，不得自动修复。
 
 只有服务端源码、Go 依赖、manifest 或 Dockerfile 变化时，才在依赖准备阶段构建；业务测试阶段不得临时联网补依赖：
 
@@ -665,10 +665,10 @@ agentid.cn:  D:\modelunion\kite\docker-deploy\data-agentid-cn\sdk-testers\python
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
-$phases = @(
-  'federation-boundary', 'notify', 'stream', 'p2p',
-  'group', 'group-fs', 'collab', 'storage'
-)
+$phases = @(
+  'federation-boundary', 'notify', 'stream', 'p2p', 'read-state',
+  'group', 'group-fs', 'collab', 'storage'
+)
 foreach ($phase in $phases) {
   $testSince = (Get-Date).ToUniversalTime().ToString('o')
   $stamp = (Get-Date).ToUniversalTime().ToString('yyyyMMddHHmmss')
@@ -769,8 +769,9 @@ foreach ($case in $jsCases) {
 | `federation-boundary` | `FEDERATION_MUTUAL_AUTH_OK`，以及 unauth/signature/issuer/RPC/event/Group-FS marker 的全部 `DENIED` |
 | `notify` | `NOTIFY_CROSS_DOMAIN_OK` |
 | `stream` | `STREAM_CREATED_EVENT_OK`、`STREAM_TARGET_BINDING_OK`、`STREAM_CLOSED_EVENT_OK` |
-| `p2p` | `P2P_ONLINE_OK`、`P2P_ACK_OK`、`P2P_OFFLINE_RECONNECT_SKIPPED` |
-| `group` | `GROUP_AUTHORITY_MEMBER_OK`、`GROUP_REMOTE_PULL_OK`、`GROUP_DIRECTORY_OK`、`GROUP_DIRECTORY_RECONNECT_SKIPPED`、`GROUP_MESSAGE_ONLINE_PULL_OK`、`GROUP_LEAVE_OK`、`GROUP_AID_CERT_OK` |
+| `p2p` | `P2P_ONLINE_OK`、`P2P_ACK_OK`、`P2P_OFFLINE_RECONNECT_SKIPPED` |
+| `read-state` | `READ_STATE_P2P_OK`、`READ_STATE_GROUP_OK`、`READ_STATE_CROSS_DEVICE_OK` |
+| `group` | `GROUP_AUTHORITY_MEMBER_OK`、`GROUP_REMOTE_PULL_OK`、`GROUP_DIRECTORY_OK`、`GROUP_DIRECTORY_RECONNECT_SKIPPED`、`GROUP_MESSAGE_ONLINE_PULL_OK`、`GROUP_LEAVE_OK`、`GROUP_AID_CERT_OK` |
 | `group-fs` | `GROUP_FS_OWNER_AREA_OK`、`GROUP_FS_NON_MEMBER_DENIED`、`GROUP_FS_MEMBERDATA_DIRECT_OK`、`GROUP_FS_OTHER_MEMBERDATA_DENIED`、`GROUP_FS_STORAGE_BYPASS_DENIED`、`GROUP_FS_MEMBERDATA_OK`、`GROUP_FS_REMOTE_COPY_OK`、`GROUP_FS_ACL_PRE_GRANT_DENIED`、`GROUP_FS_ACL_GRANTED`、`GROUP_FS_ACL_REVOKED_DENIED`、`GROUP_FS_ADMIN_DEFAULT_WRITE_OK`、`GROUP_FS_SHORT_AID_DENIED`、`GROUP_FS_AFTER_LEAVE_DENIED` |
 | `collab` | `COLLAB_CROSS_DOMAIN_READ_OK`、`COLLAB_NON_MEMBER_DENIED`、`COLLAB_STORAGE_BYPASS_DENIED` |
 | `storage` | `STORAGE_LIST_OK`、`STORAGE_RECONNECT_SKIPPED`、`STORAGE_PRIVATE_DENIED_OK`、`STORAGE_TOKEN_OK`、`STORAGE_CROSS_OWNER_ROUTING_OK`、`STORAGE_CLEANUP_OK` |
@@ -788,9 +789,35 @@ Notify 必须双向验证公开 SDK `notify()` 经过 Gateway 联邦事件转发
 3. 当前 `--skip-reconnect` 范围明确不执行离线重连回补，必须输出 `P2P_OFFLINE_RECONNECT_SKIPPED`；恢复 reconnect 验收时，才要求接收端离线发送、再上线 pull 并 ACK。
 4. receiver AID 的 issuer 必须决定远端 Gateway；本域 Message 不得把异域 receiver 当成本地收件人查询后返回 not found。
 
-成功标准是发送响应、远端接收、pull/ack 和两域日志中的同一 trace/message ID 全部闭合。仅有 `message.send` 返回成功不算通过；远端超时必须返回明确的 federation unavailable/timeout，不能伪装成接收方不存在。
-
-### Group 跨域验收
+成功标准是发送响应、远端接收、pull/ack 和两域日志中的同一 trace/message ID 全部闭合。仅有 `message.send` 返回成功不算通过；远端超时必须返回明确的 federation unavailable/timeout，不能伪装成接收方不存在。
+
+### 跨设备已读未读验收
+
+本阶段只使用本地真实域 `agentid.pub` 与 `agentid.cn` 的固定身份，验证 Message P2P、Group 消息和同一 AID 多设备的已读状态同步。不得使用 `federation-test` 的 `dist-aid.com` / `dist-aid.net` 身份或 `cross_domain_read_state.py` 作为本轮跨域验收证据；隔离 federation 仅在本指南末尾的独立参考章节中运行。
+
+在完成 `p2p` 阶段后执行：
+
+```powershell
+$runId = "agentid-read-state-" + (Get-Date).ToUniversalTime().ToString('yyyyMMddHHmmss')
+docker run --rm --network kite-agentid-federation-net `
+  -v "D:\modelunion\kite\aun-sdk-core\python\src:/sdk/src:ro" `
+  -v "D:\modelunion\kite\docker-deploy\tests\agentid_cross_domain_e2e.py:/tests/agentid_cross_domain_e2e.py:ro" `
+  -v "D:\modelunion\kite\docker-deploy\data\extended-acceptance\group-management:/identities/pub:ro" `
+  -v "D:\modelunion\kite\docker-deploy\data-agentid-cn\sdk-testers\python-fixed:/identities/cn:ro" `
+  -e PYTHONPATH=/sdk/src `
+  -e AUN_E2E_PUB_IDENTITY_ROOT=/identities/pub `
+  -e AUN_E2E_CN_IDENTITY_ROOT=/identities/cn `
+  -e AUN_E2E_CN_ENCRYPTION_SEED=cross-domain-e2e-v1 `
+  -e AUN_E2E_RUN_ROOT=/tmp/aun-e2e `
+  -e AUN_SDK_UVLOOP=0 -e AUN_CLI_UVLOOP=0 -e AUN_BENCH_UVLOOP=0 `
+  -e HTTP_PROXY= -e HTTPS_PROXY= -e ALL_PROXY= -e NO_PROXY=* `
+  aun-sdk-tester:latest python /tests/agentid_cross_domain_e2e.py `
+    --phase read-state --skip-reconnect --run-id $runId
+```
+
+该阶段必须输出 `READ_STATE_P2P_OK`、`READ_STATE_GROUP_OK`、`READ_STATE_CROSS_DEVICE_OK` 和 `PASS phase=read-state`。P2P 与 Group 的状态上报、重复上报幂等、查询结果及跨域消息 ID 必须在同一轮中闭合；跨设备部分必须使用同一 AID 的两个不同 `device_id`，并验证在线 `message.read_changed` 事件及查询补偿。失败后只从 `read-state` 阶段继续，不重复已通过的 `federation-boundary`、Notify、Stream 和 P2P 阶段。
+
+### Group 跨域验收
 
 先由 `.agentid.pub` 成员创建群并加入 `.agentid.cn` 成员，再反向创建一次。每个方向都必须验证：
 

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

@@ -55,7 +55,7 @@ Tester 和 cross-SDK 都不是服务端环境：
 
 ### 默认单实例测试前强制核验
 
-每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、10 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
+每次开始本地单实例测试前，先选择域并执行以下只读检查。材料清单固定了 Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid`；Compose 解析结果必须把 MySQL 和应用四个数据挂载全部指向同一域：
 
 ```powershell
 $domain = 'agentid.pub' # 校验本地跨域对端时改为 agentid.cn
@@ -183,7 +183,7 @@ JS 的真实 E2E 统一使用 `js/tests/e2e-browser`，不要把浏览器 E2E
 
 ## 一次性准备
 
-首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 10 个默认 Go 服务 binary：
+首次准备时构建服务镜像和 Python Tester 镜像。服务镜像会同时构建 12 个默认 Go 服务 binary：
 
 ```powershell
 cd D:\modelunion\kite\docker-deploy
@@ -341,7 +341,7 @@ 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、服务身份或数据库来补缺。
+解析后的服务端数据源必须全部位于 `data-agentid-cn`。Issuer CA 指纹、12 个服务 AID 和 MySQL `server-uuid` 由 `agentid.cn/materials.json` 锁定；不得从 `data` 复制 `agentid.pub` 的 Issuer、服务身份或数据库来补缺。
 
 `agentid.cn` Tester 使用独立 project、容器名、网络和可写目录，不与 `agentid.pub` 共享 SDK 身份。单域测试可按该域 `local.env` 启动；真实双域测试不能只启动这个 Tester，完整拓扑、固定身份规则与验收顺序见分布式指南：
 
@@ -1149,7 +1149,7 @@ docker compose --env-file NUL -f docker-compose.build.yml build kite
 
 ### 首次安装与日常替换
 
-目标 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` 也都能正常解析。
+目标 Linux 主机先准备域专属材料（至少 CA、TLS、12 个服务 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`。然后执行：