快速开始
本篇带你从零做出一个可运行的插件：一个统计文本字数的工具型插件（text-stats），注册为 MCP 工具供智能体调用。
完整流程约 5 分钟。需要 Node.js ≥ 18，以及
aweeclaw-plugins与aweeclaw-client两个仓库同级存放。
第 0 步：准备工作区
bash
cd aweeclaw-plugins
npm install # 安装 esbuild / typescript插件源码目录统一放在 plugins/，目录名与 manifest.id 一致。
第 1 步：创建插件目录
bash
mkdir -p plugins/text-stats也可以直接复制模板：
bash
cp -r templates/mcp-plugin plugins/text-stats第 2 步：编写 manifest.json
json
{
"id": "text-stats",
"name": "Text Stats",
"nameZh": "文本统计",
"description": "Count characters, words and lines of given text.",
"descriptionZh": "统计文本的字符数、词数与行数。",
"type": "tool",
"version": "1.0.0",
"main": "index.js",
"icon": "Hash",
"category": "utility",
"tags": ["text", "utility"],
"capabilities": {
"mcp": {
"transport": "in-process",
"autoConnect": true
}
},
"configSchema": { "fields": [] },
"permissions": [],
"platforms": ["darwin", "win32", "linux"],
"license": "MIT"
}几个约定：
id必须匹配^[a-z][a-z0-9-]*$，且发布后不可修改（对应后端pluginKey）。version使用 semver，每次发新版都要递增。type: tool+transport: in-process表示代码加载进客户端主进程运行。main非空 → 走 Tarball 分发模式（详见打包与发布）。
字段含义详见 manifest 清单配置。
第 3 步：编写 index.js
in-process 插件必须导出一个 MCP Server 工厂函数，返回 { server, clientTransport }：
javascript
/**
* Text Stats 插件 - 文本统计工具
*/
function getHost() {
const host = globalThis.__AWEECLAW_HOST__
if (!host) throw new Error('Host services not available. globalThis.__AWEECLAW_HOST__ is not set.')
return host
}
// Host 注入的 MCP 运行时（McpServer / InMemoryTransport / zod）
const { McpServer, InMemoryTransport, z } = getHost()
function text(t) {
return { type: 'text', text: String(t) }
}
export function createMcpServer() {
const server = new McpServer(
{ name: 'text-stats', version: '1.0.0' },
{
capabilities: { tools: { listChanged: false } },
instructions: 'Count characters, words and lines of a given text.',
},
)
server.tool(
'text_stats',
'Count characters, words and lines of the given text',
{
text: z.string().min(1).describe('The text to analyze'),
ignoreWhitespace: z.boolean().default(false).describe('Exclude whitespace when counting characters'),
},
async (args) => {
const raw = args.text
const chars = args.ignoreWhitespace ? raw.replace(/\s/g, '').length : raw.length
const words = raw.trim() ? raw.trim().split(/\s+/).length : 0
const lines = raw.split(/\r\n|\r|\n/).length
return {
content: [text(`characters: ${chars}\nwords: ${words}\nlines: ${lines}`)],
}
},
)
const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
server.connect(serverTransport).catch(() => {})
return { server, clientTransport }
}要点：
- 不要
import外部@modelcontextprotocol/sdk。in-process 插件的McpServer、InMemoryTransport、z（zod）全部来自 Host 注入的globalThis.__AWEECLAW_HOST__，自行引入会造成版本冲突。 - 工厂导出名可以是
default、createMcpServer或create，客户端按此顺序识别。 - 返回值必须是
{ server, clientTransport }，客户端用clientTransport建立进程内通道。 - 工具错误不要抛异常，返回
isError: true的结果，智能体才能读到失败原因。
第 4 步：声明 ESM
package.json：
json
{
"name": "text-stats",
"version": "1.0.0",
"type": "module"
}"type": "module" 必须声明，否则 export 语法在 Node 下会直接报错。
第 5 步：本地自检
in-process 插件依赖客户端注入 Host，无法脱离客户端独立运行，但可以先做语法与静态检查：
bash
cd plugins/text-stats
node --check index.js发布脚本上传前也会跑这一步；语法错误会直接中断发布。
想完整验证工具行为，把插件装载进客户端后，在「设置 → MCP 服务」里查看连接状态，让智能体实际调用一次工具。
第 6 步：发布
方式一：开发者中心（推荐给第三方开发者）
- 登录 开发者中心，完成实名认证（未实名无法发布）。
- 在「我的插件」中发布插件，
pluginKey填写与manifest.id完全一致的值（text-stats）。 - 上传打包好的
text-stats-1.0.0.tar.gz。 - 等待管理员审核，审核通过后出现在插件市场。
方式二：命令行脚本（平台自研 / 批量发布）
bash
export AWEECLAW_BACKEND_URL="https://gateway.aweeclaw.com"
export AWEECLAW_ADMIN_TOKEN="<管理员 JWT>"
node scripts/publish-plugin.mjs plugins/text-stats \
--changelog "Initial release"先预演打包（不上传）：
bash
node scripts/publish-plugin.mjs plugins/text-stats --skip-upload两条路径的区别：开发者中心提交的插件与版本一律进入待审核状态；管理端接口创建即上架。详见打包与发布。
第 7 步：安装验证
在客户端插件中心搜索「文本统计」→ 安装 → 在对话中让智能体"统计这段文字的字数"。
安装后的文件位置：
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/Application Support/AweeClaw/plugins/text-stats/1.0.0/ |
| Windows | %APPDATA%\AweeClaw\plugins\text-stats\1.0.0\ |
| Linux | ~/.config/AweeClaw/plugins/text-stats/1.0.0/ |
安装记录写在 plugins/installed.json。