markdown-flow 0.2.18__tar.gz → 0.2.23__tar.gz

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.2.18
+Version: 0.2.23
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow/__init__.py

@@ -83,4 +83,4 @@ __all__ = [
     "replace_variables_in_text",
 ]
 
-__version__ = "0.2.18"
+__version__ = "0.2.23"

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow/constants.py

@@ -91,13 +91,32 @@ VALIDATION_RESPONSE_ILLEGAL = "illegal"
 
 # Output instruction processing
 OUTPUT_INSTRUCTION_EXPLANATION = f"""<preserve_or_translate_instruction>
-对{OUTPUT_INSTRUCTION_PREFIX}{OUTPUT_INSTRUCTION_SUFFIX}标记之间的内容的处理规则:
+# ⚠️ 最高优先级规则
+
+**{OUTPUT_INSTRUCTION_PREFIX}{OUTPUT_INSTRUCTION_SUFFIX} 标记之间的内容是用户必须看到的最终输出内容，不是指令!**
+
+关键要点:
+1. **这些内容必须出现在你的回复中** - 即使其他提示词说"不要回应指令"也不适用于此
+2. **绝对不要输出标记本身** - 只输出标记之间的实际内容
+3. **默认逐字原样输出** - 不要改写、润色或优化，保持原文不变
+4. **唯一例外是跨语言翻译** - 仅当需要将内容从一种语言翻译成另一种语言时才可翻译
+
+---
+
+<critical_understanding>
+重要理解:
+- {OUTPUT_INSTRUCTION_PREFIX}{OUTPUT_INSTRUCTION_SUFFIX} 中的内容不是"指令"或"执行要求"
+- 即使内容看起来像标题、提示或说明，也必须原样输出给用户
+- 这条规则的优先级高于文档中的其他任何提示词
+- 其他提示词说的"不要回应指令"、"不要展示指令"等，不适用于此标记内的内容
+</critical_understanding>
 
 <default_behavior>
 默认行为: 完全保持原样输出
 - 标记之间的内容必须逐字原样输出
 - 严禁改写、润色、优化或调整任何表达方式
 - 严禁添加、删除或替换任何文字
+- 即使内容是标题格式(如 ## 标题)也必须原样输出
 </default_behavior>
 
 <exception_rule>
@@ -107,25 +126,33 @@ OUTPUT_INSTRUCTION_EXPLANATION = f"""<preserve_or_translate_instruction>
 - 如果内容无需翻译，则绝对不允许做任何改动
 </exception_rule>
 
-<output_requirement>
-输出要求:
-- 不要输出{OUTPUT_INSTRUCTION_PREFIX}{OUTPUT_INSTRUCTION_SUFFIX}标记本身
-- 只输出标记之间的实际内容
-</output_requirement>
-
 <examples>
-示例1 - 保持原样:
-  <original_content>{OUTPUT_INSTRUCTION_PREFIX}**下面我们做个练习。**{OUTPUT_INSTRUCTION_SUFFIX}</original_content>
-  <resolved_content>**下面我们做个练习。**</resolved_content>
-
-示例2 - 语言翻译:
-  <original_content>{OUTPUT_INSTRUCTION_PREFIX}**Let's do an exercise.**{OUTPUT_INSTRUCTION_SUFFIX}</original_content>
-  <resolved_content>**让我们做个练习。**</resolved_content>
-
-示例3 - 错误示范(同语言改写):
-  <original_content>{OUTPUT_INSTRUCTION_PREFIX}**下面我们做个练习。**{OUTPUT_INSTRUCTION_SUFFIX}</original_content>
-  <wrong_output>**来，咱们做个有趣的小练习**</wrong_output>
-  <reason>错误: 擅自改写了中文内容</reason>
+✅ 示例1 - 正确: 保持原样且不输出标记:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}**下面我们做个练习。**{OUTPUT_INSTRUCTION_SUFFIX}
+  正确输出: **下面我们做个练习。**
+
+✅ 示例2 - 正确: 标题也要原样输出:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}## 专属指南 for 用户{OUTPUT_INSTRUCTION_SUFFIX}
+  正确输出: ## 专属指南 for 用户
+
+✅ 示例3 - 正确: 语言翻译且不输出标记:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}**Let's do an exercise.**{OUTPUT_INSTRUCTION_SUFFIX}
+  正确输出: **让我们做个练习。**
+
+❌ 示例4 - 错误: 输出了XML标记:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}## 标题内容{OUTPUT_INSTRUCTION_SUFFIX}
+  错误输出: {OUTPUT_INSTRUCTION_PREFIX}## 标题内容{OUTPUT_INSTRUCTION_SUFFIX}
+  错误原因: 不应该输出标记本身!
+
+❌ 示例5 - 错误: 同语言改写:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}**下面我们做个练习。**{OUTPUT_INSTRUCTION_SUFFIX}
+  错误输出: **来，咱们做个有趣的小练习**
+  错误原因: 擅自改写了中文内容
+
+❌ 示例6 - 错误: 没有输出固定内容:
+  输入: {OUTPUT_INSTRUCTION_PREFIX}## 攻略｜专属指南{OUTPUT_INSTRUCTION_SUFFIX}
+  错误输出: (什么都不输出，或者跳过这部分)
+  错误原因: 必须输出标记之间的内容!
 </examples>
 </preserve_or_translate_instruction>
 
