diff --git a/CLAUDE.md b/CLAUDE.md index 7f05354..fd3a99c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -170,6 +170,13 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载 **重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。 5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。 改 `HASH_ROUNDS` 或拼接顺序会让存量 `users.json` 全部登录失败(已用独立 Python 实现逐字节核对过)。 +6. **`/api/v1/me` 是插件装饰扩展点,不是写死的端点**。`ipass_core::api::CoreExt::decorate_me` + 是身份端点的唯一装饰入口,由装配根(gateway)实现并把 `User` 与 `port` 一起传进来—— + 装饰能零额外 shm 查询就完成权限收敛(如 upstreams 按 `allowed_models` 过滤)。 + **加新字段给同事发现能力时,往 `decorate_me` 里塞,别另开 v1 端点**: + - 老 3 个 v1 端点(`/api/v1/{domains,upstreams,apix}`)保留不破坏既有客户端脚本 + - me 一个响应 = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略;同事拿一把 key 一个 me 拿全 + - 给前端 / 文档 / SDK 展示时也直接讲 me,不要再分别介绍三个端点 ## LLM API 代理(2026-09-10 新增) diff --git a/docs/plugin/PLUGIN_ARCHITECTURE.md b/docs/plugin/PLUGIN_ARCHITECTURE.md index 20eb4d5..521a8c0 100644 --- a/docs/plugin/PLUGIN_ARCHITECTURE.md +++ b/docs/plugin/PLUGIN_ARCHITECTURE.md @@ -104,7 +104,12 @@ core→plugin 循环依赖。解法是**扩展注册表**: ```rust pub trait CoreExt: Sync { fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰 - fn decorate_me(&self, username: &str, view: &mut Value) {} // me 装饰 + // 1.0.16 起:传 &User(不仅是 username),让装饰零额外 shm 查询就完成权限收敛 + // ——upstreams 按 allowed_models 过滤就是靠这里拿白名单。 + // port 从请求 Host 头取(http::host_port),让 view_all 能拼出正确的 + // `https://lm.mayishangshu.cn:88/...` base_url(部署在 88 必须带端口, + // 443 反代又不能带,见 CLAUDE.md「`base_url` 端口必须自适应」)。 + fn decorate_me(&self, _user: &User, _port: &str, _view: &mut Value) {} fn reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收 fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) } } @@ -115,6 +120,30 @@ preconfiguration 时 `set_ext(&GatewayExt)` 注入。这是方案对原设计的 原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/ me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。 +#### `decorate_me` = 能力目录的承载点(1.0.16 拍板) + +`/api/v1/me` **不是写死的端点**,它的所有插件侧数据都来自 `decorate_me`。 +拍板决策:**给同事展示能力(域名 / LLM 上游 / API 代理)时往 `decorate_me` 里塞, +不要另开 `/api/v1/catalog` 这类聚合端点**。原因: + +- 老 3 个 v1 端点(`/api/v1/{domains,upstreams,apix}`)保留不破坏既有客户端脚本 +- 一个 me = 身份 + 域名 + LLM 上游 + API 代理 + 用量 + 策略,同事拿一把 key 一个请求拿全 +- 上游白名单过滤靠 `User.allowed_models` 在装饰里就地完成,**不用让客户端先拉 me 再拉 + upstreams 自己过滤** + +当前 GatewayExt 在 `decorate_me` 里塞的字段: + +| 字段 | 来源 | 过滤/筛选 | +| --- | --- | --- | +| `domains` | `plugin_domain::domains::by_owner(user)` | 仅本人 | +| `llm_usage` | `plugin_llm::stats::user(name, now)` | 仅本人 | +| `policy` | core + plugin_domain config 常量 | — | +| `upstreams` | `plugin_llm::upstreams::view_all(&available(&user.allowed_models), port)` | **enabled + 白名单** | +| `apix` | `plugin_apix::apix::view_all(&enabled(), port)` | **仅 enabled** | + +⚠️ **新增装饰字段时一律在 `view` 之前算好 `port`**,并明确标注「从 Host 头取、不写死」—— +硬编码端口是已知坑(CLAUDE.md「`base_url` 端口必须自适应」实测踩过)。 + ### 2.4 `users::on_delete` 钩子(`core/users.rs`) 删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器: @@ -200,8 +229,12 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注 4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib; `[profile.release]` 只在 workspace 根。 5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。 -6. **验证 = `bash tests/run.sh all` 262 项全绿**;单 crate 迭代 - `cargo build -p plugin-llm`(秒级)。 +6. **验证 = `bash tests/run.sh all` 全绿**(**当前 281**:网关 102 + LLM 179); + 单 crate 迭代 `cargo build -p plugin-llm`(秒级)。 +7. **能力目录走 `decorate_me`,不要另开 `/api/v1/catalog`**。1.0.16 拍板: + 同事拿 key 一个 me 拿全(域名 + LLM 上游 + API 代理 + 用量 + 策略), + 老 3 个 v1 端点保留不破坏。新增插件侧能力展示字段一律往 `decorate_me` 里塞, + 别再另开 v1 端点把能力目录拆成 N 个调用。 --- @@ -214,6 +247,8 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注 - [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走 `plugin_llm::stats`(单一写入口) - [x] `/api/admin/trend` 留 gateway(组合根) +- [x] **`/api/v1/me` 承载能力目录(1.0.16)**:网关通过 `decorate_me` 把 domains / + upstreams / apix 一次性塞进 me,老 3 个 v1 端点保留不破坏 **1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten (插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、