evolcore 0.0.25 → 0.0.26

package/kits/docs/evolcore/trigger.md

@@ -1,575 +1,575 @@
-# ec trigger - 定时与事件触发器
-
-创建、查看、启停、删除和手动运行本机 daemon 管理的 trigger。触发词：触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger。
-
-> `ec trigger` 通过 daemon IPC 直接操作 TriggerRuntimeScheduler。agent 会话内省略 `--agent` 时，CLI 使用当前任务上下文里的 agent AID；只有跨身份操作或脱离 agent 会话执行时才需要显式传 `--agent <aid>`。
-
-## 什么时候用
-
-- 用户要求“稍后/每天/每小时/定时/周期性”执行任务
-- 需要无人值守巡检、升级检查、日报、仓库同步
-- 需要基于系统事件触发时，先读 `evolcore/event.md`
-- 需要一次性立即排队执行时，使用 `--once`
-
-不要用 trigger 代替当前会话内的即时动作；一次性马上执行直接处理当前请求。
-
-## 查询
-
-```bash
-ec trigger list
-ec trigger list --all
-ec trigger show <triggerId>
-ec trigger show <triggerId> --json
-ec trigger history [triggerId]
-ec trigger history [triggerId] --limit 500 --json
-```
-
-`list` 默认只显示 enabled trigger。排查历史、禁用项或已达到 limits 的 trigger 时加 `--all`。
-
-`list --json` 返回列表摘要，不返回完整 definition。每项只包含 `id/name/enabled/description`、精简后的 `source`、`execution.type`、`feedback.strategy/target`、`nextFireAt`、最近运行状态和 `updatedAt`。event source 只返回 `eventPattern`，不返回 `filter`；不会返回 prompt/script 参数、model、effort、permissionMode、反馈分支模板、reliability、limits 或 origin。
-
-`show --json` 返回完整 definition、definition `revision` 和精简运行态。active run 只包含标识、阶段、时间和 `eventCount`；schedule 不返回 `sourceSignature`；recent runs 只包含状态与时间摘要；script 只返回路径、runtime、大小和 mtime，不内联脚本文本。完整运行审计使用 `history` 查询。
-
-`history` 查询 `data/triggers/<aid>/history.jsonl` 中的长期审计事件，包括定义创建、完整更新快照、启停、删除 tombstone 和 run 终态。删除 trigger 目录后，历史仍保留。
-
-## 创建
-
-创建操作统一使用 `create`：
-
-| 入口 | 正式命令 | 兼容别名 |
-| --- | --- | --- |
-| CLI | `ec trigger create ...` | `ec trigger set ...` |
-| Slash | `/trigger create ...` | `/trigger set ...` |
-| Menu Protocol | `menu.action name=trigger action=create` | `action=set` |
-
-新调用只使用 `create`；`set` 仅用于兼容旧脚本和旧客户端。三种入口最终都映射到内部操作 `trigger.create`。
-
-Flag 模式适合 agent 现场创建常规 trigger：
-
-```bash
-ec trigger create \
-  --cron '0 9 * * *' \
-  --exec target-session \
-  --prompt '生成昨日摘要并发送给我' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --model <model> --effort high \
-  --name daily-summary \
-  --enable
-```
-
-CLI flag 模式必须显式指定 `--exec`、`--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--exec <type> --file <trigger.json|trigger-dir>` 导入 Trigger V3 第二阶段 JSON；CLI 会校验 `--exec` 与 JSON 的 `execution.type` 一致。
-
-多行或复杂 prompt 使用 `--prompt-file <path>`，文件内容会原样作为 prompt（UTF-8 BOM 会移除）。内联 `--prompt` 最多 4096 个字符；超限时 CLI 会提示改用 `--prompt-file <path>`：
-
-```bash
-ec trigger create --cron '0 9 * * *' \
-  --exec target-session \
-  --prompt-file ./prompts/daily-summary.md \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --name daily-summary --enable
-
-ec trigger update <triggerId> --prompt-file ./prompts/daily-summary-v2.md
-```
-
-`--file` 始终表示导入完整的 `trigger.json` 或 trigger 目录；`--prompt-file` 只表示 prompt 正文。所有 `create` 形式都必须显式指定 `--exec`；`--prompt-file` 与 `--prompt` 互斥，且不能和 `--file` 同时使用。
-
-模型通过 Bash 调用 CLI 且用双引号传递 `--prompt` 时，正文中的双引号、反引号和 Shell 变量形式的 `$` 需要分别写成 `\"`、反斜杠+反引号、`\$`。Shell 会在启动 `ec` 时去掉保护反斜杠，Trigger 中保存的仍是原始正文。
-
-支持的触发来源：
-
-```bash
---once
---delay 30m
---at 2026-06-28T09:00:00+08:00
---cron '0 9 * * *'
---every 4h
---event 'message:received'
-```
-
-这些来源互斥，只能指定一个。`--cron` 表达式必须加引号，避免被 shell 拆成多个参数。`--every` 是固定间隔，`--cron` 是日历调度。`--once` 创建后立即进入一次 run，完成后自动禁用。
-
-`--event` 基于 EventBus 事件触发，事件模式支持精确事件名、命名空间前缀和全量：`message:received`、`message:*`、`*`。flag 模式只支持设置 `eventPattern`；需要按 payload 字段过滤时，使用 Trigger V3 第二阶段 JSON 的 `source.filter.match`，再通过 `--file` 导入。事件清单、payload 字段和过滤操作见 `$KITS_DOCS/evolcore/event.md`。
-
-## 执行类型
-
-Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
-
-```bash
---exec script
---exec trigger-session
---exec target-session
-```
-
-`target-session` 把 `--prompt` 或 `--prompt-file` 的内容当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。创建时必须显式指定 `--exec target-session`，不会再隐式选择该类型。
-
-`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递；prompt 可来自 `--prompt` 或 `--prompt-file`：
-
-```bash
---exec trigger-session \
---prompt '检查服务状态并总结异常' \
---trigger-thread per-run
-```
-
-省略 `--trigger-thread` 时默认使用 `by-trigger`，同一个 trigger 复用同一条 trigger 会话；只有显式指定 `--trigger-thread per-run` 时，每次 run 才使用独立 trigger 会话。
-
-`script` 执行随 trigger 一起保存的脚本：
-
-```bash
---exec script \
---script-path scripts/check.js \
---script-runtime node \
---script-timeout 30s \
---script-args '{"scope":"daily"}'
-```
-
-`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 会被拒绝，脚本正文使用 `update --script-file` 替换。
-
-## 目标与反馈
-
-目标会话字段：
-
-```bash
---target-channel <channelKey>
---target-channel-id <channelId>
---target-chat-type <private|group>
---target-session main
---target-session thread --target-thread-id <threadId>
-```
-
-AUN 渠道由 agent AID 隐式创建，不需要写入 agent 配置的 `channels[]`。CLI 和 Trigger V3.1 definition 均可将 `aun` 用作 `channelKey` 简写；保存前会按 `agentAid` 展开为 `aun#<agentAid>#main`。AUN 目标必须明确设置 `chatType`；`channelId` 在私聊时是对端 ID，在群聊时就是群 ID，不再额外保存 `groupId`。读取缺少 `chatType` 的旧 AUN Trigger definition 时，迁移逻辑会仅在该次迁移中按 `private` 补齐并回写；新建和编辑仍要求显式指定。其他渠道仍需指定完整的实例 channel key。
-
-```json
-{
-  "strategy": "target",
-  "target": {
-    "channelKey": "aun",
-    "channelId": "peer.agentid.pub",
-    "chatType": "private",
-    "session": "main"
-  }
-}
-```
-
-Trigger V3.1 feedback 是单策略：
-
-- `origin`：送回创建 trigger 的来源会话
-- `target`：送到 `feedback.target`
-- `silent`：不投递最终结果
-
-`target-session` 执行类型只支持 `origin` 或 `target`，因为它本身就是投递到一个会话执行；`script` 和 `trigger-session` 可以使用 `silent`。
-
-默认反馈文本：
-
-- success：`reply.text`
-- noop：空文本，不发送
-- failure：标准失败文本
-
-通常不要显式设置 template。只有 `script` 支持 `feedback.onReply/onNoop/onFailure` 分支模板；`trigger-session` 和 `target-session` 不支持自定义分支模板。
-
-可用占位符示例：
-
-```text
-{{reply.text}}
-{{trigger.name}}
-{{reply.meta.durationMs}}
-{{error.message}}
-{{date}} {{time}}
-```
-
-script trigger 返回 `[[NOOP]]` 或 `outcome: "noop"` 时走 noop 分支；默认 noop 静默。
-
-## 模型与权限
-
-执行模型可按 trigger 单独覆盖：
-
-```bash
---model <模型>
---effort <low|medium|high|xhigh|max>
---baseagent <claude|codex|gemini>
-```
-
-`--model` / `--effort` 只覆盖本 trigger 执行时传给 base agent 的模型与推理强度。
-`--baseagent` 仅支持 `--exec trigger-session`，用于给该 trigger 会话单独选择 base agent；
-`script` 和 `target-session` 不接受该参数。未设置时沿用 trigger 所属 agent 当前 active baseagent。
-
-无人值守 trigger 不适合 `request`。需要写文件、git、安装升级、重启服务、管理 trigger 时应显式使用：
-
-```bash
---permission bypass
-```
-
-owner/admin 通过 `/trigger create` 创建时默认使用 `bypass`；非 admin 默认 `readonly`，不能提权到 `bypass`，也不能跨渠道或跨会话指定 target。历史 `/trigger set` 仍是兼容别名。
-
-## 执行边界
-
-周期任务建议设置系统边界，避免无限运行：
-
-```bash
---max-runs 10
---max-duration 3d
-```
-
-任一边界命中后，scheduler 会禁用后续调度，不中断当前 run。
-
-## 管理
-
-```bash
-ec trigger enable <triggerId>
-ec trigger disable <triggerId>
-ec trigger cancel <triggerId>   # disable 的兼容别名
-ec trigger delete <triggerId>
-ec trigger remove <triggerId>   # delete 的兼容别名
-ec trigger rm <triggerId>       # delete 的兼容别名
-```
-
-语义区别：
-
-| 命令 | 定义文件 | 后续调度 | 当前 run | 可恢复 |
-| --- | --- | --- | --- | --- |
-| `disable` / `cancel` | 保留，写 `enabled: false` | 清理 | 不中断 | 可 `enable` |
-| `delete` | 删除整个 trigger 运行态目录，保留 history tombstone | 清理 | 不中断 | 定义不可恢复，审计可复查 |
-
-`delete` 不需要先执行 `disable/cancel`；它内部会先清理 timer/event/schedule，再删除定义。
-
-## 局部更新
-
-`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition。已有 script trigger 使用 `--script-file <path>` 原地替换脚本内容；脚本路径、runtime、args 和调度配置保持不变：
-
-`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。
-
-```bash
-ec trigger update <triggerId> --cron '0 10 * * *'
-ec trigger update <triggerId> --prompt '新的任务内容' --name new-name
-ec trigger update <triggerId> --prompt-file ./prompts/new-task.md
-ec trigger update <triggerId> --script-file ./scripts/check-v2.js
-ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
-```
-
-可更新参数只保留三组常用字段：
-
-- 调度：`--once`、`--delay`、`--at`、`--cron`、`--every`、`--event`、`--tz`
-- 内容：`--prompt` 或 `--prompt-file <path>`、`--name`
-- 执行配置：`--model`、`--effort`、`--permission`
-- 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
-
-脚本的路径、runtime、参数、投递目标、feedback、reliability、limits、event filter 或执行类型需要变化时，删除后重新创建 trigger；仅替换已有脚本正文使用 `--script-file`。
-
-`--if-revision` 是可选的乐观并发检查；值来自 `show --json` 顶层的 `revision`。revision 不一致时更新失败，不覆盖较新的 definition。
-
-`--tz` 只对 cron 有效，用 IANA 时区（如 `Asia/Shanghai`、`UTC`）解释 cron；不写时使用运行进程时区。`--concurrency` 控制上一 run 仍在执行时的行为（`forbid`/`replace`/`allow`）；`--missed-policy` 控制错过触发时间后的行为（`skip`/`run-once`/`run-all`）。
-
-`update --json` 返回更新后的列表摘要和新 revision，不回传包含长 prompt 的完整 definition。
-
-## 手动运行
-
-```bash
-ec trigger run <triggerId>
-ec trigger run <triggerId> --dry-run
-```
-
-`--dry-run` 不写 active 状态、不写正式 audit、不执行真实副作用，适合验证 prompt/template。
-
-## 审计存储
-
-```text
-data/triggers/<aid>/<triggerId>/trigger.json
-data/triggers/<aid>/<triggerId>/active.json
-data/triggers/<aid>/history.jsonl
-logs/trigger-runs.log
-```
-
-- `history.jsonl` 是长期 append-only 审计真相源，默认不自动清理。
-- 旧版 done 归档行保持可读，不会在升级时重写。
-- `trigger-runs.log` 是短期运维日志，按天轮转并保留 7 天。
-- `show` 的 recent run 摘要、运行统计和 `history` 命令读取长期历史。
-- 启动时会把仍保留的旧 `trigger-runs*.log` 幂等补导入 `history.jsonl`。
-
-## 从文件导入
-
-复杂 trigger 使用 Trigger V3 第二阶段 JSON：
-
-```bash
-ec trigger create --exec target-session --file ./trigger.json --enable
-ec trigger create --exec script --file ./trigger-dir --enable
-```
-
-当前产品版本是 Trigger V3 第二阶段；其持久化定义版本为 `$schema_version: 3.1`。旧 `$schema_version: 4` 文件加载时会自动规范化为 `3.1`。
-
-### target-session 示例
-
-```json
-{
-  "$schema_version": 3.1,
-  "agentAid": "<aid>",
-  "enabled": true,
-  "name": "daily-summary",
-  "source": {
-    "type": "cron",
-    "expression": "0 9 * * *",
-    "timezone": "Asia/Shanghai"
-  },
-  "execution": {
-    "type": "target_session",
-    "prompt": "生成昨日摘要并发送给我",
-    "model": "<model>",
-    "effort": "high",
-    "permissionMode": "bypass",
-    "onError": "fail",
-    "noopSentinel": "[[NOOP]]"
-  },
-  "feedback": {
-    "strategy": "target",
-    "target": {
-      "channelKey": "<channelKey>",
-      "channelId": "<channelId>",
-      "chatType": "private",
-      "session": "main"
-    }
-  },
-  "reliability": {
-    "concurrency": "forbid",
-    "missedPolicy": "run_once",
-    "retry": {
-      "maxAttempts": 0,
-      "backoffMs": 30000
-    }
-  }
-}
-```
-
-### trigger-session 示例
-
-```json
-{
-  "$schema_version": 3.1,
-  "agentAid": "<aid>",
-  "enabled": true,
-  "name": "hourly-health-check",
-  "origin": {
-    "channelKey": "<channelKey>",
-    "channelId": "<channelId>",
-    "session": "main"
-  },
-  "source": {
-    "type": "interval",
-    "everyMs": 3600000
-  },
-  "execution": {
-    "type": "trigger_session",
-    "prompt": "检查服务状态并总结异常；无异常输出 [[NOOP]]",
-    "thread": "per_run",
-    "permissionMode": "readonly",
-    "onError": "retry",
-    "noopSentinel": "[[NOOP]]"
-  },
-  "feedback": {
-    "strategy": "origin"
-  },
-  "reliability": {
-    "concurrency": "forbid",
-    "missedPolicy": "run_once",
-    "retry": {
-      "maxAttempts": 1,
-      "backoffMs": 30000
-    }
-  }
-}
-```
-
-### script 示例
-
-```json
-{
-  "$schema_version": 3.1,
-  "agentAid": "<aid>",
-  "enabled": true,
-  "name": "script-health",
-  "source": {
-    "type": "cron",
-    "expression": "0 */4 * * *",
-    "timezone": "Asia/Shanghai"
-  },
-  "execution": {
-    "type": "script",
-    "script": {
-      "path": "scripts/health.js",
-      "runtime": "node",
-      "timeoutMs": 30000
-    },
-    "onError": "retry",
-    "noopSentinel": "[[NOOP]]"
-  },
-  "feedback": {
-    "strategy": "target",
-    "target": {
-      "channelKey": "<channelKey>",
-      "channelId": "<channelId>",
-      "chatType": "private",
-      "session": "main"
-    },
-    "onReply": {
-      "template": "{{reply.text}}"
-    },
-    "onNoop": {
-      "template": ""
-    },
-    "onFailure": {
-      "template": "健康检查失败：{{error.message}}"
-    }
-  },
-  "reliability": {
-    "concurrency": "forbid",
-    "missedPolicy": "run_once",
-    "retry": {
-      "maxAttempts": 2,
-      "backoffMs": 30000
-    }
-  }
-}
-```
-
-## 事件触发
-
-简单事件触发可直接用 flag 模式：
-
-```bash
-ec trigger create --event 'message:received' \
-  --exec target-session \
-  --prompt '检查收到的消息是否需要自动跟进；无动作输出 [[NOOP]]' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name on-message-received --enable
-```
-
-监听某个命名空间下的所有事件：
-
-```bash
-ec trigger create --event 'task:*' \
-  --exec target-session \
-  --prompt '任务完成或失败后生成简短诊断；无动作输出 [[NOOP]]' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name on-task-events --enable
-```
-
-flag 模式不能配置过滤条件。需要根据事件 payload 过滤时，写完整的 Trigger V3 第二阶段 JSON：
-
-```json
-{
-  "$schema_version": 3.1,
-  "agentAid": "<aid>",
-  "enabled": true,
-  "name": "on-important-message",
-  "source": {
-    "type": "event",
-    "eventPattern": "message:received",
-    "filter": {
-      "match": {
-        "channel": "<channelKey>",
-        "channelId": "<channelId>",
-        "content": { "$regex": "日报|告警|失败" }
-      }
-    }
-  },
-  "execution": {
-    "type": "target_session",
-    "prompt": "根据事件内容判断是否需要处理；无动作输出 [[NOOP]]",
-    "permissionMode": "readonly",
-    "onError": "retry",
-    "noopSentinel": "[[NOOP]]"
-  },
-  "feedback": {
-    "strategy": "target",
-    "target": {
-      "channelKey": "<channelKey>",
-      "channelId": "<channelId>",
-      "chatType": "private",
-      "session": "main"
-    }
-  },
-  "reliability": {
-    "concurrency": "forbid",
-    "missedPolicy": "run_once",
-    "retry": {
-      "maxAttempts": 0,
-      "backoffMs": 30000
-    }
-  }
-}
-```
-
-`source.filter.match` 的 key 是 payload 字段路径，支持等值、`$in`、`$regex`、数值比较和 `$exists`。例如 `message:received` 可过滤 `channel`、`channelId`、`content`、`userId`、`sessionId`；完整字段以事件目录为准。
-
-## 常用例子
-
-一次性提醒：
-
-```bash
-ec trigger create --delay 30m \
-  --exec target-session \
-  --prompt '提醒用户检查部署状态' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name deploy-reminder --enable
-```
-
-创建后立即执行一次：
-
-```bash
-ec trigger create --once \
-  --exec target-session \
-  --prompt '生成一次当前状态摘要' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name one-shot-summary --enable
-```
-
-每天巡检：
-
-```bash
-ec trigger create --cron '30 9 * * *' \
-  --exec target-session \
-  --prompt '检查服务状态并汇报异常；无异常输出 [[NOOP]]' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name daily-health-check --enable
-```
-
-复用 trigger 会话做周期跟踪：
-
-```bash
-ec trigger create --every 4h \
-  --exec trigger-session \
-  --trigger-thread by-trigger \
-  --prompt '继续跟踪升级状态并输出最新结论；无变化输出 [[NOOP]]' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name upgrade-watch --enable
-```
-
-定时尝试升级，最多 10 次或 3 天：
-
-```bash
-ec trigger create --every 4h \
-  --max-runs 10 --max-duration 3d \
-  --permission bypass \
-  --model <model> --effort high \
-  --exec target-session \
-  --prompt '尝试执行升级检查；成功后调用 ec trigger disable auto-updater；无变化输出 [[NOOP]]' \
-  --target-channel <channelKey> --target-channel-id <channelId> \
-  --target-session main \
-  --name auto-updater --enable
-```
-
-硬删除：
-
-```bash
-ec trigger delete auto-updater
-```
-
-## 相关文档
-
-- event source 可监听事件：`$KITS_DOCS/evolcore/event.md`
-- Trigger V3 第二阶段执行与反馈设计：`$PACKAGE_ROOT/docs/trigger-v3-phase2-execution-feedback-design.md`
-- limits / disable / delete 语义：`$PACKAGE_ROOT/docs/trigger-limits-feature-v2.md`
+# ec trigger - 定时与事件触发器
+
+创建、查看、启停、删除和手动运行本机 daemon 管理的 trigger。触发词：触发器/定时任务/cron/提醒/定时检查/自动执行/巡检/禁用 trigger/删除 trigger。
+
+> `ec trigger` 通过 daemon IPC 直接操作 TriggerRuntimeScheduler。agent 会话内省略 `--agent` 时，CLI 使用当前任务上下文里的 agent AID；只有跨身份操作或脱离 agent 会话执行时才需要显式传 `--agent <aid>`。
+
+## 什么时候用
+
+- 用户要求“稍后/每天/每小时/定时/周期性”执行任务
+- 需要无人值守巡检、升级检查、日报、仓库同步
+- 需要基于系统事件触发时，先读 `evolcore/event.md`
+- 需要一次性立即排队执行时，使用 `--once`
+
+不要用 trigger 代替当前会话内的即时动作；一次性马上执行直接处理当前请求。
+
+## 查询
+
+```bash
+ec trigger list
+ec trigger list --all
+ec trigger show <triggerId>
+ec trigger show <triggerId> --json
+ec trigger history [triggerId]
+ec trigger history [triggerId] --limit 500 --json
+```
+
+`list` 默认只显示 enabled trigger。排查历史、禁用项或已达到 limits 的 trigger 时加 `--all`。
+
+`list --json` 返回列表摘要，不返回完整 definition。每项只包含 `id/name/enabled/description`、精简后的 `source`、`execution.type`、`feedback.strategy/target`、`nextFireAt`、最近运行状态和 `updatedAt`。event source 只返回 `eventPattern`，不返回 `filter`；不会返回 prompt/script 参数、model、effort、permissionMode、反馈分支模板、reliability、limits 或 origin。
+
+`show --json` 返回完整 definition、definition `revision` 和精简运行态。active run 只包含标识、阶段、时间和 `eventCount`；schedule 不返回 `sourceSignature`；recent runs 只包含状态与时间摘要；script 只返回路径、runtime、大小和 mtime，不内联脚本文本。完整运行审计使用 `history` 查询。
+
+`history` 查询 `data/triggers/<aid>/history.jsonl` 中的长期审计事件，包括定义创建、完整更新快照、启停、删除 tombstone 和 run 终态。删除 trigger 目录后，历史仍保留。
+
+## 创建
+
+创建操作统一使用 `create`：
+
+| 入口 | 正式命令 | 兼容别名 |
+| --- | --- | --- |
+| CLI | `ec trigger create ...` | `ec trigger set ...` |
+| Slash | `/trigger create ...` | `/trigger set ...` |
+| Menu Protocol | `menu.action name=trigger action=create` | `action=set` |
+
+新调用只使用 `create`；`set` 仅用于兼容旧脚本和旧客户端。三种入口最终都映射到内部操作 `trigger.create`。
+
+Flag 模式适合 agent 现场创建常规 trigger：
+
+```bash
+ec trigger create \
+  --cron '0 9 * * *' \
+  --exec target-session \
+  --prompt '生成昨日摘要并发送给我' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --model <model> --effort high \
+  --name daily-summary \
+  --enable
+```
+
+CLI flag 模式必须显式指定 `--exec`、`--target-channel` 和 `--target-channel-id`，并生成 `feedback.strategy=target`。需要 `origin` 或 `silent` feedback 时，用 `/trigger` 或 `--exec <type> --file <trigger.json|trigger-dir>` 导入 Trigger V3 第二阶段 JSON；CLI 会校验 `--exec` 与 JSON 的 `execution.type` 一致。
+
+多行或复杂 prompt 使用 `--prompt-file <path>`，文件内容会原样作为 prompt（UTF-8 BOM 会移除）。内联 `--prompt` 最多 4096 个字符；超限时 CLI 会提示改用 `--prompt-file <path>`：
+
+```bash
+ec trigger create --cron '0 9 * * *' \
+  --exec target-session \
+  --prompt-file ./prompts/daily-summary.md \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --name daily-summary --enable
+
+ec trigger update <triggerId> --prompt-file ./prompts/daily-summary-v2.md
+```
+
+`--file` 始终表示导入完整的 `trigger.json` 或 trigger 目录；`--prompt-file` 只表示 prompt 正文。所有 `create` 形式都必须显式指定 `--exec`；`--prompt-file` 与 `--prompt` 互斥，且不能和 `--file` 同时使用。
+
+模型通过 Bash 调用 CLI 且用双引号传递 `--prompt` 时，正文中的双引号、反引号和 Shell 变量形式的 `$` 需要分别写成 `\"`、反斜杠+反引号、`\$`。Shell 会在启动 `ec` 时去掉保护反斜杠，Trigger 中保存的仍是原始正文。
+
+支持的触发来源：
+
+```bash
+--once
+--delay 30m
+--at 2026-06-28T09:00:00+08:00
+--cron '0 9 * * *'
+--every 4h
+--event 'message:received'
+```
+
+这些来源互斥，只能指定一个。`--cron` 表达式必须加引号，避免被 shell 拆成多个参数。`--every` 是固定间隔，`--cron` 是日历调度。`--once` 创建后立即进入一次 run，完成后自动禁用。
+
+`--event` 基于 EventBus 事件触发，事件模式支持精确事件名、命名空间前缀和全量：`message:received`、`message:*`、`*`。flag 模式只支持设置 `eventPattern`；需要按 payload 字段过滤时，使用 Trigger V3 第二阶段 JSON 的 `source.filter.match`，再通过 `--file` 导入。事件清单、payload 字段和过滤操作见 `$KITS_DOCS/evolcore/event.md`。
+
+## 执行类型
+
+Trigger V3 第二阶段使用 `execution.type` 区分执行位置：
+
+```bash
+--exec script
+--exec trigger-session
+--exec target-session
+```
+
+`target-session` 把 `--prompt` 或 `--prompt-file` 的内容当作一条 trigger 来源消息投递进目标会话队列，并等待该会话处理完成。创建时必须显式指定 `--exec target-session`，不会再隐式选择该类型。
+
+`trigger-session` 在 daemon 内部 trigger 会话执行 prompt，再把最终结果按 feedback 投递；prompt 可来自 `--prompt` 或 `--prompt-file`：
+
+```bash
+--exec trigger-session \
+--prompt '检查服务状态并总结异常' \
+--trigger-thread per-run
+```
+
+省略 `--trigger-thread` 时默认使用 `by-trigger`，同一个 trigger 复用同一条 trigger 会话；只有显式指定 `--trigger-thread per-run` 时，每次 run 才使用独立 trigger 会话。
+
+`script` 执行随 trigger 一起保存的脚本：
+
+```bash
+--exec script \
+--script-path scripts/check.js \
+--script-runtime node \
+--script-timeout 30s \
+--script-args '{"scope":"daily"}'
+```
+
+`script` 不使用 `--prompt` 或 `--prompt-file`；它必须使用 `--script-path` 和 `--script-runtime`。脚本路径必须在 trigger 目录内；通过 `--file` 导入目录时，脚本文件会随 definition 一起上传。已有 script trigger 的 `update --prompt-file` 会被拒绝，脚本正文使用 `update --script-file` 替换。
+
+## 目标与反馈
+
+目标会话字段：
+
+```bash
+--target-channel <channelKey>
+--target-channel-id <channelId>
+--target-chat-type <private|group>
+--target-session main
+--target-session thread --target-thread-id <threadId>
+```
+
+AUN 渠道由 agent AID 隐式创建，不需要写入 agent 配置的 `channels[]`。CLI 和 Trigger V3.1 definition 均可将 `aun` 用作 `channelKey` 简写；保存前会按 `agentAid` 展开为 `aun#<agentAid>#main`。AUN 目标必须明确设置 `chatType`；`channelId` 在私聊时是对端 ID，在群聊时就是群 ID，不再额外保存 `groupId`。读取缺少 `chatType` 的旧 AUN Trigger definition 时，迁移逻辑会仅在该次迁移中按 `private` 补齐并回写；新建和编辑仍要求显式指定。其他渠道仍需指定完整的实例 channel key。
+
+```json
+{
+  "strategy": "target",
+  "target": {
+    "channelKey": "aun",
+    "channelId": "peer.agentid.pub",
+    "chatType": "private",
+    "session": "main"
+  }
+}
+```
+
+Trigger V3.1 feedback 是单策略：
+
+- `origin`：送回创建 trigger 的来源会话
+- `target`：送到 `feedback.target`
+- `silent`：不投递最终结果
+
+`target-session` 执行类型只支持 `origin` 或 `target`，因为它本身就是投递到一个会话执行；`script` 和 `trigger-session` 可以使用 `silent`。
+
+默认反馈文本：
+
+- success：`reply.text`
+- noop：空文本，不发送
+- failure：标准失败文本
+
+通常不要显式设置 template。只有 `script` 支持 `feedback.onReply/onNoop/onFailure` 分支模板；`trigger-session` 和 `target-session` 不支持自定义分支模板。
+
+可用占位符示例：
+
+```text
+{{reply.text}}
+{{trigger.name}}
+{{reply.meta.durationMs}}
+{{error.message}}
+{{date}} {{time}}
+```
+
+script trigger 返回 `[[NOOP]]` 或 `outcome: "noop"` 时走 noop 分支；默认 noop 静默。
+
+## 模型与权限
+
+执行模型可按 trigger 单独覆盖：
+
+```bash
+--model <模型>
+--effort <low|medium|high|xhigh|max>
+--baseagent <claude|codex|gemini>
+```
+
+`--model` / `--effort` 只覆盖本 trigger 执行时传给 base agent 的模型与推理强度。
+`--baseagent` 仅支持 `--exec trigger-session`，用于给该 trigger 会话单独选择 base agent；
+`script` 和 `target-session` 不接受该参数。未设置时沿用 trigger 所属 agent 当前 active baseagent。
+
+无人值守 trigger 不适合 `request`。需要写文件、git、安装升级、重启服务、管理 trigger 时应显式使用：
+
+```bash
+--permission bypass
+```
+
+owner/admin 通过 `/trigger create` 创建时默认使用 `bypass`；非 admin 默认 `readonly`，不能提权到 `bypass`，也不能跨渠道或跨会话指定 target。历史 `/trigger set` 仍是兼容别名。
+
+## 执行边界
+
+周期任务建议设置系统边界，避免无限运行：
+
+```bash
+--max-runs 10
+--max-duration 3d
+```
+
+任一边界命中后，scheduler 会禁用后续调度，不中断当前 run。
+
+## 管理
+
+```bash
+ec trigger enable <triggerId>
+ec trigger disable <triggerId>
+ec trigger cancel <triggerId>   # disable 的兼容别名
+ec trigger delete <triggerId>
+ec trigger remove <triggerId>   # delete 的兼容别名
+ec trigger rm <triggerId>       # delete 的兼容别名
+```
+
+语义区别：
+
+| 命令 | 定义文件 | 后续调度 | 当前 run | 可恢复 |
+| --- | --- | --- | --- | --- |
+| `disable` / `cancel` | 保留，写 `enabled: false` | 清理 | 不中断 | 可 `enable` |
+| `delete` | 删除整个 trigger 运行态目录，保留 history tombstone | 清理 | 不中断 | 定义不可恢复，审计可复查 |
+
+`delete` 不需要先执行 `disable/cancel`；它内部会先清理 timer/event/schedule，再删除定义。
+
+## 局部更新
+
+`update` 是 patch 语义，只提交需要修改的字段；未指定字段（包括长 prompt）保持不变。`--prompt-file <path>` 只更新非 script trigger 的 prompt，不接受完整 definition。已有 script trigger 使用 `--script-file <path>` 原地替换脚本内容；脚本路径、runtime、args 和调度配置保持不变：
+
+`--script-file` 只能通过本机受控 CLI 读取文件并提交给 daemon；脚本 trigger 属于 daemon-owner 控制面，managed Agent task 不能直接读取本地脚本文件。
+
+```bash
+ec trigger update <triggerId> --cron '0 10 * * *'
+ec trigger update <triggerId> --prompt '新的任务内容' --name new-name
+ec trigger update <triggerId> --prompt-file ./prompts/new-task.md
+ec trigger update <triggerId> --script-file ./scripts/check-v2.js
+ec trigger update <triggerId> --cron '0 10 * * *' --if-revision 'sha256:...'
+```
+
+可更新参数只保留三组常用字段：
+
+- 调度：`--once`、`--delay`、`--at`、`--cron`、`--every`、`--event`、`--tz`
+- 内容：`--prompt` 或 `--prompt-file <path>`、`--name`
+- 执行配置：`--model`、`--effort`、`--permission`
+- 运行边界：`--max-runs`、`--max-duration`、`--concurrency`、`--missed-policy`
+
+脚本的路径、runtime、参数、投递目标、feedback、reliability、limits、event filter 或执行类型需要变化时，删除后重新创建 trigger；仅替换已有脚本正文使用 `--script-file`。
+
+`--if-revision` 是可选的乐观并发检查；值来自 `show --json` 顶层的 `revision`。revision 不一致时更新失败，不覆盖较新的 definition。
+
+`--tz` 只对 cron 有效，用 IANA 时区（如 `Asia/Shanghai`、`UTC`）解释 cron；不写时使用运行进程时区。`--concurrency` 控制上一 run 仍在执行时的行为（`forbid`/`replace`/`allow`）；`--missed-policy` 控制错过触发时间后的行为（`skip`/`run-once`/`run-all`）。
+
+`update --json` 返回更新后的列表摘要和新 revision，不回传包含长 prompt 的完整 definition。
+
+## 手动运行
+
+```bash
+ec trigger run <triggerId>
+ec trigger run <triggerId> --dry-run
+```
+
+`--dry-run` 不写 active 状态、不写正式 audit、不执行真实副作用，适合验证 prompt/template。
+
+## 审计存储
+
+```text
+data/triggers/<aid>/<triggerId>/trigger.json
+data/triggers/<aid>/<triggerId>/active.json
+data/triggers/<aid>/history.jsonl
+logs/trigger-runs.log
+```
+
+- `history.jsonl` 是长期 append-only 审计真相源，默认不自动清理。
+- 旧版 done 归档行保持可读，不会在升级时重写。
+- `trigger-runs.log` 是短期运维日志，按天轮转并保留 7 天。
+- `show` 的 recent run 摘要、运行统计和 `history` 命令读取长期历史。
+- 启动时会把仍保留的旧 `trigger-runs*.log` 幂等补导入 `history.jsonl`。
+
+## 从文件导入
+
+复杂 trigger 使用 Trigger V3 第二阶段 JSON：
+
+```bash
+ec trigger create --exec target-session --file ./trigger.json --enable
+ec trigger create --exec script --file ./trigger-dir --enable
+```
+
+当前产品版本是 Trigger V3 第二阶段；其持久化定义版本为 `$schema_version: 3.1`。旧 `$schema_version: 4` 文件加载时会自动规范化为 `3.1`。
+
+### target-session 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "daily-summary",
+  "source": {
+    "type": "cron",
+    "expression": "0 9 * * *",
+    "timezone": "Asia/Shanghai"
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "生成昨日摘要并发送给我",
+    "model": "<model>",
+    "effort": "high",
+    "permissionMode": "bypass",
+    "onError": "fail",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "chatType": "private",
+      "session": "main"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 0,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+### trigger-session 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "hourly-health-check",
+  "origin": {
+    "channelKey": "<channelKey>",
+    "channelId": "<channelId>",
+    "session": "main"
+  },
+  "source": {
+    "type": "interval",
+    "everyMs": 3600000
+  },
+  "execution": {
+    "type": "trigger_session",
+    "prompt": "检查服务状态并总结异常；无异常输出 [[NOOP]]",
+    "thread": "per_run",
+    "permissionMode": "readonly",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "origin"
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 1,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+### script 示例
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "script-health",
+  "source": {
+    "type": "cron",
+    "expression": "0 */4 * * *",
+    "timezone": "Asia/Shanghai"
+  },
+  "execution": {
+    "type": "script",
+    "script": {
+      "path": "scripts/health.js",
+      "runtime": "node",
+      "timeoutMs": 30000
+    },
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "chatType": "private",
+      "session": "main"
+    },
+    "onReply": {
+      "template": "{{reply.text}}"
+    },
+    "onNoop": {
+      "template": ""
+    },
+    "onFailure": {
+      "template": "健康检查失败：{{error.message}}"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 2,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+## 事件触发
+
+简单事件触发可直接用 flag 模式：
+
+```bash
+ec trigger create --event 'message:received' \
+  --exec target-session \
+  --prompt '检查收到的消息是否需要自动跟进；无动作输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name on-message-received --enable
+```
+
+监听某个命名空间下的所有事件：
+
+```bash
+ec trigger create --event 'task:*' \
+  --exec target-session \
+  --prompt '任务完成或失败后生成简短诊断；无动作输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name on-task-events --enable
+```
+
+flag 模式不能配置过滤条件。需要根据事件 payload 过滤时，写完整的 Trigger V3 第二阶段 JSON：
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "on-important-message",
+  "source": {
+    "type": "event",
+    "eventPattern": "message:received",
+    "filter": {
+      "match": {
+        "channel": "<channelKey>",
+        "channelId": "<channelId>",
+        "content": { "$regex": "日报|告警|失败" }
+      }
+    }
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "根据事件内容判断是否需要处理；无动作输出 [[NOOP]]",
+    "permissionMode": "readonly",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": {
+      "channelKey": "<channelKey>",
+      "channelId": "<channelId>",
+      "chatType": "private",
+      "session": "main"
+    }
+  },
+  "reliability": {
+    "concurrency": "forbid",
+    "missedPolicy": "run_once",
+    "retry": {
+      "maxAttempts": 0,
+      "backoffMs": 30000
+    }
+  }
+}
+```
+
+`source.filter.match` 的 key 是 payload 字段路径，支持等值、`$in`、`$regex`、数值比较和 `$exists`。例如 `message:received` 可过滤 `channel`、`channelId`、`content`、`userId`、`sessionId`；完整字段以事件目录为准。
+
+## 常用例子
+
+一次性提醒：
+
+```bash
+ec trigger create --delay 30m \
+  --exec target-session \
+  --prompt '提醒用户检查部署状态' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name deploy-reminder --enable
+```
+
+创建后立即执行一次：
+
+```bash
+ec trigger create --once \
+  --exec target-session \
+  --prompt '生成一次当前状态摘要' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name one-shot-summary --enable
+```
+
+每天巡检：
+
+```bash
+ec trigger create --cron '30 9 * * *' \
+  --exec target-session \
+  --prompt '检查服务状态并汇报异常；无异常输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name daily-health-check --enable
+```
+
+复用 trigger 会话做周期跟踪：
+
+```bash
+ec trigger create --every 4h \
+  --exec trigger-session \
+  --trigger-thread by-trigger \
+  --prompt '继续跟踪升级状态并输出最新结论；无变化输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name upgrade-watch --enable
+```
+
+定时尝试升级，最多 10 次或 3 天：
+
+```bash
+ec trigger create --every 4h \
+  --max-runs 10 --max-duration 3d \
+  --permission bypass \
+  --model <model> --effort high \
+  --exec target-session \
+  --prompt '尝试执行升级检查；成功后调用 ec trigger disable auto-updater；无变化输出 [[NOOP]]' \
+  --target-channel <channelKey> --target-channel-id <channelId> \
+  --target-session main \
+  --name auto-updater --enable
+```
+
+硬删除：
+
+```bash
+ec trigger delete auto-updater
+```
+
+## 相关文档
+
+- event source 可监听事件：`$KITS_DOCS/evolcore/event.md`
+- Trigger V3 第二阶段执行与反馈设计：`$PACKAGE_ROOT/docs/trigger-v3-phase2-execution-feedback-design.md`
+- limits / disable / delete 语义：`$PACKAGE_ROOT/docs/trigger-limits-feature-v2.md`