配置 - HeavenBase

原始配置是作用域数据。可执行配置是经过验证的不可变值。

HeavenBase 将配置存储与配置含义分开。CM_HVNB 管理保留的作用域层，ConfigEngine 则通过一条固定管线解析领域配置。

1. 为何需要配置

没有配置所有者时，每个包装函数都要携带并不属于自己的选项：

def enrich_user(
    user_id: str,
    model: str = "deepseek-chat",
    temperature: float = 0.0,
    timeout: int = 120,
    embedding_batch_size: int = 256,
):
    ...

HeavenBase 将这些默认值保存在作用域数据中，并由所属领域负责解析：

import heavenbase as hb

with hb.CM_HVNB.scoped("workspace.docs-demo"):
    llm = hb.LLM(preset="deepseek-v4-flash")

你的应用只需携带作用域或显式覆盖，而不是每个提供商与后端细节。这样既能保持函数签名聚焦，也让每个作用域拥有保留历史。

2. 理解所有权划分

Context -> Backend -> Registry -> ConfigManager -> ConfigSnapshot
                                      |
                                      v
Preset -> Normalize -> Validate -> Apply(profile) -> value
                ConfigEngine + ConfigSpec

Context 拥有机器后端及其命名 Registry 命名空间。
ConfigManager 拥有默认值、作用域、版本化配置层、插值和快照。
ConfigEngine 拥有确定性的领域解析与 Apply 配置档案。
领域引擎拥有 LLM、数据库、工作区和文件系统策略。

配置作用域记录与其他持久定义使用同一套持久 Registry 协议。配置没有独立数据库模式，也没有第二条持久化路径。

3. 读取和编辑作用域数据

使用 get(...) 读取一个当前值：

import heavenbase as hb

top_k = hb.CM_HVNB.get("heavenbase.query.near.default_top_k", default=50)

将 scoped(...) 用作上下文管理器或装饰器：

scope = "heavenbase.workspace.docs-demo"
hb.CM_HVNB.set("heavenbase.query.near.default_top_k", 25, scope=scope)

with hb.CM_HVNB.scoped("workspace.docs-demo"):
    assert hb.CM_HVNB.scope == scope
    assert hb.CM_HVNB.get("heavenbase.query.near.default_top_k") == 25

较窄的作用域会继承较宽的配置层。对于 heavenbase.workspace.docs-demo，解析顺序是 heavenbase、heavenbase.workspace，最后是完整目标作用域。重复不可变读取使用 snapshot()，读取单个原始作用域层使用 layer(...)，查看保留版本使用 history(...)：

snap = hb.CM_HVNB.snapshot()
raw_layer = hb.CM_HVNB.layer(scope=scope)
versions = hb.CM_HVNB.history(scope=scope, limit=5)

unset(...) 会写入 tombstone，使子作用域可以隐藏继承的键。setdef(...) 仅在解析值缺失时写入。列表路径支持 items[0]、items[] 和 items[2+]。

remove(...)、compact(..., reset=True) 和 setup(reset=True) 会修改保留的配置。仅对你确实要清理的作用域使用它们。

4. 解析领域配置

每个 ConfigEngine 都遵循相同阶段：

预设 (Preset) 展开完整的命名模板。
标准化 (Normalize) 解析别名、简写、优先级和规范值。
验证 (Validate) 检查规范值而不修复它。
应用 (Apply(profile)) 返回确定性的分离值。

Resolve 的结果是一个 ConfigSpec：

import heavenbase as hb

engine = hb.LLMEngine()
spec = engine.resolve({"preset": "deepseek-v4-flash"})

assert isinstance(spec, hb.ConfigSpec)
assert spec.domain == "llm"

ConfigSpec.data 包含面向用户的规范字段。bindings 包含已选择的可执行契约。raw 和 meta 保留诊断信息。to_dict() 与 from_dict() 会保留可执行信封。

序列化后的规范可能在 bindings 中包含凭证。日志和 CLI 输出请使用领域提供的脱敏 print 配置档案。

5. 使用 Apply 配置档案

Apply 配置档案会把一个已验证规范转换成特定值：

db_spec = hb.DB_ENGINE.resolve(
    {"provider": "sqlite", "database": "file://%/docs-demo.db"}
)

