插件开发指南

最小可导入插件

建立 review-helper 文件夹，把下面的文件保存为 plugin.json。文件夹名须与 id 一致。

{
  "manifestVersion": 1,
  "id": "review-helper",
  "name": "代码审查助手",
  "version": "1.0.0",
  "description": "为代码审查提供一个可编辑的任务草稿。",
  "permissions": [],
  "commands": [
    {
      "id": "review",
      "title": "审查当前修改",
      "prompt": "检查当前项目的修改，先说明正确性风险，再给出有证据的改进建议。需要修改文件时先说明计划。"
    }
  ],
  "sandbox": {
    "mode": "declarative"
  }
}

下载这个示例 · 查看 JSON Schema

从桌面端“插件”页导入文件或文件夹，审查并启用后使用命令。命令会填入可编辑的任务草稿，不会自动发送任务。

清单字段与贡献类型

id、name、version 必填。推荐声明 manifestVersion: 1 和 sandbox.mode: "declarative"。ID 为 1–64 个字母、数字或连字符，且以字母或数字开头。版本使用语义化版本。

插件采用声明式沙箱。客户端不会执行插件包内的 JavaScript、原生代码或 DSH 的 apply() 生命周期。扩展新工具应使用 MCP 接入。

权限与凭据

支持的权限名称如下；贡献所需权限必须同时包含在插件根级声明中。工具执行时仍受任务权限和审批约束。

workspace.read    workspace.write
shell.execute     network.access
credentials.read  mcp.start
git.read          git.write
artifact.read     artifact.write

插件工具别名的权限须与目标内置工具完全匹配。MCP 贡献的 permissions 须恰为 ["mcp.start"]，根级也须包含它。

不要把密钥写入 plugin.json。MCP 的 environment 只声明 name、label、description、required、secret；用户在桌面端配置实际值。凭据由系统安全存储保护，按需传给服务进程。

验证与发布

下载的 JSON Schema 可用于编辑器提示；客户端的实际校验器是最终依据。若你有 CodeAgent 源码和已安装的开发依赖，可在仓库根目录运行：

pnpm plugin:validate -- ./review-helper

此命令不是桌面安装包提供的终端命令。没有源码开发环境时，可以从插件页导入，通过预览查看校验结果。

1. 验证 plugin.json，检查 ID、贡献引用和权限。
2. 在桌面端导入、启用，并在测试项目执行目标任务。
3. 发布包含根级 plugin.json 的文件夹或公开 GitHub 仓库。
4. 让用户通过文件、文件夹或公开仓库发现流程导入，并重新审查。

你可以在 插件市场 下载官方插件与 Skill，或搜索公开 GitHub 仓库。当前不提供开发者自动上架、私有仓库凭据接入或自动升级机制。远程发现会固定仓库 revision 并校验内容；更新仍需用户重新导入和审查。

导入边界与常见错误

清单最大 64 KiB；文件夹最多 128 个常规文件、总计 8 MiB、8 层子目录；不接受符号链接，忽略 .git 和 node_modules。项目最多发现 64 个插件。审查令牌绑定项目、单次使用，有效期 5 分钟。

阅读完整 SDK 参考与签名说明 →