Files
agent/app/server/tools/skills.js
kicer 29be7bd9d7 feat(shell): 抽出执行后端,Windows 用 git-bash / busybox 跑命令
POSIX 上 spawn('/bin/sh') + kill(-pid) 是刻意选的最强约束:/bin/sh 固定
(不读 $SHELL,否则用户把 shell 设成 fish 后模型写的 POSIX 语法全废),
进程组让「停止」能一次带走孙进程。Windows 这三样都没有,同一个写法从
「有效」变成「静默失效」,detached 还会多弹一个控制台。

把三种能力收敛到 app/server/shell.js(resolve / spawnShell / killTree),
terminal、技能、engine 的取消都改走它,上层不再出现 process.platform 分支:

  - POSIX 分支逐字节不变,Linux / macOS / OpenWrt 行为与拆分前一致
  - Windows 依次探测 git-bash、busybox-w32,都没有就明确报错,不静默退到
    cmd.exe——cmd 的语法与模型写的 POSIX 差太远,降级只会让它反复试错
  - killTree 在 Windows 走 taskkill /T:child.kill() 只杀 shell 本身,
    模型起的 node/python/ffmpeg 孙进程会留下来继续占端口
  - detached 在 Windows 关闭(会新建控制台,且让子进程脱离 taskkill 的父子树)
  - 三级覆盖:AGENT_SHELL > config.terminal.shell > 自动探测;
    AGENT_SHELL_ARGS 可改参数模板(bash 想读 rc 时写 -lc)

新增 local/start-win.mjs:start.sh 那 1100 多行 bash 靠 lsof / pgrep /
readlink -f / nohup / setsid / 进程组信号,Windows 一个都没有。启动器这层
本来就只做进程管理,用 Node 重写更省事;业务代码一行都不分平台。首次运行
自动把 busybox-w32(单文件 600KB)下到 local/bin/,生成 local/config.win.yml,
之后不再覆盖。

验证(macOS 实跑):普通命令 / 超时 704ms / 取消 403ms 三条路径正常,进程组
3 个进程 kill 后归 0,procs 无残留;真实 core 启动 health 200,日志多一行
terminal=/bin/sh -c ← default。win32 分支只做了逻辑模拟(无 shell 的报错
文案、有 busybox 时解析为 busybox sh -c),真机待验。

未做:Windows 启动器未拉起四个同栈 MCP 与 office 预览网关,配置里
mcp_servers 暂为空,terminal / 文件工具 / 技能不受影响。
2026-11-19 11:27:17 +08:00

295 lines
14 KiB
JavaScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// 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');
const shell = require('../shell'); // 本地 spawn 技能时的进程树 kill(平台差异只在 shell.js)
// 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) => {
// windowsHide:Windows 上 detached 之外的第二道保险,避免弹控制台;POSIX 忽略该选项。
const child = spawn(entry, args, { cwd, env: process.env, detached: true, windowsHide: 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);
shell.killTree(child);
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);
shell.killTree(child);
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 };