Define icon UI event delivery task (T-607)
This commit is contained in:
@@ -45,7 +45,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,
|
||||
|
||||
## 当前阶段
|
||||
|
||||
当前项目已完成 Phase 0～2、T-301 与审核整改 `T-604`～`T-606`。Windows 安全路径阻断项与 Phase 2 首个图标缓存资源整改已关闭;下一步按 Phase 2 交叉审核顺序落成后台图标结果经 application event 回到 UI goroutine 的接线任务,其余审核整改与 Phase 1 中央目录预扫描继续串行处理,T-302 暂后置。
|
||||
当前项目已完成 Phase 0～2、T-301 与审核整改 `T-604`～`T-606`。Windows 安全路径阻断项与 Phase 2 首个图标缓存资源整改已关闭;Phase 2 第二个整改 `T-607` 已落成待领取,下一步实现后台图标结果经 application event 回到 UI goroutine 的线程接线,其余审核整改与 Phase 1 中央目录预扫描继续串行处理,T-302 暂后置。
|
||||
|
||||
优先路径:
|
||||
|
||||
@@ -53,7 +53,7 @@ SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,
|
||||
2. 已完成 Phase 1:清单验签、ZIP 安全解压、原子切换回滚原型。
|
||||
3. 已完成 Phase 2 与 T-301:清单/列表/详情/图标缓存 + 可恢复下载队列。
|
||||
4. 已完成 T-604:modern/Win7 workspace 与 Gio 版本解析彻底隔离。
|
||||
5. 已完成 T-606:图标缓存按 key 去重、流式有界读取、memory LRU 与双 shell 图标剪枝;下一步按审核顺序落成 UI 线程事件接线整改,再串行处理其余整改与 T-302/T-303、Phase 4-6。
|
||||
5. 已完成 T-606:图标缓存按 key 去重、流式有界读取、memory LRU 与双 shell 图标剪枝;下一步实现 T-607 的 UI 线程事件接线,再串行处理其余整改与 T-302/T-303、Phase 4-6。
|
||||
|
||||
## 领取任务规则
|
||||
|
||||
|
||||
+2
-1
@@ -59,11 +59,12 @@ Phase 1 安全整改按 `docs/review/phase1-security-review.md` 的交叉复核
|
||||
|
||||
#### Phase 2 交叉审核加固
|
||||
|
||||
Phase 2 整改按 `docs/review/phase2-review.md` 的交叉复核定稿顺序串行落成。T-606 先关闭正式图标接入前的并发、读取和内存边界;UI 线程投递、适配器契约、VisibleItems 快照与 shell 拆分在前一整改完成并提交后再正式编号。
|
||||
Phase 2 整改按 `docs/review/phase2-review.md` 的交叉复核定稿顺序串行落成。T-606 已关闭正式图标接入前的并发、读取和内存边界;T-607 建立后台图标结果经 application event 回到 Gio UI goroutine 的线程契约。适配器契约、VisibleItems 快照与 shell 拆分在前一整改完成并提交后再正式编号。
|
||||
|
||||
| ID | 任务 | 依赖 | 验收要点 |
|
||||
| --- | --- | --- | --- |
|
||||
| T-606 | 收紧图标缓存并发与内存边界 | T-204, T-605 | 按 key in-flight 去重且不同 key 并行;Fetcher 流式有界读取;memory LRU 同时限制字节/条目;modern/win7 删除 app 时剪枝内存 ImageOp |
|
||||
| T-607 | 建立图标后台结果的 UI 线程事件投递 | T-606 | 后台 Load/Decode 只发布 application event;有界 relay 请求重绘;UI goroutine drain 后 ApplyIcon;过期结果不回写已删除或已换图标的 app |
|
||||
|
||||
### Phase 3 · 下载与安装
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
## 当前快照
|
||||
|
||||
- 日期:2026-07-17
|
||||
- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列已完成;审核整改 T-604～T-606 已完成,T-302 继续暂后置
|
||||
- 阶段:Phase 2 已完成(T-201～T-204);Phase 3 的 T-301 可恢复下载队列已完成;审核整改 T-604～T-606 已完成,T-607 已落成待领取,T-302 继续暂后置
|
||||
- 技术栈:根 Go 1.25 workspace 只纳入 core/app-modern,`app-win7/go.work` 独立纳入 core/app-win7;版本闸门证明 modern Gio v0.10.1 与 win7 Gio v0.6.0 不交叉解析
|
||||
- 生产代码:core 已有 Catalog/本地状态/存储、共享 Windows 安全相对路径策略、安全 ZIP 解压/回滚原型、无 IO 软件列表模型、按 key in-flight + 流式有界读取 + 32 MiB/256-key LRU 的可信图标缓存,以及默认并发 2 的持久可恢复下载队列;modern/win7 AppShell 已实现搜索/分类/视图、惰性列表、详情右栏与随 Catalog 剪枝的内存图标
|
||||
- 测试:core 覆盖 Catalog、SemVer/12 状态、本地安装记录、Windows dot-space/设备名/Unicode 折叠路径攻击、ZIP destination 包含性、列表/图标并发/取消/读取边界/LRU、下载并发/暂停/取消/重试/Range/断连/恢复/事件失败与文件身份替换;两个 app 覆盖 500 项虚拟列表、ID 控件/图标剪枝稳定性、详情/ApplyIcon 与平台 stub;安装恢复矩阵保持通过
|
||||
@@ -21,14 +21,14 @@
|
||||
- 标准启动路径:`./init.sh` / `./init.ps1`(同步依赖、执行完整 Phase 0 闸门、打印双目标构建命令)
|
||||
- 标准验证路径:`bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1`
|
||||
- 版本管理:git 已初始化,main 分支,远端 origin 为 Gitea `opc/soft_quay`;harness 文档已提交
|
||||
- 当前 blocker:无;下一步按 `docs/review/phase2-review.md` 最终顺序落成图标后台结果经 application event 回到 UI goroutine 的接线任务;适配器契约、VisibleItems 快照、Phase 1 中央目录预扫描等继续串行,T-302 继续后置
|
||||
- 当前 blocker:无;下一步领取 T-607,建立图标后台 Load/Decode 经 application event、有界 relay 与 Invalidate 回到 Gio UI goroutine 的接线;适配器契约、VisibleItems 快照、Phase 1 中央目录预扫描等继续串行,T-302 继续后置
|
||||
|
||||
## 当前目录要点
|
||||
|
||||
| 路径 | 状态 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `docs/` | 已有 | harness coding 文档集(本次初始化完成) |
|
||||
| `docs/tasks/` | 已有 | Phase 0～2、T-301 与 T-604～T-606 已完成;其余审核整改尚未编号,T-302 暂后置 |
|
||||
| `docs/tasks/` | 已有 | Phase 0～2、T-301 与 T-604～T-606 已完成;T-607 已落成待领取,其余审核整改尚未编号,T-302 暂后置 |
|
||||
| `scripts/` | 已有 | harness 治理、core 边界、Go 版本检查与 Phase 0 双平台验证入口 |
|
||||
| `core/` | 已建 | Go 1.20 兼容;已有正式 Catalog、本地状态/存储、共享 Windows safepath、列表模型、有界并发图标缓存、可恢复下载队列与 Phase 1 安装安全原型 |
|
||||
| `app-modern/` | 已建 | Go 1.25.0 + Gio v0.10.1;Modern AppShell 已接入虚拟列表、详情和随 Catalog 剪枝的内存图标 |
|
||||
@@ -42,7 +42,7 @@
|
||||
|
||||
- 已完成:Phase 0 的 `T-001`～`T-004`;Phase 1 的 `T-101`、`T-102`、`T-103`;Phase 2 的 `T-201`～`T-204`;Phase 3 的 `T-301`;审核整改 `T-604`～`T-606`。
|
||||
- 正在进行:无。
|
||||
- 下一个可领取任务:无;先按 `docs/review/phase2-review.md` 最终顺序落成 UI 线程事件接线整改任务。
|
||||
- 下一个可领取任务:`T-607`(建立图标后台结果的 UI 线程事件投递),依赖 `T-606` 已完成。
|
||||
|
||||
## 当前可运行内容
|
||||
|
||||
|
||||
@@ -284,4 +284,5 @@ modern/win7 的 `ApplyIcon` 都直接写 `shell.icons` map,Layout 同时读取
|
||||
## 任务落地追踪
|
||||
|
||||
- `T-606` 已完成最终处理顺序第 1 项:按 key in-flight 去重、Fetcher 流式有界读取、32 MiB/256-key memory LRU 与 modern/win7 `shell.icons` 剪枝已实现并通过完整双 workspace 闸门。
|
||||
- UI 线程投递、适配器交互契约、`VisibleItems` 快照、`shell.go` 拆分和 unsafe cache 诊断尚未编号;下一任务从 UI 线程投递开始,继续按顺序串行落成。
|
||||
- `T-607` 已按最终处理顺序第 2 项落成待领取:后台图标 Load/Decode 只发布 application event,有界 relay 请求重绘,由 Gio UI goroutine drain 后执行 `ApplyEvent`/`ApplyIcon`,并拒绝过期结果回写。
|
||||
- 适配器交互契约、`VisibleItems` 快照、`shell.go` 拆分和 unsafe cache 诊断尚未编号;必须等待 T-607 完成并提交后再按顺序落成。
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
---
|
||||
id: T-607
|
||||
title: 建立图标后台结果的 UI 线程事件投递
|
||||
phase: 2
|
||||
deps: [T-606]
|
||||
status: TODO
|
||||
created: 2026-07-17
|
||||
issue: null
|
||||
context_ref: null
|
||||
claim_branch: null
|
||||
work_branch: null
|
||||
write_paths:
|
||||
- docs/tasks/T-607.md
|
||||
- core/application/
|
||||
- core/catalog/
|
||||
- app-modern/cmd/softbox/
|
||||
- app-modern/ui/gio/
|
||||
- app-win7/cmd/softbox/
|
||||
- app-win7/ui/gio/
|
||||
- docs/api.md
|
||||
- docs/routes.md
|
||||
- docs/04-architecture.md
|
||||
- docs/05-coding-rules.md
|
||||
- docs/review/phase2-review.md
|
||||
- docs/00-ai-start-here.md
|
||||
- docs/06-tasks.md
|
||||
- docs/current-state.md
|
||||
---
|
||||
|
||||
## 问题 / 背景
|
||||
|
||||
T-606 已关闭图标缓存的全局锁 convoy、远端响应无界读取和内存无上限问题,但 `IconCache.Load` 仍没有生产调用者。modern/win7 的 `AppShell.ApplyIcon` 会直接写 `shell.icons` map,Layout 同时读取该 map;当前只有同 goroutine 测试调用,所以尚未发生数据竞争。
|
||||
|
||||
正式图标后台加载若从 worker goroutine 直接调用 `ApplyIcon`,既会产生 map race,也违反 Gio 的 UI 更新模型。现有两个 `main.run` 只处理 window event,尚未把 `application.Runtime.Events()` 转成可唤醒窗口并由 Frame/UI goroutine 应用的事件流。Catalog 更新或相同 app 的新图标请求还可能使迟到结果过期;若只依靠 T-606 的 `SetItems` 剪枝,旧结果会在剪枝后把已删除或已换图标的 app 重新写回内存。
|
||||
|
||||
本任务先冻结并实现后台结果到 UI 的线程契约,让后续真实 HTTP 图标源和惰性调度只能复用该通道,不能绕过 application event 直接修改 Gio 状态。
|
||||
|
||||
## 方案
|
||||
|
||||
1. 在 `core/application` 增加图标事件类型与强类型 payload:
|
||||
- 至少区分 ready 与 failed,并纳入 `EventType.Valid()` 白名单。
|
||||
- 事件身份包含 `RequestID`、`AppID`、`IconRef` 与 DPI;ready payload 携带后台已解码的标准库 `image.Image`,不得携带 Gio 类型。
|
||||
- failed payload 提供稳定、可诊断且不包含敏感 URL/query 的失败信息;失败不伪装为成功或静默吞掉。
|
||||
- 提供统一构造/发布入口并校验空 ID、非法 `sha256:` 引用、非法 DPI、nil image 和 payload 类型,避免生产者各自拼装 `any`。
|
||||
2. 在 `core/catalog` 增加可注入的后台结果发布用例:
|
||||
- 接受已经完整确定的 `IconFetchRequest`、AppID/RequestID 和 application event publisher,在调用方提供的后台 context 中执行 `IconCache.Load` 与 `DecodeIcon`。
|
||||
- 成功发布 ready;加载、校验或解码失败发布 failed;事件发布失败显式返回/报告,不得改变 T-606 的缓存可信性语义。
|
||||
- 用例本身不创建无限 goroutine或无界 worker 队列;并发/生命周期由上层调度者和 context 控制。
|
||||
- 继续使用 T-606 的流式 Fetcher 合约,不新增图标 URL/CDN 规则。
|
||||
3. 为 modern/win7 建立相同的 application event relay:
|
||||
- 后台 pump 只接收事件、放入有界线程安全 inbox 并请求 `Window.Invalidate`;两个仓库锁定的 Gio 版本都明确允许并发调用 Invalidate,但 pump 不得调用 `ApplyIcon`、`paint.NewImageOp` 或修改 shell/model。
|
||||
- inbox 使用 FIFO、lossless backpressure:满队列时等待 UI drain 或 context/relay 关闭,不得静默丢 ready/failed;成功入队后必须请求重绘。
|
||||
- Gio Frame/UI goroutine 非阻塞 drain inbox,通过 `ApplyEvent` 校验强类型 payload 后调用 `ApplyIcon`;非图标事件不得因 T-607 被破坏或误判为图标事件。
|
||||
- window 销毁、runtime 关闭和 context 取消时 relay 可确定退出,不泄漏 goroutine,不在关闭后自旋或永久阻塞。
|
||||
4. 在两个 `AppShell` 中记录每个 app 最新期望与已应用的图标身份或等价 generation:
|
||||
- 只有 AppID 仍存在、`IconRef`/DPI 仍匹配且 RequestID 仍是最新请求时才应用 ready 结果。
|
||||
- 新请求覆盖旧请求;Catalog 删除 app、图标引用变化或请求取消后,迟到 ready/failed 均被丢弃。相同 AppID 的 `IconRef` 变化还必须清除旧 ImageOp/已应用身份,不能继续显示上一版图标。
|
||||
- failed 只保留与当前 IconRef/DPI 匹配的既有可信图标,否则保持占位状态,并结束对应 pending 状态;不得让旧失败覆盖新请求状态。
|
||||
5. 补 core 与双 Gio 的线程边界测试:
|
||||
- fake publisher/loader 证明 Load 和 Decode 不在 UI apply 路径执行,ready/failed 身份与错误传播正确。
|
||||
- 后台 submit 后 shell 尚未变化;只有 UI drain/ApplyEvent 后图标 map 才更新并触发重绘请求。
|
||||
- 覆盖删除 app、IconRef 变化并清理旧 ImageOp、同 app 新请求覆盖旧请求、非法 payload、满队列 backpressure、失败、取消与关闭 relay。
|
||||
- 使用 channel/barrier 等确定性同步;若环境支持 race detector则执行并记录,否则记录真实工具链限制。
|
||||
6. 同步事件协议、架构、路由和编码规则,明确 `ApplyIcon`/`ApplyEvent` 是 UI goroutine-only,后台唯一入口是 application event。
|
||||
|
||||
## 验收要点
|
||||
|
||||
- `EventIconReady`/`EventIconFailed` 是有效 application event,强类型 payload 不 import Gio,非法事件身份或 payload 被稳定拒绝。
|
||||
- 后台图标用例调用现有 `IconCache.Load` 与 `DecodeIcon`,成功/失败均发布带 RequestID、AppID、IconRef、DPI 的对应事件;发布失败可观察且 context 取消能及时结束。
|
||||
- modern/win7 后台 relay 收到事件时只入队并请求 invalidate,不会直接改变 `shell.icons`;Frame/UI goroutine drain 后才创建 `paint.ImageOp`。
|
||||
- relay 使用有界 FIFO 队列和可取消的 lossless backpressure,满队列不静默丢事件;window/runtime 退出后无 goroutine 泄漏、死锁或 busy loop。
|
||||
- 已删除 app、IconRef/DPI 已变化、RequestID 已被新请求取代的迟到 ready/failed 均被忽略;不会在 `SetItems` 剪枝后重新插入旧图标。相同 AppID 的 IconRef 变化会清除旧 ImageOp,直到新图标就绪前显示占位。
|
||||
- 图标失败保留可用的既有图标或占位状态,错误可诊断;非法 payload 不 panic、不污染 UI 状态。
|
||||
- 两个 Gio 适配器使用同一事件语义但不互相 import,modern Gio v0.10.1 与 win7 Gio v0.6.0 的 workspace 隔离保持不变。
|
||||
- Layout 路径继续无磁盘、网络、哈希和图片解码;`ApplyIcon` 文档与测试明确 UI goroutine-only,不通过给 map 加锁把后台直写合法化。
|
||||
- Go 1.20.14 + `GOWORK=off` 下 `go vet ./...`、`go test -count=1 ./...` 通过。
|
||||
- modern 根 workspace 与 win7 独立 workspace 的 UI/cmd 测试及 Windows amd64 构建通过;`./scripts/verify_phase0.ps1` 全绿。
|
||||
- `python scripts/validate_agent_context.py`、`python scripts/validate_harness_governance.py` 与提交前差异检查通过。
|
||||
|
||||
## 边界（不改什么）
|
||||
|
||||
- 不决定 `sha256:` 图标引用到 URL、CDN 路径或 DPI 变体的发布协议,不增加 Catalog 字段,不实现具体 HTTP `IconFetcher`。
|
||||
- 不在 Layout 中启动网络/磁盘 IO;不实现按 viewport 预取、滚动取消、优先级或完整生产调度策略,本任务只建立可复用的后台结果发布与 UI 投递通道。
|
||||
- 不把 `ApplyIcon` 改成可从任意 goroutine 调用的线程安全 API,不以 mutex 掩盖错误线程归属。
|
||||
- 不补 Phase 2 后续完整适配器交互契约矩阵,不修改 `VisibleItems` 快照 API,不拆分 `shell.go`;这些继续按审核顺序另立任务。
|
||||
- 不修改 T-606 的内存 LRU、磁盘缓存安全策略或 Fetcher 读取上限,不处理 `ErrIconCacheUnsafe` 自动隔离。
|
||||
- 不处理 ZIP 中央目录预扫描、断电耐久、Catalog 签名向量或 T-302 安装整合。
|
||||
- 不升级 Go/Gio 或合并 modern/win7 workspace,不修改、提交或删除用户的 `soft_quay.code-workspace`。
|
||||
|
||||
## 协作约束
|
||||
|
||||
- 按仓库当前规则由单 Agent 串行执行,不启动子 Agent。
|
||||
- 本任务只允许修改 frontmatter 中的 `write_paths`;若接线需要新增图标 URL/清单协议或从后台直接触碰 Gio 状态,必须停止并记录,不得在 T-607 内扩大边界。
|
||||
- T-607 完成、完整验证并提交前,不落成或领取 Phase 2 审核顺序中的后续任务。
|
||||
|
||||
## 执行记录
|
||||
|
||||
- 2026-07-17:根据 `docs/review/phase2-review.md` 交叉复核定稿的第二优先级整改落成任务;现有全局最大任务为 T-606,因此取 T-607,依赖已完成的 T-606。
|
||||
- 2026-07-17:任务冻结后台 Load/Decode→application event→有界 relay/Invalidate→Gio UI drain/ApplyEvent 的线程边界;真实 URL 映射、viewport 调度、适配器全量契约、VisibleItems 快照和文件拆分继续按审核顺序串行处理。
|
||||
- 2026-07-17:用两个隔离 workspace 的本地 `go doc gioui.org/app.Window.Invalidate` 核对 Gio v0.10.1 与 v0.6.0,两者都明确 Invalidate 可并发调用;因此只允许后台 relay 调 Invalidate,所有 shell/ImageOp 更新仍限定在 UI goroutine。
|
||||
Reference in New Issue
Block a user