File Operation Nodes

Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: crates/cheng-nodes/src/nodes/builtin/tools/file_ops, crates/cheng-file-ops/src

Two ways to use the same core. tools/file_ops_hub takes the operation as a field, which is what an agent needs — one node, many operations, and structured failure output that says whether the call may be retried unchanged. The individual nodes are for graphs you draw by hand, where the operation is part of the picture. Mutating operations return a receipt describing what actually changed on disk; when it reports that the runtime verified the postcondition, a follow-up read to confirm the write is wasted work.

File Operations Hub — `tools/file_ops_hub`

File operations aggregate node: only one node needed on canvas, control Agent's available file operation capabilities via toggle switches.

Inputs

Field	Type	Required	Default	Description
`operation`	string	—	`""`	File operation type to execute
`path`	string	—	—	Unified target path for the file operation
`sandbox_root`	string	—	—	Static sandbox root directory. Once set, LLM can only access files in this directory and its subdirectories.
`config`	object (port)	—	`{"allow_ignored":null,"allow_sensitive":null,...`	Unified configuration object. For LLM tool calls, pass this as a JSON object, not a JSON string. Connection port, not a form field. Control: `text`
`allow_read_info`	boolean	✅	`true`	是否允许获取文件元信息（只读）. Control: `switch`
`allow_read_content`	boolean	✅	`true`	是否允许读取文件内容（只读）. Control: `switch`
`allow_list_directory`	boolean	✅	`true`	是否允许列出目录（只读）. Control: `switch`
`allow_search`	boolean	✅	`true`	是否允许搜索文件内容（只读）. Control: `switch`
`allow_file_tree`	boolean	✅	`true`	是否允许渲染仓库文件树快照（只读）. Control: `switch`
`allow_diff`	boolean	✅	`true`	是否允许生成 diff（只读）. Control: `switch`
`allow_validate`	boolean	✅	`true`	是否允许 JSON/YAML 校验（只读）. Control: `switch`
`allow_write`	boolean	✅	`true`	是否允许写入/创建文件（中副作用）. Control: `switch`
`allow_edit`	boolean	✅	`true`	是否允许精确编辑文件（中副作用）. Control: `switch`
`allow_patch`	boolean	✅	`true`	是否允许 JSON/YAML 路径级补丁（中副作用）. Control: `switch`
`allow_copy`	boolean	✅	`true`	是否允许复制文件/目录（中副作用）. Control: `switch`
`allow_backup`	boolean	✅	`true`	是否允许创建快照（中副作用）. Control: `switch`
`allow_move`	boolean	✅	`true`	是否允许移动/重命名（高副作用，会移除源；启用后每次调用需用户审批）. Control: `switch`
`allow_rollback`	boolean	✅	`true`	是否允许从快照回滚（高副作用，覆写；启用后每次调用需用户审批）. Control: `switch`
`allow_delete`	boolean	✅	`true`	是否允许删除文件（高副作用，不可逆；启用后每次调用需用户审批）. Control: `switch`
`allow_batch`	boolean	✅	`true`	是否允许批量操作（混合副作用，逐项二次校验；启用后每次调用需用户审批）. Control: `switch`
`require_approval`	boolean	✅	`true`	变更操作是否需要用户审批（静态配置，LLM 不可写）。默认 true。默认策略下，经验证工作区内的小范围可撤销变更（新建文件、带备份的单文件编辑/补丁、复制到新路径、建目录、快照）自动执行；其余变更弹出审批卡。设为 false：write/edit/patch/create_directory/copy/backup 及不含破坏性子操作的 batch 直接执行；delete/move/rollback（及含它们的 batch）仍需审批，除非部署级受信任自动化策略（`CHENG_TRUSTED_AUTOMATION_POLICY_FILE`）为该工作流授权。 Control: `switch`

Outputs

