技能三件套并为skill(op=list/get/run):同一标识空间+生命周期按规范§一合并,§七配套关系转为op间依赖并迁入tool description;input_args降为可选缺省{}(缺参由技能input_schema点名报错,免双重门槛);mini整工具放行顺带获得op=list;模板/注入段/config allow/README/SKILL.md/ARCHITECTURE同步改名,tool-design补§二持久资源动作归并澄清

This commit is contained in:
2026-09-23 08:15:59 +08:00
parent d51add1893
commit 3555d29465
14 changed files with 133 additions and 72 deletions
+10 -34
View File
@@ -191,48 +191,24 @@
{
"type": "function",
"function": {
"name": "list_skills",
"description": "Lists all installed skills with a one-line description each, read live from the skill root directory.\n\nThe system prompt's Available Skills section shows skill names only; use this tool when you need descriptions to choose among them or to confirm what is installed. An empty skill set returns an empty list — that is not an error.",
"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 skill_name.\nop=run Requires skill_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 arguments 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).",
"parameters": {
"type": "object",
"required": [],
"properties": {}
}
}
},
{
"type": "function",
"function": {
"name": "get_skill_info",
"description": "Returns the full raw SKILL.md of a skill (front matter included): purpose, input_schema (the parameters run_skill accepts), and usage notes. Since the system prompt lists skill names only, call this before running a skill you have not used in this conversation. If the skill does not exist, an error is returned.",
"parameters": {
"type": "object",
"required": ["skill_name"],
"required": ["op"],
"properties": {
"op": {
"type": "string",
"enum": ["list", "get", "run"],
"description": "Operation to perform on skills."
},
"skill_name": {
"type": "string",
"description": "Name of the skill (subdirectory name under the skill root directory)."
}
}
}
}
},
{
"type": "function",
"function": {
"name": "run_skill",
"description": "Executes a skill with the given input arguments, validated against the skill's 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\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 arguments 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).",
"parameters": {
"type": "object",
"required": ["skill_name", "input_args"],
"properties": {
"skill_name": {
"type": "string",
"description": "Name of the skill to execute."
"description": "Name of the skill (subdirectory name under the skill root directory). Required with op=get and op=run."
},
"input_args": {
"type": "object",
"description": "Dictionary of input arguments for the skill. Keys and values should match the skill's input_schema. Example: {\"input\": \"file.md\", \"output\": \"out.pdf\"}."
"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."
}
}
}
+25 -3
View File
@@ -800,6 +800,30 @@ function toolScheduleTask(ctx, args) {
}
}
// skill:技能三件套(list_skills/get_skill_info/run_skill)合并后的单工具(op 分派)。
// 同一标识空间(skill_name)+ 同一生命周期(live 扫目录,无常驻状态可增删)→ 合并,
// 依据 docs/tool-design.md §一;技能不是「无持久状态」的动作,run 不必单独成工具。
// input_args 仅 op=run 用且可缺省:runSkill 把 null 视作 {},真正缺哪些字段由
// 各技能 input_schema 校验点名报错(工具层再 gate 一层是双重门槛,无益)。
async function toolSkill(ctx, args) {
const op = String(args.op || '').trim().toLowerCase();
const name = String(args.skill_name || '').trim();
switch (op) {
case 'list':
return JSON.stringify(await skills.listSkills(ctx), null, 2);
case 'get': {
if (!name) throw new Error('op=get 缺少必填参数 skill_name');
return skills.getSkillInfo(ctx, name);
}
case 'run': {
if (!name) throw new Error('op=run 缺少必填参数 skill_name');
return skills.runSkill(ctx, name, args.input_args);
}
default:
throw new Error('未知的 op:"' + op + '"。可用:list / get(需 skill_name)/ run(需 skill_name,input_args 可选)');
}
}
const HANDLERS = {
read_file: toolReadFile,
write_file: toolWriteFile,
@@ -808,9 +832,7 @@ const HANDLERS = {
terminal: toolTerminal,
fetch: toolFetch,
schedule_task: toolScheduleTask,
list_skills: async (ctx, args) => JSON.stringify(await skills.listSkills(ctx), null, 2),
get_skill_info: (ctx, args) => skills.getSkillInfo(ctx, args.skill_name),
run_skill: (ctx, args) => skills.runSkill(ctx, args.skill_name, args.input_args),
skill: toolSkill,
};
// ctx: {sessionId, taskDir, run, cfg, db, vision}
+7 -7
View File
@@ -48,7 +48,7 @@ function extractDescription(content) {
return line || '(无描述)';
}
// ---------- 3.1 list_skills ----------
// ---------- 3.1 skill op=list ----------
async function listSkills(ctx) {
const root = skillsRoot(ctx);
if (!fs.existsSync(root)) {
@@ -71,17 +71,17 @@ async function listSkills(ctx) {
// ---------- system prompt 注入:可用技能列表 ----------
// 把技能列表格式化成 “## Available Skills” 段落(仅名字,每行一个,省 token;
// 描述查 list_skills,参数查 get_skill_info)。
// 描述查 op=list,参数查 op=get)。
// 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后
// (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已装技能,
// 省掉先 list_skills 探索的往返;list_skills 保留作实时描述/兼容性查询。
// 省掉先 op=list 探索的往返;op=list 保留作实时描述/兼容性查询。
function formatSkillListForPrompt(list) {
if (!list || !list.length) return '';
const lines = list.map(s => '- ' + s.name);
return '## Available Skills\nInstalled skills (names only). To use one: `get_skill_info` for its parameters, then `run_skill` to execute. Call `list_skills` for one-line descriptions when choosing among skills.\n' + lines.join('\n');
return '## Available Skills\nInstalled skills (names only). Use the `skill` tool: op=get for its parameters, op=run to execute; op=list gives one-line descriptions when choosing among skills.\n' + lines.join('\n');
}
// ---------- 3.2 get_skill_info ----------
// ---------- 3.2 skill op=get ----------
async function getSkillInfo(ctx, skillName) {
const dir = skillDir(ctx, skillName);
const mdPath = path.join(dir, 'SKILL.md');
@@ -127,7 +127,7 @@ function validateArgs(fm, inputArgs, skillName) {
// 前台执行技能入口,带超时与取消支持;成功 resolve stdout,失败 reject SkillExecutionError。
// 配了 executor:入口命令拼成单条 shell 行(参数单引号转义,JSON payload 安全)交远端执行,
// cwd 由调用方给出(run_skill 传会话目录以命中 session 隔离与虚拟视图);
// cwd 由调用方给出(op=run 传会话目录以命中 session 隔离与虚拟视图);
// 技能依赖的 PYTHONPATH 由 executor 容器 env 提供,core 不感知依赖层。
function runEntry(ctx, entry, args, cwd, timeoutMs) {
const cfg = ctx.cfg;
@@ -191,7 +191,7 @@ function runEntry(ctx, entry, args, cwd, timeoutMs) {
});
}
// ---------- 3.3 run_skill ----------
// ---------- 3.3 skill op=run ----------
async function runSkill(ctx, skillName, inputArgs) {
// 非对象参数会在 absolutizeArgs 的 Object.entries 里静默错位成垃圾键值(如字符串→索引对象),显式拦下。
if (inputArgs != null && (typeof inputArgs !== 'object' || Array.isArray(inputArgs))) {