任务路线图(Roadmap)
本文是只读路线图:维护阶段划分、里程碑、待办池和建议拆分清单,把 MVP 拆成小步、可独立交付的任务,让 AI 一步一步开发,避免一次生成整个项目。
真实任务以「一任务一文件」存放在 tasks/(docs/tasks/T-<编号>.md)。未启用 Gitea 时以任务文件 frontmatter 为状态权威;启用后以 Issue 为实时状态、合并后的任务文件为长期事实。本文不跟踪单任务状态。
使用规则
- 开工先落文件:从下方「建议拆分清单」把下一个任务按
tasks/README.md 落成 docs/tasks/T-<编号>.md(沿用建议编号),把验收要点展开成可执行、可观察的步骤,再开始实现。
- 单 Agent 串行执行:同一时间只做一个任务,领取、状态流转、执行记录、完成定义全部遵循
tasks/README.md 和 编码规则;前一任务 DONE、验证并提交后才开始下一任务。
- 不跳步:依赖未完成的任务不能开工。
- 本文只在规划变化时修改:调整阶段划分、里程碑、增删建议任务或 Backlog 条目时才动本文;单个任务开工或完成不修改本文。
- 动手前先读
00-ai-start-here.md、05-coding-rules.md 和 current-state.md。
建议拆分清单
以下是按阶段列出的建议任务;T-编号 为建议编号,落成任务文件时沿用。
Phase 0 · 工程骨架
| ID |
任务 |
依赖 |
验收要点 |
| T-001 |
初始化 monorepo 骨架 |
- |
go.work + core/app-modern/app-win7 三模块;core go test ./... 在 Linux 通过;两个 EXE 可交叉编译(modern 用锁定 Go,win7 强制 Go 1.20);用真实命令替换 init.sh/init.ps1 顶部三个变量,并同步 00-ai-start-here.md、03-tech-stack.md、05-coding-rules.md、current-state.md |
| T-002 |
建立 domain 状态模型与事件总线 |
T-001 |
软件状态机枚举与迁移规则、application.Event 定义与 runtime 骨架;状态机表驱动测试覆盖非法迁移 |
| T-003 |
Gio 空窗口 + 平台层 stub |
T-001 |
两个 app 打开空主窗口(AppShell 骨架);platform/windows 接口 + 非 Windows stub;core 不 import Gio 的检查脚本 |
| T-004 |
CI 双目标编译闸门 |
T-001 |
CI(或本地脚本)执行:core vet+test、modern 构建、win7 用 Go 1.20 构建、依赖 go 版本检查 |
Phase 0 交叉审核加固
审核整改任务沿用全局防撞编号;路线图原有最大编号为 T-603,因此从 T-604 起编号。整改按 docs/review/phase0-skeleton-review.md 的定稿顺序串行落成和执行。
| ID |
任务 |
依赖 |
验收要点 |
| T-604 |
隔离 modern 与 Win7 workspace |
T-004 |
根 workspace 只含 modern/core;Win7 使用独立 Go 1.20 workspace;双 workspace 分别 sync;版本检查证明 Gio v0.10.1/v0.6.0 不交叉解析 |
Phase 1 · 最高风险原型
| ID |
任务 |
依赖 |
验收要点 |
| T-101 |
签名清单验签与缓存回退原型 |
T-002 |
Ed25519 验签;伪造/篡改清单被拒绝(testdata 恶意样例);断网回退最后验证成功缓存;结论写入文档 |
| T-102 |
ZIP 安全解压原型 |
T-002 |
表驱动攻击样例全部被拒:绝对路径、../、符号链接、zip bomb(数量/体积/压缩比上限)、entrypoint 外逃 |
| T-103 |
staging/backup 原子切换与回滚原型 |
T-102 |
切换成功、切换中断(模拟崩溃)、回滚三条路径测试通过;状态可从磁盘恢复 |
Phase 1 交叉审核加固
Phase 1 安全整改按 docs/review/phase1-security-review.md 的交叉复核定稿顺序串行落成。T-605、T-612、T-613 与 T-614 已关闭;T-613 建立文件、目录和 journal 的代码层耐久顺序,T-614 冻结 Catalog canonicalization/签名静态 corpus 与客户端拒绝规则。T-302 已将这些原型整合到同句柄 Catalog size/SHA、严格 app.json、安全 staging/switch/回滚的安装 use case；物理断电验证保留到 T-601。
| ID |
任务 |
依赖 |
验收要点 |
| T-605 |
统一 Windows 安全路径校验并封堵 ZIP 逃逸 |
T-102, T-201, T-202, T-604 |
Catalog/ZIP/installed-app 共用逐段 Windows 安全相对路径策略;拒绝尾随空格/点与 DOS 设备名;输出路径增加 destination 包含性兜底;原生 Windows 用例证明不写出 staging |
| T-612 |
在 ZIP 打开前限制包大小与中央目录元数据 |
T-605 |
已验签 Catalog size、已完成普通下载文件长度与同句柄 EOCD/ZIP64 预扫描一致;在 zip.NewReader 前限制原始包、中央目录与声明条目数 |
| T-613 |
建立安装文件与目录事务耐久顺序 |
T-612 |
payload Sync、staging tree/journal/rename/remove 的目录栅栏;Windows FlushFileBuffers fail-closed;物理断电故障注入仍后置到 T-601 |
| T-614 |
冻结 Catalog 规范化与签名跨实现测试向量 |
T-613 |
静态 canonical bytes/Ed25519 test vectors 覆盖 Unicode、surrogate、-0/大整数、嵌套 signature 与 Base64;客户端不自举期望值,外部发布端可消费同一 corpus |
Phase 2 · 清单与软件列表
| ID |
任务 |
依赖 |
验收要点 |
| T-201 |
catalog 模块正式接入 |
T-101 |
清单获取、验签、缓存、min_os/架构过滤、status 处理;app.json/manifest Schema 落入 schemas/ |
| T-202 |
本地安装状态识别 |
T-201, T-103 |
installed-app.json 读写;12 种状态正确呈现;版本比较用 SemVer |
| T-203 |
主界面软件列表 |
T-202, T-003 |
虚拟列表 + 搜索/分类/视图切换;控件状态按软件 ID;数百项滚动流畅;Layout 无 IO |
| T-204 |
软件详情与图标缓存 |
T-203 |
详情弹层;图标内存+磁盘缓存(按 DPI);断网可显示缓存图标 |
Phase 2 交叉审核加固
Phase 2 整改按 docs/review/phase2-review.md 的交叉复核定稿顺序串行落成。T-606 已关闭正式图标接入前的并发、读取和内存边界;T-607 建立后台图标结果经 application event 回到 Gio UI goroutine 的线程契约;T-608 为两个隔离 Gio 适配器建立交互契约;T-609 修正 VisibleItems 快照生命周期;T-610 在不改变行为的前提下拆分双端 Gio shell 职责;T-611 已用真实 fail-closed 传播、双端安全诊断和人工 runbook 关闭最终观察项。
| 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 |
| T-608 |
建立双 Gio 适配器交互契约 |
T-607 |
双端同场景验证 Editor/Clickable 接线、AppID 行身份、详情上下文、500 项 viewport 与控件释放;不重复 ViewModel 纯逻辑 |
| T-609 |
修正 VisibleItems 快照生命周期 |
T-608 |
refilter 构造新 backing array 后替换;旧快照跨 model 更新保持稳定;每帧读取不复制;明确单 owner 与只读约定 |
| T-610 |
拆分双端 Gio shell 职责 |
T-609 |
两端按状态/根编排、header/navigation、catalog/list、detail、style 拆为同 package 镜像文件;行为、事件顺序、视觉与 Gio 隔离不变 |
| T-611 |
建立不安全图标缓存诊断与人工恢复指引 |
T-610 |
真实非普通 entry 贯通 unsafe_cache event;双端详情显示无敏感字段的 fail-closed/人工处理提示;不自动删除或 quarantine |
Phase 3 · 下载与安装
Phase 3 的 T-301 → T-302 → T-303 是安全关键依赖链,任务之间保持串行。T-302 起继续由单 Agent 完成规格、实现、测试、安全检查和提交,不启动子 Agent;完整规则见 tasks/README.md 与仓库 AGENTS.md。
| ID |
任务 |
依赖 |
验收要点 |
| T-301 |
下载队列 |
T-202 |
并发默认 2;暂停/取消/重试;Range 续传;任务元数据持久化,重启恢复;事件驱动进度 |
| T-302 |
安装流程整合 |
T-301, T-102, T-103 |
完整链:下载→SHA-256→app.json 比对→安全解压→staging→切换→健康检查→回滚;04-architecture.md 关键安全流程顺序逐步可观察 |
| T-303 |
失败处理与磁盘预检查 |
T-302 |
哈希不符、磁盘不足、包损坏、程序占用各有确定结果与错误码;不破坏旧版本 |
Phase 3 交叉复核整改
docs/review/phase3-review.md 的交叉复核裁定已由 T-615 关闭 T-303 未覆盖的 staging 输出 I/O 根因保留与磁盘满统一诊断；运行状态切换临界区复查仍随 T-401 落成。
| ID |
任务 |
依赖 |
验收要点 |
| T-615 |
保留安装输出 I/O 根因并统一磁盘满诊断 |
T-303 |
区分 ZIP 输入与 staging 输出错误；write/sync/close 的可识别磁盘满统一 disk_full 且保留 errors.Is 根因；清理失败可观察并安全恢复，不破坏旧版本 |
Phase 4 · 启动、运行与更新
| ID |
任务 |
依赖 |
验收要点 |
| T-401 |
进程检测与软件启动 |
T-303, T-615 |
Toolhelp 快照检测运行状态;启动前检查文件/兼容/占用;切换临界区复查运行状态;WorkingDirectory 正确 |
| T-402 |
子软件更新流程 |
T-401 |
可更新识别→确认退出→更新→失败回滚仍可启动旧版;更新不触碰 data/licenses |
| T-403 |
SoftBoxUpdater 盒子自更新 |
T-402 |
独立 Updater 按 CLI 合约工作;更新中断可恢复;新版健康状态写入 |
Phase 5 · 授权
| ID |
任务 |
依赖 |
验收要点 |
| T-501 |
机器指纹(machine_hash) |
T-001 |
平台层采集多标识→清洗生成 hash;不落原始序列号/MAC;非 Windows stub 可测 |
| T-502 |
Ed25519 许可证验证 |
T-501 |
licensing 模块离线验签;复制到不匹配机器被拒;测试用专用密钥对 |
| T-503 |
授权界面与试用/导入/换绑 |
T-502, T-204 |
导入、授权列表、试用状态展示;撤销名单验签与宽限期 |
Phase 6 · Win7 加固与发布
| ID |
任务 |
依赖 |
验收要点 |
| T-601 |
Win7 API 降级与真机冒烟 |
T-403 |
动态加载检查(导入表无 Win10+ API);Win7 SP1 真机/VM 完成清单→下载→安装→启动 |
| T-602 |
Win7 兼容矩阵验证 |
T-601 |
DPI(100/125/150)、中文 IME、经典主题/Aero、远程桌面、非管理员、旧证书按矩阵记录结果 |
| T-603 |
发布流水线 |
T-403, T-503 |
构建→注入版本→签名→打包 ZIP→哈希→生成签名 manifest;双通道互不交叉;干净机器完成下载/更新/回滚/授权测试 |
里程碑
- M1:工程骨架完成,双目标可编译,core 无头可测(Phase 0)。
- M2:三大高风险原型(验签、解压、原子切换)全部验证(Phase 1)。
- M3:「清单→列表→下载→安装→启动」核心闭环跑通(Phase 2-4 前半)。
- M4:自更新 + 授权完成,MVP 验收(Phase 4-5)。
- M5:Win7 遗留版可交付,双通道发布(Phase 6)。
待办池(Backlog)
- files.json 复核与修复功能(V1.1)。
- 命名管道 prepare_update/ready 优雅退出协议(V1.1)。
- --softbox-info / --softbox-health 健康检查接入(V1.1)。
- Win7 x86(386)构建目标(按真实用户占比)。
- 便携模式(portable.flag +
.softbox/ 相对目录)。
- beta 通道支持。
- 托盘图标与最小化到托盘。
- 拼音搜索。
- SBOM 生成与发布归档。
- softbox-sdk 拆分(独立仓库,待协议稳定后)。