Field	Type	Description
`operation`	string	Actual operation type executed
`summary`	string	Operation summary for quick top-level result reading
`error_kind`	string	Machine-readable error type, e.g. operation_not_enabled / invalid_operation
`terminal`	boolean	true means retrying the same operation or switching entrypoint will not recover; config or approach change needed
`enabled_operations`	array<string>	List of operations enabled by current node config (only filled on terminal errors; omitted on success)
`disabled_operations`	array<string>	List of operations disabled by current node config (only filled on terminal errors; omitted on success)
`error`	string	Error message (operation denied or execution failed)
`result`	any	Operation result (JSON-serialized sub-tool output)
`correct_call`	any	A valid call for this operation as structured JSON, copyable as-is
`error_field`	string	Caller-notation path of the offending field (e.g. config.content), so the correction targets one argument instead of the whole call
`mutation_receipt`	object	Authoritative record of what this mutation actually changed on disk. self_verified=true means the runtime re-read the target and confirmed the postcondition, so a follow-up read to verify the write is unnecessary. Absent for read-only operations
`mutation_receipts`	array<object>	Per-child receipts for batch_file_ops, in execution order. Present even when the batch failed, because earlier children may already have committed
`mutation_summary`	string	One-line summary of the mutation receipt: what changed and whether it was verified on disk
`retry_disposition`	string	One of retry_same_call, retry_after_correction, do_not_retry. Says whether THIS call may be reissued unchanged — a different question from `terminal`, which says whether the approach or config must change
`suggested_action`	string	Stable next-action identifier (e.g. use_file_tree, correct_source_path), so the caller does not have to parse prose
`workspace_delta`	object	Incremental path-level changes from this operation. Use it to update your picture of the workspace instead of re-running file_tree after an edit

View File — `tools/view_file`

Read file content. Four MUTUALLY EXCLUSIVE modes: line (start_line/end_line), tail (tail_lines), byte (offset_bytes/limit_bytes), char (offset_chars/limit_chars). Always returns total_lines and eof so the full picture is visible. Line mode caps at 500 lines AND a character budget; when more remains, the response carries exactly one continuation cursor (next_start_line / next_offset_bytes / next_offset_chars) plus truncated_reason — follow that cursor instead of re-reading the same range. When NO range parameter is given and the file exceeds 500 lines, only the first 200 lines are returned as a structure preview (truncated_reason=large_file_preview) — locate what you need with search_files first.

Inputs

Field	Type	Required	Default	Description
`end_line`	integer	—	—	LINE MODE. End line number (inclusive), default min(start_line+499, total_lines). Must be >= start_line. Mutually exclusive with tail_lines and with byte/char modes
`file_path`	string	✅	—	Absolute file path to view
`known_modified_at`	string	—	—	Modification time the caller last observed (RFC 3339). A hint only — coarse or equal timestamps never prove the content is unchanged.
`known_sha256`	string	—	—	Whole-file SHA-256 the caller already observed. When it still matches on disk, the response is a compact file_unchanged marker instead of the content.
`known_size`	integer	—	—	Size the caller last observed. A hint used to skip hashing when it already differs; never proof of equality.
`limit_bytes`	integer	—	—	BYTE MODE. Max bytes to read, capped at 1 MiB. The window end is snapped down to a UTF-8 boundary, so a fixed byte budget never fails on multibyte text
`limit_chars`	integer	—	—	CHAR MODE. Max characters to read (output still capped at 1 MiB)
`offset_bytes`	integer	—	—	BYTE MODE. Byte offset (0-indexed); supplying it selects byte mode. Must land on a UTF-8 boundary — pass the response's `next_offset_bytes` here to continue, which is always a valid boundary. Mutually exclusive with line mode, tail mode, and char mode
`offset_chars`	integer	—	—	CHAR MODE. Character offset (0-indexed); supplying it selects char mode. Pass the response's `next_offset_chars` here to continue. REQUIRED to make progress when a response reports truncated_reason=line_too_long. Mutually exclusive with line mode, tail mode, and byte mode
`start_line`	integer	—	—	LINE MODE. Start line number (1-indexed), default 1. Mutually exclusive with tail_lines, byte mode (offset_bytes/limit_bytes), and char mode (offset_chars/limit_chars). Continue a truncated line-mode read by passing the response's `next_start_line` here. Note: omitting ALL range parameters on a file longer than 500 lines returns only the first 200 lines as a structure preview (truncated_reason=large_file_preview)
`tail_lines`	integer	—	—	TAIL MODE. Return the last N lines in one call (no need to know the file length). Mutually exclusive with start_line/end_line and with byte/char modes. Capped at 500 shown lines (the newest are kept).

Outputs

