跳转到主要内容
Hash 工具是一种兼容折中：让 HeavenBase 使用普通字符串 ID，同时在索引受益于类整型行为时保持哈希可排序。
当两个进程应从同一逻辑值派生相同 ID、分桶或指纹时，请使用这些 helper。

​
1. 核心思想

HeavenBase 常需要像字符串一样流转的标识符，因为它们会经过 JSON、数据库行、object_id 与文件名。有时又希望值可被解释为整数，以便排序、分桶或索引友好存储。 md5hash(...) 当前返回零填充的十进制字符串。这意味着它可作为普通字符串 ID 存在，但等长值也会按其整数表示排序。
这尚未定为通用设计。可当作整数的字符串哈希是当前预发布阶段的实用兼容手段，并非声称每个外部 API 都应依赖这一精确表示。

​
2. 创建稳定 ID

md5hash(...) 用稳定 JSON 顺序序列化常见 Python 值，并返回零填充十进制字符串。默认长度为 42，与 HeavenBase 对标识符友好的哈希宽度一致。 
from heavenbase.utils import md5hash

row_id = md5hash({"source": "docs", "name": "Ada"})
same_id = md5hash({"name": "Ada", "source": "docs"})

assert row_id == same_id
ID 应携带逻辑命名空间时使用 hash_id(...)： 
from heavenbase.utils import hash_id

prompt_id = hash_id("prompt", "demo.greet", "1")

​
3. 分桶或排序

需要取模、确定性采样或排序时使用整数摘要。 
from heavenbase.utils import md5int, sha256int

bucket = md5int("workspace-alpha") % 16
wide_bucket = sha256int({"workspace": "alpha", "entity": "person"}) % 1024
md5int(...) 更短，足以满足本地 utility ID。sha256int(...) 在需要更宽摘要表达意图时更合适。

​
4. 为较大载荷生成指纹

在 manifest、配置快照与完整性检查中使用 sha256hash(...) 生成十六进制指纹。 
from heavenbase.utils import fmt_short_hash, sha256hash

fingerprint = sha256hash({"model": "ds-flash", "temperature": 0})
display = fmt_short_hash(fingerprint, length=10)
这些是确定性 utility 哈希，不是认证或密码存储原语。

​
Further Exploration

相关资源：
  • 随机 - 确定性 seed 演进与基于哈希的采样。
  • 文件系统 - 哈希结构化数据前使用的序列化 helper。
  • 目录 - object_id 与可发现名称。