293 lines
14 KiB
JavaScript
293 lines
14 KiB
JavaScript
// Skill Manager:发现、查看与执行技能。
|
||
// 依赖不由 core 安装:requirements.txt 与技能资产(install.sh)在 executor 启动前由 agent-executor-init
|
||
// 一次性处理——镜像已带的包跳过,缺的装进 skills/deps,运行期经 executor 容器 env 的 PYTHONPATH 可见。
|
||
// 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录:
|
||
// <skill>/SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。
|
||
// 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 args)。
|
||
// 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(core 直接 mcp.callTool 转发,
|
||
// 不经沙箱——凭证留在 core)。MCP 技能不落目录:服务配成 mode=skill 时由平台自动暴露,
|
||
// 参数契约直接取注册表里的原始 input_schema。
|
||
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');
|
||
// mode=skill 的 MCP 工具在 get/run 时由 core 直接转发;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 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**(配合模板里的强制条款)
|
||
let required = false;
|
||
try {
|
||
required = parseFrontMatter(content).required === true;
|
||
} catch (_) {}
|
||
out.push({ name: e.name, description: extractDescription(content), required: required });
|
||
}
|
||
out.sort((a, b) => a.name.localeCompare(b.name));
|
||
return out;
|
||
}
|
||
|
||
// ---------- MCP 技能(mode=skill)----------
|
||
// mode=skill 的服务:工具不进 tools 数组,而是自动成为技能。既省掉每轮的 schema 开销,
|
||
// 又不用在 skills_root 里建目录、手抄一份参数说明——get 直接返回注册表里的原始 input_schema。
|
||
// 目录技能优先:同名时目录技能胜出并打 warn。手写包装可以遮住自动版,迁移期也不会撞车。
|
||
|
||
// MCP 的 description 常是多段文本;清单里只取第一行,完整内容留给 get。
|
||
function firstLine(s) {
|
||
const line = String(s == null ? '' : s).split(/\r?\n/).map(l => l.trim()).find(Boolean);
|
||
return line || '(无描述)';
|
||
}
|
||
|
||
// 模型可见的技能全集 = 目录技能 + mode=skill 的 MCP 工具。
|
||
// 设置页的技能 API 只用 listSkills(它按目录增删改),不要混用这个函数。
|
||
async function listCallableSkills(ctx) {
|
||
const dir = await listSkills(ctx);
|
||
const taken = new Set(dir.map(s => s.name));
|
||
const out = dir.slice();
|
||
for (const t of mcp.skillTools()) {
|
||
if (taken.has(t.name)) {
|
||
log.warn('skills', 'MCP 工具 ' + t.name + ' 与目录技能同名,按目录技能处理(mode=skill 的这份被遮蔽)');
|
||
continue;
|
||
}
|
||
out.push({ name: t.name, description: firstLine(t.description), required: false });
|
||
}
|
||
out.sort((a, b) => a.name.localeCompare(b.name));
|
||
return out;
|
||
}
|
||
|
||
// 把技能列表格式化成 “## Available Skills” 段落(每行 `- [**required** ]名字: 描述`;
|
||
// listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存;
|
||
// 参数查 get,执行 run;描述如需实时复核仍可查 list)。
|
||
// 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后
|
||
// (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已装技能,
|
||
// 省掉先 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 get ----------
|
||
async function getSkillInfo(ctx, skillName) {
|
||
const dir = skillDir(ctx, skillName);
|
||
const mdPath = path.join(dir, 'SKILL.md');
|
||
if (fs.existsSync(mdPath)) return fsp.readFile(mdPath, 'utf8');
|
||
// mode=skill 的 MCP 技能没有目录:直接返回注册表里的原始契约(description + input_schema),
|
||
// 模型看到的就是服务端实际声明的参数,不存在手抄副本漂移的问题。
|
||
const t = mcp.getSkillTool(skillName);
|
||
if (t) return JSON.stringify({ name: t.name, description: t.description, input_schema: t.parameters }, null, 2);
|
||
throw new SkillNotFoundError('技能不存在或缺少 SKILL.md:' + skillName);
|
||
}
|
||
|
||
// ---------- 参数路径预处理 ----------
|
||
// 技能进程的工作目录是技能目录,而 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 校验技能参数(仅校验 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 由调用方给出(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 run ----------
|
||
async function runSkill(ctx, skillName, inputArgs) {
|
||
// 非对象参数会在 absolutizeArgs 的 Object.entries 里静默错位成垃圾键值(如字符串→索引对象),显式拦下。
|
||
if (inputArgs != null && (typeof inputArgs !== 'object' || Array.isArray(inputArgs))) {
|
||
throw new SkillExecutionError('技能参数必须是对象(键值参数),收到:' + JSON.stringify(inputArgs).slice(0, 80), 1);
|
||
}
|
||
const dir = skillDir(ctx, skillName);
|
||
if (!fs.existsSync(dir)) {
|
||
// mode=skill 的 MCP 技能:直接转发。同样不做 absolutizeArgs——URL 与含 '/' 的 prompt
|
||
// 会被当成路径改写坏;也不做 validateArgs,参数与 MCP 工具自己的 op 相关。
|
||
const t = mcp.getSkillTool(skillName);
|
||
if (t) {
|
||
log.info('skills', '执行 MCP 技能 ' + t.name + ' → ' + t.server + '/' + t.tool);
|
||
return mcp.callTool(t.name, inputArgs || {}, ctx);
|
||
}
|
||
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 (_) {}
|
||
|
||
// 以下是脚本后端(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', 1);
|
||
}
|
||
|
||
// cwd 一律取会话任务目录(技能契约,见 skills/README §6:技能按 cwd 读写会话数据,
|
||
// data-page 这类会往 cwd 下写 .app/)。旧代码在「无 executor」分支退回技能目录,
|
||
// 等于假设线上一定走远端;本地桌面形态(本机 spawn)下会把所有按 cwd 干活的技能打歪。
|
||
const execCwd = ctx.taskDir || 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, listCallableSkills, getSkillInfo, runSkill, skillsRoot, parseFrontMatter, extractDescription, formatSkillListForPrompt };
|