Field	Type	Description
`content`	string	File content. line mode has line number prefixes; byte/char mode is raw slice text
`encoding`	string	Encoding (always utf-8)
`end_line`	integer	Actual end line (line mode only)
`eof`	boolean	Whether end of file was reached
`error`	string	Error message (when present, other fields are empty/zero)
`file_path`	string	Canonicalized absolute path
`file_unchanged`	boolean	The caller's known digest still describes this file; content was not resent.
`mode`	string	Read mode: line, byte, or char
`next_offset_bytes`	integer	Continuation cursor for byte mode: pass this as `offset_bytes` on the next call. Always a valid UTF-8 boundary; absent at EOF
`next_offset_chars`	integer	Continuation cursor for char mode: pass this as `offset_chars` on the next call. Also used when truncated_reason=line_too_long, where char mode is the ONLY way to advance; absent at EOF
`next_start_line`	integer	Continuation cursor for line mode: pass this as `start_line` on the next call. Present only when truncated on a line boundary; absent at EOF
`offset_bytes`	integer	Actual start byte offset (byte mode only)
`offset_chars`	integer	Actual start character offset (char mode only)
`requested_tail_lines`	integer	Requested tail line count (tail read only; actual range in start_line/end_line)
`sha256`	string	Current whole-file SHA-256, returned for conditional reads so the caller can refresh its observation.
`shown_bytes`	integer	Actual bytes returned (byte/char mode)
`shown_chars`	integer	Actual characters returned (char mode only)
`start_line`	integer	Actual start line (line mode only)
`total_bytes`	integer	Total file size in bytes
`total_chars`	integer	Total character count (char mode only)
`total_lines`	integer	Total line count (computed even in byte/char mode)
`truncated`	boolean	Whether output was truncated due to exceeding limits
`truncated_reason`	string	Why the output was cut short: max_lines, max_output_chars, byte_limit, char_limit, line_too_long, or large_file_preview. Read this together with the matching next_* cursor. large_file_preview means no range was requested on a long file, so only a leading structure preview was returned — prefer locating the region with search_files over paging the whole file

Write File — `tools/write_file`

Create new file or overwrite/append existing file. Uses atomic write (temp file + rename) to prevent file corruption from interrupted writes.

Inputs

Field	Type	Required	Default	Description
`file_path`	string	✅	—	Absolute file path to write
`content`	string	✅	—	File content to write (UTF-8)
`content_artifact`	object	—	`null`	Artifact to write to the target path (preferred over inline content)
`content_artifact_uri`	string	—	`null`	artifact:// URI for the content to write
`source_encoding`	string	—	`null`	utf-8\|text (text export) or binary (byte-exact); default auto-detects
`overwrite`	boolean	—	`false`	Whether to allow overwriting existing file, default false
`force_overwrite`	boolean	—	`false`	Force overwrite: skip the expected_sha256 confirmation round-trip and imply overwrite for existing files, default false. Backups remain on by default so recovery is preserved
`create_dirs`	boolean	—	`true`	Whether to automatically create parent directories, default true
`append`	boolean	—	`false`	Append mode (takes priority over overwrite), default false
`dry_run`	boolean	—	`false`	Preview the write (diff + current_sha256) without any side effects, default false
`expected_sha256`	string	—	—	Confirmation guard for overwriting an existing file: hex SHA-256 of the current file content as observed during preview/read. Required to overwrite an existing file; the write is rejected if it does not match the current file hash
`allow_ignored`	boolean	—	`null`	Permit writing to a path matched by .gitignore/.ignore. Default false blocks such targets.
`allow_sensitive`	boolean	—	`null`	Permit writing to a sensitive path (.env, private keys, credentials). Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory
`create_backup`	boolean	—	`null`	Create a recoverable snapshot before overwriting/appending an existing file. Defaults to true for real modifications; never created during dry runs or for new files

Outputs

Field	Type	Description
`backup_id`	string	备份 ID（create_backup=true 且覆写/追加已有文件时）
`bytes_written`	integer	写入字节数
`created`	boolean	true = new file created; false = overwritten or appended
`current_sha256`	string	当前文件内容的 SHA-256（既有可读文件时填充）。覆写时作为 expected_sha256 回传。
`diff`	string	Unified diff (filled when overwriting/appending existing text files; None if diff generation fails)
`dry_run`	boolean	是否为演练模式
`error`	string	Error message if the operation failed
`file_bytes_after`	integer	写入后磁盘文件的字节数（真实写入成功后填充）
`file_path`	string	实际写入的规范路径
`lines_after`	integer	写入后磁盘文件的行数（真实写入成功且可作为 UTF-8 读取时填充）
`requested_bytes`	integer	请求写入的内容字节数（dry_run/失败时也填充，便于 LLM 判断是否疑似截断）
`requested_lines`	integer	请求写入的内容行数（基于 UTF-8 文本的 logical line count）
`requested_sha256`	string	请求内容的 SHA-256。用于让调用方确认“传入工具的内容”到底有多长/是什么。
`self_verified`	boolean	工具侧写后自校验：磁盘内容 SHA-256 是否等于请求内容 SHA-256。
`sha256_after`	string	真实写入后磁盘文件的 SHA-256。
`summary`	string	Write result summary (suitable for passing to LLM / Preview nodes)
`verification_error`	string	自校验失败或跳过的原因。

Edit File — `tools/edit_file`

Replace file content by exact content matching. Supports multiple replacement operations; writes back atomically only when all succeed; any failure keeps original file unchanged.

Inputs

