Prompt 管理 · LightAIP · frontend-intro-v5

1. 页面概览

Prompt 管理页（路由 /admin/prompts）是 AIP 管理后台面向管理员的提示词（Prompt）模板管理台。模板以「名称 + 模型族 + 版本 + 启用状态」组织，供 NLQ/Text2SQL 等链路渲染时引用；页面提供模板列表、新建模板、编辑（保存即新建版本并置为启用）、版本管理（版本列表、回滚、单版本删除）、compile 试算（占位符变量渲染并估算 Tokens）五类能力。所有请求经 aipClient（/aip-api/v1 → AIP 18080），后端未就绪时优雅提示不白屏。

一句话总结：本页是 Prompt 模板的「列表 + 版本库 + 渲染试算」管理台，编辑即建新版本、可随时回滚，模板变更全程可追溯。

2. 访问入口

路由与菜单：path /admin/prompts、name AdminPrompts、路由 title「Prompt 管理」，位于 AIP 管理后台侧边栏（菜单项「Prompt 管理」）；源码 action/web/src/views/PromptManagePage.vue。
认证与权限：父路由 /admin 配置 requiresAuth: true, requiresAdmin: true，需登录且 aip_is_admin === '1'；请求经 aipClient 附带 aip_token，401 清 token 跳登录页。
端口与 API 前缀：AIP 后端 18080，前端 baseURL /aip-api/v1（Vite 将 /aip-api 重写为 /api）。

3. 界面布局

+--------------------------------------------------------------+
| Prompt 管理                          [新建模板]                |
| 模板列表：名称|模型族|版本|状态|描述|操作(编辑/版本管理/试算/删除) |
| 新建/编辑弹窗：名称*|模型族|描述|内容*（支持 {{var}} 占位符）     |
|   [取消] [创建 / 保存（新建版本）]                               |
| 版本管理弹窗：版本|模型族|状态|更新时间|操作(回滚/删除本版/当前版本) + 预览 |
| 试算渲染弹窗：变量行(key/value/删除) [+ 添加变量] [开始试算]      |
|   结果：模板版本 + 估算 Tokens + 渲染结果                        |
+--------------------------------------------------------------+

各板块职责：

模板列表：核心区，展示 name/model_family/version/active（启用行浅绿高亮 row-active），行操作编辑、版本管理、试算、删除。
新建/编辑弹窗：名称仅在新建时填写；编辑只改内容/模型族/描述，保存即新建版本并启用。
版本管理弹窗：列出全部版本，每行操作含「回滚」与「删除本版」；生效版本显示「当前版本」且回滚/删除均禁用（需先回滚到其它版本再删）；点击版本行下方展示该版本内容预览。
试算渲染弹窗：按行输入占位符变量，展示渲染后的模板与 estimated_tokens。

4. 交互元素

控件	位置	含义与作用
新建模板	页面头部	打开新建弹窗，填名称/模型族/描述/内容后「创建」`POST /prompts/templates`
编辑	行操作	打开编辑弹窗，改 content/model_family/description，保存「保存（新建版本）」`PUT /prompts/templates/:name`
版本管理	行操作	打开版本弹窗，加载 `GET /prompts/templates/:name/versions`，列出版本与启用状态
回滚	版本弹窗	confirm 后 `POST /prompts/templates/:name/versions/:v/rollback`，把该版本设为启用并刷新
删除本版	版本弹窗	confirm 后 `DELETE /prompts/templates/:name/versions/:v`，仅删除该单个历史版本；生效版本按钮禁用（需先回滚）
试算	行操作	打开试算弹窗，预设变量 Question/TableSchemas，可增删变量行，点「开始试算」`POST /prompts/compile`（body `{template_name, variables}`）；试算中按钮禁用并显示 spinner + 已用秒数，等待 ≥5s 时追加蓝色提示条说明 compile 为同步渲染、请勿重复点击
删除	行操作	confirm「此操作不可撤销」后 `DELETE /prompts/templates/:name`（模板级，级联删除该模板全部版本）

次要控件：顶部 alert 提示区（成功/失败/信息，右上角「关闭」）；编辑保存、回滚与删除共用 submitting 禁用态（「提交中...」）。版本管理弹窗底部有常驻删除说明：行内「删除本版」经 DELETE /prompts/templates/:name/versions/:v 仅删除单个历史版本；当前生效版本不可删除（按钮禁用，需先回滚）；列表行内「删除」为模板级操作、会级联删除全部版本，提示用户勿与本弹窗单版本删除混淆。

5. 后端关联

5.1 端点表

方法	路径	用途
GET	/prompts/templates	模板列表（name/model_family/version/active/description/content）
POST	/prompts/templates	新建模板
GET	/prompts/templates/:name	取指定模板的启用版本
PUT	/prompts/templates/:name	更新模板（后端新建版本 +1 并设为 active）
DELETE	/prompts/templates/:name	删除模板（模板级，级联全部版本）
GET	/prompts/templates/:name/versions	模板版本列表
DELETE	/prompts/templates/:name/versions/:v	删除单个版本（生效版本不可删，否则 409）
POST	/prompts/templates/:name/versions/:v/rollback	回滚到指定版本
POST	/prompts/compile	试算渲染，body `{template_name, variables}`，返回 `{name, version, rendered_content, estimated_tokens}`

