- 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。
27 KiB
Executable File
markup, import, title, description
| markup | import | title | description | ||||
|---|---|---|---|---|---|---|---|
| occlusion |
|
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。目标可以尚未创建,最近的已有祖先仍经过根目录和符号链接检查。解析只返回地址,不创建文件;结果保留逻辑路径,外部插件和进程继续按各自操作系统权限执行。
完成后返回*通过原生文件上下文解析实际地址*.