Agent/agent/core/prompts.py

"""
Agent 系统 Prompt 集中管理

本文件集中管理 Agent 系统中使用的所有 prompt 模板，
包括 runner.py、compaction.py、subagent.py、knowledge.py 等文件中的 prompt。

## 📑 目录索引

### 1. 系统级 Prompt (行 50+)
- DEFAULT_SYSTEM_PREFIX                      # Agent 基础系统提示

### 2. 研究流程 Prompt (行 60+)
- RESEARCH_STAGE_PROMPT_TEMPLATE             # 调研阶段引导
- PLANNING_STAGE_PROMPT                      # 计划阶段引导
- RESEARCH_DECISION_GUIDE_TEMPLATE           # 调研决策阶段引导

### 3. 压缩相关 Prompt (行 110+)
- COMPRESSION_EVAL_PROMPT_TEMPLATE           # Level 2 压缩与经验评估
- REFLECT_PROMPT                             # 经验反思提取
- SUMMARY_HEADER_TEMPLATE                    # 压缩后的摘要头部

### 4. 工具执行 Prompt (行 180+)
- TRUNCATION_HINT                            # 响应截断提示
- TOOL_INTERRUPTED_MESSAGE                   # 工具执行中断提示
- AGENT_INTERRUPTED_SUMMARY                  # Agent 中断摘要
- AGENT_CONTINUE_HINT_TEMPLATE               # Agent 继续执行提示

### 5. 任务生成 Prompt (行 200+)
- TASK_NAME_GENERATION_SYSTEM_PROMPT         # 任务名称生成
- TASK_NAME_FALLBACK                         # 默认任务名称

### 6. 经验管理 Prompt (行 210+)
- EXPERIENCE_ENTRY_TEMPLATE                  # 经验条目格式
- EXPERIENCE_SUMMARY_WITH_RESULTS            # 有结果的经验摘要
- EXPERIENCE_SUMMARY_NO_RESULTS              # 无结果的经验摘要
- EXPERIENCE_PARSE_WARNING                   # 经验解析警告

### 7. 辅助函数 - 基础 Prompt 构建 (行 240+)
- build_research_stage_prompt()              # 构建调研阶段 prompt
- build_research_decision_guide()            # 构建调研决策引导
- build_compression_eval_prompt()            # 构建压缩评估 prompt
- build_summary_header()                     # 构建摘要头部
- build_tool_interrupted_message()           # 构建工具中断消息
- build_agent_continue_hint()                # 构建 Agent 继续提示
- build_experience_entry()                   # 构建经验条目

### 8. 子 Agent 相关 Prompt (行 320+)
- EVALUATE_PROMPT_TEMPLATE                   # 评估任务 prompt
- DELEGATE_RESULT_HEADER                     # 委托任务结果头部
- DELEGATE_SAVED_KNOWLEDGE_HEADER            # 保存知识头部
- DELEGATE_STATS_HEADER                      # 执行统计头部
- EXPLORE_RESULT_HEADER                      # 探索结果头部
- EXPLORE_BRANCH_TEMPLATE                    # 探索分支模板
- EXPLORE_STATUS_SUCCESS                     # 成功状态
- EXPLORE_STATUS_FAILED                      # 失败状态
- EXPLORE_STATUS_ERROR                       # 错误状态
- EXPLORE_SUMMARY_HEADER                     # 探索总结头部

### 9. 辅助函数 - 子 Agent Prompt 构建 (行 380+)
- build_evaluate_prompt()                    # 构建评估 prompt

### 10. 知识管理相关 Prompt (行 400+)
- KNOWLEDGE_SEMANTIC_ROUTE_PROMPT_TEMPLATE   # 知识语义路由
- KNOWLEDGE_EVOLVE_PROMPT_TEMPLATE           # 知识进化重写
- KNOWLEDGE_SLIM_PROMPT_TEMPLATE             # 知识库瘦身

### 11. 辅助函数 - 知识管理 Prompt 构建 (行 450+)
- build_knowledge_semantic_route_prompt()    # 构建知识路由 prompt
- build_knowledge_evolve_prompt()            # 构建知识进化 prompt
- build_knowledge_slim_prompt()              # 构建知识瘦身 prompt

## 🔍 快速查找

**按使用场景查找：**
- 研究流程：第 2 节
- 对话压缩：第 3 节
- 工具调用：第 4 节
- 经验管理：第 6 节
- 子 Agent：第 8 节
- 知识管理：第 10 节

**按文件来源查找：**
- runner.py → 第 1, 2, 4, 5 节
- compaction.py → 第 3 节
- subagent.py → 第 8 节
- knowledge.py → 第 10 节

## ⚠️ 重要提示

1. **变量占位符**：所有 `{变量名}` 格式的占位符必须保留
2. **特殊标记**：`[[EVALUATION]]`、`[[SUMMARY]]` 等标记不可删除
3. **输出格式关键字**：代码解析依赖的关键字需要保持一致
4. **使用辅助函数**：优先使用 `build_*()` 函数而非直接 `.format()`
"""

