Add projects

backend/examples/plugin/README.md

@@ -0,0 +1,123 @@
+# Standard Dynamic Library Plugin Examples
+
+This directory contains standard dynamic library plugin examples for the CLIProxyAPI C ABI.
+
+## Layout
+
+- `simple/`: full provider-native skeleton that declares every supported capability.
+- `model/`: model capability only.
+- `auth/`: auth provider capability only.
+- `frontend-auth/`: frontend auth provider capability only.
+- `frontend-auth-exclusive/`: frontend auth provider that becomes the only request authentication provider when selected.
+- `executor/`: executor capability only.
+- `protocol-format/`: minimal executor focused on input/output format declarations.
+- `request-translator/`: request translation capability only.
+- `request-normalizer/`: request normalization capability only.
+- `codex-service-tier/`: Go-only request normalizer that sets Codex `gpt-5.5` requests to the priority service tier when enabled.
+- `request-lifecycle/`: Go-only request admission example with concurrency control, active HTTP termination, and terminal callbacks.
+- `scheduler/`: Go-only scheduler that can select a configured auth ID, delegate to a built-in scheduler, or deny picks.
+- `claude-web-search-router/`: ModelRouter + executor for Claude Code built-in `web_search` (antigravity / codex / xai / Tavily). See `claude-web-search-router/README.md`.
+- `response-translator/`: response translation capability only.
+- `response-normalizer/`: response normalization capability only.
+- `thinking/`: thinking applier capability only.
+- `usage/`: usage observer capability only.
+- `cli/`: command-line capability only.
+- `management-api/`: Management API and resource capability only.
+- `host-callback/`: minimal plugin resource that demonstrates host callbacks.
+- `host-callback-auth-files/`: Go-only plugin resource that calls host auth file callbacks.
+- `host-model-callback/`: Go-only plugin resource that calls the host model execution callbacks.
+
+Most standard capability examples contain `go/`, `c/`, and `rust/` subdirectories. Specialized examples may provide only the implementation language they need.
+
+## Codex Service Tier
+
+`codex-service-tier` declares the request normalization capability. When `fast` is `true`, it sets `service_tier` to `priority` for requests where `req.ToFormat` is `codex` and `req.Model` is `gpt-5.5`.
+
+```yaml
+plugins:
+  configs:
+    codex-service-tier:
+      enabled: true
+      priority: 1
+      fast: false
+```
+
+## Request Lifecycle
+
+`request-lifecycle` combines `request_interceptor` with `request_lifecycle_plugin`. It acquires a concurrency slot before auth selection, can return a custom `403` or `429` response without contacting an upstream model, and releases admitted slots from `request.complete` on success, failure, rejection, or cancellation.
+
+```yaml
+plugins:
+  configs:
+    request-lifecycle:
+      enabled: true
+      priority: 100
+      max_concurrency: 2
+      reject_keyword: "blocked"
+```
+
+See `request-lifecycle/README.md` for build instructions and lifecycle semantics.
+
+## Host Auth Files Callback
+
+`host-callback-auth-files` declares the Management API capability and exposes a browser resource named `Host Auth Files`. The resource demonstrates `host.auth.list`, `host.auth.get` (physical JSON file), `host.auth.get_runtime`, and `host.auth.save`.
+
+```yaml
+plugins:
+  configs:
+    host-callback-auth-files:
+      enabled: true
+      priority: 1
+```
+
+See `host-callback-auth-files/README.md` for URL examples.
+
+## Host Model Callback
+
+`host-model-callback` declares the Management API capability and exposes a browser resource named `Host Model Callback`. The resource calls `host.model.execute` for non-streaming requests and `host.model.execute_stream` plus `host.model.stream_read` for streaming requests. It demonstrates explicit stream close with `host.model.stream_close` and an `implicit_close=true` option for RPC-scope host cleanup.
+
+When the resource forwards its `host_callback_id`, CPA identifies the plugin that initiated the host model callback and skips that same plugin's interceptors for the nested execution. This makes host model callbacks non-recursive for the caller while allowing other plugins to intercept the nested request.
+
+```yaml
+plugins:
+  configs:
+    host-model-callback:
+      enabled: true
+      priority: 1
+```
+
+The default example model is `gpt-5.5`, but the request succeeds only when the current CPA model and auth configuration can route that model.
+
+## Scheduler
+
+`scheduler` declares the scheduler capability. It can select a configured auth ID from the candidate list, delegate to the built-in `fill-first` or `round-robin` scheduler, or reject picks when `deny` is `true`.
+
+```yaml
+plugins:
+  configs:
+    scheduler:
+      enabled: true
+      priority: 1
+      auth_id: ""
+      delegate: ""
+      deny: false
+```
+
+`auth_id` selects a matching candidate when `delegate` is empty. `delegate` accepts `""`, `fill-first`, or `round-robin`; other non-empty values leave the pick unhandled. `deny` returns a scheduler error.
+
+## Build All Examples
+
+```bash
+make -C examples/plugin list
+make -C examples/plugin build
+```
+
+Artifacts are written to `examples/plugin/bin`.
+
+## Notes
+
+`protocol-format` uses a minimal executor because format declarations belong to executor capabilities.
+
+`host-callback` uses a minimal plugin resource because host callbacks are invoked from plugin methods and are not standalone capabilities.
+
+Menu resources returned by `management.register` through the `resources` field are exposed by CPA under `/v0/resource/plugins/<pluginID>/...`. Authenticated plugin Management API routes remain under `/v0/management/...`.