dsh-local-project

Readme

<p align="center">
  <strong>简体中文</strong> | <a href="README_EN.md">English</a>
</p>

<p align="center">
  <img alt="License" src="https://img.shields.io/badge/license-MIT-0B7285?style=flat-square">
  <img alt="DSH Plugin" src="https://img.shields.io/badge/DSH-Plugin-5B4CF0?style=flat-square">
  <img alt="Platform" src="https://img.shields.io/badge/platform-Web-4B6FFF?style=flat-square">
  <img alt="Sync" src="https://img.shields.io/badge/sync-WebSocket-00B8A9?style=flat-square">
  <img alt="File System Access" src="https://img.shields.io/badge/API-File%20System%20Access-4B6FFF?style=flat-square">
</p>

# DSH Local Project · 本地项目

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

## 功能特性

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

## 安装

```bash
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` | 本地项目的服务器镜像目录。 |

## 开发 / 构建

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

## License

[MIT](LICENSE)