Prompt Registry 设计

版本: v0.5.0
日期: 2025-12-17
说明: Prompt Registry 详细设计文档

一、概述

1.1 定位

Prompt Registry 是 Core 平台提供的 Prompt 模板管理系统，支持版本化、输出 Schema 校验、PromptPack 管理。

1.2 核心原则

版本化：每个 Prompt 模板都有版本号
输出 Schema：每个 Prompt 绑定 output_schema（JSON Schema）
按 App 组织：Prompt 模板按 App ID 组织（project.*、ops.*）
PromptPack：App 可以交付 PromptPack（类似 RulePack）

二、数据模型

2.1 PromptTemplate 模型

位置: backend/app/core/prompts/models.py

SQLAlchemy 模型：

class PromptTemplate(Base):
    __tablename__ = "prompt_templates"
    
    id = Column(String(255), primary_key=True)  # 如 "project-mngt.task_decomposition@1.0.0"
    app_id = Column(String(255), nullable=False, index=True)
    name = Column(String(255), nullable=False)
    version = Column(String(50), nullable=False)
    template = Column(Text, nullable=False)  # Prompt 模板内容
    variables = Column(JSONB)  # 变量列表 ["project_name", "project_type"]
    output_schema = Column(JSONB)  # JSON Schema，用于校验输出
    status = Column(String(50), nullable=False, default="active")  # active, deprecated
    created_at = Column(DateTime, nullable=False, default=datetime.utcnow)
    updated_at = Column(DateTime, nullable=False, default=datetime.utcnow, onupdate=datetime.utcnow)
    
    __table_args__ = (
        UniqueConstraint('app_id', 'name', 'version', name='uq_prompt_app_name_version'),
        Index('idx_prompt_app_id', 'app_id'),
        Index('idx_prompt_status', 'status'),
    )

Pydantic Schema：

class PromptTemplateCreate(BaseModel):
    app_id: str
    name: str
    version: str
    template: str
    variables: Optional[List[str]] = []
    output_schema: Optional[Dict] = None
    status: str = "active"

class PromptTemplateResponse(BaseModel):
    id: str
    app_id: str
    name: str
    version: str
    template: str
    variables: List[str]
    output_schema: Optional[Dict]
    status: str
    created_at: datetime
    updated_at: datetime

三、API 设计

3.1 Prompt 模板 CRUD

GET /api/v1/prompts/templates

查询 Prompt 模板列表
支持过滤：?app_id=project-mngt&status=active
支持排序：?sort=created_at&order=desc

GET /api/v1/prompts/templates/{id}

查询 Prompt 模板详情

POST /api/v1/prompts/templates

创建 Prompt 模板
请求体：PromptTemplateCreate

PUT /api/v1/prompts/templates/{id}

更新 Prompt 模板
请求体：PromptTemplateCreate（部分字段）

DELETE /api/v1/prompts/templates/{id}

删除 Prompt 模板（软删除：设置 status=deprecated）

3.2 Prompt 渲染

POST /api/v1/prompts/render

请求：

{
  "prompt_template_id": "project-mngt.task_decomposition@1.0.0",
  "variables": {
    "project_name": "我的项目",
    "project_type": "software"
  }
}

响应：

{
  "rendered": "你是一个项目管理专家，请根据以下信息生成项目任务列表：\n\n项目信息：\n- 项目名称: 我的项目\n- 项目类型: software\n\n...",
  "variables_used": ["project_name", "project_type"],
  "variables_missing": []
}

3.3 输出校验

POST /api/v1/prompts/validate

请求：

{
  "prompt_template_id": "project-mngt.task_decomposition@1.0.0",
  "output": "{\"tasks\": [...]}"
}

响应：

{
  "valid": true,
  "parsed": {
    "tasks": [...]
  },
  "errors": []
}

或

{
  "valid": false,
  "parsed": null,
  "errors": [
    "Missing required field: tasks"
  ]
}

四、Prompt 模板格式

4.1 模板语法

变量替换：

