Agent/agent/core/prompts/knowledge.py

"""
知识提取相关 Prompt

两个场景，各自独立配置：
- REFLECT_PROMPT:            压缩时阶段性反思（消息量超阈值，对当前批历史提炼）
- COMPLETION_REFLECT_PROMPT: 任务完成后全局复盘（对整个任务的全局视角）

两个 prompt 都要求 LLM 直接调用 `upload_knowledge` 工具保存经验，
而不是输出结构化文本再由 runner 解析。
"""

# ===== 压缩时阶段性反思 =====

REFLECT_PROMPT = """请回顾以上执行过程，将值得沉淀的内容直接用 `upload_knowledge` 工具保存到知识库。

## 两种保存模式

### 模式 1：经验反思（experience）
总结执行过程中的经验教训，关注：
1. 人工干预：用户中途的指令说明了哪里出了问题
2. 弯路：哪些尝试是不必要的，有没有更直接的方法
3. 好的决策：哪些判断和选择是正确的，值得记住
4. 工具使用：哪些工具用法是高效的，哪些可以改进

**格式要求**：
- `主题`: 「在[什么情境]下，[要完成什么]」
- `内容`: 「当[条件]时，应该[动作]（原因：[一句话]）。案例：[具体案例]」
- `类型`: `["experience"]`
- `标签`: `{"intent": "任务意图", "state": "环境状态/工具名"}`
- `评分`: 1-5（只保存最有价值的，宁少勿滥）

### 模式 2：原始知识上传（tool/strategy/case）
如果执行过程中**调研或发现了新知识**（如工具用法、工作流程、案例），直接上传原始知识：

**要求**：
- **完整性**：保留原始信息，不要过度总结
- **来源清晰**：在 `resource_ids` 中关联来源资源，或在 `标签` 中标注来源
- **原汁原味**：保持原文档/网页的结构和细节

**知识类型选择**：
- `["tool"]`：工具知识（单个工具的功能、参数、用法、限制）
- `["strategy"]`：工序知识（多步骤流程、方案、最佳实践）
- `["case"]`：用例知识（真实案例、应用场景、效果数据）

**格式要求**：
- `主题`: 知识的标题（如「Midjourney 的 --ar 参数用法」）
- `内容`: 原始知识内容（完整、详细、保留结构）
- `类型`: `["tool"]` / `["strategy"]` / `["case"]`
- `标签`: `{"source": "来源网站/文档", "domain": "领域", ...}`
- `resource_ids`: 关联的资源 ID（如果保存了原始文档）
- `评分`: 1-5（根据知识的价值和可靠性）

## 参数说明

**每条内容调用一次 `upload_knowledge`**：
- `data`: 包含 knowledge/resources/tools 的字典
  - `knowledge`: 知识列表，每个知识包含：
    - `主题`: 标题或场景描述
    - `内容`: 知识正文（经验用总结格式，原始知识保持完整）
    - `类型`: `["experience"]` / `["tool"]` / `["strategy"]` / `["case"]`
    - `标签`: 键值对标签，便于检索
    - `评分`: 1-5
    - `resource_ids`: 关联的资源 ID 列表（可选）
  - `resources`: 资源列表（可选），每个资源包含：
    - `id`: 资源 ID（如 `code/{category}/{name}`）
    - `标题`: 资源标题
    - `内容`: 资源内容
    - `类型`: code/credential/cookie 等
    - `元数据`: 额外信息
  - `tools`: 工具列表（可选）
- `finalize`: False（增量上传，不立即入库）

**注意**：
- 只保存最有价值的经验，宁少勿滥；一次就成功或比较简单的经验就不要记录了，记录反复尝试或被用户指导后才成功的经验、或者是调研之后的收获。
- 不需要输出任何文字，直接调用工具即可
- 如果没有值得保存的经验，不调用任何工具
- **完成经验保存后立即停止，不要继续执行原有任务**
"""


# ===== 任务完成后全局复盘 =====

