Skip to content

给 AI 提供工具 ​

把插件的功能声明成「工具」,用户在 Claude Code、Cursor 等 AI 客户端里就能让 AI 调用它。比如计算稿纸提供「计算算式」,AI 需要精确计算时就会调用。

原理 ​

lingtools 内置一个 MCP 服务(用户在 设置 →「MCP」 里打开)。AI 客户端连上后,除了 lingtools 自带的工具,还能看到每个插件声明的工具,名字是 <插件名>_<工具名>。AI 调用工具时,lingtools 校验参数,再执行插件的处理函数,把结果交回给 AI。

插件不需要自己实现 MCP 协议,只要:在 plugin.json 里声明工具 + 写一个处理函数。

第 1 步:声明 ​

json
{
  "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[].annotationsreadOnly(只读,不改任何东西)、destructive(可能删除或覆盖数据)。AI 客户端据此决定是否请用户确认

一个插件最多 64 个工具,工具只能在这里声明,不能运行时新增。

第 2 步:写处理函数 ​

有两种写法,选一种即可。

写法一:入口文件导出(推荐) ​

在 main 指向的文件里,导出与工具同名的函数:

ts
// 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 只能用相对路径,依赖要一起打包进去:

ts
// 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 后端时,在页面加载时注册:

ts
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 调用得越准。