evolcore 0.0.23 → 0.0.25

package/kits/docs/evolcore/contact.md

@@ -1,68 +1,68 @@
-# ec contact — Agent 联系人与访问控制
-
-`ec contact` 管理指定 Agent 的 Contact Book v3。它只接受 AUN AID 主键；拉黑的是该 canonical AID，
-因此会拒绝它在 AUN 以及所有已绑定外部渠道中的私聊入站。角色统一由 relation `config.json role` 管理。
-
-## 命令
-
-```bash
-ec contact add <aid> --self <agent-aid>
-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。
-- Agent 托管会话中的 `add` 只能针对当前 AUN 私聊对端；它创建/更新 `pending`，并向本 Agent Owner 发送审核卡片。
-- `add` 复用 `/request` 的联系人申请额度、过期和请求版本校验；已有 `pending`/`declined` 条目会重新走申请流程。
-- Owner 在审核卡片点击“通过”后才变为 active；`blocked` 必须先执行 `unblock`。
-- 直接从本机终端执行 `add` 属于本地管理操作，会直接创建或恢复 active 联系人；Connect `action=add` 同样是管理端直接操作。
-- 写入 Agent Owner 时，系统会自动创建该 Owner 的 active 联系人记录。
-- `block/unblock` 只接受已存在的联系人；不存在时返回 `NOT_FOUND`。
-- `block/unblock` 至少改变本 Agent 的入站接收策略；托管任务的普通私聊 `ec msg send` 对 blocked 目标也会在 daemon 侧被拒绝。非托管 AUN CLI 发送不读取本地联系人簿。不代表对端也拉黑了本 Agent。
-- Agent owner 不能被拉黑。
-- `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
-
-## 权限边界
-
-直接从本机终端运行时，这是本地管理命令。
-
-从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
-
-| 操作 | owner | admin | 普通角色 |
-|---|---:|---:|---:|
-| `list --blocked` | 允许 | 允许 | 拒绝 |
-| Agent 会话 `add` 当前私聊对端 | 允许 | 允许 | 由当前关系授权，受 AUN 私聊和申请限制 |
-| `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。
-- 群聊不按成员的联系人状态过滤；`open` 对所有已配置渠道的群聊入站开放，`contacts` 将 Agent 已加入并
-  接收到的群聊视为授权，`owners` 仅 Owner 消息开放。
-- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
-- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。
+# ec contact — Agent 联系人与访问控制
+
+`ec contact` 管理指定 Agent 的 Contact Book v3。它只接受 AUN AID 主键；拉黑的是该 canonical AID，
+因此会拒绝它在 AUN 以及所有已绑定外部渠道中的私聊入站。角色统一由 relation `config.json role` 管理。
+
+## 命令
+
+```bash
+ec contact add <aid> --self <agent-aid>
+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。
+- Agent 托管会话中的 `add` 只能针对当前 AUN 私聊对端；它创建/更新 `pending`，并向本 Agent Owner 发送审核卡片。
+- `add` 复用 `/request` 的联系人申请额度、过期和请求版本校验；已有 `pending`/`declined` 条目会重新走申请流程。
+- Owner 在审核卡片点击“通过”后才变为 active；`blocked` 必须先执行 `unblock`。
+- 直接从本机终端执行 `add` 属于本地管理操作，会直接创建或恢复 active 联系人；Connect `action=add` 同样是管理端直接操作。
+- 写入 Agent Owner 时，系统会自动创建该 Owner 的 active 联系人记录。
+- `block/unblock` 只接受已存在的联系人；不存在时返回 `NOT_FOUND`。
+- `block/unblock` 至少改变本 Agent 的入站接收策略；托管任务的普通私聊 `ec msg send` 对 blocked 目标也会在 daemon 侧被拒绝。非托管 AUN CLI 发送不读取本地联系人簿。不代表对端也拉黑了本 Agent。
+- Agent owner 不能被拉黑。
+- `list --blocked` 只列出当前 blocked contact，并返回 `contactRevision`。
+
+## 权限边界
+
+直接从本机终端运行时，这是本地管理命令。
+
+从 Agent 活动任务执行时，CLI 不直接写文件，而是携带当前 session delegation token 调用 daemon `contact.op`：
+
+| 操作 | owner | admin | 普通角色 |
+|---|---:|---:|---:|
+| `list --blocked` | 允许 | 允许 | 拒绝 |
+| Agent 会话 `add` 当前私聊对端 | 允许 | 允许 | 由当前关系授权，受 AUN 私聊和申请限制 |
+| `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。
+- 群聊不按成员的联系人状态过滤；`open` 对所有已配置渠道的群聊入站开放，`contacts` 将 Agent 已加入并
+  接收到的群聊视为授权，`owners` 仅 Owner 消息开放。
+- 对 `ai`、`bot`、`agent`、`service` 类型的私聊对端，可限频返回 `[rejection] Not accepting messages from you.`。
+- 入站正文中的 `[rejection]` 没有协议控制语义。发送者未被本 Agent 拉黑时，该文本正常进入响应式会话。

package/kits/docs/evolcore/ctl.md

@@ -1,46 +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` 完成
+# 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

@@ -1,216 +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"` |
+# 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"` |