feat(core): add OAuth model policy plugin

Author: ssfun

.github/dependabot.yml

@@ -16,3 +16,7 @@ updates:
     directory: /cliproxyapi-pro-plugins/proxy-pool
     schedule:
       interval: weekly
+  - package-ecosystem: gomod
+    directory: /cliproxyapi-pro-plugins/oauth-model-policy
+    schedule:
+      interval: weekly

.github/workflows/release-core.yml

@@ -283,6 +283,8 @@ jobs:
           cp "${tmp_dir}/arm64/cli-proxy-api" "${context_dir}/binaries/linux/arm64/CLIProxyAPI"
           cp "${tmp_dir}/amd64/plugins/linux/amd64/proxy-pool.so" "${context_dir}/plugins/linux/amd64/proxy-pool.so"
           cp "${tmp_dir}/arm64/plugins/linux/arm64/proxy-pool.so" "${context_dir}/plugins/linux/arm64/proxy-pool.so"
+          cp "${tmp_dir}/amd64/plugins/linux/amd64/oauth-model-policy.so" "${context_dir}/plugins/linux/amd64/oauth-model-policy.so"
+          cp "${tmp_dir}/arm64/plugins/linux/arm64/oauth-model-policy.so" "${context_dir}/plugins/linux/arm64/oauth-model-policy.so"
           cp "${tmp_dir}/amd64/config.example.yaml" "${context_dir}/config.example.yaml"
           cp customizations-repo/cliproxyapi-pro-core/entrypoint.sh "${context_dir}/entrypoint.sh"
           cp customizations-repo/cliproxyapi-pro-core/Dockerfile.runtime "${context_dir}/Dockerfile.runtime"
@@ -294,7 +296,9 @@ jobs:
             "${context_dir}/binaries/linux/amd64/CLIProxyAPI" \
             "${context_dir}/binaries/linux/arm64/CLIProxyAPI" \
             "${context_dir}/plugins/linux/amd64/proxy-pool.so" \
-            "${context_dir}/plugins/linux/arm64/proxy-pool.so"
+            "${context_dir}/plugins/linux/arm64/proxy-pool.so" \
+            "${context_dir}/plugins/linux/amd64/oauth-model-policy.so" \
+            "${context_dir}/plugins/linux/arm64/oauth-model-policy.so"
 
       - name: Set up QEMU
         uses: docker/setup-qemu-action@96fe6ef7f33517b61c61be40b68a1882f3264fb8 # v4.2.0
@@ -524,23 +528,27 @@ jobs:
           plugin_extension="so"
           if [ "${GOOS}" = "darwin" ]; then plugin_extension="dylib"; fi
           if [ "${GOOS}" = "windows" ]; then plugin_extension="dll"; fi
-          plugin_relative="plugins/${GOOS}/${GOARCH}/proxy-pool.${plugin_extension}"
-          plugin_source=".proxy-pool-build"
-          rm -rf "${plugin_source}"
-          cp -R ../customizations-repo/cliproxyapi-pro-plugins/proxy-pool "${plugin_source}"
-          go -C "${plugin_source}" mod edit -replace github.com/router-for-me/CLIProxyAPI/v7=..
           mkdir -p "${archive_dir}/plugins/${GOOS}/${GOARCH}"
-          CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" go -C "${plugin_source}" build \
-            -buildvcs=false -trimpath -buildmode=c-shared \
-            -o "${PWD}/${archive_dir}/${plugin_relative}" .
+          plugin_relatives=()
+          for plugin_name in proxy-pool oauth-model-policy; do
+            plugin_relative="plugins/${GOOS}/${GOARCH}/${plugin_name}.${plugin_extension}"
+            plugin_source=".${plugin_name}-build"
+            rm -rf "${plugin_source}"
+            cp -R "../customizations-repo/cliproxyapi-pro-plugins/${plugin_name}" "${plugin_source}"
+            go -C "${plugin_source}" mod edit -replace github.com/router-for-me/CLIProxyAPI/v7=..
+            CGO_ENABLED=1 GOOS="${GOOS}" GOARCH="${GOARCH}" go -C "${plugin_source}" build \
+              -buildvcs=false -trimpath -buildmode=c-shared \
+              -o "${PWD}/${archive_dir}/${plugin_relative}" .
+            plugin_relatives+=("${plugin_relative}")
+          done
 
           cp LICENSE README.md README_EN.md config.example.yaml "${archive_dir}/"
           python ../customizations-repo/scripts/build/create_reproducible_archive.py \
             --format "${ARCHIVE_FORMAT}" \
             --output "dist/${archive_name}" \
             --root "${archive_dir}" \
             --source-date-epoch "${SOURCE_DATE_EPOCH}" \
