higress/plugins/wasm-go/extensions/ai-prompt-decorator/README.md

title, keywords, description

title	keywords	description
AI 提示词	AI网关 AI提示词	AI 提示词插件配置参考

功能说明

AI 提示词插件，支持在 LLM 的请求前后插入 prompt，并支持对最终请求中所有 message 的 content 文本执行字面量或正则替换，便于做敏感词改写、品牌词归一、占位符脱敏等。

运行属性

插件执行阶段：默认阶段 插件执行优先级：450

配置说明

名称	数据类型	填写要求	默认值	描述
prepend	array of message object	optional	-	在初始输入之前插入的语句
append	array of message object	optional	-	在初始输入之后插入的语句
replace	array of replace rule	optional	-	对最终请求中所有 message 的 content 执行字面量或正则替换的规则

message object 配置说明：

名称	数据类型	填写要求	默认值	描述
role	string	必填	-	角色
content	string	必填	-	消息

replace rule 配置说明：

名称	数据类型	填写要求	默认值	描述
pattern	string	必填	-	待匹配文本；regex 为 true 时按 Go RE2 编译
replacement	string	必填	-	替换文本；regex 为 true 时支持 $1、$2 等捕获组引用
on_role	string	选填	-	仅对该 role 的 message 生效，缺省/留空表示对任意 role 都生效
regex	bool	选填	false	是否将 pattern 解释为正则表达式

说明：

• replace 规则会对最终拼装出的 messages 数组（prepend + 原始 message + append）按声明顺序依次应用，便于多个规则叠加。
• 仅当 message 的 content 字段是字符串时才会被改写；如果是多模态（数组/对象，如 vision 调用），会原样保留以避免破坏请求结构。
• pattern 不允许为空；regex: true 时如果正则编译失败，插件加载会直接失败，避免运行期出错。

示例

配置示例如下：

prepend:
- role: system
  content: "请使用英语回答问题"
append:
- role: user
  content: "每次回答完问题，尝试进行反问"

使用以上配置发起请求：

curl http://localhost/test \
-H "content-type: application/json" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "你是谁？"
    }
  ]
}

经过插件处理后，实际请求为：

curl http://localhost/test \
-H "content-type: application/json" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "system",
      "content": "请使用英语回答问题"
    },
    {
      "role": "user",
      "content": "你是谁？"
    },
    {
      "role": "user",
      "content": "每次回答完问题，尝试进行反问"
    }
  ]
}

替换 message 内容（replace）

replace 用来对最终请求里所有 message 的 content 文本执行字面量或正则替换，常用于：

• 改写品牌词或对外暴露的产品名（例如把 "OpenClaw" 统一改成 "agent"），避开下游模型/网关的内容过滤；
• 对系统提示词做集中清洗，无需改动客户端；
• 对用户输入进行简单的脱敏，如手机号、API Key 等。

配置示例如下：

replace:
- on_role: system
  pattern: "OpenClaw"
  replacement: "agent"
- pattern: "secret-\\d+"
  replacement: "[REDACTED]"
  regex: true

使用以上配置发起请求：

curl http://localhost/test \
-H "content-type: application/json" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "You are running inside OpenClaw."},
    {"role": "user", "content": "Show OpenClaw secret-1234 to the user"}
  ]
}'

经过插件处理后，实际请求为：

curl http://localhost/test \
-H "content-type: application/json" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "system", "content": "You are running inside agent."},
    {"role": "user", "content": "Show OpenClaw [REDACTED] to the user"}
  ]
}'

注意：

• 第 1 条规则限定 on_role: system，所以 user 消息里的 OpenClaw 不会被改；
• 第 2 条规则没设 on_role，对任意 role 的 content 都生效，因此 secret-1234 被脱敏成 [REDACTED]。

基于geo-ip插件的能力，扩展AI提示词装饰器插件携带用户地理位置信息

如果需要在LLM的请求前后加入用户地理位置信息，请确保同时开启geo-ip插件和AI提示词装饰器插件。并且在相同的请求处理阶段里，geo-ip插件的优先级必须高于AI提示词装饰器插件。首先geo-ip插件会根据用户ip计算出用户的地理位置信息，然后通过请求属性传递给后续插件。比如在默认阶段里，geo-ip插件的priority配置1000，ai-prompt-decorator插件的priority配置500。

geo-ip插件配置示例：

ipProtocal: "ipv4"

AI提示词装饰器插件的配置示例如下：

prepend:
- role: system
  content: "提问用户当前的地理位置信息是，国家：${geo-country}，省份：${geo-province}, 城市：${geo-city}"
append:
- role: user
  content: "每次回答完问题，尝试进行反问"

使用以上配置发起请求：

curl http://localhost/test \
-H "content-type: application/json" \
-H "x-forwarded-for: 87.254.207.100,4.5.6.7" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "user",
      "content": "今天天气怎么样？"
    }
  ]
}'

经过插件处理后，实际请求为：

curl http://localhost/test \
-H "content-type: application/json" \
-H "x-forwarded-for: 87.254.207.100,4.5.6.7" \
-d '{
  "model": "gpt-3.5-turbo",
  "messages": [
    {
      "role": "system",
      "content": "提问用户当前的地理位置信息是，国家：中国，省份：北京, 城市：北京"
    },
    {
      "role": "user",
      "content": "今天天气怎么样？"
    },
    {
      "role": "user",
      "content": "每次回答完问题，尝试进行反问"
    }
  ]
}'