提示 (Prompt)

语言不是文字，而是信息到表达的映射。

HeavenBase 中的提示不是粘贴进 LLM 调用的字符串，而是将任意输入转为模型实际所见文本或消息的可调用对象。本页说明该编码器模型、用于格式化提示文本的 Markdown 辅助函数、单次布局约定，以及 hb.Prompt 如何将提示持久化为 Capsule 支持的工作区行并内置一等翻译。

1. 为何需要提示工具

没有提示系统时，每个 LLM 调用点都用原始 f-string 自行拼装提示文本。结果是提示漂移：一个端点用一种格式写指令，另一个端点换种措辞，且没有关于「提示应说什么」的单一事实来源。

# Anti-pattern: prompt text scattered as ad-hoc f-strings
system_prompt = f"You are a helpful assistant. Task: {task}. Use these tools: {tools}"
user_prompt = f"Context: {context}\n\nQuestion: {question}"

# Another file, different style:
instructions = "## Task\n" + task + "\n## Tools\n" + tools

这种方式把语言当作成品文本。实践中，提示是一种编码器 (encoder)：它将结构化信息——任务上下文、示例、当前实例——映射为模型可执行的表达。提示若以字符串形式存在，则难以测试、难以版本化，且无法在不复制整段模板的情况下本地化。 HeavenBase 将提示建模为返回渲染文本或消息的函数：

import heavenbase as hb

@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"

greet.register()
assert greet("Ada") == "Hello, Ada!"

可调用对象即提示。参数是载荷 (payload)。返回值是 LLM 所读内容。这种分离把逻辑留在代码中、把数据放在参数里，并使渲染结果足够稳定，便于测试与翻译。可调用编码器也比格式字符串模板更灵活。函数体可按载荷形状分支、组装实例相关段落、调用工作区辅助函数，甚至调用元提示器 (meta-prompter) LLM 根据实际输入起草 system 文本。字符串模板覆盖简单的填空场景；函数提示覆盖其余一切。

2. 提示作为编码器

将 hb.Prompt 视为具名编码器——可注册、可版本化、可重新加载的可调用对象。格式字符串提示是一种编码策略；Python 函数是另一种。二者均编译为 Capsule 支持的可调用对象，并共享同一条运行时路径。

import heavenbase as hb

# Function encoder — arbitrary logic in the body
@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"

# Format-string encoder — same Capsule-backed callable underneath
welcome = hb.Prompt("Hello, {name}!", name="demo.welcome")

Prompt 是 Capsule 的特例。提示定义——源代码或编译后的格式字符串——被捕获为 manifest，并可存为 sys-prompt 工作区行。调用时，提示 + 载荷 产出 LLM 所见的序列化文本：

payload = {"name": "Ada", "place": "Tokyo"}
text = welcome(**payload)  # "Hello, Ada!" — the model's input, not the stored encoder

这种拆分带来最大灵活性。编码器可组装 Markdown 段落、拉取工作区上下文、应用翻译、按输入形状分支或链接其他提示——随任务所需而定——而存储的定义仍是可版本化、可加载的对象。底层是 Capsule，因此提示与工作区中其他实体一样可持久化、可恢复、可审计。

构造不会写入工作区。显式调用 prompt.register(...)，或在有意于装饰时注册时传入 register=True。提示属于任务工作区时，在 register 与 load 时传入 ws=...。

3. Markdown 辅助函数

在使用 hb.Prompt 之前，你常需要稳定的 Markdown 块：标题、列表、代码围栏、结构化示例。HeavenBase 将这些放在 heavenbase.utils 中，使生成的提示文本在运行、报告与测试中保持确定性。

from heavenbase.utils import (
    bullet_dict,
    bullet_list,
    code_block,
    example_block,
    file_block,
    json_block,
    md_block,
    md_section,
    numbered_list,
    omission_list,
)

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")},
    ],
)

Helper	Use when
`md_section(...)`	带可选正文的嵌套标题
`md_block(...)` / `code_block(...)`	带可选语言标记的围栏块
`bullet_list(...)` / `numbered_list(...)`	无序或有序列表
`bullet_dict(...)`	以列表形式呈现键值对
`json_block(...)` / `file_block(...)`	结构化或带文件归属的载荷
`example_block(...)`	含 inputs、output、hints、notes 的单条少样本示例
`omission_list(...)`	保留首尾、省略中间的长列表

在函数提示内部使用这些辅助函数以完全控制版式。它们是可组合的构建块，不绑定于某一种任务形状。

4. 单次提示布局

对于常见情形——带 system 上下文、若干示例与待求解新实例的单轮任务——HeavenBase 提供 fast_prompt_section(...)。它是便捷封装，用上述 Markdown 辅助函数将常规段落布局转为 OpenAI 风格消息。布局遵循一个原则： system + descriptions + examples + instructions + instance 每条示例包含 inputs、hints、output、expected 与 notes。新实例复用相同形状，但将 output 标为 TODO，提示模型应产出什么。

