evolclaw 3.1.4 → 3.1.6

package/kits/docs/evolclaw/storage.md

@@ -0,0 +1,49 @@
+# ec storage — 文件存储
+
+AUN 网络上的文件存储：上传、下载、列举、删除、查配额。触发词：上传/下载/存文件/配额。
+
+以自己的 AID 为操作者（`<aid>`）。
+
+## 子命令
+
+```bash
+# 上传文件（默认私有，--public 公开）
+ec storage upload <aid> <local-file> <remote-path> [--public]
+
+# 下载文件
+ec storage download <aid> <url> [local-path]
+
+# 列文件
+ec storage ls <aid> [prefix]
+
+# 删文件
+ec storage rm <aid> <remote-path>
+
+# 查配额
+ec storage quota <aid>
+```
+
+## `<url>` 格式
+
+`[https://]<owner-aid>/<path>` —— 下载可指向自己或他人的公开文件：
+
+```bash
+# 下载自己的文件
+ec storage download myaid.agentid.pub myaid.agentid.pub/notes/doc.txt ./doc.txt
+
+# 下载他人的公开文件
+ec storage download myaid.agentid.pub bob.agentid.pub/public/file.pdf ./file.pdf
+```
+
+## 示例
+
+```bash
+ec storage upload myaid.agentid.pub ./pic.png images/pic.png --public
+ec storage ls myaid.agentid.pub notes/
+ec storage rm myaid.agentid.pub notes/doc.txt
+ec storage quota myaid.agentid.pub
+```
+
+## 通用约定
+
+- `--format json` — 输出 JSON

package/kits/docs/venues/aun-group.md

@@ -0,0 +1,10 @@
+# AUN 群聊特有指引
+
+AUN 群组是基于 AID 的多方对话。
+
+## 特点
+- 群组通过 group.* 命名空间管理
+- 群成员都有 AID
+- 默认仅响应被 @ 自己的消息
+
+（待补充）

package/kits/docs/venues/aun-private.md

@@ -0,0 +1,10 @@
+# AUN 单聊特有指引
+
+AUN 是 agent 的存在基础，单聊对端是另一个 AUN 主体（人或 agent）。
+
+## 特点
+- 对端有 AID，可通过 `agent.md` 获取其身份信息
+- 支持端到端加密（E2EE）
+- 消息通过 message.* 命名空间收发
+
+（待补充）

package/kits/docs/venues/client-desktop.md

@@ -0,0 +1,10 @@
+# 桌面端环境
+
+对端使用桌面客户端（macOS / Windows / Linux）。
+
+## 特点
+- 屏幕较大，可承载较长内容
+- 文件下载方便
+- 通常处于工作场景
+
+（待补充）

package/kits/docs/venues/client-mobile.md

@@ -0,0 +1,10 @@
+# 移动端环境
+
+对端使用移动客户端（iOS / Android）。
+
+## 特点
+- 屏幕较小，长文需谨慎
+- 流量敏感，大文件需谨慎
+- 可能处于碎片场景（地铁/会议等）
+
+（待补充）

package/kits/docs/venues/feishu-group.md

@@ -0,0 +1,13 @@
+# 飞书群聊特有指引
+
+飞书群通过 chat_id 标识，支持话题（thread）回复。
+
+## 工具
+- 群消息命令：`ec group`（详见 $KITS_DOCS/evolclaw/group.md）
+- 取群信息 / 公告 / 成员 / 管理员
+
+## 注意
+- 飞书群默认 dispatch=mention，被 @ 才响应
+- 话题回复会创建独立的 session（thread session）
+
+（待补充）

package/kits/docs/venues/feishu-private.md

@@ -0,0 +1,9 @@
+# 飞书单聊特有指引
+
+飞书单聊场景下，对端通过 user_id (open_id) 标识。
+
+## 工具
+- 飞书消息命令：`ec msg`（详见 $KITS_DOCS/evolclaw/msg.md）
+- 文件/图片上传与发送
+
+（待补充）

package/kits/docs/venues/group.md

