From b1875ccbca3ca6ab4d3f11e32e8c72bf7a30022e Mon Sep 17 00:00:00 2001 From: admin Date: Mon, 2 Nov 2026 23:54:50 +0800 Subject: [PATCH] =?UTF-8?q?feat(mcp):=20=E8=A1=A5=203=20=E4=B8=AA=E7=9B=B4?= =?UTF-8?q?=E8=B0=83=E5=B7=A5=E5=85=B7=EF=BC=8C=E5=B7=A5=E5=85=B7=E9=9D=A2?= =?UTF-8?q?=E5=88=B0=2052?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - permission.organize.tree(机构平铺列表,建用户前取 organizeId) - form.selector(挂菜单/绑流程选功能) - ops.db.stats(关键表行数 + 库体积,快速判断空库/错库) - 同步 docs/mcp.md / PLAN / HANDOFF 的 52 个口径;全量测试与八道静态闸门全绿 --- HANDOFF.md | 8 ++-- PLAN.md | 2 +- crates/sspf-mcp/src/tools/admin.rs | 31 ++++++++++++++ crates/sspf-mcp/src/tools/form.rs | 41 +++++++++++++++++++ crates/sspf-mcp/src/tools/mod.rs | 9 ++-- crates/sspf-mcp/src/tools/ops.rs | 31 +++++++++++++- docs/mcp.md | 7 +++- src/backend/src/mcp_adapter.rs | 5 +++ src/backend/src/mcp_compat.rs | 66 ++++++++++++++++++++++++++++++ src/backend/tests/mcp_tools_it.rs | 9 ++++ 10 files changed, 198 insertions(+), 11 deletions(-) diff --git a/HANDOFF.md b/HANDOFF.md index 1ebee6f..0491fc9 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -30,18 +30,18 @@ --- -## 0-0-bis. 2026-11-02 23:40 MCP 扩面:26 → 49 个业务工具 +## 0-0-bis. 2026-11-02 23:40 MCP 扩面:26 → 52 个业务工具 参考 dacli 的命令面,把 MCP 从「26 个工具」扩到 **49 个**(4 元工具不变,仍是分层加载): | 域 | 新增 | |---|---| | workflow | `template.list/info/create/update/delete/selector` + `task.list`(7) | -| form | `form.create / update / delete`(写定义;**release 本仓未支持,刻意不注册**) | -| ops | `ops.health / logs / online / schedule.list`(4) | +| form | `form.create / update / delete` + `form.selector`(**release 本仓未支持,刻意不注册**) | +| ops | `ops.health / logs / online / schedule.list / db.stats`(5) | | dict | `type.update / type.delete / data.create`(3) | | menu | `menu.info / menu.update`(2) | -| permission | `role.create / role.delete / user.delete`(3) | +| permission | `role.create / role.delete / user.delete` + `organize.tree`(4) | | context | `context.app.list`(1) | 🔴 **实现方式**:不重写 SQL,`src/backend/src/mcp_compat.rs` **进程内直调契约面 handler** diff --git a/PLAN.md b/PLAN.md index 4bc043e..0310a39 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`** | | 低代码元数据引擎 | ✅ **P2-b 完成**:解析 + 校验 + 建表 + 动态 CRUD(6 个工具) | visualdev 同构 + 动态 CRUD + 发布 | 读 release / 单据号 / 乐观锁 → P2-c | | 业务包格式 | 🟡 `pack.toml` 已定稿、`packs/asset` 已有样板 | 导入导出工具 | **P3** | -| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 49 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model / verify / 发布) | P1 收尾 | +| MCP 工具面 | 🟡 **P1 主体完成**:4 元工具 + registry + 分层加载 + 双适配器 + 52 个业务工具 + 3 个流程模板 | 约 55 个业务工具(补 model / verify / 发布) | P1 收尾 | | 影子对账 | ❌ 无 | 语料库 + 归一化比对 | **全新,P4** | | 部署形态 | 🟡 pglite 单二进制 | 单二进制 + 可选真实 PG | P5 收口 | diff --git a/crates/sspf-mcp/src/tools/admin.rs b/crates/sspf-mcp/src/tools/admin.rs index e15af34..d7de14d 100644 --- a/crates/sspf-mcp/src/tools/admin.rs +++ b/crates/sspf-mcp/src/tools/admin.rs @@ -381,4 +381,35 @@ pub const ADMIN_TOOLS: &[ToolDef] = &[ ROLE_DELETE, USER_DELETE, APP_LIST, + ORGANIZE_TREE, ]; + +// ================================================================ permission.organize.tree + +passthrough!(organize_tree_handler, "permission.organize.tree"); + +pub const ORGANIZE_TREE: ToolDef = ToolDef { + id: "permission.organize.tree", + category: Category::Permission, + title: "组织机构树", + one_liner: "列组织机构(平铺,前端自己拼树)", + input_schema: r#"{"type":"object","properties":{},"additionalProperties":false}"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["建用户前确认 organizeId", "排查「组织管理页空白」"], + when_not_to_use: &["要改组织(本工具只读;MCP 暂未开放组织写)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "把返回当树直接渲染", + right: "它是**平铺列表**(含 parentId),需要按 parentId 自己组树", + rationale: "官方 `/Organize` 返回 ListVO;树是前端用 parentId 拼的。\ + 直接当树用会把所有节点拍平。", + }], + examples: &[Example { + args: r#"{}"#, + note: "无参数", + }], + }, + handler: organize_tree_handler, +}; diff --git a/crates/sspf-mcp/src/tools/form.rs b/crates/sspf-mcp/src/tools/form.rs index efd3135..735d614 100644 --- a/crates/sspf-mcp/src/tools/form.rs +++ b/crates/sspf-mcp/src/tools/form.rs @@ -362,3 +362,44 @@ pub const FORM_DELETE: ToolDef = ToolDef { }, handler: delete_handler, }; + +// ================================================================ form.selector + +passthrough!(selector_handler, "form.selector"); + +pub const FORM_SELECTOR: ToolDef = ToolDef { + id: "form.selector", + category: Category::Form, + title: "功能下拉", + one_liner: "给菜单/流程选功能用(已发布优先)", + input_schema: r#"{ + "type": "object", + "properties": { + "keyword": { "type": "string" }, + "type": { "type": "integer", "description": "1=在线开发 2=流程表单" }, + "isRelease": { "type": "integer", "enum": [0, 1], "description": "1=只看已发布" }, + "webType": { "type": "integer" }, + "currentPage": { "type": "integer", "default": 1 }, + "pageSize": { "type": "integer", "default": 20 } + }, + "additionalProperties": false + }"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["menu.create 挂表单前拿 id", "给流程起始节点挑表单"], + when_not_to_use: &["要看表单结构(用 form.describe)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P1, + wrong: "选到 state=0 的草稿去挂菜单", + right: "传 `isRelease=1` 只看已发布(但本仓 release 未支持 ⇒ 通常为空)", + rationale: "本仓没有真发布动作,`base_visual_release` 不会被写入;\ + 所以菜单挂表单时要用 dev 的 id,而不是等发布。", + }], + examples: &[Example { + args: r#"{"type":1,"pageSize":10}"#, + note: "列在线开发功能", + }], + }, + handler: selector_handler, +}; diff --git a/crates/sspf-mcp/src/tools/mod.rs b/crates/sspf-mcp/src/tools/mod.rs index 8fca151..cf6255e 100644 --- a/crates/sspf-mcp/src/tools/mod.rs +++ b/crates/sspf-mcp/src/tools/mod.rs @@ -196,9 +196,9 @@ const MENU_TREE_TOOL: ToolDef = ToolDef { /// | P2-a 低代码读 | 3 | form.list / describe / validate | /// | P2-b 低代码写 | 4 | schema.table.create + data.record.insert / update / delete | /// | P2-c 表单定义 | 3 | form.create / update / delete(release 本仓未支持,不注册) | -/// | P3 dacli 对齐 | 24 | workflow ×7 / ops ×4 / dict+menu+role+user+app ×9 | +/// | P3 dacli 对齐 | 26 | workflow ×7 / ops ×5 / form+dict+menu+role+user+app ×14 | /// -/// 合计 **49 个**(`PLAN.md` §6.3 目标约 55,剩 model / verify / 其它 release 工具)。 +/// 合计 **52 个**(`PLAN.md` §6.3 目标约 55,剩 model / verify / 其它 release 工具)。 /// /// 🔴 改这个数组就要同步改这一行数字 —— `tool_count_matches_doc` 会钉住它。 pub static ALL_TOOLS: &[ToolDef] = &[ @@ -238,6 +238,7 @@ pub static ALL_TOOLS: &[ToolDef] = &[ form::FORM_CREATE, form::FORM_UPDATE, form::FORM_DELETE, + form::FORM_SELECTOR, // —— 第八批(P3):流程元数据 / 运维 / 管理面(对齐 dacli 命令面)—— workflow::TEMPLATE_LIST, workflow::TEMPLATE_INFO, @@ -250,6 +251,7 @@ pub static ALL_TOOLS: &[ToolDef] = &[ ops::LOGS, ops::ONLINE, ops::SCHEDULE_LIST, + ops::DB_STATS, admin::DICT_TYPE_UPDATE, admin::DICT_TYPE_DELETE, admin::DICT_DATA_CREATE, @@ -259,6 +261,7 @@ pub static ALL_TOOLS: &[ToolDef] = &[ admin::ROLE_DELETE, admin::USER_DELETE, admin::APP_LIST, + admin::ORGANIZE_TREE, ]; #[cfg(test)] @@ -300,7 +303,7 @@ mod tests { fn tool_count_matches_doc() { assert_eq!( ALL_TOOLS.len(), - 49, + 52, "ALL_TOOLS 数量变了:同步改 `ALL_TOOLS` 的文档表、PLAN.md 与 docs/mcp.md" ); } diff --git a/crates/sspf-mcp/src/tools/ops.rs b/crates/sspf-mcp/src/tools/ops.rs index 6f7af77..2fb49a2 100644 --- a/crates/sspf-mcp/src/tools/ops.rs +++ b/crates/sspf-mcp/src/tools/ops.rs @@ -153,4 +153,33 @@ pub const SCHEDULE_LIST: ToolDef = ToolDef { handler: schedule_handler, }; -pub const OPS_TOOLS: &[ToolDef] = &[HEALTH, LOGS, ONLINE, SCHEDULE_LIST]; +pub const OPS_TOOLS: &[ToolDef] = &[HEALTH, LOGS, ONLINE, SCHEDULE_LIST, DB_STATS]; + +// ================================================================ ops.db.stats + +passthrough!(db_stats_handler, "ops.db.stats"); + +pub const DB_STATS: ToolDef = ToolDef { + id: "ops.db.stats", + category: Category::Ops, + title: "库概览", + one_liner: "关键表行数 + 数据库体积(判断空库/有数据)", + input_schema: r#"{"type":"object","properties":{},"additionalProperties":false}"#, + annotations: Annotations::READ, + hints: Hints { + when_to_use: &["怀疑「数据没落库」时先看行数", "判断是不是空库/错库"], + when_not_to_use: &["要看具体数据(用 data.query)"], + preconditions: &[], + pitfalls: &[Pitfall { + severity: Severity::P2, + wrong: "把行数当业务指标", + right: "它只统计 7 张关键表;业务表数据用 data.count", + rationale: "这里是为了快速判断环境,不是报表。", + }], + examples: &[Example { + args: r#"{}"#, + note: "无参数", + }], + }, + handler: db_stats_handler, +}; diff --git a/docs/mcp.md b/docs/mcp.md index 724eeff..c36ae13 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -80,7 +80,7 @@ sspf_context # 1. 先确认环境 → 失败则读 error.hints / next_actions 自纠 ``` -### 当前业务工具(49 个) +### 当前业务工具(52 个) | 域 | 工具 | 一句话 | 写 | |---|---|---|---| @@ -98,6 +98,7 @@ sspf_context # 1. 先确认环境 | permission | `permission.user.list` | 用户(**不含口令字段**) | | | permission | `permission.user.create` | 建普通用户(可同时绑角色) | ✅ | | permission | `permission.user.delete` | 软删用户(管理员不可删) | ✅ | +| permission | `permission.organize.tree` | 组织机构(平铺,含 parentId) | | | permission | `permission.role.list` | 角色 | | | permission | `permission.role.create` | 建角色(enCode 全平台唯一) | ✅ | | permission | `permission.role.delete` | 软删角色(系统角色不可删) | ✅ | @@ -122,6 +123,7 @@ sspf_context # 1. 先确认环境 | form | `form.create` | 建表单定义(草稿态;`formData` 可传对象) | ✅ | | form | `form.update` | 改表单定义(只 SET 传了的键) | ✅ | | form | `form.delete` | 软删功能(菜单需另行清理) | ✅ | +| form | `form.selector` | 功能下拉(挂菜单/绑流程用) | | | workflow | `workflow.template.list` | 流程模板列表(元数据) | | | workflow | `workflow.template.info` | 模板详情 | | | workflow | `workflow.template.create` | 建模板(只写元数据) | ✅ | @@ -133,8 +135,9 @@ sspf_context # 1. 先确认环境 | ops | `ops.logs` | 按分类查系统日志 | | | ops | `ops.online` | 按账号聚合的在线会话(不含 token) | | | ops | `ops.schedule.list` | 定时任务定义(不跑调度) | | +| ops | `ops.db.stats` | 关键表行数 + 库体积 | | -**P3 这批(23 个)怎么实现的**:不重写 SQL,而是**进程内直调契约面 handler** +**P3 这批(26 个)怎么实现的**:不重写 SQL,而是**进程内直调契约面 handler** (`src/backend/src/mcp_compat.rs`),与 HTTP 路由注册的是同一个函数 ⇒ 校验、默认值、 软删语义只有一份。代价是 MCP 适配器必须构造管理员请求头(`SessionStore::issue` 一个 `admin` 会话),所以**它只适用于本地开发**;对外暴露要走 `BaselineHttpAdapter` 带真实 token。 diff --git a/src/backend/src/mcp_adapter.rs b/src/backend/src/mcp_adapter.rs index 6ceb704..f205246 100644 --- a/src/backend/src/mcp_adapter.rs +++ b/src/backend/src/mcp_adapter.rs @@ -2587,6 +2587,11 @@ impl PlatformAdapter for NativeAdapter { // ------------------------------------------------ 应用 / 运维 "context.app.list" => crate::mcp_compat::app_list(&self.state, args).await, + "permission.organize.tree" => { + crate::mcp_compat::organize_tree(&self.state, args).await + } + "form.selector" => crate::mcp_compat::form_selector(&self.state, args).await, + "ops.db.stats" => crate::mcp_compat::ops_db_stats(&self.state, args).await, "ops.health" => crate::mcp_compat::ops_health(&self.state, args).await, "ops.logs" => crate::mcp_compat::ops_logs(&self.state, args).await, "ops.online" => crate::mcp_compat::ops_online(&self.state, args).await, diff --git a/src/backend/src/mcp_compat.rs b/src/backend/src/mcp_compat.rs index f5d0b4d..dbaeba8 100644 --- a/src/backend/src/mcp_compat.rs +++ b/src/backend/src/mcp_compat.rs @@ -563,3 +563,69 @@ pub async fn ops_online(state: &AppState, _args: Value) -> Result>(), })) } + +// ================================================================ 机构树 / 表单下拉 / 库概览 + +pub async fn organize_tree(state: &AppState, args: Value) -> Result { + let r = crate::platform::compat::permission::organize_list( + State(state.clone()), + headers(state, &args).await, + ) + .await; + out("permission.organize.tree", r) +} + +pub async fn form_selector(state: &AppState, args: Value) -> Result { + let raw = RawQuery(Some(qs( + &args, + &[ + "keyword", + "type", + "isRelease", + "webType", + "currentPage", + "pageSize", + ], + ))); + let r = crate::platform::compat::online_dev::visual_dev_selector( + State(state.clone()), + headers(state, &args).await, + raw, + ) + .await; + out("form.selector", r) +} + +/// 库概览:关键表行数 + 数据库体积(排障时判断「空库 / 有数据 / 库太大」)。 +pub async fn ops_db_stats(state: &AppState, _args: Value) -> Result { + let mut counts = Map::new(); + for (label, table) in [ + ("users", "base_user"), + ("menus", "base_module"), + ("forms", "base_visual_dev"), + ("releasedForms", "base_visual_release"), + ("roles", "base_role"), + ("logs", "base_sys_log"), + ("workflowTemplates", "workflow_template"), + ] { + let n = state + .db + .scalar_text(&format!("SELECT count(*)::text FROM {table}")) + .await + .ok() + .flatten() + .and_then(|s| s.parse::().ok()) + .unwrap_or(-1); + counts.insert(label.to_string(), json!(n)); + } + let size = state + .db + .scalar_text("SELECT pg_database_size(current_database())::text") + .await + .ok() + .flatten(); + Ok(json!({ + "counts": counts, + "databaseBytes": size, + })) +} diff --git a/src/backend/tests/mcp_tools_it.rs b/src/backend/tests/mcp_tools_it.rs index abec785..7b1a251 100644 --- a/src/backend/tests/mcp_tools_it.rs +++ b/src/backend/tests/mcp_tools_it.rs @@ -69,6 +69,12 @@ async fn ops_and_app_tools_work() { assert!(online["users"].is_array(), "{online}"); let logs = call(&a, "ops.logs", json!({"category":1,"pageSize":1})).await; assert!(logs.is_ok(), "登录日志查询失败: {logs:?}"); + + let stats = call(&a, "ops.db.stats", json!({})).await.expect("ops.db.stats 失败"); + assert!(stats["counts"]["users"].as_i64().unwrap_or(0) >= 1, "{stats}"); + + let orgs = call(&a, "permission.organize.tree", json!({})).await.expect("组织树失败"); + assert!(orgs["list"].is_array(), "组织必须是 ListVO: {orgs}"); } /// 流程模板 CRUD 闭环(元数据面)。 @@ -193,6 +199,9 @@ async fn form_create_update_delete_roundtrip() { let listed = call(&a, "form.list", json!({"keyword":"MCP验证表单"})).await.expect("列表单失败"); assert!(listed["count"].as_i64().unwrap_or(0) >= 1, "{listed}"); + let sel = call(&a, "form.selector", json!({"type":1,"pageSize":5})).await.expect("功能下拉失败"); + assert!(sel.is_object(), "form.selector 必须返回对象: {sel}"); + call(&a, "form.update", json!({"id":id,"description":"改过"})) .await .expect("改表单失败");