evolclaw 2.8.3 → 3.1.0

package/evolclaw-install-aun.md

@@ -10,23 +10,29 @@ EvolClaw 是一个开源的 AI Agent 网关，将 Claude/Codex 等 AI 后端连
 
 ## 前置条件
 
-- Node.js >= 18，npm >= 8
+- Node.js >= 18，npm >= 8（使用 codex baseagent 时建议 >= 22.5 以获得完整 session 列表查询；低版本会自动降级为 rollout 文件查询）
+- 一款 baseagent CLI：`claude` / `codex` / `gemini` 任一在 PATH 中
 - 一个 AUN Agent ID（AID）——标识你的 Agent
-- 一个 Owner AID——接收欢迎消息和管理权限
+- 一个 Owner AID（可选）——接收欢迎消息和管理权限；不填则首次通信者自动绑定
 
 ---
 
 ## 安装步骤
 
+> **⚠️ 给执行安装的 AI Agent**：本文档中所有破坏性命令（`evolclaw stop` / `evolclaw restart` / `rm -rf` / `evolclaw aid delete` 等）**必须先 `AskUserQuestion` 等用户明确回复后才能执行**，不要因为已经发出确认提示就默认 yes 自动跑。用户在打字的几秒内决定 "等等先别停"，比事后回滚要省事得多。
+
 ### 步骤 1：检查环境
 
 ```bash
 node --version   # 需要 >= 18
 npm --version    # 需要 >= 8
+which claude || which codex || which gemini   # 至少一款 baseagent CLI
 ```
 
 版本不满足请先升级：https://nodejs.org
 
+baseagent CLI 缺失时可用 `npm install -g @anthropic-ai/claude-code` 安装 claude。
+
 ### 步骤 2：安装 EvolClaw
 
 ```bash
@@ -70,85 +76,144 @@ evolclaw status
 
 - 输出表明未运行（`not running` / `stopped` / 无 PID）→ 直接进入下一步。
 
-### 步骤 4：准备配置信息
+### 步骤 4：解析用户输入
+
+用户在触发安装时通常用类似下面的格式提供配置信息（**Claude Code 必须按以下规则解析**）：
 
-| 参数 | 说明 | 示例 |
-|------|------|------|
-| `--aun-aid` | **必填**，Agent 自身的 AID，作为 bot 在 AUN 网络上的独立身份 | `mybot.agentid.pub` |
-| `--aun-owner` | **必填**，Owner 的 AID，用于接收欢迎消息和管理权限 | `alice.agentid.pub` |
-| `--default-path` | 默认项目路径（bot 会话未显式 `/bind` 时使用的工作目录） | `/home/user/myproject` |
+```
+安装 evolclaw（npm install -g evolclaw），读取包内的安装文档完成配置
+你要使用的AID是:aibot.agentid.pub
+你的主人AID是:elean.agentid.pub
+你的昵称是:我是小艾
+```
 
-**注意**：`--aun-aid` 和 `--aun-owner` 必须是不同的 AID。Agent 需要独立身份，不能与 Owner 相同。
+提取规则（每条都是"消息中有则用，无则不带 flag"）：
 
-如果用户在触发安装时已提供 Owner AID（例如消息中包含"将 xxx 添加为 Owner ID"），直接使用该值，否则询问用户。Agent AID 必须单独询问用户，不能默认使用 Owner AID。
+| 用户消息模式 | 命令参数 |
+|---|---|
+| `你要使用的AID是:X` / `agent AID:X` / `bot AID is X` | 位置参数 `<aid>`（**必填**——若用户消息没提供，停下问用户） |
+| `你的主人AID是:X` / `owner AID:X` / `owner is X` | `--owner X`（可选，缺则不带 flag，首次通信者自动绑定） |
+| `你的昵称是:X` / `叫 X` / `name X` / `the bot is named X` | `--name "X"`（可选，缺则不带 flag，agent new 自动用 AID 首段） |
 
-**默认项目路径必须询问用户，提供三个选项：**
+**注意**：`<aid>` 和 `--owner` 必须不同的 AID（Agent 需要独立身份，不能与 Owner 相同）。
 
-1. **推荐默认**：`~/projects/default`（EvolClaw 约定的默认工作区；若不存在会自动创建）
+`--description` **不从用户消息提取**，按步骤 5 流程生成候选让用户选择。
+
+`--project`（agent 默认工作目录）需要单独询问用户，提供三个选项：
+
+1. **推荐默认**：`~/evolclaw-projects/<aid 首段>`（EvolClaw 约定的默认工作区；若不存在会自动创建）
 2. **当前 Claude Code 运行目录**：即本次会话启动 `claude` 的工作目录（通过 `pwd` 获取）——适合希望 bot 直接在当前项目里工作的场景
 3. **自定义路径**：用户指定绝对路径（须是已存在的目录，或接受后自动创建）
 
 示例提问：
 
-> 请选择默认项目目录（bot 未显式 `/bind` 时使用的工作目录）：
-> 1) `~/projects/default`（推荐，EvolClaw 默认工作区）
+> 请选择默认项目目录（agent 默认工作目录）：
+> 1) `~/evolclaw-projects/<aid 首段>`（推荐）
 > 2) 当前目录：`<pwd 输出>`
 > 3) 自定义路径（请提供绝对路径）
 
 用户未选择时，默认取选项 1。选项 3 需校验路径是绝对路径；目录不存在则 `mkdir -p` 创建。
 
-### 步骤 5：非交互式初始化
+### 步骤 5：生成 description 候选并让用户选择
+
+Claude Code 基于已确定的 `<aid>` / `--name`（若已提取）和当前对话上下文，**生成 3 个不同侧重的简短中文描述**（每条 10-30 字）：
+
+- **候选 1（能力陈述）**：突出 agent 能做什么，例 `"EvolClaw 多模型 AI 助手"`
+- **候选 2（服务对象）**：突出服务谁，例 `"<owner 名称>的 AI 私人助手"`
+- **候选 3（风格化）**：拟人化或带性格的表述，例 `"可爱聪明的小艾，随叫随到"`
 
-将用户选择的目录作为 `--default-path` 传入：
+用 `AskUserQuestion`（或交互问答）让用户选择。选项含**4 项**：候选 1 / 2 / 3 / 跳过；用户也可输入"其他"自定义。
+
+| 用户选择 | 命令参数 |
+|---|---|
+| 候选 1 / 2 / 3 | `--description "<对应候选>"` |
+| 其他（自定义文本） | `--description "<用户输入>"` |
+| 跳过 | 不带 `--description` flag |
+
+### 步骤 6：写全局 defaults.json
 
 ```bash