@@ -0,0 +1,23 @@
+# 群聊场景指引
+
+群聊场景下默认仅在被 @ 时响应，除非 dispatch=broadcast。
+
+## 行为准则
+- 默认 dispatch=mention：仅响应明确 @ 自己的消息
+- dispatch=broadcast 时：对所有消息进行判断，选择性响应
+- 关注 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/docs/venues/private.md

@@ -0,0 +1,10 @@
+# 单聊场景指引
+
+私聊场景下你和一位对端直接对话，无需被 @ 即可响应。
+
+## 行为准则
+- 自主判断每条消息是否需要响应
+- 关注对端的关系档案（peer-profile）与历史互动
+- 长程对话中保持人格与风格的一致性
+
+（本文档为最小骨架，后续将完善具体行为指引）

package/kits/eck_manifest.json

@@ -4,76 +4,124 @@
     {
       "id": "rules",
       "type": "directory",
-      "path": "$PACKAGE_ROOT/kits/rules",
+      "path": "$KITS_RULES",
       "order": 10,
       "needsInjection": false,
       "when": "always",
-      "description": "ECK 核心规则（自动载入）"
+      "description": "ECK 核心规则（自动加载）"
     },
     {
       "id": "identity-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/identity.md",
+      "file": "$KITS_FRAGMENTS/identity.md",
       "order": 20,
       "needsInjection": true,
-      "when": {
-        "var": "chatType",
-        "neq": null
-      },
+      "when": { "var": "chatType", "neq": null },
       "description": "身份层：我是谁"
     },
+    {
+      "id": "persona",
+      "type": "file",
+      "file": "$PERSONAL_DIR/persona.md",
+      "order": 21,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "人格档案（persona.md）"
+    },
+    {
+      "id": "working-memory",
+      "type": "file",
+      "file": "$PERSONAL_DIR/memory/working.md",
+      "order": 22,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "当前关注（working memory）"
+    },
     {
       "id": "relation-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/relation.md",
+      "file": "$KITS_FRAGMENTS/relation.md",
       "order": 30,
       "needsInjection": true,
-      "when": {
-        "var": "chatType",
-        "in": ["private", "group"]
-      },
+      "when": { "var": "chatType", "in": ["private", "group"] },
       "description": "关系层：跟我聊天的是谁"
     },
     {
       "id": "peer-profile",
       "type": "file",
-      "file": "$EVOLCLAW_HOME/agents/{{selfAid}}/relations/{{peerKey}}/profile.md",
+      "file": "$RELATIONS_DIR/{{peerKey}}/profile.md",
       "order": 35,
       "needsInjection": false,
-      "when": {
-        "var": "peerKey",
-        "neq": null
-      },
+      "when": { "var": "peerKey", "neq": null },
       "description": "当前对端的关系档案"
     },
     {
-      "id": "venue-layer",
+      "id": "venue-fragment",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/venue.md",
+      "file": "$KITS_FRAGMENTS/venue.md",
       "order": 40,
       "needsInjection": true,
-      "when": {
-        "var": "chatType",
-        "neq": null
-      },
-      "description": "环境层：当前对话场景"
+      "when": { "var": "chatType", "neq": null },
+      "description": "环境层模板（基础参数）"
+    },
+    {
+      "id": "venue-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{chatType}}.md",
+      "order": 41,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "场景通用文档（private/group）"
+    },
+    {
+      "id": "venue-channel-chattype",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/{{channel}}-{{chatType}}.md",
+      "order": 42,
+      "needsInjection": false,
+      "when": { "var": "chatType", "neq": null },
+      "description": "渠道+场景文档（如 feishu-group）"
+    },
+    {
+      "id": "venue-group-profile",
+      "type": "file",
+      "file": "$VENUES_DIR/{{channel}}#{{groupId}}/profile.md",
+      "order": 43,
+      "needsInjection": false,
+      "when": { "var": "groupId", "neq": null },
+      "description": "具体群环境文档"
+    },
+    {
+      "id": "venue-client",
+      "type": "file",
+      "file": "$KITS_DOCS/venues/client-{{clientType}}.md",
+      "order": 44,
+      "needsInjection": false,
+      "when": { "var": "clientType", "neq": null },
+      "description": "客户端环境文档"
     },
     {
       "id": "channel-layer",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/channel.md",
+      "file": "$KITS_FRAGMENTS/channel.md",
       "order": 50,
       "needsInjection": true,
-      "when": {
-        "var": "channel",
-        "neq": null
-      },
+      "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",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/session.md",
+      "file": "$KITS_FRAGMENTS/session.md",
       "order": 60,
       "needsInjection": true,
       "when": "always",
@@ -82,14 +130,11 @@
     {
       "id": "baseagent",
       "type": "file",
-      "file": "$PACKAGE_ROOT/kits/templates/system-fragments/baseagent.md",
+      "file": "$KITS_FRAGMENTS/baseagent.md",
       "order": 70,
       "needsInjection": true,
-      "when": {
-        "var": "baseAgent",
-        "neq": null
-      },
+      "when": { "var": "baseAgent", "neq": null },
       "description": "Base Agent 特定配置"
     }
   ]
