> ## Documentation Index
> Fetch the complete documentation index at: https://ahvn.top/llms.txt
> Use this file to discover all available pages before exploring further.

# 提示 (Prompt)

> 可调用提示编码器、Markdown 辅助函数、单次布局、工作区存储、翻译与 CLI。

<Note>
  *语言不是文字，而是信息到表达的映射。*
</Note>

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

<br />

## 1. 为何需要提示工具

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
# 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 将提示建模为返回渲染文本或消息的函数：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 文本。字符串模板覆盖简单的填空场景；函数提示覆盖其余一切。

<br />

## 2. 提示作为编码器

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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](/zh/features/capsules) 的特例。提示定义——源代码或编译后的格式字符串——被捕获为 manifest，并可存为 `sys-prompt` 工作区行。调用时，**提示 + 载荷** 产出 LLM 所见的序列化文本：

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

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

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

<br />

## 3. Markdown 辅助函数

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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(...)`                      | 保留首尾、省略中间的长列表                        |

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

<br />

## 4. 单次提示布局

对于常见情形——带 system 上下文、若干示例与待求解新实例的单轮任务——HeavenBase 提供 `fast_prompt_section(...)`。它是便捷封装，用上述 Markdown 辅助函数将常规段落布局转为 OpenAI 风格消息。

布局遵循一个原则：

**system + descriptions + examples + instructions + instance**

每条示例包含 **inputs**、**hints**、**output**、**expected** 与 **notes**。新实例复用相同形状，但将 output 标为 `TODO`，提示模型应产出什么。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`。

<br />

## 5. 函数提示

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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(...)` 从示例与新实例组装单次正文。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 消息内容。

<br />

## 6. 格式字符串提示

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 的短格式字符串：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import heavenbase as hb

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

<br />

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

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 行时，在工作区中注册：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

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

<br />

## 8. 翻译作为一等公民

本地化不应要求维护并行的提示文件。HeavenBase 通过 `tr` 参数与 `prompt.tr` 将翻译作为提示表面的一等部分。

每次提示调用按此顺序解析语言：显式 `lang=...`、提示对象绑定的 `lang`、当前 `CM_HVNB` 配置作用域中的 `heavenbase.prompt.lang`，然后 `main_lang`。绑定的 `tr` 函数将语言应用于编码器内的源短语：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 访问：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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`。

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 下。

<br />

## 9. 持久化智能体指令

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

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

<br />

## 10. CLI

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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` 命令创建格式字符串提示。

<br />

## Summary

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

<br />

## 进一步探索

<Tip>
  **相关资源：**

  * [智能体](/zh/features/agents) - 提示如何融入智能体记忆与 MCP 工具。
  * [Capsule](/zh/features/capsules) - 函数提示如何捕获与恢复。
  * [LLM 概览](/zh/features/llm/overview) - 提示如何流入 `hb.LLM`。
  * [配置](/zh/features/configuration) - `CM_HVNB` 中 `heavenbase.prompt.lang` 下的提示语言默认值
</Tip>

<br />