常见问题

---

该做插件还是场景？

看你要交付什么：

你的目标	选择
给平台加一个能力，让所有场景都能用	插件
做一套完整的 AI 应用（角色 + 对话流 + 界面）给用户用	场景
已有一个 MCP Server，想接入平台	插件（type: mcp）
想让 AI 在对话中调用某个 API	插件（工具）被场景引用

两者的清单文件、运行位置、发布接口都不同，详见插件开发概述。

---

开发

Q1：插件能用第三方 npm 包吗？

分情况：

模式	第三方依赖
in-process	可以，但需自行把依赖打包进 index.js（用 esbuild 打成单文件），因为 node_modules 不会随包分发
stdio（本地入口）	需在插件目录安装依赖，但打包排除了 node_modules，需用户手动安装或同样内联打包
stdio（ConfigOnly）	由 npx / uvx 在用户机器上拉取，无需自带

宿主已注入的能力（sharp、z、MCP SDK 等）直接用，不要重复安装。

Q2：为什么 in-process 插件不能 import @modelcontextprotocol/sdk？

客户端已内置一套 SDK 实例，自行引入会出现两份不同的协议实现，导致 McpServer 与传输层实例不匹配。统一从 globalThis.__AWEECLAW_HOST__ 取：

const { McpServer, InMemoryTransport, z } = globalThis.__AWEECLAW_HOST__

Q3：name / nameZh 是必填的吗？

是。name / nameZh / description / descriptionZh 四项都必填，双语信息用于市场展示与客户端界面。

Q4：图标怎么设置？

三种写法，发布脚本自动识别：

写法	示例	处理
Lucide 图标名	"Package"	透传，客户端按名渲染
远程 URL	"https://example.com/icon.png"	透传
本地相对路径	"icon/icon.png"	发布时上传，后端转 base64 存 icon 字段

本地图标规范：icon/ 目录下放 icon.png，PNG / JPEG / SVG / WebP，≤ 256KB，建议 128×128。

Q5：工具调用超时怎么调？

默认单次调用 30 秒。长任务在 manifest 显式放大：

{
  "capabilities": {
    "mcp": { "transport": "in-process", "timeout": 660000 }
  }
}

660000 即 11 分钟，适合视频生成这类任务。

---

调试

Q6：插件安装后无法连接

按顺序排查：

1. capabilities.mcp.command 是否可用（node / npx / uvx 是否在 PATH）
2. args 中的 pluginDir 变量是否写对（会被替换为实际安装目录）
3. 必填的 configSchema 字段用户是否已填写（决定环境变量是否注入）
4. in-process 插件确认工厂函数正确导出且未在顶层抛异常
5. 客户端「设置 → MCP 服务」查看连接错误日志

Q7：如何调试已安装的插件？

• in-process：看客户端「设置 → MCP 服务」的连接状态与日志
• stdio：可直接手工运行

cd ~/Library/Application\ Support/AweeClaw/plugins/my-plugin/1.0.0
API_KEY="your-key" node index.js

完整手段见本地调试。

Q8：UI 组件不显示

90% 是以下三种情况：

1. 改了 ui-src/ 但没重新构建 ui.js
2. contributes 里的 component 键与 ui.js 导出映射的键大小写不一致
3. 漏了 ui.render 权限

Q9：UI 构建报 Cannot find module 'react'

ui-src 的类型解析依赖 tsconfig.json 中的 paths 映射，指向 ../aweeclaw-client/node_modules。确保客户端仓库与本仓库同级存在。

运行时共享依赖从 window.__AWEECLAW_SHARED__ 读取，不需要在插件 package.json 声明 react 等依赖。

---

发布

Q10：上传报 manifest.id does not match plugin.pluginKey

包内 manifest.json 的 id 必须与插件 pluginKey 完全一致（大小写敏感）。发布后再改 pluginKey 是不可能的 —— 只能删除重建。

Q11：上传报 manifest.version does not match requested version

manifest.json 的 version 必须与上传时带的 version 参数一致。用脚本发布时若传了 --version，注意与 manifest 保持一致（或干脆不传，脚本从 manifest 读取）。

Q12：type 改了之后发布失败

type 创建后不可变（后端 UpdatePluginDto 不支持）。需在管理后台删除原插件后重新发布；publish-all-plugins.mjs 会自动处理（检测到 type 不匹配时删除重建）。

Q13：MinIO/S3 不可达导致上传失败

发布脚本会自动降级为内联代码模式：把 index.js 内容写入 manifest.inlineCode、UI bundle 写入 manifest.inlineUiCode，通过 create-version 接口直接存数据库，客户端安装时还原为本地文件。无需手动干预。

也可以主动使用 direct 模式：

node scripts/publish-all-plugins.mjs --token $AWEECLAW_ADMIN_TOKEN --direct

Q14：发布了为什么市场搜不到

发布路径	可见条件
开发者中心	插件与版本都需管理员审核通过（reviewStatus: approved）
管理端脚本	创建即上架

开发者可在开发者中心用 reviewStatus 过滤查看审核状态。

Q15：用户怎么拿到新版本？

客户端按版本安装。发布新版本（递增 manifest.version）后，用户在插件详情触发更新即可拉取新版本；旧版本目录保留在 plugins/<pluginKey>/<旧版本>/。

Q16：如何批量重新生成官方插件目录

# 编辑 scripts/plugins-data.mjs 中的 PLUGIN_LIST
node scripts/generate-plugins.mjs

该脚本会清理 mcp-* 与 util-* 前缀目录后重新生成（保留 computer-use 等非前缀插件）。

---

安全

Q17：密钥安全如何保障？

• configSchema 中 secret: true 的字段通过系统安全存储保存（macOS Keychain / Windows Credential Manager / Linux Secret Service），不落盘明文
• 密钥仅通过环境变量注入 stdio 子进程内存，或经 ctx.getSecret() 提供给 in-process 插件
• 后端不存储用户密钥，密钥仅存在于用户本机

Q18：插件能不能直接访问 Electron API？

不能。UI 组件只能通过 props.host 暴露的 PluginHostApi 访问能力（callTool / getConfig / sendChatMessage / log），不会拿到 window.electronAPI。

原生能力访问走 manifest.permissions 声明 + ctx.host 受限代理，未声明的能力访问会抛 PermissionDeniedError。

Q19：权限声明是必须的吗？

访问方式	是否校验权限
ctx.host（推荐）	校验，未声明即拒绝
globalThis.__AWEECLAW_HOST__（兼容）	不校验

新插件应声明 permissions 并使用 ctx.host，既符合最小权限原则，也便于审核。

---

还有问题？

• 查阅本地调试的失败排查表
• 在 GitHub Issues 反馈