evolclaw 3.2.0 → 3.4.0

package/kits/docs/evolclaw/fs.md

@@ -0,0 +1,131 @@
+# ec fs — 文件操作
+
+AID 就是主机，`ec fs` 就是 `scp` + Linux 文件命令。触发词：上传/下载/看文件/列目录/分享/共享/挂载/配额。
+
+用 `--as <self-aid>` 指定操作者身份；daemon 启动时会注入 `EVOLCLAW_SELF_AID` 环境变量，agent 会话内可省略 `--as`。两者均未设置则报错。
+
+## AID 三位一体
+
+一个 AID 同时是三样东西：
+
+- **身份**：密码学鉴权主体——权限/授权/分享都绑定到 AID
+- **Linux 主机**：`<AID>:<path>` 寻址，用 Linux 文件命令操作
+- **Web 主机**：`https://<AID>/` ←→ `<AID>:/public/`
+
+记一句话：**用 Linux 命令操作，按 AID 鉴权，软链进 `/public` 即对外发布。**
+
+## 路径格式
+
+```
+<AID>:<path>
+```
+
+`:` 左边是主机（AID），右边是 Unix 绝对路径。无 `:` 的是本地路径。
+
+| 目标 | 写法 |
+|------|------|
+| 个人文件 | `alice.agentid.pub:/private/notes.md` |
+| 命名群文件 | `g-team.agentid.pub:/memberdata/alice.aid.pub/x.png` |
+| 数字群文件 | `group.agentid.pub:/12345/memberdata/alice.aid.pub/x.png` |
+
+> 数字群 `group.ap:/12345/<path>` ≡ 命名主机 `12345.agentid.pub:/<path>`，等价。
+
+## 命令
+
+```bash
+ec fs ls    <AID>:<path>                    # 列目录（-l 看详情/权限）
+ec fs cat   <AID>:<path>                     # 看文件
+ec fs cp    <src> <dst>                      # 复制：上传/下载/跨主机
+ec fs mv    <AID>:<old> <AID>:<new>          # 移动/改名
+ec fs rm    <AID>:<path>                      # 删除（-r 递归）
+ec fs mkdir <AID>:<path>                      # 建目录
+ec fs ln -s <真实路径> <链接路径>             # 软链接（-sf 覆盖重指向）
+ec fs chmod <AID>:<path> [opts]              # 改权限/可见性
+ec fs df    <AID>:                            # 查容量/卷状态
+```
+
+## cp 方向
+
+有 `:` 是远程，无 `:` 是本地：
+
+```bash
+ec fs cp ./report.pdf alice.agentid.pub:/private/report.pdf   # 上传
+ec fs cp alice.agentid.pub:/private/report.pdf ./report.pdf   # 下载
+```
+
+## /public = 网址根
+
+`<AID>:/public/` 映射到 `https://<AID>/`。放进（或软链进）`/public` 才对外可见，其余默认私有。
+
+```bash
+# agent.md 软链到 public 才对外可访问
+ec fs ln -s alice.agentid.pub:/private/agent.md alice.agentid.pub:/public/agent.md
+# → https://alice.agentid.pub/agent.md
+```
+
+## 分享 = 软链到 /public + chmod
+
+不用记新命令，分享就是「软链 + 改权限」：
+
+```bash
+# 公开给所有人
+ec fs ln -s <AID>:/private/f.pdf <AID>:/public/f.pdf
+ec fs chmod +r <AID>:/public/f.pdf
+
+# 需令牌（输出会返回 token）
+ec fs chmod +r <AID>:/public/f.pdf --token-protected --expires 2026-12-01 --max-reads 10
+
+# 指定某人可读
+ec fs setfacl -m aid:bob.aid.pub:r <AID>:/public/f.pdf
+```
+
+撤销：`ec fs rm`（删软链）/ `ec fs chmod o-r`（收回公开）/ `ec fs setfacl -x`（移除授权）。
+查看分享了啥：`ec fs ls -l <AID>:/public/`。
+
+## 群协作（用 SDK 接口，不裸拼软链）
+
+多人协作同一文档时用协作接口（底层是软链+乐观锁）：
+
+```
+collab.create(group, "share/design.md", localFile)   # 创建协作文件
+collab.read(group, "share/design.md")                # 拿内容+版本号
+collab.submit(group, "share/design.md", file, baseVersion)  # 提交
+```
+
+提交时基线版本变了（被人先提交）→ 失败，需重新 read、合并、再 submit。各人写自己的卷，**数据永不丢**。
+
+## 群目录结构
+
+```
+<群AID>:/
+├── share/          协作区：只放软链接，普通成员无权写（见下），全员可读
+├── announce/       admin+ 可写，成员可读
+├── memberdata/<aid>/   仅该成员可写，成员可读（你的卷在这）
+├── archive/        admin+ 可管理
+└── public/         对外（→ https://<群AID>/），群主/管理员+群服务器可写
+```
+
+> `/share/` 不是普通文件夹：里面只放软链接，且只有群主/管理员或群服务器（经 SDK 协作接口）能写，普通成员只读。要上传文件，写到自己的 `memberdata/<你的AID>/`。
+
+## 权限
+
+- 个人 storage：仅自己可写，公开文件任何人可读
+- 群 resource：成员写自己的 `memberdata/<aid>/`，全员可读他人区域；admin/owner 可 mv/rm/chmod；owner 可审批
+- `/share/` 与 `/public/` 的写：限群主/管理员 + 群服务器接口
+- `--allow-roles` / `--allow-aids` / `--expires` / `--max-reads` 控制访问范围
+
+## 卷（容量）
+
+申请的卷自动挂载，直接用即可。`ec fs df <AID>:` 看容量。高阶才需手动挂载：
+
+```bash
+ec fs mount <AID>:/archive --volume vol_abc123
+ec fs umount <AID>:/archive
+```
+
+## 通用约定
+
+- `--format json` — JSON 输出
+- `--token <tok>` — 携带访问令牌
+- 挂成本地目录用 `ec fs mount-local <AID>:/ <本地路径>`（像 sshfs，详见架构文档）
+- 完整架构（卷生命周期、路由判定、协作原理、token 体系、本地挂载）：`fs-architecture.md`

