moyu-ghost 使用说明（小白完整版）

moyu-ghost 是一个命令行小说阅读器。
它支持读取 .txt 和 .epub 文件，界面看起来像前端构建日志，适合在终端里低调阅读。

1. 软件能做什么（功能总览）

• 读取本地小说文件：支持 .txt、.epub
• 自动记住阅读进度：下次打开可续读
• 手动翻页：上一行、下一行
• 自动翻页：可开启/关闭，可调速度
• 目录跳转：分页浏览目录，按章节号或目录序号跳转
• 智能起读：首次打开时可自动跳过开头目录，直接到正文附近
• 两种退出方式：
  • Esc 正常退出
  • Ctrl + C 触发“伪装报错”后退出（也会保存进度）

2. 使用前准备

2.1 安装 Node.js（只需一次）

本软件依赖 Node.js 18+。

1. 打开终端（Windows 可用 PowerShell）。
2. 输入以下命令检查：

node -v
npm -v

如果能看到版本号（如 v18.x、9.x 或更高），说明环境正常。

2.2 安装软件（只需一次）

npm i -g moyu-ghost

安装完成后，建议直接执行初始化命令进行确认：

moyu-ghost-init

如果提示找不到命令，先关闭终端再重新打开，再重试。

3. 第一次使用（一步一步）

第 1 步：初始化数据目录

moyu-ghost-init

运行后会看到类似：

• app home: ...
• data path: ...
• session file: ...

其中 data path 就是你要放小说文件的文件夹。

【截图占位：初始化命令运行结果】

第 2 步：把小说文件放进数据目录

把你的 .txt 或 .epub 文件复制到 data path 对应的目录中（通常是 .../.vs-ghost/logs_data）。

【截图占位：logs_data 文件夹中已有小说文件】

第 3 步：启动阅读器

moyu-ghost

程序会列出可选文件，例如：

1. 小说A.txt
2. 小说B.epub

输入编号（例如 1）后按回车开始阅读。

【截图占位：文件选择界面】

4. 阅读时怎么操作（按键说明）

启动后，常用按键如下：

• Down（下方向键）：下一行
• Up（上方向键）：上一行
• a：开启/关闭自动翻页
• Space（空格）：暂停/恢复自动翻页
• [ / Left / -：自动翻页减速
• ] / Right / =：自动翻页加速
• t：打开目录跳转（TOC）
• Esc：正常退出
• Ctrl + C：触发伪装报错并退出（Boss Key）

【截图占位：阅读界面与按键提示】

5. 自动翻页怎么用

1. 按 a 开启自动翻页。
2. 按 [ 或方向键左降低速度（更慢）。
3. 按 ] 或方向键右提高速度（更快）。
4. 按 Space 可暂停，再按一次 Space 可恢复。
5. 再按一次 a 可关闭自动翻页。

说明：

• 速度单位是“每秒汉字数（han-chars/s）”。
• 你调整后的速度会自动保存，下次继续生效。

【截图占位：自动翻页开启/调速提示】

6. 目录跳转怎么用（t 键）

1. 按 t 打开目录列表。
2. 按提示输入并回车：
   • 输入 n / p 可翻到下一页 / 上一页目录
   • 输入章节号（如 12），会优先按“第12章”匹配
   • 输入目录序号（如 #3），跳到第 3 条目录
3. 留空直接回车可取消跳转。

如果书里没有识别到目录，程序会提示 no chapters detected。

补充：如果这本书没有历史进度，且开头存在大段“目录页”，程序会自动把起始位置定位到正文第一章附近。

【截图占位：目录列表与跳转输入】

7. 阅读进度保存规则

• 每本书的阅读行号会自动保存。
• 下次再次打开同一本书，会从上次位置继续。
• 进度文件位置：<app home>/.ghost-session.json

一般不需要手动修改这个文件。

8. 文件与目录位置说明

默认目录（Windows）通常在：

C:\Users\你的用户名\.vs-ghost

其中：

• logs_data：放小说文件
• .ghost-session.json：阅读进度

9. 自定义存储路径（可选）

如果你不想用默认目录，可以设置环境变量 VS_GHOST_HOME。

PowerShell 示例：

$env:VS_GHOST_HOME = "D:\my-vs-ghost"
moyu-ghost-init
moyu-ghost

设置后，数据目录会变成：

D:\my-vs-ghost\logs_data

【截图占位：自定义路径后的初始化输出】

10. 常见问题（新手必看）

Q1: 启动后提示找不到文件

提示类似：no .txt/.epub files found

处理：

1. 确认你已经运行过 moyu-ghost-init
2. 确认小说确实在 logs_data 目录内
3. 文件后缀必须是 .txt 或 .epub

Q2: 输入命令提示“不是内部或外部命令”

处理：

1. 确认已执行 npm i -g moyu-ghost
2. 关闭并重开终端
3. 再试一次 moyu-ghost-init

Q3: 中文显示异常或章节识别不准

处理：

1. 优先使用 UTF-8 编码的 .txt
2. 尝试换 .epub 版本
3. 目录识别依赖原标题格式，个别书可能识别不到完整目录

11. 卸载软件

npm uninstall -g moyu-ghost

12. 兼容命令（旧名称）

以下命令与新命令等价，可继续使用：

• vs-ghost = moyu-ghost
• vs-ghost-init = moyu-ghost-init

13. 直接交给 AI 帮你操作（可复制）

你可以把下面内容发给 AI 助手，让它一步步指导你：

你是我的电脑操作助手。请用“每次只让我做一步”的方式，指导我完成 moyu-ghost 使用：
1) 检查 node 和 npm 是否安装
2) 安装 moyu-ghost
3) 初始化目录并告诉我 logs_data 在哪里
4) 让我把 txt/epub 文件放进去
5) 启动并教我按键（上下、a、[]、t、Esc、Ctrl+C）
6) 教我如何调自动翻页速度和目录跳转
7) 最后帮我排查常见报错
要求：每一步都先等我回复“完成”再继续下一步。

如果你希望 AI 直接给出命令，也可以追加一句：

我使用的是 Windows PowerShell，请给我可直接复制执行的命令。