# 插件模块 (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. 钩子逻辑会在工具执行的生命周期内被自动触发。

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

```json
{
  "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"
    }
  ]
}
```