-            "${binary_name}" LICENSE README.md README_EN.md config.example.yaml "${plugin_relative}"
+            "${binary_name}" LICENSE README.md README_EN.md config.example.yaml "${plugin_relatives[@]}"
 
       - name: Build Linux glibc plugin-capable archive
         if: matrix.kind == 'linux-glibc-plugin'
@@ -560,8 +568,10 @@ jobs:
           archive_name="CLIProxyAPI_${RELEASE_TAG#v}_linux_${ASSET_ARCH}.tar.gz"
           rm -rf "dist/linux-${GOARCH}"
           mkdir -p "${archive_dir}"
-          rm -rf .proxy-pool-build
-          cp -R ../customizations-repo/cliproxyapi-pro-plugins/proxy-pool .proxy-pool-build
+          for plugin_name in proxy-pool oauth-model-policy; do
+            rm -rf ".${plugin_name}-build"
+            cp -R "../customizations-repo/cliproxyapi-pro-plugins/${plugin_name}" ".${plugin_name}-build"
+          done
 
           go_archive="go${GO_VERSION}.linux-${GOARCH}.tar.gz"
           go_sha256="$(
@@ -595,11 +605,13 @@ jobs:
                 -ldflags="-s -w -X main.Version=${RELEASE_TAG} -X main.Commit=release-${CORE_TAG} -X main.BuildDate=${BUILD_DATE}" \
                 -o "'"${archive_dir}"'/cli-proxy-api" ./cmd/server/
 
-              go -C .proxy-pool-build mod edit -replace github.com/router-for-me/CLIProxyAPI/v7=/src
               mkdir -p "'"${archive_dir}"'/plugins/linux/${GOARCH}"
-              CGO_ENABLED=1 GOOS=linux GOARCH="${GOARCH}" go -C .proxy-pool-build build \
-                -buildvcs=false -trimpath -buildmode=c-shared \
-                -o "/src/'"${archive_dir}"'/plugins/linux/${GOARCH}/proxy-pool.so" .
+              for plugin_name in proxy-pool oauth-model-policy; do
+                go -C ".${plugin_name}-build" mod edit -replace github.com/router-for-me/CLIProxyAPI/v7=/src
+                CGO_ENABLED=1 GOOS=linux GOARCH="${GOARCH}" go -C ".${plugin_name}-build" build \
+                  -buildvcs=false -trimpath -buildmode=c-shared \
+                  -o "/src/'"${archive_dir}"'/plugins/linux/${GOARCH}/${plugin_name}.so" .
+              done
 
               glibc_versions="$(readelf --version-info "'"${archive_dir}"'/cli-proxy-api" | sed -n "s/.*Name: GLIBC_\([0-9.]*\).*/\1/p" | sort -Vu)"
               if [ -n "${glibc_versions}" ]; then
@@ -618,7 +630,9 @@ jobs:
             --output "dist/${archive_name}" \
             --root "${archive_dir}" \
             --source-date-epoch "${SOURCE_DATE_EPOCH}" \
-            cli-proxy-api LICENSE README.md README_EN.md config.example.yaml "plugins/linux/${GOARCH}/proxy-pool.so"
+            cli-proxy-api LICENSE README.md README_EN.md config.example.yaml \
+            "plugins/linux/${GOARCH}/proxy-pool.so" \
+            "plugins/linux/${GOARCH}/oauth-model-policy.so"
 
       - name: Install FreeBSD plugin build dependencies
         if: matrix.kind == 'freebsd-plugin'

README.md

@@ -16,6 +16,7 @@ CLIProxyAPI Pro 是对两个 upstream 项目的最小化定制层集合：
 - 账号巡检针对 Antigravity 软封禁和 xAI 可用性异常提供可选深度检测
 - 路由策略页面统一管理 upstream 路由行为与按 provider 配置的请求状态保护
 - 内置动态代理池插件，把多个 HTTP/SOCKS 节点汇聚为固定的本地 SOCKS5 地址，支持轮询、加权、健康隔离与故障转移