# ============================================================
# 系统级 Prompt
# ============================================================

DEFAULT_SYSTEM_PREFIX = "你是最顶尖的AI助手，可以拆分并调用工具逐步解决复杂问题。"


# ============================================================
# 研究流程 Prompt - 调研阶段
# ============================================================

RESEARCH_STAGE_PROMPT_TEMPLATE = """## 📚 研究流程 - 执行调研

现有信息不足，需要进行调研。

{research_skill_content}

**重要提示**：
- 调研完成后，请使用 `save_knowledge` 工具保存调研结果
- 系统会自动检测到 save_knowledge 调用，并进入下一阶段（计划）
"""


# ============================================================
# 研究流程 Prompt - 计划阶段
# ============================================================

PLANNING_STAGE_PROMPT = """## 📋 研究流程 - 制定计划

调研已完成（或无需调研），现在请制定执行计划。

**请立即执行以下操作**：
1. 使用 `goal` 工具创建目标树
2. 将任务分解为可执行的子目标
3. 为每个子目标设置合理的优先级

注意：这是强制步骤，必须创建 goal tree 才能进入执行阶段。
"""


# ============================================================
# 研究流程 Prompt - 调研决策阶段
# ============================================================

RESEARCH_DECISION_GUIDE_TEMPLATE = """---

## 🤔 调研决策

{experience_summary}

### 决策指南

**当前状态**：系统已自动检索知识库和经验库，相关内容已注入到上方的 GoalTree 中（查看 Current Goal 下的「📚 相关知识」部分）。

**请根据已注入的知识和经验，选择下一步行动**：

**选项 1: 知识充足，直接制定计划**
- 如果上方显示的知识和经验已经足够完成任务
- 直接使用 `goal` 工具制定执行计划

**选项 2: 知识不足，需要调研** ⭐
- 如果上方没有显示相关知识，或现有知识不足以完成任务
- **立即调用 `agent` 工具启动调研子任务**：

```python
agent(
    task=\"\"\"针对任务「{task_desc}」进行深入调研：

1. 使用 web_search 工具搜索相关技术文档、教程、最佳实践
2. 搜索关键词建议：
   - 核心技术名称 + "教程"
   - 核心技术名称 + "最佳实践"
   - 核心技术名称 + "示例代码"
3. 使用 read_file 工具查看项目中的相关文件
4. 对每条有价值的信息，使用 save_knowledge 工具保存，标签类型选择：
   - tool: 工具使用方法
   - definition: 概念定义
   - usercase: 使用案例
   - strategy: 策略经验

调研完成后，系统会自动进入计划阶段。
\"\"\",
    skills=["research"]  # 注入调研指南
)
```

**重要提示**：
- 如果 GoalTree 中没有显示「📚 相关知识」，说明知识库为空，必须先调研
- 调研应该简洁高效，最多设立两个 goal
"""


# ============================================================
# 压缩相关 Prompt - Level 2 压缩与经验评估
# ============================================================

