pkgmate 0.0.1__py3-none-any.whl

pkgtool/apt/lists.py

@@ -0,0 +1,336 @@
+"""pkgtool.apt.lists — /var/lib/apt/lists 的唯一解析器。
+
+合并原先两套并存的解析：deb_backend.build_source_index()（来源判定用）和
+apt_repo.load_index()（搜索/升级检测用）。二者读的是同一批 Packages 文件，
+每次采集要解压解析两遍，且字段各取一半、语义还不完全一致。
+
+一次遍历同时产出：
+  · (包名, 版本) → 源标签集合      来源判定：包是否来自某个已配置源
+  · 包名 → 全部版本条目            搜索、版本列表、升级候选
+  · 包名 → section / priority      卸载分类（classify.py）用
+源标签 = Release 文件的 Label（缺失时用 Origin，再缺失用文件名前缀）
+        + 文件名里解析出的 suite / component，形如 "Ubuntu noble/main"。
+
+无需 root：lists 目录全局可读。
+"""
+import glob
+import os
+import re
+import threading
+import time
+from dataclasses import asdict, dataclass
+from email.utils import parsedate_to_datetime
+from functools import cmp_to_key
+
+from ..base import matches_tokens, query_tokens
+from ..compress import open_text, read_text, strip_compressed_suffix
+from ..config import CFG
+from .version import newest, ver_cmp, ver_gt
+
+# Packages 记录里需要留存的字段（其余忽略）
+_FIELDS = frozenset(("Package", "Version", "Architecture", "Maintainer", "Size",
+                     "Filename", "Description", "Section", "Priority"))
+_PGP_TAIL = "-----BEGIN PGP SIGNATURE-----"
+_PGP_HEAD = "-----BEGIN PGP SIGNED MESSAGE-----"
+
+
+@dataclass(slots=True)
+class RepoEntry:
+    """某源里某个包的一个版本。"""
+    version: str
+    repo: str
+    suite: str
+    component: str
+    arch: str
+    maintainer: str
+    size_kb: int
+    filename: str
+    date: str
+    desc: str
+    section: str
+    priority: str
+
+
+@dataclass(slots=True)
+class _Release:
+    label: str
+    suite: str
+    date: str
+
+
+def _iter_records(lines):
+    """流式解析 Debian 控制文件：空行分隔记录；续行（空格/制表符开头）跳过，
+    因此 Description 只留首行摘要，不把多行正文吃进内存。"""
+    cur = {}
+    for line in lines:
+        line = line.rstrip("\n")
+        if not line:
+            if cur:
+                yield cur
+                cur = {}
+            continue
+        if line[0] in " \t":
+            continue
+        key, sep, value = line.partition(": ")
+        if sep and key in _FIELDS and key not in cur:
+            cur[key] = value.strip()
+    if cur:
+        yield cur
+
+
+def _release_body(path):
+    """InRelease 的字段在 PGP 头之后的第一个空行后；Release 文件直接就是字段。"""
+    text = read_text(path)
+    if text is None:
+        return ""
+    if text.startswith(_PGP_HEAD):
+        _head, _sep, body = text.partition("\n\n")
+        text = body
+    end = text.find(_PGP_TAIL)
+    return text if end < 0 else text[:end]
+
+
+def _parse_releases(lists_dir):
+    """→ {文件名前缀: _Release}。"""
+    out = {}
+    for path in glob.glob(os.path.join(lists_dir, "*")):
+        base = os.path.basename(path)
+        if base.endswith(".gpg"):
+            continue
+        prefix = None
+        for suffix in ("_InRelease", "_Release"):
+            if base.endswith(suffix):
+                prefix = base[: -len(suffix)]
+                break
+        if prefix is None:
+            continue
+        label = origin = suite = date = ""
+        for line in _release_body(path).splitlines():
+            key, sep, value = line.partition(": ")
+            if not sep:
+                continue
+            value = value.strip()
+            if key == "Label" and not label:
+                label = value
+            elif key == "Origin" and not origin:
+                origin = value
+            elif key == "Suite" and not suite:
+                suite = value
+            elif key == "Date" and not date:
+                try:
+                    date = parsedate_to_datetime(value).strftime("%Y-%m-%d")
+                except (TypeError, ValueError):
+                    date = value
+        # Label 优先于 Origin（apt 自己也是这么显示的）：Release 里 Origin 常写在
+        # Label 前面，按出现顺序取会把 "NVIDIA CUDA" 丢成 "NVIDIA"。
+        out[prefix] = _Release(label or origin or prefix, suite, date)
+    return out
+
+
+def _suite_component(basename, cfg):
+    """从 Packages 文件名解析 suite/component：
+      规范仓库  <prefix>_dists_<suite>_<component>_binary-<arch>_Packages[.gz]
+      扁平仓库（sources.list 里写 `deb <url> ./`）文件名里没有 _dists_，
+      硬套位置会把 URL 路径段当成 suite——NVIDIA 的 CUDA 源曾被解析成
+      suite="x86%5f64"，所以这种情况直接返回空，只留 Release 里的 Label。"""
+    core = strip_compressed_suffix(basename).split("_binary-")[0]
+    if "_dists_" not in core:
+        return "", ""
+    toks = core.split("_")
+    comp = toks[-1] if toks[-1] in cfg.known_components else ""
+    suite = ""
+    if len(toks) >= 2 and (comp or toks[-2] not in ("dists", "deb")):
+        suite = toks[-2]
+    return suite, comp
+
+
+def _package_files(lists_dir, cfg):
+    """→ [(路径, 文件名前缀, suite, component)]，已按架构过滤。"""
+    skip = re.compile(cfg.index_skip_arch_re)
+    out = []
+    for path in sorted(set(glob.glob(os.path.join(lists_dir, "*_Packages"))
+                           + glob.glob(os.path.join(lists_dir, "*_Packages.*")))):
+        base = os.path.basename(path)
+        if base.endswith((".gpg", ".tmp")) or skip.search(base):
+            continue
+        core = strip_compressed_suffix(base)
+        if not core.endswith("_Packages"):
+            continue
+        suite, comp = _suite_component(base, cfg)
+        out.append((path, core[: -len("_Packages")], suite, comp))
+    return out
+
+
+def _match_release(prefix, releases):
+    """Packages 文件名比 Release 多 component/arch 段，取最长前缀匹配。"""
+    best = None
+    for r in releases:
+        if prefix == r or prefix.startswith(r + "_"):
+            if best is None or len(r) > len(best):
+                best = r
+    return releases.get(best)
+
+
+class RepoIndex:
+    """已解析的仓库索引，构造后只读。"""
+
+    def __init__(self, entries):
+        self._entries = entries          # name → [RepoEntry]
+        self._top = {}                   # name → 最新版本的 RepoEntry（惰性缓存）
+
+    def __len__(self):
+        return len(self._entries)
+
+    def __contains__(self, name):
+        return name in self._entries
+
+    def names(self):
+        return self._entries.keys()
+
+    def entries(self, name):
+        return self._entries.get(name, [])
+
+    def top(self, name):
+        """最新版本的条目（同版本多源时取先出现的）；无此包返回 None。"""
+        if name not in self._top:
+            es = self._entries.get(name) or []
+            if not es:
+                self._top[name] = None
+            else:
+                best = newest(e.version for e in es)
+                self._top[name] = next(e for e in es if e.version == best)
+        return self._top[name]
+
+    def candidate(self, name):
+        """仓库里的最高版本；包不在任何源则返回 ""。"""
+        e = self.top(name)
+        return e.version if e else ""
+
+    def versions(self, name):
+        """去重后的版本列表，按 Debian 版本序从高到低。"""
+        vs = {e.version for e in self.entries(name)}
+        return sorted(vs, key=cmp_to_key(ver_cmp), reverse=True)
+
+    def repos(self, name, version=None):
+        """命中的源标签：给了 version 就按 (名,版本) 精确匹配，否则按包名。"""
+        es = self.entries(name)
+        if version is not None:
+            es = [e for e in es if e.version == version]
+        out = []
+        for e in es:
+            if e.repo not in out:
+                out.append(e.repo)
+        return out
+
+    def meta(self, name):
+        """→ {section, priority}（取最新版本条目），供卸载分类用。"""
+        e = self.top(name)
+        return {"section": e.section, "priority": e.priority} if e else {}
+
+    def search(self, q, limit=30):
+        """按包名/描述搜索。
+        排名：完全匹配 > 前缀 > 名字含 > 描述含 > 分词全命中。最后一级用分词，
+        让 "zen browser" 这类多词查询也能命中名字里用下划线/连字符的包。
+        先全量扫描再排序——原实现边扫边在 limit*3 处 break，结果取决于 dict
+        插入顺序，会漏掉更优匹配。"""
+        q = (q or "").lower().strip()
+        if not q:
+            return []
+        tokens = query_tokens(q)
+        hits = []
+        for name in self._entries:
+            nl = name.lower()
+            e = self.top(name)
+            desc = ((e.desc if e else "") or "").lower()
+            if nl == q:
+                rank = 0
+            elif nl.startswith(q):
+                rank = 1
+            elif q in nl:
+                rank = 2
+            elif q in desc:
+                rank = 3
+            elif matches_tokens(f"{name} {desc}", tokens):
+                rank = 4
+            else:
+                continue
+            hits.append((rank, name))
+        hits.sort()
+        out = []
+        for _rank, name in hits[:limit]:
+            e = self.top(name)
+            out.append({"name": name, "version": e.version, "repo": e.repo,
+                        "suite": e.suite, "component": e.component,
+                        "maintainer": e.maintainer, "size_kb": e.size_kb,
+                        "date": e.date, "desc": e.desc, "section": e.section})
+        return out
+
+    def info(self, name):
+        """单包详情：全部版本（每源每版本一条）。"""
+        es = self.entries(name)
+        if not es:
+            return None
+        # RepoEntry 是 slots dataclass，vars() 会抛 TypeError，得用 asdict
+        return {"name": name, "candidate": self.candidate(name),
+                "versions": [asdict(e) for e in es]}
+
+
+_CACHE = {"t": 0.0, "mtime": None, "idx": None}
+_LOCK = threading.Lock()
+
+
+def _lists_mtime(lists_dir):
+    """目录 mtime：apt update 会重写列表文件，比单纯 TTL 更准。"""
+    try:
+        return os.path.getmtime(lists_dir)
+    except OSError:
+        return None
+
+
+def load_index(cfg=CFG, force=False):
+    """解析并缓存仓库索引；force=True 忽略缓存。"""
+    with _LOCK:
+        now = time.time()
+        mtime = _lists_mtime(cfg.apt_lists_dir)
+        if (_CACHE["idx"] is not None and not force
+                and now - _CACHE["t"] < cfg.index_cache_ttl
+                and _CACHE["mtime"] == mtime):
+            return _CACHE["idx"]
+        idx = _build(cfg)
+        _CACHE.update(t=now, mtime=mtime, idx=idx)
+        return idx
+
+
+def _build(cfg):
+    releases = _parse_releases(cfg.apt_lists_dir)
+    entries = {}
+    for path, prefix, suite, comp in _package_files(cfg.apt_lists_dir, cfg):
+        rel = _match_release(prefix, releases)
+        label = rel.label if rel else prefix
+        loc = "/".join(x for x in (suite or (rel.suite if rel else ""), comp) if x)
+        tag = f"{label} {loc}".strip()
+        date = rel.date if rel else ""
+        try:
+            with open_text(path) as fh:
+                for rec in _iter_records(fh):
+                    name, ver = rec.get("Package"), rec.get("Version")
+                    arch = rec.get("Architecture", "")
+                    if not name or not ver or arch not in cfg.index_arches:
+                        continue
+                    size = rec.get("Size", "")
+                    entries.setdefault(name, []).append(RepoEntry(
+                        version=ver, repo=tag, suite=suite, component=comp,
+                        arch=arch, maintainer=rec.get("Maintainer", "?"),
+                        size_kb=int(size) // 1024 if size.isdigit() else 0,
+                        filename=rec.get("Filename", ""), date=date,
+                        desc=rec.get("Description", "")[:160],
+                        section=rec.get("Section", ""),
+                        priority=rec.get("Priority", "")))
+        except OSError:
+            continue
+    return RepoIndex(entries)
+
+
+def is_upgrade(candidate, installed):
+    """仓库候选版本是否高于已安装版本。"""
+    return bool(candidate) and ver_gt(candidate, installed)

