# 安装与开始使用

## 先试用工作台

本仓库需要 Node.js 24 或更新版本。克隆后运行 `npm ci`，然后运行 `npm run preview:workbench`，打开返回的地址。预览使用独立临时目录，不读取你的日常作品，也不提供真实模型对话。

也可以用自己的单本作品备份创建试用副本：

```powershell
npm run preview:workbench -- "C:\你的备份目录\作品.cuigengji.json"
```

修改只写入临时副本。要保留内容，请在预览工作台中导出。

## 安装到 DSH Windows 桌面版

当前已验证 DSH 0.2.0-rc.2，其他版本请先核对发布说明。0.4.1 起，仓库随源码提供编译后的安装文件，支持 DSH 官方 GitHub 地址安装；同时继续提供[成品安装包](https://github.com/mistnest/dsh-cuigengji-plugin/releases/latest)。

1. 从 DSH 左侧进入“插件”，点击“添加插件”。
2. 在“包名或地址”输入 `https://github.com/mistnest/dsh-cuigengji-plugin`。
3. “安装源”保持默认，或选择 npm 官方源 / 中国大陆镜像源；它用于下载依赖，不填写 GitHub 仓库地址。
4. 点击“安装”，完成后按 DSH 提示完整重启，从左侧“催更姬”进入。

使用固定发布版本时，也可将成品 `.tgz` URL 或下载后的 Windows 绝对路径填入同一个“包名或地址”输入框。也可以把[Windows Agent 安装指南](agent-installation.md)交给 DSH 的 Agent 完成安装、重启和校验。升级会自动备份并迁移已有数据，详见[更新说明](upgrade.md)。本项目尚未发布 npm 包，不直接填 `dsh-cuigengji` 作为安装目标。

### 开发者本地安装

下面的源码构建流程仅供开发维护使用。

1. 安装并启动过 DSH 桌面版，让它创建 `desktop` profile。
2. 克隆本仓库，进入项目目录，执行 `npm ci`。
3. 从 DSH 菜单退出应用，包括托盘进程。
4. 运行安装脚本，将参数换成你实际的 DSH 可执行文件路径：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\install-desktop.ps1 -DesktopExe "C:\你的DSH安装目录\DeepSeek Harness.exe"
```

脚本构建并打包插件，使用 DSH 自带的 Node/pnpm 安装到 `%USERPROFILE%\.dsh\profiles\desktop`。如果自定义过 DSH Home，请额外传入 `-DshHome "你的DSH数据目录"`。打包文件存于项目内 `releases`，不包含小说工作数据。

5. 首次安装时，在 `desktop` profile 的 `package.json` 中找到 `dsh.profile.bundles`，保留已有内容并加入 `"dsh-cuigengji"`。更新已启用的插件无需重复添加。
6. 通过 DSH 自己的快捷方式重新启动，从左侧栏的“催更姬”进入。

若找不到可执行文件，可查看桌面快捷方式的属性。不要用 CLI 创建或替换名为 `desktop` 的 profile；桌面 profile 由 DSH 桌面应用管理。

## 开始一起写

先创建或选择作品。你在当前会话选中的作品会成为 AI 的写作项目，可以直接告诉它：

> 先看看这本书的正文和相关设定，和我讨论下一章怎么推进，暂时不要续写。

> 把我们确定的走向更新到规划里，接在当前情节后面。

> 按这条规划续写下一章，保持人物动机和世界规则一致。

正文可直接编辑；规划支持多页、分组、拖拽连线和批注；设定支持角色卡、世界书、分组和关系图。写作预设在设置里，启用后作为该作品的写作要求提供给绑定会话。

## 作品保存在哪里

“工作数据 · 导入/导出”会显示实际保存位置。默认目录：

- Windows：`%LOCALAPPDATA%\cuigengji`
- Linux/macOS：`$XDG_DATA_HOME/cuigengji`；没有设置时使用 `~/.local/share/cuigengji`

Windows 桌面版是当前主要验证环境；其他系统的默认目录已实现，但本次没有完成宿主适配验收。

如需修改位置，可在 desktop profile 的插件配置中设置 `dataRoot`，或使用 `CUIGENGJI_DATA_ROOT` 环境变量。优先级为插件配置、环境变量、默认目录。配置不会自动搬运已有作品，请先导出备份，切换位置后在工作台导入。

不要把源码或插件安装目录作为小说目录。代码升级、Git 提交和 npm 打包都不应携带你的作品。

## 备份与迁移

- **作品与备份**：导出或恢复单本作品，包括正文历史、设定、规划和预设。
- **工作数据 · 导入/导出**：导出整个小说工作数据，导入前会展示预览和冲突，保存导入前快照。
- 同 ID、同内容会跳过；同 ID、不同内容不会直接覆盖。
- DSH 聊天记录、附件、账号配置和浏览器未保存草稿不属于小说备份。迁移 DSH 时需要另外处理。

升级前建议导出一份工作数据；不要用旧备份覆盖升级后新增的正文。详细存储边界见[架构说明](architecture.md)。

## 常见问题

**安装后没有入口**：检查 desktop profile 的 bundles 是否包含 `dsh-cuigengji`，并完全退出、重启 DSH。脚本安装成功不代表正在运行的应用已经加载新插件。

**提示版本冲突**：保留草稿，读取最新内容后比较。不要修改版本号强行覆盖另一会话或 AI 的修改。

**找不到以前的作品**：检查“工作数据”显示的实际目录，再从旧环境导出备份。切换数据目录不会自动迁移。

**酒馆文件导入后效果不同**：我们保留资料和提示词内容，不运行酒馆的触发与装填规则；导入后检查和编辑内容，再启用预设。见[导入说明](tavern-import.md)和[预设说明](presets.md)。