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

27 KiB
Executable File

markup, import, title, description
markup import title description
occlusion
json csv
lib/json.mq.md lib/csv.mq.md
lib/fs English filesystem wrappers

English filesystem wrappers

Read, write, find and organize files under an explicit root.

Behavior and limits: Legacy remove recursively deletes directories. Prefer remove_file/remove_empty_dir. Atomic operations replace one file; directory batches are not transactions. Native-only operations state their CoW boundary.

This single source file is the usage and development manual. Import it directly, or use marqdo call with a function heading below. Parameter tables give types and defaults; required parameters must be supplied. Return tables are progressive contracts; prose describes failure and limits.

Relative IO paths use --fs-root, or the called file directory when omitted. Writes require explicit fs.write grants, subprocesses require process.exec, and pure transforms require no IO grant.

Implementation: src/host/fs.rs、src/host/fs_ops.rs、src/host/sandbox_fs.rs

For development, keep EN/ZH behavior aligned and compose public libraries first. Add host primitives only at OS or algorithm boundaries and declare their effects. Run marqdo check --narrative-ratio on this file and the real workflows in tests/stdlib_tasks.rs after edits.

read_text

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result text Read UTF-8 text from path

Use path as the inputs for this operation.

Effects: fs.read.

Read UTF-8 text from path.

Return [Read UTF-8 text from path](> host_read_text path=path).

write_text

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
text text required Text supplied by the caller
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, text as the inputs for this operation.

Effects: fs.write.

Write text to path (overwrite).

Return [Write text to path (overwrite)](> host_write_text path=path text=text).

append_text

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
text text required Text supplied by the caller
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, text as the inputs for this operation.

Effects: fs.write.

Append text to path.

Return [Append text to path](> host_append_text path=path text=text).

exists

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result bool Whether path exists

Use path as the inputs for this operation.

Effects: fs.read.

Whether path exists.

Return [Whether path exists](> host_exists path=path).

list_dir

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result list List directory entries at path

Use path as the inputs for this operation.

Effects: fs.read.

List directory entries at path.

Return [List directory entries at path](> host_list_dir path=path).

make_dir

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Create directory at path.

Return [Create directory at path](> host_make_dir path=path).

make_dirs

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Create directories recursively (mkdir -p).

Return [Create directories recursively (mkdir -p)](> host_make_dirs path=path).

remove

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Remove a file or recursively remove a directory. Legacy behavior; use remove_file or remove_empty_dir for narrow deletion.

Remove a file or recursively remove a directory. For narrow deletion use remove_file or remove_empty_dir.

Return [Remove a file or recursively remove a directory](> host_remove path=path).

remove_tree

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Remove a directory recursively. Errors if path is a file.

Return [Remove a directory recursively](> host_remove_tree path=path).

stat

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result map Returns {size, mtime_unix, is_file, is_dir}

Use path as the inputs for this operation.

Effects: fs.read.

Returns {size, mtime_unix, is_file, is_dir}.

Return [Returns {size, mtime_unix, is_file, is_dir}](> host_stat path=path).

walk

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
返回 类型 说明
result list Depth-first listing of relative paths under path (forward slashes)

Use path as the inputs for this operation.

Effects: fs.read.

Depth-first listing of relative paths under path (forward slashes).

Return [Depth-first listing of relative paths under path (forward slashes)](> host_walk path=path).

copy_file

参数 类型 默认 说明
src text required Source path under the granted root
dest text required Destination path under the granted root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use src, dest as the inputs for this operation.

Effects: fs.write.

Copy a file (overwrites dest if it exists). Paths are sandboxed like other fs ops.

Return [Copy a file (overwrites dest if it exists)](> host_copy_file src=src dest=dest).

move

参数 类型 默认 说明
src text required Source path under the granted root
dest text required Destination path under the granted root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use src, dest as the inputs for this operation.

Effects: fs.write.

Rename / move within the sandbox.

Return [Rename / move within the sandbox](> host_move src=src dest=dest).

make_temp

参数 类型 默认 说明
prefix any None Prefix added to the generated name or tested against text
返回 类型 说明
result text Create an empty temp file under the program directory; return its relative path

Use prefix=None as the inputs for this operation.

Effects: fs.write.

Create an empty temp file under the program directory; return its relative path.

Return [Create an empty temp file under the program directory; return its relative path](> host_make_temp prefix=prefix).

