From df63306b245905a20dad3dc595344525b0ec53c3 Mon Sep 17 00:00:00 2001 From: admin Date: Sat, 31 Oct 2026 11:23:16 +0800 Subject: [PATCH] =?UTF-8?q?feat(mcp):=20=E6=8E=88=E6=9D=83=E9=97=AD?= =?UTF-8?q?=E7=8E=AF=20+=20=E6=B5=81=E7=A8=8B=E6=A8=A1=E6=9D=BF=20+=20?= =?UTF-8?q?=E5=9F=BA=E7=BA=BF=E9=80=82=E9=85=8D=E5=99=A8=EF=BC=88P1=20?= =?UTF-8?q?=E4=B8=BB=E4=BD=93=E5=AE=8C=E6=88=90=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 授权闭环 4 工具:authorize.grant / revoke / effective(四源并集 + 应用过滤两组数)+ user.create —— effective 是「授权了但看不见」的唯一诊断入口;user.create 建非管理员账号让闭环可自证 - prompts 3 模板:new_business_module / diagnose_menu_not_visible / verify_all —— 测试核对模板里引用的工具 id 是否存在(防腐烂) - 新 crate sspf-adapter-baseline:PlatformAdapter 第二实现,5 个只读 op + 形状归一化 —— 用 hyper::client::conn::http1,只支持 http://,口令传密文 - 新增 AR6 与 baseline-smoke.sh(10 条);mcp-smoke 23 → 32 条 - 影响:测试 282 → 306;十一闸全绿;工具 15 → 19;内存仍 7 MB --- .workbuddy/memory/2026-10-31.md | 71 ++ CLAUDE.md | 18 +- Cargo.lock | 32 + Cargo.toml | 3 +- PLAN.md | 18 +- crates/sspf-adapter-baseline/Cargo.toml | 24 + .../sspf-adapter-baseline/examples/probe.rs | 118 +++ crates/sspf-adapter-baseline/src/http.rs | 235 ++++++ crates/sspf-adapter-baseline/src/lib.rs | 407 ++++++++++ crates/sspf-adapter-baseline/src/map.rs | 436 ++++++++++ crates/sspf-mcp/src/lib.rs | 1 + crates/sspf-mcp/src/prompts.rs | 409 ++++++++++ crates/sspf-mcp/src/server.rs | 76 +- crates/sspf-mcp/src/tools/mod.rs | 9 +- crates/sspf-mcp/src/tools/permission.rs | 309 +++++++ docs/mcp.md | 95 ++- scripts/baseline-smoke.sh | 202 +++++ scripts/check-arch.sh | 20 +- scripts/mcp-smoke.sh | 78 +- src/backend/src/mcp_adapter.rs | 755 ++++++++++++++++++ 20 files changed, 3287 insertions(+), 29 deletions(-) create mode 100644 crates/sspf-adapter-baseline/Cargo.toml create mode 100644 crates/sspf-adapter-baseline/examples/probe.rs create mode 100644 crates/sspf-adapter-baseline/src/http.rs create mode 100644 crates/sspf-adapter-baseline/src/lib.rs create mode 100644 crates/sspf-adapter-baseline/src/map.rs create mode 100644 crates/sspf-mcp/src/prompts.rs create mode 100644 crates/sspf-mcp/src/tools/permission.rs create mode 100755 scripts/baseline-smoke.sh diff --git a/.workbuddy/memory/2026-10-31.md b/.workbuddy/memory/2026-10-31.md index 053933c..58ae3ab 100644 --- a/.workbuddy/memory/2026-10-31.md +++ b/.workbuddy/memory/2026-10-31.md @@ -499,3 +499,74 @@ MCP 客户端都会收 stderr 进日志,生产无影响;但 **shell 里测 `cargo test` **282** |十道闸门全绿 | `mcp-smoke` **23/23** +--- + +## P1-d:授权闭环 + prompts 模板 + 基线适配器(11:00 收工) + +三件事一起做,主线是「**把 AI 从能看推进到能干活并自证**」。 + +### 1. 授权闭环(4 个新工具,总工具数 15 → 19) + +`permission.authorize.grant` / `authorize.revoke` / `effective` / `user.create`。 + +**为什么必须有 `effective`**:`base_authorize` 是扁平多态表 +(`f_object_type` = user/role/organize/position + `f_item_id` = 菜单), +命中判定是**四源并集**。「授权了但看不见」有四种完全不同的根因, +`authorize.list` 只看一源回答不了。`effective` 同时返回两组数: + +- `fourSource` —— 四源并集(授权表**不带应用维度**) +- `visible` —— 再与当前应用菜单求交(这才是能点到的) + +两者不一致 ⇒ 授权指向了别的应用的菜单。这是把「排查」变成「读一个字段」。 + +**为什么必须有 `user.create`**:`is_admin == 1` 在守卫第一条判据就短路, +用 admin 测菜单可见性等于没测。没有非管理员账号,授权闭环无法自证。 +刻意把 `isAdministrator` 硬编码 false —— 不让 AI 顺手造超管。 + +**踩坑**:`base_role_relation` 里用户标识在 `f_object_id`(配 `f_object_type='user'`), +`base_user_relation` 才有 `f_user_id`。两张关系表列名不对称,抄错一句就静默不生效。 + +### 2. prompts 模板(3 个) + +`new_business_module`(5 步 + 失败对照表)/ `diagnose_menu_not_visible`(五步定位)/ +`verify_all`(全量闸门)。 + +🔴 **防腐烂的测试**:模板正文里会出现工具 id,工具改名后模板变错误指导且没人发现。 +`prompts.rs` 的测试扫出正文里所有 `域.动作` 字符串,逐个到 `ALL_TOOLS` 核对 —— +引用不存在的工具直接测试失败。这是「文档即代码」的具体落地。 + +### 3. BaselineHttpAdapter(crates/sspf-adapter-baseline) + +`PlatformAdapter` 的第二种实现,19 个测试 + 探针 example + `baseline-smoke.sh` 10 条。 + +**核心不是端点映射,是形状归一化**:baseline 返回 `{code,msg,data:{list,pagination}}`, +native 返回 `{count, users}`。不统一形状,P4 对账每一条都是差异,看不出业务问题。 +所以 adapter 负责:`list` → `users/roles/menus/types`、`organize` → `organizeId`、 +裁掉 native 没有的键。 + +**只映射 5 个只读 op 是刻意的**:baseline 是业务 API,没有元数据 API, +硬凑「列结构」「查索引」会造出语义不对的工具。不支持的 op 在**发请求前**返回 +`CAPABILITY_UNSUPPORTED` + 切 native 的建议。 + +**三个技术选择**: +- HTTP 客户端用 `hyper::client::conn::http1`(不用 reqwest:依赖树大; + 不用 hyper-util 的 client-legacy:会拉 tower-service/socket2,为连接池付费) +- 只支持 `http://`,`https://` 构造期直接报错(不静默降级成明文) +- 口令要传**密文**(`--enc` 生成):复制 cipher 会漂移,下沉 contract 破坏 AR4 + +**验证方式**:用适配器打**自己的 HTTP 端口**(本仓内核就是契约的实现)。 +这等于跨进程走一遍契约 —— 也是 P4 影子对账的预演。 + +### 新增闸门 + +- `check-arch.sh` 加 **AR6**:`sspf-adapter-baseline` 依赖 ⊆ 工具契约层 + HTTP 客户端, + 不许依赖内核 store(否则第二种后端被钉死在本进程旁) +- `scripts/baseline-smoke.sh`:10 条(登录 / 裸对象 health / 三处形状归一化 / 不支持拦截) +- `mcp-smoke.sh` 23 → 32 条(授权闭环 6 条 + prompts 3 条) + +### 数字 + +`cargo test` **306**(+24)|十一道闸门全绿 +| `mcp-smoke` **32/32** | `baseline-smoke` **10/10** | 内存 7 MB + + diff --git a/CLAUDE.md b/CLAUDE.md index 8e67dd6..c9de2ea 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -201,7 +201,7 @@ ssw-platform/ --- -## 6. 验收闸门(十道,缺一不可) +## 6. 验收闸门(十一道,缺一不可) | 类别 | 脚本 | 测什么 | 当前状态 | |---|---|---|---| @@ -209,18 +209,19 @@ ssw-platform/ | 静态 | `scripts/check-boundary.sh` | 分层红线 CP1–CP6(平台层不许有业务知识) | 已绿(11/11) | | 静态 | `scripts/check-contract.sh` | 契约端点表 ↔ 代码真实路由(CC2–CC10,含官方端点台账 CC10) | 已绿(10/10) | | 静态 | `scripts/check-citations.sh` | 文档引文 `路径:行号` 逐条核对 | 4/4 已绿(192 条引文全解析;CIT3 依赖官方 DDL,缺失则 `⏭`) | -| **静态·架构** | **`scripts/check-arch.sh`** | **crate 依赖纪律 AR1–AR5 + 内存红线 MEM1–MEM2(`--self-test` 反自证)** | **6/7 已绿(AR5 待 MCP)** | +| **静态·架构** | **`scripts/check-arch.sh`** | **crate 依赖纪律 AR1–AR6 + 内存红线 MEM1–MEM2(`--self-test` 反自证)** | **8/8 已绿** | | **静态·命名** | **`scripts/check-naming.sh`** | **内部标识剥离 NM1–NM3 阻断 + NM4 注释量化(`--strict` 可升级)** | **3/0 已绿(69 处注释技术债)** | | 契约尺子·面 A | `scripts/perm-smoke.sh` | 43 条(面 A 契约闭环 32 + 真实业务模块 asset 9 + 多应用 `App-Code` 路由 2) | 已绿 | | 契约尺子·面 B | `scripts/perm-smoke-jnpf.sh` | 23 条(官方形状 18 + 多应用 `App-Code` 路由 1 + 用户 CRUD 4,诚实记 SKIP) | **23/23 已绿** | -| **契约尺子·MCP** | **`scripts/mcp-smoke.sh`** | **23 条:4 元工具上限 / 分层加载 / 自提示 / 业务失败不误报协议错 / 结构注入防护 / 写工具校验 / stdout 纯 NDJSON** | **23/23 已绿** | +| **契约尺子·MCP** | **`scripts/mcp-smoke.sh`** | **32 条:4 元工具上限 / 分层加载 / 自提示 / 业务失败不误报协议错 / 结构注入防护 / 写工具校验 / 授权闭环 / prompts 模板 / stdout 纯 NDJSON** | **32/32 已绿** | +| **契约尺子·双后端** | **`scripts/baseline-smoke.sh`** | **10 条:基线适配器自动登录 / health 裸对象 / 形状归一化(list→menus、organize→organizeId、裁剪多余键)/ 不支持的 op 发请求前拦下** | **10/10 已绿** | | **运行时·内存** | **`scripts/mem-budget.sh`** | **空载物理内存(vmmap `Physical footprint`)是否 ≤ 预算** | **7 MB / 40 MB 预算 已绿** | 🔴 期望值只有一处:`docs/contract.md` 附录 A(机器可读 `[ENDPOINT]` / `[OFFICIAL]` 等),由 `scripts/contract_expect.py` 解析。 每把尺子结尾比对「实际断言数 vs 契约登记数」,对不上即失败 —— 尺子不会被悄悄改弱。 -**加任何业务模块 / 改任何契约 / 加任何 crate 依赖 / 改任何内部标识,九道闸门必须全绿才算完成。** +**加任何业务模块 / 改任何契约 / 加任何 crate 依赖 / 改任何内部标识,十一道闸门必须全绿才算完成。** -🔴 **`cargo test --workspace` 当前 240 条**(内核 88+8+集成 124 + contract 13 + sdk 2 + pack-asset 5)—— +🔴 **`cargo test --workspace` 当前 306 条**(内核 + contract 13 + store 17 + sdk 2 + pack-asset 5 + mcp 45 + adapter-baseline 19 + 集成测试)—— 拆 crate 后总数会变,**不许把断言数写死**,跑一遍看实际值。 cipher 自证(免 node):`./target/release/ssw-platform --enc 123456`。 @@ -271,18 +272,19 @@ cp .env.example .env && ./run.sh install && ./run.sh dev ```bash cargo build --release # 编译(workspace 根,含 crates/* 与 packs/*) -cargo test --workspace # 单测(当前 240 条) +cargo test --workspace # 单测(当前 306 条) bash run.sh dev # 起后端(30010) + 前端(5173) bash scripts/perm-smoke.sh # 面 A 43 条 bash scripts/perm-smoke-jnpf.sh # 面 B 23 条 bash scripts/check-boundary.sh # 分层红线 CP1–CP6 bash scripts/check-contract.sh # 契约端点 ↔ 代码路由 对账 bash scripts/check-module.sh # 业务模块 10 接触点 -bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR5 + 内存红线 MEM1–MEM2 +bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR6 + 内存红线 MEM1–MEM2 bash scripts/check-arch.sh --self-test # 反自证:造违规必须被抓到 bash scripts/check-naming.sh # 内部标识剥离(NM1–NM3 阻断 / NM4 注释量化) bash scripts/check-naming.sh --strict # 注释里的原厂名也算红(技术债清零时用) -bash scripts/mcp-smoke.sh # MCP 工具层契约(4 元工具 + 分层加载) +bash scripts/mcp-smoke.sh # MCP 工具层契约 32 条(4 元工具 + 分层加载 + 授权闭环 + prompts) +bash scripts/baseline-smoke.sh # 双后端契约 10 条(HTTP 适配器 + 形状归一化) bash scripts/mem-budget.sh # 空载内存实测(P0 出口判据,预算 40 MB) cargo test -p sspf-pack-asset # 业务包独立可编(业务包剥离的硬证据) ./target/release/ssw-platform --mcp # 起 MCP stdio 服务(供 AI 直接驱动,见 docs/mcp.md) diff --git a/Cargo.lock b/Cargo.lock index 24f4df8..3a20db0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -536,6 +536,7 @@ dependencies = [ "pin-project-lite", "smallvec", "tokio", + "want", ] [[package]] @@ -1066,6 +1067,22 @@ dependencies = [ "windows-sys", ] +[[package]] +name = "sspf-adapter-baseline" +version = "0.1.0" +dependencies = [ + "bytes", + "http", + "http-body-util", + "hyper", + "hyper-util", + "serde", + "serde_json", + "sspf-contract", + "sspf-mcp", + "tokio", +] + [[package]] name = "sspf-contract" version = "0.1.0" @@ -1287,6 +1304,12 @@ dependencies = [ "once_cell", ] +[[package]] +name = "try-lock" +version = "0.2.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b" + [[package]] name = "twox-hash" version = "2.1.5" @@ -1343,6 +1366,15 @@ version = "0.9.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" +[[package]] +name = "want" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec4cdd0dd910afe868b7ef477227d8d538b46b3075031afee8a9f2acb0a2ed0b" +dependencies = [ + "try-lock", +] + [[package]] name = "wasi" version = "0.11.1+wasi-snapshot-preview1" diff --git a/Cargo.toml b/Cargo.toml index f9491f6..3efe59e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -13,7 +13,8 @@ [workspace] # src/backend = 内核;crates/* = 平台侧 crate;packs/* = 业务包(只依赖 sspf-sdk) -members = ["src/backend", "crates/*", "packs/*"] +members = [ + "src/backend", "crates/*", "packs/*"] resolver = "2" [workspace.package] diff --git a/PLAN.md b/PLAN.md index f8dfcea..b7cdbb2 100644 --- a/PLAN.md +++ b/PLAN.md @@ -256,7 +256,7 @@ ssw-platform/ | 平台/业务分层 | ✅ `check-boundary.sh` 钉住 | 升级为 crate 级隔离 | **P0 已拆 contract / store / sdk;asset 包可独立编译;`jnpf.rs`→`face_b.rs`** | | 低代码元数据引擎 | ❌ 无 | visualdev 同构 + 动态 CRUD | **全新,P2 主体** | | 业务包格式 | 🟡 `pack.toml` 已定稿、`packs/asset` 已有样板 | 导入导出工具 | **P3** | -| MCP 工具面 | 🟡 **骨架已落地**:4 元工具 + registry + 分层加载 + 原生适配器 + 4 个业务工具 | 约 55 个业务工具 + `BaselineHttpAdapter` | **P1 进行中** | +| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 19 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 form/model/workflow) | P1 收尾 | | 影子对账 | ❌ 无 | 语料库 + 归一化比对 | **全新,P4** | | 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 | @@ -831,13 +831,19 @@ tools/diff-harness/ **P1 已完成(2026-10-31)**: - `crates/sspf-mcp`:协议(stdio NDJSON)+ registry + 4 元工具 + 五段自提示 + resources -- `NativeAdapter`(进程内,共用 `AppState`)+ `--mcp` 子命令 -- 业务工具 4 个:`context.get` / `schema.table.list` / `schema.table.describe` / `menu.tree` -- `scripts/mcp-smoke.sh`:13 条契约尺子(含「stdout 纯 NDJSON」「业务失败不误报协议错」) +- `NativeAdapter`(进程内,共用 `AppState`)+ `--mcp` 子命令 + `--mcp --with-http` 双形态 +- 业务工具 **19 个**:context(1) / schema(3) / menu(3) / permission(6) / dict(3) / data(2) +- **授权闭环**:`authorize.grant` / `authorize.revoke` / `effective`(四源并集 + 应用过滤两组数) + + `user.create`(建非管理员账号,让「授权是否真的生效」可验证) +- **多步模板 3 个**:`new_business_module` / `diagnose_menu_not_visible` / `verify_all`; + 测试会核对模板里引用的工具 id 是否真实存在(防腐烂) +- **`BaselineHttpAdapter`**(`crates/sspf-adapter-baseline`):5 个只读 op 的端点映射 + + **形状归一化**(`{code,msg,data:{list}}` → native 形状),P4 对账的前置件 +- 两道尺子:`mcp-smoke.sh` 32 条、`baseline-smoke.sh` 10 条 - 接入说明见 `docs/mcp.md` -**P1 待做**:`BaselineHttpAdapter`(P4 前)、业务工具补到约 55 个、`prompts/*` 模板、 -「与 HTTP 同进程」的双形态(当前 MCP / HTTP 各占一个数据目录)。 +**P1 待做**:业务工具补到约 55 个(缺 form / model / workflow 三大域)、 +基线适配器按对账需要扩展 op。 > ⚠️ 轨道 A 的定位要摆正:它是**过渡期的开发加速器 + 对账基准**,不是终态。 > 终端产品交付形态只有 Rust 版(判断 ⑥)。 diff --git a/crates/sspf-adapter-baseline/Cargo.toml b/crates/sspf-adapter-baseline/Cargo.toml new file mode 100644 index 0000000..f50b958 --- /dev/null +++ b/crates/sspf-adapter-baseline/Cargo.toml @@ -0,0 +1,24 @@ +[package] +name = "sspf-adapter-baseline" +version.workspace = true +edition.workspace = true +rust-version.workspace = true +description = "基线平台 HTTP 适配器:让同一套 MCP 工具打远端 Java 后端(P4 影子对账用)" + +[dependencies] +# 工具契约层:实现 PlatformAdapter,复用 ToolError / EnvInfo +sspf-mcp = { path = "../sspf-mcp" } +sspf-contract = { path = "../sspf-contract" } + +serde = { workspace = true } +serde_json = { workspace = true } +tokio = { workspace = true } +http = { workspace = true } + +# 🔴 HTTP 客户端只用 hyper 的**底层 conn API**(`client` + `http1`), +# 不用 hyper-util 的 `client-legacy`(那会拉进 tower-service / socket2, +# 而 P4 对账是 localhost 串行请求,不需要连接池与 keep-alive 管理)。 +hyper = { version = "1", features = ["client", "http1"] } +hyper-util = { version = "0.1", features = ["tokio"] } +http-body-util = "0.1" +bytes = "1" diff --git a/crates/sspf-adapter-baseline/examples/probe.rs b/crates/sspf-adapter-baseline/examples/probe.rs new file mode 100644 index 0000000..72933ab --- /dev/null +++ b/crates/sspf-adapter-baseline/examples/probe.rs @@ -0,0 +1,118 @@ +//! probe —— 用基线适配器打一个**真实 HTTP 后端**,对每个 op 打印结果。 +//! +//! ## 为什么需要它 +//! +//! `BaselineHttpAdapter` 的单元测试只能验证「形状归一化」这半边; +//! 「端点映射对不对、登录流程通不通」必须打真实服务才能证明。 +//! +//! 同时这也是 **P4 影子对账的探针雏形**: +//! 同一个 op 分别用 native 与 baseline 跑,输出可直接 diff。 +//! +//! ## 用法 +//! +//! ```bash +//! # 1. 起一个 HTTP 后端(它就是契约的实现,可以是被测的基线平台,也可以是本仓内核) +//! PGLITE_DIR=/tmp/db PORT=30994 ./target/debug/ssw-platform & +//! +//! # 2. 取密文口令 +//! ENC=$(./target/debug/ssw-platform --enc 123456) +//! +//! # 3. 探针(账号 + 密文 ⇒ 自动登录) +//! cargo run -p sspf-adapter-baseline --example probe -- \ +//! http://127.0.0.1:30994 admin "$ENC" +//! ``` +//! +//! 输出是一行一个 JSON(NDJSON),便于 `jq` / python 消费: +//! +//! ```json +//! {"op":"permission.role.list","ok":true,"data":{"count":2,...}} +//! {"op":"schema.table.list","ok":false,"error":{"code":"CAPABILITY_UNSUPPORTED",...}} +//! ``` + +use sspf_adapter_baseline::BaselineHttpAdapter; +use sspf_mcp::adapter::PlatformAdapter; +use serde_json::json; + +/// 逐个探测的 op(含一个**预期不支持**的,用来验证边界声明是诚实的)。 +const OPS: &[&str] = &[ + "context.get", + "menu.tree", + "permission.user.list", + "permission.role.list", + "dict.type.list", + // 下面这条应当返回 CAPABILITY_UNSUPPORTED —— 必须在**发请求前**拦下 + "schema.table.list", +]; + +#[tokio::main] +async fn main() { + let mut args = std::env::args().skip(1); + let base = match args.next() { + Some(v) => v, + None => { + eprintln!("用法: probe "); + eprintln!("示例: probe http://127.0.0.1:30994 admin \"$(ssw-platform --enc 123456)\""); + std::process::exit(2); + } + }; + let account = args.next().unwrap_or_else(|| "admin".to_string()); + let cipher = match args.next() { + Some(v) => v, + None => { + eprintln!("缺少 password_cipher(用 `ssw-platform --enc <明文>` 生成)"); + std::process::exit(2); + } + }; + + let adapter = match BaselineHttpAdapter::with_credentials(&base, &account, &cipher) { + Ok(a) => a, + Err(e) => { + eprintln!("构造适配器失败: {e}"); + std::process::exit(2); + } + }; + + // 环境信息(登录也在这一步发生) + let env = adapter.describe_env().await; + println!( + "{}", + json!({ + "op": "describe_env", + "ok": true, + "data": { + "backend": env.backend, + "version": env.version, + "app_code": env.app_code, + "system_id": env.system_id, + "user": env.user, + "tables": env.tables, + "capabilities": env.capabilities, + } + }) + ); + + for op in OPS { + let args = match *op { + "permission.user.list" => json!({ "limit": 5 }), + _ => json!({}), + }; + match adapter.invoke(op, args).await { + Ok(data) => println!("{}", json!({ "op": op, "ok": true, "data": data })), + Err(e) => println!( + "{}", + json!({ + "op": op, + "ok": false, + "error": { + "code": e.code, + "message": e.message, + "hints": e.hints, + "next_actions": e.next_actions.iter() + .map(|n| json!({"tool": n.tool, "why": n.why})) + .collect::>(), + } + }) + ), + } + } +} diff --git a/crates/sspf-adapter-baseline/src/http.rs b/crates/sspf-adapter-baseline/src/http.rs new file mode 100644 index 0000000..1ec4d4b --- /dev/null +++ b/crates/sspf-adapter-baseline/src/http.rs @@ -0,0 +1,235 @@ +//! http —— 极简 HTTP/1.1 客户端(hyper 底层 conn API)。 +//! +//! ## 为什么不用 reqwest / hyper-util 的 `client-legacy` +//! +//! | 方案 | 为什么不选 | +//! |---|---| +//! | `reqwest` | 依赖树巨大(rustls + 一堆),而本机拉新 crate 受限 | +//! | `hyper-util::client-legacy` | 会拉进 `tower-service` / `socket2`,为「连接池 + 负载均衡」付费 | +//! | `hyper::client::conn::http1` ✅ | 只要 hyper 本身,一次一连接,语义最直白 | +//! +//! ## 适用场景的诚实说明 +//! +//! 每次调用新建一条 TCP 连接,**没有连接池、没有 keep-alive**。 +//! 这在 P4 影子对账(localhost、串行、几百条请求)完全够用; +//! 若将来要做高频转发,再换 `client-legacy`,接口不变。 +//! +//! 🔴 **只支持 `http://`**。基线平台内网部署是明文 HTTP; +//! 要打 `https://` 必须引入 TLS 栈(当前刻意不做,避免依赖膨胀)。 +//! 传 `https://` ⇒ 构造期直接报错,不静默降级。 + +use bytes::Bytes; +use http_body_util::{BodyExt, Full}; +use hyper::client::conn::http1; +use hyper::{Request, StatusCode}; +use hyper_util::rt::TokioIo; + +/// HTTP 方法(转出给 `lib.rs` / `map.rs` 用,避免它们各自 import hyper)。 +pub use hyper::Method; + +/// 解析后的服务地址(`http://host:port`)。 +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Endpoint { + /// 主机(IPv4 / 域名 / `[::1]` 已去方括号)。 + pub host: String, + /// 端口。 + pub port: u16, +} + +impl Endpoint { + /// 从 `http://host:port[/path]` 解析。 + /// + /// 🔴 只接受 `http://`:`https://` 会明确报错,不静默降级成明文 + /// (那会把口令以明文发出去,比报错糟得多)。 + pub fn parse(base: &str) -> Result { + let rest = base.trim().trim_end_matches('/'); + let Some(rest) = rest.strip_prefix("http://") else { + if rest.starts_with("https://") { + return Err(format!( + "只支持 http://(当前构建未引入 TLS):{base}。\ + 基线平台内网是明文 HTTP;要打 https 需先加 TLS 栈。" + )); + } + return Err(format!("base_url 必须形如 http://host:port,收到: {base}")); + }; + + // 去掉可能存在的路径部分(`http://h:p/api` ⇒ `h:p`) + let authority = rest.split('/').next().unwrap_or(rest); + if authority.is_empty() { + return Err(format!("base_url 缺少主机: {base}")); + } + + // IPv6 字面量 `[::1]:30010` + if let Some(stripped) = authority.strip_prefix('[') { + let Some((host, tail)) = stripped.split_once(']') else { + return Err(format!("IPv6 地址格式不对: {authority}")); + }; + let port = match tail.strip_prefix(':') { + Some(p) => p + .parse::() + .map_err(|_| format!("端口不合法: {p}"))?, + None => 80, + }; + return Ok(Self { + host: host.to_string(), + port, + }); + } + + match authority.rsplit_once(':') { + Some((host, port)) => { + if host.is_empty() { + return Err(format!("base_url 缺少主机: {base}")); + } + let port = port + .parse::() + .map_err(|_| format!("端口不合法: {port}"))?; + Ok(Self { + host: host.to_string(), + port, + }) + } + None => Ok(Self { + host: authority.to_string(), + port: 80, + }), + } + } + + /// `host:port`(连 TCP 用)。 + fn authority(&self) -> String { + if self.host.contains(':') { + format!("[{}]:{}", self.host, self.port) + } else { + format!("{}:{}", self.host, self.port) + } + } +} + +/// 一次 HTTP 调用的结果。 +#[derive(Debug, Clone)] +pub struct HttpResponse { + /// 状态码。 + pub status: u16, + /// 响应体(已读全)。 + pub body: Bytes, +} + +impl HttpResponse { + /// 按 UTF-8 取文本(非法字节用替换字符,不 panic)。 + pub fn text(&self) -> String { + String::from_utf8_lossy(&self.body).to_string() + } +} + +/// 发一个请求。 +/// +/// - `path` 必须带前导 `/`(可含 query string) +/// - `headers` 里的名字用规范小写(`authorization` / `vue-version` / `app-code`) +pub async fn call( + ep: &Endpoint, + method: Method, + path: &str, + headers: &[(&str, String)], + body: Option, + timeout: std::time::Duration, +) -> Result { + let fut = async { + let stream = tokio::net::TcpStream::connect(ep.authority()) + .await + .map_err(|e| format!("连不上 {}: {e}", ep.authority()))?; + // Nagle 会让小请求多等 40ms;对账要跑几百条,关掉。 + let _ = stream.set_nodelay(true); + + let io = TokioIo::new(stream); + let (mut sender, conn) = http1::handshake(io) + .await + .map_err(|e| format!("HTTP 握手失败: {e}"))?; + + // 连接任务:请求结束后自然退出(http1 一次一连接) + tokio::spawn(async move { + let _ = conn.await; + }); + + let uri = format!("http://{}{}", ep.authority(), path); + let mut builder = Request::builder().method(method).uri(uri); + for (k, v) in headers { + builder = builder.header(*k, v); + } + let req = builder + .body(Full::new(body.unwrap_or_default())) + .map_err(|e| format!("构造请求失败: {e}"))?; + + let resp = sender + .send_request(req) + .await + .map_err(|e| format!("发送请求失败: {e}"))?; + let status = resp.status(); + let bytes = resp + .into_body() + .collect() + .await + .map_err(|e| format!("读响应体失败: {e}"))? + .to_bytes(); + + Ok::(HttpResponse { + status: status.as_u16(), + body: bytes, + }) + }; + + match tokio::time::timeout(timeout, fut).await { + Ok(r) => r, + Err(_) => Err(format!("请求超时({}ms): {path}", timeout.as_millis())), + } +} + +/// 判断状态码是否成功(2xx)。 +pub fn is_success(status: u16) -> bool { + StatusCode::from_u16(status) + .map(|s| s.is_success()) + .unwrap_or(false) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn parses_host_and_port() { + let ep = Endpoint::parse("http://127.0.0.1:30010").unwrap(); + assert_eq!(ep.host, "127.0.0.1"); + assert_eq!(ep.port, 30010); + + let ep = Endpoint::parse("http://localhost").unwrap(); + assert_eq!(ep.port, 80, "缺端口默认 80"); + + let ep = Endpoint::parse("http://h:8080/api/").unwrap(); + assert_eq!(ep.host, "h"); + assert_eq!(ep.port, 8080); + + let ep = Endpoint::parse("http://[::1]:9000").unwrap(); + assert_eq!(ep.host, "::1"); + assert_eq!(ep.port, 9000); + } + + /// 🔴 https 必须明确拒绝 —— 静默降级会把口令以明文发出去。 + #[test] + fn rejects_https_explicitly() { + let e = Endpoint::parse("https://example.com").unwrap_err(); + assert!(e.contains("只支持 http://"), "错误信息要说清楚: {e}"); + } + + #[test] + fn rejects_garbage() { + assert!(Endpoint::parse("127.0.0.1:30010").is_err()); + assert!(Endpoint::parse("http://").is_err()); + assert!(Endpoint::parse("http://h:notaport").is_err()); + } + + #[test] + fn ipv6_authority_is_bracketed() { + let ep = Endpoint::parse("http://[::1]:9000").unwrap(); + assert_eq!(ep.authority(), "[::1]:9000"); + } +} diff --git a/crates/sspf-adapter-baseline/src/lib.rs b/crates/sspf-adapter-baseline/src/lib.rs new file mode 100644 index 0000000..3e01eb2 --- /dev/null +++ b/crates/sspf-adapter-baseline/src/lib.rs @@ -0,0 +1,407 @@ +//! sspf-adapter-baseline —— 让同一套 MCP 工具打**远端基线平台 HTTP 后端**。 +//! +//! ## 它解决什么问题 +//! +//! `PLAN.md` §1.1 的双轨里,轨道 A 是「MCP 接现有 Java 后端」,用于过渡期提速与 +//! P4 影子对账。工具层本身不认识后端 —— 只认 [`PlatformAdapter`] 这个 trait。 +//! 本 crate 就是这个 trait 的第二种实现: +//! +//! ```text +//! ┌─────────────┐ ┌──────────────────┐ ┌────────────────────┐ +//! │ sspf-mcp │─────▶│ PlatformAdapter │─────▶│ NativeAdapter │ 进程内 AppState +//! │ (4 元工具) │ │ (只两个方法) │ ├────────────────────┤ +//! └─────────────┘ └──────────────────┘ │ BaselineHttpAdapter│ HTTP → 基线平台 +//! └────────────────────┘ +//! ``` +//! +//! ## 能力边界(刻意收窄) +//! +//! 只映射**语义严格对齐**的 5 个只读 op(见 [`map::SUPPORTED_OPS`])。 +//! 其余 op 返回 `CAPABILITY_UNSUPPORTED` + 「切 native」的明确指引 —— +//! 硬凑端点会造出「看起来能跑、语义其实不对」的工具,比明确不支持更糟。 +//! +//! ## 登录:为什么要求传**密文**而不是明文 +//! +//! 基线平台的登录口令要先过 AES 加密(与官方前端的 `cipher` 一致), +//! 否则服务端解不出 md5。本 crate **不复制加密逻辑**: +//! +//! - 复制 = 两份实现,密钥/填充模式一改就漂移 +//! - 下沉到 `sspf-contract` = 破坏契约层「无 IO 且依赖极简」的边界(AR4) +//! +//! ⇒ 密文由内核生成,调用方传进来: +//! +//! ```bash +//! ENC=$(./target/release/ssw-platform --enc 123456) +//! # ENC 就是参数 passwordCipher +//! ``` +//! +//! ## 一个必须知道的取舍 +//! +//! 每次调用新建 TCP 连接(无连接池)。P4 对账是 localhost 串行几百条,够用。 +//! 要高频转发再换连接池,[`PlatformAdapter`] 接口不变。 + +pub mod http; +pub mod map; + +use std::sync::Arc; +use std::time::Duration; + +use serde_json::{json, Value}; +use tokio::sync::RwLock; + +use sspf_mcp::adapter::{BoxFut, EnvInfo, PlatformAdapter, ToolError}; + +/// 默认超时:对账是本地/内网,5 秒足够;超时说明后端挂了,早报错比挂着好。 +const DEFAULT_TIMEOUT: Duration = Duration::from_secs(5); + +/// 基线平台 HTTP 适配器。 +#[derive(Debug)] +pub struct BaselineHttpAdapter { + ep: http::Endpoint, + /// 登录态(`Authorization` 头里用 `Bearer `)。 + token: RwLock>, + /// 自动登录凭据:`(account, password_cipher)`。 + creds: Option<(String, String)>, + /// 多应用路由头(`App-Code`)。 + app_code: String, + timeout: Duration, +} + +impl BaselineHttpAdapter { + /// 用已有的 token 构造(**P4 对账的推荐用法**:token 由脚本预先取好)。 + pub fn with_token(base_url: &str, token: impl Into) -> Result { + let ep = http::Endpoint::parse(base_url)?; + Ok(Self { + ep, + token: RwLock::new(Some(token.into())), + creds: None, + app_code: "mainSystem".to_string(), + timeout: DEFAULT_TIMEOUT, + }) + } + + /// 用「账号 + 密文口令」构造,首次调用时自动登录。 + /// + /// 🔴 `password_cipher` 必须是**已加密**的 hex(`ssw-platform --enc <明文>` 生成)。 + /// 传明文会让服务端解不出 md5,报「账号或密码错误」。 + pub fn with_credentials( + base_url: &str, + account: impl Into, + password_cipher: impl Into, + ) -> Result { + let ep = http::Endpoint::parse(base_url)?; + Ok(Self { + ep, + token: RwLock::new(None), + creds: Some((account.into(), password_cipher.into())), + app_code: "mainSystem".to_string(), + timeout: DEFAULT_TIMEOUT, + }) + } + + /// 指定多应用(`App-Code` 头)。 + pub fn with_app_code(mut self, app_code: impl Into) -> Self { + self.app_code = app_code.into(); + self + } + + /// 覆盖超时。 + pub fn with_timeout(mut self, timeout: Duration) -> Self { + self.timeout = timeout; + self + } + + /// 服务地址(诊断用)。 + pub fn base_url(&self) -> String { + format!("http://{}:{}", self.ep.host, self.ep.port) + } + + /// 业务请求头:`Authorization` + `Vue-Version: 3`(面 B 判别头)+ `App-Code`。 + /// + /// 🔴 `Vue-Version: 3` 不带 ⇒ 后端按**面 A** 语义处理,返回形状不同。 + /// 这是契约的一部分(`docs/contract.md` §3),不是可选装饰。 + async fn headers(&self) -> Result, ToolError> { + let token = self.ensure_token().await?; + Ok(vec![ + ("authorization", format!("Bearer {token}")), + ("vue-version", "3".to_string()), + ("app-code", self.app_code.clone()), + ("accept", "application/json".to_string()), + ]) + } + + /// 拿 token;没有就登录。 + async fn ensure_token(&self) -> Result { + if let Some(t) = self.token.read().await.clone() { + return Ok(t); + } + + let Some((account, cipher)) = self.creds.clone() else { + return Err(ToolError::new( + "NOT_AUTHENTICATED", + "既没有 token,也没有登录凭据", + ) + .hint("用 BaselineHttpAdapter::with_token(...) 或 with_credentials(...) 构造") + .hint("口令必须是密文:`ssw-platform --enc <明文>`")); + }; + + let body = format!( + "account={}&password={}", + map_url_encode(&account), + map_url_encode(&cipher) + ); + let resp = http::call( + &self.ep, + http::Method::POST, + "/api/oauth/Login", + &[ + ( + "content-type", + "application/x-www-form-urlencoded".to_string(), + ), + ("vue-version", "3".to_string()), + ], + Some(bytes::Bytes::from(body)), + self.timeout, + ) + .await + .map_err(|e| { + ToolError::new("BASELINE_UNREACHABLE", format!("登录请求失败: {e}")) + .hint("确认基线平台已启动、base_url 与端口正确") + .retryable() + })?; + + let v: Value = serde_json::from_slice(&resp.body).map_err(|e| { + ToolError::new( + "BASELINE_BAD_RESPONSE", + format!("登录响应不是 JSON: {e};body={}", truncate(&resp.text(), 200)), + ) + .hint("可能打到了非基线平台服务(如前端 dev server)") + })?; + + let data = map::unwrap_envelope(&v).map_err(|mut e| { + e.message = format!("登录失败:{}", e.message); + e.hints.push("口令要用 --enc 生成的密文,不是明文".to_string()); + e + })?; + + let Some(token) = data.get("token").and_then(Value::as_str) else { + return Err(ToolError::new( + "BASELINE_NO_TOKEN", + "登录响应里没有 data.token", + ) + .hint(format!("实际 data = {}", truncate(&data.to_string(), 200)))); + }; + + let token = token.to_string(); + *self.token.write().await = Some(token.clone()); + Ok(token) + } + + /// 发一个 GET 并解出 `data`。 + async fn get_data(&self, path: &str) -> Result { + let headers = self.headers().await?; + let resp = http::call( + &self.ep, + http::Method::GET, + path, + &headers, + None, + self.timeout, + ) + .await + .map_err(|e| { + ToolError::new("BASELINE_UNREACHABLE", format!("请求 {path} 失败: {e}")) + .hint("确认基线平台在跑、端口对") + .retryable() + })?; + + if !http::is_success(resp.status) { + return Err(ToolError::new( + "BASELINE_HTTP_ERROR", + format!("{path} 返回 HTTP {}", resp.status), + ) + .hint(format!("body={}", truncate(&resp.text(), 200))) + .retryable()); + } + + let v: Value = serde_json::from_slice(&resp.body).map_err(|e| { + ToolError::new( + "BASELINE_BAD_RESPONSE", + format!("{path} 响应不是 JSON: {e}"), + ) + .hint(format!("body={}", truncate(&resp.text(), 200))) + })?; + + map::unwrap_envelope(&v) + } +} + +/// 供本 crate 复用的 URL 编码(与 [`map`] 内部同一份语义,避免两处漂移)。 +fn map_url_encode(s: &str) -> String { + let mut out = String::with_capacity(s.len() * 3); + for b in s.as_bytes() { + match b { + b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => { + out.push(*b as char) + } + _ => out.push_str(&format!("%{b:02X}")), + } + } + out +} + +/// 截断长字符串(错误消息里放全文会淹掉 hint)。 +fn truncate(s: &str, max: usize) -> String { + if s.chars().count() <= max { + return s.to_string(); + } + let head: String = s.chars().take(max).collect(); + format!("{head}…(共 {} 字符)", s.chars().count()) +} + +impl PlatformAdapter for BaselineHttpAdapter { + fn describe_env<'a>(&'a self) -> BoxFut<'a, EnvInfo> { + Box::pin(async move { + // health 是**裸对象**(不是 {code,msg,data} 信封),单独处理。 + let (tables, version) = match http::call( + &self.ep, + http::Method::GET, + "/api/health", + &[], + None, + self.timeout, + ) + .await + { + Ok(resp) => match serde_json::from_slice::(&resp.body) { + Ok(v) => ( + v.get("tables").and_then(Value::as_u64).unwrap_or(0) as usize, + v.get("version") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string(), + ), + Err(_) => (0, "unknown".to_string()), + }, + Err(_) => (0, "unknown".to_string()), + }; + + // CurrentUser 能拿到当前系统与用户名;失败不影响主功能(可能是无登录态)。 + let mut system_id = self.app_code.clone(); + let mut user = None; + if let Ok(data) = self.get_data("/api/oauth/CurrentUser").await { + if let Some(s) = data.get("currentSystemId").and_then(Value::as_str) { + system_id = s.to_string(); + } + user = data + .get("userInfo") + .and_then(|u| u.get("account")) + .and_then(Value::as_str) + .map(str::to_string); + } + + EnvInfo { + backend: "baseline-http".to_string(), + version, + app_code: self.app_code.clone(), + system_id, + user, + tables, + capabilities: vec![ + "context".to_string(), + "menu".to_string(), + "permission".to_string(), + "dict".to_string(), + ], + } + }) + } + + fn invoke<'a>(&'a self, op: &'a str, args: Value) -> BoxFut<'a, Result> { + Box::pin(async move { + // context.get 要两次请求:health(裸对象)+ CurrentUser(信封) + if op == "context.get" { + let env = self.describe_env().await; + return Ok(json!({ + "backend": env.backend, + "version": env.version, + "app_code": env.app_code, + "system_id": env.system_id, + "user": env.user, + "tables": env.tables, + "note": "基线平台只有业务 API,没有元数据 API ⇒ schema.* / data.* 不可用", + })); + } + + let Some(m) = map::map(op, &args)? else { + return Err(map::unsupported(op)); + }; + + let data = self.get_data(&m.path).await?; + map::normalize(op, &data) + }) + } +} + +/// 便捷构造:`Arc`,直接喂给 `sspf_mcp::Server::new`。 +pub fn shared(adapter: BaselineHttpAdapter) -> Arc { + Arc::new(adapter) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn constructs_with_token_and_exposes_base_url() { + let a = BaselineHttpAdapter::with_token("http://127.0.0.1:30010", "tkn").unwrap(); + assert_eq!(a.base_url(), "http://127.0.0.1:30010"); + assert_eq!(a.app_code, "mainSystem"); + } + + #[test] + fn rejects_https_at_construction() { + let e = BaselineHttpAdapter::with_token("https://x.example", "t").unwrap_err(); + assert!(e.contains("只支持 http://")); + } + + /// 连不上时 `invoke` 要报错而不是挂住。 + #[tokio::test] + async fn unreachable_backend_is_reported_fast() { + let a = + BaselineHttpAdapter::with_credentials("http://127.0.0.1:1", "admin", "cipher").unwrap(); + let e = a + .invoke("permission.role.list", json!({})) + .await + .unwrap_err(); + assert!( + e.code == "BASELINE_UNREACHABLE" || e.code == "NOT_AUTHENTICATED", + "意外的错误码: {}", + e.code + ); + } + + /// 不支持的 op 必须在发请求**之前**就被拦下(省一次无用往返)。 + #[tokio::test] + async fn unsupported_op_fails_without_network() { + // 指向不存在的端口:若真发了请求就会变成 BASELINE_UNREACHABLE + let a = BaselineHttpAdapter::with_token("http://127.0.0.1:1", "t").unwrap(); + let e = a.invoke("schema.table.list", json!({})).await.unwrap_err(); + assert_eq!(e.code, "CAPABILITY_UNSUPPORTED"); + } + + #[test] + fn url_encode_handles_chinese_and_space() { + assert_eq!(map_url_encode("张 三"), "%E5%BC%A0%20%E4%B8%89"); + assert_eq!(map_url_encode("a-b_c.d~e"), "a-b_c.d~e"); + } + + #[test] + fn truncate_keeps_head_and_reports_total() { + let s = "x".repeat(300); + let t = truncate(&s, 10); + assert!(t.starts_with("xxxxxxxxxx"), "{t}"); + assert!(t.contains("300"), "{t}"); + } +} diff --git a/crates/sspf-adapter-baseline/src/map.rs b/crates/sspf-adapter-baseline/src/map.rs new file mode 100644 index 0000000..cc491a4 --- /dev/null +++ b/crates/sspf-adapter-baseline/src/map.rs @@ -0,0 +1,436 @@ +//! map —— op ↔ baseline 端点的映射表 + **响应形状归一化**。 +//! +//! ## 这个文件是适配器的核心,不是配菜 +//! +//! 同一个工具在两种后端上的「形状」不一样,P4 影子对账要先消化掉形状差异, +//! 否则每条都是差异,看不出业务问题: +//! +//! | 维度 | native(进程内) | baseline(HTTP) | +//! |---|---|---| +//! | 外层信封 | 裸对象 `{count, users}` | `{code, msg, data:{list, pagination}}` | +//! | 列表键 | `users` / `roles` / `types` | 一律 `list` | +//! | 分页 | `limit` 参数 | `currentPage` / `pageSize` / `pagination.total` | +//! | 字段名 | `organizeId` | `organize` | +//! +//! ⇒ [`normalize`] 把 baseline 的输出**投影成 native 的形状**。 +//! 对账时两边形状一致,剩下的差异就一定是业务差异。 +//! +//! ## 映射范围:只有 5 个只读 op,且这是刻意的 +//! +//! baseline 是**业务 API**,不是元数据 API:它没有「列出表结构」「查索引」这类端点。 +//! 硬凑映射会造出「看起来能跑、语义其实不对」的工具 —— 那比明确不支持更糟。 +//! +//! | op | baseline 端点 | 语义是否严格对齐 | +//! |---|---|---| +//! | `context.get` | `/api/health` + `/api/oauth/CurrentUser` | ✅ | +//! | `menu.tree` | `/api/system/Menu/Selector/All` | ✅ | +//! | `permission.user.list` | `/api/permission/Users` | ✅ | +//! | `permission.role.list` | `/api/permission/Role` | ✅ | +//! | `dict.type.list` | `/api/system/DictionaryType` | ✅ | +//! +//! 其余 op(`schema.*` / `data.*` / 全部写工具)⇒ [`map`] 返回 `Ok(None)`, +//! 由调用方转成 `CAPABILITY_UNSUPPORTED` + 可执行建议。 + +use http::Method; +use serde_json::{json, Map, Value}; + +use sspf_mcp::adapter::ToolError; + +/// 一次待发的 HTTP 请求。 +#[derive(Debug, Clone)] +pub struct Mapping { + /// HTTP 方法。 + pub method: Method, + /// 路径 + query(必须带前导 `/`)。 + pub path: String, +} + +/// 本适配器支持的 op 清单(`describe_env` 的 `capabilities` 用它)。 +pub const SUPPORTED_OPS: &[&str] = &[ + "context.get", + "menu.tree", + "permission.user.list", + "permission.role.list", + "dict.type.list", +]; + +/// 把 op 映射成一次 HTTP 请求;不支持的 op 返回 `Ok(None)`。 +pub fn map(op: &str, args: &Value) -> Result, ToolError> { + let s = |k: &str| args.get(k).and_then(Value::as_str).unwrap_or("").to_string(); + let n = |k: &str, d: u64| args.get(k).and_then(Value::as_u64).unwrap_or(d); + + let m = match op { + // 注意:context.get 需要两次请求(health + CurrentUser),由 lib.rs 特判, + // 这里只给出第一次的请求,让「单请求」这条路径保持简单。 + "context.get" => Mapping { + method: Method::GET, + path: "/api/health".to_string(), + }, + + "menu.tree" => Mapping { + method: Method::GET, + path: "/api/system/Menu/Selector/All".to_string(), + }, + + "permission.user.list" => { + let limit = n("limit", 50).clamp(1, 200); + let keyword = s("keyword"); + let mut path = format!("/api/permission/Users?currentPage=1&pageSize={limit}"); + if !keyword.is_empty() { + path.push_str(&format!("&keyword={}", url_encode(&keyword))); + } + Mapping { + method: Method::GET, + path, + } + } + + "permission.role.list" => Mapping { + method: Method::GET, + path: "/api/permission/Role?currentPage=1&pageSize=200".to_string(), + }, + + "dict.type.list" => { + let keyword = s("keyword"); + let mut path = "/api/system/DictionaryType?currentPage=1&pageSize=200".to_string(); + if !keyword.is_empty() { + path.push_str(&format!("&keyword={}", url_encode(&keyword))); + } + Mapping { + method: Method::GET, + path, + } + } + + // 其余一律「本后端不支持」,不猜、不硬凑 + _ => return Ok(None), + }; + + Ok(Some(m)) +} + +/// 极简 URL 编码(只处理会破坏 query 的字符,足够用于中文关键词)。 +fn url_encode(s: &str) -> String { + let mut out = String::with_capacity(s.len() * 3); + for b in s.as_bytes() { + match b { + b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' => { + out.push(*b as char) + } + _ => out.push_str(&format!("%{b:02X}")), + } + } + out +} + +/// 从 baseline 的 envelope 里取 `data`;`code != 200` ⇒ 业务错误。 +/// +/// 🔴 baseline 的失败也是 HTTP 200 + `{code:400}`,不能只看状态码。 +pub fn unwrap_envelope(body: &Value) -> Result { + let code = body.get("code").and_then(Value::as_i64).unwrap_or(0); + if code != 200 { + let msg = body + .get("msg") + .and_then(Value::as_str) + .unwrap_or("(无消息)"); + // 602 / 600 ⇒ 会话失效,是最常见的失败,单独给码 + let err_code = match code { + 600 | 602 => "SESSION_INVALID", + 400 => "BAD_REQUEST", + 403 => "FORBIDDEN", + _ => "BASELINE_ERROR", + }; + return Err( + ToolError::new(err_code, format!("基线平台返回 code={code}: {msg}")) + .hint("600/602 表示登录态失效 —— 重新登录拿 token") + .retryable(), + ); + } + Ok(body.get("data").cloned().unwrap_or(Value::Null)) +} + +/// 按白名单投影一个对象(只保留 native 也有的键,缺失的补默认)。 +fn project(src: &Map, keys: &[(&str, Value)]) -> Value { + let mut out = Map::new(); + for (k, default) in keys { + let v = src.get(*k).cloned().unwrap_or_else(|| default.clone()); + out.insert((*k).to_string(), v); + } + Value::Object(out) +} + +/// 取 `data.list`(baseline 的列表统一叫 `list`)。 +fn list_of(data: &Value) -> Vec { + data.get("list") + .and_then(Value::as_array) + .cloned() + .unwrap_or_default() +} + +/// 把 baseline 的响应投影成 **native 的形状**。 +/// +/// `op` 决定投影到哪个形状;未知 op 原样返回(便于调试)。 +/// +/// 🔴 **已知差异(不掩盖)**:`count` 统一取「本次返回的条数」,与 native 一致。 +/// baseline 的 `pagination.total`(总条数)**不映射** —— native 没有「总数」概念, +/// 映射过来会造成「形状一样但含义不同」的假一致。要总数就单独查。 +pub fn normalize(op: &str, data: &Value) -> Result { + match op { + // native: {count, users:[{id,account,realName,mobilePhone,organizeId,roleId,isAdministrator,enabledMark,lockMark}]} + "permission.user.list" => { + let raw = list_of(data); + let count = raw.len(); + let users: Vec = raw + .iter() + .filter_map(Value::as_object) + .map(|o| { + // baseline 用 organize,native 用 organizeId ⇒ 显式改名 + let mut m = o.clone(); + if let Some(v) = o.get("organize").cloned() { + m.insert("organizeId".to_string(), v); + } + project( + &m, + &[ + ("id", json!("")), + ("account", json!("")), + ("realName", json!("")), + ("mobilePhone", json!("")), + ("organizeId", json!("")), + ("roleId", json!("")), + ("isAdministrator", json!(0)), + ("enabledMark", json!(0)), + ("lockMark", json!(0)), + ], + ) + }) + .collect(); + Ok(json!({ "count": count, "users": users })) + } + + // native: {count, roles:[{id,fullName,enCode,sortCode,type,enabledMark}]} + "permission.role.list" => { + let raw = list_of(data); + let roles: Vec = raw + .iter() + .filter_map(Value::as_object) + .map(|o| { + project( + o, + &[ + ("id", json!("")), + ("fullName", json!("")), + ("enCode", json!("")), + ("sortCode", json!(0)), + ("type", json!("")), + ("enabledMark", json!(0)), + ], + ) + }) + .collect(); + Ok(json!({ "count": roles.len(), "roles": roles })) + } + + // native: {count, types:[...]} + "dict.type.list" => { + let raw = list_of(data); + let types: Vec = raw + .iter() + .filter_map(Value::as_object) + .map(|o| { + project( + o, + &[ + ("id", json!("")), + ("fullName", json!("")), + ("enCode", json!("")), + ("type", json!(0)), + ("isTree", json!(0)), + ("enabledMark", json!(0)), + ], + ) + }) + .collect(); + Ok(json!({ "count": types.len(), "types": types })) + } + + // native: {system_id, mode, count, menus:[{id,fullName,urlAddress,parentId,enCode,icon}]} + "menu.tree" => { + let raw = list_of(data); + let system_id = raw + .first() + .and_then(|m| m.get("systemId")) + .and_then(Value::as_str) + .unwrap_or("mainSystem") + .to_string(); + let menus: Vec = raw + .iter() + .filter_map(Value::as_object) + .map(|o| { + project( + o, + &[ + ("id", json!("")), + ("fullName", json!("")), + ("urlAddress", Value::Null), + ("parentId", json!("0")), + ("enCode", Value::Null), + ("icon", Value::Null), + ], + ) + }) + .collect(); + Ok(json!({ + "system_id": system_id, + "mode": "flat", + "count": menus.len(), + "menus": menus, + })) + } + + _ => Ok(data.clone()), + } +} + +/// 生成「本后端不支持该 op」的错误(带可执行建议)。 +pub fn unsupported(op: &str) -> ToolError { + ToolError::new( + "CAPABILITY_UNSUPPORTED", + format!("基线平台 HTTP 适配器不支持 `{op}`"), + ) + .hint(format!( + "本适配器只映射业务 API 语义对得上的 5 个只读 op:{}", + SUPPORTED_OPS.join(" / ") + )) + .hint("要建表/改数据/授权,请切到 native 适配器(`--mcp`,进程内直连内核)") + .next( + "sspf_context", + json!({}), + "先确认当前 backend 是 baseline-http 还是 native", + ) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn envelope(data: Value) -> Value { + json!({ "code": 200, "msg": "成功", "data": data }) + } + + #[test] + fn maps_supported_ops() { + assert!(map("context.get", &json!({})).unwrap().is_some()); + assert!(map("menu.tree", &json!({})).unwrap().is_some()); + assert!(map("permission.user.list", &json!({})).unwrap().is_some()); + assert!(map("permission.role.list", &json!({})).unwrap().is_some()); + assert!(map("dict.type.list", &json!({})).unwrap().is_some()); + } + + /// 🔴 不支持的 op 必须返回 None(而不是硬凑一个端点)。 + #[test] + fn refuses_unmappable_ops() { + for op in [ + "schema.table.list", + "schema.table.describe", + "data.query", + "data.count", + "menu.create", // 写工具:baseline 有端点但语义不同(缺 en_code/system_id),刻意不映射 + "permission.effective", // 四源合并是内核侧算法,baseline 没有对等端点 + ] { + assert!(map(op, &json!({})).unwrap().is_none(), "{op} 不该被映射"); + } + } + + #[test] + fn user_list_path_carries_limit_and_keyword() { + let m = map( + "permission.user.list", + &json!({"limit": 10, "keyword": "张 三"}), + ) + .unwrap() + .unwrap(); + assert!(m.path.contains("pageSize=10"), "{}", m.path); + assert!(m.path.contains("keyword=%E5%BC%A0%20%E4%B8%89"), "{}", m.path); + } + + #[test] + fn unwrap_rejects_business_error_with_session_hint() { + let body = json!({"code": 602, "msg": "登录状态已失效"}); + let e = unwrap_envelope(&body).unwrap_err(); + assert_eq!(e.code, "SESSION_INVALID"); + assert!(e.hints.iter().any(|h| h.contains("600/602"))); + } + + #[test] + fn unwrap_passes_through_success() { + let d = unwrap_envelope(&envelope(json!({"list": []}))).unwrap(); + assert!(d.get("list").is_some()); + } + + /// 形状归一化的核心断言:baseline 的 `list` 要变成 native 的具名键。 + #[test] + fn user_list_is_projected_to_native_shape() { + let data = envelope(json!({ + "list": [{ + "id": "u1", "account": "admin", "realName": "管理员", + "fullName": "管理员", "organize": "org1", "position": "p1", + "isAdministrator": 1, "enabledMark": 1, "lockMark": 0, + "creatorTime": 1793416289000i64 + }], + "pagination": { "currentPage": 1, "pageSize": 20, "total": 1 } + })); + let d = unwrap_envelope(&data).unwrap(); + let n = normalize("permission.user.list", &d).unwrap(); + + assert_eq!(n["count"], 1); + let u = &n["users"][0]; + assert_eq!(u["organizeId"], "org1", "baseline 的 organize 要映射成 organizeId"); + assert_eq!(u["roleId"], "", "native 有 roleId、baseline 没有 ⇒ 补空串"); + assert!(u.get("creatorTime").is_none(), "多余键要裁掉(否则对账永远不等)"); + assert!(u.get("fullName").is_none(), "多余键要裁掉"); + } + + #[test] + fn role_and_dict_are_projected() { + let d = unwrap_envelope(&envelope(json!({ + "list": [{"id": "role_admin", "fullName": "管理员", "enCode": "admin", + "sortCode": 1, "type": "user", "enabledMark": 1, "description": null}] + }))) + .unwrap(); + let r = normalize("permission.role.list", &d).unwrap(); + assert_eq!(r["count"], 1); + assert_eq!(r["roles"][0]["enCode"], "admin"); + assert!(r["roles"][0].get("description").is_none()); + + let t = normalize("dict.type.list", &d).unwrap(); + assert_eq!(t["count"], 1); + assert_eq!( + t["types"][0]["isTree"], 0, + "baseline 没有 isTree 键 ⇒ 补默认值" + ); + } + + #[test] + fn menu_tree_is_projected_flat() { + let d = unwrap_envelope(&envelope(json!({ + "list": [{"id": "m_sys", "fullName": "系统管理", "urlAddress": "system", + "parentId": "0", "enCode": "permission", "icon": "setting", + "systemId": "mainSystem", "type": 1, "sortCode": 1}] + }))) + .unwrap(); + let n = normalize("menu.tree", &d).unwrap(); + assert_eq!(n["system_id"], "mainSystem"); + assert_eq!(n["count"], 1); + assert_eq!(n["menus"][0]["urlAddress"], "system"); + assert!(n["menus"][0].get("type").is_none(), "裁剪掉 native 没有的键"); + } + + #[test] + fn unsupported_error_is_actionable() { + let e = unsupported("schema.table.list"); + assert_eq!(e.code, "CAPABILITY_UNSUPPORTED"); + assert!(e.hints.iter().any(|h| h.contains("native")), "要指引切后端"); + assert!(!e.next_actions.is_empty()); + } +} diff --git a/crates/sspf-mcp/src/lib.rs b/crates/sspf-mcp/src/lib.rs index 4ebf8fc..d603157 100644 --- a/crates/sspf-mcp/src/lib.rs +++ b/crates/sspf-mcp/src/lib.rs @@ -37,6 +37,7 @@ pub mod adapter; pub mod jsonrpc; +pub mod prompts; pub mod registry; pub mod server; pub mod tools; diff --git a/crates/sspf-mcp/src/prompts.rs b/crates/sspf-mcp/src/prompts.rs new file mode 100644 index 0000000..971b2cd --- /dev/null +++ b/crates/sspf-mcp/src/prompts.rs @@ -0,0 +1,409 @@ +//! prompts —— 多步流程模板(MCP `prompts/*`)。 +//! +//! ## 为什么模板比工具更值钱 +//! +//! 单个工具只回答「这一步怎么做」,模板回答「整件事按什么顺序做、做到哪算完成」。 +//! AI 最容易犯的错不是调错参数,而是**漏步骤**: +//! +//! - 建了菜单忘了授权 ⇒ 非管理员看不见,以为是 bug +//! - 授权了没验证 ⇒ 交付时才发现授权对象是错的 +//! - 建表不看命名规范 ⇒ 后面业务包里表名对不上 +//! +//! 模板把这些「隐性顺序」显式化,等于把资深开发的经验固化成可复用的检查单。 +//! +//! ## 🔴 防腐烂 +//! +//! 模板正文里会出现工具 id(`menu.create` 等)。工具一旦改名或删除,模板就变成 +//! 错误的指导 —— 而且**不会有人发现**(模板不参与编译)。 +//! +//! ⇒ 本文件的测试会扫出正文里所有 `域.动作` 形态的字符串, +//! 逐个到 [`crate::tools::ALL_TOOLS`] 里核对。引用不存在的工具 ⇒ 测试失败。 +//! +//! ## 参数约定 +//! +//! 参数是 `{{name}}` 占位符,渲染时做字符串替换。缺必填参数 ⇒ 调用方应当返回 +//! `INVALID_PARAMS`(见 `server.rs::on_prompts_get`)。 + +use std::collections::BTreeMap; + +/// 一个模板参数。 +pub struct PromptArg { + /// 占位符名(`{{name}}`)。 + pub name: &'static str, + /// 给 AI 看的说明。 + pub description: &'static str, + /// 缺了就不能渲染。 + pub required: bool, +} + +/// 一个模板。 +pub struct PromptDef { + /// 模板名(`prompts/get` 的 `name`)。 + pub name: &'static str, + /// 人类可读标题。 + pub title: &'static str, + /// 一句话说明(`prompts/list` 里显示)。 + pub description: &'static str, + /// 参数表。 + pub arguments: &'static [PromptArg], + /// 渲染:拿到参数表,产出提示词正文。 + pub render: fn(&BTreeMap) -> String, +} + +/// 取参数,缺省时用默认值。 +fn arg<'a>(args: &'a BTreeMap, key: &str, default: &'a str) -> &'a str { + args.get(key).map(String::as_str).unwrap_or(default) +} + +// ================================================================ new_business_module + +/// 建一个业务模块的完整流程:建表 → 建菜单 → 授权 → 建测试用户 → 验证。 +fn render_new_business_module(a: &BTreeMap) -> String { + let name = arg(a, "module_name", "<模块中文名>"); + let code = arg(a, "module_code", "<模块英文标识>"); + let role = arg(a, "role_id", ""); + let role_line = if role.is_empty() { + "先 `permission.role.list` 选一个目标角色(推荐 role_user),后面授权用它。".to_string() + } else { + format!("目标角色 id 固定为 `{role}`(已指定,不用再查)。") + }; + + format!( + r#"# 任务:新建业务模块「{name}」({code}) + +按下面的顺序做,**每一步成功后再进下一步**。任何一步失败, +先读 `error.hints` / `error.next_actions` 自纠,不要原样重试。 + +## 第 0 步:确认环境 +调用 `sspf_context`,确认 `backend` / `app_code` / `tables`。 +🔴 多应用下菜单与权限按 `f_system_id` 隔离,app_code 不对时表现成「菜单是空的」,不报错。 + +## 第 1 步:定名(先想清楚再动手) +- 物理表名:`{code}_<实体>`,全小写 + 下划线,**必须**以业务前缀开头 +- 菜单 enCode:`permission.{code}.<资源>`(面 B 点权限判据) +- 菜单 urlAddress:`{code}/`,**不要前导斜杠**(面 A 按字符串全等比对) +- 前端 Route path 必须与 urlAddress 一字不差,三处(菜单 / module_key / Route)一致 + +先 `schema.table.list(prefix="{code}_")` 看有没有重名。 + +## 第 2 步:建菜单 +`menu.create`,参数示例: +```json +{{"fullName":"{name}","enCode":"permission.{code}.<资源>","urlAddress":"{code}/","sortCode":10}} +``` +🔴 建完**非管理员看不见** —— 这是安全默认,不是 bug。必须继续第 3 步。 + +## 第 3 步:授权 +{role_line} + +`permission.authorize.grant`,`objectType="role"`,`menuEnCode` 用第 2 步的 enCode。 +🔴 父目录与子页面**各自**需要授权 —— `base_authorize` 是扁平表,没有树继承。 + +## 第 4 步:用非管理员账号验证(关键) +🔴 不要用 admin 验证:`is_admin=1` 在守卫第一条判据就返回 true,**根本不查授权表**, +用 admin 测等于什么都没测。 + +若无非管理员账号: +`permission.user.create`,`account` 字母开头、`password` 传**明文**(内部转 md5), +`roleIds` 填第 3 步的角色。 + +然后 `permission.effective(account="<新账号>", withMenuDetail=true)`: +- `fourSource.count` = 四源并集 +- `visible.count` = 与当前应用菜单求交后**真正能看到的** +- 两者不一致 ⇒ 有授权指向了别的应用的菜单(或菜单已删) + +期望:`visible` 里能看到第 2 步建的模块。 + +## 第 5 步:交付自检 +逐条确认: +- [ ] `menu.tree(flat=true)` 里能看到新菜单,urlAddress 无前导斜杠 +- [ ] `permission.effective` 的非管理员账号能看到它 +- [ ] 若已建表:`schema.table.describe` 的列名符合 `f_` + 下划线规范 +- [ ] enCode / urlAddress / 前端 Route 三者一字不差 + +## 常见失败对照 +| 现象 | 原因 | 处置 | +|---|---|---| +| 菜单建了但看不见 | 没授权 / 授权给了别的应用 | `permission.effective` 查 fourSource 与 visible | +| `MENU_EXISTS` | enCode 或 urlAddress 已被占用 | `menu.tree(flat=true)` 找出来,复用或换名 | +| `BAD_URL_ADDRESS` | 带前导斜杠 | 去掉 `/` | +| 授权成功但仍看不见 | 只授了子页面,父目录没授 | 给父目录也授权 | +"# + ) +} + +// ================================================================ diagnose_menu_not_visible + +/// 排查「菜单授权了但看不见」—— 这是最高频的困惑。 +fn render_diagnose(a: &BTreeMap) -> String { + let account = arg(a, "account", "<待排查的账号>"); + + format!( + r#"# 任务:排查账号 `{account}` 为什么看不到某个菜单 + +## 顺序(从最可能到最不可能) + +### 1. 确认账号身份与管理员标志 +`permission.user.list(keyword="{account}")` → 拿 `id` 与 `isAdministrator`。 +- `isAdministrator=1` ⇒ 守卫直接放行,**问题不在授权**,去查别处(前端 Route、应用码) + +### 2. 确认「实际生效」而不只是「授权表里有」 +`permission.effective(account="{account}", withMenuDetail=true)` + +读三个字段: +- `isAdmin` —— true 就直接结束(见上) +- `fourSource` —— 四源并集(直授 + 角色 + 组织 + 岗位) +- `visible` —— 与当前应用菜单求交后的结果 + +| fourSource | visible | 结论 | +|---|---|---| +| 0 | 0 | **压根没授上** ⇒ 去第 3 步 | +| >0 | 0 | 授上了但**不在这个应用** ⇒ 去第 4 步 | +| >0 | >0 但没目标菜单 | 授的是**别的菜单** ⇒ 去第 3 步核对 menuId | + +### 3. 逐源核对 +`permission.authorize.list(objectType="user", objectId="")` 看直授; +角色来源则先看用户绑了哪些角色(`permission.user.list` 的返回里带角色信息), +再对每个角色 `permission.authorize.list(objectType="role", objectId="")`。 + +🔴 常见错:授权的 `f_object_id` 是**主键**,不是账号/角色名。 +传错时插进去的行永远匹配不上 —— 不报错、也不生效。 + +### 4. 核对应用隔离 +`sspf_context` 的 `app_code` 与菜单的 `systemId` 必须一致。 +同一 urlAddress / enCode 在不同应用里是**两条独立记录**: +在 A 应用授的权,对 B 应用的菜单无效(`base_authorize` 不带应用维度, +所以授权行是"跨应用共享"的,但菜单 id 不同 ⇒ 仍然对不上)。 + +用 `menu.tree(flat=true)` 确认目标菜单的 id 与 systemId。 + +### 5. 核对父目录 +`base_authorize` 是扁平表,**没有树继承**。 +只授子页面、没授父目录 ⇒ 前端侧栏没有父节点可挂 ⇒ 表现为「授权的菜单不显示」。 +`menu.tree` 看目标菜单的 `parentId`,给父目录也授权。 + +## 输出要求 +给出:**根因一句话** + **已执行的修复**(或需人工确认的点)。 +不要只列「可能的原因」——要落到「就是这一个」。 +"# + ) +} + +// ================================================================ verify_all + +/// 交付前跑全部闸门。 +fn render_verify_all(_a: &BTreeMap) -> String { + r#"# 任务:交付前跑全部验收闸门 + +## 顺序 +全部在仓库根执行,**任何一道红都不算完成**。 + +```bash +# 1. 单元测试 +cargo test --workspace + +# 2. 五道静态闸门 +bash scripts/check-module.sh # 业务模块 10 接触点 +bash scripts/check-boundary.sh # 分层红线 CP1–CP6 +bash scripts/check-contract.sh # 契约端点 ↔ 代码路由 +bash scripts/check-citations.sh # 文档引文 路径:行号 +bash scripts/check-arch.sh # crate 依赖纪律 AR1–AR5 + 内存红线 +bash scripts/check-naming.sh # 原厂标识剥离 NM1–NM3 + +# 3. 契约尺子(起服务后跑) +bash scripts/perm-smoke.sh # 面 A +bash scripts/perm-smoke-jnpf.sh # 面 B +bash scripts/mcp-smoke.sh # MCP 工具层 + +# 4. 内存实测(终端产品的硬约束) +bash scripts/mem-budget.sh +``` + +## 读结果的要点 +- 每把尺子结尾都会比对「实际断言数 vs 契约登记数」—— + 对不上即失败,**尺子不会被悄悄改弱** +- `check-arch.sh --self-test` 是反自证:故意造违规,必须被抓到 +- `check-naming.sh` 注释里的原厂名只量化上报不阻断;`--strict` 才阻断 + +## 失败处置 +- 静态闸门红 ⇒ 先看它打印的「为什么」,多数是漏了某处同步 +- 契约尺子红 ⇒ 先确认是不是服务没起 / 端口被占 +- `mcp-smoke` 红 ⇒ 先 `cargo clean -p sspf-mcp && cargo build`, + cargo 指纹不更新会让测试跑在旧二进制上(历史上排查过很久) + +## 输出要求 +一行一道,标注 ✅/❌ 与数字。有 ❌ 就停,先修再重跑。 +"# + .to_string() +} + +// ================================================================ 注册表 + +/// 全部模板。 +pub static PROMPTS: &[PromptDef] = &[ + PromptDef { + name: "new_business_module", + title: "新建业务模块", + description: "从建菜单到用非管理员账号验证可见的完整流程(含授权闭环)", + arguments: &[ + PromptArg { + name: "module_name", + description: "模块中文名,如「数据资源」", + required: true, + }, + PromptArg { + name: "module_code", + description: "模块英文标识(小写),如 asset;用于表名前缀与菜单 enCode", + required: true, + }, + PromptArg { + name: "role_id", + description: "目标角色 id(可选;不给则让 AI 先 role.list 选一个)", + required: false, + }, + ], + render: render_new_business_module, + }, + PromptDef { + name: "diagnose_menu_not_visible", + title: "排查菜单不可见", + description: "「授权了但看不见」的五步定位法,按 fourSource / visible 分流", + arguments: &[PromptArg { + name: "account", + description: "待排查的账号", + required: true, + }], + render: render_diagnose, + }, + PromptDef { + name: "verify_all", + title: "交付前全量验收", + description: "一次性跑完测试、静态闸门、契约尺子与内存实测", + arguments: &[], + render: render_verify_all, + }, +]; + +/// 按名字找模板。 +pub fn find(name: &str) -> Option<&'static PromptDef> { + PROMPTS.iter().find(|p| p.name == name) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::tools::ALL_TOOLS; + use std::collections::HashSet; + + fn sample_args(p: &PromptDef) -> BTreeMap { + p.arguments + .iter() + .filter(|a| a.required) + .map(|a| (a.name.to_string(), format!("<{}>", a.name))) + .collect() + } + + /// 🔴 防腐烂的核心测试:模板正文里提到的工具 id 必须真实存在。 + /// + /// 工具改名/删除后,模板会变成错误指导,而且**没人会发现**(模板不参与编译)。 + #[test] + fn prompts_only_reference_existing_tools() { + let known: HashSet<&str> = ALL_TOOLS.iter().map(|t| t.id).collect(); + // 元工具不在 ALL_TOOLS 里,单独放行 + let meta = [ + "sspf_context", + "sspf_discover", + "sspf_describe", + "sspf_call", + ]; + + for p in PROMPTS { + let text = (p.render)(&sample_args(p)); + // 抓 `域.动作` 形态的标识:小写字母开头,点分隔,至少两段 + for token in text.split(|c: char| { + !(c.is_ascii_alphanumeric() || c == '.' || c == '_' || c == '-') + }) { + if !token.contains('.') || token.starts_with('.') || token.ends_with('.') { + continue; + } + let Some((head, _)) = token.split_once('.') else { + continue; + }; + if !head.chars().all(|c| c.is_ascii_lowercase()) || head.len() < 3 { + continue; + } + // 只关心看起来像工具 id 的(域.动作),排除文件扩展名与路径 + let looks_like_tool = token.starts_with("permission.") + || token.starts_with("menu.") + || token.starts_with("schema.") + || token.starts_with("data.") + || token.starts_with("dict.") + || token.starts_with("context.") + || token.starts_with("form.") + || token.starts_with("model."); + if !looks_like_tool { + continue; + } + let is_meta = meta.contains(&token); + assert!( + known.contains(token) || is_meta, + "模板 `{}` 引用了不存在的工具 `{}`(工具改名后要同步改模板)", + p.name, + token + ); + } + } + } + + /// 每个模板都必须能渲染出**非空且有内容**的正文。 + #[test] + fn every_prompt_renders_meaningfully() { + for p in PROMPTS { + let text = (p.render)(&sample_args(p)); + assert!(text.len() > 200, "{} 渲染结果太短({})", p.name, text.len()); + assert!(text.contains("任务"), "{} 缺少任务标题", p.name); + // 必须提到具体工具,否则只是空泛建议 + assert!( + text.contains("sspf_") || text.contains('.'), + "{} 没有提到任何工具", + p.name + ); + } + } + + /// 必填参数必须真的出现在正文里(否则参数名对不上占位符)。 + #[test] + fn required_args_are_interpolated() { + for p in PROMPTS { + let args = sample_args(p); + let text = (p.render)(&args); + for a in p.arguments.iter().filter(|a| a.required) { + assert!( + text.contains(&format!("<{}>", a.name)), + "{} 的必填参数 {} 没有渲染进正文(占位符写错?)", + p.name, + a.name + ); + } + } + } + + /// 名字唯一 + 参数名唯一(重名会让 prompts/get 拿到错的那个)。 + #[test] + fn names_and_args_are_unique() { + let mut seen = HashSet::new(); + for p in PROMPTS { + assert!(seen.insert(p.name), "模板名重复: {}", p.name); + let mut arg_seen = HashSet::new(); + for a in p.arguments { + assert!(arg_seen.insert(a.name), "{} 参数名重复: {}", p.name, a.name); + } + } + } + + #[test] + fn find_works() { + assert!(find("new_business_module").is_some()); + assert!(find("nope").is_none()); + } +} diff --git a/crates/sspf-mcp/src/server.rs b/crates/sspf-mcp/src/server.rs index 49611bf..0840725 100644 --- a/crates/sspf-mcp/src/server.rs +++ b/crates/sspf-mcp/src/server.rs @@ -186,8 +186,8 @@ impl Server { "tools/call" => self.on_tools_call(msg.params).await, "resources/list" => Ok(self.on_resources_list()), "resources/read" => self.on_resources_read(msg.params), - "prompts/list" => Ok(json!({ "prompts": [] })), - "prompts/get" => Err((codes::INVALID_PARAMS, "P1 阶段还没有 prompt 模板".to_string())), + "prompts/list" => Ok(on_prompts_list()), + "prompts/get" => on_prompts_get(msg.params), other => Err(( codes::METHOD_NOT_FOUND, format!("不支持的方法: {other}"), @@ -339,6 +339,78 @@ impl Server { } } +/// `prompts/list` —— 列出全部多步流程模板。 +/// +/// 模板不占常驻 token:客户端只在用户主动引用时才 `prompts/get`。 +fn on_prompts_list() -> Value { + let list: Vec = crate::prompts::PROMPTS + .iter() + .map(|p| { + json!({ + "name": p.name, + "title": p.title, + "description": p.description, + "arguments": p.arguments.iter().map(|a| json!({ + "name": a.name, + "description": a.description, + "required": a.required, + })).collect::>(), + }) + }) + .collect(); + json!({ "prompts": list }) +} + +/// `prompts/get` —— 渲染一个模板。 +/// +/// 🔴 必填参数缺失 ⇒ `INVALID_PARAMS`:模板正文会带着 `<参数名>` 占位符发出去, +/// AI 会照着字面量去执行(拿到 `` 这种值),比直接报错更糟。 +fn on_prompts_get(params: Value) -> Result { + let name = params + .get("name") + .and_then(Value::as_str) + .ok_or_else(|| (codes::INVALID_PARAMS, "缺少 name".to_string()))?; + + let Some(p) = crate::prompts::find(name) else { + let avail: Vec<&str> = crate::prompts::PROMPTS.iter().map(|x| x.name).collect(); + return Err(( + codes::INVALID_PARAMS, + format!("未知模板 {name};可用:{}", avail.join(" / ")), + )); + }; + + let mut args: std::collections::BTreeMap = + std::collections::BTreeMap::new(); + if let Some(obj) = params.get("arguments").and_then(Value::as_object) { + for (k, v) in obj { + if let Some(s) = v.as_str() { + args.insert(k.clone(), s.to_string()); + } + } + } + + let missing: Vec<&str> = p + .arguments + .iter() + .filter(|a| a.required && !args.contains_key(a.name)) + .map(|a| a.name) + .collect(); + if !missing.is_empty() { + return Err(( + codes::INVALID_PARAMS, + format!("模板 {name} 缺少必填参数:{}", missing.join(", ")), + )); + } + + Ok(json!({ + "description": p.description, + "messages": [{ + "role": "user", + "content": { "type": "text", "text": (p.render)(&args) } + }] + })) +} + /// `sspf://docs/quickstart` 的内容。 const QUICKSTART: &str = r#"# SSPF 工具层快速上手 diff --git a/crates/sspf-mcp/src/tools/mod.rs b/crates/sspf-mcp/src/tools/mod.rs index 63055bb..954d66c 100644 --- a/crates/sspf-mcp/src/tools/mod.rs +++ b/crates/sspf-mcp/src/tools/mod.rs @@ -20,6 +20,7 @@ pub mod business; pub mod meta; +pub mod permission; pub mod write; use serde_json::Value; @@ -182,7 +183,8 @@ const MENU_TREE_TOOL: ToolDef = ToolDef { /// 全部业务工具。 /// /// P1 首批 4 个(context / schema ×2 / menu)+ 第二批 8 个(permission ×3 / dict ×2 / data ×2 / schema ×1) -/// = **12 个**。后续按 `PLAN.md` §6.3 的 12 域补齐到约 55 个。 +/// + 第三批 3 个写工具(menu ×2 / dict ×1)+ 第四批 3 个授权闭环(grant / revoke / effective) +/// = **18 个**。后续按 `PLAN.md` §6.3 的 12 域补齐到约 55 个。 pub static ALL_TOOLS: &[ToolDef] = &[ // —— 首批(P1-a)—— CONTEXT_GET_TOOL, @@ -202,6 +204,11 @@ pub static ALL_TOOLS: &[ToolDef] = &[ write::MENU_CREATE, write::MENU_DELETE, write::DICT_TYPE_CREATE, + // —— 第四批(P1-d):授权闭环(建菜单后的最后一公里)—— + permission::AUTHORIZE_GRANT, + permission::AUTHORIZE_REVOKE, + permission::EFFECTIVE, + permission::USER_CREATE, ]; #[cfg(test)] diff --git a/crates/sspf-mcp/src/tools/permission.rs b/crates/sspf-mcp/src/tools/permission.rs new file mode 100644 index 0000000..12cb595 --- /dev/null +++ b/crates/sspf-mcp/src/tools/permission.rs @@ -0,0 +1,309 @@ +//! permission —— 授权闭环(P1 第四批):授 / 撤 / 查生效。 +//! +//! ## 为什么必须有这一批 +//! +//! `menu.create` 建完菜单后,**非管理员看不见**(安全默认:默认不授权)。 +//! 没有授权工具时,AI 建完菜单就卡住 —— 它能做的最后一句话是 +//! 「请人工去后台点授权」,整条链路断在这里。 +//! +//! ## 授权的数据模型(四源合并) +//! +//! `base_authorize` 是一张**多态关联表**,一条记录 = 「谁」对「什么」有权限: +//! +//! ```text +//! f_item_type = 'module' ← 被授权的对象类型(本期只有菜单) +//! f_item_id = base_module.f_id ← 被授权的菜单 +//! f_object_type = 'user' | 'role' | 'organize' | 'position' ← 授权给谁(四选一) +//! f_object_id = 对应表的 f_id +//! ``` +//! +//! 计算「某用户能看到哪些菜单」时,四源**并集**: +//! 直授 user + 所属 role + 所属 organize + 所属 position(见 `permission.rs`)。 +//! +//! ⇒ 授权给角色是**推荐做法**(一改全组生效);直授用户只用于临时特批。 +//! +//! ## 🔴 三个工具的分工 +//! +//! | 工具 | 回答什么问题 | +//! |---|---| +//! | `permission.authorize.grant` | 「给他开这个菜单」 | +//! | `permission.authorize.revoke` | 「把这个菜单收回来」 | +//! | `permission.effective` | 「他**实际**能看到哪些菜单,分别从哪来」 | +//! +//! `permission.effective` 是排查「授权了还是看不见」的唯一入口 —— +//! 它能区分「没授上」「授给了别的应用」「用户不是这个角色」,比反复 grep 数据库快得多。 + +use serde_json::Value; + +use crate::adapter::{BoxFut, PlatformAdapter, ToolError}; +use crate::registry::{Annotations, Category, Example, Hints, Pitfall, Severity, ToolDef}; + +macro_rules! passthrough { + ($name:ident, $op:literal) => { + fn $name<'a>( + adapter: &'a dyn PlatformAdapter, + args: Value, + ) -> BoxFut<'a, Result> { + Box::pin(async move { adapter.invoke($op, args).await }) + } + }; +} + +// ================================================================ permission.authorize.grant + +passthrough!(grant_handler, "permission.authorize.grant"); + +pub const AUTHORIZE_GRANT: ToolDef = ToolDef { + id: "permission.authorize.grant", + category: Category::Permission, + title: "授权菜单", + one_liner: "把某个菜单授权给用户/角色/组织/岗位(幂等,已授权则跳过)", + input_schema: r#"{ + "type": "object", + "properties": { + "objectType": { + "type": "string", + "enum": ["user", "role", "organize", "position"], + "description": "授权给谁:user 直授(临时特批)/ role 角色(推荐)/ organize 组织 / position 岗位" + }, + "objectId": { "type": "string", "description": "对应对象的 id(如 roleId)" }, + "menuId": { "type": "string", "description": "菜单 id(base_module.f_id)" }, + "menuEnCode": { "type": "string", "description": "或用 enCode 指定菜单(与 menuId 二选一,便于 AI 少查一次)" }, + "systemEnCode": { "type": "string", "default": "mainSystem", "description": "按 enCode 查菜单时限定应用,避免跨应用同名" } + }, + "required": ["objectType"], + "additionalProperties": false + }"#, + annotations: Annotations::UPSERT, + hints: Hints { + when_to_use: &[ + "menu.create 建完菜单后,让非管理员也能看到", + "新同事入职,把一组菜单开给他的角色", + "临时给某个人开一个页面(objectType=user)", + ], + when_not_to_use: &[ + "要给管理员开权限(is_admin=1 本来就全通过,不需要授权)", + "还没建菜单(先 menu.create)", + "想收回权限(用 permission.authorize.revoke)", + ], + preconditions: &[ + "菜单必须已存在(menuId 或 menuEnCode 能查到)", + "授权对象必须存在(roleId / userId 等要真实)", + "推荐授给 role 而不是 user:角色变更时不用逐人重授", + ], + pitfalls: &[ + Pitfall { + severity: Severity::P0, + wrong: "给用户授了菜单,但他还是看不见", + right: "先 permission.effective 查他**实际**的有效菜单,看这条授权有没有进去", + rationale: "菜单可见性 = 四源并集 ∩ 当前应用(f_system_id)。\ + 授上了但 system_id 不匹配时,集合里有这个 id、菜单查询却按另一应用过滤 ⇒ 看不见。\ + effective 会同时返回「四源贡献」与「应用过滤后剩多少」,一眼定位是哪一层。", + }, + Pitfall { + severity: Severity::P0, + wrong: "以为授权会自动包含子菜单", + right: "只授权**这一条**菜单;父目录/子页面各自需要授权", + rationale: "`base_authorize` 是扁平关联表,没有树继承语义。\ + 官方前端靠「父目录也授权」来保证侧栏能渲染出层级 —— 只授子页面会导致\ + 侧栏没有父节点可挂,表现成「授权的菜单不显示」。", + }, + Pitfall { + severity: Severity::P1, + wrong: "用 f_id 之外的东西当 objectId(如账号、角色名)", + right: "一律用主键 id(permission.user.list / role.list 拿)", + rationale: "`base_authorize.f_object_id` 存的是主键字符串,不做名称解析;\ + 传账号会插进一条**永远匹配不上**的授权 —— 不报错、也不生效。", + }, + ], + examples: &[ + Example { + args: r#"{"objectType":"role","objectId":"","menuEnCode":"permission.asset.dataResource"}"#, + note: "推荐做法:授给角色,组内所有人可见", + }, + Example { + args: r#"{"objectType":"user","objectId":"","menuId":""}"#, + note: "临时特批:只给这一个人", + }, + ], + }, + handler: grant_handler, +}; + +// ================================================================ permission.authorize.revoke + +passthrough!(revoke_handler, "permission.authorize.revoke"); + +pub const AUTHORIZE_REVOKE: ToolDef = ToolDef { + id: "permission.authorize.revoke", + category: Category::Permission, + title: "撤销授权", + one_liner: "收回某个菜单的授权(软删 base_authorize 行)", + input_schema: r#"{ + "type": "object", + "properties": { + "objectType": { "type": "string", "enum": ["user", "role", "organize", "position"] }, + "objectId": { "type": "string" }, + "menuId": { "type": "string", "description": "菜单 id" }, + "menuEnCode": { "type": "string", "description": "或用 enCode 指定菜单" }, + "systemEnCode": { "type": "string", "default": "mainSystem" } + }, + "required": ["objectType"], + "additionalProperties": false + }"#, + annotations: Annotations::DESTRUCTIVE, + hints: Hints { + when_to_use: &[ + "某人离职/转岗,收回他直授的菜单", + "角色权限收窄", + "调试时临时开的权限用完要关", + ], + when_not_to_use: &[ + "要删的是菜单本身(用 menu.delete)", + "只是想确认有没有授上(用 permission.effective,别用撤权试探)", + ], + preconditions: &[ + "先 permission.authorize.list 确认这条授权确实存在(撤不存在的会报 NOT_FOUND,不是静默成功)", + "撤权只影响本层;用户仍可能通过角色/组织/岗位拿到同一菜单 —— 用 effective 复核", + ], + pitfalls: &[Pitfall { + severity: Severity::P0, + wrong: "撤了直授就以为他没权限了", + right: "用 permission.effective 复核:他可能还从角色/组织/岗位拿到同一个菜单", + rationale: "四源是**并集**语义,撤掉一源不代表集合里没有这个 id。\ + 这是最常见的「撤了还能看」解释。", + }], + examples: &[Example { + args: r#"{"objectType":"user","objectId":"","menuEnCode":"permission.asset.dataResource"}"#, + note: "收回某人的直授", + }], + }, + handler: revoke_handler, +}; + +// ================================================================ permission.effective + +passthrough!(effective_handler, "permission.effective"); +pub const EFFECTIVE: ToolDef = ToolDef { + id: "permission.effective", + category: Category::Permission, + title: "查用户的有效菜单", + one_liner: "四源并集算出某用户实际能访问的菜单,并标出每个菜单来自哪个源", + input_schema: r#"{ + "type": "object", + "properties": { + "userId": { "type": "string", "description": "用户 id(不是账号)" }, + "account": { "type": "string", "description": "或直接用账号,内部换算成 id" }, + "systemEnCode": { "type": "string", "default": "mainSystem", "description": "限定应用" }, + "withMenuDetail": { "type": "boolean", "default": false, "description": "true 则返回菜单名/路径,默认只返回 id 列表(省 token)" } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &[ + "「菜单授权了但用户看不见」—— 这是第一诊断入口", + "确认某个角色的授权是否真的生效到人", + "排查跨应用(App-Code)授权错位", + ], + when_not_to_use: &[ + "只想看某人被直授了什么(用 permission.authorize.list,那个只看一源)", + "想看菜单树结构(用 menu.tree)", + ], + preconditions: &[ + "userId 或 account 至少给一个", + "要判断「为什么看不见」,还需要 withMenuDetail=true 才能看到菜单名", + ], + pitfalls: &[ + Pitfall { + severity: Severity::P0, + wrong: "把 effective 的 id 列表直接和 menu.tree 对比,发现数量不一致就说工具错了", + right: "effective 返回 **fourSource**(四源并集,未按应用过滤)与 **visible**(按 f_system_id 过滤后)两组数", + rationale: "菜单表按 `f_system_id` 隔离,而 `base_authorize` **不带应用维度**。\ + ⇒ 同一份授权会同时匹配多个应用里的同 id 菜单。effective 把两组都给你,\ + 就是为了区分「授上了」和「在这个应用里能看到」。", + }, + Pitfall { + severity: Severity::P1, + wrong: "用账号当 userId 传", + right: "传 id;或改用 account 参数让工具自己换算", + rationale: "主键与账号是两套标识,混用会查到空集 —— 而且不报错。", + }, + ], + examples: &[ + Example { + args: r#"{"account":"admin","withMenuDetail":true}"#, + note: "按账号查,带菜单名(管理员会短路成全量,注意 isAdmin 字段)", + }, + Example { + args: r#"{"userId":""}"#, + note: "只要 id 列表(省 token,适合程序化比对)", + }, + ], + }, + handler: effective_handler, +}; + +// ================================================================ permission.user.create + +passthrough!(user_create_handler, "permission.user.create"); + +pub const USER_CREATE: ToolDef = ToolDef { + id: "permission.user.create", + category: Category::Permission, + title: "建用户", + one_liner: "建一个普通用户并可同时绑角色(用于验证「新人是否真能看见」)", + input_schema: r#"{ + "type": "object", + "properties": { + "account": { "type": "string", "description": "登录账号,字母开头,只含字母数字下划线" }, + "realName": { "type": "string", "description": "真实姓名" }, + "password": { "type": "string", "description": "明文口令(工具内部转 md5 存库,不落地明文)" }, + "roleIds": { "type": "array", "items": { "type": "string" }, "description": "要绑定的角色 id 列表(可选,一步到位)" }, + "isAdministrator": { "type": "boolean", "default": false, "description": "默认 false —— 真人测试必须是非管理员,否则权限短路看不到问题" }, + "gender": { "type": "string", "enum": ["male", "female", "unknown"], "description": "性别(官方取值 male/female/unknown)" }, + "mobilePhone": { "type": "string" }, + "email": { "type": "string" } + }, + "required": ["account", "realName", "password"], + "additionalProperties": false + }"#, + annotations: Annotations::CREATE, + hints: Hints { + when_to_use: &[ + "验证「授权后非管理员真的能看见」—— 这是授权闭环的最后一步", + "新同事入职建账号", + ], + when_not_to_use: &[ + "只是要查现有用户(用 permission.user.list)", + "要建管理员(本期刻意不开放:isAdministrator 默认 false,避免 AI 顺手造超管)", + ], + preconditions: &[ + "account 必须唯一(软删的也算占用,避免「删了重建」后历史授权错位)", + "roleIds 里的角色必须存在", + ], + pitfalls: &[ + Pitfall { + severity: Severity::P0, + wrong: "建完用户直接用 admin 账号去测菜单可见性", + right: "用**新建的非管理员账号**测:admin 走 is_admin 短路,永远看得见,测不出授权问题", + rationale: "菜单守卫第一条判据是 `is_admin == 1 ⇒ true`,根本不查授权表。\ + 用 admin 验证等于什么都没验证。", + }, + Pitfall { + severity: Severity::P1, + wrong: "口令传 md5 值", + right: "传明文,工具内部算 md5(库内存的就是 `md5(明文)`)", + rationale: "登录时密文解出来直接与库里值比对,库里存的是 md5。传 md5 会导致\ + 二次哈希 ⇒ 登录永远失败,而且不报错(只报「账号或密码错误」)。", + }, + ], + examples: &[ + Example { + args: r#"{"account":"zhangsan","realName":"张三","password":"Ss@123456","roleIds":["role_user"]}"#, + note: "建人 + 绑角色,一步到位", + }, + ], + }, + handler: user_create_handler, +}; diff --git a/docs/mcp.md b/docs/mcp.md index 2fda37b..0288a95 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -80,7 +80,7 @@ sspf_context # 1. 先确认环境 → 失败则读 error.hints / next_actions 自纠 ``` -### 当前业务工具(15 个) +### 当前业务工具(19 个) | 域 | 工具 | 一句话 | 写 | |---|---|---|---| @@ -92,8 +92,12 @@ sspf_context # 1. 先确认环境 | menu | `menu.create` | 建菜单(写全 enCode + systemId) | ✅ | | menu | `menu.delete` | 软删菜单 | ✅ | | permission | `permission.user.list` | 用户(**不含口令字段**) | | +| permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ | | permission | `permission.role.list` | 角色 | | | permission | `permission.authorize.list` | 查某对象的直授 | | +| permission | `permission.authorize.grant` | 给用户/角色/组织/岗位授菜单(幂等) | ✅ | +| permission | `permission.authorize.revoke` | 撤权(软删,撤不存在会报错) | ✅ | +| permission | `permission.effective` | 四源并集算出**实际**可见的菜单 | | | dict | `dict.type.list` | 字典分类 | | | dict | `dict.data.list` | 字典项 | | | dict | `dict.type.create` | 建字典分类 | ✅ | @@ -101,13 +105,36 @@ sspf_context # 1. 先确认环境 | data | `data.count` | 按表名计数 | | **写工具为什么少而严**:读工具错了只是「看到错的数据」,写工具错了是「把库改坏」。 -所以三个写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一), +所以写工具都在写库**之前**做完校验(必填/格式/父节点存在/编码唯一), 并给出可执行的 `hints`;删除一律软删。 🔴 **`menu.create` 比 HTTP 侧的 `module_save` 更完整**:后者只写 12 列,缺 `f_en_code`(面 B 权限判据)与 `f_system_id`(多应用隔离)——那两列缺了, 菜单要么点进去 403,要么根本不显示。P2 元数据引擎统一时会把两处合成一处。 +### 授权闭环:建完菜单不等于看得见 + +``` +menu.create 建菜单 + → permission.authorize.grant 授给角色(推荐)或用户(临时特批) + → permission.user.create 建一个**非管理员**账号验证 + → permission.effective 看他实际能访问什么,每项标明来自哪个源 +``` + +🔴 **绝不能用 admin 验证**:`is_admin == 1` 在守卫第一条判据就返回 true, +根本不查授权表 —— 用 admin 测等于什么都没测。`permission.effective` 会显式 +返回 `isAdmin: true` 与 `mode: "admin-bypass"`,提醒你这个结果不代表授权生效。 + +`permission.effective` 返回两组数,这是排查「授权了但看不见」的关键: + +| 字段 | 含义 | +|---|---| +| `fourSource` | 四源并集(直授 + 角色 + 组织 + 岗位),**不按应用过滤** | +| `visible` | 再与当前应用的菜单求交 —— 这才是用户真正能点到的 | +| `sources.*` | 每个源各贡献了哪些菜单 id(定位「这条权限从哪来」) | + +两者不一致 ⇒ 授权指向了别的应用的菜单(或菜单已删)。 + --- ## 3. 失败返回长什么样(比成功更重要) @@ -138,9 +165,9 @@ sspf_context # 1. 先确认环境 --- -## 4. 资源与提示 +## 4. 资源、模板与双后端 -`resources/read` 可读: +### 可读资源(`resources/read`) | URI | 内容 | |---|---| @@ -148,6 +175,59 @@ sspf_context # 1. 先确认环境 | `sspf://docs/quickstart` | 上面的推荐顺序与常见误区 | | `sspf://contract/endpoints` | HTTP 契约端点表(与 MCP 工具不是一一对应) | +### 多步流程模板(`prompts/*`) + +模板回答的是「整件事按什么顺序做、做到哪算完成」——AI 最容易错的不是参数, +而是**漏步骤**(建了菜单忘授权、授权了没验证)。 + +| 模板 | 参数 | 干什么 | +|---|---|---| +| `new_business_module` | `module_name` / `module_code` / `role_id`(可选) | 建菜单 → 授权 → 建非管理员账号 → 验证可见,共 5 步 + 失败对照表 | +| `diagnose_menu_not_visible` | `account` | 五步定位法,按 `fourSource` / `visible` 分流判断根因 | +| `verify_all` | — | 一次跑完全部测试、静态闸门、契约尺子、内存实测 | + +模板**不占常驻 token**(只在用户主动引用时 `prompts/get`)。 + +🔴 模板正文里引用了工具 id,工具改名后模板会变成错误指导且**没人会发现**。 +`crates/sspf-mcp/src/prompts.rs` 的测试会扫出正文里所有 `域.动作` 字符串逐个核对, +引用不存在的工具 ⇒ 测试失败。 + +### 双后端:同一套工具打两种后端 + +`PlatformAdapter` 只有两个方法,实现有三个(`Null` 是测试用): + +| 实现 | 位置 | 后端 | 用在哪 | +|---|---|---|---| +| `NativeAdapter` | `src/backend/src/mcp_adapter.rs` | 进程内 `AppState` | 主力形态(`--mcp`) | +| `BaselineHttpAdapter` | `crates/sspf-adapter-baseline` | 远端 HTTP(Java 后端或本仓内核) | P4 影子对账 / 过渡期提速 | + +基线适配器**刻意只映射 5 个只读 op**(`context.get` / `menu.tree` / +`permission.user.list` / `permission.role.list` / `dict.type.list`): + +- baseline 是**业务 API**,没有「列出表结构」这类端点 —— 硬凑会造出 + 「看起来能跑、语义其实不对」的工具,比明确不支持更糟 +- 不支持的 op 返回 `CAPABILITY_UNSUPPORTED` + 「切 native」的可执行建议 + +它同时是**形状适配器**(这才是对账的关键): + +``` +baseline: {code,msg,data:{list,pagination}} → native: {count, users/roles/menus/types} +organize → organizeId +多余键(creatorTime/fullName…) → 裁掉 +``` + +形状不统一时,对账每一条都是差异,看不出业务问题。 + +```bash +# 探针:用它打任意实现了契约的 HTTP 后端 +PGLITE_DIR=/tmp/db PORT=30994 ./target/release/ssw-platform & +cargo run -p sspf-adapter-baseline --example probe -- \ + http://127.0.0.1:30994 admin "$(./target/release/ssw-platform --enc 123456)" +``` + +🔴 口令要传**密文**(`--enc` 生成)。适配器不复制 cipher 逻辑 —— +复制会漂移,下沉到 contract 会破坏「契约层无 IO」的边界(AR4)。 + --- ## 5. 已知限制(P1 阶段) @@ -155,9 +235,10 @@ sspf_context # 1. 先确认环境 | 限制 | 说明 | 计划 | |---|---|---| | 没有登录态 | 进程内适配器是**管理员视角**,绕过菜单守卫 | 刻意如此(本地开发);对外暴露必须换 `BaselineHttpAdapter` | -| 业务工具 15 个 | 见上面清单;form / model / workflow 还没有 | P2 补 | -| `prompts/*` 返回空 | 多步流程模板还没写 | P2 | -| 没有 `BaselineHttpAdapter` | 只能驱动自身内核,不能打远端 Java 后端 | P4 对账前必须有 | +| 业务工具 19 个 | 见上面清单;form / model / workflow 还没有 | P2 补 | +| 基线适配器只支持 5 个只读 op | baseline 无元数据 API | P4 按对账需要再补 | +| 基线适配器只支持 `http://` | 未引入 TLS 栈;`https://` 构造期直接报错 | 需要时再加 | +| `permission.user.create` 不开放建管理员 | `isAdministrator` 硬编码 false | 刻意:避免 AI 顺手造超管 | | 🔴 **stderr 不能是 `/dev/null`** | 见下方「坑 ④」 | 已在代码里尽量兜,但客户端请收 stderr | ### 🔴 坑 ④:stderr 指向 `/dev/null` 时会零响应 diff --git a/scripts/baseline-smoke.sh b/scripts/baseline-smoke.sh new file mode 100755 index 0000000..c30a073 --- /dev/null +++ b/scripts/baseline-smoke.sh @@ -0,0 +1,202 @@ +#!/usr/bin/env bash +# ============================================================================ +# baseline-smoke —— 基线平台 HTTP 适配器的契约尺子(P1-d) +# +# 验证什么: +# B1 自动登录(账号 + 密文口令)能拿到 token +# B2 describe_env 能读到 tables / version(health 是裸对象,不是信封) +# B3 menu.tree 的 `data.list` 被投影成 native 的 `menus` +# B4 user.list 的 `organize` → `organizeId`,缺的 `roleId` 补空串 +# B5 user.list 裁剪掉 native 没有的键(creatorTime/fullName…) +# B6 dict.type.list 可用(空库返回 0 条也不算失败) +# B7 不支持的 op 在**发请求前**被拦下(CAPABILITY_UNSUPPORTED) +# +# 🔴 为什么打自己而不是打 Java 后端: +# 本仓内核实现的 HTTP 端点就是契约本身(docs/contract.md)。 +# 用适配器打自己 = 跨进程走一遍契约,能验证端点映射与形状归一化; +# 等真实基线平台接入时,把 BASE_URL 换掉即可(P4 对账的预演)。 +# +# 用法: bash scripts/baseline-smoke.sh [端口] +# 退出码: 0 全过 / 1 有 ❌ +# ============================================================================ + +set -u + +ROOT="$(cd "$(dirname "$0")/.." && pwd)" +cd "$ROOT" || exit 1 + +PORT="${1:-30993}" +BIN="$ROOT/target/debug/ssw-platform" +PROBE="$ROOT/target/debug/examples/probe" + +PASS=0 +FAIL=0 + +ok() { PASS=$((PASS + 1)); printf '✅ %s\n' "$1"; } +bad() { FAIL=$((FAIL + 1)); printf '❌ %s\n' "$1"; } + +if [ ! -x "$BIN" ]; then + echo "❌ 找不到 $BIN(先 cargo build)" + exit 1 +fi +if [ ! -x "$PROBE" ]; then + echo "❌ 找不到 $PROBE(先 cargo build -p sspf-adapter-baseline --example probe)" + exit 1 +fi + +TMP="$(mktemp -d /tmp/baseline-smoke.XXXXXX)" || exit 1 +SVC_PID="" + +cleanup() { + [ -n "$SVC_PID" ] && kill "$SVC_PID" 2>/dev/null + sleep 1 + [ -n "$SVC_PID" ] && kill -9 "$SVC_PID" 2>/dev/null + rm -rf "$TMP" +} +trap cleanup EXIT + +# ---- 起一个 HTTP 后端(临时库,不污染开发数据)---- +PGLITE_DIR="$TMP/db" PORT="$PORT" "$BIN" > "$TMP/svc.log" 2>&1 & +SVC_PID=$! + +# 等就绪(最多 10 秒) +for _ in $(seq 1 20); do + if curl -s --noproxy '*' --max-time 1 "http://127.0.0.1:$PORT/api/health" > /dev/null 2>&1; then + break + fi + sleep 0.5 +done + +if ! curl -s --noproxy '*' --max-time 2 "http://127.0.0.1:$PORT/api/health" | grep -q '"ok":true'; then + echo "❌ 后端没起来;日志末尾:" + tail -5 "$TMP/svc.log" + exit 1 +fi + +# ---- 跑探针 ---- +ENC="$("$BIN" --enc 123456)" +if [ -z "$ENC" ]; then + echo "❌ 取不到密文口令" + exit 1 +fi + +"$PROBE" "http://127.0.0.1:$PORT" admin "$ENC" > "$TMP/probe.ndjson" 2> "$TMP/probe.err" +if [ ! -s "$TMP/probe.ndjson" ]; then + echo "❌ 探针没有输出;stderr:" + cat "$TMP/probe.err" + exit 1 +fi + +# ---- 断言 ---- +python3 - "$TMP/probe.ndjson" <<'PY' +import json, sys + +lines = [l for l in open(sys.argv[1], encoding='utf-8') if l.strip()] +rows = {} +for line in lines: + try: + m = json.loads(line) + except json.JSONDecodeError as e: + print(f"❌ 输出不是合法 JSON 行: {e}\n {line[:120]}") + sys.exit(1) + rows[m["op"]] = m + +PASS = [0] +FAIL = [0] + +def ok(msg): + PASS[0] += 1 + print(f"✅ {msg}") + +def bad(msg): + FAIL[0] += 1 + print(f"❌ {msg}") + +# B1 / B2 环境与登录 +env = rows.get("describe_env", {}) +if env.get("ok") and env.get("data", {}).get("backend") == "baseline-http": + d = env["data"] + ok(f"B1 自动登录成功(账号+密文 ⇒ token),backend={d['backend']}") + if d.get("tables", 0) > 0 and d.get("version"): + ok(f"B2 describe_env 读到 health 裸对象:tables={d['tables']} version={d['version']}") + else: + bad(f"B2 describe_env 没读到 tables/version: {json.dumps(d, ensure_ascii=False)[:160]}") +else: + bad(f"B1 describe_env 失败: {json.dumps(env, ensure_ascii=False)[:200]}") + +# B3 menu.tree 形状 +mt = rows.get("menu.tree", {}) +md = mt.get("data", {}) if mt.get("ok") else {} +menus = md.get("menus") or [] +if mt.get("ok") and md.get("count", 0) > 0 and isinstance(menus, list): + # native 形状:有 menus 键、每项有 urlAddress/parentId;baseline 的 list 键必须消失 + first = menus[0] if menus else {} + if "list" not in md and {"id", "fullName", "urlAddress", "parentId"} <= set(first): + ok(f"B3 menu.tree 投影成 native 形状({md['count']} 条,键为 menus 而非 list)") + else: + bad(f"B3 menu.tree 形状不对: {json.dumps(md, ensure_ascii=False)[:200]}") +else: + bad(f"B3 menu.tree 失败: {json.dumps(mt, ensure_ascii=False)[:200]}") + +# B4 / B5 user.list 字段改名与裁剪 +ul = rows.get("permission.user.list", {}) +ud = ul.get("data", {}) if ul.get("ok") else {} +users = ud.get("users") or [] +if ul.get("ok") and users: + u0 = users[0] + if "organizeId" in u0 and "organize" not in u0: + ok("B4 user.list 的 organize → organizeId 改名生效") + else: + bad(f"B4 organizeId 改名失效: {json.dumps(u0, ensure_ascii=False)[:160]}") + if "roleId" in u0: + ok("B4b baseline 缺失的 roleId 补了空串(形状对齐 native)") + else: + bad("B4b roleId 没补默认值") + leaked = {"creatorTime", "fullName", "description", "headIcon"} & set(u0) + if not leaked: + ok("B5 user.list 已裁剪掉 native 没有的键(否则对账永远不等)") + else: + bad(f"B5 有多余键未裁剪: {sorted(leaked)}") +else: + bad(f"B4 user.list 失败: {json.dumps(ul, ensure_ascii=False)[:200]}") + +# B6 role / dict +rl = rows.get("permission.role.list", {}) +if rl.get("ok") and rl.get("data", {}).get("count", 0) >= 2: + ok(f"B6 role.list 投影正常({rl['data']['count']} 个角色)") +else: + bad(f"B6 role.list 失败: {json.dumps(rl, ensure_ascii=False)[:160]}") + +dt = rows.get("dict.type.list", {}) +if dt.get("ok") and isinstance(dt.get("data", {}).get("types"), list): + ok(f"B6b dict.type.list 可用({dt['data'].get('count', 0)} 条,空库不算失败)") +else: + bad(f"B6b dict.type.list 失败: {json.dumps(dt, ensure_ascii=False)[:160]}") + +# B7 不支持的 op 必须在发请求前被拦下 +st = rows.get("schema.table.list", {}) +if st.get("ok") is False and st.get("error", {}).get("code") == "CAPABILITY_UNSUPPORTED": + hints = " ".join(st["error"].get("hints") or []) + if "native" in hints: + ok("B7 不支持的 op ⇒ CAPABILITY_UNSUPPORTED,且指引切 native") + else: + bad("B7 错误没有可执行的 hint") + if st["error"].get("next_actions"): + ok("B7b 错误带 next_actions(AI 能自纠)") + else: + bad("B7b 错误缺 next_actions") +else: + bad(f"B7 schema.table.list 应该被拦下: {json.dumps(st, ensure_ascii=False)[:200]}") + +print() +print(f"PASS={PASS[0]} FAIL={FAIL[0]}") +sys.exit(1 if FAIL[0] else 0) +PY +RC=$? + +echo +if [ "$RC" -ne 0 ]; then + echo "❌ baseline-smoke 有失败项(见上)" + exit 1 +fi +echo "✅ baseline-smoke 全过" diff --git a/scripts/check-arch.sh b/scripts/check-arch.sh index c34d3b5..1912187 100755 --- a/scripts/check-arch.sh +++ b/scripts/check-arch.sh @@ -23,6 +23,9 @@ # AR5 `crates/sspf-mcp`(若已存在)依赖 ⊆ {sspf-contract, serde, serde_json, tokio, async-trait} # —— MCP 层要能同时接「进程内内核」和「远端 Java 后端」⇒ **不许依赖内核内部** # —— tokio / async-trait 是协议实现(stdio 异步读写)所需,不是业务依赖 +# AR6 `crates/sspf-adapter-baseline` 依赖 ⊆ {sspf-mcp, sspf-contract, serde, serde_json, +# tokio, http, hyper, hyper-util, http-body-util, bytes} +# —— 适配器只认工具契约层;依赖内核 store 就等于把第二种后端钉死在本进程旁 # MEM1 非注释代码里不许出现 `SELECT *` # —— 终端产品内存预算 ≤ 120MB(PLAN.md 判断 ⑥)⇒ 全表读进 Vec 直接爆 # MEM2 `crates/**` 与 `src/backend/src/platform/**` 里不许出现无界 `HashMap` 缓存 @@ -46,7 +49,7 @@ skip() { SKIP=$((SKIP + 1)); printf '⏭ %s\n' "$1"; } usage() { echo "用法: bash scripts/check-arch.sh [--self-test]" - echo " 静态检查 crate 依赖纪律(AR1–AR5)与内存红线(MEM1–MEM2)" + echo " 静态检查 crate 依赖纪律(AR1–AR6)与内存红线(MEM1–MEM2)" echo "退出码: 0 全过 / 1 有 ❌ / 2 用法错" } @@ -140,6 +143,20 @@ check_ar5() { fi } +# ---------------------------------------------------------------- AR6 +check_ar6() { + local f="$CRATES/sspf-adapter-baseline/Cargo.toml" + [ -f "$f" ] || { skip "AR6 sspf-adapter-baseline 不存在"; return; } + local deps; deps="$(deps_of "$f" | tr '\n' ' ')" + # 🔴 适配器只许依赖「工具契约层 + HTTP 客户端」。 + # 一旦依赖 sspf-store / axum,第二种后端就只能跑在同一个内核旁边 —— 双轨失效。 + if subset_of "$deps" "sspf-mcp sspf-contract serde serde_json tokio http hyper hyper-util http-body-util bytes"; then + ok "AR6 sspf-adapter-baseline 依赖干净([$deps])" + else + bad "AR6 sspf-adapter-baseline 依赖越界:[$deps] —— 只许工具契约层 + HTTP 客户端,不许依赖内核 store" + fi +} + # ---------------------------------------------------------------- MEM1 # 只看**代码行**:去掉 `//` 之后的注释、`//!` / `///` 文档注释、以及字符串里的反引号示例。 check_mem1() { @@ -263,6 +280,7 @@ check_ar2 check_ar3 check_ar4 check_ar5 +check_ar6 check_mem1 check_mem2 diff --git a/scripts/mcp-smoke.sh b/scripts/mcp-smoke.sh index 534373a..34bf1a3 100755 --- a/scripts/mcp-smoke.sh +++ b/scripts/mcp-smoke.sh @@ -79,6 +79,15 @@ cat > "$REQ" <<'NDJSON' {"jsonrpc":"2.0","id":18,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"menu.create","args":{"fullName":"冒烟菜单","enCode":"permission.smoke.page","urlAddress":"smoke/Page"}}}} {"jsonrpc":"2.0","id":19,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"menu.create","args":{"fullName":"重复","enCode":"permission.smoke.page","urlAddress":"smoke/Other"}}}} {"jsonrpc":"2.0","id":20,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"menu.create","args":{"fullName":"坏路径","enCode":"permission.smoke.bad","urlAddress":"/bad/Path"}}}} +{"jsonrpc":"2.0","id":21,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.authorize.grant","args":{"objectType":"role","objectId":"role_user","menuEnCode":"permission.smoke.page"}}}} +{"jsonrpc":"2.0","id":22,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.user.create","args":{"account":"smoke_user","realName":"冒烟用户","password":"Smoke@123","roleIds":["role_user"]}}}} +{"jsonrpc":"2.0","id":23,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.effective","args":{"account":"smoke_user","withMenuDetail":true}}}} +{"jsonrpc":"2.0","id":24,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.authorize.revoke","args":{"objectType":"role","objectId":"role_user","menuEnCode":"permission.smoke.page"}}}} +{"jsonrpc":"2.0","id":25,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.effective","args":{"account":"smoke_user"}}}} +{"jsonrpc":"2.0","id":26,"method":"tools/call","params":{"name":"sspf_call","arguments":{"tool_id":"permission.authorize.revoke","args":{"objectType":"role","objectId":"role_user","menuEnCode":"permission.smoke.page"}}}} +{"jsonrpc":"2.0","id":27,"method":"prompts/list","params":{}} +{"jsonrpc":"2.0","id":28,"method":"prompts/get","params":{"name":"new_business_module","arguments":{"module_name":"冒烟","module_code":"smoke"}}} +{"jsonrpc":"2.0","id":29,"method":"prompts/get","params":{"name":"diagnose_menu_not_visible","arguments":{}}} NDJSON echo "── MCP 工具层契约尺子(4 元工具 + 分层加载)──" @@ -156,10 +165,10 @@ else: ok("M3 业务工具不在 tools/list(只能经 discover 访问)") # ---- M4 通知不回复 ---- -if len(parsed) == 20: - ok("M4 20 条带 id 的请求各一个回复;通知无回复") +if len(parsed) == 29: + ok("M4 29 条带 id 的请求各一个回复;通知无回复") else: - bad(f"M4 回复数 {len(parsed)},期望 20(通知不该有回复)") + bad(f"M4 回复数 {len(parsed)},期望 29(通知不该有回复)") # ---- M5 context ---- sc = (result(3) or {}).get("structuredContent", {}) @@ -285,6 +294,69 @@ if w3.get("ok") is False and w3e.get("code") == "BAD_URL_ADDRESS": else: bad(f"M22 坏路径未被拒: {json.dumps(w3, ensure_ascii=False)[:140]}") +# ---- M23~M30 授权闭环(建菜单后的最后一公里)---- +g = (result(21) or {}).get("structuredContent", {}) +if g.get("ok") is True and g.get("data", {}).get("granted") is True: + ok("M23 permission.authorize.grant 授给角色成功") +else: + bad(f"M23 授权失败: {json.dumps(g, ensure_ascii=False)[:160]}") + +u = (result(22) or {}).get("structuredContent", {}) +if u.get("ok") is True and u.get("data", {}).get("isAdministrator") is False: + ok("M24 user.create 建出的是**非管理员**账号(能测出授权问题)") +else: + bad(f"M24 建用户失败: {json.dumps(u, ensure_ascii=False)[:160]}") + +e1 = (result(23) or {}).get("structuredContent", {}).get("data", {}) +vis1 = [m.get("urlAddress") for m in (e1.get("visible") or {}).get("menus", []) + if isinstance(m, dict)] +src1 = (e1.get("sources") or {}).get("role", {}).get("menuIds") or [] +if e1.get("isAdmin") is False and "smoke/Page" in vis1 and src1: + ok(f"M25 effective 看到授权的菜单(visible={e1['visible']['count']},来源=role)") +else: + bad(f"M25 授权后仍看不到: visible={vis1} isAdmin={e1.get('isAdmin')}") + +rv = (result(24) or {}).get("structuredContent", {}) +if rv.get("ok") is True and rv.get("data", {}).get("revoked") is True: + ok("M26 revoke 撤权成功(软删)") +else: + bad(f"M26 撤权失败: {json.dumps(rv, ensure_ascii=False)[:160]}") + +e2 = (result(25) or {}).get("structuredContent", {}).get("data", {}) +vis2 = [m.get("urlAddress") for m in (e2.get("visible") or {}).get("menus", []) + if isinstance(m, dict)] +if "smoke/Page" not in vis2: + ok("M27 撤权后 effective 立刻看不到(四源并集真的变了)") +else: + bad(f"M27 撤权后仍可见: {vis2}") + +e3 = (result(26) or {}).get("structuredContent", {}) +if e3.get("ok") is False and e3.get("error", {}).get("code") == "AUTHORIZE_NOT_FOUND": + ok("M28 重复撤权 ⇒ AUTHORIZE_NOT_FOUND(不静默成功)") +else: + bad(f"M28 重复撤权未被拒: {json.dumps(e3, ensure_ascii=False)[:160]}") + +pl = result(27) or {} +names = [x.get("name") for x in (pl.get("prompts") or [])] +if len(names) >= 3 and "new_business_module" in names: + ok(f"M29 prompts/list 返回 {len(names)} 个模板(含 new_business_module)") +else: + bad(f"M29 prompts/list 异常: {names}") + +pg = result(28) or {} +ptext = ((pg.get("messages") or [{}])[0].get("content") or {}).get("text", "") +if "非管理员" in ptext and "menu.create" in ptext and "permission.authorize.grant" in ptext: + ok("M30 prompts/get 正文含关键步骤(建菜单 + 授权 + 非管理员验证)") +else: + bad(f"M30 模板正文缺关键步骤(长度 {len(ptext)})") + +# 缺参时是 JSON-RPC error(没有 result),所以要拿整条响应 +pm = parsed.get(29, {}) +if pm.get("error", {}).get("code") == -32602: + ok("M31 模板缺必填参数 ⇒ INVALID_PARAMS(不渲染带占位符的正文)") +else: + bad(f"M31 缺参未被拦: {json.dumps(pm, ensure_ascii=False)[:140]}") + print() print(f"PASS={PASS} FAIL={FAIL}") sys.exit(0 if FAIL == 0 else 1) diff --git a/src/backend/src/mcp_adapter.rs b/src/backend/src/mcp_adapter.rs index 93182f7..72c55c0 100644 --- a/src/backend/src/mcp_adapter.rs +++ b/src/backend/src/mcp_adapter.rs @@ -890,6 +890,755 @@ impl NativeAdapter { "note": "分类已建;字典**项**(下拉选项)P2 通过 dict.data.create 补", })) } + + // ---------------------------------------------------------------- 授权(第四批:闭环) + + /// `base_authorize.f_object_type` → 真实表名。 + /// + /// 🔴 **硬编码映射,不走 `valid_table`**:这里的表名是代码常量, + /// 用户输入只贡献 enum 值,拼不出任意表名 —— 这是比字符串白名单更强的保证。 + fn object_table(object_type: &str) -> Option<&'static str> { + match object_type { + "user" => Some("base_user"), + "role" => Some("base_role"), + "organize" => Some("base_organize"), + "position" => Some("base_position"), + _ => None, + } + } + + /// 解析要授权的菜单:`menuId` 优先,否则 `menuEnCode` + 应用过滤。 + /// + /// 返回 `(id, fullName, enCode)`。 + async fn resolve_menu(&self, args: &Value) -> Result<(String, String, String), ToolError> { + let menu_id = args + .get("menuId") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + let menu_en_code = args + .get("menuEnCode") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + + if menu_id.is_empty() && menu_en_code.is_empty() { + return Err(ToolError::new( + "MISSING_ARG", + "menuId 与 menuEnCode 至少给一个", + ) + .field("menuId") + .hint("menuId 来自 menu.tree;menuEnCode 是建菜单时写的 permission.x.y") + .next("menu.tree", json!({"flat": true}), "先查菜单 id 与编码")); + } + + let rows = if !menu_id.is_empty() { + let mid = menu_id.clone(); + self.state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_full_name,'') AS \"fullName\", \ + COALESCE(f_en_code,'') AS \"enCode\" \ + FROM base_module WHERE f_id = $1 AND f_delete_mark = 0 LIMIT 1", + &[&mid], + ) + .await + .map_err(db_err)? + } else { + // 按编码查时要限定应用:不同应用可以存在同 en_code 的菜单,跨应用授权等于授错对象。 + let sys_code = args + .get("systemEnCode") + .and_then(Value::as_str) + .unwrap_or("mainSystem") + .to_string(); + let system_id = self.system_id_of(&sys_code).await?; + let ec = menu_en_code.clone(); + self.state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_full_name,'') AS \"fullName\", \ + COALESCE(f_en_code,'') AS \"enCode\" \ + FROM base_module \ + WHERE f_en_code = $1 AND f_system_id = $2 AND f_delete_mark = 0 LIMIT 1", + &[&ec, &system_id], + ) + .await + .map_err(db_err)? + }; + + let Some(row) = rows.first() else { + let what = if menu_id.is_empty() { + format!("enCode={menu_en_code}(应用 {})", args + .get("systemEnCode") + .and_then(Value::as_str) + .unwrap_or("mainSystem")) + } else { + format!("id={menu_id}") + }; + return Err(ToolError::new("MENU_NOT_FOUND", format!("菜单不存在或已删除: {what}")) + .field(if menu_id.is_empty() { "menuEnCode" } else { "menuId" }) + .hint("P0:同 enCode 在不同应用是不同菜单,确认 systemEnCode 对不对") + .next("menu.tree", json!({"flat": true}), "列出当前应用的菜单")); + }; + + Ok(( + row["id"].as_str().unwrap_or("").to_string(), + row["fullName"].as_str().unwrap_or("").to_string(), + row["enCode"].as_str().unwrap_or("").to_string(), + )) + } + + /// `permission.authorize.grant` —— 幂等:已授权则原样返回,不重复插行。 + async fn authorize_grant(&self, args: &Value) -> Result { + let object_type = args + .get("objectType") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + let Some(table) = Self::object_table(&object_type) else { + return Err(ToolError::new( + "BAD_OBJECT_TYPE", + format!("objectType 只能是 user / role / organize / position,收到 `{object_type}`"), + ) + .field("objectType") + .hint("推荐 role(一改全组生效);user 只用于临时特批,逐人维护成本高")); + }; + + let object_id = args + .get("objectId") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + if object_id.is_empty() { + return Err(ToolError::new("MISSING_ARG", "objectId 不能为空") + .field("objectId") + .hint(format!( + "用主键 id,不是账号/名称(permission.{} 拿)", + if object_type == "user" { "user" } else { "role" }.to_string() + + ".list" + ))); + } + + // 授权对象必须真实存在:插一条指向不存在 id 的行,不报错但永远不生效。 + let obj_rows = self + .state + .db + .query_json_params( + &format!( + "SELECT f_id AS \"id\", COALESCE(f_full_name,'') AS \"name\" \ + FROM {table} WHERE f_id = $1 AND f_delete_mark = 0 LIMIT 1" + ), + &[&object_id], + ) + .await + .map_err(db_err)?; + if obj_rows.is_empty() { + return Err(ToolError::new( + "OBJECT_NOT_FOUND", + format!("{object_type} 不存在或已删除: {object_id}"), + ) + .field("objectId") + .hint("objectId 是主键,不是账号/角色名") + .next( + format!("permission.{}.list", if object_type == "user" { "user" } else { "role" }), + json!({}), + "先列表拿真实 id", + )); + } + let object_name = obj_rows[0]["name"].as_str().unwrap_or("").to_string(); + + let (menu_id, menu_name, menu_en_code) = self.resolve_menu(args).await?; + + // 幂等:已有未删的同三元组 ⇒ 直接返回,不插重复行。 + let dup = self + .state + .db + .query_json_params( + "SELECT f_id AS \"id\" FROM base_authorize \ + WHERE f_item_type = 'module' AND f_item_id = $1 \ + AND f_object_type = $2 AND f_object_id = $3 AND f_delete_mark = 0 LIMIT 1", + &[&menu_id, &object_type, &object_id], + ) + .await + .map_err(db_err)?; + if let Some(row) = dup.first() { + return Ok(json!({ + "granted": false, + "alreadyGranted": true, + "authorizeId": row["id"].as_str().unwrap_or(""), + "objectType": object_type, + "objectId": object_id, + "menuId": menu_id, + "note": "该授权已存在(幂等,未重复插入)", + })); + } + + let id = crate::platform::ids::new_uuid(); + let vals: Vec> = vec![ + Some(id.clone()), + Some("0".to_string()), // f_tenant_id + Some("module".to_string()), // f_item_type + Some(menu_id.clone()), + Some(object_type.clone()), + Some(object_id.clone()), + Some("0".to_string()), // f_sort_code + Some("0".to_string()), // f_delete_mark + ]; + let refs: Vec<&(dyn ToSql + Sync)> = + vals.iter().map(|v| v as &(dyn ToSql + Sync)).collect(); + + self.state + .db + .exec_params( + "INSERT INTO base_authorize \ + (f_id, f_tenant_id, f_item_type, f_item_id, f_object_type, f_object_id, \ + f_sort_code, f_delete_mark, f_creator_time) \ + VALUES ($1::text, $2::text, $3::text, $4::text, $5::text, $6::text, \ + $7::text::bigint, $8::text::integer, now())", + &refs, + ) + .await + .map_err(db_err)?; + + Ok(json!({ + "granted": true, + "authorizeId": id, + "objectType": object_type, + "objectId": object_id, + "objectName": object_name, + "menuId": menu_id, + "menuName": menu_name, + "menuEnCode": menu_en_code, + "next": "用 permission.effective 复核是否真的生效(四源并集 ∩ 当前应用)", + })) + } + + /// `permission.authorize.revoke` —— 软删;撤不存在的行要报错(不静默成功)。 + async fn authorize_revoke(&self, args: &Value) -> Result { + let object_type = args + .get("objectType") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + if Self::object_table(&object_type).is_none() { + return Err(ToolError::new( + "BAD_OBJECT_TYPE", + format!("objectType 只能是 user / role / organize / position,收到 `{object_type}`"), + ) + .field("objectType")); + } + let object_id = args + .get("objectId") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + if object_id.is_empty() { + return Err(ToolError::new("MISSING_ARG", "objectId 不能为空").field("objectId")); + } + + let (menu_id, menu_name, _) = self.resolve_menu(args).await?; + + let hit = self + .state + .db + .query_json_params( + "SELECT f_id AS \"id\" FROM base_authorize \ + WHERE f_item_type = 'module' AND f_item_id = $1 \ + AND f_object_type = $2 AND f_object_id = $3 AND f_delete_mark = 0 LIMIT 1", + &[&menu_id, &object_type, &object_id], + ) + .await + .map_err(db_err)?; + let Some(row) = hit.first() else { + // 🔴 不静默成功:撤一条不存在的授权,最常见原因是 objectId 用错了(账号 vs id)。 + return Err(ToolError::new( + "AUTHORIZE_NOT_FOUND", + format!("没有这条授权:{object_type}={object_id} → {menu_name}"), + ) + .field("objectId") + .hint("objectId 是主键;用 permission.authorize.list 确认这条授权到底存不存在")); + }; + let auth_id = row["id"].as_str().unwrap_or("").to_string(); + + self.state + .db + .exec_params( + "UPDATE base_authorize SET f_delete_mark = 1, f_delete_time = now() \ + WHERE f_id = $1 AND f_delete_mark = 0", + &[&auth_id], + ) + .await + .map_err(db_err)?; + + Ok(json!({ + "revoked": true, + "authorizeId": auth_id, + "objectType": object_type, + "objectId": object_id, + "menuId": menu_id, + "menuName": menu_name, + "note": "只撤这一源;用户仍可能通过角色/组织/岗位拿到同一菜单 ⇒ 用 permission.effective 复核", + })) + } + + /// 查某个对象(user/role/…)被直授的菜单 id 列表。 + async fn authorized_modules( + &self, + object_type: &str, + object_id: &str, + ) -> Result, ToolError> { + let rows = self + .state + .db + .query_json_params( + "SELECT f_item_id AS \"itemId\" FROM base_authorize \ + WHERE f_item_type = 'module' AND f_object_type = $1 AND f_object_id = $2 \ + AND f_delete_mark = 0", + &[&object_type, &object_id], + ) + .await + .map_err(db_err)?; + Ok(rows + .iter() + .filter_map(|r| r["itemId"].as_str().map(str::to_string)) + .filter(|s| !s.is_empty()) + .collect()) + } + + /// `permission.effective` —— 四源并集 + 按应用过滤,两组数都给。 + /// + /// 🔴 这是「授权了但看不见」的唯一诊断入口:能把「没授上」和 + /// 「授上了但不在这个应用」区分开,省掉反复 grep 数据库。 + async fn permission_effective(&self, args: &Value) -> Result { + let user_id = args + .get("userId") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + let account = args + .get("account") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + + if user_id.is_empty() && account.is_empty() { + return Err(ToolError::new( + "MISSING_ARG", + "userId 与 account 至少给一个", + ) + .field("userId") + .hint("userId 是主键;不知道 id 就传 account,工具内部换算") + .next("permission.user.list", json!({}), "列出用户拿 id")); + } + + // 解析用户(id 优先) + let user_rows = if !user_id.is_empty() { + let uid = user_id.clone(); + self.state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_account,'') AS \"account\", \ + COALESCE(f_is_administrator, 0) AS \"isAdmin\" \ + FROM base_user WHERE f_id = $1 AND f_delete_mark = 0 LIMIT 1", + &[&uid], + ) + .await + .map_err(db_err)? + } else { + let acc = account.clone(); + self.state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_account,'') AS \"account\", \ + COALESCE(f_is_administrator, 0) AS \"isAdmin\" \ + FROM base_user WHERE f_account = $1 AND f_delete_mark = 0 LIMIT 1", + &[&acc], + ) + .await + .map_err(db_err)? + }; + let Some(urow) = user_rows.first() else { + return Err(ToolError::new( + "USER_NOT_FOUND", + format!( + "用户不存在: {}", + if user_id.is_empty() { &account } else { &user_id } + ), + ) + .field(if user_id.is_empty() { "account" } else { "userId" }) + .next("permission.user.list", json!({}), "列出用户确认账号")); + }; + let uid = urow["id"].as_str().unwrap_or("").to_string(); + let uaccount = urow["account"].as_str().unwrap_or("").to_string(); + let is_admin = urow["isAdmin"].as_i64().unwrap_or(0) == 1; + + let sys_code = args + .get("systemEnCode") + .and_then(Value::as_str) + .unwrap_or("mainSystem") + .to_string(); + let system_id = self.system_id_of(&sys_code).await?; + let with_detail = args + .get("withMenuDetail") + .and_then(Value::as_bool) + .unwrap_or(false); + + // ---- 四源各自收集(保留来源,才能回答「这条权限从哪来」)---- + let direct = self.authorized_modules("user", &uid).await?; + + let role_ids: Vec = { + let u = uid.clone(); + self.state + .db + .query_json_params( + "SELECT f_role_id AS \"roleId\" FROM base_role_relation \ + WHERE f_object_type = 'user' AND f_object_id = $1", + &[&u], + ) + .await + .map_err(db_err)? + .iter() + .filter_map(|r| r["roleId"].as_str().map(str::to_string)) + .filter(|s| !s.is_empty()) + .collect() + }; + let mut from_roles: Vec = Vec::new(); + for rid in &role_ids { + from_roles.extend(self.authorized_modules("role", rid).await?); + } + + let relation_ids = |object_type: &'static str| { + let u = uid.clone(); + let ot = object_type.to_string(); + let db = self.state.db.clone(); + async move { + db.query_json_params( + "SELECT f_object_id AS \"objectId\" FROM base_user_relation \ + WHERE f_user_id = $1 AND f_object_type = $2", + &[&u, &ot], + ) + .await + .map(|rows| { + rows.iter() + .filter_map(|r| r["objectId"].as_str().map(str::to_string)) + .filter(|s| !s.is_empty()) + .collect::>() + }) + } + }; + + let organize_ids: Vec = relation_ids("organize").await.map_err(db_err)?; + let mut from_orgs: Vec = Vec::new(); + for oid in &organize_ids { + from_orgs.extend(self.authorized_modules("organize", oid).await?); + } + + let position_ids: Vec = relation_ids("position").await.map_err(db_err)?; + let mut from_positions: Vec = Vec::new(); + for pid in &position_ids { + from_positions.extend(self.authorized_modules("position", pid).await?); + } + + // ---- 并集(去重)---- + use std::collections::BTreeSet; + let mut union: BTreeSet = BTreeSet::new(); + for group in [&direct, &from_roles, &from_orgs, &from_positions] { + union.extend(group.iter().cloned()); + } + + // ---- 当前应用内的菜单(按 system_id 过滤 + 未软删)---- + let sys = system_id.clone(); + let sys_menus = self + .state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_full_name,'') AS \"fullName\", \ + COALESCE(f_url_address,'') AS \"urlAddress\", \ + COALESCE(f_en_code,'') AS \"enCode\" \ + FROM base_module WHERE f_system_id = $1 AND f_delete_mark = 0", + &[&sys], + ) + .await + .map_err(db_err)?; + + let sys_ids: BTreeSet = sys_menus + .iter() + .filter_map(|r| r["id"].as_str().map(str::to_string)) + .collect(); + + if is_admin { + // 管理员短路:守卫直接放行,不看授权表。 + let mut menus: Vec = sys_menus; + if !with_detail { + menus = menus + .iter() + .map(|m| json!(m["id"].as_str().unwrap_or(""))) + .collect(); + } + return Ok(json!({ + "userId": uid, + "account": uaccount, + "isAdmin": true, + "systemId": system_id, + "mode": "admin-bypass", + "visible": { "count": sys_ids.len(), "menus": menus }, + "note": "管理员短路:守卫在第一条判据就返回 true,与 base_authorize 无关", + })); + } + + let visible_ids: BTreeSet = union.intersection(&sys_ids).cloned().collect(); + + let visible_menus: Vec = if with_detail { + sys_menus + .iter() + .filter(|m| { + m["id"] + .as_str() + .is_some_and(|id| visible_ids.contains(id)) + }) + .cloned() + .collect() + } else { + visible_ids.iter().map(|id| json!(id)).collect() + }; + + Ok(json!({ + "userId": uid, + "account": uaccount, + "isAdmin": false, + "systemId": system_id, + "sources": { + "direct": { "objectIds": [], "menuIds": direct }, + "role": { "objectIds": role_ids, "menuIds": dedup(&from_roles) }, + "organize": { "objectIds": organize_ids, "menuIds": dedup(&from_orgs) }, + "position": { "objectIds": position_ids, "menuIds": dedup(&from_positions) }, + }, + "fourSource": { "count": union.len(), "menuIds": union.iter().cloned().collect::>() }, + "visible": { "count": visible_ids.len(), "menus": visible_menus }, + "explain": "fourSource 是四源并集(授权表不带应用维度);visible 再与当前应用的菜单求交。\ + 两者不一致说明有授权指向了别的应用的菜单(或菜单已删)。", + })) + } + + /// `permission.user.create` —— 建普通用户(可同时绑角色)。 + /// + /// 🔴 存在的唯一理由:**验证授权闭环必须有一个非管理员账号**。 + /// 管理员走 `is_admin` 短路,永远看得见,用 admin 测菜单可见性等于没测。 + /// + /// 🔴 刻意不开放建管理员:`isAdministrator` 被硬编码为 0, + /// 入参只接受 false。让 AI 顺手造超管是难以回收的权限风险。 + async fn user_create(&self, args: &Value) -> Result { + let account = args + .get("account") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + if account.is_empty() { + return Err(ToolError::new("MISSING_ARG", "account 不能为空").field("account")); + } + if account.len() > 50 + || !account + .chars() + .next() + .is_some_and(|c| c.is_ascii_alphabetic()) + || !account + .chars() + .all(|c| c.is_ascii_alphanumeric() || c == '_') + { + return Err(ToolError::new( + "BAD_ACCOUNT", + format!("account 只能字母开头 + 字母数字下划线,且 ≤50 字符: {account}"), + ) + .field("account") + .hint("如 zhangsan、li_si01")); + } + + let real_name = args + .get("realName") + .and_then(Value::as_str) + .unwrap_or("") + .trim() + .to_string(); + if real_name.is_empty() { + return Err(ToolError::new("MISSING_ARG", "realName 不能为空").field("realName")); + } + + let password = args + .get("password") + .and_then(Value::as_str) + .unwrap_or("") + .to_string(); + if password.len() < 6 { + return Err(ToolError::new("BAD_PASSWORD", "password 至少 6 位") + .field("password") + .hint("传**明文**,工具内部算 md5 存库;传 md5 会导致登录永远失败")); + } + + // 🔴 软删的账号也算占用:否则「删了重建」会让历史授权指向新 id, + // 出现「新建的人莫名其妙有一堆权限」。 + let dup = self + .state + .db + .query_json_params( + "SELECT f_id AS \"id\", COALESCE(f_delete_mark,0) AS \"deleted\" \ + FROM base_user WHERE f_account = $1 LIMIT 1", + &[&account], + ) + .await + .map_err(db_err)?; + if let Some(row) = dup.first() { + let deleted = row["deleted"].as_i64().unwrap_or(0) == 1; + return Err(ToolError::new( + "ACCOUNT_EXISTS", + format!( + "账号已存在{}: {account}", + if deleted { "(已软删,仍占用)" } else { "" } + ), + ) + .field("account") + .hint(if deleted { + "软删的账号仍占用编码;换一个账号,或在库里恢复原账号" + } else { + "换一个账号" + }) + .next("permission.user.list", json!({"keyword": account}), "先确认是不是同一个人")); + } + + // 角色必须存在(绑到不存在的角色 = 一条永远不生效的关系行) + let role_ids: Vec = args + .get("roleIds") + .and_then(Value::as_array) + .map(|a| { + a.iter() + .filter_map(Value::as_str) + .map(|s| s.trim().to_string()) + .filter(|s| !s.is_empty()) + .collect() + }) + .unwrap_or_default(); + for rid in &role_ids { + let r = self + .state + .db + .query_json_params( + "SELECT f_id AS \"id\" FROM base_role WHERE f_id = $1 AND f_delete_mark = 0 LIMIT 1", + &[rid], + ) + .await + .map_err(db_err)?; + if r.is_empty() { + return Err(ToolError::new( + "ROLE_NOT_FOUND", + format!("角色不存在: {rid}"), + ) + .field("roleIds") + .hint("roleIds 是角色主键(如 role_user),不是角色名") + .next("permission.role.list", json!({}), "列出角色拿真实 id")); + } + } + + let gender = args + .get("gender") + .and_then(Value::as_str) + .unwrap_or("unknown") + .to_string(); + let mobile = args + .get("mobilePhone") + .and_then(Value::as_str) + .map(str::to_string); + let email = args + .get("email") + .and_then(Value::as_str) + .map(str::to_string); + + let id = crate::platform::ids::new_uuid(); + let pwd_md5 = crate::platform::cipher::md5_hex(&password); + + let vals: Vec> = vec![ + Some(id.clone()), + Some("0".to_string()), // f_tenant_id + Some(account.clone()), + Some(real_name.clone()), + Some(gender), + mobile, + email, + Some(pwd_md5), + Some("0".to_string()), // f_is_administrator —— 硬编码,不开放 + Some("1".to_string()), // f_enabled_mark + Some("0".to_string()), // f_delete_mark + Some("0".to_string()), // f_sort_code + ]; + let refs: Vec<&(dyn ToSql + Sync)> = + vals.iter().map(|v| v as &(dyn ToSql + Sync)).collect(); + + self.state + .db + .exec_params( + "INSERT INTO base_user \ + (f_id, f_tenant_id, f_account, f_real_name, f_gender, f_mobile_phone, f_email, \ + f_password, f_is_administrator, f_enabled_mark, f_delete_mark, f_sort_code, \ + f_creator_time) \ + VALUES ($1::text, $2::text, $3::text, $4::text, $5::text, $6::text, $7::text, \ + $8::text, $9::text::integer, $10::text::integer, $11::text::integer, \ + $12::text::bigint, now())", + &refs, + ) + .await + .map_err(db_err)?; + + // 绑角色(base_role_relation:用户标识在 f_object_id,不在 f_user_id) + for rid in &role_ids { + let rel_id = crate::platform::ids::new_uuid(); + let rvals: Vec> = vec![ + Some(rel_id), + Some("0".to_string()), // f_tenant_id + Some(rid.clone()), // f_role_id + Some("user".to_string()), // f_object_type + Some(id.clone()), // f_object_id + Some("0".to_string()), // f_sort_code + Some("0".to_string()), // f_delete_mark + ]; + let rrefs: Vec<&(dyn ToSql + Sync)> = + rvals.iter().map(|v| v as &(dyn ToSql + Sync)).collect(); + self.state + .db + .exec_params( + "INSERT INTO base_role_relation \ + (f_id, f_tenant_id, f_role_id, f_object_type, f_object_id, \ + f_sort_code, f_delete_mark, f_creator_time) \ + VALUES ($1::text, $2::text, $3::text, $4::text, $5::text, \ + $6::text::bigint, $7::text::integer, now())", + &rrefs, + ) + .await + .map_err(db_err)?; + } + + Ok(json!({ + "id": id, + "account": account, + "realName": real_name, + "isAdministrator": false, + "roleIds": role_ids, + "note": "口令已转 md5 存库,明文不落地。用 non-admin 账号验证菜单可见性才有意义。", + "next": "用 permission.effective({account}) 看它实际能访问哪些菜单", + })) + } +} + +/// 去重并保持稳定顺序(BTreeSet 排序,避免每次调用结果顺序漂移)。 +fn dedup(items: &[String]) -> Vec { + let set: std::collections::BTreeSet<&String> = items.iter().collect(); + set.into_iter().cloned().collect() } /// 把 pglite 错误转成结构化的工具错误(AI 能看懂的那种)。 @@ -1132,6 +1881,12 @@ impl PlatformAdapter for NativeAdapter { "menu.delete" => self.menu_delete(&args).await, "dict.type.create" => self.dict_type_create(&args).await, + // ------------------------------------------------ 授权(第四批) + "permission.authorize.grant" => self.authorize_grant(&args).await, + "permission.authorize.revoke" => self.authorize_revoke(&args).await, + "permission.effective" => self.permission_effective(&args).await, + "permission.user.create" => self.user_create(&args).await, + other => Err(ToolError::new( "OP_NOT_IMPLEMENTED", format!("原生适配器还没实现 op: {other}"),