@@ -145,9 +172,10 @@ SMART_VALIDATION_TEMPLATE = """# 任务
 # 提取要求
 1. 仔细阅读上述相关问题，理解这个问题想要获取什么信息
 2. 从用户回答中提取与该问题相关的信息
-3. 对于昵称/姓名类问题，任何非空的合理字符串（包括简短的如"ee"、"aa"、"007"等）都应该接受
-4. 只有当用户回答完全无关、包含不当内容或明显不合理时才标记为不合法
-5. 确保提取的信息准确、完整且符合预期格式"""
+3. 如果提供了预定义选项，用户选择这些选项时都应该接受；自定义输入应与选项主题相关
+4. 对于昵称/姓名类问题，任何非空的合理字符串（包括简短的如"ee"、"aa"、"007"等）都应该接受
+5. 只有当用户回答完全无关、包含不当内容或明显不合理时才标记为不合法
+6. 确保提取的信息准确、完整且符合预期格式"""
 
 # Validation template for buttons with text input
 BUTTONS_WITH_TEXT_VALIDATION_TEMPLATE = """用户针对以下问题进行了输入：
@@ -193,7 +221,9 @@ VARIABLE_DEFAULT_VALUE = "UNKNOWN"
 # Context generation constants
 CONTEXT_QUESTION_MARKER = "# 相关问题"
 CONTEXT_CONVERSATION_MARKER = "# 对话上下文"
+CONTEXT_BUTTON_OPTIONS_MARKER = "## 预定义选项"
 
 # Context generation templates
 CONTEXT_QUESTION_TEMPLATE = f"{CONTEXT_QUESTION_MARKER}\n{{question}}"
 CONTEXT_CONVERSATION_TEMPLATE = f"{CONTEXT_CONVERSATION_MARKER}\n{{content}}"
+CONTEXT_BUTTON_OPTIONS_TEMPLATE = f"{CONTEXT_BUTTON_OPTIONS_MARKER}\n可选的预定义选项包括：{{button_options}}\n注意：用户如果选择了这些选项，都应该接受；如果输入了自定义内容，应检查是否与选项主题相关。"

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow/core.py

@@ -60,6 +60,7 @@ class MarkdownFlow:
     _document_prompt: str | None
     _interaction_prompt: str | None
     _interaction_error_prompt: str | None
+    _max_context_length: int
     _blocks: list[Block] | None
     _interaction_configs: dict[int, InteractionValidationConfig]
 
@@ -70,6 +71,7 @@ class MarkdownFlow:
         document_prompt: str | None = None,
         interaction_prompt: str | None = None,
         interaction_error_prompt: str | None = None,
+        max_context_length: int = 0,
     ):
         """
         Initialize MarkdownFlow instance.
@@ -80,12 +82,14 @@ class MarkdownFlow:
             document_prompt: Document-level system prompt
             interaction_prompt: Interaction content rendering prompt
             interaction_error_prompt: Interaction error rendering prompt
+            max_context_length: Maximum number of context messages to keep (0 = unlimited)
         """
         self._document = document
         self._llm_provider = llm_provider
         self._document_prompt = document_prompt
         self._interaction_prompt = interaction_prompt or DEFAULT_INTERACTION_PROMPT
         self._interaction_error_prompt = interaction_error_prompt or DEFAULT_INTERACTION_ERROR_PROMPT
+        self._max_context_length = max_context_length
         self._blocks = None
         self._interaction_configs: dict[int, InteractionValidationConfig] = {}
 
@@ -110,6 +114,44 @@ class MarkdownFlow:
         else:
             raise ValueError(UNSUPPORTED_PROMPT_TYPE_ERROR.format(prompt_type=prompt_type))
 
+    def _truncate_context(
+        self,
+        context: list[dict[str, str]] | None,
+    ) -> list[dict[str, str]] | None:
+        """
+        Filter and truncate context to specified maximum length.
+
+        Processing steps:
+        1. Filter out messages with empty content (empty string or whitespace only)
+        2. Truncate to max_context_length if configured (0 = unlimited)
+
+        Args:
+            context: Original context list
+
+        Returns:
+            Filtered and truncated context. Returns None if no valid messages remain.
+        """
+        if not context:
+            return None
+
+        # Step 1: Filter out messages with empty or whitespace-only content
+        filtered_context = [msg for msg in context if msg.get("content", "").strip()]
+
+        # Return None if no valid messages remain after filtering
+        if not filtered_context:
+            return None
+
+        # Step 2: Truncate to max_context_length if configured
+        if self._max_context_length == 0:
+            # No limit, return all filtered messages
+            return filtered_context
+
+        # Keep the most recent N messages
+        if len(filtered_context) > self._max_context_length:
+            return filtered_context[-self._max_context_length :]
+
+        return filtered_context
+
     @property
     def document(self) -> str:
         """Get document content."""
@@ -210,7 +252,7 @@ class MarkdownFlow:
         if block.block_type == BlockType.INTERACTION:
             if user_input is None:
                 # Render interaction content
-                return self._process_interaction_render(block_index, mode, variables)
+                return self._process_interaction_render(block_index, mode, context, variables)
             # Process user input
             return self._process_interaction_input(block_index, user_input, mode, context, variables)
 
@@ -231,8 +273,11 @@ class MarkdownFlow:
         variables: dict[str, str | list[str]] | None,
     ):
         """Process content block."""
-        # Build messages
-        messages = self._build_content_messages(block_index, variables)
+        # Truncate context to configured maximum length
+        truncated_context = self._truncate_context(context)
+
+        # Build messages with context
+        messages = self._build_content_messages(block_index, variables, truncated_context)
 
         if mode == ProcessMode.PROMPT_ONLY:
             return LLMResult(prompt=messages[-1]["content"], metadata={"messages": messages})
