POML Python Native Prompt 参考指南

导语

本文基于 POML 官方文档页面"Python POML Native Prompt"，聚焦 poml.prompt.Prompt 的类概述、上下文管理、渲染与调试方法，以及若干消息/结构化标签的用法与示例。所有信息均直接整理自官方内容，不做额外推断。

文档链接：microsoft.github.io/poml/stable...

类概述：`poml.prompt.Prompt`

继承自：_TagLib
作用：构建基于 ElementTree 的 XML 结构，并支持上下文管理（context-managed tags）。
源文件位置：python/poml/prompt.py
关键实现要点（来自文档展示的代码片段）：
- 内部维护 root_elements（根级元素列表）与 current_parent_stack（当前打开标签的父元素栈）。
- 通过 tag(tag_name, **attrs) 返回隐式的双端标签处理器 _ImplicitDualTagHandler（用于 with 语法管理标签的进入/退出）。

渲染与调试

render(chat=True, context=None, stylesheet=None) -> list | dict | str
- 说明：渲染最终 XML；若仍存在未关闭的标签会抛出错误。
- 行为（据文档代码）：内部先调用私有的 _generate_xml_string(pretty=False) 得到紧凑字符串，再调用 poml(final_xml, context=context, stylesheet=stylesheet, chat=chat) 返回结果。
dump_xml()
- 说明：返回美化后的 XML 字符串，便于调试与查看结果。

上下文管理与文本

__enter__()
- 说明：进入构建上下文；可在多个 with 块中复用同一个 Prompt 实例。每次进入会重置"当前打开元素栈"，但保留已创建的根元素，允许分段追加。
__exit__(exc_type, exc_val, exc_tb)
- 说明：退出 with 块时的清理；若存在未关闭的标签且无异常，将发出警告并清空打开元素栈。
text(content)
- 说明：向当前打开的 XML 元素添加文本；若没有打开的标签会报错。对于含子元素的混合内容，文本会追加到最近子元素的 tail；否则写入元素的 text。

消息与会话相关标签

system_message(**kwargs)
- 用途：将内容包装为系统消息。
- 示例（来自文档）：
  xml 复制代码
```
<system-msg>Answer concisely.</system-msg>
```
human_message(**kwargs)
- 用途：将内容包装为用户消息。
- 示例：
  xml 复制代码
```
<user-msg>What is the capital of France?</user-msg>
```
ai_message(**kwargs)
- 用途：将内容包装为 AI 消息。
- 示例：
  xml 复制代码
```
<ai-msg>Paris</ai-msg>
```
conversation(messages=None, selectedMessages=None, **kwargs)
- 用途：展示 system、human、ai 之间的会话。
- 参数要点：
  - messages：消息列表，每条包含 speaker 与 content 字段。
  - selectedMessages：可选的筛选字符串；不提供则选择全部。
    - 取单条："2"
    - 取区间（左闭右开）："2:4"
    - 取末尾若干："-6:"
- 示例：
  xml 复制代码
```
<conversation messages="{{[{ speaker: 'human', content: 'What is the capital of France?' }, { speaker: 'ai', content: 'Paris' }]}}" />
```

结构与格式标签（节选）

hint(caption=None, captionSerialized=None, captionStyle=None, captionTextTransform=None, captionColon=None, **kwargs)
- 用途：在提示任意位置提供简短的提示或解释。
- 关键参数（文档给出的默认与可选项）：
  - caption：标题/标签，默认 "Hint"。
  - captionSerialized：序列化标题（用于"serializer"语法），默认 "hint"。
  - captionStyle：仅对"markup"语法生效，默认 "bold"；可选 "header"、"bold"、"plain"、"hidden"。
  - captionTextTransform：仅对"markup"语法生效，默认 "none"；可选 "upper"、"level"、"capitalize"、"none"。
  - captionColon：是否在标题后添加冒号；对 bold/plain 默认 true，其他情况默认 false。
- 示例：
  xml 复制代码
```
<hint>Alice first purchased 4 apples and then 3 more, so she has 7 apples in total.</hint>
```
strikethrough(**kwargs)
- 用途：删除线（<s>、<strike>）表示删除或无效文本（用于"markup"语法）。
- 示例：
  xml 复制代码
```
<s>This messages is removed.</s>
```
sub_content(**kwargs)
- 用途：<section> 渲染嵌套内容（常跟在标题后），内部标题会自动降级一个层级。
- 示例：
  xml 复制代码
```
<h>Section Title</h>
<section>
  <h>Sub-section Title</h>
  <p>Sub-section details</p>
</section>
```

其他说明

文档还展示了 Prompt 的属性与内部实现细节（如属性准备、序列化、pretty-print 行为等），以及更多标签方法（如媒体、表格、列表、段落等）。本文仅节选了页面中给出明确定义与示例的若干项。

总结

poml.prompt.Prompt 提供基于 ElementTree 的 XML 构建能力，并以上下文管理的方式组织标签，便于构造结构化、可读的 POML 提示。文档展示了渲染/调试方法与多种标签（系统/用户/AI 消息、会话、提示、删除线、嵌套内容等）的定义与示例。实际使用时，可按需组合这些标签，并通过 render 输出最终结果或用 dump_xml 进行调试。

参考文档：

microsoft.github.io/poml/stable...

POML Python Native Prompt 参考指南

POML Python Native Prompt 参考指南

导语

类概述：poml.prompt.Prompt

渲染与调试

上下文管理与文本

消息与会话相关标签

结构与格式标签（节选）

其他说明

总结

类概述：`poml.prompt.Prompt`