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

# 概述

> HeavenBase 工具箱导览地图。

<Note>
  *「给我六小时砍倒一棵树，我会用前四小时磨斧子。」——亚伯拉罕·林肯*
</Note>

当你需要配置 HeavenBase，或在编写功能代码前选择合适的 helper 时，请阅读本节。页面顺序按多数读者最常见的工作流排列。

<br />

## 1. 选择工具

<CardGroup cols={2}>
  <Card title="配置" icon="gear" href="/zh/features/configuration">
    将活动默认值移出 wrapper 签名，再按应用作用域覆盖。
  </Card>

  <Card title="文件系统" icon="folder-open" href="/zh/features/utilities/file-system">
    规范化路径、解析别名，并按配置驱动的编码默认值读写文件。
  </Card>

  <Card title="哈希" icon="fingerprint" href="/zh/features/utilities/hash">
    在字符串 ID、确定性哈希与类整型可排序标识符之间桥接。
  </Card>

  <Card title="随机" icon="dice" href="/zh/features/utilities/random">
    生成在固定 seed 下可复现、在采样变化下仍稳定的数据。
  </Card>

  <Card title="Prompt" icon="message" href="/zh/features/utilities/prompt">
    将结构化上下文转为 prompt 文本、消息、模板与已存储的 prompt 行。
  </Card>

  <Card title="杂项" icon="toolbox" href="/zh/features/utilities/miscs">
    浏览支持 helper 与开发期工具：命令、并行工作、诊断与迁移桥接。
  </Card>
</CardGroup>

<br />

## 2. 核心思想

`heavenbase.utils` 并非要长成庞大的公开框架。它是 HeavenBase 中反复出现的本地工具箱：配置、路径、序列化、确定性 ID、确定性数据生成、prompt 文本、命令执行、诊断，以及少量迁移桥接。

经验法则很简单：

* 面向应用的 helper 使用专题工具页。
* workspace、backend、query、LLM、prompt、capsule、toolkit 等功能面使用功能文档。
* 即使某些系统专用支持模块暂时可从 `heavenbase.utils` 导入，也应视为实现细节。

<Info>
  部分当前 utility 导出存在，是因为 HeavenBase 仍在完成从 legacy AgentHeaven utility 模块的迁移。operation token、registry 身份 helper 以及部分命名 helper 等内部模块，预计会逐步移出通用 utility 表面。
</Info>

<br />

## 3. 导入方式

多数 demo 可从顶层 utility 表面导入：

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

编写实现代码且希望依赖边界更清晰时，从专题模块导入：

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from heavenbase.utils.files import pj, touch_dir
from heavenbase.utils.serialize import load_json
```

<br />

## 进一步探索

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

  * [配置](/zh/features/configuration) - 作用域活动默认值与覆盖。
  * [文件系统](/zh/features/utilities/file-system) - 路径、文件与序列化。
  * [杂项](/zh/features/utilities/miscs) - 支持 helper 与开发期工具。
</Tip>

<br />