Field	Type	Required	Default	Description
`allow_ignored`	boolean	—	`null`	Permit editing a path matched by .gitignore/.ignore. Default false blocks such targets.
`allow_sensitive`	boolean	—	`null`	Permit editing a sensitive path (.env, private keys, credentials). Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory; defaults next to the target file
`confusable_fallback`	boolean	—	`null`	If exact match fails, retry after normalizing a small set of confusables (smart quotes, en/em dash, non-breaking space, selected full-width punctuation) to ASCII. Default false. Exact matching is always tried first.
`create_backup`	boolean	—	`null`	Create a recoverable snapshot before writing. Defaults to true for real modifications; never created during dry runs. Pass false to opt out
`dry_run`	boolean	—	`false`	Validate and preview diff without writing, default false
`expected_sha256`	string	—	—	Optional lost-update guard: hex SHA-256 of the file content as last read; the edit is rejected if the current file hash differs
`file_path`	string	✅	—	Absolute file path to edit
`force_overwrite`	boolean	—	`false`	Force write fast-path: short-circuit the expected_sha256 lost-update guard, default false. Backups remain on by default
`ignore_whitespace`	boolean	—	`null`	If exact match fails, retry comparing whitespace-normalized forms (collapse runs of spaces/tabs, ignore leading indentation and trailing whitespace; newlines stay significant). Applies only when exactly ONE normalized candidate exists; multiple candidates fail with ambiguous_whitespace_match. Default false; exact matching is always tried first.
`max_diagnostic_candidates`	integer	—	—	Maximum similarity candidates returned in failure diagnostics, default 3
`replace_all`	boolean	—	`null`	Replace all occurrences within the selected scope. Default false preserves the require_unique_match safety model. Use dry_run for broad replace_all edits first.
`replacements`	array<object>	—	—	List of replacement operations (executed in order). Can be provided as a direct array OR as a JSON string for convenience.
`replacements_json`	string	—	—	Alternative: provide replacements as a JSON string (e.g., '{"old_content":"...","new_content":"..."}'). If provided, overrides the replacements field.
`require_unique_match`	boolean	—	—	Require a unique match per replacement, default true. When false, multiple matches replace the first occurrence.
`return_diff`	boolean	—	—	Return a unified diff for changed files and dry runs, default true
`snippet_context_lines`	integer	—	—	Context lines around each changed range in returned snippets. Default 3.

Outputs

Field	Type	Description
`applied_count`	integer	成功应用的替换数（输入数组中产生变更的条目数）
`backup_id`	string	备份 ID（create_backup=true 且成功写入时）
`changed`	boolean	Whether the file content changed
`diagnostics`	array<object>	Failure diagnostics
`diff`	string	Unified diff of changes (filled when return_diff or dry_run)
`dry_run`	boolean	是否为演练模式
`error`	string	Error message (stops on first replacement failure; file remains unchanged)
`file_path`	string	编辑的文件路径
`match_mode`	string	匹配模式：exact \| whitespace_normalized \| confusable_normalized
`replacement_occurrences`	integer	实际替换的匹配次数（replace_all 时可大于 applied_count）
`snippets`	array<object>	Change snippets around each modified range with line numbers (on success or dry run)
`total_lines_after`	integer	编辑后总行数
`total_lines_before`	integer	编辑前总行数
`used_confusable_fallback`	boolean	是否使用了视觉混淆字符归一化回退匹配

Patch File — `tools/patch_file`

Apply JSON Pointer path-level patches (set/remove/append/insert/replace) to JSON/YAML, or write whole text/Markdown content. Atomic: all patches validated in memory before writing. Supports dry_run.

Inputs

Field	Type	Required	Default	Description
`allow_ignored`	boolean	—	—	Permit patching a path matched by .gitignore/.ignore. Default false blocks such targets.
`allow_sensitive`	boolean	—	—	Permit patching a sensitive path (.env, keys, credentials). Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory
`content`	string	—	—	Whole-file replacement content. When provided, patches are ignored.
`create_backup`	boolean	—	—	Create a recoverable snapshot before writing. Defaults to true for real modifications; never created during dry runs. Pass false to opt out
`dry_run`	boolean	✅	—	Preview diff without writing, default false
`file_path`	string	✅	—	Target JSON/YAML file path
`format`	string	—	—	auto \| json \| yaml \| text \| markdown, default auto
`patches`	array<object>	—	—	List of patches applied in order

Outputs

