evolcore 0.0.1 → 0.0.3

package/kits/docs/evolcore/agent.md

@@ -0,0 +1,77 @@
+# ec agent — EvolAgent 生命周期管理
+
+管理本机托管的 EvolAgent（创建、启停、配置、热重载）。触发词：创建/新建/列出/查看/启用/禁用/删除/热重载/改配置。
+
+## 子命令
+
+```bash
+# 列出所有 agent
+ec agent list
+
+# 查看 agent 详情（身份 + 配置 + 连接 + 会话 + 路径）
+ec agent show <aid>
+# 简写，等价于 show
+ec agent <aid>
+
+# 创建 agent（交互式）
+ec agent new [aid]
+
+# 创建 agent（非交互式，自动化场景）
+ec agent new <aid> --non-interactive --project <绝对路径> \
+  [--baseagent claude|codex|gemini] [--owner <aid>] \
+  [--name "<显示名>"] [--description "<text>"] [--force]
+
+# 启用 / 停用
+ec agent enable <aid>
+ec agent disable <aid>
+
+# 读 / 改单个配置字段（支持点路径，如 active_baseagent）
+ec agent get <aid> <key>
+ec agent set <aid> <key> <val>
+
+# 修改 agent.md 显示名称
+ec agent rename <aid> "<name>"
+
+# 标记 bootstrap 完成，进入 active 状态
+ec agent ready <aid>
+
+# 热重载配置（无参数 = 全量 resync：扫磁盘，新增上线/删除下线/修改热更新）
+ec agent reload [aid]
+
+# 删除 agent（--purge 连数据一并清除）
+ec agent delete <aid> [--purge]
+```
+
+## 非交互创建必填项
+
+`ec agent new <aid> --non-interactive` 时：
+- 必填：`--project <absolute path>`
+- 可选：`--baseagent`（默认 PATH 中第一个可用项）、`--owner`、`--name`、`--description`、`--force`（覆盖已有 config.json）
+
+## 头像更新
+
+头像上传通过 menu 协议暴露，不是 `ec agent` CLI 子命令：
+
+```json
+{
+  "type": "menu.action",
+  "name": "agent",
+  "action": "update",
+  "args": {
+    "aid": "mybot.agentid.pub",
+    "patch": {
+      "avatar": "data:image/png;base64,..."
+    }
+  }
+}
+```
+
+约束：
+- `patch.avatar` 必须单独提交，不能和 `chatmode`、`owners`、`channels` 等 config patch 混合。
+- 支持 PNG/JPEG/WebP；后端按解码后图片大小硬限制 500KB。
+- 成功后头像上传到该 agent 自己的 AUN storage，`agent.md` frontmatter 写入 AID 风格 URL，并重新签名发布。
+
+## 通用约定
+
+- `--format json` — 用于 `list/show/new/enable/disable/get/set/rename/ready/reload/delete` 的结构化输出
+- `--help` / `-h` — 各子命令均支持，查看详细用法

package/kits/docs/evolcore/aid.md

@@ -0,0 +1,52 @@
+# ec aid — AID 身份管理
+
+管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
+
+## 子命令
+
+```bash
+# 列出本地所有 AID（实测 sign+verify）
+ec aid list [筛选选项] [--no-verify]
+
+# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
+ec aid show <aid>
+
+# 创建新 AID 身份
+ec aid new <aid> [--force]
+
+# 远程探测 AID（是否存在 + 网关 + agent.md）
+ec aid lookup <aid>
+
+# agent.md 名片：签名上传 / 下载验签
+ec aid agentmd put <aid>
+ec aid agentmd get <aid>
+
+# 删除指定本地 AID（无网络注销）
+ec aid delete <aid>
+```
+
+## list 筛选选项
+
+不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
+- `--mine` — 仅本地可用身份（实测可签名+验签通过）
+- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
+- `--no-cert` — 仅无私钥无证书的孤儿目录
+- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
+
+输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
+
+## delete 批量清理
+
+批量删除**默认 dry-run，加 `--yes` 才真正执行**：
+- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
+- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
+- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
+
+## 通用约定
+
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
+- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
+- `--help` / `-h` — 各子命令均支持

