本地调试

插件运行在客户端内，调试手段与纯 Node 项目不同。本篇按"能在本地验证的"与"必须装载进客户端才能验证的"两类给出方法。

---

调试手段速查

模式	本地可验证	完整验证
in-process	node --check 语法检查	装载进客户端，看「设置 → MCP 服务」
stdio（本地入口）	MCP Inspector、手工 JSON-RPC	同上
stdio（外部包）	直接命令行跑一次 command	同上
sse	curl 探测端点	同上
UI 扩展	node scripts/build-ui.mjs 构建通过	客户端界面实际渲染

---

通用：语法与静态检查

发布脚本上传前会执行这一步，本地先跑能省一轮往返：

cd plugins/my-plugin
node --check index.js

ESM 模块的导入是否有问题，可以再跑一次真实导入：

node -e "import('./index.js').then(() => console.log('module ok')).catch(e => { console.error(e); process.exit(1) })"

对 in-process 插件，这条命令会因缺少 globalThis.__AWEECLAW_HOST__ 而报错退出，属预期行为 —— 它只验证语法与顶层导入是否成立。

---

in-process 插件

in-process 插件无法脱离客户端独立运行，调试依赖客户端运行环境。

1. 装载进客户端

1. 发布插件（或直接替换本地安装目录中的 index.js）
2. 重启客户端，或重新连接该 MCP 服务
3. 打开「设置 → MCP 服务」，确认插件状态为已连接

2. 观察调用

• 在对话中让智能体调用你的工具，观察工具返回是否符合预期
• 插件内的 logger.system.info(...) / console.error(...) 输出会进入客户端日志

3. 快速迭代

改了 index.js 之后：

改什么	生效方式
插件代码逻辑	替换本地安装目录文件后重启客户端（或重新发布递增版本）
manifest.json	重新发布；已安装的配置表单以本地 manifest 为准
ui-src/	重新构建 ui.js，替换后重启客户端

客户端按 plugins/<pluginKey>/<version>/ 管理安装目录，直接改本地目录只影响本机调试，不会同步回后端。

---

stdio 插件

MCP Inspector（推荐）

官方可视化调试器，可列出工具、填参数、查看原始响应：

cd plugins/my-mcp
API_KEY="your-test-key" npx @modelcontextprotocol/inspector node index.js

手工发一帧初始化请求

cd plugins/my-mcp
export API_KEY="your-test-key"
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node index.js

正常情况会看到 JSON-RPC 响应；若返回空或抛出错误，先检查：

1. 必填配置对应的环境变量是否已导出
2. 是否存在 console.log 污染 stdout（日志必须走 stderr）

外部包（ConfigOnly）

直接按 capabilities.mcp 里的命令跑一遍，验证包能否启动：

npx -y @modelcontextprotocol/server-brave-search

若卡住无输出属正常（等待 stdio 输入）；若报网络或找不到包，说明用户环境不具备拉包条件。

---

UI 扩展

构建

node scripts/build-ui.mjs my-plugin

构建成功会在插件根目录生成 ui.js。构建失败常见于：

报错	原因
Cannot find module 'react'	tsconfig.json 的 paths 指向 ../aweeclaw-client/node_modules，客户端仓库需与本仓库同级
ui-src/index.tsx 不存在	插件未创建 ui-src/ 目录，或文件名不符
JSX 语法错误	检查 .tsx 中未闭合标签或类型断言写法

运行时排错

组件不显示时按顺序检查：

1. manifest.permissions 是否包含 ui.render
2. contributes.ui.entry 是否为 ui.js
3. contributes.xxx[].component 的键是否与 ui.js 导出映射的键完全一致（大小写敏感）
4. ui.js 是否已重新构建（改了源码没构建是最常见原因）
5. 客户端日志中是否有 [Plugin:<pluginKey>] 前缀的错误输出

组件抛出的异常会被客户端错误边界捕获，不会导致整个界面崩溃，因此务必在 catch 中调用 host.log.error，否则错误无处可查。

---

安装目录与日志

安装目录

平台	插件目录
macOS	~/Library/Application Support/AweeClaw/plugins/<pluginKey>/<version>/
Windows	%APPDATA%\AweeClaw\plugins\<pluginKey>\<version>\
Linux	~/.config/AweeClaw/plugins/<pluginKey>/<version>/

安装记录：plugins/installed.json。

日志

来源	位置
客户端运行日志	用户数据目录下的 logs/
MCP 连接状态与调用	客户端「设置 → MCP 服务」
插件内日志	同上（in-process 插件经 logger 输出）

---

失败排查表

现象	优先排查
插件安装后列表里没有	插件或版本是否已通过审核（开发者提交默认 pending）
显示已安装但连不上	command 是否可用（node / npx / uvx 是否在 PATH）
工具列表为空	ListToolsRequestSchema 未注册，或工厂函数未正确返回 { server, clientTransport }
调用报参数错误	参数 schema 与 handler 取值方式不匹配（args.xxx 拼写、类型）
调用 30 秒中断	长任务需放大 capabilities.mcp.timeout
配置改了没生效	修改配置后需要重新连接；确认 configSchema.fields[].key 与代码读取的变量名一致
密钥读不到	字段是否标了 secret: true；stdio 读 process.env，in-process 读 ctx.getSecret()
发布报版本冲突	manifest.version 已存在，递增后重发

---

下一步

• 打包与发布 — 发布与版本管理
• 常见问题 — 更多踩坑记录