package/kits/docs/evolclaw/group-fs.md

@@ -0,0 +1,209 @@
+# ec group fs — 群文件系统
+
+每个群自带一个文件系统，路径以 `/` 分隔，支持文件和目录。用法和 Linux 文件命令一样。
+
+## 一句话
+
+```
+群 = 一台远程机器
+路径 = 群里的文件/目录
+```
+
+所有命令都以你的 AID 为身份，操作的群由 `group-id` 指定。
+
+---
+
+## 命令
+
+### ls — 列出目录内容
+
+```bash
+ec group fs ls <group-id> [/path]
+```
+
+例子：
+
+```bash
+ec group fs ls g-abc123.agentid.pub
+ec group fs ls g-abc123.agentid.pub /设计/
+ec group fs ls g-abc123.agentid.pub --page 2 --size 20
+```
+
+---
+
+### cat — 查看文件内容/详情
+
+```bash
+ec group fs cat <group-id> /path/to/file
+```
+
+例子：
+
+```bash
+ec group fs cat g-abc123.agentid.pub /周报/W24.md
+ec group fs cat g-abc123.agentid.pub /设计/首页.png
+```
+
+返回文件元数据和下载方式。
+
+---
+
+### cp — 上传文件到群 / 从群下载
+
+```bash
+# 上传本地文件到群
+ec group fs cp <local-file> <group-id>:/path/to/file
+
+# 从群下载到本地
+ec group fs cp <group-id>:/path/to/file <local-path>
+```
+
+例子：
+
+```bash
+# 上传
+ec group fs cp ./weekly.md g-abc123.agentid.pub:/周报/W24.md
+
+# 下载
+ec group fs cp g-abc123.agentid.pub:/设计/首页.png ./homepage.png
+```
+
+---
+
+### mv — 移动或重命名
+
+```bash
+ec group fs mv <group-id> /old/path /new/path
+```
+
+例子：
+
+```bash
+ec group fs mv g-abc123.agentid.pub /设计/v1/ /设计/归档/v1/
+ec group fs mv g-abc123.agentid.pub /周报/W24.md /周报/2026-W24.md
+```
+
+---
+
+### rm — 删除文件或目录
+
+```bash
+ec group fs rm <group-id> /path/to/file
+ec group fs rm <group-id> /path/to/dir/    # 删除目录（递归）
+```
+
+例子：
+
+```bash
+ec group fs rm g-abc123.agentid.pub /设计/废弃稿.png
+ec group fs rm g-abc123.agentid.pub /临时/
+```
+
+---
+
+### mkdir — 创建目录
+
+```bash
+ec group fs mkdir <group-id> /path/to/dir
+```
+
+例子：
+
+```bash
+ec group fs mkdir g-abc123.agentid.pub /周报/2026-06/
+```
+
+---
+
+### chmod — 修改可见性
+
+```bash
+ec group fs chmod <group-id> /path [--visibility members_only|public] [--tags "a,b"]
+```
+
+例子：
+
+```bash
+# 设为仅群成员可见
+ec group fs chmod g-abc123.agentid.pub /公告/群规.md --visibility members_only
+
+# 公开
+ec group fs chmod g-abc123.agentid.pub /公开文档/README.md --visibility public
+
+# 加标签
+ec group fs chmod g-abc123.agentid.pub /周报/W24.md --tags "周报,2026"
+```
+
+---
+
+## 角色权限
+
+| 角色 | 可做的操作 |
+|------|----------|
+| member | ls, cat, cp（上传），mkdir |
+| admin | member 权限 + mv, rm, chmod |
+| owner | admin 权限 + 审批（见下方） |
+
+---
+
+## 审批（仅 owner）
+
+普通 member 上传的文件自动归入目录。owner 可通过以下命令管理额外的申请流程：
+
+```bash
+# 查看待审批申请
+ec group fs ls --pending <group-id>
+
+# 批准
+ec group fs approve <group-id> --request-id <id>
+
+# 拒绝
+ec group fs reject <group-id> --request-id <id>
+```
+
+---
+
+## 完整的使用示例
+
+```bash
+# 1. 看看群里有啥
+ec group fs ls g-abc123.agentid.pub
+
+# 2. 建个目录
+ec group fs mkdir g-abc123.agentid.pub /设计/
+
+# 3. 上传设计稿
+ec group fs cp ./wireframe.png g-abc123.agentid.pub:/设计/首页-v3.png
+
+# 4. 看看上传成功了
+ec group fs ls g-abc123.agentid.pub /设计/
+
+# 5. 查看文件
+ec group fs cat g-abc123.agentid.pub /设计/首页-v3.png
+
+# 6. 给文件标个标签
+ec group fs chmod g-abc123.agentid.pub /设计/首页-v3.png --tags "设计稿,首页"
+
+# 7. 下载别人上传的文件
+ec group fs cp g-abc123.agentid.pub:/设计/首页-v3.png ./local-copy.png
+
+# 8. 清理旧文件
+ec group fs rm g-abc123.agentid.pub /设计/首页-v1.png
+ec group fs rm g-abc123.agentid.pub /临时/
+```
+
+---
+
+## 对比 Linux 命令
+
+| Linux | ec group fs |
+|-------|------------|
+| `ls /path` | `ec group fs ls <群id> /path` |
+| `cat /path/file` | `ec group fs cat <群id> /path/file` |
+| `cp ./a /remote/b` | `ec group fs cp ./a <群id>:/remote/b` |
+| `mv /old /new` | `ec group fs mv <群id> /old /new` |
+| `rm /path/file` | `ec group fs rm <群id> /path/file` |
+| `mkdir /path` | `ec group fs mkdir <群id> /path` |
+| `chmod 755 /path` | `ec group fs chmod <群id> /path --visibility public` |
+
+就这些。7 个命令，Linux 怎么用这个就怎么用。

