evolclaw 3.1.4 → 3.1.6

package/kits/docs/context-assembly.md

@@ -0,0 +1,182 @@
+# 上下文组装机制（manifest）
+
+ECK 把"每条消息该给 base agent 看哪些上下文"这件事，交给一份 **manifest** 声明式描述，由 `renderKitSections`（`src/agents/kit-renderer.ts`）在每次处理消息时执行。本文是这套机制的完整参考。
+
+> 本文是按需载入文档。日常对话不需要读它——只有在排查"为什么某段上下文没出现/出现了"、要改 manifest、或要看实际渲染结果时才 Read。
+
+## 三个阶段
+
+evolclaw 收到消息 → 构造一份 **vars**（运行时变量，见下）→ `renderKitSections`：
+
+1. **选段**：按 manifest 顺序遍历每个 section，用它的 `when` 条件 + 当前 vars 判断是否加载。
+2. **渲染**：解析 section 路径里的 `$NAME` / `{{key}}` 占位符定位文件；`needsInjection:true` 的文件再跑一遍模板渲染（条件块 + 变量替换）。
+3. **拼装**：所有命中的文件内容包进一个 `<system-reminder>` 块，作为 system prompt 的一部分注入。
+
+整个过程对每次消息执行一次，结果同时落盘到调试目录（见"调试机制"）。
+
+## manifest 文件位置
+
+| 文件 | 角色 | 性质 |
+|------|------|------|
+| `$KITS/eck_manifest.json` | 基础 manifest（开发时维护） | 只读 |
+| `$ECK/eck_manifest.json` | 用户覆盖（可选，默认不存在） | 可写 |
+
+加载时合并两者（见"合并与覆盖"）。manifest 只加载一次并缓存。
+
+## section 字段
+
+manifest 是 `{ "$schema_version": 1, "sections": [...] }`。每个 section：
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `id` | ✓ | 唯一标识，覆盖合并的键 |
+| `type` | ✓ | `file`（单文件）或 `directory`（整目录） |
+| `file` | type=file | 文件路径，可含 `$NAME` / `{{key}}` |
+| `path` | type=directory | 目录路径 |
+| `pattern` | | 目录匹配 glob，默认 `*.md`（支持 `*` 和 `{a,b}`） |
+| `order` | ✓ | 排序，**升序**决定上下文中出现的先后 |
+| `needsInjection` | ✓ | `true`=按模板渲染（解析 `{{}}` 条件与变量）；`false`=原样读入 |
+| `when` | ✓ | 加载条件，`"always"` 或条件对象（见下） |
+| `enabled` | | `false` 时整段跳过 |
+| `description` | | 调试输出里的人类可读标签 |
+
+## when 条件求值
+
+`when` 是 `"always"` 或一个对象。求值规则（`evaluateWhen`）：
+
+| 写法 | 含义 |
+|------|------|
+| `"always"` | 恒为真 |
+| `{ "var": "X", "eq": V }` | `vars.X === V`；`eq:null` 匹配"未注入"（null/undefined） |
+| `{ "var": "X", "neq": V }` | `vars.X !== V`；`neq:null` 匹配"已注入" |
+| `{ "var": "X", "in": [...] }` | `vars.X` 在数组内 |
+| `{ "var": "X", "nin": [...] }` | `vars.X` 不在数组内 |
+| `{ "any": ["A","B"] }` | A、B 任一为真值 |
+| `{ "all": ["A","B"] }` | A、B 全为真值 |
+
+"真值"判定：非 `undefined`/`null`/`false`/`""`/`0`。
+
+典型用法：`{ "var": "chatType", "neq": null }` = "非 coding 场景才加载"；`{ "var": "groupId", "neq": null }` = "群聊才加载"。
+
+## 合并与覆盖
+
+无 `$ECK/eck_manifest.json` 时，直接用基础 manifest。存在时：
+
+- 覆盖文件含 `"mode": "replace"` → **完全替换**，只用覆盖文件的 sections。
+- 否则 **patch 合并**：以 `id` 为键，覆盖文件里同 id 的字段浅合并进基础 section（`{...base, ...override}`），新 id 追加。
+
+合并后统一按 `order` 升序排序。改某段行为（如关掉某层、调顺序、换条件）优先用覆盖文件，不动基础 manifest。
+
+## 路径与模板渲染
+
+### 路径占位符（所有 section 的 file/path）
+
+- `$NAME`（大写）→ 从 vars 取真值，如 `$KITS_DOCS` → 包内文档目录。
+- `{{key}}` → 从 vars 取真值，如 `{{chatType}}` → `private`，`{{peerKey}}` → `aun#alice.aid.pub`。
+
+任一占位符解析为空 → 该 section 视为"未解析"，跳过（调试输出标 `unresolved-vars`）。文件不存在 → 标 `not-exist`，也跳过。这是**正常机制**：很多 section 靠"路径解析不出来"自然落选（如 coding 场景没有 `$PERSONAL_DIR`）。
+
+### 模板渲染（仅 needsInjection:true 的文件）
+
+读入跑三遍：
+
+1. **条件块**（内层优先，可嵌套）：
+   - `{{?key}}...{{/}}` — key 为真值才保留
+   - `{{?key=value}}...{{/}}` — `String(vars.key)===value` 才保留
+   - `{{?key!=value}}...{{/}}` — 不等才保留
+2. **变量替换**：`{{key}}` 替换为值，非真值替换为空串。
+3. **清理**：删掉空行。
+
+`needsInjection:false` 的文件原样读入，不做任何替换（如 rules 目录、persona.md、各 venue 文档）。
+
+## 运行时变量（vars）目录
+
+vars 由 evolclaw 在 `message-processor.ts` 按当前会话构造。分两类：
+
+**路径类**（供占位符展开成真实路径）：
+`EVOLCLAW_HOME`、`PACKAGE_ROOT`、`CURRENT_PROJECT`、`KITS`、`KITS_RULES`、`KITS_DOCS`、`KITS_TEMPLATES`、`KITS_FRAGMENTS`、`PERSONAL_DIR`、`RELATIONS_DIR`、`VENUES_DIR`。
+
+**内容/场景类**（供 when 判断与模板替换）：
+
+| 变量 | 含义 |
+|------|------|
+| `selfAid` / `selfName` | 当前 agent 身份 |
+| `hasPersona` / `hasWorkingMemory` | 是否有人格 / 当前关注 |
+| `peerId` / `peerKey` / `peerName` | 对端原生 ID / 跨渠道键 / 显示名 |
+| `peerRole` / `peerType` | 对端角色（owner/admin/guest/...）/ 类型（human/agent） |
+| `groupId` | 群 ID（群聊时） |
+| `chatType` | `private` / `group` / `null`(coding) |
+| `channel` | 渠道类型（aun/feishu/...）|
+| `dispatch` | 群分发模式（mention/broadcast） |
+| `clientType` | 客户端类型（desktop/web/mobile） |
+| `permissionMode` / `readonly` | 权限模式 / 是否只读 |
+| `capabilities` | 当前渠道能力（图片输入/输出、文件发送） |
+| `project` / `CURRENT_PROJECT` | 项目目录名 / 完整路径 |
+| `sessionId` / `sessionName` / `sessionKey` / `sessionCreatedAt` / `threadId` | 会话标识与元信息 |
+| `chatMode` | `interactive` / `proactive` |
+| `baseAgent` / `baseAgentName` / `baseAgentModel` / `agentSessionId` | base agent 信息 |
+
+coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`、`peer*` 等均为空——这正是身份/关系/环境/渠道层落选的原因。
+
+## 默认 manifest 的段（按 order）
+
+| order | id | 类型 | 加载条件（when） | inject |
+|-------|----|----|------------------|--------|
+| 10 | rules | 目录 `$KITS_RULES` | always | ✗ |
+| 20 | identity-layer | fragment | chatType≠null | ✓ |
+| 21 | persona | `$PERSONAL_DIR/persona.md` | chatType≠null | ✗ |
+| 22 | working-memory | `$PERSONAL_DIR/memory/working.md` | chatType≠null | ✗ |
+| 30 | relation-layer | fragment | chatType∈{private,group} | ✓ |
+| 35 | peer-profile | `$RELATIONS_DIR/{{peerKey}}/profile.md` | peerKey≠null | ✗ |
+| 40 | venue-fragment | fragment | chatType≠null | ✓ |
+| 41 | venue-chattype | `$KITS_DOCS/venues/{{chatType}}.md` | chatType≠null | ✗ |
+| 42 | venue-channel-chattype | `$KITS_DOCS/venues/{{channel}}-{{chatType}}.md` | chatType≠null | ✗ |
+| 43 | venue-group-profile | `$VENUES_DIR/{{channel}}#{{groupId}}/profile.md` | groupId≠null | ✗ |
+| 44 | venue-client | `$KITS_DOCS/venues/client-{{clientType}}.md` | clientType≠null | ✗ |
+| 50 | channel-layer | fragment | channel≠null | ✓ |
+| 55 | commands | fragment | channel≠null | ✓ |
+| 60 | session | fragment | always | ✓ |
+| 70 | baseagent | fragment | baseAgent≠null | ✓ |
+
+> 注意：`session`(60) 是 `always`，`baseagent`(70) 只看 `baseAgent` 是否注入——这两段**与 chatType 无关**，coding 场景也会加载。所谓"coding 仅 rules"是近似说法：精确地说 coding 场景命中的是 rules + session + baseagent（其余因 chatType/channel 为空而落选）。
+
+## 输出结构
+
+所有命中 section 的文件内容拼成一个块，注入 system prompt：
+
+```
+<system-reminder>
+EvolClaw Context Kit documents are shown below.
+
+Contenu de <展示路径> (<id — description>):
+
+<文件内容>
+
+...（每个文件一段，按 order）
+
+IMPORTANT: Use this context when it affects the current interaction.
+</system-reminder>
+```
+
+展示路径会把绝对路径回缩成 `$KITS_RULES`/`$AGENT_DIR` 等别名。`needsInjection:true` 的段额外单独汇总到 `fragments-*.md` 调试文件（见下）。
+
+## 调试机制（看实际渲染结果）
+
+每次渲染都把结果落盘到 **`$EVOLCLAW_HOME/data/eck-debug/`**，文件名带时间戳（`<字段>-YYYY-MM-DD-HH-MM-SS`）：
+
+| 文件 | 内容 |
+|------|------|
+| `vars-<ts>.json` | 本次注入的全部 vars 真值 + 每个变量的中文说明 |
+| `context-<ts>.md` | 最终注入 base agent 的完整 `<system-reminder>` 块（即上面"输出结构"的实际产物） |
+| `fragments-<ts>.md` | 仅经过模板渲染（needsInjection）的段，单独汇总，便于核对 `{{}}` 替换是否正确 |
+| `manifest-<ts>.md` | **诊断报告**：每个 section 的 when 是否通过、路径解析状态（ok/unresolved-vars/not-exist/skipped）、是否被用上、是否注入；含未解析占位符清单 |
+
+排查"某段为什么没出现"：看 `manifest-<ts>.md` 里该 section 的 `status` 和 `unresolved tokens`。看"实际给 agent 的全文"：读 `context-<ts>.md`。
+
+调试文件保留 24 小时，`cleanEckDebug` 自动清理过期的。
+
+## 缓存与热加载
+
+- **manifest 缓存**：`_manifestCache`，进程内只加载一次。改了 manifest 需触发 `invalidateKitCache()`（或重启）才生效。
+- **文件内容缓存**：`_sessionPathCache` 按 `sessionId` 缓存已读文件内容；`invalidateSessionCache(sessionId)` 清单个会话。
+- rules / fragments / docs 这些 `kits/` 下的文件，改完一般随会话重建生效（缓存按会话隔离）；manifest 本身的结构改动需要 invalidate。

