opc/soft_quay
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
agent/codex/T-204
soft_quay/docs/02-requirements.md
T
ilaandClaude Fable 5 0184595ccc
Harness governance / validate (push) Has been cancelled
Details
Add harness coding docs for SoftBox (Go + Gio dual-build) 
Initialize the full harness coding document set from the
harness_coding_docs template, customized for the SoftBox project:

- Vision, requirements, tech stack (modern Go 1.25 + Gio v0.10.1;
  Win7 legacy Go 1.20.14 + Gio v0.6.0), architecture, coding rules
- Protocol contracts (signed catalog, package protocol v1, Ed25519
  license, events, CLI) and Gio view structure
- Roadmap Phase 0-6 with 20 suggested tasks; T-001 (monorepo
  skeleton) filed and ready to claim
- Agent entry points (AGENTS.md, docs/00-ai-start-here.md),
  context manifest, governance scripts and tests
- Merge Go gitignore with harness rules; keep go.work tracked

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-16 14:33:54 +08:00

6.7 KiB
Raw Permalink Blame History

需求

本文只描述要什么与怎么算达成,用产品 / 用户语言表达,不涉及技术实现。 技术方案、数据结构、字段定义见 架构设计 与 协议合约。

一、业务现状

项 状态
用户 自家系列软件的用户,目前手动下载、解压、升级、输注册码,流程易错
数据 已有系列软件的安装包和授权体系(旧盒子);新 Catalog、许可证格式待按新协议建立
现有系统 参考过一个商用软件盒子的逻辑(下载、更新、注册绑定电脑);本项目为全新自研,不复用其代码和旧注册码算法
约束 需兼容少量 Win7 SP1 用户;下载与更新必须防篡改;不依赖管理员权限

二、用户角色

  • 普通用户:浏览软件列表、下载、更新、启动软件、导入许可证、试用。
  • Win7 遗留用户:使用 Legacy 版盒子,只能看到并下载兼容自己系统的软件包。
  • 发布者(自己,不在客户端内):通过 Catalog 发布签名清单和软件包、签发许可证、维护撤销名单。

三、功能清单

第一版 MVP(最小闭环)

功能 用户能做什么 优先级
远程软件清单 打开盒子看到签名清单中的软件;断网时看到最后一次验证成功的缓存 P0
分类、标签和搜索 按名称/标签搜索,按分类和「全部/已安装/可更新」视图筛选 P0
本地安装状态识别 每款软件显示未安装/已安装/可更新/下载中/运行中等状态 P0
下载队列与进度 排队、开始、暂停、取消、重试;看到速度、进度和剩余时间;重启后恢复 P0
ZIP 安全解压与安装 下载校验后一键安装;失败不破坏已安装版本 P0
版本检测和更新 有新版本时提示并可一键更新;更新失败自动回滚 P0
软件启动与运行检测 一键启动;运行中的软件不被更新覆盖 P0
盒子自身更新 盒子提示自身新版本并安全自更新,失败可恢复 P0
机器绑定许可证 导入许可证,离线验证,区分正式版/试用版/授权错误 P0
双版本 现代版(Win10/11 x64)和 Win7 遗留版各自可用,更新通道不交叉 P0
日志与失败恢复 关键操作有日志;下载/安装失败有明确提示和重试路径 P0

后续迭代

功能 描述 阶段
files.json 复核与修复 按文件清单发现缺失/被改文件并修复安装 V1.1
命名管道优雅退出 更新前通知子软件保存并退出(prepare_update/ready) V1.1
--softbox-info / --softbox-health 子软件标准自检参数接入健康检查 V1.1
Win7 x86 构建 有真实用户需求时提供 32 位遗留版 V2
便携模式 portable.flag 触发相对目录存储 V2
beta 通道 用户可选参与 beta 清单 V2
SQLite 存储 历史记录、全文搜索需求出现后再评估 V2+