-evolclaw init --non-interactive \
-  --default-path <用户选择的绝对路径> \
-  --channel aun \
-  --aun-aid <AID> \
-  --aun-owner <Owner AID>
+evolclaw init --non-interactive
 ```
 
+可选传 `--baseagent <claude|codex|gemini>` 显式指定；不传则取 PATH 中第一个可用项。
+重装场景下需要覆盖已有 `defaults.json`，加 `--force`。
+
+此命令仅创建 `$EVOLCLAW_HOME/agents/defaults.json`（`$EVOLCLAW_HOME` 默认 `~/.evolclaw`），不碰 AID 与渠道。
+
+### 步骤 7：创建 agent
+
+```bash
+evolclaw agent new <aid> --non-interactive \
+  --project <用户选择的绝对路径> \
+  [--owner <Owner AID>] \
+  [--name "<昵称>"] \
+  [--description "<选定描述>"] \
+  [--baseagent <claude|codex|gemini>]
+```
+
+按步骤 4/5 的提取规则填入 flag——**省略未提取到的可选参数**，不要主动填默认值（agent new 内部会处理默认）。
+
 此命令自动完成：
-1. 创建配置文件 `~/.evolclaw/data/evolclaw.json`
-2. 安装 `@agentunion/aun-node`
-3. 创建 AID 密钥对（如本地不存在）
-4. 下载 CA 根证书到 `~/.aun/CA/root/root.crt`
-5. 写入初始 `agent.md`（`initialized: false`）
-6. 写入配置（含 owner 字段）
 
-### 步骤 6：启动前验证
+1. 校验 AID 格式（多级域名，如 `mybot.agentid.pub`）
+2. 创建 AID 密钥对（如本地不存在）；下载 CA 根证书到 `~/.aun/CA/root/root.crt`
+3. 创建 per-agent 配置文件 `$EVOLCLAW_HOME/agents/<aid>/config.json`（含 `initialized: false`）
+4. 生成并签名上传 `agent.md` 到 AUN 网络
+
+AUN 通道由 `agent.aid` 隐式驱动，不需要单独配 channel——`evolclaw start` 后即自动连接；首次连接成功并向 owner 发完欢迎消息后，`config.json` 中的 `initialized` 会被更新为 `true`。
+
+### 步骤 8：启动前验证
 
 读取配置文件确认关键字段：
 
 ```bash