@@ -266,7 +311,13 @@ class MarkdownFlow:
 
         return LLMResult(content=content)
 
-    def _process_interaction_render(self, block_index: int, mode: ProcessMode, variables: dict[str, str | list[str]] | None = None):
+    def _process_interaction_render(
+        self,
+        block_index: int,
+        mode: ProcessMode,
+        context: list[dict[str, str]] | None = None,
+        variables: dict[str, str | list[str]] | None = None,
+    ):
         """Process interaction content rendering."""
         block = self.get_block(block_index)
 
@@ -283,8 +334,11 @@ class MarkdownFlow:
             # Unable to extract, return processed content
             return LLMResult(content=processed_block.content)
 
-        # Build render messages
-        messages = self._build_interaction_render_messages(question_text)
+        # Truncate context to configured maximum length
+        truncated_context = self._truncate_context(context)
+
+        # Build render messages with context
+        messages = self._build_interaction_render_messages(question_text, truncated_context)
 
         if mode == ProcessMode.PROMPT_ONLY:
             return LLMResult(
@@ -356,7 +410,7 @@ class MarkdownFlow:
         # Basic validation
         if not user_input or not any(values for values in user_input.values()):
             error_msg = INPUT_EMPTY_ERROR
-            return self._render_error(error_msg, mode)
+            return self._render_error(error_msg, mode, context)
 
         # Get the target variable value from user_input
         target_values = user_input.get(target_variable, [])
@@ -370,24 +424,103 @@ class MarkdownFlow:
 
         if "error" in parse_result:
             error_msg = INTERACTION_PARSE_ERROR.format(error=parse_result["error"])
-            return self._render_error(error_msg, mode)
+            return self._render_error(error_msg, mode, context)
 
         interaction_type = parse_result.get("type")
 
         # Process user input based on interaction type
         if interaction_type in [
-            InteractionType.BUTTONS_ONLY,
             InteractionType.BUTTONS_WITH_TEXT,
-            InteractionType.BUTTONS_MULTI_SELECT,
             InteractionType.BUTTONS_MULTI_WITH_TEXT,
         ]:
-            # All button types: validate user input against available buttons
+            # Buttons with text input: smart validation (match buttons first, then LLM validate custom text)
+            buttons = parse_result.get("buttons", [])
+
+            # Step 1: Match button values
+            matched_values, unmatched_values = self._match_button_values(buttons, target_values)
+
+            # Step 2: If there are unmatched values (custom text), validate with LLM
+            if unmatched_values:
+                # Create user_input for LLM validation (only custom text)
+                custom_input = {target_variable: unmatched_values}
+
+                validation_result = self._process_llm_validation(
+                    block_index=block_index,
+                    user_input=custom_input,
+                    target_variable=target_variable,
+                    mode=mode,
+                    context=context,
+                )
+
+                # Handle validation result based on mode
+                if mode == ProcessMode.PROMPT_ONLY:
+                    # Return validation prompt
+                    return validation_result
+
+                if mode == ProcessMode.COMPLETE:
+                    # Check if validation passed
+                    if isinstance(validation_result, LLMResult) and validation_result.variables:
+                        validated_values = validation_result.variables.get(target_variable, [])
+                        # Merge matched button values + validated custom text
+                        all_values = matched_values + validated_values
+                        return LLMResult(
+                            content="",
+                            variables={target_variable: all_values},
+                            metadata={
+                                "interaction_type": str(interaction_type),
+                                "matched_button_values": matched_values,
+                                "validated_custom_values": validated_values,
+                            },
+                        )
+                    else:
+                        # Validation failed, return error
+                        return validation_result
+
+                if mode == ProcessMode.STREAM:
+                    # For stream mode, collect validation result
+                    def stream_merge_generator():
+                        # Consume the validation stream
+                        for result in validation_result:  # type: ignore[attr-defined]
+                            if isinstance(result, LLMResult) and result.variables:
+                                validated_values = result.variables.get(target_variable, [])
+                                all_values = matched_values + validated_values
+                                yield LLMResult(
+                                    content="",
+                                    variables={target_variable: all_values},
+                                    metadata={
+                                        "interaction_type": str(interaction_type),
+                                        "matched_button_values": matched_values,
+                                        "validated_custom_values": validated_values,
+                                    },
+                                )
+                            else:
+                                # Validation failed
+                                yield result
+
+                    return stream_merge_generator()
+            else:
+                # All values matched buttons, return directly
+                return LLMResult(
+                    content="",
+                    variables={target_variable: matched_values},
+                    metadata={
+                        "interaction_type": str(interaction_type),
+                        "all_matched_buttons": True,
+                    },
+                )
+
+        if interaction_type in [
+            InteractionType.BUTTONS_ONLY,
+            InteractionType.BUTTONS_MULTI_SELECT,
+        ]:
+            # Pure button types: only basic button validation (no LLM)
             return self._process_button_validation(
                 parse_result,
                 target_values,
                 target_variable,
                 mode,
                 interaction_type,
+                context,
             )
 
         if interaction_type == InteractionType.NON_ASSIGNMENT_BUTTON:
@@ -403,19 +536,50 @@ class MarkdownFlow:
             )
 
         # Text-only input type: ?[%{{sys_user_nickname}}...question]
-        # For text-only inputs, directly use the target variable values
+        # Use LLM validation to check if input is relevant to the question
         if target_values:
