@agentunion/fastaun-browser 0.2.20 → 0.3.1

package/_packed_docs/sdk/04-/350/277/236/346/216/245/344/270/216/350/256/244/350/257/201.md

@@ -202,26 +202,49 @@ Name Service 同时提供面向 Agent Web 的标准 HTTP 资源：
 - `HEAD https://{aid}/agent.md`
   匿名查询是否存在，并获取 `ETag`、`Last-Modified`、`Cache-Control`
 
-SDK 已封装上传、下载、签名、验签高层方法：
+### 推荐主 API（自 v0.x 起）
+
+SDK 在 `AUNClient` 上提供两个一站式主方法，封装了"读文件/内容 → 签名 → 上传 → 刷新 etag"和"下载 → 自动验签 → 可选写盘"两条主线：
 
 ```python
-signed_agent_md = await client.auth.sign_agent_md(agent_md_text)
-await client.auth.upload_agent_md(signed_agent_md)
-peer_agent_md = await client.auth.download_agent_md("bob.agentid.pub")
-peer_verify_result = await client.auth.verify_agent_md(peer_agent_md, aid="bob.agentid.pub")
+# 发布自己的 agent.md（读文件 → 签名 → 上传 → 刷新内部 etag）
+await client.publish_agent_md("/path/to/agent.md")
+
+# 下载并自动验签别人的 agent.md（aid 缺省取自身 AID）
+info = await client.fetch_agent_md("bob.agentid.pub", save_path="./bob.md")
+print(info["signature"]["status"], info["in_sync"])
 ```
 
-其中：
-
-- `sign_agent_md()` 使用当前本地身份私钥在文件尾部追加 `AUN-SIGNATURE` 块；若已有尾部签名块，会先剥离再重签
-- `verify_agent_md()` 返回三态结果：`verified`、`invalid`、`unsigned`；未传 `cert_pem` 时会按 `aid + cert_fingerprint` 拉取对端证书
-- `upload_agent_md()` 会自动复用本地缓存的 access token；若 token 缺失或过期，会自动重新认证后再上传
-- `download_agent_md()` 不需要登录态，直接匿名下载
-- 签名块不改变服务端 HTTP 端点；上传前是否签名由应用层决定
-- 服务端返回短时缓存头，调用方也可以直接使用上述 HTTP 端点自行下载或做缓存协商
-- 常见错误返回：
-  `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
-  `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
+详细签名见 `06-API手册.md` 中的 `publish_agent_md` / `fetch_agent_md` 章节。
+
+| SDK | publish | fetch |
+|------|---------|-------|
+| Python | `client.publish_agent_md(path)` | `client.fetch_agent_md(aid, save_path)` |
+| TypeScript（Node） | `client.publishAgentMd(path)` | `client.fetchAgentMd(aid?, savePath?)` |
+| Go | `client.PublishAgentMD(ctx, path)` | `client.FetchAgentMD(ctx, aid, savePath)` |
+| C++ | `client.PublishAgentMd(path, cb)` | `client.FetchAgentMd(aid, save_path, cb)` |
+| JavaScript（浏览器） | `client.publishAgentMd(content)` | `client.fetchAgentMd(aid?)` |
+
+JS 浏览器版本无文件系统，`publish` 接收 markdown 文本（应用层用 `<input type=file>` 等读出），`fetch` 不接受 `savePath`。
+
+### Deprecated（保留代码、未来版本将移除）
+
+| 旧方法 | 推荐替代 |
+|--------|----------|
+| `client.auth.sign_agent_md` | `client.publish_agent_md` 内部已包含 |
+| `client.auth.verify_agent_md` | `client.fetch_agent_md` 内部已包含 |
+| `client.auth.upload_agent_md` | `client.publish_agent_md` |
+| `client.auth.download_agent_md` | `client.fetch_agent_md` |
+
+底层方法仅推荐用于离线签名 / 纯文本验签等特殊场景。
+
+> v0.x 起删除了 `set_local_agent_md_path` / `get_local_agent_md_etag` / `get_remote_agent_md_etag` 三个 client 端 API；本地 etag 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存。事件 payload 仍会注入 `_agent_md.{local_etag, remote_etag}` 供应用层比对。
+
+### 错误返回
+
+- `PUT /agent.md` 可能返回 `401`（缺失或无效 token）、`403`（token 的 AID 与 Host 不匹配）、`400`（frontmatter 非法或 frontmatter.aid 与 Host 不匹配）、`413`（文档超过大小上限）
+- `GET/HEAD /agent.md` 在目标尚未发布时返回 `404`
+- 主 API 在上述场景抛对应异常（NotFoundError / AUNError 等）
 
 ---
 