Field	Type	Description
`backup_id`	string	备份 ID（create_backup=true 且成功写入时）
`changed`	boolean	Whether the file content changed
`diff`	string	Unified diff of changes
`dry_run`	boolean	是否演练模式
`error`	string	Error message if the operation failed
`error_details`	array<object>	补丁级失败详情（patch_index/op/path/message）
`file_path`	string	规范化文件路径
`format`	string	Actual format used
`patches_applied`	integer	成功应用的补丁数
`validation_after_patch`	object	补丁后序列化结果的格式校验（确认仍可解析）

Copy File — `tools/copy_file`

Copy a file or directory to a new location. Content is copied to a temporary staging path and then atomically renamed into place (existing targets are preserved until the swap succeeds). Directories require recursive=true. Refuses to overwrite unless overwrite=true.

Inputs

Field	Type	Required	Default	Description
`allow_ignored`	boolean	—	`null`	Permit copying to a destination matched by .gitignore/.ignore. Default false blocks such targets.
`allow_sensitive`	boolean	—	`null`	Permit copying to a sensitive destination (.env, keys, credentials). Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory
`create_backup`	boolean	—	`null`	Create a recoverable snapshot of an existing destination file before overwriting it. Defaults to true for real overwrites; never created during dry runs or for new destinations
`create_dirs`	boolean	—	`true`	Whether to automatically create destination parent directories, default true
`destination_path`	string	✅	—	Destination path
`dry_run`	boolean	—	`false`	Preview the copy (validation + created/overwritten report) without any side effects, default false
`overwrite`	boolean	—	`false`	Whether to allow overwriting an existing destination, default false
`recursive`	boolean	—	`false`	Must be true to copy a directory, default false
`source_path`	string	✅	—	Source file or directory path

Outputs

Field	Type	Description
`backup_id`	string	覆写前目标文件快照的备份 ID（仅覆写已有目标文件时；dry_run / 新建为 None）
`bytes_copied`	integer	复制的字节数（目录为聚合值）
`created`	boolean	true = destination was newly created; false = overwritten
`destination_path`	string	规范化后的目标路径
`dry_run`	boolean	是否为演练模式
`error`	string	Error message if the operation failed
`is_dir`	boolean	Whether the source is a directory
`overwritten`	boolean	Whether an existing destination was overwritten
`source_path`	string	规范化后的源路径
`summary`	string	Operation result summary

Move File — `tools/move_file`

Move or rename a file or directory. Prefers atomic rename; falls back to copy-then-delete across filesystems (source deleted only after a fully successful copy).

Inputs

Field	Type	Required	Default	Description
`allow_ignored`	boolean	—	`null`	Permit moving when the source or destination is matched by .gitignore/.ignore. Default false blocks.
`allow_sensitive`	boolean	—	`null`	Permit moving when the source or destination is a sensitive path. Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory
`create_backup`	boolean	—	`null`	Create a recoverable snapshot of an existing destination file before it is overwritten by the move. Defaults to true for real overwrites; never created during dry runs or when the destination is new
`create_dirs`	boolean	—	`true`	Whether to automatically create destination parent directories, default true
`destination_path`	string	✅	—	Destination path
`dry_run`	boolean	—	`false`	Preview the move (validation + overwrite report) without any side effects, default false
`overwrite`	boolean	—	`false`	Whether to allow overwriting an existing destination, default false
`source_path`	string	✅	—	Source file or directory path

Outputs

Field	Type	Description
`backup_id`	string	覆写前目标文件快照的备份 ID（destination overwrite backup：仅覆写已有目标文件时创建；dry_run / 新建目标为 None）
`destination_path`	string	规范化后的目标路径
`dry_run`	boolean	是否为演练模式
`error`	string	Error message if the operation failed
`moved`	boolean	Whether the move was successful
`overwritten`	boolean	Whether an existing destination was overwritten
`source_path`	string	规范化后的源路径
`summary`	string	Operation result summary

Delete File — `tools/delete_file`

Delete file (high side-effect, irreversible). Only allows deleting files, not directories. Supports dry_run rehearsal mode.

Inputs

Field	Type	Required	Default	Description
`allow_ignored`	boolean	—	`null`	Permit deleting a path matched by .gitignore/.ignore (e.g. generated output). Requires explicit intent; default false blocks.
`allow_sensitive`	boolean	—	`null`	Permit deleting a sensitive path (.env, keys, credentials). Normally requires approval; default false blocks.
`backup_label`	string	—	—	Optional label for the backup
`backup_root`	string	—	—	Optional backup root directory
`create_backup`	boolean	—	`null`	Create a recoverable snapshot before deleting the file. Defaults to true for real deletions; never created during dry runs
`dry_run`	boolean	—	`false`	Dry run mode (validate only, no actual deletion), default false
`file_path`	string	✅	—	Absolute file path to delete

Outputs

