《互联网产品的 AI 架构·模型接入与能力边界》6.1 提示是产物，不是字符串

你是「回声」的私信回复助手。只根据对话内容生成回复，不得编造订单状态。

// file: src/prompt/template.ts
// tier: L1
// verify: node --test test/prompt/template.test.ts

import { AiError } from "../core/errors.ts";

export type VariableType = "string" | "number" | "boolean";

export interface VariableSpec {
  type: VariableType;
  /** 缺省视为必填；可选变量缺失时渲染为空串。 */
  required?: boolean;
  /** 渲染后文本的最大字符数，按 Unicode 码点计，不是 token。 */
  maxChars?: number;
}

export interface PromptTemplate {
  id: string;
  version: string;
  owner: string;
  body: string;
  variables: Record<string, VariableSpec>;
}

export type Segment =
  | { kind: "text"; text: string }
  | { kind: "slot"; name: string; index: number };

export interface CompiledPrompt {
  template: PromptTemplate;
  segments: Segment[];
  /** 变量首次出现的顺序，去重。 */
  variables: string[];
}

export type PromptValues = Record<string, string | number | boolean | undefined>;

const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;

function fail(message: string): never {
  throw new AiError("invalid-request", `prompt: ${message}`);
}

/**
 * 只接受 {{name}}。表达式、过滤器、注释与局部模板全部拒绝：
 * 提示里一旦出现图灵完备的模板逻辑，评审就无法只靠阅读判断它会输出什么。
 */
export function parseTemplate(body: string): Segment[] {
  const segments: Segment[] = [];
  let cursor = 0;
  while (cursor < body.length) {
    const open = body.indexOf("{{", cursor);
    const close = body.indexOf("}}", cursor);
    if (close !== -1 && (open === -1 || close < open)) {
      fail(`stray "}}" at ${close}`);
    }
    if (open === -1) {
      if (cursor < body.length) {
        segments.push({ kind: "text", text: body.slice(cursor) });
      }
      break;
    }
    if (open > cursor) {
      segments.push({ kind: "text", text: body.slice(cursor, open) });
    }
    const end = body.indexOf("}}", open + 2);
    if (end === -1) {
      fail(`unclosed "{{" at ${open}`);
    }
    const raw = body.slice(open + 2, end);
    const name = raw.trim();
    if (name === "") {
      fail(`empty placeholder at ${open}`);
    }
    if (!NAME.test(name)) {
      fail(`unsupported placeholder "${name}"`);
    }
    segments.push({ kind: "slot", name, index: open });
    cursor = end + 2;
  }
  return segments;
}

/**
 * 编译期做三件事：名字合法、槽位都有声明、声明的变量都被使用。
 * 最后一条用来抓 schema 漂移：模板删了变量但声明还在，评审会误以为它仍生效。
 */
export function compilePrompt(template: PromptTemplate): CompiledPrompt {
  if (template.id.trim() === "") fail("id is required");
  if (template.version.trim() === "") fail("version is required");
  if (template.owner.trim() === "") fail("owner is required");
  if (template.body === "") fail("body is required");

  const declared = Object.keys(template.variables);
  for (const name of declared) {
    if (!NAME.test(name)) fail(`invalid variable name "${name}"`);
    const spec = template.variables[name];
    if (spec.type !== "string" && spec.type !== "number" && spec.type !== "boolean") {
      fail(`invalid type for "${name}"`);
    }
    if (
      spec.maxChars !== undefined &&
      (!Number.isInteger(spec.maxChars) || spec.maxChars <= 0)
    ) {
      fail(`maxChars for "${name}" must be a positive integer`);
    }
  }

  const segments = parseTemplate(template.body);
  const used: string[] = [];
  for (const segment of segments) {
    if (segment.kind !== "slot") continue;
    if (!Object.hasOwn(template.variables, segment.name)) {
      fail(`undeclared variable "${segment.name}"`);
    }
    if (!used.includes(segment.name)) used.push(segment.name);
  }
  for (const name of declared) {
    if (!used.includes(name)) fail(`declared but unused variable "${name}"`);
  }
  return { template, segments, variables: used };
}

function formatValue(
  name: string,
  spec: VariableSpec,
  value: string | number | boolean,
): string {
  let text: string;
  if (spec.type === "string") {
    if (typeof value !== "string") fail(`variable "${name}" expects string`);
    text = value;
  } else if (spec.type === "number") {
    if (typeof value !== "number" || !Number.isFinite(value)) {
      fail(`variable "${name}" expects finite number`);
    }
    text = String(value);
  } else {
    if (typeof value !== "boolean") fail(`variable "${name}" expects boolean`);
    text = value ? "true" : "false";
  }
  if (spec.maxChars !== undefined && [...text].length > spec.maxChars) {
    fail(`variable "${name}" exceeds maxChars ${spec.maxChars}`);
  }
  return text;
}

/** 渲染不做隐式默认值：缺失的必填变量直接失败，可选变量渲染为空串。 */
export function renderPrompt(compiled: CompiledPrompt, values: PromptValues): string {
  const parts: string[] = [];
  for (const segment of compiled.segments) {
    if (segment.kind === "text") {
      parts.push(segment.text);
      continue;
    }
    const spec = compiled.template.variables[segment.name];
    const value = values[segment.name];
    if (value === undefined) {
      if (spec.required !== false) fail(`missing required variable "${segment.name}"`);
      continue;
    }
    parts.push(formatValue(segment.name, spec, value));
  }
  return parts.join("");
}

node --test test/prompt/template.test.ts

✔ 编译保留字面量与槽位顺序 (1.355208ms)
✔ 同一变量可以重复出现，渲染时逐处替换 (0.148875ms)
✔ 未声明的变量在编译期失败 (0.261792ms)
✔ 声明但未使用的变量被视为 schema 漂移 (0.089458ms)
✔ 缺少必填变量时不渲染半个提示 (0.094791ms)
✔ 可选变量缺失渲染为空串，而不是塞默认值 (0.06575ms)
✔ 类型不符在渲染期失败 (0.088791ms)
✔ maxChars 按 Unicode 码点计数 (0.087ms)
✔ 表达式、过滤器与注释语法一律拒绝 (0.111959ms)
✔ 未闭合与多余的括号都被拒绝 (0.143375ms)
ℹ tests 10
ℹ suites 0
ℹ pass 10
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 202.993541