pkgtool/apt/logs.py

@@ -0,0 +1,83 @@
+"""pkgtool.apt.logs — dpkg.log / apt history.log 时间线解析。
+
+安装通道判定（base.Channel）的证据来源。合并原先两套 apt history 解析：
+deb_backend.parse_apt_history()（返回 {名: [(时间,版本)]}）和
+update_channels.apt_history_names()（返回名字集合，且用 split(", ") 拆条目，
+遇到版本括号内的逗号就拆错——靠正则补救）。这里统一成一个解析器。
+
+数据来源可信度：
+  /var/log/dpkg.log*        所有 dpkg 操作的时间线，含 dpkg -i，最接近事实
+  /var/log/apt/history.log* 仅 apt 系工具的操作记录（apt install ./x.deb 也在里面）
+两者都会轮转，查无记录时只能标 UNKNOWN，不能当成"没装过"。
+"""
+import re
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+from ..compress import iter_lines
+from ..config import CFG
+
+TS_FMT = "%Y-%m-%d %H:%M:%S"
+
+# dpkg.log: "2024-01-01 12:00:00 install bash:amd64 <none> 5.2-2ubuntu1"
+# 第 3 字段是安装前版本（新装时为 <none>），第 4 字段才是装上的版本。
+# 原实现取第 3 字段当版本号，拿到的一律是 "<none>"（好在只用了时间戳）。
+_DPKG_INSTALL_RE = re.compile(
+    r"^(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) install (\S+) (\S+)(?: (\S+))?")
+
+# apt history: "Install: libfoo:amd64 (1.2-3, automatic), bar:amd64 (4.5)"
+# 架构段可有可无，括号内可能带 ", automatic"，所以不能用逗号拆条目。
+_APT_ENTRY_RE = re.compile(r"([\w.+\-~]+)(?::[\w\-]+)?\s*\(([^)]*)\)")
+
+
+def parse_ts(text):
+    """→ datetime；解析不了返回 None（不抛）。"""
+    try:
+        return datetime.strptime(" ".join((text or "").split()), TS_FMT)
+    except (ValueError, TypeError):
+        return None
+
+
+def dpkg_installs(cfg=CFG):
+    """→ ({包名: (首次 install 时间, 版本)}, 全局最早事件时间)。
+    只取每个包的第一次 install 事件；earliest 用于推算系统"出生时间"。"""
+    first = {}
+    earliest = None
+    for line in iter_lines([cfg.dpkg_log_glob]):
+        m = _DPKG_INSTALL_RE.match(line)
+        if not m:
+            continue
+        ts, pkg, _old, new = m.groups()
+        pkg = pkg.split(":")[0]
+        if earliest is None or ts < earliest:
+            earliest = ts
+        if pkg not in first:
+            first[pkg] = (ts, new or "")
+    return first, earliest
+
+
+def apt_history(cfg=CFG):
+    """→ {包名: [(时间, 版本字符串), ...]}，来自 Install/Upgrade 行。
+    括号里的 ", automatic" 是 apt 的自动安装标记不是版本的一部分，
+    剥掉（Upgrade 行的 "旧版, 新版" 双版本则保留）。"""
+    out = defaultdict(list)
+    cur_ts = ""
+    for line in iter_lines([cfg.apt_history_glob]):
+        if line.startswith("Start-Date:"):
+            cur_ts = " ".join(line.split(":", 1)[1].split())
+        elif line.startswith(("Install:", "Upgrade:")):
+            for name, ver in _APT_ENTRY_RE.findall(line):
+                parts = [p.strip() for p in ver.split(",")]
+                if parts and parts[-1] == "automatic":
+                    parts = parts[:-1]
+                out[name].append((cur_ts, ", ".join(parts)))
+    return dict(out)
+
+
+def birth_cutoff(earliest_ts, cfg=CFG):
+    """系统"出生时间"上界 = 日志最早事件 + birth_margin_hours。
+    在此窗口内装入且无 apt 记录的包，判为镜像自带。日志缺失时返回 None。"""
+    start = parse_ts(earliest_ts)
+    if start is None:
+        return None
+    return start + timedelta(hours=cfg.birth_margin_hours)

