提示词管理

提示词管理维护两份模板：系统提示词（人设、能力边界、回复风格，所有会话基线）和会话上下文（每次新会话起手注入的实时变量段，与系统提示词分离以保证 LLM 端 KV cache 命中）。本章讲入口、二级导航、编辑器、模板变量与预览。

7.1 入口与权限

左侧菜单进入「提示词管理」，URL /admin/prompts。本菜单仅 super_admin 可见——普通 admin 不会在侧边栏看到这一项。

1. 用 super_admin 账号登录管理后台
2. 侧边栏点「提示词管理」进入 /admin/prompts
3. 页面左侧是 200px 宽的二级导航，含两项：系统提示词、会话上下文
4. 右侧主区根据所选项展示对应编辑面板，默认进入「系统提示词」

注意： 权限模型提醒：提示词改动会影响所有用户、所有产品、所有项目的对话基线。仅 super_admin 可见这一菜单不是 UI 装饰——它是后端路由守卫硬卡的。请把 super_admin 账号控制在 1-2 人内。

7.2 系统提示词（SystemPromptPanel）

二级导航选中「系统提示词」时打开。系统提示词定义助手的人设、能力边界、回复风格，所有会话都会带上它。

面板布局

• 顶部工具栏：标题「系统提示词」+ 已保存时显示 v{版本号} · 更新时间 · 操作人 副标题 + 右上「预览」「保存」两个按钮
• 左侧主编辑区：单 textarea，Markdown 语法支持，底部一行显示「{字符数} 字符 · 支持 Markdown · 点右侧变量插入」
• 右侧变量面板：280px 宽，按 4 个分组列出可插入变量（见 7.4）

首次使用：初始化

如果数据库中尚未有「系统提示词」记录，编辑器中央会显示空态——一句提示语 + 一个「初始化默认内容」按钮。点击后后端 seed 一份默认模板（角色 / 能力 / 回复风格三段），随后即可编辑保存。

编辑要点

1. 顶部副标题展示当前版本号 v{N}、最近更新时间、最近操作人——每次保存版本号 +1
2. 点「保存」前内容若为空会被前端拦截（弹 toast「内容不能为空」）
3. 点「保存」成功后弹 toast「已保存（v{N+1}）」，新版本立即对后续会话生效；已在进行中的会话不会被改写历史
4. 点「预览」打开模态框，显示由后端 previewPrompt() 拼接出的最终 prompt（含变量替换结果），可一键复制

小贴士： 保存前必预览：「预览」按钮调后端真实拼接路径，把当前 body + 当前上下文实际替换后的字符串端给你看一遍。这比肉眼检查 {{...}} 占位靠谱得多。

7.3 会话上下文（CurrentInfoPanel）

二级导航选中「会话上下文」时打开。这是另一份独立的提示词模板，不是「实时上下文快照展示」。

它的作用：运行时作为新会话的第一条信息注入，承载会变的实时变量（用户名、平台、服务地址、当前时间、会话 ID 等）。系统提示词本身保持稳定不变，以便 LLM 端 KV cache 命中——把易变信息从 system prompt 中剥离到这里是关键的性能优化。

默认模板

初始化后的默认 body：

当前会话上下文：
- 用户：{{user_name}}（{{user_role}}）
- 平台：{{platform_label}}
- 服务地址：{{server_url}}
- 日期时间：{{datetime}}
- 会话 ID：{{session_id}}

与系统提示词的差异

• 两者面板布局、操作流程完全相同（共用 PromptEditorPanel 组件）
• 区别在 prompt 内容定位：系统提示词放不变的人设/规则，会话上下文放会变的实时字段
• 「预览」对会话上下文目前只回显当前 body，不调后端拼接（后端暂无对应预览接口）

提示： 为什么要拆两份？每次会话都带「2026-06-16 14:32」这样的时间戳进 system prompt，会让 LLM 端的 KV cache 永远 miss。把易变字段移到「会话上下文」作为首条消息注入，system prompt 保持稳定可被缓存——延迟和成本都会显著下降。

7.4 模板变量

两个编辑器都支持运行时变量替换——你写的是 {{var}} 占位符，AI 看到的是带具体值的句子。点右侧变量面板中的某一项，会以双花括号包裹的形式插入到光标位置。

变量按 4 个分组组织（与右侧面板一一对应）：

提示： 变量是字符串替换，不是函数：替换在请求 LLM 之前完成。如果你写错变量名（比如 {{用户}}），它会原样发给 AI 当字面量，AI 大概率装作懂——但实际上下文就丢了。建议保存前用「预览」按钮看实际拼接结果。

7.5 预览拼接结果

顶部「预览」按钮打开模态框，显示带变量替换后的最终 prompt：

1. 系统提示词：调后端 previewPrompt() 接口，返回 final_prompt 字段，是真实运行时下发给 LLM 的完整字符串
2. 会话上下文：暂无后端预览接口，前端直出当前 textarea 中的 body
3. 模态框底部「关闭」「复制」两个按钮——「复制」将整段写入剪贴板，方便贴到外部工具对比

注意： 预览仅在已保存条目上可用：顶部「预览」按钮在记录尚未初始化时（即未点过「初始化默认内容」）处于禁用态。先初始化、再编辑、再预览。

7.6 调试技巧：traces 调用日志

提示词改完用户说"回答变奇怪了"，先去「监控 → 调用日志」/admin/traces 翻具体那条对话。traces 完整记录每次请求实际发给 LLM 的 prompt 全文 + 工具调用链 + 模型回包。

套路

1. 问用户："是哪条消息？什么时间？" 记下时间点和用户名
2. 打开 /admin/traces，按用户名 + 时间窗筛选
3. 找到具体那条 trace，点开看实际发送的 system prompt 段——模板变量是否替换正确、有没有漏字段
4. 对照 LLM 回包，定位是 prompt 引导问题，还是 skill / MCP 工具调用错
5. 定位后再决定：改 prompt 措辞 / 调 skill 顺序 / 还是给模板加新变量

小贴士： 调用日志在另一个章节：traces 的具体操作请看监控：调用 · 审计 · 系统日志。本章只讲提示词侧的入口。

7.7 本章小结 + 上线 checklist

每次改提示词前后过一遍这个清单，能挡掉大多数事故：

• 改之前先在编辑器里完整复制一份当前 body 到本地备份（当前版本无历史回滚 UI）
• 用到的变量都在右侧变量面板里有列出（写错变量名会被原样发给 LLM）
• 易变字段（时间 / 会话 ID）放「会话上下文」而不是塞进「系统提示词」，保 KV cache
• 保存前点「预览」，肉眼确认变量替换结果符合预期
• 没有泄漏敏感字段（API key / 内部 URL / 数据库密码）到 prompt
• 保存后开一个新会话跑 3 个典型问题（首次提问 / 业务数据 / 拒绝越权）确认行为符合预期
• 上线后 24 小时内扫一眼 traces 错误率，无异常再放心

注意： 当前无内置历史回滚 UI：本版本前端只在副标题展示 v{N} 当前版本号，未提供历史抽屉、diff 对比、一键回滚按钮。大改之前请手工另存一份备份到本地编辑器，避免覆盖后无法找回。

提示： 相关章节：Skill 技能包管理 · MCP 外部工具管理 · 模型管理 · 监控：调用日志。

相关

• Skill 技能包管理
• MCP 外部工具管理
• 模型管理
• 监控：调用 · 审计 · 系统日志