AI应用表(dou_ai) | DouPHP 开发手册 | 文档中心 | DouPHP企业建站系统

AI应用表(dou_ai)

简介

本设计文档围绕 DouPHP 的 AI 创作应用表 dou_ai，系统化说明其表结构设计、字段约束、配置契约、关联模型与提示词机制、公开与推荐状态、排序与生命周期管理，以及面向 AI 功能开发者的配置与使用指南。文档同时覆盖“后台应用形态”list_batch/form_create/field_assist 三类挂载方式，并结合现有代码实现给出可落地的落地方案。

项目结构

AI 应用相关的数据定义与业务逻辑分布在以下位置：

数据库表定义：系统表结构 SQL 与模块备份 SQL
数据模型：AiApplication 模型类
控制器与服务：AiController、ApplicationService、AiToolbarBuilder
语言与提示词：后台语言包 ai.lang.php

graph TB
A["数据库: dou_ai"] --> B["模型: AiApplication"]
B --> C["服务: ApplicationService"]
C --> D["控制器: AiController"]
C --> E["工具: AiToolbarBuilder"]
D --> F["前端视图: ai.htm"]
E --> G["前端脚本: ai.assist.js"]

核心组件

数据表 dou_ai：承载 AI 应用的元数据、能力类型、挂载模块、字段约束、输出契约、配置 JSON、提示词、状态与排序等。
模型 AiApplication：封装字段写入策略、筛选作用域、默认排序等。
服务 ApplicationService：负责列表构建、新增/编辑/删除、表单数据组装、策略校验（placement/task_type/model）、模块字段下发。
控制器 AiController：路由到页面与保存操作，组织视图数据。
工具 AiToolbarBuilder：根据已挂载的应用生成前端页面配置 JSON，驱动列表/表单页的 AI 按钮与弹窗行为。

架构总览

AI 应用在后台以“应用形态 + 任务形态 + 挂载模块”三维组合的方式被发现与调用：

列表页：当模块支持导入且存在 batch 应用时显示批量生成按钮。
表单页：当存在 fill 应用或全局 assist/translate 应用时显示相应按钮；banner 面板仅展示 banner 任务的图像应用。
运行时：通过 ApplicationService 组装 schema 与提示词，结合模型与密钥调用 AI 网关完成生成。

sequenceDiagram
participant Admin as "管理员"
participant Ctrl as "AiController"
participant Svc as "ApplicationService"
participant Model as "AiApplication"
participant Tool as "AiToolbarBuilder"
participant View as "ai.htm / 前端脚本"
Admin->>Ctrl : 访问列表/创建/编辑
Ctrl->>Svc : 构建列表/表单数据
Svc->>Model : 查询/写入应用记录
Svc-->>Ctrl : 返回数据
Ctrl->>View : 渲染页面
View->>Tool : 请求页面配置JSON
Tool-->>View : 返回 assist/fill/batch/translate 配置

详细组件分析

表结构与字段语义（dou_ai）

id：自增主键
name：应用名称
slug：URL标识（系统表结构中存在，用于唯一标识）
type：AI能力类型（chat/image/video/audio/code/translate/summarize/other）
placement：后台应用形态（list_batch/form_create/field_assist），在模块备份中体现为 assist/fill/batch/translate
module：挂载的内容创作模块（含 _category 变体）
field：字段约束（JSON数组），用于限定参与生成的字段集合
response_schema：输出契约（JSON Schema），用于约束AI输出结构
description：应用描述
icon/cover_image：图标与封面图
model_ids：关联的模型（JSON数组），模块备份中以 model_id 表示单模型关联
default_prompt：预设提示词
config：应用配置（JSON格式），如批量数量限制、Banner画布尺寸与对齐等
is_public：是否公开
is_featured：是否推荐
sort_order/sort：排序（系统表结构为 sort_order，模块备份为 sort）
status：启用/禁用
created_at/updated_at：时间戳

注意：系统表结构与模块备份在字段命名上略有差异（slug/type/model_ids/sort_order vs model_id/sort），实际以运行期使用的模块备份为准，但语义保持一致。

模型层 AiApplication

表名映射：ai
主键：id
类型转换：对数值型字段进行 cast
白名单写入：name/placement/task_type/module/field/model_id/default_prompt/config/sort/status
筛选作用域：按 placement、task_type、module、status 过滤
默认排序：sort ASC, id DESC
属性写入策略：
- task_type：空字符串归一化为 assist
- module：空字符串转为 null
- field：数组清洗后编码为 JSON 字符串
- config：空字符串转为 {}

服务层 ApplicationService

列表构建：按 placement/task_type/status 筛选并分页，批量加载模型名称，组装展示数据
新增/编辑：
- 默认草稿：config 为 {}，task_type 默认 assist，model_id 默认 0
- 策略校验：
  - placement 与 task_type 必须匹配
  - 所选模型需支持该 task_type
  - assist/translate 不挂载模块、不选字段；fill/batch 必须选择 module 与 field
删除：二次确认审计日志
模块字段下发：按模块名返回 fields JSON

控制器层 AiController

