【效率反馈】agent 检索/工具使用效率：120s 超时的递归列目录命令 + 输入输出 token 冗余（附拆解与建议）

[Zhangbo-cn]

一句话

在"为什么先选工作区"这类需要检索代码库的问题上，agent 的工具调用与 token 消耗存在明显可优化点：一次误用 shell 的递归列目录命令单独耗时 120s（超时）并产出约 78KB 无效输出；整轮 9 步累计输入 307K token、输出 7.1K token，其中相当一部分是可避免的冗余。

观测数据（一次真实会话）

指标	值
轮次	1 轮 · 9 步
LLM 耗时	1m4s
工具调用耗时	2m6s
首 token 平均	0.9s
解码速度	126 tok/s
缓存命中	84%
输入 / 输出	307K tok / 7.1K tok

问题拆解

1. 工具调用是最大瓶颈（约占全轮 66%）：一次 Get-ChildItem -Recurse -Depth 2 -File -Include *.md（PowerShell）遍历进了 node_modules 的损坏符号链接，超时 120 秒并吐约 78KB 错误输出（最终被截断）。这一个调用几乎占满全部工具时间。
2. 输入 token 冗余：307K 是 9 步累计（每步重发全部上下文，平均约 34K/步）。84% 命中缓存（读取成本低），16%（约 49K）重新计算，其中包含：那次 78KB 垃圾输出、多次整篇读文件（部分只需几行）、grep 输出未限流。
3. 输出 token 冗余：7.1K = 8 个中间步的叙述性文字 + 最终答案；中间探索发现与最终答案存在重复。
4. 首 token 0.9s 与 126 tok/s：均正常/偏快，不是瓶颈；LLM 时间主要由输出长度决定（7.1K ÷ 126 ≈ 56s）。

建议

1. agent 检索文件时优先使用内置的 Glob / Grep / Read 工具（自动排除 node_modules、支持 offset/limit、head_limit），而不是 shell 递归列目录命令——这也是仓库 AGENTS.md 已有的约定。
2. 对工具输出设置合理上限，避免超大或垃圾输出进入上下文（read 用 offset/limit，grep 用 head_limit + 少量上下文行）。
3. 相关文件并行批读取，减少轮次与上下文重发（9 步可压到 4-5 步）。
4. 中间步输出只报结论，最终答案与问题匹配长度。

期望

• agent 在代码库检索时默认优先使用内置搜索工具，而不是 shell 递归命令；
• 工具调用侧对"递归列目录"类命令有护栏或提示，避免遍历 node_modules 符号链接超时；
• 保持提示词前缀稳定以持续命中缓存。

环境

Windows 11 Pro 10.0.26200 x64 · Node v24.14.1 · dsh 0.1.0-rc.5

补充：以上为观测性质反馈，供改进 agent 检索链路参考；数字来自一次真实会话的会话统计。

[zoahdev]

The data matches our local micro-benchmark and the fix direction is right.

Local benchmark (Windows, Node 24, PowerShell 7): Get-ChildItem -Recurse -Depth 2 -File -Include *.md on a clean tree completes in 4ms ? so the 120s hang is not the command itself but what it walks into (symlink/junction cycles, network drives, huge dependency trees). The reliable fix is "don't use shell recursion for discovery", exactly as you said.

We shipped the reusable part: a tools-first Retrieval contract for AGENTS.md (Glob/Grep/Read over shell, node_modules excluded, offset/limit + head_limit, parallel batch reads, stable prompt prefix) ? tutorial with copy-paste snippet:

• zh: https://zoahdev.github.io/dsh-tutorials/zh-15-retrieval-efficiency.html
• en: https://zoahdev.github.io/dsh-tutorials/en-15-retrieval-efficiency.html

Supporting your guardrail asks: a default tool-output cap (bytes/lines with truncation marker) and a hint when a shell command looks like recursive directory listing would both prevent the 78KB-garbage-into-context class. Happy to help spec either.

[weijiafu14]

[非官方] 你拆出的第 2 个问题（大段工具输出进入上下文并在后续步骤反复携带）现在有一条不改 Harness 源码的现成路径：pi2dsh@0.11.0 可以把 Pi 扩展直接挂到 DSH，配合 pi-quiet-tools 在 tool result 进入模型前压缩大结果，并把完整原文保存在可回读的本地 artifact。我们已经在真实 DSH 会话里验证过这条链路。\n\nsh\ndsh plugin --profile web add pi2dsh@0.11.0\ndsh plugin --profile web add pi-quiet-tools\n\n\n项目与验证材料：https://github.com/weijiafu14/pi2dsh\n\n边界也说清楚：它能直接挡住“78KB 垃圾输出继续污染后续上下文”，但不会让已经发出的 Get-ChildItem -Recurse 提前结束；递归检索优先 Glob/Grep/Read、避免走进 node_modules/坏链接，仍需要你文中第 1 条的检索策略或宿主侧命令护栏。两层一起做，才同时减少 120s 工具耗时和后续 token 重发。