跳转到主要内容

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 模块共享的小导入：类型名、dataclass、字典路径、hash、日志、网络代理上下文、脱敏和颜色格式化。

​
1. 类型和 dataclass

HeavenBase 从 heavenbase.utils 暴露常用类型和 dataclass 名称，方便内部模块迁移到本地工具面。 
from heavenbase.utils import Any, Dict, List, Optional, dataclass, field

@dataclass
class Stage:
    name: str
    notes: List[str] = field(default_factory=list)
这只是便利层。公共 API 仍然应该写清楚读者能直接理解的类型注解。

​
2. 字典路径

处理嵌套 config 或 agent state 时，可以用 dget, dset, dunset, dsetdef, dmerge, dflat, dunflat。 
from heavenbase.utils import dget, dset

state = {}
dset(state, "metadata.step", 2)
assert dget(state, "metadata.step") == 2

​
3. Hash 和 debug 输出

md5hash 和 sha256hash 用于确定性本地标识和完整性检查。md5hash(...) 返回补零后的十进制字符串，适合直接作为字符串 ID；需要取模或排序时用 md5int(...) 或 sha256int(...)。 
from heavenbase.utils import capture_error, error_str, md5hash, md5int, raise_mismatch, safe_error, sha256int

row_key = md5hash(["bench-item", "p0001"])
bucket = md5int(row_key) % 16
wide_bucket = sha256int(row_key) % 1024

try:
    raise_mismatch(["json", "yaml"], "jsno", name="format")
except ValueError as exc:
    message = error_str(exc, tb=False)
    record = capture_error(exc)

message = safe_error(RuntimeError("Connection failed: password=secret-token"))
safe_error(exc) 会包含异常类型，并脱敏常见 token、password 和带凭据的 URL。provider 边界处优先使用它。

​
4. 标识符、命名和操作 token

用户提供的名字跨过后端边界前，先用标识符 helper 校验。它们能把 workspace/entity ID 转成后端安全的表名和索引名。 
from heavenbase.utils import check_entity_id, entity_table_name, workspace_index_name

entity_id = check_entity_id("person-001")
table = entity_table_name(entity_id)
index = workspace_index_name("workspace-main")
生成名称或文档片段时使用 class_name, field_name, kebab, snake, clean_doc。handler 代码需要理解查询操作族时，使用 normalize_op, registered_ops, ops_for 和 OP_* 常量。

​
5. 日志

使用 get_logger 获取 HeavenBase logger。configure_logs(...) 会改变这些 logger 的全局输出行为。 
from heavenbase.utils import configure_logs, get_logger, restore_logs, suppress_logs

logger = get_logger("heavenbase.demo")
logger.success("ready")

configure_logs(file="logs/heavenbase.log", level="INFO")
logger.warning("written to the configured log file")

suppress_logs()
logger.warning("suppressed")
restore_logs()
redirect_logs(path, loggers=[...]) 可以把指定 logger 写到文件；结束后调用 restore_logs(...) 恢复。

​
6. 网络代理上下文

需要临时设置 HTTP_PROXY、HTTPS_PROXY 或 NO_PROXY 时使用 NetworkProxy。context 退出后会恢复原环境变量；传空字符串会在 context 内禁用对应代理变量。 
from heavenbase.utils import NetworkProxy

with NetworkProxy(http_proxy="http://localhost:7890", no_proxy="localhost,127.0.0.1"):
    ...

​
7. 终端颜色

颜色 helper 使用 ANSI，并尊重 NO_COLOR。 
from heavenbase.utils import color_success, strip_color

text = color_success("ready")
plain = strip_color(text)
颜色只用于终端诊断，不要存进 JSON、数据库行或 benchmark artifact。

​
Further Exploration

相关资源：
  • 配置 - 字典路径 helper 的主要使用场景。
  • 函数工具 - 命令执行、并行 helper 和 StableRNG。