好记性不如烂笔头。
pj(...) 用于可移植路径，以及 序列化家族 (serialization family) —— 在 JSON、YAML、文本、JSONL、jstr、二进制等相关格式上实现一致的读写。
1. 为何需要统一的文件系统工具
若没有统一的文件系统工具，每个脚本与 demo 都会重新实现路径拼接、别名解析、编码处理与序列化，结果不一致：一个模块用os.path.join(...) 搭配硬编码相对路径，另一个用 pathlib.Path 与 expanduser()，第三个硬编码在 Windows 上会失效的 / 分隔符。序列化同样会各自为政 —— 一个调用方用 indent=2 写 JSON，另一个用 default=str，第三个硬编码 utf-8 编码。
pj(...) 是统一的路径词汇：展开 ~、解析环境变量、规范化分隔符、可选返回绝对路径，并解析调用方提供的别名。序列化家族 使用配置驱动的默认值（CM_HVNB 中的 heavenbase.serialize.encoding 与 heavenbase.serialize.indent），让各调用方无需重复这些参数即可获得一致输出。
pj(...) 构建路径，再通过匹配的序列化 helper 读写，无需重复指定编码、缩进或平台细节。
2. 两个核心思想
文件系统工具清晰分为路径词汇与序列化 I/O。本页其余内容 —— 创建文件夹、列出文件、复制产物、文件夹结构图 —— 均服务于这两条主线。2.1. pj(...) — 可移植路径
pj(...) 是规范的路径拼接 helper。它拼接路径片段、展开 ~ 与环境变量、规范化分隔符、可选返回绝对路径，并可解析调用方提供的别名。
可将其视为一套小型路径词汇。. 表示当前工作位置，~ 展开为用户主目录，环境变量通过操作系统展开，而 % 或 & 等别名可在调用方或配置管理器提供别名映射时指向包数据文件夹或资源文件夹。
工具
pj(...) 处理普通路径与调用方别名。CM_HVNB.pj(...) 处理 HeavenBase 包别名：%/ 表示包本地数据，&/ 表示包资源。2.2. 序列化家族 — 配置驱动的 I/O
序列化 helper 封装常见读写，原因与配置封装超参数相同：调用方不应在每个函数中传递编码、缩进与平台路径细节。 每种格式暴露相同的命名模式：
文本编码默认为
heavenbase.serialize.encoding，在默认配置中为 utf-8。JSON 与 YAML 缩进默认为 heavenbase.serialize.indent，值为 4。缺失文件返回空默认值（""、{}、[] 或 b""），除非传入 strict=True。这里展示了配置驱动方法的好处：你可以更改默认编码或缩进，而无需更改每个调用方。
JSON helper 使用 HbJsonEncoder 与 HbJsonDecoder，保留 datetime、Decimal、元组、集合与 callable 引用等常见 HeavenBase 值 —— 产物可往返而无需临时 default=str 处理器。
3. 构建路径
对普通本地路径使用pj(...)：
4. 准备文件与文件夹
写入产物前使用touch_dir(...) 与 touch_file(...)。两者都会创建缺失的父目录并返回绝对路径。
clear=True：
5. 读写数据
序列化是本页的第二根支柱。选定格式、调用匹配的 helper，让CM_HVNB 提供编码与缩进默认值。结合 pj(...) 与 touch_dir(...) 即可完成完整的产物工作流。
5.1. JSON
JSON 适用于结构化、机器可读的产物 —— 配置、运行元数据、工作区 (Workspace) 快照，以及与其他工具的交换。sort_keys=True。需要单行输出时传入 compact=True 或 indent=None。
5.2. YAML
YAML 适用于人类可编辑的结构化文件，例如配置模板与小型清单。heavenbase.serialize.indent 与 JSON 共享相同的缩进默认值。
5.3. 文本
文本 helper 适用于日志、Markdown 笔记、纯文本报告，以及任何人可读的行式输出。load_txt 在文件缺失时返回 ""，除非 strict=True。append_txt 在每次写入后追加换行符。
5.4. JSONL
当工作流逐条追加事件或记录时使用 JSONL —— 运行日志、流式导出与增量审计轨迹。append_jsonl；完整可迭代对象在内存中时用 dump_jsonl。大文件用 iter_jsonl 流式读取，无需一次加载所有行。
5.5. jstr — 面向 Python 的文本
jstr 表示「顶层值为容器时用 JSON，否则用字符串」。在 Tool 结果、memstate 行与 MCP 载荷等文本边界处使用dumps_jstr、loads_jstr、dump_jstr、load_jstr 与 save_jstr，让结构化值保持机器可读，标量与其他值通过 str(...) 保持人类可读。
规则：
- 顶层
dict或list值（含嵌套容器）通过与dumps_json相同的编码器序列化为紧凑 JSON。 - 所有其他值，包括
int、float、bool、None、元组、集合与自定义对象，均使用str(obj)。 loads_jstr解析形如 JSON 对象或数组的文本；该形态下的无效 JSON 以及所有其他文本，均原样作为字符串返回。
serializer=None，在执行时解析为共享的 jstr_serializer Capsule，因此 toolkit.run_to_str(...) 与 FastMCP 服务会将成功的工具输出路由到 dumps_jstr。本地 Python 调用方仍可使用 toolkit.run(...) 获取原始对象。
5.6. 二进制
二进制 helper 适用于原始字节载荷 —— 模型权重、压缩 blob、图像字节及其他非文本产物。load_bin 在文件缺失时返回 b""，除非 strict=True。
5.7. Hex 与 Base64
当字节载荷需要在文件或日志中以文本安全形式表示时，使用 hex 与 Base64 helper。dump_hex 与 dump_b64 解码 hex 或 Base64 字符串并写入结果字节。load_hex 与 load_b64 读取二进制文件并返回 hex 或 Base64 文本表示。内存编码不触及文件系统时使用 dumps_b64 / loads_b64。
5.8. Pickle
请仅对由你自身环境产生的可信本地产物使用 pickle。加载 pickle 可能执行任意代码，绝不可跨越信任边界。6. 列出、复制与删除产物
list_files(...) 读取直接子项。enum_files(...) 递归遍历。两者均返回稳定、不区分大小写的顺序。
replace、skip 与 strict；目录还支持 merge。
7. 显示文件夹结构图
在日志、报告与文档片段中使用folder_diagram(...) 做紧凑诊断。