@agentunion/fastaun-browser 0.5.18 → 0.5.20

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 以本人 token 上传，可选 owner 附签且存在必须验证；Group 旧实体单签及实体身份上传持续兼容，Org 不开放。通用多签、实体证书代际和恢复以 [协议 §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 表示。
+
+允许连续多尾块。第 i 块签署文件起点至本块 `<` 前的完整原始 UTF-8 prefix；第一块仍只签正文，后续块含前序完整块与分隔空白。append 仅向已有链追加才在末字节非 LF/CR 时补 LF 并纳入新块输入；无旧块按首签要求正文以 CR/LF 结束，否则拒绝。块间及末块后只允许空白，不规范化换行。顺序受后续签名保护；移除末端块可形成有效短链，verify 只返回实际列表且必须全块验签。
+
+签名块标识使用 `<!-- AUN-SIGNATURE` 前缀，可选追加大写 TAG（例如 `<!-- AUN-SIGNATURE-AGENTMD-V2` 或 `<!-- AUN-SIGNATURE-OWNERSHIP-V2`）。`agent.md` 的主签证书必须属于 frontmatter `aid` 对应的 sub_aid；`owner.md` 的主签证书必须属于 frontmatter `owner_aid`。验证方按证书指纹取得公钥，并确认签署者 AID、证书有效期和签名算法均符合要求。
+
+各块仅允许上述四字段及 `signer_aid`；附签必填与该块证书 AID 一致的 `signer_aid`，通用容器可解析主块可选 signer_aid；普通 agent.md／owner.md 主块不输出且业务拒绝该字段，实体主块显式 signer_aid=target。除可选 `public_key_fingerprint` 外其余字段必填，重复及未知字段拒绝。TAG 为 `[A-Z0-9-]+` 字面后缀，空串无后缀，传短 tag，AUN-SIGNATURE 不作特殊选项，不授予角色或权限；证书沿用可信 resolver 按指纹获取。通用 Store document 签验不判断 YAML 业务，资源角色及授权由调用者检查。`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，逐块验各自之前的完整 prefix。
+3. 解析 payload 的 YAML frontmatter。
+4. 对 agent.md 按 aid 校验；对 owner.md 按 owner_aid、sub_aid 和路径校验。
+```

package/_packed_docs/agent.md//350/277/234/347/250/213agent.md/347/274/223/345/255/230/344/270/216etag/351/200/217/344/274/240/346/226/271/346/241/210.md

@@ -101,12 +101,12 @@ Gateway RPC response 和 event push 的 `_meta` 字段：
 
 ## SDK 缓存模型
 
-每个远程 AID 在内存和本地持久化记录中都维护一条 agent.md 状态。Python / TypeScript / Go 的持久化记录是 `{aun_path}/AIDs/{aid}/agentmd.json`；浏览器 JavaScript 是 IndexedDB 中的 `{aid}/agentmd.json` logical key。SDK 启动或内存 miss 时按需加载该记录。
+每个 AID 在内存和本地持久化记录中维护一条 agent.md 状态，远端已确认缓存与自有身份上传失败稿分开保存。Python / TypeScript / Go 的记录是 `{aun_path}/AIDs/{aid}/agentmd.json`；浏览器 JavaScript 是 IndexedDB 中的 `{aid}/agentmd.json` logical key。SDK 启动或内存 miss 时按需加载。
 
 | 字段 | 含义 |
 | --- | --- |
 | `aid` | 远程 AID |
-| `content` | 本地缓存的完整 `agent.md` 内容，可为空 |
+| `content` | 已确认的远端完整 `agent.md` 缓存，可为空；不用于保存尚未提交的本地失败稿 |
 | `local_etag` | 当前 `content` 对应的 ETag，由成功 GET 200 内容确认；304 复用本地内容时沿用原值 |
 | `remote_etag` | 从消息信封、RPC response `_meta` 或 event push `_meta` 观察到的远端云端 ETag |
 | `last_modified` | GET 响应的 `Last-Modified` |
@@ -114,15 +114,15 @@ Gateway RPC response 和 event push 的 `_meta` 字段：
 | `checked_at` | 最近一次 HEAD / GET 确认远端状态的本机时间 |
 | `observed_at` | 最近一次观察到远端 ETag 的本机时间 |
 | `remote_status` | `found` / `missing` / `error` |
-| `verify_status` | 最近一次 agent.md 验签结果：`ok` / `unsigned` / `invalid` 等 |
+| `verify_status` | 最近一次远端 agent.md 验签结果：`ok` / `unsigned` / `invalid` 等；不表示本地草稿已被远端验收 |
 | `verify_error` | 最近一次验签失败原因 |
 | `last_error` | 最近一次网络或 HTTP 错误 |
-
+| `local_draft_content` | 私有元数据：本地 schema／外层签名验证通过的上传候选，在首次远端 preflight 前独立保存；服务端确认对应候选提交成功后才清除 |
 状态规则：
 
 - 收到远端 ETag 时，只更新 `remote_etag` 和 `observed_at`。
-- 只有下载到内容并完成验签后，才能更新 `content`、`local_etag`、`last_modified`、`fetched_at`。
-- `remote_etag == local_etag` 时视为同步。
+- 只有下载到内容并完成验签后，才能更新 `content`、`local_etag`、`last_modified`、`fetched_at`；远端下载、同步和 ETag 观察不清除 `local_draft_content`。
+- `remote_etag == local_etag` 时仅表示远端缓存同步；返回本地草稿时必须标记 unverified、in_sync=false、source.agent_md_fetched=false。
 - `remote_etag != local_etag` 或 `content` 为空时视为需要更新；该状态可由字段推导，不要求单独存储 `stale` 字段。
 - `verify_status=invalid` 时内容可以缓存但应用层应能看到无效状态；是否拒绝展示由上层策略决定。
 
@@ -308,12 +308,12 @@ observe_remote_agent_md_etag(aid, etag, source)
 
 ### 按需下载
 
-当应用调用 `downloadAgentMd(aid)` 或 SDK 需要展示远程 agent 信息时：
+应用显式调用 `downloadAgentMd(aid)` 或 forceRefresh／本语言等效选项时读取远端权威内容并保留草稿；默认 resolve 对持有本地私钥的自有身份优先返回 `local_draft_content`，其余远程信息继续按以下缓存下载规则处理：
 
 - 可先查内存，miss 时查 agentmd.json / IndexedDB，用于展示本地已有状态。
 - `downloadAgentMd(aid)` 的远端下载请求一律发起无条件 GET，不用本地 ETag 决定请求头。
 - GET 请求不得发送 `If-None-Match` / `If-Modified-Since`。
-- 200：验签，更新内容和 `local_etag`。
+- 200：验签，更新远端 `content` 和 `local_etag`，保留独立的 `local_draft_content`。
 - 304：本地已有 content 时复用该 content；本地没有 content 时再发起一次无条件 GET。第二次仍非 2xx 时按错误返回。
 - 404：标记远端未发布 `agent.md`，不要删除已有内容，除非产品要求严格同步。
 - 网络错误：保留旧内容，记录 `fetch_error` 或更新失败时间。
@@ -334,15 +334,15 @@ agent.md 不写入 SQLite。当前 SDK 使用以下持久化位置：
 | 字段 | 说明 |
 | --- | --- |
 | `aid` | AID |
-| `content` | 正文副本；文件系统 SDK 也会单独写 `agent.md` |
+| `content` | 已确认的远端正文副本；文件系统 SDK 也会单独写 `agent.md`，不与本地失败稿混用 |
 | `local_etag` / `remote_etag` | 本地内容版本 / 远端观察版本 |
 | `last_modified` | 远端 Last-Modified |
 | `fetched_at` / `checked_at` / `observed_at` / `updated_at` | 本机时间戳 |
 | `remote_status` | `found` / `missing` / `error` |
 | `verify_status` / `verify_error` | 最近一次验签状态 |
 | `last_error` | 最近一次错误 |
-
-四个已实现 SDK 应保持字段语义一致。旧 `agent_md_cache` / `remote_agent_md_cache` SQLite 表不再作为 agent.md 缓存来源；迁移逻辑可清理旧表，但不得把新 agent.md 写回 SQLite。
+| `local_draft_content` | 私有上传候选，独立于远端缓存、ETag 和普通 pending 条件；不得作为已同步内容返回 |
+四个 SDK 保持上述语义一致：普通及 Group/Org 名片失败稿仅本地保留，重连即使发现普通名片 pending 也不隐式上传；由应用显式重试，服务端确认对应候选后才清稿。Ownership 2.1 任务、消息及 outbox 仍按原机制恢复。旧 `agent_md_cache` / `remote_agent_md_cache` SQLite 表不再作为缓存来源，不得把新 agent.md 写回 SQLite。
 
 ## 异常与竞态处理