evolcore 0.0.23 → 0.0.25

package/kits/docs/aun/CHEATSHEET.md

@@ -1,19 +1,19 @@
-# AUN 协议速查表
-
-## 命名空间
-
-| 命名空间 | 作用 |
-|---|---|
-| `auth.*` | AID 创建、认证、JWT |
-| `message.*` | 点对点消息收发 |
-| `group.*` | 群组生命周期、群消息 |
-| `storage.*` | 文件上传下载 |
-| `stream.*` | 实时流（语音/视频/token） |
-| `meta.*` | ping、状态、信任根查询 |
-| `nameservice.*` | AID 名字注册查询 |
-| `custody.*` | AID 托管 |
-| `peer.*` / `relay.*` | 直连/中继认证 |
-
-## Group 使用入口
-
-日常群操作使用 `ec group`，详见 `evolcore/group.md`。群文件使用 `ec fs`，详见 `evolcore/fs.md`。
+# AUN 协议速查表
+
+## 命名空间
+
+| 命名空间 | 作用 |
+|---|---|
+| `auth.*` | AID 创建、认证、JWT |
+| `message.*` | 点对点消息收发 |
+| `group.*` | 群组生命周期、群消息 |
+| `storage.*` | 文件上传下载 |
+| `stream.*` | 实时流（语音/视频/token） |
+| `meta.*` | ping、状态、信任根查询 |
+| `nameservice.*` | AID 名字注册查询 |
+| `custody.*` | AID 托管 |
+| `peer.*` / `relay.*` | 直连/中继认证 |
+
+## Group 使用入口
+
+日常群操作使用 `ec group`，详见 `evolcore/group.md`。群文件使用 `ec fs`，详见 `evolcore/fs.md`。

package/kits/docs/aun/SYNC_PROTOCOL.md

@@ -1,15 +1,15 @@
-# AUN 协议同步 SOP
-
-<!-- TODO: 填充上游协议同步流程 -->
-
-## 同步时机
-
-- AUN SDK 有新版本发布时
-- 协议文档有重大变更时
-
-## 同步步骤
-
-1. 拉取上游最新协议文档
-2. 对比本地认知包与上游差异
-3. 更新 `$KITS_RULES/04-aun.md` 和 `$KITS_DOCS/aun/` 下相关文档
-4. 更新索引
+# AUN 协议同步 SOP
+
+<!-- TODO: 填充上游协议同步流程 -->
+
+## 同步时机
+
+- AUN SDK 有新版本发布时
+- 协议文档有重大变更时
+
+## 同步步骤
+
+1. 拉取上游最新协议文档
+2. 对比本地认知包与上游差异
+3. 更新 `$KITS_RULES/04-aun.md` 和 `$KITS_DOCS/aun/` 下相关文档
+4. 更新索引

package/kits/docs/channels/aun.md

