@agentunion/fastaun 0.5.25 → 0.5.27

package/_packed_docs/sdk/agent.md/344/270/216group.index/347/232/204ETag/350/247/202/345/257/237/344/270/216/345/220/214/346/255/245/346/234/272/345/210/266.md

@@ -0,0 +1,240 @@
+# agent.md 与 group.index 的 ETag 观察与同步机制
+
+## 1. 先看结论
+
+| 对象 | ETag 权威来源 | 观察入口 | 正文/设置何时更新 |
+|---|---|---|---|
+| `agent.md` | Nameservice 对当前 HTTP 表示的完整响应正文计算 SHA-256，返回带引号的十六进制 ETag | Gateway RPC `_meta`、消息信封 `agent_md` | 观察只更新 `remote_etag`；显式下载或“本地无正文”的自动补拉完成验签后才更新正文 |
+| `group.index` | Group 服务对签名 JSONL entries 的 canonical bytes 计算 `"sha256:<hex>"` | RPC 响应 `_meta.group_indexes` | 观察只标记 stale；`getGroupIndex` 显式拉取并验签，`updateGroupIndex` 以 ETag CAS 提交 |
+
+`remote_etag` 是远端版本提示，`local_etag` 是当前本地已验证正文/索引的版本。两者不能混用。观察到新 ETag 不等于已经下载了新正文，也不等于应自动覆盖应用缓存。
+
+## 2. 总体流程
+
+```mermaid
+flowchart LR
+    W[写入 agent.md / group.index] --> A[服务端生成权威 ETag]
+    A --> P[Gateway RPC _meta / 消息信封携带版本提示]
+    P --> O[SDK observer 保存 remote_etag 或 remote_meta]
+    O --> C{本地版本相同?}
+    C -->|是| K[保持正文/设置缓存]
+    C -->|否| D{资源类型与本地状态}
+    D -->|agent.md 无正文| G[自动 GET + 验签]
+    D -->|agent.md 已有正文| H[仅标记待更新，由应用显式 download/check]
+    D -->|group.index| I[仅标记 stale]
+    G --> U[写入 content/local_etag]
+    I --> J[getGroupIndex 显式拉取、验签、hydrate]
+    J --> U2[写入 settings/local_etag]
+```
+
+## 3. agent.md
+
+### 3.1 服务端写入和版本发布
+
+```mermaid
+sequenceDiagram
+    participant SDK as SDK
+    participant NS as Nameservice
+    participant GW as Gateway
+    participant MSG as Message Service
+
+    SDK->>NS: PUT /agent.md
+    NS->>NS: 保存权威正文并计算 HTTP ETag
+    NS-->>SDK: 200 + ETag + Last-Modified
+    NS-->>GW: nameservice.agent_md_updated(aid)
+    GW->>GW: 清除该 AID 的 agent.md 元数据缓存和发送节流
+    GW-->>SDK: 后续 RPC response 的 _meta.agent_md_etags
+    MSG-->>SDK: message envelope.agent_md.sender/group
+```
+
+Nameservice 的 `GET`/`HEAD` 对相同请求头返回同一表示的 ETag；`HEAD` 不返回正文，并支持 `If-None-Match`/`If-Modified-Since`。成功写入会发 `nameservice.agent_md_updated`，Gateway 用它清理自己的 ETag 元数据缓存；该通知不是 SDK 的版本事件。当前已确认的 Gateway 下发入口是后续 RPC response 的 `_meta`；消息信封也会携带发送者观察值。SDK 能解析事件 `_meta`，但当前服务端链路未确认普通事件推送会注入 agent.md ETag。四个 SDK 的下载 GET 不主动发送条件头；对代理返回的 304 仅做兼容处理。
+
+事件 payload 中的 ETag 针对 Nameservice 保存的完整记录；HTTP ETag 针对本次请求的响应表示，签名格式投影可能使两者不同。事件的可靠用途是让 Gateway 失效并重新读取元数据，SDK 不应把它当作已下载正文。
+
+Gateway 元数据示例：
+
+```json
+{
+  "_meta": {
+    "agent_md_etag": "\"<sha256-hex>\"",
+    "agent_md_etags": {
+      "requester": {"aid": "alice.agentid.pub", "etag": "\"<sha256-hex>\""},
+      "peer": {"aid": "bob.agentid.pub", "etag": "\"<sha256-hex>\"", "last_modified": "..."},
+      "group": {"aid": "team.agentid.pub", "etag": "\"<sha256-hex>\""}
+    }
+  }
+}
+```
+
+消息信封只承载观察值，不承载正文：
+
+```json
+{"agent_md":{"sender":{"aid":"bob.agentid.pub","etag":"\"<sha256-hex>\""}}}
+```
+
+### 3.2 SDK 观察和下载判定
+
+四个 SDK 都在传输层注册 observer，读取 `_meta.agent_md_etag`、`_meta.agent_md_etags`，并读取信封的 `agent_md.sender`/`group`。记录至少区分：
+
+```text
+remote_etag       观察到的服务端版本
+local_etag        本地已验证 content 的版本
+observed_at       最近观察时间
+observation_version 观察代次
+fetched_at        正文最近成功下载时间
+verify_status     最近一次验签结果
+```
+
+观察流程：
+
+```mermaid
+flowchart TD
+    E[收到 RPC _meta 或 message envelope 的 ETag] --> S[保存 remote_etag/observed_at]
+    S --> Q{本地是否已有已验证正文?}
+    Q -->|否| F[单飞 GET /agent.md]
+    Q -->|是| N[不 HEAD、不自动 GET；触发 changed/待更新标记]
+    F --> V[校验 AID、Schema、签名]
+    V -->|成功| L[保存正文、local_etag、fetched_at]
+    V -->|失败| R[记录错误并退避；等待新观察或显式重试]
+```
+
+SDK 也能解析带 `_meta` 的事件，但当前服务端实现中已确认的 agent.md ETag 下发路径是 Gateway RPC 响应；普通事件推送不作为同步保证。`check_agent_md`/`checkAgentMd`/`CheckAgentMD` 是检查入口：本地 ETag 与观察值一致且检查 TTL 未过时可直接返回缓存；否则发一次 `HEAD`，只报告 `needs_update`，不会自动跟随 GET。Python、TS、JS 管理器可按 TTL 短路；Go 管理器的 `Check` 支持 TTL，但公开 `AIDStore.CheckAgentMD` 直接发 HEAD。`download_agent_md`/`downloadAgentMd`/`DownloadAgentMD` 才是正文下载入口。
+
+四端当前实现位置：
+
+- Python：`python/src/aun_core/agent_md.py` 的 `observe_meta`、`observe_rpc_meta`、`check`、`download`。
+- Go：`go/agent_md_manager.go` 的观察、`Check`、下载；公开 `AIDStore.CheckAgentMD` 是直接 HEAD 的低层入口。
+- TypeScript：`ts/src/agent-md.ts` 的 `observeMeta`、`observeRpcMeta`、`check`、`download`。
+- JavaScript：`js/src/agent-md.ts` 的同名逻辑；浏览器记录存 IndexedDB，缺少持久层时退化为内存。
+
+应用层按需同步示例（`AIDStore`）：
+
+```ts
+const state = await store.checkAgentMd(peerAid, 1);
+if (state.ok && state.data.needs_update) {
+  await store.downloadAgentMd(peerAid);
+}
+```
+
+```python
+checked = await store.check_agent_md(peer_aid, ttl_days=1)
+if checked.ok and checked.data["needs_update"]:
+    await store.download_agent_md(peer_aid)
+```
+
+```go
+checked := store.CheckAgentMD(ctx, peerAid)
+if checked.Ok && checked.Data.NeedsUpdate {
+    downloaded := store.DownloadAgentMD(ctx, peerAid)
+    if !downloaded.Ok { /* handle downloaded.Error */ }
+}
+```
+
+Go 的公开 `AIDStore.CheckAgentMD` 每次都执行 HEAD；`maxUnsyncedDays` 不会让该入口跳过 HEAD。
+
+不要把 `remote_etag` 放进 `If-None-Match`，也不要因为每次 RPC 都收到相同 ETag 就重复下载。SDK 已按 AID、身份存储范围和观察代次做单飞/退避。
+
+## 4. group.index
+
+### 4.1 服务端协议
+
+`group.index` 是 owner/admin SDK 生成并签名的 canonical JSONL。服务端不根据数据库重建正文，只做签名、Schema、`body_hash`、ETag、权限和 CAS 校验。
+
+```mermaid
+sequenceDiagram
+    participant SDK as Owner/Admin SDK
+    participant G as Group Service
+    participant DB as Group DB
+
+    SDK->>G: group.set_settings(indexed settings + signed group.index + expected_index_etag)
+    G->>DB: 事务内锁定 group.index
+    G->>DB: 比较当前 etag
+    alt ETag 匹配
+        G->>DB: 写 indexed settings 和 group.index
+        G-->>SDK: 成功 + _meta.group_indexes
+    else 冲突
+        G-->>SDK: group.index etag conflict
+    end
+```
+
+索引元数据示例：
+
+```json
+{
+  "type": "index_meta",
+  "group_aid": "team.agentid.pub",
+  "etag": "\"sha256:...\"",
+  "last_modified": 1780000000000,
+  "body_hash": "sha256:...",
+  "schema": "aun.group.index.v1",
+  "signed_by": "alice.agentid.pub",
+  "sig_alg": "ECDSA-P256-SHA256",
+  "signature": "base64..."
+}
+```
+
+响应版本提示：
+
+```json
+{"_meta":{"group_indexes":{"team.agentid.pub":{
+  "etag":"\"sha256:...\"",
+  "last_modified":1780000000000,
+  "schema":"aun.group.index.v1"
+}}}}
+```
+
+### 4.2 SDK 观察、读取和写入
+
+```mermaid
+flowchart TD
+    M[收到 _meta.group_indexes] --> R[保存 remote_meta]
+    R --> E{remote etag == local_etag?}
+    E -->|是| F[本地快照 fresh]
+    E -->|否| T[标记 stale]
+    T --> A{应用需要最新设置?}
+    A -->|否| W[继续使用已验证本地快照，并暴露 stale]
+    A -->|是| P[getGroupIndex: group.get_settings(group.index)]
+    P --> V[验签、校验 entry etag、校验 signer 权限]
+    V --> U[保存 settings、entry_etags、index.jsonl、local_etag]
+    U --> F[结束：本地快照 fresh]
+```
+
+四端共同规则：
+
+TypeScript/JavaScript 按需读取：
+
+```ts
+const state = await client.group.checkGroupIndex({ group_id: groupAid });
+if (state.needs_update) {
+  await client.group.getGroupIndex({ group_id: groupAid });
+}
+```
+
+Python 与 Go 分别调用 `client.group.check_group_index(...)` / `client.Group().CheckGroupIndex(...)`，需同步时调用对应的 `get_group_index` / `GetGroupIndex`。`updateGroupIndex` / `update_group_index` / `UpdateGroupIndex` 才执行签名写入和 `expected_index_etag` CAS。
+
+- `checkGroupIndex` 只比较本地 `local_etag` 与已观察的 `remote_meta.etag`，不发 RPC；尚未观察到远端 meta 时，不能据此确认远端最新版本。
+- `getGroupIndex` 才拉正文；成功验签后才把 `local_etag` 标为 fresh。
+- `updateGroupIndex` 先读取最新索引、合并设置、重新签名，再提交 CAS；遇到 `group.index etag conflict` 重新读取并重试。
+- indexed settings 的便捷读取可能使用已验证本地缓存；收到新远端 ETag 不会自动 pull 覆盖缓存，应用需显式调用 `getGroupIndex` 获取最新快照。
+- 本地缓存按 `local_aid + group_aid` 隔离。Python/Go/TS 使用文件缓存；JS 使用 IndexedDB。
+- `_meta.group_indexes` 不是索引正文；Gateway/Message 只透传或合并 meta，不生成索引。
+
+Go/Python/TS/JS 的门面名称分别为 `check_group_index`/`CheckGroupIndex`/`checkGroupIndex`、`get_group_index`/`GetGroupIndex`/`getGroupIndex`、`update_group_index`/`UpdateGroupIndex`/`updateGroupIndex`。
+
+## 5. 规范与实现边界
+
+- `agent.md` 格式和发现规则见 [06-服务协议](../../../docs/aun文档/aun协议/06-服务协议.md#641-agentmd-规范)；显式 `/agent.md` 访问见 [附录 K](../../../docs/aun文档/aun协议/附录K-Agent_Web发现协议.md#1342-显式访问-agentmd)。
+- `group.index`、`expected_index_etag`、`_meta.group_indexes` 和冲突处理见 [Group 子协议 §10.13](../../../docs/aun文档/aun协议/10-Group-子协议.md#1013-群设置与-groupindex)。
+- SDK agent.md 上传/下载/检查及被动观察见 [API 手册](06-API手册.md#agentmd)。
+- Storage 的 `if_sha256` 是另一套 RPC 条件读取语义，不等于 agent.md 的 HTTP ETag，也不等于 group.index 的 CAS ETag。
+
+源码索引：
+
+| 链路 | 主要实现 |
+|---|---|
+| agent.md 服务端写入/HTTP ETag | `extensions/services/nameservice/go/internal/httpserver/agentmd.go` |
+| Gateway agent.md meta | `extensions/services/gateway/go/internal/httpserver/server.go` |
+| group.index ETag/签验 | `extensions/services/group/go/internal/groupindex/index.go` |
+| group.index CAS | `extensions/services/group/go/internal/store/group_index_cas.go` |
+| Group meta 注入 | `extensions/services/group/go/internal/settings/get_settings.go` |
+