技能三件套:description按实现补全返回/超时/校验契约,与system prompt冲突消除;Available Skills注入改仅列名字省token(list_skills职责调整为描述/兜底查询);runSkill加input_args类型守卫

This commit is contained in:
2026-09-22 22:43:45 +08:00
parent 290527d2b7
commit 0527270aa5
5 changed files with 17 additions and 11 deletions
+1 -1
View File
@@ -38,7 +38,7 @@ For out-of-scope requests: state the limit in one or two sentences, don't over-a
## Skills ## Skills
- Prefer skills when they match. The Available Skills list below is current — call them directly, no need for `list_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. - 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. - 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.
+1 -1
View File
@@ -50,7 +50,7 @@ You are a file / data / information processing assistant. The environment expose
## Skill Usage ## Skill Usage
- Prefer using available skills when they match the task. - Prefer using available skills when they match the task.
- The "Available Skills" list below shows the currently installed skills; use it directly without calling `list_skills` first. If the list is empty or seems stale (e.g. a listed skill does not exist), call `list_skills` to check live. - 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. - Use `get_skill_info` to understand a skill's parameters, then `run_skill` to execute it.
- Only if no skill matches, proceed with other tools or write your own solution. - 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. - The listed skills are prepared and ready at server startup; do not try to install dependencies for a skill yourself.
+3 -3
View File
@@ -187,7 +187,7 @@
"type": "function", "type": "function",
"function": { "function": {
"name": "list_skills", "name": "list_skills",
"description": "Lists all available skills from the skill root directory, returning each skill's name and brief description.\n\nSkills are self-contained directories with a SKILL.md description and an executable entry point (run.py or run.sh). Use this tool to refresh or confirm the current list of available skills, then use get_skill_info for details or run_skill to execute.", "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.",
"parameters": { "parameters": {
"type": "object", "type": "object",
"required": [], "required": [],
@@ -199,7 +199,7 @@
"type": "function", "type": "function",
"function": { "function": {
"name": "get_skill_info", "name": "get_skill_info",
"description": "Returns the full content of the SKILL.md file for a given skill, including its purpose, parameters (input_schema), and usage instructions.", "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": { "parameters": {
"type": "object", "type": "object",
"required": ["skill_name"], "required": ["skill_name"],
@@ -216,7 +216,7 @@
"type": "function", "type": "function",
"function": { "function": {
"name": "run_skill", "name": "run_skill",
"description": "Executes a specified skill with the provided input arguments. The skill's entry script receives a JSON string as the only command-line argument.\n\n- Required parameters are validated against the skill's input_schema.\n- Default timeout is 120 seconds.\n- Relative paths in arguments are resolved against the session working directory; you may pass relative or absolute paths.", "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": { "parameters": {
"type": "object", "type": "object",
"required": ["skill_name", "input_args"], "required": ["skill_name", "input_args"],
+10 -5
View File
@@ -70,14 +70,15 @@ async function listSkills(ctx) {
} }
// ---------- system prompt 注入:可用技能列表 ---------- // ---------- system prompt 注入:可用技能列表 ----------
// 把技能列表格式化成 “## Available Skills” 段落(每行一个技能:名称 + 描述,描述内换行压成空格)。 // 把技能列表格式化成 “## Available Skills” 段落(仅名字,每行一个,省 token;
// 描述查 list_skills,参数查 get_skill_info)。
// 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后 // 由 llm.setSkillListText 拼入 system prompt:启动时快照(server.js)与技能变更后
// (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已有技能, // (routes/skills.js 的创建/重命名/删除/文件变更)调用,让模型直接感知已装技能,
// 省掉先 list_skills 探索的往返;list_skills 仍保留作实时兑底查询。 // 省掉先 list_skills 探索的往返;list_skills 保留作实时描述/兼容性查询。
function formatSkillListForPrompt(list) { function formatSkillListForPrompt(list) {
if (!list || !list.length) return ''; if (!list || !list.length) return '';
const lines = list.map(s => '- ' + s.name + ': ' + String(s.description).replace(/\s*\n\s*/g, ' ')); const lines = list.map(s => '- ' + s.name);
return '## Available Skills\nSkills installed on this server (call directly via run_skill; no need to call list_skills first):\n' + lines.join('\n'); 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');
} }
// ---------- 3.2 get_skill_info ---------- // ---------- 3.2 get_skill_info ----------
@@ -192,6 +193,10 @@ function runEntry(ctx, entry, args, cwd, timeoutMs) {
// ---------- 3.3 run_skill ---------- // ---------- 3.3 run_skill ----------
async function runSkill(ctx, skillName, inputArgs) { 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);
}
const dir = skillDir(ctx, skillName); const dir = skillDir(ctx, skillName);
if (!fs.existsSync(dir)) throw new SkillNotFoundError('技能不存在:' + skillName); if (!fs.existsSync(dir)) throw new SkillNotFoundError('技能不存在:' + skillName);
+2 -1
View File
@@ -302,7 +302,8 @@ stateDiagram-v2
- 依赖不由 core 安装(core 只发现与执行):系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M'(需重建镜像);pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 一次性落到宿主 `./skills`。 - 依赖不由 core 安装(core 只发现与执行):系统层依赖(apt 等,`install.sh` 的副作用)在镜像 `skills` 阶段烘入 M'(需重建镜像);pip 依赖与技能资产(如字体提取)在服务启动前由 `agent-executor-init` 一次性落到宿主 `./skills`。
- init 的 pip 步骤先离线探测(`pip install --no-index --dry-run <逐行>`,不联网):镜像已带的包直接跳过,只把缺的装进 `deps/`;`.deps_installed` marker(requirements/install.sh 两份 hash)也在那里维护。 - 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),不需重建镜像**。 - 外挂层可见性:`skills/deps` 由 compose 放进 executor 容器 env 的 `PYTHONPATH`(`server.js` 白名单同步放行),技能入口与 AI 终端命令都能 import;运行期 skills 与 deps 均 `:ro`,**加包只需改 `requirements.txt` 后 `docker compose up -d`(重跑 init),不需重建镜像**。
- `runSkill` 流程:`skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`) → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。 - `runSkill` 流程:`input_args` 类型守卫(非对象早拒,免得在 Object.entries 里静默错位) → `skillDir` 校验 → `absolutizeArgs`(按任务目录 + 启发式判断路径类参数) → `validateArgs`(按 front matter `input_schema.required`,缺项报错点名字段) → 选 `python3 run.py '<json>'` 或 `bash run.sh '<json>'` → `runEntry`。
- system prompt 注入(`formatSkillListForPrompt`)只列名字省 token;描述查 `list_skills`、参数查 `get_skill_info`,配合关系写在注入段/模板里。
- **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。 - **走 executor**:命令拼成 `shq` 转义后的单条 shell 行(`shellLine`);env 不额外传,依赖层由容器 env 提供。
- **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。 - **cwd 分两类**:`run_skill` 传会话任务目录(`ctx.taskDir`),命中 executor 的 session 隔离与虚拟视图,技能在 `/workspace/tasks/<sid>` 看到的就是本会话数据,`absolutizeArgs` 产出的绝对路径因此有效;入口脚本一律用绝对路径(cwd 已不是技能目录)。