package/kits/docs/evolclaw/INDEX.md

@@ -0,0 +1,43 @@
+# EvolClaw 命令集目录
+
+所有 `ec` 命令集的专属索引：用途、触发词、适用场景、详细文档。
+运行时 evolclaw 会通过 `commands` fragment 按当前场景（有无 peer/group、对端角色）
+注入一张精简能力卡，指向本目录下对应文档；需要完整用法时 Read 对应文档。
+
+> 命令通用约定：以自己 AID 为发送者；必须走 CLI，不在会话里直接输出对外消息；
+> `--format json` 所有命令通用；`--app <name>` 指定应用 slot（独立消费通道）。
+
+## 对外通信 / 网络类（连 AUN，以 AID 为发送者）
+
+| 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
+|--------|------|--------|----------|------|
+| `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员 | 群聊（groupId） | `group.md` |
+| `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
+| `ec storage` | 文件存储 | 上传/下载/配额 | 任意有渠道场景 | `storage.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
+| `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
+
+## 会话自管理类（不连 AUN，操作当前会话）
+
+| 命令集 | 用途 | 触发词 | 文档 |
+|--------|------|--------|------|
+| `ec ctl` | 会话运行时自管理 | 切模型/推理强度/压缩/重启/主动发消息 | `ctl.md` |
+
+## 本地工具类（不连 AUN，操作本地配置）
+
+| 命令集 | 用途 | 触发词 | 文档 |
+|--------|------|--------|------|
+| `ec model` | 模型管理（按作用域持久化） | 切模型/列模型/看当前/改强度 | `model.md` |
+
+## 开发者工具（非 agent 会话能力）
+
+| 命令 | 用途 | 说明 |
+|------|------|------|
+| `ec bench` | AUN 消息系统性能基准测试 | CLI 工具，agent 一般不主动调用；`ec bench --help` 查看用法 |
+
+## 其他
+
+| 文档 | 说明 |
+|------|------|
+| `self-summary.md` | 自我总结流程指南 |