单版本删除已补齐（2026-09-14）：新增 DELETE /prompts/templates/:name/versions/:v（prompt/handler.go 的 DeleteVersion，服务层 prompt/service.go 同名校验+删除）。服务层语义：按 (name, version) 精确定位，仅删除该行；当前生效版本拒绝删除（返回 409 CONFLICT），理由见 §8 缺陷表与 API 文档 §5.1——active 是 GetActive/Compile/text2sql 运行时读取生效版本的唯一标记，模型未定义「删掉 active 后由谁上位」。模板级 DELETE /prompts/templates/:name（级联全版本）行为不变，前端两处入口已用文案明确区分。

5.2 关键机制

版本化保存：编辑保存走 PUT，后端对模板新建版本号 +1 并设为 active；列表与版本弹窗中的「启用中」状态即由 active 标记，回滚同样通过切换 active 实现。
compile 试算（契约已修正）：请求体字段名为 template_name（binding:"required"，prompt/handler.go:163-167），此前前端误发 name 会被 ShouldBindJSON 判为缺必填字段直接 400；响应为 CompileResult{name, version, rendered_content, estimated_tokens}（prompt/service.go:59-65），此前前端误读 rendered/warnings（后端无 warnings 字段）。本批已按后端契约修正请求/响应字段，并在结果区展示模板版本号。未填变量值时后端 missingkey=default 渲染为空串，仅查看原模板。
等待反馈：compile 为同步请求（后端 handler 直接返回渲染结果，无 task_id，prompt/handler.go:162-178），无法做进度条；前端以「spinner + 已用秒数」+ ≥5s 蓝色提示条给出等待反馈，按钮在请求期间禁用，避免重复点击放大同步负载。
占位符语法：模板内容支持 {{var}} 形式占位符，前端示例变量为 Question、TableSchemas。
响应结构：统一 {code, data, trace_id} 包裹，模板列表响应为 {templates: [...]}；错误取 message/error 展示。

6. 权限与安全

全部 /prompts/* 路由挂在 admin 管理组，仅管理员可读写；列表请求需有效 aip_token。
删除与回滚均有 confirm 二次确认，删除不可撤销。
模板内容为内部提示词工程资产，前端不对外暴露脱敏逻辑。

7. 常见问题与排错

现象：页面提示「加载模板列表失败：...」。原因：后端未启动、Token 失效或代理未指向 18080。处理：确认 AIP 服务存活、重新登录、检查 /aip-api 代理。
现象：编辑保存后列表版本号未变化。原因：保存请求实际失败（网络/后端写入失败），alert 报「保存失败」。处理：按提示检查请求与后端日志，成功后页面自动 fetchTemplates 刷新。
现象：试算结果中变量未被替换。原因：变量名与模板占位符不一致，或只填了变量名未填值。处理：确认占位符写法为 {{var}} 且与变量 key 完全一致，值为空时仅查看原模板。
现象：操作时跳转登录页（401）。原因：aip_token 过期被响应拦截器清理。处理：重新登录后重试。

8. 已知缺陷与边界

项	说明
编辑不可改名	名称仅在新建时填写，编辑弹窗不展示名称字段（由路由参数锁定）
单版本删除（已于 2026-09-14 补齐）	新增 `DELETE /prompts/templates/:name/versions/:v`（`prompt/handler.go` `DeleteVersion` / `prompt/service.go` `DeleteVersion`）与版本弹窗行内「删除本版」。约束：当前生效版本不可删除（409），需先回滚到其它版本——active 是 `GetActive`/`Compile`/text2sql 运行时的唯一生效标记，模型无「active 被删后自动上位」规则。模板级 `DELETE /prompts/templates/:name`（级联全部版本）仍保留，两处入口文案已明确区分
无独立启用开关	启用态由「最近一次保存/回滚」决定，无单独激活按钮
试算为同步请求（已加等待反馈）	compile 为同步渲染，后端直接返回结果、无 task_id（`prompt/handler.go:162-178`），无法做进度条；超大模板或复杂变量时响应耗时表现为页面等待。前端已加 spinner + 已用秒数 + ≥5s 提示条，按钮期间禁用防重复点击（已于 2026-09-13 补齐）
compile 契约（已于 2026-09-13 修正）	请求体字段为 `template_name`、响应为 `rendered_content`/`estimated_tokens`/`version`（`prompt/handler.go:163-167`、`prompt/service.go:59-65`）；修正前前端误发 `name`、误读 `rendered` 会导致 400 与空结果

9. 2026-09-10 安全与行为修订

PromptManagePage 列表展示修复：管理页提示模板列表此前存在的列表渲染异常已修复，模板条目/版本信息正常展示（2026-09-10 修复战役回归项）。

10. 2026-09-14 单版本删除补齐

后端：prompt 包新增 DeleteVersion(ctx, name, version) 服务方法与 DELETE /api/v1/prompts/templates/:name/versions/:v 端点（admin）。版本不存在 → 404；版本号非正整数 → 400；生效版本 → 409 拒绝；成功返回 {deleted, name, version}。
前端：版本弹窗每行新增「删除本版」（生效版本禁用），底部边界说明改为真实删除指引，并与列表行内模板级「删除」（级联全部版本）明确区分。
测试：products/aip/prompt 新增 TestPromptHTTPDeleteVersion（正常删单版本 / 其它版本不受影响 / 不存在 404 / 非法版本号 400 / 删生效版本 409 / 回滚后再删生效版本成功）；products/aip/server/prompt_http_test.go 路由鉴权矩阵补入新端点。