diff --git a/app/config.example.yml b/app/config.example.yml index f5f0968..17af11d 100644 --- a/app/config.example.yml +++ b/app/config.example.yml @@ -7,7 +7,7 @@ platforms: [] # 模型 profile:prompt + tools 白名单组合,模型用 profile: <名> 引用(不配 = 全量)。 model_profiles: mini: # 小模型:只留核心工具,省上下文 - tools_allow: [read_file, write_file, edit_file, terminal, fetch, web_search, get_skill_info, run_skill] + tools_allow: [read_file, write_file, edit_file, terminal, fetch, web_search, skill] system_prompt_file: mini-system.txt # 相对 server/templates/(也接受绝对路径) zero: # 纯文本对话:一个工具都不发 tools_allow: [] diff --git a/app/server/config.js b/app/server/config.js index 5d1e139..1ed3b3e 100644 --- a/app/server/config.js +++ b/app/server/config.js @@ -88,7 +88,7 @@ const DEFAULTS = { model_profiles: { // 小模型:只留文件/终端/网页等核心工具,省上下文。 mini: { - tools_allow: ['read_file', 'write_file', 'edit_file', 'terminal', 'fetch', 'web_search', 'get_skill_info', 'run_skill'], + tools_allow: ['read_file', 'write_file', 'edit_file', 'terminal', 'fetch', 'web_search', 'skill'], system_prompt_file: 'mini-system.txt', }, // 纯文本对话:一个工具都不发。 diff --git a/app/server/routes/skills.js b/app/server/routes/skills.js index d977ff4..ce4d165 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 响应, -// list_skills 仍是实时兑底。 +// skill op=list 仍是实时兑底。 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 dfc5327..9fda973 100644 --- a/app/server/server.js +++ b/app/server/server.js @@ -135,8 +135,8 @@ function dumpPromptBundle() { // 启动时先发现各 MCP 服务的工具(单个服务失败只警告,不阻止启动), // 并对技能列表做快照(注入 system prompt,见 llm.setSkillListText),完成后开始监听。 mcp.init(cfg).then(async () => { - // 技能列表快照:模型直接感知已有技能,免先 list_skills 探索; - // 此处失败不阻塞启动,list_skills 仍可做实时兑底。 + // 技能列表快照:模型直接感知已有技能,免先 skill op=list 探索; + // 此处失败不阻塞启动,skill op=list 仍可做实时兑底。 try { const list = await skills.listSkills({ cfg }); llm.setSkillListText(skills.formatSkillListForPrompt(list)); diff --git a/app/server/templates/mini-system.txt b/app/server/templates/mini-system.txt index a823639..8c02b55 100644 --- a/app/server/templates/mini-system.txt +++ b/app/server/templates/mini-system.txt @@ -38,9 +38,8 @@ For out-of-scope requests: state the limit in one or two sentences, don't over-a ## Skills -- Prefer skills when they match. The Available Skills list shows names only; check parameters with `get_skill_info`, then `run_skill`. `list_skills` gives one-line descriptions when you need to choose. -- Use `get_skill_info` for parameters, then `run_skill` to execute. -- Skills run in the server's managed Python env; you cannot install packages for them at runtime. If `run_skill` fails for a missing package or system tool, tell the user it needs a server-side change. +- Prefer skills when they match. The Available Skills list shows names only; use `skill`: op=get for its parameters, op=run to execute, op=list for descriptions when choosing. +- Skills run in the server's managed Python env; you cannot install packages for them at runtime. If a skill fails for a missing package or system tool, tell the user it needs a server-side change. {APP_SKILLS} diff --git a/app/server/templates/system-prompt.txt b/app/server/templates/system-prompt.txt index 904de3a..773b02a 100644 --- a/app/server/templates/system-prompt.txt +++ b/app/server/templates/system-prompt.txt @@ -20,7 +20,7 @@ You are a file / data / information processing assistant. The environment expose - Do not fake results: no placeholder files, no claiming a file was created, no crude substitutes (e.g. ASCII art or a hand-drawn SVG) that miss the user's real intent. **When the user asks for something out of scope** -1. If the request might be handled by an available skill, check the skill list (or call `list_skills` if needed) before declaring it out of scope. +1. If the request might be handled by an available skill, check the skill list (or `skill` op=list if needed) before declaring it out of scope. 2. If no skill or tool can handle it, answer directly in your reply — do NOT call tools just to handle an out-of-scope request. 3. State the limitation in one or two sentences; do not over-apologize. 4. If a reasonable third-party tool covers it, mention one briefly (e.g. 豆包 / Doubao、即梦 / 可灵 / 通义万相 for AI image and video; Photoshop / Canva / 美图秀秀 for manual editing). @@ -50,11 +50,10 @@ You are a file / data / information processing assistant. The environment expose ## Skill Usage - Prefer using available skills when they match the task. -- The "Available Skills" list below shows installed skill names only. Pick a skill by name, call `get_skill_info` for its parameters, then `run_skill`. Call `list_skills` for one-line descriptions (e.g. to choose among several skills) or to confirm a stale/empty list. -- Use `get_skill_info` to understand a skill's parameters, then `run_skill` to execute it. +- The "Available Skills" list below shows installed skill names only. The `skill` tool (op=list / get / run) covers discovery, parameters and execution; its description states the op dependencies. - Only if no skill matches, proceed with other tools or write your own solution. - The listed skills are prepared and ready at server startup; do not try to install dependencies for a skill yourself. -- Skills run on the server's managed Python environment; you cannot add packages to a skill at runtime. If `run_skill` fails due to a missing package or system tool, report it to the user — the skill needs a server-side change. +- Skills run on the server's managed Python environment; you cannot add packages to a skill at runtime. If a skill fails due to a missing package or system tool, report it to the user — the skill needs a server-side change. {APP_SKILLS} diff --git a/app/server/tools/definitions.json b/app/server/tools/definitions.json index 3f6d986..0eb0019 100644 --- a/app/server/tools/definitions.json +++ b/app/server/tools/definitions.json @@ -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." } } } diff --git a/app/server/tools/executor.js b/app/server/tools/executor.js index 81a4855..bb553c2 100644 --- a/app/server/tools/executor.js +++ b/app/server/tools/executor.js @@ -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} diff --git a/app/server/tools/skills.js b/app/server/tools/skills.js index 573fc93..c0ef19b 100644 --- a/app/server/tools/skills.js +++ b/app/server/tools/skills.js @@ -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))) { diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 629a5fa..c023e34 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -41,9 +41,9 @@ agent/ │ │ ├── balance.js 余额查询适配器(按 platform.type 分发) │ │ ├── version.js 版本信息(package.json + git 短提交号) │ │ ├── tools/ -│ │ │ ├── definitions.json 内置 10 个工具的 OpenAI function 格式定义 +│ │ │ ├── definitions.json 内置 8 个工具的 OpenAI function 格式定义 │ │ │ ├── executor.js 工具执行器(文件类 + terminal + skill 委托) -│ │ │ └── skills.js Skill Manager(list/info/run + 路径预处理) +│ │ │ └── skills.js Skill Manager(skill 工具的 list/get/run + 路径预处理) │ │ ├── download-token.js 下载链接签名(浏览器原生下载用;密钥进程内随机) │ │ ├── download-send.js 单文件下载响应(Content-Disposition / 缓存策略) │ │ ├── public-files.js 公网临时文件短 ID 表(mint/resolve + 过期) @@ -279,7 +279,7 @@ stateDiagram-v2 - session 补偿:MCP 规范的 `Mcp-Session-Id` 缓存在 `server.sessionId`;过期(400 + 含 "session" 字样)自动重 initialize 后重试一次。 - 某些老服务无 `initialize` → catch `Method not found` 不阻断。 -### 5.4 `tools/executor.js` —— 内置 10 工具的派发器 +### 5.4 `tools/executor.js` —— 内置 8 工具的派发器 `HANDLERS` 是 `name → async(ctx, args) → result` 的表;`executeTool(ctx, name, args)` 按 `name` 派发;**未知名直接转发给 MCP**(若 `mcp.hasTool(name)`,调 `mcp.callTool`)。 @@ -287,12 +287,12 @@ stateDiagram-v2 |---|---| | `read_file` | 走 `resolveInTask` 防路径穿越;图像(PNG/JPEG/WebP/GIF/BMP/TIFF)按 vision 能力走 `sharp` 压缩后落盘 `.imgcache/` 并回传 `image_rel`(长边 ≤ 2000px,JPEG q=80;文件名带源文件 mtime+size 指纹,重读复用不增殖;重编码无收益时不落盘、直指原文件),发送前由 `llm.buildMessages` 现签成公网外链(engine 侧 mint 前 realpath 复核);大文本/二进制给 outline,超 32MB 拒读并引导 terminal;行号前缀格式 "`<6位右对齐行号>\\t<原文>`"(`edit_file` 用) | | `write_file` / `edit_file` | `edit_file` 用模糊定位(Zed 风格):先精确匹配,失败后用 Levenshtein DP 找最相似行;超 32MB 拒绝整文件读写(OOM 防护);DP 候选区间不连续(中间跳过无关 buffer 行)即弃用,防静默吞行;空 `new_text` = 整行干净删除(精确/模糊两层统一,对齐 `"".lines()` 零行语义);`old_text`/`new_text` 协议见 `definitions.json` | -| 已移除的工具 | `list_directory` / `create_directory` / `delete_path` / `move_path` / `copy_path` / `find_path` / `grep`:环境固定,文件操作与检索统一走 `terminal`(ls / mkdir / rm / mv / cp / find / rg),内置工具 17 → 10 | +| 已移除的工具 | `list_directory` / `create_directory` / `delete_path` / `move_path` / `copy_path` / `find_path` / `grep`:环境固定,文件操作与检索统一走 `terminal`(ls / mkdir / rm / mv / cp / find / rg),内置工具 17 → 10;技能三件套又并为 `skill` 后为 8 | | `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 | -| `list_skills` / `get_skill_info` / `run_skill` | 委托 `tools/skills.js` | -| `schedule_task` | 为**当前会话**(`ctx.sessionId`,AI 不可指定他会话)建定时任务;校验/写入全在 `scheduler.createTask`(cron 可解析 → 连续两次 `next()` 间隔 ≥ 1h → 查重 → INSERT 主键兑底),失败抛中文 Error 回给 AI;描述里限定「仅用户明确要求时调用」(安全缓解,见 §5.12) | +| `skill` | op 分派 list/get/run(三件套合并:同一 `skill_name` 标识空间 + 同一生命周期,见 `docs/tool-design.md` §一);委托 `tools/skills.js`;`input_args` 仅 op=run 且可缺省 `{}`,缺参由各技能 `input_schema` 校验点名报错 | +| `schedule_task` | **当前会话**(`ctx.sessionId`,AI 不可指定他会话)定时任务的完整生命周期:op 分派 get/create/update/delete(表主键 session_id → 每会话至多一条,无 id 参数);条件必填在代码里校验、错误回显 op 与缺失字段;数据层在 `scheduler.js`(cron 可解析 → 间隔 ≥1h → prompt ≤20000 → 查重/存在性检查),delete 不落 scheduler_note;描述里限定「仅用户明确要求时调用」(安全缓解,见 §5.12) | `resolveInTask(taskDir, relOrAbs)`:把相对路径或绝对路径解析为绝对路径并校验落在 `taskDir` 之内(含根),防穿越。 @@ -303,9 +303,9 @@ stateDiagram-v2 - init 的 pip 步骤先离线探测(`pip install --no-index --dry-run <逐行>`,不联网):镜像已带的包直接跳过,只把缺的装进 `deps/`;`.deps_installed` marker(requirements/install.sh 两份 hash)也在那里维护。 - 外挂层可见性:`skills/deps` 由 compose 放进 executor 容器 env 的 `PYTHONPATH`(`server.js` 白名单同步放行),技能入口与 AI 终端命令都能 import;运行期 skills 与 deps 均 `:ro`,**加包只需改 `requirements.txt` 后 `docker compose up -d`(重跑 init),不需重建镜像**。 - `runSkill` 流程:`input_args` 类型守卫(非对象早拒,免得在 Object.entries 里静默错位) → `skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`,缺项报错点名字段) → 选 `python3 run.py ''` 或 `bash run.sh ''` → `runEntry`。 -- system prompt 注入(`formatSkillListForPrompt`)只列名字省 token;描述查 `list_skills`、参数查 `get_skill_info`,配合关系写在注入段/模板里。 +- system prompt 注入(`formatSkillListForPrompt`)只列名字省 token;描述查 op=list、参数查 op=get、执行 op=run(`skill` 工具),op 间依赖写进工具 description。 - **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。 -- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。 +- **cwd 分两类**:`skill` op=run 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。 ### 5.6 `remote-exec.js` —— 远端 executor 客户端 diff --git a/docs/tool-design.md b/docs/tool-design.md new file mode 100644 index 0000000..0e1ad7b --- /dev/null +++ b/docs/tool-design.md @@ -0,0 +1,65 @@ +## LLM 工具接口设计规范 + +### 一、合并还是分开 + +共享同一**标识空间** + 同一**生命周期** → 合并为一个工具,用 `op` 分派。否则分开。 + +### 二、动词表 + +按资源性质选: + +| 资源性质 | 动词 | +|---|---| +| 持久化资源(存在/不存在两态) | `list` / `get` / `create` / `update` / `delete` | +| 可开关资源 | 上面 + `enable` / `disable` | +| 瞬时动作(无持久状态) | `run`,单独成工具 | + +表按**资源**选动词:动作作用于持久资源时(如技能的 `run`)并入该资源工具的 op 集;「`run` 单独成工具」只针对资源本身无持久状态、只剩动作的情形(`terminal`、`fetch` 类)。 + +跨工具统一用词:枚举 `list`、读单个 `get`、新建 `create`、删除 `delete`。 + +### 三、参数的放置 + +默认全部展开为顶层 `properties`。 + +- 跨 op 共享的参数放顶层,description 说明哪些 op 用它; +- op 专属参数也放顶层,description 说明 `op=X 时必填`; +- 仅当参数结构在工具定义时无法确定时,才用自由对象 `{ "type": "object" }`。 + +### 四、条件必填 + +- op 专属参数一律设为**可选**; +- 工具 description 用紧凑格式列依赖: + +``` +op=list 无参数。 +op=create 需要 A 和 B。 +op=delete 需要 id。 +``` + +- 参数 description 补一句"op=X 时使用"。 + +### 五、错误处理 + +- 分派的 default 分支**列出可用 op**; +- 报错**回显**:哪个 op、缺哪个字段; +- 代码里做校验,不只依赖 schema。 + +### 六、内容分工 + +| 内容 | 位置 | +|---|---| +| 有哪些 op、每个 op 要什么参数 | tool schema | +| op 之间的依赖 | tool description | +| 跨工具的动作指令 | system prompt | +| 动词表、命名约定 | 开发文档 | + +system prompt 不重复 schema 已表达的内容。 + +### 七、配套工具 + +成对出现的工具("执行动态能力" + "查询其 schema")相互依赖。删一个前先确认另一个的定位是否随之改变。 + +### 八、上下文成本 + +tools 数组每轮请求完整重发。新工具进来时,先问"能不能装进已有工具",再问"要不要新建"。 diff --git a/skills/README.md b/skills/README.md index cf3e93a..4d2015f 100644 --- a/skills/README.md +++ b/skills/README.md @@ -8,9 +8,9 @@ 技能是一个自包含的目录,通常存放在技能根目录(默认为 `skills/`)下。每个技能包含一个描述文件(`SKILL.md`)和一个可执行入口(`run.py` 或 `run.sh`)。Agent 通过以下流程使用技能: -1. 调用 `list_skills` 查看所有可用技能的名称和简介; -2. 调用 `get_skill_info` 获取某个技能的详细说明; -3. 调用 `run_skill` 执行技能,传入所需参数。 +1. 调用 `skill`(op=list)查看所有可用技能的名称和简介; +2. 调用 `skill`(op=get)获取某个技能的详细说明; +3. 调用 `skill`(op=run)执行技能,传入所需参数。 技能可以处理任何任务,例如文件格式转换、数据处理、网页抓取等。 @@ -56,7 +56,7 @@ output_schema: ``` - `name`:技能名称,应与目录名一致。 -- `description`:一句话描述技能功能,用于 `list_skills` 展示。 +- `description`:一句话描述技能功能,用于 `skill` op=list 展示。 - `input_schema`:输入参数的 JSON Schema 定义,用于参数校验和文档生成。 - `output_schema`:输出结果的描述(可选)。 - 若未提供 Front Matter,系统会尝试从正文第一行提取描述。 @@ -78,7 +78,7 @@ output_schema: - 自动处理某某 ## 使用说明 -通过 `run_skill` 调用,参数: +通过 `skill`(op=run)调用,参数: - `input`:某某路径(必填) - `output`:某某路径(可选,默认与输入同名) ``` @@ -226,7 +226,7 @@ input_schema: --- ## 使用说明 -通过 `run_skill` 调用,参数: +通过 `skill`(op=run)调用,参数: - `text`:要回显的文本(必填) ``` diff --git a/skills/img-utils/SKILL.md b/skills/img-utils/SKILL.md index 11d2f0f..f3b5493 100644 --- a/skills/img-utils/SKILL.md +++ b/skills/img-utils/SKILL.md @@ -87,7 +87,7 @@ output_schema: - `grid`:把同一目录下多张图拼成一张 contact sheet(缩略图网格) ## 使用说明 -通过 `run_skill` 调用,参数 `input_args`: +通过 `skill`(op=run)调用,参数 `input_args`: - `action`:操作类型(必填) - `input`:输入图片或目录(必填;相对会话工作目录的路径即可,会自动转绝对路径) - `output`:输出路径(建议给全;不给时自动生成 `<原名>_<动作>.<原扩展名>`,绝不覆盖原图) diff --git a/skills/md2pdf/SKILL.md b/skills/md2pdf/SKILL.md index d54fdad..8b8275c 100644 --- a/skills/md2pdf/SKILL.md +++ b/skills/md2pdf/SKILL.md @@ -29,6 +29,6 @@ output_schema: - 自动处理中文字体 ## 调用方式 -通过 `run_skill` 调用,参数: +通过 `skill`(op=run)调用,参数: - `input`:Markdown 文件路径(必填) - `output`:PDF 输出路径(可选,默认与输入同名)