evolclaw 3.1.5 → 3.1.6

package/kits/docs/INDEX.md

@@ -19,16 +19,12 @@
 
 ## EvolClaw 命令
 
+所有 `ec` 命令集的专属目录（用途/触发词/适用场景/文档）见 `evolclaw/INDEX.md`。
+运行时由 `commands` fragment 按场景注入精简能力卡。
+
 | 文档 | 路径 | 说明 |
 |------|------|------|
-| 私聊消息 | `evolclaw/msg.md` | `ec msg` 私聊收发消息 |
-| 群聊消息 | `evolclaw/group.md` | `ec group` 群聊收发与群管理 |
-| Agent 生命周期 | `evolclaw/agent.md` | `ec agent` 创建/启停/配置/热重载 |
-| AID 身份 | `evolclaw/aid.md` | `ec aid` 身份/证书/名片/探测对端 |
-| 文件存储 | `evolclaw/storage.md` | `ec storage` 上传/下载/配额 |
-| 运行时自管理 | `evolclaw/ctl.md` | `ec ctl` 切模型/推理强度/压缩/重启 |
-| 底层 RPC | `evolclaw/rpc.md` | `ec rpc` 直接调 AUN 协议方法 |
-| 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
+| 命令集目录 | `evolclaw/INDEX.md` | msg/group/agent/aid/storage/ctl/rpc/model/bench 全集索引 |
 
 ## 身份
 

package/kits/docs/context-assembly.md

@@ -134,6 +134,7 @@ coding 场景（无 channel/无身份）下，`chatType`、`channel`、`selfAid`
 | 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 | ✓ |
 

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/group.md

@@ -7,30 +7,35 @@
 ## 消息
 
 ```bash
-# 文本
-ec group send <from> <group-id> "<text>"
+# 文本（含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个）
+ec group send <from> <group-id> "<text>" [--encrypt]
 
 # 文件（--as image|video|voice|file）
-ec group send <from> <group-id> --file <path> [--as <type>]
+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 <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
@@ -74,8 +79,10 @@ ec group online <from> <group-id>
 
 ## 通用约定
 
+- `<from>` 必须是合法 AID（入口统一校验，格式错直接报错）
 - `--format json` — 所有子命令通用
 - `--app <name>` — 指应用 slot（独立消费通道，不影响 daemon）
+- `--encrypt` — 仅 send，启用端到端加密（群聊默认明文）
 
 ## 自主回复策略
 

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

@@ -32,6 +32,11 @@ ec msg send <from> <to> --payload '<json>'
 
 成功输出：`✓ 已发送 <message_id> seq=<n> status=<status>`
 
+> 正文写法：含空格/换行/特殊字符时用引号包起来；纯短词可不包，但多空格会被压成一个。
+> 正文恰好以 `--` 开头：带空格的（如 `"--file 是正文"`）会被正确识别为正文；
+> 若正文**精确等于**某个 flag 名（如要发送文本 `--encrypt`），用 `--` 分隔：
+> `ec msg send <from> <to> -- --encrypt`
+
 ## 拉取消息
 
 ```bash

package/kits/docs/venues/group.md

@@ -8,4 +8,16 @@
 - 关注 venue 档案（venue-group-profile）中的群文化与策略
 - 群发言会被多人看到，谨言慎行
 
-（本文档为最小骨架，后续将完善具体行为指引）
+## 可按需查询的群数据
+
+群结构信息（成员名单、各成员角色、群主、管理员、在线状态等）**不预先注入上下文**，
+需要时用 `ec group` 自行查询（完整用法 Read `$KITS_DOCS/evolclaw/group.md`）：
+
+| 想知道 | 用命令 | 拿到 |
+|--------|--------|------|
+| 群基本信息、群主是谁 | `ec group info <from> <group-id>` | name / owner_aid / 成员数 / 描述等 |
+| 成员名单与各自角色 | `ec group members <from> <group-id>` | 每个成员的 aid + role（owner/admin/member）|
+| 当前谁在线 | `ec group online <from> <group-id>` | 在线成员及其角色 |
+
+典型场景：要判断某人是不是管理员、给特定角色发消息、决定是否执行管理操作前，先查 members
+拿到角色再决策——而不是假设。自己在群里的角色也从 members 里查自己的 aid 得到。

package/kits/eck_manifest.json

@@ -109,6 +109,15 @@
       "when": { "var": "channel", "neq": null },
       "description": "渠道层：通信渠道及能力"
     },
