QwenGlass-Reader：在千问 AI 眼镜上看自己的 TXT 小说

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

这个仓库有两个分支，是同一个阅读器的两种接入方式。现在看的是 main（页图版），文字版在 agent 分支，能听书、智能翻页。两个版本可以各跑一个实例，挂同一个书库和进度目录，换个 Skill 接着读。

两个版本能做什么

Related MCP server: Co Reading Kit

怎么工作

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

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

部署指南

要准备三样东西：

• 一台公网服务器和一个 HTTPS 域名。平台调 MCP、手机下载页图都走公网，证书要正规（Let's Encrypt 就行）。

• 一个千问开放平台账号。第一次登录会自动注册，按提示做个人实名认证。

• 一副千问 AI 眼镜。

第一步：配置

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

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

第二步：部署到服务器

1. 在仓库根目录复制 .env.example 为 .env，填 READER_TOKEN、READER_KEY（各一串随机字符），READER_PUBLIC_URL 填你的域名。

2. 准备书库和进度目录。容器里的用户是 10001，进度目录要它能写：

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

3. 把 TXT 放进 deploy/books/，启动：

   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，都不用申请开通。仓库里的文件这样放：

1. 新建 MCP 插件

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

保存时平台会马上连你的服务拉工具，应该拉到 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。排版在 macOS 上用系统自带的冬青黑体和宋体，在 Linux 上要装 fonts-noto-cjk。

uv sync

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

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

眼镜上的操作

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