前言¶
在 DeepSeek Harness（DSH）里做智能体或插件开发时，工作区文件往往分散在多层目录里。若只靠系统文件管理器或在外部编辑器里搜索，上下文会不断从 DSH 切出去；而 DSH 本身也没有对外暴露可复用的全局文件搜索服务。社区插件 dsh-file-finder（维护者 chzisnull）把 VS Code 习惯的「按文件名 / 按内容」查找搬进 DSH 客户端：搜索、浏览、预览和轻量编辑都在同一套界面里完成，读写仍走 DSH 的工作区文件系统，而不是插件自建一套存储。
下面按定位、能力、安装与用法说明该插件；事实依据为 GitHub 仓库 与 中文 README。插件在 SkillHub 目录归类为客户端，当前 GitHub 星标为 2；npm 包版本在 package.json 中为 0.11.0，许可证 MIT。
这是什么¶
dsh-file-finder 是 DeepSeek Harness 的客户端插件：在 DSH 内按文件名或文件内容查找当前工作区文件，用 DSH 右侧栏的原生预览打开，或在插件自带的查看器、编辑器里阅读与修改。简介与仓库描述一致：search files by name or content, customizable shortcuts, and in-app text editing。
设计上插件是纯加法：不注册 DSH 自带的文档渲染器、右侧栏 tab 或 Files 树覆盖层；遍历、读写在服务端通过 DSH 的 ctx.fs 完成，卸载后 DSH 界面保持原样（见仓库 ADR 0001）。
核心功能¶
浏览与搜索¶
- 空查询时浏览目录：无搜索词时列出当前工作区目录（文件夹在前、文件在后）。回车或 → 进入子目录，Backspace 返回上级，面包屑可跳转；开始输入即切换为搜索，清空后回到刚才浏览的目录。
- 按文件名搜索：支持路径片段，例如
src/view。 - 按内容搜索：每个命中单独一行，带行号与上下文。
Esc 逐层后退：先从查看器/编辑器回到打开文件时的目录，再逐级向上，最后关闭面板。
打开方式与媒体¶
全局 打开方式（设置 → 文件查找）决定文本文件回车后的落点：
- 原生预览（默认）：DSH 右侧栏，经
ctx.sidebarRight.openResource()与dsh-resource://file/session/<sessionId>/<path>。 - 查看器：插件只读界面，语法着色与文件内查找。
- 编辑器：通过
ctx.fs写回；若磁盘文件在打开后被外部修改，保存会拒绝覆盖，需重新加载后再保存。
⌘/Ctrl+回车 在「看」与「编」之间切换。图片、视频、音频、PDF、HTML、Markdown 无论打开方式如何都进插件查看器；Office、压缩包等查看器无法渲染的类型改走原生预览，不可用时会有提示。原生预览在无活动 Session 或无右侧栏时会回退到查看器并说明原因。
快捷键¶
插件在 DSH 快捷键服务中注册命令，但不声明默认绑定（避免与 DSH 内置默认键冲突导致启动失败）；VS Code 习惯的组合由插件自己的按键监听实现：
| 操作 | 键位 |
|---|---|
| 按文件名 | ⌘/Ctrl+P |
| 按内容 | ⌘/Ctrl+Shift+F |
| 切换 Bot / 经典 Agent（仅安装 DS Bot 时） | ⌘/Ctrl+Shift+B |
可在 设置 → 编辑快捷键 中为上述命令另行指定键位。注意：DSH 默认将 ⇧⌘F / Ctrl+Shift+F 用于 fork 会话；使用本插件做内容搜索时，若仍需 fork，请为 session.fork 重新绑定。网页版中 ⇧⌘B 可能与右侧栏开关冲突；桌面版相对空闲。设置页还提供打开文件浏览器的一键试用（无默认全局快捷键）。
预览与编辑细节¶
- 内置查看器：视频支持字节范围与拖动进度；HTML 在沙箱 iframe 中运行；Markdown 使用 DSH 渲染器，相对路径图片解析到工作区。
- 编辑器面向约 1 MB 以内的 UTF-8 文本；二进制及
node_modules、.git、常见构建目录等不参与搜索。超过约 200 KB 时语法着色会退回纯文本（标题栏有说明）。 - 编辑器内 ⌘/Ctrl+F 为文件内查找；⌘/Ctrl 悬停/点击支持同文件内的定义跳转（JS/TS、Python、Go、Rust、Java/C 系、HTML 锚点等），跨文件 TypeScript 解析为后续计划。
可选：DS Bot 桥接¶
若启动清单中包含 ds-bot 插件，本插件额外提供 Bot 模式与经典 Agent 模式的切换（⌘/Ctrl+Shift+B）及对应设置卡片；未安装时不注册命令、不显示卡片。桥接通过识别启动图并操作 DS Bot 自身 UI 完成，不 patch DS Bot 内部状态。
设置项¶
设置 → 文件查找 包括：快捷键参考与试用、区分大小写、额外忽略目录、文件名/内容结果数量上限、全局打开方式、恢复默认；修改自动保存。
安装与启用¶
插件已发布到 npm，包名为 dsh-file-finder。在 DSH 设置 → 插件 → 添加插件 中可使用：
dsh plugin add dsh-file-finder
从本地目录安装（路径按你的机器修改）：
dsh plugin add /Library/aiProject/dsh-file-finder
安装后若入口未出现，刷新 DSH 页面。Agent 侧也可调用同名能力，工具名为 file_finder。
典型用法¶
- 在 DSH 中打开目标工作区并确保插件已启用。
- 按 ⌘/Ctrl+P，输入文件名或路径片段，回车打开；若默认是预览，需要编辑时按 ⌘/Ctrl+回车 进入编辑器，⌘/Ctrl+S 保存。
- 按 ⌘/Ctrl+Shift+F 搜索内容，在结果列表中选行跳转对应文件与位置。
- 不输入搜索词时可直接用面板浏览目录，配合面包屑与 Esc 返回。
- 在 设置 → 文件查找 中调整打开方式、忽略目录与结果上限；与 DSH 快捷键冲突时在 设置 → 编辑快捷键 中改绑。
适用场景与注意¶
适合需要在 DSH 会话旁快速定位文件、扫一眼内容或做小改动的开发者。插件以当前 DSH 进程权限访问工作区；安装前请阅读 源码与 LICENSE，确认符合你的安全与合规要求。
DSH 生态强调「一切皆插件」；SkillHub 目录 是社区站点，与 DeepSeek / 幻方无官方从属关系，安装来源以 npm 包名或你信任的 Git 仓库为准。
结尾¶
dsh-file-finder 把文件名/内容搜索、目录浏览、多 surface 打开和轻量编辑收进 DSH 客户端，并复用 DSH 原生预览与 ctx.fs，避免与核心文件界面抢注册位。进一步了解可访问 SkillHub 插件页 与 GitHub：chzisnull/dsh-file-finder。
