# 📦 Readmake 换机迁移与分发指南

> 适用：把 Readmake 插件 + 阅读数据迁移到另一台电脑，或分发/安装到其他 DSH 环境
> 更新：2026-08-19

---

## 一、数据都在哪里（重要）

插件所有**用户数据**都存放在 DSH 家目录下，**与代码分离**：

```
~/.dsh/readmake/
├── config.json                 ← 配置文件（换机主要改这里）
└── data/                       ← 数据目录（拷贝这一个文件夹 = 全部带走）
    ├── progress.json           ← 阅读进度
    ├── annotations/            ← 高亮/批注（每本书一个文件，按路径哈希命名）
    │   ├── a1b2c3d4e5f6.json
    │   └── …
    └── uploaded/               ← 通过「添加书籍」上传的书
```

`config.json` 结构：

```json
{
  "version": 1,
  "dataDir": "~/.dsh/readmake/data",     // 数据目录（支持 ~ 前缀）
  "scanDirs": ["~/Desktop"]              // 书架扫描目录（可多个）
}
```

> 首次运行会自动生成默认配置（数据目录 + 扫 `~/Desktop`）。

---

## 二、换机迁移步骤（新电脑）

### 1. 旧电脑：拷贝数据

把 `~/.dsh/readmake/` 整个文件夹拷走（U 盘 / 网盘 / Git 均可）。

> 另外别忘了你的 **PDF 书籍文件**本身——插件只打开它们，书不自动跟着走。

### 2. 新电脑：安装插件

见下方「三、安装到其他电脑」。

### 3. 新电脑：放回数据

把拷来的 `readmake/` 放到新电脑的 `~/.dsh/` 下（即 `~/.dsh/readmake/`）。

### 4. 新电脑：改配置（如需）

编辑 `~/.dsh/readmake/config.json`：

| 字段 | 说明 | 默认 |
|---|---|---|
| `dataDir` | 数据目录（一般不用改） | `~/.dsh/readmake/data` |
| `scanDirs` | 书架扫描目录，改成新电脑上你放书的地方 | `["~/Desktop"]` |

```json
{
  "version": 1,
  "dataDir": "~/.dsh/readmake/data",
  "scanDirs": ["~/Desktop", "~/Documents/Books"]
}
```

### 5. 重启应用

**⌘Q 完全退出 → 重新打开**（配置/数据在 Host 端加载，必须重启）。

> 新电脑上如果 PDF 的路径和旧电脑不同，书架里「路径添加」的书需重新添加；扫描目录能自动发现新位置的书。

---

## 三、安装到其他电脑（三种方式）

### 方式 ①：打包传输（最简单，无网络依赖）

```bash
# 在项目目录打包
pnpm pack          # 生成 dsh-book-reader-<版本>.tgz
```

把 `.tgz` 拷到目标机：

```bash
dsh plugin --profile desktop add dsh-book-reader-0.1.0.tgz
```

### 方式 ②：GitHub 仓库（私人库也可以）

1. 把项目推送到 GitHub（**记得提交 `lib/` 构建产物**，或配置 `prepare` 脚本）
2. 目标机安装：

```bash
# 公开库
dsh plugin --profile desktop add github:你的用户名/dsh-book-reader

# 私人库（需配置 SSH key 或 token）
dsh plugin --profile desktop add git+ssh://git@github.com:你的用户名/dsh-book-reader.git
```

> `dsh plugin add` 本质是 pnpm 安装：git 源仓库需有 `prepare` 脚本自动构建
> （`"prepare": "pnpm build"`），否则目标机没有 `lib/` 产物会失败。

### 方式 ③：npm 发布（最正式）

```bash
# 发布（需 npm 账号）
npm publish --access public    # 或 private registry

# 目标机安装
dsh plugin --profile desktop add dsh-book-reader@<版本>
```

---

## 四、上架插件平台（可选）

| 渠道 | 方式 |
|---|---|
| npm | 发布后加 `dsh-plugin` 关键词 |
| GitHub topic | 仓库打 `dsh-plugin` topic → 被 [Oh-My-DSH](https://github.com/like-study1/Oh-My-DSH) 等聚合目录收录 |
| dshfind.com | 插件目录站，提交收录 |
| 官方仓库 | [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) Discussions 宣传 |

---

## 五、常见问题

| 问题 | 解决 |
|---|---|
| 换机后书架是空的 | 检查 `scanDirs` 是否指向新电脑上放书的位置；PDF 是否已拷过去 |
| 高亮/进度丢了 | 确认 `~/.dsh/readmake/data/` 已完整拷到新电脑 |
| 改配置后不生效 | 配置在 Host 加载，需**重启应用**（光刷新不够） |
| 「路径添加」的书打不开 | 新电脑上该路径的 PDF 需存在；或重新添加 |
| 想换数据目录 | 改 `config.json` 的 `dataDir`，把旧数据移到新目录，重启 |

---

## 六、相关文档

- 设计 Brief：`docs/opendesign-brief.md`
- 需求文档：`docs/需求文档.md`