+- 内置 OAuth 模型策略插件，首期可按 xAI 账号套餐分别排除不可用模型，并同步约束模型列表和账号调度
 
 ## 项目结构
 
@@ -36,7 +37,8 @@ CLIProxyAPI Pro 是对两个 upstream 项目的最小化定制层集合：
 │   └── overlay/
 │
 ├── cliproxyapi-pro-plugins/
-│   └── proxy-pool/
+│   ├── proxy-pool/
+│   └── oauth-model-policy/
 │
 ├── scripts/validation/
 └── .github/workflows/
@@ -62,11 +64,12 @@ CLIProxyAPI Pro 是对两个 upstream 项目的最小化定制层集合：
 - 支持 SQLite-backed quota cache。
 - 支持模型价格持久化。
 - 支持 QuotaProvider 插件协议和 Gemini CLI legacy adapter。
+- 支持通用 `AuthModelFilter` 插件协议；预打包的 `oauth-model-policy` 首期可按 xAI OAuth 套餐排除模型。
 - 启动时在内存中强制必要 upstream 配置；仅修改 YAML 中已存在的键，禁止自动新增键。
 - 支持后端账号巡检调度器和执行器，巡检探测前可刷新 token。
 - 支持统一路由策略与请求状态保护 API。
 - 支持 Komari agent 可选启动。
-- 标准 macOS、Windows amd64、Linux Release 和 Docker 镜像预打包 `proxy-pool` 动态插件；Windows ARM64、FreeBSD 与 `_no-plugin` 产物暂不内置代理池。
+- 标准 macOS、Windows amd64、Linux Release 和 Docker 镜像预打包 `proxy-pool` 与 `oauth-model-policy` 动态插件；Windows ARM64、FreeBSD 与 `_no-plugin` 产物暂不内置动态插件。
 - 将 `/` 跳转到 `/management.html`。
 - 增强 `/healthz` 返回信息。
 

README_EN.md

@@ -16,6 +16,7 @@ This project does not maintain a full fork of either upstream project. Instead,
 - Optional deep probes for Antigravity soft bans and xAI availability anomalies.
 - A routing-policy page for upstream routing behavior and provider-scoped request-state protection.
 - A bundled dynamic proxy-pool plugin that aggregates HTTP/SOCKS nodes behind one fixed loopback SOCKS5 endpoint with rotation, health isolation, and failover.
+- A bundled OAuth model-policy plugin that initially removes unavailable models per xAI account plan and constrains both model listing and auth scheduling.
 
 ## Repository layout
 
@@ -36,7 +37,8 @@ This project does not maintain a full fork of either upstream project. Instead,
 │   └── overlay/
 │
 ├── cliproxyapi-pro-plugins/
-│   └── proxy-pool/
+│   ├── proxy-pool/
+│   └── oauth-model-policy/
 │
 ├── scripts/validation/
 └── .github/workflows/
@@ -62,11 +64,12 @@ Main capabilities:
 - Supports SQLite-backed quota cache.
 - Supports model price persistence.
 - Supports the QuotaProvider plugin protocol and a Gemini CLI legacy adapter.
+- Supports a generic `AuthModelFilter` plugin protocol; the bundled `oauth-model-policy` initially filters xAI OAuth models by account plan.
 - Forces required upstream startup config: `usage-statistics-enabled=true` and the Pro management panel repository.
 - Adds a backend account-inspection scheduler and executor with token refresh before probing.
 - Adds unified routing-policy and request-state-protection APIs.
 - Optionally starts the Komari agent.
-- Prebundles the `proxy-pool` dynamic library in standard macOS, Windows amd64, and Linux releases plus Docker images; Windows ARM64, FreeBSD, and `_no-plugin` assets do not currently bundle it.
+- Prebundles the `proxy-pool` and `oauth-model-policy` dynamic libraries in standard macOS, Windows amd64, and Linux releases plus Docker images; Windows ARM64, FreeBSD, and `_no-plugin` assets do not currently bundle dynamic plugins.
 - Redirects `/` to `/management.html`.
 - Enhances the `/healthz` response.
 

cliproxyapi-pro-core/Dockerfile

