跳转到主要内容
「给我六小时砍倒一棵树，我会用前四小时磨斧子。」——亚伯拉罕·林肯
当你需要配置 HeavenBase，或在编写功能代码前选择合适的 helper 时，请阅读本节。页面顺序按多数读者最常见的工作流排列。

​
1. 选择工具

配置

将活动默认值移出 wrapper 签名，再按应用作用域覆盖。

文件系统

规范化路径、解析别名，并按配置驱动的编码默认值读写文件。

哈希

在字符串 ID、确定性哈希与类整型可排序标识符之间桥接。

随机

生成在固定 seed 下可复现、在采样变化下仍稳定的数据。

Prompt

将结构化上下文转为 prompt 文本、消息、模板与已存储的 prompt 行。

杂项

浏览支持 helper 与开发期工具：命令、并行工作、诊断与迁移桥接。

​
2. 核心思想

heavenbase.utils 并非要长成庞大的公开框架。它是 HeavenBase 中反复出现的本地工具箱：配置、路径、序列化、确定性 ID、确定性数据生成、prompt 文本、命令执行、诊断，以及少量迁移桥接。 经验法则很简单：
  • 面向应用的 helper 使用专题工具页。
  • workspace、backend、query、LLM、prompt、capsule、toolkit 等功能面使用功能文档。
  • 即使某些系统专用支持模块暂时可从 heavenbase.utils 导入，也应视为实现细节。
部分当前 utility 导出存在，是因为 HeavenBase 仍在完成从 legacy AgentHeaven utility 模块的迁移。operation token、registry 身份 helper 以及部分命名 helper 等内部模块，预计会逐步移出通用 utility 表面。

​
3. 导入方式

多数 demo 可从顶层 utility 表面导入： 
from heavenbase.utils import StableRNG, dump_json, pj, touch_dir

root = touch_dir(pj("demos", ".temp", "trial"))
dump_json({"seed": StableRNG(seed=42).rnd_int()}, pj(root, "meta.json"))
编写实现代码且希望依赖边界更清晰时，从专题模块导入： 
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json

​
进一步探索

相关资源：
  • 配置 - 作用域活动默认值与覆盖。
  • 文件系统 - 路径、文件与序列化。
  • 杂项 - 支持 helper 与开发期工具。