diff --git a/README.md b/README.md index 114d8b3..c144794 100644 --- a/README.md +++ b/README.md @@ -263,7 +263,7 @@ platforms: | `terminal` | 执行 shell 命令;默认在会话目录,超时可终止 | | `fetch` | 抓取 HTTP/HTTPS 并转 Markdown;带 SSRF 防护与分段续读 | | `mint_public_link` | 为会话内文件签发短期公网链接 | -| `skill` | 技能 `list` / `get` / `run` | +| `skill` | 技能:`{"list":"all"}` / `{"get":"<名>"}` / `{"run":"<名>","args":{...}}`(动词作键,三选一) | | `db` | 操作会话本地 `data.db`:`exec`、`query`、`insert`、`tables`、`schema` | | `schedule` | 定时任务 `get` / `list` / `create` / `update` / `delete` | | `profile` | 用户画像 `list` / `set` / `add` / `remove` | @@ -287,8 +287,8 @@ skills/my-skill/ ``` - `SKILL.md` 的 `description` 会进入 system prompt,模型启动时就知道有哪些技能。 -- `input_schema.required` 在 `skill op=run` 前校验。 -- `mcp_tool`:声明后端为某个 MCP 工具。此时 `op=run` 由 core 直接转发给 MCP(不落沙箱、不需要密钥), +- `input_schema.required` 在 `{"run":"<名>","args":{...}}` 前校验。 +- `mcp_tool`:声明后端为某个 MCP 工具。此时 `run` 由 core 直接转发给 MCP(不落沙箱、不需要密钥), 配合该服务的 `mode: silent` 就能把工具从模型的 tools 数组里隐藏,只留一行技能描述。仓库自带的 `skills/image`、`skills/video` 就是这么封装的 `image_task` / `video_task`。 - 入口脚本以绝对路径启动;远端执行时 cwd 是会话目录,本地开发时是技能目录。相对路径参数会先按会话目录转成绝对路径。 diff --git a/app/AGENTS.md b/app/AGENTS.md index e53103e..dd36f6b 100644 --- a/app/AGENTS.md +++ b/app/AGENTS.md @@ -170,12 +170,15 @@ POST /api/sessions/:id/messages `source_path`,且只限同一用户的会话。写侧显式拒绝——否则会造出字面 `@task-x` 目录。 - `checkToolArgs` + `unwrapToolArgs`:前者做结构性预检并生成 `errAck`,后者按 schema 逐层剥掉 弱模型多包的信封。两者都是纯函数并已导出,便于回归验证。 -- 技能(`tools/skills.js`):`SKILL.md` front matter 提供 `description`/`input_schema`; - `input_schema.required` 在 `run` 前校验;相对路径参数按会话目录转绝对路径;入口一律用绝对路径 - (远端 cwd 是会话目录)。配了 executor 就走 `remote-exec`,否则本地 `spawn`。 +- 技能(`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` 兜底翻译(存量技能文档里还写着它),不再对外文档化。 声明了 `mcp_tool` 的技能走另一条后端:`runSkill` 在 `absolutizeArgs` **之前**分流,由 core 直接 `mcp.callTool` 转发(不落沙箱,所以也不需要任何密钥);否则 URL 与含 `/` 的 prompt 会被 - 当路径改写。此时不跑 `input_schema.required` 校验(参数是 op 相关的,交给 MCP 服务管)。 + 当路径改写。此时不跑 `input_schema.required` 校验(参数与 MCP 工具自己的 `op` 相关,交给服务管)。 - MCP(`mcp.js`):启动时 `initialize` → `notifications/initialized` → `tools/list`;与内置或已有 MCP 工具重名时加 `<服务名>__` 前缀;请求随带 `X-Session-Dir`、`X-Public-Base`; `content` 里的 `ui_card` 块不进模型上下文,转成 SSE `ui_card` 事件。 diff --git a/app/server/routes/skills.js b/app/server/routes/skills.js index 5961638..67f0330 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 op=list 仍是实时兑底。 +// skill {"list":"all"} 仍是实时兜底。 function refreshSkillPrompt() { listSkills({ cfg: engine.getConfig() }) .then(list => llm.setSkillListText(formatSkillListForPrompt(list))) diff --git a/app/server/server.js b/app/server/server.js index 489706f..6649365 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 () => { - // 技能列表快照:模型直接感知已有技能,免先 skill op=list 探索; - // 此处失败不阻塞启动,skill op=list 仍可做实时兑底。 + // 技能列表快照:模型直接感知已有技能,免先 {"list":"all"} 探索; + // 此处失败不阻塞启动,{"list":"all"} 仍可做实时兜底。 try { const list = await skills.listSkills({ cfg }); llm.setSkillListText(skills.formatSkillListForPrompt(list)); diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index 7581f31..c754e50 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -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\":\"\"} 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).", "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." } } } diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 65da054..369c4ee 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -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, diff --git a/app/server/tools/skills.js b/app/server/tools/skills.js index dcbddf6..f52e8c2 100644 --- a/app/server/tools/skills.js +++ b/app/server/tools/skills.js @@ -3,7 +3,7 @@ // 一次性处理——镜像已带的包跳过,缺的装进 skills/deps,运行期经 executor 容器 env 的 PYTHONPATH 可见。 // 技能统一存放于技能根目录(cfg.skills_root,所有任务/会话共享;容器内挂 ./skills → /workspace/skills),每个技能一个子目录: // /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); diff --git a/docs/tool-design.md b/docs/tool-design.md index 0e1ad7b..fe7ee53 100644 --- a/docs/tool-design.md +++ b/docs/tool-design.md @@ -25,6 +25,9 @@ - 跨 op 共享的参数放顶层,description 说明哪些 op 用它; - op 专属参数也放顶层,description 说明 `op=X 时必填`; - 仅当参数结构在工具定义时无法确定时,才用自由对象 `{ "type": "object" }`。 +- 动词 + 单 token 标识可以折叠成「动词作键、标识作值」(技能的 `{"get":"<名>"}` 即此形)。 + 多个动词互斥时 `required` 表达不了,必须在代码里校验,并在报错里回显全部合法形态; + 取值范围暂只有一个时(如 `{"list":"all"}`)仍用字符串而非布尔,便于后续扩成分类等子集。 ### 四、条件必填 diff --git a/skills/README.md b/skills/README.md index 84147b2..44decd3 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,9 +8,9 @@ 技能是一个自包含的目录,通常存放在技能根目录(默认为 `skills/`)下。每个技能包含一个描述文件(`SKILL.md`)和一个可执行入口(`run.py` 或 `run.sh`)。Agent 通过以下流程使用技能: -1. 调用 `skill`(op=list)查看所有可用技能的名称和简介; -2. 调用 `skill`(op=get)获取某个技能的详细说明; -3. 调用 `skill`(op=run)执行技能,传入所需参数。 +1. 调用 `skill` 的 `{"list":"all"}` 查看所有可用技能的名称和简介; +2. 调用 `skill` 的 `{"get":"<技能名>"}` 获取某个技能的详细说明; +3. 调用 `skill` 的 `{"run":"<技能名>","args":{...}}` 执行技能,传入所需参数。 技能可以处理任何任务,例如文件格式转换、数据处理、网页抓取等。 @@ -58,10 +58,10 @@ mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此 ``` - `name`:技能名称,应与目录名一致。 -- `description`:一句话描述技能功能,用于 `skill` op=list 展示。 +- `description`:一句话描述技能功能,用于 `{"list":"all"}` 的清单展示。 - `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。 - `output_schema`:输出结果的描述(可选)。 -- `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`op=run` 成功后由 core(tools/executor.js)拼上 `public_link.base_url`,在输出末尾追加一行「访问地址:<完整 URL>」——技能进程跑在 executor 隔离视图里不知道公网地址,完整链接只能 core 补;AI 拿到相对路径会原样转给用户,而相对路径打不开。 +- `visit_url`:(可选)页面类技能声明的访问路径模板,`{task_id}` 占位执行时替换为会话 id。`run` 成功后由 core(tools/executor.js)拼上 `public_link.base_url`,在输出末尾追加一行「访问地址:<完整 URL>」——技能进程跑在 executor 隔离视图里不知道公网地址,完整链接只能 core 补;AI 拿到相对路径会原样转给用户,而相对路径打不开。 - `mcp_tool`:(可选)声明该技能的后端是某个已注册的 MCP 工具(见 3.3)。声明后不需要 `run.py` / `run.sh`。 - 若未提供 Front Matter,系统会尝试从正文第一行提取描述。 @@ -82,7 +82,7 @@ mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此 - 自动处理某某 ## 使用说明 -通过 `skill`(op=run)调用,参数: +通过 `skill` 的 `{"run":"<技能名>","args":{...}}` 调用,参数: - `input`:某某路径(必填) - `output`:某某路径(可选,默认与输入同名) ``` @@ -91,7 +91,7 @@ mcp_tool: image_task # 可选:声明后端为某个 MCP 工具(此 ### 3.3 MCP 后端技能(无入口脚本) -front matter 里写 `mcp_tool: <工具名>`,这个技能的 `op=run` 就不落 executor 沙箱,而是由 **core +front matter 里写 `mcp_tool: <工具名>`,这个技能的 `run` 就不落 executor 沙箱,而是由 **core 直接调用 `mcp.callTool`** 转发给 `mcp_servers` 里配置的服务: ```yaml @@ -102,12 +102,12 @@ mcp_tool: image_task --- ``` -- `input_args` **原样透传**成 MCP 工具的 `arguments`;参数校验由 MCP 服务负责(不做 - `input_schema.required` 预检——MCP 工具的参数常与 op 相关,静态必填列表会误伤)。 +- `args` **原样透传**成 MCP 工具的 `arguments`;参数校验由 MCP 服务负责(不做 + `input_schema.required` 预检——MCP 工具的参数常与它自己的 `op` 相关,静态必填列表会误伤)。 - **不经过沙箱**,所以也不需要密钥:凭证留在 core 的 `mcp_servers[].headers` 里。 executor 的环境变量白名单会按名字丢掉 `*KEY` / `*TOKEN`,沙箱本来也拿不到。 - 目的通常是省上下文:把该服务设成 `mode: silent`,工具不进模型的 tools 数组,模型只看到 - 技能清单里的一行描述,需要时再用 `op=get` 读本文件。 + 技能清单里的一行描述,需要时再用 `{"get":"<名>"}` 读本文件。 - `mcp_tool` 填**最终工具名**(与内置工具重名时会被加 `<服务名>__` 前缀,见 `app/AGENTS.md`)。 - 启动时 core 会自检:声明的工具不在注册表里会打 `warn`,不会等到模型第一次调用才暴露。 @@ -202,7 +202,7 @@ Agent 调用技能时,传入的文件路径可能是相对路径(相对于 - **运行时的工作目录是「会话任务目录」,不是技能目录**(远端模式下即 executor 隔离视图里的 `/workspace/tasks/<会话>`)。技能进程只能看到当前会话的数据,看不到其他会话。 - 因此技能内部引用**自身资源**(模板、字体、配置等)时,**必须**基于脚本位置取绝对路径,不要依赖 cwd:Python 用 `Path(__file__).resolve().parent`,Shell 用 `"$(dirname "$0")"`。 -- 读写会话数据用 `input_args` 里传入的路径即可;相对路径会被预转绝对路径,且在隔离视图里与 Agent 看到的是同一份数据。 +- 读写会话数据用 `args` 里传入的路径即可;相对路径会被预转绝对路径,且在隔离视图里与 Agent 看到的是同一份数据。 --- @@ -254,7 +254,7 @@ input_schema: --- ## 使用说明 -通过 `skill`(op=run)调用,参数: +通过 `skill` 的 `{"run":"<技能名>","args":{...}}` 调用,参数: - `text`:要回显的文本(必填) ``` diff --git a/skills/data-page/SKILL.md b/skills/data-page/SKILL.md index 6ed0e7f..c20d229 100644 --- a/skills/data-page/SKILL.md +++ b/skills/data-page/SKILL.md @@ -31,7 +31,7 @@ visit_url: /app/{task_id}/ ## 初始化 -调用 `skill(name="data-page", op="run")`,无需参数。它会把以下文件复制到 `.app/`: +调用 `skill {"run":"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(name="data-page", op="run")`。 +3. **初始化**:调用 `skill {"run":"data-page"}`。 4. **为每个要生成的页面写 config 文件**(见下一节)。**不要读也不要改模板本身**。 5. **选定入口页 `.app/index.html`**(index 是副本,允许编辑;模板本体不动): - **用到 ≥2 个模板页** → `cp .app/nav.html .app/index.html`,改标题为业务名,并把未启用页面的卡片删掉(没配过的页点开会报 no such table)。子页标题左侧的「‹」返回键链回此导航页。 diff --git a/skills/data-page/run.py b/skills/data-page/run.py index 0daa2ac..75f0a50 100644 --- a/skills/data-page/run.py +++ b/skills/data-page/run.py @@ -25,7 +25,7 @@ def main(): try: args = json.loads(sys.argv[1]) if not isinstance(args, dict): - raise ValueError('input_args 必须是 JSON 对象') + raise ValueError('技能参数必须是 JSON 对象') if args: print('本技能无参数,收到:' + json.dumps(args, ensure_ascii=False), file=sys.stderr) diff --git a/skills/image/SKILL.md b/skills/image/SKILL.md index e35f203..ed94485 100644 --- a/skills/image/SKILL.md +++ b/skills/image/SKILL.md @@ -10,7 +10,7 @@ mcp_tool: image_task ## 参数 -`input_args` 原样透传给底层服务: +`args` 原样透传给底层服务: - `op=create`:`prompt` 必填。描述越具体越好(主体、风格、构图、光线、画面里的文字要求)。 - `op=get`:`task_id` 必填,取回任务状态;`SUCCESS` 时返回图片 URL。 @@ -20,7 +20,7 @@ mcp_tool: image_task 1. 提交 ``` - skill op=run name=image input_args={"op":"create","prompt":"一只橘猫趴在窗台上晒太阳,水彩风格"} + skill {"run":"image","args":{"op":"create","prompt":"一只橘猫趴在窗台上晒太阳,水彩风格"}} ``` → 返回 `task_id` 与 `task_status: PROCESSING` @@ -28,7 +28,7 @@ mcp_tool: image_task 2. 查询 ``` - skill op=run name=image input_args={"op":"get","task_id":"<上一步返回的 id>"} + skill {"run":"image","args":{"op":"get","task_id":"<上一步返回的 id>"}} ``` → `SUCCESS` 时返回 `Image N: ` diff --git a/skills/img-utils/SKILL.md b/skills/img-utils/SKILL.md index df8e6ba..59667f1 100644 --- a/skills/img-utils/SKILL.md +++ b/skills/img-utils/SKILL.md @@ -87,7 +87,7 @@ output_schema: - `grid`:把同一目录下多张图拼成一张 contact sheet(缩略图网格) ## 使用说明 -通过 `skill`(op=run)调用,参数 `input_args`: +通过 `skill` 的 `{"run":"img-utils","args":{...}}` 调用,参数: - `action`:操作类型(必填) - `input`:输入图片或目录(必填;相对会话工作目录的路径即可,会自动转绝对路径) - `output`:输出路径(建议给全;不给时自动生成 `<原名>_<动作>.<原扩展名>`,绝不覆盖原图) diff --git a/skills/video/SKILL.md b/skills/video/SKILL.md index 0235e39..c7ed9cb 100644 --- a/skills/video/SKILL.md +++ b/skills/video/SKILL.md @@ -10,7 +10,7 @@ mcp_tool: video_task ## 参数 -`input_args` 原样透传给底层服务: +`args` 原样透传给底层服务: - `op=create`:`prompt` 与 `image_url` **至少给一个**。 - 文生视频:只给 `prompt`(≤512 字符)。 @@ -24,7 +24,7 @@ mcp_tool: video_task 1. 提交 ``` - skill op=run name=video input_args={"op":"create","prompt":"镜头缓慢推进,海浪拍打礁石","with_audio":true} + skill {"run":"video","args":{"op":"create","prompt":"镜头缓慢推进,海浪拍打礁石","with_audio":true}} ``` → 返回 `task_id` @@ -32,7 +32,7 @@ mcp_tool: video_task 2. 查询 ``` - skill op=run name=video input_args={"op":"get","task_id":"<上一步返回的 id>"} + skill {"run":"video","args":{"op":"get","task_id":"<上一步返回的 id>"}} ``` → `SUCCESS` 时返回 `Video URL: ` diff --git a/skills/x2pdf/SKILL.md b/skills/x2pdf/SKILL.md index 14e3a3f..2e9d596 100644 --- a/skills/x2pdf/SKILL.md +++ b/skills/x2pdf/SKILL.md @@ -66,7 +66,7 @@ output_schema: ## 调用方式 -通过 `skill`(op=run)调用,参数: +通过 `skill` 的 `{"run":"x2pdf","args":{...}}` 调用,参数: - `input`:输入文件路径(必填) - `output`:PDF 输出路径(可选,默认与输入同名) - `css`:自定义 CSS 文件路径(可选,仅 md/html/txt)