WebCodex Native Tool Plugins 教程:不用写 MCP Server,把任意本地程序变成 AI 可调用的工具

原创2026-10-15 20:58:491,349 阅读
文章标签:人工智能AI AgentMCP 服务工具调用本地部署后端桌面应用CLI

WebCodex Native Tool Plugins 教程:不用写 MCP Server,把任意本地程序变成 AI 可调用的工具

在 WebCodex 中使用 Native Tool Plugins,你可以把任意本地程序变成 AI 可调用的工具——不需要实现 MCP Server,也不依赖 MCP SDK。一个能读 stdin、写 stdout 的可执行程序(Node.js、Python、Rust、Go 二进制均可),加上几行配置,就能被云端 AI Agent 通过你本地的 WebCodex Runner 安全调用。本教程会带你完成从零编写、注册到让 AI 真正调用的完整流程。

🧩 什么是 Native Tool Plugin:本地程序即 AI 工具

Native Tool Plugin 允许 WebCodex Runner 把一个受信任的本地可执行程序暴露为工具集。协议很简单:基于 stdin/stdout 的换行分隔 JSON-RPC 2.0(协议版本 webcodex-plugin-v1),只需要支持三个方法:

  • initialize:握手,声明协议版本;
  • tools/list:声明你提供的工具及参数 Schema;
  • tools/call:执行工具并返回结果。

Plugin 进程只运行在 Runner 所在机器上。Server 不会收到它的命令、参数、工作目录、环境、PID、stderr 或本地凭据,天然适合封装"只有在你本机才能执行"的能力。

⚠️ 注意:Native Plugin 是受信任的本地进程。WebCodex 不做沙箱或签名隔离,它的信任级别等同于你直接运行这个程序。

🆚 和 MCP Server 有什么区别

对比项 MCP Server WebCodex Native Tool Plugin
需要引入 MCP SDK 是 否
工具注册位置 全局 MCP 工具命名空间 Runner 本地,按 provider 隔离
进程归属 需要自行管理 由 Runner 启动、超时、回收
权限体系 依赖宿主 plugin:inspect / plugin:invoke / plugin:manage 细粒度授权

核心思想是:Runner 是唯一的执行权威。Plugin 工具不会加入 Server 全局工具命名空间,也不会和 WebCodex 内建工具撞名;AI 统一通过一等工具 plugin_tool 走 list → describe → call 的标准路径调用。

🚀 快速上手:一个零依赖的最小示例

仓库里就带了一份无需任何第三方依赖的参考实现 examples/native-tool-plugin.mjs(约 110 行),声明了 echo 和 add 两个工具。核心结构长这样:

const tools = [
  {
    name: "echo",
    description: "Echo one string",
    inputSchema: {
      type: "object",
      properties: { text: { type: "string" } },
      required: ["text"],
      additionalProperties: false,
    },
  },
];

// 每收到一行 JSON-RPC 请求,处理 initialize / tools/list / tools/call

如果你偏好 Python,还有一份仅用标准库的 plugins/examples/python-raw/plugin.py 示例,可以直接照着改。

🛠️ 用官方 CLI 生成项目:webcodex plugin init

不想手写协议样板?WebCodex CLI 提供了本地脚手架生成命令:

webcodex plugin init ./my-plugin

它会生成一个确定性 TypeScript/ESM 项目(package.json、tsconfig.json、src/plugin.ts 等),精确依赖 npm 上公开发布的 @yyjeqhc/webcodex-plugin-sdk@0.1.0。配合官方 SDK,写一个工具就像这样(见 npm/plugin-sdk/README.md):

const echo = defineTool({
  name: "echo",
  description: "Echo one string",
  inputSchema: schema.object({
    text: schema.string({ minLength: 1, maxLength: 4096 }),
  }),
  async execute({ text }) {
    return textResult(text, { text });
  },
});

runPlugin(definePlugin({ tools: [echo] }));

