POML Python Native Prompt 参考指南

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