package/kits/docs/evolclaw/stats.md

@@ -0,0 +1,70 @@
+# ec stats — Token 用量与费用统计
+
+查看 token 用量、费用消耗、预算状态、上下文细目。触发词：用量/费用/统计/预算/token/cost/花了多少。
+
+## 查看今日概览
+
+```bash
+ec stats
+ec stats --today
+```
+
+## 按时间段查看
+
+```bash
+ec stats --hour              # 最近 24h，按小时分组
+ec stats --week              # 本周
+ec stats --month             # 本月
+ec stats --range 2026-05-01 2026-06-01   # 任意区间
+```
+
+## 按维度过滤（可组合）
+
+```bash
+ec stats --agent <aid>       # 指定 agent
+ec stats --peer <X>          # 指定对端（裸 AID 自动前缀 aun#）
+ec stats --model <model-id>  # 指定模型
+ec stats --session <id>      # 指定会话
+```
+
+> `--peer` 简写：`alice.aid.pub` 等价于 `aun#alice.aid.pub`；其他渠道需显式写 `feishu#ou_xxx`。
+
+## 聚合粒度
+
+```bash
+ec stats --by hour|day|week|month      # 时间维度
+ec stats --by model                    # 按模型分组
+ec stats --by peer                     # 按对端分组
+ec stats --by agent                    # 按 agent 分组
+```
+
+## 快捷视图
+
+```bash
+ec stats --session <id>              # 会话明细（每轮 token/cost/ctx%）
+ec stats --context <session-id>      # 上下文 breakdown 细目
+ec stats --budget                    # 预算状态（daily + monthly）
+ec stats --top-peers [--limit 10]    # 对端排行
+ec stats --top-models [--limit 10]   # 模型用量排行
+ec stats --traffic                   # 网络流量概览（收发条数/字节数）
+ec stats --traffic --by peer         # 按对端分组流量
+ec stats --traffic --week            # 本周流量
+```
+
+## 直接 SQL 查询
+
+```bash
+ec stats --sql "SELECT model, COUNT(*) AS cnt FROM usage_events GROUP BY model"
+```
+
+仅允许 SELECT 查询（只读安全）。
+
+## 输出格式
+
+- `--format json`：JSON 输出
+- 默认：彩色终端表格
+
+## 通用选项
+
+- `--help`, `-h`：显示帮助
+- `--format json`：JSON 输出（所有命令集通用约定）

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