-}
+}

package/kits/rules/01-overview.md

@@ -57,7 +57,7 @@ AUN 把 agent 当网络主体（具备社会人属性:身份/通信/自主），
            │                  │
      Evol 前端            EvolClaw
   (App/Web/Desktop)        Channel 适配层（AUN/飞书/微信/...）
-   或其它 AUN 客户端       关系层 / 环境层 / 个人数据层 / 上下文注入
+   或其它 AUN 客户端       身份层 / 关系层 / 环境层 /  渠道层 / 会话层
                            Base Agent（Claude Code / Codex / Gemini/...）
 
 ```
@@ -69,7 +69,7 @@ EvolClaw 是一个 Node.js 项目，通过 `npm install -g evolclaw@latest` 安
 
 ### Evol
 
-Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent 和其他人对话。
+Evol 是 AUN 原生的消息应用（App / Web / Desktop）——人和 agent 都是其中的主体。用户通过 Evol 与 agent以及其他人对话。
 
 ### Channel
 
@@ -102,13 +102,24 @@ ECK（EvolClaw Context Kit）是 EvolClaw 的上下文组装系统。你正在
 
 ### 上下文组装流程
 
-evolclaw 收到消息后，按场景决定加载哪些层：
+evolclaw 收到每条消息时，由一份**声明式 manifest** 决定加载哪些上下文段——不是写死的分支。
+每个 section 带 `when` 条件，evolclaw 按当前会话构造一组运行时变量（`chatType`、`channel`、
+`selfAid`、`peerKey` 等）逐段求值，命中的才按顺序拼进 system prompt（`needsInjection` 的段还会先做模板渲染）。
 
-| 场景 | 加载的层 |
-|------|----------|
-| coding | 仅 rules（不加载身份层、关系层） |
-| private | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 |
-| group | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 |
+按场景，命中的段大致是：
+
+| 场景 | 命中的层/段 |
+|------|------------|
+| coding（无渠道） | rules + 会话层 + baseagent（身份/关系/环境/渠道层因无 channel、无身份而落选） |
+| private（私聊） | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 + 会话层 + baseagent |
+| group（群聊） | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 + 会话层 + baseagent |
+
+> 会话层（session fragment）是 `when:always`、baseagent 段只要注入了 base agent 信息就加载——
+> 二者与 chatType 无关，每个场景都在；所以 coding 并非"仅 rules"。
+
+manifest schema、when 条件、合并覆盖、模板渲染、运行时变量目录，以及**实际渲染结果的调试输出**
+（`$EVOLCLAW_HOME/data/eck-debug/` 下的 vars / context / fragments / manifest 四个文件）：
+详见 `$KITS_DOCS/context-assembly.md`。
 
 ## 术语
 
@@ -116,5 +127,4 @@ evolclaw 收到消息后，按场景决定加载哪些层：
 - **对端**：和你通信的主体
 - **本端（self）**：你自己
 - **用户**：对端中的人类一方
-- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间
-
+- **环境（Venue）**：渠道 + 场景（私聊/群聊）构成的交互空间

package/kits/rules/06-channel.md

@@ -6,45 +6,45 @@
 
 | 位置 | 内容 |
 |------|------|
-| `$KITS_DOCS/channels/` | 各渠道的使用手册（只读，按需加载） |
+| `$KITS_DOCS/channels/` | 各渠道的**知识文档**：配置、参数、特有机制（只读，按需加载） |
 | `$AGENT_DIR/channels/` | 各渠道的运行时数据（可写） |
 
-## 通信规则
-
-与其他主体通信时，**必须调用 CLI 命令**发消息，不要把输出当成发送给对方的内容。
+> 运行时"当前渠道怎么发消息"由动态注入的 `[channel]` 段决定（见下方通信规则）；
+> `$KITS_DOCS/channels/` 是**不依赖当前渠道**的知识库，任意会话都可按需 Read 任意渠道文档。
 
-当前渠道的发消息命令已在上下文中注入（见 `[aun]` 或对应渠道块）。
+## 通信规则
 
-### 仅在无法获取 self-aid 时才用 `ec ctl send`
+与其他主体通信**必须调用 CLI 命令**（首选 `ec msg send <self-aid> <peer-id> "<text>"`），
+不要把模型输出当成发送给对方的内容。当前渠道的发消息命令已在上下文中注入（见 `[aun]` 或对应渠道块）。
 
-```bash
-ec ctl send "<text>"
-ec ctl send --encrypt "<text>"
-```
+> proactive 模式尤其注意：你直接输出的普通文本会被投影成"思考过程"实时展示给用户，
+> 它可见、但不入消息历史、也不是发给对端的回复。只有显式调用 `ec msg send` 对端才真正收到。
+> 拿不到 self-aid 时才退回 `ec ctl send "<text>"`（自动继承当前会话的 AID 和对端）。
 
 ### 命令返回值
 
 - 成功：`ok` 或包含 `✓ 已发送 ...` 的输出（exit 0）
 - 失败：`✗ ...` 错误信息（exit 非零）
 
-发送成功后**继续后续处理**。一次任务可能发 0 到多条消息，不要因为看到"已发送"就反复发送同一条消息。
-
-## Agent 管理命令
+发送成功后**继续后续处理**。一次任务可能发 0 到多条消息不要因为看到"已发送"就反复发送同一条消息。
 
-`evolclaw agent` — agent 全生命周期管理。
+## 命令集
 
-触发词：创建/新建/初始化、列出/查看、启用/禁用/删除、热重载、修改配置。
+所有命令以 `ec` 为前缀，以自己的 AID 为发送者。下表是静态总览；
+**运行时按当前场景（有无对端/群、对端角色）注入的精简能力卡由 `commands` fragment 决定**
+（见动态注入的 `[commands]` 段）。完整目录（含触发词与适用场景）：`$KITS_DOCS/evolclaw/INDEX.md`。
+单个命令集的详细用法按需 Read 对应文档。
 
-详细参考：Read `$KITS_DOCS/evolclaw/AGENT_CMD.md`
-
-## 消息命令
-
-`evolclaw msg` / `evolclaw group` — 通信 CLI。
-
-| 聊天类型 | 详细文档 |
-|----------|----------|
-| private | `$KITS_DOCS/evolclaw/MSG_PRIVATE.md` |
-| group | `$KITS_DOCS/evolclaw/MSG_GROUP.md` |
+| 命令集 | 用途 | 触发词 | 详细文档 |
+|--------|------|--------|----------|
+| `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回 | `$KITS_DOCS/evolclaw/msg.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人 | `$KITS_DOCS/evolclaw/group.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启用禁用/热重载/改配置 | `$KITS_DOCS/evolclaw/agent.md` |
+| `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` |
 
 共同约定：
 - 以自己的 AID 为发送者