package/kits/docs/evolcore/config.md

@@ -0,0 +1,149 @@
+# ec config — 配置体系底层入口
+
+按作用域读写所有配置参数 + 配置快照/回滚/启动历史。触发词：看配置/改配置/查字段/列配置/校验配置/快照/回滚/历史/对比版本/启动记录。
+
+> `ec config` 是配置读写的统一 CLI 入口；模型交互由 menu 协议和 slash `/model` 提供。
+> 字段按 owner 路由：H 字段写 daemon/defaults/config，HA 行为字段写行为配置。
+
+## 参数读写
+
+```bash
+# 读 effective 值（显示覆盖链来源）；可一次传多个字段批量读取（共享同一 selector/--format）
+ec config get <field> [<field> ...] [--self <aid>] [--peer <X>] [--default] [--process]
+#   单字段输出不变；多字段时 text 每行一条、json 返回 { ok, results: [...] }，任一字段失败退出码为 1
+
+# 写参数：scope 由 selector 推断
+ec config set <field> <value> [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 删除某层显式设置，回落下一层
+ec config unset <field> [--self <aid>] [--peer <X>]
+
+# 查看某一层文件原始内容（不合并，凭证显示 ${VAR} 不展开）
+ec config show [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 打印合并后的全部生效配置
+ec config effective [--self <aid>] [--peer <X>]
+
+# 列出某作用域可设字段（类型/枚举值，来源 schema）
+ec config fields [--self <aid>] [--default] [--process]
+
+# 列出所有配置文件
+ec config list
+
+# 按 schema 校验配置文件
+ec config validate [--self <aid>] [--peer <X>] [--default] [--process]
+
+# 按 schema 物化骨架文件（仅人）
+ec config init [--self <aid>] [--peer <X>] [--default] [--process]
+```
+
+## 快照 / 回滚
+
+总开关直接保存在 `$EVOLCORE_HOME/daemon.json` 顶层，默认 `true`：
+
+```bash
+ec config set configSnapshots true --process
+ec config set configSnapshots false --process
+```
+
+开启时首次成功启动创建全量基线，后续成功启动检测到配置变化后自动建立新版本。关闭时不写快照、启动日志，也不执行自检回落。
+
+```bash
+# 立即创建快照（与当前版本比对，不一致才建；--full 强制新全量）（仅人）
+ec config snapshot [--full] [--desc "说明"]
+
+# 列出快照版本（版本号/类型/触发/时间/说明）
+ec config history
+
+# 对比两版本差异
+ec config diff <v1> <v2>
+
+# 恢复到指定版本：展开到工作目录 + 更新 current.json（先 pre-restore 快照）（仅人）
+ec config restore <version>
+
+# 显示 current.json 选定版本（上次启动回落时给出告警）
+ec config current
+
+# 查看启动历史（含回落标记）
+ec config boots [-n N]
+
+# 清理旧快照（默认 dry-run，--yes 真删；拒删被依赖全量 / current 指向版本）（仅人）
+ec config prune [--keep-full N] [--keep-delta N] [--yes]
+```
+
+## Schema 查看
+
+查看随包分发的配置 schema **定义本身**（`kits/schemas/*.schema.*.json`）——不是读写配置值，而是查「某作用域有哪些字段、类型/枚举/默认、schema 有几个版本」。纯只读，人和 agent 均可。
+
+```bash
+# 概览：列出全部逻辑 schema 及各自当前版本
+ec config schema
+
+# 列出某 schema 磁盘上的所有版本（* 标当前版本，附日期/说明）
+ec config schema <name> --list
+
+# 查看某 schema 的原始定义（缺省版本号 = 当前版本）
+ec config schema <name> [version]
+```
+
+逻辑 schema 名（`<name>`）：`daemon` / `defaults` / `agent-config` / `relation-config` /
+`contact-book` / `role-registry` / `role-config`。
+
+三种输出模式：
+
+| 调用形式 | mode | 输出 |
+|----------|------|------|
+| `config schema` | overview | 全部 schema + 各自当前版本号 |
+| `config schema <name> --list` | versions | 该 schema 所有磁盘版本，`*` 标当前，附 date/description |
+| `config schema <name> [version]` | content | 指定版本（缺省=当前）的完整 schema JSON |
+
+约定与报错：
+- `--list` 与 version 参数互斥（`INVALID_CONFIG_COMMAND`）
+- `--list` 或指定 version 时必须带 `<name>`（`MISSING_ARG`）
+- version 须为非负整数；未知 name → `UNKNOWN_SCHEMA`；版本不存在 → `SCHEMA_VERSION_NOT_FOUND`（错误信息列出可用版本）
+
+> 用途：写配置前先 `ec config fields` 看字段可设值，或 `ec config schema <name>` 看该层 schema 的完整字段约束与 `x-merge` 合并语义；排查「字段为何被拒/怎么合并」时定位 schema 版本。
+
+## 作用域 selector
+
+| 参数 | 作用域 | 落盘 |
+|------|--------|------|
+| `--self <aid>` | agent 级 | `agents/<aid>/config.json` |
+| `--self <aid> --peer <X>` | 关系级 | `agents/<aid>/relations/<peerKey>/config.json` |
+| `--default` | 全局默认 | `agents/defaults.json` |
+| `--process` | 进程级 | `~/.evolcore/daemon.json` |
+| 写操作三者全无 | — | **拒绝**（防误写全局） |
+
+`--peer` 取 `channelType#channelId` 或裸 aid（裸 aid 视为 `aun#<aid>`）。改某作用域后，对应范围所有会话的下一条消息即时生效。
+
+## 覆盖链
+
+```
+defaults → agent/config → relation/config
+```
+
+ConfigManager 只合并上述物理层并返回物理来源。角色策略不进入配置合并链：`permissionMode` 和 `baseagents.*.model` 由消费方按当前角色单独应用。
+
+## 权限控制
+
+**写权限**（API 层判定）：
+- **通用可写字段**：active_baseagent / baseagents / chatmode / show_activities / flush_delay / debounce / render
+- **角色专用入口**：`roles/index.json` 与 `roles/{roleId}.json` 由角色服务维护；relation 的
+  `role` 由角色分配服务维护；`permissionMode` 仅在角色策略中维护
+- **兼容字段**：`enable_rich_content` 仍可读取旧值，但已废弃且不再产生运行时效果
+- **仅人可写**：channels / owners / admins / 凭证 / aid / enabled / projects / aun / models.allowed
+- Agent 托管环境写仅人字段被拒
+
+**操作权限**：
+- 读操作（get/show/list/effective/fields/schema/history/diff/current/boots/validate）：人和 agent 均可
+- 快照管理（snapshot/restore/init/prune）：仅人可执行
+
+**凭证安全**：
+- 凭证一律 `${VAR}` 引用，CLI 读命令永不展开、不泄露明文
+- `.env` 全程禁读写
+
+## 通用约定
+
+- `--format json` — 所有子命令通用
+- 本命令操作本地配置，不连 AUN 网络
+- 单文件内 list 字段 `set` = 追加去重；删单个元素请直接编辑文件（角色/owner 链只增不减）