{{variable_name}} - 简单变量
{{variable_name|default}} - 带默认值
{{#if condition}}...{{/if}} - 条件判断（可选）
{{#each items}}...{{/each}} - 循环（可选）

示例：

你是一个项目管理专家，请根据以下信息生成项目任务列表：

项目信息：
- 项目名称: {{project_name}}
- 项目类型: {{project_type}}
- 项目描述: {{project_description|暂无描述}}

{{#if similar_projects}}
参考任务模板（相似项目）：
{{#each similar_projects}}
- {{name}}: {{tasks}}
{{/each}}
{{/if}}

请生成详细的任务列表...

4.2 输出 Schema

示例：

{
  "type": "object",
  "properties": {
    "tasks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": {"type": "string"},
          "description": {"type": "string"},
          "priority": {"type": "string", "enum": ["low", "normal", "high"]},
          "estimated_hours": {"type": "number"}
        },
        "required": ["title", "priority"]
      }
    }
  },
  "required": ["tasks"]
}

五、PromptPack 设计

5.1 PromptPack 格式

文件: apps/{app_id}/prompts/promptpack.yaml

格式：

promptpack:
  id: project-mngt.promptpack.v1
  name: Project Management Prompts
  version: 1.0.0
  app_id: project-mngt
  prompts:
    - id: project-mngt.task_decomposition@1.0.0
      name: 任务分解
      template: |
        你是一个项目管理专家...
      variables:
        - project_name
        - project_type
      output_schema:
        type: object
        properties:
          tasks:
            type: array
    - id: project-mngt.meeting_minutes@1.0.0
      name: 会议纪要生成
      template: |
        你是一个会议记录专家...
      variables:
        - meeting_title
        - agenda
      output_schema:
        type: object
        properties:
          content:
            type: string

5.2 PromptPack 安装

安装流程：

App 安装时检测 prompts/promptpack.yaml
解析 PromptPack
验证 Prompt 模板格式
注册 Prompt 模板到 Prompt Registry
处理版本冲突（如果已存在，比较版本号）

版本冲突处理：

如果版本号相同，跳过（不覆盖）
如果版本号更高，更新
如果版本号更低，跳过（不降级）

六、实现细节

6.1 Prompt 渲染器

位置: backend/app/core/prompts/renderer.py

实现：

class PromptRenderer:
    def render(
        self,
        template: str,
        variables: Dict[str, Any],
    ) -> str:
        """
        渲染 Prompt 模板
        
        支持：
        - {{variable}} - 变量替换
        - {{variable|default}} - 带默认值
        - {{#if condition}}...{{/if}} - 条件判断（可选）
        - {{#each items}}...{{/each}} - 循环（可选）
        """
        # 使用 Jinja2 或自定义实现
        # 简单实现：使用正则表达式替换 {{variable}}
        rendered = template
        for key, value in variables.items():
            pattern = r'\{\{' + key + r'(\|.*?)?\}\}'
            rendered = re.sub(pattern, str(value), rendered)
        return rendered

6.2 输出校验器

位置: backend/app/core/prompts/validator.py

实现：

import jsonschema

class OutputValidator:
    def validate(
        self,
        output: str,
        output_schema: Dict,
    ) -> Tuple[bool, Optional[str], Optional[Dict]]:
        """
        校验输出是否符合 schema
        
        返回: (is_valid, error_message, parsed_data)
        """
        try:
            parsed = json.loads(output)
        except json.JSONDecodeError:
            return False, "Output is not valid JSON", None
        
        try:
            jsonschema.validate(parsed, output_schema)
            return True, None, parsed
        except jsonschema.ValidationError as e:
            return False, str(e), None

七、使用示例

7.1 创建 Prompt 模板

# 通过 API
POST /api/v1/prompts/templates
{
  "app_id": "project-mngt",
  "name": "task_decomposition",
  "version": "1.0.0",
  "template": "你是一个项目管理专家...",
  "variables": ["project_name", "project_type"],
  "output_schema": {
    "type": "object",
    "properties": {
      "tasks": {"type": "array"}
    }
  }
}

7.2 使用 Prompt 模板

# 在规则中使用
action:
  type: invoke_llm_generate_doc
  prompt_template: project-mngt.task_decomposition@1.0.0
  context_refs:
    entityIds: ["{{entity_id}}"]
  variables:
    project_name: "{{data.name}}"
    project_type: "{{data.project_type}}"

文档版本: v1.0
最后更新: 2025-12-17