@@ -1,56 +1,56 @@
-# AUN 渠道
-
-> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
-> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
-> 群聊使用 `evolcore/group.md`；群文件使用 `evolcore/fs.md`。
-
-## 概述
-
-AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolcore 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
-
-## 配置
-
-AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolcore 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
-
-### agent 配置（`agents/<aid>/config.json`）
-
-```json
-{
-  "$schema_version": 1,
-  "aid": "myagent.agentid.pub",
-  "enabled": true,
-  "owners": ["owner.agentid.pub"],
-  "channels": [],
-  "active_baseagent": "claude"
-}
-```
-
-| 字段 | 说明 |
-|------|------|
-| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
-| `enabled` | agent 是否启用 |
-| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
-| `admins` | admin 的 AID 列表 |
-| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
-
-> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
-
-### AUN keystore seed
-
-AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置项或环境变量入口。
-检测到历史自定义值时 daemon 会拒绝启动并提示联系管理人员，避免用错误值加载现有身份。
-
-> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCORE_HOME`。
-
-## 特有机制
-
-- **隐式创建**：aun 渠道由顶层 `aid` 派生，无独立配置实例；这是它与飞书等渠道最大的不同。
-- **网关发现**：连接前查询 `https://<aid>/.well-known/aun-gateway` 获取网关地址（AID 本身即域名）；per-agent 流程不提供手填 gateway 的入口，发现失败即连接失败。
-- **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
-- **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCORE_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
-  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
-- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；keystore seed 由 EvolCore 固定管理。
-- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
-- **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
-- **群 @ 处理策略**：`mention_mode=disabled|mention-only` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
-- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。
+# AUN 渠道
+
+> 知识性文档：AUN 渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（aun 渠道用 `ec msg send` / `ec group send`），不在本文。
+> 群聊使用 `evolcore/group.md`；群文件使用 `evolcore/fs.md`。
+
+## 概述
+
+AUN 渠道把 agent 接入 AUN（Agent Union Network），对端以 **AID** 为身份标识（既是身份也是地址）。evolcore 通过 AUN SDK（`@agentunion/fastaun`）维护到 Gateway 的 WebSocket 长连接，支持私聊、群聊、文件、E2EE 加密。
+
+## 配置
+
+AUN 渠道是**隐式**的——它不写在 `channels[]` 数组里，而是从 agent 自身的 AID 自动创建。一个 agent 就是一个 AID，启动时 evolcore 用顶层 `aid` 字段隐式构造唯一的 aun 实例（`channel-loader.ts`）。所以真实的 agent config.json 里 `channels` 数组通常是空的（飞书等非 aun 渠道才往里加）。
+
+### agent 配置（`agents/<aid>/config.json`）
+
+```json
+{
+  "$schema_version": 1,
+  "aid": "myagent.agentid.pub",
+  "enabled": true,
+  "owners": ["owner.agentid.pub"],
+  "channels": [],
+  "active_baseagent": "claude"
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | agent 的 AID，**即 aun 渠道身份**（隐式创建，无需在 channels[] 声明） |
+| `enabled` | agent 是否启用 |
+| `owners` | owner 的 **AID** 列表（最高权限）；首个 owner 用于首次连接发欢迎消息 |
+| `admins` | admin 的 AID 列表 |
+| `channels` | 非 aun 渠道（飞书等）的实例数组；aun 不在此 |
+
+> `owners`/`admins` 用 **AID**，不是渠道原生 ID。
+
+### AUN keystore seed
+
+AUN keystore seed 由 EvolCore 使用固定应用值管理，不再提供配置项或环境变量入口。
+检测到历史自定义值时 daemon 会拒绝启动并提示联系管理人员，避免用错误值加载现有身份。
+
+> Gateway 不在配置里手填：连接时从 AID 自动发现（见下）。Keystore 默认落在 `$EVOLCORE_HOME`。
+
+## 特有机制
+
+- **隐式创建**：aun 渠道由顶层 `aid` 派生，无独立配置实例；这是它与飞书等渠道最大的不同。
+- **网关发现**：连接前查询 `https://<aid>/.well-known/aun-gateway` 获取网关地址（AID 本身即域名）；per-agent 流程不提供手填 gateway 的入口，发现失败即连接失败。
+- **身份与信任**：每条入站消息携带发送者 AID，经四级 X.509 证书链（Root CA → Registry CA → Issuer CA → Agent）验签。
+- **agent.md 缓存**：对端名片 `https://<aid>/agent.md` 由 **AUN SDK 自动拉取并缓存**（`AgentMdManager`，带 ETag/TTL，默认 1 天内不重复探测）。缓存落在 **`$EVOLCORE_HOME/AIDs/<aid>/`**，每个 AID 两个文件：`agent.md`（带签名正文）+ `agentmd.json`（元数据：etag/last_modified/checked_at/verify_status）。本端与对端的 agent.md 都缓存于此。
+  - 关系层另存一份**派生**的精简身份 `relations/<peerKey>/peer-identity.json`（type/isAgent/name），由 evolcore 从 agent.md 提取，不是 agent.md 本体。
+- **E2EE 加密**：可选端到端加密，回复默认跟随对端消息加密状态（密文回密文，明文回明文）；keystore seed 由 EvolCore 固定管理。
+- **断线重连**：SDK 内置退避策略自动重连。实时连接状态用 `ec watch aid` 查看（`ec aid` 是身份/证书管理，不显示连接状态）。
+- **群 ID 格式**：当前协议规范使用 `g-{slug}.issuer-domain` canonical 形式，输入也可接受本域简写 `g-{slug}` 或兼容形式 `g-{slug}@issuer-domain`。历史会话里可能仍出现 `group.{issuer}/{group_no}` 一类旧格式，运行时需兼容读取。
+- **群 @ 处理策略**：`mention_mode=disabled|mention-only` 是群级配置，只决定哪些群消息进入 Agent LLM 上下文，不影响 AUN 协议层投递；被过滤消息仍应本地存档。
+- **身份体系**：对端以 AID 标识，关系层 peerKey 形如 `aun#alice.aid.pub`。

package/kits/docs/channels/feishu.md