import heavenbase as hb

messages = hb.fast_prompt_section(
    system="You are a concise worker.",
    descriptions={"Task": ["Read the files.", "Write the result."]},
    examples=[{"inputs": {"numbers": [1, 2]}, "output": 3, "hints": "Sum the list."}],
    instructions=["Use tools for filesystem access.", "Return one line."],
    instance={"inputs": {"numbers": [5, 8]}},
)

user_message = messages[-1]["content"]

该布局适用于单次任务：分类、抽取、结构化生成，以及展示若干已解示例后交给模型新输入的类似模式。它不太适合多轮对话，或在多轮中动态组装上下文的开放式智能体——这些流程更适合自定义函数提示。目标 LLM 路径需要独立 system 消息而非单个包含全部段落的 user 消息时，传入 separate_system=True。

5. 函数提示

编码器逻辑应留在代码中并持久化为 Capsule 支持的可调用对象时，装饰 Python 函数。函数体即编码器；调用参数即载荷。

import heavenbase as hb


@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"


greet.register()
greet.tr.set("Hello", "zz", "HEY")

assert greet("Ada", lang="zz") == "HEY, Ada!"
assert hb.Prompt.load("demo.greet", lang="zz")("Bob") == "HEY, Bob!"

提示含面向用户的短语时，在签名中接受 *, tr=str。HeavenBase 在调用时注入绑定的翻译函数，使本地化文本经同一条编码器路径流出，无需分叉函数。

5.1. 组合编码器

函数提示可在同一编码器内调用其他提示、布局辅助函数与 LLM。玩具式元提示器 (meta-prompter) 模式：一行格式字符串提示起草 system 段落；fast_prompt_section(...) 从示例与新实例组装单次正文。

import heavenbase as hb

meta_system = hb.Prompt(
    "Write one concise system paragraph for this one-shot task: {task}",
    name="demo.meta_system",
)


@hb.Prompt(name="demo.adaptive_extraction")
def adaptive_extraction(task: str, examples: list, instance: dict, *, tr=str) -> str:
    system = meta_system(task=tr(task))
    messages = hb.fast_prompt_section(
        system=system,
        descriptions={"Task": [tr(f"Extract fields from: {task}")]},
        examples=examples,
        instructions=[tr("Match the example format exactly.")],
        instance=instance,
        tr=tr,
    )
    return messages[-1]["content"]


def adaptive_extraction_with_llm_meta(task: str, examples: list, instance: dict, *, tr=str) -> str:
    meta_llm = hb.LLM(preset="chat")
    system = meta_llm.chat(
        tr(f"Task={task}; instance={instance}"),
        system=tr("Write one system paragraph for the one-shot task in the user message."),
    )
    messages = hb.fast_prompt_section(
        system=system,
        descriptions={"Task": [tr(task)]},
        examples=examples,
        instance=instance,
        tr=tr,
    )
    return messages[-1]["content"]

第一种变体将元生成保留在 HeavenBase 提示内。第二种将 system 起草委托给另一 LLM，而外层编码器仍拥有最终版式。二者均返回下游任务 LLM 应看到的 user 消息内容。

6. 格式字符串提示

向 hb.Prompt(...) 传入字符串会创建最简单的编码器：带占位符替换的编译格式字符串。它与函数提示使用相同的 Capsule 支持可调用路径，但函数体不能执行任意逻辑。短而稳定的模式用格式字符串；编码器需要分支、组合或元生成时用函数提示。

import heavenbase as hb

welcome = hb.Prompt(
    "Hello, {name}! Welcome to {place}",
    name="demo.welcome",
    tr_keys=["place"],
)
welcome.register()
welcome.tr.set("Hello, {name}! Welcome to {place}", "zz", "HEY, {name}! GO {place}")
welcome.tr.set("Tokyo", "zz", "TOKIO")

assert welcome(name="Ada", place="Tokyo", lang="zz") == "HEY, Ada! GO TOKIO"

仅整段字符串需要翻译时，使用不含 tr_keys 的短格式字符串：

import heavenbase as hb

welcome = hb.Prompt("Hello, {name}", name="demo.welcome")
text = welcome(name="Ada")

7. 加载、列出与版本化提示

提示按点分名称、紧凑版本引用或行 id 加载：

import heavenbase as hb

hb.Prompt.load("demo.greet")
hb.Prompt.load("demo.greet:2")
hb.Prompt.list(prefix="demo.")
hb.Prompt.versions("demo.greet")
hb.Prompt.delete("demo.greet:2")

最新版本选择仅考虑活跃行。已 tombstone 的行在默认 load 与 list 中隐藏。需要将提示存为 sys-prompt 行时，在工作区中注册：

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)

提示行可恢复可执行 Capsule manifest。仅从可信工作区加载已持久化提示。

8. 翻译作为一等公民

