docs(me+plugin): 登记 /api/v1/me 能力目录扩展点(1.0.16)

CLAUDE.md
- 「核心机制」补第 6 条:/api/v1/me 是插件装饰扩展点,不是写死端点;
  加新字段往 decorate_me 里塞,不要另开 v1 端点(避免老客户端脚本被破坏,
  也避免能力目录被拆成 N 个调用)
- 提示协作者给同事/文档/SDK 展示能力时直接讲 me

docs/plugin/PLUGIN_ARCHITECTURE.md
- §2.3 更新 decorate_me 签名为 (User, port)(1.0.16 引入):传 &User 让
  装饰零额外 shm 查询就能做权限收敛(upstreams 按 allowed_models 过滤);
  port 从 Host 头取(不写死是已知坑)
- 新增「decorate_me = 能力目录的承载点」子段:拍板决策 + 当前塞入字段表
  (domains / llm_usage / policy / upstreams / apix)+ 新增字段的纪律
- §6 纪律补第 7 条:能力目录走 decorate_me,不要另开 /api/v1/catalog
- §7 已拍板补 1.0.16 一条 "me 承载能力目录"

不动代码,仅文档同步。
This commit is contained in:
admin committed 2026-09-14 17:25:10 +08:00
1 parent 479024c61e
commit dfbfe5cf6c
2 files changed
+45 -3

No files matched your search

+7
View File
@@ -170,6 +170,13 @@ gateway 只剩:模块壳(7 条指令 + `ModuleConfig` 开关 + 变量/装载
**重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。 **重置 API Key 必须先摘旧 `ukey:`**,否则被换掉的 Key 照样能通过 LLM 鉴权(本项目踩过)。
5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。 5. **口令哈希必须与旧版逐位一致**:`sha256(salt + ":" + password)` 之后再迭代 1000 轮 `sha256(x + salt)`。
改 `HASH_ROUNDS` 或拼接顺序会让存量 `users.json` 全部登录失败(已用独立 Python 实现逐字节核对过)。 改 `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 新增) ## LLM API 代理(2026-09-10 新增)
+38 -3
View File
@@ -104,7 +104,12 @@ core→plugin 循环依赖。解法是**扩展注册表**:
```rust ```rust
pub trait CoreExt: Sync { pub trait CoreExt: Sync {
fn decorate_admin_users(&self, views: &mut [Value]) {} // 账号列表装饰 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 reclaim_on_delete(&self, username: &str) -> usize { 0 } // 删账号连带回收
fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) } fn validate_slots(&self, slots: &[String]) -> Result<(), String> { Ok(()) }
} }
@@ -115,6 +120,30 @@ preconfiguration 时 `set_ext(&GatewayExt)` 注入。这是方案对原设计的
原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/ 原方案把「删账号连带回收域名」塞在 on_delete 钩子里,落地时发现账号列表装饰/
me 装饰/白名单校验同样反向依赖插件数据,统一收进 CoreExt 更干净。 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`) ### 2.4 `users::on_delete` 钩子(`core/users.rs`)
删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器: 删账号时内核只清自己的键(`ukey:`/`sess:`/`fail:`),插件键空间由插件注册清理器:
@@ -200,8 +229,12 @@ gateway 保留:7 条指令解析(`ModuleConfig` 四开关 + `loc_switch` 注
4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib; 4. **`ngx` 走 `vendor/ngx-rust` path 依赖**;插件 rlib、gateway cdylib;
`[profile.release]` 只在 workspace 根。 `[profile.release]` 只在 workspace 根。
5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。 5. **`data/*.json` 持久化格式零变化**:所有字段带 `#[serde(default)]`,改字段先想存量文件。
6. **验证 = `bash tests/run.sh all` 262 项全绿**;单 crate 迭代 6. **验证 = `bash tests/run.sh all` 全绿**(**当前 281**:网关 102 + LLM 179);
`cargo build -p plugin-llm`(秒级)。 单 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 记账走 - [x] 下行鉴权/配额与记账原语下沉 core;用量解读归 plugin-llm;apix 记账走
`plugin_llm::stats`(单一写入口) `plugin_llm::stats`(单一写入口)
- [x] `/api/admin/trend` 留 gateway(组合根) - [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 **1.0.13 增补(2026-09-13)**:sso 上游化建议 4 条已合入内核——`User.extra` flatten
(插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、 (插件字段透传)+ `users::update_extra`、`state::split_value` 改 `rposition`、