跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://ahvn.top/llms.txt

Use this file to discover all available pages before exploring further.

文件 helper 让本地路径行为保持一致。需要拼路径、建目录、列文件或清理临时 artifact 时使用它们。

​
1. 用 pj 构建路径

pj 会拼接路径片段，展开 ~ 和环境变量，并按当前平台规范化分隔符。 
from heavenbase.utils.files import pj

db_path = pj("demos", ".temp", "workspace.db", abs=True)
cache_path = pj("~/heavenbase-cache", "index.json", abs=True)
别名需要显式传入，读代码时可以直接看到别名指向哪里： 
path = pj("%/runs/latest.json", aliases={"%": "demos/.temp"}, abs=True)

​
2. 创建和检查文件

touch_dir 和 touch_file 会创建缺失的父目录，并返回解析后的路径字符串。 
from heavenbase.utils.files import exists_file, touch_dir, touch_file

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

assert exists_file(report)
需要空目录或空文件时使用 clear=True。

​
3. 列表和清理

list_files 只读直接子文件，enum_files 递归遍历。两者都返回稳定的大小写无关顺序。 
from heavenbase.utils.files import delete_path, enum_files, list_files

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

for path in enum_files("demos/.temp", ext="json", abs=True):
    delete_path(path)
delete_dir 和 delete_path 会删除本地数据。demo 和 benchmark artifact 应放在 demos/.temp/ 下，避免误删项目文件或用户数据。

​
4. 复制和查看路径

需要明确冲突行为时使用 copy_file、copy_dir 或 copy_path。文件复制支持 mode="replace", mode="skip", mode="strict"；目录复制额外支持 mode="merge"。 
from heavenbase.utils.files import copy_path

copy_path("demos/.temp/source", "demos/.temp/archive", mode="merge")
copy_path("demos/.temp/report.md", "demos/.temp/latest.md", mode="replace")
folder_diagram 用于生成紧凑文件树。当前实现故意保持简单：支持单文件、根名称、基础注释、数量限制和深度限制；未来更偏 docs 或 LLM 的渲染可以在同一签名上扩展。 
from heavenbase.utils.files import folder_diagram

print(folder_diagram("demos/.temp", annotations={"latest.md": "current report"}, limit=12))

​
Further Exploration

相关资源：
  • 序列化工具 - 读写文件内容。
  • 工具概览 - 工具如何分组。