# 应用内更新

Quiet TV 在首页前台显示后检查已签名的公开版本清单，成功检查间隔为 24 小时；自动失败间隔为 30 分钟。待机、关机和应用未运行时不唤醒检查。“检查更新”可主动立即检查。

1.3.1 从“桌面设置 → 版本更新 → 检查更新”主动查询；“版本更新”标签位于“文件传输”之后，“诊断日志”之前。1.3.0 从“应用管理”进入，已发布更旧包可能仍使用右上角“关于”入口。有匹配更新时，“版本更新”标签显示红底白描边的“新版本”角标，内容区的检查按钮显示红点。查看说明不清除提示，确认实际更新版本后清除。无更新或检查失败只在弹窗显示，不增加常驻辅助文字。

1.3.0 的更新清单与安装包下载均采用固定主备顺序：ghfast.top、gh-proxy.com、v4.gh-proxy.org，失败后自动切换下一源。历史成功记录不改变顺序，GitHub 原生来源始终排在三个镜像后；镜像重定向回原生地址也按该镜像失败处理。v4.gh-proxy.org 是 GH-Proxy 的另一条线路，不代表独立的服务提供方。此调整已随 1.3.0 测试版交付。

检查更新按上述镜像顺序读取 Raw 清单，镜像之后依次尝试 GitHub Pages、GitHub Raw 直连；通常比较两个已验签响应并保留较高 revision。仍使用防缓存请求、40 秒总预算和已有最低 revision 限制，不能只因第一个来源返回旧清单就停止。

总预算耗尽时停止继续请求；已取得符合最低 revision 的有效签名清单时仍按成功处理，不因比较其他来源超时而丢弃。用户主动取消则终止本次检查，不保存本次结果。尚未取得有效清单时，按实际失败阶段提示网络超时、地址解析、HTTPS 安全连接、服务响应、清单校验或本地保存问题。

安卓 4.4～7.1 的更新检查和下载使用请求专用的 TLS 1.2 适配，在系统信任根基础上补充随包的 DigiCert / ISRG 根证书；保留证书有效期和域名校验，不修改全局 TLS 或其他网络请求。较新系统继续使用系统默认 TLS。诊断日志记录更新来源、连接/读取/验签阶段、异常类型链、HTTP 状态和固定校验原因，不记录服务端原文、网址参数或本地文件路径。以上容错与诊断修复已包含在 1.3.0 测试版中。

后续本地修复（尚未发布）：Android 4.0～4.3 的系统 HTTPS 实现会将第三方 Socket 改为仅启用 SSLv3；更新连接现在保留原先配置的 TLS 1.2，API19 及以上维持原路径。Bouncy Castle 明确报告“无可用协议”或“无可用密码套件”时，按 TLS 握手失败记录并继续既定备用源；其他运行时异常仍向上报告。清单与 APK 下载共用此处理，证书、域名、清单签名及 APK 哈希校验均保留。已发布的 1.3.1、1.3.2 安装包不包含此修复。

用户选择下载安装包后，按上述镜像顺序尝试，GitHub 原源最后。连接和首字节共用 8 秒预算；断流 8 秒或连续三个 5 秒窗口低于 100 KiB/s 时切源。完成度达到 95% 或剩余不超过 512 KiB 时，只因中断或错误换源。最后一个仍在传输的源允许继续慢速下载。

只有符合 Content-Range 偏移与总大小的 206 才续传；200 从头写入。同一下载任务固定目标文件，完整 SHA-256 不匹配时丢弃该下载内容并从下一源重新获取同一签名清单指定的文件，全部失败则报错。校验通过后仍检查实际 APK 包名、版本、SDK、ABI 和签名关系，不因切源放宽校验。下载不使用电视 ADB；应用内安装由用户通过系统安装器确认。首次需要授权时，点击“继续”后由系统安装器展示来源授权提示，用户在系统设置中允许后返回确认安装；应用不自行改变安装权限。