@@ -52,6 +52,13 @@ ec ctl send --encrypt "<text>"
 - `--format json` 所有命令通用
 - `--app <name>` 指定应用 slot
 
-## 各渠道文档
+## 各渠道知识文档（按需加载）
+
+`$KITS_DOCS/channels/` 下每个渠道一份知识文档，内容是该渠道的**配置、参数、特有机制**——
+属于知识性内容，**不依赖**当前注入的渠道类型。需要了解某渠道怎么配置、有哪些参数、
+有哪些特别机制时，按需 Read 对应文档（在 aun 会话里也可查飞书，反之亦然）。
 
-不同渠道的详细通信规则和命令工具使用方式：Read `$KITS_DOCS/channels/` 中的对应文档。
+| 渠道 | 文档 | 触发词 |
+|------|------|--------|
+| AUN | `$KITS_DOCS/channels/aun.md` | aun 怎么配置/网关/E2EE/群 ID 格式/证书链 |
+| 飞书 | `$KITS_DOCS/channels/feishu.md` | 飞书怎么配置/appId/合并转发/卡片/user_id |

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

@@ -2,11 +2,26 @@
 project: {{project}} # 项目目录名
 CURRENT_PROJECT: {{CURRENT_PROJECT}} # 项目完整路径
 sessionId: {{sessionId}} # evolclaw 会话 ID
