im.ttalk.agent.tools.files — im.ttalk/clj-agent-tools 0.5.447

文件工具（T-02）：read_file / list_dir / glob / grep / write_file / delete_path。

read_file / list_dir / grep 的口径翻译自 OpenAI Codex CLI（Apache-2.0，Copyright 2025 OpenAI； 见模块根 THIRD-PARTY-NOTICES.md），经 Keelson ReadFileTool.cs / ListDirTool.cs / GrepTool.cs 转写：

• read_file：codex-rs/core/src/tools/handlers/read_file.rs（14c35a16a8^）——offset 缺省 1、limit 缺省 2000、 单行 500 字节、TAB 宽 4、行前缀 L{n}:、slice / indentation 两种模式；
• list_dir：codex-rs/core/src/tools/handlers/list_dir.rs（70807730f5^）——offset 1、limit 25、depth 2、 条目名 500 字节、每层缩进 2 空格；
• grep：codex-rs/core/src/tools/handlers/grep_files.rs（178c3b15b4^）——limit 100、顶 2000、按修改时间倒序。 glob 是 Keelson 新增（Codex 没有）；write_file / delete_path 借鉴 coxswain（Apache-2.0）。

每个工具函数体只读 (ws/current)——工作区由 im.ttalk.agent.tools/workspace-tools 绑定。

binary-probe-bytes clj

commit-plan! clj

(commit-plan! w {:keys [full shown output verdict]})

落盘一个 plan（edit_file / write_file 共用）：语法闸 ⇒ 写前再问策略 ⇒ 原子写 ⇒ 登记新 tag。⇒ 新 tag 提示（或 nil）

delete-path* clj

(delete-path* w args)

delete_path clj

(delete_path {:as args2790 :or {recursive false} :keys [path recursive]})

删除一个文件、目录或符号链接。删东西优先用这件工具，不要用 exec 跑 rm / rm -rf。路径相对于工作目录；非空目录要 recursive=true 才会整棵删掉，不加会报错；不存在的路径直接算成功。符号链接只删链接本身、不跟过去；工作根目录本身不能删；越出工作区的路径会被拒绝。

glob clj

(glob {:as args2692 :or {path nil limit nil} :keys [pattern path limit]})

按 glob 模式找文件（* 不跨目录，** 跨任意层目录，{a,b} 任选其一），按修改时间（新的在前）列出路径。认 .gitignore / .ignore，跳过 .git。

glob* clj

(glob* w {:keys [pattern path limit]})

grep clj

(grep {:as args2740
       :or {include nil path nil limit nil}
       :keys [pattern include path limit]})

找内容匹配正则的文件，按修改时间（新的在前）列出路径（不回匹配行）。认 .gitignore / .ignore，跳过隐藏文件与二进制文件。装了 ripgrep 时用 rg（Rust regex 语法，不支持环视 / 反向引用），否则用 Java regex，逐行匹配。

grep* clj

(grep* w {:keys [pattern include path limit]})

list-dir* clj

(list-dir* w {:keys [dir_path offset limit depth]})

list-indent clj

list-max-entry-bytes clj

list_dir clj

(list_dir {:as args2683
           :or {offset nil limit nil depth nil}
           :keys [dir_path offset limit depth]})

列本地目录的条目（广度优先、按名字排序、子项缩进），带简单的类型标记（目录 /、链接 @、其它 ?）。

plan-delete clj

(plan-delete w {:keys [path recursive]})

路径策略（逃出根的链接按所在目录判）⇒ 根拒删 ⇒ 现状 ⇒ 非空目录要 recursive。无副作用。

plan-write clj

(plan-write w {:keys [path content]})

从参数到「要写下去的字节」的全部判断（无副作用：预览与执行共用）。

preview-delete clj

(preview-delete w args)

preview-write clj

(preview-write w args)

read-default-limit clj

read-file* clj

(read-file* w {:keys [file_path offset limit mode] :as args})

read-max-line-bytes clj

read_file clj

(read_file {:as args2625
            :or {offset nil
                 limit nil
                 mode nil
                 anchor_line nil
                 max_levels nil
                 include_siblings nil
                 include_header nil
                 max_lines nil}
            :keys [file_path offset limit mode anchor_line max_levels
                   include_siblings include_header max_lines]})

读本地文件，每行带从 1 起的行号（「L行号: 」），支持按行切片（slice，缺省）与按缩进取块（indentation）两种模式。大文件用 offset/limit 分页。输出第一行是 [路径#TAG]：之后改这个文件要求读过、且读完没变。

search-default-limit clj

search-max-limit clj

tab-width clj

write-file* clj

(write-file* w args)

write_file clj

(write_file {:as args2762 :or {} :keys [path content]})

把内容整篇写进一个文件（覆盖）。中间不存在的目录会自动创建。覆盖已经存在的文件之前先用 read_file 看一眼 —— 没读过的文件写不进去；新建文件不用先读。改一两处不要用它，用 edit_file：这个工具只用来新建文件或整篇重写。覆盖时文件原来的换行、编码与 BOM 原样保留。