// Skill Manager:发现、查看与执行技能。 // 依赖不由 core 安装:requirements.txt 与技能资产(install.sh)在 executor 启动前由 agent-executor-init // 一次性处理——镜像已带的包跳过,缺的装进 skills/deps,运行期经 executor 容器 env 的 PYTHONPATH 可见。 // 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录: // /SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。 // 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 input_args)。 // 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(front matter 声明 mcp_tool, // run 由 core 直接调 mcp.callTool,不经沙箱——凭证留在 core,模型只看到一行技能描述)。 const fs = require('fs'); const fsp = require('fs').promises; const path = require('path'); const { spawn } = require('child_process'); const YAML = require('yaml'); const log = require('../log'); const rexec = require('../remote-exec'); // 技能可声明 mcp_tool(front matter),run 时由 core 直接转发给 MCP;mcp.js 只依赖 ./log,不成环。 const mcp = require('../mcp'); class SkillNotFoundError extends Error { constructor(msg) { super(msg); this.name = 'SkillNotFoundError'; } } class SkillExecutionError extends Error { constructor(msg, code) { super(msg); this.name = 'SkillExecutionError'; this.code = code; } } // 技能根目录:优先 cfg.skills_root(config.yml 配置,所有任务共享);缺省取 workspace_root 的同级 skills 目录。 function skillsRoot(ctx) { if (ctx.cfg && ctx.cfg.skills_root) return ctx.cfg.skills_root; if (ctx.cfg && ctx.cfg.skills && ctx.cfg.skills.skills_root) return path.resolve(ctx.cfg.skills.skills_root); return path.resolve(ctx.cfg.workspace_root, '..', 'skills'); } function skillDir(ctx, skillName) { const name = String(skillName || '').trim(); if (!name) throw new SkillNotFoundError('技能名为空'); if (name.includes('/') || name.includes('..')) throw new SkillNotFoundError('非法技能名:' + name); return path.join(skillsRoot(ctx), name); } // 解析 SKILL.md 的 YAML Front Matter;无 Front Matter 返回 {}。 function parseFrontMatter(content) { const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(content); if (!m) return {}; try { return YAML.parse(m[1]) || {}; } catch (_) { return {}; } } // 提取描述:优先 Front Matter 的 description,回退为第一个非标题文本行。 function extractDescription(content) { const fm = parseFrontMatter(content); if (fm.description && String(fm.description).trim()) return String(fm.description).trim(); const line = content.split(/\r?\n/).map(l => l.trim()).find(l => l && !/^#/.test(l)); return line || '(无描述)'; } // ---------- 3.1 skill op=list ---------- async function listSkills(ctx) { const root = skillsRoot(ctx); if (!fs.existsSync(root)) { log.warn('skills', '技能根目录不存在:' + root); return []; } const out = []; const entries = await fsp.readdir(root, { withFileTypes: true }); for (const e of entries) { if (!e.isDirectory()) continue; const mdPath = path.join(root, e.name, 'SKILL.md'); if (!fs.existsSync(mdPath)) continue; let content; try { content = await fsp.readFile(mdPath, 'utf8'); } catch (_) { continue; } // frontmatter 可选 required: true —— 进 system prompt 时行首标 **required**(配合模板里的强制条款) // 可选 mcp_tool: —— 声明后端为 MCP 服务(run 不落沙箱),仅在声明时带该键 let required = false, mcpTool = ''; try { const fm = parseFrontMatter(content); required = fm.required === true; mcpTool = String(fm.mcp_tool || '').trim(); } catch (_) {} const item = { name: e.name, description: extractDescription(content), required: required }; if (mcpTool) item.mcp_tool = mcpTool; out.push(item); } out.sort((a, b) => a.name.localeCompare(b.name)); return out; } // ---------- system prompt 注入:可用技能列表 ---------- // 把技能列表格式化成 “## Available Skills” 段落(每行 `- [**required** ]名字: 描述`; // listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存; // 参数查 op=get,执行 op=run;描述如需实时复核仍可查 op=list)。 // 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后 // (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已装技能, // 省掉先 op=list 探索的往返。 function formatSkillListForPrompt(list) { if (!list || !list.length) return ''; const lines = list.map(s => { // 描述压成单行:YAML 块标量可能带换行,不能让它撞破列表结构 const desc = String(s.description || '').replace(/\s*\n\s*/g, ' ').trim(); return (s.required ? '- **required** ' : '- ') + s.name + (desc ? ': ' + desc : ''); }); return '## Available Skills\n' + lines.join('\n'); } // ---------- 3.2 skill op=get ---------- async function getSkillInfo(ctx, skillName) { const dir = skillDir(ctx, skillName); const mdPath = path.join(dir, 'SKILL.md'); if (!fs.existsSync(mdPath)) { throw new SkillNotFoundError('技能不存在或缺少 SKILL.md:' + skillName); } return fsp.readFile(mdPath, 'utf8'); } // ---------- 参数路径预处理 ---------- // 技能进程的工作目录是技能目录,而 Agent 习惯传相对会话任务目录的路径; // 执行前统一把路径样式的相对参数转成绝对路径,技能脚本无感知。 // 含路径分隔符,或以字母开头的扩展名结尾(排除 "1.5" 这类数字串误判)。 function looksLikePath(v) { return /[\\/]/.test(v) || /\.\D\w{0,5}$/.test(v); } function absolutizeValue(key, v, baseDir) { if (typeof v !== 'string' || !v.trim()) return v; const looksAbs = v.startsWith('/') || v.startsWith('\\') || /^[a-zA-Z]:[\\/]/.test(v); if (looksAbs) return v; const outputish = /out|dest|target|save/i.test(key); const exists = fs.existsSync(path.resolve(baseDir, v)); if (outputish || exists || looksLikePath(v)) return path.resolve(baseDir, v); return v; } function absolutizeArgs(inputArgs, baseDir) { const out = {}; for (const [k, v] of Object.entries(inputArgs || {})) out[k] = absolutizeValue(k, v, baseDir); return out; } // 按 input_schema 校验 input_args(仅校验 required 字段存在且非空)。 function validateArgs(fm, inputArgs, skillName) { const schema = fm && fm.input_schema; if (!schema || !Array.isArray(schema.required)) return; const missing = schema.required.filter(k => inputArgs[k] === undefined || inputArgs[k] === null || inputArgs[k] === ''); if (missing.length) { throw new SkillExecutionError('技能 ' + skillName + ' 缺少必填参数:' + missing.join(', '), 1); } } // 前台执行技能入口,带超时与取消支持;成功 resolve stdout,失败 reject SkillExecutionError。 // 配了 executor:入口命令拼成单条 shell 行(参数单引号转义,JSON payload 安全)交远端执行, // cwd 由调用方给出(op=run 传会话目录以命中 session 隔离与虚拟视图); // 技能依赖的 PYTHONPATH 由 executor 容器 env 提供,core 不感知依赖层。 function runEntry(ctx, entry, args, cwd, timeoutMs) { const cfg = ctx.cfg; if (cfg && rexec.isRemote(cfg)) { return rexec.run(cfg, { command: rexec.shellLine(entry, args), cwd, timeout_ms: timeoutMs, run: ctx.run, }).then(r => { const trimmed = r.out.replace(/\n+$/, '').trim(); if (r.killed_by === 'timeout') throw new SkillExecutionError('技能执行超时(' + timeoutMs + 'ms)已终止:\n' + trimmed, -1); if (r.killed_by === 'cancelled') throw new SkillExecutionError('技能执行被用户终止', -1); if (r.code === 0) return trimmed || '(无输出)'; throw new SkillExecutionError((trimmed || ('技能执行失败,退出码 ' + r.code)) + '\n[exit code: ' + r.code + ']', r.code); }); } return new Promise((resolve, reject) => { const child = spawn(entry, args, { cwd, env: process.env, detached: true }); if (ctx.run && ctx.run.procs) ctx.run.procs.add(child); let out = ''; let settled = false; const onData = d => { out += d.toString(); }; child.stdout.on('data', onData); child.stderr.on('data', onData); const timer = setTimeout(() => { if (settled) return; settled = true; clearInterval(cancelCheck); if (ctx.run && ctx.run.procs) ctx.run.procs.delete(child); try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { try { child.kill('SIGKILL'); } catch (__) {} } reject(new SkillExecutionError('技能执行超时(' + timeoutMs + 'ms)已终止:\n' + out.trim(), -1)); }, timeoutMs); const cancelCheck = setInterval(() => { if (ctx.run && ctx.run.cancelled && !settled) { settled = true; clearTimeout(timer); if (ctx.run && ctx.run.procs) ctx.run.procs.delete(child); try { process.kill(-child.pid, 'SIGKILL'); } catch (_) { try { child.kill('SIGKILL'); } catch (__) {} } reject(new SkillExecutionError('技能执行被用户终止', -1)); } }, 200); child.on('error', err => { if (settled) return; settled = true; clearTimeout(timer); clearInterval(cancelCheck); if (ctx.run && ctx.run.procs) ctx.run.procs.delete(child); reject(new SkillExecutionError('技能入口启动失败:' + err.message, -1)); }); child.on('close', code => { if (settled) return; settled = true; clearTimeout(timer); clearInterval(cancelCheck); if (ctx.run && ctx.run.procs) ctx.run.procs.delete(child); const trimmed = out.replace(/\n+$/, '').trim(); if (code === 0) resolve(trimmed || '(无输出)'); else reject(new SkillExecutionError((trimmed || ('技能执行失败,退出码 ' + code)) + '\n[exit code: ' + code + ']', code)); }); }); } // ---------- 3.3 skill op=run ---------- async function runSkill(ctx, skillName, inputArgs) { // 非对象参数会在 absolutizeArgs 的 Object.entries 里静默错位成垃圾键值(如字符串→索引对象),显式拦下。 if (inputArgs != null && (typeof inputArgs !== 'object' || Array.isArray(inputArgs))) { throw new SkillExecutionError('input_args 必须是对象(键值参数),收到:' + JSON.stringify(inputArgs).slice(0, 80), 1); } const dir = skillDir(ctx, skillName); if (!fs.existsSync(dir)) throw new SkillNotFoundError('技能不存在:' + skillName); const mdPath = path.join(dir, 'SKILL.md'); if (!fs.existsSync(mdPath)) throw new SkillNotFoundError('技能缺少 SKILL.md:' + skillName); let fm = {}; try { fm = parseFrontMatter(await fsp.readFile(mdPath, 'utf8')); } catch (_) {} // MCP 后端技能(front matter 声明 mcp_tool):run 不落沙箱,由 core 直接转发给 MCP 服务。 // core 用 cfg.mcp_servers[].headers 里的凭证调服务,技能进程根本不参与——这是唯一 // 既能让模型只看到一行技能描述、又能让 key 不出 core 的路径(executor 的 env 白名单 // 会按名字丢掉 *KEY/*TOKEN,沙箱里既拿不到也不该拿到)。 // 必须在 absolutizeArgs 之前分流:它把「像路径」的参数改写成会话目录下的绝对路径, // 而 URL(含 '/')与含斜杠的 prompt 都会中招。 // 不跑 validateArgs:MCP 工具的参数是 op 相关的(如 op=create 才要 prompt), // 静态 required 列表会误伤 op=get。 if (fm.mcp_tool) { const tool = String(fm.mcp_tool).trim(); if (!mcp.hasTool(tool)) { throw new SkillExecutionError('技能 ' + skillName + ' 的 MCP 后端不可用:' + tool + '(检查 mcp_servers 是否含该服务,且 mode 不为 disable)', 1); } log.info('skills', '执行 ' + skillName + ':mcp_tool=' + tool); return mcp.callTool(tool, inputArgs || {}, ctx); } // 以下是脚本后端(run.py / run.sh):先把相对路径参数按会话任务目录转成绝对路径(缺任务目录时退回进程当前目录)。 const args = absolutizeArgs(inputArgs || {}, ctx.taskDir || process.cwd()); const payload = JSON.stringify(args); validateArgs(fm, args, skillName); let entry, cmdArgs; const runPy = path.join(dir, 'run.py'); const runSh = path.join(dir, 'run.sh'); if (fs.existsSync(runPy)) { // 直接走系统 python3(技能依赖由 executor 容器 env 的 PYTHONPATH 提供)。 // 入口一律用绝对路径:远端 cwd 是会话目录,相对的 'run.py' 会找不到。 entry = 'python3'; cmdArgs = [runPy, payload]; } else if (fs.existsSync(runSh)) { entry = 'bash'; cmdArgs = [runSh, payload]; } else { throw new SkillExecutionError('技能 ' + skillName + ' 缺少入口 run.py 或 run.sh(也未声明 mcp_tool)', 1); } // cwd:远端取会话目录(executor 侧命中 session 隔离,技能看到的 /workspace/tasks/ // 与 core 侧是同一份数据,absolutizeArgs 产出的绝对路径因此有效);缺 taskDir 时退回 // 技能目录(退化为旧行为)。本地无隔离诉求,仍以技能目录为 cwd。 const execCwd = rexec.isRemote(ctx.cfg) ? (ctx.taskDir || dir) : dir; const timeoutMs = (ctx.cfg && ctx.cfg.skills && ctx.cfg.skills.timeout_ms) || 120000; log.info('skills', '执行 ' + skillName + ':' + entry + ' ' + cmdArgs.join(' ') + '(cwd=' + execCwd + ')'); return runEntry(ctx, entry, cmdArgs, execCwd, timeoutMs); } module.exports = { listSkills, getSkillInfo, runSkill, skillsRoot, parseFrontMatter, extractDescription, formatSkillListForPrompt };