-cat ~/.evolclaw/data/evolclaw.json
+cat $EVOLCLAW_HOME/agents/<aid>/config.json
 ```
 
-检查：
-- `channels.aun.aid` — 你的 AID
-- `channels.aun.owner` — Owner AID
+检查关键字段：
+
+- `aid` — 你的 AID
+- `owners` — Owner AID 数组（可为空，留给自动绑定）
+- `active_baseagent` — `claude` / `codex` / `gemini`
 - `projects.defaultPath` — 项目路径（目录需存在）
-- `channels.defaultChannel` — 应为 `"aun"`
+- `channels` — 数组，初始为空（AUN 隐式上线，无需在此配置）
+- `initialized` — 应为 `false`（首次连接成功后由系统更新为 `true`）
+
+> 注：config.json 还包含 `$schema_version`、`enabled`、`baseagents`、`chatmode`、`dispatch` 等字段，由 `agent new` 自动填入，无需手动检查。
 
 如发现缺失或异常，向用户说明并提供修复方案。
 
-### 步骤 7：启动服务
+### 步骤 9：启动服务
+
+首次安装（服务未运行）：
 
 ```bash
 evolclaw start
 ```
 
-### 步骤 8：验证运行状态
+若服务已在运行（升级/重装场景，步骤 3 已停止旧进程）：
+
+```bash
+evolclaw restart
+```
+
+### 步骤 10：验证运行状态
 
 ```bash
 evolclaw status
-tail -n 30 ~/.evolclaw/logs/evolclaw.log
+evolclaw logs   # 实时滚动日志，Ctrl+C 退出
+```
+
+或直接读最近日志（LogWriter 会切片归档，需要 `tail -F` 跨切片续接）：
+
+```bash
+tail -F ~/.evolclaw/logs/evolclaw.log
 ```
 
 日志中应出现：`[AUN] Connected as @<aid>`
 
-如未出现或有错误，读取完整日志分析原因并提供修复建议。
+如未出现或有错误，读取完整日志分析原因并提供修复建议（也可运行 `evolclaw diagnose` 快速检查配置和数据目录）。
 
 ---
 
@@ -156,9 +221,12 @@ tail -n 30 ~/.evolclaw/logs/evolclaw.log
 
 EvolClaw 首次连接 AUN 网络时自动：
 
-1. 检测 `~/.aun/AIDs/<aid>/agent.md` 中的 `initialized` 字段
-2. 若为 `false`，生成完整 agent.md 并发布到 AUN 网络
-3. 向 Owner 发送欢迎消息
+1. 检测 `$EVOLCLAW_HOME/agents/<aid>/config.json` 中的 `initialized` 字段
+2. 若为 `false`，且 `owners[0]` 已配置：
+   - 生成完整 agent.md（含基于 owner 的 display name）并发布到 AUN 网络
+   - 向 Owner 发送欢迎消息
+   - 把 `config.json` 中的 `initialized` 更新为 `true`
+3. 若 `owners[]` 为空（自动绑定模式）：跳过欢迎消息，`initialized` 维持 `false`；首次有人和该 agent 私聊时自动绑定为 owner，**自动绑定后立即补发欢迎消息**并把 `initialized` 置 `true`（订阅 `channel:owner-bound` 事件实现）
 
 无需手动触发，连接成功后自动完成。
 
@@ -179,10 +247,10 @@ EvolClaw 首次连接 AUN 网络时自动：
 ## 常见问题
 
 **Q: AID 已存在怎么办？**
-`evolclaw init --non-interactive` 会检测本地密钥，已存在则跳过创建。
+`evolclaw agent new` 会检测本地密钥，已存在则跳过创建（`alreadyExisted`）。如果 `agents/<aid>/config.json` 已存在，命令会失败；加 `--force` 可覆盖配置（AID 密钥保留；agent.md 会按当前 `--name` / `--description` 重新生成并重新上传）。
 
 **Q: 启动失败怎么办？**
-查看 `~/.evolclaw/logs/evolclaw.log` 或运行 `evolclaw diagnose`。
+运行 `evolclaw logs` 实时滚动日志，或 `evolclaw diagnose` 检查配置和数据目录。
 
 **Q: 如何重启/查看日志？**
 ```bash
