跳转到主要内容
Prompt 工具把 prompt 文本当作结构化运行时数据，而不是散落的 f-string。
本页从轻量字符串构建器开始，再展示它们如何连接到 fast_prompt_section(...) 与 Prompt 实体。

​
1. 核心思想

LLM 应用大量时间用于组装上下文：任务描述、示例、输入 schema、指令，以及待求解的新实例。若每个调用点都手写格式，prompt 会漂移且难以测试。 HeavenBase 将 prompt 工作分为三层：
  • 字符串与 Markdown helper 生成稳定的文本块。
  • fast_prompt_section(...) 将常见 agent 区块转为 OpenAI 风格消息。
  • Prompt 把可调用 prompt 与模板 prompt 存为工作区行，并支持可选翻译。

​
2. 构建可读的 Prompt 文本

需要跨生成 prompt、报告与测试保持稳定的 Markdown 时使用字符串 helper。 
from heavenbase.utils import bullet_list, code_block, md_section

content = md_section(
    title="Task",
    content="Inspect the workspace and report the next action.",
    sections=[
        {"title": "Rules", "content": bullet_list(["Read files first", "Use HeavenBase utilities"])},
        {"title": "Example", "content": code_block("result = hb.HeavenBase.load('demo')", lang="python")},
    ],
)
prompt 需要结构化示例而非手写字符串时，使用 json_block(...)、file_block(...)、example_block(...)、bullet_dict(...) 与 numbered_list(...)。

​
3. 组装 Agent 消息

常见 agent prompt 需要描述、示例、指令与新输入实例时，使用 fast_prompt_section(...)。 
import heavenbase as hb

messages = hb.fast_prompt_section(
    system="You are a task agent using HeavenBase as memory.",
    descriptions={"Context": ["Workspace: docs-demo", "Mode: dry-run"]},
    instructions=[
        "Inspect relevant files before running commands.",
        "Return one concise status update.",
    ],
)

user_message = messages[-1]["content"]
目标 LLM 路径需要独立 system 消息时传入 separate_system=True。

​
4. 持久化可复用 Prompt

prompt 应成为可调用对象与工作区行时使用 hb.Prompt(...)。 
import heavenbase as hb

welcome = hb.Prompt("Hello, {name}", name="demo.welcome")
text = welcome(name="Ada")
构造不会写入工作区。有意将 prompt 存为 sys-prompt 行时调用 register(...)。 
import heavenbase as hb

ws = hb.HeavenBase("prompt-docs", preset="debug")
welcome = hb.Prompt("Hello, {name}", name="demo.welcome", ws=ws)
welcome.register(ws=ws)
loaded = hb.Prompt.load("demo.welcome", ws=ws)
Prompt 行可恢复可执行的 Capsule manifest。仅从你信任的工作区加载已持久化的 prompt。

​
5. 翻译 Prompt 文本

每个 prompt 在 prompt.tr 绑定翻译 helper。精确翻译优先，其次是用 {placeholder} 捕获的模板模式翻译。 
import heavenbase as hb

ws = hb.HeavenBase("prompt-tr-docs", preset="debug")
prompt = hb.Prompt("Hello, {name}", name="demo.hello", ws=ws)
prompt.tr.set("Hello, {name}", "zz", "HEY, {name}")

assert prompt(name="Ada", lang="zz") == "HEY, Ada"
语言解析顺序：显式 lang=...，然后 prompt 对象绑定的语言，然后 heavenbase.prompt.lang，最后 prompt 的 main_lang。

​
Further Exploration

相关资源：
  • Prompts - 完整 prompt 实体、翻译与 CLI 表面。
  • LLM 概述 - prompt 如何流入 hb.LLM。
  • 配置 - heavenbase.prompt 下的 prompt 语言默认值。