text_patch

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
find any required Exact text to locate before replacement
replace any required Replacement text for each exact match
返回 类型 说明
result any Exact FIND→REPLACE once in a UTF-8 text file

Use path, find, replace as the inputs for this operation.

Effects: fs.write.

Exact FIND→REPLACE once in a UTF-8 text file. find must match exactly once.

Return [Exact FIND→REPLACE once in a UTF-8 text file](> host_text_patch path=path find=find replace=replace).

apply_patch_blocks

参数 类型 默认 说明
path text required Path relative to the granted filesystem root
text text required Text supplied by the caller
soft bool False Whether a missing patch match becomes a recoverable outcome
返回 类型 说明
result any Apply plan-style triple-angle FIND/REPLACE blocks from text to path

Use path, text, soft=False as the inputs for this operation.

Effects: fs.write.

Apply plan-style triple-angle FIND/REPLACE blocks from text to path. Also accepts fenced find/replace pairs and minimal Begin Patch hunks. When soft=True, only “FIND not found” returns 0 (run continues). Empty FIND, multi-match, parse errors, and whole-file FIND still abort — whole-file rewrite is forbidden.

Return [Apply plan-style triple-angle FIND/REPLACE blocks from text to path](> host_apply_patch_blocks path=path text=text soft=soft).

try_read_text

参数 类型 默认 说明
path text required Path within the granted filesystem root
返回 类型 说明
result map Read text as {ok,value,error}; file and permission failures are data

Use path as the inputs for this operation.

Effects: fs.read.

Call this function directly:

marqdo call lib/fs.mq.md try_read_text 'path="lib/fs.mq.md"' --effects fs.read --fs-root . --json

Read at most 8 MiB of UTF-8 text as {ok,value,error}; file, encoding and permission failures are data. The function still requires fs.read.

Return [Read at most 8 MiB of UTF-8 text as {ok,value,error}; file, encoding and permission failures are data](> host_fs_try_read_text path=path).

try_write_text

参数 类型 默认 说明
path text required Path within the granted filesystem root
text text required Text to read, transform or emit as described by this operation
返回 类型 说明
result map Overwrite UTF-8 text and return {ok,value,error}; requires fs

Use path, text as the inputs for this operation.

Effects: fs.write.

Overwrite UTF-8 text and return {ok,value,error}; requires fs.write.

Return [Overwrite UTF-8 text and return {ok,value,error}; requires fs.write](> host_fs_try_write_text path=path text=text).

read_bytes

参数 类型 默认 说明
path text required Path within the granted filesystem root
max_bytes number 8388608 Maximum bytes read or expanded; exceeding it fails
返回 类型 说明
result map Read binary data as a bytes record

Use path, max_bytes=8388608 as the inputs for this operation.

Effects: fs.read.

Read binary data as a bytes record. Default limit is 8 MiB, maximum is 64 MiB; decoding is explicit via lib/bytes.

Return [Read binary data as a bytes record](> host_fs_read_bytes path=path max_bytes=max_bytes).

write_bytes

参数 类型 默认 说明
path text required Path within the granted filesystem root
data map required Portable bytes record containing _type=bytes and base64
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, data as the inputs for this operation.

Effects: fs.write.

Atomically replace a file with bytes; no UTF-8 conversion. Requires fs.write.

Return [Atomically replace a file with bytes; no UTF-8 conversion](> host_fs_write_bytes path=path data=data).

read_chunk

参数 类型 默认 说明
path text required Path within the granted filesystem root
offset number 0 Zero-based byte offset of the next chunk
size number 65536 Number of bytes to read in this chunk
返回 类型 说明
result map Read at most size bytes from offset, returning data/next_offset/eof

Use path, offset=0, size=65536 as the inputs for this operation.

Effects: fs.read.

Read at most size bytes from offset, returning data/next_offset/eof. Offsets are zero-based bytes; each call closes the file, so no handles escape sessions.

Return [Read at most size bytes from offset, returning data/next_offset/eof](> host_fs_read_chunk path=path offset=offset size=size).

append_bytes

参数 类型 默认 说明
path text required Path within the granted filesystem root
data map required Portable bytes record containing _type=bytes and base64
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, data as the inputs for this operation.

Effects: fs.write.

Append bytes, creating a file if absent; parent directory must exist.