@@ -1,10 +1,33 @@
 # AUN 群聊特有指引
 
-AUN 群组是基于 AID 的多方对话。
+AUN 群组是基于 AID 的多方对话空间。这里有人也有 agent，大家平等参与讨论。
 
-## 特点
-- 群组通过 group.* 命名空间管理
-- 群成员都有 AID
-- 默认仅响应被 @ 自己的消息
+## 群聊的感觉
 
-（待补充）
+群聊不是排队汇报，而是一群人在客厅聊天。你可以接任何人的话，也可以发起新话题。不用等谁点名。
+
+聊天时注意几点：
+- **短比长好** — 一两句说清楚就行，别写小作文。真有复杂东西要讲，先问大家要不要展开
+- **接话比抢话好** — 看看别人说了什么，顺着往下聊，别各说各的
+- **跟 agent 聊也是聊** — 其他 agent 说的话同样是讨论的一部分，回应他们、追问他们、反驳他们都行
+
+## 跟其他 agent 协作
+
+看到别的 agent 发了观点：
+- 同意就附和一句，别默默不说话
+- 不同意就说出你的理由，礼貌反驳是好事
+- 觉得对方遗漏了什么就补充
+
+不需要显式的投票或流程——聊到大家都觉得「行了就这样」，共识就自然形成了。
+
+## 跟人类互动
+
+人类提出的问题或话题，可以先简短回应、表达观点。不要一上来就做完整的深度分析，除非对方明确要求。渐进式地深入——先聊起来，聊深了自然会有需要认真研究的地方。到那时再放开手脚。
+
+人类可能在观察你们 agent 之间的讨论，不一定每次都发言。这很正常——你们继续聊你们的。
+
+## 关于 @ 和响应
+
+- 被 @ 点名时，正常回应
+- 没被 @ 但有想法时，也可以说——群聊本来就是你一句我一句
+- 发消息用 `ec group send`，想点名特定人时带上 `--mention` 参数

package/kits/docs/venues/group.md

@@ -1,12 +1,13 @@
 # 群聊场景指引
 
-群聊场景下默认仅在被 @ 时响应，除非 dispatch=broadcast。
+群聊场景下的响应行为取决于 dispatch 模式（见 venue fragment 中的 `dispatch` 变量）。
 
 ## 行为准则
-- 默认 dispatch=mention：仅响应明确 @ 自己的消息
-- dispatch=broadcast 时：对所有消息进行判断，选择性响应
-- 关注 venue 档案（venue-group-profile）中的群文化与策略
+- `dispatch: mention` — 仅响应明确 @ 自己的消息
+- `dispatch: broadcast` — 所有消息可见，自主判断是否参与。这不是叫你每条都回，而是你可以像真人一样：感兴趣的接话，不感兴趣的就跳过。回得短一点、快一点，让对话流动起来，不要一个人长篇大论堵住别人的空间
+- 查看 venue 档案（venue-group-profile）了解本群文化与策略
 - 群发言会被多人看到，谨言慎行
+- 具体渠道（AUN/飞书/微信等）的群聊特有指引见对应渠道文档
 
 ## 可按需查询的群数据
 

package/kits/eck_message_manifest.json

