refactor(skill): 参数改为动词作键,去掉 op/name/input_args
形状:{"list":"all"} / {"get":"<名>"} / {"run":"<名>","args":{...}},三者恰好给一个。
- 互斥无法用 required 表达,校验与报错回显放在 toolSkill
- list 取值是字符串范围而非布尔,为将来的技能分类留扩展位;今天只认 all
- list/get 带非空 args 一律报错,不静默丢弃
- 旧形状 {op,name,input_args} 仍由 toolSkill 兜底翻译,只为兼容存量技能文档,不再对外文档化
- README/AGENTS/skills 文档与内置技能调用示例同步为新形态
This commit is contained in:
+12
-12
@@ -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`:要回显的文本(必填)
|
||||
```
|
||||
|
||||
|
||||
@@ -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)。子页标题左侧的「‹」返回键链回此导航页。
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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: <url>`
|
||||
|
||||
@@ -87,7 +87,7 @@ output_schema:
|
||||
- `grid`:把同一目录下多张图拼成一张 contact sheet(缩略图网格)
|
||||
|
||||
## 使用说明
|
||||
通过 `skill`(op=run)调用,参数 `input_args`:
|
||||
通过 `skill` 的 `{"run":"img-utils","args":{...}}` 调用,参数:
|
||||
- `action`:操作类型(必填)
|
||||
- `input`:输入图片或目录(必填;相对会话工作目录的路径即可,会自动转绝对路径)
|
||||
- `output`:输出路径(建议给全;不给时自动生成 `<原名>_<动作>.<原扩展名>`,绝不覆盖原图)
|
||||
|
||||
@@ -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: <url>`
|
||||
|
||||
@@ -66,7 +66,7 @@ output_schema:
|
||||
|
||||
## 调用方式
|
||||
|
||||
通过 `skill`(op=run)调用,参数:
|
||||
通过 `skill` 的 `{"run":"x2pdf","args":{...}}` 调用,参数:
|
||||
- `input`:输入文件路径(必填)
|
||||
- `output`:PDF 输出路径(可选,默认与输入同名)
|
||||
- `css`:自定义 CSS 文件路径(可选,仅 md/html/txt)
|
||||
|
||||
Reference in New Issue
Block a user