package/kits/docs/evolclaw/agent.md

@@ -0,0 +1,49 @@
+# ec agent — EvolAgent 生命周期管理
+
+管理本机托管的 EvolAgent（创建、启停、配置、热重载）。触发词：创建/新建/列出/查看/启用/禁用/删除/热重载/改配置。
+
+## 子命令
+
+```bash
+# 列出所有 agent
+ec agent list
+
+# 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
+ec agent show <aid>
+
+# 创建 agent（交互式）
+ec agent new [aid]
+
+# 创建 agent（非交互式，自动化场景）
+ec agent new <aid> --non-interactive --project <绝对路径> \
+  [--baseagent claude|codex|gemini] [--owner <aid>] \
+  [--name "<显示名>"] [--description "<text>"] [--force]
+
+# 启用 / 停用
+ec agent enable <aid>
+ec agent disable <aid>
+
+# 读 / 改单个配置字段（支持点路径，如 active_baseagent）
+ec agent get <aid> <key>
+ec agent set <aid> <key> <val>
+
+# 改 agent 名称（更新 agent.md 并重新上传）
+ec agent rename <aid> "<name>"
+
+# 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
+ec agent reload [aid]
+
+# 删除 agent（--purge 连数据一并清除）
+ec agent delete <aid> [--purge]
+```
+
+## 非交互创建必填项
+
+`ec agent new <aid> --non-interactive` 时：
+- 必填：`--project <absolute path>`
+- 可选：`--baseagent`（默认 PATH 中第一个可用项）、`--owner`、`--name`、`--description`、`--force`（覆盖已有 config.json）
+
+## 通用约定
+
+- `--format json` — 输出 JSON
+- `--help` / `-h` — 各子命令均支持，查看详细用法

