Skip to main content
Glama
README.md
# QwenGlass-Reader:在千问 AI 眼镜上看自己的 TXT 小说

![两个版本的功能演示:滑动翻页、菜单、章节跳转、自动翻页、字号、粗细、亮度、行距、语音指令、智能翻页、听书、段落标记](docs/demo.gif)

<sub>一张图里是两个版本的功能:没有标签的两个版本都有,标了「页图版」「文字版」的只有那个版本有。在本地模拟器里录的,模拟器和千问开放平台的页面预览用同一个渲染内核,书是自带的原创示例。每格右上角的绿标是这一下做的手势,下面一行是说的话和眼镜的回答。调设置的几格从打开设置面板开始。模拟器的计时比真机慢,自动翻页那一格按真机的节奏加快了。</sub>

这个仓库有两个分支,是同一个阅读器的两种接入方式。现在看的是 `main`(页图版),文字版在 [`agent`](https://github.com/Edint386/QwenGlass-Reader/tree/agent) 分支,能听书、智能翻页。两个版本可以各跑一个实例,挂同一个书库和进度目录,换个 Skill 接着读。

## 两个版本能做什么

| | 页图版(`main`,本分支) | 文字版(`agent`) |
|---|---|---|
| 平台上怎么接入 | MCP 插件 + Skill | Agent 自定义接入(WebSocket) |
| 平台要不要开通 | 不用 | 账号要先开通「自定义接入」白名单 |
| 正文怎么显示 | 服务把每页画成图片 | 眼镜的原生文字 |
| 滑动翻页 | ✅ 约 1 秒一页,每页要下载一张图 | ✅ 立即响应 |
| 菜单 | ✅ | ✅ |
| 章节跳转 | ✅ 菜单里滑动选章,面板上显示章名;也能语音说第几章 | ✅ 菜单里滑动选章,面板上显示第几章;也能语音说第几章 |
| 自动翻页 | ✅ 每页停 1~30 秒 | ✅ 每页停 1~30 秒 |
| 智能翻页:按这一页的字数算停多久 | ❌ | ✅ 每秒 4~60 字 |
| 听书 | ❌ | ✅ 平台朗读,页面跟着翻 |
| 语音指令 | ✅ 经过大模型,说法随意,要等几秒 | ✅ 不经过大模型,只认固定说法,立即执行 |
| 字号 | ✅ 16~32,九档 | ✅ 16~32,七档 |
| 粗细 | ✅ 六档 | ✅ 常规、粗体 |
| 行距 | ✅ 五档 | ❌ 固定 |
| 亮度(页面遮罩) | ✅ 10%~100% | ✅ 10%~100% |
| 真机亮度(眼镜本身) | ❌ | ✅ 0~100,平台下发了调亮度的工具才能用 |
| 段落标记 | ❌ | ✅ 圆点、竖线、下划线、圆角框 |
| 缺字 | 不缺:服务用自己的字体画 | 眼镜字体里没有的字显示成空白 |
| 阅读进度 | 存在服务上,两个版本共用 | 同左 |

## 怎么工作

服务读 TXT、分章、分页,把每页画成适合眼镜绿色屏幕的图片(478×290,4 级灰度)。眼镜上的页面用镜腿滑动翻页,翻页不经过大模型:页面直接下载下一张页图,这个请求本身就记下了阅读进度。打开书、换书、跳章、问读到哪了,靠语音让大模型调 MCP 工具。说“下一页”“字大一点”也行,大模型调完工具会重新打开页面,要等几秒。

| 路径 | 内容 |
|---|---|
| `glassreader/` | 服务的 Python 源码:读 TXT、切章(`book.py`)、分页和画页图(`pager.py`)、书库和进度(`library.py`)、MCP 工具(`mcp_tools.py`)、HTTP 服务(`server.py`) |
| `skill/` | 千问平台上 Skill 的文件,结构和平台编辑器一样:`SKILL.md`、`ui_schema.json`、`Pages/reader/` |
| `deploy/` | `Dockerfile`、`compose.yaml` 和反向代理配置示例 `site.conf` |
| `docs/demo.gif` | 上面的演示图 |

代码注释里提到的 `docs/research.md` 是开发笔记,没有放进这个仓库。

## 部署指南

要准备三样东西:

- 一台公网服务器和一个 HTTPS 域名。平台调 MCP、手机下载页图都走公网,证书要正规(Let's Encrypt 就行)。
- 一个[千问开放平台](https://device.qianwen.com)账号。第一次登录会自动注册,按提示做个人实名认证。
- 一副千问 AI 眼镜。

### 第一步:配置

复制 `.env.example` 为 `.env` 填好。优先级:命令行 > 环境变量 > 默认值。

| 变量 | 说明 |
|---|---|
| `READER_TOKEN` | 平台 MCP 插件的 Bearer Token。不填每次启动随机生成,平台插件会失效 |
| `READER_KEY` | 页图地址里的随机段:眼镜发不了请求头,页图只能靠路径鉴权。只用字母、数字、`-` 和 `_` |
| `READER_PUBLIC_URL` | 眼镜和平台访问的公网根地址,如 `https://reader.example.com`,可以带路径前缀。不填只能本机调试 |
| `READER_BOOKS_DIR` | TXT 书库目录,递归收集 `*.txt`,扩展名不分大小写(默认 `~/Books`) |
| `READER_STATE_FILE` | 进度文件(默认 `~/Library/Application Support/glassreader/progress.json`) |
| `READER_HOST` / `READER_PORT` | 监听地址(默认 `127.0.0.1:8780`) |
| `READER_SWAP_SWIPE` | `1` = 前滑、后滑方向对调,真机方向和预期相反时用 |
| `READER_ALLOWED_HOSTS` | MCP 额外放行的 Host 头,逗号分隔 |

TXT 支持 UTF-8 和 GBK/GB18030,章节标题自动识别(“第 N 章”“序章”“Chapter 12”这类)。

### 第二步:部署到服务器

1. 在仓库根目录复制 `.env.example` 为 `.env`,填 `READER_TOKEN`、`READER_KEY`(各一串随机字符),`READER_PUBLIC_URL` 填你的域名。
2. 准备书库和进度目录。容器里的用户是 10001,进度目录要它能写:

   ```bash
   cd deploy && mkdir -p books data && sudo chown 10001:10001 data
   ```

3. 把 TXT 放进 `deploy/books/`,启动:

   ```bash
   docker compose up -d --build
   ```

   服务只监听本机的 `127.0.0.1:19516`,根文件系统只读,内存上限 256 MB。
4. 反向代理照 `deploy/site.conf` 配:80 端口只放行证书校验,443 只转发 `/healthz`、`/r/`(页图)、`/mcp`(平台),其余 404。示例里证书和日志的路径是 1Panel OpenResty 的写法,按你的服务器改。
5. 打开 `https://你的域名/healthz`,返回 `ok` 就通了。

### 第三步:在千问开放平台上配置

页图版在平台上是一个 MCP 插件加一个 Skill,都不用申请开通。仓库里的文件这样放:

| 仓库里的文件 | 放到平台上的哪里 | 怎么放 |
|---|---|---|
| 无 | MCP 插件 | 在网页上填表,见下面第 1 步 |
| `skill/SKILL.md` | Skill 编辑器里的 `SKILL.md` | 整篇复制粘贴,再把里面的 `READER` 全部换成你的 MCP 插件编码 |
| `skill/ui_schema.json` | Skill 根目录的 `ui_schema.json` | 内容保持 `[]` |
| `skill/Pages/reader/template.xml` | `Pages/reader/template.xml` | 新建页面 `reader`,名字要一样(SKILL.md 按这个名字打开页面),整篇复制粘贴 |
| `skill/Pages/reader/data.json` | 同一个页面的 Mock 数据 | 复制粘贴,只用来预览 |
| 无 | `tool_schema.json` | 保存 SKILL.md 后平台自动生成 |

**1. 新建 MCP 插件**

在「资源库 → MCP 插件」新建:

| 字段 | 填什么 |
|---|---|
| 名称、描述 | 随意,比如“小说书架” |
| 基础 URL | `READER_PUBLIC_URL`,如 `https://reader.example.com` |
| 端点路径 | `/mcp` |
| 传输协议 | 无状态(文档里叫“无状态 HTTP”) |
| 认证方式 | Bearer Token,填 `READER_TOKEN`,只填 Token 本身,平台会自己加 `Bearer` |

保存时平台会马上连你的服务拉工具,应该拉到 5 个:`list_books`、`open_book`、`jump`、`reading_status`、`set_font_size`。拉不到时:

- 报错连不上:先用浏览器打开 `https://你的域名/healthz`,看是不是 `ok`。
- 工具数是 0:多半是 Token 填错了,改好后在插件详情里点「刷新 MCP 工具」,在弹出的「同步服务端工具」里点「确认同步」。
- 服务只认 `READER_PUBLIC_URL` 里的域名,这是为了防 DNS 重绑定。平台填的地址要和它一致,别的域名加进 `READER_ALLOWED_HOSTS`。

保存后,在插件详情里记下「插件编码」(6 位字母和数字,形如 `AbC123`),下一步要用。

**2. 新建 Skill「眼镜看小说」**

在「Skill 开发 → 创建 SKILL」里选空白创建:

- 名称:`眼镜看小说`。
- 标识:只能用字母、数字和中划线,建好以后不能改。
- 描述:写清楚什么时候用这个 Skill,平台靠它决定你说的话要不要进来。可以照抄 `skill/SKILL.md` 开头的 description。

然后按上面的表把文件放进去:

- `SKILL.md` 里调工具的地方写成 `^^READER.open_book^^` 这样的工具卡片。粘贴后把 `READER` 全部替换成插件编码,保存后就变成卡片。
- 打开页面用的是平台官方的「UI页面渲染」工具(`^^tQ8fCF.ui_page_render^^`)。如果这张卡片在你的编辑器里显示不出来,用 SKILL.md 右上角的「工具」按钮重新插入「UI页面渲染」。

**3. 预览**

打开页面后,右侧选「千问 AI 眼镜 S1」,切到「Mock」看 `data.json` 的效果。预览只运行已经保存的文件,也不下载页图,页图只能在真机上看。还可以在编辑器里对 AI 说“看小说”,确认它先调 `open_book`、再调 UI 页面渲染。

**4. 真机测试**

1. 在「设备管理」里添加眼镜(一键绑定,或用千问 AI 穿戴 App「我的 → 扫码」),打开开发者模式。
2. 在 Skill 编辑器顶部点「真机测试」,选你的眼镜。之后这副眼镜用的就是编辑中的版本,直到解绑或关掉开发者模式。
3. 对眼镜说“看小说”。

自己用不需要发布:MCP 插件和 Skill 都是草稿时,真机测试就能正常用。发布只影响没有绑定测试的设备。真要发布的话,范围选「个人私有」;Skill 发布前,它引用的插件也要先发布,而插件发布后就锁定了,连 Token 都改不了,只能删了重建。

改了页面以后,眼镜上要退出再打开才会用上新页面。升级到新版本时,先部署服务,再在插件详情里「刷新 MCP 工具」→「确认同步」,把新加的工具同步进插件(比如字号的 `set_font_size`),最后重新粘贴 `SKILL.md` 和页面。

### 在电脑上运行

本地跑起来主要是为了调试。需要 Python 3.12 和 [uv](https://docs.astral.sh/uv/)。排版在 macOS 上用系统自带的冬青黑体和宋体,在 Linux 上要装 `fonts-noto-cjk`。

```bash
uv sync
```

```bash
uv run glassreader serve --books ~/Books --state .state/progress.json
```

不想装 uv,`pip install .` 之后直接运行 `glassreader serve` 也行。其他子命令:`glassreader books` 列出书库和进度,`glassreader open [书名]` 打印一份可以贴进模拟器的 dataSource。

## 眼镜上的操作

| 状态 | 前滑 / 后滑 | 单击 | 双击 |
|---|---|---|---|
| 阅读 | 下一页 / 上一页 | 打开菜单 | 退出(进度已经存在服务上) |
| 菜单 | 移动选中项 | 返回阅读、自动翻页、显示设置、章节跳转 | 同上 |
| 自动翻页 | 每页停留时间加减 1 秒(1~30 秒) | 确定 | 同上 |
| 章节跳转 | 往后、往前选一章,面板上显示章名和第几章 | 跳过去 | 同上 |
| 显示设置 | 最上面一项是返回;选字号、粗细、亮度、行距,进去后前滑增大、后滑减小 | 保存 | 同上 |

语音(经过大模型,说法比较随意):看小说、继续看、打开《书名》、换一本、书架上有什么、跳到第 N 章、下一章、跳到一半、跳到百分之 N、回到开头、往后翻 N 页、下一页、上一页、字大一点、字小一点、字号调到 N、我看到哪了。