Field	Type	Description
`backup_id`	string	删除前快照的备份 ID（可用 rollback_file 恢复；dry_run / 未删除时为 None）
`deleted`	boolean	true = successfully deleted (dry_run=true means deletable)
`dry_run`	boolean	是否为演练模式
`error`	string	Error message if the operation failed
`file_path`	string	操作的文件路径
`file_size_bytes`	integer	被删除文件的大小（删除前记录）

Diff File — `tools/diff_file`

Generate a unified diff between two files, or between a file and proposed new content. Read-only.

Inputs

Field	Type	Required	Default	Description
`compare_path`	string	—	—	File to compare against
`context_lines`	integer	—	—	Context lines, default 3
`file_path`	string	✅	—	Base file path
`new_content`	string	—	—	Proposed new content to diff against

Outputs

Field	Type	Description
`added_lines`	integer	新增行数
`compare_path`	string	对比文件路径（file-to-content 模式为 null）
`diff`	string	Unified diff text
`error`	string	Error message if the operation failed
`file_path`	string	规范化后的基准文件路径
`has_changes`	boolean	Whether there are differences
`removed_lines`	integer	删除行数
`truncated`	boolean	Whether the diff was truncated due to exceeding output limit

Validate File — `tools/validate_file`

Validate that a file's content (or inline content) is well-formed JSON or YAML. Read-only.

Inputs

Field	Type	Required	Default	Description
`content`	string	—	—	Inline content to validate
`file_path`	string	—	—	File path to validate
`format`	string	—	—	auto \| json \| yaml, default auto

Outputs

Field	Type	Description
`column`	integer	Error column number (when provided by parser)
`error`	string	Node-level error (path resolution / read failure etc.)
`error_message`	string	Validation error message when validation fails
`file_path`	string	Canonical file path (empty for inline content)
`format`	string	Actual format used (json or yaml)
`line`	integer	Error line number (when provided by parser)
`summary`	string	Result summary
`valid`	boolean	Whether the content is valid

File Info — `tools/file_info`

Get file or directory metadata (size, line count, modification time, binary or not, etc.) without reading file content.

Inputs

Field	Type	Required	Default	Description
`path`	string	✅	—	Absolute path of file or directory

Outputs

Field	Type	Description
`created`	string	Creation time (ISO 8601; None on some OSes)
`entry_type`	enum	Entry type: File, Dir, or Symlink. Options: `file`, `dir`, `symlink`
`error`	string	Error message if the operation failed
`exists`	boolean	Whether the path exists
`is_binary`	boolean	Whether the file is binary
`is_readable`	boolean	Whether the current process has read permission
`is_writable`	boolean	Whether the current process has write permission
`metadata`	string	Aggregated metadata summary (suitable for passing to LLM / Preview nodes)
`mime_type`	string	Inferred MIME type (e.g. text/x-rust, text/plain)
`modified`	string	Modification time (ISO 8601)
`path`	string	Canonical absolute path
`size_bytes`	integer	File size in bytes; None for directories
`total_lines`	integer	Total line count for text files; None for binary or directories

File Tree — `tools/file_tree`

Render a character-budgeted repository tree snapshot with structured stats. Respects .gitignore, never follows symlinks. Ideal for cold-start project orientation.

Inputs

Field	Type	Required	Default	Description
`exclude_patterns`	array	—	—	Gitignore-style glob patterns to exclude. A recursive directory pattern such as ["target/**"] removes both target/ and all descendants; real empty directories not matched by an exclude remain visible.
`include_patterns`	array	—	—	Gitignore-style glob whitelist with search_files override semantics. Patterns match entries, not a separate file-only namespace: [".rs"] keeps Rust files (and traverses their parent directories), while ["/"] matches directories only and therefore renders a directory-only view.
`include_stats`	boolean	—	—	Compute extension_stats and largest_dirs, default false
`max_chars`	integer	—	—	Character budget for the rendered tree string. Default 20000, hard cap 200000.
`max_depth`	integer	—	—	Depth convention: the root is depth 0; max_depth = 1 renders only direct root entries, max_depth = 2 adds one more level, and so on. Default 64, hard cap 256. Entries beyond the limit are never rendered, but their existence is reported via truncated/truncated_reason.
`max_file_size`	integer	—	—	Files larger than this (bytes) are omitted from the tree (still scanned). None = no limit.
`max_scan_ms`	integer	—	—	Wall-clock budget for the scan in milliseconds. Default 5000, hard cap 60000.
`max_scanned_files`	integer	—	—	Upper bound on filesystem entries visited during traversal. Default 20000.
`offset`	integer	—	—	Continuation offset into the deterministic rendered entries, excluding the root line. Default 0. When next_offset is returned, call again with the same options and offset=next_offset.
`root_path`	string	✅	—	Root directory to snapshot (must be a directory, not a file)
`show_hidden`	boolean	—	`false`	Include dotfiles/dot-directories, default false
`stats_scope`	enum	—	—	Statistics scope: 'rendered' (cheap) or 'scanned' (walks past render budget). Default rendered. Options: `rendered`, `scanned`