-            return LLMResult(
-                content="",
-                variables={target_variable: target_values},
-                metadata={
-                    "interaction_type": "text_only",
-                    "target_variable": target_variable,
-                    "values": target_values,
-                },
+            return self._process_llm_validation(
+                block_index=block_index,
+                user_input=user_input,
+                target_variable=target_variable,
+                mode=mode,
+                context=context,
             )
         error_msg = f"No input provided for variable '{target_variable}'"
-        return self._render_error(error_msg, mode)
+        return self._render_error(error_msg, mode, context)
+
+    def _match_button_values(
+        self,
+        buttons: list[dict[str, str]],
+        target_values: list[str],
+    ) -> tuple[list[str], list[str]]:
+        """
+        Match user input values against button options.
+
+        Args:
+            buttons: List of button dictionaries with 'display' and 'value' keys
+            target_values: User input values to match
+
+        Returns:
+            Tuple of (matched_values, unmatched_values)
+            - matched_values: Values that match button options (using button value)
+            - unmatched_values: Values that don't match any button
+        """
+        matched_values = []
+        unmatched_values = []
+
+        for value in target_values:
+            matched = False
+            for button in buttons:
+                if value in [button["display"], button["value"]]:
+                    matched_values.append(button["value"])  # Use button value
+                    matched = True
+                    break
+
+            if not matched:
+                unmatched_values.append(value)
+
+        return matched_values, unmatched_values
 
     def _process_button_validation(
         self,
@@ -424,6 +588,7 @@ class MarkdownFlow:
         target_variable: str,
         mode: ProcessMode,
         interaction_type: InteractionType,
+        context: list[dict[str, str]] | None = None,
     ) -> LLMResult | Generator[LLMResult, None, None]:
         """
         Simplified button validation with new input format.
@@ -434,6 +599,7 @@ class MarkdownFlow:
             target_variable: Target variable name
             mode: Processing mode
             interaction_type: Type of interaction
+            context: Conversation history context (optional)
         """
         buttons = parse_result.get("buttons", [])
         is_multi_select = interaction_type in [
@@ -459,7 +625,7 @@ class MarkdownFlow:
             # Pure button mode requires input
             button_displays = [btn["display"] for btn in buttons]
             error_msg = f"Please select from: {', '.join(button_displays)}"
-            return self._render_error(error_msg, mode)
+            return self._render_error(error_msg, mode, context)
 
         # Validate input values against available buttons
         valid_values = []
@@ -484,7 +650,7 @@ class MarkdownFlow:
         if invalid_values and not allow_text_input:
             button_displays = [btn["display"] for btn in buttons]
             error_msg = f"Invalid options: {', '.join(invalid_values)}. Please select from: {', '.join(button_displays)}"
-            return self._render_error(error_msg, mode)
+            return self._render_error(error_msg, mode, context)
 
         # Success: return validated values
         return LLMResult(
@@ -505,10 +671,11 @@ class MarkdownFlow:
         user_input: dict[str, list[str]],
         target_variable: str,
         mode: ProcessMode,
+        context: list[dict[str, str]] | None = None,
     ) -> LLMResult | Generator[LLMResult, None, None]:
         """Process LLM validation."""
         # Build validation messages
-        messages = self._build_validation_messages(block_index, user_input, target_variable)
+        messages = self._build_validation_messages(block_index, user_input, target_variable, context)
 
         if mode == ProcessMode.PROMPT_ONLY:
             return LLMResult(
@@ -612,9 +779,18 @@ class MarkdownFlow:
 
             return stream_generator()
 
-    def _render_error(self, error_message: str, mode: ProcessMode) -> LLMResult | Generator[LLMResult, None, None]:
+    def _render_error(
+        self,
+        error_message: str,
+        mode: ProcessMode,
+        context: list[dict[str, str]] | None = None,
+    ) -> LLMResult | Generator[LLMResult, None, None]:
         """Render user-friendly error message."""
-        messages = self._build_error_render_messages(error_message)
+        # Truncate context to configured maximum length
+        truncated_context = self._truncate_context(context)
+
+        # Build error messages with context
+        messages = self._build_error_render_messages(error_message, truncated_context)
 
         if mode == ProcessMode.PROMPT_ONLY:
             return LLMResult(
@@ -645,6 +821,7 @@ class MarkdownFlow:
         self,
         block_index: int,
         variables: dict[str, str | list[str]] | None,
+        context: list[dict[str, str]] | None = None,
     ) -> list[dict[str, str]]:
         """Build content block messages."""
         block = self.get_block(block_index)
@@ -671,18 +848,22 @@ class MarkdownFlow:
             # No document prompt but has preserved content, add explanation alone
             messages.append({"role": "system", "content": OUTPUT_INSTRUCTION_EXPLANATION.strip()})
 
-        # For most content blocks, historical conversation context is not needed
-        # because each document block is an independent instruction
-        # If future specific scenarios need context, logic can be added here
-        # if context:
-        #     messages.extend(context)
+        # Add conversation history context if provided
+        # Context is inserted after system message and before current user message
+        truncated_context = self._truncate_context(context)
+        if truncated_context:
+            messages.extend(truncated_context)
 
         # Add processed content as user message (as instruction to LLM)
         messages.append({"role": "user", "content": block_content})
 
         return messages
 
-    def _build_interaction_render_messages(self, question_text: str) -> list[dict[str, str]]:
+    def _build_interaction_render_messages(
+        self,
+        question_text: str,
+        context: list[dict[str, str]] | None = None,
+    ) -> list[dict[str, str]]:
         """Build interaction rendering messages."""
         # Check if using custom interaction prompt
         if self._interaction_prompt != DEFAULT_INTERACTION_PROMPT:
@@ -696,15 +877,32 @@ class MarkdownFlow:
         messages = []
 
         messages.append({"role": "system", "content": render_prompt})
+
+        # NOTE: Context is temporarily disabled for interaction rendering
+        # Mixing conversation history with interaction content rewriting can cause issues
+        # The context parameter is kept in the signature for future use
+        # truncated_context = self._truncate_context(context)
+        # if truncated_context:
+        #     messages.extend(truncated_context)
+
         messages.append({"role": "user", "content": question_text})
 
         return messages
 
-    def _build_validation_messages(self, block_index: int, user_input: dict[str, list[str]], target_variable: str) -> list[dict[str, str]]:
+    def _build_validation_messages(
+        self,
+        block_index: int,
+        user_input: dict[str, list[str]],
+        target_variable: str,
+        context: list[dict[str, str]] | None = None,
+    ) -> list[dict[str, str]]:
         """Build validation messages."""
         block = self.get_block(block_index)
         config = self.get_interaction_validation_config(block_index)
 
+        # Truncate context to configured maximum length
+        truncated_context = self._truncate_context(context)
+
         if config and config.validation_template:
             # Use custom validation template
             validation_prompt = config.validation_template
@@ -716,6 +914,7 @@ class MarkdownFlow:
         else:
             # Use smart default validation template
             from .utils import (
+                InteractionParser,
                 extract_interaction_question,
                 generate_smart_validation_template,
             )
@@ -723,11 +922,17 @@ class MarkdownFlow:
             # Extract interaction question
             interaction_question = extract_interaction_question(block.content)
 
-            # Generate smart validation template
+            # Parse interaction to extract button information
+            parser = InteractionParser()
+            parse_result = parser.parse(block.content)
+            buttons = parse_result.get("buttons") if "buttons" in parse_result else None
+
+            # Generate smart validation template with context and buttons
             validation_template = generate_smart_validation_template(
                 target_variable,
-                context=None,  # Could consider passing context here
+                context=truncated_context,
                 interaction_question=interaction_question,
+                buttons=buttons,
             )
 
             # Replace template variables
@@ -740,6 +945,11 @@ class MarkdownFlow:
         messages = []
 
         messages.append({"role": "system", "content": system_message})
+
+        # Add conversation history context if provided (only if not using custom template)
+        if truncated_context and not (config and config.validation_template):
+            messages.extend(truncated_context)
+
         messages.append({"role": "user", "content": validation_prompt})
 
         return messages
@@ -770,7 +980,11 @@ class MarkdownFlow:
 
         return messages
 
-    def _build_error_render_messages(self, error_message: str) -> list[dict[str, str]]:
+    def _build_error_render_messages(
+        self,
+        error_message: str,
+        context: list[dict[str, str]] | None = None,
+    ) -> list[dict[str, str]]:
         """Build error rendering messages."""
         render_prompt = f"""{self._interaction_error_prompt}
 
@@ -783,6 +997,12 @@ Original Error: {error_message}
             messages.append({"role": "system", "content": self._document_prompt})
 
         messages.append({"role": "system", "content": render_prompt})
+
+        # Add conversation history context if provided
+        truncated_context = self._truncate_context(context)
+        if truncated_context:
+            messages.extend(truncated_context)
+
         messages.append({"role": "user", "content": error_message})
 
         return messages

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow/llm.py

@@ -43,7 +43,8 @@ class LLMProvider(ABC):
         Non-streaming LLM call.
 
         Args:
-            messages: Message list in format [{"role": "system/user/assistant", "content": "..."}]
+            messages: Message list in format [{"role": "system/user/assistant", "content": "..."}].
+                      This list already includes conversation history context merged by MarkdownFlow.
 
         Returns:
             str: LLM response content
@@ -58,7 +59,8 @@ class LLMProvider(ABC):
         Streaming LLM call.
 
         Args:
-            messages: Message list in format [{"role": "system/user/assistant", "content": "..."}]
+            messages: Message list in format [{"role": "system/user/assistant", "content": "..."}].
+                      This list already includes conversation history context merged by MarkdownFlow.
 
         Yields:
             str: Incremental LLM response content

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow/utils.py

@@ -19,6 +19,7 @@ from .constants import (
     COMPILED_PERCENT_VARIABLE_REGEX,
     COMPILED_PRESERVE_FENCE_REGEX,
     COMPILED_SINGLE_PIPE_SPLIT_REGEX,
+    CONTEXT_BUTTON_OPTIONS_TEMPLATE,
     CONTEXT_CONVERSATION_TEMPLATE,
     CONTEXT_QUESTION_MARKER,
     CONTEXT_QUESTION_TEMPLATE,
@@ -479,6 +480,7 @@ def generate_smart_validation_template(
     target_variable: str,
     context: list[dict[str, Any]] | None = None,
     interaction_question: str | None = None,
+    buttons: list[dict[str, str]] | None = None,
 ) -> str:
     """
     Generate smart validation template based on context and question.
@@ -487,19 +489,28 @@ def generate_smart_validation_template(
         target_variable: Target variable name
         context: Context message list with role and content fields
         interaction_question: Question text from interaction block
+        buttons: Button options list with display and value fields
 
     Returns:
         Generated validation template
     """
     # Build context information
     context_info = ""
-    if interaction_question or context:
+    if interaction_question or context or buttons:
         context_parts = []
 
         # Add question information (most important, put first)
         if interaction_question:
             context_parts.append(CONTEXT_QUESTION_TEMPLATE.format(question=interaction_question))
 
+        # Add button options information
+        if buttons:
+            button_displays = [btn.get("display", "") for btn in buttons if btn.get("display")]
+            if button_displays:
+                button_options_str = ", ".join(button_displays)
+                button_info = CONTEXT_BUTTON_OPTIONS_TEMPLATE.format(button_options=button_options_str)
+                context_parts.append(button_info)
+
         # Add conversation context
         if context:
             for msg in context:

{markdown_flow-0.2.18 → markdown_flow-0.2.23}/markdown_flow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.2.18
+Version: 0.2.23
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues

markdown_flow-0.2.23/tests/test_preserved_simple.py

@@ -0,0 +1,262 @@
+"""
+增强的固定输出测试框架
+
+使用方法：
+1. 修改 document 变量，写入你的 MarkdownFlow 文档
+2. 修改 block_index，指定要测试的块索引
+3. 修改 variables，设置变量值（如果需要）
+4. 修改 context，添加历史对话（如果需要）
+5. 修改 max_context_length，控制 context 长度（如果需要）
+6. 运行测试，查看输出
+
+测试重点：
+- 检查 XML 标记 <preserve_or_translate> 是否正确使用
+- 检查 system 消息中是否包含约束提示词
+- 检查 user 消息中是否不包含约束提示词
+- 检查 LLM 输出是否不包含 XML 标记
+- 检查 context 是否正确合并到 messages 中
+- 检查 max_context_length 是否正确截断 context
+- 检查变量替换是否正确
+"""
+
+import os
+import sys
+
+
+# 添加项目路径
+project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, project_root)
+
+from llm import create_llm_provider  # noqa: E402
+
+from markdown_flow import MarkdownFlow, ProcessMode  # noqa: E402
+from markdown_flow.llm import LLMResult  # noqa: E402
+
+
+def test_preserved_output():
+    """测试固定输出功能"""
+    print("\n" + "=" * 60)
+    print("🔖 固定输出测试")
+    print("=" * 60)
+
+    # ========== 配置区域 - 修改这里 ==========
+    # 你的 MarkdownFlow 文档
+    document = """
+===# 💖七夕约会全阶段攻略 ===
+
+=== 选择你的 MBTI 类型 ===
+?[%{{mbti}}ENFJ|ENFP|ENTJ|ENTP|ESFJ|ESFP|ESTJ|ESTP|INFJ|INFP|INTJ|INTP|ISFJ|ISFP|ISTJ|ISTP]
+
+===你现在最关心哪个阶段？ ===
+?[%{{攻略}}脱单|热恋|相守]
+
+给{{mbti}}一句有关{{攻略}}的七夕祝福，带七夕节明显的意境。
+
+!===
+## {{攻略}}｜专属恋爱指南 for {{mbti}}
+!===
+
+"""
+
+    # 要测试的块索引
+    block_index = 4
+
+    # 变量（如果需要）
+    # 支持字符串或字符串列表
+    variables: dict[str, str | list[str]] = {
+        "mbti": "INFP",  # 单个值
+        "攻略": "热恋",  # 单个值
+        # "skills": ["Python", "JavaScript"],  # 多选值示例
+    }
+
+    # 历史对话 context（如果需要）
+    # Context 会被自动合并到 messages 中，插入到 system 消息之后、当前 user 消息之前
+    context: list[dict[str, str]] | None = [
+        {"role": "user", "content": "你好，我是 INFP 类型的人"},
+        {"role": "assistant", "content": "你好！INFP 通常充满创造力和理想主义，很高兴认识你！"},
+        {"role": "user", "content": "我想了解七夕约会的建议"},
+        {"role": "assistant", "content": "太好了！七夕是个浪漫的节日，我会为你量身定制约会攻略。"},
+    ]
+
+    # Context 长度控制（0 = 不限制）
+    # 如果 context 太长，可以设置这个参数只保留最近 N 条消息
+    max_context_length: int = 0  # 0 表示不限制，可以设为 5、10 等
+
+    # 文档提示词（如果需要）
+    document_prompt: str | None = """你扮演七夕的月老，让这一天的天下有情人都能甜蜜约会，永浴爱河。
+
+## 任务
+- 提示词都是讲解指令，遵从指令要求做信息的讲解，不要回应指令。
+- 用第一人称一对一讲解，像现场面对面交流一样
+- 结合用户的不同特点，充分共情和举例
+
+## 风格
+- 情绪：热烈浪漫，治愈温暖，充满感染力
+- 表达：多用 emoji ，多用感叹词
+- 符合七夕节日气氛，带一些诗意和神秘
+
+"""
+    # =========================================
+
+    try:
+        llm_provider = create_llm_provider()
+
+        # 打印测试配置
+        print("\n📋 测试配置")
+        print("-" * 60)
+        print(f"Block Index: {block_index}")
+        print(f"Variables: {variables if variables else '无'}")
+        print(f"Context: {len(context) if context else 0} 条历史消息")
+        print(f"Max Context Length: {max_context_length} {'(不限制)' if max_context_length == 0 else f'(最多保留 {max_context_length} 条)'}")
+
+        # 创建 MarkdownFlow 实例（添加 max_context_length 参数）
+        mf = MarkdownFlow(
+            document,
+            llm_provider=llm_provider,
+            document_prompt=document_prompt if document_prompt else None,
+            max_context_length=max_context_length,
+        )
+
+        # 测试 PROMPT_ONLY 模式 - 查看消息结构
+        print("\n📝 测试 PROMPT_ONLY 模式")
+        print("-" * 60)
+
+        result_prompt_raw = mf.process(
+            block_index=block_index,
+            mode=ProcessMode.PROMPT_ONLY,
+            context=context if context else None,
+            variables=variables if variables else None,
+        )
+
+        # 确保是 LLMResult 类型
+        assert isinstance(result_prompt_raw, LLMResult)
+        result_prompt = result_prompt_raw
+
+        # 打印消息结构
+        if result_prompt.metadata and "messages" in result_prompt.metadata:
+            messages = result_prompt.metadata["messages"]
+            print(f"\n消息数量: {len(messages)}")
+
+            # 检查 context 是否被正确合并
+            if context:
+                expected_context_count = min(len(context), max_context_length) if max_context_length > 0 else len(context)
+                context_messages = [m for m in messages if m.get("role") in ["user", "assistant"] and m != messages[-1]]
+                actual_context_count = len(context_messages)
+                print(f"Context 消息: {actual_context_count} 条 (预期: {expected_context_count} 条)")
+                if actual_context_count == expected_context_count:
+                    print("✅ Context 正确合并到 messages")
+                else:
+                    print(f"⚠️  Context 数量不匹配")
+            print()
+
+            for i, msg in enumerate(messages, 1):
+                role = msg.get("role", "")
+                content = msg.get("content", "")
+
+                print(f"{'=' * 60}")
+                print(f"消息 {i} [{role.upper()}]")
+                print(f"{'=' * 60}")
+                print(content)
+                print()
+
+                # 关键检查
+                if role == "system":
+                    has_xml_instruction = "<preserve_or_translate>" in content
+                    print(f"✅ system 包含 XML 标记说明: {has_xml_instruction}")
+
+                elif role == "user":
+                    has_xml_tag = "<preserve_or_translate>" in content
+                    has_explanation = "不要输出<preserve_or_translate>" in content
+                    print(f"✅ user 包含 XML 标记: {has_xml_tag}")
+                    print(f"❌ user 不应包含说明（应在system）: {not has_explanation}")
+
+                    # 检查变量是否被正确替换
+                    if variables:
+                        replaced_vars = []
+                        for var_name, var_value in variables.items():
+                            if isinstance(var_value, list):
+                                var_str = ", ".join(var_value)
+                            else:
+                                var_str = var_value
+                            if var_str in content:
+                                replaced_vars.append(f"{var_name}={var_str}")
+                        if replaced_vars:
+                            print(f"✅ 变量已替换: {', '.join(replaced_vars)}")
+
+                print()
+
+        # 测试 COMPLETE 模式 - 查看 LLM 输出
+        print("\n📝 测试 COMPLETE 模式")
+        print("-" * 60)
+
+        result_complete_raw = mf.process(
+            block_index=block_index,
+            mode=ProcessMode.COMPLETE,
+            context=context if context else None,
+            variables=variables if variables else None,
+        )
+
+        # 确保是 LLMResult 类型
+        assert isinstance(result_complete_raw, LLMResult)
+        result_complete = result_complete_raw
+
+        print("\n" + "=" * 60)
+        print("LLM 输出结果")
+        print("=" * 60)
+        print(result_complete.content)
+        print("=" * 60)
+
+        # 输出检查
+        has_xml_in_output = "<preserve_or_translate>" in result_complete.content
+        print(f"\n✅ 输出不包含 XML 标记: {not has_xml_in_output}")
+
+        # 使用统计
+        if result_complete.metadata and "usage" in result_complete.metadata:
+            usage = result_complete.metadata["usage"]
+            if usage:
+                print(f"📊 Token 使用: {usage.get('total_tokens', 0)} tokens")
+
+        # 测试总结
+        print("\n" + "=" * 60)
+        print("📊 测试总结")
+        print("=" * 60)
+        test_results = []
+
+        # 检查变量替换
+        if variables:
+            for var_name, var_value in variables.items():
+                var_str = ", ".join(var_value) if isinstance(var_value, list) else var_value
+                if var_str in result_complete.content or "{{" + var_name + "}}" not in document:
+                    test_results.append(f"✅ 变量 '{var_name}' 已正确处理")
+                else:
+                    test_results.append(f"❌ 变量 '{var_name}' 未被替换")
+
+        # 检查 context
+        if context:
+            if max_context_length > 0:
+                test_results.append(f"✅ Context 长度控制: {max_context_length} 条")
+            else:
+                test_results.append(f"✅ Context 全部保留: {len(context)} 条")
+
+        # 检查 XML 标记
+        if not has_xml_in_output:
+            test_results.append("✅ LLM 输出不包含 XML 标记")
+        else:
+            test_results.append("❌ LLM 输出包含 XML 标记（应该被过滤）")
+
+        for result in test_results:
+            print(result)
+
+        print("\n" + "=" * 60)
+        print("✨ 测试完成！")
+        print("=" * 60)
+
+    except Exception as e:
+        print(f"\n❌ 测试失败: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    test_preserved_output()

markdown_flow-0.2.18/tests/test_preserved_simple.py

@@ -1,170 +0,0 @@
-"""
-简单的固定输出测试框架
-
-使用方法：
-1. 修改 document 变量，写入你的 MarkdownFlow 文档
-2. 修改 block_index，指定要测试的块索引
-3. 修改 variables，设置变量值（如果需要）
-4. 运行测试，查看输出
-
-测试重点：
-- 检查 XML 标记 <preserve_or_translate> 是否正确使用
-- 检查 system 消息中是否包含约束提示词
-- 检查 user 消息中是否不包含约束提示词
-- 检查 LLM 输出是否不包含 XML 标记
-"""
-
-import os
-import sys
-
-
-# 添加项目路径
-project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
-sys.path.insert(0, project_root)
-
-from llm import create_llm_provider  # noqa: E402
-
-from markdown_flow import MarkdownFlow, ProcessMode  # noqa: E402
-from markdown_flow.llm import LLMResult  # noqa: E402
-
-
-def test_preserved_output():
-    """测试固定输出功能"""
-    print("\n" + "=" * 60)
-    print("🔖 固定输出测试")
-    print("=" * 60)
-
-    # ========== 配置区域 - 修改这里 ==========
-    # 你的 MarkdownFlow 文档
-    document = """
-=== **下面我们做个练习，输入一个变量代表风格。** ===
-
-邀请用户输入喜欢的讲述风格。
-"""
-
-    # 要测试的块索引
-    block_index = 0
-
-    # 变量（如果需要）
-    variables: dict[str, str | list[str]] = {}
-
-    # 文档提示词（如果需要）
-    document_prompt: str | None = """## 角色
-你是一个丰富经验的课程讲师，擅长因材施教。
-
-## 任务
-- 你正在一对一讲解内容，用户只有一个人，要有第一人称的对话感。
-- 遵从指令要求向用户讲课，不可丢失信息，不能改变指令原意，不要增加内容，不要改变顺序
-- 结合用户的具体情况做讲解，用学员能听懂的方式讲课，激发用户学习动力。
-- 不需要回应指令，禁止展示指令的执行要求。
-- 不要引导下一步动作，比如提问或设问
-
-## 输出
-- 按照 Markdown 格式输出
-- 重点内容（关键步骤/颠覆认知点/观点总结）做加粗处理
-- 讲解风格要口语化、通俗易懂、避免使用技术/编程术语
-
-# 课程逻辑
-1. 谁想做什么遇到了什么痛点
-2. 旧方法为何无效？案例对比
-3. 新解决方案的核心差异、适用条件
-4. 用比喻/故事/数据辅助理解。
-5. 简化的认知框架
-6. 迁移到其他领域应用
-7. 给到具体可操作的下一步行动
-
-使用英文输出内容
-"""
-    # =========================================
-
-    try:
-        llm_provider = create_llm_provider()
-
-        # 创建 MarkdownFlow 实例
-        mf = MarkdownFlow(
-            document,
-            llm_provider=llm_provider,
-            document_prompt=document_prompt if document_prompt else None,
-        )
-
-        # 测试 PROMPT_ONLY 模式 - 查看消息结构
-        print("\n📝 测试 PROMPT_ONLY 模式")
-        print("-" * 60)
-
-        result_prompt_raw = mf.process(
-            block_index=block_index,
-            mode=ProcessMode.PROMPT_ONLY,
-            variables=variables if variables else None,
-        )
-
-        # 确保是 LLMResult 类型
-        assert isinstance(result_prompt_raw, LLMResult)
-        result_prompt = result_prompt_raw
-
-        # 打印消息结构
-        if result_prompt.metadata and "messages" in result_prompt.metadata:
-            messages = result_prompt.metadata["messages"]
-            print(f"\n消息数量: {len(messages)}\n")
-
-            for i, msg in enumerate(messages, 1):
-                role = msg.get("role", "")
-                content = msg.get("content", "")
-
-                print(f"{'=' * 60}")
-                print(f"消息 {i} [{role.upper()}]")
-                print(f"{'=' * 60}")
-                print(content)
-                print()
-
-                # 关键检查
-                if role == "system":
-                    has_xml_instruction = "<preserve_or_translate>" in content
-                    print(f"✅ system 包含 XML 标记说明: {has_xml_instruction}")
-
-                elif role == "user":
-                    has_xml_tag = "<preserve_or_translate>" in content
-                    has_explanation = "不要输出<preserve_or_translate>" in content
-                    print(f"✅ user 包含 XML 标记: {has_xml_tag}")
-                    print(f"❌ user 不应包含说明（应在system）: {not has_explanation}")
-
-                print()
-
-        # 测试 COMPLETE 模式 - 查看 LLM 输出
-        print("\n📝 测试 COMPLETE 模式")
-        print("-" * 60)
-
-        result_complete_raw = mf.process(
-            block_index=block_index,
-            mode=ProcessMode.COMPLETE,
-            variables=variables if variables else None,
-        )
-
-        # 确保是 LLMResult 类型
-        assert isinstance(result_complete_raw, LLMResult)
-        result_complete = result_complete_raw
-
-        print("\n" + "=" * 60)
-        print("LLM 输出结果")
-        print("=" * 60)
-        print(result_complete.content)
-        print("=" * 60)
-
-        # 输出检查
-        has_xml_in_output = "<preserve_or_translate>" in result_complete.content
-        print(f"\n✅ 输出不包含 XML 标记: {not has_xml_in_output}")
-
-        # 使用统计
-        if result_complete.metadata and "usage" in result_complete.metadata:
-            usage = result_complete.metadata["usage"]
-            if usage:
-                print(f"📊 Token 使用: {usage.get('total_tokens', 0)} tokens")
-
-    except Exception as e:
-        print(f"\n❌ 测试失败: {e}")
-        import traceback
-
-        traceback.print_exc()
-
-
-if __name__ == "__main__":
-    test_preserved_output()