COMPRESSION_EVAL_PROMPT_TEMPLATE = """请对以上对话历史进行压缩总结，并评价所引用的历史知识/经验。
### 任务 1：评价已用知识
本次任务参考了以下知识内容：{ex_reference_list}

请对比"知识建议"与"实际执行轨迹"，给出三色打分：
[[EVALUATION]]
ID: knowledge-xxx 或 research-xxx | Result: helpful/harmful/mixed | Reason: [优点]... [局限/修正]...

### 任务 2：对话历史摘要
要求：
1. 保留关键决策、结论和产出（如创建的文件、修改的代码、得出的分析结论）
2. 保留重要的上下文（如用户的要求、约束条件、之前的讨论结果）
3. 省略中间探索过程、重复的工具调用细节
4. 使用结构化格式（标题 + 要点 + 相关资源引用，若有）
5. 控制在 2000 字以内
格式要求：
[[SUMMARY]]
(此处填写结构化的摘要内容)

当前 GoalTree 状态：
{goal_tree_prompt}
"""


# ============================================================
# 压缩相关 Prompt - 经验反思
# ============================================================

REFLECT_PROMPT = """请回顾以上整个执行过程，提取有价值的经验教训。
你必须将经验与当前的任务意图（Intent）和环境状态（State）挂钩，以便未来精准检索。
关注以下方面：
1. 人工干预：用户中途的指令是否说明了原来的执行过程哪里有问题
2. 弯路：哪些尝试是不必要的，有没有更直接的方法
3. 好的决策：哪些判断和选择是正确的，值得记住
4. 工具使用：哪些工具用法是高效的，哪些可以改进

输出格式（严格遵守）：
- 在每条经验前加一个[]中添加自定义的标签，标签要求总结实际的内容为若干词语，包括：
    - intent: 当前的goal
    - state: 环境状态（如果与工具相关，可以在标签中加入工具的名称）
- 经验标签可用自然语言描述
- 每条经验单独成段，格式固定为：- 当 [条件] 时，应该 [动作]（原因：[一句话说明]）。具体案例：[案例]
- 条目之间用一个空行分隔
- 不输出任何标题、分类、编号、分隔线或其他结构
- 不使用 markdown 加粗、表格、代码块等格式
- 每条经验自包含，读者无需上下文即可理解
- 只提取最有价值的 5-10 条，宁少勿滥

示例（仅供参考格式，不要复制内容）：
- [intent:示例生成 state:用户提醒，指定样本] 当用户说"给我示例"时，应该用真实数据而不是编造（原因：编造的示例无法验证质量）。具体案例：training_samples.json 中的示例全是 LLM 自己编造的，用户明确要求"基于我指定的样本"。
"""


# ============================================================
# 压缩相关 Prompt - 压缩后的摘要头部
# ============================================================

SUMMARY_HEADER_TEMPLATE = """## 对话历史摘要（自动压缩）

{summary_text}

---
请基于以上摘要和当前 GoalTree 继续执行任务。"""


# ============================================================
# 工具执行 Prompt - 响应截断提示
# ============================================================

TRUNCATION_HINT = """你的响应因为 max_tokens 限制被截断，tool call 参数不完整，未执行。请将大内容拆分为多次小的工具调用（例如用 write_file 的 append 模式分批写入）。"""


# ============================================================
# 工具执行 Prompt - 工具执行中断提示
# ============================================================

TOOL_INTERRUPTED_MESSAGE = """⚠️ 工具 {tool_name} 执行被中断（进程异常退出），未获得执行结果。请根据需要重新调用。"""

AGENT_INTERRUPTED_SUMMARY = "⚠️ 子Agent执行被中断（进程异常退出）"

AGENT_CONTINUE_HINT_TEMPLATE = '使用 continue_from="{sub_trace_id}" 可继续执行，保留已有进度'


# ============================================================
# 任务生成 Prompt
# ============================================================

TASK_NAME_GENERATION_SYSTEM_PROMPT = "用中文为以下任务生成一个简短标题（10-30字），只输出标题本身："

TASK_NAME_FALLBACK = "未命名任务"


# ============================================================
# 经验保存 Prompt - 经验条目格式
# ============================================================

