Prompt 模板设计：构建可复用的工业级提示模板

Prompt Template Architecture
├── L0 - Base Templates（基础模板）
│   ├── system-base.md（系统基础模板）
│   ├── chat-base.md（对话基础模板）
│   └── tool-base.md（工具调用模板）
│
├── L1 - Domain Templates（领域模板）
│   ├── customer-service.md（客服）
│   ├── code-generation.md（代码生成）
│   ├── data-analysis.md（数据分析）
│   └── content-writing.md（内容创作）
│
├── L2 - Task Templates（任务模板）
│   ├── sentiment-analysis.md
│   ├── text-summarization.md
│   ├── question-answering.md
│   └── entity-extraction.md
│
└── L3 - Instance Templates（实例模板）
    ├── review-classification.md
    ├── medical-chatbot.md
    └── ecommerce-QA.md

from string import Template
from typing import Dict, Any, Optional
import json
import hashlib

class PromptTemplate:
    """工业级 Prompt 模板系统"""
    
    def __init__(self, template_id: str, template_str: str, 
                 metadata: Optional[Dict] = None):
        self.id = template_id
        self.template = Template(template_str)
        self.metadata = metadata or {}
        self.version = metadata.get("version", "1.0.0")
        self.created_at = metadata.get("created_at", "")
    
    def render(self, variables: Dict[str, Any]) -> str:
        """渲染模板，注入变量"""
        # 变量预处理
        processed_vars = self._preprocess_variables(variables)
        
        try:
            return self.template.safe_substitute(**processed_vars)
        except KeyError as e:
            raise ValueError(f"缺少必需变量: {e}")
    
    def _preprocess_variables(self, variables: Dict) -> Dict:
        """变量预处理和验证"""
        required = self.metadata.get("required_vars", [])
        processed = {}
        
        for var in required:
            if var not in variables:
                raise ValueError(f"缺少必需变量 '{var}' 的定义")
        
        for key, value in variables.items():
            # JSON 序列化
            if isinstance(value, (dict, list)):
                processed[key] = json.dumps(value, ensure_ascii=False, indent=2)
            else:
                processed[key] = str(value)
        
        return processed
    
    def validate(self, rendered_output: str) -> bool:
        """验证渲染后的 Prompt"""
        checks = self.metadata.get("validation", [])
        for check in checks:
            if check["type"] == "min_length":
                if len(rendered_output) < check["value"]:
                    return False
            elif check["type"] == "contains":
                if check["value"] not in rendered_output:
                    return False
        return True
    
    def get_checksum(self) -> str:
        """模板内容的校验和"""
        return hashlib.md5(self.template.template.encode()).hexdigest()

class TemplateRegistry:
    """模板注册中心"""
    
    def __init__(self):
        self._templates: Dict[str, PromptTemplate] = {}
    
    def register(self, template: PromptTemplate):
        self._templates[template.id] = template
    
    def get(self, template_id: str) -> PromptTemplate:
        if template_id not in self._templates:
            raise KeyError(f"模板 '{template_id}' 未注册")
        return self._templates[template_id]
    
    def list_by_category(self, category: str) -> list:
        return [
            t for t in self._templates.values()
            if t.metadata.get("category") == category
        ]
    
    def search(self, query: str) -> list:
        """搜索模板"""
        results = []
        for t in self._templates.values():
            if query.lower() in t.id.lower():
                results.append(t)
            elif query.lower() in json.dumps(t.metadata).lower():
                results.append(t)
        return results

法则 1：单一职责
- 一个模板只做一件事
- 例：不要将"情感分类"和"摘要生成"放在一个模板里

法则 2：显式变量
- 所有可变部分必须声明为变量
- 禁止在模板中硬编码业务数据

法则 3：默认值策略
- 每个变量都有合理的默认值
- 默认值应体现最通用的配置

法则 4：版本追踪
- 每个模板必须有版本号
- 变更必须更新版本并记录 changelog

法则 5：降级路径
- 模板必须有 fallback 输出
- 当条件不满足时仍有合理行为

法则 6：边界标注
- 用明确的标记分割模板段落
- 例：=== INSTRUCTIONS ===、=== CONTEXT ===

法则 7：可测试性
- 模板变量应可以被 mock
- 每个模板配套测试用例

法则 8：文档内嵌
- 模板本身要自文档化
- 注释说明每个段落的作用

法则 9：国际化
- 文本内容使用变量占位
- 语言切换只需替换变量值

---
# 模板元数据
id: "qa-domain-expert"
name: "领域专家问答"
version: "2.1.0"
category: "question-answering"
required_vars: ["domain", "question"]
optional_vars: ["context", "tone", "max_length"]
created: "2026-01-15"
updated: "2026-06-01"
---

=== SYSTEM PROMPT ===
你是 ${domain} 领域的专家。
${
  context if context else ""
}

=== INSTRUCTIONS ===
请回答以下问题。要求：
1. 使用专业但不晦涩的语言
2. 优先使用数据支撑观点
3. 如果不确定，明确说明不确定性
4. 回答长度控制在 ${
  max_length if max_length else "500"
} 字以内
5. 语气：${tone if tone else "专业严谨"}

=== USER QUERY ===
${question}