Outputs

Field	Type	Description
`elapsed_ms`	integer	Operation duration in milliseconds
`error`	string	Error message when the operation failed
`extension_stats`	array<object>	Per-extension file counts and sizes (populated when include_stats=true)
`largest_dirs`	array<object>	Largest directories by recursive file count (populated when include_stats=true)
`next_offset`	integer	Continuation offset when max_chars truncates after at least one entry. Pass it as offset with all other options unchanged. Absent at the end or when no entry can fit.
`omitted_entries`	integer	Number of entries omitted from the tree (scanned_total - rendered_total)
`rendered_dirs`	integer	Number of directories appearing in the tree string (including root)
`rendered_files`	integer	Number of files appearing in the tree string
`root_path`	string	Canonical root directory path
`scan_cancelled`	boolean	True when the filesystem scan was cancelled due to max_scan_ms
`scan_truncated`	boolean	True when the filesystem scan was truncated due to max_scanned_files
`scanned_dirs`	integer	Number of directories counted during traversal (including root, per stats_scope)
`scanned_files`	integer	Number of files counted during traversal (per stats_scope)
`snapshot_fingerprint`	string	Stable fingerprint of the rendered structure; equal fingerprints mean the caller's cached tree is still current.
`stats_complete`	boolean	True when statistics are complete (scan was not truncated or cancelled)
`stats_scope`	enum	Effective statistics scope used for this result: 'rendered' or 'scanned'. Echoes the input or the 'rendered' default. Options: `rendered`, `scanned`
`tree`	string	Rendered directory tree string (character-budgeted)
`truncated`	boolean	True when the tree was truncated due to max_chars or max_depth
`truncated_reason`	string	Human-readable reason for truncation or cancellation

List Directory — `tools/list_directory`

List directory contents, return structured entry list. Supports glob filtering, recursive depth control, and offset pagination.

Inputs

Field	Type	Required	Default	Description
`directory_path`	string	✅	—	Absolute directory path to list
`max_depth`	integer	—	—	Recursion depth (0=directory itself only, 1=direct children). Default 1, max 5.
`offset`	integer	—	`0`	Pagination offset into matched entries, default 0
`page_size`	integer	—	—	Entries to return for this page, default 50, max 200
`pattern`	string	—	—	Filename glob filter (e.g. "*.rs"), matches filename only, not full path
`show_hidden`	boolean	—	`false`	Whether to show hidden files/directories (starting with .), default false
`verbose`	boolean	—	`false`	Return full per-entry metadata (absolute_path, modified, is_binary) when true. Default false returns only name/relative_path/entry_type/size_bytes/depth to keep directory browsing cheap; set true only when you actually need timestamps, binary detection, or absolute paths.

Outputs

Field	Type	Description
`directory_path`	string	规范化后的目录路径
`elapsed_ms`	integer	操作耗时（毫秒）
`entries`	array<object>	Entry list (depth-first, directories first, sorted by hierarchy)
`error`	string	Error message if the operation failed
`next_offset`	integer	Next page offset; None when no more entries
`offset`	integer	Current pagination offset
`page_size`	integer	Current page size
`returned_entries`	integer	本页实际返回条目数
`total_entries`	integer	匹配的总条目数（分页前）
`truncated`	boolean	Whether more entries are available via offset=next_offset

Search Files — `tools/search_files`

Search text in files or directories, like grep, returns structured matching results. Supports regex, case-insensitive, glob filtering and context lines.

Inputs

Field	Type	Required	Default	Description
`case_insensitive`	boolean	—	`false`	Whether to ignore case, default false
`context_lines`	integer	—	—	Show N lines of context before/after each match (0-3), default 0 (content mode only)
`exclude_patterns`	array	—	—	Exclude filename glob list (e.g. [".bak", "target/*"])
`file_types`	array	—	—	Language type filters (e.g. ["rust","ts","tsx"]). Recognized names map to common extensions; any unrecognized name is treated as a file extension glob (e.g. "vue" → *.vue).
`include_patterns`	array	—	—	Filename glob filter list (e.g. [".rs", ".toml"]), only search matching files
`is_regex`	boolean	—	`false`	Whether query is a regex pattern, default false
`max_files`	integer	—	—	files_with_matches mode: max returned files, default 500, hard cap 5000
`max_match_span_bytes`	integer	—	—	multiline: skip matches spanning more than this many bytes
`max_match_span_lines`	integer	—	—	multiline: skip matches spanning more than this many lines
`max_results`	integer	—	—	content mode: max returned matches, default 200, hard cap 1000
`max_scanned_bytes`	integer	—	—	Upper bound on total text bytes scanned, default 256MB
`max_scanned_files`	integer	—	—	Upper bound on files opened/searched, default 50000
`multiline`	boolean	—	`false`	Evaluate regex against full file text (spanning lines), default false
`output_mode`	enum	—	—	Output mode: content (default, returns matching lines), files_with_matches (only file paths + counts), count (only counts)
`query`	string	✅	—	Search keyword or regular expression
`search_path`	string	✅	—	Starting path for search (file or directory absolute path)
`timeout_ms`	integer	—	—	multiline: wall-clock timeout in ms, default 5000, hard cap 30000

