claudecode/crates/plugins

插件模块 (plugins)

本模块实现了 Claw 的插件系统，允许通过外部扩展来增强 AI 的功能，包括自定义工具、命令以及在工具执行前后运行的钩子 (Hooks)。

概览

plugins 模块的主要职责是：

• 定义插件的清单格式 (plugin.json) 和元数据结构。
• 管理插件的完整生命周期：安装、加载、初始化、启用/禁用、更新和卸载。
• 提供插件类型的抽象：
  • Builtin (内置)：编译在程序内部的插件。
  • Bundled (绑定)：随应用程序分发但作为独立文件存在的插件。
  • External (外部)：用户自行安装或从远程仓库下载的插件。
• 实现插件隔离与执行机制，支持插件定义的自定义工具。

关键特性

• 插件清单 (PluginManifest)：每个插件必须包含一个 plugin.json，详细说明其名称、版本、所需权限、钩子、生命周期脚本以及它所暴露的工具。
• 自定义工具 (PluginTool)：插件可以定义全新的工具供 AI 调用。这些工具在执行时被作为独立的外部进程启动。
• 钩子系统 (Hooks)：支持 PreToolUse 和 PostToolUse 钩子，允许插件在 AI 调用任何工具之前或之后执行特定的逻辑。
• 生命周期管理：提供 Init 和 Shutdown 阶段，允许插件在加载时进行环境准备，在卸载或关闭时进行清理。
• 权限模型：强制要求插件声明权限（read, write, execute），并为定义的工具指定安全级别（read-only, workspace-write, danger-full-access）。

实现逻辑

核心模块

• lib.rs: 包含了插件定义的各种结构体（Manifest, Metadata, Tool, Permission 等）以及插件特性的定义。
• manager.rs: 实现了 PluginManager，负责插件在磁盘上的组织、注册表的维护以及安装/更新逻辑。
• hooks.rs: 实现了钩子执行器 (HookRunner)，负责在正确的时机触发插件定义的脚本。

插件加载与执行流程

1. PluginManager 扫描指定的目录（内置、绑定及外部安装目录）。
2. 读取并验证每个插件的 plugin.json。
3. 如果插件被启用，则初始化该插件并将其定义的工具注册到系统的全局工具注册表中。
4. 当 AI 调用插件工具时，系统根据清单中定义的命令行信息启动一个子进程，并通过标准输入/环境变量传递参数。
5. 钩子逻辑会在工具执行的生命周期内被自动触发。

使用示例 (插件定义样例)

{
  "name": "my-custom-plugin",
  "version": "1.0.0",
  "description": "一个演示插件",
  "permissions": ["read", "execute"],
  "tools": [
    {
      "name": "custom_search",
      "description": "执行自定义搜索",
      "inputSchema": { "type": "object", "properties": { "query": { "type": "string" } } },
      "command": "python3",
      "args": ["search_script.py"],
      "requiredPermission": "read-only"
    }
  ]
}