docs: 添加 AI 测试参数动态表单设计文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-23 14:56:37 +08:00
parent c8f22bb157
commit 5888816646
1 changed files with 130 additions and 0 deletions
@@ -0,0 +1,130 @@
+---
+author: 华钟民
+created_at: 2026-05-23
+purpose: AI 配置测试对话框参数动态表单化，解决测试时不知道填什么参数的问题
+---
+
+# AI 配置测试参数动态表单设计
+
+## 1. 问题背景
+
+当前测试对话框只有一个 JSON 输入框：
+- 用户不知道应该填哪些参数名
+- `defaultInputs` 在数据库中都是空的 `{}`
+- 没有参数类型提示和验证
+
+## 2. 设计方案
+
+### 2.1 参数提取（多源合并）
+
+测试对话框打开时，按以下优先级提取参数列表：
+
+| 优先级 | 来源 | 实现方式 |
+|--------|------|----------|
+| 1 | `endpoint.defaultInputs` | 解析 JSON key 作为参数名，已有值作为默认值 |
+| 2 | `endpoint.requestTemplate` | 正则提取 `{{paramName}}` 占位符 |
+| 3 | 接口类型默认值 | Dify 对话默认 `query`；Coze 工作流默认 `input` |
+| 4 | Dify `/parameters` API | 对于 Dify 对话型应用，后端调用其 API 获取真实参数定义（后续优化）|
+
+### 2.2 动态表单渲染（前端）
+
+**参数对象结构**（TypeScript）：
+```typescript
+interface TestParamField {
+  name: string        // 参数名（JSON key）
+  label: string       // 显示标签
+  type: 'string' | 'number' | 'boolean' | 'textarea'
+  value: any          // 当前值
+  defaultValue: any   // 默认值
+  required: boolean
+}
+```
+
+**对话框改造**：
+
+```vue
+<!-- 在 JSON 框上方增加动态表单区域 -->
+<el-form v-if="paramFields.length > 0" label-width="120px">
+  <el-form-item v-for="field in paramFields" :key="field.name" :label="field.label">
+    <el-input v-if="field.type === 'string'" v-model="field.value" />
+    <el-input v-if="field.type === 'textarea'" v-model="field.value" type="textarea" :rows="3" />
+    <el-input-number v-if="field.type === 'number'" v-model="field.value" />
+    <el-switch v-if="field.type === 'boolean'" v-model="field.value" />
+  </el-form-item>
+</el-form>
+
+<!-- JSON 编辑区域折叠为「高级编辑」-->
+<el-collapse>
+  <el-collapse-item title="高级编辑（JSON）">
+    <el-input v-model="testInputsJson" type="textarea" :rows="6" />
+  </el-collapse-item>
+</el-collapse>
+```
+
+**双向绑定逻辑**：
+- 表单值变更 → 自动更新 `testInputsJson`
+- JSON 文本框变更 → 尝试解析并回填到表单（仅当 JSON 结构与表单字段匹配时）
+
+### 2.3 接口编辑页面增强
+
+在「新增/编辑接口工作流」对话框中增加「参数定义」区域：
+
+```vue
+<el-form-item label="参数定义">
+  <div v-for="(param, index) in paramDefinitions" :key="index" class="param-row">
+    <el-input v-model="param.name" placeholder="参数名" style="width: 120px" />
+    <el-input v-model="param.label" placeholder="显示标签" style="width: 140px" />
+    <el-select v-model="param.type" style="width: 100px">
+      <el-option label="文本" value="string" />
+      <el-option label="多行文本" value="textarea" />
+      <el-option label="数字" value="number" />
+      <el-option label="开关" value="boolean" />
+    </el-select>
+    <el-input v-model="param.defaultValue" placeholder="默认值" style="width: 120px" />
+    <el-checkbox v-model="param.required">必填</el-checkbox>
+    <el-button link type="danger" @click="removeParam(index)">删除</el-button>
+  </div>
+  <el-button link type="primary" @click="addParam">+ 添加参数</el-button>
+</el-form-item>
+```
+
+**参数定义保存格式**（存到 `defaultInputs` 字段）：
+```json
+{
+  "prompt": {
+    "_meta": { "label": "提示词", "type": "textarea", "required": true },
+    "value": "请用一句中文回复测试成功。"
+  },
+  "style": {
+    "_meta": { "label": "风格", "type": "string", "required": false },
+    "value": "幽默"
+  }
+}
+```
+
+当后端 adapter 使用 `defaultInputs` 时，需要兼容这种格式：如果 value 是普通值，直接使用；如果 value 是对象且包含 `_meta`，提取 `.value`。
+
+### 2.4 后端兼容性处理
+
+`AiTemplateRenderer.mergeInputs()` 需要兼容新的 `defaultInputs` 格式：
+
+```java
+// 伪代码：mergeInputs 中处理 _meta 格式
+if (value instanceof JSONObject && ((JSONObject) value).containsKey("_meta")) {
+    return ((JSONObject) value).get("value");
+}
+```
+
+## 3. 文件清单
+
+| 操作 | 文件 |
+|------|------|
+| 修改 | `web-admin/src/views/aiconfig/AiRoutingList.vue` |
+| 修改 | `web-admin/src/types/aiconfig.ts` |
+| 修改 | `backend-single/src/main/java/com/emotion/service/ai/AiTemplateRenderer.java` |
+
+## 4. 风险
+
+- `defaultInputs` 格式变更需要确保向后兼容（旧的纯 JSON `{}` 仍然可用）
+- 动态表单和 JSON 文本框的双向绑定需要处理格式不匹配的情况
+- Dify `/parameters` API 调用需要有效的 API Key，后续再实现