url = hb.DB_ENGINE.apply(db_spec, profile="url")
uri = hb.DB_ENGINE.apply(db_spec, profile="uri")
safe = hb.DB_ENGINE.apply(db_spec, profile="print")

数据库配置档案返回 SQLAlchemy URL、序列化 URI、引擎参数、缓存键、pragmas、生命周期配置或脱敏显示值。LLM 入口 (Gateway) 配置档案返回分离的客户端参数。活动引擎与 SDK 客户端留在下游缓存中。 validate(restored_spec) 与 apply(restored_spec, ...) 不会重新读取原始管理器或目录。这让可执行规范可以跨共享相同代码契约的进程边界传递。

6. 使用严格的本地文件 URI

显式本地存储只使用一种语法：

形式	含义
`file:///absolute/path`	规范的本地绝对路径。
`file://%/relative/path`	HeavenBase 包主目录下的路径。
`file://&/relative/path`	只读的包资源路径。

可写位置拒绝资源别名。网络 authority、反斜杠、根目录逃逸、查询字符串、片段和旧式 file: 拼写都会被拒绝。数据库字段也可以使用不含分隔符的逻辑名称。DBEngine 会在 heavenbase.db.local_root 下解析它，并在 DBSpec 中保存规范的 file:/// URI。

from heavenbase.utils import file_uri_to_path, path_to_file_uri

uri = path_to_file_uri("/tmp/heavenbase/demo.db")
path = file_uri_to_path(uri)
assert path == "/tmp/heavenbase/demo.db"

scripts/migrate_config_locations.py 用于转换受控的旧配置文件。它默认执行 dry-run，并在写入前验证每个替换项都解析到相同的原生目标。

7. 理解缓存和插值

每个领域引擎都为已解析规范和 Apply 值提供有界缓存。缓存身份包含当前作用域 generation、被引用的环境值、根覆盖、已选择目录 revision 和领域契约 revision。环境插值默认开启；命令插值默认关闭：

from heavenbase.utils import resolve_interpolations

value = resolve_interpolations({"key": "${env:MY_KEY,missing}"})

使用 engine.clear_cache() 使本地领域缓存失效；当下一次源读取必须立即观察当前 Registry revision 时，使用 CM_HVNB.refresh()。

8. 安全扩展配置

新增领域时，请继承 ConfigEngine，声明一个稳定的 domain，并实现受保护的 Normalize、Bind、Validate 和默认配置档案 hook。通过注册返回值的 Apply 配置档案扩展，而不要在通用配置中添加分支。请为幂等性、序列化、无需源的恢复规范 Apply、缓存失效和脱敏添加测试。提供商选择、方言事实、文件策略、SDK 行为和活动资源应留在所属领域。

开发期间使用 engine.assert_idempotent(raw)。它会针对同一个冻结源检查两次不使用缓存的 Normalize/Bind，并报告第一个变化路径。

进一步探索

相关资源：

LLM 概览 - 预设 (Preset)、提供商、入口 (Gateway) 和模型路由。
数据库集成 - 已解析的 SQL 配置与数据库执行。
文件系统 - 严格文件 URI 与路径辅助函数。
CLI 参考 - 使用同一配置管理器的 hb config 命令。

介绍

快速开始

核心概念

开发者

工具箱

LLM

智能体运行时

社区

配置

1. 为何需要配置

2. 理解所有权划分

3. 读取和编辑作用域数据

4. 解析领域配置

5. 使用 Apply 配置档案

6. 使用严格的本地文件 URI

7. 理解缓存和插值

8. 安全扩展配置

进一步探索

​1. 为何需要配置

​2. 理解所有权划分

​3. 读取和编辑作用域数据

​4. 解析领域配置

​5. 使用 Apply 配置档案

​6. 使用严格的本地文件 URI

​7. 理解缓存和插值

​8. 安全扩展配置

​进一步探索

1. 为何需要配置

2. 理解所有权划分

3. 读取和编辑作用域数据

4. 解析领域配置

5. 使用 Apply 配置档案

6. 使用严格的本地文件 URI

7. 理解缓存和插值

8. 安全扩展配置

进一步探索