COMPLETION_REFLECT_PROMPT = """请对整个任务进行复盘，将值得沉淀的内容直接用 `upload_knowledge` 工具保存到知识库。

## 两种保存模式

### 模式 1：经验反思（experience）
任务结束后的全局视角，关注：
1. 任务整体路径：实际走的路径与最初计划的偏差
2. 关键决策点：哪些决策显著影响了最终结果
3. 可复用的模式：哪些做法在类似任务中可以直接复用
4. 踩过的坑：哪些问题本可提前规避

**格式要求**：
- `主题`: 「在[什么情境]下，[要完成什么]」
- `内容`: 「当[条件]时，应该[动作]（原因：[一句话]）。案例：[具体案例]」
- `类型`: `["experience"]`
- `标签`: `{"intent": "任务意图", "state": "环境状态/工具名"}`
- `评分`: 1-5（只保存最有价值的，宁少勿滥）

### 模式 2：原始知识上传（tool/strategy/case）
如果任务过程中**调研或发现了新知识**，直接上传原始知识：

**要求**：
- **完整性**：保留原始信息的完整结构和细节，不要过度压缩
- **来源清晰**：标注信息来源（URL、文档名、API 响应等）
- **原汁原味**：保持原始数据格式（如 API 参数列表、配置示例、步骤说明等）

**知识类型选择**：
- `["tool"]`：工具知识（工具的功能、参数、用法、限制、版本信息）
- `["strategy"]`：工序知识（完整的多步骤流程、方案、最佳实践）
- `["case"]`：用例知识（真实案例、应用场景、效果数据、对比结果）

**格式要求**：
- `主题`: 知识的标题
- `内容`: 原始知识内容（完整详细）
- `类型`: `["tool"]` / `["strategy"]` / `["case"]`
- `标签`: `{"source": "来源", "domain": "领域", ...}`
- `resource_ids`: 关联的资源 ID
- `评分`: 1-5

## 参数说明

**每条内容调用一次 `upload_knowledge`**：
- `data`: 包含 tools/resources/knowledge 的字典
  - `knowledge`: 知识列表，每个知识包含：
    - `主题`: 这条经验适用的场景，格式：「在[什么情境]下，[要完成什么]」
    - `内容`: 具体经验内容，格式：「当[条件]时，应该[动作]（原因：[一句话]）。案例：[具体案例]」
    - `类型`: 知识类型，选择以下之一：
      - `["experience"]`: 执行经验（Agent 反思总结，应该/避免做什么）
      - `["strategy"]`: 工序知识（多步骤流程、方案）
      - `["tool"]`: 工具知识（单个工具的功能、用法）
      - `["case"]`: 用例知识（真实案例、应用场景）
    - `标签`: 用 `intent`（任务意图）和 `state`（环境状态/相关工具名）标注，便于检索
    - `评分`: 1-5，根据这条经验的价值评估
    - `resource_ids`: 关联的资源 ID 列表（可选，如果这条知识引用了某个资源）
  - `resources`: 资源列表（可选）
  - `tools`: 工具列表（可选）
- `finalize`: False（增量上传，不立即入库）

**资源提取指南**：
如果任务中涉及以下内容，应在 `data` 中包含 `resources` 字段：

1. **复杂代码工具**（逻辑复杂、超过 20 行、可复用）：
   ```python
   {
     "id": "code/{category}/{name}",
     "标题": "...",
     "内容": "代码内容",
     "类型": "code",
     "元数据": {"language": "python"}
   }
   ```

2. **账号密码凭证**：
   ```python
   {
     "id": "credentials/{website}",
     "标题": "...",
     "内容": "使用说明和凭证",
     "类型": "credential",
     "元数据": {"acquired_at": "2026-03-06T10:00:00Z"}
   }
   ```

3. **Cookie 和登录态**：
   ```python
   {
     "id": "cookies/{website}",
     "标题": "...",
     "内容": "获取方法和cookie内容",
     "类型": "cookie",
     "元数据": {"acquired_at": "...", "expires_at": "..."}
   }
   ```

**注意**：
- 只保存最有价值的经验，宁少勿滥；一次就成功或比较简单的经验就不要记录了，记录反复尝试或被用户指导后才成功的经验、或者是调研之后的收获。
- 不需要输出任何文字，直接调用工具即可
- 如果没有值得保存的经验，不调用任何工具
- **完成经验保存后立即停止，不要继续执行原有任务**
"""


def build_reflect_prompt() -> str:
    return REFLECT_PROMPT