# OpenHands Agent System Prompt 架构说明

## 🏗️ 整体架构

```
┌─────────────────────────────────────────────────────────────────┐
│                      OpenHands Agent                             │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              System Prompt (Jinja2 模板)                  │  │
│  │  ┌────────────────────────────────────────────────────┐  │  │
│  │  │ <ROLE>          Agent 的角色定义                    │  │  │
│  │  ├────────────────────────────────────────────────────┤  │  │
│  │  │ <PRINCIPLES>    核心行为原则                       │  │  │
│  │  ├────────────────────────────────────────────────────┤  │  │
│  │  │ <WORKFLOW>      工作流程                           │  │  │
│  │  ├────────────────────────────────────────────────────┤  │  │
│  │  │ <CONSTRAINTS>   约束条件                           │  │  │
│  │  ├────────────────────────────────────────────────────┤  │  │
│  │  │ {% if custom_instructions %}                       │  │  │
│  │  │   {{ custom_instructions }}  ← 变量注入            │  │  │
│  │  │ {% endif %}                                        │  │  │
│  │  └────────────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                        Tools                              │  │
│  │  • TerminalTool      - 执行命令                          │  │
│  │  • FileEditorTool    - 编辑文件                          │  │
│  │  • TaskTrackerTool   - 跟踪任务                          │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                         LLM                               │  │
│  │  Model: vertex_ai/gemini-2.5-flash                        │  │
│  │  API Key: ***                                             │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │   Conversation   │
                    │   (对话管理器)    │
                    └──────────────────┘
                              │
                              ▼
                    ┌──────────────────┐
                    │    Workspace     │
                    │   (工作目录)      │
                    └──────────────────┘
```

## 📊 自定义 System Prompt 的三层架构

```
┌───────────────────────────────────────────────────────────────┐
│ 第 1 层: Agent 初始化参数                                      │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│  agent = Agent(                                                │
│      llm=llm,                                                  │
│      tools=tools,                                              │
│      system_prompt_filename="custom.j2",  ← 指定模板文件      │
│      system_prompt_kwargs={...}            ← 传递变量         │
│  )                                                             │
│                                                                │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│ 第 2 层: Jinja2 模板文件 (custom.j2)                          │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│  You are an AI agent...                                        │
│                                                                │
│  <ROLE>                                                        │
│  * Your primary role is...                                     │
│  </ROLE>                                                       │
│                                                                │
│  {% if custom_instructions %}      ← 条件判断                 │
│  <CUSTOM>                                                      │
│  {{ custom_instructions }}         ← 变量引用                 │
│  </CUSTOM>                                                     │
│  {% endif %}                                                   │
│                                                                │
│  {% if project_name %}                                         │
│  <CONTEXT>                                                     │
│  Project: {{ project_name }}                                   │
│  Task: {{ task_type }}                                         │
│  </CONTEXT>                                                    │
│  {% endif %}                                                   │
│                                                                │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│ 第 3 层: 渲染后的最终 Prompt (发送给 LLM)                      │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│  You are an AI agent...                                        │
│                                                                │
│  <ROLE>                                                        │
│  * Your primary role is...                                     │
│  </ROLE>                                                       │
│                                                                │
│  <CUSTOM>                                                      │
│  Focus on code evolution and optimization...                   │
│  </CUSTOM>                                                     │
│                                                                │
│  <CONTEXT>                                                     │
│  Project: ShinkaEvolve                                         │
│  Task: Code Evolution                                          │
│  </CONTEXT>                                                    │
│                                                                │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
                      发送给 LLM 执行
```

## 🔄 数据流程图

```
┌─────────────────┐
│  User Message   │ "请优化这段代码"
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                    Conversation                              │
│  • 管理对话历史                                               │
│  • 格式化用户消息                                             │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                       Agent                                  │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ System Prompt (自定义的演化 prompt)                  │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ User Message: "请优化这段代码"                       │   │
│  ├─────────────────────────────────────────────────────┤   │
│  │ Conversation History: [...]                          │   │
│  └─────────────────────────────────────────────────────┘   │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                        LLM                                   │
│  • 理解指令和上下文                                           │
│  • 生成响应                                                   │
│  • 决定使用哪些工具                                           │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Tool Execution                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │ TerminalTool │  │FileEditorTool│  │TaskTracker   │     │
│  ├──────────────┤  ├──────────────┤  ├──────────────┤     │
│  │ 运行测试     │  │ 修改代码     │  │ 创建任务     │     │
│  │ 检查性能     │  │ 保存文件     │  │ 更新状态     │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                   Tool Results                               │
│  • 命令输出                                                   │
│  • 文件修改确认                                               │
│  • 任务状态                                                   │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────┐
│                   LLM (再次处理)                             │
│  • 分析工具执行结果                                           │
│  • 生成最终响应                                               │
│  • 或决定执行更多工具                                         │
└────────┬────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────┐
│  User Response  │ "代码已优化，性能提升 20%"
└─────────────────┘
```

## 🎯 四种自定义方法对比