EXPERIENCE_ENTRY_TEMPLATE = """---
id: {ex_id}
trace_id: {trace_id}
tags: {{intent: {intents}, state: {states}}}
metrics: {{helpful: 1, harmful: 0}}
created_at: {created_at}
---
{content}
"""


# ============================================================
# 经验检索 Prompt - 经验摘要格式
# ============================================================

EXPERIENCE_SUMMARY_WITH_RESULTS = "✅ 已自动检索到 {count} 条相关经验（见上方 GoalTree 中的「📚 相关知识」）\n"

EXPERIENCE_SUMMARY_NO_RESULTS = "❌ 未找到相关经验\n"


# ============================================================
# 经验评估 Prompt - 格式解析警告
# ============================================================

EXPERIENCE_PARSE_WARNING = "未能解析出符合格式的经验条目，请检查 REFLECT_PROMPT。"


# ============================================================
# 辅助函数：构建特定场景的 Prompt
# ============================================================

def build_research_stage_prompt(research_skill_content: str) -> str:
    """构建调研阶段的引导 prompt"""
    return RESEARCH_STAGE_PROMPT_TEMPLATE.format(
        research_skill_content=research_skill_content
    )


def build_research_decision_guide(
    experience_results: list,
    task_desc: str
) -> str:
    """构建调研决策阶段的引导消息"""
    if experience_results:
        experience_summary = EXPERIENCE_SUMMARY_WITH_RESULTS.format(
            count=len(experience_results)
        )
    else:
        experience_summary = EXPERIENCE_SUMMARY_NO_RESULTS

    # 截取任务描述前100字符
    task_desc_short = task_desc[:100] if len(task_desc) > 100 else task_desc

    return RESEARCH_DECISION_GUIDE_TEMPLATE.format(
        experience_summary=experience_summary,
        task_desc=task_desc_short
    )


def build_compression_eval_prompt(
    goal_tree_prompt: str,
    ex_reference_list: str
) -> str:
    """构建 Level 2 压缩 prompt（含经验评估）"""
    return COMPRESSION_EVAL_PROMPT_TEMPLATE.format(
        goal_tree_prompt=goal_tree_prompt,
        ex_reference_list=ex_reference_list
    )


def build_summary_header(summary_text: str) -> str:
    """构建压缩后的摘要头部"""
    return SUMMARY_HEADER_TEMPLATE.format(summary_text=summary_text)


def build_tool_interrupted_message(tool_name: str) -> str:
    """构建工具中断消息"""
    return TOOL_INTERRUPTED_MESSAGE.format(tool_name=tool_name)


def build_agent_continue_hint(sub_trace_id: str) -> str:
    """构建 Agent 继续执行提示"""
    return AGENT_CONTINUE_HINT_TEMPLATE.format(sub_trace_id=sub_trace_id)


def build_experience_entry(
    ex_id: str,
    trace_id: str,
    intents: list,
    states: list,
    created_at: str,
    content: str
) -> str:
    """构建经验条目"""
    return EXPERIENCE_ENTRY_TEMPLATE.format(
        ex_id=ex_id,
        trace_id=trace_id,
        intents=intents,
        states=states,
        created_at=created_at,
        content=content
    )

# ============================================================
# 子 Agent 相关 Prompt - 评估任务
# ============================================================

EVALUATE_PROMPT_TEMPLATE = """# 评估任务

请评估以下任务的执行结果是否满足要求。

## 目标描述

{goal_description}

## 执行结果

{result_text}

## 输出格式

## 评估结论
[通过/不通过]

## 评估理由
[详细说明通过或不通过原因]

## 修改建议（如果不通过）
1. [建议1]
2. [建议2]
"""


# ============================================================
# 子 Agent 相关 Prompt - 结果格式化
# ============================================================

DELEGATE_RESULT_HEADER = "## 委托任务完成\n"

DELEGATE_SAVED_KNOWLEDGE_HEADER = "**保存的知识** ({count} 条):"

DELEGATE_STATS_HEADER = "**执行统计**:"

EXPLORE_RESULT_HEADER = "## 探索结果\n"

