本地文件共享 · Local File Share

让 dsh 的 agent 直接读写你电脑上的文件 —— 不复制进容器，不落在服务器磁盘上。

npm：
GitHub：
Gitee：
精选列表：

一个悬浮卡片，一座桥： 在 dsh 页面里授权一个本地目录，agent 就能用三个模型工具（local_file_list / local_file_read / local_file_write）直接操作它 —— 文件字节经私有 WebSocket 通道在内存里转发，一个字节都不落 dsh 宿主的磁盘。

为什么需要它

dsh 通常跑在容器或远端服务器里，自带的 fs 工具只能摸到宿主机；而你的资料、图纸、手册、代码都在本机。把整个目录塞进容器既慢又占空间（一个安装包镜像就 15 GiB）。

本插件补上这个缺口：浏览器既能看到本机文件，又能连上 dsh，于是让它当桥。

本机磁盘 ──File System Access API──► 你的浏览器页面
                                        │  私有 WebSocket（同源 + 会话校验）
                                        ▼
                              dsh 宿主进程（内存中转发）
                                        │
                                        ▼
                        agent 的三个工具：list / read / write

特性


零占用	不落盘、不缓存、不复制；只有一个在线标签页的内存开销
悬浮卡片	右下角圆钮（40px，跟随主题的 SVG 图标 + 状态点），点一下展开完整面板；可拖动、可拖底部手柄调高度、位置和高度记忆在浏览器本地
主题跟随	视觉全部走 dsh 的 `--dsw-alias-*` token，浅色/深色自动一致；`prefers-reduced-motion` 全量降级
键盘可用	标题行可 Tab 聚焦，方向键移动卡片（`Shift` 加速），`Esc` 收起，双击标题行收起；状态行 `aria-live` 播报
目录树	懒加载、递归搜索、hover 显形「复制路径」；点文件名弹预览窗（图片 / 文本 / 代码语法高亮）
可读可写	完整模式下文本/代码可在预览窗里编辑保存回本机；兼容模式自动降级为只读
多设备	每台开页面的设备各自授权；工具结果带执行设备标签（如 `设备：Windows · Chrome`）
安全	WS 升级同时校验同源与浏览器会话（`connection.requestRejection`），不过即 401/403 关连接；不依赖任何第三方服务

界面

收起：右下角圆钮，右上角状态点用颜色表达连接/授权状态（绿=已授权，黄=待确认，灰=未授权/离线）。
展开：状态行 + 设备昵称（可编辑）+ 授权按钮组 + 「目录内容」树 + 底部高度手柄。
预览窗：钉顶标题栏（文件名 / 大小 / 编辑 / 关闭）、路径行、独立滚动内容区，可拖动可缩放。

视觉截图：docs/screenshot-upstream.png 是上游版本（dsh-browser-fs）的界面，仅作功能示意；本版本的主题化界面截图待补。

原理

双面插件（cordis 体系）：

host 半（src/index.ts，跑在 dsh 宿主 Node 进程）
- ctx.webServer.registerUpgrade 注册精确路径 /local-file-share/ws 的 WebSocket；
- ctx.tools.register 注册 local_file_list / local_file_read / local_file_write；
- 工具调用打包成 {type:'call', rpcId, op, args} 帧发给持有授权句柄的标签页，按 rpcId 配对 result 帧；exec.signal 接 abort（同时给浏览器发 cancel 帧）；
- 同目录派生 /local-file-share/highlight.mjs 路由，按需供给语法高亮 chunk。
client 半（src/client/，跑在浏览器）
- 启动从 IndexedDB 读回目录句柄并 queryPermission，连回 host 的 WS（断线指数退避重连）；
- 收到 call 帧后用 File System Access API 执行，回发 result 帧；
- 在 shell.overlay 注册悬浮卡片，状态变化时广播 {type:'state', hasHandle, dirName, label}；
- 多标签页在线时，host 只把调用派给 hasHandle=true 的标签页。

安装

# 1) 从 npm 安装（推荐：零脚本、无需构建授权）
dsh plugin --profile web add dsh-local-file-share

# 2) 直接从 GitHub 安装（lib/ 构建产物入库，安装零脚本）
dsh plugin --profile web add github:deepseekharness-dsh/dsh-local-file-share

# 3) 从 Gitee 镜像安装（同一份产物）
dsh plugin --profile web add git+https://gitee.com/deepseekharness/dsh-local-file-share.git

# 4) 本地开发：改代码后重装（改动需先 npm run build，产物 lib/ 已入库）
npm install && npm run verify
dsh plugin --profile web add file:/abs/path/to/dsh-local-file-share

安装后重启 dsh（宿主半需要重新加载模块与路由），重新打开页面即可看到右下角圆钮。

快速上手

打开 dsh web 页面 → 右下角圆钮 → 「授权目录」→ 在系统对话框里选一个目录。浏览器会询问读写权限（插件按当前「权限」设置请求 readwrite；选「只读」时请求 read）。
直接对 agent 说：“列一下我授权目录里的内容”，它会调用 local_file_list。
之后可以：读某个文件（local_file_read）、写入或新建文件（local_file_write），也可以在卡片里点文件名自己预览。

工具参考

工具	参数	返回
`local_file_list`	`path?`（相对授权根，省略=根）、`recursive?`（默认 false）	目录条目：相对路径、类型、大小（递归时含全部层级）
`local_file_read`	`path`（必填）、`maxBytes?`（默认 256 KiB，超出标注截断）	文本内容（UTF-8）
`local_file_write`	`path`、`content`（自动创建父目录；同名覆盖）	写入字节数

三个工具的描述里都写明：操作对象是浏览器所在机器的本地磁盘，不是 dsh 宿主机。多设备同时持柄时，结果会标注执行设备。

