diff --git a/README.md b/README.md index d494eac..3b4a645 100644 --- a/README.md +++ b/README.md @@ -118,7 +118,7 @@ mcp_servers: | `skill` | ✓ | ✗ | ✓ | `skill` 工具与 `lab` | | `disable` | ✗ | ✗ | ✗ | 无人 | -`skill` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,改为以技能形式暴露——`{"list":"all"}` 能看到它,`{"get":"<名>"}` 直接返回 MCP 原始的 `description` + `input_schema`,`{"run":"<名>","args":{…}}` 转发给服务。不用在 `skills/` 里建目录。旧字段 `enable` 已废弃,`mode: silent` 已移除(启动会报错并提示改用 `skill`)。 +`skill` 用于「能力包在技能后面」的场景:工具照常发现并注册,只是不进模型的 tools 数组,改为以技能形式暴露——`{"op":"list"}` 能看到它,`{"op":"get","name":"<名>"}` 直接返回 MCP 原始的 `description` + `input_schema`,`{"op":"run","name":"<名>","args":{…}}` 转发给服务。不用在 `skills/` 里建目录。旧字段 `enable` 已废弃,`mode: silent` 已移除(启动会报错并提示改用 `skill`)。 工具发现只在启动时做一次,因此发现失败后会自动按 **2s / 20s / 1min 重试 3 次**(覆盖 compose 并行拉起与宿主机重启后的容器乱序);成功后工具在下一轮请求即可用,三次都失败则需重启 core。三个 MCP 服务都配了 `/health` 健康检查,`docker ps` 可直接看状态。 @@ -263,7 +263,7 @@ platforms: | `terminal` | 执行 shell 命令;默认在会话目录,超时可终止 | | `fetch` | 抓取 HTTP/HTTPS 并转 Markdown;带 SSRF 防护与分段续读 | | `mint_public_link` | 为会话内文件签发短期公网链接 | -| `skill` | 技能:`{"list":"all"}` / `{"get":"<名>"}` / `{"run":"<名>","args":{...}}`(动词作键,三选一) | +| `skill` | 技能:`op` = `list` / `get` / `run`;`name` 指技能,`args` 传参数 | | `db` | 操作会话本地 `data.db`:`exec`、`query`、`insert`、`tables`、`schema` | | `schedule` | 定时任务 `get` / `list` / `create` / `update` / `delete` | | `profile` | 用户画像 `list` / `set` / `add` / `remove` | @@ -287,7 +287,7 @@ skills/my-skill/ ``` - `SKILL.md` 的 `description` 会进入 system prompt,模型启动时就知道有哪些技能。 -- `input_schema.required` 在 `{"run":"<名>","args":{...}}` 前校验。 +- `input_schema.required` 在 `op=run` 前校验。 - MCP 工具不用建目录:给该服务配 `mode: skill`,平台会自动把它暴露成技能(`get` 返回 MCP 原始的 `input_schema`,`run` 转发),见上文「同栈 MCP 服务」。 - 入口脚本以绝对路径启动;远端执行时 cwd 是会话目录,本地开发时是技能目录。相对路径参数会先按会话目录转成绝对路径。 diff --git a/app/AGENTS.md b/app/AGENTS.md index 64d21c3..e9ac47a 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -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` 转发 diff --git a/app/server/routes/skills.js b/app/server/routes/skills.js index f39c434..f860f98 100644 --- a/app/server/routes/skills.js +++ b/app/server/routes/skills.js @@ -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))) diff --git a/app/server/server.js b/app/server/server.js index 31bacb7..7527211 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -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)); diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index c754e50..ed9987c 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -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\":\"\"} 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\":\"\",\"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\":\"\"} return the skill's full details; call it before the first run\n{\"op\":\"run\",\"name\":\"\",\"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." } } } diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 27cf2db..8e2b433 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -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 全部能力)。 diff --git a/docs/tool-design.md b/docs/tool-design.md index fe7ee53..8e2adcd 100644 --- a/docs/tool-design.md +++ b/docs/tool-design.md @@ -25,9 +25,8 @@ - 跨 op 共享的参数放顶层,description 说明哪些 op 用它; - op 专属参数也放顶层,description 说明 `op=X 时必填`; - 仅当参数结构在工具定义时无法确定时,才用自由对象 `{ "type": "object" }`。 -- 动词 + 单 token 标识可以折叠成「动词作键、标识作值」(技能的 `{"get":"<名>"}` 即此形)。 - 多个动词互斥时 `required` 表达不了,必须在代码里校验,并在报错里回显全部合法形态; - 取值范围暂只有一个时(如 `{"list":"all"}`)仍用字符串而非布尔,便于后续扩成分类等子集。 +- 互斥的多动作一律用枚举开关 `op` + 各自顶层参数,不要把动作编码进键名:键名方案无法用 + `required` 约束(漏键只能到运行时才发现),弱模型也更容易漏写。 ### 四、条件必填 diff --git a/skills/README.md b/skills/README.md index 6adc654..b52611f 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,9 +8,9 @@ 技能是一个自包含的目录,通常存放在技能根目录(默认为 `skills/`)下。每个技能包含一个描述文件(`SKILL.md`)和一个可执行入口(`run.py` 或 `run.sh`)。Agent 通过以下流程使用技能: -1. 调用 `skill` 的 `{"list":"all"}` 查看所有可用技能的名称和简介; -2. 调用 `skill` 的 `{"get":"<技能名>"}` 获取某个技能的详细说明; -3. 调用 `skill` 的 `{"run":"<技能名>","args":{...}}` 执行技能,传入所需参数。 +1. 调用 `skill` 的 `{"op":"list"}` 查看所有可用技能的名称和简介; +2. 调用 `skill` 的 `{"op":"get","name":"<技能名>"}` 获取某个技能的详细说明; +3. 调用 `skill` 的 `{"op":"run","name":"<技能名>","args":{...}}` 执行技能,传入所需参数。 技能可以处理任何任务,例如文件格式转换、数据处理、网页抓取等。 @@ -57,7 +57,7 @@ visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板 ``` - `name`:技能名称,应与目录名一致。 -- `description`:一句话描述技能功能,用于 `{"list":"all"}` 的清单展示。 +- `description`:一句话描述技能功能,用于 `op=list` 的清单展示。 - `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。 - `output_schema`:输出结果的描述(可选)。 - `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`run` 成功后由 core(tools/executor.js)拼上 `public_link.base_url`,在输出末尾追加一行「访问地址:<完整 URL>」——技能进程跑在 executor 隔离视图里不知道公网地址,完整链接只能 core 补;AI 拿到相对路径会原样转给用户,而相对路径打不开。 @@ -80,7 +80,7 @@ visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板 - 自动处理某某 ## 使用说明 -通过 `skill` 的 `{"run":"<技能名>","args":{...}}` 调用,参数: +通过 `skill` 的 `{"op":"run","name":"<技能名>","args":{...}}` 调用,参数: - `input`:某某路径(必填) - `output`:某某路径(可选,默认与输入同名) ``` @@ -92,10 +92,10 @@ visit_url: /app/{task_id}/ # 可选:页面类技能的访问路径模板 把 `config.yml` 里某个 MCP 服务配成 `mode: skill` 即可:它的每个工具会自动成为技能,不需要 `SKILL.md`,也不需要入口脚本。 -- `{"list":"all"}` 里出现工具名,描述取 MCP `description` 的第一行; -- `{"get":"<工具名>"}` 直接返回 MCP 原始的 `description` + `input_schema`(单一来源,不会与 +- `{"op":"list"}` 里出现工具名,描述取 MCP `description` 的第一行; +- `{"op":"get","name":"<工具名>"}` 直接返回 MCP 原始的 `description` + `input_schema`(单一来源,不会与 实现漂移); -- `{"run":"<工具名>","args":{…}}` 把 `args` 原样透传成 MCP 的 `arguments`,由 core 直接转发。 +- `{"op":"run","name":"<工具名>","args":{…}}` 把 `args` 原样透传成 MCP 的 `arguments`,由 core 直接转发。 几个约束: @@ -251,7 +251,7 @@ input_schema: --- ## 使用说明 -通过 `skill` 的 `{"run":"<技能名>","args":{...}}` 调用,参数: +通过 `skill` 的 `{"op":"run","name":"<技能名>","args":{...}}` 调用,参数: - `text`:要回显的文本(必填) ``` diff --git a/skills/data-page/SKILL.md b/skills/data-page/SKILL.md index c20d229..72d3044 100644 --- a/skills/data-page/SKILL.md +++ b/skills/data-page/SKILL.md @@ -31,7 +31,7 @@ visit_url: /app/{task_id}/ ## 初始化 -调用 `skill {"run":"data-page"}`,无需参数。它会把以下文件复制到 `.app/`: +调用 `skill {"op":"run","name":"data-page"}`,无需参数。它会把以下文件复制到 `.app/`: - `table.html` / `dashboard.html` / `kanban.html` —— 三个数据页模板 - `nav.html` —— 多页导航首页模板(静态卡片,无 config) @@ -80,7 +80,7 @@ const taskId = location.pathname.split('/').filter(Boolean)[1]; 1. **明确数据结构**:与用户确认字段。如果描述模糊,可以建议合理的结构。 2. **创建表并录入数据**:用 `db` 工具完成。 -3. **初始化**:调用 `skill {"run":"data-page"}`。 +3. **初始化**:调用 `skill {"op":"run","name":"data-page"}`。 4. **为每个要生成的页面写 config 文件**(见下一节)。**不要读也不要改模板本身**。 5. **选定入口页 `.app/index.html`**(index 是副本,允许编辑;模板本体不动): - **用到 ≥2 个模板页** → `cp .app/nav.html .app/index.html`,改标题为业务名,并把未启用页面的卡片删掉(没配过的页点开会报 no such table)。子页标题左侧的「‹」返回键链回此导航页。 diff --git a/skills/image-process/SKILL.md b/skills/image-process/SKILL.md index 8284ee8..da0ccdd 100644 --- a/skills/image-process/SKILL.md +++ b/skills/image-process/SKILL.md @@ -87,7 +87,7 @@ output_schema: - `grid`:把同一目录下多张图拼成一张 contact sheet(缩略图网格) ## 使用说明 -通过 `skill` 的 `{"run":"image-process","args":{...}}` 调用,参数: +通过 `skill` 的 `{"op":"run","name":"image-process","args":{...}}` 调用,参数: - `action`:操作类型(必填) - `input`:输入图片或目录(必填;相对会话工作目录的路径即可,会自动转绝对路径) - `output`:输出路径(建议给全;不给时自动生成 `<原名>_<动作>.<原扩展名>`,绝不覆盖原图) diff --git a/skills/x2pdf/SKILL.md b/skills/x2pdf/SKILL.md index 2e9d596..b1fcc65 100644 --- a/skills/x2pdf/SKILL.md +++ b/skills/x2pdf/SKILL.md @@ -66,7 +66,7 @@ output_schema: ## 调用方式 -通过 `skill` 的 `{"run":"x2pdf","args":{...}}` 调用,参数: +通过 `skill` 的 `{"op":"run","name":"x2pdf","args":{...}}` 调用,参数: - `input`:输入文件路径(必填) - `output`:PDF 输出路径(可选,默认与输入同名) - `css`:自定义 CSS 文件路径(可选,仅 md/html/txt)