前言¶
在 DSH 里让智能体读文件、改代码时，路径往往又长又碎：模型只记得片段文件名，或把 src/foo/bar.ts 说成 bar ts。内置工具通常要求精确路径，多轮对话里反复猜路径会拖慢节奏。Pi Coding Agent 生态里的 pi-fff（FFF = fast fuzzy finder）用模糊匹配和索引缓解这类问题；维护者 sleepinginsummer 将其能力移植为 DSH 插件 dsh-fff，在会话中提供 find_files、resolve_file、related_files 以及基于 ripgrep 的 fff_grep。下面介绍它是什么、如何安装，以及使用时需要注意什么。
这是什么¶
dsh-fff 是 DeepSeek Harness 的社区插件（分类：联网工具），由 sleepinginsummer 维护，源码在 GitHub，目录页见 SkillHub。
一句话定位：在工作区内做模糊路径查找和索引内容搜索，把「记不清的引用」收成可交给 read / replace 的精确路径，或按规则拉出相关文件。实现上为纯 JavaScript 路径索引与子序列打分，零 npm 依赖（因 DSH 动态插件不能 require 原生 npm 包，相对 pi-fff 的原生 @ff-labs/fff-node 做了重写；README 说明中型项目性能足够）。
核心功能¶
插件向 DSH 注册四类工具（安装并对所有会话生效）：
| 工具 | 作用 |
|---|---|
find_files |
模糊路径搜索：fzf 风格多 token（空格分隔，每个 token 须命中）；basename 权重加倍、目录段减半，连续片段加分；返回排序后的路径列表 |
resolve_file |
将模糊引用解析为单个精确路径，并给出 runner-up，便于发现歧义；结果可直接用于读/替换类操作 |
related_files |
按相关性列文件：同 stem（如 .test.ts / .spec.ts 与实现配对）→ 同目录 → 兄弟目录 |
fff_grep |
内容搜索：通过子进程调用 ripgrep（rg --no-heading --line-number），支持 regex/字面量、模糊 scope、glob 过滤；结果按文件分组并带计数。本机未安装 rg 时会报错，并提示改用 DSH 内置 grep |
路径索引：用 fs.listDir 递归遍历工作区，跳过 .git、node_modules、dist、build 等目录；上限约 5 万文件、16 层深度；索引带 60 秒 TTL 缓存。
与 pi-fff 的主要差异（据 README）：无原生索引库与后台 watcher；无编辑器 @... 补全（DSH 聊天输入无该机制）；不覆盖 DSH 内置 read/grep，模糊能力通过 resolve_file / fff_grep 显式调用。
安装与启用¶
在目标 profile 下执行官方安装命令：
dsh plugin --profile <name> add dsh-fff
安装后重启 DSH，find_files、resolve_file、related_files、fff_grep 即可在会话中使用。若要用 fff_grep，需在本机安装 ripgrep（rg）。
当前 npm 包版本为 0.1.0（见 package.json），许可证 MIT。
典型用法¶
README 未给出逐条对话示例，但工具语义可直接对应常见工作流：
- 先搜路径：用
find_files传入若干 token（例如auth middleware ts），从返回列表里确认目标文件。 - 消歧义读文件：用
resolve_file把模型的模糊描述（如user service）解析成一条主路径；若 runner-up 分数接近，先向用户或上下文确认再read。 - 补全测试/实现上下文：对已知文件调用
related_files，拉同 stem 的测试、同目录或兄弟目录文件，减少漏改。 - 按内容定位：用
fff_grep在限定 glob 或 scope 下搜 regex/字面量，再对命中文件做精确编辑。
开发侧可用包内测试验证行为：
npm test # 15 用例：子序列打分、多 token、basename/目录权重、排序/截断、相关文件、搜索结果分组、静态求值、工具注册
适用场景与注意¶
适合：仓库文件多、路径深，希望智能体用模糊 token 找文件、显式解析路径后再读写；需要按 stem/目录关系批量拉相关文件；希望在插件侧统一走 ripgrep 做内容搜索（且本机已装 rg）的 DSH 用户。
注意：
- 索引有规模与深度上限，极大 monorepo 可能无法全覆盖；缓存 60 秒，新建文件后短暂期内可能需等待或触发重新索引逻辑（以插件实际行为为准）。
fff_grep依赖系统rg，与 DSH 内置 grep 是两条路径，未装 ripgrep 时应改用内置工具或先安装rg。- DSH 社区目录（如 SkillHub）是独立站点，与 DeepSeek / 幻方无官方从属关系；插件以当前 dsh 进程权限 遍历工作区并可能执行子进程，安装前建议阅读 源码 与 MIT 许可证，确认符合你的安全与合规要求。
结尾¶
dsh-fff 把 pi-fff 的「模糊找文件 + 相关文件 + ripgrep 搜索」搬到 DSH，用四个显式工具补足精确路径与内容检索，适合在智能体开发流程里减少路径猜测成本。更多信息见 SkillHub 目录页 与 GitHub 仓库。
