date: 2026-06-11 tags: [inbox, project/cli-agent, type/report] source: tb-16g:/home/ubuntu/workspace/lobe-search-agent-eval/tmp/local-system-tool-adoption-analysis/final-report/final_report.md public: true

lobe-local-system 工具采用分析报告

Background & Motivation

LH local-system 提供一组 runCommand 之外的本地文件工具：listFiles、searchFiles 等。本身希望 agent 少写 shell，多用结构化工具完成文件探索、搜索、读取和编辑。这样可以减少命令试错、无效 tool call 和交互轮次。但实际 trace 里仍然有大量 shell 的等价操作。本报告调研两个问题：

agent 在可用场景中有多倾向于采用 LH 专用工具。
LH 专用工具是否引入 fallback，增加额外 step。

Method

Data Collection

scoped_actions 只统计 LH local-system 非命令执行工具覆盖的本地文件操作：

listing
path_search
content_search
file_read
file_write
file_edit
file_move

每个 scoped_action 归入一个簇：

LH：通过 LH 专用工具完成，例如 listFiles、searchFiles、grepContent、readFile、writeFile、editFile、moveFiles。
shell：通过 runCommand 中的 shell equivalent 完成，例如 ls、find、grep、cat、sed、Python 脚本等。

纯命令执行、构建、测试、安装、进程控制、getCommandOutput、killCommand 不计入。

边界例子：

case	是否计入	归类
`grep foo /app/a.py`	是	`content_search / shell`
`ps aux \| grep python`	否	进程输出过滤，不是文件内容搜索
`npm test`	否	纯命令执行，不是 local-system 文件操作

Metrics

统计目的：分析 agent 是否采用 LH 专用工具，以及采用后是否减少探索成本。

采用情况：衡量 agent 在可用场景中是否选择 LH 专用工具。
- RQ 1 范围占比：判断 local-system 文件操作需求在 judge 抽取的动作序列中占多大比例。
- RQ 2 LH 采用率：判断 agent 在范围内操作中有多大比例选择 LH 专用工具。
切换情况：衡量 agent 是否在同一执行意图内更换工具簇。
- RQ 3 切换率：判断 agent 是否从 LH 切到 shell，或从 shell 切到 LH。
- RQ 4 使用惯性：
  - 执行动作序列图：按 step 展示每条 trace 中 LH、shell、other 的动作顺序，观察 agent 是否持续使用同一类工具。
  - 拐点前后对比：以首次 LH/shell 切换为拐点，对比拐点前后的采用率，观察一次切换是否改变后续工具偏好。

Experiment

本报告使用 2026-05-27 的 88 条完整 LH trace。

实验从原始 LH trace 开始。先把 trace 切成连续 chunk，再让 LLM judge 在每个 chunk 内识别 agent 想完成的底层意图、实际采取的动作，以及这个意图是否形成完成闭环。

LH trace
  -> 按 step 切成 trace chunk
  -> 在 chunk 内识别多个意图闭环
    -> 对每个意图闭环记录动作序列
      -> 判断动作属于 LH、shell 还是 other
      -> 判断动作功能：搜索、读取、写入、编辑、移动等
      -> 判断意图是否完成，以及是否发生 LH/shell 切换
  -> 聚合得到采用率、切换率和可视化

Main Result

RQ 1 & RQ 2 采用情况

LLM judge 从 88 条 trace 中抽取 3555 个 action。

其中有 1375 次统计范围内的文件操作，范围占比 38.7%。
在这些范围内操作中，agent 使用 LH 专用工具 964 次，使用 shell 平替 411 次。LH 采用率 lh_adoption_rate = 70.1%。

RQ 3 & RQ 4 切换情况

切换定义：

在同一个意图闭环内，agent 用后续工具替代或重试前一个工具，继续完成同一目的。只换了工具但目的不同，不算切换。
例如：
- 先用 searchFiles 找文件，再用 find 找同一个文件，记为 lh_to_shell。
- 先找文件再读文件，属于正常工作流，不算切换。

