soft_quay/docs/tasks/T-616.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-616	Catalog 启动投递与空白界面诊断	2	T-204 T-607	DONE	2026-07-19	null	06234e11bf	null	agent/codex/T-616	docs/tasks/T-616.md core/application/catalog_bootstrap.go core/application/catalog_bootstrap_test.go app-modern/cmd/softbox/ app-win7/cmd/softbox/ app-modern/ui/gio/ app-win7/ui/gio/ docs/00-ai-start-here.md docs/04-architecture.md docs/06-tasks.md docs/api.md docs/routes.md docs/current-state.md docs/testing/windows-ui-smoke.md

问题 / 背景

dist/SoftBox.exe 的入口只创建空 AppShell，未装配 Catalog client/cache、也未向 AppShell.SetItems 投递快照；生产调用点不存在。因此软件目录永久为空。空目录仍应显示完整 shell 和明确状态，但当前 -H=windowsgui 构建隐藏 stdout/stderr，用户看到白色/空白窗口时无法区分“没有可信 Catalog 来源”与 Gio 首帧渲染故障。现有测试只在内存 layout.Context 中验证布局和图标事件，不是 Windows 真机 GPU 首帧证据。

仓库当前没有可入库的真实 Catalog HTTPS URL、Ed25519 公钥或发布配置。不能用 testdata、allow-all verifier、未签名本地文件或环境变量临时拼装成生产来源；这样会破坏 T-201 的签名/缓存信任边界。

方案

1. 在纯 Go 1.20 的 core/application 新增窄 CatalogSnapshotLoader、不可变 CatalogSnapshot 和 CatalogBootstrap。后台 bootstrap 只调用注入 loader，并通过现有 runtime 发布 CatalogRefreshed（带已准备 CatalogListItem 快照）或 CatalogRejected（只带稳定 catalog_source_unconfigured / catalog_load_failed 代码）；它不 import Gio、Windows、网络、存储或 catalog 实现，且不把 raw error/URL/签名材料放进 UI payload。
2. 两端 cmd/softbox 在 event pump 建好后启动 bootstrap，且为没有正式发布配置的当前发行物明确注入 fail-closed 的 catalog_source_unconfigured loader。为以后可信装配保留受测的 runWithCatalogLoader composition seam；未来只能把已验签、目标过滤后的 T-201 Catalog/cache 转成 CatalogSnapshot 后注入，不能绕过 verifier/cache 或让 UI 读取文件/网络。
3. 两端 Gio shell 在 UI goroutine 的 ApplyEvent 严格解析 Catalog payload：刷新事件用新快照调用 SetItems，拒绝事件只更新最小的启动状态。空列表区须明确区分“正在加载”“来源尚未配置”“验证/加载失败”“已加载但空 Catalog”“筛选无结果”；页面保留 header、导航和 footer，绝不显示 raw error、URL、文件路径或密钥信息。Layout 继续只读取内存状态。
4. 固定 API/架构/路由文档中的 payload、信任边界和当前不含真实 Catalog 来源的事实。新增 Windows 手工 UI smoke runbook：从 dist/SoftBox.exe 验证首帧标题、搜索、导航与“来源未配置”诊断可见；它记录观察步骤而不把人工视觉检查伪装成 CI/GPU 结论。T-601 仍负责真实 Win7/图形环境矩阵。
5. core 测试覆盖成功快照的深拷贝/事件、未配置/加载失败的稳定代码、context/发布失败；两端 UI contract 测试覆盖 event→SetItems、四种空态和未知/错误 payload fail closed；cmd composition test 证明 loader 只在后台启动一次且通过 relay 更新 UI。验证脚本继续构建双端主程序。

验收要点

