本地项目同步0xKcyzz/dsh-local-project

简体中文 | English

DSH Local Project · 本地项目

将本地文件夹导入为服务器 DSH 的工作区，并让 DSH 的修改自动同步回本地文件夹。
适合在浏览器中把本机代码或资料交给远程 DSH 直接读写，同时保留本地副本。

功能特性

- 点击「添加工作区」选择本地文件夹，自动上传并在服务器创建镜像工作区。
- DSH 使用原生 read/write/edit/glob/bash 工具直接操作服务器镜像，无需自定义工具。
- DSH 修改文件后通过 WebSocket 实时同步回本地，断线自动重连并补齐漏掉的变更。
- 删除项目只删除服务器副本与工作区记录，不影响本地文件。
- 刷新页面后可从服务器恢复项目列表，并可重新选择本地文件夹恢复同步。

安装

dsh plugin --profile web add github:0xKcyzz/dsh-local-project

安装后重启 DSH，「添加工作区」会打开本地项目导入对话框。

使用

1. 在 DSH 侧边栏或空状态中点击「添加工作区」。
2. 输入项目名称，点击「选择文件夹并导入」。
3. 在系统对话框中选择本地文件夹（需要 Chrome/Edge 浏览器授权）。
4. 首次导入会开始上传文件；完成后左侧工作区列表出现「本地项目: 名称」。
5. 打开该工作区对话，DSH 操作的是服务器镜像副本，文件改动会自动同步回本地。

限制

- 需要浏览器支持 File System Access API：Chrome / Edge（含 Chromium）。Firefox / Safari 不支持。
- 单个文件上限约 15MB（上传使用 base64 JSON）；超大文件请勿放入项目。
- 不传播单个文件的删除：只有「删除项目」会整包删除服务器副本，本地/服务器各自删除的文件不会被对面清除。
- 本地改动不会自动上传：只有首次导入会上传本地文件；之后本地手改的文件不会同步到服务器。
- 实时推送需要保持 WebSocket 连接；断线会自动重连并补齐漏掉的变更。
- 桌面端 Electron 窗口若 API 不可用，请用系统浏览器打开 DSH 的 Web 地址。

工作原理

- Host 侧：提供 /local-project/* HTTP 接口和 WebSocket 推送，负责创建/上传/删除服务器镜像，并用 fs.watch 监听文件变化。
- Client 侧：填充 DSH 的「添加工作区」目录流，负责选择本地文件夹、上传文件、接收 WebSocket 变更并写回本地。
- 同步方向为 DSH → 本地：服务器文件变化通过 WebSocket 推送，浏览器只下载被改动的文件；不做持续双向同步。

Host 接口

| 接口 | 说明 |
| --- | --- |
| POST /local-project/create | 创建服务器目录 + 工作区记录 |
| POST /local-project/upload | 上传/覆盖服务器文件（base64） |
| GET /local-project/rev | 获取项目变更号 |
| GET /local-project/pull | 获取断线期间漏掉的变更 |
| GET /local-project/list | 列出服务器镜像项目 |
| GET /local-project/manifest | 获取服务器文件清单 |
| GET /local-project/download | 下载服务器文件（base64） |
| POST /local-project/delete | 删除服务器目录 + 工作区记录 |
| GET /local-project/ws | WebSocket 实时变更推送 |

配置（环境变量）

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| DSH_LOCAL_PROJECT_ROOT | $DSH_HOME/workspaces | 本地项目的服务器镜像目录。 |

开发 / 构建

npm install
npm run build   # 产出 lib/index.js（Host）+ lib/client.js（浏览器）

License

MIT