dsh-file-finder 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chzisnull
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# dsh-file-finder
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A DeepSeek Harness plugin for finding workspace files without leaving DSH: search by file name or by file content, then open the result in DSH's own right-sidebar preview — or in the built-in editor when you need to change something.
+
+[中文文档](README.zh.md)
+
+## What it does
+
+- **Search by file name**, including a path fragment such as `src/view`.
+- **Search by content**, with one result row per matching line.
+- **Open natively**: Enter opens the file in DSH's right-sidebar document preview, the same surface the Files tab uses, and jumps to the matching line for content hits.
+- **Edit in place** when you need to: ⌘/Ctrl+Enter opens the built-in editor, which saves through DSH's workspace filesystem and refuses to overwrite a file that changed after it was loaded.
+- **Native shortcuts**: Cmd/Ctrl+P and Cmd/Ctrl+Shift+F, like VS Code, without claiming a default binding in DSH's shortcut registry.
+- **Optional DS Bot bridge**: when the DS Bot plugin is installed, Cmd/Ctrl+Shift+B flips between Bot mode and classic Agent mode; without it neither the shortcut nor its settings card exists.
+- **A redesigned settings page** with cards, keycaps, steppers, and switches, plus an "Opening" preference that chooses whether Enter previews or edits.
+- **Polished interaction**: a frosted command palette, spring-eased mode switch, selected-row rail, loading skeletons, and reduced-motion support.
+
+## File system: it already uses DSH's
+
+There is no second filesystem hidden in this plugin:
+
+| Operation | Owner |
+| --- | --- |
+| Walking, reading, writing workspace files | DSH's `ctx.fs` seam (`index.js`) |
+| Search and ranking | This plugin (DSH exposes no reusable search service) |
+| Opening and viewing a file | DSH's right-sidebar document preview, via `ctx.sidebarRight.openResource()` and a `dsh-resource://file/session/<sessionId>/<path>` address |
+| Editing and conflict checks | This plugin's editor, over the same `ctx.fs` seam |
+
+When the native preview is unavailable (no live Session, or a shell without the right sidebar), the finder falls back to its own editor and says so. The **Settings → File Finder** page lets you make the editor the default action instead.
+
+## Shortcuts
+
+| Action | Default keys |
+| --- | --- |
+| Search by file name | Cmd/Ctrl+P |
+| Search by content | Cmd/Ctrl+Shift+F |
+| Toggle DS Bot / classic Agent mode (only with the DS Bot plugin installed) | Cmd/Ctrl+Shift+B |
+
+The commands are registered with DSH's shortcut service so you can assign your own keys in **Settings → Edit shortcuts**, but they declare **no default binding**. DSH's registry throws when one command's default overlaps another's, and it throws from inside the *other* plugin's `apply()`, so claiming Cmd+Shift+F here took the whole Web UI boot down (`Conflicting shortcut defaults: session.fork and files.searchContent`). The VS Code keys above are served by this plugin's own keydown handler instead.
+
+Note that Cmd+Shift+F is DSH's own "fork session" binding; this plugin uses it for content search, so rebind `session.fork` in **Settings → Edit shortcuts** if you relied on it.
+
+In the browser Web shell (not the desktop app), Cmd+Shift+B is DSH's right-sidebar toggle. With DS Bot installed this plugin takes that key for the mode switch, so assign a different key to `files.toggleBotMode` in **Settings → Edit shortcuts** if you need the sidebar binding there. On the desktop app the combination is free.
+
+## DS Bot mode switch (optional)
+
+When the DS Bot plugin (`ds-bot`) is part of the running boot, this plugin also offers **Toggle Bot / classic Agent mode** on Cmd/Ctrl+Shift+B, plus a matching card in **Settings → File Finder**.
+
+DS Bot keeps its surface switch private — it exposes no client service — so the bridge does the two things another plugin safely can: it detects `ds-bot` in the boot graph, and it drives the controls DS Bot renders itself (the account menu's surface-switch entry to leave Bot mode, and the DS Bot return pill to come back). Nothing is patched or forked, and DS Bot's own `ds-bot:surface` preference stays authoritative.
+
+Without DS Bot nothing is registered or shown: the command never reaches **Settings → Edit shortcuts**, the settings card stays hidden, and Cmd/Ctrl+Shift+B is left to whatever else owns it.
+
+## Settings
+
+**Settings → File Finder** covers:
+
+- Shortcut reference with one-click try buttons
+- Case sensitivity
+- Extra ignored directory names (with live chips)
+- Name and content result limits (steppers)
+- The default Enter action: **Sidebar preview** or **Built-in editor**
+- Reset to defaults; changes save automatically
+
+## Editing
+
+Choose a result and press Cmd/Ctrl+Enter (or set the built-in editor as the default action). Save writes the full text back through the workspace filesystem and refuses to overwrite a file that changed after it was loaded. Reload, then save again, to take the newer version. The editor is for UTF-8 text under about 1 MB. Binary files and common build or dependency directories are skipped.
+
+The editor shows a line-number gutter and highlights the caret's line. **Cmd/Ctrl+F** opens in-file search: every match is highlighted, the current one more strongly, with a match count, previous/next buttons, and a **Aa** case-sensitivity toggle. Enter and Shift+Enter step through matches, Escape closes the search and returns focus to the text.
+
+## Install
+
+From this directory, after the plugin is on disk:
+
+```sh
+dsh plugin add /Library/aiProject/dsh-file-finder
+```
+
+Or install the GitHub archive once it has been pushed. Restart or refresh the DSH page if the new client module does not appear immediately.
+
+The same operations are available to the agent as the `file_finder` tool.
+
+## Development
+
+```sh
+node --check index.js
+node --check client.js
+npm test
+```
+
+`npm test` covers the search helpers, the shortcut-default regression guard, and the UI contract (native preview address, palette hooks, reduced-motion rules, the DS Bot bridge, and the editor's line gutter plus in-file find).
+
+The editor has its own browser check for the gutter and in-file find:
+
+```sh
+npm run check:find
+```
+
+The DS Bot bridge also has a browser check that runs the real key handler against DS Bot's real selectors, with and without `ds-bot` in the boot graph:
+
+```sh
+node preview/bot-check.mjs
+```
+
+The native-integration research — address grammar, session derivation, service access, HMR behavior, and the keep-vs-delegate matrix — is documented in [docs/native-integration.md](docs/native-integration.md).
+
+`preview/` is a dev-only harness that renders the palette and settings page outside DSH with the real DSH theme tokens, and captures light/dark screenshots with Playwright:
+
+```sh
+node preview/screenshot.mjs
+```
+
+It is not part of the published package.
+
+## License
+
+MIT

package/README.zh.md

@@ -0,0 +1,115 @@
+# dsh-file-finder
+
+DeepSeek Harness 插件：在 DSH 里按文件名或文件内容查找工作区文件，用 DSH 自带的右侧栏预览打开，需要修改时再切到内置编辑器。
+
+[English](README.md)
+
+## 能做什么
+
+- **按文件名搜索**，也可以直接搜路径片段，例如 `src/view`。
+- **按文件内容搜索**，每一条命中单独一行，显示行号和上下文。
+- **用 DSH 原生预览打开**：回车后在 DSH 右侧栏的文档预览里打开文件——和文件树点开文件是同一个界面；内容搜索会直接跳到命中行。
+- **需要时再编辑**：⌘/Ctrl+回车打开内置编辑器，保存通过 DSH 的工作区文件系统写回；文件在打开后被别的程序改过时会拒绝覆盖。
+- **VS Code 习惯的快捷键**：⌘/Ctrl+P 与 ⌘/Ctrl+Shift+F，但不占用 DSH 快捷键注册表的默认键位。
+- **可选的 DS Bot 桥接**：装了 DS Bot 插件时，⌘/Ctrl+Shift+B 在 Bot 模式与经典 Agent 模式之间来回切换；没装时快捷键和设置卡片都不存在。
+- **重新设计的设置页**：卡片分组、键帽、步进器和开关，并新增「打开方式」选择，决定回车是预览还是编辑。
+- **更细腻的交互**：磨砂质感的命令面板、弹性切换动画、选中行指示条、加载骨架，以及 reduced-motion 支持。
+
+## 文件系统：本来就用的是 DSH 自带的
+
+插件里没有另一套文件系统：
+
+| 操作 | 归属 |
+| --- | --- |
+| 遍历、读取、写入工作区文件 | DSH 的 `ctx.fs` 文件系统接口（`index.js`） |
+| 搜索与排序 | 本插件（DSH 没有对外暴露可复用的搜索服务） |
+| 打开与预览文件 | DSH 右侧栏文档预览：`ctx.sidebarRight.openResource()` + `dsh-resource://file/session/<sessionId>/<path>` 地址 |
+| 编辑与冲突检查 | 本插件的编辑器，同样走 `ctx.fs` |
+
+如果原生预览不可用（没有活动会话，或当前界面没有右侧栏），文件查找会自动回退到内置编辑器并给出提示。也可以在 **设置 → 文件查找 → 打开方式** 里把「内置编辑」设为默认动作。
+
+## 默认快捷键
+
+| 操作 | 桌面版 | 网页版 |
+| --- | --- | --- |
+| 按文件名 | ⌘/Ctrl+P | ⌘/Ctrl+P |
+| 按内容 | ⇧⌘F / Ctrl+Shift+F | ⇧⌘F / Ctrl+Shift+F |
+| 切换 Bot / 经典 Agent 模式（仅装了 DS Bot 时） | ⇧⌘B / Ctrl+Shift+B | ⇧⌘B / Ctrl+Shift+B |
+
+三个命令都注册到 DSH 的快捷键服务里，可以在 **设置 → 编辑快捷键** 中另外指定键位，但**不声明默认值**。DSH 的快捷键注册表在检测到默认键位撞车时会在*对方*插件里抛错，会把整个界面启动搞崩（`Conflicting shortcut defaults: session.fork and files.searchContent`）。所以上面的 VS Code 键位由插件自己的按键监听实现。
+
+> 注意：⇧⌘F 在 DSH 里原本是「fork 会话」，本插件按 VS Code 习惯把它用于内容搜索。需要原来的 fork 的话，在「设置 → 编辑快捷键」里给 fork 换一个键即可。
+
+> 网页版（非桌面 App）里 ⇧⌘B 原本是 DSH 的右侧栏开关。装了 DS Bot 时本插件会占用这个组合做模式切换；如果网页版里还需要侧栏开关，在「设置 → 编辑快捷键」里给 `files.toggleBotMode` 换一个键即可。桌面版里这个组合是空闲的。
+
+## DS Bot 模式切换（可选）
+
+当前这次启动里带了 DS Bot 客户端模块（`ds-bot`）时，本插件会额外提供 **切换 Bot / 经典 Agent 模式**（⌘/Ctrl+Shift+B），并在 **设置 → 文件查找** 里多一张对应的卡片。
+
+DS Bot 的模式切换是它自己的私有状态，没有对外暴露客户端服务，所以这个桥接只做两件别家插件能安全做的事：从启动清单里识别 `ds-bot`，以及点击 DS Bot 自己渲染的控件（账号菜单里第二组的那一项用于离开 Bot 模式，DS Bot 的返回按钮用于切回来）。不 patch、不 fork，模式的真实来源仍然是 DS Bot 自己的 `ds-bot:surface` 偏好。
+
+没装 DS Bot 时什么都不会注册或显示：命令不会出现在 **设置 → 编辑快捷键** 里，设置卡片隐藏，⌘/Ctrl+Shift+B 留给原本占用它的功能。
+
+## 设置
+
+**设置 → 文件查找** 包含：
+
+- 快捷键参考和一键试用
+- 区分大小写
+- 额外忽略的目录（输入时实时显示为标签）
+- 文件名 / 内容结果数量上限（步进器）
+- 回车默认动作：**侧栏预览** 或 **内置编辑**
+- DS Bot 模式切换（只有装了 DS Bot 时才出现）
+- 恢复默认设置；修改后自动保存
+
+## 编辑
+
+选中结果后按 ⌘/Ctrl+回车（或把「内置编辑」设为默认动作）打开编辑器。⌘/Ctrl+S 保存；保存使用打开时读到的版本，如果文件期间被别的程序改过，会拒绝覆盖，需要先重新加载。只编辑约 1 MB 以内的 UTF-8 文本。二进制文件，以及 `node_modules`、`.git`、构建目录等，不会进入搜索。
+
+编辑器左边有行号栏，并高亮光标所在行。**⌘/Ctrl+F** 打开文件内查找：所有命中都会高亮、当前命中更醒目，带命中计数、上一个/下一个按钮和 **Aa** 区分大小写开关；回车/⇧回车切换命中，Esc 关闭查找并把焦点交还正文。
+
+## 安装
+
+```sh
+dsh plugin add /Library/aiProject/dsh-file-finder
+```
+
+安装后如果页面没有马上出现入口，刷新 DSH 页面。Agent 也可以调用同名能力：工具 `file_finder`。
+
+仓库：<https://github.com/chzisnull/dsh-file-finder>
+
+## 开发
+
+```sh
+node --check index.js
+node --check client.js
+npm test
+```
+
+`npm test` 覆盖搜索函数、快捷键默认值的防回归测试，以及 UI 契约（原生预览地址、面板钩子、reduced-motion 规则、DS Bot 桥接，以及编辑器的行号栏与文件内查找）。
+
+编辑器另有浏览器检查，分别验证行号和文件内查找：
+
+```sh
+npm run check:find
+```
+
+DS Bot 桥接还有一个浏览器检查，用 DS Bot 真实的类名跑一遍按键逻辑，分别验证启动清单里有 / 没有 `ds-bot` 两种情况：
+
+```sh
+node preview/bot-check.mjs
+```
+
+原生集成的调研结论——地址语法、会话推导、服务获取方式、HMR 行为以及「保留 / 委托」矩阵——记录在 [docs/native-integration.md](docs/native-integration.md)。
+
+`preview/` 是只在开发时使用的预览工程：用真实的 DSH 主题变量在 DSH 之外渲染命令面板与设置页，并用 Playwright 生成明暗两套截图：
+
+```sh
+node preview/screenshot.mjs
+```
+
+它不会被打进发布包。
+
+## License
+
+MIT