eval_agent/design_draft/ARCHITECTURE_ZH.md

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 类的核心参数

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 模板语法速查

基本变量引用

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

条件判断

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

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

循环

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

包含其他模板

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

注释

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

过滤器

{{ 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: 代码优化任务

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 修复任务

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: 代码重构任务

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

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

验证模板渲染

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 行为

# 简单任务测试
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