mirror of
https://gitee.com/spark-store-project/spark-store
synced 2026-04-30 03:10:16 +08:00
修复更新器打开卡顿，优化更新中心
This commit is contained in:
365
docs/superpowers/specs/2026-04-14-gitee-issue-bot-design.md
Normal file
365
docs/superpowers/specs/2026-04-14-gitee-issue-bot-design.md
Normal file
@@ -0,0 +1,365 @@
|
||||
# Gitee Issue 巡检与 Opencode 启动设计
|
||||
|
||||
## 背景
|
||||
|
||||
当前仓库没有一个稳定的自动化流程，能够按固定周期检查 `https://gitee.com/spark-store-project/spark-store/issues`，筛出当前“最新且最重要”的 issue，并在人工确认后自动拉起新的 opencode 进程开始分析与修复。
|
||||
|
||||
你的目标不是让机器人直接静默修复，而是建立一个半自动流程：
|
||||
|
||||
1. 每 6 小时自动检查一次 Gitee issues。
|
||||
2. 自动筛出 1 个当前最值得处理的候选 issue。
|
||||
3. 默认只汇报，不自动开始修改。
|
||||
4. 你确认后，自动打开新的 opencode 窗口开始处理。
|
||||
5. 后续实际开始修改代码时，仍然以 `~/Desktop/spark-store` 作为基仓库，但必须通过 git worktree 从 `Erotica` 分支开出新分支，在隔离工作区中执行修改。
|
||||
|
||||
## 目标
|
||||
|
||||
1. 使用 `systemd --user` 定时器实现每 6 小时自动巡检。
|
||||
2. 每轮最多选择 1 个 issue 作为候选项。
|
||||
3. 候选项必须有可解释的评分结果，便于人工确认。
|
||||
4. 默认不自动修复，只记录候选状态并等待批准。
|
||||
5. 批准后自动启动新的 opencode 窗口，并把 issue 上下文传入。
|
||||
6. 为后续修复流程固定 worktree 约束：从 `Erotica` 分支开新分支，并保持 `~/Desktop/spark-store` 作为主仓库入口。
|
||||
7. 整个方案尽量独立于 Electron 主进程现有运行逻辑，避免把定时调度耦合进应用本体。
|
||||
|
||||
## 非目标
|
||||
|
||||
1. 不在本次实现中加入“自动修复后自动提交 PR”之类更长的链路。
|
||||
2. 不在本次实现中加入应用内 GUI 审批界面。
|
||||
3. 不在本次实现中实现复杂的 AI 优先级判断；优先使用透明、可维护的规则评分。
|
||||
4. 不在本次实现中把 issue 处理结果自动回写到 Gitee。
|
||||
5. 不在本次实现中实际创建 worktree 并改代码；这里只固定后续执行约束和启动提示。
|
||||
|
||||
## 方案选择
|
||||
|
||||
本次考虑三种方案：
|
||||
|
||||
1. 用户级 `systemd` 定时器 + 独立 Node/TypeScript 巡检脚本 + 本地批准入口。
|
||||
2. 用户级 `systemd` 定时器 + Gitee 评论驱动批准。
|
||||
3. 完全接入 Electron，使用应用内常驻进程和弹窗审批。
|
||||
|
||||
最终选择方案 1。
|
||||
|
||||
原因：
|
||||
|
||||
1. 它最小化对现有桌面应用逻辑的侵入，不要求应用常驻。
|
||||
2. `systemd --user` 已符合你的运行环境偏好，也与仓库里已有的用户级后台命令模式一致。
|
||||
3. 本地批准入口最容易落地，不依赖额外的 Gitee 写权限和 webhook/comment 解析。
|
||||
4. 后续如果要升级成评论审批或 GUI 审批，也可以在该方案基础上扩展。
|
||||
|
||||
## 设计概览
|
||||
|
||||
新增一个独立的 issue 巡检子系统，由五部分组成：
|
||||
|
||||
1. `check-issues` 巡检入口：抓取 issue、打分、落本地状态。
|
||||
2. `state` 状态层：保存当前候选项、历史批准记录和最近一次运行结果。
|
||||
3. `approve-issue` 批准入口：由你手动触发，读取当前候选项并进入启动流程。
|
||||
4. `opencode launcher`：负责拼接 issue prompt 并打开新的 opencode 窗口。
|
||||
5. `systemd --user` 单元：负责每 6 小时调度巡检入口。
|
||||
|
||||
整体数据流分为两个阶段：
|
||||
|
||||
1. 自动巡检阶段：仅发现和记录，不启动修复。
|
||||
2. 人工批准阶段：由你确认后，才启动新的 opencode 会话。
|
||||
|
||||
## 文件与模块边界
|
||||
|
||||
### 脚本入口
|
||||
|
||||
- 新增：`scripts/issue-bot/check-issues.ts`
|
||||
- 负责单次巡检执行。
|
||||
- 拉取 Gitee issues。
|
||||
- 调用评分逻辑选出候选项。
|
||||
- 写入状态文件和运行日志。
|
||||
|
||||
- 新增：`scripts/issue-bot/approve-issue.ts`
|
||||
- 负责读取当前候选项。
|
||||
- 检查是否已有未完成批准任务。
|
||||
- 标记当前 issue 为已批准。
|
||||
- 调用 opencode 启动器。
|
||||
|
||||
### 共享库
|
||||
|
||||
- 新增：`scripts/issue-bot/lib/gitee.ts`
|
||||
- 封装 issue 列表获取与基础字段归一化。
|
||||
- 输出统一结构，例如：`id`、`title`、`url`、`state`、`createdAt`、`updatedAt`、`labels`、`bodyPreview`。
|
||||
|
||||
- 新增：`scripts/issue-bot/lib/ranking.ts`
|
||||
- 根据“最新且最重要”的规则计算分数。
|
||||
- 输出总分和评分明细，便于人工解释。
|
||||
|
||||
- 新增：`scripts/issue-bot/lib/state.ts`
|
||||
- 负责本地状态读写。
|
||||
- 处理状态文件缺失、损坏、备份与迁移。
|
||||
|
||||
- 新增：`scripts/issue-bot/lib/opencode.ts`
|
||||
- 负责生成发给 opencode 的 prompt。
|
||||
- 负责调用本地 opencode 启动命令。
|
||||
- 固定写入 worktree 执行约束。
|
||||
|
||||
### 配置与调度
|
||||
|
||||
- 新增：`extras/systemd/spark-store-issue-bot.service`
|
||||
- 用户级一次性服务，执行单轮巡检。
|
||||
|
||||
- 新增：`extras/systemd/spark-store-issue-bot.timer`
|
||||
- 每 6 小时触发一次 service。
|
||||
|
||||
- 修改：`package.json`
|
||||
- 增加 `issue-bot:check`。
|
||||
- 增加 `issue-bot:approve`。
|
||||
|
||||
## 本地状态模型
|
||||
|
||||
建议把状态文件写到用户目录下的缓存位置，而不是仓库内，避免污染工作区。
|
||||
|
||||
建议路径：`~/.cache/spark-store/issue-bot/state.json`
|
||||
|
||||
状态至少包含：
|
||||
|
||||
```ts
|
||||
interface IssueBotState {
|
||||
currentCandidate: RankedIssue | null;
|
||||
approvedIssue: ApprovedIssue | null;
|
||||
seenIssueIds: number[];
|
||||
lastRunAt: string | null;
|
||||
lastRunStatus: "idle" | "success" | "network-error" | "parse-error";
|
||||
lastRunMessage: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
其中：
|
||||
|
||||
1. `currentCandidate` 表示当前等待你批准的候选 issue。
|
||||
2. `approvedIssue` 表示已经批准并已启动 opencode 的 issue，用于避免重复批准。
|
||||
3. `seenIssueIds` 用于辅助去重，避免每轮都反复选择同一批低质量 issue。
|
||||
4. `lastRun*` 用于排查巡检失败原因。
|
||||
|
||||
## Gitee 拉取策略
|
||||
|
||||
优先顺序如下：
|
||||
|
||||
1. 若存在可稳定使用的 Gitee API，则优先使用 API。
|
||||
2. 若 API 受限或字段不足，则退回页面抓取。
|
||||
|
||||
无论采用哪种来源，`gitee.ts` 对外只暴露统一的 issue 数据结构，不把 HTML 解析细节传播到评分层和状态层。
|
||||
|
||||
抓取范围只包含：
|
||||
|
||||
1. 打开的 issue。
|
||||
2. 当前仓库 `spark-store-project/spark-store`。
|
||||
3. 必需字段能提取成功的 issue。
|
||||
|
||||
如果本轮无法获取完整 issue 列表：
|
||||
|
||||
1. 记录错误。
|
||||
2. 不覆盖现有 `currentCandidate`。
|
||||
3. 结束本轮执行，等待下次 timer。
|
||||
|
||||
## 排序与筛选规则
|
||||
|
||||
评分逻辑使用可解释的静态规则，不做黑盒决策。
|
||||
|
||||
### 基础过滤
|
||||
|
||||
先过滤掉以下 issue：
|
||||
|
||||
1. 已关闭 issue。
|
||||
2. 已批准且尚未被显式清理的 issue。
|
||||
3. 缺少标题或链接等关键字段的异常项。
|
||||
|
||||
### 加分项
|
||||
|
||||
以下情况加分：
|
||||
|
||||
1. 标题或内容包含高影响关键词：`崩溃`、`打不开`、`无法安装`、`升级失败`、`卡死`、`白屏`、`闪退`。
|
||||
2. 与主流程强相关：安装、卸载、更新、启动、搜索、列表加载。
|
||||
3. 最近创建或最近更新。
|
||||
4. 含有复现步骤、日志、截图、错误信息。
|
||||
5. 带有明显 bug 类型标签。
|
||||
|
||||
### 减分项
|
||||
|
||||
以下情况减分：
|
||||
|
||||
1. 纯咨询类或需求讨论类 issue。
|
||||
2. 信息过少，例如只有一句“不能用”。
|
||||
3. 明显重复、无明确可执行内容。
|
||||
|
||||
### 产出格式
|
||||
|
||||
`ranking.ts` 输出不只包含总分，还包含明细，例如：
|
||||
|
||||
```ts
|
||||
interface RankingBreakdown {
|
||||
total: number;
|
||||
reasons: string[];
|
||||
}
|
||||
```
|
||||
|
||||
状态文件和批准前摘要都需要携带这些明细，确保“为什么选它”是透明的。
|
||||
|
||||
## 巡检流程
|
||||
|
||||
`check-issues.ts` 的单轮行为固定为：
|
||||
|
||||
1. 读取本地状态。
|
||||
2. 拉取 Gitee issue 列表。
|
||||
3. 标准化数据。
|
||||
4. 按过滤规则剔除不可处理项。
|
||||
5. 计算每个 issue 的分数。
|
||||
6. 选出得分最高的 1 个 issue。
|
||||
7. 将其写入 `currentCandidate`。
|
||||
8. 更新 `lastRunAt`、`lastRunStatus` 和摘要信息。
|
||||
|
||||
如果没有候选项：
|
||||
|
||||
1. 将 `currentCandidate` 设为 `null`。
|
||||
2. 写入“本轮无可处理 issue”的状态。
|
||||
3. 不触发任何后续动作。
|
||||
|
||||
## 批准流程
|
||||
|
||||
`approve-issue.ts` 的行为固定为：
|
||||
|
||||
1. 读取本地状态。
|
||||
2. 检查 `currentCandidate` 是否存在。
|
||||
3. 检查是否已有 `approvedIssue` 正在等待处理结果。
|
||||
4. 若可批准，则将候选项复制到 `approvedIssue`。
|
||||
5. 调用 opencode 启动器。
|
||||
6. 启动成功后保留 `approvedIssue`，并可选择清空 `currentCandidate`。
|
||||
|
||||
本次实现采用保守策略：
|
||||
|
||||
1. 启动成功后，清空 `currentCandidate`。
|
||||
2. 保留 `approvedIssue`，避免同一 issue 被重复批准。
|
||||
|
||||
后续如果需要“已完成”或“已放弃”清理动作，可以再补一个独立命令。
|
||||
|
||||
## Opencode 启动器设计
|
||||
|
||||
`opencode.ts` 负责两件事：
|
||||
|
||||
1. 生成 prompt。
|
||||
2. 调用本地 opencode 启动命令。
|
||||
|
||||
### Prompt 内容
|
||||
|
||||
prompt 需要至少包含：
|
||||
|
||||
1. issue 标题。
|
||||
2. issue URL。
|
||||
3. issue 摘要。
|
||||
4. 评分原因。
|
||||
5. 任务目标：分析根因并开始修复。
|
||||
6. 明确约束：开始修改时，基仓库使用 `~/Desktop/spark-store`，但实际编码必须通过 git worktree，从 `Erotica` 分支开出新分支后进行。
|
||||
|
||||
### Worktree 约束
|
||||
|
||||
批准后启动的新 opencode 会话中，必须显式看到以下执行约束：
|
||||
|
||||
1. 基仓库固定为 `~/Desktop/spark-store`。
|
||||
2. 真正开始修改代码前，使用 git worktree 创建隔离工作区。
|
||||
3. 新 worktree 必须从 `Erotica` 分支开出新的工作分支。
|
||||
4. 修复工作在该 worktree 中进行，而不是直接在主仓库工作目录中进行。
|
||||
|
||||
这里的职责是“把约束传给后续修复会话”，而不是在当前巡检脚本里代替用户创建 worktree。
|
||||
|
||||
### 启动命令配置
|
||||
|
||||
不要把 opencode 启动命令硬编码成不可修改的固定路径。
|
||||
|
||||
推荐顺序：
|
||||
|
||||
1. 读取环境变量，例如 `SPARK_STORE_OPENCODE_CMD`。
|
||||
2. 若未配置，则退回默认命令模板。
|
||||
3. 若命令不存在，返回明确错误并保留 `currentCandidate`/`approvedIssue` 状态供重试。
|
||||
|
||||
## systemd 调度设计
|
||||
|
||||
使用用户级 systemd 单元：
|
||||
|
||||
### `spark-store-issue-bot.service`
|
||||
|
||||
职责：
|
||||
|
||||
1. 调用一次 `issue-bot:check`。
|
||||
2. 以 oneshot 形式运行。
|
||||
3. 将日志交给 systemd journal。
|
||||
|
||||
### `spark-store-issue-bot.timer`
|
||||
|
||||
职责：
|
||||
|
||||
1. 每 6 小时触发一次 service。
|
||||
2. 启用持久化调度，使设备休眠后恢复时仍可补跑。
|
||||
|
||||
不把批准动作放进 timer，因为批准必须由人工触发。
|
||||
|
||||
## 错误处理
|
||||
|
||||
### 网络或解析失败
|
||||
|
||||
1. 记录 `lastRunStatus` 为失败类型。
|
||||
2. 保留旧候选项，不清空有效状态。
|
||||
3. 输出清晰日志，供 `journalctl --user` 排查。
|
||||
|
||||
### 状态文件损坏
|
||||
|
||||
1. 读取失败时先备份原文件。
|
||||
2. 生成新的空状态。
|
||||
3. 在日志中注明发生了状态恢复。
|
||||
|
||||
### 启动 opencode 失败
|
||||
|
||||
1. 不丢失候选 issue 信息。
|
||||
2. 记录失败信息到状态文件。
|
||||
3. 允许你修正环境后再次执行批准或重试命令。
|
||||
|
||||
## 测试与验证
|
||||
|
||||
### 脚本层验证
|
||||
|
||||
需要至少覆盖以下行为：
|
||||
|
||||
1. 有多个 issue 时，能按规则稳定选出得分最高的候选项。
|
||||
2. 无 issue 或全被过滤时，`currentCandidate` 正确为空。
|
||||
3. 状态文件缺失时能初始化默认状态。
|
||||
4. 状态文件损坏时能备份并恢复。
|
||||
5. 批准入口能读取候选项并更新状态。
|
||||
6. opencode 启动命令缺失时，能返回明确错误而不丢状态。
|
||||
|
||||
### 手动验证
|
||||
|
||||
需要人工验证：
|
||||
|
||||
1. `npm run issue-bot:check` 能成功写出候选项。
|
||||
2. 连续运行两次巡检，状态更新符合预期，没有异常重复。
|
||||
3. `npm run issue-bot:approve` 能基于当前候选项启动新的 opencode 窗口。
|
||||
4. 启动后的 prompt 中包含 worktree 约束和 `Erotica` 分支要求。
|
||||
5. `systemctl --user start spark-store-issue-bot.service` 可执行。
|
||||
6. `systemctl --user enable --now spark-store-issue-bot.timer` 后能看到 timer 生效。
|
||||
|
||||
### 仓库质量验证
|
||||
|
||||
完成实现后，至少执行：
|
||||
|
||||
1. `npm run lint`
|
||||
2. `npm run build:vite`
|
||||
|
||||
如果脚本新增了独立测试，还要运行相应测试命令。
|
||||
|
||||
## 风险与约束
|
||||
|
||||
1. Gitee 页面结构可能变化，因此 `gitee.ts` 需要把抓取逻辑局部化，避免影响其他模块。
|
||||
2. “最重要”本质上是启发式规则，不保证绝对正确，因此必须保留人工批准环节。
|
||||
3. 如果 opencode 的命令行接口或窗口启动方式在本机环境中变化，需要通过配置而不是源码硬编码来适配。
|
||||
4. worktree 约束属于后续修复会话的执行要求，当前设计只负责传达和固化，不负责提前改变用户当前工作区。
|
||||
|
||||
## 决策总结
|
||||
|
||||
1. 用 `systemd --user` 定时器每 6 小时巡检一次 Gitee issues。
|
||||
2. 每轮只选 1 个“最新且最重要”的候选 issue。
|
||||
3. 默认只汇报，不自动修复。
|
||||
4. 你批准后，再自动拉起新的 opencode 窗口。
|
||||
5. 启动 prompt 中必须固定写明：后续开始修改时，以 `~/Desktop/spark-store` 为基仓库，并通过 git worktree 从 `Erotica` 分支开新分支后执行修复。
|
||||
@@ -0,0 +1,276 @@
|
||||
# 已安装应用管理与更新中心加载态设计
|
||||
|
||||
## 背景
|
||||
|
||||
当前仓库里有三个直接影响体验的问题：
|
||||
|
||||
1. 更新中心调用 `updateCenterStore.open()` 时，会先等待主进程返回快照，再决定是否展示模态框。用户在数据返回前看不到任何反馈，主观感受就是“打开很慢”。
|
||||
2. 软件管理里 `spark` 来源当前直接读取 `dpkg-query -W` 的全量安装包，结果混入了大量没有桌面入口的系统包，与“软件管理”应管理可见应用的预期不符。
|
||||
3. 软件管理弹窗目前只有“卸载”操作，没有“打开”操作；同时 `src/App.vue` 对 `spark` 来源还有一条“若不在远端商店目录中则直接跳过”的过滤，会导致本机已有桌面应用即使后端已发现，也不会展示出来。
|
||||
|
||||
本次设计的目标是用最小改动修复这三个问题，不重做更新中心和软件管理的整体结构。
|
||||
|
||||
## 目标
|
||||
|
||||
1. 更新中心在用户触发打开时立即显示模态框，并展示明确的加载反馈。
|
||||
2. `spark` 软件管理改为基于 `/usr/share/applications` 的桌面应用扫描，而不是全量系统包扫描。
|
||||
3. `spark` 桌面应用通过 `realpath` 后的 desktop 文件路径，结合 `dpkg -S <desktop-path>` 反查所属包名。
|
||||
4. `apm` 软件管理保持现有 `apm list --installed` 语义，继续展示依赖项。
|
||||
5. 软件管理弹窗中的已安装项支持直接打开软件，复用当前已有的应用启动 IPC，而不是新增一套启动协议。
|
||||
|
||||
## 非目标
|
||||
|
||||
1. 不重构更新中心的主进程数据加载流程。
|
||||
2. 不把软件管理改成“每个 desktop 入口一条记录”；本次仍按“每个包一条记录”展示。
|
||||
3. 不改变 `apm` 来源中依赖项继续显示的现有产品决定。
|
||||
4. 不新增应用启动器脚本，也不修改 `launch-app` IPC 的入参与调用协议。
|
||||
5. 不把软件管理改造成新的独立模块或完整应用索引子系统。
|
||||
|
||||
## 方案概览
|
||||
|
||||
本次改动拆成三条最小链路：
|
||||
|
||||
1. 更新中心在渲染层增加独立加载态，让模态框先出现，再等待主进程快照。
|
||||
2. `list-installed("spark")` 改为扫描 `/usr/share/applications` 并反查包名，再补齐版本、架构与图标信息。
|
||||
3. 已安装应用弹窗增加“打开”按钮，并移除 `spark` 来源依赖远端商店目录的前端过滤，让本机已发现的桌面应用能够真正显示与启动。
|
||||
|
||||
## 更新中心加载态
|
||||
|
||||
### 当前问题
|
||||
|
||||
`src/App.vue` 中的 `openUpdateModal()` 直接 `await updateCenterStore.open()`，而 `src/modules/updateCenter.ts` 的 `open()` 会在拿到完整快照后才把 `isOpen` 设为 `true`。因此用户点击后会先经历一段无反馈等待。
|
||||
|
||||
### 目标行为
|
||||
|
||||
1. 用户触发打开更新中心时，模态框立即出现。
|
||||
2. 数据尚未返回时，模态框主体显示“正在检查更新”的加载态，而不是空白区域。
|
||||
3. 首次打开完成后，正常展示更新列表或错误提示。
|
||||
4. 用户在已打开的更新中心里点击“刷新”时，继续使用同一加载状态字段，并禁用刷新按钮，避免重复触发。
|
||||
|
||||
### 设计
|
||||
|
||||
在 `src/modules/updateCenter.ts` 中为 `UpdateCenterStore` 新增渲染层加载状态，例如 `loading: Ref<boolean>`。
|
||||
|
||||
行为规则：
|
||||
|
||||
1. `open()` 调用开始时：
|
||||
- 先重置本次会话状态；
|
||||
- 立即设置 `isOpen.value = true`；
|
||||
- 设置 `loading.value = true`；
|
||||
- 然后再等待 `window.updateCenter.open()`。
|
||||
2. `open()` 成功或失败结束时：
|
||||
- 统一将 `loading.value = false`。
|
||||
3. `refresh()` 开始时：
|
||||
- 设置 `loading.value = true`；
|
||||
- 调用 `window.updateCenter.refresh()`；
|
||||
- 完成后再恢复 `loading.value = false`。
|
||||
4. `closeNow()` 时：
|
||||
- 关闭模态框；
|
||||
- 清理搜索、选中项与迁移确认状态；
|
||||
- 同时清理渲染层加载态，避免下次打开继承旧状态。
|
||||
|
||||
### UI 呈现
|
||||
|
||||
`src/components/UpdateCenterModal.vue` 负责根据 `store.loading.value` 切换内容：
|
||||
|
||||
1. 当 `loading === true` 且还没有可展示项时，列表区域显示居中的加载卡片或 spinner，文案为“正在检查更新…”。
|
||||
2. 当 `loading === true` 且已有旧列表时，保留当前列表内容，同时在顶部或列表区域显示轻量的“正在刷新…”提示，避免刷新时内容闪烁清空。
|
||||
3. `src/components/update-center/UpdateCenterToolbar.vue` 中的刷新按钮在 `loading === true` 时禁用，并可复用现有刷新图标做旋转或弱化处理。
|
||||
|
||||
这个方案只在渲染层加状态，不改主进程 `update-center-open` / `update-center-refresh` 的 IPC 协议，因此不会影响现有更新中心服务与测试边界。
|
||||
|
||||
## `spark` 软件管理的桌面应用扫描规则
|
||||
|
||||
### 当前问题
|
||||
|
||||
`electron/main/backend/install-manager.ts` 中 `list-installed("spark")` 目前直接跑：
|
||||
|
||||
```bash
|
||||
dpkg-query -W -f=${Package} ${Version} ${Architecture}\n
|
||||
```
|
||||
|
||||
它得到的是全量系统包，而不是用户可管理的桌面软件。
|
||||
|
||||
### 目标行为
|
||||
|
||||
`spark` 来源的软件管理只显示 `/usr/share/applications` 下可映射到系统包的桌面应用，每个包只展示一个条目。
|
||||
|
||||
### 扫描算法
|
||||
|
||||
主进程对 `spark` 来源执行以下流程：
|
||||
|
||||
1. 枚举 `/usr/share/applications` 目录中的 `.desktop` 文件。
|
||||
2. 对每个候选文件执行 `realpath`，得到实际 desktop 路径，兼容软链接场景。
|
||||
3. 读取 desktop 内容，解析：
|
||||
- `Name`
|
||||
- `Icon`
|
||||
- `NoDisplay`
|
||||
4. 过滤规则：
|
||||
- 不是 `.desktop` 的文件直接跳过；
|
||||
- `NoDisplay=true` 的 desktop 跳过；
|
||||
- 无法读取、无法解析或 `realpath` 失败的条目跳过；
|
||||
- `dpkg -S <realpath后的desktop路径>` 无法定位所属包名的条目跳过。
|
||||
5. 对通过过滤的条目调用 `dpkg -S <desktop-path>` 反查所属包。
|
||||
6. 将 desktop 条目按包名去重：
|
||||
- 同一包命中多个有效 desktop 时，仅保留第一个有效条目；
|
||||
- “第一个”的定义以稳定排序后的 desktop 文件名遍历顺序为准，保证结果可预测。
|
||||
7. 收集到包名后，再补齐版本和架构信息，形成最终 `InstalledAppInfo[]`。
|
||||
|
||||
### 包信息补齐
|
||||
|
||||
为了保留当前软件管理卡片里的版本与架构展示，`spark` 来源仍需要版本与架构信息，但不再以它作为筛选源。
|
||||
|
||||
推荐做法：
|
||||
|
||||
1. 先通过 desktop 扫描得到有效包名集合。
|
||||
2. 再执行一次 `dpkg-query -W -f=${Package}\t${Version}\t${Architecture}\n` 构建元数据映射。
|
||||
3. 仅为扫描结果中出现的包补齐 `version` 和 `arch`。
|
||||
|
||||
这样保留了现有 UI 所需字段，同时避免再次回到“全量包即软件管理内容”的旧行为。
|
||||
|
||||
### 图标与名称
|
||||
|
||||
对于 `spark` 来源：
|
||||
|
||||
1. `name` 优先使用 desktop 的 `Name=`。
|
||||
2. `icon` 优先使用 desktop 的 `Icon=`；若图标字段是绝对路径，则延续现有 `file://` 使用方式；若是图标名，则允许继续走当前前端回退策略或显示默认占位。
|
||||
3. `pkgname` 以 `dpkg -S` 反查出的包名为准，而不是 desktop 文件名。
|
||||
|
||||
### 错误处理
|
||||
|
||||
桌面应用扫描必须按“单项失败不拖垮整体列表”处理：
|
||||
|
||||
1. 某个 desktop 读取失败，只跳过该项。
|
||||
2. 某个 desktop 无法反查包名，只跳过该项。
|
||||
3. 只有当整个目录无法读取、或关键命令整体失败时，才返回 `success: false` 给渲染层。
|
||||
|
||||
## `apm` 软件管理保持现状
|
||||
|
||||
`apm` 来源继续使用当前 `apm list --installed` 结果，行为保持不变：
|
||||
|
||||
1. 仍保留依赖项展示。
|
||||
2. 仍使用现有的 APM `entries/applications` 解析名称、图标与是否为依赖项。
|
||||
3. 不把 `apm` 来源改成纯 desktop 视角。
|
||||
|
||||
这样可以满足“apm 包含依赖”的明确要求，同时把本次修改范围限制在 `spark` 侧软件识别逻辑。
|
||||
|
||||
## 渲染层已安装应用列表修正
|
||||
|
||||
### 当前问题
|
||||
|
||||
`src/App.vue` 中 `refreshInstalledApps()` 当前有一条 `spark` 特有过滤：
|
||||
|
||||
1. 先在远端商店应用列表 `apps.value` 中寻找同名应用；
|
||||
2. 如果 `origin === "spark" && !appInfo`，则直接 `continue`。
|
||||
|
||||
这会让许多本机桌面应用即使被主进程发现，也不会显示在软件管理中。
|
||||
|
||||
### 新规则
|
||||
|
||||
1. `refreshInstalledApps()` 对 `spark` 与 `apm` 统一采用“远端有完整信息则复用，远端没有则构造最小 App 对象”的策略。
|
||||
2. 删除 `spark` 来源的“找不到远端目录就跳过”逻辑。
|
||||
3. 这样主进程发现的本机桌面应用，无论是否存在于远端商店分类 JSON 中，都能在软件管理中展示出来。
|
||||
|
||||
### 最小 App 对象
|
||||
|
||||
当远端列表中找不到对应应用时，继续构造最小 `App` 对象，并补齐以下关键字段：
|
||||
|
||||
1. `name`
|
||||
2. `pkgname`
|
||||
3. `version`
|
||||
4. `origin`
|
||||
5. `currentStatus: "installed"`
|
||||
6. `arch`
|
||||
7. `flags`
|
||||
8. `isDependency`
|
||||
9. `icons`（如主进程提供）
|
||||
|
||||
其他目录型字段继续使用当前最小占位值即可，不额外扩展模型。
|
||||
|
||||
## 软件管理“打开软件”交互
|
||||
|
||||
### 目标行为
|
||||
|
||||
已安装应用弹窗中的每一项都支持直接打开软件，且不影响现有“卸载”入口。
|
||||
|
||||
### 交互设计
|
||||
|
||||
`src/components/InstalledAppsModal.vue` 中每个应用项新增一个 `打开` 按钮：
|
||||
|
||||
1. 点击“打开”时向父组件发出 `open-app` 事件，并透传：
|
||||
- `pkgname`
|
||||
- `origin`
|
||||
2. “卸载”按钮保留。
|
||||
3. 对于没有可启动信息的项，不新增额外灰态逻辑，因为本次两侧都沿用包名启动；只要条目被纳入软件管理，就认为可以尝试启动。
|
||||
|
||||
### 启动链路
|
||||
|
||||
继续复用当前已有 IPC：`launch-app`
|
||||
|
||||
1. `spark` 来源继续执行：
|
||||
- `/opt/spark-store/extras/app-launcher start <pkgname>`
|
||||
2. `apm` 来源继续执行：
|
||||
- `apm launch <pkgname>`
|
||||
|
||||
这个 IPC 已被下载详情与应用详情页复用，因此本次不改协议，只把软件管理接入同一入口。
|
||||
|
||||
## 模块影响范围
|
||||
|
||||
### 主进程
|
||||
|
||||
1. `electron/main/backend/install-manager.ts`
|
||||
- 调整 `list-installed("spark")` 的发现逻辑。
|
||||
- 可按需要抽出一个小型 helper 处理 spark desktop 扫描，避免继续堆大单文件。
|
||||
|
||||
### 渲染层状态与页面
|
||||
|
||||
1. `src/modules/updateCenter.ts`
|
||||
- 新增加载态，并调整 `open()` / `refresh()` / `closeNow()` 的时序。
|
||||
2. `src/components/UpdateCenterModal.vue`
|
||||
- 根据加载态展示“正在检查更新”或“正在刷新”提示。
|
||||
3. `src/components/update-center/UpdateCenterToolbar.vue`
|
||||
- 刷新按钮支持禁用与加载视觉状态。
|
||||
4. `src/components/InstalledAppsModal.vue`
|
||||
- 新增“打开”按钮与 `open-app` 事件。
|
||||
5. `src/App.vue`
|
||||
- 打开更新中心时不再等待模态框延迟出现。
|
||||
- 修正 `spark` 来源软件列表的远端目录过滤。
|
||||
- 将软件管理中的 `open-app` 事件接到现有 `openDownloadedApp()`。
|
||||
|
||||
## 测试策略
|
||||
|
||||
### 更新中心
|
||||
|
||||
扩展以下测试：
|
||||
|
||||
1. `src/__tests__/unit/update-center/store.test.ts`
|
||||
- 覆盖 `open()` 在等待快照期间就已将 `isOpen` 置为 `true`。
|
||||
- 覆盖 `loading` 在 `open()` 与 `refresh()` 生命周期中的变化。
|
||||
2. `src/__tests__/unit/update-center/UpdateCenterModal.test.ts`
|
||||
- 覆盖加载态文案展示。
|
||||
- 覆盖刷新按钮在加载时被禁用。
|
||||
|
||||
### 软件管理
|
||||
|
||||
1. 为 `spark` desktop 扫描逻辑新增单元测试，覆盖：
|
||||
- 从 `/usr/share/applications` 发现有效 desktop；
|
||||
- 通过 `realpath + dpkg -S` 反查包名；
|
||||
- 跳过 `NoDisplay=true`；
|
||||
- 同包多个 desktop 仅保留一个；
|
||||
- 单个 desktop 失败不会让整批结果失败。
|
||||
2. 扩展 `src/__tests__/unit/InstalledAppsModal.test.ts`
|
||||
- 覆盖“打开”按钮可见；
|
||||
- 覆盖点击后会发出 `open-app` 事件。
|
||||
|
||||
### 回归验证
|
||||
|
||||
1. `spark` 来源软件管理仍可卸载。
|
||||
2. `apm` 来源软件管理仍保留依赖项显示。
|
||||
3. 下载详情与应用详情页已有的 `launch-app` 调用不受影响。
|
||||
|
||||
## 风险与约束
|
||||
|
||||
1. `dpkg -S` 输出格式可能包含架构后缀或多条匹配结果，解析时需要明确采用“第一条所有权记录”的稳定策略，并只提取包名部分。
|
||||
2. 某些 desktop 图标可能是主题图标名而非绝对路径；本次不重做图标解析，只保证名称与路径被正确透传。
|
||||
3. 如果某些本机桌面应用没有远端商店元数据，软件管理中会显示最小信息卡片；这是预期结果，因为需求本身就是“以本机 `/usr/share/applications` 为准”。
|
||||
4. 更新中心加载态只解决“无反馈等待”的问题，不保证主进程真实查询耗时本身缩短。
|
||||
Reference in New Issue
Block a user