四、核心用户故事(MVP)

  1. 作为普通用户,我打开盒子后能看到软件列表(断网也能看到缓存的列表),并能搜索和按分类筛选。
  2. 我可以点击「下载」,看到进度和速度;下载完成后自动校验、安装,状态变为「已安装」;我点击「启动」即可使用软件。
  3. 当软件有新版本时,列表中显示「可更新」;我点击更新,旧版本被安全替换;若更新中途失败,软件仍能以旧版本启动。
  4. 我导入许可证文件后,盒子显示已授权的软件;子软件独立启动时同样能识别授权;把许可证复制到别的电脑无法通过验证。
  5. 当清单签名被篡改、下载包哈希不符、磁盘不足或断网时,盒子给出明确提示,不执行任何未验证内容,也不破坏已安装的软件。
  6. 作为 Win7 用户,我使用遗留版盒子,只看到并下载 Win7 兼容的软件包,不会被推送无法启动的现代版。

五、验收标准(MVP)

  • 清单:断网启动可读取最后验证成功的缓存;伪造或篡改的清单被拒绝且不回退到未验证内容;下架软件通过 status 隐藏而不是改名。
  • 下载:并发默认 2;暂停/取消/重试可用;中断后重启盒子能续传;速度、进度、剩余时间实时刷新。
  • 安装/更新:哈希不符、路径穿越、磁盘不足、目标程序运行中——每种情况都有确定的失败结果且不破坏 current;更新失败后旧版本仍可启动。
  • 启动:启动前检查文件存在、系统兼容和授权;运行中软件在列表显示「运行中」;运行状态通过进程快照检测。
  • 盒子自更新:更新过程中断电/失败,下次启动可恢复旧版;新版启动后写入健康状态。
  • 授权:许可证离线可验证;machine_hash 不匹配即拒绝;更新任何软件都不覆盖许可证与用户数据;试用与正式状态在盒子和子软件中一致。
  • 双版本:两个 EXE 分别在 Win11 和 Win7 SP1 真机可打开并完成「清单→下载→安装→启动」;Win7 版清单不出现现代版软件包。
  • 性能:数百个软件项列表滚动流畅;界面每帧不做磁盘/网络 IO。

六、范围边界与决策

问题 决策
第一版平台 Windows 桌面(现代版 x64 + Win7 遗留版 x64;x86 按需)
是否需要账号 否;授权基于许可证文件 + 机器绑定,无在线账号体系
第一版范围 上表 P0 的最小闭环
软件包格式 ZIP(标准软件包协议 v1),不再依赖 UnRAR.dll
暂不支持 评论/评分/社区、支付、云同步、皮肤市场、插件脚本、驱动安装
Win7 定位 Legacy:仅兼容与严重修复,有用户占比门槛和停止维护日期

七、待确认 / 风险点

  • Catalog 服务端:清单签名发布器和对象存储的落地方式(本仓库只消费签名清单,发布侧在 softbox-catalog 仓库);首期可用本地/静态文件模拟,需确认正式域名和存储。
  • 签名密钥管理:Ed25519 私钥的保管和签发流程,谁持有、如何轮换;私钥绝不进入本仓库。
  • Win7 支持门槛:真实 Win7 用户占比未量化;需确认是否提供 x86 和 Legacy 停止维护日期。
  • 授权迁移:旧盒子存量用户的注册码如何换发为新许可证,人工流程谁负责。
  • 第三方平台风险:下载走自有对象存储/CDN,需确认带宽成本和 URL 防盗链策略。
  • 自动化边界:盒子不强杀用户进程;更新前等待用户关闭软件,超时取消更新。
  • 隐私:只上送/记录 machine_hash,不保存原始序列号和 MAC;日志不含注册码和敏感查询参数。
  • Authenticode 证书:EXE 代码签名证书的采购与签名流水线接入时间点。
Reference in New Issue View Git Blame Copy Permalink