kb26

7分钟阅读

date: 2026-06-11 tags:

  • inbox
  • project/cli-agent
  • type/topic public: true

工具优化

讨论目标：确认 local-system 文件工具的封装边界：哪些工具值得保留为强封装，哪些能力应该降级为 prompt guidance，让 agent 使用 find、fd、rg 等 shell 原语完成。

local-system 工具采用分析报告

报告使用 2026-05-27 的 88 条完整 LH trace。LLM judge 从 trace chunk 中识别意图闭环、动作功能和工具簇，再聚合采用率、切换率和切换后的工具惯性。

当前关键结果：

  • local-system 专用文件操作占所有操作 38.7% 。
  • 范围内操作中，LH 专用工具采用率 70.1%。
  • 按功能看，file_write、file_edit、file_read 的 LH 采用率较高 69%。
  • listing 的 LH 采用率为 37.1%，path_search 为 29.3%。

讨论：

  1. listing / path_search 的低采用率说明工具封装不够好，还是 agent 在代码仓库里更信任 shell 原语？
  2. readFile / grepContent 的 fallback 来自能力缺口、结果文案、错误恢复成本，还是单纯的使用惯性。

listing / path_search / grepContent

讨论： 强封装 vs 弱封装。

  • 强封装： API 对 Shell 命令 / lib 封装程度高，对 Agent 使用 Shell 平替的禁止程度高
  • 弱封装： 不提供 API 封装， Agent 在指引或不指引下使用 Shell 命令

listing

LH

LH 现在把 listing 做成强封装工具 listFiles。工具入参面向目录浏览，不面向搜索：

  • path：必填目录路径。
  • limit：默认 100。
  • sortBy：默认 modifiedTime，可选 name / modifiedTime / createdTime / size。
  • sortOrder：默认 desc。

system prompt 要求 agent “列目录时用 listFiles”，并告诉 agent 结果包含文件名、大小、修改时间，系统文件会自动过滤。

Claude Code, Codex, Open Code 没有把普通 listing 单独做成核心搜索工具。

方案判断

listing 可以从强封装工具降级为 prompt guidance。保留强封装的收益不高，因为它只覆盖一层目录浏览；agent 在代码仓库里的主需求通常是 scoped discovery。

建议在 Guidelines 中给出有边界的 shell 原语：

find . -maxdepth 2 -type f
find . -maxdepth 2 -type d
fd . src
rg --files | head -n 100
rg --files src | head -n 100

约束需要写清楚：

  • 默认带 maxdepth、路径 scope 或 head，避免远端设备上跑无界扫描。
  • 想看目录结构时用 find <scope> -maxdepth N。
  • 想找文件候选时用 fd 或 rg --files。
  • 已经知道精确目录且只想看一层时，ls / find <dir> -maxdepth 1 比 listFiles 更贴近 agent 的操作习惯。

LH

LH 现在把 path_search 拆成两个工具：

  • searchFiles：关键词搜索，keywords 必填，可以加 scope、contentContains、时间、类型、排序等过滤项。
  • globFiles：glob pattern 搜索，pattern 必填，scope 可选。这个工具更接近 Claude Code / Open Code 的 Glob。

实现上 Desktop 和 CLI 不一样。

  • Desktop 会走平台搜索封装：macOS 优先 Spotlight
  • Linux 优先 fd / find，最后退到 fast-glob。
  • CLI / remote device 当前走轻量 wrapper，searchFiles 和 globFiles 底层都是 fast-glob。

Claude Code

Glob 工具，入参：pattern ， path?。 Prompt 提示 agent 支持 **/*.js、src/**/*.ts 这类 glob pattern，但 description 没直接说底层是 rg --files。底层实现用 rg --files --glob ...。

Codex

通过 system prompt 直接告诉 agent：搜文本用 rg，搜文件用 rg —files。

Open Code

Glob 工具同 Claude Code， description 只说 glob pattern 和按 mtime 排序，不说底层 rg —files 。

grepContent

LH

LH 现在把 grepContent 做成强封装工具。入参接近 ripgrep：

  • pattern：必填 regex。
  • scope：搜索目录。
  • output_mode：content / files_with_matches / count。
  • glob / type：过滤文件。
  • -i / -n / -A / -B / -C / head_limit / multiline：控制匹配输出。

Desktop 实现有封装价值：Unix 路径优先 rg，再退到 ag / grep / Node.js；Windows 优先 rg，再退到 findstr / Node.js。

但 CLI / remote device 当前走的是轻量 wrapper：直接 spawn rg --json -n，只消费 cwd / filePattern，和 manifest 里的 scope / glob / output_mode 不完全对齐。也就是说，模型看到的是一个 ripgrep-like 工具，远端实际执行却没有完整的 ripgrep 参数面。

Claude Code

Grep 工具，入参接近 ripgrep ，明确告知 Agent 工具 “built on ripgrep”，pattern syntax 也写 “Uses ripgrep”。禁止 agent 用 Bash 直接跑 grep 或 rg。

Codex

通过 system prompt 直接告诉 agent：搜文本用 rg，搜文件用 rg —files。

Open Code

grep 入参比 Claude Code 少很多：pattern ，path?，include? 。 Prompt：如果需要统计 match 数，用 Bash tool 直接跑 rg，不要用 grep。

方案判断

grepContent 不应该和 listing / path_search 一起直接降级。它在 Desktop 上有真实封装价值，问题主要在两点：

  • Desktop 和 CLI / remote device 的实现能力不一致。
  • Prompt 没有告诉 agent 这个工具和 rg 的关系，也没有说明哪些复杂搜索可以直接用 rg。

这里更适合做成单独讨论项：要么把 CLI / remote device 的 grepContent 对齐到 rich implementation，要么在 Guidelines 中允许 agent 在复杂 content search 下直接使用 rg。

讨论

如何取得工具封装的平衡？

  • listing / path_search 的采用率低，继续强化封装可能收益有限。
  • 在 prompt 设计上 path_search 需要明确 scope，避免 agent 在远端设备上跑无界扫描。

方案思路：

  • 最激进：
    • -> Codex： 把 listing / path_search 从强封装工具降级为 prompt guidelines ，给出稳定命令样例和约束：
find . -maxdepth 3 -type f
fd '<name-or-pattern>' .
rg --files | rg '<path-fragment>'
rg -n '<pattern>' <scope> --glob '<glob>'
  • 保守：
    • -> Claude: 丰富参数，尽可能提供能力
    • -> OpenCode： 丰富指引和 Shell 示例，指出 agent 可以根据平台和需求自选 cli 。

关系图谱

反向链接