完整的 SDK 示例可参考 npm/plugin-sdk/examples/echo-plugin.ts。

💡 两个细节:stdout 只能输出协议 JSON,日志请写到 stderr;构建产物是 dist/plugin.js,Runner 执行的是编译后的 JavaScript。

📋 注册 Plugin:Desktop 界面与 runner.toml

在 Desktop 中打开 Extensions → Native Plugins,通过 Add a native Tool Plugin 填 Plugin ID、显示名、可执行程序、参数和工作目录即可保存:

WebCodex 桌面端扩展页面中注册 Native Tool Plugin 的表单界面

也可以直接在 Runner 启动时读取的 runner.toml 中配置:

[[plugins.providers]]
id = "repo-tools"
name = "Repo Tools"
command = "node"
args = ["/absolute/path/to/plugin.js"]
cwd = "/absolute/path/to/your-repo"
timeout_secs = 30

其中 id、name、command 必填,cwd 必须是绝对路径。Plugin 会复用 Runner 的 shell profile 环境(PATH、init script 等),敏感凭据会被自动过滤。

🔁 标准开发闭环:check → reload → list → describe

改完代码后,不需要重启整个 Runner,用 CLI 一条一条走即可(详细语义见 docs/PLUGINS.zh-CN.md):

webcodex plugin check --runner special --plugin repo-info   # 预检:真实启动候选进程做协议校验
webcodex plugin reload --runner special                     # 原子热加载整个 provider 集合
webcodex plugin list --runner special --plugin repo-info    # 查看工具清单
webcodex plugin describe --runner special --plugin repo-info --tool git_summary

各命令的语义值得记住:

  • check:Runner 会真实启动一个一次性候选进程,完成 initialize + tools/list 校验后销毁,不会污染当前运行的 provider;
  • reload:重新读取 runner.toml,全部候选通过才原子替换,任何一个失败则旧集合原样保留,老 binding 自动失效;
  • describe:返回一个不透明 binding(形如 wc_pbind_...),后续 call 只认这个 binding。

这套机制保证了调试坏掉的 Plugin 时不会搞挂正在服务的工具。

🤖 AI 会话中实际调用 Plugin 工具

注册完成后,云端 AI Agent 会通过 plugin_tool 网关访问你的本地工具。在 WebCodex 的 Work 界面中,你可以直观看到会话正在 Runner 上执行的 Job 与活动信号:

WebCodex 运行时会话页面,展示 Workflow Session 与 Runner 上正在执行的任务

AI 侧的标准调用序列是:

plugin_tool(action="list", runner="my-runner")          # 看有哪些 provider
plugin_tool(action="describe", ..., tool="git_summary") # 换取 binding
plugin_tool(action="call", binding="wc_pbind_...", arguments={...})

🔐 权限与信任边界

Native Plugin 的权限是按操作细分的:

  • plugin:inspect:只读观察(list / describe);
  • plugin:invoke:执行工具(call);
  • plugin:manage:开发管理操作(check / reload),不隐含 invoke。

在桌面端,敏感操作会像下面这样明确提示并请求授权,Plugin 的有副作用调用还会走同样的 Workflow Session 守卫:

WebCodex 桌面端弹出权限申请对话框,逐项请求 Screen Recording 与 Accessibility 授权

另一个安全设计:对"可能已产生副作用"的调用,如果发送后连接断开,WebCodex 会报告 OutcomeUnknown 而绝不自动重试,避免误删、误写被执行两次。

📚 更多示例与延伸阅读

仓库自带了几个可直接参考的 first-party Plugin:

架构细节(执行权威划分、开发阶段规划)可查阅 docs/architecture/native-tool-plugins.md,完整操作手册见 docs/PLUGINS.md。现在打开终端跑一下 webcodex plugin init,五分钟就能让 AI 用上你的第一个本地工具 🎉

登录后查看全文
webcodex