docs: 添加 AI 测试参数动态表单设计文档
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -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，后续再实现
|
||||||
Reference in New Issue
Block a user