跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

hb.Prompt 把提示词变成可调用的 Python 对象，同时也是 HeavenBase 实体。函数提示词通过 Capsule manifest 捕获，存为 sys-prompt 行；翻译存为同一 workspace 下可查询的 sys-translation 行，普通代码优先通过 prompt.tr 访问。
Prompt 行可以恢复可执行的 Capsule manifest。只从可信 workspace 加载 prompt。

​
函数提示词

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!"
构造 Prompt 不会自动写入 workspace。需要持久化时显式调用 prompt.register(...)；只有明确传入 register=True 时才会在装饰器绑定阶段注册。Agent 工作流里建议在 register/load 时传入 ws=...，让 prompt 版本和翻译都限定在任务 workspace 内。

​
模板提示词

向 hb.Prompt(...) 传入字符串会创建 format-string 提示词，并编译成和函数提示词一样的 Capsule-backed callable。可以翻译整个模板，也可以通过 tr_keys 指定哪些占位符值需要先翻译再格式化。 
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"

​
加载与版本

Prompt 可以用 dotted name、紧凑版本引用或 row id 加载： 
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")
默认加载只选择 active 行； tombstone 后的行不会出现在默认 load/list 结果里。

​
翻译查找

每个 prompt 默认绑定同名翻译字典，也可以绑定共享字典作为 fallback。 
prompt.tr.bind("shared.agent-ui")
prompt.tr.set("Hello", "zz", "HEY", dict_name="shared.agent-ui")
prompt.tr.unbind("shared.agent-ui")
prompt.tr 是绑定到当前 prompt 的翻译 helper；持久化后的翻译仍然是普通 sys-translation 行，可以像其他 HeavenBase 实体一样查询。 Translation 从 heavenbase.prompt 导出，供底层代码使用；根导入 import heavenbase as hb 的用户界面把翻译收敛在 Prompt.tr 下。 查找顺序是 exact match 优先，然后匹配带 {placeholder} 的 source pattern。如果没有命中翻译且 elicit="none"，返回原文；elicit="llm" 在当前版本保留接口并抛出 NotImplementedError。 Prompt 调用解析语言的顺序是：显式 lang=...、prompt 对象绑定的 lang、当前 CM_HVNB scope 下的 heavenbase.prompt.lang，最后是 main_lang。 
hb.CM_HVNB.set("heavenbase.prompt.lang", "zz", scope="heavenbase.demo-zz")

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

​
Agent prompt assembly

使用 hb.fast_prompt_section(...) 组装多段 agent prompt，不需要导入 AgentHeaven： 
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)
如果目标 LLM 路径需要独立 system message，可以传入 separate_system=True。

​
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 命令只创建模板提示词。