1. 报告概要

用户执行玲珑应用升级命令时失败：

ll-cli upgrade --json github.troyeguo.koodo-reader

输出：

{"message":"Checking for updates github.troyeguo.koodo-reader","percentage":0.0}
{"message":"Upgrade failed"}

系统上已安装 Koodo Reader 2.4.3.5，稳定仓库中存在新版本 2.4.4.0（确认可搜索到），但升级任务在"检查更新"阶段即失败，错误码 2201（all apps failed to upgrade）。守护进程日志给出最终错误为 packages is empty（远程搜索结果为空），而同一查询用 curl 直连仓库 API 却能返回数据，判定为客户端（安装版 linyaps 1.13.4）与服务端响应之间的解析/过滤不兼容问题。

---

2. 环境信息

项目	值
操作系统	Deepin（基于 Debian Linux），X11 会话
ll-cli 版本	如意玲珑 CLI 1.13.4-1
相关软件包	linglong-bin 1:1.13.4-1-20260709、linglong-box 2.2.1-1、linglong-builder 1:1.13.4-1-20260709、linglong-pica 1.2.8-1、linglong-store 3.6.0
目标应用	github.troyeguo.koodo-reader（Koodo Reader）
已安装版本	2.4.3.5（channel=main, module=binary, arch=x86_64）
仓库可用版本	2.4.4.0（stable 仓库）
仓库配置	stable: https://mirror-repo-linglong.deepin.com（默认，优先级0）；testing: https://cdn-linglong.odata.cc（优先级0）；dev: https://repo-dev.linyaps.org.cn（优先级0）

---

3. 问题现象

1. ll-cli upgrade github.troyeguo.koodo-reader → 仅输出 升级失败，无详细原因。

2. ll-cli -v upgrade ... → Error 2201: all apps failed to upgrade。

3. 升级任务从开始到失败仅约 4~5 秒，进度始终为 0.0%，未发生任何下载。

4. 通过 D-Bus 抓取任务状态（org.deepin.linglong.Task1 的 PropertiesChanged），状态变迁为：

   顺序	Code	Message	State
   1	1000	update apps	4（运行中）
   2	1000	Checking for updates github.troyeguo.koodo-reader	3（进度）
   3	1000	Checking for updates github.troyeguo.koodo-reader	3（进度）
   4	1000	Checking for updates github.troyeguo.koodo-reader（Percentage 0.0）	3（进度）
   5	2201	all apps failed to upgrade	1（失败）

5.玲珑的搜索、安装、卸载功能均正常。

---

4. 排查过程与证据

4.1 应用与仓库状态确认（正常）

• ll-cli list / ll-cli info：koodo-reader 2.4.3.5 已安装，channel=main。
• ll-cli search github.troyeguo.koodo-reader：仓库存在 2.4.4.0。
• /var/lib/linglong/states.json：koodo-reader 记录完整（commit=2c65d957…，channel=main，version=2.4.3.5）。
• /var/lib/linglong/layers/2c65d957.../：应用层文件存在。
• 远程仓库 summary 中确认存在 main/github.troyeguo.koodo-reader/2.4.4.0/x86_64/binary。

4.2 守护进程日志（sudo）—— 定位最终错误

failed to update app github.troyeguo.koodo-reader: [code -1]:
    packages is empty
action update apps failed: [code 2201]:
    all apps failed to upgrade

4.3 根因代码路径分析

packages is empty 来自 RemotePackages::getLatestPackage()（remote_packages.cpp:22），即 matchRemoteByPriority 汇总后未得到任何候选包。调用链：

PackageUpdateAction::updateApp
  └─ needToUpgrade(fuzzyRef, local)
       ├─ matchRemoteByPriority(fuzzyRef)      ← 遍历所有仓库 searchRemote
       │    └─ searchRemote(fuzzyRef, repo, semanticMatching=true)
       │         ├─ POST /api/v0/apps/fuzzysearchapp  （HTTP 请求成功，code=200）
       │         └─ semanticMatch(fuzzyRef, pkgInfo)  ← 本地语义过滤
       └─ getLatestPackage()  →  "packages is empty"  ← 过滤后为空

关键差异（对比）：

• ll-cli search 走守护进程 Search 方法：searchRemote(params.id, repo)，构造的 fuzzyRef channel=nullopt → semanticMatch 跳过 channel 校验 → 返回全部数据 → 搜索正常。
• 升级走 needToUpgrade：FuzzyReference::create(app.channel="main", app.id, ...) → semanticMatch 要求 记录 channel 必须等于 "main" → 全部被过滤 → 结果为空。

4.4 直接调用仓库 API 验证（正常返回）

用与守护进程相同的参数直连：

curl -X POST "https://mirror-repo-linglong.deepin.com/api/v0/apps/fuzzysearchapp" \
  -H "Content-Type: application/json" \
  -d '{"appId":"github.troyeguo.koodo-reader","arch":"x86_64","channel":"main","repoName":"stable"}'

返回 code:200，data 中包含全部版本（含 2.4.4.0），且每条记录的 channel 均为 "main"。

• testing 仓库（cdn-linglong.odata.cc）与 dev 仓库返回 {"code":200,"data":null}（该应用不在其中，属正常）。

4.5 已排除的干扰项

怀疑点	结论
网络不通 / 仓库不可达	排除。curl 直连三个仓库均正常；summary 可下载（2.4MB）。
代理缺失	排除。无代理环境，无代理直连也正常。
polkit 授权失败	排除。pkcheck / CheckAuthorization 测试均返回授权成功；期间 dde-polkit-agent 与 polkit-agent-helper 出现 GLib 断言错误（json_node_unref / g_output_stream_write_all），属独立缺陷，未阻断授权。
磁盘空间不足	排除。/ 可用 9.9G，/home 可用 114G。
仓库残留 .commitpartial（20:54 中断提交遗留）	基本排除。失败发生在 0% 进度、未进入下载/提交阶段；但该残留仍需清理。
应用/层数据损坏	排除。states.json、layers、远程 ref 均完好。

---

5. 根因结论

安装版守护进程（ll-package-manager，linyaps 1.13.4-20260709）在升级路径 needToUpgrade → matchRemoteByPriority → searchRemote 中，对服务端返回的包列表做 semanticMatch 语义过滤时，带 channel="main" 过滤条件，最终把全部候选项过滤掉，导致 RemotePackages 为空，报错 packages is empty。

两种可能的具体机制（待调试日志确认二选一）：

1. 响应解析不兼容：安装版 C 客户端解析 fuzzysearchapp 响应时，channel 字段解析结果与 "main" 不一致（非空但 ≠ "main"，如映射到其他字段），导致 semanticMatch 全部返回 false。
2. 过滤逻辑差异：安装版（1.13.4）与用户源码（1.13.0-111-g14443d9b）不一致，安装版的 semanticMatch/channel 处理存在回归。

判断依据：守护进程日志中未出现 invalid packageInfo（semanticMatch 报错才会打印，说明并非 channel 为空导致 Reference::create 抛错，而是比较结果 false）；ll-cli search（channel 过滤关闭）可正常返回，升级（channel 过滤开启）返回空。

影响范围：预计所有玲珑应用的升级操作均会失败（不止 koodo-reader），玲珑应用商店（linglong-store）中的升级功能同样受影响。

---