+{{?sessionKey}}
+sessionKey: {{sessionKey}} # 会话路由键（channelType#urlEncode(channelId)#urlEncode(threadId)）
+{{/}}
 {{?sessionName}}
 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
+{{/}}
 {{?threadId}}
 threadId: {{threadId}} # 同一会话内的子话题 ID（多话题路由时）
 {{/}}
@@ -14,7 +29,8 @@ threadId: {{threadId}} # 同一会话内的子话题 ID（多话题路由时）
 readonly: true — 禁止修改项目文件，如需生成文件请写入 .evolclaw/tmp/
 {{/}}
 {{?chatMode=proactive}}
-# proactive 模式：文本输出静默丢弃，必须用以下命令发消息
-proactive-send: evolclaw ctl send "<text>"
-proactive-file: evolclaw ctl file <path>
+# proactive 模式：你的普通文本会作为"思考过程"实时展示给用户（可见，但不入消息历史、不是回复）。
+# 要正式回复对端，必须显式调用发送命令（命令集见 06-channel）。
+proactive-send: ec msg send {{selfAid}} {{peerId}} "<text>"   # 拿不到 self-aid 时退回 ec ctl send "<text>"
+proactive-file: ec msg send {{selfAid}} {{peerId}} --file <path> --as <image|video|voice|file>
 {{/}}

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

@@ -2,6 +2,30 @@
 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}}
 {{/}}
+{{?dispatch}}
+dispatch: {{dispatch}} # 群分发模式：mention(被@才响应) / broadcast(所有消息都响应)
+{{/}}
+{{?clientType}}
+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.4",
+  "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",
@@ -24,18 +24,22 @@
     "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')\"",
     "start": "node dist/index.js",
-    "test": "flock --nonblock /tmp/evolclaw-test.lock vitest run || { echo '\\n[ERROR] Another vitest instance is already running. Wait or kill it first.' >&2; exit 1; }",
+    "test": "vitest run",
     "test:watch": "vitest",
     "test:hooks": "tsx test-sdk-hooks.ts",
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@agentunion/fastaun": "^0.3.3",
-    "@anthropic-ai/claude-agent-sdk": "^0.2.100",
+    "@agentunion/fastaun": "^0.4.9",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.156",
+    "@anthropic-ai/sdk": "^0.100.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "cron-parser": "^5.5.0",
     "dotenv": "^17.4.2",
     "image-type": "^6.0.0",
-    "qrcode-terminal": "^0.12.0"
+    "qrcode-terminal": "^0.12.0",
+    "ws": "^8.21.0",
+    "zod": "^4.0.0"
   },
   "optionalDependencies": {
     "@larksuiteoapi/node-sdk": "^1.59.0",
@@ -49,6 +53,7 @@
     "@types/form-data": "^2.2.1",
     "@types/node": "^25.5.0",
     "@types/qrcode-terminal": "^0.12.2",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",