@@ -192,8 +260,19 @@ evolclaw logs
 
 **Q: 如何清理损坏的 AID 重新注册？**
 ```bash
-rm -rf ~/.aun/AIDs/<aid>
-evolclaw init --non-interactive --channel aun --aun-aid <aid> --aun-owner <owner>
+evolclaw aid delete <aid>      # 删本地密钥与证书
+rm -rf $EVOLCLAW_HOME/agents/<aid>   # 删 per-agent 配置
+evolclaw agent new <aid> --non-interactive --project <abs path>
+```
+
+**Q: 想加飞书 / 微信 / 钉钉等 IM 通道？**
+agent 已建好后再单独配置（每条命令交互式从已有 agents 里选目标）：
+```bash
+evolclaw init feishu      # 飞书扫码
+evolclaw init wechat      # 微信扫码
+evolclaw init dingtalk    # 钉钉扫码
+evolclaw init qqbot       # QQ 机器人扫码
+evolclaw init wecom       # 企业微信手输 Bot ID + Secret
 ```
 
 ---
@@ -293,7 +372,8 @@ node -e "try{require('@anthropic-ai/claude-code-win32-x64');console.log('OK')}ca
 # 1. 升级到 evolclaw >= 2.5.4
 npm install -g evolclaw@latest
 
-# 2. 如仍报错，先手动安装 AUN SDK 依赖再执行 init
+# 2. 如仍报错，先手动安装 AUN SDK 依赖再执行 init / agent new
 npm install -g @agentunion/aun-node
-evolclaw init --non-interactive --channel aun --aun-aid <aid> --aun-owner <owner>
-```
+evolclaw init --non-interactive
+evolclaw agent new <aid> --non-interactive --project <abs path>
+```

package/kits/docs/GUIDE.md

@@ -0,0 +1,20 @@
+# 文档查阅指南
+
+## 查阅流程
+
+1. 先看 `$KITS_RULES`（自动加载的 8 个规则文件）了解机制骨架
+2. 需要详细信息时，按 `INDEX.md` 找到对应文档路径
+3. Read 对应文档
+
+## 路径解析
+
+文档中用 `$名称` 引用路径。解析步骤：
+1. 查 `$KITS_RULES/01-entry.md` 的路径体系速查表
+2. 如需完整定义，Read `$KITS_DOCS/path-registry.md`
+3. 如需运行时实际值，Read `$ECK/path-registry.md`
+
+## 不要做的事
+
+- 不要一次性加载所有文档——按需逐个 Read
+- 不要猜测路径——查注册表
+- 不要在当前会话输出对外消息——用 CLI

package/kits/docs/INDEX.md

@@ -0,0 +1,52 @@
+# EvolClaw 文档索引
+
+本文件是 `$KITS_DOCS` 下所有文档的索引。
+
+## 路径与机制
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 查阅指南 | `GUIDE.md` | 文档查阅流程 |
+| 路径定义 | `path-registry.md` | 所有预定义路径及派生规则 |
+
+## AUN 协议
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 速查表 | `aun/CHEATSHEET.md` | AUN 协议命名空间与常用操作速查 |
+| 同步协议 | `aun/SYNC_PROTOCOL.md` | 上游协议同步 SOP |
+
+## EvolClaw 命令
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| Agent 命令 | `evolclaw/AGENT_CMD.md` | agent 全生命周期管理命令 |
+| 运行时工具 | `evolclaw/tools.md` | ctl 命令集 |
+| 自我总结 | `evolclaw/self-summary.md` | 自我总结流程指南 |
+| 私聊消息 | `evolclaw/MSG_PRIVATE.md` | 私聊消息命令 |
+| 群聊消息 | `evolclaw/MSG_GROUP.md` | 群聊消息命令 |
+
+## 身份
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 身份工具 | `identity/identity-tools.md` | 身份识别与环境层工具 |
+| 角色详情 | `identity/ROLE_DETAIL.md` | 角色与场景详细规则 |
+| AID 档案规范 | `identity/AID_PROFILE_SPEC.md` | AID 档案格式规范 |
+| 路径运维 | `identity/PATH_OPS.md` | 路径运维操作 |
+
+## 渠道
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| AUN 渠道 | `channels/aun.md` | AUN 通信约定 |
+| 飞书渠道 | `channels/feishu.md` | 飞书渠道接入 |
+
+## ECK 模板
+
+| 文档 | 路径 | 说明 |
+|------|------|------|
+| 运行时配置模板 | `eck_templates/runtime.template.md` | agent 运行时配置模板 |
+| 路径注册表模板 | `eck_templates/path-registry.template.md` | 路径实例模板 |
+| 索引模板 | `eck_templates/INDEX.template.md` | agent 级索引模板 |
+| 指南模板 | `eck_templates/GUIDE.template.md` | agent 级查阅指南模板 |