Return [Append bytes, creating a file if absent; parent directory must exist](> host_fs_append_bytes path=path data=data).

atomic_write

参数 类型 默认 说明
path text required Path within the granted filesystem root
text text required Text to read, transform or emit as described by this operation
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, text as the inputs for this operation.

Effects: fs.write.

Replace text through a reserved sibling temporary file and rename; failures remove that temp file. This is one-file replacement, not a multi-file transaction.

Return [Replace text through a reserved sibling temporary file and rename; failures remove that temp file](> host_fs_atomic_write path=path text=text).

write_changed

参数 类型 默认 说明
path text required Path within the granted filesystem root
text text required Text to read, transform or emit as described by this operation
返回 类型 说明
result bool Write atomically only when content differs; return whether it was written

Use path, text as the inputs for this operation.

Effects: fs.write.

Write atomically only when content differs; return whether it was written.

Return [Write atomically only when content differs; return whether it was written](> host_fs_write_changed path=path text=text).

write_checked

参数 类型 默认 说明
path text required Path within the granted filesystem root
text text required Text to read, transform or emit as described by this operation
expected_sha256 text required Digest of the exact prior text; None disables the check where allowed
返回 类型 说明
result map Check current SHA-256 before atomic replacement, returning Result

Use path, text, expected_sha256 as the inputs for this operation.

Effects: fs.write.

Check current SHA-256 before atomic replacement, returning Result. Detects stale content; concurrent writers still need external coordination.

Return [Check current SHA-256 before atomic replacement, returning Result](> host_fs_write_checked path=path text=text expected_sha256=expected_sha256).

read_lines

参数 类型 默认 说明
path text required Path within the granted filesystem root
max_bytes number 8388608 Maximum bytes read or expanded; exceeding it fails
返回 类型 说明
result list Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row

Use path, max_bytes=8388608 as the inputs for this operation.

Effects: fs.read.

Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row.

Return [Read bounded UTF-8 lines without terminators; CRLF is accepted and a final newline does not create a phantom row](> host_fs_read_lines path=path max_bytes=max_bytes).

write_lines

参数 类型 默认 说明
path text required Path within the granted filesystem root
lines list required List of text lines to write
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, lines as the inputs for this operation.

Effects: fs.write.

Atomically write text lines using LF and one final newline for nonempty input.

Return [Atomically write text lines using LF and one final newline for nonempty input](> host_fs_write_lines path=path lines=lines).

remove_file

参数 类型 默认 说明
path text required Path within the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Delete a file, refusing directories; missing paths fail. Legacy remove remains recursive for compatibility.

Return [Delete a file, refusing directories; missing paths fail](> host_fs_remove_file path=path).

remove_empty_dir

参数 类型 默认 说明
path text required Path within the granted filesystem root
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path as the inputs for this operation.

Effects: fs.write.

Delete only an empty directory; refuses nonempty directories. Native filesystem only.

Return [Delete only an empty directory; refuses nonempty directories](> host_fs_remove_empty_dir path=path).

temp_dir

参数 类型 默认 说明
prefix text "mqtmp" Prefix added to the generated name or tested against text
返回 类型 说明
result text Create a directory under the filesystem root and return its relative name

Use prefix="mqtmp" as the inputs for this operation.

Effects: fs.write.

Create a directory under the filesystem root and return its relative name. Caller owns cleanup with remove_tree; never uses a global OS temp directory.

Return [Create a directory under the filesystem root and return its relative name](> host_fs_temp_dir prefix=prefix).

file_hash

参数 类型 默认 说明
path text required Path within the granted filesystem root
返回 类型 说明
result text Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file

Use path as the inputs for this operation.

Effects: fs.read.

Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file.

Return [Compute SHA-256 with a 64 KiB read buffer; supports binary and large files without loading the whole file](> host_fs_file_hash path=path).

find

参数 类型 默认 说明
path text required Path within the granted filesystem root
pattern text "**" Relative path glob supporting *, ** and ?
exclude any None Glob pattern list pruned during traversal; None excludes nothing
max_depth number 64 Maximum traversal depth
kind text "file" Entry kind filter: file, dir or all (files and directories)
返回 类型 说明
result list Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all

Use path, pattern="**", exclude=None, max_depth=64, kind="file" as the inputs for this operation.

Effects: fs.read.

Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all. No symlink traversal; at most 100000 results. Native filesystem snapshot.