@@ -37,6 +37,7 @@ RUN set -eux; \
 COPY cliproxyapi-pro-core/embeddedusage /tmp/embeddedusage
 COPY cliproxyapi-pro-core/patches /tmp/patches
 COPY cliproxyapi-pro-plugins/proxy-pool /tmp/proxy-pool
+COPY cliproxyapi-pro-plugins/oauth-model-policy /tmp/oauth-model-policy
 
 RUN python3 /tmp/patches/apply_upstream_patches.py
 
@@ -47,6 +48,13 @@ RUN set -eux; \
     CGO_ENABLED=1 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
       go build -buildvcs=false -trimpath -buildmode=c-shared -o /out/proxy-pool.so .
 
+RUN set -eux; \
+    cd /tmp/oauth-model-policy; \
+    go mod edit -replace github.com/router-for-me/CLIProxyAPI/v7=/src/CLIProxyAPI; \
+    go mod tidy; \
+    CGO_ENABLED=1 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH:-amd64} \
+      go build -buildvcs=false -trimpath -buildmode=c-shared -o /out/oauth-model-policy.so .
+
 RUN set -eux; \
     go mod tidy; \
     CLIPROXY_SOURCE_VERSION="$(cat /tmp/cliproxy-version)"; \
@@ -77,6 +85,7 @@ WORKDIR /CLIProxyAPI
 
 COPY --from=builder /out/CLIProxyAPI /CLIProxyAPI/CLIProxyAPI
 COPY --from=builder /out/proxy-pool.so /CLIProxyAPI/plugins/linux/${TARGETARCH}/proxy-pool.so
+COPY --from=builder /out/oauth-model-policy.so /CLIProxyAPI/plugins/linux/${TARGETARCH}/oauth-model-policy.so
 COPY --from=builder /src/CLIProxyAPI/config.example.yaml /CLIProxyAPI/config.example.yaml
 COPY cliproxyapi-pro-core/entrypoint.sh /CLIProxyAPI/entrypoint.sh
 

cliproxyapi-pro-core/README.md

@@ -4,7 +4,7 @@
 
 本目录不维护 upstream 的完整 fork。Docker 构建时会下载指定 upstream release，复制本地 `embeddedusage/` 包，执行 `patches/` 中的补丁脚本，然后构建 Pro 部署使用的多架构镜像。
 
-标准 macOS、Windows amd64、Linux Pro Release 与 Docker 镜像还会预打包 `cliproxyapi-pro-plugins/proxy-pool` 动态插件。插件在回环地址提供固定 SOCKS5 入口，Core 继续使用单一 `proxy-url`，节点轮询、健康隔离和故障转移由插件完成，不修改 upstream 的代理执行路径。Windows ARM64、FreeBSD 与 `_no-plugin` 资产暂不内置该功能。
+标准 macOS、Windows amd64、Linux Pro Release 与 Docker 镜像会预打包 `proxy-pool` 和 `oauth-model-policy` 动态插件。前者在回环地址提供固定 SOCKS5 入口；后者首期按 xAI OAuth 套餐排除账号不可用的模型。Windows ARM64、FreeBSD 与 `_no-plugin` 资产暂不内置动态插件。
 
 ## 定制内容
 
