API7 网关 AI Agent Skill：ai-prompt-template 插件

概览

ai-prompt-template 插件通过预配置提示词模板和 {{variable}} 占位符处理 Chat Completions 请求。客户端只需提交模板名称和变量值，插件就会填充模板并生成完整请求。这样可以强制统一提示词结构，避免客户端发送任意系统提示词。

优先级：1071

该插件在优先级为 1070 的 ai-prompt-decorator 和优先级为 1040 的 ai-proxy 之前运行。

适用场景

• 在所有客户端之间强制使用固定的提示词结构。
• 仅允许用户为指定字段提供输入（填空式输入）。
• 通过控制系统消息防止提示词注入。
• 构建由客户端按名称选择的提示词库。
• 直接在服务或路由上统一提示词模板。

插件配置参考

字段	类型	是否必填	说明
templates	array	是	模板对象数组（至少 1 个）
templates[].name	string	是	模板标识符（最小长度为 1）
templates[].template	object	是	模板规格
templates[].template.model	string	是	AI 模型名称
templates[].template.messages	array	是	消息对象数组（至少 1 个）
templates[].template.messages[].role	string	是	system, user, 或 assistant
templates[].template.messages[].content	string	是	使用 {{variable}} 占位符的提示词内容

客户端请求格式

客户端不再发送标准的 messages 数组，而是发送：

{
  "template_name": "my-template",
  "variable1": "value1",
  "variable2": "value2"
}

分步指南：创建模板化路由

1. 使用 ai-prompt-template 和 ai-proxy 创建路由

所有运行时资源都必须通过 --gateway-group 或 -g 参数限定在一个网关组中。

a7 service create -g default -f - <<'EOF'
{
  "id": "ai-chat-service",
  "name": "AI Chat Service"
}
EOF

a7 route create -g default -f - <<'EOF'
{
  "id": "templated-chat",
  "uri": "/v1/chat/completions",
  "service_id": "ai-chat-service",
  "methods": ["POST"],
  "plugins": {
    "ai-proxy": {
      "provider": "openai",
      "auth": {
        "header": {
          "Authorization": "Bearer sk-your-key"
        }
      },
      "options": {
        "model": "gpt-4"
      }
    },
    "ai-prompt-template": {
      "templates": [
        {
          "name": "code-review",
          "template": {
            "model": "gpt-4",
            "messages": [
              {
                "role": "system",
                "content": "You are an expert {{language}} code reviewer. Review the code for bugs, performance issues, and style."
              },
              {
                "role": "user",
                "content": "Review this code:\n\n{{code}}"
              }
            ]
          }
        }
      ]
    }
  }
}
EOF

2. 使用模板变量发送请求

curl http://127.0.0.1:9080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "template_name": "code-review",
    "language": "Python",
    "code": "def add(a, b): return a + b"
  }'

使用服务

你可以在服务上定义标准提示词模板，并将路由关联到该服务。

a7 service create -g default -f - <<'EOF'
{
  "id": "global-ai-prompts",
  "name": "Global AI Prompts",
  "plugins": {
    "ai-prompt-template": {
      "templates": [
        {
          "name": "summarize",
          "template": {
            "model": "gpt-4",
            "messages": [
              {"role": "system", "content": "Summarize this in one sentence."},
              {"role": "user", "content": "{{text}}"}
            ]
          }
        }
      ]
    }
  }
}
EOF

配置同步示例

配置同步的作用域由网关组限定：

a7 config sync -f config.yaml --gateway-group default

version: "1"
services:
  - id: ai-chat-service
    name: AI Chat Service
routes:
  - id: templated-chat
    uri: /v1/chat/completions
    service_id: ai-chat-service
    methods:
      - POST
    plugins:
      ai-proxy:
        provider: openai
        auth:
          header:
            Authorization: Bearer sk-your-key
        options:
          model: gpt-4
      ai-prompt-template:
        templates:
          - name: code-review
            template:
              model: gpt-4
              messages:
                - role: system
                  content: "You are an expert {{language}} code reviewer."
                - role: user
                  content: "Review this code:\n\n{{code}}"

故障排查

现象	原因	解决方法
400 "template not found"	template_name 与已配置模板不匹配	检查拼写和大小写
{{variable}} 未填充	请求体中缺少变量键	在请求 JSON 中包含所有变量
404 Not Found	缺少 --gateway-group	确保所有运行时命令都包含 -g <group>
插件未转换请求	插件名称错误	验证插件名称为 ai-prompt-template

---

本页面由 api7/a7 仓库中的 a7-plugin-ai-prompt-template/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。