WebCodex Native Tool Plugins 教程:不用写 MCP Server,把任意本地程序变成 AI 可调用的工具
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、显示名、可执行程序、参数和工作目录即可保存:
也可以直接在 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 与活动信号:
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 会报告 OutcomeUnknown 而绝不自动重试,避免误删、误写被执行两次。
📚 更多示例与延伸阅读
仓库自带了几个可直接参考的 first-party Plugin:
- plugins/repo-info/:只读
git_summary工具,最适合学习 SDK 开发闭环; - plugins/safe-delete/:把文件移入系统回收站的有副作用 Plugin;
- plugins/campus-application/:浏览器语义快照转简历填写计划,展示复杂业务流封装。
架构细节(执行权威划分、开发阶段规划)可查阅 docs/architecture/native-tool-plugins.md,完整操作手册见 docs/PLUGINS.md。现在打开终端跑一下 webcodex plugin init,五分钟就能让 AI 用上你的第一个本地工具 🎉


