Plugin文件结构与manifest规范

一、Plugin的标准目录结构

一个规范的Claude Code Plugin项目应当遵循统一的标准目录结构，以确保可维护性、可读性和兼容性。标准目录结构如下所示：

my-plugin/
├── manifest.json        # 插件清单文件（必需）
├── index.js             # 入口文件（必需）
├── README.md            # 插件说明文档（推荐）
├── LICENSE              # 开源许可证（推荐）
├── lib/                 # 核心逻辑模块目录
│   ├── commands.js      # 命令处理模块
│   └── utils.js         # 工具函数模块
└── assets/              # 静态资源目录
    ├── icon.png         # 插件图标
    └── styles.css       # 自定义样式

manifest.json：插件的清单文件，是Plugin的核心配置文件。它声明了插件的基本信息、入口文件路径、所需权限、依赖关系等元数据。Claude Code会在加载插件时首先读取此文件以验证和初始化插件。

index.js：插件的入口文件，是Plugin执行的起点。该文件需要导出插件的主要功能，包括命令处理器、生命周期钩子函数等。Claude Code通过此文件与插件进行交互。

README.md：插件的说明文档，向用户介绍插件的功能、安装方法、使用示例和配置选项。良好的文档可以显著降低用户的使用门槛。

LICENSE：开源许可证文件，明确插件的使用和分发条款。常见的许可证包括MIT、Apache-2.0、GPL-3.0等。

lib/ 目录：存放核心逻辑代码的模块目录。将不同功能的代码拆分到独立的模块文件中，有助于代码的组织、测试和复用。例如 commands.js 负责命令处理逻辑，utils.js 提供通用工具函数。

assets/ 目录：存放插件的静态资源文件，如图标、样式表、图片等。这些资源在插件加载或运行时被引用。

最佳实践：建议将所有源代码放在 lib/ 目录下，保持根目录整洁。入口文件 index.js 应当尽量精简，只负责导出和初始化，具体逻辑委托给 lib/ 中的模块。

二、manifest.json核心字段

manifest.json 是Plugin的"身份证"，包含了插件的所有关键元数据。以下是各核心字段的详细说明：

name（必需）

插件的唯一名称，在整个Claude Code生态系统中应保持唯一性。命名建议采用小写字母和连字符的组合，如 my-plugin。名称一经发布不应轻易更改，否则可能导致现有用户配置失效。

version（必需）

插件的版本号，必须遵循语义化版本规范（Semantic Versioning，即 semver），格式为 major.minor.patch。主版本号变更表示不兼容的API修改，次版本号变更表示向下兼容的功能新增，补丁号变更表示向下兼容的问题修复。

description

对插件功能的简短描述，用于在插件市场或列表页面中向用户展示。描述应当简洁明了，让用户一眼就能理解插件的核心用途。

main（必需）

指定插件的入口文件路径，相对于插件根目录。Claude Code通过此字段找到并加载插件的执行入口。默认值为 index.js，如果入口文件位于其他路径，需要显式指定。

permissions

声明插件运行所需的权限列表。Claude Code的安全模型要求插件必须明确声明所需的每一项权限，用户在安装时会收到权限提示。未声明的权限在运行时将被拒绝。

dependencies

声明插件所依赖的其他Plugin或外部包。Claude Code会在加载插件时自动解析并安装这些依赖。依赖格式为包名: 版本号，同样遵循语义化版本规范。

homepage

插件项目的主页URL，通常是GitHub仓库地址或官方文档页面。用户可以通过此链接了解插件的更多信息、提交问题或参与贡献。

author

插件作者信息，可以包含作者姓名、邮箱地址或个人主页链接。方便用户在遇到问题时联系作者。

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "A concise description of my plugin",
  "main": "index.js",
  "permissions": ["fs:read", "fs:write", "network"],
  "dependencies": {
    "helper-plugin": "^1.2.0"
  },
  "homepage": "https://github.com/username/my-plugin",
  "author": "Your Name <email@example.com>"
}

三、功能声明

Plugin通过功能声明向Claude Code注册其提供的能力。功能声明位于 manifest.json 的特定字段中，定义了插件与宿主应用的交互方式。

commands（命令列表）

插件提供的命令列表。每个命令包含名称、描述和处理器函数。Claude Code会将注册的命令整合到命令系统中，用户可以直接调用。命令名称通常以插件名为前缀，避免与其他插件的命令冲突。例如 my-plugin.do-something。

hooks（生命周期钩子）

生命周期钩子允许插件在Claude Code的特定事件发生时执行自定义逻辑。常见的钩子包括：onActivate（插件被激活时触发）、onDeactivate（插件被停用时触发）、onCommand（命令被执行前/后触发）、onConfigChange（配置发生变化时触发）等。合理使用钩子可以让插件深度集成到工作流中。