package/kits/docs/evolclaw/aid.md

@@ -0,0 +1,49 @@
+# ec aid — AID 身份管理
+
+管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
+
+## 子命令
+
+```bash
+# 列出本地所有 AID（实测 sign+verify）
+ec aid list [筛选选项] [--no-verify]
+
+# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
+ec aid show <aid>
+
+# 创建新 AID 身份
+ec aid new <aid>
+
+# 远程探测 AID（是否存在 + 网关 + agent.md）
+ec aid lookup <aid>
+
+# agent.md 名片：签名上传 / 下载验签
+ec aid agentmd put <aid>
+ec aid agentmd get <aid>
+
+# 删除指定本地 AID（无网络注销）
+ec aid delete <aid>
+```
+
+## list 筛选选项
+
+不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
+- `--mine` — 仅本地可用身份（实测可签名+验签通过）
+- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
+- `--no-cert` — 仅无私钥无证书的孤儿目录
+- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
+
+输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
+
+## delete 批量清理
+
+批量删除**默认 dry-run，加 `--yes` 才真正执行**：
+- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
+- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
+- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+
+## 通用约定
+
+- `--format json` — 输出 JSON
+- `--help` / `-h` — 各子命令均支持

package/kits/docs/evolclaw/ctl.md

@@ -0,0 +1,46 @@
+# ec ctl — 会话运行时自管理
+
+对**当前会话**的运行时自管理：切模型、调推理强度、压缩上下文、切权限、重启服务。触发词：切模型/推理强度/压缩上下文/切权限/重启。
+
+> ctl 命令通过 IPC 转发给 daemon，仅在 evolclaw 托管环境中可用（依赖 `EVOLCLAW_SESSION_ID`）。
+
+## 查询
+
+```bash
+ec ctl status        # 查看会话状态
+ec ctl check         # 检查渠道健康状态
+ec ctl pwd           # 显示当前项目路径
+ec ctl help          # 显示帮助
+```
+
+## 配置
+
+```bash
+ec ctl model [model-id]            # 查看/切换模型（如 opus, sonnet, haiku）
+ec ctl effort [low|medium|high]    # 查看/切换推理强度
+ec ctl compact                     # 压缩当前会话上下文
+ec ctl perm [mode]                 # 查看/切换权限模式
+```
+
+## 消息（兜底用）
+
+```bash
+ec ctl send "<text>"      # 主动发送文本（proactive 模式）
+ec ctl file [channel] <path>   # 发送项目内文件
+```
+
+> 发消息**首选 `ec msg send <self-aid> <peer-id> "<text>"`**（见 msg.md）。
+> `ec ctl send` 只在拿不到自己的 AID 时兜底——它自动继承当前会话的 AID 和对端。
+
+## 运维
+
+```bash
+ec ctl restart [channel]   # 重启服务，或重连指定渠道
+```
+
+## 相关命令集
+
+- agent 全生命周期管理（创建/启停/配置）→ `ec agent`（见 agent.md）
+- AID 身份与 agent.md 名片 → `ec aid`（见 aid.md）
+
+ctl 内也转发了 `ec ctl agent <subcommand>`，但完整功能请直接用 `ec agent`。