package/kits/docs/aun/CHEATSHEET.md

@@ -0,0 +1,17 @@
+# AUN 协议速查表
+
+<!-- TODO: 填充 AUN 协议命名空间与常用操作速查内容 -->
+
+## 命名空间
+
+| 命名空间 | 作用 |
+|---|---|
+| `auth.*` | AID 创建、认证、JWT |
+| `message.*` | 点对点消息收发 |
+| `group.*` | 群组生命周期、群消息 |
+| `storage.*` | 文件上传下载 |
+| `stream.*` | 实时流（语音/视频/token） |
+| `meta.*` | ping、状态、信任根查询 |
+| `nameservice.*` | AID 名字注册查询 |
+| `custody.*` | AID 托管 |
+| `peer.*` / `relay.*` | 直连/中继认证 |

package/kits/docs/aun/SYNC_PROTOCOL.md

@@ -0,0 +1,15 @@
+# AUN 协议同步 SOP
+
+<!-- TODO: 填充上游协议同步流程 -->
+
+## 同步时机
+
+- AUN SDK 有新版本发布时
+- 协议文档有重大变更时
+
+## 同步步骤
+
+1. 拉取上游最新协议文档
+2. 对比本地认知包与上游差异
+3. 更新 `$KITS_RULES/04-aun.md` 和 `$KITS_DOCS/aun/` 下相关文档
+4. 更新索引

package/kits/docs/channels/aun.md

@@ -0,0 +1,25 @@
+# AUN 通信约定
+
+## 消息收发
+
+- 私聊：`message.send` / `message.receive`
+- 群聊：`group.message.send` / `group.message.receive`
+- 消息格式：纯文本 / Markdown / 文件引用
+
+## 身份识别
+
+- 每条入站消息携带发送者 AID
+- 通过 `https://<aid>/agent.md` 获取对端名片
+- 名片包含：名称、能力声明、联系方式
+
+## 连接管理
+
+- evolclaw 自动维护 WebSocket 长连接
+- 断线自动重连（SDK 内置退避策略）
+- 连接状态可通过 `evolclaw ctl aid` 查看
+
+## 群聊
+
+- 群 ID 格式：`<issuer>/<group-name>`
+- 被 @ 时才默认响应（可通过 venue policy 配置）
+- 群消息按窗口批量推送（batch_window_seconds）

package/kits/docs/channels/feishu.md

@@ -0,0 +1,27 @@
+# 飞书渠道
+
+<!-- TODO: 填充飞书渠道接入文档 -->
+
+## 概述
+
+飞书渠道通过 evolclaw 的 feishu channel 实现，支持：
+- 单聊消息收发
+- 群聊消息收发
+- 合并转发消息解析
+- 文件/图片/视频消息
+
+## 配置
+
+在 evolclaw 配置中启用飞书渠道：
+
+```json
+{
+  "channels": {
+    "feishu": {
+      "enabled": true,
+      "appId": "<app-id>",
+      "appSecret": "<app-secret>"
+    }
+  }
+}
+```

package/kits/docs/eck_templates/GUIDE.template.md

@@ -0,0 +1,22 @@
+# Agent 查阅指南
+
+本文件是 {{SELF_AID}} 的个人查阅指南。
+
+## 查阅优先级
+
+1. `$KITS_RULES`（自动加载）— ECK 机制骨架
+2. `$AGENT_INDEX/INDEX.md`（本目录）— 个人索引
+3. `$KITS_DOCS/INDEX.md` — evolclaw 级文档索引
+4. 按索引中的路径 Read 具体文档
+
+## 路径解析
+
+遇到 `$名称` 时：
+1. 查 `$ECK/path-registry.md` 获取实际路径
+2. 如果实例文件中没有，查 `$KITS_DOCS/path-registry.md` 了解派生规则
+
+## 索引维护
+
+当以下范围内有文档变动时，更新本索引：
+- `{{CURRENT_PROJECT}}`
+- `{{AGENT_DIR}}`

