DeepSeek Harness 中 glob 超限结果的顶层采样：从“单棵子树主导“到“跨条目代表性分页“

人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载本篇技术指南围绕 DeepSeek Harnessdeepseek-ai/dsh-tool-fs-search插件对glob工具超上限结果的采样决策展开。它适用于任何需要让 Agent 通过glob工具快速建立工作区全局认知的部署场景当你发现模型把某棵子树误当成整个项目时可以通过sampleOverCapGlobResults配置开启跨顶层条目的轮转采样让超限页面覆盖多个顶层条目而不是全部集中在修改时间最早的子树上。读完本文你将掌握问题成因、配置语义、轮转采样算法、页面 footer 与 spill 行为以及对应的源码与测试验证方式。1. 问题背景三个独立且合理的行为叠加出的错误印象Agent Note.agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md记录了一次真实的故障形态工作区有22 个顶层条目、11,485 个文件glob {pattern:*}匹配到10,030 条路径内联显示的100 条路径全部位于一棵近期解压的子树中模型因此完全没有看到其余21 个顶层条目把子文件夹描述成了整个项目。三个单独看都合理的行为叠加共同制造了这个错误印象不含/的 glob 会匹配任意深度的文件名。Ripgrep 语义下*表示目录树中的每个文件而不是 shell 对当前目录执行的顶层展开。这也是*.ts能跨目录树搜索的原因。--sortmodified按升序排列。归档包还原出的旧时间戳让该子树排在结果最前面。内联页面直接截取排序后的前部。截取逻辑没有说明它只代表集中于一处的切片模型看到的就是整个工作区的内容。1.1 从源码确认*的语义与排序在 glob.ts 的buildGlobCommand中可以看到实际传给打包的 ripgrep 二进制的参数const parts [ --files, --glob${input.pattern}, --sortmodified, --no-ignore, --hidden, // 每个 VCS 名称两条取反 glob裸形式在遍历时剪枝/** 形式在搜索根位于目录内部时排除内容 ...GLOB_VCS_EXCLUDES.flatMap(name [ --glob!**/${name}, --glob!**/${name}/**, ]), ]--sortmodified正是按修改时间升序的来源搜索根通过--以普通 argv 元素传递path以-开头也不会被解析成 flag所有模型可控值都是普通 argv 元素没有 shell 层因此不存在引号转义问题tests/tools.spec.ts 验证了命令替换、反引号、引号、换行、前导-等 hostile 输入都保持为一个惰性 argv 元素每次 glob 调用默认内联上限为GLOB_MAX_RESULTS 100glob.ts与 Claude Code 的GlobTool默认上限一致。2. 决策必填的采样开关两种超限模式未超过globMaxResults的结果保持不变完整、按修改时间排序、逐字节不变。只有超限时才进入两种模式之一由必填配置sampleOverCapGlobResults决定没有回退值配置值超限行为false保留按修改时间排序的前部与历史行为一致true在完整结果的顶层条目之间按轮转方式采样在 index.ts 的 schemastery 配置声明中可以看到这一必填约束export const Config: zConfig z.object({ sampleOverCapGlobResults: z.boolean().required(), globMaxResults: z.number().default(GLOB_MAX_RESULTS), // ...其余字段均有默认值 })测试 tools.spec.ts 也锁定了缺少该配置时加载直接失败it(requires an explicit over-cap glob sampling choice, () { expect(() new ToolFsSearch.Config()).toThrow(/sampleOverCapGlobResults/) expect(new ToolFsSearch.Config({ sampleOverCapGlobResults: false })).toMatchObject({ sampleOverCapGlobResults: false, globMaxResults: 100, }) })2.1 为什么不做默认值Note 的考虑过的替代方案中明确否决了为采样选项提供默认值没有全产品范围的证据支持把任一排序作为隐式约定因此每个组合bundle/preset都必须显式选择一种配置错误在加载时失败fail loud而不是静默地选择一个可能误导模型的排序。2.2 采样模式的排序契约采样模式遵循一组可精确描述的规则由 sampleAcrossTopLevel 实现每个条目都先获得一个位置之后才有条目获得第二个位置round-robin已经用尽的分组退出轮转剩余槽位继续分给仍有路径的条目各组内部的相对顺序保持稳定按修改时间顺序分组以实际搜索根为基准显式指定path时也是如此root参与分组计算。如果完整结果本身是扁平的所有路径都在顶层、没有子目录采样结果与修改时间前部完全一致——tools.spec.ts 中的reproduces the modification-time-ordered head for a flat result用例锁定了这一点。3. 配置与部署语义3.1 配置参数一览deepseek-ai/dsh-tool-fs-search的完整配置config-catalog.md配置项类型默认值说明sampleOverCapGlobResultsboolean必填无默认超限 glob 页面按顶层条目采样true还是保留修改时间前部falseglobMaxResultsnumber100单次 glob 调用内联保留的路径数上限超出部分进入格式化 spill 文件grepMaxMatchesnumber200grep 单次内联保留的匹配数上限grepMaxLineBytesnumber—单条匹配行预览的最大字节数截断保持 UTF-8 边界searchMetaMaxBytesnumber—一次搜索序列化presentationMeta的最大字节数rawOutputMaxBytesnumber—可解析的完整原始rgstdout 字节上限超过报SEARCH_RAW_OUTPUT_OVERFLOWgraceMsnumber3000终止升级宽限期毫秒受MAX_TIMER_DELAY_MS约束stderrMaxBytesnumber64 * 1024保留的 stderr 诊断尾部字节数timeoutMsnumber30000工具调用超时预算毫秒通过exec.signal生效所有计数/字节/毫秒类配置必须是正整数否则加载时抛错index.tsthrow new Error(tool-fs-search: ${name} must be a positive integer)3.2 随产品交付的 CLI 组合显式选择保留前部随产品交付的 CLIcommand-line interface组合显式选择保留前部的模式。在 standard/agent.cordis.yml、cordis/agent.cordis.yml、ptc/agent.cordis.yml 中都是sampleOverCapGlobResults: false而希望达到上限的页面具有代表性的部署例如工作区定位导向的 web 组合则选择采样模式true。注意globMaxResults默认100但组合可以自行调低例如 fs-glob-sampling 场景 将globMaxResults设为4以便用少量 fixture 验证采样行为。4. 采样模式的页面呈现与 footer4.1 页面分组与 footer 文案采样模式下footer 会明确说明当前页面是跨条目的样本而不是按修改时间排序的前部当触达的顶层条目数能提供额外信息时还会报告该数量(Showing 4 of 8 paths, sampled across 4 of the 6 top-level entries this pattern matched instead of taken in modification-time order. Narrow path to inspect a specific subtree. Full sorted result stored at: locator. Use read with offset/limit, or grep this path to search within it.)来自 formatGlobOutput 的实现逻辑若shown total样本触达了全部顶层条目basis 文案为.否则附加sampled across N of M top-level entries ... instead of taken in modification-time order.若shown total追加Narrow path to inspect a specific subtree.提示模型缩小path保留前部的模式false沿用达到上限时的普通 footer不包含采样说明。fs-glob-samplingACP 场景的真实快照session.jsonl展示了端到端结果glob {pattern:*,path:tree}在globMaxResults: 4下返回tree/archive/a.ts tree/docs/guide.md tree/src/index.ts tree/test/spec.ts覆盖了 4 个顶层条目archive、docs、src、test而不是只返回某棵子树的前 4 条模型据此回复GLOB_SAMPLED。系统提示词快照system-prompt.expected.md与 schema 快照tool-schemas.expected.json也同步体现了采样语义。4.2 内联页面与 Native 卡片的一致性renderGlobPaths面向模型的文本与globCardPageNative UI 的搜索卡片通过presentationMeta投影使用同一套采样算法保证卡片与文本就哪些路径存活过上限达成一致glob.ts。卡片携带truncated与total信号元数据缺失或畸形时如回放的旧日志回退到通用卡片而不是报错。4.3 spill两种模式都保留完整排序列表当结果超限时tools/post-execute钩子会尝试把完整排序结果保存为格式化 spill 文件glob-results.txtfooter 中给出 locator 与检索提示Use read with offset/limit, or grep this path to search within it.。spill 不可用无后端、保存失败、无会话归属不会导致搜索失败此时 footer 降级为The complete result could not be saved; narrow pattern or path to see more.相关测试见 tools.spec.ts。spill 由ctx.spillStore通过ctx.get()机会性读取可选依赖这正是 index.ts 的inject列表中只声明tools、systemPrompt、subprocess的原因。4.4 提示词与 schema 同步说明排序方式applyGlobTool会根据配置值渲染不同的系统提示词段落与工具描述glob.ts采样开启while a larger one is sampled across top-level entries, so it spans the tree instead of one subtree.采样关闭while a larger one keeps the modification-time-ordered head.提示词同时固化了几条语义约定使用 glob 工具而非 shellfind来按路径模式发现文件不含/的模式匹配任意深度的 basename*匹配整棵树而非顶层glob 只返回文件绝不返回目录条目This tool does not enumerate directory entries.结果包含隐藏与忽略文件VCS 元数据目录除外。测试 tools.spec.ts 对两种配置下的提示词与描述逐字锁定。5. 目录定位分工glob 与 shellls、ctx.fs.listDir的边界本次决策没有扩大工具接口也没有新增面向模型的list工具在向模型暴露 bash 工具的部署中目录定位仍由普通 shell 操作完成查看一个目录用ls跨目录树按指定文件路径模式查找用 glob。skill 发现流程仍将ctx.fs.listDir作为内部提供方原语使用不面向模型暴露。新增list工具被明确否决见 Note考虑过的替代方案默认编程组合已经提供通用 bash模型也理解ls重复工具会永久增加 schema 与提示词占用的 token并引入排序、分页、符号链接、转义、UI 与快照等一整套新约定却没有独立的安全或策略收益。不向模型提供 bash 的精简部署也不会因本次改动获得目录定位能力。6. 考虑过的替代方案回顾Note 记录了七项被否决或暂缓的替代方案理解它们有助于把握设计权衡替代方案结论理由只保留修改时间前部否决某些部署需要稳定排序但重视工作区定位的部署应显式选择代表性数据而非让模型怀疑自己拿到的唯一一批路径为采样选项提供默认值否决没有全产品范围的证据支持任一隐式约定配置错误应在加载时失败对所有结果采样否决完整结果没有信息损失按修改时间排序仍有助于回答新旧时间问题只有截取前部无法描述整体时才采样改为最新优先排序否决只是换一棵子树主导既取消最旧优先约定也没让受限页面更具代表性仅在偏斜超过阈值时采样否决无统一阈值证据模型也无法判断当前排序约定现有上限是可清楚解释的切换点顶层以下递归平衡暂缓按第一路径段平衡已修复观测故障更深平衡需要尚无依据的深度/广度取舍策略新增面向模型的list工具否决见第 5 节拒绝*或在无分隔符模式前静默加根锚点否决会破坏*.ts跨目录树搜索的有效语义记录规则即可保留正常 Ripgrep 语义7. 影响与已知边界采样模式下超限 glob 页面无法再根据内联路径回答按时间判断新旧的问题footer 明确说明这一点spill 产物仍保留完整排序视图。采样只平衡搜索根下的第一路径段某个顶层条目内部较深处、结果密集的子树仍可能主导采样结果这是设计上的已知边界对应在顶层以下递归平衡被暂缓。保留前部模式则把集中风险作为显式部署取舍保留下来——选择该模式的部署必须接受超限页面可能集中于单棵子树。工具接口不会扩大每个组合必须设置sampleOverCapGlobResults更改该值会同时改变 glob 的提示词、schema 描述以及超限时的 Native 渲染。规范输出保留root字段{ root, paths }以便采样模式恢复其分组基准未超限的结果完全不变。8. 测试覆盖与验证路径包测试tools.spec.ts锁定了必填配置缺省抛错两种超限模式及其提示词、schema 描述sampled across top-level entriesvsmodification-time-ordered head结果集中如 125,000 个分组超过 JS 参数个数上限L724-L727与扁平两种情况显式根目录与绝对根目录分组L809-L833分组耗尽、位置数少于分组数、工作目录以外的路径按第一真实名称分组L676-L681。集成测试tests/integration.spec.ts固定真实rg行为。ACP 场景snapshots/session/fs-glob-sampling/显式启用采样启动最小化的真实 Loader/app/local-bash 组合让真实搜索插件对接确定性的rg进程 fixture其结果覆盖 4 个顶层条目而非某棵子树前部同时锁定了系统提示词与工具 schema 快照。9. 总结跨目录树采样是 DeepSeek Harness 为 Agent 工作区定位设计的确定性、可解释的超限分页策略它以必填配置sampleOverCapGlobResults迫使每个部署显式选择排序契约用第一路径段的轮转采样在 100 条内联路径内覆盖更多顶层条目用 footer 与 spill 保证模型始终知道页面代表性与完整排序视图之间的关系。源码、包测试与 ACP 场景快照三者的相互印证使其成为可审计、可回归验证的工程决策也为以有限 token 换取工作区全局认知这一 Agent 交互难题提供了一个经过实践检验的答案。赞分享人工智能AI AgentAgent 框架DeepSeek【免费下载链接】deepseek-harnessDeepSeek Harness: Everything is a Plugin.项目地址https://gitcode.com/gh_mirrors/de/deepseek-harness点击查看免费下载相关推荐DeepSeek Harness 模型侧搜索工具架构grep/glob 发现工具的边界划分、双层预算与结果溢出回收DeepSeek Harness 模型侧搜索工具架构grep/glob 发现工具的边界划分、双层预算与结果溢出回收 导读 glob 与 grep 是 Deep人工智能AI AgentAgent 框架DeepSeek决策树与集成学习从单棵树到强大组合决策树与集成学习从单棵树到强大组合 本文深入探讨了决策树构建与分裂准则的核心原理包括信息增益和方差减少两种主要分裂方法的实现细节。随后详细分析了随机森林的并机器学习深度学习强化学习人工智能深度解析 CANN ops-nn 算子库目录结构从顶层工程到单算子五件套深度解析 CANN ops nn 算子库目录结构从顶层工程到单算子五件套 本篇技术指南基于仓库内的《项目目录》文档 docs/zh/install/dir_人工智能算子库深度学习CANNAscend创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考