xmz7891
fd8be87209
用户这一轮报了两个问题，都修了。
== 一、Win7 上语音播报不能用 ==
用户原话："我 win7 上的语音播报好像不能用，你再试一下别的版本能不能用"
**原来只有一条路**：
powershell -NoProfile -WindowStyle Hidden -Command
"Add-Type -AssemblyName System.Speech; $s = New-Object ...; $s.Speak('...')"
这在 Win7 上有三个坑，任何一个都能让它彻底不出声：
1. **`powershell` 只按名字找**
Win7 的 powershell.exe 在 `%SystemRoot%\System32\WindowsPowerShell\v1.0\`。
精简版系统、或从服务/计划任务拉起时 PATH 里可能没有 ——
CreateProcess 按名字找不到时是**静默失败**的。
2. **Win7 默认 PowerShell 2.0，它按 ANSI 代码页解析 `-Command`**
PS 3.0 起才按 UTF-16 处理。中文经 `-Command` 传进去容易乱码 ——
表现是念出来是乱码，或者干脆不念。
3. **`System.Speech` 需要 .NET Framework 3.0+**
而系统自带的 **SAPI5** 从 Windows XP 就有，**根本不需要 .NET**。
**改成多方案降级**，按"依赖越少越优先"排：
1. cscript + VBScript + SAPI5 <- Win98 起就有，不用装任何东西
2. wscript + VBScript + SAPI5 <- 上一条被安全软件拦时的备选
3. powershell + SAPI5 (COM) <- 绕开 .NET
4. powershell + System.Speech <- 原来的做法，改用绝对路径
5. powershell(PATH) + System.Speech <- 最原始的，兜底
一条通了**记住它**，以后直接用（不用每次从头试）。
**顺带修掉一个"骗人"的行为**：原来 `say()` 用 `Popen` 不等进程结束，
失败了也返回"已播报" —— 明明没出声却报成功。
现在等退出码，**全失败会明确报错并列出试过哪几条**。
代价是同步等待（念多久等多久），但"报成功其实没出声"比"慢一点"糟糕得多。
还加了 `_build/diag_tts.py`：在一台机器上把 5 条方案全试一遍并报告
哪条能用 —— 下次再有"某台机器上不行"，跑一下就知道。
VBScript 的细节：**必须用 ANSI(mbcs) 写**，写成 UTF-8 的话
cscript 读出来中文是乱码（VBScript 的老规矩，很隐蔽）。
长文本还要分句 —— VBScript 单行有长度上限。
== 二、快捷栏按钮太小 + 4 格都要能换 ==
用户原话："屏幕最上面这个按钮有些按不到，按钮太小了，做大一点，
然后呢，这个每每个四格算换一下吧，第一个第二个第三个
第四个都能换东西"
* **按钮做大**：30dp -> 46dp（接近 Android 建议的最小可点区域 48），
字号 11 -> 14。30dp 在表盘上手指按上去一半在栏外。
**栏高做成常量 QUICK_BAR_DP，栏高 / 面板 topMargin / addView
三处用同一个值** —— 分三处写的话改一个忘一个，
表现是"内容被盖住"或"上面空一条"。
* **4 格全部可自定义**。用户最早说"其中有一个按钮不能改，
功能就是一键返回桌面"，第一版就按"第 4 格写死 desktop"做的。
现在他改主意了 —— 所以 desktop 变成**普通可选动作**，
默认仍放第 4 格（习惯不用改），但想换也能换。
可选动作从 7 个变成 8 个。
**教训（写进测试注释了）**：别把"用户当时的一句话"当成永久约束
焊进结构里；真是约束的话，注释里要写清是什么时候的要求，
下次他改主意时才知道该动哪儿。
== 三、修一个"测试自己没擦干净"造成的假 bug ==
全量回归报：
[FAIL] 配对码正确写入 实际 '（旧的残留值）'
而 `（旧的残留值）` 是**上一次测试遗留**的配对码 —— 数据目录
`C:\ProgramData\ykxmz\data` 在卸载时**故意不删**（那里存着用户的
中转地址、配对码等，卸载不该删），所以机器上会留着上一轮的
settings.json。测试装的时候虽然传了 `/CODE=517284`，但环境没擦干净时
就可能读到旧值 —— 表现成"安装包有 bug"。
**修法**：`test_installer_cycle.py` 加一步"装前先清残留"
（正规卸载 -> 杀进程 -> 删安装目录 -> **删数据目录**）。
数据目录那一步是关键 —— 卸载器不删它。
== 四、其他 ==
* `docs/项目规矩.md` 第一节改成**按预案执行**：
预案一 = 做完测试没问题就上传；预案二 = 做完测试但不上传，直接给用户。
用户没说预案几时默认按预案一，并在交付时说明。
* 顺手把那份文档里的老域名 `relay.xxmxxs.top` 改成现在的
`yk.xxmxxs.top`（老服务器早就退役了）。
* 修掉自己造的重复定义：往 actions.py 插降级链时，
`list_voices` / `say` 各插了两份（pyflakes 报 redefinition）。
* 一次危险的误操作：`Path.write_text(..., newline='\n')` 会**先截断文件
再校验参数**，参数非法时文件已经空了 —— 我用它把
`_tests/test_quickbar.py` 清空了。已重写。
**以后不给 write_text 传 newline。**
== 验证 ==
全量回归（21 关）全部 PASS
新增关卡：3a13 手表快捷栏 / 3a14 语音播报降级
安装包周期 23 项全过（装 -> 验 -> 卸 -> 再验）
Java 编译通过（android-34, --release 8）
本机实测语音播报：cscript 那条通了（2.4 秒）
全部产物重建，Win7 兼容校验通过
6.5 KiB
项目规矩（每次改动都要遵守）
这份文件是给开发和发布看的硬性约束。新会话接手时先读这个。
一、发布流程：按「预案」执行
用户原话：「以后我会说按照预案几处理」
用户原话（预案一）：「做完以后测试，没问题上传」 用户原话（预案二）：「做完以后测试，测试完以后别上传，直接给我」
用户会明确说"按预案几"，说了就按那个走。
| 预案 | 做什么 |
|---|---|
| 预案一 | 做完 → 测试 → 没问题 → 上传（创建 Gitee 发布 + 传附件 + 部署到服务器） |
| 预案二 | 做完 → 测试 → 不上传，产物交给用户 |
两个预案共同的部分（都必须做）
- 本地把所有产物构建完成（APK / 安装包 / 服务端包）
- 跑测试：全量回归 + 安装包周期 + 发布验收
- 测试不绿就停，先说清楚哪儿红了 —— 不许带着红测试交付
只有预案一才做的部分
-
提交
main+ 推送 -
创建 Gitee 发布、上传三个附件
-
部署到服务器（
_build/deploy_lightsail_release.py），并实测线上：/v1/update/latest返回的版本 = 刚发的- 官网角标 = 刚发的
- 安装包能下（看真实字节数）
/v1/health正常
用户没说预案几的时候
默认按预案一（那是长期以来的既有习惯），但要在交付时说明 "我按预案一做了，已经上传"，让用户有机会纠正。
历史（这条规矩怎么来的）
最早用户说「你先把所有东西给我，我运行没问题再告诉你帮我推送」， 中间放宽过一次（「你自己上传就行了」），后来又要"自己测完再上传"。 现在固化成两个预案，由用户每次指定。
仍然绝对不做的：不测就上传。
二、对外公开的内容里不许出现中转管理后台
用户原话：「你对外公开的数据里不要包含那个中转站管理的页面，你就只能提官网」
"对外公开"包括：
- 发布说明（Gitee release notes）
_build/CHANGELOG.md（它会变成发布说明）- 官网页面（
relay/landing.py渲染出来的） README.md- 我（AI）在对话里给出的总结、汇报、方案
- 任何我会贴给用户看、或用户可能转给别人的材料
只能提官网 https://yk.xxmxxs.top。
不要说：/zhongzhuanzhan、/admin、"管理后台"、"管理页"、
"管理入口"、管理密码之类。
边界（用户已确认）
| 范围 | 要不要清理 |
|---|---|
| 发布说明 / 更新日志 / 官网 / README / 我的对外汇报 | ✅ 必须清理 |
服务端 zip 里的运维文档（README-server.txt、AFTER-INSTALL.txt 等） |
❌ 保留 —— 那是给装服务器的人看的，删了他不知道怎么运维 |
仓库源码里的实现（relay/relay.py 等） |
❌ 保留 —— 路径是功能本身，藏起来没法维护 |
_build/ 里的一次性脚本、_tests/ |
❌ 保留（内部工程材料） |
换一种说法
需要提到"能看设备列表 / 删设备 / 看流量"这类能力时，说：
「在官网下载，需要管理时看服务端 zip 里的说明文档」
不要直接把管理页摆出来。
三、发版必须更新版本号
用户原话：「自行更新版号」 后来又补了怎么加的规定（见下表）
每次上传都要升版本号。怎么加按改动性质定：
| 改动性质 | 怎么加 | 例子 |
|---|---|---|
| 只修 bug | 最后一位 +1 | 1.8.2 → 1.8.3 |
| 加了新内容 / 重构 | 第二位 +1，最后一位清 0 | 1.8.2 → 1.9.0 |
⚠️ 一轮里只要同时有"新东西"和"修 bug"，就按新东西算（升第二位）。
比如某一轮既加了设置窗口的中转服务器字段（新功能）、
又把面板切换重构成 showOnly()（重构）、还修了 502（bug）——
那就是 1.9.0，不是 1.8.3。
为什么这条重要：下载站是按 URL 缓存的
（/download/ykxmz-setup-1.8.2.exe 带 max-age=604800, immutable）。
内容变了但不换 URL，缓存就会失效一次 —— 实测重新打包 server.zip
之后第一次请求 cf-cache-status=MISS。升版本号正好把 URL 换掉。
版本号散落在多处，用脚本统一改：
python _build\bump_180.py # 改版本号时把里面的 OLD/NEW 改掉
⚠️ .ps1 文件必须保留 UTF-8 BOM，否则 PowerShell 按 GBK 读会中文乱码 + 语法报错。
用 edit 工具改 .ps1 会吃掉 BOM，改完要补：
python _build\fix_ps1_bom.py
四、发布产物的组成
| 平台 | 产物 | 说明 |
|---|---|---|
| Windows | ykxmz-setup-X.Y.Z.exe |
安装包，不是 agent zip。用户要双击就能装 |
| 服务端 | ykxmz-server-X.Y.Z.zip |
随身 WiFi / Linux |
| 手表 | ykxmz-watch-X.Y.Z.apk |
直接给 APK，不打 zip |
发布说明只放更新内容（用户原话：「以后只放更新内容」），不要放安装教程之类的。
五、README 只在功能变化时更新
用户原话：「以后只放更新内容」/ 修 bug 不用动 README
功能变了才更新 README.md；纯 bug 修复不用。
六、设计理念：白色简洁
用户原话：「所有东西都要白色简洁，这是我的设计理念」
官网、管理后台、文档、任何界面 —— 一律白色、简洁、克制。
配色令牌见 relay/landing.py 顶部（#ffffff / #fafbfc / #e6e8eb /
#1a1d21 / #6b7280 / #2563eb）。
七、改完必须立刻验
这一天里我因为"改完没验"翻了三次车：
- 替换管理页时把
main()入口一起删了 → relay 起不来，systemd 重启 24 次， 所有接口 000。教训："删到文件末尾"之前必须先确认末尾有什么。 - 引用了从没定义过的
ADMIN_PATH常量 → 管理页 NameError。 - 改了
_send()的调用没传 Content-Type → 浏览器把整页 HTML 当纯文本显示。当时只验了 HTTP 200 和字节数，两个都对。 → 200 不等于页面能看，响应头也得看。
规矩：任何改动之后，至少跑一遍 「管理页 + 官网 + 关键接口 + 响应头」的回归。
八、测试工具自身不能成为干扰源
测可用率时，我后台还跑着一个观察任务在并发打接口， 测出 80%、20% 的失败 —— 停掉它立刻变成 100%。
测稳定性之前，先确认没有别的任务在打同一个接口。