@@ -137,6 +137,12 @@ detail 还会保留 upstream `ClientRequestMetadata` 提供的 `client_ip`、`x_
 `Executor.HttpRequest` 提供兼容适配；插件未来原生实现协议后会自动优先使用原生能力。
 协议字段与兼容策略见 [QUOTA_PROVIDER.md](QUOTA_PROVIDER.md)。
 
+### OAuth 套餐模型策略插件
+
+补丁层为 upstream 插件 SDK/ABI 增加通用 `AuthModelFilter` 能力。Core 只提供当前 auth、原始模型集合和受控 HTTP callback，并强制插件只能减去已有模型；套餐识别与规则均位于预打包的 `oauth-model-policy` 插件中。
+
+首期仅支持 xAI OAuth，规则键包括 `free`、`supergrok`、`x-premium-plus`、`supergrok-heavy`、`paid-unknown` 以及 `_unknown` 回退。处理顺序为 upstream `excluded_models`、插件套餐过滤、OAuth alias/prefix、模型注册。最终注册结果同时约束 `/v1/models` 聚合和请求调度候选账号。配置与探测细节见 `cliproxyapi-pro-plugins/oauth-model-policy/README.md`。
+
 ### 后端账号巡检调度器
 
 补丁层在 management API 下增加账号巡检路由：
@@ -227,6 +233,7 @@ https://github.com/ssfun/CLIProxyAPI-Pro
 - `Dockerfile` — 下载 upstream CLIProxyAPI，应用定制层，并构建最终镜像。
 - `Dockerfile.runtime` — GitHub Actions 使用预构建 Linux 二进制组装运行时镜像。
 - `QUOTA_PROVIDER.md` — QuotaProvider 插件协议和兼容策略。
+- `../cliproxyapi-pro-plugins/oauth-model-policy/` — 按 OAuth 套餐过滤账号模型的动态插件。
 - `entrypoint.sh` — 启动 Komari、主 API 和 WebDAV usage 恢复逻辑。
 - `embeddedusage/` — 内嵌 SQLite usage service 和 management routes。
 - `patches/apply_upstream_patches.py` — Docker build 阶段 patch upstream 源码。

cliproxyapi-pro-core/README_EN.md

@@ -4,7 +4,7 @@ Customized Docker build layer for upstream `router-for-me/CLIProxyAPI`.
 
 This directory does not maintain a full fork of upstream. During Docker build it downloads an upstream release, copies in the local `embeddedusage/` package, applies the patch script in `patches/`, and builds a multi-arch image for the Pro deployment.
 
-Standard macOS, Windows amd64, and Linux Pro releases plus Docker images prebundle the `cliproxyapi-pro-plugins/proxy-pool` dynamic plugin. It exposes a fixed loopback SOCKS5 endpoint while rotation, health isolation, and failover stay inside the plugin, so upstream's proxy execution path is unchanged. Windows ARM64, FreeBSD, and `_no-plugin` assets do not currently bundle this feature.
+Standard macOS, Windows amd64, and Linux Pro releases plus Docker images prebundle the `proxy-pool` and `oauth-model-policy` dynamic plugins. The former exposes a fixed loopback SOCKS5 endpoint; the latter initially removes models unavailable to each xAI OAuth plan. Windows ARM64, FreeBSD, and `_no-plugin` assets do not currently bundle dynamic plugins.
 
 ## What this customization adds
 
@@ -138,6 +138,12 @@ changes: Core adapts its existing `Executor.HttpRequest`; a future native implem
 priority automatically. See [QUOTA_PROVIDER.md](QUOTA_PROVIDER.md) for the schema and compatibility
 rules.
 
+### OAuth plan model policy plugin
+
+The patch layer adds a generic `AuthModelFilter` capability to the upstream plugin SDK/ABI. Core provides the current auth, its native model set, and a controlled HTTP callback, while enforcing that a plugin may only subtract existing models. Plan discovery and policy rules stay in the bundled `oauth-model-policy` plugin.
+
+The first version supports xAI OAuth with `free`, `supergrok`, `x-premium-plus`, `supergrok-heavy`, `paid-unknown`, and `_unknown` fallback rules. Processing order is upstream `excluded_models`, plugin plan filtering, OAuth alias/prefix, then model registration. The final registration constrains both `/v1/models` aggregation and scheduler candidates. See `cliproxyapi-pro-plugins/oauth-model-policy/README.md` for configuration and discovery details.
+
 ### Backend account inspection scheduler
 
 The patch layer adds backend account-inspection routes under the management API:
@@ -228,6 +234,7 @@ It then starts `CLIProxyAPI` and optionally restores the latest usage backup fro
 - `Dockerfile` — downloads upstream CLIProxyAPI, applies this customization layer, and builds the final image.
 - `Dockerfile.runtime` — assembles the Actions runtime image from prebuilt Linux binaries.
 - `QUOTA_PROVIDER.md` — QuotaProvider plugin protocol and compatibility rules.
+- `../cliproxyapi-pro-plugins/oauth-model-policy/` — dynamic plugin for filtering auth models by OAuth plan.
 - `entrypoint.sh` — starts Komari, starts the main API, and restores WebDAV usage backups.
 - `embeddedusage/` — embedded SQLite usage service and management routes.
 - `patches/apply_upstream_patches.py` — patches upstream source during Docker build.