POML Meta 元素与运行配置（Meta, Stylesheet, Output Schema, Tools, Runtime）

参考官方文档：

Meta（稳定版）：microsoft.github.io/poml/stable...

相关：Components：microsoft.github.io/poml/stable...

TS 概览：microsoft.github.io/poml/stable...

概览

Meta 元素：为 POML 文档提供"版本约束、组件启用/禁用"等核心配置。
类 Meta 组件 ：不直接渲染为 LLM 消息，但影响渲染/执行：
- <stylesheet>：样式（以 JSON 方式批量设置组件属性）。
- <output-schema>：响应模式（约束模型输出结构）。
- <tool-definition> / <tool>：工具注册（为模型声明可调用函数）。
- <runtime>：运行时参数（温度、top-p、模型名、最大输出 token 等）。

基本用法（不产生可见输出）

位置：通常放在 <poml> 开头；一个文档内可出现多次，但需避免冲突。
常用属性：
- minVersion / maxVersion：版本范围（语义化版本号）。
- components：启用/禁用组件与别名（见下文）。

示例：

poml 复制代码

<poml>
  <meta minVersion="0.5.0" maxVersion="2.0.0" />
  <p>Your content here</p>
</poml>

组件开关（Component Control）

在 components 中使用前缀 - 禁用组件：

poml 复制代码

<poml>
  <meta components="-table,-image" />
  <p>Now <table> and <image> will throw errors if used.</p>
</poml>

使用前缀 + 重新启用：

poml 复制代码

<poml>
  <meta components="-table" />
  <!-- later -->
  <meta components="+table" />
</poml>

可独立禁用"别名"（alias），而不影响主组件名。

样式表（批量设置组件属性）

写法：根 <poml> 下的一个 JSON 对象，键为组件名或类选择器，值为要设置的属性集合。
作用：相当于用"样式"给组件批量对齐属性（如语法、渲染选项）。

示例 1：为所有 <p> 设置 syntax="json"

poml 复制代码

<poml>
  <stylesheet>
    { "p": { "syntax": "json" } }
  </stylesheet>
  <p>{"name":"Alice"}</p>
</poml>

示例 2：使用 className + 选择器（.csv）并设置 writerOptions（注意转义）

poml 复制代码

<poml>
  <table className="csv" records="[[1,2,3],[4,5,6]]"/>
  <stylesheet>
    {
      ".csv": {
        "syntax": "csv",
        "writerOptions": "{\\\"csvSeparator\\\": \\\";\\\", \\\"csvHeader\\\": false}"
      }
    }
  </stylesheet>
</poml>

提示：writerOptions 当前为实验性 API，字符串中的 JSON 需正确转义反斜杠与引号。

响应模式（让输出可解析、可验证）

目的：将自由文本输出约束为结构化数据（JSON Schema、或 JS 表达式返回 Zod/JSON Schema）。
仅允许文档内出现一个 <output-schema>。
格式一（JSON Schema）：

poml 复制代码

<poml>
  <output-schema parser="json">
    {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age":  { "type": "number" }
      },
      "required": ["name"]
    }
  </output-schema>
</poml>

支持模板表达式：

poml 复制代码

<poml>
  <let name="maxAge" value="100" />
  <output-schema parser="json">
    {
      "type": "object",
      "properties": {
        "age": { "type": "number", "minimum": 0, "maximum": {{ maxAge }} }
      }
    }
  </output-schema>
</poml>

格式二（表达式 eval → Zod/JSON Schema）：

poml 复制代码

<poml>
  <let name="fields" value='["name", "email", "age"]' />
  <output-schema parser="eval">
    z.object(Object.fromEntries(fields.map(f => [f, z.string()])))
  </output-schema>
</poml>

工具注册： /

目的：让模型在对话中"可调用函数"。
两种格式与响应模式一致：parser="json" 或 parser="eval"（Zod）。

JSON Schema 格式：

poml 复制代码

<poml>
  <tool-definition name="getWeather" description="Get weather information">
    {
      "type": "object",
      "properties": {
        "location": { "type": "string" },
        "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
      },
      "required": ["location"]
    }
  </tool-definition>
</poml>

表达式（Zod）格式：

poml 复制代码

<poml>
  <tool-definition name="calculate" description="Perform calculation" parser="eval">
    z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
      a: z.number(),
      b: z.number()
    })
  </tool-definition>
</poml>

属性也可用模板表达式：

poml 复制代码

<poml>
  <let name="toolName">calculate</let>
  <let name="toolDesc">Perform mathematical calculations</let>
  <let name="schemaParser">json</let>
  <tool-definition name="{{toolName}}" description="{{toolDesc}}" parser="{{schemaParser}}">
    { "type": "object", "properties": { "operation": { "type": "string" } } }
  </tool-definition>
</poml>

注：与响应模式配合的工具使用，取决于所选模型/提供商（OpenAI 等）。

运行参数（类型自动转换 + 键名转换）

示例：

poml 复制代码

<poml>
  <runtime
    provider="openai"
    model="gpt-5"
    temperature="0.7"
    top-p="0.9"
    max-output-tokens="1000"
    frequency-penalty="0.2"
    presence-penalty="0.1"
    stop='["END", "STOP"]'
  />
</poml>

键名转换：kebab-case → camelCase（如 max-output-tokens → maxOutputTokens，top-p → topP）。
值转换：
- 布尔字符串："true" / "false" → true / false
- 数字字符串："1000"、"0.7" → 1000、0.7
- JSON 字符串：'[...]'、'{...}' → 解析为数组/对象
VS Code 内置运行器基于 Vercel AI SDK，参数支持以其为准。
Python SDK ：运行参数键将转为 snake_case 返回，如 maxOutputTokens → max_output_tokens，topP → top_p。

实战组合小例（版本 + 组件开关 + 样式 + 结构化输出 + 运行参数）

poml 复制代码

<poml>
  <meta minVersion="0.5.0" />
  <meta components="-image" />

  <stylesheet>
    { "p": { "syntax": "json" } }
  </stylesheet>

  <let name="maxAge" value="120" />
  <output-schema parser="json">
    {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "age":  { "type": "number", "maximum": {{ maxAge }} }
      },
      "required": ["name"]
    }
  </output-schema>

  <runtime model="gpt-5" temperature="0.6" max-output-tokens="800" />

  <p>{"task":"Return a JSON object with name and age"}</p>
</poml>

常见坑与建议

多个 <meta>：允许但要避免相互矛盾（如同一组件反复启/禁）。
样式 JSON 格式 ：必须是合法 JSON；字符串中的 JSON（如 writerOptions）要正确转义。
响应模式唯一性 ：一个文档仅允许一个 <output-schema>。
工具 + 响应模式：仅部分模型/提供商支持二者联用，按实际 SDK 能力确认。
运行参数：理解键名/值的自动转换；注意 VS Code 运行器与 Python SDK 的差异。

参考与下一步

Meta（稳定版）：microsoft.github.io/poml/stable...
Components： microsoft.github.io/poml/stable...
语法基础： microsoft.github.io/poml/stable...
VS Code 扩展：microsoft.github.io/poml/stable...
Python SDK： microsoft.github.io/poml/stable...