package/_packed_docs/sdk/06-API/346/211/213/345/206/214.md

@@ -15,17 +15,20 @@
 - [disconnect()](#await-disconnect---none) - 断开连接（可重连）
 - [list_identities()](#list_identities---listdict) - 列出本地身份
 - [ping()](#await-pingparams-dict--none---any) - 连通性探测
-- [set_local_agent_md_path()](#set_local_agent_md_pathpath-str---str--agentmd-版本一致性) - 配置本地 agent.md 路径，与服务端 etag 比对
+- [set_local_agent_md_path()](#set_local_agent_md_pathpath-str---str--agentmd-版本一致性) - **已删除**，请改用 `publish_agent_md()` / `fetch_agent_md()`
+- [publish_agent_md()](#await-publish_agent_mdpath-str---dict--agentmd-发布主-api) - 读取本地 agent.md → 签名 → 上传，并刷新内部 etag
+- [fetch_agent_md()](#await-fetch_agent_mdaid-str--none-save_path-str--none---dict--agentmd-下载主-api) - 下载 agent.md → 自动验签 → 可选写盘
 - [status()](#await-statusparams-dict--none---any) - 网关状态查询
 - [check_gateway_health()](#await-check_gateway_healthgateway_url-str-timeout-float--50---bool) - 检查网关可用性
 
 ### [AUNClient.Auth](#authnamespace-clientauth)
 - [create_aid()](#await-create_aidparams-dict---dict) - 注册新 AID
+- [check_aid()](#await-check_aidparams-dict---dict) - 检查 AID 状态（本地完整性 + 远程注册）
 - [authenticate()](#await-authenticateparams-dict--none---dict) - 认证获取令牌
-- [sign_agent_md()](#await-sign_agent_mdcontent-str-aid-str--none---str) - 为 agent.md 生成尾部签名
-- [verify_agent_md()](#await-verify_agent_mdcontent-str-aid-str--none-cert_pem-str--none---dict) - 验证 agent.md 尾部签名
-- [upload_agent_md()](#await-upload_agent_mdcontent-str---dict) - 上传自己的 agent.md
-- [download_agent_md()](#await-download_agent_mdaid-str---str) - 下载指定 AID 的 agent.md
+- [sign_agent_md()](#await-sign_agent_mdcontent-str-aid-str--none---str) - 为 agent.md 生成尾部签名 **（已 deprecated，建议改用 `client.publish_agent_md`）**
+- [verify_agent_md()](#await-verify_agent_mdcontent-str-aid-str--none-cert_pem-str--none---dict) - 验证 agent.md 尾部签名 **（已 deprecated，建议改用 `client.fetch_agent_md`）**
+- [upload_agent_md()](#await-upload_agent_mdcontent-str---dict) - 上传自己的 agent.md **（已 deprecated，建议改用 `client.publish_agent_md`）**
+- [download_agent_md()](#await-download_agent_mdaid-str---str) - 下载指定 AID 的 agent.md **（已 deprecated，建议改用 `client.fetch_agent_md`）**
 - [renew_cert()](#await-renew_certparams-dict--none---dict) - 续期证书
 - [rekey()](#await-rekeyparams-dict--none---dict) - 密钥轮换
 - [request_cert()](#await-request_certparams-dict---dict) - 通用证书请求
@@ -394,58 +397,99 @@ for item in identities:
 
 ---
 
-### `set_local_agent_md_path(path: str) -> str` — agent.md 版本一致性
+### `await publish_agent_md(path: str) -> dict` — agent.md 发布主 API
 
-记录本地 `agent.md` 文件路径并一次性计算 etag（带引号的 sha256 hex，与服务端 `_agent_md_etag` 算法严格一致）。
+读取本地 `agent.md` 文件 → 调用 `auth.sign_agent_md` 在尾部追加 `<!-- AUN-SIGNATURE -->` 块 → 调用 `auth.upload_agent_md` 上传到服务端，并以**上传字节的 sha256**计算 quoted etag 写入内部 `_local_agent_md_etag`，使后续应用事件 payload 中的 `_agent_md.local_etag` 字段反映服务端实际生效的版本。
 
-**用途：** 配合服务端 Gateway 在每次 RPC 响应注入的 `_meta.agent_md_etag`，让 SDK 应用层判断 "本地 agent.md 是否已发布到服务端 / 服务端是否有新版本"。
+**API 跨语言对齐：**
+
+| SDK | 签名 |
+|------|------|
+| Python | `await client.publish_agent_md(path: str) -> dict` |
+| TypeScript（Node） | `await client.publishAgentMd(path: string)` |
+| Go | `client.PublishAgentMD(ctx, path string) (map[string]any, error)` |
+| C++ | `client.PublishAgentMd(path, callback)` |
+| JavaScript（浏览器） | `await client.publishAgentMd(content: string)` — 浏览器无文件系统，接收 markdown 文本 |
+
+**返回值：** 透传 `auth.upload_agent_md` 的返回，含 `aid` / `etag` / `last_modified` / `agent_md_url` / `bytes`。
+
+**异常：**
+- `ValidationError`：path / content 为空
+- `FileNotFoundError`（其它语言对应）：文件不存在
+- `StateError`：尚未持有本地身份
+- `AUNError`：上传失败
+
+**示例：**
+
+```python
+result = await client.publish_agent_md("/path/to/agent.md")
+print(result["agent_md_url"])
+```
+
+---
+
+### `await fetch_agent_md(aid: str | None = None, save_path: str | None = None) -> dict` — agent.md 下载主 API
+
+下载指定 AID 的 `agent.md`，自动调用 `auth.verify_agent_md` 验签；`aid` 缺省取本地身份；可选 `save_path` 写盘；若目标 aid 是自己则同步刷新内部 `_local_agent_md_etag` 并计算 `in_sync`。
 
 **API 跨语言对齐：**
 
-| SDK | 设置方法 | 读本地 etag | 读远端 etag |
-|------|---------|-----------|----------|
-| Python | `client.set_local_agent_md_path(path)` | `client.get_local_agent_md_etag()` | `client.get_remote_agent_md_etag()` |
-| TypeScript | `client.setLocalAgentMdPath(path)` | `client.getLocalAgentMdEtag()` | `client.getRemoteAgentMdEtag()` |
-| Go | `client.SetLocalAgentMDPath(path) string` | `client.GetLocalAgentMDEtag() string` | `client.GetRemoteAgentMDEtag() string` |
-| C++ | `client.SetLocalAgentMdPath(path)` | `client.GetLocalAgentMdEtag()` | `client.GetRemoteAgentMdEtag()` |
-| JavaScript（浏览器） | `client.setLocalAgentMdContent(content)` | `client.getLocalAgentMdEtag()` | `client.getRemoteAgentMdEtag()` |
+| SDK | 签名 |
+|------|------|
+| Python | `await client.fetch_agent_md(aid=None, save_path=None) -> dict` |
+| TypeScript（Node） | `await client.fetchAgentMd(aid?, savePath?)` |
+| Go | `client.FetchAgentMD(ctx, aid string, savePath string) (*AgentMDInfo, error)` |
+| C++ | `client.FetchAgentMd(aid, save_path, callback)` |
+| JavaScript（浏览器） | `await client.fetchAgentMd(aid?)` — 无 savePath（浏览器无文件系统） |
 
-**JavaScript 特殊说明：** 浏览器无法读本地文件，改为接收文本内容直接计算 etag（业务侧可用 `<input type=file>` 读出文本传入）。TS SDK 在 Node 环境读文件，浏览器环境返回空串并 warn。
+**返回字段：**
 
-**返回值：** 当前 etag（形如 `"abc123..."` 带引号），文件不存在/读取失败时返回空串，**不抛异常**。
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aid` | `str` | 实际下载的 AID（缺省时为自身 AID） |
+| `content` | `str` | agent.md 完整文本 |
+| `signature` | `dict` | `auth.verify_agent_md` 的返回（status / verified / reason / cert_fingerprint / timestamp） |
+| `in_sync` | `bool \| None` | 仅当 aid 是自己时给出：本地 etag == 服务端 etag；否则为 `null` |
+| `saved_to` | `str \| None` | 若传了 save_path 且写盘成功，返回路径；其他情况为 `null`（JS 浏览器版无此字段） |
+| `save_error` | `str \| None` | 写盘失败原因；不影响下载成功（JS 浏览器版无此字段） |
 
-**应用层事件注入：** SDK 在 publish `message.received` / `group.message_created` 等应用事件时，会自动给 payload 加 `_agent_md` 字段：
+**异常：**
+- `ValidationError`：未传 aid 且本地无身份
+- `NotFoundError`：服务端 404
+- `AUNError`：其他 HTTP 错误
+
+**etag 缓存：** 内部沿用 `auth.download_agent_md` 的 If-None-Match / 304 缓存机制；命中 304 时返回上次缓存的内容。
+
+**示例：**
+
+```python
+# 拉自己的 agent.md，并判断是否与服务端同步
+info = await client.fetch_agent_md()
+print(info["signature"]["status"], info["in_sync"])
+
+# 拉别人的 agent.md，并存到本地路径
+info = await client.fetch_agent_md("bob.agentid.pub", save_path="./bob.md")
+```
+
+---
+
+### `_agent_md` 事件 payload 字段（保留）
+
+SDK 在 publish `message.received` / `group.message_created` 等应用事件时仍会自动注入：
 
 ```python
 {
   "_agent_md": {
-    "local_etag": "\"abc...\"",   # 本地 agent.md 的 etag
-    "remote_etag": "\"def...\"",  # gateway 注入的服务端 etag
+    "local_etag": "\"abc...\"",   # publish_agent_md / fetch_agent_md（自身）后内部计算
+    "remote_etag": "\"def...\"",  # gateway 在每次 RPC envelope._meta.agent_md_etag 注入
   },
   # ... 原有业务字段
 }
 ```
 
-**典型用法：**
+应用层比对二者是否一致即可知本地是否需要重新 publish。
 
-```python
-client = AUNClient()
-client.set_local_agent_md_path("/path/to/agent.md")  # 启动时调一次
-
-await client.connect(auth)
-
-@client.on("message.received")
-async def on_msg(payload):
-    meta = payload.get("_agent_md", {})
-    if meta["local_etag"] and meta["remote_etag"] and meta["local_etag"] != meta["remote_etag"]:
-        # 本地与服务端不一致，提示用户重新上传
-        print("agent.md 已变化，请调用 client.auth.upload_agent_md() 同步")
-```
-
-**注意事项：**
-- 文件改了之后需要再次调用 `set_local_agent_md_path()` 触发重算（设计上一次性计算，不监听文件 mtime）
-- 服务端 etag 来自 Gateway 缓存（5 分钟 TTL，上传后通过 kernel 事件立即失效）
-- 注入失败被吞，**绝不影响业务路径**
+> **注意：** v0.x 起删除了 `set_local_agent_md_path()` / `get_local_agent_md_etag()` / `get_remote_agent_md_etag()` 三个旧 API。`_local_etag` 现在由 `publish_agent_md` / `fetch_agent_md(自身 aid)` 自动计算并缓存；不再支持外部直接设置或读取。
 
 ---
 
@@ -509,6 +553,46 @@ result = await client.auth.create_aid({"aid": MY_AID})
 
 ---
 
+### `await check_aid(params: dict) -> dict`
+
+检查 AID 的本地密钥/证书完整性和远程注册状态。用于首次启动时判断是创建还是恢复，或连接前确认本地状态。
+
+**参数**
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `aid` | `str` | 是 | 要检查的 AID |
+
+**返回值**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `status` | `str` | `local_ready` / `local_incomplete` / `available` / `registered_remote` / `unknown` |
+| `can_register` | `bool\|null` | 是否可注册（`local_ready` 时为 `false`） |
+| `local` | `dict` | 本地状态详情（`exists` / `complete` / `private_key` / `public_key` / `certificate` / `issues`） |
+| `remote` | `dict` | 远程状态（`status`: `not_checked` / `registered` / `available` / `error`） |
+
+```python
+result = await client.auth.check_aid({"aid": "alice.agentid.pub"})
+if result["status"] == "local_ready":
+    # 可以直接连接
+    pass
+elif result["can_register"]:
+    # AID 可用，创建新身份
+    await client.auth.create_aid({"aid": "alice.agentid.pub"})
+```
+
+**跨语言**
+
+| 语言 | 调用方式 |
+|------|----------|
+| Python | `await client.auth.check_aid({"aid": "..."})` |
+| TypeScript | `await client.auth.checkAid({ aid: '...' })` |
+| Go | `client.Auth.CheckAID(ctx, map[string]any{"aid": "..."})` |
+| C++ | `client->Auth()->CheckAID("...", callback)` |
+
+---
+
 ### `await authenticate(params: dict | None) -> dict`
 
 执行双向 ECDSA 挑战-响应认证，获取访问令牌。
@@ -537,6 +621,8 @@ auth = await client.auth.authenticate({"aid": MY_AID})
 
 ### `await sign_agent_md(content: str, aid: str | None = None) -> str`
 
+> **⚠️ Deprecated。** 主要场景请改用 `client.publish_agent_md(path)`，它内部已包含读文件 + 签名 + 上传一整套流程。`sign_agent_md` 仅作为离线签名（先签名后异步发布、给非 SDK 渠道发送等）的底层工具继续保留，未来版本将移除。
+
 为 `agent.md` 生成尾部签名块。
 
 **参数**
@@ -560,6 +646,8 @@ auth = await client.auth.authenticate({"aid": MY_AID})
 
 ### `await verify_agent_md(content: str, aid: str | None = None, cert_pem: str | None = None) -> dict`
 
+> **⚠️ Deprecated。** 主要场景请改用 `client.fetch_agent_md(aid)`，它内部已包含下载 + 自动验签 + etag 缓存。`verify_agent_md` 仅作为对纯文本 agent.md（来自非 SDK 渠道）的验签底层工具继续保留，未来版本将移除。
+
 验证 `agent.md` 尾部签名。
 
 **参数**
@@ -592,6 +680,8 @@ auth = await client.auth.authenticate({"aid": MY_AID})
 
 ### `await upload_agent_md(content: str) -> dict`
 
+> **⚠️ Deprecated。** 请改用 `client.publish_agent_md(path)`，它会自动读文件、签名、上传并刷新内部 etag。`upload_agent_md` 仅作底层 API 继续保留以兼容旧代码，未来版本将移除。
+
 上传当前 AID 的公开 `agent.md` 文档。
 
 **参数**
@@ -636,6 +726,8 @@ name: Alice
 
 ### `await download_agent_md(aid: str) -> str`
 
+> **⚠️ Deprecated。** 请改用 `client.fetch_agent_md(aid)`，它会自动下载、验签、刷新内部 etag，并支持可选写盘。`download_agent_md` 仅作底层 API 继续保留以兼容旧代码，未来版本将移除。
+
 匿名下载指定 AID 的公开 `agent.md` 文档。
 
 **参数**

package/_packed_docs/sdk/09-message-rpc-manual.md

@@ -20,8 +20,8 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | 方法 | 说明 |
 |------|------|
 | [message.send](#messagesend) | 发送消息 |
-| [message.thought.put](#messagethoughtput) | 写入某个 P2P 上下文的思考内容 |
-| [message.thought.get](#messagethoughtget) | 读取某个 P2P 上下文的思考内容 |
+| [message.thought.put](#messagethoughtput) | 写入某个 P2P 上下文的思考内容 |
+| [message.thought.get](#messagethoughtget) | 读取某个 P2P 上下文的思考内容 |
 | [message.pull](#messagepull) | 增量拉取消息 |
 | [message.ack](#messageack) | 确认送达 |
 | [message.recall](#messagerecall) | 撤回消息 |
@@ -43,7 +43,6 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | 事件 | 说明 |
 |------|------|
 | [event/message.received](#eventmessagereceived) | 收到新消息 |
-| [event/message.ack](#eventmessageack) | 消息被确认 |
 | [event/message.recalled](#eventmessagerecalled) | 消息被撤回 |
 
 ---
@@ -76,13 +75,13 @@ P2P `message.*` 的最终投递语义由连接阶段声明的 `delivery_mode`
 | `to` | string | 是 | — | 接收方 AID |
 | `payload` | object | 是 | — | 消息内容（任意 JSON 对象） |
 | `type` | string | 否 | — | 信封/封装类型，普通业务消息无需填写；SDK 加密发送时自动使用 `e2ee.encrypted` |
-| `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
-| `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
-| `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
-| `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
-
-> 连接级 `delivery_mode` 在 `auth.connect` 阶段声明，结构见 `02-WebSocket协议.md`。Python SDK 的 P2P 消息发送会沿用当前连接的 `delivery_mode`，应用层发送时无需重复指定。
-> `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
+| `encrypted` | boolean | 否 | `false` | 底层 RPC 的 E2EE 标记。Python SDK 便捷层通常使用 `encrypt` 入参并由 SDK 自动填充此字段 |
+| `message_id` | string | 否 | — | 幂等键（客户端提供或服务端生成 UUID） |
+| `timestamp` | integer | 否 | — | 客户端时间戳（毫秒）。**服务端忽略此字段，始终使用服务端时间** |
+| `protected_headers` / `headers` | object | 否 | — | SDK 加密前读取的 E2EE 信封元数据，类似 HTTP headers；服务端不解释，接收端验 `_auth` 后在 `e2ee.protected_headers` 暴露 |
+
+> 连接级 `delivery_mode` 在 `auth.connect` 阶段声明，结构见 `02-WebSocket协议.md`。Python SDK 的 P2P 消息发送会沿用当前连接的 `delivery_mode`，应用层发送时无需重复指定。
+> `protected_headers` 只在 SDK 加密路径生效；裸 RPC 发送明文或已加密信封时，调用方需自行遵守 [05-E2EE加密通信](05-E2EE加密通信.md#protectedheaders-与可验证上下文) 的格式和校验规则。
 
 ### Payload 参考约定
 
@@ -140,24 +139,24 @@ result = await client.call("message.send", {
 
 ## message.thought.put
 
-写入当前发送者针对一个上下文的思考内容。它不是普通消息：不广播、不进 `message.pull`、不占用收件箱 `seq`，只通过 `message.thought.get` 主动读取。
+写入当前发送者针对一个上下文的思考内容。它不是普通消息：不广播、不进 `message.pull`、不占用收件箱 `seq`，只通过 `message.thought.get` 主动读取。
 
 SDK 调用时必须走 P2P E2EE。应用层传入明文 `payload`，SDK 会加密成 `e2ee.encrypted` 信封、补齐 `thought_id` / `timestamp`，并附加 `client_signature`。裸 WebSocket 客户端若绕过 SDK，则必须自行完成同等加密和签名。
 
-存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
+存储键为 `sender_aid + peer_aid + context.type + context.id`。其中 `sender_aid` 由认证态派生，`peer_aid` 来自 `to`；`context` 是 thought head 的唯一 selector，推荐使用 `{"type": "run", "id": "run-xxx"}`。同一会话里每个 sender 保留最近 N 个 context 对应的 head，N 由 Message 服务配置 `max_thought_heads_per_sender` 控制，当前默认值为 5；同一个 head 下可追加多条 thought item。
 
 ### 参数
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `to` | string | 是 | P2P 会话另一方 AID，不能是 `group.{issuer}` |
-| `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
-| `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
-| `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
-| `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
-| `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `mt-*` |
-| `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
-| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；`context` 会被 SDK 复制进信封并单独验 `_auth` |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `to` | string | 是 | P2P 会话另一方 AID，不能是 `group.{issuer}` |
+| `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
+| `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
+| `payload` | object | 是 | SDK 加密前的思考内容；推荐格式见 [09-payload-reference](09-payload-reference.md#thought思考内容) |
+| `encrypt` | boolean | 否 | SDK 侧固定按 `true` 处理；`false` 会被拒绝 |
+| `thought_id` | string | 否 | thought item ID；不传时 SDK 生成 `mt-*` |
+| `timestamp` | integer | 否 | 客户端时间戳；不传时 SDK 生成 |
+| `protected_headers` / `headers` | object | 否 | SDK 加密前读取的 E2EE 信封元数据；`context` 会被 SDK 复制进信封并单独验 `_auth` |
 
 ### SDK 调用示例
 
@@ -203,20 +202,20 @@ await client.call("message.thought.put", {
 
 ## message.thought.get
 
-读取指定发送者针对指定上下文的当前思考内容。`get` 是查询操作，可重复调用；它不触发 push/pull、ack 或 replay 消费。
+读取指定发送者针对指定上下文的当前思考内容。`get` 是查询操作，可重复调用；它不触发 push/pull、ack 或 replay 消费。
 
 ### 参数
 
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `sender_aid` | string | 是 | thought 作者 AID |
-| `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
-| `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
-| `peer_aid` / `to` | string | 条件必填 | P2P 会话另一方。读取自己写的 thought 时必须提供；读取对方写给当前认证 AID 的 thought 时可省略，服务端自动用当前认证 AID 作为 peer |
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `sender_aid` | string | 是 | thought 作者 AID |
+| `context.type` | string | 是 | 思考的上下文类型，推荐 `run` |
+| `context.id` | string | 是 | 思考的上下文 ID，如 `run_id` |
+| `peer_aid` / `to` | string | 条件必填 | P2P 会话另一方。读取自己写的 thought 时必须提供；读取对方写给当前认证 AID 的 thought 时可省略，服务端自动用当前认证 AID 作为 peer |
 
 ### SDK 调用示例
 
-读取 Bob 针对当前上下文的思考：
+读取 Bob 针对当前上下文的思考：
 
 ```python
 result = await client.call("message.thought.get", {
@@ -388,14 +387,10 @@ for msg in result["messages"]:
 |------|------|------|
 | `success` | boolean | 操作是否成功 |
 | `ack_seq` | integer | 本次推进到的 ack_seq |
-| `event_published` | boolean | 可选。`false` 表示 DB 已写入但 ack 事件发布失败（部分成功语义） |
-| `event_error` | string | 可选。仅 `event_published=false` 时出现，包含事件发布错误详情 |
-
-其中 `event_published` / `event_error` 为可选字段：当 ack 游标已成功写入数据库，但事件发布失败时，当前实现会返回 `{"success": true, "ack_seq": ..., "event_published": false, "event_error": "..."}`，提示调用方不要因重试而重复推进状态。
 
 ### 副作用
 
-确认成功后，服务端向**发送方**推送 `event/message.ack` 事件。
+确认成功后仅推进接收方消费游标。服务端不会向发送方或其他客户端推送 `message.ack` 事件，也不会把对端已读状态作为协议通知暴露。
 
 ### 示例
 
@@ -536,38 +531,6 @@ client.on("message.received", lambda msg: print(msg["payload"]))
 
 ---
 
-## event/message.ack
-
-消息被接收方确认时推送给**发送方**。
-
-### Payload
-
-```json
-{
-    "to": "bob.agentid.pub",
-    "ack_seq": 150,
-    "device_id": "device-001",
-    "slot_id": "slot-a",
-    "timestamp": 1234567890000
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `to` | string | **确认方（接收方）AID** — 即执行 ack 操作的一方 |
-| `ack_seq` | integer | 已确认的最大 seq |
-| `device_id` | string | 触发 ack 的设备标识；legacy 客户端为空字符串 |
-| `slot_id` | string | 触发 ack 的消费槽位；空字符串表示设备单实例或 legacy 路径 |
-| `timestamp` | integer | 服务端时间戳（毫秒） |
-
-### 订阅
-
-```python
-client.on("message.ack", lambda ev: print(f"{ev['to']}[{ev['device_id']}/{ev['slot_id']}] 已确认到 seq {ev['ack_seq']}"))
-```
-
----
-
 ## event/message.recalled
 
 消息被发送方撤回时推送给**接收方**。

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/auth.js

@@ -837,16 +837,19 @@ export class AuthFlow {
                     if (!receivedChallenge) {
                         // 首条消息是 challenge，忽略并发送 RPC 请求
                         receivedChallenge = true;
-                        ws.send(JSON.stringify({
+                        const requestPayload = JSON.stringify({
                             jsonrpc: '2.0',
                             id: `pre-${method}`,
                             method,
                             params,
-                        }));
+                        });
+                        this._log.debug(`short RPC request full: ${requestPayload}`);
+                        ws.send(requestPayload);
                         return;
                     }
                     // 第二条消息是 RPC 响应
                     globalThis.clearTimeout(timeout);
+                    this._log.debug(`short RPC response full: method=${method} ${JSON.stringify(msg)}`);
                     try {
                         ws.close();
                     }
@@ -981,6 +984,16 @@ export class AuthFlow {
     async _initializeSession(transport, nonce, token, opts) {
         const connectionKind = opts?.connectionKind ?? 'long';
         const shortTtlMs = opts?.shortTtlMs ?? 0;
+        const extraInfo = opts?.extraInfo ?? {};
+        // _capabilities 来自 extra_info；可选覆盖默认能力声明，不会透传到服务端
+        const overrideCaps = extraInfo._capabilities;
+        const capabilities = isJsonObject(overrideCaps) ? overrideCaps : {
+            e2ee: true,
+            group_e2ee: true,
+            // AUN E2EE V2: 默认仅声明 V2 能力（V2-only 客户端）
+            supported_p2p_e2ee: ['e2ee_v2'],
+            supported_group_e2ee: ['group_e2ee_v2'],
+        };
         const request = {
             nonce,
             auth: { method: 'kite_token', token },
@@ -988,7 +1001,7 @@ export class AuthFlow {
             device: { id: String(opts?.deviceId ?? this._deviceId ?? ''), type: 'sdk' },
             client: { slot_id: String(opts?.slotId ?? this._slotId ?? '') },
             delivery_mode: opts?.deliveryMode ?? { mode: 'fanout' },
-            capabilities: { e2ee: true, group_e2ee: true },
+            capabilities,
         };
         // 长短连接选项：默认 long 时不写入 options（保持 wire 兼容）
         if (connectionKind === 'short') {
@@ -999,9 +1012,16 @@ export class AuthFlow {
             request.options = options;
         }
         // extra_info：应用层自定义信息（PID/HOME/备注等），踢人时透传给被踢方
-        const extraInfo = opts?.extraInfo;
+        // _ 前缀字段是内部覆盖字段，不透传到服务端
         if (extraInfo && Object.keys(extraInfo).length > 0) {
-            request.extra_info = extraInfo;
+            const filtered = {};
+            for (const [k, v] of Object.entries(extraInfo)) {
+                if (!k.startsWith('_'))
+                    filtered[k] = v;
+            }
+            if (Object.keys(filtered).length > 0) {
+                request.extra_info = filtered;
+            }
         }
         this._log.debug(`auth.connect send: device_id=${opts?.deviceId ?? ''} slot_id=${opts?.slotId ?? ''} kind=${connectionKind}`);
         const result = await transport.call('auth.connect', request);