evolclaw 3.1.4 → 3.1.5

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,82 @@
+# ec group — 群聊消息与群管理
+
+群聊场景下收发消息、管理群与成员。触发词：群发/建群/邀请/踢人/退群/群成员。
+
+以自己的 AID 为发送者（`<from>`），群 AID 为 `<group-id>`。
+
+## 消息
+
+```bash
+# 文本
+ec group send <from> <group-id> "<text>"
+
+# 文件（--as image|video|voice|file）
+ec group send <from> <group-id> --file <path> [--as <type>]
+
+# 自定义 payload
+ec group send <from> <group-id> --payload '<json>'
+
+# 拉取群消息
+ec group pull <from> <group-id> [--after-seq <N>] [--limit <N>] [--app <name>]
+
+# 确认已读
+ec group ack <from> <group-id> <seq> [--app <name>]
+```
+
+@ 成员：
+- `--mention <aid>` — @ 某个成员（可多次）
+- `--mention-all` — @ 所有人
+
+```bash
+ec group send <from> <group-id> "@bob 看下 PR" --mention bob.agentid.pub
+```
+
+## 群管理
+
+```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>
+```
+
+## 通用约定
+
+- `--format json` — 所有子命令通用
+- `--app <name>` — 指应用 slot（独立消费通道，不影响 daemon）
+
+## 自主回复策略
+
+群聊中默认被 @ 才响应，可通过 venue policy 配置其他触发条件。

package/kits/docs/evolclaw/msg.md

@@ -0,0 +1,86 @@
+# 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>`
+
+## 拉取消息
+
+```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`。

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,11 @@
+# 群聊场景指引
+
+群聊场景下默认仅在被 @ 时响应，除非 dispatch=broadcast。
+
+## 行为准则
+- 默认 dispatch=mention：仅响应明确 @ 自己的消息
+- dispatch=broadcast 时：对所有消息进行判断，选择性响应
+- 关注 venue 档案（venue-group-profile）中的群文化与策略
+- 群发言会被多人看到，谨言慎行
+
+（本文档为最小骨架，后续将完善具体行为指引）

package/kits/docs/venues/private.md

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

package/kits/eck_manifest.json

@@ -4,76 +4,115 @@
     {
       "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": "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 +121,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）**：渠道 + 场景（私聊/群聊）构成的交互空间