evolcore 0.0.28 → 0.0.29

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

@@ -0,0 +1,629 @@
+/**
+ * ec-skill 唯一实现。
+ *
+ * 被两个入口共用：
+ *   - CLI:    ec skill <sub>        （薄转发到本文件的 export）
+ *   - 模型侧: node <绝对路径>/skill.mjs <sub>
+ *
+ * 脚本必须自定位（import.meta.dirname），绝不依赖 cwd。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { evolcoreHome, loadDep } from './deps.mjs';
+import { readSkillFrontmatter } from './frontmatter.mjs';
+
+// ── 路径 ──────────────────────────────────────────────────────────────
+
+/** 技能三级的根目录 */
+function skillRoots() {
+  return {
+    builtin: path.join(packageRoot(), 'kits', 'skills'),
+    local: path.join(evolcoreHome(), 'skills'),
+    agent: agentSkillsDir(),
+  };
+}
+
+/** 包根：本文件在 <pkg>/kits/skills/ec-skill/scripts/ → 上溯 5 层 */
+function packageRoot() {
+  return path.resolve(import.meta.dirname, '..', '..', '..', '..');
+}
+
+/** 当前 agent 的 skills 目录。由环境变量注入，缺失时退回本机级之外的空值。 */
+function agentSkillsDir() {
+  const agentDir = process.env.EVOLCORE_AGENT_DIR;
+  if (agentDir) return path.join(agentDir, 'skills');
+  const aid = process.env.EVOLCORE_SELF_AID;
+  if (aid) return path.join(evolcoreHome(), 'agents', aid, 'skills');
+  return null;
+}
+
+const SWITCHES_FILE = '.switches.json';
+
+// ── 权限门禁 ──────────────────────────────────────────────────────────
+//
+// 三级技能目录的写权限不对等，判据也不同：
+//
+//   agent 级  $AGENT_DIR/skills/          只影响本 Agent → 本 Agent 的 owner
+//   本机级    $EVOLCORE_HOME/skills/      整机所有 agent 共享 → daemonowner
+//
+// 群聊一律拒绝——包括 owner 亲自下指令。技能开关是 agent 的自身配置，
+// 不该被群里的对话推动（owner 要改就私聊说）。
+//
+// 判据取自 daemon 注入的运行时上下文（EVOLCORE_TASK_RUNTIME_CONTEXT）。
+// peerRole 是关系层角色，peerId 是 daemon 自己填的对端原生 ID，会话内伪造不了。
+// 无上下文（宿主终端直连、daemon 自己的调度脚本、CI）视为本机管理员在操作，放行。
+//
+// 门禁只在本文件实现：CLI（ec skill）和模型侧（node skill.mjs）共用同一份实现，
+// 放 CLI 层挡不住模型直接跑脚本那条路径。
+
+const RUNTIME_CONTEXT_ENV = 'EVOLCORE_TASK_RUNTIME_CONTEXT';
+
+/** 读取 daemonowner 名单（daemon.json 的 owners[]）；读不到返回空数组 */
+function daemonOwners() {
+  const file = path.join(evolcoreHome(), 'daemon.json');
+  try {
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!Array.isArray(data?.owners)) return [];
+    return data.owners.map(v => String(v || '').trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 校验当前调用方对某一级的写权限。
+ * @param {'agent'|'local'} scope
+ */
+function assertPermission(scope) {
+  const raw = process.env[RUNTIME_CONTEXT_ENV];
+  if (!raw) return; // 无上下文：终端直连，放行
+
+  let ctx;
+  try {
+    ctx = JSON.parse(raw);
+  } catch {
+    return; // 上下文损坏按无上下文处理，与本目录既有的「读不到就退回默认」一致
+  }
+
+  const chatType = ctx?.chatType;
+  const target = scope === 'local' ? '本机级' : 'Agent 级';
+
+  if (chatType === 'group') {
+    throw new Error(
+      `拒绝：${target}技能开关不支持在群聊中操作。请在私聊中提出，或由管理员在宿主终端执行。`
+    );
+  }
+
+  if (scope === 'agent') {
+    if (ctx?.peerRole !== 'owner' && ctx?.peerRole !== 'admin') {
+      throw new Error(
+        `拒绝：Agent 级技能开关仅限本 Agent 的 owner 或 admin（当前角色：${ctx?.peerRole || '未知'}）。`
+      );
+    }
+    return;
+  }
+
+  // 本机级：所有 agent 共享，仅 daemonowner 可改
+  const peerId = String(ctx?.peerId || '').trim();
+  if (!peerId || !daemonOwners().includes(peerId)) {
+    throw new Error(
+      `拒绝：本机级技能为整机所有 agent 共享，仅限 daemonowner 安装、删除、创建与开关。`
+      + `\n   当前身份：${peerId || '未知'}（可用 ec skill where 查看本机级目录）`
+    );
+  }
+}
+
+// ── 开关读写 ──────────────────────────────────────────────────────────
+
+function readSwitches(dir) {
+  if (!dir) return {};
+  const file = path.join(dir, SWITCHES_FILE);
+  try {
+    if (!fs.existsSync(file)) return {};
+    const data = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (!data || typeof data !== 'object') return {};
+    return data;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * 写开关：读-改-写。原子替换（先写临时文件再 rename），避免写入中途被读到半截。
+ * locked 只在内置级有意义，本机/Agent 级写入时忽略该字段。
+ */
+function writeSwitch(dir, name, { enabled, locked }) {
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, SWITCHES_FILE);
+  const current = readSwitches(dir);
+
+  const entry = { ...(current[name] || {}) };
+  if (enabled !== undefined) entry.enabled = enabled;
+  if (locked !== undefined) entry.locked = locked;
+  current[name] = entry;
+
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(current, null, 2) + '\n', 'utf-8');
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+// ── 技能扫描与校验 ────────────────────────────────────────────────────
+
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** 从 SKILL.md 读 frontmatter（自带解析器，零外部依赖） */
+function readFrontmatter(skillDir) {
+  return readSkillFrontmatter(skillDir);
+}
+
+/**
+ * 校验技能是否合规。返回错误数组（空数组 = 合规）。
+ * 依据 skill-md-spec-and-loading.md §8.1。
+ */
+export function validateSkill(skillDir) {
+  const errors = [];
+  const dirName = path.basename(skillDir);
+
+  if (!fs.existsSync(path.join(skillDir, 'SKILL.md'))) {
+    return [`缺少 SKILL.md`];
+  }
+
+  const fm = readFrontmatter(skillDir);
+  if (fm === null) return [`SKILL.md 缺少 frontmatter（需以 --- 包裹的 YAML 块）`];
+  if (fm.__error) return [`frontmatter 解析失败: ${fm.__error}`];
+
+  const name = typeof fm.name === 'string' ? fm.name.trim() : '';
+  const description = typeof fm.description === 'string' ? fm.description.trim() : '';
+
+  if (!name) errors.push('frontmatter 缺少必填字段 name');
+  if (!description) errors.push('frontmatter 缺少必填字段 description');
+
+  if (name) {
+    if (!NAME_RE.test(name)) errors.push(`name「${name}」不符合 kebab-case（小写字母/数字/连字符）`);
+    if (name.length > 64) errors.push(`name 超过 64 字符（当前 ${name.length}）`);
+    if (name !== dirName) errors.push(`name「${name}」与目录名「${dirName}」不一致`);
+  }
+
+  return errors;
+}
+
+/** 扫描一级目录下所有技能（含 SKILL.md 的目录） */
+function scanSkills(root) {
+  if (!root) return [];
+  try {
+    if (!fs.existsSync(root)) return [];
+    return fs.readdirSync(root, { withFileTypes: true })
+      .filter(e => !e.name.startsWith('.'))
+      .filter(e => e.isDirectory() || e.isSymbolicLink())
+      .map(e => {
+        const dir = path.join(root, e.name);
+        try { if (!fs.statSync(dir).isDirectory()) return null; } catch { return null; }
+        if (!fs.existsSync(path.join(dir, 'SKILL.md'))) return null;
+        return { name: e.name, dir };
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 三级解析 + 覆盖链求值，与 src/core/skill/switch-resolver.ts 同规则。
+ * 来源由 SKILL.md 物理位置决定（本机有同名则算本机）。
+ */
+export function resolveAll() {
+  const roots = skillRoots();
+  const builtinSkills = scanSkills(roots.builtin);
+  const localSkills = scanSkills(roots.local);
+  const builtinSw = readSwitches(roots.builtin);
+  const localSw = readSwitches(roots.local);
+  const agentSw = readSwitches(roots.agent);
+
+  const byName = new Map();
+  for (const s of builtinSkills) byName.set(s.name, { ...s, source: 'builtin' });
+  for (const s of localSkills) byName.set(s.name, { ...s, source: 'local' }); // 本机覆盖内置
+
+  const out = [];
+  for (const [name, info] of byName) {
+    const b = builtinSw[name] || {};
+    const l = localSw[name] || {};
+    const a = agentSw[name] || {};
+    const hasBuiltinLock = b.locked === true;
+
+    let enabled;
+    let decidedBy;
+    if (hasBuiltinLock) {
+      enabled = b.enabled === true;
+      decidedBy = 'builtin(locked)';
+    } else if (name in agentSw) {
+      enabled = a.enabled === true;
+      decidedBy = 'agent';
+    } else if (name in localSw) {
+      enabled = l.enabled === true;
+      decidedBy = 'local';
+    } else if (name in builtinSw) {
+      enabled = b.enabled === true;
+      decidedBy = 'builtin';
+    } else {
+      enabled = false;
+      decidedBy = 'default(缺省禁用)';
+    }
+
+    out.push({
+      name,
+      source: info.source,
+      dir: info.dir,
+      enabled,
+      decidedBy,
+      locked: hasBuiltinLock,
+      overridable: !hasBuiltinLock,
+    });
+  }
+  return out.sort((x, y) => x.name.localeCompare(y.name));
+}
+
+// ── 子命令 ────────────────────────────────────────────────────────────
+
+export function cmdList({ json = false } = {}) {
+  const skills = resolveAll();
+  if (json) return skills;
+
+  if (skills.length === 0) return '（没有任何技能）';
+
+  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('');
+  lines.push('列：名称 / 来源 / 最终状态');
+  return lines.join('\n');
+}
+
+export function cmdInfo(name, { json = false } = {}) {
+  const skill = resolveAll().find(s => s.name === name);
+  if (!skill) throw new Error(`技能不存在: ${name}`);
+
+  const roots = skillRoots();
+  const b = readSwitches(roots.builtin)[name] || {};
+  const l = readSwitches(roots.local)[name] || {};
+  const a = readSwitches(roots.agent)[name] || {};
+  const fm = readFrontmatter(skill.dir) || {};
+  const errors = validateSkill(skill.dir);
+
+  const info = {
+    name: skill.name,
+    source: skill.source,
+    dir: skill.dir,
+    description: typeof fm.description === 'string' ? fm.description : '',
+    enabled: skill.enabled,
+    decidedBy: skill.decidedBy,
+    locked: skill.locked,
+    switches: {
+      builtin: name in readSwitches(roots.builtin) ? b : null,
+      local: name in readSwitches(roots.local) ? l : null,
+      agent: name in readSwitches(roots.agent) ? a : null,
+    },
+    valid: errors.length === 0,
+    errors,
+  };
+
+  if (json) return info;
+
+  const lines = [];
+  lines.push(`技能: ${info.name}`);
+  lines.push(`来源: ${info.source}`);
+  lines.push(`路径: ${info.dir}`);
+  lines.push(`状态: ${info.enabled ? '开' : '关'}（由 ${info.decidedBy} 决定）`);
+  if (info.locked) lines.push(`锁定: 内置级 locked，任何级别都关不掉`);
+  lines.push('');
+  lines.push(`描述: ${info.description || '(无)'}`);
+  lines.push('');
+  lines.push('三级开关:');
+  lines.push(`  内置级: ${info.switches.builtin ? JSON.stringify(info.switches.builtin) : '(无声明)'}`);
+  lines.push(`  本机级: ${info.switches.local ? JSON.stringify(info.switches.local) : '(无声明)'}`);
+  lines.push(`  Agent级: ${info.switches.agent ? JSON.stringify(info.switches.agent) : '(无声明)'}`);
+  if (!info.valid) {
+    lines.push('');
+    lines.push('⚠️ 校验问题:');
+    errors.forEach(e => lines.push(`  - ${e}`));
+  }
+  return lines.join('\n');
+}
+
+export function cmdValidate(target, { json = false } = {}) {
+  const dir = resolveSkillDirArg(target);
+  const errors = validateSkill(dir);
+  const valid = errors.length === 0;
+  if (json) return { dir, valid, errors };
+
+  const output = valid
+    ? `✅ ${path.basename(dir)} 校验通过`
+    : [`❌ ${path.basename(dir)} 校验失败:`, ...errors.map(e => `  - ${e}`)].join('\n');
+  // 非 JSON 模式也带上 valid，供 CLI 决定退出码
+  return { valid, output, __isText: true };
+}
+
+/** 把「技能名」或「目录路径」统一解析成技能目录 */
+export function resolveSkillDirArg(target) {
+  if (!target) throw new Error('缺少技能名或路径');
+  if (fs.existsSync(target) && fs.statSync(target).isDirectory()) return path.resolve(target);
+  // 当作技能名，在三级里找
+  const roots = skillRoots();
+  for (const root of [roots.local, roots.builtin]) {
+    if (!root) continue;
+    const dir = path.join(root, target);
+    if (fs.existsSync(dir)) return dir;
+  }
+  throw new Error(`找不到技能: ${target}`);
+}
+
+export function cmdCreate(name, { desc = '', force = false, enable = false, json = false } = {}) {
+  assertPermission('local'); // 骨架固定建在本机级，与 install 同档
+  if (!name) throw new Error('缺少技能名。用法：ec skill create <name> --desc "..."');
+  if (!NAME_RE.test(name)) {
+    throw new Error(`技能名「${name}」不符合 kebab-case（小写字母/数字/连字符，如 my-skill）`);
+  }
+  if (name.length > 64) throw new Error(`技能名超过 64 字符`);
+
+  const roots = skillRoots();
+  const target = path.join(roots.local, name);
+
+  if (fs.existsSync(target) && !force) {
+    throw new Error(`技能已存在: ${target}\n如需覆盖请加 --force`);
+  }
+
+  fs.mkdirSync(path.join(target, 'scripts'), { recursive: true });
+  fs.mkdirSync(path.join(target, 'references'), { recursive: true });
+
+  const tmpl = fs.readFileSync(path.join(import.meta.dirname, 'template', 'SKILL.md.tmpl'), 'utf-8');
+  const content = tmpl
+    .replaceAll('{{name}}', name)
+    .replaceAll('{{description}}', desc || '（一句话说明这个技能做什么。务必补全触发场景与不适用场景，description 是模型选择技能的唯一依据。）');
+
+  fs.writeFileSync(path.join(target, 'SKILL.md'), content, 'utf-8');
+
+  // 与 install 一致：缺省即禁用，不写开关文件；只有 --enable 才显式开启
+  if (enable) writeSwitch(roots.local, name, { enabled: true });
+
+  const result = { name, dir: target, created: true, enabled: enable };
+  if (json) return result;
+
+  return [
+    `✅ 已创建技能 ${name}`,
+    `   路径: ${target}`,
+    `   状态: ${enable ? '已启用' : '已禁用（开关缺省即禁用）'}`,
+    '',
+    '下一步：',
+    '  1. 补全 SKILL.md 的 description（决定技能会不会被选中，务必写清触发场景）',
+    '  2. 正文写清步骤；需要时把大块资料放 references/',
+    '  3. 需要脚本就放 scripts/，脚本内用 import.meta.dirname 自定位，不要依赖 cwd',
+    enable ? `  4. 如需停用: ec skill disable ${name}` : `  4. 完成后启用: ec skill enable ${name}`,
+  ].join('\n');
+}
+
+export function cmdInstall(src, { force = false, enable = false, json = false } = {}) {
+  assertPermission('local'); // 目标恒为本机级
+  if (!src) throw new Error('缺少源。用法：ec skill install <目录|zip文件|SKILL.md>');
+  if (!fs.existsSync(src)) throw new Error(`源不存在: ${src}`);
+
+  const roots = skillRoots();
+  const stat = fs.statSync(src);
+  let staging = null;
+  let skillDir;
+
+  if (stat.isDirectory()) {
+    skillDir = path.resolve(src);
+  } else if (/\.zip$/i.test(src)) {
+    staging = extractZip(src);
+    skillDir = findSkillDirIn(staging);
+    if (!skillDir) throw new Error(`压缩包里没找到 SKILL.md（已解压到 ${staging}）`);
+  } else if (/\.md$/i.test(src)) {
+    staging = fs.mkdtempSync(path.join(os.tmpdir(), 'ec-skill-'));
+    const name = path.basename(src).replace(/\.md$/i, '');
+    skillDir = path.join(staging, name);
+    fs.mkdirSync(skillDir, { recursive: true });
+    fs.copyFileSync(src, path.join(skillDir, 'SKILL.md'));
+  } else {
+    throw new Error(`不支持的源类型: ${src}（支持目录、.zip、.md）`);
+  }
+
+  try {
+    const name = path.basename(skillDir);
+
+    // 安全：不得装进内置级，不得装进 Agent 级
+    if (samePath(skillDir, roots.builtin) || isInside(skillDir, roots.builtin)) {
+      throw new Error('拒绝安装：源位于内置级目录内（内置技能随包发布，不可通过 install 修改）');
+    }
+    if (roots.agent && (samePath(skillDir, roots.agent) || isInside(skillDir, roots.agent))) {
+      throw new Error('拒绝安装：源位于 Agent 级目录内（Agent 级只放开关，不放 SKILL.md）');
+    }
+    if (!NAME_RE.test(name)) {
+      throw new Error(`技能名「${name}」不符合 kebab-case，拒绝安装`);
+    }
+
+    const errors = validateSkill(skillDir);
+    if (errors.length > 0) {
+      throw new Error(['拒绝安装：SKILL.md 校验未通过', ...errors.map(e => `  - ${e}`)].join('\n'));
+    }
+
+    const target = path.join(roots.local, name);
+    if (fs.existsSync(target)) {
+      if (!force) throw new Error(`技能已存在: ${target}\n如需覆盖请加 --force`);
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+
+    copyDir(skillDir, target);
+
+    // 装完**不写开关文件**：开关字典里没有该技能 = 禁用（缺省即禁用）。
+    // 只有 --enable 才显式写入 {"enabled": true}。
+    if (enable) writeSwitch(roots.local, name, { enabled: true });
+
+    const result = { name, dir: target, installed: true, enabled: enable };
+    if (json) return result;
+    return [
+      `✅ 已安装技能 ${name} → ${target}`,
+      `   状态: ${enable ? '已启用' : '已禁用（开关缺省即禁用）'}`,
+      '',
+      '约 2 秒后标记待更新，下一条消息处理时重建索引。可用 `ec skill list` 确认。',
+      enable
+        ? `如需停用: ec skill disable ${name}`
+        : `确认要启用吗？启用: ec skill enable ${name}（本机级全机启用加 --level local）`,
+    ].join('\n');
+  } finally {
+    if (staging) fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+export function cmdRemove(name, { json = false } = {}) {
+  assertPermission('local'); // 只删本机级
+  if (!name) throw new Error('缺少技能名。用法：ec skill remove <name>');
+  const roots = skillRoots();
+  const target = path.join(roots.local, name);
+
+  if (!fs.existsSync(target)) {
+    if (fs.existsSync(path.join(roots.builtin, name))) {
+      throw new Error(`「${name}」是内置技能，随包发布，不能用 remove 删除。\n如要禁用请用: ec skill disable ${name}`);
+    }
+    throw new Error(`本机级没有这个技能: ${name}`);
+  }
+
+  fs.rmSync(target, { recursive: true, force: true });
+
+  // 顺带清掉该技能在本机级/Agent 级的开关残留
+  for (const dir of [roots.local, roots.agent]) {
+    if (!dir) continue;
+    const sw = readSwitches(dir);
+    if (name in sw) {
+      delete sw[name];
+      const file = path.join(dir, SWITCHES_FILE);
+      const tmp = `${file}.tmp-${process.pid}`;
+      fs.writeFileSync(tmp, JSON.stringify(sw, null, 2) + '\n', 'utf-8');
+      fs.renameSync(tmp, file);
+    }
+  }
+
+  const result = { name, removed: true };
+  if (json) return result;
+  return `✅ 已删除本机技能 ${name}`;
+}
+
+export function cmdEnableDisable(name, enabled, { level = 'agent', json = false } = {}) {
+  if (!name) throw new Error(`缺少技能名。用法：ec skill ${enabled ? 'enable' : 'disable'} <name>`);
+  if (!['agent', 'local'].includes(level)) {
+    throw new Error(`--level 只能是 agent 或 local（内置级不可写）`);
+  }
+  // 级别校验通过后再判权限，避免非法 --level 先撞权限门禁而掩盖真实错因
+  assertPermission(level === 'local' ? 'local' : 'agent');
+
+  const roots = skillRoots();
+  const dir = roots[level];
+  if (!dir) {
+    throw new Error(`无法定位 ${level} 级目录（Agent 级需要 EVOLCORE_AGENT_DIR 或 EVOLCORE_SELF_AID 环境变量）`);
+  }
+
+  // 校验技能存在（否则开关写了也没用）
+  const known = resolveAll().find(s => s.name === name);
+  if (!known) throw new Error(`技能不存在: ${name}`);
+
+  if (known.locked && level !== 'builtin') {
+    throw new Error(`「${name}」是内置 locked 技能，任何级别都关不掉`);
+  }
+
+  const file = writeSwitch(dir, name, { enabled });
+
+  const result = { name, level, enabled, file };
+  if (json) return result;
+  return [
+    `✅ ${enabled ? '已启用' : '已禁用'} ${name}（${level} 级）`,
+    `   写入: ${file}`,
+    '',
+    '约 2 秒后标记待更新，下一条消息处理时重建索引。',
+  ].join('\n');
+}
+
+export function cmdWhere({ json = false } = {}) {
+  const roots = skillRoots();
+  const info = {
+    builtin: roots.builtin,
+    local: roots.local,
+    agent: roots.agent,
+    deps: path.join(evolcoreHome(), 'skills', '.deps'),
+  };
+  if (json) return info;
+  return [
+    '技能三级根目录：',
+    `  内置级: ${info.builtin}`,
+    `  本机级: ${info.local}`,
+    `  Agent级: ${info.agent || '(未定位：缺少 EVOLCORE_AGENT_DIR / EVOLCORE_SELF_AID)'}`,
+    '',
+    `依赖目录: ${info.deps}`,
+  ].join('\n');
+}
+
+// ── 工具 ──────────────────────────────────────────────────────────────
+
+function extractZip(zipPath) {
+  const AdmZip = loadDep('adm-zip');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ec-skill-zip-'));
+  const zip = new AdmZip(zipPath);
+
+  // 防 zip-slip：条目路径不得逃出目标目录
+  for (const entry of zip.getEntries()) {
+    const dest = path.resolve(dir, entry.entryName);
+    if (!isInside(dest, dir) && dest !== path.resolve(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      throw new Error(`压缩包含越界路径，拒绝解压: ${entry.entryName}`);
+    }
+  }
+  zip.extractAllTo(dir, true);
+  return dir;
+}
+
+/** 压缩包里技能目录可能在任意深度（常见是顶层套一层同名目录） */
+function findSkillDirIn(root) {
+  const direct = path.join(root, 'SKILL.md');
+  if (fs.existsSync(direct)) return root;
+  const entries = fs.readdirSync(root, { withFileTypes: true }).filter(e => e.isDirectory());
+  if (entries.length === 1) {
+    const nested = path.join(root, entries[0].name);
+    if (fs.existsSync(path.join(nested, 'SKILL.md'))) return nested;
+  }
+  // 再宽一点：任意一层找到 SKILL.md
+  for (const e of entries) {
+    const nested = path.join(root, e.name);
+    if (fs.existsSync(path.join(nested, 'SKILL.md'))) return nested;
+  }
+  return null;
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) copyDir(s, d);
+    else if (entry.isSymbolicLink()) {
+      // 不跟随软链接，避免把外部内容带进来
+      continue;
+    } else fs.copyFileSync(s, d);
+  }
+}
+
+function isInside(child, parent) {
+  if (!parent) return false;
+  const rel = path.relative(path.resolve(parent), path.resolve(child));
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function samePath(a, b) {
+  if (!b) return false;
+  return path.resolve(a) === path.resolve(b);
+}

package/kits/skills/ec-skill/scripts/template/SKILL.md.tmpl

@@ -0,0 +1,30 @@
+---
+name: {{name}}
+description: >-
+  {{description}}
+---
+
+# {{name}}
+
+## 目标
+
+（一句话说清这个技能解决什么问题。）
+
+## 步骤
+
+1. 确认用户的需求落在本技能的适用范围内
+2. ……
+3. ……
+
+## 输出契约
+
+（这个技能产出什么、什么格式、写到哪。有确定格式就写死。）
+
+## 边界情况
+
+- 输入缺失时如何处理
+- 遇到不适用场景时如何退出
+
+## 参考资料
+
+（大块资料放 `references/`，在这里指出文件名。不要把它塞进本文件。）

package/kits/templates/decision/auto-mention.md

@@ -0,0 +1,25 @@
+# Auto Mention Decision Prompt
+
+每次模型判定前通过 mtime + size 检查本模板的变化，修改后下一次判定自动加载。
+以下四个二级章节必须保留且不能为空。加载失败时沿用当前 gate 上次成功加载的版本并告警；
+若尚无有效版本，则走现有的 mention-only 降级。失败结果不缓存，修复后会自动重试。
+
+## Instructions
+
+请结合 state 中提供的全部会话信息，判断 new_messages 整体应采用哪一种执行策略。state 中包含当前群会话历史对话、尚未完成处理的消息、本次新消息、当前处理状态以及适用的规则和资料。请综合这些信息判断本次新消息是否需要当前 Agent 介入，以及介入时机。只对本次 new_messages 统一选择一个 execution_policy；recent_messages 和 pending_messages 仅作为背景参考，不重新分类。判定时以消息内容、发送者 role 和是否明确要求当前 Agent 回应或行动为依据。role=owner/admin 是当前群的所有者/管理员：其在群内的发言默认应视为需要当前 Agent 关注，判 interrupt——不论语气是提问、追问、补充指示还是评述，也不要求它 @ 或点名当前 Agent。唯一的例外是：该发言内容明确是针对其他某个成员的一对一指示或对话、且与当前 Agent 无关，此时才可判 ignore。正文中出现 @ 到当前 Agent、或提到当前 Agent 的 AID 或显示名时，属于点名，应视为要求当前 Agent 回应，判 interrupt；若 @ 或提到的是其他成员，或当前 Agent 仅被他人在引述中转述提及，则不据此判 interrupt。
+
+确实不需要当前 Agent 回应或行动的消息不构成介入理由。典型情形是：纯粹发生在其他成员之间、且没有指向当前 Agent 的进度汇报、状态确认、讨论、澄清、评审与争辩。但判断时必须区分两种情形，不可一概而论：只要消息的指向是当前 Agent 或全体成员，就应视为需要当前 Agent 回应，即使它没有 @、没有点名，也不得因为前文是成员之间的往来就一并忽略。尤其要记住：owner/admin 在群内的发言默认判 interrupt，不要求它指向当前 Agent 或全体、也不要求它用提问或追问的语气——把 owner/admin 的发言判成 ignore 只有一个出口，就是该发言明确是针对其他某个成员的一对一指示或对话、且与当前 Agent 无关。此外，不要因为消息出现在当前 Agent 曾参与过的话题串内，就把纯粹发生在其他成员之间的往来当成与自己相关。
+
+若新消息承接当前 Agent 上一轮的发言或汇报，并据此给出后续追问、指令或分派，即使未直接 @ 或提及当前 Agent，也应视为要求当前 Agent 回应；其中明确排除当前 Agent 的部分不构成其处理理由，但其余仍需处理的后续任务不因此排除。
+
+## Interrupt Criteria
+
+需要当前 Agent 立即回应或行动的请求，包括：被 @、被点名，或正文提到当前 Agent 的 AID 或显示名；owner/admin 在群内的发言（默认视为需要当前 Agent 关注，唯一例外是它明确针对其他成员的一对一指示或对话、且与当前 Agent 无关）；承接当前 Agent 上一轮发言或汇报所给出的后续追问、指令或分派。
+
+## Defer Criteria
+
+可能需要当前 Agent 处理，但当前 Agent 正在处理其他任务且不紧急，可等待其完成后执行。
+
+## Ignore Criteria
+
+不需要当前 Agent 回应或行动。