更新保留当前包名、系统兼容档、HOME 声明形态和渠道。64 位处理器不等于系统支持 ARM64。构建号必须更高，软件版本必须更新；不把同版本其他架构的更高构建号当作更新。缺少匹配包、签名不兼容或电视限制安装时，不卸载、不清数据、不强制降级，按安装指引处理。

后续客户端采用统一安装入口：安卓5至6（API21–23）优先把内部目录中已校验的APK写入系统安装会话，用户通过系统确认页完成覆盖安装，无需先复制到外部缓存。仅当会话接口明确未实现或系统确认页无法启动时，释放本次会话后回退到文件安装一次；用户取消、权限/策略拒绝、空间不足、校验冲突或未知读写错误不触发回退。安卓4.0至4.4继续使用文件安装，安卓7及以上继续使用FileProvider。

文件安装请求系统返回结果，并持久保留待核对状态；系统未返回结果时，回到更新页仍核对实际已安装版本。尚未确认安装完成时保留已校验下载包，展示重试及电脑更新入口，不自动重试或把安装页调起当作成功。Android8及以上未获安装来源授权时先打开该应用的系统授权页，返回后明确提示授权状态。日志另记实际解析的安装组件、授权状态、数字返回值及版本核对结论。此补充以本地源码为准，未随本次验证发布。

文件安装使用应用专属外部缓存目录；目录不可用时尝试应用专属外部文件目录。已通过大小和SHA-256校验的安装副本可复用。提示区分空间不足、目录不可用、读写失败、系统安装存储不可用和用户取消；系统存储失败不自动等同容量不足。日志记录attempt、会话ID、路径类别、步骤、固定原因码、数字结果和容量（未知为-1，真实0字节保留0），不包含路径或异常原文。安装回调仅接受本次会话；应用后台时保留待确认状态，回到更新页面才展示系统确认页。进程重建不自动重新提交；用户可重试，且只释放自己记录的会话。打开安装器或收到系统成功结果后仍核对实际已安装版本。此修复已随1.3.2测试版发布，Android5/6及厂商固件上的确认页和覆盖升级仍需实机验收。

## 1.3.3测试版257/258

