From c2fcbd9b48853bfba62dd956d9bbe42a61b9eeca Mon Sep 17 00:00:00 2001 From: kicer Date: Wed, 23 Sep 2026 22:34:02 +0800 Subject: [PATCH] =?UTF-8?q?skill=E5=B7=A5=E5=85=B7=E5=8F=82=E6=95=B0skill?= =?UTF-8?q?=5Fname=E6=94=B9=E5=90=8Dname(=E5=89=8D=E7=BC=80=E5=86=97?= =?UTF-8?q?=E4=BD=99:=E5=B7=A5=E5=85=B7=E5=90=8D=E5=B7=B2=E9=99=90?= =?UTF-8?q?=E5=AE=9A=E6=8A=80=E8=83=BD=E8=AF=AD=E5=A2=83,=E6=A0=87?= =?UTF-8?q?=E8=AF=86=E7=A9=BA=E9=97=B4=E5=B0=B1=E5=8F=ABname=E8=B6=B3?= =?UTF-8?q?=E5=A4=9F;schema/description/=E6=8A=A5=E9=94=99=E5=9B=9E?= =?UTF-8?q?=E6=98=BE/=E6=B3=A8=E9=87=8A/=E6=9E=B6=E6=9E=84=E6=96=87?= =?UTF-8?q?=E6=A1=A3=E5=90=8C=E6=AD=A5,=E5=85=A8=E5=BA=93=E9=9B=B6?= =?UTF-8?q?=E6=AE=8B=E7=95=99)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- app/server/tools/definitions.json | 4 ++-- app/server/tools/executor.js | 10 +++++----- docs/ARCHITECTURE.md | 2 +- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index 7c2f7a0..1fd84ac 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -228,7 +228,7 @@ "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 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).", + "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 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": ["op"], @@ -238,7 +238,7 @@ "enum": ["list", "get", "run"], "description": "Operation to perform on skills." }, - "skill_name": { + "name": { "type": "string", "description": "Name of the skill (subdirectory name under the skill root directory). Required with op=get and op=run." }, diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index a73b114..4538364 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -999,26 +999,26 @@ function toolDb(ctx, args) { } // skill:技能三件套(list_skills/get_skill_info/run_skill)合并后的单工具(op 分派)。 -// 同一标识空间(skill_name)+ 同一生命周期(live 扫目录,无常驻状态可增删)→ 合并, +// 同一标识空间(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(); + const name = String(args.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'); + if (!name) throw new Error('op=get 缺少必填参数 name'); return skills.getSkillInfo(ctx, name); } case 'run': { - if (!name) throw new Error('op=run 缺少必填参数 skill_name'); + if (!name) throw new Error('op=run 缺少必填参数 name'); return skills.runSkill(ctx, name, args.input_args); } default: - throw new Error('未知的 op:"' + op + '"。可用:list / get(需 skill_name)/ run(需 skill_name,input_args 可选)'); + throw new Error('未知的 op:"' + op + '"。可用:list / get(需 name)/ run(需 name,input_args 可选)'); } } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8563f74..ed84ccc 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -291,7 +291,7 @@ stateDiagram-v2 | `terminal` | **唯一一个走 executor 的内置工具**(当 `rexec.isRemote(cfg)`);本地分支用 `spawn` + `detached` + 进程组 kill;远端分支 `rexec.run` SSE 收流,结果套上超时/截断/取消注解后 `truncate(text, cfg.terminal.max_output_chars)` 返回 | | `fetch` | `AbortController` 覆盖全生命周期(响应头之后的 body 读流同样被超时/取消打断,取消用与 terminal 同款的 200ms 轮询);content-type 先行,非文本只回状态/类型/尺寸不读 body;流式读到 `cfg.fetch.max_bytes`(默认 1MB)即断开并标注截断;按响应 charset 解码(full-icu 支持 gbk/gb18030 等,未知编码退回 UTF-8);HTML 用 `htmlToMarkdown` 转;HTML 实体单遍解码(常见命名实体+数字实体通吃,修 `&` 双重解码);网络错误解包 `err.cause` 直述 ENOTFOUND/TLS 等真因;engine 不截工具结果,返回值末尾另有 `truncate` 1MB 字符护栏 | | `mint_public_link` | **唯一的 mint 入口**:与 core 同进程,直接 `publicFiles.mint()`,不绕任何 HTTP;`ctx.taskDir` 就是会话目录,`relOf` 的结果正是取用侧要的 `rel`。校验:`public_link.base_url` 已配 + `resolveInTask` 沙箱 + 确认是文件 + `realpath` 未沿符号链接跳出任务目录;返回单行 URL | -| `skill` | op 分派 list/get/run(三件套合并:同一 `skill_name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错 | +| `skill` | op 分派 list/get/run(三件套合并:同一 `name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错 | | `schedule` | **当前会话**(`ctx.sessionId`,AI 不可指定他会话)定时任务的完整生命周期:op 分派 get/create/update/delete(表主键 session_id → 每会话至多一条,无 id 参数);条件必填在代码里校验、错误回显 op 与缺失字段;数据层在 `scheduler.js`(cron 可解析 → 间隔 ≥1h → prompt ≤20000 → 查重/存在性检查),delete 不落 scheduler_note;描述里限定「仅用户明确要求时调用」(安全缓解,见 §5.12) | | `lab` | 元工具统一入口:`tool` + 自由 `args` 转发内置 + MCP 全部能力(目标 schema 定义期不可知,条件校验归内层 handler);`help` 伪工具做现场发现(无参列名单、带 `args.tool` 出完整 schema),未知名回显全清单,禁嵌套、内层错误冒泡不包装。默认被全局 `tools_deny: ['lab']` 屏蔽,仅 `lab` profile(allow `[lab]` + deny `[]` 清空)下发,见 §5.8 |