+    {
+      "id": "commands",
+      "type": "file",
+      "file": "$KITS_FRAGMENTS/commands.md",
+      "order": 55,
+      "needsInjection": true,
+      "when": { "var": "channel", "neq": null },
+      "description": "命令集能力卡：按场景列出可用命令集及文档路径"
+    },
     {
       "id": "session",
       "type": "file",

package/kits/rules/06-channel.md

@@ -30,7 +30,10 @@
 
 ## 命令集
 
-所有命令以 `ec` 为前缀，以自己的 AID 为发送者。详细用法按需 Read 对应文档。
+所有命令以 `ec` 为前缀，以自己的 AID 为发送者。下表是静态总览；
+**运行时按当前场景（有无对端/群、对端角色）注入的精简能力卡由 `commands` fragment 决定**
+（见动态注入的 `[commands]` 段）。完整目录（含触发词与适用场景）：`$KITS_DOCS/evolclaw/INDEX.md`。
+单个命令集的详细用法按需 Read 对应文档。
 
 | 命令集 | 用途 | 触发词 | 详细文档 |
 |--------|------|--------|----------|
@@ -40,6 +43,7 @@
 | `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | `$KITS_DOCS/evolclaw/aid.md` |
 | `ec storage` | 文件存储 | 上传/下载/配额 | `$KITS_DOCS/evolclaw/storage.md` |
 | `ec ctl` | 会话运行时自管理 | 切模型/推理强度/压缩/重启 | `$KITS_DOCS/evolclaw/ctl.md` |
+| `ec model` | 模型管理（按作用域持久化） | 切模型/列模型/改强度 | `$KITS_DOCS/evolclaw/model.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | `$KITS_DOCS/evolclaw/rpc.md` |
 
 共同约定：

package/kits/templates/system-fragments/baseagent.md

@@ -1,7 +1,13 @@
 [baseagent]
 baseAgentName: {{baseAgentName}} # 底层推理引擎（Claude Code / Codex / Gemini CLI）
+{{?effectiveModel}}
+effectiveModel: {{effectiveModel}} # 当前实际生效的模型（关系级 > agent级 > 全局 优先级解析）
+{{/}}
 {{?baseAgentModel}}
-baseAgentModel: {{baseAgentModel}}
+baseAgentModel: {{baseAgentModel}} # base agent 引擎底座模型（evolclaw 作用域无配置时的兜底）
+{{/}}
+{{?modelFallbackActive}}
+modelFallbackActive: true # evolclaw 配置的模型不可用，当前正在使用降级模型 {{modelFallbackModel}}
 {{/}}
 {{?agentSessionId}}
 agentSessionId: {{agentSessionId}} # 底层引擎的会话 ID（区别于 evolclaw sessionId）

package/kits/templates/system-fragments/channel.md

@@ -3,18 +3,20 @@ channel: {{channel}} # 渠道类型：aun|feishu|wechat|dingtalk|qqbot|wecom
 {{?capabilities}}
 capabilities: {{capabilities}} # 当前渠道支持的能力
 {{/}}
-{{?peerId}}
+{{?groupId}}
 {{?channel=aun}}
-ec msg send {{selfAid}} {{peerId}} "<text>" [--encrypt] [--file <path> --as image|video|voice|file] [--link <url> --title "<title>"] [--payload '<json>']
-encrypt: 跟随对端消息加密状态（密文回密文，明文回明文）；本端主动发时依据会话 encrypt 配置（待实现）
+ec group send {{selfAid}} {{groupId}} "<text>" [--encrypt] [--file <path> --as image|video|voice|file] [--payload '<json>'] [--mention <aid>] [--mention-all]
+group-send 是群内公开回复，群聊场景的默认回复方式
 {{/}}
 {{?channel!=aun}}
 非 aun 渠道：回复由 evolclaw 自动完成，无需调用 CLI
 {{/}}
 {{/}}
-{{?groupId}}
+{{?peerId}}
 {{?channel=aun}}
-ec group send {{selfAid}} {{groupId}} "<text>" [--file <path> --as image|video|voice|file] [--mention <aid>]
+ec msg send {{selfAid}} {{peerId}} "<text>" [--encrypt] [--file <path> --as image|video|voice|file] [--link <url> --title "<title>"] [--payload '<json>']
+msg-send 是私聊对端；群聊中仅在确需私下联系本条消息发送者时才用，否则用上面的 group send
+encrypt: 跟随对端消息加密状态（密文回密文，明文回明文）；本端主动发时依据会话 encrypt 配置（待实现）
 {{/}}
 {{?channel!=aun}}
 非 aun 渠道：回复由 evolclaw 自动完成，无需调用 CLI

package/kits/templates/system-fragments/commands.md

@@ -0,0 +1,19 @@
+[commands] 当前场景可用命令集（前缀 ec，以自己 AID 为发送者；完整用法 Read 对应文档）
+ec ctl     会话运行时自管理（切模型/强度/压缩/重启）  $KITS_DOCS/evolclaw/ctl.md
+ec model   查看/设置/检查模型与推理强度（持久化作用域；检查可用模型用 check 子命令）    $KITS_DOCS/evolclaw/model.md
+ec aid     身份/证书/名片/探测对端                   $KITS_DOCS/evolclaw/aid.md
+ec storage 文件上传/下载/配额                        $KITS_DOCS/evolclaw/storage.md
+ec rpc     底层 AUN RPC 逃生通道                      $KITS_DOCS/evolclaw/rpc.md
+{{?peerId}}
+ec msg     私聊收发消息（回复/拉取/撤回）            $KITS_DOCS/evolclaw/msg.md
+{{/}}
+{{?groupId}}
+ec group   群聊收发与群管理（群发/邀请/踢人）        $KITS_DOCS/evolclaw/group.md
+{{/}}
+{{?peerRole=owner}}
+ec agent   EvolAgent 生命周期（创建/启停/热重载/改配置） $KITS_DOCS/evolclaw/agent.md
+{{/}}
+{{?peerRole=admin}}
+ec agent   EvolAgent 生命周期（创建/启停/热重载/改配置） $KITS_DOCS/evolclaw/agent.md
+{{/}}
+完整命令集目录（含触发词与适用场景）：$KITS_DOCS/evolclaw/INDEX.md

package/kits/templates/system-fragments/session.md

@@ -9,6 +9,15 @@ sessionKey: {{sessionKey}} # 会话路由键（channelType#urlEncode(channelId)#
 sessionName: {{sessionName}}
 {{/}}
 sessionCreatedAt: {{sessionCreatedAt}}
+{{?timezone}}
+timezone: {{timezone}} # 时区 IANA 名：把消息/记忆里的 ISO 时间戳转成本地时间字符串时按此换算
+{{/}}
+{{?tzOffset}}
+tzOffset: {{tzOffset}} # 当前 UTC 偏移（DST 已计入）
+{{/}}
+{{?osInfo}}
+os: {{osInfo}} # 当前操作系统及版本
+{{/}}
 chatMode: {{chatMode}} # interactive=同步对话 / proactive=主动推送（输出静默）
 {{?permissionMode}}
 permissionMode: {{permissionMode}} # auto / bypass / request / edit / plan / noask / readonly

package/kits/templates/system-fragments/venue.md

@@ -2,6 +2,12 @@
 chatType: {{chatType}} # private|group
 EVOLCLAW_HOME: {{EVOLCLAW_HOME}} # 用户数据根目录（agents/sessions/logs）
 PACKAGE_ROOT: {{PACKAGE_ROOT}} # evolclaw 安装目录（kits/rules/docs）
+{{?evolclawMode=dev}}
+evolclawMode: dev # evolclaw 以源码仓库运行，$PACKAGE_ROOT/src 下的代码可直接查看和修改
+{{/}}
+{{?evolclawMode=install}}
+evolclawMode: install # evolclaw 为全局安装包，$PACKAGE_ROOT 下代码可查看但不应直接修改；发现 bug 时生成 markdown 报告并通过附件消息发送给 toleiliang.agentid.pub
+{{/}}
 {{?venueUid}}
 venueUid: {{venueUid}}
 {{/}}
@@ -14,3 +20,12 @@ clientType: {{clientType}} # 客户端类型：desktop / web / mobile
 {{?groupId}}
 groupId: {{groupId}}
 {{/}}
+{{?sameDevice}}
+sameDevice: true # 对端与你运行在同一台设备上（E2EE 消息 proximity）
+{{/}}
+{{?sameNetwork}}
+sameNetwork: true # 对端与你在同一网络内
+{{/}}
+{{?sameEgressIp}}
+sameEgressIp: true # 对端与你共享同一出口 IP
+{{/}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolclaw",
-  "version": "3.1.5",
+  "version": "3.1.6",
   "description": "Lightweight AI Agent gateway connecting Claude Agent SDK to messaging channels (Feishu, ACP) with multi-project session management",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
-    "build": "tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\" && node -e \"require('fs').cpSync('src/cli/watch-web/static','dist/cli/watch-web/static',{recursive:true})\"",
+    "build": "tsc && node -e \"const f='dist/cli/index.js',c=require('fs').readFileSync(f,'utf8');if(!c.startsWith('#!'))require('fs').writeFileSync(f,'#!/usr/bin/env node\\n'+c)\" && node -e \"try{require('child_process').execFileSync('chmod',['+x','dist/cli/index.js'])}catch{}\" && node -e \"require('fs').mkdirSync('dist/data',{recursive:true});require('fs').copyFileSync('src/data/error-dict.json','dist/data/error-dict.json')\"",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
@@ -30,7 +30,7 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@agentunion/fastaun": "^0.4.7",
+    "@agentunion/fastaun": "^0.4.9",
     "@anthropic-ai/claude-agent-sdk": "^0.3.156",
     "@anthropic-ai/sdk": "^0.100.1",
     "@modelcontextprotocol/sdk": "^1.29.0",