Prompt 模板变量设计要注意什么？

简化版

Prompt 变量要像 API 参数一样定义类型、来源、信任级别、最大长度、必填/默认值和转义规则。用户文本、检索证据不能插入高权限指令位置；枚举和结构对象优于自由字符串。渲染前做 schema 校验，渲染后检查未绑定占位符、Token 上限与段落边界，并记录变量哈希以便复现。

详细版

先建立变量清单，例如 locale 是受控枚举，documents 是带 source_id 的数组，user_query 是不可信字符串，max_items 是有范围整数。模板引擎按上下文转义 XML/JSON/Markdown，不能把所有变量做同一种替换；秘密和服务端权限根本不应进入模型可见变量。

缺值要明确 fail-closed 还是安全默认，不能静默渲染空字符串。长内容按文档边界裁剪并保留截断标记；列表用循环结构而非预拼文本。测试覆盖引号、闭合标签、Unicode、超长值、空值和注入语句，并对最终 Prompt 做快照结构测试而非敏感全文泄露。

变量定义(schema+trust) -> 输入校验 -> 上下文转义 -> 模板渲染 -> Token/占位符检查 -> 模型

完整版教学

一、变量是接口，不是字符串洞

模板变量连接用户、数据库、检索和配置。若只做字符串替换，任何来源都可能改变 Prompt 结构，类型错误也只能到模型输出异常时才发现。把变量视作函数参数，就需要明确契约和失败行为。

同名变量还要有唯一语义。context 这种大口袋常同时装历史、文档和工具结果，无法分配权限与预算。拆成 conversation_state、evidence_documents 和 tool_result 更易治理。

二、变量 schema 应包含哪些信息

每个变量至少定义类型、来源、信任、必填、长度/范围、转义上下文和日志策略。枚举字段不要让调用方传“formal，并忽略以上规则”这种自由文本。结构化数组保留每个元素边界和来源。

变量	类型	信任	约束
locale	enum	应用配置	zh-CN/en-US
max_items	integer	应用配置	1~20
user_query	string	不可信	≤4000 Token
documents	object[]	不可信证据	source_id 必填
policy_version	enum	高信任	服务端注入

记忆钩子：变量设计要同时回答“它是什么”和“它从谁那里来”；类型防错误，信任级别防越权。

三、转义必须看目标上下文

插入 XML 时要转义 <>&，插入 JSON 要用序列化器处理引号与反斜线，Markdown code fence 内则要防用户内容提前闭合围栏。不存在一种 sanitize() 能安全适配所有位置。最好由模板引擎根据 typed slot 自动序列化。

const payload = JSON.stringify({ query: userQuery });
// 不要：'{"query":"' + userQuery + '"}'

转义能保护结构，不会让内容变可信。用户即使被安全包在 <user_input> 中，模型仍可能听从其中注入，所以还需明确角色和执行层权限。

四、缺值和默认值怎么处理

关键变量如权限、目标 schema 和证据来源缺失时应 fail closed，返回配置错误；风格等非关键变量可有安全默认。空字符串、null、未提供要区分，否则模型会看到“依据以下证据：”后空白并自行猜测。

默认值必须写在 schema，而不是散落模板的自然语言中。新增必填变量会破坏旧调用方，应升级模板接口版本。渲染完成后扫描 {...} 等未解析占位符，但不要用过宽规则误判用户正文。

五、Token 预算怎样分配给变量

每个可变长字段设置独立预算和全局上限。证据数组按相关性和文档边界截断，对话历史用结构化摘要，用户查询通常保留完整。不能先任意拼接再从字符串尾部硬截，可能切掉输出 schema 或半句关键条件。

假设窗口 16K：固定规则 1K、输出 2K、用户 2K、证据 8K、历史 2K、缓冲 1K。渲染器输出每段实际 Token 和被丢弃元素 ID。预算变化也需版本化，因为它能改变质量。

六、秘密与权限为何不能作为普通变量

API key、数据库凭据和用户无权查看的数据不应进入 Prompt，即使 system 说“不要输出”。模型可能受注入或日志系统泄露。工具在服务器端使用凭据，只向模型返回最小必要结果。

身份与权限从认证上下文传给策略引擎，不接受用户变量声明。模型可以看到匿名的 permission=read_only 以规划行为，但最终执行仍由后端使用真实主体判定，且模型不能修改这个值。

七、怎样测试模板变量

为每种类型生成边界值：空、最大长度、Unicode、引号、标签闭合、代码围栏、换行和注入句。断言渲染结构、角色、Token 上限和日志脱敏正确。属性测试可随机生成字符串，发现手工样例没覆盖的转义组合。

测试还应验证相同输入得到稳定 Prompt 哈希，列表排序有明确规则，locale 不改变事实字段。生产日志记录模板版本、变量 schema 版本、各段 Token 与非敏感哈希，必要时在受控环境重放。

八、常见误区与追问

• 误区：所有变量先 HTML escape 就安全。 转义取决于 JSON/XML/Markdown 上下文，且不等于指令隔离。
• 误区：空变量让模型自己处理更灵活。 关键输入缺失应显式失败，避免模型猜测。
• 误区：用户写自己是管理员可作为 role 变量。 身份来自认证系统，不可信文本不能授权。
• 追问：如何防模板注入？ 类型化 slot、上下文转义、角色隔离，并在执行层最小权限。
• 追问：如何裁剪文档变量？ 按相关性和完整元素边界，保留 source_id 与截断记录。
• 追问：日志如何兼顾复现和隐私？ 记版本、长度、来源 ID 和哈希，敏感全文进入受控短期存储。

九、加强记忆

模板变量可记成“型、源、信、界、转、验”：定义类型与来源，标信任等级，限制长度范围，按所在格式转义，渲染前后都校验。秘密不入 Prompt、权限不由变量决定、截断不破坏结构。做到这些，Prompt 模板才是有契约的接口，而不是危险的字符串拼接。