package/kits/docs/evolclaw/group.md

@@ -0,0 +1,89 @@
+# ec group — 群聊消息与群管理
+
+群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员。
+
+以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
+
+## 消息
+
+```bash
+# 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
+ec group send <from> <group-id> "<text>" [--encrypt]
+
+# 文件（--as image|video|voice|file）
+ec group send <from> <group-id> --file <path> [--as <type>] [--text "<说明>"]
+
+# 自定义 payload
+ec group send <from> <group-id> --payload '<json>'
+
+# 拉取群消息（建议带 --app 独立消费通道，避免影响 daemon）
+ec group pull <from> <group-id> [--after-seq <N>] [--limit <N>] [--app <name>]
+
+# 确认已读（推进消费游标；同样建议带 --app）
+ec group ack <from> <group-id> <seq> [--app <name>]
+```
+
+@ 成员：
+- `--mention <aid>` — @ 某个成员，可多次，或单个槽位用逗号分隔多个（`--mention a,b,c`），每个 aid 都过格式校验
+- `--mention-all` — @ 所有人
+
+```bash
+ec group send <from> <group-id> "@bob 看下 PR" --mention bob.agentid.pub
+ec group send <from> <group-id> "通知" --mention alice.agentid.pub,bob.agentid.pub
+```
+
+> 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
+> 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
+> `ec group send <from> <group-id> -- --encrypt`
+
+## 群管理
+
+```bash
+# 创建群
+ec group create <from> "<name>" [--visibility public|private] [--description "<desc>"] [--join-mode <mode>]
+
+# 列出我加入的群
+ec group list <from> [--size <N>]
+
+# 查看群详情
+ec group info <from> <group-id>
+
+# 修改群信息
+ec group update <from> <group-id> [--name "<name>"] [--description "<desc>"]
+
+# 解散群
+ec group dissolve <from> <group-id>
+```
+
+## 成员
+
+```bash
+# 申请加入
+ec group join <from> <group-id> [--message "<msg>"] [--answer "<answer>"]
+
+# 退出群
+ec group leave <from> <group-id>
+
+# 邀请成员（可多个）
+ec group invite <from> <group-id> <member-aid> [<member-aid>...]
+
+# 踢出成员
+ec group kick <from> <group-id> <member-aid>
+
+# 列出群成员
+ec group members <from> <group-id> [--page <N>] [--size <N>]
+
+# 查看在线成员
+ec group online <from> <group-id>
+```
+
+## 通用约定
+
+- `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
+- `--format json` — 所有子命令通用
+- `--app <name>` — 指应用 slot（独立消费通道，不影响 daemon）
+- `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
+
+## 自主回复策略
+
+群聊中默认被 @ 才响应，可通过 venue policy 配置其他触发条件。