provides（提供的功能类型）

声明插件向其他Plugin提供的功能接口。通过 provides 字段，一个插件可以暴露特定的API给其他插件使用，实现插件间的协作。其他插件可以通过 requires 字段来声明对这些功能的依赖。

requires（依赖的其他Plugin功能）

声明本插件需要依赖的其他Plugin所提供的功能。Claude Code在加载插件时会先加载被依赖的其他插件，并确保依赖的功能可用。这形成了一个插件化的生态系统，允许功能复用和组合。

{
  "commands": [
    {
      "name": "my-plugin.hello",
      "description": "Say hello from my plugin"
    },
    {
      "name": "my-plugin.analyze",
      "description": "Analyze the current project"
    }
  ],
  "hooks": {
    "onActivate": "lib/hooks.js",
    "onDeactivate": "lib/hooks.js"
  },
  "provides": {
    "formatting": "1.0.0"
  },
  "requires": {
    "theme-system": "^2.0.0"
  }
}

四、权限声明

权限系统是Claude Code安全模型的核心组成部分。插件必须通过 manifest.json 的 permissions 字段明确声明所需的每一项权限，遵循最小权限原则。

文件系统访问权限

控制插件对本地文件系统的访问能力，包括 fs:read（读取文件）、fs:write（写入文件）、fs:delete（删除文件）等。建议根据实际需要声明最小范围的权限，避免过度授权。

网络访问权限

控制插件发起网络请求的能力。声明 network 权限后，插件可以访问外部API、下载资源或上传数据。对于仅需要访问特定域名的插件，可以在权限中限定允许访问的域名白名单。

执行命令权限

控制插件在本地环境中执行Shell命令的能力。声明 exec 权限后，插件可以运行外部程序、脚本或系统命令。这是一个高风险权限，建议在插件安装时向用户明确说明执行命令的目的。

读取配置权限

控制插件读取Claude Code配置和用户设置的能力。声明 config:read 权限后，插件可以获取当前工作空间配置、用户偏好设置等信息。更敏感的 config:write 权限允许插件修改配置。

{
  "permissions": [
    "fs:read",
    "fs:write",
    "network",
    "exec",
    "config:read"
  ]
}

安全提醒：权限声明应当遵循最小权限原则——只申请插件正常运行所必需的最小权限集。过度声明权限可能引发用户的安全担忧，降低插件的可信度。用户安装插件时会看到完整的权限列表，应提供清晰的说明解释每项权限的用途。

五、国际化支持

为覆盖更广泛的用户群体，Plugin应当支持国际化（i18n）。规范的多语言文件组织方式可以帮助插件轻松适配不同语言环境。

多语言文件组织（i18n/目录）

在插件根目录下创建 i18n/ 文件夹，内部按语言代码组织子目录或文件。常见的结构是将所有语言的翻译文件集中存放在 i18n/ 目录中，文件名使用语言代码标识。

my-plugin/
├── manifest.json
├── index.js
├── i18n/
│   ├── zh-CN.json       # 简体中文翻译
│   ├── zh-TW.json       # 繁体中文翻译
│   ├── en.json          # 英文翻译
│   ├── ja.json          # 日文翻译
│   └── ko.json          # 韩文翻译
└── lib/

语言文件格式（JSON）

每个语言文件采用标准的JSON格式，以键值对的方式存储翻译文本。键名使用点号分隔的层级结构表示上下文，如 commands.hello.description。这样既保持了结构的清晰性，也便于在代码中按路径查找对应的翻译文本。

{
  "plugin": {
    "name": "My Plugin",
    "description": "一个强大的文件管理插件"
  },
  "commands": {
    "hello": {
      "description": "向用户问好"
    }
  },
  "errors": {
    "fileNotFound": "文件未找到：{path}"
  }
}

不同语言的manifest描述

为了让插件在不同语言环境下呈现更自然的展示效果，manifest.json 中的 name 和 description 字段可以根据用户的语言偏好自动切换。Claude Code会读取 i18n/ 目录下对应语言的翻译文件，覆盖 manifest.json 中的默认值，从而实现该插件名称和描述的本地化显示。

{
  "plugin": {
    "name": "File Manager",
    "description": "A powerful file management plugin"
  }
}

建议：如果插件面向全球用户，至少提供英文（en.json）和简体中文（zh-CN.json）两种语言的翻译。在 manifest.json 中使用英文作为默认值，然后在 i18n/ 目录中为各语言提供本地化翻译。Claude Code会根据用户的系统语言设置自动匹配最合适的语言文件。