pkgtool/apt/version.py

@@ -0,0 +1,92 @@
+"""pkgtool.apt.version — Debian 版本号比较（dpkg verrev 算法，纯标准库实现）。
+
+版本格式：[epoch:]upstream_version[-debian_revision]
+比较规则（dpkg/version.c）：
+  · epoch 按整数比，缺省为 0
+  · upstream 与 revision 各自交替比较「非数字段」和「数字段」：
+      非数字段逐字符按 order() 排序，数字段整体按数值（前导零无意义）
+  · order(): '~' < 字符串结束 < 数字 < 字母 < 其他符号
+"""
+
+
+def _order(ch):
+    """dpkg 的字符序。ch=None 表示字符串已结束。"""
+    if ch == "~":
+        return -1
+    if ch is None:
+        return 0
+    if ch.isdigit():
+        return 0
+    if ch.isalpha():
+        return ord(ch)
+    return ord(ch) + 256
+
+
+def _nondigit(s, i):
+    j = i
+    while j < len(s) and not s[j].isdigit():
+        j += 1
+    return s[i:j], j
+
+
+def _digit(s, i):
+    j = i
+    while j < len(s) and s[j].isdigit():
+        j += 1
+    return s[i:j], j
+
+
+def _cmp_part(a, b):
+    """交替比较非数字段与数字段，直到两边都走完。"""
+    i = j = 0
+    while i < len(a) or j < len(b):
+        sa, i = _nondigit(a, i)
+        sb, j = _nondigit(b, j)
+        for k in range(max(len(sa), len(sb))):
+            ca = sa[k] if k < len(sa) else None
+            cb = sb[k] if k < len(sb) else None
+            oa, ob = _order(ca), _order(cb)
+            if oa != ob:
+                return -1 if oa < ob else 1
+        da, i = _digit(a, i)
+        db, j = _digit(b, j)
+        na = int(da) if da else 0
+        nb = int(db) if db else 0
+        if na != nb:
+            return -1 if na < nb else 1
+    return 0
+
+
+def _split(v):
+    """→ (epoch, upstream, revision)。"""
+    v = (v or "").strip()
+    epoch = 0
+    if ":" in v:
+        head, v = v.split(":", 1)
+        epoch = int(head) if head.isdigit() else 0
+    up, sep, rev = v.rpartition("-")   # 最后一个连字符之后才是 debian revision
+    if not sep:
+        up, rev = v, ""
+    return epoch, up, rev
+
+
+def ver_cmp(a, b):
+    """Debian 版本比较 → -1 / 0 / 1。"""
+    ea, ua, ra = _split(a)
+    eb, ub, rb = _split(b)
+    if ea != eb:
+        return -1 if ea < eb else 1
+    return _cmp_part(ua, ub) or _cmp_part(ra, rb)
+
+
+def ver_gt(a, b):
+    return ver_cmp(a, b) > 0
+
+
+def newest(versions):
+    """一组版本字符串里最高的那个；空序列返回 ""。"""
+    best = ""
+    for v in versions:
+        if not best or ver_gt(v, best):
+            best = v
+    return best

