--- markup: occlusion import: json: lib/json.mq.md csv: lib/csv.mq.md title: lib/文件 description: 中文文件系统包装 --- 中文文件系统包装 在明确文件根目录内读写、筛选和整理文件。 能力与边界:旧删除会递归删除目录;窄操作请用只删文件或只删空目录。原子操作只替换一个文件,批量目录操作不是事务。字节和文本支持 CoW;目录状态操作的限制见能力矩阵。 本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。 相对文件路径以 --fs-root 为准,省略时以被调用文件所在目录为准。写入需要显式 fs.write 授权,子进程需要 process.exec;纯计算无需 IO 权限。 实现入口:[src/host/fs.rs](../src/host/fs.rs)、[src/host/fs_ops.rs](../src/host/fs_ops.rs)、[src/host/sandbox_fs.rs](../src/host/sandbox_fs.rs) 开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。 ## 读文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | text | 从路径读取 UTF-8 文本 | 这里使用`路径`。 调用效应:fs.read。 从路径读取 UTF-8 文本。 完成后返回*[从路径读取 UTF-8 文本](> host_read_text path=`路径`)*。 ## 写文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 内容 | any | 必填 | 本操作读取、转换或输出的文本 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`内容`。 调用效应:fs.write。 把文本写入路径(覆盖)。 完成后返回*[把文本写入路径(覆盖)](> host_write_text path=`路径` text=`内容`)*。 ## 追加文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 内容 | any | 必填 | 本操作读取、转换或输出的文本 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`内容`。 调用效应:fs.write。 向路径追加文本。 完成后返回*[向路径追加文本](> host_append_text path=`路径` text=`内容`)*。 ## 存在 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | bool | 路径是否存在 | 这里使用`路径`。 调用效应:fs.read。 路径是否存在。 完成后返回*[路径是否存在](> host_exists path=`路径`)*。 ## 列目录 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | list | 列出路径下的目录项 | 这里使用`路径`。 调用效应:fs.read。 列出路径下的目录项。 完成后返回*[列出路径下的目录项](> host_list_dir path=`路径`)*。 ## 建目录 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 创建目录。 完成后返回*[创建目录](> host_make_dir path=`路径`)*。 ## 建目录树 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 递归创建目录(等同 `mkdir -p`)。 完成后返回*[递归创建目录(等同 mkdir -p)](> host_make_dirs path=`路径`)*。 ## 删除 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 删除指定文件或递归删除目录;旧行为保持兼容,不能用于只允许删除空目录的场景。 删除指定文件或递归删除目录。仅删文件请用只删文件,仅删空目录请用只删空目录。 完成后返回*[删除指定文件或递归删除目录](> host_remove path=`路径`)*。 ## 删目录树 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 递归删除目录;若路径是文件则报错。 完成后返回*[递归删除目录;若路径是文件则报错](> host_remove_tree path=`路径`)*。 ## 状态 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | map | 返回 `{size, mtime_unix, is_file, is_dir}` | 这里使用`路径`。 调用效应:fs.read。 返回 `{size, mtime_unix, is_file, is_dir}`。 完成后返回*[返回 {size, mtime_unix, is_file, is_dir}](> host_stat path=`路径`)*。 ## 遍历 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | list | 深度优先列出相对路径(正斜杠) | 这里使用`路径`。 调用效应:fs.read。 深度优先列出相对路径(正斜杠)。 完成后返回*[深度优先列出相对路径(正斜杠)](> host_walk path=`路径`)*。 ## 复制文件 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 源 | any | 必填 | 来源路径;归档打包时必须是目录 | | 目标 | any | 必填 | 目标路径;仅在操作明确允许时才能覆盖 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`源`、`目标`。 调用效应:fs.write。 复制文件(目标已存在则覆盖)。路径沙箱同其他文件操作。 完成后返回*[复制文件(目标已存在则覆盖)](> host_copy_file src=`源` dest=`目标`)*。 ## 移动 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 源 | any | 必填 | 来源路径;归档打包时必须是目录 | | 目标 | any | 必填 | 目标路径;仅在操作明确允许时才能覆盖 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`源`、`目标`。 调用效应:fs.write。 在沙箱内重命名 / 移动。 完成后返回*[在沙箱内重命名 / 移动](> host_move src=`源` dest=`目标`)*。 ## 建临时 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 前缀 | any | None | 生成名称的前缀,或需要匹配的文本前缀 | | 返回 | 类型 | 说明 | |---|---|---| | result | text | 在程序目录下创建空临时文件,返回相对路径 | 这里使用`前缀`=None。 调用效应:fs.write。 在程序目录下创建空临时文件,返回相对路径。 完成后返回*[在程序目录下创建空临时文件,返回相对路径](> host_make_temp prefix=`前缀`)*。 ## 文本补丁 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 查找 | any | 必填 | 替换前需要精确查找的文本 | | 替换 | any | 必填 | 每个精确匹配项的替换文本 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 对 UTF-8 文本文件做精确 FIND→REPLACE(`查找` 必须唯一匹配一次) | 这里使用`路径`、`查找`、`替换`。 调用效应:fs.write。 对 UTF-8 文本文件做精确 FIND→REPLACE(`查找` 必须唯一匹配一次)。 完成后返回*[对 UTF-8 文本文件做精确 FIND→REPLACE(查找 必须唯一匹配一次)](> host_text_patch path=`路径` find=`查找` replace=`替换`)*。 ## 应用补丁块 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | any | 必填 | 授权文件根目录内的路径 | | 文本 | any | 必填 | 本操作读取、转换或输出的文本 | | 软失败 | any | False | 补丁未匹配时是否软失败 | | 返回 | 类型 | 说明 | |---|---|---| | result | any | 解析规划回复中的 FIND/REPLACE 块并应用到 `路径` | 这里使用`路径`、`文本`、`软失败`=False。 调用效应:fs.write。 解析规划回复中的 FIND/REPLACE 块并应用到 `路径`。`软失败=真` 时仅「找不到 FIND」返回 0;空 FIND、多匹配、整文件重写仍报错。 完成后返回*[解析规划回复中的 FIND/REPLACE 块并应用到 路径](> host_apply_patch_blocks path=`路径` text=`文本` soft=`软失败`)*。 ## 尝试读文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | map | 以 {ok,value,error} 返回文本或错误;仍需 fs | 这里使用`路径`。 调用效应:fs.read。 直接调用此函数: ```sh marqdo call lib/文件.mq.md 尝试读文本 '路径="lib/fs.mq.md"' --effects fs.read --fs-root . --json ``` 以 {ok,value,error} 返回至多 8 MiB 的 UTF-8 文本或错误;仍需 fs.read 授权。 完成后返回*[以 {ok,value,error} 返回至多 8 MiB 的 UTF-8 文本或错误;仍需 fs.read 授权](> host_fs_try_read_text path=`路径`)*。 ## 尝试写文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 内容 | text | 必填 | 本操作读取、转换或输出的文本 | | 返回 | 类型 | 说明 | |------|------|------| | result | map | 覆盖写入 UTF-8 文本,返回 {ok,value,error};需要 fs | 这里使用`路径`、`内容`。 调用效应:fs.write。 覆盖写入 UTF-8 文本,返回 {ok,value,error};需要 fs.write。 完成后返回*[覆盖写入 UTF-8 文本,返回 {ok,value,error};需要 fs.write](> host_fs_try_write_text path=`路径` text=`内容`)*。 ## 读字节 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 字节上限 | number | 8388608 | 读取或展开的字节上限;超限则失败 | | 返回 | 类型 | 说明 | |------|------|------| | result | map | 读取 bytes 记录;默认上限 8 MiB,最大 64 MiB;解码须明确使用字节库。 | 这里使用`路径`、`字节上限`=8388608。 调用效应:fs.read。 读取 bytes 记录;默认上限 8 MiB,最大 64 MiB;解码须明确使用字节库。 完成后返回*[读取 bytes 记录;默认上限 8 MiB,最大 64 MiB;解码须明确使用字节库](> host_fs_read_bytes path=`路径` max_bytes=`字节上限`)*。 ## 写字节 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 数据 | map | 必填 | 含 _type=bytes 与 base64 的可移植字节记录 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`数据`。 调用效应:fs.write。 用字节原子替换文件,不进行 UTF-8 转换;需要 fs.write。 完成后返回*[用字节原子替换文件,不进行 UTF-8 转换;需要 fs.write](> host_fs_write_bytes path=`路径` data=`数据`)*。 ## 读块 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 偏移 | number | 0 | 下一块的字节偏移,从零开始 | | 大小 | number | 65536 | 本次块读取的字节数 | | 返回 | 类型 | 说明 | |------|------|------| | result | map | 从零起字节偏移 offset 读取至多 size 字节,返回 data/next_offset/eof;每次调用关闭文件,不跨会话持有句柄。 | 这里使用`路径`、`偏移`=0、`大小`=65536。 调用效应:fs.read。 从零起字节偏移 offset 读取至多 size 字节,返回 data/next_offset/eof;每次调用关闭文件,不跨会话持有句柄。 完成后返回*[从零起字节偏移 offset 读取至多 size 字节,返回 data/next_offset/eof;每次调用关闭文件,不跨会话持有句柄](> host_fs_read_chunk path=`路径` offset=`偏移` size=`大小`)*。 ## 追加字节 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 数据 | map | 必填 | 含 _type=bytes 与 base64 的可移植字节记录 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`数据`。 调用效应:fs.write。 追加字节,不存在则创建文件;父目录必须存在。 完成后返回*[追加字节,不存在则创建文件;父目录必须存在](> host_fs_append_bytes path=`路径` data=`数据`)*。 ## 原子写文本 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 内容 | text | 必填 | 本操作读取、转换或输出的文本 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`内容`。 调用效应:fs.write。 经同目录独占临时文件和重命名替换文本;失败清理临时文件。这是单文件替换,不是多文件事务。 完成后返回*[经同目录独占临时文件和重命名替换文本;失败清理临时文件](> host_fs_atomic_write path=`路径` text=`内容`)*。 ## 变化才写 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 内容 | text | 必填 | 本操作读取、转换或输出的文本 | | 返回 | 类型 | 说明 | |------|------|------| | result | bool | 仅内容变化时原子写入;返回是否发生写入。 | 这里使用`路径`、`内容`。 调用效应:fs.write。 仅内容变化时原子写入;返回是否发生写入。 完成后返回*[仅内容变化时原子写入;返回是否发生写入](> host_fs_write_changed path=`路径` text=`内容`)*。 ## 校验后写 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 内容 | text | 必填 | 本操作读取、转换或输出的文本 | | 预期摘要 | text | 必填 | 前次精确文本的摘要;操作允许时 None 表示不检查 | | 返回 | 类型 | 说明 | |------|------|------| | result | map | 核对当前 SHA-256 后原子替换,返回结果记录;可发现过期内容,并发写者仍需外部协调。 | 这里使用`路径`、`内容`、`预期摘要`。 调用效应:fs.write。 核对当前 SHA-256 后原子替换,返回结果记录;可发现过期内容,并发写者仍需外部协调。 完成后返回*[核对当前 SHA-256 后原子替换,返回结果记录;可发现过期内容,并发写者仍需外部协调](> host_fs_write_checked path=`路径` text=`内容` expected_sha256=`预期摘要`)*。 ## 读行 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 字节上限 | number | 8388608 | 读取或展开的字节上限;超限则失败 | | 返回 | 类型 | 说明 | |------|------|------| | result | list | 有界读取 UTF-8 行,去除行尾;接受 CRLF,末尾换行不产生额外行。 | 这里使用`路径`、`字节上限`=8388608。 调用效应:fs.read。 有界读取 UTF-8 行,去除行尾;接受 CRLF,末尾换行不产生额外行。 完成后返回*[有界读取 UTF-8 行,去除行尾;接受 CRLF,末尾换行不产生额外行](> host_fs_read_lines path=`路径` max_bytes=`字节上限`)*。 ## 写行 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 行表 | list | 必填 | 待写入的文本行列表 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`行表`。 调用效应:fs.write。 按 LF 原子写入文本行;非空输入追加一个末尾换行。 完成后返回*[按 LF 原子写入文本行;非空输入追加一个末尾换行](> host_fs_write_lines path=`路径` lines=`行表`)*。 ## 只删文件 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 删除文件,拒绝目录;不存在则失败。旧删除接口保持递归兼容行为。 完成后返回*[删除文件,拒绝目录;不存在则失败](> host_fs_remove_file path=`路径`)*。 ## 只删空目录 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`。 调用效应:fs.write。 只删除空目录;非空目录失败。仅原生文件系统支持。 完成后返回*[只删除空目录;非空目录失败](> host_fs_remove_empty_dir path=`路径`)*。 ## 临时目录 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 前缀 | text | "mqtmp" | 生成名称的前缀,或需要匹配的文本前缀 | | 返回 | 类型 | 说明 | |------|------|------| | result | text | 在文件根目录内创建临时目录,返回相对名称;调用方负责删目录树清理,不使用系统全局临时目录。 | 这里使用`前缀`="mqtmp"。 调用效应:fs.write。 在文件根目录内创建临时目录,返回相对名称;调用方负责删目录树清理,不使用系统全局临时目录。 完成后返回*[在文件根目录内创建临时目录,返回相对名称;调用方负责删目录树清理,不使用系统全局临时目录](> host_fs_temp_dir prefix=`前缀`)*。 ## 文件摘要 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | text | 以 64 KiB 缓冲区计算 SHA-256;支持二进制大文件,不整文件载入内存。 | 这里使用`路径`。 调用效应:fs.read。 以 64 KiB 缓冲区计算 SHA-256;支持二进制大文件,不整文件载入内存。 完成后返回*[以 64 KiB 缓冲区计算 SHA-256;支持二进制大文件,不整文件载入内存](> host_fs_file_hash path=`路径`)*。 ## 查找文件 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 授权文件根目录内的路径 | | 模式 | text | "**" | 相对路径 glob,支持 *、** 与 ? | | 排除 | any | None | 遍历时剪枝的 glob 模式列表;None 表示不排除 | | 深度上限 | number | 64 | 最大遍历深度 | | 类型 | text | "file" | 条目类型过滤:file、dir 或 all;all 同时包含文件和目录 | | 返回 | 类型 | 说明 | |------|------|------| | result | list | 按 单星号、双星号与问号 模式查找有序相对路径;exclude 可剪除目录,kind 为 file/dir/all;不跟随符号链接,最多十万项。读取原生文件系统快照。 | 这里使用`路径`、`模式`="**"、`排除`=None、`深度上限`=64、`类型`="file"。 调用效应:fs.read。 按 单星号、双星号与问号 模式查找有序相对路径;exclude 可剪除目录,kind 为 file/dir/all;不跟随符号链接,最多十万项。读取原生文件系统快照。 完成后返回*[按 单星号、双星号与问号 模式查找有序相对路径;exclude 可剪除目录,kind 为 file/dir/all;不跟随符号链接,最多十万项](> host_fs_find path=`路径` pattern=`模式` exclude=`排除` max_depth=`深度上限` kind=`类型`)*。 ## 复制目录树 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 来源 | text | 必填 | 来源路径;归档打包时必须是目录 | | 目标 | text | 必填 | 目标路径;仅在操作明确允许时才能覆盖 | | 覆盖 | bool | False | 是否允许替换已存在的目标文件 | | 排除 | any | None | 遍历时剪枝的 glob 模式列表;None 表示不排除 | | 预演 | bool | False | 是否仅返回计划而不修改文件 | | 返回 | 类型 | 说明 | |------|------|------| | result | list | 在不相交目录树间复制文件;先检查冲突,覆盖须明确开启。返回相对文件列表;dry_run 仅计划。不复制权限、链接和空目录。 | 这里使用`来源`、`目标`、`覆盖`=False、`排除`=None、`预演`=False。 调用效应:fs.write。 在不相交目录树间复制文件;先检查冲突,覆盖须明确开启。返回相对文件列表;dry_run 仅计划。不复制权限、链接和空目录。 完成后返回*[在不相交目录树间复制文件;先检查冲突,覆盖须明确开启](> host_fs_copy_tree src=`来源` dest=`目标` overwrite=`覆盖` exclude=`排除` dry_run=`预演`)*。 ## 同步目录树 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 来源 | text | 必填 | 来源路径;归档打包时必须是目录 | | 目标 | text | 必填 | 目标路径;仅在操作明确允许时才能覆盖 | | 覆盖 | bool | False | 是否允许替换已存在的目标文件 | | 排除 | any | None | 遍历时剪枝的 glob 模式列表;None 表示不排除 | | 预演 | bool | False | 是否仅返回计划而不修改文件 | | 返回 | 类型 | 说明 | |------|------|------| | result | list | 按复制目录树的冲突规则复制新增或变化文件;不删除目标独有文件,执行不是事务。 | 这里使用`来源`、`目标`、`覆盖`=False、`排除`=None、`预演`=False。 调用效应:fs.write。 按复制目录树的冲突规则复制新增或变化文件;不删除目标独有文件,执行不是事务。 完成后返回*[按复制目录树的冲突规则复制新增或变化文件;不删除目标独有文件,执行不是事务](> host_fs_sync_tree src=`来源` dest=`目标` overwrite=`覆盖` exclude=`排除` dry_run=`预演`)*。 ## 批量改名 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 改名表 | list | 必填 | 来源与目标路径组成的改名记录列表 | | 预演 | bool | False | 是否仅返回计划而不修改文件 | | 返回 | 类型 | 说明 | |------|------|------| | result | number | 预检 src/dest 文件记录,拒绝已有或重复目标,然后按输入顺序改名。不支持环路或回滚;dry_run 返回计划数量。 | 这里使用`改名表`、`预演`=False。 调用效应:fs.write。 预检 src/dest 文件记录,拒绝已有或重复目标,然后按输入顺序改名。不支持环路或回滚;dry_run 返回计划数量。 完成后返回*[预检 src/dest 文件记录,拒绝已有或重复目标,然后按输入顺序改名](> host_fs_rename_many moves=`改名表` dry_run=`预演`)*。 ## 读JSON | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 相对文件根目录的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 解析后的数据 | 这里使用`路径`。 调用效应:fs.read。 读取 UTF-8 文本后使用同一标准解析器;错误会终止,批处理请先尝试读文本。 得到**`body` = [读取指定文件的 UTF-8 正文](读文本(路径=`路径`))**。 完成后返回*[解析 JSON 传输文本](json.parse(text=`body`))*。 ## 写JSON | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 相对文件根目录的路径 | | 数据 | any | 必填 | 待序列化的数据 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`数据`。 调用效应:fs.write。 序列化后以原子写入替换文件;不保留旧格式与注释。 得到**`body` = [将结构化值编码为 JSON 文本](json.stringify(value=`数据`))**。 完成后返回*[将准备好的文本写入指定文件](原子写文本(路径=`路径`, 内容=`body`))*。 ## 读CSV | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 相对文件根目录的路径 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 解析后的数据 | 这里使用`路径`。 调用效应:fs.read。 读取 UTF-8 文本后使用同一标准解析器;错误会终止,批处理请先尝试读文本。 得到**`body` = [读取指定文件的 UTF-8 正文](读文本(路径=`路径`))**。 完成后返回*[调用 parse](csv.parse(text=`body`))*。 ## 写CSV | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 相对文件根目录的路径 | | 数据 | list | 必填 | 待序列化的数据 | | 返回 | 类型 | 说明 | |------|------|------| | result | any | 完成后返回 None;文件操作失败时返回诊断 | 这里使用`路径`、`数据`。 调用效应:fs.write。 序列化后以原子写入替换文件;不保留旧格式与注释。 得到**`body` = [调用 stringify](csv.stringify(rows=`数据`))**。 完成后返回*[将准备好的文本写入指定文件](原子写文本(路径=`路径`, 内容=`body`))*。 ## 解析路径 | 参数 | 类型 | 默认 | 说明 | |---|---|---|---| | 路径 | text | 必填 | 相对已授予文件根的路径,或根内的绝对路径 | | 返回 | 类型 | 说明 | |---|---|---| | result | text | 经过原生根目录与符号链接检查的绝对逻辑路径 | 输入`路径`,在授权 fs.read 后解析绝对地址。它使用读文本与临时目录相同的文件上下文,因此进程工作目录与 --fs-root 不同时也能正确组合本地资源 URI。目标可以尚未创建,最近的已有祖先仍经过根目录和符号链接检查。解析只返回地址,不创建文件;结果保留逻辑路径,外部插件和进程继续按各自操作系统权限执行。 完成后返回*[通过原生文件上下文解析实际地址](host_fs_resolve(path=`路径`))*.