🔍 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) 渲染最终 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) 将内容包装为系统消息；human_message(**kwargs) 将内容包装为用户消息；ai_message(**kwargs) 将内容包装为 AI 消息；conversation(messages=None, selectedMessages=None, **kwargs) 展示 system、human、ai 之间的会话，messages 为消息列表，每条包含 speaker 与 content 字段。

💡 hint(caption=None, captionSerialized=None, captionStyle=None, captionTextTransform=None, captionColon=None, **kwargs) 在提示任意位置提供简短的提示或解释，caption 默认 'Hint'，captionStyle 默认 'bold'。

🚫 strikethrough(**kwargs) 删除线（<s>、<strike>；）表示删除或无效文本（用于“markup”语法）。

📦 sub_content(**kwargs) <section> 渲染嵌套内容（常跟在标题后），内部标题会自动降级一个层级。

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)
用途：将内容包装为系统消息。示例（来自文档）：

<system-msg>Answer concisely.</system-msg>

human_message(**kwargs)
用途：将内容包装为用户消息。示例：

<user-msg>What is the capital of France?</user-msg>

ai_message(**kwargs)
用途：将内容包装为 AI 消息。示例：

<ai-msg>Paris</ai-msg>

conversation(messages=None, selectedMessages=None, **kwargs)
用途：展示 system、human、ai 之间的会话。参数要点：
messages：消息列表，每条包含 speaker 与 content 字段。selectedMessages：可选的筛选字符串；不提供则选择全部。
取单条："2"取区间（左闭右开）："2:4"取末尾若干："-6:"
示例：

<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。
示例：

<hint>Alice first purchased 4 apples and then 3 more, so she has 7 apples in total.</hint>

strikethrough(**kwargs)
用途：删除线（<s>、<strike>）表示删除或无效文本（用于“markup”语法）。示例：

<s>This messages is removed.</s>

sub_content(**kwargs)
用途：<section> 渲染嵌套内容（常跟在标题后），内部标题会自动降级一个层级。示例：

<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…