pkgtool/backends/__init__.py

@@ -0,0 +1,30 @@
+"""pkgtool.backends — 各包格式采集器的注册表。
+
+新增一种格式 = 新建 <fmt>.py 实现 Backend 子类 + 在 BACKENDS 里加一行，
+其余模块（inventory / classify / report / cli / app）都不需要改。
+"""
+from ..base import Backend
+from ..config import CFG
+from .appimage import AppImageBackend
+from .deb import DebBackend
+from .flatpak import FlatpakBackend
+from .linyap import LinyapBackend
+from .snap import SnapBackend
+
+BACKENDS = (DebBackend, SnapBackend, FlatpakBackend, LinyapBackend,
+            AppImageBackend)
+
+
+def available_backends(cfg=CFG):
+    """本机存在对应包管理体系的后端类（available() 不得抛异常）。"""
+    return [b for b in BACKENDS if b.available(cfg)]
+
+
+def discover(cfg=CFG):
+    """→ 本机可用后端的实例列表。"""
+    return [b(cfg) for b in available_backends(cfg)]
+
+
+__all__ = ["BACKENDS", "Backend", "available_backends", "discover",
+           "DebBackend", "SnapBackend", "FlatpakBackend", "LinyapBackend",
+           "AppImageBackend"]

pkgtool/backends/appimage.py

