POML：Token 控制（Token Control）

导语

POML 提供对内容长度的精细控制能力，包括字符限制（charLimit）、令牌限制（tokenLimit）以及基于优先级的截断（priority）。当需要满足大模型输入长度约束或确保内容在既定边界内时，这些特性尤为实用。注意：该功能为实验性特性，未来可能发生变更；仅对以 syntax="text" 或 syntax="markdown" 渲染的组件生效。

功能概览

字符与令牌限制 ：通过 charLimit 与 tokenLimit 对内容设置"软限制"，超出时自动截断并追加标记。
基于优先级的截断 ：使用 priority 控制在空间不足时保留或优先移除的内容。数值越低（含默认 0），优先被截断；数值越高，优先保留。
截断行为可配置 ：writerOptions 可自定义截断标记、截断方向及令牌计数模型：
- truncateMarker：截断时追加的文本，默认 (...truncated)。
- truncateDirection："end"（默认）/"start"/"middle"。
- tokenEncodingModel：用于计数的模型名，默认 "gpt-4o"（采用 o200k_base 编码，基于 js-tiktoken）。

适用场景

受输入长度约束的 AI 应用：当大模型存在上下文/输入长度限制时，需按令牌或字符数对内容进行裁剪。
需保证内容适配固定边界：在页面、摘要、消息等场景确保内容不超过指定长度。

配置与用法

1）适用语法

仅对以 syntax="text" 或 syntax="markdown" 渲染的组件启用 Token 控制。

text 复制代码

syntax="text"

text 复制代码

syntax="markdown"

2）字符与令牌限制

使用 charLimit 和 tokenLimit 设置软限制，超出即自动截断，并在尾部追加截断标记：

xml 复制代码

<poml>
  <!-- 限制为 100 个字符 -->
  <p charLimit="100">
    This is a very long paragraph that will be truncated if it exceeds the character limit. The truncation will add a marker to indicate that content was cut off.
  </p>

  <!-- 按令牌计数（示例为 10 个 token）更贴近模型处理 -->
  <p tokenLimit="10">
    This paragraph will be truncated based on token count rather than character count, which is more accurate for AI model processing.
  </p>
</poml>

渲染效果示例（会附加截断标记）：

text 复制代码

This is a very long paragraph that will be truncated if it exceeds the character limit. The truncati (...truncated)
This paragraph will be truncated based on token count rather (...truncated)

3）自定义截断行为（writerOptions）

可通过 writerOptions 控制截断标记、方向与计数模型：

truncateMarker（默认 (...truncated)）
truncateDirection："end" | "start" | "middle"
tokenEncodingModel：默认 "gpt-4o"（o200k_base 编码）

示例：保留开头与结尾，截断中间并替换自定义标记。

xml 复制代码

<p charLimit="20" writerOptions='{ "truncateMarker": " [...] ", "truncateDirection": "middle"}'>
  This is a very long paragraph that will be truncated if it exceeds the character limit. The truncation will add a marker to indicate that content was cut off.
</p>

渲染效果：

text 复制代码

This is a [...] s cut off.

说明：默认分词器基于 js-tiktoken 的 o200k_base 编码（用于 gpt-4o 到 o3 模型）。可在 writerOptions.tokenEncodingModel 中指定模型名以自定义计数行为。

基于优先级的截断（Priority-Based Truncation）

priority 控制空间紧张时的保留顺序。数值越低（含未显式设置时的默认 0），越早被截断；数值越高，则更优先保留。

xml 复制代码

<poml tokenLimit="40">
  <p priority="1">This content has low priority and may be removed first to save space.</p>
  <p priority="3">This content has high priority and will be preserved longer.</p>
  <p priority="2">This content has medium priority.</p>
  <!-- 未设置 priority 的内容默认为 0（最低），最先被截断 -->
  <p>This content will be truncated first since it has no explicit priority.</p>
</poml>

当进一步收紧限制（例如令牌上限降至 8）时，仅保留最高优先级内容，且其本身也可能被截断并附加标记：

text 复制代码

This content has high priority and will be (...truncated)

组合使用与计算顺序

可将限额与优先级结合，实现更细粒度的内容管理。父子组件存在分层的令牌计算顺序：

先处理子组件：考虑其各自的限额与优先级。
按优先级排序：优先移除低优先级子内容（必要时整块移除）。
仍超限则继续截断：对剩余内容进行截断。
再应用 charLimit/tokenLimit：在优先级移除之后应用组件级限额。

示例：

xml 复制代码

<poml tokenLimit="40">
  <h priority="5">Critical Section Header</h>
  <p priority="4" charLimit="10">
    Important introduction that should be preserved but can be shortened individually.
  </p>
  <list priority="2">
    <item priority="3">High priority item</item>
    <item priority="1">Lower priority item</item>
    <item>Lowest priority item (no explicit priority)</item>
  </list>
  <p priority="3" tokenLimit="5">Optional additional context that can be truncated aggressively.</p>
</poml>

渲染效果示例：

text 复制代码

# Critical Section Header
Important (...truncated)
Optional additional context that can (...truncated)

注意事项

实验性：该能力为实验特性，未来可能变化，使用需谨慎。
适用范围 ：仅对 syntax="text" 或 syntax="markdown" 的组件生效。
令牌计数 ：默认使用 js-tiktoken 的 o200k_base 编码（示例模型 gpt-4o/o3）；可通过 writerOptions.tokenEncodingModel 自定义。

总结

POML 的 Token 控制围绕"限额 + 优先级 + 可配置截断"三要素展开：

通过 charLimit/tokenLimit 设定软限制；
借助 priority 定义保留顺序；
使用 writerOptions 调整截断标记、方向与计数模型。

该能力适合需要满足输入边界或令牌预算的场景。鉴于其为实验性特性，建议在实际项目中结合具体模型与内容结构，谨慎启用并充分测试。