EXPLORE_BRANCH_TEMPLATE = "### 方案 {branch_name}: {task}"

EXPLORE_STATUS_SUCCESS = "**状态**: ✓ 完成"

EXPLORE_STATUS_FAILED = "**状态**: ✗ 失败"

EXPLORE_STATUS_ERROR = "**状态**: ✗ 异常"

EXPLORE_SUMMARY_HEADER = "## 总结"


# ============================================================
# 辅助函数：构建子 Agent 相关 Prompt
# ============================================================

def build_evaluate_prompt(goal_description: str, result_text: str) -> str:
    """构建评估 prompt"""
    return EVALUATE_PROMPT_TEMPLATE.format(
        goal_description=goal_description,
        result_text=result_text or "（无执行结果）"
    )


# ============================================================
# 知识管理相关 Prompt - 语义路由
# ============================================================

KNOWLEDGE_SEMANTIC_ROUTE_PROMPT_TEMPLATE = """你是一个知识检索专家。根据用户的当前任务需求，从下列原子知识元数据中挑选出最相关的最多 {routing_k} 个知识 ID。
任务需求："{query_text}"

可选知识列表：
{routing_data}

请直接输出 ID 列表，用逗号分隔（例如: knowledge-20260302-001, research-20260302-002）。若无相关项请输出 "None"。
"""


# ============================================================
# 知识管理相关 Prompt - 知识进化重写
# ============================================================

KNOWLEDGE_EVOLVE_PROMPT_TEMPLATE = """你是一个 AI Agent 知识库管理员。请根据反馈建议，对现有的知识内容进行重写进化。

【原知识内容】:
{old_content}

【实战反馈建议】:
{feedback}

【重写要求】:
1. 融合知识：将反馈中的避坑指南、新参数或修正后的选择逻辑融入原知识，使其更具通用性和准确性。
2. 保持结构：如果原内容有特定格式（如 Markdown、代码示例等），请保持该格式。
3. 语言：简洁直接，使用中文。
4. 禁止：严禁输出任何开场白、解释语或额外的 Markdown 标题，直接返回重写后的正文。
"""


# ============================================================
# 知识管理相关 Prompt - 知识库瘦身
# ============================================================

KNOWLEDGE_SLIM_PROMPT_TEMPLATE = """你是一个 AI Agent 知识库管理员。以下是当前知识库的全部条目，请执行瘦身操作：

【任务】:
1. 识别语义高度相似或重复的知识，将它们合并为一条更精炼、更通用的知识。
2. 合并时保留 helpful 最高的那条的 ID 和 metrics（metrics 中 helpful/harmful 取各条之和）。
3. 对于独立的、无重复的知识，保持原样不动。
4. 保持原有的知识结构和格式。

【当前知识库】:
{entries_text}

【输出格式要求】:
严格按以下格式输出每条知识，条目之间用 === 分隔：
ID: <保留的id>
TAGS: <yaml格式的tags>
METRICS: <yaml格式的metrics>
SCORE: <评分>
SCENARIO: <场景描述>
CONTENT: <知识内容>
===
"""


# ============================================================
# 辅助函数：构建知识管理相关 Prompt
# ============================================================

def build_knowledge_semantic_route_prompt(
    query_text: str,
    routing_data: str,
    routing_k: int
) -> str:
    """构建知识语义路由 prompt"""
    return KNOWLEDGE_SEMANTIC_ROUTE_PROMPT_TEMPLATE.format(
        query_text=query_text,
        routing_data=routing_data,
        routing_k=routing_k
    )


def build_knowledge_evolve_prompt(old_content: str, feedback: str) -> str:
    """构建知识进化重写 prompt"""
    return KNOWLEDGE_EVOLVE_PROMPT_TEMPLATE.format(
        old_content=old_content,
        feedback=feedback
    )


def build_knowledge_slim_prompt(entries_text: str) -> str:
    """构建知识库瘦身 prompt"""
    return KNOWLEDGE_SLIM_PROMPT_TEMPLATE.format(
        entries_text=entries_text
    )