refactor(skill): 参数改为动词作键,去掉 op/name/input_args
形状:{"list":"all"} / {"get":"<名>"} / {"run":"<名>","args":{...}},三者恰好给一个。
- 互斥无法用 required 表达,校验与报错回显放在 toolSkill
- list 取值是字符串范围而非布尔,为将来的技能分类留扩展位;今天只认 all
- list/get 带非空 args 一律报错,不静默丢弃
- 旧形状 {op,name,input_args} 仍由 toolSkill 兜底翻译,只为兼容存量技能文档,不再对外文档化
- README/AGENTS/skills 文档与内置技能调用示例同步为新形态
This commit is contained in:
@@ -337,29 +337,25 @@
|
||||
"type": "function",
|
||||
"function": {
|
||||
"name": "skill",
|
||||
"description": "Use the skills installed on this server. A skill is a directory under the skill root whose SKILL.md defines its purpose and input_schema.\n\nop=list No arguments.\nop=get Requires name.\nop=run Requires name; input_args optional (default {}).\n\nop=list: lists all installed skills with a one-line description each, read live from the skill root; use it to choose among skills or to confirm what is installed. An empty skill set returns an empty list — that is not an error.\nop=get: returns the full raw SKILL.md (front matter included): purpose, input_schema, and usage notes. Call it before op=run with a skill you have not used in this conversation. A nonexistent skill returns an error.\nop=run: executes the skill with input_args validated against its input_schema (a validation error names the missing fields). The entry script receives a JSON string as its only CLI argument, so input_args must be a JSON object.\n- Returns the skill's combined stdout+stderr as plain text after it exits; exit 0 with no output yields '(无输出)'. A non-zero exit raises an error containing the output and [exit code: N].\n- Direct output files via arguments: relative paths in input_args are resolved against the session working directory; do not rely on the skill's cwd.\n- Default timeout 120 seconds: the process group is killed and the error includes partial output collected so far (a timeout is not a skill failure).",
|
||||
"description": "Run or inspect the skills installed on this server. A skill is a directory under the skill root whose SKILL.md defines its purpose and input_schema.\n\nPass EXACTLY ONE verb key:\n{\"list\":\"all\"} List every installed skill with a one-line description, read live from the skill root; an empty list is not an error.\n{\"get\":\"<name>\"} Return the skill's full raw SKILL.md (front matter included): purpose, input_schema and usage notes. Call it before run for a skill you have not used in this conversation.\n{\"run\":\"<name>\",\"args\":{...}} Execute the skill; args are key/value pairs matching its input_schema, and may be omitted for skills that take none.\n\nrun returns the skill's combined stdout+stderr as plain text after it exits (exit 0 with no output yields '(无输出)'); a non-zero exit raises an error containing the output and [exit code: N]. Relative paths in args are resolved against the session working directory, so pass output paths explicitly and never rely on the skill's cwd. Default timeout 120 seconds: the process group is killed and the error includes partial output collected so far (a timeout is not a skill failure).",
|
||||
"parameters": {
|
||||
"type": "object",
|
||||
"required": [
|
||||
"op"
|
||||
],
|
||||
"properties": {
|
||||
"op": {
|
||||
"list": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"list",
|
||||
"get",
|
||||
"run"
|
||||
],
|
||||
"description": "Operation to perform on skills."
|
||||
"description": "Scope of the listing. The only scope today is \"all\" (every installed skill)."
|
||||
},
|
||||
"name": {
|
||||
"get": {
|
||||
"type": "string",
|
||||
"description": "Name of the skill (subdirectory name under the skill root directory). Required with op=get and op=run."
|
||||
"description": "Skill name (subdirectory name under the skill root): return its SKILL.md."
|
||||
},
|
||||
"input_args": {
|
||||
"run": {
|
||||
"type": "string",
|
||||
"description": "Skill name: execute it with args."
|
||||
},
|
||||
"args": {
|
||||
"type": "object",
|
||||
"description": "Dictionary of input arguments for the skill. Keys and values should match the skill's input_schema (call op=get first if unsure). Example: {\"input\": \"file.md\", \"output\": \"out.pdf\"}. Used only with op=run; omit it for skills that take no arguments."
|
||||
"description": "Only with run: the skill's input arguments, e.g. {\"input\": \"file.md\", \"output\": \"out.pdf\"}. Omit it for skills that take no arguments."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1498,11 +1498,16 @@ function toolDb(ctx, args) {
|
||||
}
|
||||
}
|
||||
|
||||
// skill:技能三件套(list_skills/get_skill_info/run_skill)合并后的单工具(op 分派)。
|
||||
// 同一标识空间(name)+ 同一生命周期(live 扫目录,无常驻状态可增删)→ 合并,
|
||||
// 依据 docs/tool-design.md §一;技能不是「无持久状态」的动作,run 不必单独成工具。
|
||||
// input_args 仅 op=run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由
|
||||
// 各技能 input_schema 校验点名报错(工具层再 gate 一层是双重门槛,无益)。
|
||||
// skill:技能三件套(list/get/run)合并后的单工具(依据 docs/tool-design.md §一)。
|
||||
// 参数形状是「动词作键、技能名作值」,三者恰好给一个:
|
||||
// {list:"all"} / {get:"<名>"} / {run:"<名>", args:{...}}
|
||||
// list 的值是范围而非布尔:将来技能分类落地时直接扩成 {list:"<分类>"},调用形状不变,
|
||||
// 模型不用学第二套写法。今天只认 "all" 且报错点名——静默返回全部会让错拼的分类名
|
||||
// 看起来「能用」,将来接分类时更难排查。
|
||||
// args 仅 run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由各技能 input_schema
|
||||
// 校验点名报错(工具层再 gate 一层是双重门槛,无益)。
|
||||
// 旧形状 {op, name, input_args} 仍接受:存量技能文档的调用示例里写的是它,模型 get 到
|
||||
// 旧示例就会照着发;仅作兼容兜底,不再对外文档化(文档只体现新形状)。
|
||||
// visit_url(front matter 可选):页面产物类技能声明访问路径模板,run 成功后在本层拼
|
||||
// public_link.base_url(与 mint_public_link 同源)追加完整「访问地址」——技能进程跑在
|
||||
// executor 隔离视图里不知道公网前缀,AI 拿到相对路径就会原样转给用户,而相对路径打不开。
|
||||
@@ -1524,25 +1529,69 @@ async function runSkillWithVisit(ctx, name, inputArgs) {
|
||||
: rel + '(站内路径:public_link.base_url 未配置,拼不出公网前缀)');
|
||||
}
|
||||
|
||||
async function toolSkill(ctx, args) {
|
||||
const op = String(args.op || '').trim().toLowerCase();
|
||||
const name = String(args.name || '').trim();
|
||||
const SKILL_USAGE = 'skill 用法:{"list":"all"} / {"get":"<技能名>"} / {"run":"<技能名>","args":{...}},三者恰好给一个';
|
||||
|
||||
// 技能名必须是单 token:它要原样塞进 {run:"<名>"} 的值里,空格与等号会让日志与
|
||||
// 报错里的表达产生歧义('/' 与 '..' 由 skills.skillDir 拦下)。
|
||||
function skillNameArg(value, verb) {
|
||||
if (typeof value !== 'string' || !value.trim()) {
|
||||
throw new Error('skill ' + verb + ' 需要一个技能名字符串,收到:' + JSON.stringify(value).slice(0, 60) + '。' + SKILL_USAGE);
|
||||
}
|
||||
const name = value.trim();
|
||||
if (/[\s=]/.test(name)) throw new Error('技能名不能含空格或等号:"' + name + '"');
|
||||
return name;
|
||||
}
|
||||
|
||||
// list/get 带非空 args 一律报错而不是静默丢弃:否则模型会以为参数生效了。
|
||||
function rejectSkillArgs(a, verb) {
|
||||
if (!a.args || typeof a.args !== 'object' || !Object.keys(a.args).length) return;
|
||||
throw new Error(verb + ' 不接受 args,只有 run 才带参数。' + SKILL_USAGE);
|
||||
}
|
||||
|
||||
// 旧形状 {op, name, input_args} 的等价翻译(兼容存量技能文档,见上方注释)。
|
||||
async function legacyToolSkill(ctx, a) {
|
||||
const op = String(a.op == null ? '' : a.op).trim().toLowerCase();
|
||||
const name = String(a.name == null ? '' : a.name).trim();
|
||||
switch (op) {
|
||||
case 'list':
|
||||
return JSON.stringify(await skills.listSkills(ctx), null, 2);
|
||||
case 'get': {
|
||||
if (!name) throw new Error('op=get 缺少必填参数 name');
|
||||
case 'get':
|
||||
if (!name) throw new Error('op=get 缺少技能名。' + SKILL_USAGE);
|
||||
return skills.getSkillInfo(ctx, name);
|
||||
}
|
||||
case 'run': {
|
||||
if (!name) throw new Error('op=run 缺少必填参数 name');
|
||||
return runSkillWithVisit(ctx, name, args.input_args);
|
||||
}
|
||||
case 'run':
|
||||
if (!name) throw new Error('op=run 缺少技能名。' + SKILL_USAGE);
|
||||
return runSkillWithVisit(ctx, name, a.input_args);
|
||||
default:
|
||||
throw new Error('未知的 op:"' + op + '"。可用:list / get(需 name)/ run(需 name,input_args 可选)');
|
||||
throw new Error('未知的 op:"' + op + '"。' + SKILL_USAGE);
|
||||
}
|
||||
}
|
||||
|
||||
async function toolSkill(ctx, args) {
|
||||
const a = args || {};
|
||||
const verbs = ['list', 'get', 'run'].filter(k => a[k] !== undefined && a[k] !== null && a[k] !== false);
|
||||
if (!verbs.length) {
|
||||
// 三个动词键都没给时才回落到旧形状:两种都给时以新形状为准。
|
||||
if (a.op !== undefined || a.name !== undefined || a.input_args !== undefined) return legacyToolSkill(ctx, a);
|
||||
throw new Error(SKILL_USAGE);
|
||||
}
|
||||
if (verbs.length > 1) {
|
||||
throw new Error('skill 一次只能给一个动词键,收到 ' + verbs.join(' + ') + '。' + SKILL_USAGE);
|
||||
}
|
||||
const verb = verbs[0];
|
||||
if (verb === 'list') {
|
||||
const scope = String(a.list).trim().toLowerCase();
|
||||
if (scope !== 'all') throw new Error('list 目前只支持 "all"(技能分类尚未提供),收到:"' + scope + '"');
|
||||
rejectSkillArgs(a, 'list');
|
||||
return JSON.stringify(await skills.listSkills(ctx), null, 2);
|
||||
}
|
||||
const name = skillNameArg(a[verb], verb);
|
||||
if (verb === 'get') {
|
||||
rejectSkillArgs(a, 'get');
|
||||
return skills.getSkillInfo(ctx, name);
|
||||
}
|
||||
return runSkillWithVisit(ctx, name, a.args);
|
||||
}
|
||||
|
||||
// lab:全工具统一入口(元工具,tools 数组收缩到 1 个仍可达内置 + MCP 全部能力)。
|
||||
// args 为自由对象——目标 schema 定义期不可知(docs/tool-design.md §三 的合法例外),
|
||||
// 条件校验归内层 handler;错误冒泡不包装(只有一层)。help 是伪工具:不进 HANDLERS,
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
// 一次性处理——镜像已带的包跳过,缺的装进 skills/deps,运行期经 executor 容器 env 的 PYTHONPATH 可见。
|
||||
// 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录:
|
||||
// <skill>/SKILL.md(必须)、run.py | run.sh(入口)、requirements.txt、install.sh(可选)。
|
||||
// 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 input_args)。
|
||||
// 入口脚本约定接收一个 JSON 字符串作为唯一命令行参数(含全部 args)。
|
||||
// 后端两种:脚本(run.py/run.sh,落 executor 沙箱执行)与 MCP(front matter 声明 mcp_tool,
|
||||
// run 由 core 直接调 mcp.callTool,不经沙箱——凭证留在 core,模型只看到一行技能描述)。
|
||||
const fs = require('fs');
|
||||
@@ -52,7 +52,7 @@ function extractDescription(content) {
|
||||
return line || '(无描述)';
|
||||
}
|
||||
|
||||
// ---------- 3.1 skill op=list ----------
|
||||
// ---------- 3.1 skill list ----------
|
||||
async function listSkills(ctx) {
|
||||
const root = skillsRoot(ctx);
|
||||
if (!fs.existsSync(root)) {
|
||||
@@ -86,10 +86,10 @@ async function listSkills(ctx) {
|
||||
// ---------- system prompt 注入:可用技能列表 ----------
|
||||
// 把技能列表格式化成 “## Available Skills” 段落(每行 `- [**required** ]名字: 描述`;
|
||||
// listSkills 已按名字 localeCompare 排序,行序恒定,不破坏前缀缓存;
|
||||
// 参数查 op=get,执行 op=run;描述如需实时复核仍可查 op=list)。
|
||||
// 参数查 get,执行 run;描述如需实时复核仍可查 list)。
|
||||
// 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后
|
||||
// (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已装技能,
|
||||
// 省掉先 op=list 探索的往返。
|
||||
// 省掉先 list 探索的往返。
|
||||
function formatSkillListForPrompt(list) {
|
||||
if (!list || !list.length) return '';
|
||||
const lines = list.map(s => {
|
||||
@@ -100,7 +100,7 @@ function formatSkillListForPrompt(list) {
|
||||
return '## Available Skills\n' + lines.join('\n');
|
||||
}
|
||||
|
||||
// ---------- 3.2 skill op=get ----------
|
||||
// ---------- 3.2 skill get ----------
|
||||
async function getSkillInfo(ctx, skillName) {
|
||||
const dir = skillDir(ctx, skillName);
|
||||
const mdPath = path.join(dir, 'SKILL.md');
|
||||
@@ -134,7 +134,7 @@ function absolutizeArgs(inputArgs, baseDir) {
|
||||
return out;
|
||||
}
|
||||
|
||||
// 按 input_schema 校验 input_args(仅校验 required 字段存在且非空)。
|
||||
// 按 input_schema 校验技能参数(仅校验 required 字段存在且非空)。
|
||||
function validateArgs(fm, inputArgs, skillName) {
|
||||
const schema = fm && fm.input_schema;
|
||||
if (!schema || !Array.isArray(schema.required)) return;
|
||||
@@ -146,7 +146,7 @@ function validateArgs(fm, inputArgs, skillName) {
|
||||
|
||||
// 前台执行技能入口,带超时与取消支持;成功 resolve stdout,失败 reject SkillExecutionError。
|
||||
// 配了 executor:入口命令拼成单条 shell 行(参数单引号转义,JSON payload 安全)交远端执行,
|
||||
// cwd 由调用方给出(op=run 传会话目录以命中 session 隔离与虚拟视图);
|
||||
// cwd 由调用方给出(run 传会话目录以命中 session 隔离与虚拟视图);
|
||||
// 技能依赖的 PYTHONPATH 由 executor 容器 env 提供,core 不感知依赖层。
|
||||
function runEntry(ctx, entry, args, cwd, timeoutMs) {
|
||||
const cfg = ctx.cfg;
|
||||
@@ -210,11 +210,11 @@ function runEntry(ctx, entry, args, cwd, timeoutMs) {
|
||||
});
|
||||
}
|
||||
|
||||
// ---------- 3.3 skill op=run ----------
|
||||
// ---------- 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('input_args 必须是对象(键值参数),收到:' + JSON.stringify(inputArgs).slice(0, 80), 1);
|
||||
throw new SkillExecutionError('技能参数必须是对象(键值参数),收到:' + JSON.stringify(inputArgs).slice(0, 80), 1);
|
||||
}
|
||||
const dir = skillDir(ctx, skillName);
|
||||
if (!fs.existsSync(dir)) throw new SkillNotFoundError('技能不存在:' + skillName);
|
||||
|
||||
Reference in New Issue
Block a user