Files
marqdo/lib/文件.mq.md
T
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

27 KiB
Executable File
Raw Blame History

markup, import, title, description
markup import title description
occlusion
json csv
lib/json.mq.md lib/csv.mq.md
lib/文件 中文文件系统包装

中文文件系统包装

在明确文件根目录内读写、筛选和整理文件。

能力与边界:旧删除会递归删除目录;窄操作请用只删文件或只删空目录。原子操作只替换一个文件,批量目录操作不是事务。字节和文本支持 CoW;目录状态操作的限制见能力矩阵。

本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。

相对文件路径以 --fs-root 为准,省略时以被调用文件所在目录为准。写入需要显式 fs.write 授权,子进程需要 process.exec;纯计算无需 IO 权限。

实现入口:src/host/fs.rs、src/host/fs_ops.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。

直接调用此函数:

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

参数 类型 默认 说明
路径 text 必填 相对文件根目录的路径
数据 any 必填 待序列化的数据
返回 类型 说明
result any 完成后返回 None;文件操作失败时返回诊断

这里使用路径、数据。

调用效应:fs.write。

序列化后以原子写入替换文件;不保留旧格式与注释。

得到**body = 将结构化值编码为 JSON 文本**。 完成后返回*[将准备好的文本写入指定文件](原子写文本(路径=路径, 内容=body))*。

读CSV

参数 类型 默认 说明
路径 text 必填 相对文件根目录的路径
返回 类型 说明
result any 解析后的数据

这里使用路径。

调用效应:fs.read。

读取 UTF-8 文本后使用同一标准解析器;错误会终止,批处理请先尝试读文本。

得到**body = 读取指定文件的 UTF-8 正文**。 完成后返回*调用 parse*。

写CSV

参数 类型 默认 说明
路径 text 必填 相对文件根目录的路径
数据 list 必填 待序列化的数据
返回 类型 说明
result any 完成后返回 None;文件操作失败时返回诊断

这里使用路径、数据。

调用效应:fs.write。

序列化后以原子写入替换文件;不保留旧格式与注释。

得到**body = 调用 stringify**。 完成后返回*[将准备好的文本写入指定文件](原子写文本(路径=路径, 内容=body))*。

解析路径

参数 类型 默认 说明
路径 text 必填 相对已授予文件根的路径,或根内的绝对路径
返回 类型 说明
result text 经过原生根目录与符号链接检查的绝对逻辑路径

输入路径,在授权 fs.read 后解析绝对地址。它使用读文本与临时目录相同的文件上下文,因此进程工作目录与 --fs-root 不同时也能正确组合本地资源 URI。目标可以尚未创建,最近的已有祖先仍经过根目录和符号链接检查。解析只返回地址,不创建文件;结果保留逻辑路径,外部插件和进程继续按各自操作系统权限执行。

完成后返回*通过原生文件上下文解析实际地址*.