package/kits/docs/eck_templates/INDEX.template.md

@@ -0,0 +1,28 @@
+# Agent 索引
+
+本文件是 {{SELF_AID}} 的 agent 级文档索引。
+
+## 项目文档
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| — | — | （初始化后由 agent 维护） | — |
+
+## 个人档案
+
+| 文档 | 路径 | 说明 | 最后更新 |
+|------|------|------|----------|
+| 人格档案 | `$SELF_DIR/persona.md` | 行为规范与人格定义 | {{CREATED_AT}} |
+| 工作记忆 | `$SELF_DIR/memory/working.md` | 短期关注点 | {{CREATED_AT}} |
+
+## 关系档案
+
+| 对端 AID | 路径 | 最后交互 |
+|----------|------|----------|
+| — | — | — |
+
+## 场所档案
+
+| 场所 | 路径 | 说明 |
+|------|------|------|
+| — | — | — |

package/kits/docs/eck_templates/path-registry.template.md

@@ -0,0 +1,33 @@
+# 路径注册表实例
+
+本文件记录运行时解析出的实际路径值。由 evolclaw 初始化时生成。
+
+## 基础路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$EVOLCLAW_HOME` | {{EVOLCLAW_HOME}} |
+| `$PACKAGE_ROOT` | {{PACKAGE_ROOT}} |
+| `$CURRENT_PROJECT` | {{CURRENT_PROJECT}} |
+
+## 派生路径
+
+| 名称 | 实际路径 |
+|------|----------|
+| `$KITS` | {{KITS}} |
+| `$KITS_RULES` | {{KITS_RULES}} |
+| `$KITS_DOCS` | {{KITS_DOCS}} |
+| `$KITS_TEMPLATES` | {{KITS_TEMPLATES}} |
+| `$ECK` | {{ECK}} |
+| `$AGENT_DIR` | {{AGENT_DIR}} |
+| `$SELF_DIR` | {{SELF_DIR}} |
+| `$RELATIONS_DIR` | {{RELATIONS_DIR}} |
+| `$VENUES_DIR` | {{VENUES_DIR}} |
+| `$AGENT_INDEX` | {{AGENT_INDEX}} |
+
+## 外部依赖
+
+| 名称 | 实际路径 | 状态 |
+|------|----------|------|
+| `$KITE` | {{KITE}} | {{KITE_STATUS}} |
+| `$AUN_SDK_CORE` | {{AUN_SDK_CORE}} | {{AUN_SDK_STATUS}} |

package/kits/docs/eck_templates/runtime.template.md

@@ -0,0 +1,19 @@
+# 运行时配置
+
+## 基本信息
+
+- AID: {{SELF_AID}}
+- 名称: {{AGENT_NAME}}
+- 创建时间: {{CREATED_AT}}
+
+## 运行时参数
+
+- 模型: {{MODEL_ID}}
+- 推理强度: {{EFFORT_LEVEL}}
+- 权限模式: {{PERMISSION_MODE}}
+
+## 行为配置
+
+- 自我总结: {{SELF_SUMMARY_ENABLED}}
+- 空闲总结间隔: {{IDLE_SUMMARY_MINUTES}} 分钟
+- 每日总结 token 预算: {{DAILY_SUMMARY_BUDGET}}

package/kits/docs/evolclaw/AGENT_CMD.md

