开发插件

插件包包含插件清单、文件清单、实现文件和用户文档。先获取唯一的发布者命名空间，并按插件规范设置版本号。

在 capabilities 中声明全部能力及其主机、端口和密钥槽位约束。
校验实际使用的配置字段，忽略无关字段。
生成可复现的插件包和文件摘要。
排除凭据、个人路径、构建缓存和运行数据。
测试成功、失败、权限不足和插件包无效等场景。

开发工具与打包

开发工具 @gamex/plugin-tools 提供 gamex-plugin CLI，要求 Node.js 22.13.0 或更高版本。源码位于 Registry 仓库的 plugins/tools，从仓库构建并以本地 npm 归档分发。

在 gamex-registry 根目录安装依赖后运行：

npm --prefix plugins run build
npm --prefix plugins run test

在 plugins/tools 目录运行 npm pack，将生成的工具归档安装到插件工程后使用：

npm install --no-save /path/to/gamex-plugin-tools-<version>.tgz
npx --no-install gamex-plugin pack ./files --output /tmp/my-plugin.gxplugin
npx --no-install gamex-plugin validate /tmp/my-plugin.gxplugin

将路径和版本替换为实际生成结果。输出必须位于输入目录之外，且不能覆盖已有归档。打包器生成 META-INF/gamex.files.json，开发工具、依赖目录和运行数据不入包。

图标与工作区视图

metadata.icon 用于插件市场和已安装插件列表。contributions.panels[].icon 用于工作区标签页，两者独立设置，不会自动继承。路径相对于包根目录，图片须为 PNG 或 WebP，每张不超过 512 KiB，未设置面板图标时使用默认拼图图标。

在 contributions.panels 中声明视图，并在 requires.features 中加入 panel-ui/v1：

json

{
  "icon": "panel-icon.png",
  "id": "server-tools",
  "path": "ui/panel.mjs",
  "style": "ui/panel.css",
  "title": "服务器工具"
}

将 React、ReactDOM 和其他依赖打包到浏览器 ESM 中，导出 mount(container, context)，返回同步清理函数。宿主不提供 HTML 或 iframe；CSS 使用插件专属类名前缀。

Context 接口	用途
`installationId`、`workspaceId`	当前插件安装和工作区
`toast.error/success/info/warning(message)`	显示宿主全局提示
`request(path, options)`	按当前用户权限调用同源面板 API，返回响应的 `data`
`callTool(serverId, toolName, arguments)`	调用当前插件的普通 MCP 工具
`authentication(serverId, action)`	查询或管理共享账号连接，操作为 `status/start/cancel/disconnect`

标签页隐藏后已访问的视图仍保持挂载，不要把隐藏视为卸载。切换工作区或版本等导致卸载时，清理 React root、订阅、定时器和弹窗，宿主会取消通过 Context 发起的请求并清除该视图的提示。

配置与会话范围

普通配置须为对象，Schema 使用宿主支持的 JSON Schema 子集。additionalProperties: false 会清除未声明字段；未提供配置 Schema 时，宿主将配置归一为 {}。支持的属性默认值会在归一时补入，但仍须验证最终配置，不要依赖任意分支或引用下的完整自动补全。秘密使用独立 Secret 槽位。

MCP 的 agentScope 默认为 workspace，也可设置为 panel，服务仅出现在相同类型的会话中。需要文件、Shell 或安装操作的技能，应在工作区会话执行。面板会话可先选定或创建工作区，再使用 workspace_handoff 创建共享工作区对话并交接任务，只传递用户打算共享的完整任务摘要。

包内辅助文件的路径与 SHA-256 摘要由 plugin_skills_read 的 packageFiles 返回。使用 plugin_file_import 的 area=package 可按正常写入授权和审批导入已验证文件，不覆盖已有文件；导入脚本不会执行脚本。

运行与数据隔离

本地 MCP 以面板服务账号运行，没有操作系统沙箱。hosts、ports 只限制远程 MCP 连接端点，不限制本地程序自行访问主机或网络。
普通配置可进入技能上下文和 PLUGIN_CONFIG，不可存放凭据。安装级 Secret 由面板加密保存，按声明和授权注入。
认证文件存入 PLUGIN_DATA/.private，不得通过工具结果、公开 data 或视图资源返回。持久数据按安装隔离，不会自动按用户或工作区隔离。
React 视图是受信任的同源模块，没有 iframe 沙箱。request 使用当前用户权限；MCP 和账号操作还会检查当前版本与访问设置。
视图直接操作不进入 AI 审批队列。AI 调用的普通 MCP 工具仅在声明 annotations.readOnlyHint: true 时按读取处理；工作区密钥写入始终要求人工审批。

外部聊天事件

声明 panel-events/v1、mcp/v1，申请 panel.mcp.connect 与 panel.thread.control，并为工作区 MCP 服务配置名称互不相同的 receive、send 和可选 poll 工具。这些内部工具不向 AI 展示，也不能通过视图的 callTool 调用。宿主负责绑定确认、权限、审批与任务执行；插件负责校验提供方消息并处理收发。

发出的审批和问题交互包含请求 ID、正整数修订号及获准操作的成员标识。记录交互控件时保留修订号，并按投递 ID 去重发送。轮询可附带来源名称等可选展示信息。

回调、轮询、持久化与绑定接口见面板事件协议。

提交发布

在 GameX Registry 登录具备发布权限的账号。
上传已验证的 .gxplugin 包，检查包名、版本和权限声明，再提交审核。
在发布者页面查看结果；页面保持可见时会自动更新审核状态。

审核通过的版本不可覆盖，后续修改必须使用新版本号。开发规范和示例位于 Registry 仓库的 plugins/docs/，本地工具位于 plugins/tools/。

开发插件 ​

开发工具与打包 ​

图标与工作区视图 ​

配置与会话范围 ​

运行与数据隔离 ​

外部聊天事件 ​