列表：接收 placement/task_type/status/page 参数，调用服务构建数据并渲染 ai.htm
创建/编辑：调用服务构建表单数据，回显模型分组与模块列表
保存：经表单请求校验后调用服务插入/更新
删除：二次确认后删除
模块字段：get_fields 接口返回字段集 JSON

前端集成 AiToolbarBuilder

pageConfig(module, context, banner=false)：
- list：若模块支持导入且存在 batch 应用则输出按钮
- form：若存在 fill 应用或全局 assist/translate 应用则输出；banner 面板仅展示 banner 任务的图像应用
- 返回 JSON：包含 module/context/assist/assist_image/translate/banner 等键
banner 配置：material_max、upload_max_bytes、styles 来自配置项

应用配置 JSON 与输出契约

应用配置 config：
- 通用：如批量最小/最大数量等
- Banner：canvas_size（画布宽x高）、content_width（内容宽度）、content_align（left/center/right）
输出契约 response_schema：
- 使用 JSON Schema 约束 AI 输出结构，确保下游消费稳定
字段约束 field：
- JSON 数组，声明参与生成的字段集合，由服务在运行时动态计算 schema

关联模型与提示词

关联模型：
- 系统表结构使用 model_ids（JSON数组）
- 模块备份使用 model_id（整数），0 表示系统默认模型
预设提示词 default_prompt：
- 作为模板提示词，结合 system prompts 与上下文拼装最终提示词

公开状态、推荐状态与排序

is_public：控制是否对外公开
is_featured：控制是否推荐展示
sort_order/sort：排序字段，默认按 sort ASC, id DESC 排序

生命周期管理与状态控制

创建：通过 AiController.store -> ApplicationService.insert，写入应用记录并审计
编辑：AiController.update -> ApplicationService.update，策略校验后更新
删除：AiController.destroy -> ApplicationService.delete，二次确认并审计
启用/禁用：通过 status 字段控制，列表页支持筛选
排序：通过 sort 字段调整顺序，默认排序规则保证稳定性

挂载模块与字段约束

挂载模块 module：
- 支持模块名及 _category 变体
- assist/translate 不挂载模块；fill/batch 必须选择模块
字段约束 field：
- JSON 数组，限定参与生成的字段
- 运行时由 SchemaBuilder 基于 field 动态生成 schema

前端页面配置流程

flowchart TD
Start(["进入列表/表单页"]) --> CheckList{"context=list?"}
CheckList --> |是| HasBatch{"是否存在batch应用?"}
HasBatch --> |是| ShowBatch["显示批量生成按钮"]
HasBatch --> |否| End1["无按钮"]
CheckList --> |否| CheckForm{"是否存在fill或全局assist/translate?"}
CheckForm --> |是| ShowForm["显示表单侧按钮"]
CheckForm --> |否| CheckBanner{"是否banner面板且有image应用?"}
CheckBanner --> |是| ShowBanner["显示banner面板按钮"]
CheckBanner --> |否| End2["无按钮"]
ShowBatch --> End3["结束"]
ShowForm --> End4["结束"]
ShowBanner --> End5["结束"]

依赖关系分析

控制器依赖服务：AiController -> ApplicationService
服务依赖模型与工具：ApplicationService -> AiApplication、SchemaBuilder、AiGateway
前端依赖工具：AiToolbarBuilder 提供页面配置 JSON
数据表依赖：dou_ai 与 dou_ai_model/dou_ai_provider/dou_ai_key 等辅助表共同支撑应用运行

graph LR
Ctrl["AiController"] --> Svc["ApplicationService"]
Svc --> Model["AiApplication"]
Svc --> Tool["AiToolbarBuilder"]
Svc --> Gate["AiGateway"]
Model --> DB["dou_ai"]

性能考量

列表查询优化：批量加载模型名称，避免每行单查
默认排序：sort ASC, id DESC 保证稳定排序
JSON 字段处理：field/config 在写入时进行清洗与规范化，减少运行时解析成本
前端配置：按需输出按钮与配置，减少不必要的数据传输

故障排查指南

无可用的AI模型配置：检查模型与供应商配置是否正确
API访问凭证获取失败：核对密钥与基础地址
HTTP请求失败/错误码：检查网络与供应商端点
JSON解析失败/响应异常：确认输出契约与模型返回格式
流式输出不支持：更换模型或在应用中调整设置
任务表不存在/超时/异步不支持：执行升级SQL创建任务表，或调整任务模式

结论

dou_ai 表为 DouPHP AI 创作能力的核心元数据载体，通过“能力类型 + 应用形态 + 任务形态 + 挂载模块 + 字段约束 + 输出契约 + 配置 JSON + 提示词 + 状态与排序”的组合，实现了灵活、可扩展的 AI 应用编排。配合模型层、服务层与控制器的协作，以及前端工具的配置下发，开发者可以高效地创建与管理 AI 应用，并在不同模块中复用与扩展。

附录

应用配置示例要点

通用配置：批量最小/最大数量
Banner 配置：画布尺寸、内容宽度、文字对齐方式

应用形态与任务形态映射

assist：字段润色/重写/翻译等文本增强
fill：整页生成
batch：批量生成
translate：翻译

添加日期：2026-10-05