=== OUTPUT FORMAT ===
## 核心回答
<直接回答用户问题>
## 关键依据
<支持回答的依据>
## 补充说明
<注意事项或扩展信息>

from enum import Enum
from typing import Union, List, Optional

class VarType(Enum):
    STRING = "string"
    INTEGER = "integer"
    FLOAT = "float"
    BOOLEAN = "boolean"
    LIST = "list"
    DICT = "dict"
    MARKDOWN = "markdown"
    CODE = "code"

class TemplateVariable:
    """模板变量的定义"""
    
    def __init__(
        self,
        name: str,
        var_type: VarType,
        required: bool = True,
        default: Optional[Any] = None,
        description: str = "",
        validator: Optional[callable] = None,
        examples: List[str] = None
    ):
        self.name = name
        self.type = var_type
        self.required = required
        self.default = default
        self.description = description
        self.validator = validator
        self.examples = examples or []
    
    def validate_value(self, value: Any) -> bool:
        """验证变量值"""
        if value is None and not self.required:
            return True
        if value is None and self.required:
            raise ValueError(f"变量 '{self.name}' 是必需的")
        
        if self.validator:
            return self.validator(value)
        return True

# 变量 schema 定义示例
VARIABLE_SCHEMA = {
    "domain": TemplateVariable(
        name="domain",
        var_type=VarType.STRING,
        required=True,
        description="专业领域名称",
        examples=["机器学习", "量子物理", "金融投资"]
    ),
    "question": TemplateVariable(
        name="question",
        var_type=VarType.STRING,
        required=True,
        description="用户的问题",
        validator=lambda x: len(x) >= 10
    ),
    "max_length": TemplateVariable(
        name="max_length",
        var_type=VarType.INTEGER,
        required=False,
        default=500,
        description="回答最大字数"
    )
}

import re

class VariableSanitizer:
    """变量清洗安全层"""
    
    @staticmethod
    def sanitize_text(value: str) -> str:
        """清除可能破坏模板结构的字符"""
        # 移除模板变量语法
        value = re.sub(r'\$\{[^}]+\}', '', value)
        # 转义 Markdown 代码块
        value = value.replace('```', '```')
        return value
    
    @staticmethod
    def sanitize_code(value: str) -> str:
        """清理代码变量"""
        # 限制代码长度
        max_code_length = 5000
        return value[:max_code_length]
    
    @staticmethod
    def sanitize_list(value: list, max_items: int = 10) -> list:
        """限制列表长度"""
        return value[:max_items]

class TemplateVersionManager:
    """模板版本管理器"""
    
    def __init__(self, storage_path: str):
        self.storage_path = storage_path
        self.versions = {}
    
    def save_version(self, template: PromptTemplate, change_log: str):
        """保存新版本"""
        version = template.metadata.get("version", "1.0.0")
        version_path = f"{self.storage_path}/{template.id}/v{version}.json"
        
        version_data = {
            "id": template.id,
            "version": version,
            "content": template.template.template,
            "metadata": template.metadata,
            "change_log": change_log,
            "checksum": template.get_checksum(),
            "saved_at": "2026-06-25T12:00:00Z"
        }
        
        # 保存到存储
        os.makedirs(os.path.dirname(version_path), exist_ok=True)
        with open(version_path, 'w', encoding='utf-8') as f:
            json.dump(version_data, f, ensure_ascii=False, indent=2)
    
    def rollback_to(self, template_id: str, version: str):
        """回滚到指定版本"""
        version_path = f"{self.storage_path}/{template_id}/v{version}.json"
        with open(version_path, 'r', encoding='utf-8') as f:
            data = json.load(f)
        
        return PromptTemplate(
            template_id=data["id"],
            template_str=data["content"],
            metadata=data["metadata"]
        )

class TemplateTestCase:
    def __init__(self, template_id: str, variables: dict, 
                 expected_contains: list = None):
        self.template_id = template_id
        self.variables = variables
        self.expected_contains = expected_contains or []

def run_template_tests(registry: TemplateRegistry, 
                      test_cases: list) -> dict:
    """运行模板测试套件"""
    results = {"passed": 0, "failed": 0, "errors": []}
    
    for case in test_cases:
        try:
            template = registry.get(case.template_id)
            rendered = template.render(case.variables)
            
            # 验证必需内容
            for expected in case.expected_contains:
                if expected not in rendered:
                    raise AssertionError(
                        f"缺少预期内容: {expected}"
                    )
            
            results["passed"] += 1
            
        except Exception as e:
            results["failed"] += 1
            results["errors"].append({
                "template_id": case.template_id,
                "error": str(e)
            })
    
    return results

# 初始化模板系统
registry = TemplateRegistry()

# 注册基础模板
base_template = PromptTemplate(
    template_id="system-base-v2",
    template_str="""你是一个${role}助手。
${constraints}
""" + """
=== INPUT ===
${user_input}

=== RESPONSE ===
""",
    metadata={
        "version": "2.0.0",
        "category": "base",
        "required_vars": ["role", "user_input"],
        "optional_vars": ["constraints"],
        "created_at": "2026-01-01"
    }
)
registry.register(base_template)

# 使用模板
result = registry.get("system-base-v2").render({
    "role": "编程",
    "constraints": "请使用 TypeScript 回答",
    "user_input": "如何实现一个 Promise 池？"
})