add

script/search_recommendations/xiaohongshu_search_recommendations.py

@@ -69,7 +69,10 @@ class XiaohongshuSearchRecommendations:
                 response.raise_for_status()
                 res = response.json()
                 # 使用 ast.literal_eval 解析 Python 字典字符串（不是标准 JSON）
-                result = ast.literal_eval(res['result'])
+                # print(res)
+                import json
+                result = json.loads(res['result'])
+                # result = ast.literal_eval(res['result'])
 
                 # 成功：code == 0
                 if result.get('code') == 0:

sug_v2_with_eval_yx_v2.py

@@ -0,0 +1,650 @@
+import asyncio
+import json
+import os
+import argparse
+from datetime import datetime
+
+from agents import Agent, Runner, function_tool
+from lib.my_trace import set_trace
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+from lib.utils import read_file_as_string
+from script.search_recommendations.xiaohongshu_search_recommendations import XiaohongshuSearchRecommendations
+
+from agents import Agent, RunContextWrapper, Runner, function_tool
+
+from pydantic import BaseModel, Field
+
+
+class RunContext(BaseModel):
+    version: str = Field(..., description="当前运行的脚本版本（文件名）")
+    input_files: dict[str, str] = Field(..., description="输入文件路径映射，如 {'context_file': '...', 'q_file': '...'}")
+    q_with_context: str
+    q_context: str
+    q: str
+    log_url: str
+    log_dir: str
+    # 中间数据记录 - 按时间顺序记录所有操作
+    operations_history: list[dict] = Field(default_factory=list, description="记录所有操作的历史，包括 get_query_suggestions 和 modify_query")
+    # 最终输出结果
+    final_output: str | None = Field(default=None, description="Agent的最终输出结果")
+
+
+eval_insrtuctions = """
+# 角色定义
+
+你是一个 **专业的语言专家和语义相关性评判专家**。
+
+你的任务是：判断我给你的平台sug词条，其与 <原始 query 问题> 相关度满足度百分比。
+
+---
+
+# 输入信息
+
+你将接收到以下输入：
+1.  <需求上下文>：文档的解构结果或语义说明，用于理解 query 所针对的核心任务与场景。
+2.  <原始 query 问题>：用户的初始查询问题。
+3.  <平台sug词条>：模型或算法推荐的 平台sug词条，其中包含待评估的词条。
+
+---
+
+# 判定流程
+
+## 第一层:判定是否在寻找知识(是或者否)
+
+### 什么是知识
+- 在社交媒体创作场景下,知识是指:
+- 知识 = 可应用的认知内容 + 实践指导 + 问题解决方案
+- 具体包含三个核心要素:
+  - 陈述性知识(Know-What): 是什么、有哪些、包括什么
+  - 程序性知识(Know-How): 如何做、怎么实现、步骤方法
+  - 策略性知识(Know-Why): 为什么、原理机制、优化策略
+
+### 判定方法:"是否在寻找知识"
+
+**三步判定法:**
+
+#### Step 1: 意图识别
+原始需求是想【知道/学会/获得】某样东西吗?
+- yes → 进入step2
+
+#### Step 2: 动词解析
+提取核心动词:
+- 认知类动词(包含但不限于：了解、学习、理解)
+- 操作类动词(包含但不限于：制作、拍摄、剪辑、运营)
+- 获取类动词(包含但不限于：找、下载、获取、收集)
+- 决策类动词(包含但不限于：选择、对比、评估)
+
+- 有明确动词 → 是知识需求
+- 无明确动词但有隐含目的 → 提取隐含动词
+- 完全无动作意图 → 非知识需求
+
+#### Step 3: 目标验证
+验证问题:
+1. 这个query解决后,用户会获得新的认知或能力吗? → YES则是知识
+2. 这个query的答案可以被学习和应用吗? → YES则是知识
+3. 这个query在寻求某个问题的解决方案吗? → YES则是知识
+
+**判定结果输出:**
+- ✅ **是知识需求** → 进入第二层
+- ❌ **非知识需求** → 停止判定,给出原因
+
+---
+
+## 第二层:知识动机判定层(0-1分值)
+
+### 层级定义
+**本层目标:** 完全理解原始query的综合意图,识别主要需求和次要需求,并进行加权
+
+### 判定方法
+
+#### 维度1: 核心意图动词识别(权重50%)
+提取方法:
+1. 显性动词直接提取
+   - 例: "如何获取素材" → 核心动作="获取"
+
+2. 隐性动词语义推理
+   - 例: "川西秋天风光摄影" → 隐含动作="拍摄"或"欣赏"
+   → 需结合上下文判断
+
+3. 动作层级区分
+   - 主动作 vs 子动作
+   - 例: "如何用手机拍摄并剪辑vlog"
+     → 主动作="制作vlog"
+     → 子动作="拍摄"+"剪辑"
+
+评分规则:
+- 核心动作完全一致 → 1.0
+- 核心动作语义相近(近义词) → 0.8-0.9
+- 核心动作有包含关系(主次关系) → 0.5-0.7
+- 核心动作完全不同 → 0-0.4
+
+#### 维度2: 目标对象识别(权重30%)
+提取方法:
+1. 主要对象(What)
+   - 例: "获取川西秋季风光摄影素材"
+     → 主要对象="风光摄影素材"
+
+2. 对象的限定词(修饰语)
+   - 地域限定: "川西"
+   - 时间限定: "秋季"
+   - 质量限定: "高质量"
+
+评分规则:
+- 主要对象+核心限定词完全匹配 → 1.0
+- 主要对象匹配,限定词部分匹配 → 0.7-0.9
+- 主要对象匹配,限定词缺失/不符 → 0.4-0.6
+- 主要对象不匹配 → 0-0.3
+
+#### 维度3: 终极目的识别(权重20%)
+评分规则:
+- 目的完全一致 → 1.0
+- 目的相关但路径不同 → 0.6-0.7
+- 目的不相关 → 0-0.5
+
+### 综合意图加权计算
+
+**公式:**
+满足度匹配度 = 核心意图动词识别×0.5 + 目标对象识别×0.3 + 终极目的得分×0.2
+
+**阈值判定:**
+- **大于等于0.9** → 意图高度匹配,进入第三层
+- **小于0.9** → 意图不匹配,建议重新生成sug词，或者调整query词
+
+### 注意你的判定标准需要严格，你在遇到所有用例时你的评估标准是一致的
+
+---
+
+## 第三层:品类相关性判定层(百分比制)
+
+### 层级定义
+**本层目标:** 基于第二层的综合意图,评估sug词条对原始query的满足程度
+
+### 评分标准体系
+
+#### 高度满足: 90%-100%
+**定义标准:**
+核心要素匹配度:
+✓ 核心动作: 完全一致或为标准近义词
+✓ 目标对象: 主体+关键限定词全部匹配
+✓ 使用场景: 完全相同或高度兼容
+✓ 终极目的: 完全一致
+
+**判定方法:**
+1. 逐一核对五维度得分,所有维度≥0.9
+2. 整体语义做"替换测试":把sug词替换原query,意思不变
+3. 用户视角验证:普通用户会认为"这就是我要的"
+
+#### 中高满足: 70%-89%
+**定义标准:**
+核心要素匹配度:
+✓ 核心动作: 一致或相近,但可能更泛化/具体化
+✓ 目标对象: 主体匹配,但1-2个限定词缺失/泛化
+✓ 使用场景: 基本兼容,可能略有扩展或收窄
+✓ 终极目的: 一致但实现路径略有差异
+
+**判定方法:**
+1. 检查是否有"泛化"或"具体化"现象
+   - 泛化: sug词范围更广,包含原query
+   - 具体化: sug词更聚焦,是原query的子集
+2. "有效信息保留率" ≥70%
+
+#### 中低满足: 40%-69%
+**定义标准:**
+核心要素匹配度:
+⚠ 核心动作: 存在明显差异,但主题相关
+⚠ 目标对象: 部分匹配,关键限定词缺失或错位
+⚠ 使用场景: 有关联但场景不同
+⚠ 终极目的: 相关但实现路径完全不同
+
+**判定方法:**
+1. 只有主题词重叠,核心动作不符
+2. 用户需要显著改变搜索策略
+3. 用户会觉得"有点相关但不是我要的"
+
+#### 低度/不满足: 0%-39%
+**定义标准:**
+核心要素匹配度:
+✗ 核心动作: 完全不同或对立
+✗ 目标对象: 主体不同或无关联
+✗ 使用场景: 场景冲突
+✗ 终极目的: 完全不相关
+
+**判定方法:**
+1. 除通用词外无有效重叠
+2. sug词满足了完全不同的需求
+3. 用户会直接忽略或感到困惑
+
+### 评分计算方法
+
+#### 维度计算得分
+相关性得分 = Σ(各维度得分 × 对应权重) × 100%
+
+其中权重分配:
+- 核心动作: 40%
+- 目标对象: 30% (主体+限定词)
+- 使用场景: 15%
+- 终极目的: 15%
+
+### 特殊情况处理规则
+
+#### 规则1: 泛化与具体化的区分
+泛化(sug词更广):
+- 如果原query的所有要素都在sug词覆盖范围内 → 中高满足档位
+- 泛化导致信息过载 → 适当降档
+
+具体化(sug词更窄):
+- 如果sug词是原query的典型子场景 → 中高满足档位
+- 具体化偏离主要需求 → 中低满足或更低
+
+#### 规则2: 同义转换的宽容度
+允许的同义转换:
+- 核心动作的近义词(如: 获取/下载/寻找/收集)
+- 目标对象的近义词(如: 技巧/方法/教程/攻略)
+- 行业内通用的同义表达
+
+不允许的转换(视为动作不符):
+- 动作意图改变(如: 获取 ≠ 制作)
+- 动作层级错位(如: 学习 ≠ 查看)
+- 目标对象改变(如: 工具推荐 ≠ 使用教程)
+
+#### 规则3: 多意图处理
+如果原query包含多个并列意图:
+1. 识别主次意图(通过语序、连接词判断)
+2. sug词至少满足主意图 → 基本可定义为中高满足
+3. sug词同时满足主次意图 → 可定义为高度满足
+4. sug词只满足次意图 → 降档处理
+
+---
+
+# 输出要求
+
+输出结果必须为一个 JSON 格式，包含以下内容：
+
+```json
+{
+  "第一层_知识识别": {
+    "是否为知识需求": "是/否",
+    "判定依据": "简要说明判定理由,包括意图识别、动词提取、目标验证三步的关键发现"
+  },
+
+  "第二层_知识动机判定": {
+    "得分": "0-1之间的小数",
+    "判定依据": "简要说明各维度得分情况"
+  },
+
+  "第三层_相关性评分": {
+    "相关度满足度百分比": "0-100之间的整数",
+    "相关度满足度依据": "简要说明该sug词条如何与原始query和需求上下文共同形成的综合意图相匹配"
+  }
+}
+```
+
+**重要提示：请严格保持评估标准的一致性，在所有用例中使用相同的判定逻辑。**
+"""
+
+class KnowledgeRecognition(BaseModel):
+    """第一层：知识识别"""
+    是否为知识需求: str = Field(..., description="是/否")
+    判定依据: str = Field(..., description="简要说明判定理由")
+
+class MotivationJudgment(BaseModel):
+    """第二层：知识动机判定"""
+    得分: float = Field(..., description="0-1之间的小数", ge=0, le=1)
+    判定依据: str = Field(..., description="简要说明各维度得分情况")
+
+class RelevanceScore(BaseModel):
+    """第三层：相关性评分"""
+    相关度满足度百分比: int = Field(..., description="0-100之间的整数", ge=0, le=100)
+    相关度满足度依据: str = Field(..., description="简要说明匹配情况")
+
+class EvaluationFeedback(BaseModel):
+    """完整的三层评估反馈"""
+    第一层_知识识别: KnowledgeRecognition
+    第二层_知识动机判定: MotivationJudgment
+    第三层_相关性评分: RelevanceScore
+
+evaluator = Agent[None](
+    name="评估专家",
+    instructions=eval_insrtuctions,
+    output_type=EvaluationFeedback,
+)
+
+@function_tool
+async def get_query_suggestions(wrapper: RunContextWrapper[RunContext], query: str):
+    """Fetch search recommendations from Xiaohongshu."""
+    xiaohongshu_api = XiaohongshuSearchRecommendations()
+    query_suggestions = xiaohongshu_api.get_recommendations(keyword=query)
+    print(query_suggestions)
+
+    async def evaluate_single_query(q_sug: str, q_with_context: str):
+        """Evaluate a single query suggestion."""
+        eval_input = f"""
+{q_with_context}
+<待评估的推荐query>
+{q_sug}
+</待评估的推荐query>
+        """
+        evaluator_result = await Runner.run(evaluator, eval_input)
+        result: EvaluationFeedback = evaluator_result.final_output
+
+        # 提取三层评估结果
+        layer1 = result.第一层_知识识别
+        layer2 = result.第二层_知识动机判定
+        layer3 = result.第三层_相关性评分
+
+        return {
+            "query": q_sug,
+            "第一层_知识识别": {
+                "是否为知识需求": layer1.是否为知识需求,
+                "判定依据": layer1.判定依据,
+            },
+            "第二层_知识动机判定": {
+                "得分": layer2.得分,
+                "判定依据": layer2.判定依据,
+            },
+            "第三层_相关性评分": {
+                "相关度满足度百分比": layer3.相关度满足度百分比,
+                "相关度满足度依据": layer3.相关度满足度依据,
+            },
+            # 为了向后兼容，保留旧的 score 字段（使用第三层百分比除以100）
+            "score": layer3.相关度满足度百分比 / 100.0,
+        }
+
+    # 并发执行所有评估任务
+    q_with_context = wrapper.context.q_with_context
+    res = []
+    if query_suggestions:
+        res = await asyncio.gather(*[evaluate_single_query(q_sug, q_with_context) for q_sug in query_suggestions])
+    else:
+        res = '未返回任何推荐词'
+
+    # 记录到 RunContext
+    wrapper.context.operations_history.append({
+        "operation_type": "get_query_suggestions",
+        "timestamp": datetime.now().isoformat(),
+        "query": query,
+        "suggestions": query_suggestions,
+        "evaluations": res,
+    })
+
+    return res
+
+@function_tool
+def modify_query(wrapper: RunContextWrapper[RunContext], original_query: str, operation_type: str, new_query: str, reason: str):
+    """
+    Modify the search query with a specific operation.
+
+    Args:
+        original_query: The original query before modification
+        operation_type: Type of modification - must be one of: "简化", "扩展", "替换", "组合"
+        new_query: The modified query after applying the operation
+        reason: Detailed explanation of why this modification was made and what insight from previous suggestions led to this change
+
+    Returns:
+        A dict containing the modification record and the new query to use for next search
+    """
+    operation_types = ["简化", "扩展", "替换", "组合"]
+    if operation_type not in operation_types:
+        return {
+            "status": "error",
+            "message": f"Invalid operation_type. Must be one of: {', '.join(operation_types)}"
+        }
+
+    modification_record = {
+        "original_query": original_query,
+        "operation_type": operation_type,
+        "new_query": new_query,
+        "reason": reason,
+    }
+
+    # 记录到 RunContext
+    wrapper.context.operations_history.append({
+        "operation_type": "modify_query",
+        "timestamp": datetime.now().isoformat(),
+        "modification_type": operation_type,
+        "original_query": original_query,
+        "new_query": new_query,
+        "reason": reason,
+    })
+
+    return {
+        "status": "success",
+        "modification_record": modification_record,
+        "new_query": new_query,
+        "message": f"Query modified successfully. Use '{new_query}' for the next search."
+    }
+
+insrtuctions = """
+你是一个专业的搜索query优化专家，擅长通过动态探索找到最符合用户搜索习惯的query。
+
+## 核心任务
+给定原始问题，通过迭代调用搜索推荐接口（get_query_suggestions），找到与原始问题语义等价且更符合平台用户搜索习惯的推荐query。
+
+## 重要说明
+- **你不需要自己评估query的等价性**
+- get_query_suggestions 函数内部已集成评估子agent，会自动对每个推荐词进行**三层评估**
+- 返回结果包含三层评估信息：
+  - **第一层_知识识别**：判断是否为知识需求（是/否）
+  - **第二层_知识动机判定**：综合意图匹配度得分（0-1分值）
+  - **第三层_相关性评分**：相关度满足度百分比（0-100%）
+  - **score**：为兼容旧逻辑保留的字段（第三层百分比/100）
+- **你的职责是分析三层评估结果，做出决策和策略调整**
+
+## 三层评估结果的解读
+
+### 第一层：知识识别
+- 如果"是否为知识需求"为"否"，说明该推荐词不符合知识类需求，直接忽略
+
+### 第二层：知识动机判定（重要过滤层）
+- **高分（接近1.0）**：意图高度匹配，说明核心动词、目标对象、终极目的都基本吻合
+- **中等偏上（0.8-0.9）**：意图部分匹配，可能某些维度有偏差
+- **中等偏下或低分（< 0.8）**：意图明显偏离，核心要素不匹配，考虑调整query
+
+### 第三层：相关性评分
+根据评估标准分为四个档位：
+- **高度满足（90-100%）**：所有核心要素高度匹配，可作为最终结果
+- **中高满足（70-89%）**：核心要素基本匹配但有泛化/具体化，可作为备选
+- **中低满足（40-69%）**：部分相关但存在明显差异
+- **低度满足（0-39%）**：严重偏离，不建议使用
+
+## 防止幻觉 - 关键原则
+- **严禁编造数据**：只能基于 get_query_suggestions 实际返回的结果进行分析
+- **空结果处理**：如果返回的列表为空（[]），必须明确说明"未返回任何推荐词"
+- **不要猜测**：在 modify_query 的 reason 中，不能引用不存在的推荐词或评分
+- **如实记录**：每次分析都要如实反映实际返回的数据
+
+## 工作流程
+
+### 1. 理解原始问题
+- 仔细阅读<需求上下文>和<当前问题>
+- 提取问题的核心需求和关键概念
+- 明确问题的本质意图（what）、应用场景（where）、实现方式（how）
+
+### 2. 动态探索策略
+
+**第一轮尝试：**
+- 使用原始问题直接调用 get_query_suggestions(query="原始问题")
+- **检查返回结果**：
+  - 如果返回空列表 []：说明"该query未返回任何推荐词"，需要简化或替换query
+  - 如果有推荐词：查看每个推荐词的三层评估结果
+- **做出判断**：是否有符合条件的高质量推荐词？
+  - 第一层：是否为知识需求 = "是"
+  - 第二层：得分较高（体现意图匹配度）
+  - 第三层：相关度满足度百分比较高（在"高度满足"档位）
+
+**后续迭代：**
+如果没有符合条件的高分推荐词（或返回空列表），必须先调用 modify_query 记录修改，然后再次搜索：
+
+**工具使用流程：**
+1. **分析三层评估反馈**（必须基于实际返回的数据）：
+   - **情况A - 返回空列表**：
+     * 在 reason 中说明："第X轮未返回任何推荐词，可能是query过于复杂或生僻"
+     * 不能编造任何推荐词或评分
+
+   - **情况B - 有推荐词但不符合条件**：
+     * **第一层过滤**：哪些推荐词"是否为知识需求"为"否"？直接忽略
+     * **第二层分析**：查看"知识动机判定得分"，分析判定依据，了解意图匹配情况
+       - 得分较高但仍不够：哪些维度拉低了得分？
+       - 得分偏低：核心意图偏离，需要调整query方向
+     * **第三层分析**：分析"相关度满足度百分比"和相关度依据：
+       - 高度满足档位：可作为最终结果
+       - 中高满足档位：评估是否可接受作为备选
+       - 中低及以下：分析偏离的具体原因（泛化/具体化/动作不符/对象错位等）
+     * 推荐词整体趋势是什么？（过于泛化/具体化/领域偏移等）
+
+2. **决策修改策略**：基于实际三层评估反馈，调用 modify_query(original_query, operation_type, new_query, reason)
+   - reason 必须引用具体的三层数据，不能编造
+   - 例如："第1轮共返回5个推荐词，2个通过第一层知识识别，其第二层得分分别为X和Y，判定依据显示[具体原因]，第三层相关度为Z%，依据为[具体内容]..."
+
+3. 使用返回的 new_query 调用 get_query_suggestions
+
+4. 分析新的三层评估结果，如果仍不满足，重复步骤1-3
+
+**四种操作类型（operation_type）：**
+- **简化**：删除冗余词汇，提取核心关键词（当推荐词过于发散时）
+- **扩展**：添加限定词或场景描述（当推荐词过于泛化时）
+- **替换**：使用同义词、行业术语或口语化表达（当推荐词偏离核心时）
+- **组合**：调整关键词顺序或组合方式（当推荐词结构不合理时）
+
+**每次修改的reason必须包含：**
+- 上一轮评估结果的关键发现（引用具体的score和reason）
+- 基于评估反馈，为什么这样修改
+- 预期这次修改会带来什么改进
+
+### 3. 决策标准（基于三层评估）
+
+**优先级判断：**
+1. **首先检查第一层**：是否为知识需求 = "是"（否则直接忽略）
+2. **然后检查第二层**：知识动机判定得分，综合评估意图匹配度
+   - 得分高：核心动词、目标对象、终极目的基本吻合
+   - 得分中等：部分维度匹配，需分析判定依据
+   - 得分低：意图明显偏离，考虑调整query
+3. **最后检查第三层**：相关度满足度百分比，查看所属档位
+   - **高度满足档位**：核心要素高度匹配，可作为最终结果
+   - **中高满足档位**：基本匹配但有泛化/具体化，可作为备选
+   - **中低满足档位**：部分相关但存在明显差异，需要继续优化
+   - **低度满足档位**：严重偏离
+
+**综合判断：**
+- 理想结果：第一层通过 + 第二层高分 + 第三层高度满足档位
+- 可接受结果：第一层通过 + 第二层较好 + 第三层中高满足档位（作为备选）
+- 需要优化：任何一层表现不佳
+
+### 4. 迭代终止条件
+- **成功终止**：找到至少一个高质量的推荐query（三层评估均表现良好）
+- **尝试上限**：最多迭代5轮，避免无限循环
+- **无推荐词**：推荐接口返回空列表或错误
+
+### 5. 输出要求
+
+**成功找到高质量query时，输出格式：**
+```
+原始问题：[原问题]
+优化后的query：[最终找到的推荐query]
+三层评估结果：
+- 第一层（知识识别）：[是/否]，[判定依据]
+- 第二层（知识动机判定）：得分 [X.X]，[判定依据摘要]
+- 第三层（相关性评分）：[X]%（[满足档位]），[相关度依据摘要]
+```
+
+**未找到理想query时，输出格式：**
+```
+原始问题：[原问题]
+结果：未找到完全符合条件的推荐query
+最佳备选（如有）：[最接近的推荐词]
+  - 三层评估：第一层[结果]、第二层[得分]、第三层[百分比%]
+建议：[基于实际情况的建议]
+```
+
+## 注意事项
+- **第一轮必须使用原始问题**：直接调用 get_query_suggestions(query="原始问题")
+- **后续修改必须调用 modify_query**：不能直接用新query调用 get_query_suggestions
+- **重点关注三层评估结果**：每次都要仔细分析三层评估数据
+- **基于数据决策**：修改策略必须基于三层评估反馈，不能凭空猜测
+- **引用具体评分**：在分析和决策时，引用具体的三层数据
+  * 第一层：是否为知识需求及判定依据
+  * 第二层：知识动机判定得分及判定依据
+  * 第三层：相关度满足度百分比及相关度依据
+- **分层过滤**：按照第一层→第二层→第三层的顺序逐层分析
+- **严禁编造数据**：
+  * 如果返回空列表，必须在 reason 中明确说明"未返回任何推荐词"
+  * 不能引用不存在的推荐词、评分或评估理由
+  * 每次 modify_query 的 reason 必须基于上一轮实际返回的三层评估结果
+  * 必须引用实际的数值和判定依据，不能编造
+""".strip()
+
+
+
+
+async def main(input_dir: str):
+    current_time, log_url = set_trace()
+
+    # 从目录中读取固定文件名
+    input_context_file = os.path.join(input_dir, 'context.md')
+    input_q_file = os.path.join(input_dir, 'q.md')
+
+    q_context = read_file_as_string(input_context_file)
+    q = read_file_as_string(input_q_file)
+    q_with_context = f"""
+<需求上下文>
+{q_context}
+</需求上下文>
+<当前问题>
+{q}
+</当前问题>
+""".strip()
+
+    # 获取当前文件名作为版本
+    version = os.path.basename(__file__)
+    version_name = os.path.splitext(version)[0]  # 去掉 .py 后缀
+
+    # 日志保存到输入目录的 output/版本/时间戳 目录下
+    log_dir = os.path.join(input_dir, "output", version_name, current_time)
+
+    run_context = RunContext(
+        version=version,
+        input_files={
+            "input_dir": input_dir,
+            "context_file": input_context_file,
+            "q_file": input_q_file,
+        },
+        q_with_context=q_with_context,
+        q_context=q_context,
+        q=q,
+        log_dir=log_dir,
+        log_url=log_url,
+    )
+    agent = Agent[RunContext](
+        name="Query Optimization Agent",
+        instructions=insrtuctions,
+        tools=[get_query_suggestions, modify_query],
+       
+    )
+    result = await Runner.run(agent, input=q_with_context,  context = run_context,)
+    print(result.final_output)
+
+    # 保存最终输出到 RunContext
+    run_context.final_output = str(result.final_output)
+
+    # 保存 RunContext 到 log_dir
+    os.makedirs(run_context.log_dir, exist_ok=True)
+    context_file_path = os.path.join(run_context.log_dir, "run_context.json")
+    with open(context_file_path, "w", encoding="utf-8") as f:
+        json.dump(run_context.model_dump(), f, ensure_ascii=False, indent=2)
+    print(f"\nRunContext saved to: {context_file_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="搜索query优化工具")
+    parser.add_argument(
+        "--input-dir",
+        type=str,
+        default="input/简单扣图",
+        help="输入目录路径，默认: input/简单扣图"
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(args.input_dir))

sug_v4_2.py

@@ -0,0 +1,468 @@
+import asyncio
+import json
+import os
+import argparse
+from datetime import datetime
+
+from agents import Agent, Runner, function_tool, AgentOutputSchema
+from lib.my_trace import set_trace
+from typing import Literal
+from pydantic import BaseModel, Field
+
+
+from lib.utils import read_file_as_string
+from script.search_recommendations.xiaohongshu_search_recommendations import XiaohongshuSearchRecommendations
+
+from agents import Agent, RunContextWrapper, Runner, function_tool
+
+from pydantic import BaseModel, Field
+
+
+class RunContext(BaseModel):
+    version: str = Field(..., description="当前运行的脚本版本（文件名）")
+    input_files: dict[str, str] = Field(..., description="输入文件路径映射，如 {'context_file': '...', 'q_file': '...'}")
+    q_with_context: str
+    q_context: str
+    q: str
+    log_url: str
+    log_dir: str
+    # 问题标注结果 - 直接用字符串记录
+    question_annotation: str | None = Field(default=None, description="问题的标注结果，类似NER格式")
+    # 中间数据记录 - 按时间顺序记录所有操作
+    operations_history: list[dict] = Field(default_factory=list, description="记录所有操作的历史，包括 get_query_suggestions 和 modify_query")
+    # 最终输出结果
+    final_output: str | None = Field(default=None, description="Agent的最终输出结果")
+
+
+# 问题标注 Agent - 三层标注
+question_annotation_instructions = """
+你是搜索需求分析专家。给定问题（含需求背景），在原文上标注三层：本质、硬性、软性。
+
+## 三层结构
+
+**[本质]** - 问题的核心意图，改变后是完全不同的问题
+- 如何获取、教程、推荐、作品、测评等
+
+**[硬]** - 在本质意图下，必须满足的约束
+- 地域、时间、对象、质量要求等
+
+**[软]** - 可有可无的修饰
+- 能体现、特色、快速、简单等
+
+## 输出格式
+
+词语[本质-描述]、词语[硬-描述]、词语[软-描述]
+
+## 注意
+- 只输出标注后的字符串
+- 结合需求背景判断意图
+""".strip()
+
+question_annotator = Agent[None](
+    name="问题标注专家",
+    instructions=question_annotation_instructions,
+)
+
+eval_instructions = """
+你是搜索query评估专家。给定原始问题标注（三层）和推荐query，评估三个分数。
+
+## 评估目标
+
+用这个推荐query搜索，能否找到满足原始需求的内容？
+
+## 三层评分
+
+### 1. essence_score（本质/意图）= 0 或 1
+
+推荐query的本质/意图是否与原问题一致？
+
+**原问题标注中的[本质-XXX]：**
+- 找方法/如何获取 → 推荐词应该是方法/获取途径
+- 教程/学习 → 推荐词应该是教程/教学
+- 作品/欣赏 → 推荐词应该是作品展示
+- 工具/推荐 → 推荐词应该是工具推荐
+
+**评分：**
+- 1 = 本质一致
+- 0 = 本质改变（完全答非所问）
+
+### 2. hard_score（硬性约束）= 0 或 1
+
+在本质一致的前提下，是否满足所有硬性约束？
+
+**原问题标注中的[硬-XXX]：**地域、时间、对象、质量、工具（如果用户明确要求）等
+
+**评分：**
+- 1 = 所有硬性约束都满足
+- 0 = 任一硬性约束不满足
+
+### 3. soft_score（软性修饰）= 0-1
+
+软性修饰词保留了多少？
+
+**原问题标注中的[软-XXX]：**修饰词、非关键限定等
+
+**评分参考：**
+- 1.0 = 完整保留
+- 0.7-0.9 = 保留核心
+- 0.4-0.6 = 部分丢失
+- 0-0.3 = 大量丢失
+
+## 注意
+
+- essence=0 直接拒绝，不管hard/soft多高
+- essence=1, hard=0 也要拒绝
+- essence=1, hard=1 才看soft_score
+""".strip()
+
+class EvaluationFeedback(BaseModel):
+    """评估反馈模型 - 三层评分"""
+    essence_score: Literal[0, 1] = Field(..., description="本质/意图匹配度，0或1。1=问题本质/意图一致，0=本质改变")
+    hard_score: Literal[0, 1] = Field(..., description="硬性约束匹配度，0或1。1=所有硬性约束都满足，0=任一硬性约束不满足")
+    soft_score: float = Field(..., description="软性修饰完整度，0-1的浮点数。1.0=完整保留，0.7-0.9=保留核心，0.4-0.6=泛化较大，0-0.3=大量丢失")
+    reason: str = Field(..., description="评估理由，包括：1）本质/意图是否一致 2）硬性约束是否满足 3）软性修饰保留情况 4）搜索预期")
+
+evaluator = Agent[None](
+    name="评估专家",
+    instructions=eval_instructions,
+    output_type=EvaluationFeedback,
+)
+
+@function_tool
+async def get_query_suggestions(wrapper: RunContextWrapper[RunContext], query: str):
+    """Fetch search recommendations from Xiaohongshu."""
+
+    # 1. 首次调用时，先标注问题（带需求背景）
+    if wrapper.context.question_annotation is None:
+        print("正在标注问题...")
+        annotation_result = await Runner.run(question_annotator, wrapper.context.q_with_context)
+        wrapper.context.question_annotation = str(annotation_result.final_output)
+        print(f"问题标注完成：{wrapper.context.question_annotation}")
+
+    # 2. 获取推荐词
+    xiaohongshu_api = XiaohongshuSearchRecommendations()
+    query_suggestions = xiaohongshu_api.get_recommendations(keyword=query)
+    print(f"获取到 {len(query_suggestions) if query_suggestions else 0} 个推荐词：{query_suggestions}")
+
+    # 3. 评估推荐词（三层评分）
+    async def evaluate_single_query(q_sug: str):
+        """Evaluate a single query suggestion."""
+        eval_input = f"""
+<原始问题标注（三层）>
+{wrapper.context.question_annotation}
+</原始问题标注（三层）>
+
+<待评估的推荐query>
+{q_sug}
+</待评估的推荐query>
+
+请评估该推荐query的三个分数：
+1. essence_score: 本质/意图是否一致（0或1）
+2. hard_score: 硬性约束是否满足（0或1）
+3. soft_score: 软性修饰保留程度（0-1）
+4. reason: 详细的评估理由
+"""
+        evaluator_result = await Runner.run(evaluator, eval_input)
+        result: EvaluationFeedback = evaluator_result.final_output
+        return {
+            "query": q_sug,
+            "essence_score": result.essence_score,
+            "hard_score": result.hard_score,
+            "soft_score": result.soft_score,
+            "reason": result.reason,
+        }
+
+    # 并发执行所有评估任务
+    res = []
+    if query_suggestions:
+        res = await asyncio.gather(*[evaluate_single_query(q_sug) for q_sug in query_suggestions])
+    else:
+        res = '未返回任何推荐词'
+
+    # 记录到 RunContext
+    wrapper.context.operations_history.append({
+        "operation_type": "get_query_suggestions",
+        "timestamp": datetime.now().isoformat(),
+        "query": query,
+        "suggestions": query_suggestions,
+        "evaluations": res,
+    })
+
+    return res
+
+@function_tool
+def modify_query(wrapper: RunContextWrapper[RunContext], original_query: str, operation_type: str, new_query: str, reason: str):
+    """
+    Modify the search query with a specific operation.
+
+    Args:
+        original_query: The original query before modification
+        operation_type: Type of modification - must be one of: "简化", "扩展", "替换", "组合"
+        new_query: The modified query after applying the operation
+        reason: Detailed explanation of why this modification was made and what insight from previous suggestions led to this change
+
+    Returns:
+        A dict containing the modification record and the new query to use for next search
+    """
+    operation_types = ["简化", "扩展", "替换", "组合"]
+    if operation_type not in operation_types:
+        return {
+            "status": "error",
+            "message": f"Invalid operation_type. Must be one of: {', '.join(operation_types)}"
+        }
+
+    modification_record = {
+        "original_query": original_query,
+        "operation_type": operation_type,
+        "new_query": new_query,
+        "reason": reason,
+    }
+
+    # 记录到 RunContext
+    wrapper.context.operations_history.append({
+        "operation_type": "modify_query",
+        "timestamp": datetime.now().isoformat(),
+        "modification_type": operation_type,
+        "original_query": original_query,
+        "new_query": new_query,
+        "reason": reason,
+    })
+
+    return {
+        "status": "success",
+        "modification_record": modification_record,
+        "new_query": new_query,
+        "message": f"Query modified successfully. Use '{new_query}' for the next search."
+    }
+
+instructions = """
+你是一个专业的搜索query优化专家，擅长通过动态探索找到最符合用户搜索习惯的query。
+
+## 核心任务
+给定原始问题，通过迭代调用搜索推荐接口（get_query_suggestions），找到满足硬性要求且尽量保留软性信息的推荐query。
+
+## 重要说明
+- **你不需要自己评估query的适配性**
+- get_query_suggestions 函数会：
+  1. 首次调用时自动标注问题（三层：本质、硬性、软性）
+  2. 对每个推荐词进行三维度评估
+- 返回结果包含：
+  - **query**：推荐词
+  - **essence_score**：本质/意图匹配度（0或1），0=本质改变，1=本质一致
+  - **hard_score**：硬性约束匹配度（0或1），0=不满足约束，1=满足所有约束
+  - **soft_score**：软性修饰完整度（0-1），越高表示保留的信息越完整
+  - **reason**：详细的评估理由
+- **你的职责是分析评估结果，做出决策和策略调整**
+
+## 防止幻觉 - 关键原则
+- **严禁编造数据**：只能基于 get_query_suggestions 实际返回的结果进行分析
+- **空结果处理**：如果返回的列表为空（[]），必须明确说明"未返回任何推荐词"
+- **不要猜测**：在 modify_query 的 reason 中，不能引用不存在的推荐词或评分
+- **如实记录**：每次分析都要如实反映实际返回的数据
+
+## 工作流程
+
+### 1. 理解原始问题
+- 仔细阅读<需求上下文>和<当前问题>
+- 提取问题的核心需求和关键概念
+- 明确问题的本质意图（what）、应用场景（where）、实现方式（how）
+
+### 2. 动态探索策略
+
+**第一轮尝试：**
+- 使用原始问题直接调用 get_query_suggestions(query="原始问题")
+- 第一次调用会自动标注问题（三层），后续调用会复用该标注
+- **检查返回结果**：
+  - 如果返回空列表 []：说明"该query未返回任何推荐词"，需要简化或替换query
+  - 如果有推荐词：查看每个推荐词的 essence_score、hard_score、soft_score 和 reason
+- **做出判断**：是否有 essence_score=1 且 hard_score=1 且 soft_score >= 0.7 的推荐词？
+
+**后续迭代：**
+如果没有合格推荐词（或返回空列表），必须先调用 modify_query 记录修改，然后再次搜索：
+
+**工具使用流程：**
+1. **分析评估反馈**（必须基于实际返回的数据）：
+   - **情况A - 返回空列表**：
+     * 在 reason 中说明："第X轮未返回任何推荐词，可能是query过于复杂或生僻"
+     * 不能编造任何推荐词或评分
+
+   - **情况B - 有推荐词但无合格词**：
+     * **首先检查 essence_score**：
+       - 如果全是 essence_score=0：本质/意图完全不对，需要重新理解问题
+       - 如果有 essence_score=1：本质对了，继续分析
+
+     * **分析 essence_score=1 且 hard_score=1 的推荐词**：
+       - 有哪些？soft_score 是多少？
+       - 如果 soft_score 较低（<0.7），reason 中说明丢失了哪些信息？
+       - 能否通过修改query提高 soft_score？
+
+     * **如果 essence_score=1 但全是 hard_score=0**：
+       - reason 中说明了哪些硬性约束不满足？（地域、时间、对象、质量等）
+       - 需要如何调整query才能满足硬性约束？
+
+2. **决策修改策略**：基于实际评估反馈，调用 modify_query(original_query, operation_type, new_query, reason)
+   - reason 必须引用具体的 essence_score、hard_score、soft_score 和评估理由
+   - 不能编造任何数据
+
+3. 使用返回的 new_query 调用 get_query_suggestions
+
+4. 分析新的评估结果，如果仍不满足，重复步骤1-3
+
+**四种操作类型（operation_type）：**
+- **简化**：删除冗余词汇，提取核心关键词（当推荐词过于发散时）
+- **扩展**：添加限定词或场景描述（当推荐词过于泛化时）
+- **替换**：使用同义词、行业术语或口语化表达（当推荐词偏离核心时）
+- **组合**：调整关键词顺序或组合方式（当推荐词结构不合理时）
+
+**每次修改的reason必须包含：**
+- 上一轮评估结果的关键发现（引用具体的 essence_score、hard_score、soft_score 和评估理由）
+- 基于评估反馈，为什么这样修改
+- 预期这次修改会带来什么改进
+
+### 3. 决策标准
+
+采用**三级评分标准**：
+
+**优先级1：本质/意图（最高优先级）**
+- **essence_score = 1**：本质一致，继续检查
+- **essence_score = 0**：本质改变，**直接放弃**
+
+**优先级2：硬性约束（必须满足）**
+- **hard_score = 1**：所有约束满足，继续检查
+- **hard_score = 0**：约束不满足，**直接放弃**
+
+**优先级3：软性修饰（越高越好）**
+- **soft_score >= 0.7**：信息保留较完整，**理想结果**
+- **0.5 <= soft_score < 0.7**：有所丢失但可接受，**备选结果**
+- **soft_score < 0.5**：丢失过多，继续优化
+
+**采纳标准：**
+- **最优**：essence=1 且 hard=1 且 soft >= 0.7
+- **可接受**：essence=1 且 hard=1 且 soft >= 0.5（多次尝试后）
+- **不可接受**：essence=0 或 hard=0（无论soft多高）
+
+### 4. 迭代终止条件
+- **成功终止**：找到 essence=1 且 hard=1 且 soft >= 0.7 的推荐query
+- **可接受终止**：5轮后找到 essence=1 且 hard=1 且 soft >= 0.5 的推荐query
+- **失败终止**：最多5轮
+- **无推荐词**：返回空列表或错误
+
+### 5. 输出要求
+
+**成功找到合格query时：**
+```
+原始问题：[原问题]
+优化后的query：[最终推荐query]
+本质匹配度：[essence_score] (1=本质一致)
+硬性约束匹配度：[hard_score] (1=所有约束满足)
+软性修饰完整度：[soft_score] (0-1)
+评估理由：[简要说明]
+```
+
+**未找到合格query时：**
+```
+原始问题：[原问题]
+结果：未找到合格推荐query
+原因：[本质不符 / 硬性约束不满足 / 软性信息丢失过多]
+最接近的推荐词：[如果有essence=1且hard=1的词，列出soft最高的]
+建议：[简要建议]
+```
+
+## 注意事项
+- **第一轮必须使用原始问题**：直接调用 get_query_suggestions(query="原始问题")
+  - 第一次调用会自动标注问题（三层），打印出标注结果
+  - 后续调用会复用该标注进行评估
+
+- **后续修改必须调用 modify_query**：不能直接用新query调用 get_query_suggestions
+
+- **重点关注评估结果**：每次都要仔细分析返回的三个分数
+  - **essence_score=0 直接放弃**，本质不对
+  - **hard_score=0 也直接放弃**，约束不满足
+  - **优先关注 essence=1 且 hard=1 的推荐词**，分析如何提升 soft_score
+
+- **基于数据决策**：修改策略必须基于评估反馈
+  - 引用具体的 essence_score、hard_score、soft_score
+  - 引用 reason 中的关键发现
+
+- **采纳标准明确**：
+  - **最优**：essence=1 且 hard=1 且 soft >= 0.7，立即采纳
+  - **可接受**：essence=1 且 hard=1 且 soft >= 0.5，多次尝试后可采纳
+  - **不可接受**：essence=0 或 hard=0，无论soft多高都不能用
+
+- **严禁编造数据**：
+  * 如果返回空列表，必须明确说明"未返回任何推荐词"
+  * 不能引用不存在的推荐词、分数或评估理由
+  * 每次 modify_query 的 reason 必须基于上一轮实际返回的结果
+""".strip()
+
+
+
+
+async def main(input_dir: str):
+    current_time, log_url = set_trace()
+
+    # 从目录中读取固定文件名
+    input_context_file = os.path.join(input_dir, 'context.md')
+    input_q_file = os.path.join(input_dir, 'q.md')
+
+    q_context = read_file_as_string(input_context_file)
+    q = read_file_as_string(input_q_file)
+    q_with_context = f"""
+<需求上下文>
+{q_context}
+</需求上下文>
+<当前问题>
+{q}
+</当前问题>
+""".strip()
+
+    # 获取当前文件名作为版本
+    version = os.path.basename(__file__)
+    version_name = os.path.splitext(version)[0]  # 去掉 .py 后缀
+
+    # 日志保存到输入目录的 output/版本/时间戳 目录下
+    log_dir = os.path.join(input_dir, "output", version_name, current_time)
+
+    run_context = RunContext(
+        version=version,
+        input_files={
+            "input_dir": input_dir,
+            "context_file": input_context_file,
+            "q_file": input_q_file,
+        },
+        q_with_context=q_with_context,
+        q_context=q_context,
+        q=q,
+        log_dir=log_dir,
+        log_url=log_url,
+    )
+    agent = Agent[RunContext](
+        name="Query Optimization Agent",
+        instructions=instructions,
+        tools=[get_query_suggestions, modify_query],
+    )
+    result = await Runner.run(agent, input=q_with_context,  context = run_context,)
+    print(result.final_output)
+
+    # 保存最终输出到 RunContext
+    run_context.final_output = str(result.final_output)
+
+    # 保存 RunContext 到 log_dir
+    os.makedirs(run_context.log_dir, exist_ok=True)
+    context_file_path = os.path.join(run_context.log_dir, "run_context.json")
+    with open(context_file_path, "w", encoding="utf-8") as f:
+        json.dump(run_context.model_dump(), f, ensure_ascii=False, indent=2)
+    print(f"\nRunContext saved to: {context_file_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="搜索query优化工具")
+    parser.add_argument(
+        "--input-dir",
+        type=str,
+        default="input/简单扣图",
+        help="输入目录路径，默认: input/简单扣图"
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(args.input_dir))

sug_v5_1.py

@@ -0,0 +1,765 @@
+import asyncio
+import json
+import os
+import argparse
+from datetime import datetime
+
+from agents import Agent, Runner
+from lib.my_trace import set_trace
+from typing import Literal
+from pydantic import BaseModel, Field
+
+from lib.utils import read_file_as_string
+from script.search_recommendations.xiaohongshu_search_recommendations import XiaohongshuSearchRecommendations
+
+
+class RunContext(BaseModel):
+    version: str = Field(..., description="当前运行的脚本版本（文件名）")
+    input_files: dict[str, str] = Field(..., description="输入文件路径映射")
+    q_with_context: str
+    q_context: str
+    q: str
+    log_url: str
+    log_dir: str
+    question_annotation: str | None = Field(default=None, description="问题的标注结果")
+    operations_history: list[dict] = Field(default_factory=list, description="记录所有操作的历史")
+    final_output: str | None = Field(default=None, description="最终输出结果")
+
+
+# ============================================================================
+# Agent 1: 问题标注专家
+# ============================================================================
+question_annotation_instructions = """
+你是搜索需求分析专家。给定问题（含需求背景），在原文上标注三层：本质、硬性、软性。
+
+## 判断标准
+
+**[本质]** - 问题的核心意图
+- 如何获取、教程、推荐、作品、测评等
+
+**[硬]** - 客观事实性约束（可明确验证、非主观判断）
+- 能明确区分类别的：地域、时间、对象、工具、操作类型
+- 特征：改变后得到完全不同类别的结果
+
+**[软]** - 主观判断性修饰（因人而异、程度性的）
+- 需要主观评价的：质量、速度、美观、特色、程度
+- 特征：改变后仍是同类结果，只是满足程度不同
+
+## 输出格式
+
+词语[本质-描述]、词语[硬-描述]、词语[软-描述]
+
+## 注意
+- 只输出标注后的字符串
+- 结合需求背景判断意图
+""".strip()
+
+question_annotator = Agent[None](
+    name="问题标注专家",
+    instructions=question_annotation_instructions,
+)
+
+
+# ============================================================================
+# Agent 2: 评估专家
+# ============================================================================
+eval_instructions = """
+你是搜索query评估专家。给定原始问题标注（三层）和推荐query，评估三个分数。
+
+## 评估目标
+
+用这个推荐query搜索，能否找到满足原始需求的内容？
+
+## 三层评分
+
+### 1. essence_score（本质/意图）= 0 或 1
+
+推荐query的本质/意图是否与原问题一致？
+
+**原问题标注中的[本质-XXX]对应推荐词要求：**
+- 找方法/如何获取 → 推荐词**必须明确包含方法/途径类词汇**
+  - ✅ "...网站推荐"、"如何获取..."、"...获取途径"、"...方法"
+  - ❌ "...下载"、"...素材"（直接找内容，不是找方法）
+- 教程/学习 → 推荐词应该是教程/教学
+- 作品/欣赏 → 推荐词应该是作品展示
+- 工具/推荐 → 推荐词应该是工具推荐
+
+**评分原则：**
+- 1 = 本质一致，推荐词**明确表达**相同意图
+- 0 = 本质改变或**不够明确**（宁可严格，不可放松）
+
+### 2. hard_score（硬性约束）= 0 或 1
+
+在本质一致的前提下，是否满足所有硬性约束？
+
+**原问题标注中的[硬-XXX]：**地域、时间、对象、质量、工具等
+
+**评分：**
+- 1 = 所有硬性约束都满足
+- 0 = 任一硬性约束不满足
+
+### 3. soft_score（软性修饰）= 0-1
+
+软性修饰词保留了多少？
+
+**评分参考：**
+- 1.0 = 完整保留
+- 0.7-0.9 = 保留核心
+- 0.4-0.6 = 部分丢失
+- 0-0.3 = 大量丢失
+
+## 注意
+
+- essence=0 直接拒绝，不管hard/soft多高
+- essence=1, hard=0 也要拒绝
+- essence=1, hard=1 才看soft_score
+""".strip()
+
+class EvaluationFeedback(BaseModel):
+    """评估反馈模型 - 三层评分"""
+    essence_score: Literal[0, 1] = Field(..., description="本质/意图匹配度，0或1")
+    hard_score: Literal[0, 1] = Field(..., description="硬性约束匹配度，0或1")
+    soft_score: float = Field(..., description="软性修饰完整度，0-1")
+    reason: str = Field(..., description="评估理由")
+
+evaluator = Agent[None](
+    name="评估专家",
+    instructions=eval_instructions,
+    output_type=EvaluationFeedback,
+)
+
+
+# ============================================================================
+# Agent 3: 修改策略生成专家
+# ============================================================================
+strategy_instructions = """
+你是query修改策略专家。**模拟人在搜索引擎中的真实搜索行为**，基于反馈动态调整query。
+
+## 核心思路：搜索是探索过程，不是直达过程
+
+**关键认知：**
+1. **中间query不需要满足原始需求** - 它是探索工具，可以偏离原需求
+2. **推荐词是最宝贵的反馈信号** - 告诉你系统理解成什么了，有什么内容
+3. **每一步query都有明确的探索目的** - 不是盲目改词，而是试探和引导
+4. **最终目标：找到满足需求的推荐词** - 不是让query本身满足需求
+
+## 人的真实搜索过程
+
+**搜索的本质**：通过多步探索，利用推荐词作为桥梁，逐步引导系统
+
+**典型模式**：
+
+第1步：直接尝试
+- 目的：看系统能否直接理解
+- 结果：空列表或essence=0
+- essence=0的推荐词：告诉你系统理解成什么了
+
+第2步：降低要求，简化query
+- 目的：让系统有响应，看它在基础层面有什么
+- 推荐词虽然essence=0，但揭示了系统在某个主题有内容
+- **关键**：选一个最有潜力的推荐词
+
+第3步：基于推荐词，往目标方向引导
+- 目的：利用推荐词作为桥梁，加上目标方向的词
+- 推荐词还是essence=0，但主题在变化（接近目标）
+- **渐进式**：不求一步到位，每步都有进展
+
+第4步：继续引导或换角度
+- 如果推荐词主题不变 → 换角度
+- 如果推荐词主题在接近 → 继续引导
+
+最终：找到essence=1的推荐词
+
+**关键原则**：
+1. essence_score是评估推荐词的，不是评估中间query的
+2. essence=0的推荐词也有价值，它揭示了系统的理解方向
+3. 每一步都有明确的探索目的，看目的是否达成
+4. 通过推荐词的主题变化，判断是否在接近目标
+
+## 输入信息
+- 原始问题标注（三层）：本质、硬性约束、软性修饰
+- 历史尝试记录：所有轮次的query、推荐词、评估结果
+- 当前query和推荐词评估
+
+## 分析步骤
+
+### 第一步：理解当前推荐词的信号
+**核心问题：推荐词告诉我什么信息？**
+
+**重要提醒：essence_score是评估推荐词是否满足原始需求的最终目标**
+- essence_score=1: 推荐词满足原需求的本质
+- essence_score=0: 推荐词不满足原需求的本质
+- **但中间query的目的可能不是满足原需求**，所以essence_score只是参考
+
+1. **系统理解层面**（看推荐词的主题）：
+   - 空列表 → 系统完全不理解当前query
+   - 有推荐词 → 系统理解成了什么主题？
+     - 旅游？教程？素材？工具？品种介绍？
+     - 这些主题是否有助于往目标方向引导？
+
+2. **内容可用性层面**（看推荐词的价值）：
+   - **即使推荐词essence=0，也可能是很好的探索起点**
+   - 例如：推荐词"川西旅游攻略"虽然essence=0，但揭示了系统认识"川西"
+   - 哪些推荐词最有潜力作为下一步的桥梁？
+
+3. **探索目的验证**：
+   - 当前query的探索目的是什么？达到了吗？
+   - 例如：目的是"看系统对川西有什么" → 达到了（有推荐词）
+   - 下一步要验证/探索什么？
+
+### 第二步：回顾历史，识别规律
+
+**什么是真正的死胡同？**
+- ❌ 不是essence=0就是死胡同
+- ✅ 死胡同：连续多次尝试，**推荐词的主题完全不变**
+  - 例如：连续3轮都是"取名/品种介绍"
+  - 例如：连续3轮都是"旅游攻略"
+
+**什么是有进展？**
+- ✅ 推荐词的主题在变化（旅游→摄影→作品→素材）
+- ✅ 即使essence=0，也说明在接近目标
+- ✅ 说明系统的理解在被引导
+
+**避免同义词打转**：
+- ❌ "素材"→"照片"→"图片"→"资源"
+- 这些同义词不会改变系统理解，纯粹浪费轮次
+- ✅ 应该从推荐词中选一个作为桥梁，或换完全不同的角度
+
+### 第三步：选择策略类型（带着明确的探索目的）
+
+**refine_current（微调当前query）**
+- 适用：推荐词方向对了，需要微调让它更精确
+- 探索目的：在正确方向上精细化
+- 动作：加词/减词/换词/调整顺序
+
+**use_recommendation（选推荐词作为新起点）** ⭐ 最重要策略
+- 适用：推荐词虽然essence=0，但**揭示了系统在这个方向有内容**
+- 探索目的：利用推荐词这个客观信号，引导系统往目标方向
+- **核心思维**：推荐词是系统给你的提示，告诉你"我有这个"
+- 动作：
+  - 选一个最有潜力的推荐词作为base_query
+  - 在它基础上加目标方向的词
+  - **这个新query可能不满足原需求，但目的是探索和引导**
+
+**change_approach（换完全不同的角度）**
+- 适用：当前方向是死路（多次尝试推荐词主题不变）
+- 探索目的：跳出当前框架，从另一个角度切入
+- 动作：换一种完全不同的表述方式
+
+**relax_constraints（放宽约束）**
+- 适用：query太复杂，系统不理解（返回空列表）
+- 探索目的：先让系统有响应，看它在最基础层面有什么
+- 动作：去掉限定词，保留核心概念
+
+## 输出要求
+
+### 1. reasoning（推理过程）
+必须包含三部分，**核心是目标导向**：
+
+- **当前位置评估**（相对于最终目标）：
+  - 当前推荐词反映了系统在什么主题空间？
+  - 离原始需求多远？（完全偏离/部分相关/已经接近）
+  - **不要只看essence_score**：
+    - essence_score=0不代表没用，可能是必经之路
+    - 关键看推荐词能否帮助靠近目标
+
+- **历史进展判断**：
+  - 推荐词主题是否在变化？（变化=进展，不变=死胡同）
+  - 在靠近目标，还是原地打转？
+  - 哪些尝试让系统理解发生了改变？
+
+- **下一步探索规划**：
+  - **这一步的作用**（必须明确！）：
+    * 离目标远？→ 先让系统理解某个关键词/概念
+    * 部分相关？→ 选推荐词作为桥梁，引导往目标方向
+    * 已经接近？→ 微调细节，精确匹配
+  - 为什么选这个base_query？
+  - 这个修改如何让我们靠近目标？
+  - **重要**：中间query不需要满足原需求，只要能靠近目标
+
+### 2. strategy_type
+从4种策略中选择：refine_current, use_recommendation, change_approach, relax_constraints
+
+### 3. base_query
+**关键**：可以选择历史中的query，也可以选择历史推荐词
+- 如果选历史query：base_query_source = "history_query"
+- 如果选历史推荐词：base_query_source = "history_recommendation"
+
+### 4. base_query_source
+说明base_query的来源
+
+### 5. modification_action
+**重要：一次只做一个核心动作**
+- 不要列举多个动作
+- 只描述最核心的那一个修改
+- 例如："选择推荐词'川西旅游'作为新起点"
+- 例如："去掉'如何获取'改为直接搜内容"
+- 例如："加上'AI生成'转向生成方向"
+
+### 6. new_query
+最终的新query
+
+## 重要原则
+
+1. **推荐词是最宝贵的反馈** - 充分利用推荐词这个客观信号
+   - 即使essence=0的推荐词，也揭示了系统在这个方向有什么
+   - **优先考虑use_recommendation策略** - 选一个推荐词作为起点
+
+2. **中间query可以偏离原需求** - 每一步都有明确的探索目的
+   - 不要纠结"这个query不满足原需求"
+   - 关键是：这个query能不能帮你往正确方向引导系统
+
+3. **识别死胡同，及时换方向**
+   - 如果多次尝试推荐词主题不变 → 换方向
+   - 如果推荐词越来越偏 → 回退到之前的某个好的起点
+
+4. **保持推理简洁** - 抓住关键信息
+   - 明确说出探索目的
+   - 不要重复啰嗦
+""".strip()
+
+class ModificationStrategy(BaseModel):
+    """修改策略模型 - 模拟人的搜索调整过程"""
+    reasoning: str = Field(..., description="推理过程：1）当前推荐词分析：系统理解成什么了？2）历史尝试总结：哪些方向有效/无效？3）下一步策略：为什么这样调整？")
+
+    strategy_type: Literal[
+        "refine_current",      # 微调当前query（加词/减词/换词/换顺序）
+        "use_recommendation",  # 选择推荐词作为新起点，在它基础上修改
+        "change_approach",     # 换完全不同的表述角度
+        "relax_constraints"    # 放宽约束，去掉部分限定词
+    ] = Field(..., description="策略类型")
+
+    base_query: str = Field(..., description="基础query，可以是：1）历史中的query 2）历史推荐词中的某一个")
+    base_query_source: Literal["history_query", "history_recommendation"] = Field(..., description="base_query的来源")
+
+    modification_action: str = Field(..., description="核心修改动作（只一个），如：'选择推荐词作为新起点' 或 '去掉方法类词改为直接搜内容' 或 '加上AI生成转向生成方向'")
+
+    new_query: str = Field(..., description="修改后的新query")
+
+strategy_generator = Agent[None](
+    name="策略生成专家",
+    instructions=strategy_instructions,
+    output_type=ModificationStrategy,
+)
+
+
+# ============================================================================
+# 核心函数
+# ============================================================================
+
+async def annotate_question(q_with_context: str) -> str:
+    """标注问题（三层）"""
+    print("\n正在标注问题...")
+    result = await Runner.run(question_annotator, q_with_context)
+    annotation = str(result.final_output)
+    print(f"问题标注完成：{annotation}")
+    return annotation
+
+
+async def get_suggestions_with_eval(query: str, annotation: str, context: RunContext) -> list[dict]:
+    """获取推荐词并评估"""
+    print(f"\n正在获取推荐词：{query}")
+
+    # 1. 调用小红书API
+    xiaohongshu_api = XiaohongshuSearchRecommendations()
+    query_suggestions = xiaohongshu_api.get_recommendations(keyword=query)
+    print(f"获取到 {len(query_suggestions) if query_suggestions else 0} 个推荐词：{query_suggestions}")
+
+    if not query_suggestions:
+        # 记录到历史
+        context.operations_history.append({
+            "operation_type": "get_query_suggestions",
+            "timestamp": datetime.now().isoformat(),
+            "query": query,
+            "suggestions": [],
+            "evaluations": "未返回任何推荐词",
+        })
+        return []
+
+    # 2. 并发评估所有推荐词
+    async def evaluate_single_query(q_sug: str):
+        eval_input = f"""
+<需求背景>
+{context.q_context if context.q_context else "无"}
+</需求背景>
+
+<原始问题>
+{context.q}
+</原始问题>
+
+<原始问题标注（三层）>
+{annotation}
+</原始问题标注（三层）>
+
+<待评估的推荐query>
+{q_sug}
+</待评估的推荐query>
+
+请评估该推荐query的三个分数：
+1. essence_score: 本质/意图是否一致（0或1）
+2. hard_score: 硬性约束是否满足（0或1）
+3. soft_score: 软性修饰保留程度（0-1）
+4. reason: 详细的评估理由
+"""
+        evaluator_result = await Runner.run(evaluator, eval_input)
+        result: EvaluationFeedback = evaluator_result.final_output
+        return {
+            "query": q_sug,
+            "essence_score": result.essence_score,
+            "hard_score": result.hard_score,
+            "soft_score": result.soft_score,
+            "reason": result.reason,
+        }
+
+    evaluations = await asyncio.gather(*[evaluate_single_query(q_sug) for q_sug in query_suggestions])
+
+    # 3. 记录到历史
+    context.operations_history.append({
+        "operation_type": "get_query_suggestions",
+        "timestamp": datetime.now().isoformat(),
+        "query": query,
+        "suggestions": query_suggestions,
+        "evaluations": evaluations,
+    })
+
+    return evaluations
+
+
+async def generate_modification_strategy(
+    annotation: str,
+    context: RunContext
+) -> ModificationStrategy:
+    """生成修改策略"""
+    print("\n正在生成修改策略...")
+
+    # 整理历史尝试记录 - 完整保留推荐词和评估结果
+    history_records = []
+    round_num = 0
+
+    for op in context.operations_history:
+        if op["operation_type"] == "get_query_suggestions":
+            round_num += 1
+            record = {
+                "round": round_num,
+                "query": op["query"],
+                "suggestions": op["suggestions"],
+                "evaluations": op["evaluations"]
+            }
+            history_records.append(record)
+        elif op["operation_type"] == "modify_query":
+            # 修改操作也记录，但不增加轮数
+            history_records.append({
+                "operation": "modify_query",
+                "strategy_type": op.get("strategy_type", op.get("modification_type")),  # 兼容旧字段
+                "base_query": op.get("base_query"),
+                "base_query_source": op.get("base_query_source"),
+                "modification_action": op.get("modification_action", op.get("modification_actions", [])),  # 兼容旧版本
+                "original_query": op["original_query"],
+                "new_query": op["new_query"],
+                "reasoning": op["reasoning"]
+            })
+
+    # 格式化历史记录为JSON
+    history_json = json.dumps(history_records, ensure_ascii=False, indent=2)
+
+    strategy_input = f"""
+<需求背景>
+{context.q_context if context.q_context else "无"}
+</需求背景>
+
+<原始问题>
+{context.q}
+</原始问题>
+
+<原始问题标注（三层）>
+{annotation}
+</原始问题标注（三层）>
+
+<历史尝试记录（完整）>
+{history_json}
+</历史尝试记录（完整）>
+
+请基于所有历史尝试，生成下一步的query修改策略。
+
+**说明**：历史记录中最后一条就是当前轮的query和推荐词评估结果。
+
+**核心思路**：每一步都要明确 "当前在哪 → 离目标多远 → 下一步做什么能靠近目标"
+
+重点分析：
+
+1. **评估当前位置**（相对于最终目标）：
+   - 当前推荐词反映了什么？系统在哪个主题空间？
+   - 离原始需求的距离：完全偏离？部分相关？已经接近？
+   - **不要只看essence_score**：essence=0不代表没用，可能是通往目标的必经之路
+
+2. **判断历史进展**：
+   - 推荐词主题是否在变化？（变化=有进展，不变=死胡同）
+   - 是在靠近目标，还是在原地打转？
+   - 哪个方向的query让系统理解发生了改变？
+
+3. **规划下一步探索**：
+   - **这一步query的作用是什么**？（必须明确！）
+     * 如果离目标很远：需要先让系统理解某个关键词/概念
+     * 如果部分相关：选一个推荐词作为桥梁，在它基础上引导
+     * 如果已经接近：微调细节，精确匹配需求
+   - **记住**：中间query不需要满足原需求，只要能让我们往目标靠近
+"""
+    result = await Runner.run(strategy_generator, strategy_input)
+    strategy: ModificationStrategy = result.final_output
+    return strategy
+
+
+def find_qualified_queries(evaluations: list[dict], min_soft_score: float = 0.7) -> list[dict]:
+    """查找所有合格的query，按soft_score降序排列"""
+    qualified = [
+        e for e in evaluations
+        if e['essence_score'] == 1
+        and e['hard_score'] == 1
+        and e['soft_score'] >= min_soft_score
+    ]
+    # 按soft_score降序排列
+    return sorted(qualified, key=lambda x: x['soft_score'], reverse=True)
+
+
+# ============================================================================
+# 主流程（代码控制）
+# ============================================================================
+
+async def optimize_query(context: RunContext, max_rounds: int = 20) -> dict:
+    """
+    主优化流程 - 由代码控制
+
+    Args:
+        context: 运行上下文
+        max_rounds: 最大迭代轮数，默认20
+
+    返回格式：
+    {
+        "success": True/False,
+        "result": {...} or None,
+        "message": "..."
+    }
+    """
+    # 1. 标注问题（仅一次）
+    annotation = await annotate_question(context.q_with_context)
+    context.question_annotation = annotation
+
+    # 2. 迭代优化
+    current_query = context.q
+
+    for round_num in range(1, max_rounds + 1):
+        print(f"\n{'='*60}")
+        print(f"第 {round_num} 轮：{'使用原始问题' if round_num == 1 else '使用修改后的query'}")
+        print(f"当前query: {current_query}")
+        print(f"{'='*60}")
+
+        # 获取推荐词并评估
+        evaluations = await get_suggestions_with_eval(current_query, annotation, context)
+
+        if evaluations:
+            # 检查是否找到合格query
+            qualified_queries = find_qualified_queries(evaluations, min_soft_score=0.7)
+            if qualified_queries:
+                return {
+                    "success": True,
+                    "results": qualified_queries,
+                    "message": f"第{round_num}轮找到{len(qualified_queries)}个合格query"
+                }
+
+        # 如果是最后一轮，不再生成策略
+        if round_num == max_rounds:
+            break
+
+        # 生成修改策略
+        print(f"\n--- 生成修改策略 ---")
+        strategy = await generate_modification_strategy(annotation, context)
+
+        print(f"\n修改策略：")
+        print(f"  推理过程：{strategy.reasoning}")
+        print(f"  策略类型：{strategy.strategy_type}")
+        print(f"  基础query：{strategy.base_query} (来源: {strategy.base_query_source})")
+        print(f"  修改动作：{strategy.modification_action}")
+        print(f"  新query：{strategy.new_query}")
+
+        # 记录修改
+        context.operations_history.append({
+            "operation_type": "modify_query",
+            "timestamp": datetime.now().isoformat(),
+            "reasoning": strategy.reasoning,
+            "strategy_type": strategy.strategy_type,
+            "base_query": strategy.base_query,
+            "base_query_source": strategy.base_query_source,
+            "modification_action": strategy.modification_action,
+            "original_query": current_query,
+            "new_query": strategy.new_query,
+        })
+
+        # 更新当前query
+        current_query = strategy.new_query
+
+    # 所有轮次后仍未找到，从所有历史评估中降低标准查找
+    print(f"\n{'='*60}")
+    print(f"{max_rounds}轮后未找到最优query，降低标准（soft_score >= 0.5）")
+    print(f"{'='*60}")
+
+    # 收集所有历史轮次的评估结果
+    all_evaluations = []
+    for op in context.operations_history:
+        if op["operation_type"] == "get_query_suggestions" and op["evaluations"]:
+            all_evaluations.extend(op["evaluations"])
+
+    if not all_evaluations:
+        return {
+            "success": False,
+            "results": [],
+            "message": "所有轮次均未返回推荐词"
+        }
+
+    # 降级查找：soft_score >= 0.5
+    acceptable_queries = find_qualified_queries(all_evaluations, min_soft_score=0.5)
+    if acceptable_queries:
+        return {
+            "success": True,
+            "results": acceptable_queries,
+            "message": f"{max_rounds}轮后找到{len(acceptable_queries)}个可接受query（soft_score >= 0.5）"
+        }
+
+    # 完全失败：找出最接近的（essence=1, hard=1）
+    essence_hard_ok = [
+        e for e in all_evaluations
+        if e['essence_score'] == 1 and e['hard_score'] == 1
+    ]
+    if essence_hard_ok:
+        # 返回所有满足essence和hard的，按soft_score降序
+        closest_queries = sorted(essence_hard_ok, key=lambda x: x['soft_score'], reverse=True)
+        return {
+            "success": False,
+            "results": closest_queries,
+            "message": f"未找到合格query，但有{len(closest_queries)}个接近的推荐词（essence=1, hard=1）"
+        }
+
+    return {
+        "success": False,
+        "results": [],
+        "message": "未找到任何满足本质和硬性约束的推荐词"
+    }
+
+
+# ============================================================================
+# 输出格式化
+# ============================================================================
+
+def format_output(optimization_result: dict, context: RunContext) -> str:
+    """格式化输出结果"""
+    results = optimization_result.get("results", [])
+
+    if optimization_result["success"] and results:
+        output = f"原始问题：{context.q}\n"
+        output += f"状态：{optimization_result['message']}\n\n"
+        output += "合格的推荐query（按soft_score降序）：\n"
+        for i, result in enumerate(results, 1):
+            output += f"\n{i}. {result['query']}\n"
+            output += f"   - 本质匹配度：{result['essence_score']} (1=本质一致)\n"
+            output += f"   - 硬性约束匹配度：{result['hard_score']} (1=所有约束满足)\n"
+            output += f"   - 软性修饰完整度：{result['soft_score']:.2f} (0-1)\n"
+            output += f"   - 评估理由：{result['reason']}\n"
+        return output.strip()
+    else:
+        output = f"原始问题：{context.q}\n"
+        output += f"结果：未找到合格推荐query\n"
+        output += f"原因：{optimization_result['message']}\n"
+
+        if results:
+            output += "\n最接近的推荐词（按soft_score降序）：\n"
+            for i, result in enumerate(results[:3], 1):  # 只显示前3个
+                output += f"\n{i}. {result['query']}\n"
+                output += f"   - essence_score: {result['essence_score']}\n"
+                output += f"   - hard_score: {result['hard_score']}\n"
+                output += f"   - soft_score: {result['soft_score']:.2f}\n"
+                output += f"   - reason: {result['reason']}\n"
+
+        output += "\n建议：尝试简化问题或调整需求描述"
+        return output.strip()
+
+
+# ============================================================================
+# 主函数
+# ============================================================================
+
+async def main(input_dir: str, max_rounds: int = 20):
+    current_time, log_url = set_trace()
+
+    # 从目录中读取固定文件名
+    input_context_file = os.path.join(input_dir, 'context.md')
+    input_q_file = os.path.join(input_dir, 'q.md')
+
+    q_context = read_file_as_string(input_context_file)
+    q = read_file_as_string(input_q_file)
+    q_with_context = f"""
+<需求上下文>
+{q_context}
+</需求上下文>
+<当前问题>
+{q}
+</当前问题>
+""".strip()
+
+    # 获取当前文件名作为版本
+    version = os.path.basename(__file__)
+    version_name = os.path.splitext(version)[0]
+
+    # 日志保存目录
+    log_dir = os.path.join(input_dir, "output", version_name, current_time)
+
+    run_context = RunContext(
+        version=version,
+        input_files={
+            "input_dir": input_dir,
+            "context_file": input_context_file,
+            "q_file": input_q_file,
+        },
+        q_with_context=q_with_context,
+        q_context=q_context,
+        q=q,
+        log_dir=log_dir,
+        log_url=log_url,
+    )
+
+    # 执行优化流程（代码控制）
+    optimization_result = await optimize_query(run_context, max_rounds=max_rounds)
+
+    # 格式化输出
+    final_output = format_output(optimization_result, run_context)
+    print(f"\n{'='*60}")
+    print("最终结果")
+    print(f"{'='*60}")
+    print(final_output)
+
+    # 保存结果
+    run_context.final_output = final_output
+
+    # 保存 RunContext 到 log_dir
+    os.makedirs(run_context.log_dir, exist_ok=True)
+    context_file_path = os.path.join(run_context.log_dir, "run_context.json")
+    with open(context_file_path, "w", encoding="utf-8") as f:
+        json.dump(run_context.model_dump(), f, ensure_ascii=False, indent=2)
+    print(f"\nRunContext saved to: {context_file_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="搜索query优化工具")
+    parser.add_argument(
+        "--input-dir",
+        type=str,
+        default="input/简单扣图",
+        help="输入目录路径，默认: input/简单扣图"
+    )
+    parser.add_argument(
+        "--max-rounds",
+        type=int,
+        default=20,
+        help="最大迭代轮数，默认: 20"
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(args.input_dir, max_rounds=args.max_rounds))

sug_v5_2.py

@@ -0,0 +1,726 @@
+import asyncio
+import json
+import os
+import argparse
+from datetime import datetime
+
+from agents import Agent, Runner
+from lib.my_trace import set_trace
+from typing import Literal
+from pydantic import BaseModel, Field
+
+from lib.utils import read_file_as_string
+from script.search_recommendations.xiaohongshu_search_recommendations import XiaohongshuSearchRecommendations
+
+
+class RunContext(BaseModel):
+    version: str = Field(..., description="当前运行的脚本版本（文件名）")
+    input_files: dict[str, str] = Field(..., description="输入文件路径映射")
+    q_with_context: str
+    q_context: str
+    q: str
+    log_url: str
+    log_dir: str
+    question_annotation: str | None = Field(default=None, description="问题的标注结果")
+    operations_history: list[dict] = Field(default_factory=list, description="记录所有操作的历史")
+    final_output: str | None = Field(default=None, description="最终输出结果")
+
+
+# ============================================================================
+# Agent 1: 问题标注专家
+# ============================================================================
+question_annotation_instructions = """
+你是搜索需求分析专家。给定问题（含需求背景），在原文上标注三层：本质、硬性、软性。
+
+## 判断标准
+
+**[本质]** - 问题的核心意图
+- 如何获取、教程、推荐、作品、测评等
+
+**[硬]** - 客观事实性约束（可明确验证、非主观判断）
+- 能明确区分类别的：地域、时间、对象、工具、操作类型
+- 特征：改变后得到完全不同类别的结果
+
+**[软]** - 主观判断性修饰（因人而异、程度性的）
+- 需要主观评价的：质量、速度、美观、特色、程度
+- 特征：改变后仍是同类结果，只是满足程度不同
+
+## 输出格式
+
+词语[本质-描述]、词语[硬-描述]、词语[软-描述]
+
+## 注意
+- 只输出标注后的字符串
+- 结合需求背景判断意图
+""".strip()
+
+question_annotator = Agent[None](
+    name="问题标注专家",
+    instructions=question_annotation_instructions,
+)
+
+
+# ============================================================================
+# Agent 2: 评估专家
+# ============================================================================
+eval_instructions = """
+你是搜索query评估专家。给定原始问题标注（三层）和推荐query，评估三个分数。
+
+## 评估目标
+
+用这个推荐query搜索，能否找到满足原始需求的内容？
+
+## 三层评分
+
+### 1. essence_score（本质/意图）= 0 或 1
+
+推荐query的本质/意图是否与原问题一致？
+
+**原问题标注中的[本质-XXX]对应推荐词要求：**
+- 找方法/如何获取 → 推荐词**必须明确包含方法/途径类词汇**
+  - ✅ "...网站推荐"、"如何获取..."、"...获取途径"、"...方法"
+  - ❌ "...下载"、"...素材"（直接找内容，不是找方法）
+- 教程/学习 → 推荐词应该是教程/教学
+- 作品/欣赏 → 推荐词应该是作品展示
+- 工具/推荐 → 推荐词应该是工具推荐
+
+**评分原则：**
+- 1 = 本质一致，推荐词**明确表达**相同意图
+- 0 = 本质改变或**不够明确**（宁可严格，不可放松）
+
+### 2. hard_score（硬性约束）= 0 或 1
+
+在本质一致的前提下，是否满足所有硬性约束？
+
+**原问题标注中的[硬-XXX]：**地域、时间、对象、质量、工具等
+
+**评分：**
+- 1 = 所有硬性约束都满足
+- 0 = 任一硬性约束不满足
+
+### 3. soft_score（软性修饰）= 0-1
+
+软性修饰词保留了多少？
+
+**评分参考：**
+- 1.0 = 完整保留
+- 0.7-0.9 = 保留核心
+- 0.4-0.6 = 部分丢失
+- 0-0.3 = 大量丢失
+
+## 注意
+
+- essence=0 直接拒绝，不管hard/soft多高
+- essence=1, hard=0 也要拒绝
+- essence=1, hard=1 才看soft_score
+""".strip()
+
+class EvaluationFeedback(BaseModel):
+    """评估反馈模型 - 三层评分"""
+    essence_score: Literal[0, 1] = Field(..., description="本质/意图匹配度，0或1")
+    hard_score: Literal[0, 1] = Field(..., description="硬性约束匹配度，0或1")
+    soft_score: float = Field(..., description="软性修饰完整度，0-1")
+    reason: str = Field(..., description="评估理由")
+
+evaluator = Agent[None](
+    name="评估专家",
+    instructions=eval_instructions,
+    output_type=EvaluationFeedback,
+)
+
+
+# ============================================================================
+# Agent 3: 修改策略生成专家
+# ============================================================================
+strategy_instructions = """
+你是query修改策略专家。**模拟人在搜索引擎中的真实搜索行为**，基于反馈动态调整query。
+
+## 核心思路：搜索是探索过程，不是直达过程
+
+**关键认知：**
+1. **中间query不需要满足原始需求** - 它是探索工具，可以偏离原需求
+2. **推荐词是最宝贵的反馈信号** - 告诉你系统理解成什么了，有什么内容
+3. **每一步query都有明确的探索目的** - 不是盲目改词，而是试探和引导
+4. **最终目标：找到满足需求的推荐词** - 不是让query本身满足需求
+
+## 人的真实搜索过程
+
+**搜索的本质**：通过多步探索，利用推荐词作为桥梁，逐步引导系统
+
+**典型模式**：
+
+第1步：直接尝试
+- 目的：看系统能否直接理解
+- 结果：空列表或essence=0
+- essence=0的推荐词：告诉你系统理解成什么了
+
+第2步：降低要求，简化query
+- 目的：让系统有响应，看它在基础层面有什么
+- 推荐词虽然essence=0，但揭示了系统在某个主题有内容
+- **关键**：选一个最有潜力的推荐词
+
+第3步：基于推荐词，往目标方向引导
+- 目的：利用推荐词作为桥梁，加上目标方向的词
+- 推荐词还是essence=0，但主题在变化（接近目标）
+- **渐进式**：不求一步到位，每步都有进展
+
+第4步：继续引导或换角度
+- 如果推荐词主题不变 → 换角度
+- 如果推荐词主题在接近 → 继续引导
+
+最终：找到essence=1的推荐词
+
+**关键原则**：
+1. essence_score是评估推荐词的，不是评估中间query的
+2. essence=0的推荐词也有价值，它揭示了系统的理解方向
+3. 每一步都有明确的探索目的，看目的是否达成
+4. 通过推荐词的主题变化，判断是否在接近目标
+
+## 输入信息
+- 原始问题标注（三层）：本质、硬性约束、软性修饰
+- 历史尝试记录：所有轮次的query、推荐词、评估结果
+- 当前query和推荐词评估
+
+## 分析步骤
+
+### 第一步：理解当前推荐词的信号
+**核心问题：推荐词告诉我什么信息？**
+
+**重要提醒：essence_score是评估推荐词是否满足原始需求的最终目标**
+- essence_score=1: 推荐词满足原需求的本质
+- essence_score=0: 推荐词不满足原需求的本质
+- **但中间query的目的可能不是满足原需求**，所以essence_score只是参考
+
+1. **系统理解层面**（看推荐词的主题）：
+   - 空列表 → 系统完全不理解当前query
+   - 有推荐词 → 系统理解成了什么主题？
+     - 旅游？教程？素材？工具？品种介绍？
+     - 这些主题是否有助于往目标方向引导？
+
+2. **内容可用性层面**（看推荐词的价值）：
+   - **即使推荐词essence=0，也可能是很好的探索起点**
+   - 例如：推荐词"川西旅游攻略"虽然essence=0，但揭示了系统认识"川西"
+   - 哪些推荐词最有潜力作为下一步的桥梁？
+
+3. **探索目的验证**：
+   - 当前query的探索目的是什么？达到了吗？
+   - 例如：目的是"看系统对川西有什么" → 达到了（有推荐词）
+   - 下一步要验证/探索什么？
+
+### 第二步：回顾历史，识别规律
+- 哪些query让系统理解方向变化了？（从"旅游"变成"摄影"）
+- 哪些方向是死路？（多次essence=0且推荐词主题不变）
+- **是否有渐进的改善？**（推荐词越来越接近目标）
+
+### 第三步：选择策略类型（带着明确的探索目的）
+
+**refine_current（微调当前query）**
+- 适用：推荐词方向对了，需要微调让它更精确
+- 探索目的：在正确方向上精细化
+- 动作：加词/减词/换词/调整顺序
+
+**use_recommendation（选推荐词作为新起点）** ⭐ 最重要策略
+- 适用：推荐词虽然essence=0，但**揭示了系统在这个方向有内容**
+- 探索目的：利用推荐词这个客观信号，引导系统往目标方向
+- **核心思维**：推荐词是系统给你的提示，告诉你"我有这个"
+- 动作：
+  - 选一个最有潜力的推荐词作为base_query
+  - 在它基础上加目标方向的词
+  - **这个新query可能不满足原需求，但目的是探索和引导**
+
+**change_approach（换完全不同的角度）**
+- 适用：当前方向是死路（多次尝试推荐词主题不变）
+- 探索目的：跳出当前框架，从另一个角度切入
+- 动作：换一种完全不同的表述方式
+
+**relax_constraints（放宽约束）**
+- 适用：query太复杂，系统不理解（返回空列表）
+- 探索目的：先让系统有响应，看它在最基础层面有什么
+- 动作：去掉限定词，保留核心概念
+
+## 输出要求
+
+### 1. reasoning（推理过程）
+必须包含三部分，**重点写探索目的**：
+
+- **当前推荐词信号分析**：
+  - 系统理解成什么主题了？（旅游？教程？素材？工具？品种？）
+  - 推荐词揭示了什么信息？（系统在哪个方向有内容）
+  - **不要只看essence_score**：
+    - essence_score=0不代表推荐词没用
+    - 关键看推荐词的主题是否有助于引导
+  - 哪个推荐词最有潜力作为下一步的桥梁？
+
+- **历史尝试与趋势**：
+  - 系统理解的主题变化：从"品种介绍"→"旅游"→"摄影"
+  - 是否在逐步接近目标？还是原地打转？
+
+- **下一步策略与探索目的**：
+  - **这一步query的探索目的是什么？**
+    - 验证系统对某个词的理解？
+    - 往某个方向引导？
+    - 利用推荐词作为桥梁？
+  - 为什么选这个base_query？
+  - 为什么这样修改？
+  - **重要**：不要纠结"这个query不满足原需求"，关键是它能否达成探索目的
+
+### 2. strategy_type
+从4种策略中选择：refine_current, use_recommendation, change_approach, relax_constraints
+
+### 3. base_query
+**关键**：可以选择历史中的query，也可以选择历史推荐词
+- 如果选历史query：base_query_source = "history_query"
+- 如果选历史推荐词：base_query_source = "history_recommendation"
+
+### 4. base_query_source
+说明base_query的来源
+
+### 5. modification_actions
+列出具体的修改动作，例如：
+- ["去掉'如何获取'", "保留'川西秋季'", "把'素材'改为'图片'"]
+- ["选择推荐词'川西旅游'", "加上'秋季'", "加上'照片'"]
+
+### 6. new_query
+最终的新query
+
+## 重要原则
+
+1. **推荐词是最宝贵的反馈** - 充分利用推荐词这个客观信号
+   - 即使essence=0的推荐词，也揭示了系统在这个方向有什么
+   - **优先考虑use_recommendation策略** - 选一个推荐词作为起点
+
+2. **中间query可以偏离原需求** - 每一步都有明确的探索目的
+   - 不要纠结"这个query不满足原需求"
+   - 关键是：这个query能不能帮你往正确方向引导系统
+
+3. **识别死胡同，及时换方向**
+   - 如果多次尝试推荐词主题不变 → 换方向
+   - 如果推荐词越来越偏 → 回退到之前的某个好的起点
+
+4. **保持推理简洁** - 抓住关键信息
+   - 明确说出探索目的
+   - 不要重复啰嗦
+""".strip()
+
+class ModificationStrategy(BaseModel):
+    """修改策略模型 - 模拟人的搜索调整过程"""
+    reasoning: str = Field(..., description="推理过程：1）当前推荐词分析：系统理解成什么了？2）历史尝试总结：哪些方向有效/无效？3）下一步策略：为什么这样调整？")
+
+    strategy_type: Literal[
+        "refine_current",      # 微调当前query（加词/减词/换词/换顺序）
+        "use_recommendation",  # 选择推荐词作为新起点，在它基础上修改
+        "change_approach",     # 换完全不同的表述角度
+        "relax_constraints"    # 放宽约束，去掉部分限定词
+    ] = Field(..., description="策略类型")
+
+    base_query: str = Field(..., description="基础query，可以是：1）历史中的query 2）历史推荐词中的某一个")
+    base_query_source: Literal["history_query", "history_recommendation"] = Field(..., description="base_query的来源")
+
+    modification_actions: list[str] = Field(..., description="具体修改动作的描述，如：['去掉\"如何获取\"', '保留核心词\"川西秋季\"', '把\"素材\"改为\"图片\"']")
+
+    new_query: str = Field(..., description="修改后的新query")
+
+strategy_generator = Agent[None](
+    name="策略生成专家",
+    instructions=strategy_instructions,
+    output_type=ModificationStrategy,
+)
+
+
+# ============================================================================
+# 核心函数
+# ============================================================================
+
+async def annotate_question(q_with_context: str) -> str:
+    """标注问题（三层）"""
+    print("\n正在标注问题...")
+    result = await Runner.run(question_annotator, q_with_context)
+    annotation = str(result.final_output)
+    print(f"问题标注完成：{annotation}")
+    return annotation
+
+
+async def get_suggestions_with_eval(query: str, annotation: str, context: RunContext) -> list[dict]:
+    """获取推荐词并评估"""
+    print(f"\n正在获取推荐词：{query}")
+
+    # 1. 调用小红书API
+    xiaohongshu_api = XiaohongshuSearchRecommendations()
+    query_suggestions = xiaohongshu_api.get_recommendations(keyword=query)
+    print(f"获取到 {len(query_suggestions) if query_suggestions else 0} 个推荐词：{query_suggestions}")
+
+    if not query_suggestions:
+        # 记录到历史
+        context.operations_history.append({
+            "operation_type": "get_query_suggestions",
+            "timestamp": datetime.now().isoformat(),
+            "query": query,
+            "suggestions": [],
+            "evaluations": "未返回任何推荐词",
+        })
+        return []
+
+    # 2. 并发评估所有推荐词
+    async def evaluate_single_query(q_sug: str):
+        eval_input = f"""
+<原始问题标注（三层）>
+{annotation}
+</原始问题标注（三层）>
+
+<待评估的推荐query>
+{q_sug}
+</待评估的推荐query>
+
+请评估该推荐query的三个分数：
+1. essence_score: 本质/意图是否一致（0或1）
+2. hard_score: 硬性约束是否满足（0或1）
+3. soft_score: 软性修饰保留程度（0-1）
+4. reason: 详细的评估理由
+"""
+        evaluator_result = await Runner.run(evaluator, eval_input)
+        result: EvaluationFeedback = evaluator_result.final_output
+        return {
+            "query": q_sug,
+            "essence_score": result.essence_score,
+            "hard_score": result.hard_score,
+            "soft_score": result.soft_score,
+            "reason": result.reason,
+        }
+
+    evaluations = await asyncio.gather(*[evaluate_single_query(q_sug) for q_sug in query_suggestions])
+
+    # 3. 记录到历史
+    context.operations_history.append({
+        "operation_type": "get_query_suggestions",
+        "timestamp": datetime.now().isoformat(),
+        "query": query,
+        "suggestions": query_suggestions,
+        "evaluations": evaluations,
+    })
+
+    return evaluations
+
+
+async def generate_modification_strategy(
+    current_query: str,
+    evaluations: list[dict],
+    annotation: str,
+    context: RunContext
+) -> ModificationStrategy:
+    """生成修改策略"""
+    print("\n正在生成修改策略...")
+
+    # 整理历史尝试记录 - 完整保留推荐词和评估结果
+    history_records = []
+    round_num = 0
+
+    for op in context.operations_history:
+        if op["operation_type"] == "get_query_suggestions":
+            round_num += 1
+            record = {
+                "round": round_num,
+                "query": op["query"],
+                "suggestions": op["suggestions"],
+                "evaluations": op["evaluations"]
+            }
+            history_records.append(record)
+        elif op["operation_type"] == "modify_query":
+            # 修改操作也记录，但不增加轮数
+            history_records.append({
+                "operation": "modify_query",
+                "strategy_type": op.get("strategy_type", op.get("modification_type")),  # 兼容旧字段
+                "base_query": op.get("base_query"),
+                "base_query_source": op.get("base_query_source"),
+                "modification_actions": op.get("modification_actions", []),
+                "original_query": op["original_query"],
+                "new_query": op["new_query"],
+                "reasoning": op["reasoning"]
+            })
+
+    # 格式化历史记录为JSON
+    history_json = json.dumps(history_records, ensure_ascii=False, indent=2)
+
+    strategy_input = f"""
+<原始问题标注（三层）>
+{annotation}
+</原始问题标注（三层）>
+
+<历史尝试记录（完整）>
+{history_json}
+</历史尝试记录（完整）>
+
+<当前query>
+{current_query}
+</当前query>
+
+<当前轮推荐词评估结果>
+{json.dumps(evaluations, ensure_ascii=False, indent=2) if evaluations else "空列表"}
+</当前轮推荐词评估结果>
+
+请基于所有历史尝试和当前评估结果，生成下一步的query修改策略。
+
+重点分析：
+
+1. **当前推荐词的信号**：
+   - 系统理解成什么主题了？（旅游？教程？素材？工具？品种？）
+   - 推荐词揭示了什么信息？系统在哪个方向有内容？
+   - **不要只看essence_score**：essence=0的推荐词也可能是好的探索起点
+   - 哪个推荐词最有潜力作为下一步的桥梁？
+
+2. **历史趋势分析**：
+   - 推荐词的主题变化：从"品种介绍"→"旅游"→"摄影"？
+   - 是否在逐步接近目标？还是原地打转（主题不变）？
+   - 哪些query让系统理解方向改变了？
+
+3. **确定探索目的**：
+   - 下一步query的探索目的是什么？
+     * 验证系统对某个词的理解？
+     * 往某个方向引导系统？
+     * 利用推荐词作为桥梁？
+   - **记住**：中间query不需要满足原需求，关键是达成探索目的
+"""
+    result = await Runner.run(strategy_generator, strategy_input)
+    strategy: ModificationStrategy = result.final_output
+    return strategy
+
+
+def find_qualified_queries(evaluations: list[dict], min_soft_score: float = 0.7) -> list[dict]:
+    """查找所有合格的query，按soft_score降序排列"""
+    qualified = [
+        e for e in evaluations
+        if e['essence_score'] == 1
+        and e['hard_score'] == 1
+        and e['soft_score'] >= min_soft_score
+    ]
+    # 按soft_score降序排列
+    return sorted(qualified, key=lambda x: x['soft_score'], reverse=True)
+
+
+# ============================================================================
+# 主流程（代码控制）
+# ============================================================================
+
+async def optimize_query(context: RunContext, max_rounds: int = 20) -> dict:
+    """
+    主优化流程 - 由代码控制
+
+    Args:
+        context: 运行上下文
+        max_rounds: 最大迭代轮数，默认20
+
+    返回格式：
+    {
+        "success": True/False,
+        "result": {...} or None,
+        "message": "..."
+    }
+    """
+    # 1. 标注问题（仅一次）
+    annotation = await annotate_question(context.q_with_context)
+    context.question_annotation = annotation
+
+    # 2. 迭代优化
+    current_query = context.q
+
+    for round_num in range(1, max_rounds + 1):
+        print(f"\n{'='*60}")
+        print(f"第 {round_num} 轮：{'使用原始问题' if round_num == 1 else '使用修改后的query'}")
+        print(f"当前query: {current_query}")
+        print(f"{'='*60}")
+
+        # 获取推荐词并评估
+        evaluations = await get_suggestions_with_eval(current_query, annotation, context)
+
+        if evaluations:
+            # 检查是否找到合格query
+            qualified_queries = find_qualified_queries(evaluations, min_soft_score=0.7)
+            if qualified_queries:
+                return {
+                    "success": True,
+                    "results": qualified_queries,
+                    "message": f"第{round_num}轮找到{len(qualified_queries)}个合格query"
+                }
+
+        # 如果是最后一轮，不再生成策略
+        if round_num == max_rounds:
+            break
+
+        # 生成修改策略
+        print(f"\n--- 生成修改策略 ---")
+        strategy = await generate_modification_strategy(current_query, evaluations, annotation, context)
+
+        print(f"\n修改策略：")
+        print(f"  推理过程：{strategy.reasoning}")
+        print(f"  策略类型：{strategy.strategy_type}")
+        print(f"  基础query：{strategy.base_query} (来源: {strategy.base_query_source})")
+        print(f"  修改动作：{', '.join(strategy.modification_actions)}")
+        print(f"  新query：{strategy.new_query}")
+
+        # 记录修改
+        context.operations_history.append({
+            "operation_type": "modify_query",
+            "timestamp": datetime.now().isoformat(),
+            "reasoning": strategy.reasoning,
+            "strategy_type": strategy.strategy_type,
+            "base_query": strategy.base_query,
+            "base_query_source": strategy.base_query_source,
+            "modification_actions": strategy.modification_actions,
+            "original_query": current_query,
+            "new_query": strategy.new_query,
+        })
+
+        # 更新当前query
+        current_query = strategy.new_query
+
+    # 所有轮次后仍未找到，降低标准查找
+    print(f"\n{'='*60}")
+    print(f"{max_rounds}轮后未找到最优query，降低标准（soft_score >= 0.5）")
+    print(f"{'='*60}")
+
+    acceptable_queries = find_qualified_queries(evaluations, min_soft_score=0.5)
+    if acceptable_queries:
+        return {
+            "success": True,
+            "results": acceptable_queries,
+            "message": f"{max_rounds}轮后找到{len(acceptable_queries)}个可接受query（soft_score >= 0.5）"
+        }
+
+    # 完全失败：找出最接近的
+    essence_hard_ok = [
+        e for e in evaluations
+        if e['essence_score'] == 1 and e['hard_score'] == 1
+    ]
+    if essence_hard_ok:
+        # 返回所有满足essence和hard的，按soft_score降序
+        closest_queries = sorted(essence_hard_ok, key=lambda x: x['soft_score'], reverse=True)
+        return {
+            "success": False,
+            "results": closest_queries,
+            "message": f"未找到合格query，但有{len(closest_queries)}个接近的推荐词（essence=1, hard=1）"
+        }
+
+    return {
+        "success": False,
+        "results": [],
+        "message": "未找到任何满足本质和硬性约束的推荐词"
+    }
+
+
+# ============================================================================
+# 输出格式化
+# ============================================================================
+
+def format_output(optimization_result: dict, context: RunContext) -> str:
+    """格式化输出结果"""
+    results = optimization_result.get("results", [])
+
+    if optimization_result["success"] and results:
+        output = f"原始问题：{context.q}\n"
+        output += f"状态：{optimization_result['message']}\n\n"
+        output += "合格的推荐query（按soft_score降序）：\n"
+        for i, result in enumerate(results, 1):
+            output += f"\n{i}. {result['query']}\n"
+            output += f"   - 本质匹配度：{result['essence_score']} (1=本质一致)\n"
+            output += f"   - 硬性约束匹配度：{result['hard_score']} (1=所有约束满足)\n"
+            output += f"   - 软性修饰完整度：{result['soft_score']:.2f} (0-1)\n"
+            output += f"   - 评估理由：{result['reason']}\n"
+        return output.strip()
+    else:
+        output = f"原始问题：{context.q}\n"
+        output += f"结果：未找到合格推荐query\n"
+        output += f"原因：{optimization_result['message']}\n"
+
+        if results:
+            output += "\n最接近的推荐词（按soft_score降序）：\n"
+            for i, result in enumerate(results[:3], 1):  # 只显示前3个
+                output += f"\n{i}. {result['query']}\n"
+                output += f"   - essence_score: {result['essence_score']}\n"
+                output += f"   - hard_score: {result['hard_score']}\n"
+                output += f"   - soft_score: {result['soft_score']:.2f}\n"
+                output += f"   - reason: {result['reason']}\n"
+
+        output += "\n建议：尝试简化问题或调整需求描述"
+        return output.strip()
+
+
+# ============================================================================
+# 主函数
+# ============================================================================
+
+async def main(input_dir: str, max_rounds: int = 20):
+    current_time, log_url = set_trace()
+
+    # 从目录中读取固定文件名
+    input_context_file = os.path.join(input_dir, 'context.md')
+    input_q_file = os.path.join(input_dir, 'q.md')
+
+    q_context = read_file_as_string(input_context_file)
+    q = read_file_as_string(input_q_file)
+    q_with_context = f"""
+<需求上下文>
+{q_context}
+</需求上下文>
+<当前问题>
+{q}
+</当前问题>
+""".strip()
+
+    # 获取当前文件名作为版本
+    version = os.path.basename(__file__)
+    version_name = os.path.splitext(version)[0]
+
+    # 日志保存目录
+    log_dir = os.path.join(input_dir, "output", version_name, current_time)
+
+    run_context = RunContext(
+        version=version,
+        input_files={
+            "input_dir": input_dir,
+            "context_file": input_context_file,
+            "q_file": input_q_file,
+        },
+        q_with_context=q_with_context,
+        q_context=q_context,
+        q=q,
+        log_dir=log_dir,
+        log_url=log_url,
+    )
+
+    # 执行优化流程（代码控制）
+    optimization_result = await optimize_query(run_context, max_rounds=max_rounds)
+
+    # 格式化输出
+    final_output = format_output(optimization_result, run_context)
+    print(f"\n{'='*60}")
+    print("最终结果")
+    print(f"{'='*60}")
+    print(final_output)
+
+    # 保存结果
+    run_context.final_output = final_output
+
+    # 保存 RunContext 到 log_dir
+    os.makedirs(run_context.log_dir, exist_ok=True)
+    context_file_path = os.path.join(run_context.log_dir, "run_context.json")
+    with open(context_file_path, "w", encoding="utf-8") as f:
+        json.dump(run_context.model_dump(), f, ensure_ascii=False, indent=2)
+    print(f"\nRunContext saved to: {context_file_path}")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="搜索query优化工具")
+    parser.add_argument(
+        "--input-dir",
+        type=str,
+        default="input/简单扣图",
+        help="输入目录路径，默认: input/简单扣图"
+    )
+    parser.add_argument(
+        "--max-rounds",
+        type=int,
+        default=20,
+        help="最大迭代轮数，默认: 20"
+    )
+    args = parser.parse_args()
+
+    asyncio.run(main(args.input_dir, max_rounds=args.max_rounds))