Pi Agent: 提示词模板
最后更新：2026-08-31
好的提示词就像好的菜谱——照着做，每次都能出好菜。
1. 为什么需要提示词模板
直接写提示词的问题：
- 同类任务重复写类似的提示词
- 提示词质量参差不齐
- 难以在团队间共享最佳实践
提示词模板解决这些问题：
| 特性 | 说明 |
|---|---|
| 可复用 | 一次定义，反复调用 |
| 可参数化 | 用变量替换，适配不同场景 |
| 可共享 | 团队共享模板库 |
| 可测试 | 模板可以单独测试和优化 |
2. 内置模板
Pi Agent 提供常用场景的内置模板：
| 模板 | 用途 |
|---|---|
| code_review | 代码审查 |
| bug_fix | Bug 修复 |
| test_gen | 测试生成 |
| doc_gen | 文档生成 |
| translate | 翻译 |
| summarize | 摘要 |
| refactor | 重构 |
使用内置模板：
PYTHON
from pi_agent import Agent
agent = Agent(name="reviewer")
result = agent.run(template="code_review", code="def add(a,b): return a+b")
3. 自定义模板
(1) YAML 模板文件
创建 ~/.pi-agent/templates/code_explain.yaml：
YAML
name: code_explain
description: "解释代码的功能和原理"
system: |
你是一个代码解释专家。用简洁易懂的语言解释代码，
包括：1) 功能概述 2) 关键逻辑 3) 潜在问题
template: |
请解释以下 {{ language }} 代码：
```{{ language }}
{{ code }}
要求：
- 用通俗语言说明功能
- 标注关键逻辑点
- 指出潜在问题（如有） variables:
- name: language type: string required: true description: "编程语言名称"
- name: code type: string required: true description: "要解释的代码"
### (2) Python 定义模板
```python
from pi_agent import PromptTemplate
explain_template = PromptTemplate(
name="code_explain",
description="解释代码的功能和原理",
system="你是代码解释专家，用简洁易懂的语言解释代码",
template="请解释以下 {language} 代码：\n{code}",
variables=["language", "code"]
)
agent = Agent(name="explainer")
agent.add_template(explain_template)
result = agent.run(
template="code_explain",
language="python",
code="def fib(n): return n if n < 2 else fib(n-1) + fib(n-2)"
)
4. 模板变量与条件
(1) 基本变量
YAML
template: |
将以下文本从 {{ source_lang }} 翻译成 {{ target_lang }}：
{{ text }}
(2) 条件渲染
YAML
template: |
请审查以下代码：
{{ code }}
{% if focus_area %}
重点关注 {{ focus_area }} 方面。
{% endif %}
{% if severity == "strict" %}
请严格审查，列出所有问题。
{% else %}
只列出严重问题。
{% endif %}
(3) 循环
YAML
template: |
请检查以下文件是否符合编码规范：
{% for file in files %}
- {{ file }}
{% endfor %}
5. 模板组合
▶ 示例 1：多模板工作流（难度⭐⭐）
PYTHON
from pi_agent import Agent, PromptTemplate
review_template = PromptTemplate(
name="review",
template="审查代码：{code}\n关注点：{focus}"
)
fix_template = PromptTemplate(
name="fix",
template="根据审查意见修复代码：{review_result}\n原代码：{code}"
)
test_template = PromptTemplate(
name="test",
template="为以下代码写测试：{code}"
)
agent = Agent(name="pipeline")
code = "def add(a, b): return a + b"
review_result = agent.run(template="review", code=code, focus="安全性")
fix_result = agent.run(template="fix", review_result=review_result, code=code)
test_result = agent.run(template="test", code=fix_result)
6. 模板测试与优化
(1) A/B 测试
PYTHON
from pi_agent import Agent
template_a = "请审查这段代码：{code}"
template_b = "作为高级工程师，请严格审查这段代码的安全性、性能和可读性：{code}"
agent = Agent(name="ab_test")
result_a = agent.run(template=template_a, code=sample_code)
result_b = agent.run(template=template_b, code=sample_code)
(2) 模板评分
PYTHON
from pi_agent import TemplateEvaluator
evaluator = TemplateEvaluator()
score = evaluator.evaluate(
template="review",
test_cases=[
{"input": {"code": "x=1"}, "expected_contains": ["安全", "性能"]},
{"input": {"code": "def hello(): pass"}, "expected_contains": ["建议"]}
]
)
print(f"模板评分: {score}")
❓ 常见问题
Q 模板变量和 Python f-string 有什么区别？
A 模板变量用
{{ var }}（Jinja2 风格），在渲染时替换，支持条件和循环。f-string 是 Python 语法，不能存到配置文件中。Q 模板太多怎么管理？
A 按目录组织：
templates/coding/、templates/writing/、templates/review/。Pi Agent 会递归扫描所有子目录。Q 团队共享模板的最佳方式？
A 把模板目录放在 Git 仓库中，每人 clone 到
~/.pi-agent/templates/。或发布为 Pi Agent 包。📖 小节
- 提示词模板解决复用性、一致性、可共享三大问题
- 支持 YAML 文件和 Python 两种定义方式
- 模板变量支持条件渲染和循环
- 多模板可组合成工作流
- A/B 测试和评分机制持续优化模板质量
📝 作业
- 基础题（难度⭐）：创建一个简单的翻译模板，支持 source_lang 和 target_lang 参数。
- 进阶题（难度⭐⭐）：创建一个带条件渲染的代码审查模板，根据 severity 参数调整审查严格度。
- 挑战题（难度⭐⭐⭐）：设计一套完整的开发模板库（审查→修复→测试），并测试其效果。
