跳转到主要内容
File System 工具让本地产物可预期：规范化路径、解析别名、使用配置的编码，再通过统一的小契约读写。
当 demo、测试、脚本或扩展需要可预测的本地文件，又不想手写路径处理与序列化细节时，请阅读本页。

​
1. 核心思想

pj(...) 是规范的路径拼接 helper。它拼接路径部分、展开 ~ 与环境变量、规范化分隔符，可选返回绝对路径，并可解析调用方提供的别名。 可把它看作一小套路径词汇：. 表示当前工作位置，~ 展开为用户主目录，环境变量经操作系统展开，而 % 或 & 等别名在调用方或 config manager 提供 alias map 时可指向运行时或资源目录。 文件与序列化 helper 包装常见 I/O，原因与配置包装超参数相同：调用方不应在每个函数里透传编码、缩进与平台路径细节。heavenbase.serialize.encoding 与 heavenbase.serialize.indent 等默认值位于 CM_HVNB。
utility 的 pj(...) 处理普通路径与调用方别名。CM_HVNB.pj(...) 处理 HeavenBase 包别名：%/ 表示包内运行时数据，&/ 表示包资源。

​
2. 构建路径

普通本地路径使用 pj(...)： 
from heavenbase.utils import pj

project_root = pj(".", abs=True)
cache_file = pj("~/heavenbase-cache", "index.json", abs=True)
第一段路径是项目专用快捷方式时传入 aliases： 
from heavenbase.utils import pj

run_path = pj("%/runs/latest.json", aliases={"%": "demos/.temp"}, abs=True)
asset_path = pj("&/sample.txt", aliases={"&": "demos/assets"}, abs=True)
包别名通过 config manager 使用： 
from heavenbase.utils import CM_HVNB

config_db = CM_HVNB.pj("%/config.db", abs=True)
default_yaml = CM_HVNB.pj("&/configs/default.yaml", abs=True)

​
3. 准备文件与目录

写入产物前使用 touch_dir(...) 与 touch_file(...)。两者会创建缺失的父目录并返回绝对路径。 
from heavenbase.utils import exists_file, touch_dir, touch_file

root = touch_dir("demos/.temp/report")
summary = touch_file(f"{root}/summary.md", content="# Summary")

assert exists_file(summary)
仅当目录或文件应以空状态开始时使用 clear=True： 
from heavenbase.utils import touch_dir

run_dir = touch_dir("demos/.temp/run", clear=True)

​
4. 读写数据

机器可读产物用 JSON 与 YAML，人类可读输出用 text，工作流逐条追加事件时用 JSONL。 
from heavenbase.utils import append_jsonl, dump_json, load_json, pj, save_txt, touch_dir

root = touch_dir(pj("demos", ".temp", "docs-run"))
meta_path = pj(root, "meta.json")

dump_json({"workspace": "docs-demo", "rows": 3}, meta_path, sort_keys=True)
save_txt("# Run Notes", pj(root, "notes.md"))
append_jsonl({"event": "created", "path": meta_path}, pj(root, "events.jsonl"))

meta = load_json(meta_path)
文本编码默认为 heavenbase.serialize.encoding，在默认配置中为 utf-8。JSON 与 YAML 缩进默认为 heavenbase.serialize.indent，为 4。
load_pkl(...) 读取 Python pickle 数据。仅对你自己环境产生的可信本地产物使用 pickle。

​
5. 列出、复制与删除产物

list_files(...) 读取直接子项。enum_files(...) 递归遍历。两者都返回稳定、不区分大小写的顺序。 
from heavenbase.utils import copy_path, delete_path, enum_files, list_files

for name in list_files("demos/.temp/docs-run", ext="json"):
    print(name)

for path in enum_files("demos/.temp/docs-run", ext=["json", "jsonl"], abs=True):
    print(path)

copy_path("demos/.temp/docs-run", "demos/.temp/docs-run-copy", mode="merge")
delete_path("demos/.temp/docs-run-copy")
复制 helper 使用显式冲突模式。文件支持 replace、skip 与 strict；目录还支持 merge。

​
6. 展示目录结构图

在日志、报告与文档片段中用 folder_diagram(...) 做紧凑诊断。 
from heavenbase.utils import folder_diagram

print(folder_diagram("demos/.temp/docs-run", annotations={"meta.json": "run metadata"}, limit=12))
delete_dir(...) 与 delete_path(...) 会删除本地数据。请将 demo 清理目标限制在 demos/.temp/ 等已知临时目录下。

​
Further Exploration

相关资源：
  • 配置 - 序列化 helper 使用的配置驱动默认值。
  • 哈希 - 确定性、文件安全的标识符与指纹。
  • 开发 - 围绕本地产物的命令执行。