dsh-plugin-better-glob

以 per-agent 阴影顶替 DSH 内置 glob 工具：自动排除无底洞目录（node_modules、dist、build、.venv 等），模型要搜这些目录时必须显式传 include 白名单。grep 不受影响，不改任何内置插件注册面。

为什么是 per-agent 阴影

• 工具注册表按 scope 分层解析：agent 自己层的注册遮蔽一切继承层（headless 的全局层、web profile 里 preset 挂载的 standing scope 层）。
• 全局注册在 web profile 下会输给 preset 挂载；bundle patch 够不到 preset 文件。所以唯一全覆盖的机制是监听 agent/session-start，把同名工具经 agent.ctx 注册进 agent 自己的层 —— 同时注册同名 tool:glob 提示词 section（同 order）遮蔽内置文案。
• startup/resume/clear/compact 都会触发 session-start，WeakSet 保证幂等；插件配置热重载时对存活 agent 做dispose-再注册的 resync。

工具行为

• pattern（必填）/ path（可选）：与内置 glob 语义一致，mtime 排序、含隐藏与被 ignore 文件、100 条封顶 + spill 恢复。
• include（可选，string[]）：白名单。include 模式的路径段命中某排除目录名 → 该目录在本调用中被放行（argv 构造期摘掉它的否定 glob）；include: ["**"] 放行全部。include 永不过滤结果 —— pattern 才是匹配器。
• 排除的实现在 argv 构造期而非后置 glob：ripgrep 在遍历期 prune 掉被排除目录，后置 glob 救不回被剪的子树。
• VCS 目录（.git/.svn/.hg/.bzr/.jj/.sl）永远排除，不配置化。
• 执行底座复用内置 @deepseek-ai/dsh-tool-fs-search 的打包 ripgrep 二进制、subprocess 缝、错误词汇表与 spill 设施。

默认排除清单（excludeDirs 整体替换式）

node_modules bower_components vendor Pods .yarn dist build out target obj .next .nuxt .output .svelte-kit .turbo .parcel-cache .cache coverage __pycache__ .venv venv .tox .mypy_cache .pytest_cache .ruff_cache .gradle .terraform .idea

配置

字段	默认	说明
excludeDirs	上表	排除目录名（裸名，不允许分隔符），整体替换默认清单
sampleOverCapGlobResults	false	超帽页是否按顶层条目抽样（同内置开关）
globMaxResults	100	单次内联保留路径数，超出部分 spill
globMetaMaxBytes	65536	卡片 meta 字节预算
rawOutputMaxBytes	20000000	单次解析的 rg stdout 上限
graceMs / stderrMaxBytes / timeoutMs	3000 / 65536 / 30000	同内置语义

开发

pnpm install            # pnpm-workspace.yaml 锚定本目录（防止向上并入 D:\Projects 的 workspace）
pnpm exec node scripts/relink-deps.mjs   # 把 @deepseek-ai/* junction 到 ~/.dsh/source/current 的已构建包（pretest/prebuild 自动跑）
pnpm run typecheck      # tsc --noEmit（类型经 tsconfig paths 解析 source/current 的 lib/types）
pnpm test               # vitest：argv/meta 纯逻辑 + 真实 ToolRuntime 组合 preflight
pnpm run build          # tsdown（lib/index.js）+ tsc（lib/types/*.d.ts）

peer 依赖（@deepseek-ai/cordis、dsh-tools、dsh-tool-fs-search、dsh-system-prompt、dsh-agent）由宿主提供，均为 optional peer；schemastery 是直接依赖。

运行

dsh plugin --profile web add "link:D:/Projects/deepseek-harness/dsh-plugin-better-glob"
# 之后重启 dsh web（由人类执行）+ 浏览器硬刷新

link: 引用下改源码后 pnpm run build 重建 lib/ 即生效，无需重装。发布形态：GitHub huanlinoto/dsh-plugin-better-glob（预构建 lib/ 入库，无 prepare）/ npm @huanlin/dsh-plugin-better-glob。

检查

• pnpm run typecheck — 严格模式类型门禁
• pnpm test — 40 用例：argv 构造（默认排除、include 按段提升、** 全提升、VCS 恒排除）、参数与配置校验、meta 投影/收窄、render 页脚；组合 preflight 用真实 ToolRuntime + SystemPrompt 验证阴影生效、全局视图不受污染、re-fire 幂等、reload resync
• pnpm run build — 产物 lib/index.js（peer 全 external）+ lib/types/

已知限制

• 插件停用后，已存活 agent 的阴影注册会保留到该 agent 销毁（注册挂在 agent scope 上，随其 unwind）。
• 配置热重载对「已在会话中的 agent」经 resync 生效；若加载器将来改为 cache-bust 重导入模块（同进程新模块实例），resync 会因 agent 层重名而失败报错（fail loud，不会静默失效）。
• include 的提升粒度是「目录名」，include 模式中目录名之后的子路径不影响遍历范围（node_modules/a/** 放行整个 node_modules）；精确到子目录的放行需缩小 excludeDirs 配置。