LLM judge 从 169 个 trace window 中抽取 1987 个 judge episode，其中 115 个 episode 发生工具簇切换。切换率 5.8%。

跨簇切换方向并不均匀：

切换方向	次数
`lh_to_shell`	60
`shell_to_lh`	3

主要切换类型：

切换类型	次数	占切换 episode 比例
`fallback_after_error`	49	42.6%
`fallback_after_mismatch`	43	37.4%
`fallback_after_empty`	13	11.3%

Analysis

RQ 1 & RQ 2 工具采用率分析

按功能拆分，工具采用率实际上并不均匀：

功能	RQ1 范围内操作	LH 操作	shell 操作	RQ 2 LH 采用率
`file_move`	1	1	0	100.0%
`file_write`	318	289	29	90.9%
`file_edit`	227	184	43	81.1%
`file_read`	483	334	149	69.2%
`content_search`	120	78	42	65.0%
`listing`	151	56	95	37.1%
`path_search`	75	22	53	29.3%

结论：

local-system 文件操作占 judge action 的 38.7%，这个范围值得优化。
优化需要聚焦重点。
- file_write、file_edit、file_read 的 LH 采用率已经较高，继续增加专用 API 的收益有限。
- listing 和 path_search 的 LH 采用率最低，agent 更愿意直接用 ls、find、rg --files、fd 等 shell 工具。这两个工具需要优化。

RQ 3 & RQ 4 工具切换趋势分析

LH -> shell 的来源工具集中在少数几个 LH 工具：

LH 来源工具	目标工具	次数	主要功能
`readFile`	`runCommand`	40	`file_read`
`grepContent`	`runCommand`	12	`content_search`
`listFiles`	`runCommand`	5	`listing` / `path_search`
`editFile`	`runCommand`	2	`file_edit`
`writeFile`	`runCommand`	1	`file_write`

使用惯性上，lh_to_shell 一旦发生，后续 LH 使用占比明显下降。以切换事件为拐点，统计同一个 operation 内拐点前后的全部 episode：

拐点方向	可比较事件	拐点前 LH 占比	拐点后 LH 占比	LH 变化
`lh_to_shell`	42	64.6%	32.2%	-32.4 pp
`shell_to_lh`	3	23.2%	32.6%	+9.4 pp

同功能粘性也存在。60 次 lh_to_shell 中，47 次后续还有相同功能调用；其中 27 次没有回到纯 LH，占 57.4%。这些同功能后续调用的平均 shell 占比为 73.3%。

lh_to_shell 也更容易发生在前期：60 次 lh_to_shell 中有 33 次出现在 trace 前 25% 的 step，占 55.0%。

可视化：

导读：

fix-code-vulnerability：content_search 中先用 grepContent，随后切到 shell grep。这个 case 适合观察搜索类工具为什么留不住 agent。
large-scale-text-editing：早期发生 file_read 的 LH -> shell，后续动作长期偏向 shell。这个 case 适合观察一次切换后的通道惯性。
gpt2-codegolf：listing 后续同功能调用保持 shell。这个 case 适合观察目录查看类需求中 agent 对 ls 的偏好。

结论：

切换率只有 5.8%，说明大部分意图不会在 LH 和 shell 之间来回尝试。
发生切换时方向高度不对称，主要是 LH -> shell，很少是 shell -> LH。
LH -> shell 往往不是一次孤立调用。切换后 LH 占比明显下降，说明 agent 会形成 shell 惯性。
切换问题和采用率问题不是同一件事：listing / path_search 的问题是初始采用率低；readFile / grepContent 的问题是使用后更容易 fallback 到 shell。
对 listing 和 path_search，与其强制封装专用 API，不如把优化重点放在 prompt 中提供稳定 shell 命令样例和 scope 约束。

kb26

探索