• CatalogBootstrap 只接受完整有效的内存快照，发布成功/失败均保留错误链供后台观察，UI 只收到稳定公开代码；nil loader、非法 payload、取消和 runtime/relay 关闭 fail closed，不发布伪造列表。
• 成功刷新后双端 shell 显示 loader 注入的 CatalogListItem，保留既有搜索/分类/选择/图标生命周期；错误或未配置不会清除已成功显示的快照，也不会让 Layout 进行 I/O。
• 默认 dist/SoftBox.exe 不使用 testdata、URL、环境变量、假公钥或 allow-all verifier；没有正式可信来源时稳定显示“Catalog 来源尚未配置”而非白色/无说明空区，并在文档如实说明无法显示真实软件列表的原因。
• API/架构/路由与 Windows UI smoke runbook 对齐；手工 smoke 只验证 UI 可见诊断，不声明 GPU、RDP、杀毒或 Win7 真机兼容已经由自动化证明。
• go -C core vet ./...、go -C core test -count=1 ./...、两个 app 的全包测试、两个 Windows amd64 主程序构建、./scripts/verify_phase0.ps1、python scripts/validate_agent_context.py 与 python scripts/validate_harness_governance.py 全部通过。

边界（不改什么）

• 不引入真实 Catalog URL、公钥、私钥、证书、环境变量协议、未签名本地文件、testdata 生产回退或 allow-all verifier；不实现 Catalog 发布、下载、安装、授权、图标网络请求或更新按钮。
• 不修改 T-201 验签/缓存语义、manifest/schema、installed-app 扫描、UI 布局风格、Gio/Go 版本或 Windows 图形后端；不把手工 smoke 当作 T-601/T-602 的真机矩阵结论。
• 不在 Layout 做文件/网络/哈希，也不让后台 goroutine 改 shell；不自动收集截图、启动外部 shell、写日志中的敏感 URL/密钥或改变 data/、licenses/。

协作约束

• 当前项目为单 Agent 串行模式；当前 Agent 独占全部 write_paths，自行完成规格、实现、测试、审查、状态更新和提交，不启动子 Agent。
• 先提交本任务规格和项目快照；领取后将本文件改为 DOING，填写当前 HEAD 的 context_ref 与 work_branch: agent/codex/T-616，再重跑基线。
• T-501 仍是 Phase 5 的下一条路线图任务；T-616 仅关闭已证实的 Phase 2 production composition/诊断缺口，不改变授权任务依赖或假定真实发布配置已经存在。

执行记录

• 2026-07-19:正式落成。根据 dist/SoftBox.exe 白色/空白界面诊断，冻结“受测后台 Catalog 快照投递 + UI 明确空态”的最小闭环；明确当前无可信发布配置时默认发行物必须 fail closed 并说明原因，而不是读取 testdata 或伪装可用列表。
• 2026-07-19:领取任务，基于 06234e11bf6782945e3ac5c7f2ea5dc33f6cbdeb 在 agent/codex/T-616 执行；先重跑基线，再实现 Catalog 快照投递和空态诊断。
• 2026-07-19:完成。新增纯 core CatalogBootstrap、强类型深拷贝 Catalog event payload、稳定 catalog_source_unconfigured / catalog_load_failed 和默认 fail-closed loader；双端 cmd 在后台启动它并经现有 runtime/relay 投递，双端 Gio Frame 只解析内存事件后更新 SetItems。初始加载、未配置、加载失败、已加载空 Catalog 和筛选无结果均有不同可见文本，失败不清除最后成功快照；无真实 URL/公钥时不使用 testdata、环境变量、未签名文件或 allow-all verifier。新增 Windows 手工首帧 smoke runbook；它不替代 T-601/T-602 真机图形矩阵。验证通过：go -C core vet ./...、go -C core test -count=1 ./...、go -C core test -count=10 ./application、两个 app 的 cmd/softbox/ui/gio 与全包测试、双端 Windows amd64 主程序构建、./scripts/verify_phase0.ps1、python scripts/validate_agent_context.py、python scripts/validate_harness_governance.py。