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

工作区：路径策略 + 文件层 + 每实例状态（设计：designs/tools-module.md §3 §4）。

• IPathPolicy：每个路径碰之前都问它。缺省 workspace-policy——可写根、只读根、 受保护名（.git .agents .codex .aws，照 Codex PROTECTED_METADATA_PATH_NAMES）， 判定在字面（.. 已折叠）与解链接后两个口径上都做（出处 Keelson WorkspacePathPolicy.cs）。
• IFileLayer：读写类工具只经它碰文件（出处 Keelson FileLayer.cs），缺省 local-file-layer——原子写（同目录临时文件 + ATOMIC_MOVE）、写解链接后的真实路径。
• workspace：把选项收成一个 ws map；*workspace* 由 im.ttalk.agent.tools/workspace-tools 造的匿名 var 在工具函数体内部绑定（与引擎 / 线程无关，见 design-principles §3）。

业务失败一律 fail!：抛 ex-info，ex-data 带 :error-class :semantic 与 :code， tool/invoke 把它变成给模型的「错误: …」。

*workspace* clj

当前工具调用的工作区。只由 workspace-tools 造的匿名 var 在函数体内部 binding。

->path clj

(->path x)

atomic-write! clj

(atomic-write! p data)

原子写：同目录临时文件 → ATOMIC_MOVE（不支持时退回 REPLACE_EXISTING）。 写的是解链接后的真实路径（链接指向的文件被更新，链接本身保留）；保留原文件 POSIX 权限。

canonical clj

(canonical p)

逐段解开已存在的符号链接（含悬空链接：按其目标继续解），回解完的绝对路径； 链接成环（超过 40 跳）⇒ nil。不存在的尾段原样拼上。p 须是绝对、已 normalize。

check! clj

(check! ws full access)

问策略；拒绝 ⇒ fail!（码 = 策略的码）。

current clj

(current)

当前工作区；没绑定 ⇒ 抛（直接调用 deftool var 而没经 workspace-tools）。

default-protected-names clj

可写根下这些顶层目录只读（Codex permissions.rs PROTECTED_METADATA_PATH_NAMES）。

deny clj

(deny ws full access)

问策略；拒绝 ⇒ 理由 map，放行 ⇒ nil。

directory? clj

(directory? p)

entry-of clj

(entry-of p)

NIO 取一项（不跟随链接）。

exists-no-follow? clj

(exists-no-follow? p)

fail! clj

(fail! code msg)

(fail! code msg data)

业务失败（模型改参数即可）：抛 ex-info，:code 给宿主按码判别（⛔ 比对文案）。

failure-code clj

(failure-code e)

从 ex-info 取错误码；不是本模块的失败 ⇒ nil。

IFileLayer clj protocol

delete! clj

(delete! layer path recursive?)

删文件或目录（recursive? 才删非空目录；链接只删链接本身）；不存在不算错。

entry clj

(entry layer path)

一项的现状；不存在 ⇒ nil。符号链接本身是 :link（⛔ 跟随）。 {:kind :file|:dir|:link|:other :size n :mtime ms :link-target str}

open-in clj

(open-in layer path)

读打开（跟随链接）。不存在 ⇒ NoSuchFileException。

write-bytes! clj

(write-bytes! layer path bytes)

整份写入：原子，父目录不存在就建。

IPathPolicy clj protocol

check-path clj

(check-path policy full-path access)

full-path：绝对、已 normalize 的 Path；access ∈ :read / :write。 放行 ⇒ nil；拒绝 ⇒ {:code "workspace/…" :message "…"}。

link? clj

(link? p)

local-file-layer clj

(local-file-layer)

缺省文件层：直接经本机文件系统。

read-all-bytes clj

(read-all-bytes layer path)

经文件层读全部字节。

real clj

(real full)

解链接后的路径（已读表的键：同一个文件经不同写法 / 链接访问是同一条）；成环 ⇒ 原样。

resolve! clj

(resolve! ws path arg-name access)

(resolve! ws path arg-name access allow-empty?)

解析 + 问策略；失败 ⇒ fail!。

resolve-path clj

(resolve-path ws path arg-name)

(resolve-path ws path arg-name allow-empty?)

解析模型给的路径：相对 ⇒ 按 :cwd；空 ⇒ :cwd 本身（allow-empty?）。返回绝对、已 normalize 的 Path （不问策略；问策略用 resolve!）。解析不了 ⇒ fail!。

root-like? clj

(root-like? ws full)

文件系统根、工作目录、策略的根（可写 / 只读）以及它们的祖先——删了就是把工作区整个端掉。

shown clj

(shown raw full)

报错里给模型看的路径：它自己传的那个（空则完整路径）。

target-entry clj

(target-entry ws full)

一项的现状，链接则看它指向的那一项（悬空链接 ⇒ nil）。

unrestricted-policy clj

(unrestricted-policy)

不设限的策略——确实不限时显式给它（⛔ 静默缺省）。

workspace clj

(workspace opts)

把选项收成工作区 map（workspace-tools 调它；宿主也可先建好再传，便于审批预览共用）。

选项：

• :root / :roots 可写根（绝对路径）。给了 :policy 时可省
• :read-only-roots 只读根
• :protected-names 受保护名（缺省 .git .agents .codex .aws）
• :policy 自带 IPathPolicy（给了就不用 :root 造缺省策略）
• :cwd 相对路径的基目录；缺省第一个可写根；显式 nil ⇒ 只收绝对路径
• :file-layer IFileLayer（缺省 local-file-layer）
• :read-tracking? 读写新鲜度闸（缺省 true）
• :reads 已读表（freshness/read-table）；缺省每个工作区一张
• :syntax 语法闸 {:enabled? true :checkers [...]}（追加在内置前面）
• :grep {:rg :auto|false|"/path/to/rg" :max-file-bytes n :regex-timeout-ms n}
• :exec / :web-fetch / :skills / :notes 各工具组的选项（见对应 ns）

workspace-policy clj

(workspace-policy roots)

(workspace-policy roots
                  {:keys [read-only-roots protected-names]
                   :or {protected-names default-protected-names}})

工作区路径策略。roots：可读可写的根（绝对路径，至少一个）。 opts：:read-only-roots（只读根）、:protected-names（缺省 default-protected-names）。