一、阶段整体工作概述

本阶段核心开发内容是独立的管理员后台管理系统，开发目的是把项目里各处大模型提示词、模型配置从代码里剥离出来，做成网页可视化操作页面。之前调试 NPC 发言、剧本生成、对局 AI 逻辑时，所有人想要改提示词、换大模型，都需要改项目源码、重启服务，效率很低。本次做完管理端之后，开发、测试人员直接在浏览器页面就能切换模型、修改提示内容、调试参数，不用改动后端代码、不用本地部署项目，大幅缩短 AI 内容的迭代调试周期。整体工作包含可行性调研、管理端页面架构规划、后端数据表新增、接口开发、页面 UI 整改、模型对接调试、提示词编辑配套功能、日志统计、在线测试等全流程落地。

二、前期方案研讨与开发规划

1. 可行性分析：小组先开会讨论可视化 AI 管理方案能不能落地，确定可以搭建独立管理后台，拆分四大功能模块：模型配置管理、各场景提示词编辑、在线调试测试、大模型调用日志统计。每个模块单独开页面，不堆砌在同一个页面里。
2. 文档归档：把整套开发方案整理写入《管理端开发者文档》，确定前后端开发顺序、数据库新增字段、页面布局规范，作为后续开发统一标准。
3. 基础规则敲定：密钥安全规范：大模型 API 密钥只从服务器环境变量读取，不在数据库、配置文件里明文存储；模型名称、请求地址、各类参数全部存数据库，页面可视化新增 / 修改，实现线上动态切换模型。优先对接通阿里百炼 qwen-plus 兼容接口作为项目第一个入库模型。

三、后端相关开发落地

1、数据库新增

新建模型配置表、提示词模板表、AI 调用日志表、测试样例存储表，分别用来保存各类大模型参数、每个业务场景对应的提示文案、每次调用的详细数据、调试用的输入样例。日志会完整记录调用方、选用模型、入参提示词、消耗 token、耗时、大模型厂商、返回内容等全量信息，方便后续对账和问题排查。

2、模型配置接口开发

开发模型新增、编辑、启用停用、查询、在线测试接口，遵循密钥隔离规范：把剧本生成、DM 主持、NPC 自动回复三大原有 AI 业务全部接入新的动态调用逻辑，LLM_API_KEY仅读取系统环境变量，BASE_URL、模型名称、温度、上下文长度等全部从数据库读取，做到页面改配置即时生效。完成百炼通配地址https://dashscope.aliyuncs.com/compatible-mode/v1对接，在数据库中创建 qwen-plus 作为系统第一条可用模型配置，完成接口连通自测。

3、提示词 & 测试相关接口

1. 开发各场景提示词的增删改查接口，支持按对局场景分类存储模板；
2. 开发在线试运行接口，页面填写入参即可远程调用大，不落地数据库；
3. 新增测试样例的新增、删除、查询接口，支持保存多套调试输入数据；
4. 新增对比测试接口，可挑选不同模型、不同版本提示词、不同测试用例做横向效果对比。

4、日志接口

拉取全量 AI 调用记录、单条日志详情接口，详情内容做自动换行格式化，原始 JSON、长文本自动排版，内容不再挤在同一行。每一次 AI 调用都会完整落地日志，记录内容包含场景编号、选用模型、整套提示、入参出参、各类 token 消耗、接口耗时、厂商信息、是否降级、房间编号、玩家信息等数十项内容，方便后期排查问题。

四、前端管理端页面改造与功能实现

1、整体页面规范整改

1. 管理端做成独立系统，不和游戏前台共用样式、导航栏，页面采用常规后台浏览器默认主题，彻底脱离游戏复古 UI 风格；
2. 原四个功能板块全部拆分独立页面，不再堆砌在同一个页面：模型配置页、提示词工作台页、在线测试页、调用日志页；
3. 首页进入 AI 管理台按钮从单独占用区块，调整至基础档案右上角，悬浮叠加展示，不挤占原有页面布局；
4. 优化页面空间，各类弹窗、抽屉放大尺寸，原先狭小的配置弹窗扩容，适配提示词长篇编辑需求。

2、提示词工作台核心功能落地

1. 变量可视化展示：编辑提示词区域旁，展示当前场景入参、出参的结构，采用树形组件展示字段，解决同 key 重复报错问题；支持展开 / 收起字段，管理员编写{request.actor.name}这类占位变量时，可以直观查看可用参数，不用翻阅代码；
2. 提示词变量渲染规则落地：数据库直接存储{变量名}格式文本，程序运行时使用 f-string 动态替换真实内容，管理端配套输入联想功能，输入前缀自动带出可用字段；
3. 场景配套初始文案：按照现有对局全场景（NPC 发言、调查判定、剧情推进等），批量生成第一版标准提示词，批量入库；
4. 在线调试区：页面新增调试面板，管理员可以手动填写入参，也选用已保存的测试样例，点击运行即可实时调取大模型返回结果；支持新增、删除测试样例，删除后下拉选项实时同步更新。

3、模型在线检测功能

在模型配置页面新增对话测试弹窗，填入测试内容即可实时调用对应大模型，快速验证当前配置能不能正常连通，测试数据不用存入数据库，仅临时展示返回内容。

4、对比测试页面优化

修复点击开始对比报错问题，页面支持自由挑选场景、备选模型、不同版本提示、多套测试用例，横向对比 AI 生成效果。

5、页面细节优化

1. 配置模块、试验方案模块拉长页面可用区域，解决内容拥挤；
2. 大模型返回的多层 JSON 文本在日志、结果区自动格式化换行，紧凑字符串自动排版拆分，阅读更直观。

6、页面 bug 修复

修复 Schema 树形组件重复 key（theme、description）控制台警告问题，去重树节点数据，消除前端报错。

五、配套落地的细节优化

1. 区分左右结构作用：左侧是入参 / 出参规范 Schema（用来提示有哪些可用字段），右侧是实际填写样例 JSON，页面分别排版、分开展示，左右内容不用保持一致；
2. 优化输入输出 JSON 展示格式，自动换行缩进，整块内容不再堆成一行；
3. 调整弹窗布局，内容过长复用项目已有滚动条组件，避免内容超出屏幕。

六、本阶段落地收益

1. 后续想要优化 NPC 说话风格、剧本 AI 生成规则、DM 剧情文案，产品、测试、开发全都能在网页改提示词，不用改代码、不用本地搭环境重启项目，大幅缩短 AI 迭代周期；
2. 线上可以随时切换大模型服务商，比如从通义换成其他模型，页面改配置即可，不用修改后端源码；
3. 全量 AI 调用留痕，出现回复异常时，通过日志快速定位是提示词问题还是模型接口问题；
4. 同场景多模型、多文案一键对比，直观挑选最优提示词方案。

七、现存小问题 & 下一阶段工作计划

1. 现存：少量字段预览排版还可以微调，部分边界异常场景缺少兜底提示；
2. 下一阶段： ① 扩充更多业务场景的提示词模板； ② 增加提示词版本归档功能，支持回滚历史文案； ③ 对接更多厂商大模型配置，扩充备选模型库； ④ 全页面多轮测试，补齐边角交互细节。