fix(skill): 参数改回 op/name/args 的扁平结构,压缩描述并修正调用示例

This commit is contained in:
2026-10-21 20:53:33 +08:00
parent 89c673864f
commit 29e46692fc
11 changed files with 65 additions and 103 deletions
+6 -5
View File
@@ -173,11 +173,12 @@ POST /api/sessions/:id/messages
- `checkToolArgs` + `unwrapToolArgs`:前者做结构性预检并生成 `errAck`,后者按 schema 逐层剥掉
弱模型多包的信封。两者都是纯函数并已导出,便于回归验证。
- 技能(`tools/skills.js`):`SKILL.md` front matter 提供 `description`/`input_schema`。
工具参数是「动词作键」:`{"list":"all"}` / `{"get":"<名>"}` / `{"run":"<名>","args":{...}}`,
三者恰好给一个(无法用 `required` 表达,校验在 `toolSkill` 里做)。`input_schema.required` 在
`run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径(远端 cwd 是会话目录)。
配了 executor 就走 `remote-exec`,否则本地 `spawn`。旧形状 `{op, name, input_args}` 仅由
`toolSkill` 兜底翻译(存量技能文档里还写着它),不再对外文档化。
工具参数是扁平的 `{op, name, args}`:`op` 必填且三选一(`list`/`get`/`run`),`name` 供
get/run 指认技能,`args` 仅 run 用;条件必填写不进 schema,由 `toolSkill` 校验并点名。
`toolSkill` 在入口把旧字段名 `input_args` 归一化成 `args`,之后只走一条分派路径
(曾有两条路径,其中一条只读 `input_args`,会静默丢参)。
`input_schema.required` 在 `run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径
(远端 cwd 是会话目录)。配了 executor 就走 `remote-exec`,否则本地 `spawn`。
模型可见的技能清单是 `listCallableSkills`(目录技能 + `mode=skill` 的 MCP 工具,同名时目录胜出);
设置页的技能 API 仍只用 `listSkills`(按目录增删改),两者不要混用。
mode=skill 的 MCP 技能在 `runSkill` 里位于 `absolutizeArgs` **之前**:直接 `mcp.callTool` 转发
+1 -1
View File
@@ -77,7 +77,7 @@ function absInSkill(dir, rel) {
// 技能发生任何变更(创建/重命名/删除/文件增删改都经过本模块)后,
// 重建 system prompt 的 “可用技能” 段落(llm.setSkillListText):
// 模型立即感知新技能或改名,无需重启。fire-and-forget:扫描失败不影响 API 响应,
// skill {"list":"all"} 仍是实时兜底。
// skill op=list 仍是实时兜底。
function refreshSkillPrompt() {
listCallableSkills({ cfg: engine.getConfig() })
.then(list => llm.setSkillListText(formatSkillListForPrompt(list)))
+2 -2
View File
@@ -178,8 +178,8 @@ function dumpPromptBundle() {
// 启动时先发现各 MCP 服务的工具(单个服务失败只警告,不阻止启动),
// 并对技能列表做快照(注入 system prompt,见 llm.setSkillListText),完成后开始监听。
mcp.init(cfg).then(async () => {
// 技能列表快照:模型直接感知已有技能,免先 {"list":"all"} 探索;
// 此处失败不阻塞启动,{"list":"all"} 仍可做实时兜底。
// 技能列表快照:模型直接感知已有技能,免先 op=list 探索;
// 此处失败不阻塞启动,op=list 仍可做实时兜底。
try {
const list = await skills.listCallableSkills({ cfg });
llm.setSkillListText(skills.formatSkillListForPrompt(list));
+8 -10
View File
@@ -337,25 +337,23 @@
"type": "function",
"function": {
"name": "skill",
"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).",
"description": "Run or inspect the skills installed on this server. Each skill describes its purpose and input_schema.\n\n{\"op\":\"list\"} list every skill with a one-line description\n{\"op\":\"get\",\"name\":\"<skill>\"} return the skill's full details; call it before the first run\n{\"op\":\"run\",\"name\":\"<skill>\",\"args\":{...}} execute it; args follow its input_schema\n\nop is required. op=get and op=run require name. Put skill arguments inside args, never at the top level.",
"parameters": {
"type": "object",
"required": ["op"],
"properties": {
"list": {
"op": {
"type": "string",
"description": "Scope of the listing. The only scope today is \"all\" (every installed skill)."
"enum": ["list", "get", "run"],
"description": "Operation to perform on skills."
},
"get": {
"name": {
"type": "string",
"description": "Skill name (subdirectory name under the skill root): return its SKILL.md."
},
"run": {
"type": "string",
"description": "Skill name: execute it with args."
"description": "Skill name. Required with op=get and op=run."
},
"args": {
"type": "object",
"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."
"description": "Only with op=run: the skill's input arguments, e.g. {\"input\":\"a.md\",\"output\":\"b.pdf\"}. Omit for skills that take no arguments."
}
}
}
+30 -66
View File
@@ -1498,18 +1498,14 @@ function toolDb(ctx, args) {
}
}
// skill:技能三件套(list/get/run)合并后的单工具(依据 docs/tool-design.md §一)。
// 参数形状是「动词作键、技能名作值」,三者恰好给一个:
// {list:"all"} / {get:"<名>"} / {run:"<名>", args:{...}}
// list 的值是范围而非布尔:将来技能分类落地时直接扩成 {list:"<分类>"},调用形状不变,
// 模型不用学第二套写法。今天只认 "all" 且报错点名——静默返回全部会让错拼的分类名
// 看起来「能用」,将来接分类时更难排查。
// {list:"all"} 的清单 = 目录技能 + mode=skill 的 MCP 工具;get/run 对两者一视同仁:
// 目录技能读 SKILL.md,MCP 技能直接回注册表里的原始 input_schema。
// args 仅 run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由各技能 input_schema
// 校验点名报错(工具层再 gate 一层是双重门槛,无益)。
// 旧形状 {op, name, input_args} 仍接受:存量技能文档的调用示例里写的是它,模型 get 到
// 旧示例就会照着发;仅作兼容兜底,不再对外文档化(文档只体现新形状)。
// skill:技能三件套(list/get/run)合并后的单工具(依据 docs/tool-design.md §一/§二/§三)。
// 扁平参数:op 是唯一必填的开关,name 供 get/run 指认技能,args 仅 run 用;条件必填写不进
// schema,由 toolSkill 校验并在报错里点名(§四/§五)。
// 旧字段名 input_args 在入口归一化成 args(存量技能文档里仍写着它),之后只走一条分派路径——
// 曾有两条执行路径,其中一条只读 input_args,{op:"run", args:{...}} 的参数会被静默丢弃。
// 上一版「动词作键」不再兼容:schema 的 required:["op"] 会在 checkToolArgs 阶段先拦下,
// 留着分支只会是死代码(lab 直调除外,不值得为它多一条路径)。
// op=list 的清单取 listCallableSkills:目录技能 + mode=skill 的 MCP 工具;get/run 对两者一视同仁。
// visit_url(front matter 可选):页面产物类技能声明访问路径模板,run 成功后在本层拼
// public_link.base_url(与 mint_public_link 同源)追加完整「访问地址」——技能进程跑在
// executor 隔离视图里不知道公网前缀,AI 拿到相对路径就会原样转给用户,而相对路径打不开。
@@ -1531,67 +1527,35 @@ async function runSkillWithVisit(ctx, name, inputArgs) {
: rel + '(站内路径:public_link.base_url 未配置,拼不出公网前缀)');
}
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;
}
const SKILL_USAGE = 'skill 用法:{"op":"list"} / {"op":"get","name":"<技能名>"} / {"op":"run","name":"<技能名>","args":{...}}';
// 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.listCallableSkills(ctx), null, 2);
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 缺少技能名。' + SKILL_USAGE);
return runSkillWithVisit(ctx, name, a.input_args);
default:
throw new Error('未知的 op:"' + op + '"。' + SKILL_USAGE);
}
function rejectSkillArgs(skillArgs, op) {
if (!skillArgs || typeof skillArgs !== 'object' || !Object.keys(skillArgs).length) return;
throw new Error('op=' + op + ' 不接受 args,只有 op=run 才带参数。' + SKILL_USAGE);
}
// 旧字段名 input_args 在这里归一化成 args,再走同一条分派(见上方注释)。
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);
const op = String(a.op == null ? '' : a.op).trim().toLowerCase();
const name = String(a.name == null ? '' : a.name).trim();
const skillArgs = a.args !== undefined ? a.args : a.input_args;
if (!op) throw new Error('skill 缺少必填参数 op(list / get / run)。' + SKILL_USAGE);
switch (op) {
case 'list':
rejectSkillArgs(skillArgs, 'list');
return JSON.stringify(await skills.listCallableSkills(ctx), null, 2);
case 'get':
if (!name) throw new Error('op=get 缺少必填参数 name。' + SKILL_USAGE);
rejectSkillArgs(skillArgs, 'get');
return skills.getSkillInfo(ctx, name);
case 'run':
if (!name) throw new Error('op=run 缺少必填参数 name。' + SKILL_USAGE);
return runSkillWithVisit(ctx, name, skillArgs);
default:
throw new Error('未知的 op:' + JSON.stringify(op) + '。' + 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.listCallableSkills(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 全部能力)。