TTS Reader —— 智能正文抽取与朗读
概述
把「看的」变成「听的」。输入一个网址或一份文档，本技能会自动定位真正的正文、
剔除导航与注释类噪音，再用微软 Edge 神经语音（edge-tts，免费、无需 API Key）
朗读出来，或保存为 MP3。
核心价值是正文识别：直接读网页会念出「登录 注册 课程列表 扫码关注
版权所有」这类噪音，本技能把朗读稿从「整页文本」压缩到「真正的正文」。
何时使用
触发场景：
- 用户给出 URL 并说"读出来 / 念一下 / 播放 / 用声音读"
- 用户给出
.docx/.pdf/.txt/.md路径，想听内容而不是看 - 用户说"听课程""听书""把这篇转成音频""我不想看，想听"
- 用户要求把长文转成 MP3 以便通勤或离线收听
不适用：
- 用户只想看网页摘要 → 用内置网页读取
- 站点有反爬拦截（当当/京东/淘宝等）抓不到正文 → 先用 agent-browser 技能
保存页面 HTML，再用本技能读该本地.html - 云文档 / 资料库 / 网盘链接（腾讯文档等）→ 先走 library 技能取到内容
标准工作流
第 1 步：环境自检（首次使用或报错时）
python <skill_dir>/scripts/check_env.py # 只检查
python <skill_dir>/scripts/check_env.py --install # 缺什么自动装什么
必需依赖：edge-tts、readability-lxml、lxml、pypdf、python-docx。
播放还需 ffmpeg（提供 ffplay）；仅保存 MP3 则不需要。
可用 python <skill_dir>/scripts/selftest.py 做一次功能自检（离线 25 项）。
优先使用已装好依赖的解释器执行后续命令；若默认 python 缺依赖而机器上另有
已配置好的环境，改用那个环境的解释器路径。
第 2 步：先 dry 跑一遍，确认抽到的正文是对的
python <skill_dir>/scripts/tts_reader.py "<URL或文件>" --mode dry --preview 600
--mode dry 不出声，只打印「原文多少字 → 朗读稿多少字」和被过滤掉的行，
用于确认正文识别正确、没有误伤。这是推荐的前置步骤。
第 3 步：朗读或保存
# 流式朗读（默认，不落盘，约 1-2 秒出声）
python <skill_dir>/scripts/tts_reader.py "<URL或文件>"
# 只保存 MP3
python <skill_dir>/scripts/tts_reader.py "<URL或文件>" --mode save --out "D:/path/out.mp3"
# 边播边存
python <skill_dir>/scripts/tts_reader.py "<URL或文件>" --mode both
长音频（超过约 1 分钟）必须放后台执行，否则会撞上前台命令超时。
用后台命令方式启动，播完后再取回输出，不要在启动后立即 sleep 轮询。
行为约定（重要）
- 不要擅自出声。 用户只说"读出来"时可以播放；但如果用户还在确认方案、
在问成本、或在对比模式，先把音频生成好、告知路径，等用户明确要听再播。
播放会占用扬声器，中途打断体验很差。 - 先 dry 后播。 面对陌生的站点或文档，先
--mode dry确认抽取效果，
避免念出一堆导航噪音后才返工。 - 不静默删内容。 脚本会打印每一行被过滤的内容。如果用户质疑"这段怎么没了"，
用--mode dry展示，或用--keep-annotations保留注释行重跑。 - 扫描件要如实说明。 PDF 无文字层时脚本会报错，此时告知用户需要先做 OCR，
不要谎称已读取成功。 - 转述原文而非改写。 朗读稿即原文正文（仅去噪），不要自行润色、概括或翻译，
除非用户明确要求。 - 大文件先估算时长。 按中文约 250–300 字/分钟估算；超长内容建议先告知
用户预计时长，或询问是否只读指定章节（可用--max-chars截断）。
隐私、网络与权限（使用前必读）
数据流向：正文文本会发送到站外
语音合成经由 edge-tts 调用微软的在线语音服务完成。
这意味着待朗读的文本会以 HTTPS 发送到微软服务器，不是纯本地处理。
因此：
- 处理涉密、含个人敏感信息（身份证号、手机号、银行账号、病历等）、
受保密协议约束的材料前，必须先向用户说明这一点，由用户决定是否继续。 - 联系方式、证件号等字段建议先剔除再朗读（可直接在源文档中删掉，或先转成
清洗过的.txt）。本工具不会自动识别并脱敏，不承诺任何脱敏效果。 - 网页抓取由本机发起（
curl），目标网站可见请求来源。
会调用的子进程
| 命令 | 触发时机 | 用途 |
|---|---|---|
curl |
输入为 URL 时 | 抓取网页 HTML |
ffplay |
--mode play / both |
经扬声器播放 |
pip |
仅在显式执行 check_env.py --install 时 |
安装缺失依赖 |
调用 curl 时不带凭据、不写入 cookie、不使用代理；抓取结果仅存内存。
依赖安装需要用户同意
check_env.py 默认只检查不安装。--install 会执行 pip install
（包名硬编码在脚本内，不接受外部输入，但仍会改动 Python 环境）。
未经用户明确同意，不要代其执行 --install，应先把缺失项告知用户。
参数速查
| 参数 | 说明 | 默认 |
|---|---|---|
--mode |
play 朗读 / save 只存 / both 边播边存 / dry 只看抽取 |
play |
--out |
音频保存路径（save/both 时；缺省自动命名） |
自动 |
--voice |
音色 | zh-CN-XiaoxiaoNeural |
--rate |
语速，如 -10% / +0% / +20% |
-5% |
--volume |
音量 | +0% |
--max-chars |
截断字数，0 不截断 | 0 |
--keep-annotations |
保留注释性内容（默认丢弃） | 关 |
--preview |
dry 模式预览字数 | 500 |
--list-voices |
列出推荐音色 | — |
常用音色：zh-CN-XiaoxiaoNeural（女·默认）、zh-CN-YunxiNeural（男）、
zh-CN-YunjianNeural（男·解说）、zh-CN-YunyangNeural（男·播报）、
zh-CN-liaoning-XiaobeiNeural（东北方言）、en-US-AriaNeural（英文）。
完整列表用 --list-voices。
支持的输入
| 输入 | 说明 |
|---|---|
http(s)://… |
网页，自动抽正文；结束时 .pdf 的链接按 PDF 处理 |
*.html / *.htm |
本地网页，同样走正文识别 |
*.pdf |
需有文字层；扫描件会明确报错提示 OCR |
*.docx |
含表格内容 |
*.txt / *.md / *.markdown |
纯文本，自动清洗 Markdown 标记 |
输出位置
--mode play：不落盘，直接出声--mode save/both：- 网页 → 当前工作目录的
outputs/<slug>__朗读.mp3 - 本地文件 → 与源文件同目录的
<文件名>__朗读.mp3 - 也可用
--out显式指定
生成 MP3 后，用文件展示能力把音频呈现给用户，便于试听。
资源
scripts/tts_reader.py—— 主程序：正文抽取 + 清洗 + 合成 + 播放scripts/check_env.py—— 依赖自检与自动安装（含国内镜像回退）scripts/selftest.py—— 离线自测（25 项，覆盖四类输入、清洗规则、边界报错）。
python scripts/selftest.py；加--online追加联网抓取与合成校验。
改动脚本后应先跑它再交付。references/troubleshooting.md—— 实现原理、常见错误处置、网络坑、音色表。
遇到报错、抽取结果异常、或需要解释「为什么不用系统自带语音」时查阅该文件。
