- 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。
786 lines
27 KiB
Markdown
Executable File
786 lines
27 KiB
Markdown
Executable File
---
|
||
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=`路径`))*.
|