From 01ff1435f6912726d0abb70c5d9fc35a247d18a7 Mon Sep 17 00:00:00 2001
From: linshen <32978552+linshenkx@users.noreply.github.com>
Date: Mon, 2 Feb 2026 20:12:51 +0800
Subject: [PATCH] docs(user): add context mode guides

---
 docs/user/README.md          |   4 +-
 docs/user/context-mode.md    | 147 +++++++++++++++++++++++++++++++++++
 docs/user/context-mode_en.md | 126 ++++++++++++++++++++++++++++++
 3 files changed, 276 insertions(+), 1 deletion(-)
 create mode 100644 docs/user/context-mode.md
 create mode 100644 docs/user/context-mode_en.md

diff --git a/docs/user/README.md b/docs/user/README.md
index e7a38ff8..b1fe903e 100644
--- a/docs/user/README.md
+++ b/docs/user/README.md
@@ -8,7 +8,9 @@
 - [桌面用户手册](./desktop-user-manual.md) - 桌面版完整使用指南
 
 ### Web版
-- Web用户指南（待创建） - Web版使用说明
+- [快速开始](./quick-start.md) - 5分钟快速上手
+- [上下文模式指南](./context-mode.md) - 上下文模式（多消息/变量）使用说明
+- [Context Mode Guide (English)](./context-mode_en.md) - Context Mode usage guide (Multi-message/Variable)
 
 ### 模型配置
 - [多自定义模型配置指南](./multi-custom-models.md) - 配置无限数量自定义模型的完整指南