package/kits/docs/evolcore/contact.md

@@ -0,0 +1,57 @@
+# ec contact — Agent 联系人与访问控制
+
+`ec contact` 管理指定 Agent 的 Contact Book v2。它只接受 AUN AID 主键，并只负责 AUN 私聊拉黑状态；角色统一由 relation `config.json role` 管理。
+
+## 命令
+
+```bash
+ec contact block <aid> --self <agent-aid>
+ec contact unblock <aid> --self <agent-aid>
+ec contact list --blocked --self <agent-aid>
+```
+
+所有命令都要求显式 `--self`，支持 `--format json`。
+
+## 约束
+
+- `<aid>` 和 `--self` 必须是合法 AID。
+- `block/unblock` 只改变本 Agent 的入站接收策略，不代表对端也拉黑了本 Agent。
+- Agent owner 不能被拉黑。
+- `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
+
+## 权限边界
+
+直接从本机终端运行时，这是本地管理命令。
+
+从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
+
+| 操作 | owner | admin | 普通角色 |
+|---|---:|---:|---:|
+| `list --blocked` | 允许 | 允许 | 拒绝 |
+| `block` / `unblock` | 允许 | 允许 | 拒绝 |
+
+缺少、伪造、撤销或跨会话 delegation token 时失败关闭。托管调用的 `--self` 必须等于当前任务所属 Agent。
+
+角色管理使用 Role Menu relation assignment；admin 的授予和撤销必须由 owner 执行。
+
+## JSON 输出
+
+拉黑成功：
+
+```json
+{
+  "ok": true,
+  "operation": "set-blocked",
+  "selfAid": "bot.agentid.pub",
+  "primaryId": "peer.agentid.pub",
+  "blocked": true,
+  "changed": true,
+  "contactRevision": "..."
+}
+```
+
+## 拉黑后的消息行为
+
+- AUN 外部入站在 MessageBridge 的业务入口被拦截，不进入 menu/auth/command/session/queue/LLM。
+- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
+- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。

package/kits/docs/evolcore/ctl.md

@@ -0,0 +1,46 @@
+# ec ctl — 当前会话工具
+
+在**当前托管会话**中发送消息或文件、重命名、管理队列，以及查询项目路径和会话状态。
+
+> ctl 命令通过 IPC 转发给 daemon，仅在 evolcore 托管环境中可用（依赖 `EVOLCORE_SESSION_ID`）。
+
+## 查询
+
+```bash
+ec ctl status        # 查看会话状态
+ec ctl pwd           # 显示当前项目路径
+ec ctl help          # 显示帮助
+```
+
+## 会话名称
+
+```bash
+ec ctl name <新名称>
+```
+
+## 消息（兜底用）
+
+```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 queue               # 查看当前会话队列
+ec ctl queue --full        # 显示完整预览
+ec ctl queue --clear       # 清空待处理消息
+ec ctl queue --cancel <id> # 取消指定消息
+ec ctl queue --interrupt   # 打断当前处理
+```
+
+## 相关命令集
+
+- agent 全生命周期管理（创建/启停/配置）→ `ec agent`（见 agent.md）
+- AID 身份与 agent.md 名片 → `ec aid`（见 aid.md）
+- 定时与事件触发器 → `ec trigger`（见 trigger.md）
+- 模型查看与切换通过 menu 协议或 slash `/model` 完成

package/kits/docs/evolcore/event.md

@@ -0,0 +1,216 @@
+# Trigger Event Catalog
+
+本目录用于编写 `source.type = "event"` 的 trigger 时按需查阅。最终事实源是
+`$PACKAGE_ROOT/src/core/event-bus.ts` 的 `GatewayEvent` 类型；本文只做面向 trigger
+作者的事件索引和使用约定。
+
+## Event Source 规则
+
+`source.eventPattern` 支持三种形式：
+
+| 形式 | 示例 | 含义 |
+|------|------|------|
+| 精确事件名 | `message:received` | 只监听这一种事件 |
+| 命名空间前缀 | `task:*` | 监听该命名空间下所有事件 |
+| 全量 | `*` | 监听所有 EventBus 事件，需谨慎使用 filter |
+
+`source.filter.match` 用事件 payload 的字段路径做匹配，支持：
+
+| 操作 | 示例 |
+|------|------|
+| 等值 | `{ "channel": "feishu" }` |
+| `$in` | `{ "toolName": { "$in": ["Bash", "Edit"] } }` |
+| `$regex` | `{ "content": { "$regex": "^/echo" } }` |
+| 数值比较 | `{ "durationMs": { "$gte": 30000 } }` |
+| 存在性 | `{ "userId": { "$exists": true } }` |
+
+字段路径支持点号，例如 `replyContext.threadId`。禁止使用 `__proto__`、`prototype`、
+`constructor` 路径段。
+
+## 循环防护
+
+监听 `trigger:*` 时，系统默认禁止 trigger 响应自身产生的 trigger 事件：
+当事件带有 `originTriggerId` 且等于当前 trigger id 时，该事件会被跳过。
+
+跨 trigger 的链式触发仍然允许。需要追踪链路时使用：
+
+| 字段 | 含义 |
+|------|------|
+| `runId` | 本次 trigger run 的唯一 ID |
+| `originTriggerId` | 产生当前 `trigger:*` 事件的 trigger id |
+
+## 常用事件
+
+| 事件 | 常见用途 |
+|------|----------|
+| `message:received` | 用户消息触发自动化 |
+| `task:completed` | agent 完成回复后触发后处理 |
+| `task:error` | agent 任务失败后触发诊断或告警 |
+| `permission:requested` | 观察权限请求 |
+| `permission:cancelled` | 权限请求因中断等原因被取消 |
+| `runner:model-changed` | 模型或推理强度变化后同步状态 |
+| `agent:*` | agent 生命周期、配置变化、运行态变化 |
+| `trigger:*` | trigger 编排、链式触发、审计 |
+
+## 事件目录
+
+### system
+
+| 事件 | Payload |
+|------|---------|
+| `system:started` | `{ channels, timestamp }` |
+| `system:shutdown` | `{ reason?, timestamp? }` |
+| `system:restart` | `{ channel, channelId }` |
+
+### channel
+
+| 事件 | Payload |
+|------|---------|
+| `channel:connected` | `{ channel, channelName?, timestamp? }` |
+| `channel:disconnected` | `{ channel, channelName?, reason? }` |
+| `channel:error` | `{ channel, channelName?, status, message, timestamp? }` |
+| `channel:owner-bound` | `{ channel, channelName?, userId }` |
+
+### session
+
+| 事件 | Payload |
+|------|---------|
+| `session:created` | `{ sessionId, channel, channelName?, channelId, projectPath?, name?, chatType?, threadId?, timestamp? }` |
+| `session:switched` | `{ sessionId, fromSessionId, toSessionId }` |
+| `session:deleted` | `{ sessionId }` |
+| `session:renamed` | `{ sessionId, oldName, newName }` |
+| `session:forked` | `{ sessionId, sourceSessionId, name? }` |
+| `session:rewind` | `{ sessionId, turnNum, mode }` |
+| `session:imported` | `{ sessionId, agentSessionId, projectPath }` |
+| `session:chat-mode-changed` | `{ sessionId, mode, timestamp? }` |
+| `session:dispatch-mode-changed` | `{ sessionId, mode, timestamp? }` |
+
+### message
+
+| 事件 | Payload |
+|------|---------|
+| `message:received` | `{ sessionId, channel, channelName?, channelId, content, userId?, agentName?, timestamp? }` |
+| `message:text` | `{ sessionId, text, isFinal }` |
+| `message:thought-put` | `{ agentName, channelId, taskId?, text? }` |
+
+### task
+
+| 事件 | Payload |
+|------|---------|
+| `task:started` | `{ sessionId, agentName?, encrypt?, chatmode? }` |
+| `task:queued` | `{ channel, channelId, replyContext? }` |
+| `task:completed` | `{ sessionId, channel, channelName?, channelId, finalText?, durationMs?, terminalReason?, agentName?, numTurns?, timestamp? }` |
+| `task:error` | `{ sessionId, error, errorType, terminalReason?, agentName? }` |
+| `task:interrupted` | `{ sessionId, reason?, agentName? }` |
+
+### tool
+
+| 事件 | Payload |
+|------|---------|
+| `tool:use` | `{ sessionId, toolName, input, timestamp? }` |
+| `tool:result` | `{ sessionId, toolName, isError?, agentName?, timestamp? }` |
+
+### permission
+
+| 事件 | Payload |
+|------|---------|
+| `permission:requested` | `{ sessionId, requestId, toolName, input }` |
+| `permission:resolved` | `{ sessionId, requestId, approved }` |
+| `permission:cancelled` | `{ sessionId, requestId, toolName?, reason? }` |
+
+### runner
+
+| 事件 | Payload |
+|------|---------|
+| `runner:compact-start` | `{ sessionId }` |
+| `runner:compact-complete` | `{ sessionId, preTokens }` |
+| `runner:model-changed` | `{ sessionId?, agentName?, baseagent?, model?, effort?, timestamp? }` |
+| `runner:idle-timeout` | `{ sessionId, idleSec }` |
+| `runner:idle-notify` | `{ sessionId, idleSec, totalEvents, totalToolCalls, lastToolName? }` |
+| `runner:idle-warn` | `{ sessionId, idleSec, totalEvents, totalToolCalls, lastToolName? }` |
+| `runner:file-sent` | `{ sessionId, filePath, channel, channelName? }` |
+| `runner:state-changed` | `{ sessionId, state }` |
+| `runner:status` | `{ sessionId, subtype, message, timestamp? }` |
+
+### self-heal
+
+| 事件 | Payload |
+|------|---------|
+| `self-heal:started` | `{ reason }` |
+| `self-heal:attempt` | `{ attemptNumber, maxAttempts }` |
+| `self-heal:completed` | `{ success, attempts }` |
+
+### trigger
+
+| 事件 | Payload |
+|------|---------|
+| `trigger:registered` | `{ triggerId, name, peerId?, targetChannel?, targetChannelId?, scheduleType, scheduleValue, timestamp? }` |
+| `trigger:updated` | `{ triggerId, name, peerId?, scheduleType, scheduleValue, timestamp? }` |
+| `trigger:fired` | `{ triggerId, name, runId, originTriggerId, fireTime, targetChannel?, targetChannelId?, scheduleType, timestamp? }` |
+| `trigger:completed` | `{ triggerId, name, runId, originTriggerId, messageId, durationMs, targetChannel, targetChannelId, fireTime }` |
+| `trigger:failed` | `{ triggerId, name, runId, originTriggerId, messageId, error, targetChannel, targetChannelId, fireTime, phase }` |
+| `trigger:skipped` | `{ triggerId, name, runId, originTriggerId, reason, targetChannel, targetChannelId, fireTime? }` |
+| `trigger:cancelled` | `{ triggerId, name, by }` |
+
+### agent
+
+| 事件 | Payload |
+|------|---------|
+| `agent:created` | `{ aid, name?, baseagent?, projectPath?, owner?, timestamp? }` |
+| `agent:updated` | `{ aid, timestamp? }` |
+| `agent:reloaded` | `{ aid, timestamp? }` |
+| `agent:enabled` | `{ aid, reloaded?, timestamp? }` |
+| `agent:disabled` | `{ aid, reloaded?, timestamp? }` |
+| `agent:deleted` | `{ aid, purged?, timestamp? }` |
+| `agent:started` | `{ aid, timestamp? }` |
+| `agent:stopped` | `{ aid, timestamp? }` |
+| `agent:error` | `{ aid, action?, error, timestamp? }` |
+| `agent:baseagent-changed` | `{ aid, baseagent, previousBaseagent?, scope, timestamp? }` |
+
+## 示例
+
+监听飞书用户消息：
+
+```json
+{
+  "source": {
+    "type": "event",
+    "eventPattern": "message:received",
+    "filter": {
+      "match": {
+        "channel": "feishu",
+        "content": { "$regex": "^/echo" }
+      }
+    }
+  }
+}
+```
+
+监听非自身产生的 trigger 完成事件：
+
+```json
+{
+  "source": {
+    "type": "event",
+    "eventPattern": "trigger:completed",
+    "filter": {
+      "match": {
+        "targetChannel": { "$exists": true }
+      }
+    }
+  }
+}
+```
+
+## 不存在或已移除的事件
+
+不要使用这些历史设计稿中出现过的事件：
+
+| 事件 | 替代 |
+|------|------|
+| `message:sent-out` | 使用 `task:completed` |
+| `permission:timeout` | 当前权限不会 timeout；取消用 `permission:cancelled` |
+| `session:safe-mode-entered` / `session:safe-mode-exited` | 已移除 |
+| `project:switched` / `project:bound` | 已移除 |
+| `config:corrupted` | 已移除 |
+| `agent:create-failed` | 使用 `agent:error` 且 `action = "create"` |