```
┌─────────────────────────────────────────────────────────────────────────┐
│ 方法 1: 默认 Prompt                                                      │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Agent(llm, tools)                                                       │
│       │                                                                  │
│       ├─→ 自动使用 system_prompt.j2                                     │
│       └─→ 通用指令，适用于大多数任务                                     │
│                                                                          │
│  ✓ 最简单                                                                │
│  ✗ 无法自定义                                                            │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ 方法 2: 选择内置模板                                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Agent(                                                                  │
│      llm, tools,                                                         │
│      system_prompt_filename="system_prompt_planning.j2"                 │
│  )                                                                       │
│       │                                                                  │
│       ├─→ 使用 OpenHands 预定义的模板                                   │
│       └─→ 针对特定任务类型优化（规划/交互/长期任务等）                   │
│                                                                          │
│  ✓ 简单，无需自己写 prompt                                              │
│  ✗ 选择有限（只有 5-6 个模板）                                          │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ 方法 3: 自定义模板 + 变量注入 (推荐)                                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Agent(                                                                  │
│      llm, tools,                                                         │
│      system_prompt_filename="custom_evolution_prompt.j2",               │
│      system_prompt_kwargs={                                              │
│          "custom_instructions": "...",                                   │
│          "project_name": "ShinkaEvolve",                                 │
│          "task_type": "Code Evolution",                                  │
│      }                                                                   │
│  )                                                                       │
│       │                                                                  │
│       ├─→ 使用自定义模板文件                                            │
│       ├─→ 动态注入任务特定信息                                          │
│       └─→ 灵活适应不同场景                                              │
│                                                                          │
│  ✓ 高度灵活                                                              │
│  ✓ 可重用模板                                                            │
│  ✓ 动态配置                                                              │
│  ✗ 需要维护模板文件                                                      │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│ 方法 4: 完全自定义模板                                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Agent(                                                                  │
│      llm, tools,                                                         │
│      system_prompt_filename="path/to/fully_custom.j2"                   │
│  )                                                                       │
│       │                                                                  │
│       ├─→ 完全从零编写 prompt                                           │
│       ├─→ 针对特定领域深度定制                                          │
│       └─→ 包含专业领域知识                                              │
│                                                                          │
│  ✓ 最大灵活性                                                            │
│  ✓ 完全控制                                                              │
│  ✗ 需要深入理解 prompt engineering                                       │
│  ✗ 维护成本高                                                            │
└─────────────────────────────────────────────────────────────────────────┘
```

## 🔧 关键 API 参数详解

### Agent 类的核心参数

```python
class Agent:
    def __init__(
        self,
        llm: LLM,                              # LLM 配置
        tools: List[Tool],                     # 可用工具列表
        
        # System Prompt 相关
        system_prompt_filename: str = "system_prompt.j2",
        system_prompt_kwargs: Dict[str, Any] = {},
        
        # 其他配置
        security_policy_filename: str = "security_policy.j2",
        agent_context: Optional[AgentContext] = None,
        condenser: Optional[CondenserBase] = None,
        critic: Optional[CriticBase] = None,
        
        # 工具过滤
        filter_tools_regex: Optional[str] = None,
        include_default_tools: List[str] = [],
        
        # MCP 配置
        mcp_config: Dict[str, Any] = {},
    ):
        ...
```

### 参数说明

| 参数 | 类型 | 默认值 | 说明 |
|-----|------|--------|------|
| `llm` | `LLM` | 必需 | LLM 配置对象 |
| `tools` | `List[Tool]` | 必需 | Agent 可用的工具列表 |
| `system_prompt_filename` | `str` | `"system_prompt.j2"` | Prompt 模板文件名或路径 |
| `system_prompt_kwargs` | `Dict` | `{}` | 传递给模板的变量字典 |
| `security_policy_filename` | `str` | `"security_policy.j2"` | 安全策略模板文件 |
| `agent_context` | `AgentContext` | `None` | Agent 上下文信息 |
| `condenser` | `CondenserBase` | `None` | 对话压缩器 |
| `critic` | `CriticBase` | `None` | 批评者组件 |

## 🎨 Jinja2 模板语法速查

### 基本变量引用

```jinja2
{{ variable_name }}              # 直接输出变量
{{ project_name }}               # 输出: ShinkaEvolve
```

### 条件判断

```jinja2
{% if custom_instructions %}
<CUSTOM>
{{ custom_instructions }}
</CUSTOM>
{% endif %}

{% if not use_default %}
使用自定义配置
{% else %}
使用默认配置
{% endif %}
```

### 循环

```jinja2
{% for tool in available_tools %}
- {{ tool.name }}: {{ tool.description }}
{% endfor %}
```

### 包含其他模板

```jinja2
{% include 'security_policy.j2' %}
{% include 'self_documentation.j2' %}
```

### 注释

```jinja2
{# 这是注释，不会出现在最终输出中 #}
```

### 过滤器

