给 AI 提供工具
把插件的功能声明成「工具」,用户在 Claude Code、Cursor 等 AI 客户端里就能让 AI 调用它。比如计算稿纸提供「计算算式」,AI 需要精确计算时就会调用。
原理
lingtools 内置一个 MCP 服务(用户在 设置 →「MCP」 里打开)。AI 客户端连上后,除了 lingtools 自带的工具,还能看到每个插件声明的工具,名字是 <插件名>_<工具名>。AI 调用工具时,lingtools 校验参数,再执行插件的处理函数,把结果交回给 AI。
插件不需要自己实现 MCP 协议,只要:在 plugin.json 里声明工具 + 写一个处理函数。
第 1 步:声明
{
"extends": {
"ai": {
"main": "dist/ai-tools.js",
"tools": [
{
"name": "evaluate",
"description": "计算一行数学算式并返回结果。支持 + - * /、括号、小数、百分号、^ 乘方。",
"inputSchema": {
"type": "object",
"properties": {
"expression": { "type": "string", "description": "要计算的算式,如 (3.5*2)/7" }
},
"required": ["expression"]
},
"annotations": { "readOnly": true }
}
]
}
}
}| 字段 | 说明 |
|---|---|
main | 处理函数所在的入口文件(.js / .mjs),所有工具共用;单个工具也可以写自己的 main |
tools[].name | 工具名:小写字母开头,只含小写字母、数字、下划线;插件名_工具名 不超过 60 个字符 |
tools[].description | 给 AI 看的说明,写清楚能做什么、参数长什么样,最多 1024 个字符。AI 靠它决定什么时候调用 |
tools[].inputSchema | 参数的 JSON Schema,顶层必须是 "type": "object"。lingtools 调用前按它校验,不合格不会调用插件 |
tools[].outputSchema | 返回值的 JSON Schema,可选;写了就必须返回符合它的对象 |
tools[].annotations | readOnly(只读,不改任何东西)、destructive(可能删除或覆盖数据)。AI 客户端据此决定是否请用户确认 |
一个插件最多 64 个工具,工具只能在这里声明,不能运行时新增。
第 2 步:写处理函数
有两种写法,选一种即可。
写法一:入口文件导出(推荐)
在 main 指向的文件里,导出与工具同名的函数:
// src/ai-tools/index.ts,构建为 src-ling/dist/ai-tools.js
import { createAiTool } from '@lingtools/plugin-sdk'
export const evaluate = createAiTool<{ expression: string }>((input, ctx) => {
const result = calculate(input.expression)
if (result === null) throw new Error('算式不完整')
return { expression: input.expression, result }
})函数在 lingtools 内嵌的轻量 JS 引擎里执行,不会打开插件,速度快。它能调用 ling.*(照常检查权限)和 fetch,但没有 DOM 和 Node。createAiTool 只是帮你获得类型提示,不用它直接导出函数也可以。
入口文件要单独打成一个 ES module,import 只能用相对路径,依赖要一起打包进去:
// vite.ai-tools.config.ts
import { defineConfig } from 'vite'
export default defineConfig({
build: {
outDir: 'src-ling/dist',
emptyOutDir: false,
target: 'es2022',
lib: { entry: 'src/ai-tools/index.ts', formats: ['es'], fileName: () => 'ai-tools.js' },
},
})写法二:在页面或 Node 后端里注册
工具需要用到插件页面的状态或 Node 后端时,在页面加载时注册:
await window.ling.registerTool('evaluate', async (input, ctx) => {
return { result: await window.services.compute(input.expression) }
})插件没在运行时,lingtools 会在后台启动它(不显示界面、不触发 onPluginEnter),最多等 5 秒让它注册。所以要在页面一加载就注册,不要等用户操作。入口文件里有同名导出时,导出优先。
返回值
| 返回 | AI 收到 |
|---|---|
| 字符串 | 文字 |
| 普通对象 | 结构化结果(同时附 JSON 文字) |
| 数组、数字、布尔 | JSON 文字 |
ling.ai.toolResult({ text, images }) | 文字和图片(图片为 data:image/png;base64,… 等) |
| 抛出错误 | 错误结果,错误信息交给 AI |
结果序列化后不超过 10 MiB。
上下文 ctx
| 成员 | 用途 |
|---|---|
ctx.signal | 调用被取消(AI 客户端取消、超过 60 秒、插件停止)时触发;传给 fetch 或在循环里检查 |
ctx.progress(current, total?, message?) | 报告进度 |
ctx.elicit(message, schema) | 中途问用户一个问题(客户端支持时)。等待回答的时间不计入 60 秒。不要用它索要密码、密钥 |
ctx.canElicit | 这次调用能否提问 |
ctx.tool | 工具名,一个函数处理多个工具时用来区分 |
ctx.source | 'mcp'(AI 客户端)或 'test'(开发者工具测试页) |
单次调用最长 60 秒(不含等用户回答的时间)。
测试
不用连 AI 客户端:在开发者工具里打开项目详情,进入「AI 工具测试」,填参数直接执行,能看到进度、提问和返回结果。
注意事项
- 用户打开 MCP 服务就等于授权 AI 调用所有工具,lingtools 不会逐次确认。会删除或覆盖数据的工具,标上
destructive: true,必要时用ctx.elicit让用户确认。 description是 AI 唯一的使用说明,写得越具体,AI 调用得越准。