[v1.3.3](https://github.com/BeatsAD/quiet-tv/releases/tag/v1.3.3) 提供标准通用包257（最低API21）和Android4.0–4.4兼容包258（legacy14，最低API14），同源、同测试签名、无原生库。按维护者确认的最新说明发布两个APK；实际公开下载大小和SHA-256已与本地原件核对。旧247/248审核候选及历史本地测试包保留，不覆盖或改名充作本批新包。

本批包含动态壁纸跨品牌及Android4.1–4.4软硬解码回退、低版本桌面守护和信号源选择保存、AI首装系统入口验证，以及接管恢复记录和兼容守护验收采集修复。Android4.0/4.0.3保留原播放路径；Android4.3窗口守护与Android4.4本机守护按实际能力配置，不代表所有固件均已验收。安装与维护沿用固定Agent入口和实时索引，不需要用户逐版修改提示词。

签名更新清单递增为revision12：旧 `updates.json` 仅新增标准257，新 `updates-v2.json` 新增标准257和legacy14兼容258；两份均保留此前9个版本及原有公钥。按实际包名、系统档位、HOME形态、签名、版本与架构选包，不能因258构建号较大而给标准系统推荐兼容包。原本地1.3.3.1与公开1.3.3具有相同基础版本，不由应用内更新当作更高基础版本自动替换。

源码PR [#128](https://github.com/BeatsAD/quiet-tv/pull/128) 的Validate及全部CodeQL通过；两个最终包的benchmark构建、必要Lint、元数据、签名、内置更新公钥、哈希和批次一致性通过。壁纸任务75项测试、合并后30项旧版回归，以及本轮11项审查回归和16项既有HOME/守护回归通过；生产Java的16项验签、档位选择、防降级和篡改拒绝验证通过。

本批最终257/258的设备安装、核心功能、覆盖升级数据保留、厂商真机、实体HOME、重启/冷启动/待机验收，按维护者本次发布授权延续延期。构建、模拟运行及历史索尼包的现场记录不代替本批最终APK验收。

## 1.3.2测试版172/173

[v1.3.2](https://github.com/BeatsAD/quiet-tv/releases/tag/v1.3.2) 提供标准通用包172（最低API21）和Android4.0–4.4兼容包173（legacy14，最低API14），同源同测试签名、均无原生库。按审核通过的正文及附件材料发布两包与同名SHA-256校验文件，公开下载大小和哈希均已核对。

签名更新清单递增为revision11：旧 `updates.json` 仅新增标准172，新 `updates-v2.json` 新增标准172与legacy14兼容173，两份均保留原有8个历史版本记录和原公钥。选包仍按实际包名、系统档位、HOME形态、签名、版本及架构，标准版不能因173构建号更大而选用兼容包，专用包及relay不跨档更新。

两档benchmark构建、Lint、元数据、签名和批次校验通过，针对性回归标准127项、兼容145项通过。标准最终172包已在API31模拟器从169保留数据覆盖升级，拉回APK哈希与本地一致，所见壁纸、首页顺序及维护配置保留；设置入口和文件传输页面、连接码及授权文件列表检查通过。Android4.x最终包运行与覆盖升级、厂商真机逐项功能、实体遥控器及重启／冷启动／待机验收，已由用户明确决定延期。模拟器与旧索尼包记录不替代这些验收。

## 1.3.1测试版146/147

[v1.3.1](https://github.com/BeatsAD/quiet-tv/releases/tag/v1.3.1) 提供标准通用包146（最低API21）和Android4.0至4.4兼容包147（legacy14，最低API14），同源同签名、均无原生库。发布正文采用审核通过的新增功能和问题修复第2稿，附件公开下载校验通过后同步签名清单revision10。

旧 `updates.json` 新增标准146，保留旧客户端认识的全部历史记录；`updates-v2.json` 新增标准146和legacy14兼容147并保留其全部历史记录。1.3.0标准130和legacy14兼容131可按各自档位选择1.3.1更新；旧legacy19客户端读取旧清单，不能自动选择legacy14的147，需按实时索引手动下载兼容包。标准版不能把147作为更新，酷开包名及relay形态也不跨档更新。

本批构建、Lint、元数据、签名与校验通过，相关31项单测和源码Validate通过。最终146/147未安装到设备，新增功能、覆盖升级数据保留、Android4.x实际运行和厂商真机验收已由用户明确决定延期；旧1.3.0/143索尼安装及开发阶段模拟器记录不替代本批验收。

## 1.3.0累加测试版130/131

原v1.3.0 Release新增标准通用包130和安卓4.0至4.4兼容包131，均无原生库、同包名同测试签名。发布同步revision9：旧 `updates.json` 仅加入标准130，保持旧解析器认识的档位；新 `updates-v2.json` 提供标准130及legacy14兼容131。历史其他版本条目保留，原117/118 APK附件由维护者手动删除。

已安装1.3.0按软件版本判断更新，不会提示本批同版本新包；旧legacy19客户端也不能自动选择legacy14，需经[实时安装索引](https://beatsad.github.io/quiet-tv/latest.json)手动下载后覆盖安装，不卸载、不清数据。API14–19实际系统运行、旧系统升级及厂商真机验收继续延期。原v1.3.0标签保持历史位置，新包生产源码与main提交a6c6c466一致。

## 电脑适配迁移与覆盖升级

1.3.0 测试版已发布标准通用包117和安卓4.4包118，签名更新清单 revision 8 提供对应更新并保留历史版本。两包均无原生库；旧标准 ARM32、ARM64 与通用包升级到标准通用包117，安卓4.4档升级到118。工具更新本身不代表应用内有新版本；旧 APK 缺接口时仍按已有能力处理，先完成匹配包名、签名和递增构建号的覆盖升级。

覆盖升级到同包名、同签名且构建号递增的 1.3.0 APK 时，固件、HOME 形态、原桌面及助手版本未变才沿用接管路线；保留暂停和 ADB 选择，自动代理重新核对主程序版本，旧实机场景验收清为待验证。覆盖后仍分别检查接管、守护、ADB 和原桌面恢复，不以文档或构建通过替代实机验证。详见[已有安装](AGENT_INSTALL.zh-CN.md#已有安装覆盖校验与仅更新)。

## 公开输入与首次接入

生产输入为 `updates/updates.json` 和 `app/src/main/assets/updates/public-key.der`。Pages 工作流复制原字节清单到站点根目录；Raw 地址指向仓库同一份文件。Pages 域名不通过 GitHub 代理前缀包装，Raw 和 Releases 文件才使用代理。

清单包含 keyId、Base64 payload 和 SHA256withRSA 签名。应用验签后读取 payload，拒绝低于已缓存 revision 的清单。代理没有发布签名权；APK 不包含私钥、GitHub Token 或代理凭据。没有已批准的新包时，初始化清单的 releases 为空，不发布虚构版本或旧包升级提示。

第一批包含更新能力的 APK 仍需通过已有安装方式安装一次。合入代码不等于清单已上线；Pages、Raw 和 Release 的公开部署必须分别确认。

## 本地生成清单

### 外部 Agent 与安装页的最新版入口

安装站点另提供 `https://beatsad.github.io/quiet-tv/latest.json` 与 `agent.md`。`scripts/build_install_guide.py` 在部署时实时读取 GitHub 的完整公开 Release 列表，包含测试版、排除草稿，按数字软件版本排序，只保留真实上传的主程序 APK 及其下载地址、大小和 SHA-256。历史档位保留为适配候选；全局最新软件版本不代表适配每台电视。全部撤回后索引的 `latestVersion` 为 `null`、`releases` 为空，停止安装步骤；统一入口仍可用于检查和恢复。索引不推断 APK 的实际构建号、签名或架构，也不重签、修改电视端 `updates.json`。

Release 发布、编辑、转正式或撤回后，工作流自动请求从 `main` 重新部署安装站点；此路径兼容 Pages 仅允许 `main` 部署的环境规则。更新规范、站点脚本或签名清单合入 `main` 时同样自动部署。普通新版本不需要修改网页、提示词或固定链接。发布操作须保留原有审核授权；用仓库 `GITHUB_TOKEN` 发布 Release 不会触发普通工作流事件，发布者使用该方式时须显式执行 `gh workflow run pages.yml --ref main --repo BeatsAD/quiet-tv`。自动部署完成前站点仍为上次成功版本；失败时检查 Pages 工作流并修复后重跑，不把失败视为上线成功。

安装页打开和复制时用 `no-store` 与自动时间参数读取索引；复制内容只保留一个官方操作说明地址，不写入当前版本号、特定发布页或复制时的时间戳，保存后也不会锁定当时版本。实时查询、选包、校验与防缓存规则放在操作说明中，由 Agent 每次执行时处理，无需用户维护版本号。第三方工具不执行读取、网络不可达或站点部署失败时仍须报告失败，不能承诺任何网络与任意工具下都实时可用。

本地检查（仅生成文件，不部署）：

```sh
python3 scripts/build_install_guide.py --output output/install-guide
```

`--releases /绝对路径/releases.json` 可改用保存的 GitHub API 响应进行离线检查。生成失败不会清理或替换已上线站点；Pages 上传与部署仅发生在构建成功后。

### 电视端签名清单

从不可变 APK 归档及其 JSON 生成。版本说明文件仅保留本地，例如：

```json
{
  "versionName": "2.0.0",
  "channel": "test",
  "features": ["本版实际新增的功能"],
  "fixes": ["本版实际修复的问题"],
  "artifacts": [
    {"receipt": "../dist/apk/本地归档记录.json", "url": "https://github.com/BeatsAD/quiet-tv/releases/download/v2.0.0/已审核的实际文件名.apk"}
  ]
}
```

示例版本不预占交付版号。`receipt` 相对说明文件解析。脚本重新核对 APK 字节、版本、架构、签名和 HOME 形态，同版本要求同一源码提交。

```sh
python3 scripts/build_update_manifest.py --release /绝对路径/本地版本说明.json --revision 2 --key /仓库外/持久私钥.pem --output updates/updates.json
```

可通过 `python3 scripts/build_update_manifest.py --verify updates/updates.json` 只用公开密钥验证清单；现有 Validate 会执行此检查，不依赖私钥或本地测试模块。

撤回版本时，使用更高 revision 的 `--empty` 清单。脚本不联网查询、不上传、不创建标签。持久私钥应备份在仓库外；APK 的公开密钥必须与签名密钥匹配。新克隆可以独立构建和验签，无需私钥；发布者生成下一份清单才需要私钥。不要替换现有公钥或用临时密钥发布。

发布前先按 [版本规则](VERSIONING.md) 和 [工作区指令](../AGENTS.md) 备齐、审核真实的更新功能、修复文案及 APK 材料。附件上传并校验可下载后再发布对应签名清单。历史 Release 与 APK 不覆盖。

## 每次上传发布后同步清单

每批 APK 公开上传并完成下载校验后，发布者须在同次任务中继续同步应用内签名更新清单，无需用户再次提出或确认。用户对本批文案与材料可上传发布的确认，同时授权对应清单的生成、签名、提交、经 PR/Validate 合并及部署；仅保存草稿或用户明确要求暂不更新清单时按其范围执行。

1. 使用已获批的更新文案和本批真实 APK 归档，核对公开下载地址、包名、版本、构建号、SDK、架构、签名、大小及 SHA-256。
2. 沿用原持久签名密钥，递增 revision，保留已有版本记录，生成并验证新清单及应用选包结果。
3. 按仓库 PR 和必需 Validate 流程合并、部署清单，核对 Pages、Raw 的线上签名、revision 和内容与提交一致。
4. 报告 APK 发布及应用内清单同步的结果。清单同步失败时继续处理并如实说明，不能仅因 APK 已上传就宣布整次发布完成。

## 验证范围

自动规则和受控传输测试不能代替真实代理完整下载、电视网络、未知来源授权、实体遥控器及升级保留验证。实际系统安装器样式与能力由电视固件决定。应用被替换时可能退出；再次启动会读取实际版本，不以“安装器已打开”判断更新完成。

统一 `agent.md` 由 `docs/AGENT.md` 生成短入口，不再拼接完整安装长文和附件列表。`latest.json` 的 `tools`、`guides` 提供本次工具、规则和按需说明的实际 URL 与 SHA-256；任务保存这些文件的固定版本，中断后核对现场再继续。维护说明为 `maintenance.md`，旧 `adapt.md` 保留兼容。此索引不改变电视端签名更新清单。

## API14 兼容包与清单版本

新增 `legacy14` / minSdk14 使用 `updates-v2.json`，保留原签名信任与 revision 校验。新客户端可回退读取旧清单；标准客户端继续使用 `updates.json`。发布时旧清单仅保留旧客户端认识的 standard/legacy19 且 minSdk>=19 的记录；API14 包仅加入新清单，网站生成器会验签并合并两份清单的安装包元数据。构建脚本不允许将 API14 包直接生成到名为 `updates.json` 的目标，以保护已安装旧客户端。新清单和新包均需按发布审核流程操作，本次开发不执行线上发布。