diff --git a/docs/user/context-mode.md b/docs/user/context-mode.md
new file mode 100644
index 00000000..7058d026
--- /dev/null
+++ b/docs/user/context-mode.md
@@ -0,0 +1,147 @@
+# 上下文模式（Context Mode）使用指南
+
+本文档解释 Prompt Optimizer 的「上下文模式」怎么用、什么时候用、以及常见踩坑。
+
+上下文模式在界面上对应顶部功能模式里的「上下文」，并提供两个子模式：
+
+- 多消息（Multi-message）：面向多轮对话/多条消息的“消息级优化”
+- 变量（Variable）：面向单条用户提示词的“变量与工具驱动优化”
+
+## 1. 一句话理解：上下文模式解决什么问题？
+
+当你发现“单条提示词优化”不够稳定时，往往缺的是上下文信息（前置约束、示例、工具可用性、变量值等）。
+
+上下文模式的核心价值是：
+
+- 在优化时，把你配置的「对话消息 / 变量 / 工具」一并作为上下文交给模型
+- 让优化结果更贴合真实运行环境（而不是只看一段孤立文字）
+
+## 2. 先选对模式：多消息 vs 变量
+
+用下面这张表快速判断：
+
+| 你现在要做的事 | 推荐子模式 |
+| --- | --- |
+| 你在做角色扮演/多轮对话，想优化某一条 system/user 消息，让风格与上下文一致 | 多消息 |
+| 你在写“一条用户提示词”，但里面有大量可复用参数（如人名、日期、规格、输出格式），想用 {{var}} 管理与测试 | 变量 |
+| 你想配置/管理工具（Function Calling），并在测试时验证工具调用行为 | 变量（更匹配 UI 行为） |
+
+提示：两种子模式都支持右侧“测试区”用多列对比跑不同变量/不同版本。
+
+## 3. 多消息（Multi-message）快速上手
+
+适合：优化对话中的某一条 system/user 消息（不是让模型回答）。
+
+### Step 0：进入多消息模式
+
+1. 顶部功能模式选择「上下文」
+2. 子模式选择「多消息」
+
+### 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：用右侧测试区验证效果
+
+建议把测试当成“验收步骤”：
+
+1. 在测试区填变量（如果对话中用到了 {{var}}）
+2. 运行测试（可以用多列对比不同变量组合/不同版本）
+3. 看输出是否满足你期望的格式、语气和约束
+
+## 4. 变量（Variable）快速上手
+
+适合：优化“一条用户提示词”，并把其中的可变信息抽成变量，方便复用与测试。
+
+### Step 0：进入变量模式
+
+1. 顶部功能模式选择「上下文」
+2. 子模式选择「变量」
+
+### Step 1：用 {{var}} 写提示词
+
+你可以把可复用参数写成双花括号变量，例如：
+
+```text
+请你根据 {{product_name}} 的需求，输出一份 {{output_format}} 格式的方案。
+约束：预算 {{budget}}，交付时间 {{deadline}}。
+```
+
+小技巧：输入 `{{}}` 通常可以触发变量自动补全。
+
+### Step 2：管理变量值（让测试可复现）
+
+变量模式会提示缺失变量，并提供预览：
+
+- 缺失变量：先补齐变量值，再看优化/测试结果
+- 预览：确认最终渲染出来的提示词是否符合预期（占位符是否被正确替换）
+
+### Step 3：可选：配置工具（Function Calling）
+
+如果你希望提示词在“可调用工具”的环境运行：
+
+1. 在工具管理里维护工具定义（名称、描述、参数等）
+2. 在测试时验证模型是否会按预期触发工具
+
+### Step 4：选择模板并开始优化
+
+变量模式对应的模板通常会强调：
+
+- 在上下文/工具约束下，把原始用户提示词改写得更明确、可执行、可验证
+- 必须保留所有 {{var}} 占位符
+
+推荐先从“上下文版·用户提示词基础优化”开始。
+
+## 5. 常见问题（高频踩坑）
+
+### Q1：为什么我感觉“上下文模式”输出像在回答我？
+
+多消息模式的推荐模板明确要求“只输出优化后的消息”，不是生成回复。
+如果你换了自定义模板，请检查模板里是否混入了“回答任务”的指令。
+
+### Q2：为什么优化按钮是灰的？
+
+多消息模式下通常是因为：
+
+- 没有选中要优化的 system/user 消息
+- 没选模型或没选模板
+
+### Q3：优化后内容直接改了原消息，是 bug 吗？
+
+不是。多消息模式默认会把 V1 应用回会话，方便你继续在“真实上下文”里测试。
+如果不满意，应该通过版本切换回到 V0。
+
+### Q4：变量没替换/预览里还有 {{var}} 怎么办？
+
+说明该变量没有赋值。补齐变量值后再预览或测试。
+
diff --git a/docs/user/context-mode_en.md b/docs/user/context-mode_en.md
new file mode 100644
index 00000000..4d45a46d
--- /dev/null
+++ b/docs/user/context-mode_en.md
@@ -0,0 +1,126 @@
+# Context Mode Guide
+
+This document explains how to use **Context Mode** in Prompt Optimizer: what it is, when to use it, and common pitfalls.
+
+In the UI, Context Mode is the top-level **Function Mode: Context**. It provides two sub-modes:
+
+- **Multi-message**: message-level optimization in a conversation (multi-turn)
+- **Variable**: single user prompt optimization with variables & tools
+
+## 1. What problem does Context Mode solve?
+
+When “single prompt optimization” feels unstable, it often lacks real context: prior constraints, examples, available tools, or variable values.
+
+Context Mode helps by sending your configured **messages / variables / tools** together as the optimization context, so the output better matches the real execution environment.
+
+## 2. Choose the right sub-mode: Multi-message vs Variable
+
+Use this table as a quick decision:
+
+| Your goal | Recommended sub-mode |
+| --- | --- |
+| You are doing role-play or multi-turn chat, and want to optimize one specific system/user message while keeping style consistent with the conversation | Multi-message |
+| You have one user prompt, but many reusable parameters (name/date/spec/output format) and want to manage them via {{var}} for reuse & testing | Variable |
+| You want to configure tools (Function Calling) and verify tool behavior during testing | Variable |
+
+Both sub-modes support the test area (multi-column comparison) on the right.
+
+## 3. Multi-message quick start
+
+Best for: optimizing a **single** system/user message inside a conversation (not generating a reply).
+
+### Step 0: Enter Multi-message
+
+1. Select **Function Mode: Context**
+2. Select sub-mode **Multi-message**
+
+### Step 1: Build the conversation context
+
+Add/edit conversation messages on the left:
+
+- system/user/assistant/tool can all exist as context
+- but the usual optimization targets are system or user messages
+
+### Step 2: Select the message to optimize
+
+You must select a system/user message; otherwise the Optimize button is disabled.
+
+### Step 3: Pick model & template
+
+Start with the built-in recommended template:
+
+- **General Message Optimization (Recommended)**
+
+This template enforces a few critical rules:
+
+- Optimization is NOT replying
+- Keep the original role (system stays system, user stays user)
+- Preserve all `{{var}}` placeholders as-is
+
+### Step 4: Understand V0/V1
+
+Multi-message optimization uses a per-message version chain:
+
+- **V0**: original content (for rollback)
+- **V1**: optimized content (usually applied back to the conversation by default)
+
+If the optimization gets worse, switch versions (e.g. back to V0) instead of manual copy/paste rollback.
+
+### Step 5: Validate with the test area
+
+Treat testing as acceptance:
+
+1. Fill variable values (if your messages contain `{{var}}`)
+2. Run tests (use multi-column variants to compare)
+3. Check format, tone, constraints, and tool behavior
+
+## 4. Variable quick start
+
+Best for: optimizing **one user prompt** with reusable variables and optional tools.
+
+### Step 0: Enter Variable mode
+
+1. Select **Function Mode: Context**
+2. Select sub-mode **Variable**
+
+### Step 1: Write prompts with {{var}}
+
+Example:
+
+```text
+Create a plan for {{product_name}}.
+Output format: {{output_format}}.
+Constraints: budget {{budget}}, deadline {{deadline}}.
+```
+
+Tip: typing `{{}}` often triggers variable auto-completion.
+
+### Step 2: Provide variable values
+
+If you still see `{{var}}` in preview/test outputs, that variable has no value. Set it first, then re-run preview or test.
+
+### Step 3 (Optional): Configure tools (Function Calling)
+
+If your prompt is meant to run with tools:
+
+1. Define tools in Tool Manager (name/description/parameters)
+2. Validate tool calling behavior in the test area
+
+### Step 4: Optimize with a suitable template
+
+Variable-mode templates usually focus on rewriting the user prompt to be clear, executable, and verifiable, while preserving all `{{var}}` placeholders.
+
+Recommended starting template:
+
+- **Contextual User Prompt Basic Refinement**
+
+## 5. Common pitfalls
+
+- “It replies instead of optimizing”: check your template instructions; the recommended multi-message template is explicitly *optimization-only*.
+- “Optimize button disabled”: in Multi-message mode, you likely didn't select a target message or didn't choose model/template.
+- “The message content changed after optimize”: expected behavior; use version switching to revert to V0.
+- “I still see {{var}} in preview/output”: that variable has no value yet. Set the variable value, then re-run preview/test.
+
+---
+
+If you are preparing a reply for Issue #240, you can link this doc (`docs/user/context-mode_en.md`) and quote the decision table in Section 2. That usually helps users pick the correct sub-mode quickly.