@@ -0,0 +1,31 @@
+# EvolClaw 可用命令
+
+通过 `evolclaw ctl <command> [args]` 管理运行时配置。仅在 evolclaw 托管环境中可用。
+
+## 查询类（所有用户）
+- `evolclaw ctl help` — 显示帮助
+- `evolclaw ctl status` — 显示会话状态
+- `evolclaw ctl check` — 检查渠道健康状态
+
+## 配置类（管理员）
+- `evolclaw ctl model` — 查看当前模型和可选列表
+- `evolclaw ctl model <model-id>` — 切换模型（如 `opus`, `sonnet`, `haiku`）
+- `evolclaw ctl effort` — 查看当前推理强度
+- `evolclaw ctl effort <low|medium|high|max>` — 切换推理强度
+- `evolclaw ctl compact` — 压缩当前会话上下文
+
+## 权限类
+- `evolclaw ctl perm` — 查看当前权限模式（管理员）
+- `evolclaw ctl perm <mode>` — 切换权限模式（仅 owner）
+
+## 运维类（仅 owner）
+- `evolclaw ctl activity <all|dm|owner|none>` — 查看/控制中间输出显示模式
+- `evolclaw ctl send [channel] <message>` — 发送消息
+- `evolclaw ctl file <path>` — 发送文件
+- `evolclaw ctl restart` — 重启服务
+- `evolclaw ctl restart <channel>` — 重连指定渠道
+- `evolclaw ctl agentmd` — 查看当前 agent.md
+- `evolclaw ctl agentmd put` — 发布本地 agent.md
+- `evolclaw ctl agentmd set <内容>` — 直接设置 agent.md 内容
+- `evolclaw ctl aid` — 列出所有 AUN 实例及连接状态
+- `evolclaw ctl aid new <aid>` — 创建新 AID 并热加载

package/kits/docs/evolclaw/MSG_GROUP.md

@@ -0,0 +1,30 @@
+# 群聊消息命令
+
+<!-- TODO: 填充群聊消息命令详细参考 -->
+
+## 发送群消息
+
+```bash
+evolclaw group send <from-aid> <group-id> "<message>"
+```
+
+## 拉取群消息
+
+```bash
+evolclaw group pull <self-aid> <group-id> --app <app-name>
+```
+
+## 群管理
+
+```bash
+evolclaw group create <owner-aid> --name "<group-name>"
+evolclaw group list <self-aid>
+evolclaw group info <self-aid> <group-id>
+evolclaw group invite <self-aid> <group-id> <target-aid>
+evolclaw group kick <self-aid> <group-id> <target-aid>
+evolclaw group members <self-aid> <group-id>
+```
+
+## 自主回复策略
+
+群聊中被 @ 才默认响应，可通过 venue policy 配置其他触发条件。

package/kits/docs/evolclaw/MSG_PRIVATE.md

@@ -0,0 +1,25 @@
+# 私聊消息命令
+
+<!-- TODO: 填充私聊消息命令详细参考 -->
+
+## 发送消息
+
+```bash
+evolclaw msg send <from-aid> <to-aid> "<message>"
+```
+
+## 拉取消息
+
+```bash
+evolclaw msg pull <self-aid> --app <app-name>
+```
+
+## 确认消息
+
+```bash
+evolclaw msg ack <self-aid> --app <app-name> --seq <seq>
+```
+
+## 自主回复策略
+
+收到消息 ≠ 必须回复。是否回复、怎么回复、何时回复由 agent 自主决定。

package/kits/docs/evolclaw/self-summary.md

@@ -0,0 +1,29 @@
+# 自我总结流程指南
+
+自我总结是 agent 的自省行为——在会话结束或空闲时，回顾本次交互，提炼值得记住的信息。
+
+## 触发时机
+
+- 会话结束时（`on_session_end: true`）
+- 空闲超过 N 分钟（`on_idle_minutes: 30`）
+- 每日定时（`daily_at: "03:00"`）
+- 每周定时（`weekly_on: "Sunday"`）
+
+## 总结目标
+
+| 目标层 | 写入位置 | 内容 |
+|---|---|---|
+| 事件性记忆 | `personal/memory/episodic.jsonl` | "我经历了什么"——关键事件、决策、结果 |
+| 语义性记忆 | `personal/memory/semantic.md` | 习得的事实、规律、结论 |
+| 当前关注 | `personal/memory/working.md` | 短期关注点（下次会话开始时加载） |
+| 反思日志 | `personal/journal.jsonl` | 关键决策的复盘、自我修订 |
+
+## 预算控制
+
+- `max_tokens_per_day: 50000`——每日总结消耗的 token 上限
+- 超出预算时跳过本次总结，记录到 `self_summary_failures.jsonl`
+
+## 去重
+
+- episodic.jsonl 按时间窗口去重（同一小时内的重复事件合并）
+- semantic.md 由 LLM 判断是否已有等价结论