节点手册：文件操作

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：crates/cheng-nodes/src/nodes/builtin/tools/file_ops、crates/cheng-file-ops/src

同一套内核有两种用法。tools/file_ops_hub 把操作作为字段传入，这正是智能体需要的形态 —— 一个节点、多种操作，并且失败时返回结构化信息，说明这次调用能否原样重试。 而单独的节点适合手工绘制的图，此时操作本身就是图的一部分。 写操作会返回回执，说明磁盘上实际改动了什么；当回执表明运行时已校验后置条件时，再读一次来确认写入纯属多余。

文件操作中心 — tools/file_ops_hub

文件操作聚合节点：画布上只需一个节点，通过开关控制 Agent 可用的文件操作能力。

输入

字段	类型	必填	默认值	说明
operation	string	—	""	输入 – 操作
path	string	—	—	文件操作的统一目标路径
sandbox_root	string	—	—	静态沙箱根目录;启用后只能访问该目录及其子目录.
config	object （端口）	—	{"allow_ignored":null,"allow_sensitive":null,...	统一配置对象。LLM 工具调用时直接传 JSON 对象，不要传 JSON 字符串。 连接端口，不是表单字段。 控件：text
allow_read_info	boolean	✅	true	是否允许获取文件元信息(只读). 控件：switch
allow_read_content	boolean	✅	true	是否允许读取文件内容(只读). 控件：switch
allow_list_directory	boolean	✅	true	是否允许列出目录(只读). 控件：switch
allow_search	boolean	✅	true	是否允许搜索文件内容(只读). 控件：switch
allow_file_tree	boolean	✅	true	是否允许渲染仓库文件树快照(只读). 控件：switch
allow_diff	boolean	✅	true	是否允许生成 diff(只读). 控件：switch
allow_validate	boolean	✅	true	是否允许 JSON/YAML 校验(只读). 控件：switch
allow_write	boolean	✅	true	是否允许写入/创建文件(中副作用). 控件：switch
allow_edit	boolean	✅	true	是否允许精确编辑文件(中副作用). 控件：switch
allow_patch	boolean	✅	true	是否允许 JSON/YAML 路径级补丁(中度副作用). 控件：switch
allow_copy	boolean	✅	true	是否允许复制文件/目录(中度副作用). 控件：switch
allow_backup	boolean	✅	true	是否允许创建快照(中度副作用). 控件：switch
allow_move	boolean	✅	true	是否允许移动/重命名(高副作用,会移除源). 控件：switch
allow_rollback	boolean	✅	true	是否允许从快照回滚(高副作用,覆盖). 控件：switch
allow_delete	boolean	✅	true	是否允许删除文件(高副作用,不可逆). 控件：switch
allow_batch	boolean	✅	true	是否允许批量操作(混合副作用,逐项二次校验). 控件：switch
require_approval	boolean	✅	true	变更操作执行前是否需要用户审批. 控件：switch

输出

字段	类型	说明
operation	string	实际执行的操作类型
summary	string	操作摘要，用于快速读取顶层结果
error_kind	string	机器可读的错误类型，如 operation_not_enabled / invalid_operation
terminal	boolean	为 true 表示重试相同操作或切换入口点无法恢复；需要更改配置或方法
enabled_operations	array<string>	当前节点配置启用的操作列表
disabled_operations	array<string>	当前节点配置禁用的操作列表
error	string	错误信息(操作被禁止或执行失败)
result	any	操作结果(JSON 序列化的子工具输出)
correct_call	any	该操作的一次合法调用,以结构化 JSON 给出,可直接照抄
error_field	string	出错字段的调用侧路径(例如 config.content),使纠正只针对某一个参数而不是整次调用
mutation_receipt	object	本次变更在磁盘上实际改动了什么的权威记录。self_verified=true 表示运行时已重新读取目标并确认后置条件成立,因此无需再读一次来验证写入。只读操作没有该字段
mutation_receipts	array<object>	batch_file_ops 中每个子操作的回执,按执行顺序排列。即使批处理失败也会存在,因为先执行的子操作可能已经落盘
mutation_summary	string	变更回执的一行摘要:改了什么、是否已在磁盘上验证
retry_disposition	string	取值为 retry_same_call、retry_after_correction、do_not_retry 之一。它回答的是本次调用能否原样重发 —— 与 terminal 不同,后者回答的是方案或配置是否必须改变
suggested_action	string	稳定的下一步动作标识(例如 use_file_tree、correct_source_path),调用方无需解析自然语言
workspace_delta	object	本次操作带来的路径级增量变化。用它更新你对工作区的认知,而不必在编辑后重跑 file_tree

查看文件 — tools/view_file

按指定行范围读取文件内容。四种互斥模式：line（start_line/end_line）、tail（tail_lines）、byte（offset_bytes/limit_bytes）、char（offset_chars/limit_chars）。始终返回 total_lines 和 eof 标记，帮助 LLM 感知文件全貌并防止幻觉。line 模式单次最多 500 行且受字符预算约束；还有内容时响应会给出唯一的续读游标与 truncated_reason。不填任何范围参数时，超过 500 行的文件只返回前 200 行结构预览（truncated_reason=large_file_preview），应先用 search_files 定位再精读。

输入

字段	类型	必填	默认值	说明
end_line	integer	—	—	结束行号（含），默认 min(start_line+499, total_lines)
file_path	string	✅	—	输入 – 文件路径
known_modified_at	string	—	—	调用方上次观察到的修改时间(RFC 3339)。仅作提示 —— 时间戳粒度粗或相等都不能证明内容未变。
known_sha256	string	—	—	调用方已观察到的整文件 SHA-256。若与磁盘上仍然一致,响应只返回紧凑的 file_unchanged 标记而不是文件内容。
known_size	integer	—	—	调用方上次观察到的大小。仅作提示,用于在大小已不同的情况下跳过哈希计算;绝不能作为内容相同的证明。
limit_bytes	integer	—	—	字节模式下读取的最大字节数,上限为 1 MiB.
limit_chars	integer	—	—	字符模式下读取的最大字符数(输出仍上限为 1 MiB).
offset_bytes	integer	—	—	字节偏移量(启用字节模式,从 0 开始).必须落在 UTF-8 边界上.
offset_chars	integer	—	—	字符偏移量(启用字符模式,从 0 开始).
start_line	integer	—	—	LINE 模式。起始行号（1-indexed），默认 1。与 tail_lines、byte 模式、char 模式互斥。续读被截断的结果时，把响应里的 next_start_line 填到这里。注意：完全不填任何范围参数时，超过 500 行的文件只返回前 200 行结构预览（truncated_reason=large_file_preview）。
tail_lines	integer	—	—	一次调用返回文件最后 N 行（无需知道文件长度）。与 start_line/end_line 和字节/字符偏移模式互斥。上限 500 显示行（保留最近的行）。

输出

字段	类型	说明
content	string	带行号前缀的文件内容(格式:” 42 内容”)
encoding	string	编码(固定 “utf-8”)
end_line	integer	输入 – End Line
eof	boolean	是否已到达文件末尾
error	string	错误信息（存在时其他字段为空/零）
file_path	string	输入 – 文件路径
file_unchanged	boolean	调用方提供的摘要仍然描述该文件,因此没有重复发送内容。
mode	string	读取模式: “line” \
next_offset_bytes	integer	字节模式的续读游标:下次调用时作为 offset_bytes 传入。始终位于合法的 UTF-8 边界;读到文件末尾时不返回
next_offset_chars	integer	字符模式的续读游标:下次调用时作为 offset_chars 传入。当 truncated_reason=line_too_long 时也用它,此时字符模式是唯一能推进的方式;读到文件末尾时不返回
next_start_line	integer	行模式的续读游标:下次调用时作为 start_line 传入。仅在按行边界截断时出现;读到文件末尾时不返回
offset_bytes	integer	字节模式: 实际起始字节偏移
offset_chars	integer	字符模式: 实际起始字符偏移
requested_tail_lines	integer	请求的尾部行数（仅尾部读取；实际范围在 start_line/end_line 中）
sha256	string	当前整文件的 SHA-256,用于条件读取时刷新调用方的观察值。
shown_bytes	integer	字节/字符模式: 实际返回的字节数
shown_chars	integer	字符模式: 实际返回的字符数
start_line	integer	输入 – 启动 Line
total_bytes	integer	输入 – 总数 Bytes
total_chars	integer	字符模式: 文件总字符数
total_lines	integer	总行数（字节/字符模式下也会计算）
truncated	boolean	是否因超出 500 行上限而截断
truncated_reason	string	输出被截断的原因:max_lines、max_output_chars、byte_limit、char_limit、line_too_long 或 large_file_preview。请与对应的 next_* 游标一起看。large_file_preview 表示对长文件没有指定范围,因此只返回了开头的结构预览 —— 此时应当用 search_files 定位目标区域,而不是整篇翻页

写入文件 — tools/write_file

创建新文件或覆写/追加已有文件。使用原子写入（临时文件 + 重命名）防止写入中断导致文件损坏。

输入

字段	类型	必填	默认值	说明
file_path	string	✅	—	输入 – 文件路径
content	string	✅	—	输入 – 内容
content_artifact	object	—	null	要写入目标路径的工件（优先于内联内容）
content_artifact_uri	string	—	null	要写入内容的 artifact:// URI
source_encoding	string	—	null	utf-8\
overwrite	boolean	—	false	是否允许覆写已有文件，默认 false
force_overwrite	boolean	—	false	强制覆写：跳过 expected_sha256 确认往返并隐含覆写已有文件，默认 false。备份默认仍开启以保留恢复能力
create_dirs	boolean	—	true	是否自动创建父目录，默认 true
append	boolean	—	false	追加模式（优先于覆写），默认 false
dry_run	boolean	—	false	预览写入（diff + current_sha256），无任何副作用，默认 false
expected_sha256	string	—	—	覆写已有文件的确认保护：预览/读取时观察到的当前文件内容的十六进制 SHA-256。覆写已有文件时必填；不匹配当前文件哈希时拒绝写入
allow_ignored	boolean	—	null	允许写入被 .gitignore/.ignore 匹配的路径。默认 false 阻止此类目标。
allow_sensitive	boolean	—	null	允许写入敏感路径（.env、私钥、凭证）。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录
create_backup	boolean	—	null	覆写/追加已有文件前创建可恢复快照。真实修改时默认为 true；演练模式或新文件时不会创建

输出

字段	类型	说明
backup_id	string	备份 ID（create_backup=true 且覆写/追加已有文件时）
bytes_written	integer	输入 – Bytes Written
created	boolean	true=新建文件,false=覆写或追加
current_sha256	string	当前文件内容的 SHA-256（既有可读文件时填充）。覆写时作为 expected_sha256 回传。
diff	string	Unified diff（覆写/追加已有文本文件时填充；diff 生成失败时为 None）
dry_run	boolean	是否为演练模式
error	string	输入 – 错误
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	写入结果摘要(适合直接传给 LLM / Preview 节点)
verification_error	string	自校验失败或跳过的原因。

编辑文件 — tools/edit_file

通过精确内容匹配/替换编辑文件。支持多个替换操作；全部成功后原子写入；任何失败保持原文件不变。

输入

字段	类型	必填	默认值	说明
allow_ignored	boolean	—	null	允许编辑被 .gitignore/.ignore 匹配的路径。默认 false 阻止此类目标。
allow_sensitive	boolean	—	null	允许编辑敏感路径（.env、私钥、凭证）。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录；默认在目标文件旁边
confusable_fallback	boolean	—	null	精确匹配失败时，归一化少量视觉混淆字符（智能引号、en/em 破折号、不间断空格、部分全宽标点）为 ASCII 后重试。默认 false。始终先尝试精确匹配。
create_backup	boolean	—	null	写入前创建可恢复快照。真实修改时默认为 true；演练模式时不会创建。传 false 可 opt out
dry_run	boolean	—	false	校验并预览 diff，不写入文件，默认 false
expected_sha256	string	—	—	可选的丢失更新保护：上次读取时文件内容的十六进制 SHA-256；当前文件哈希不匹配时拒绝编辑
file_path	string	✅	—	输入 – 文件路径
force_overwrite	boolean	—	false	强制写入快速路径：跳过 expected_sha256 丢失更新保护，默认 false。备份默认仍开启
ignore_whitespace	boolean	—	null	精确匹配失败时，比较空白归一化形式后重试（折叠空格/制表符序列，忽略行首缩进和行尾空白；换行仍有效）。仅在恰好只有一个归一化候选时生效；多个候选则以 ambiguous_whitespace_match 失败。默认 false；始终先尝试精确匹配。
max_diagnostic_candidates	integer	—	—	失败诊断中返回的最大相似候选数，默认 3
replace_all	boolean	—	null	替换所选范围内的所有匹配项。默认 false 保持 require_unique_match 安全模型。建议先用 dry_run 测试广泛的 replace_all 编辑。
replacements	array<object>	—	—	替换操作列表（按顺序执行）。可直接提供数组或 JSON 字符串。
replacements_json	string	—	—	替代方式：以 JSON 字符串提供替换内容（如 ‘{“old_content”:”…”,”new_content”:”…”}’）。提供时覆盖 replacements 字段。
require_unique_match	boolean	—	—	要求每次替换唯一匹配，默认 true。为 false 时，多个匹配替换第一个匹配项。
return_diff	boolean	—	—	返回已更改文件和演练模式的 unified diff，默认 true
snippet_context_lines	integer	—	—	返回代码片段中每个更改范围周围的上下文行数。默认 3。

输出

字段	类型	说明
applied_count	integer	输入 – 已应用数量
backup_id	string	备份 ID（create_backup=true 且成功写入时）
changed	boolean	文件内容是否已更改
diagnostics	array<object>	失败诊断信息
diff	string	更改的 unified diff（return_diff 或 dry_run 时填充）
dry_run	boolean	是否为演练模式
error	string	错误信息（首次替换失败即停止；文件保持不变）
file_path	string	输入 – 文件路径
match_mode	string	匹配模式：exact \
replacement_occurrences	integer	实际替换的匹配次数（replace_all 时可大于 applied_count）
snippets	array<object>	每个修改范围周围的更改代码片段（含行号，成功或演练模式时返回）
total_lines_after	integer	输入 – 总数 Lines After
total_lines_before	integer	输入 – 总数 Lines Before
used_confusable_fallback	boolean	是否使用了视觉混淆字符归一化回退匹配

补丁文件 — tools/patch_file

对 JSON 或 YAML 文件应用 JSON 指针路径级别的补丁(set/remove/append/insert/replace).原子操作:在写入前在内存中验证所有补丁.支持 dry_run.

输入

字段	类型	必填	默认值	说明
allow_ignored	boolean	—	—	允许补丁被 .gitignore/.ignore 匹配的路径。默认 false 阻止此类目标。
allow_sensitive	boolean	—	—	允许补丁敏感路径（.env、密钥、凭证）。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录
content	string	—	—	整文件替换内容。提供时忽略补丁。
create_backup	boolean	—	—	写入前创建可恢复快照。真实修改时默认为 true；演练模式时不会创建。传 false 可 opt out
dry_run	boolean	✅	—	预览差异而不写入,默认值为 false
file_path	string	✅	—	目标 JSON/YAML 文件路径
format	string	—	—	格式: auto \
patches	array<object>	—	—	按顺序应用的补丁列表

输出

字段	类型	说明
backup_id	string	备份 ID（create_backup=true 且成功写入时）
changed	boolean	文件内容是否发生变化
diff	string	变更的统一 diff
dry_run	boolean	是否为演练模式
error	string	错误信息
error_details	array<object>	补丁级失败详情（patch_index/op/path/message）
file_path	string	规范化后的文件路径
format	string	实际使用的格式
patches_applied	integer	成功应用的补丁数
validation_after_patch	object	补丁后序列化结果的格式校验（确认仍可解析）

复制文件 — tools/copy_file

复制文件或目录到新位置.内容先复制到临时暂存路径,然后原子性地重命名到位(现有目标保留直到交换成功).目录需要 recursive=true.除非 overwrite=true 否则拒绝覆盖.

输入

字段	类型	必填	默认值	说明
allow_ignored	boolean	—	null	允许复制到被 .gitignore/.ignore 匹配的目标路径。默认 false 阻止此类目标。
allow_sensitive	boolean	—	null	允许复制到敏感目标（.env、密钥、凭证）。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录
create_backup	boolean	—	null	覆写已有目标文件前创建可恢复快照。真实覆写时默认为 true；演练模式或新建目标时不会创建
create_dirs	boolean	—	true	是否自动创建目标父目录,默认值为 true
destination_path	string	✅	—	目标路径
dry_run	boolean	—	false	预览复制操作（校验 + 创建/覆写报告），无任何副作用，默认 false
overwrite	boolean	—	false	是否允许覆盖已存在的目标,默认值为 false
recursive	boolean	—	false	复制目录时必须为 true,默认值为 false
source_path	string	✅	—	源文件或目录路径

输出

字段	类型	说明
backup_id	string	覆写前目标文件快照的备份 ID（仅覆写已有目标文件时；dry_run / 新建为 None）
bytes_copied	integer	复制的字节数(目录为聚合值)
created	boolean	true表示目标为新建,false表示覆写
destination_path	string	规范化后的目标路径
dry_run	boolean	是否为演练模式
error	string	错误信息
is_dir	boolean	源是否为目录
overwritten	boolean	是否覆盖了已有目标
source_path	string	规范化后的源路径
summary	string	操作结果摘要

移动文件 — tools/move_file

移动或重命名文件或目录.优先进行原子重命名;跨文件系统时回退为先复制后删除(仅在完全成功复制后才删除源).

输入

字段	类型	必填	默认值	说明
allow_ignored	boolean	—	null	允许源或目标被 .gitignore/.ignore 匹配时移动。默认 false 阻止。
allow_sensitive	boolean	—	null	允许源或目标为敏感路径时移动。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录
create_backup	boolean	—	null	移动覆写已有目标文件前创建可恢复快照。真实覆写时默认为 true；演练模式或新建目标时不会创建
create_dirs	boolean	—	true	是否自动创建目标父目录,默认值为 true
destination_path	string	✅	—	目标路径
dry_run	boolean	—	false	预览移动操作（校验 + 覆写报告），无任何副作用，默认 false
overwrite	boolean	—	false	是否允许覆盖已存在的目标,默认值为 false
source_path	string	✅	—	源文件或目录路径

输出

字段	类型	说明
backup_id	string	覆写前目标文件快照的备份 ID（destination overwrite backup：仅覆写已有 目标文件时创建；dry_run / 新建目标为 None）
destination_path	string	规范化后的目标路径
dry_run	boolean	是否为演练模式
error	string	错误信息
moved	boolean	是否成功移动
overwritten	boolean	是否覆盖了已有目标
source_path	string	规范化后的源路径
summary	string	操作结果摘要

删除文件 — tools/delete_file

删除文件（高副作用，不可逆）。仅允许删除文件，不允许删除目录。支持 dry_run 演练模式。

输入

字段	类型	必填	默认值	说明
allow_ignored	boolean	—	null	允许删除被 .gitignore/.ignore 匹配的路径（如生成产物）。需明确意图；默认 false 阻止。
allow_sensitive	boolean	—	null	允许删除敏感路径（.env、密钥、凭证）。通常需要审批；默认 false 阻止。
backup_label	string	—	—	备份的可选标签
backup_root	string	—	—	可选的备份根目录
create_backup	boolean	—	null	删除文件前创建可恢复快照。真实删除时默认为 true；演练模式时不会创建
dry_run	boolean	—	false	演练模式（仅校验，不实际删除），默认 false
file_path	string	✅	—	输入 – 文件路径

输出

字段	类型	说明
backup_id	string	删除前快照的备份 ID（可用 rollback_file 恢复；dry_run / 未删除时为 None）
deleted	boolean	true=成功删除(dry_run=true 时表示”可以删除”)
dry_run	boolean	输入 – 模拟运行
error	string	输入 – 错误
file_path	string	输入 – 文件路径
file_size_bytes	integer	输入 – 文件大小 Bytes

差异对比 — tools/diff_file

生成两个文件之间,或文件与建议的新内容之间的统一 diff 差异.只读操作.

输入

字段	类型	必填	默认值	说明
compare_path	string	—	—	用于对比的目标文件
context_lines	integer	—	—	上下文行数,默认值为 3
file_path	string	✅	—	基准文件路径
new_content	string	—	—	用于对比的建议新内容

输出

字段	类型	说明
added_lines	integer	新增行数
compare_path	string	对比文件路径(文件对内容模式下为 null)
diff	string	统一 diff 文本
error	string	错误信息
file_path	string	规范化后的基准文件路径
has_changes	boolean	是否存在差异
removed_lines	integer	删除行数
truncated	boolean	diff 是否因超过输出上限而被截断

验证文件 — tools/validate_file

验证文件的内容(或内联内容)是否为格式良好的 JSON 或 YAML.只读操作.

输入

字段	类型	必填	默认值	说明
content	string	—	—	要验证的内联内容
file_path	string	—	—	要验证的文件路径
format	string	—	—	格式: auto \

输出

字段	类型	说明
column	integer	错误所在的列(当解析器提供时)
error	string	节点级错误(路径解析/读取失败等)
error_message	string	校验失败时的错误信息
file_path	string	规范化后的文件路径(内联内容时为空)
format	string	实际使用的格式(“json” \
line	integer	错误所在的行(当解析器提供时)
summary	string	结果摘要
valid	boolean	内容是否合法

文件信息 — tools/file_info

获取文件/目录元数据(大小,行数,修改时间,二进制检测)

输入

字段	类型	必填	默认值	说明
path	string	✅	—	输入 – 路径

输出

字段	类型	说明
created	string	创建时间(ISO 8601,部分 OS 不支持则为 None)
entry_type	enum	输入 – Entry 类型. 取值：file, dir, symlink
error	string	输入 – 错误
exists	boolean	路径是否存在
is_binary	boolean	输入 – Is Binary
is_readable	boolean	当前进程是否有读权限
is_writable	boolean	当前进程是否有写权限
metadata	string	所有元信息的聚合摘要(适合直接传给 LLM / Preview 节点)
mime_type	string	推断的 MIME 类型（如 text/x-rust, text/plain）
modified	string	修改时间(ISO 8601)
path	string	规范化后的绝对路径
size_bytes	integer	输入 – 大小 Bytes
total_lines	integer	文本文件的总行数；二进制或目录为 None

文件树 — tools/file_tree

渲染字符预算受限的仓库目录树快照，附带结构化统计。遵守 .gitignore，不跟随符号链接。适合冷启动时快速了解项目结构。

输入

字段	类型	必填	默认值	说明
exclude_patterns	array	—	—	Gitignore 风格的排除 glob；如 [“target/**”] 会同时隐藏 target/ 目录及其全部后代，未命中的真实空目录仍会保留。
include_patterns	array	—	—	Gitignore 风格的条目 glob 白名单；[“.rs”] 保留 Rust 文件，[“/”] 只匹配目录并生成纯目录视图。
include_stats	boolean	—	—	是否计算 extension_stats 和 largest_dirs，默认 false
max_chars	integer	—	—	树字符串的字符预算。默认 20000，硬上限 200000。
max_depth	integer	—	—	深度约定：root 为深度 0；max_depth=1 只渲染 root 的直接子条目，max_depth=2 再加一层，以此类推。默认 64，硬上限 256。
max_file_size	integer	—	—	超过此大小（字节）的文件从树中省略（仍计入扫描）。None=不限制。
max_scan_ms	integer	—	—	扫描的墙钟时间预算（毫秒）。默认 5000，硬上限 60000。
max_scanned_files	integer	—	—	遍历时访问的文件系统条目上限。默认 20000。
offset	integer	—	—	确定性树条目的续读偏移（不含每页重复显示的 root 行）。响应返回 next_offset 时，保持其余参数不变并将其传入 offset。
root_path	string	✅	—	要快照的根目录（必须是目录，不是文件）
show_hidden	boolean	—	false	是否包含以 . 开头的隐藏文件/目录，默认 false
stats_scope	enum	—	—	统计范围：’rendered’（廉价）或 ‘scanned’（可越过渲染预算继续遍历）。默认 rendered。 取值：rendered, scanned

输出

字段	类型	说明
elapsed_ms	integer	操作耗时（毫秒）
error	string	操作失败时的错误信息
extension_stats	array<object>	按扩展名的文件数和大小统计（include_stats=true 时填充）
largest_dirs	array<object>	按递归文件数排列的最大目录（include_stats=true 时填充）
next_offset	integer	max_chars 截断且本页已有条目时的续读偏移；保持其他参数不变并作为 offset 传入。到达末尾或本页无法容纳任何条目时为空。
omitted_entries	integer	从树中省略的条目数（scanned_total – rendered_total）
rendered_dirs	integer	出现在树字符串中的目录数（含 root）
rendered_files	integer	出现在树字符串中的文件数
root_path	string	规范化后的根目录路径
scan_cancelled	boolean	文件系统扫描是否因 max_scan_ms 被取消
scan_truncated	boolean	文件系统扫描是否因 max_scanned_files 被截断
scanned_dirs	integer	遍历统计到的目录数（含 root，按 stats_scope）
scanned_files	integer	遍历统计到的文件数（按 stats_scope）
snapshot_fingerprint	string	所渲染结构的稳定指纹;指纹相同即表示调用方缓存的目录树仍然有效。
stats_complete	boolean	统计是否完整（扫描未被截断/取消时为 true）
stats_scope	enum	本次结果实际使用的统计范围：rendered 或 scanned；回显输入值，未提供时为 rendered。 取值：rendered, scanned
tree	string	渲染的目录树字符串（字符预算受限）
truncated	boolean	树是否因 max_chars 或 max_depth 被截断
truncated_reason	string	截断或取消的人类可读原因

列出目录 — tools/list_directory

列出目录内容，返回结构化条目列表。支持 glob 过滤、递归深度控制和偏移分页。

输入

字段	类型	必填	默认值	说明
directory_path	string	✅	—	输入 – Directory 路径
max_depth	integer	—	—	递归深度（0=仅目录本身，1=直接子项）。默认 1，最大 5。
offset	integer	—	0	匹配条目的分页偏移量，默认 0
page_size	integer	—	—	每页返回的条目数，默认 50，最大 200
pattern	string	—	—	文件名 glob 过滤（如 “*.rs”），仅匹配文件名，不匹配完整路径
show_hidden	boolean	—	false	是否显示隐藏文件/目录（以 . 开头），默认 false
verbose	boolean	—	false	为 true 时返回每个条目的完整元数据（absolute_path、modified、is_binary）。默认 false 只返回 name/relative_path/entry_type/size_bytes/depth，浏览目录开销更低；确实需要修改时间、二进制判断或绝对路径时才设为 true。

输出

字段	类型	说明
directory_path	string	输入 – Directory 路径
elapsed_ms	integer	输入 – 已用时间 Ms
entries	array<object>	目录条目列表(按 name 字母序排列)
error	string	输入 – 错误
next_offset	integer	下一页偏移量；无更多条目时为 None
offset	integer	当前分页偏移量
page_size	integer	当前每页大小
returned_entries	integer	本页实际返回条目数
total_entries	integer	输入 – 总数 Entries
truncated	boolean	是否可通过 offset=next_offset 获取更多条目

搜索文件 — tools/search_files

在文件或目录中搜索文本，类似 grep，返回结构化匹配结果。支持正则、大小写不敏感、glob 过滤和上下文行。

输入

字段	类型	必填	默认值	说明
case_insensitive	boolean	—	false	输入 – Case Insensitive
context_lines	integer	—	—	每个匹配前后显示 N 行上下文（0-3），默认 0（仅 content 模式）
exclude_patterns	array	—	—	排除文件名 glob 列表（如 [“*.bak”, “target/**”]）
file_types	array	—	—	语言类型过滤（如 [“rust”,”ts”]）；展开为常见扩展名 glob。支持：rust, js, ts, py, go, java, kt, md, json, yaml, toml, c, cpp, rb, sh
include_patterns	array	—	—	文件名 glob 过滤列表（如 [“.rs”, “.toml”]），仅搜索匹配文件
is_regex	boolean	—	false	query 是否为正则表达式，默认 false
max_files	integer	—	—	files_with_matches 模式：最大返回文件数，默认 500，硬上限 5000
max_match_span_bytes	integer	—	—	multiline：跳过跨度过大的匹配（字节数）
max_match_span_lines	integer	—	—	multiline：跳过跨度过大的匹配（行数）
max_results	integer	—	—	content 模式：最大返回匹配数，默认 200，硬上限 1000
max_scanned_bytes	integer	—	—	扫描总文本字节上限，默认 256MB
max_scanned_files	integer	—	—	打开/搜索文件数上限，默认 50000
multiline	boolean	—	false	对完整文件文本（跨行）求值正则，默认 false
output_mode	enum	—	—	输出模式：content（默认，返回匹配行）、files_with_matches（仅文件路径 + 计数）、count（仅计数）
query	string	✅	—	输入 – 查询
search_path	string	✅	—	搜索起始路径（文件或目录的绝对路径）
timeout_ms	integer	—	—	multiline：挂钟超时（毫秒），默认 5000，硬上限 30000

输出

字段	类型	说明
elapsed_ms	integer	输入 – 已用时间 Ms
error	string	输入 – 错误
file_match_counts	array<object>	每文件匹配计数（files_with_matches / count 模式）
files_with_matches	array<string>	包含匹配的文件路径列表（files_with_matches 模式）
matched_files	integer	有匹配的文件数量
matches	array<object>	匹配结果列表(按文件路径 + 行号升序)
searched_files	integer	输入 – Searched Files
total_matches	integer	返回的匹配数（content 模式：返回条目数；其他模式：总命中数）
truncated	boolean	是否因达到 max_results 上限而截断
truncated_reason	string	截断原因的可读说明

备份文件 — tools/backup_file

在隐藏备份目录下创建文件的显式快照,以便稍后使用 rollback_file 恢复.

输入

字段	类型	必填	默认值	说明
backup_root	string	—	—	可选的备份根目录
file_path	string	✅	—	要备份的文件路径
label	string	—	—	备份的可选标签

输出

字段	类型	说明
backup_id	string	备份 ID(用于 rollback_file)
backup_path	string	备份内容文件路径
bytes_copied	integer	备份的字节数
error	string	错误信息
file_path	string	规范化的源文件路径

回滚文件 — tools/rollback_file

从由 backup_file 创建的快照恢复文件.原子写入;支持 dry_run 以先预览 diff.高副作用.

输入

字段	类型	必填	默认值	说明
allow_target_override	boolean	—	false	是否允许目标路径与备份元数据不同,默认值为 false
backup_id	string	✅	—	来自 backup_file 的 backup_id，或 “last” 恢复该文件的最近快照
backup_root	string	—	—	可选的备份根目录
dry_run	boolean	✅	—	仅预览差异而不写入,默认值为 false
file_path	string	✅	—	要恢复的文件路径

输出

字段	类型	说明
backup_id	string	使用的备份 ID
diff	string	当前内容 -> 备份内容的 diff 差异
dry_run	boolean	是否为演练模式
error	string	错误信息
file_path	string	规范化的文件路径
restored	boolean	是否已恢复(dry_run=true 时表示「可恢复」)

下一步

• 工作区工具节点
• 代码执行节点
• 使用 CLI