本地化不应要求维护并行的提示文件。HeavenBase 通过 tr 参数与 prompt.tr 将翻译作为提示表面的一等部分。每次提示调用按此顺序解析语言：显式 lang=...、提示对象绑定的 lang、当前 CM_HVNB 配置作用域中的 heavenbase.prompt.lang，然后 main_lang。绑定的 tr 函数将语言应用于编码器内的源短语：

import heavenbase as hb

@hb.Prompt(name="demo.greet")
def greet(name: str, *, tr=str) -> str:
    return f"{tr('Hello')}, {name}!"

将 tr=... 传给 fast_prompt_section(...) 以同样方式翻译段落标题与列表项。签名声明 tr 时，函数提示会自动接收 tr。翻译行以可查询的 sys-translation 实体存在于同一工作区。通过 prompt.tr 访问：

prompt.tr.bind("shared.agent-ui")
prompt.tr.set("Hello", "zz", "HEY", dict_name="shared.agent-ui")
prompt.tr.unbind("shared.agent-ui")

查找先匹配精确行，再匹配带 {placeholder} 捕获的源模式。找不到翻译时，HeavenBase 对 elicit="none" 返回源文本。elicit="llm" 为预留项，本版本会抛出 NotImplementedError。

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"

hb.CM_HVNB.set("heavenbase.prompt.lang", "zz", scope="heavenbase.demo-zz")

with hb.CM_HVNB.scoped("demo-zz"):
    assert prompt(name="Ada") == "HEY, Ada"

Translation 可从 heavenbase.extensions.prompt 供底层代码使用，但根 import heavenbase as hb 表面将翻译放在 Prompt.tr 下。

9. 持久化智能体指令

智能体指令应与任务工作区一起持久化时，将 fast_prompt_section(...) 与 hb.Prompt 结合使用。函数编码器封装单次布局；注册将可调用对象存为可版本化行。

import heavenbase as hb

ws = hb.HeavenBase("agent-prompts", preset="debug")


def agent_bootstrap(task_dir: str, workspace_id: str, *, tr=str) -> str:
    messages = hb.fast_prompt_section(
        system=tr("You are a task agent using HeavenBase as memory."),
        descriptions={"Context": [f"Workspace: {workspace_id}", f"Task directory: {task_dir}"]},
        instructions=[
            "Inspect files before running commands.",
            "Write structured results to the workspace.",
            "Return one plain final line.",
        ],
        tr=tr,
    )
    return messages[-1]["content"]


hb.Prompt(agent_bootstrap, name="agent.bootstrap", ws=ws).register(ws=ws)
system = hb.Prompt.load("agent.bootstrap", ws=ws)(task_dir="./task", workspace_id=ws.id)

10. CLI

hb prompt list --prefix demo. --json
hb prompt show demo.greet --json
hb prompt create demo.hello --template "Hello, {name}" --tr-key name
hb prompt render demo.hello --args '{"name":"Ada"}' --lang zz
hb prompt tr-set demo.hello "Hello, {name}" zz "HEY, {name}"
hb prompt tr-list demo.hello --lang zz --json
hb prompt remove demo.hello

函数提示创建仅支持 Python。CLI 的 create 命令创建格式字符串提示。

Summary

将提示建模为编码器——将输入数据映射为 LLM 所见文本的可调用函数，而非静态字符串。
hb.Prompt 是 Capsule 特例：提示 + 载荷产出最终序列化输出，编码器本身可持久化。
编码器需要逻辑、组合或元生成时优先用函数提示；简单替换用格式字符串提示。
用 Markdown 辅助函数构建稳定文本块；适用时用 fast_prompt_section(...) 的标准单次布局。
经编码器与 fast_prompt_section(...) 传递 tr，使本地化与渲染处于同一代码路径。

进一步探索

相关资源：

智能体 - 提示如何融入智能体记忆与 MCP 工具。
Capsule - 函数提示如何捕获与恢复。
LLM 概览 - 提示如何流入 hb.LLM。
配置 - CM_HVNB 中 heavenbase.prompt.lang 下的提示语言默认值

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

1. 为何需要提示工具

2. 提示作为编码器

3. Markdown 辅助函数

4. 单次提示布局

5. 函数提示

5.1. 组合编码器

6. 格式字符串提示

7. 加载、列出与版本化提示

8. 翻译作为一等公民

9. 持久化智能体指令

10. CLI

Summary

进一步探索

​1. 为何需要提示工具

​2. 提示作为编码器

​3. Markdown 辅助函数

​4. 单次提示布局

​5. 函数提示

​5.1. 组合编码器

​6. 格式字符串提示

​7. 加载、列出与版本化提示

​8. 翻译作为一等公民

​9. 持久化智能体指令

​10. CLI

​Summary

​进一步探索

1. 为何需要提示工具

2. 提示作为编码器

3. Markdown 辅助函数

4. 单次提示布局

5. 函数提示

5.1. 组合编码器

6. 格式字符串提示

7. 加载、列出与版本化提示

8. 翻译作为一等公民

9. 持久化智能体指令

10. CLI

Summary

进一步探索