# 标准动态库插件示例

这是混合全部能力的完整骨架示例。单能力示例请查看 `../README_CN.md`。

本目录是当前标准动态库插件 ABI 的参考骨架。ABI 与语言无关：宿主加载原生动态库，调用 `cliproxy_plugin_init`，然后通过稳定的 C 函数表交换 JSON 信封。

本目录包含同一个混合能力示例的 Go、C、Rust 三种完整实现。Go 示例使用 `-buildmode=c-shared`，C 示例使用 CMake，Rust 示例使用 `cdylib` crate。

## 入口

每个插件必须导出：

```c
int cliproxy_plugin_init(const cliproxy_host_api* host, cliproxy_plugin_api* plugin);
```

插件填充 `cliproxy_plugin_api`：

```c
int call(char* method, uint8_t* request, size_t request_len, cliproxy_buffer* response);
void free_buffer(void* ptr, size_t len);
void shutdown(void);
```

宿主提供 `cliproxy_host_api`：

```c
int call(void* host_ctx, char* method, uint8_t* request, size_t request_len, cliproxy_buffer* response);
void free_buffer(void* ptr, size_t len);
```

C ABI 不传递 Go interface、Go slice、Go map、Go channel、`context.Context` 或 Go error。

## JSON 信封

成功响应：

```json
{
  "ok": true,
  "result": {}
}
```

错误响应：

```json
{
  "ok": false,
  "error": {
    "code": "invalid_request",
    "message": "request is invalid"
  }
}
```

原始字节字段通过 JSON 自动使用 base64 编码。

## 能力

`plugin.register` 和 `plugin.reconfigure` 返回 metadata 和能力开关。本示例声明完整的提供方插件能力：

- 模型提供方
- 模型注册器
- 认证提供方
- 前端认证提供方
- 执行器
- 请求和响应转换
- 思考配置处理
- 用量观察
- 命令行插件
- Management API 插件

宿主保留现有优先级规则：原生逻辑优先，插件补齐缺口，高优先级插件先于低优先级插件执行。

## 目录布局

- `go/`：完整混合能力 Go 实现。
- `c/`：完整混合能力 C 实现，不依赖外部库。
- `rust/`：完整混合能力 Rust 实现，不依赖外部库。

三种实现都会在需要请求内容的方法中解析传入 JSON。认证方法会把原始请求作为 `StorageJSON`，请求和响应转换会回显传入 `Body`，Thinking 会解码 `Body` 并追加 `plugin_example_thinking`，执行器方法会使用 `Model`、`Format`、`Payload` 等请求字段，Usage 会维护进程内计数。

## 构建

在仓库根目录构建。

构建全部插件示例，包括 `simple` 的三种语言实现：

```bash
make -C examples/plugin build
```

产物会写入 `examples/plugin/bin`，当前平台扩展名下分别为 `simple-go`、`simple-c`、`simple-rust`。

macOS 手动构建 Go：

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
go build -buildmode=c-shared -o plugins/darwin/$(go env GOARCH)/simple-go.dylib ./examples/plugin/simple/go
rm -f plugins/darwin/$(go env GOARCH)/simple-go.h
```

macOS 手动构建 C：

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
cmake -S examples/plugin/simple/c -B /tmp/cliproxy-simple-c-build -DCMAKE_LIBRARY_OUTPUT_DIRECTORY=$PWD/plugins/darwin/$(go env GOARCH)
cmake --build /tmp/cliproxy-simple-c-build
```

macOS 手动构建 Rust：

```bash
mkdir -p plugins/darwin/$(go env GOARCH)
cd examples/plugin/simple/rust
CARGO_TARGET_DIR=/tmp/cliproxy-simple-rust-target cargo build --release --locked
cp /tmp/cliproxy-simple-rust-target/release/libcliproxy_simple_rust.dylib ../../../../plugins/darwin/$(go env GOARCH)/simple-rust.dylib
```

Linux、FreeBSD 或 Windows 使用相同源码目录，平台扩展名以 `examples/plugin/Makefile` 的规则为准。

插件 ID 来自动态库文件名去掉平台扩展名。通过 Makefile 构建的产物分别对应 `plugins.configs.simple-go`、`plugins.configs.simple-c` 和 `plugins.configs.simple-rust`。

## 发现规则

宿主搜索：

```text
plugins/<GOOS>/<GOARCH>-<variant>
plugins/<GOOS>/<GOARCH>
plugins
```

支持的扩展名：

- Linux 和 FreeBSD 使用 `.so`
- macOS 使用 `.dylib`
- Windows 使用 `.dll`

插件 ID 必须匹配：

```text
[A-Za-z0-9][A-Za-z0-9._-]{0,127}
```

## 配置

动态插件默认关闭。

```yaml
plugins:
  enabled: true
  dir: "plugins"
  configs:
    simple-go:
      enabled: true
      priority: 1
      config1: true
      config2: "string"
      config3: 3
      mode: "safe"
```

`plugins.configs.<pluginID>` 会作为标准化 YAML 字节放进 JSON 请求，传给 `plugin.register` 或 `plugin.reconfigure`。

## 宿主 HTTP 桥接

插件可以通过 `host.call` 调用宿主能力。HTTP 桥接方法是：

```text
host.http.do
```

真实 HTTP 请求仍由宿主执行，因此代理、传输策略、认证上下文和请求日志仍由宿主控制。

## Management API

原生插件管理接口包括：

```text
GET /v0/management/plugins
DELETE /v0/management/plugins/{pluginID}
PATCH /v0/management/plugins/{pluginID}/enabled
GET /v0/management/plugins/{pluginID}/config
PUT /v0/management/plugins/{pluginID}/config
PATCH /v0/management/plugins/{pluginID}/config
```

插件自有 Management API 路由通过 `management.register` 的 `routes` 字段注册，并通过 `management.handle` 处理。

可由浏览器直接访问的菜单资源通过 `management.register` 的 `resources` 字段注册。CPA 会将这些资源暴露在 `/v0/resource/plugins/<pluginID>/...` 下；例如插件 ID 为 `example` 且资源路径为 `/status` 时，最终路径是 `/v0/resource/plugins/example/status`。

## 信任边界

标准动态库插件是可信进程内代码。panic 恢复可以保护宿主管理的调用，但不能阻止插件退出进程、破坏内存、修改进程全局状态或泄露敏感数据。只安装你像信任服务二进制一样信任的插件。

## 验证

当前平台示例构建：

```bash
make -C examples/plugin list
make -C examples/plugin build
find examples/plugin/bin -maxdepth 1 -type f | wc -l
make -C examples/plugin clean
```

如果修改了本仓库的 Go 代码，还需要运行：

```bash
go build -o test-output ./cmd/server && rm test-output
```