@@ -0,0 +1,145 @@
+"""pkgtool.backends.appimage — AppImage 嗅探（纯被动，不执行目标文件）。
+
+原理：AppImage v1/v2 = ELF 运行时 + 追加的 squashfs 负载。
+  1. 扫描用户区域找 *.AppImage（主目录/下载、~/Applications、/opt…）
+  2. 在文件里找 squashfs 超块（魔数 hsqs + block_size 是 4096~1MB 的 2 次幂
+     + inode 数合理），避开 ELF 运行时内嵌 unsquashfs 代码里的字符串误报
+  3. `unsquashfs -o <off> -l` 列出负载（只读目录树，不解压不执行）：
+     取 .desktop 文件名作显示名、usr/bin/* 作可执行文件
+  4. 版本号从文件名解析（CC-Switch-v3.20.4-Linux-x86_64 → 3.20.4）
+位置语义：~/Applications、/opt、/usr/local/bin 下 = 已安置的便携应用；
+下载等散落区域 = 未安装的包文件（extra["loose"]，与 deb 散落文件同构）。
+"""
+import os
+import re
+import shutil
+import struct
+import subprocess
+import time
+
+from ..base import Backend, OriginKind, PackageRecord, file_size_mb, scan_file_areas
+from ..config import CFG
+
+# 核心版本号 + 可选预发布后缀（beta/rc…），避免吞掉 -Linux-x86_64 这类架构尾巴
+_VERSION_RE = re.compile(
+    r"v?(\d+(?:\.\d+)+[A-Za-z0-9.+~]*"
+    r"(?:-(?:beta|alpha|rc|dev|pre|nightly)[A-Za-z0-9.]*)?)")
+_USR_BIN_RE = re.compile(r"(?:^|/)usr/bin/([^/]+)$")
+
+
+def _squashfs_offset(path, limit):
+    """找 squashfs 超块偏移；找不到返回 None。"""
+    try:
+        with open(path, "rb") as fh:
+            data = fh.read(limit)
+    except OSError:
+        return None
+    i = 0
+    while True:
+        i = data.find(b"hsqs", i)
+        if i < 0 or i + 16 > len(data):
+            return None
+        # 超块布局: magic(4) + inode_count(4) + creation_time(4) + block_size(4)
+        inodes, _mtime, blk = struct.unpack("<III", data[i + 4:i + 16])
+        if (blk and (blk & (blk - 1)) == 0 and 4096 <= blk <= 1 << 20
+                and 0 < inodes < 10 ** 6):
+            return i
+        i += 1
+
+
+def _payload_listing(path, offset, cfg):
+    """unsquashfs -l → (显示名, [usr/bin 可执行])。失败返回 ("", [])。"""
+    if not shutil.which("unsquashfs"):
+        return "", []
+    try:
+        p = subprocess.run(["unsquashfs", "-q", "-o", str(offset), "-l", path],
+                           capture_output=True, text=True, timeout=cfg.timeout_query)
+    except (OSError, subprocess.SubprocessError):
+        return "", []
+    display, bins = "", []
+    for line in p.stdout.splitlines():
+        line = line.strip()
+        if not line or "/" not in line:
+            continue
+        base = line.rsplit("/", 1)[-1]
+        if not display and base.endswith(".desktop"):
+            display = base[: -len(".desktop")]
+        m = _USR_BIN_RE.search(line)
+        if m and m.group(1) not in cfg.appimage_xdg_wrappers:
+            bins.append(m.group(1))
+    return display, bins[:cfg.appimage_max_exes]
+
+
+def _version_from_name(stem):
+    found = _VERSION_RE.findall(stem)
+    return found[-1] if found else ""
+
+
+class AppImageBackend(Backend):
+    pkg_type = "appimage"
+
+    @classmethod
+    def available(cls, cfg=CFG):
+        home = cfg.home
+        cands = [os.path.join(home, d) for d in
+                 cfg.appimage_app_dirs + cfg.appimage_download_dirs]
+        cands += list(cfg.appimage_system_dirs)
+        return any(os.path.isdir(d) for d in cands)
+
+    def _settled_dirs(self):
+        """已安置目录：这些位置下的 .AppImage 算便携应用，其余算散落文件。"""
+        home = self.cfg.home
+        return [os.path.join(home, d) for d in self.cfg.appimage_app_dirs] \
+            + list(self.cfg.appimage_system_dirs)
+
+    def _record(self, path, loose):
+        cfg = self.cfg
+        fn = os.path.basename(path)
+        stem = fn.rsplit(".", 1)[0] if "." in fn else fn
+        try:
+            mtime = time.strftime("%Y-%m-%d", time.localtime(os.path.getmtime(path)))
+        except OSError:
+            mtime = ""
+
+        name, exes = stem, []
+        off = _squashfs_offset(path, cfg.appimage_scan_limit)
+        if off is not None:
+            display, exes = _payload_listing(path, off, cfg)
+            if display:
+                name = display
+        extra = {"found_at": path, "mtime": mtime}
+        if loose:
+            extra.update(loose=path, state="uninstalled",
+                         found_in=os.path.basename(os.path.dirname(path)))
+        return PackageRecord(
+            pkg_type=self.pkg_type, name=name,
+            version=_version_from_name(stem) or "?",
+            # name 取自 .desktop 显示名，两个不同文件可能同名；用文件名做变体，
+            # 否则 /opt 里已安置的和下载目录里散落的那份会互相顶掉
+            variant=fn,
+            origin_kind=OriginKind.FILE if loose else OriginKind.LOCAL,
+            size_mb=file_size_mb(path),
+            install_path=path, executables=exes, extra=extra)
+
+    def collect(self):
+        records, seen = [], set()
+
+        def add(path, loose):
+            try:
+                rp = os.path.realpath(path)
+            except OSError:
+                return
+            if rp in seen:
+                return
+            seen.add(rp)
+            records.append(self._record(path, loose))
+
+        for d in self._settled_dirs():
+            if not os.path.isdir(d):
+                continue
+            for f in sorted(os.listdir(d)):
+                if f.lower().endswith(".appimage"):
+                    add(os.path.join(d, f), loose=False)
+        for p in scan_file_areas((".appimage",), cfg=self.cfg):
+            add(p, loose=True)
+        return records