Files

T

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

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-23 14:56:37 +08:00

4.6 KiB

Raw Blame History

author, created_at, purpose

author	created_at	purpose
华钟民	2026-05-23	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）：

interface TestParamField {
  name: string        // 参数名（JSON key）
  label: string       // 显示标签
  type: 'string' | 'number' | 'boolean' | 'textarea'
  value: any          // 当前值
  defaultValue: any   // 默认值
  required: boolean
}

对话框改造：

<!-- 在 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 接口编辑页面增强

在「新增/编辑接口工作流」对话框中增加「参数定义」区域：

<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 字段）：

{
  "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 格式：

// 伪代码：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，后续再实现

4.6 KiB Raw Blame History Unescape Escape