```jinja2
{{ text | upper }}               # 转大写
{{ text | trim }}                # 去除首尾空白
{{ items | length }}             # 获取长度
```

## 📁 文件组织结构

```
eval_agent/
│
├── 📄 openhands_sample.py                    
│   └─→ 基础示例和自定义示例
│       • basic_example()              使用默认 prompt
│       • custom_evolution_example()   使用自定义 prompt
│
├── 📄 openhands_custom_prompt_examples.py    
│   └─→ 详细的方法对比和示例
│       • example_custom_prompt_file()        方法 1
│       • example_with_kwargs()               方法 2
│       • example_builtin_templates()         方法 3
│       • example_with_custom_evolution_prompt()  方法 4
│       • print_comparison()                  打印对比
│
├── 📄 custom_evolution_prompt.j2             
│   └─→ 代码演化专用的 system prompt 模板
│       包含：
│       • <ROLE> 角色定义
│       • <CODE_EVOLUTION_PRINCIPLES> 演化原则
│       • <MUTATION_STRATEGIES> 变异策略
│       • <WORKFLOW> 工作流程
│       • 变量注入点
│
├── 📖 README_CUSTOM_PROMPT.md                
│   └─→ 完整的使用指南（中文）
│       • 基础概念
│       • 四种自定义方法详解
│       • 完整代码示例
│       • 最佳实践
│       • 常见问题
│
├── 📖 QUICK_START_ZH.md                      
│   └─→ 快速入门指南（中文）
│       • 核心要点
│       • 方法对比
│       • 立即可用的示例代码
│
└── 📖 ARCHITECTURE_ZH.md (本文件)            
    └─→ 架构说明和可视化图表
        • 整体架构图
        • 数据流程图
        • API 参数详解
```

## 💼 实际使用场景

### 场景 1: 代码优化任务

```python
agent = Agent(
    llm=llm,
    tools=[TerminalTool, FileEditorTool],
    system_prompt_filename="custom_evolution_prompt.j2",
    system_prompt_kwargs={
        "custom_instructions": "Focus on performance optimization",
        "task_type": "Performance Optimization",
    }
)

conversation.send_message("Optimize the sorting algorithm in utils.py")
```

### 场景 2: Bug 修复任务

```python
agent = Agent(
    llm=llm,
    tools=[TerminalTool, FileEditorTool, TaskTrackerTool],
    system_prompt_filename="custom_evolution_prompt.j2",
    system_prompt_kwargs={
        "custom_instructions": "Focus on finding and fixing bugs",
        "task_type": "Bug Fixing",
    }
)

conversation.send_message("Find and fix the memory leak in server.py")
```

### 场景 3: 代码重构任务

```python
agent = Agent(
    llm=llm,
    tools=[TerminalTool, FileEditorTool],
    system_prompt_filename="custom_evolution_prompt.j2",
    system_prompt_kwargs={
        "custom_instructions": "Refactor for better readability and maintainability",
        "task_type": "Code Refactoring",
    }
)

conversation.send_message("Refactor the authentication module")
```

## 🎓 最佳实践总结

### ✅ 推荐做法

1. **使用方法 3（自定义模板 + 变量注入）** 对于大多数专业任务
2. **保持模板结构清晰** 使用 `<SECTION>` 标签组织内容
3. **使用条件块** 让模板更灵活：`{% if variable %}`
4. **提供具体指令** 而不是模糊的描述
5. **包含示例** 在 prompt 中展示期望的行为
6. **版本控制** 对 prompt 模板文件进行版本管理
7. **测试验证** 通过实际任务验证 prompt 的效果

### ❌ 避免做法

1. **过于冗长** 的 prompt 可能降低效果
2. **矛盾的指令** 会让 agent 困惑
3. **硬编码** 任务特定信息（应该用变量注入）
4. **忽略测试** 直接在生产环境使用未验证的 prompt
5. **过度复杂** 的条件逻辑

## 🔍 调试技巧

### 查看最终 Prompt

```python
agent = Agent(...)
print("="*80)
print("Final System Prompt:")
print("="*80)
print(agent.system_message)
print("="*80)
```

### 验证模板渲染

```python
from pathlib import Path
from jinja2 import Template

template_path = Path("custom_evolution_prompt.j2")
template = Template(template_path.read_text())

rendered = template.render(
    custom_instructions="Test instructions",
    project_name="TestProject"
)

print(rendered)
```

### 测试 Agent 行为

```python
# 简单任务测试
conversation.send_message("Describe your role and capabilities")
conversation.run()

# 检查是否理解特定指令
conversation.send_message("What are your constraints?")
conversation.run()
```

## 📚 相关资源

- **完整指南**: `README_CUSTOM_PROMPT.md`
- **快速入门**: `QUICK_START_ZH.md`
- **代码示例**: `openhands_custom_prompt_examples.py`
- **基础示例**: `openhands_sample.py`
- **模板文件**: `custom_evolution_prompt.j2`

---

**创建日期**: 2026-01-29  
**版本**: 1.0  
**项目**: ShinkaEvolve - OpenHands Integration