Return [Find sorted relative paths with star, double-star and question-mark globs; exclude patterns prune directories; kind is file/dir/all](> host_fs_find path=path pattern=pattern exclude=exclude max_depth=max_depth kind=kind).

copy_tree

参数 类型 默认 说明
src text required Source path; archive packing expects a directory
dest text required Destination path; overwrite is allowed only where documented
overwrite bool False Whether an existing destination file may be replaced
exclude any None Glob pattern list pruned during traversal; None excludes nothing
dry_run bool False Whether to return the plan without modifying files
返回 类型 说明
result list Copy files between disjoint trees

Use src, dest, overwrite=False, exclude=None, dry_run=False as the inputs for this operation.

Effects: fs.write.

Copy files between disjoint trees. Preflight conflicts; overwrite is opt-in. Returns relative changed files; dry_run plans only. Does not copy permissions, symlinks or empty directories.

Return [Copy files between disjoint trees](> host_fs_copy_tree src=src dest=dest overwrite=overwrite exclude=exclude dry_run=dry_run).

sync_tree

参数 类型 默认 说明
src text required Source path; archive packing expects a directory
dest text required Destination path; overwrite is allowed only where documented
overwrite bool False Whether an existing destination file may be replaced
exclude any None Glob pattern list pruned during traversal; None excludes nothing
dry_run bool False Whether to return the plan without modifying files
返回 类型 说明
result list Copy new or changed files with copy_tree conflict rules

Use src, dest, overwrite=False, exclude=None, dry_run=False as the inputs for this operation.

Effects: fs.write.

Copy new or changed files with copy_tree conflict rules. Never deletes destination-only files; execution is not transactional.

Return [Copy new or changed files with copy_tree conflict rules](> host_fs_sync_tree src=src dest=dest overwrite=overwrite exclude=exclude dry_run=dry_run).

rename_many

参数 类型 默认 说明
moves list required List of source/destination rename records
dry_run bool False Whether to return the plan without modifying files
返回 类型 说明
result number Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order

Use moves, dry_run=False as the inputs for this operation.

Effects: fs.write.

Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order. No cycles or rollback; dry_run reports the planned count.

Return [Preflight src/dest file records, reject existing or duplicate destinations, then rename in input order](> host_fs_rename_many moves=moves dry_run=dry_run).

read_json

参数 类型 默认 说明
path text required Path relative to filesystem root
返回 类型 说明
result any 解析后的数据

Use path as the inputs for this operation.

Effects: fs.read.

Read UTF-8 then use the standard parser; errors abort, so batch tasks should first use try_read_text.

We retain body = Read UTF-8 text from the selected file. Return Parse the JSON transport text.

write_json

参数 类型 默认 说明
path text required Path relative to filesystem root
value any required Data to serialize
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, value as the inputs for this operation.

Effects: fs.write.

Serialize then atomically replace the file; formatting and comments are not preserved.

We retain body = Encode the structured value as JSON text. Return [Atomic write](atomic_write(path=path, text=body)).

read_csv

参数 类型 默认 说明
path text required Path relative to filesystem root
返回 类型 说明
result any 解析后的数据

Use path as the inputs for this operation.

Effects: fs.read.

Read UTF-8 then use the standard parser; errors abort, so batch tasks should first use try_read_text.

We retain body = Read UTF-8 text from the selected file. Return Parse.

write_csv

参数 类型 默认 说明
path text required Path relative to filesystem root
value list required Data to serialize
返回 类型 说明
result any None after completion; filesystem failures produce a diagnostic

Use path, value as the inputs for this operation.

Effects: fs.write.

Serialize then atomically replace the file; formatting and comments are not preserved.

We retain body = Stringify. Return [Atomic write](atomic_write(path=path, text=body)).

resolve

参数 类型 默认 说明
path text required Path relative to the granted filesystem root, or an absolute path inside it
返回 类型 说明
result text Normalized absolute logical path after the native root and symlink checks

Use path to obtain an absolute address before giving a local file to another resource, such as a SQLite URL. The host resolves it using the same filesystem context as read_text and temp_dir, so a different process working directory does not change the selected root. The destination may not exist yet; its nearest existing ancestor still undergoes the native root and symlink checks. Requires fs.read and creates no file. The returned path remains logical, including permitted links; external plugins and processes retain their own operating-system authority.

Return Resolve the path through the native filesystem context.