Files
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

786 lines
27 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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=`路径`))*.