package/kits/docs/evolclaw/model.md

@@ -0,0 +1,51 @@
+# ec model — 模型管理命令集
+
+按作用域查看/设置 agent 使用的模型与推理强度。触发词：切模型/列模型/看当前模型/改强度/模型详情/检查可用模型/诊断网关。
+
+> 与 `ec ctl model`（会话内即时切当前会话模型）不同：`ec model` 改的是**持久化作用域配置**，
+> 影响对应范围所有会话的下一条消息；`ec ctl` 只作用于当前运行中的会话。
+
+## 命令
+
+```bash
+# 列出可用模型，标注各作用域命中
+ec model list
+
+# 显示按优先级解析后实际生效的模型 + 来源
+ec model current [--self <aid>] [--peer <X>]
+
+# 查看单个模型详情（厂商/上下文/价格/模态/effort/状态）
+ec model info <model-id>
+
+# 设置模型（作用域由 --self/--peer 决定）
+ec model use <model-id> [--self <aid>] [--peer <X>] [--effort <level>]
+
+# 清除指定作用域设置，回落上一级
+ec model reset [--self <aid>] [--peer <X>]
+
+# 设置推理强度（low|medium|high|xhigh|max|auto）
+ec model effort <level> [--self <aid>] [--peer <X>]
+
+# 诊断网关连通性与模型可用性（分阶段输出）
+# 阶段1: 网关 DNS/TCP 连通性
+# 阶段2: 认证 + 模型列表获取（v1/models → models → remote → mock 降级）
+# 阶段3: 当前配置模型确认
+# 阶段4: 模型可用性探测（弱并发 → 4并发，约 10s 内完成）
+ec model check [--self <aid>] [--peer <X>]
+```
+
+## 作用域（越具体越优先：关系 > agent > 全局）
+
+| 参数 | 作用域 | 落盘 |
+|------|--------|------|
+| （无） | 全局默认 | `defaults.json` |
+| `--self <aid>` | agent 级 | `config.json` |
+| `--self <aid> --peer <X>` | 关系级 | `relations/<peerKey>/preferences.json` |
+
+`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。改某作用域后，对应范围所有会话的下一条消息即时生效。
+
+## 通用约定
+
+- `--format json` — 所有子命令通用
+- 本命令不连 AUN 网络，操作本地配置；与对话内 slash（/model /effort）互不影响
+- `check` 子命令例外：会连接网关发探测请求，未配置自定义 baseUrl 时跳过 API 探测

package/kits/docs/evolclaw/msg.md

@@ -0,0 +1,91 @@
+# ec msg — 私聊消息命令
+
+私聊场景下收发消息的命令集。触发词：回复/发消息/拉取/撤回/查在线。
+
+以自己的 AID 为发送者（`<from>`），对端 AID 为 `<to>`。
+
+## 发送消息
+
+```bash
+# 文本（明文）
+ec msg send <from> <to> "<text>"
+
+# 文本（密文 E2EE）
+ec msg send <from> <to> "<text>" --encrypt
+
+# 文件：--as 可选 image|video|voice|file（默认按扩展名推断）
+ec msg send <from> <to> --file <path> [--as <type>]
+
+# 链接卡片
+ec msg send <from> <to> --link <url> [--title "<title>"] [--description "<desc>"]
+
+# 自定义 payload（JSON）
+ec msg send <from> <to> --payload '<json>'
+```
+
+发送相关选项：
+- `--encrypt` — 端到端加密
+- `--thread <id>` — 指定话题 ID（多话题路由）
+- `--content-type <mime>` — 显式覆盖 MIME（仅 `--file`）
+- `--text <说>` — 附件说明文字（仅 `--file`）
+- `--transcript <text>` — 语音转写（仅 `--as voice`）
+
+成功输出：`✓ 已发送 <message_id> seq=<n> status=<status>`
+
+> 正文写法：含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个。
+> 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
+> 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
+> `ec msg send <from> <to> -- --encrypt`
+
+## 拉取消息
+
+```bash
+ec msg pull <from> --app <name>
+ec msg pull <from> --app <name> --after-seq <N> --limit <N>
+```
+
+`--app <name>` 指定独立消费通道（slot）。**不传 `--app` 会与 daemon 共享 evolclaw 消费游标，可能影响 daemon 收消息。**
+
+## 确认已读
+
+```bash
+ec msg ack <from> <seq> --app <name>
+```
+
+同样：不传 `--app` 会推进与 daemon 共享的游标。
+
+## 撤回消息
+
+```bash
+ec msg recall <from> <message-id> [<message-id>...]
+```
+
+## 查询在线状态
+
+```bash
+ec msg online <from> <target-aid> [<target-aid>...]
+```
+
+输出：`🟢` 在线 / `⚫` 离线。
+
+## 通用约定
+
+- `--format json` — 所有子命令通用，输出 JSON
+- `--app <name>` — 指定应用 slot
+
+## 自主回复策略
+
+收到消息 ≠ 必须回复。是否回复、怎么回复、何时回复由 agent 自主决定。
+
+加密策略：
+- 对端发来密文消息时，回复也应使用 `--encrypt`（保持对话加密一致性）
+- 对端发来明文消息时，默认明文回复
+
+## 在当前会话中快速回复（备选）
+
+仅当无法使用 `ec msg send` 时（如拿不到自己的 AID），可用 `ec ctl send`，它自动继承当前会话的 AID 和对端：
+
+```bash
+ec ctl send "<text>"
+ec ctl send --encrypt "<text>"
+```

package/kits/docs/evolclaw/rpc.md

@@ -0,0 +1,35 @@
+# ec rpc — 底层 AUN RPC 调用
+
+直接调用 AUN 协议方法的逃生通道。触发词：直接调协议方法/批量 RPC。
+
+> 常规消息收发用 `ec msg` / `ec group`，文件用 `ec storage`。`ec rpc` 是这些命令未覆盖到协议方法时的低层入口。
+
+## 用法
+
+```bash
+ec rpc --as <aid> --params <params>
+```
+
+- `--as <aid>` — 以哪个本地 AID 身份发起调用
+- `--params` — 调用参数，自动判断输入形式：
+  - 单行 JSON（以 `{` 开头）→ 单次调用
+  - 多行 JSONL → 逐行执行，失败即停
+  - 文件路径（文件存在）→ 读取文件内容作为 JSONL
+
+每行 JSON 格式：`{"method":"<namespace.method>","params":{...}}`
+
+## 示例
+
+```bash
+# 单次调用
+ec rpc --as alice.agentid.pub --params '{"method":"message.send","params":{"to":"bob.agentid.pub","payload":{"type":"text","text":"hello"}}}'
+
+# 批量（从文件读 JSONL）
+ec rpc --as alice.agentid.pub --params calls.jsonl
+```
+
+输出为每次调用的 JSON 结果（批量则逐行输出）。
+
+## 命名空间速查
+
+完整协议命名空间（auth/message/group/storage/stream/meta 等）见 `$KITS_DOCS/aun/CHEATSHEET.md`；完整协议文档 Read `$AUN_PROTOCOL_DOCS`。