Outputs

Field	Type	Description
`elapsed_ms`	integer	Operation elapsed time in milliseconds
`error`	string	Error message if the operation failed
`file_match_counts`	array<object>	Per-file match counts (files_with_matches / count mode)
`files_with_matches`	array<string>	List of file paths that contain matches (files_with_matches mode)
`matched_files`	integer	Number of files with matches
`matches`	array<object>	Match results list (content mode; sorted by file path + line number)
`searched_files`	integer	Number of files actually scanned
`total_matches`	integer	Number of matches returned (content mode: returned entries; other modes: total hits)
`truncated`	boolean	Whether results were truncated due to any budget limit
`truncated_reason`	string	Human-readable reason for truncation

Backup File — `tools/backup_file`

Create an explicit snapshot of a file under a hidden backup directory, for later rollback_file restore.

Inputs

Field	Type	Required	Default	Description
`backup_root`	string	—	—	Optional backup root directory
`file_path`	string	✅	—	File path to back up
`label`	string	—	—	Optional label for the backup

Outputs

Field	Type	Description
`backup_id`	string	Unique backup identifier for use with rollback_file
`backup_path`	string	Path to the backup content file
`bytes_copied`	integer	Number of bytes copied to the backup
`error`	string	Error message when the backup failed
`file_path`	string	Canonical source file path that was backed up

Rollback File — `tools/rollback_file`

Restore a file from a snapshot created by backup_file. Atomic write; supports dry_run to preview the diff first. High side-effect.

Inputs

Field	Type	Required	Default	Description
`allow_target_override`	boolean	—	`false`	Allow target path to differ from backup metadata, default false
`backup_id`	string	✅	—	backup_id from backup_file, or "last" to restore the most recent snapshot of the file
`backup_root`	string	—	—	Optional backup root directory
`dry_run`	boolean	✅	—	Preview diff without writing, default false
`file_path`	string	✅	—	File path to restore

Outputs

Field	Type	Description
`backup_id`	string	Backup ID used for restoration
`diff`	string	Diff between current content and backup content
`dry_run`	boolean	Whether this was a dry run
`error`	string	Error message if the operation failed
`file_path`	string	Canonical file path
`restored`	boolean	Whether the file was restored (dry_run=true means restorable)

File Operation Nodes

File Operations Hub — tools/file_ops_hub

Inputs

Outputs

View File — tools/view_file

Inputs

Outputs

Write File — tools/write_file

Inputs

Outputs

Edit File — tools/edit_file

Inputs

Outputs

Patch File — tools/patch_file

Inputs

Outputs

Copy File — tools/copy_file

Inputs

Outputs

Move File — tools/move_file

Inputs

Outputs

Delete File — tools/delete_file

Inputs

Outputs

Diff File — tools/diff_file

Inputs

Outputs

Validate File — tools/validate_file

Inputs

Outputs

File Info — tools/file_info

Inputs

Outputs

File Tree — tools/file_tree

Inputs

Outputs

List Directory — tools/list_directory

Inputs

Outputs

Search Files — tools/search_files

Inputs

Outputs

Backup File — tools/backup_file

Inputs

Outputs

Rollback File — tools/rollback_file

Inputs

Outputs

Next steps

File Operations Hub — `tools/file_ops_hub`

View File — `tools/view_file`

Write File — `tools/write_file`

Edit File — `tools/edit_file`

Patch File — `tools/patch_file`

Copy File — `tools/copy_file`

Move File — `tools/move_file`

Delete File — `tools/delete_file`

Diff File — `tools/diff_file`

Validate File — `tools/validate_file`

File Info — `tools/file_info`

File Tree — `tools/file_tree`

List Directory — `tools/list_directory`

Search Files — `tools/search_files`

Backup File — `tools/backup_file`

Rollback File — `tools/rollback_file`