# AGENTS.md — iPass cache 网关(插件仓) 面向 AI agent 的项目上手与改造约束。先读这份,再碰代码。 ## 这是什么 iPass 统一制品缓存网关的**插件仓**(内网 Gitea:`ipass/cache`)。 一个 nginx 入口 + 一把统一 `sk_` Key + 8 个路由(go / cargo / cargo-dl / pypi / pypi-files / npm / maven / docker v2),数据面用 nginx 原生 `proxy_cache`(本地磁盘),鉴权 / 计量 / 上游表由 Rust 模块管。 **本仓只含 cache 插件本身的源码**(见下「仓库边界」)。内核 `ipass-core`、模块壳 `gateway`、vendored `ngx-rust`、以及 domain/llm/apix 等其他子系统,**不在本仓**——它们属于主项目 `ipass/ipass`,本仓通过 git submodule(`deps/ipass`)引用,仅用于编译 cache 插件时解析依赖。 ## 仓库边界(改前必看) - ✅ 入库(本仓库职责):`rust/crates/plugin-cache`(cache 插件源码)、`conf`(cache 网关 nginx 模板)、`www`(cache 管理台前端)、`tests/cache`(cache 端到端)、`docs`、`AGENTS.md`、`docs/plugins.md`。 - 🔗 以 submodule 引入(**非本仓源码**,来自 `ipass/ipass`,不要在本仓改):`deps/ipass/`(`ipass-core` / `gateway` / `vendor/ngx-rust` / `plugin-domain` / `plugin-llm` / `plugin-apix`)。 - ❌ 不入库(见 `.gitignore`):`rust/target/`、`build/`、`*.dylib/*.so`、`tests/cache/.run-*/`(所有测试运行时目录)、`.workbuddy/`。 - 远程:`origin = http://ssw:sswsswssw@192.168.1.18:13300/ipass/cache.git`,分支 `main`。 > ⚠️ **避免相互干扰**:本仓与主项目 `ipass/ipass` 代码分离。cache 插件的全部修改只落在本仓;`ipass-core` 等内核/框架的修改回到 `ipass/ipass`。改内核共享内存 schema 前务必评估对所有插件的影响。 ## 代码布局 本仓是一个**单成员 cargo workspace**,只编 `plugin-cache`: | 组件 | 位置 | 版本 | 职责 | 归属 | |------|------|------|------|------| | `plugin-cache` | `rust/crates/plugin-cache` | 0.1.0 | 统一制品缓存:8 路由代理、命中计量、上游动态注入、管理 API、容量管理 | ★ 本仓库 | | `ipass-core` | `deps/ipass/rust/crates/ipass-core`(submodule) | 2.0.0 | 内核:共享内存 / 账号 / 会话 / 认证 / 存储 / 通用原语 | 主项目 `ipass/ipass` | | `gateway` | `deps/ipass/rust/gateway`(submodule) | 2.0.0 | 唯一 cdylib:聚合插件 `ngx_module_t`、FFI 边界 | 主项目 | | `vendor/ngx-rust` | `deps/ipass/rust/vendor/ngx-rust`(submodule) | — | vendored `ngx` + `nginx-sys`(离线编译) | 主项目(vendored) | | `plugin-domain` / `plugin-llm` / `plugin-apix` | `deps/ipass/rust/crates/*`(submodule) | 2.0.0 | 其他子系统 | 主项目各子系统 | `plugin-cache` 的依赖(`ipass-core` / `ngx` / `nginx-sys`)在 `rust/Cargo.toml` 中通过 `../deps/ipass/rust/...` 指向 submodule。依赖方向单向:`plugin-cache` → `ipass-core` → `vendor/ngx-rust` → nginx C 进程;跨 `.so` 不传 Rust 类型(否则双重 free),所以只有 `gateway` 是 cdylib,其余全是 rlib。 ## 构建 前置:本仓需要主项目代码来解析依赖。 ```bash git submodule update --init deps/ipass # 拉取 ipass-core / gateway / ngx-rust ... ``` - **仅类型检查 / 编译插件(rlib)**:`cd rust && cargo build -p plugin-cache`。 这会顺着 `../deps/ipass` 把 `ipass-core` 与 `nginx-sys` 一起编出来(nginx-sys 需要 `NGINX_SOURCE_DIR` / `NGINX_BUILD_DIR` 指向一份 nginx 源码,见技能 `nginx-rs-module-local-verify`)。 - **产出可加载模块(cdylib)并跑端到端**:本仓没有 `gateway`(cdylib 在 submodule 里)。要在本机得到 `libipass_gateway.dylib` 并运行 `tests/cache/*.sh`,请在主项目 `ipass/ipass` 中装配 cache 插件: 1. 把本仓的 `rust/crates/plugin-cache` 放到 `ipass/ipass/rust/crates/plugin-cache`(或让主项目以 submodule/override 消费本仓); 2. 在 `ipass/ipass/rust/Cargo.toml` 的 `members` 加 `"crates/plugin-cache"`,在 `ipass/ipass/rust/gateway/Cargo.toml` 的 `[dependencies]` 加 `plugin-cache.workspace = true`; 3. 按技能 `nginx-rs-module-local-verify` 编译 `gateway` 得到 `.dylib`,再以 `tests/cache/dev-server.sh` / `test-cache*.sh` 验证。 > 主项目 `ipass/ipass` 当前的 `gateway` 只装配 domain/llm/apix(不含 cache),所以上面第 2 步是接 cache 的唯一接线点。 - macOS 编译 nginx 必须 `-DNGX_HAVE_SCHED_SETAFFINITY=0`;`[profile.release]` 只能放 workspace 根(`panic="abort"`,丢了意味着 panic 跨 FFI 边界展开进 nginx)。 ## 端到端验证(基线,连跑两轮一致) cache 测试都在 `tests/cache/`: - `tests/cache/test-cache.sh` 23/23、`tests/cache/test-ipass-cache.sh` 24/24、`tests/cache/validate-prod-conf.sh` ✅、`tests/cache/e2e-auth.sh` 29/29。 - 容量管理:`tests/cache/test-cache-capacity.sh` 48/48。 - 跑法见 `tests/cache/run.sh`(或单独 `bash tests/cache/<脚本>`);任何「读上游日志做断言」的步骤先断言本次 MISS,且测试开头清 `$RUN/cache`。 ## 不可动摇的架构约定(改前要懂) 1. 上游地址 / 凭据只存共享内存 `cx:`(管理台写穿,落盘 `data/cache-upstreams.json`);conf 只出现变量名 `$cache_target` / `$cache_host` / `$cache_auth`。改上游不改 conf、不 reload。 2. `$cache_key` 必须含 query(`:[?args]`);`proxy_cache_key = $cache_key$request_method$http_accept`(不含 `sk_`)。 3. `sk_` 绝不外传上游:出站 `Authorization` 三段式(本路由凭据 → 透传客户端值 → 丢弃网关 `sk_`);同时抹掉 `x-api-key` / `api-key`。 4. 未配上游的路由 → 503(不是 500)。 5. **唯一 conf 渲染器**:`tests/cache/lib-render.sh`(`cache_render_prod_conf` / `cache_write_upstreams`)。禁止手抄第二份「生产 conf → 测试前缀」替换逻辑。 6. 清理缓存**只删文件,绝不删 `cache/` 目录本身**(否则 `[crit] mkdir failed` + 客户端断开);批量清理用 `find <子树> -type f -delete` + 残留自检。 7. 生成 / 改写 conf 一律用 python,不用 BSD `sed`;脚本里 `curl` 统一 `--noproxy '*'`(本机代理会吞 localhost)。 ## 提交规范 - 只提交源码(`.gitignore` 已排除产物);push 到 `ipass/cache` 的 `main`。 - **改动范围**:只动本仓的 `plugin-cache` / `conf` / `www` / `tests/cache` / `docs`。若要升级 `ipass-core` 等,请到 `ipass/ipass` 改,或在本仓 `git submodule update` 拉新提交后 `git add deps/ipass`。**禁止在 `deps/ipass/` 里直接改代码**(那是主项目源码)。 - 大 push 设 `http.postBuffer=524288000`;若报 `unable to get credential storage lock`,先 `rm -f ~/.git-credentials.lock`(无 git 进程时)。 ## 插件边界 见 [`docs/plugins.md`](docs/plugins.md)。