@@ -1,56 +1,56 @@
-# 飞书渠道
-
-> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
-> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolcore 自动回复，agent 不调 CLI），不在本文。
-
-## 概述
-
-飞书渠道通过 evolcore 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
-
-## 配置
-
-飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
-
-```json
-{
-  "aid": "myagent.aid.pub",
-  "channels": [
-    {
-      "type": "feishu",
-      "name": "main",
-      "enabled": true,
-      "appId": "cli_xxx",
-      "appSecret": "<app-secret>",
-      "owners": ["ou_owner_user_id"],
-      "admins": ["ou_admin_user_id"]
-    }
-  ]
-}
-```
-
-### 实例字段
-
-| 字段 | 必填 | 说明 |
-|------|------|------|
-| `type` | 是 | 固定 `"feishu"` |
-| `name` | 是（数组形式） | 该 agent 内飞书实例的本地标识，不含 `#` |
-| `enabled` | 否 | 默认启用；`false` 关闭该实例 |
-| `appId` | 是 | 飞书自建应用 App ID |
-| `appSecret` | 是 | 飞书自建应用 App Secret |
-| `owners` | 否 | owner 的飞书 `user_id` 列表（最高权限） |
-| `admins` | 否 | admin 的飞书 `user_id` 列表 |
-| `flushDelay` | 否 | flush 间隔（秒），覆盖全局值 |
-| `debounce` | 否 | 入站消息去抖间隔（秒），覆盖全局值 |
-| `showActivities` | 否 | 思考过程展示范围：`all` / `dm-only` / `owner-dm-only` / `none` |
-
-> `owners`/`admins` 用飞书原生 `user_id`，**不是 AID**。
-
-agent 级（config.json 顶层）相关开关：
-- `enable_rich_content`：已废弃，仅为旧配置兼容保留；飞书继续按 Markdown/post 消息发送。
-
-## 特有机制
-
-- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
-- **交互卡片**：命令和交互请求可使用飞书卡片发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
-- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
-- **自动回复**：飞书是非 aun 渠道，回复由 evolcore 自动完成，agent 无需调用 `ec msg send`。
+# 飞书渠道
+
+> 知识性文档：飞书渠道的配置、参数与特有机制。**不依赖当前会话渠道**——任意会话都可按需 Read（在 aun 会话里也可查飞书）。
+> 运行时"怎么发消息"由注入的 `[channel]` 段决定（飞书是 evolcore 自动回复，agent 不调 CLI），不在本文。
+
+## 概述
+
+飞书渠道通过 evolcore 的 feishu channel 插件接入，对端以飞书 `user_id`（如 `ou_xxx`）为身份标识。支持单聊/群聊收发、合并转发解析、富文本卡片、文件/图片/视频消息。
+
+## 配置
+
+飞书渠道按 **per-agent** 配置，写在 `agents/<aid>/config.json` 的 `channels` 数组里。每个元素是一个独立实例，靠 `name` 区分；同一 agent 可配多个飞书实例。
+
+```json
+{
+  "aid": "myagent.aid.pub",
+  "channels": [
+    {
+      "type": "feishu",
+      "name": "main",
+      "enabled": true,
+      "appId": "cli_xxx",
+      "appSecret": "<app-secret>",
+      "owners": ["ou_owner_user_id"],
+      "admins": ["ou_admin_user_id"]
+    }
+  ]
+}
+```
+
+### 实例字段
+
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `type` | 是 | 固定 `"feishu"` |
+| `name` | 是（数组形式） | 该 agent 内飞书实例的本地标识，不含 `#` |
+| `enabled` | 否 | 默认启用；`false` 关闭该实例 |
+| `appId` | 是 | 飞书自建应用 App ID |
+| `appSecret` | 是 | 飞书自建应用 App Secret |
+| `owners` | 否 | owner 的飞书 `user_id` 列表（最高权限） |
+| `admins` | 否 | admin 的飞书 `user_id` 列表 |
+| `flushDelay` | 否 | flush 间隔（秒），覆盖全局值 |
+| `debounce` | 否 | 入站消息去抖间隔（秒），覆盖全局值 |
+| `showActivities` | 否 | 思考过程展示范围：`all` / `dm-only` / `owner-dm-only` / `none` |
+
+> `owners`/`admins` 用飞书原生 `user_id`，**不是 AID**。
+
+agent 级（config.json 顶层）相关开关：
+- `enable_rich_content`：已废弃，仅为旧配置兼容保留；飞书继续按 Markdown/post 消息发送。
+
+## 特有机制
+
+- **合并转发解析**：飞书的 `merge_forward` 消息会被自动展开为文本注入上下文（含"以下是引用的原消息"包裹）。
+- **交互卡片**：命令和交互请求可使用飞书卡片发送；卡片按钮**仅发起者可操作**，他人点击返回提示。
+- **身份体系**：对端以 `user_id` 标识，关系层 peerKey 形如 `feishu#ou_xxx`。
+- **自动回复**：飞书是非 aun 渠道，回复由 evolcore 自动完成，agent 无需调用 `ec msg send`。