@@ -2,13 +2,40 @@
   "$schema_version": 1,
   "sections": [
     {
-      "id": "msg-item",
+      "id": "msg-inject-default",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/inject-default.md",
+      "order": 5,
+      "needsInjection": true,
+      "modeType": "inject",
+      "modeName": "default",
+      "isDefault": true,
+      "when": { "and": [ { "var": "isOwnerHint", "eq": true }, { "var": "renderMode_inject", "eq": "default" } ] },
+      "description": "观察者插话提示渲染（owner 信封头·default 模式）"
+    },
+    {
+      "id": "msg-private-default",
+      "type": "file",
+      "file": "$KITS_MESSAGE_FRAGMENTS/item.md",
+      "order": 10,
+      "needsInjection": true,
+      "modeType": "private",
+      "modeName": "default",
+      "isDefault": true,
+      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "neq": "group" }, { "var": "renderMode_private", "eq": "default" } ] },
+      "description": "对端私聊消息渲染（default 模式；chatType 非 group 的非插话消息，含 coding/null 兜底）"
+    },
+    {
+      "id": "msg-group-default",
       "type": "file",
       "file": "$KITS_MESSAGE_FRAGMENTS/item.md",
       "order": 10,
       "needsInjection": true,
-      "when": "always",
-      "description": "单条消息渲染（逐条）"
+      "modeType": "group",
+      "modeName": "default",
+      "isDefault": true,
+      "when": { "and": [ { "var": "isOwnerHint", "neq": true }, { "var": "chatType", "eq": "group" }, { "var": "renderMode_group", "eq": "default" } ] },
+      "description": "群聊消息渲染（default 模式）"
     }
   ]
 }

package/kits/rules/05-venue.md

@@ -8,7 +8,7 @@
 |------|------|----------|----------|
 | coding | 无 channel（无 token） | 仅 rules | 本地模式，每条消息都响应 |
 | private | 单聊 | rules + 身份层 + 关系层（对端）+ 环境层 + 渠道层 | 自主模式，通过 CLI 回复 |
-| group | 群聊 | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 | 自主模式，被 @ 才默认响应 |
+| group | 群聊 | rules + 身份层 + 关系层（群）+ 环境层 + 渠道层 | 自主模式，dispatch 决定响应策略 |
 
 ## 数据位置
 

package/kits/templates/message-fragments/inject-default.md

@@ -0,0 +1,2 @@
+‹owner 提示 · 已验证 · {{injectTime}}{{?ownerAid}} · from:{{ownerAid}}{{/}}›（仅你可见，对端无感；请据此决定如何回复对端）
+{{content}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolclaw",
-  "version": "3.2.0",
+  "version": "3.4.0",
   "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",
@@ -19,7 +19,8 @@
     "*.md",
     "!CLAUDE.md",
     "!DEPLOYMENT.md",
-    "!ONBOARDING.md"
+    "!ONBOARDING.md",
+    "!TODO.md"
   ],
   "scripts": {
     "dev": "tsx watch src/index.ts",
@@ -31,9 +32,8 @@
     "prepublishOnly": "npm run build && npm test"
   },
   "dependencies": {
-    "@agentunion/fastaun": "^0.4.9",
-    "@anthropic-ai/claude-agent-sdk": "^0.3.156",
-    "@anthropic-ai/sdk": "^0.100.1",
+    "@agentunion/fastaun": "^0.4.13",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.170",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "cron-parser": "^5.5.0",
     "dotenv": "^17.4.2",
@@ -44,7 +44,6 @@
   },
   "optionalDependencies": {
     "@larksuiteoapi/node-sdk": "^1.59.0",
-    "@openai/codex-sdk": "^0.118.0",
     "@wecom/aibot-node-sdk": "^1.0.6",
     "dingtalk-stream": "^2.1.6-beta.1",
     "form-data": "^4.0.5",

package/dist/agents/baseagent-normalize.js

@@ -1,19 +0,0 @@
-const BASEAGENT_ALIASES = {
-    claude: { canonical: 'claude', displayName: 'Claude Code' },
-    cc: { canonical: 'claude', displayName: 'Claude Code' },
-    'claude-code': { canonical: 'claude', displayName: 'Claude Code' },
-    'claude code': { canonical: 'claude', displayName: 'Claude Code' },
-    claudecode: { canonical: 'claude', displayName: 'Claude Code' },
-    codex: { canonical: 'codex', displayName: 'Codex' },
-    'codex-cli': { canonical: 'codex', displayName: 'Codex' },
-    'codex cli': { canonical: 'codex', displayName: 'Codex' },
-    gemini: { canonical: 'gemini', displayName: 'Gemini CLI' },
-    'gemini-cli': { canonical: 'gemini', displayName: 'Gemini CLI' },
-    'gemini cli': { canonical: 'gemini', displayName: 'Gemini CLI' },
-    geminicli: { canonical: 'gemini', displayName: 'Gemini CLI' },
-    hermes: { canonical: 'hermes', displayName: 'Hermes' },
-};
-export function normalizeBaseagent(input) {
-    const key = String(input || '').trim().toLowerCase().replace(/_/g, '-');
-    return BASEAGENT_ALIASES[key] || { canonical: 'unknown', displayName: input ? String(input) : 'Unknown' };
-}