build: 将 CLIProxyAPI 纳入 submodule

.gitignore

@@ -9,4 +9,5 @@ coverage.out
 .cache/
 /.runtime/
 /.home/
-/.externals/
+/.externals/*
+!/.externals/CLIProxyAPI/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule ".externals/CLIProxyAPI"]
+	path = .externals/CLIProxyAPI
+	url = https://github.com/router-for-me/CLIProxyAPI

AGENTS.md

@@ -12,15 +12,17 @@
 - `cpa-plugin-key-billing` CLIProxyAPI 下游 API Key 计费与订阅额度插件
 - `cpa-usage-keeper` 用量持久化与分析面板
 
-## 参考仓库边界
+## 上游依赖与参考仓库边界
 
-`.externals/CLIProxyAPI/`、`.externals/cpa-plugin-key-billing/`、`.externals/cpa-usage-keeper/` 都不是本项目的实际开发仓库，只用于测试、契约核对和实现对比。
+`.externals/CLIProxyAPI/` 是锁定官方基线的 Git submodule，用于宿主构建、契约核对和集成测试。宿主修复仍以根仓库 `patch/` 中的补丁维护，不直接提交到官方 submodule。
 
-- 默认不检查这些目录的 Git 状态、提交历史、分支、远端或工作区改动。
-- 不为这些仓库修复问题，不修改或提交其中的代码，也不处理其 Git 状态。
+`.externals/cpa-plugin-key-billing/`、`.externals/cpa-usage-keeper/` 不是本项目的实际开发仓库，只用于测试、契约核对和实现对比。
+
+- 默认不检查两个参考插件目录的 Git 状态、提交历史、分支、远端或工作区改动。
+- 不为这两个参考插件仓库修复问题，不修改或提交其中的代码，也不处理其 Git 状态。
 - 上述限制不影响运行时测试：可直接加载已经构建好的参考插件；测试 CPA 插件组合时，按需启用 `cpa-key-billing` 作为对照插件，但不得因此进入其仓库做源码或 Git 操作。
 - 只有在 billing 的兼容性验证、测试或实现判断确有必要时，才按最小范围只读查看相关文件。
-- 需要修改、构建、提交或维护任一参考仓库时，必须由用户明确提出。
+- CPA submodule 只允许按 `patch/README.md` 应用、验证或重新生成本项目维护的宿主补丁；除此以外的 CPA 修改，以及两个参考插件的修改、构建、提交或维护，必须由用户明确提出。
 - 项目的实现、提交和工作区清洁度只以 billing 根仓库为准。
 
 ## DO

README.md

@@ -66,7 +66,7 @@ CLIProxyAPI 负责 HTTP 接入、协议转换、上游凭证和实际请求执
 
 ## 当前兼容目标
 
-- CLIProxyAPI 基线：`v7.2.132` / `78f0c4079e3e6273d65d03b5549cffc898703264`，需依次应用 `patch/` 中两项宿主补丁
+- CLIProxyAPI 基线：`v7.2.132` / `78f0c4079e3e6273d65d03b5549cffc898703264`，由 `.externals/CLIProxyAPI` submodule 锁定，需依次应用 `patch/` 中三项宿主补丁
 - 插件版本：`0.1.0`
 - Native ABI：`1`
 - RPC schema：最高 `4`，注册时按宿主版本向下协商；schema v4 提供 Usage 请求身份
@@ -149,4 +149,4 @@ CGO_ENABLED=1 go test ./...
 - `internal/plugin`：RPC dispatcher、契约 DTO、原子配置与 Usage 接入。
 - `internal/modelcatalog`：models.dev 下载、规范化、搜索和最后可用缓存。
 - `scripts`：环境检查与可复现构建。
-- `.externals/CLIProxyAPI`：上游契约参考，不属于插件实现。
+- `.externals/CLIProxyAPI`：锁定官方基线的宿主 submodule，用于构建、契约核对和集成测试；本项目的宿主改动由 `patch/` 维护。

docs/dev.md

@@ -1,5 +1,13 @@
 # 开发与测试
 
+克隆后先初始化锁定版本的 CLIProxyAPI 宿主：
+
+```bash
+git submodule update --init --recursive
+```
+
+需要构建本项目使用的 CPA 时，再按 [`../patch/README.md`](../patch/README.md) 的顺序应用三个宿主补丁。submodule 本身始终锁定官方基线，补丁来源以根仓库 `patch/` 为准。
+
 开发按依赖从少到多推进：先确定数据和规则，再实现存储与服务，最后接入外部协议和界面。核心逻辑不依赖框架类型，协议转换集中在边界层。涉及持久化时，先定义迁移和历史数据语义
 
 开发的核心在于每一步的可预见性与可测试性

patch/README.md

@@ -66,22 +66,30 @@ billing 在请求拦截阶段创建并发占用，依赖 CPA 后续发送唯一
 
 ## 应用
 
-在干净的 CLIProxyAPI 工作区执行：
+首次克隆主仓库后，先初始化锁定官方基线的 CPA submodule：
 
 ```bash
-git checkout 78f0c4079e3e6273d65d03b5549cffc898703264
-git apply --check /path/to/billing/patch/cli-proxy-api-usage-context.patch
-git apply /path/to/billing/patch/cli-proxy-api-usage-context.patch
-git apply --check /path/to/billing/patch/cli-proxy-api-usage-identity.patch
-git apply /path/to/billing/patch/cli-proxy-api-usage-identity.patch
-git apply --check /path/to/billing/patch/cli-proxy-api-request-lifecycle-cancel.patch
-git apply /path/to/billing/patch/cli-proxy-api-request-lifecycle-cancel.patch
+git submodule update --init --recursive
+```
+
+然后从主仓库根目录执行：
+
+```bash
+git -C .externals/CLIProxyAPI apply --check ../../patch/cli-proxy-api-usage-context.patch
+git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-usage-context.patch
+git -C .externals/CLIProxyAPI apply --check ../../patch/cli-proxy-api-usage-identity.patch
+git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-usage-identity.patch
+git -C .externals/CLIProxyAPI apply --check ../../patch/cli-proxy-api-request-lifecycle-cancel.patch
+git -C .externals/CLIProxyAPI apply ../../patch/cli-proxy-api-request-lifecycle-cancel.patch
+cd .externals/CLIProxyAPI
 gofmt -w internal/pluginhost sdk/api/handlers sdk/cliproxy/usage sdk/pluginabi sdk/pluginapi
 go test -race ./internal/pluginhost ./sdk/api/handlers ./sdk/cliproxy/usage -count=1
 CGO_ENABLED=1 go build -o test-output ./cmd/server
 rm test-output
 ```
 
+应用补丁后 submodule 显示工作区修改是预期状态；主仓库只提交 submodule 的官方基线指针和 `patch/`，不提交官方仓库中的派生提交。
+
 billing 必须使用 RPC schema v4 重新构建；旧 billing 动态库会向下协商到旧 schema，无法获得 Usage 请求身份。
 
 ## 验证标准