evolcore 0.0.35 → 0.0.36

package/kits/skills/ec-skill/scripts/skill.mjs

@@ -41,6 +41,15 @@ function agentSkillsDir() {
 
 const SWITCHES_FILE = '.switches.json';
 
+/**
+ * 写操作后的索引刷新提示。技能目录监控默认关闭（daemon.json `skills.watch=false`），
+ * 不刷新的话注入给模型的技能索引仍是旧列表。
+ */
+function refreshHint() {
+  const aid = process.env.EVOLCORE_SELF_AID || '<aid>';
+  return `注入给模型的技能索引不会自动更新，请执行: ec skill refresh ${aid}`;
+}
+
 // ── 权限门禁 ──────────────────────────────────────────────────────────
 //
 // 三级技能目录的写权限不对等，判据也不同：
@@ -267,23 +276,108 @@ export function resolveAll() {
 
 // ── 子命令 ────────────────────────────────────────────────────────────
 
-export function cmdList({ json = false } = {}) {
+export function cmdList({ json = false, all = false, filter = [], page = 1, limit = 20, paginateJson = false, commandStyle = process.env.SKILL_COMMAND_STYLE || 'cli' } = {}) {
   const skills = resolveAll();
-  if (json) return skills;
+  // --filter 可多次出现，每次值内逗号分隔。
+  // 组内（逗号分隔）→ OR；多个 --filter 之间 → AND。
+  // 匹配范围：技能名 + description，大小写不敏感。
+  const rawGroups = Array.isArray(filter) ? filter : (filter ? [filter] : []);
+  const filterGroups = rawGroups
+    .map(g => String(g).split(',').map(s => s.trim()).filter(Boolean))
+    .filter(g => g.length > 0);
+
+  const descOf = s => {
+    const fm = readFrontmatter(s.dir) || {};
+    return typeof fm.description === 'string' ? fm.description : '';
+  };
+
+  let shown = all ? skills : skills.filter(s => s.enabled);
+  if (filterGroups.length > 0) {
+    shown = shown.filter(s => {
+      const hay = `${s.name}\n${descOf(s)}`.toLowerCase();
+      return filterGroups.every(group => group.some(kw => hay.includes(kw.toLowerCase())));
+    });
+  }
 
-  if (skills.length === 0) return '（没有任何技能）';
+  const cmdPrefix = commandStyle === 'slash' ? '/skill list' : 'ec skill list';
+  const filterArgs = filterGroups.map(g => `--filter '${g.join(',')}'`);
+
+  // 分页：limit > 0 且总数超 limit 才分页
+  const total = shown.length;
+  const effectiveLimit = limit > 0 ? limit : 20;
+  const hasPaging = total > effectiveLimit;
+  const totalPages = hasPaging ? Math.ceil(total / effectiveLimit) : 1;
+  const requestedPage = page < 1 ? 1 : page;
+  const currentPage = Math.min(requestedPage, totalPages);
+  const paged = hasPaging
+    ? shown.slice((currentPage - 1) * effectiveLimit, currentPage * effectiveLimit)
+    : shown;
+
+  // JSON 默认返回全部匹配项（供脚本消费）；显式给了 --page/--limit 才分页
+  if (json) return paginateJson ? paged : shown;
+
+  const enabledCount = skills.filter(s => s.enabled).length;
+  const fmtGroup = g => g.length === 1 ? `"${g[0]}"` : `(${g.map(k => `"${k}"`).join(' | ')})`;
+
+  if (shown.length === 0) {
+    if (filterGroups.length > 0) {
+      const tip = all ? '' : `；搜全部技能: ${[cmdPrefix, '--all', ...filterArgs].join(' ')}`;
+      return `（没有匹配 ${filterGroups.map(fmtGroup).join(' AND ')} 的技能${tip}）`;
+    }
+    return all ? '（没有任何技能）' : `（没有启用的技能，共 ${skills.length} 个；查看全部: ${cmdPrefix} --all）`;
+  }
 
+  const filterNote = filterGroups.length > 0 ? `，过滤: ${filterGroups.map(fmtGroup).join(' AND ')}` : '';
+  const allNote = all ? '' : '（仅列启用；加 --all 查看全部）';
+  const pageNote = hasPaging ? `，第 ${currentPage}/${totalPages} 页` : '';
   const lines = [];
-  lines.push(`${skills.length} 个技能：`);
-  lines.push('');
-  const nameW = Math.max(20, ...skills.map(s => s.name.length + 2));
-  for (const s of skills) {
-    const state = s.enabled ? '开' : '关';
-    const lock = s.locked ? ' [locked]' : '';
-    lines.push(`  ${s.name.padEnd(nameW)}${s.source.padEnd(9)}${state}${lock}`);
+  lines.push(`${skills.length} 个技能，${enabledCount} 个启用${allNote}${filterNote}${pageNote}`);
+
+  const groups = [
+    { label: '内置技能', items: paged.filter(s => s.source === 'builtin') },
+    { label: '本机技能', items: paged.filter(s => s.source === 'local') },
+  ];
+
+  const nameW = Math.max(20, ...paged.map(s => s.name.length + 2));
+
+  for (const { label, items } of groups) {
+    if (items.length === 0) continue;
+    lines.push('');
+    lines.push(`── ${label} (${items.length}) ──`);
+    for (const s of items) {
+      const state = s.enabled ? '开' : '关';
+      const lock = s.locked ? ' [locked]' : '';
+      const fm = readFrontmatter(s.dir) || {};
+      const rawDesc = typeof fm.description === 'string' ? fm.description : '';
+      const desc = rawDesc.length > 30
+        ? rawDesc.slice(0, 30).replace(/[，。、,.\s]+$/, '') + '…'
+        : rawDesc;
+      lines.push(`  ${s.name.padEnd(nameW)}${(state + lock).padEnd(10)}${desc}`);
+    }
   }
-  lines.push('');
-  lines.push('列：名称 / 来源 / 最终状态');
+
+  // 页脚：有翻页就给翻页命令 + 缩小范围的方法（与是否带 --all 无关）
+  if (hasPaging) {
+    const scope = all ? ['--all'] : [];
+    const limitArg = effectiveLimit !== 20 ? [`--limit ${effectiveLimit}`] : [];
+    const pageCmd = p => [cmdPrefix, ...scope, ...filterArgs, ...limitArg, `--page ${p}`].join(' ');
+
+    lines.push('');
+    lines.push(`── 第 ${currentPage}/${totalPages} 页（每页 ${effectiveLimit} 条，共 ${total} 条）──`);
+    if (requestedPage > totalPages) {
+      lines.push(`（请求的第 ${requestedPage} 页超出范围，已显示最后一页）`);
+    }
+    if (currentPage < totalPages) lines.push(`下一页: ${pageCmd(currentPage + 1)}`);
+    if (currentPage > 1) lines.push(`上一页: ${pageCmd(currentPage - 1)}`);
+    if (filterGroups.length === 0) {
+      lines.push(`缩小范围: ${[cmdPrefix, ...scope, "--filter '<关键词>'"].join(' ')}（匹配名称和描述，逗号分隔为或）`);
+      lines.push(`  例: ${[cmdPrefix, ...scope, "--filter '飞书,lark'"].join(' ')}`);
+    } else {
+      lines.push(`继续缩小: 再加一个 --filter（多个 --filter 之间为且）`);
+      lines.push(`  例: ${[cmdPrefix, ...scope, ...filterArgs, "--filter '<关键词>'"].join(' ')}`);
+    }
+  }
+
   return lines.join('\n');
 }
 
@@ -406,6 +500,7 @@ export function cmdCreate(name, { desc = '', force = false, enable = false, json
     '  2. 正文写清步骤；需要时把大块资料放 references/',
     '  3. 需要脚本就放 scripts/，脚本内用 import.meta.dirname 自定位，不要依赖 cwd',
     enable ? `  4. 如需停用: ec skill disable ${name}` : `  4. 完成后启用: ec skill enable ${name}`,
+    ...(enable ? ['', refreshHint()] : []),
   ].join('\n');
 }
 
@@ -472,7 +567,7 @@ export function cmdInstall(src, { force = false, enable = false, json = false }
       `✅ 已安装技能 ${name} → ${target}`,
       `   状态: ${enable ? '已启用' : '已禁用（开关缺省即禁用）'}`,
       '',
-      '约 2 秒后标记待更新，下一条消息处理时重建索引。可用 `ec skill list` 确认。',
+      refreshHint(),
       enable
         ? `如需停用: ec skill disable ${name}`
         : `确认要启用吗？启用: ec skill enable ${name}（本机级全机启用加 --level local）`,
@@ -512,7 +607,7 @@ export function cmdRemove(name, { json = false } = {}) {
 
   const result = { name, removed: true };
   if (json) return result;
-  return `✅ 已删除本机技能 ${name}`;
+  return [`✅ 已删除本机技能 ${name}`, refreshHint()].join('\n');
 }
 
 export function cmdEnableDisable(name, enabled, { level = 'agent', json = false } = {}) {
@@ -545,10 +640,102 @@ export function cmdEnableDisable(name, enabled, { level = 'agent', json = false
     `✅ ${enabled ? '已启用' : '已禁用'} ${name}（${level} 级）`,
     `   写入: ${file}`,
     '',
-    '约 2 秒后标记待更新，下一条消息处理时重建索引。',
+    refreshHint(),
   ].join('\n');
 }
 
+export function cmdPath(name, { json = false } = {}) {
+  if (!name) throw new Error('缺少技能名。用法：ec skill path <name>');
+  const all = resolveAll();
+  // 注意：resolveAll 按覆盖链只保留一个来源（本机覆盖内置），
+  // 需要两个来源都有的情况要分别扫描
+  const roots = skillRoots();
+  const builtinDir = path.join(roots.builtin, name);
+  const localDir = roots.local ? path.join(roots.local, name) : null;
+  const builtinExists = fs.existsSync(path.join(builtinDir, 'SKILL.md'));
+  const localExists = localDir ? fs.existsSync(path.join(localDir, 'SKILL.md')) : false;
+
+  if (!builtinExists && !localExists) {
+    throw new Error(`技能不存在: ${name}\n用 ec skill list --all --filter '${name}' 查找相近的技能`);
+  }
+
+  const skill = all.find(s => s.name === name);
+  const rows = [];
+  if (builtinExists) {
+    const p = path.join(builtinDir, 'SKILL.md');
+    const mtime = fs.statSync(p).mtimeMs;
+    const enabled = skill ? skill.enabled : false;
+    rows.push({ source: 'builtin', enabled, path: p, mtime });
+  }
+  if (localExists) {
+    const p = path.join(localDir, 'SKILL.md');
+    const mtime = fs.statSync(p).mtimeMs;
+    const enabled = skill ? skill.enabled : false;
+    rows.push({ source: 'local', enabled, path: p, mtime });
+  }
+
+  // 建议路径：优先本机级（覆盖链顶端），再按 mtime 最新
+  const suggested = rows.find(r => r.source === 'local') ??
+    rows.reduce((a, b) => b.mtime > a.mtime ? b : a);
+
+  if (json) return { rows, suggested: suggested.path };
+
+  const lines = rows.map(r => {
+    const mtimeStr = new Date(r.mtime).toLocaleString('zh-CN');
+    const stateStr = r.enabled ? '开' : '关';
+    const marker = r.path === suggested.path && rows.length > 1 ? ' ← 建议' : '';
+    return `${r.source.padEnd(8)}${stateStr}  ${r.path}  (${mtimeStr})${marker}`;
+  });
+  if (rows.length === 1) lines.push(rows[0].path);
+  return lines.join('\n');
+}
+
+export function cmdLoad(name, { source = null, withFrontmatter = false, json = false } = {}) {
+  if (!name) throw new Error('缺少技能名。用法：ec skill load <name> [--source builtin|local] [--with-frontmatter]');
+  if (source && source !== 'builtin' && source !== 'local') {
+    throw new Error('--source 只能是 builtin 或 local');
+  }
+
+  const roots = skillRoots();
+  const all = resolveAll();
+  const skill = all.find(s => s.name === name);
+
+  // 确定技能目录：source 指定时用对应根目录，否则按覆盖链结果
+  let skillDir;
+  if (source === 'builtin') {
+    skillDir = path.join(roots.builtin, name);
+  } else if (source === 'local') {
+    if (!roots.local) throw new Error('无法定位本机级目录');
+    skillDir = path.join(roots.local, name);
+  } else {
+    if (!skill) throw new Error(`技能不存在: ${name}\n用 ec skill list --all --filter '${name}' 查找相近的技能`);
+    skillDir = skill.dir;
+  }
+
+  const skillMd = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillMd)) {
+    if (!source) throw new Error(`SKILL.md 不存在: ${skillMd}`);
+    const label = source === 'builtin' ? '内置级' : '本机级';
+    throw new Error(skill
+      ? `${label}没有技能 ${name}（该技能来自 ${skill.source}，去掉 --source 或改用 --source ${skill.source}）`
+      : `${label}没有技能 ${name}\n用 ec skill list --all --filter '${name}' 查找相近的技能`);
+  }
+
+  if (!skill || !skill.enabled) {
+    throw new Error(`技能未启用: ${name}\n请先执行: ec skill enable ${name}`);
+  }
+
+  let content = fs.readFileSync(skillMd, 'utf-8');
+  if (!withFrontmatter) {
+    content = content.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
+  }
+  const footer = `\n---\nskillDir: ${skillDir}\n`;
+  const output = content.trimStart() + footer;
+
+  if (json) return { name, skillDir, content: output };
+  return output;
+}
+
 export function cmdWhere({ json = false } = {}) {
   const roots = skillRoots();
   const info = {

package/kits/skills/ec-trigger/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: ec-trigger
+description: >-
+  EC Trigger（定时/事件触发器）的使用决策指南。用户说"过会儿提醒我""每天/每周几点"
+  "每隔 N 分钟看一眼""盯着、巡检、自动跟进、到时通知""有事就说""定时任务/定时检查/cron/
+  闹钟/计划任务"，或要取消、改期已有 trigger，排查 trigger 为什么没触发、没发送、发错地方时
+  使用。也用于设计事件驱动自动化（消息到达、任务失败、会话闲置后触发）。不适用于当前会话里
+  马上能做完的事（直接做），也不适用于跨话题收发消息本身（用 thread-ops）。
+license: MIT
+---
+
+# EC Trigger 决策指南
+
+**本 skill 只讲决策与行为语义**：什么场景该建 trigger、建哪一种、结果发给谁、建完怎么
+复核、什么时候收尾。参数细节看 `ec trigger --help` 和 `$KITS_DOCS/evolcore/trigger.md`。
+命令的可选参数很多，但建错 90% 是下面四件事里的一件：**执行类型 / 投递目标 / 边界 / NOOP**。
+
+## 一、场景速查（先对号入座）
+
+| 用户这么说 | 该怎么建 |
+|---|---|
+| "明天早上 9 点提醒我带合同" | 一次 `--at` 或单次 cron，**trigger-session**，投递到用户的会话 |
+| "以后每天 9 点给我出昨日总结" | `--cron '0 9 * * *' --tz Asia/Shanghai`，**trigger-session**，投递用户会话 |
+| "帮我把这个任务跟到底，对方回了我马上告诉我" | 跨话题委托时用 `msg send --check-every`，**不要自建 trigger**（见 thread-ops） |
+| "每 30 分钟看一眼升级有没有新版本" | `--every 30m`，**trigger-session**，提示词写"无变化只输出 `[[NOOP]]`"，加 `--max-runs` |
+| "任务失败就自动继续 / 出错误告诉我" | `--event 'task:error'` 或 `--event 'message:received' --event-filter ...` |
+| "帮我盯着这个会话，闲下来时看看有没有漏掉的事" | 这是会话 loop，`/loop 300`（事件 `session:idle`），**不是**普通 trigger |
+| "这个 trigger 改成立刻跑一次试试" | `ec trigger run <id>`；只验证模板用 `--dry-run` |
+| "不要了 / 停掉" | 不再需要就 `ec trigger delete <id>`；只是暂缓用 `disable` |
+
+**先问自己一句**：这件事要一个**全新的模型上下文**去做（巡检、判断、生成摘要），还是
+交给用户**当前那个会话**去做（在已有对话里追问、看上下文才能判断）？答案决定执行类型。
+
+## 二、执行类型（选错最常见）
+
+| 类型 | 谁在执行 | 用在哪 | 坑 |
+|---|---|---|---|
+| `trigger-session` | daemon 专属的 trigger 会话，**与用户对话隔离** | 周期巡检、生成摘要、独立判断。默认同 trigger 复用一条会话 | 只有它支持 `--baseagent`；`--trigger-thread per-run` 每次都开新会话 |
+| `target-session` | 把提示词**当成一条消息**投进目标会话，由那个会话的 agent 处理 | 要在用户的对话里、带着上下文做的事；跨话题复查（`--check-every`） | 不支持 `feedback=silent`；目标会话被占用会等/冲突；也**不支持** `execution.thread` |
+| `script` | 确定性脚本，不过模型 | 只看数、查文件、调 IPC、算东西——**不需要模型判断**时优先用，又快又便宜 | 走沙箱，脚本不能读受保护路径；宿主执行要求独立批准 |
+
+**结论**：用户要"看到结果"→ 让结果落在**用户会话**（trigger-session + target feedback，
+或 target-session）。用户要"有人替我去做判断"→ trigger-session。脚本能做的别用模型。
+
+## 三、投递目标：结果落在哪
+
+`feedback.strategy` 三个可用值：
+
+- **`target`** — 送到 `--target-*` 指定的会话。**最常用**。
+- **`origin`** — 送回创建它的那条会话。在某个话题里建、想回到该话题，用这个（比手写 target 稳）。
+- **`silent`** — 不投递结果，只做副作用（只用于 `trigger-session` / `script`）。
+
+单聊最省事的写法（AUN）：
+
+```bash
+ec trigger create --cron '0 9 * * *' --tz Asia/Shanghai \
+  --exec trigger-session \
+  --prompt '生成昨日要点，直接输出结论' \
+  --target-channel aun --target-channel-id <用户AID> --target-chat-type private \
+  --target-session main --name daily-brief --enable
+```
+
+- `--target-channel aun` 是简写，保存时自动展开成 `aun#<自己AID>#main`。
+- `--target-session main` = 用户的主会话；`thread --target-thread-id <threadId>` = 指定话题。
+- **群聊**：`--target-channel-id` 填**群 AID**，`--target-chat-type group`。
+- 其他渠道（飞书/微信等）要写完整 channelKey，不能写 `aun`。
+- **目标会话不存在时会就地新建一个**，不会报错——建完一定要 `show --json` 看 `feedback.target`
+  是不是你以为的那条会话。
+
+## 四、必须做的四件事
+
+1. **边界**：短期跟进的周期 trigger 加 `--max-runs` 或 `--max-duration`。到上限自动 `disable`
+   （定义留着、可查），不会删。无限周期的巡检只留给用户明确要求"一直跑"的场景。
+2. **NOOP**：周期任务有"没事可报"的情况，提示词里写死"无异常时**只输出** `[[NOOP]]`"。
+   **整段输出必须恰好是 `[[NOOP]]`**（前后不能有其它文字，结尾换行没关系），否则结果照样
+   投递，模型还会额外对着用户说一圈废话。
+3. **复核**：建完立刻 `ec trigger show <id> --json` 看三样：`enabled`、`feedback.target`、
+   `schedule.nextFireAt`（cron 看得到下次触发时刻；与预期不符就是时区/表达式问题）。
+   改定义一律带 `--if-revision <show 返回的 revision>`，改完再看 revision 变了没有。
+4. **收尾**：任务线结束 → `ec trigger delete <id>`。不要用 `disable/cancel` 留尸体——
+   定义和调度状态都会留在磁盘上，越积越多。删除后历史审计仍在（`ec trigger history`）。
+
+## 五、反直觉的语义（文档没写透的）
+
+- **cron 从"创建那一刻"起算下一次**：17:41 建 `0 */2 * * *`，下次是 19:00，不是 18:00。
+- **一次性来源自动关**：`--once` / `--delay` / `--at` 跑完一轮自动 `disable`，定义保留。
+- **错过的时间点合并**：默认 `missedPolicy=run_once`，daemon 停机期间错过的几次只补跑一次。
+- **并发**：默认 `forbid`——同一会话正被另一个 run 占用时，**后到的直接被 skip**；
+  只有 `replace` 才会掐掉前一个。别以为"排队等"。queue 里塞着的多个 target-session
+  trigger 是**串行**的，每个都要等前面跑完。
+- **投递失败只重发结果，不重跑任务**：`effects` 里才是真实投递记录；状态 `failed` 不代表
+  用户没收到。排查时看 `history` 里的 `effects`。
+- **你被 trigger 唤醒时**：信封里的 `触发于:` 是排定时刻（firedAt），不是唤醒时刻；
+  proactive 模式下正文流式输出会被丢弃，**回复必须走 `ec ctl send`**；`[[NOOP]]` 仍适用，
+  只用它、别在它前后多说一句。
+- **提示词里能用的变量**：`{{trigger.name}}`、`{{run.number}}`（第几次）、`{{run.elapsed}}`、
+  `{{date}}`、`{{time}}`，事件触发另有 `{{event.<字段>}}`。提示词正文走同一套渲染。
+- **每次创建都是新 trigger**：重复建同一个提醒会得到多个 trigger，各自都会触发。先 `list` 查。
+- **列表默认只显示 enabled**：排查"怎么没有"要 `ec trigger list --all`。
+
+## 六、常用命令
+
+```bash
+ec trigger list [--all] [--json]
+ec trigger show <id> [--json]                 # revision、nextFireAt、recentRuns、subscription
+ec trigger history [<id>] [--limit 50]        # created/updated/disabled/deleted + 每次 run 终态
+ec trigger update <id> --cron '...' --if-revision <rev>
+ec trigger enable|disable|delete <id>
+ec trigger run <id> [--dry-run]               # 手动跑一次；--dry-run 不执行真实副作用
+```
+
+**定位用 id（`trig_...`）不用名称**。只有 `once/delay/at/cron/every/event` 六种来源，互斥。
+
+## 七、事件触发
+
+`--event` 支持精确名、命名空间前缀（`task:*`）、全量（`*`），配 `--event-filter` 按字段过滤。
+常用：`message:received`、`task:completed`、`task:error`、`session:idle`、`permission:requested`、
+`runner:model-changed`。
+
+- `trigger:*` 是**内部事件**，普通 trigger 订阅不了。
+- 监听 `*` 必须配 filter，否则每次模型输出都会触发。
+- 订阅前查 `$KITS_DOCS/evolcore/event.md` 的事件目录；文末"不存在或已移除的事件"表里的名字
+  一律不要用（写出来的 trigger 会永远不触发）。
+- **脚本的 `files` 字段不会真的发文件**：要发文件在脚本正文或提示词里给出路径。
+
+示例：
+
+```bash
+ec trigger create --event 'task:error' \
+  --exec trigger-session \
+  --prompt '诊断这次失败，给出原因和下一步；无需处理只输出 [[NOOP]]' \
+  --target-channel aun --target-channel-id <用户AID> --target-chat-type private \
+  --target-session main --name task-error-watch --enable
+```
+
+## 八、不要做
+
+1. 不用 trigger 代替当前会话里立刻能做的事。
+2. **默认**不给无上限的周期任务；用户明说长期跑，或任务本身长期有效（如每日简报）才可省略，
+   并在建之前说明"这条会一直跑到被删"。
+3. 不在提示词里写主动发消息的命令（`ec msg send` / `ec ctl send`）——结果会被**再投递一次**，
+   用户收到两遍。让模型只产出正文。
+4. 不用 `--agent` 去操作别的 agent 的 trigger（托管会话里很容易被拒）。
+5. 不直接读 `trigger.json`、`scripts/*`、`data/`、`AIDs/` 这类受保护路径——沙箱按 H 类拦截，
+   脚本会直接启动失败。
+6. 提示词超过 4096 字符用 `--prompt-file`，不要硬塞。
+7. 群聊里不要用 `--mention` 去 @ 人做提醒——`ec group send` 和 trigger 提示词不共享参数；
+   要在群里点名，写进目标会话的提示词里，或让 target-session 在群里自己 @。
+
+## 九、排查手册
+
+| 现象 | 先查 | 常见原因 |
+|---|---|---|
+| 根本没触发 | `show --json` 的 `nextFireAt`、`recentRuns`；`list --all` | 被 disable、cron 表达式/时区错、一次性已跑完、上限已命中 |
+| 触发了但没送到 | `history` 的 `effects` / `feedback` | target 路由写错、AUN 缺 chatType、渠道未配置 |
+| 发到了错的会话 | `show --json` 的 `feedback.target` / `origin` | 在话题里建但用了 target、目标会话不存在被新建 |
+| 用户收到一堆废话 | run 状态 `completed` 但内容很啰嗦 | `[[NOOP]]` 没独占整段输出 |
+| 每次跑很久/堆任务 | `show --json` 的 `active`；`history` | 周期比执行时间短，queue 串行排队；concurrency 设为 forbid |
+| 脚本报沙箱不可用 | 脚本路径/项目路径 | 受保护路径，或宿主未准备沙箱 |
+| 手动跑有效、定时没效 | `history` 时间线 | 错过策略、daemon 停机、时区 |
+
+## 参考资料
+
+- `$KITS_DOCS/evolcore/trigger.md` — 完整参数与 Trigger V3.1 JSON 定义（建复杂 trigger 前读）
+- `$KITS_DOCS/evolcore/event.md` — 事件目录与过滤语法
+- `$KITS/skills/thread-ops/SKILL.md` — 跨话题复查（`--check-every`）的正确用法
+- `$KITS/skills/ec-trigger/references/examples.md` — 可直接改用的 JSON 定义：每日简报、错误告警、闲置巡检、定时发文件

package/kits/skills/ec-trigger/references/examples.md

@@ -0,0 +1,153 @@
+# Trigger 定义样例（Trigger V3.1）
+
+复杂 trigger 用 JSON 导入，CLI flag 覆盖不了的字段（`origin` / `silent` feedback /
+分支模板 / `event filter`）只能走这里：
+
+```bash
+ec trigger create --exec <script|trigger-session|target-session> --file ./trigger.json --enable
+```
+
+`--exec` 必须与 JSON 里的 `execution.type` 一致。`<aid>` 换成自己的 AID。
+
+## 1. 每日简报（trigger-session → 用户会话）
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "daily-brief",
+  "source": { "type": "cron", "expression": "0 9 * * *", "timezone": "Asia/Shanghai" },
+  "execution": {
+    "type": "trigger_session",
+    "prompt": "生成昨日要点：3-5 条，直接给结论，不要寒暄。",
+    "permissionMode": "readonly",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": { "channelKey": "aun", "channelId": "<用户AID>", "chatType": "private", "session": "main" }
+  },
+  "reliability": { "concurrency": "forbid", "missedPolicy": "run_once", "retry": { "maxAttempts": 1, "backoffMs": 30000 } }
+}
+```
+
+## 2. 错误告警（事件 → 原会话，链式恢复的简化版）
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "task-error-watch",
+  "source": {
+    "type": "event",
+    "eventPattern": "task:error",
+    "filter": { "match": { "agentAid": "<aid>", "originTriggerId": { "$exists": false } } }
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "本次任务失败。给出原因与下一步；无需告知用户时只输出 [[NOOP]]。",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": { "channelKey": "aun", "channelId": "<用户AID>", "chatType": "private", "session": "main" }
+  },
+  "reliability": { "concurrency": "forbid", "missedPolicy": "run_once", "retry": { "maxAttempts": 2, "backoffMs": 30000 } }
+}
+```
+
+> `originTriggerId: {$exists: false}` 用来排除"自己触发的错误"造成的递归。
+> 需要"失败后自动恢复原会话"时不要仿写，直接用系统自带的 `__task-recovery`。
+
+## 3. 闲置巡检（session:idle → 原会话）
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "idle-check",
+  "source": {
+    "type": "event",
+    "eventPattern": "session:idle",
+    "filter": { "match": { "chatType": { "$in": ["private", "group"] } } }
+  },
+  "execution": {
+    "type": "target_session",
+    "prompt": "本会话已闲置。检查有没有未完成却停滞的事项；有就在职责内推进或提醒一次，没有只输出 [[NOOP]]。",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": { "strategy": "event_session" },
+  "reliability": { "concurrency": "forbid", "missedPolicy": "run_once", "retry": { "maxAttempts": 2, "backoffMs": 30000 } }
+}
+```
+
+- `session:idle` 只对**打开了会话 loop 的会话**发出：`/loop 300`（主会话）或
+  `/loop 300`（话题会话，配置存在该会话上）。秒数范围 30–86400，默认 300。
+- `event_session` 会把事件里的 `sessionId` 解析回原会话，**不会**退化为普通消息投递；
+  找不到就失败关闭。
+- 系统自带的 `__session-idle-check` 已经是这个形状，`/loop` 要求它处于 enabled。
+
+## 4. 定时给群里发一份文件（script → 群）
+
+脚本在 trigger 目录内，Windows 上非 owner 的脚本要走沙箱（独立批准），普通场景优先
+trigger-session 生成正文后由目标会话自己发文件：
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "weekly-report",
+  "source": { "type": "cron", "expression": "0 10 * * 1", "timezone": "Asia/Shanghai" },
+  "execution": {
+    "type": "trigger_session",
+    "prompt": "生成本周周报（Markdown），写到 <项目目录>/reports/weekly.md，然后把文件路径和一句话摘要输出。",
+    "permissionMode": "auto",
+    "onError": "retry",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": {
+    "strategy": "target",
+    "target": { "channelKey": "aun", "channelId": "<群AID>", "chatType": "group", "session": "main" }
+  },
+  "limits": { "maxRuns": 12 },
+  "reliability": { "concurrency": "forbid", "missedPolicy": "run_once", "retry": { "maxAttempts": 1, "backoffMs": 30000 } }
+}
+```
+
+- 脚本的 `files` 字段**不会**自动发文件，要发就把路径交给目标会话。
+- `limits` 命中后自动 disable，不会删定义。
+
+## 5. 静默 script（只做副作用，不打扰用户）
+
+```json
+{
+  "$schema_version": 3.1,
+  "agentAid": "<aid>",
+  "enabled": true,
+  "name": "clean-tmp",
+  "source": { "type": "cron", "expression": "30 3 * * *", "timezone": "Asia/Shanghai" },
+  "execution": {
+    "type": "script",
+    "script": { "path": "clean.cjs", "runtime": "node", "timeoutMs": 60000 },
+    "onError": "fail",
+    "noopSentinel": "[[NOOP]]"
+  },
+  "feedback": { "strategy": "silent" },
+  "reliability": { "concurrency": "forbid", "missedPolicy": "run_once", "retry": { "maxAttempts": 0, "backoffMs": 30000 } }
+}
+```
+
+## 6. 跨话题复查（只有懂这个形状才手写）
+
+正常用 `ec msg send '...' --thread <T2> --check-every 5m` 生成，不要手写。要点：
+
+- `labels.kind = "cross-thread-review"` 决定投递身份取**目标话题自身**的对端，而不是来源对端。
+- 只支持 `target_session`，`feedback.target.session = "thread"` 且带 `threadId`。
+- 结束复查一律 `ec trigger delete`，积压的复查 trigger 会持续唤醒目标话题。