Commit 27f44475439630cf6968a05b247871c5a7e4b659
1 parent
38321fa4
docs: legacy 64-tool capability inventory (migration coverage baseline)
Showing
1 changed file
with
51 additions
and
0 deletions
docs/legacy-tool-inventory.md
0 → 100644
| 1 | +# 旧 64 AI 工具能力盘点（迁移覆盖基线） | |
| 2 | + | |
| 3 | +> 目的：现有 64 个元数据工具（`ai_tool`/`ai_tool_detail_params`）→ 迁到 5 个通用工具（Read/Query/KgSearch/AskUser/ProposeWrite）时，**不能丢**的业务语义清单。 | |
| 4 | +> 关键发现：**这 64 个不是"薄读"——其中 25 个是写操作，内含大量业务逻辑**（BtnCopyTo 单据流转引擎 + 报价定价引擎）。 | |
| 5 | + | |
| 6 | +## 执行机制（证据） | |
| 7 | +- `AppStartupRunner.initCache()` 载入 → `DynamicToolProvider.init()` 每行建一个 `ToolSpecification`+`ToolExecutor`（按 `sSceneId` 分桶）。 | |
| 8 | +- **LLM 面向的 executor 只收集/校验参数**，不跑业务逻辑；真正执行在用户确认后 `XlyErpService.doDynamicTool()` → `DynamicToolProvider.doDynamicTool()`。 | |
| 9 | +- **`iBizType` 是操作类型判别键**（`executeToolAfter`）：`1|4`=存储过程写；`2`=`sBizContent` 字面 SQL；`3`=HTTP（当前 0 工具用）；`doDynamicTool` 里 `4|5`=ERP 表单 API 读；`8`=NL2SQL/向量。 | |
| 10 | + | |
| 11 | +## 按操作类型分布（共 64） | |
| 12 | +| iBizType | 类型 | 数量 | 参数 | 覆盖工具 | | |
| 13 | +|---|---|---|---|---| | |
| 14 | +| 8 | read-nl2sql（NL→SQL + Milvus 向量兜底） | 33 | 0（纯 NL） | **Query (+KgSearch)** | | |
| 15 | +| 4 | read-list→确认→write-copyto（BtnCopyTo 流转） | 21 | 16 | **Query+AskUser+ProposeWrite** | | |
| 16 | +| 1 | write-proc 报价定价（bQuo） | 4 | 78 | **AskUser+ProposeWrite**（最复杂） | | |
| 17 | +| 5 | read-erpapi（表单 REST 读，可导出） | 3 | 8 | **Read/Query** | | |
| 18 | +| 1 | read-aggregate 工单成本（**配置损坏**） | 1 | 1 | Query（需先修） | | |
| 19 | +| 2 | read-fixedsql（手写 SELECT + 数据权限函数） | 1 | 0 | Query | | |
| 20 | +| 7 | chat（无执行） | 1 | 0 | —（不属 5 工具） | | |
| 21 | + | |
| 22 | +form-backed 61；3 个无业务表单（`queryWorkOrderCost` 空 `sSrcFormId`；`queryTodayTask`+`chat` 用通用 KPI 模块）。`sSrcSlaveId` 全 NULL（未用）。 | |
| 23 | + | |
| 24 | +## 覆盖映射（按新工具） | |
| 25 | +- **Query** ≈ 35（33 nl2sql + queryTodayTask + queryWorkOrderCost） | |
| 26 | +- **ProposeWrite** = 25 写（21 copyto + 4 报价），全部人在环确认 | |
| 27 | +- **AskUser** = 缺参/消歧/确认循环（type-4 选行、type-1 报价 13–25 参数） | |
| 28 | +- **Read** = 3 个表单明细读（type-5） | |
| 29 | +- **KgSearch** = 33 个 nl2sql 里内嵌的 Milvus 向量兜底（每工具一个 collection + 字段映射） | |
| 30 | + | |
| 31 | +## ⚠️ 迁移绝不能丢的语义（最重要） | |
| 32 | +1. **每表单的 NL2SQL 接地 + 表范围**（`sInputTabelName`、`sStructureMemo`）——没它 Query 既丢正确性、又丢**权限/范围边界**（33 工具）。注：安全调查发现这个范围**只在"喂模型"时生效、执行期不强制** → 新 Query 必须把它变成**强制 allowlist**。 | |
| 33 | +2. **每表单的向量 collection + 字段映射**（`sVectorfiled/sVectorjson/…`）驱动 KgSearch，以及 SQL-vs-向量的 `routeQuery` 决策。 | |
| 34 | +3. **学习到的 SQL few-shot 缓存 + 自修复循环**：`ai_global_agent_question_sql` 缓存、5 次带错重试、`ai_sql_error_history`。 | |
| 35 | +4. **BtnCopyTo 单据流转引擎（21 工具）**：源→目标表单对、`operateType` **合并 vs 分单**（一个/多个单据）、行→`sSlaveId` 解析、`Sp_Ai_AddCommonAfterNew`、`sCopyTo/sCopyToSrcId` 打开已建单据。→ 通用 ProposeWrite **必须带 源/目标表单对 + 选择模式**，不能只给一堆行。**（这正是我建的 `viw_kg_edge_flow` 提供的映射。）** | |
| 36 | +5. **报价定价引擎（4 工具）**：分组参数（产品/部件）、动态部件增删（拼音克隆）、`sDynamicParamRuleSql` 动态参数、枚举/常量/SQL 选项列表、`sParamMissMemo` 缺参提示、`Sp_Ai_AddQuoQuoAfter` 定价。→ **复杂到应单独做成一个 Skill/专用能力，别硬塞通用 ProposeWrite。** | |
| 37 | +6. **参数归一化 + 外键消歧**（`applyValues`）：名称→id 解析、"不存在"拒绝、"存在多个请选择"编号消歧、中↔英/CONST 反查、`sDefaultValue`、类型感知必填（数值 d 字段 0=空）、只校验首个必填参的怪癖、date 强制 `yyyy-MM-dd` 注入当前日期、`bConfirmAfter`。→ 映射到 **AskUser + KG 字段字典**。 | |
| 38 | +7. **ERP-API 读路径（type-5 + type-4 的读半段）**：走 ERP token、表单权限、列可见性 `bVisible`、聚合过程（AR/AP/进度）、Excel 导出。→ 直连 DB 的 Query **会绕过**这些。 | |
| 39 | +8. **数据权限**：`fun_get_jurisdiction`（queryTodayTask）、表单权限——通用 Query 必须保留。 | |
| 40 | +9. **多租户/会话上下文**（`executeToolAfter` 注入 `sUserId/sBrandsId/sSubsidiaryId/sSrcFormId/sControlName`）——每个 proc 都要。 | |
| 41 | +10. **防重复 + 确认门**：单次调用锁 `toolExecuted`、`isConfirmed`（确认/生成/全部确认）、`iActionType=1` 清记忆。 | |
| 42 | + | |
| 43 | +## 需清理的配置异常（别原样迁） | |
| 44 | +- `queryWorkOrderCost`：type 1 但 `sBizContent` 空、无表单 → 空 proc，需先查清目标数据源。 | |
| 45 | +- `queryTodayTask`+`chat`：用通用非业务表单 id。 | |
| 46 | +- `sSrcSlaveId` 全 NULL；`iBizType 3`（HTTP）定义了但 0 工具使用。 | |
| 47 | + | |
| 48 | +## 对架构的启示 | |
| 49 | +- **ProposeWrite 需分两类**：copyto（源→目标+合并/分单，靠 KG 映射）与 报价（结构化多部件填单+定价，做成 Skill）。 | |
| 50 | +- **KgSearch + KG 视图正好承接** BtnCopyTo 的源→目标映射（`viw_kg_edge_flow`）与参数消歧（`viw_kg_field_dict`）。 | |
| 51 | +- **Query 的"每表单范围"必须从"喂模型软约束"升级为"执行期强制 allowlist"**（与安全调查一致）。 | ... | ... |