上下文模式（Context Mode）使用指南
本文档解释 Prompt Optimizer 的「上下文模式」怎么用、什么时候用、以及常见踩坑。
上下文模式在界面上对应顶部功能模式里的「上下文」，并提供两个子模式：
- 多消息（Multi-message）：面向多轮对话/多条消息的“消息级优化”
- 变量（Variable）：面向单条用户提示词的“变量与工具驱动优化”
1. 一句话理解：上下文模式解决什么问题？
当你发现“单条提示词优化”不够稳定时，往往缺的是上下文信息（前置约束、示例、工具可用性、变量值等）。
上下文模式的核心价值是：
- 在优化时，把你配置的「对话消息 / 变量 / 工具」一并作为上下文交给模型
- 让优化结果更贴合真实运行环境（而不是只看一段孤立文字）
2. 先选对模式：多消息 vs 变量
用下面这张表快速判断：
| 你现在要做的事 | 推荐子模式 |
|---|---|
| 你在做角色扮演/多轮对话，想优化某一条 system/user 消息，让风格与上下文一致 | 多消息 |
| 你在写“一条用户提示词”，但里面有大量可复用参数（如人名、日期、规格、输出格式），想用 {{var}} 管理与测试 | 变量 |
| 你想配置/管理工具（Function Calling），并在测试时验证工具调用行为 | 变量（更匹配 UI 行为） |
提示：两种子模式都支持右侧“测试区”用多列对比跑不同变量/不同版本。
3. 多消息（Multi-message）快速上手
适合：优化对话中的某一条 system/user 消息（不是让模型回答）。
Step 0：进入多消息模式
- 顶部功能模式选择「上下文」
- 子模式选择「多消息」
Step 1：准备对话上下文
在左侧的会话管理区域添加/编辑消息：
- system/user/assistant/tool 都可以存在于上下文中
- 但“可被优化的目标”通常是 system 或 user 消息
Step 2：选中你要优化的那条消息
关键点：必须选中一条 system/user 消息，否则“优化”按钮会不可用。
Step 3：选择模型与模板
推荐先从内置模板开始：
- 通用消息优化（推荐）：适用于绝大多数对话场景
它的核心规则是：
- 优化 != 回复（只改写那条消息本身）
- 保持原消息角色不变（system 还是 system、user 还是 user）
- 保留所有 {{变量占位符}} 原样
Step 4：点击“优化”并理解 V0/V1
多消息模式的优化是“消息级版本链”：
- V0：原始内容（首次创建时保存，用于回退）
- V1：优化后的内容（默认会应用回对话）
如果你觉得“优化后反而变差”，正确做法是：
- 切换版本回到 V0 或其它版本（而不是手动复制粘贴回退）
Step 5：用右侧测试区验证效果
建议把测试当成“验收步骤”：
- 在测试区填变量（如果对话中用到了 {{var}}）
- 运行测试（可以用多列对比不同变量组合/不同版本）
- 看输出是否满足你期望的格式、语气和约束
4. 变量（Variable）快速上手
适合：优化“一条用户提示词”，并把其中的可变信息抽成变量，方便复用与测试。
Step 0：进入变量模式
- 顶部功能模式选择「上下文」
- 子模式选择「变量」
Step 1：用 {{var}} 写提示词
你可以把可复用参数写成双花括号变量，例如：
请你根据 {{product_name}} 的需求，输出一份 {{output_format}} 格式的方案。
约束：预算 {{budget}}，交付时间 {{deadline}}。
小技巧：输入 {{}} 通常可以触发变量自动补全。
Step 2：管理变量值（让测试可复现）
变量模式会提示缺失变量，并提供预览：
- 缺失变量：先补齐变量值，再看优化/测试结果
- 预览：确认最终渲染出来的提示词是否符合预期（占位符是否被正确替换）
Step 3：可选：配置工具（Function Calling）
如果你希望提示词在“可调用工具”的环境运行：
- 在工具管理里维护工具定义（名称、描述、参数等）
- 在测试时验证模型是否会按预期触发工具
Step 4：选择模板并开始优化
变量模式对应的模板通常会强调：
- 在上下文/工具约束下，把原始用户提示词改写得更明确、可执行、可验证
- 必须保留所有 {{var}} 占位符
推荐先从“上下文版·用户提示词基础优化”开始。
5. 常见问题（高频踩坑）
Q1：为什么我感觉“上下文模式”输出像在回答我？
多消息模式的推荐模板明确要求“只输出优化后的消息”，不是生成回复。 如果你换了自定义模板，请检查模板里是否混入了“回答任务”的指令。
Q2：为什么优化按钮是灰的？
多消息模式下通常是因为：
- 没有选中要优化的 system/user 消息
- 没选模型或没选模板
Q3：优化后内容直接改了原消息，是 bug 吗？
不是。多消息模式默认会把 V1 应用回会话，方便你继续在“真实上下文”里测试。 如果不满意，应该通过版本切换回到 V0。
Q4：变量没替换/预览里还有 {{var}} 怎么办？
说明该变量没有赋值。补齐变量值后再预览或测试。
Source: docs/user/context-mode.md