共享范围与读写权限

默认是全局共享 + 可读可写（不配置时的行为与 1.0.0 一致）。想收紧时，在卡片上直接改：

设置	取值	说明
共享范围	全局（默认）	同一 dsh 实例内所有会话都能用这三个工具
	指定会话	只有在列表里勾选的会话能用；卡片标题行的徽标会显示当前范围
权限	读写（默认）	列目录、读文件、写文件
	只读	只放行列目录与读文件；写入一律拒绝

要点：

三层强制，不是 UI 提示：① 选「只读」时授权请求 mode: 'read'，浏览器层面就拿不到写权限； ② 客户端收到写指令先按策略拒绝，根本不去碰 File System Access；③ host 侧（唯一权威）不满足策略不派发，并返回带"去哪改"的错误。
改了就生效：策略存在浏览器本地（localStorage['dsh-local-file-share:share-policy']），随状态帧上报给 host；host 不持久化、重启不丢。解除授权会一并清除策略（下次授权回到默认）。
"指定会话"下的子代理/团队成员：它们的会话 id 与发起会话不同，不会自动被覆盖。卡片列表里子代理会标注；需要时手动勾选，或直接用「全局」。
非会话调用者（不来自任何会话的调用）：指定会话 模式下会被拒绝，错误里说明如何放开。
会话内小条：切到「指定会话」后，每个会话输入框上方会出现一条小条，一键「加入本会话 / 移出本会话」—— 根卡片不知道"当前会话是谁"，小条知道，两者互补；全局模式下小条不出现。
升级到 1.1.0 无需重新授权。

安全模型

授权范围：只有你主动选中的那一个目录（及其子树）可见，插件拿不到目录之外的路径；共享范围与权限见上一节（默认全局 + 读写，可收紧到指定会话 / 只读）。
权限语义：写入只在你（或 agent）明确调用、且策略允许时发生。File System Access API 不允许插件在没有用户手势的情况下重新授权。
连接校验：WS 升级先做同源（Origin 与 Host 一致）与浏览器会话（connection.requestRejection）双重校验，不通过直接 401/403 关闭 —— 别的站点无法挂在你的会话上。
数据流向：字节只在「你的浏览器 ↔ 你的 dsh 宿主」之间流动，不经过任何第三方服务。
页面必须在场：没有标签页在线时，工具调用立即返回明确错误，不会静默挂起。

兼容性与限制

	完整模式	兼容模式（自动降级）
触发	HTTPS 或 `localhost`（安全上下文）	纯 HTTP 局域网访问等
选择方式	`showDirectoryPicker` 系统目录选择器	`input[webkitdirectory]` 选目录 / 多选文件
list / read	✅	✅（只读快照）
write	✅	❌ 明确报错
授权持久化	✅ IndexedDB，刷新自动恢复	❌ 刷新需重选

句柄随刷新失效是浏览器安全模型决定的（权限不跨会话持久时需重新授权），不是 bug；
跨域 iframe 里不能弹目录选择器，被嵌套时请到顶层页面授权（卡片会给出直达链接）；
移动端：华为浏览器等可能报"可用"但点击无反应，插件会自动退到兼容模式的多选入口；
只在 UTF-8 文本读写范围内工作（二进制写入不在范围；图片仅在卡片内预览）。

开发

npm install
npm run build       # node build.mjs → lib/（host ESM + client CJS 闭包 + 高亮 chunk）
npm run typecheck   # tsc --noEmit
npm run smoke       # 协议往返 / abort / 断连 / 跨源拒绝 / 钳位纯逻辑
npm run verify      # 上面三步串起来（prepublishOnly 也走它）

lib/ 是入库产物：改完代码必须先 npm run build 再提交，否则发出的包是旧代码。

目录地图（src/client/）：

文件	职责
`index.ts`	client 入口、WS 重连、帧分发、卡片数据源
`ui.tsx`	悬浮卡片 / 目录树 / 预览窗（React JSX）
`styles.ts`	主题化样式层（注入式样式表 + `lfs-` 类名体系）
`fs.ts` / `files-backend.ts`	File System Access 操作与后端抽象
`store.ts`	IndexedDB 句柄存取
`preview.ts` / `highlight.ts`	预览判定与代码着色
`compat-picker.ts`	无 File System Access API 环境的降级选择器
`device.ts` / `i18n.ts`	设备标签 / 跟随 dsh 语言的中英文案
`panel-fit.ts`	悬浮面板定位防出界

发布与上架

维护者文档：完整清单见 docs/publishing.md。

npm：npm run verify → 改版本号 → 提交 → 打同号 tag（如 v1.0.1）→ GitHub Actions .github/workflows/publish.yml（校验 tag 与版本号一致 + 跑测试后 npm publish）。本机手动兜底见 docs/publishing.md。
GitHub：（主仓库，已带 dsh-plugin topic）。
Gitee：（代码镜像与国内分发； npm 包仍发布在 npmjs，插件市场按 npm 包名安装）。
插件市场：dshmarket 的安装来源只认 curated registry awesome-dsh-plugin —— 往那个仓库提一个 PR，新增 data/plugins/deepseekharness-dsh__dsh-local-file-share.yml （内容见 publish/awesome-dsh-plugin.yml）。不要往 dshmarket 主仓库提插件条目。

许可与出处

MIT。LICENSE 里保留了上游署名与衍生说明。

本仓库是 dsh-browser-fs（作者 whitefirer，MIT）的衍生版本：WS 中继协议、host/client 双半结构、 File System Access 后端、语法高亮 chunk、兼容模式选择器、多设备 roster 均来自上游；本版本在其上完成了更名、主题化视觉层、交互与可达性补强，以及 WS 会话校验加固。详见 CHANGELOG.md。

dsh-local-file-share

安裝

說明文件