ilaandClaude Fable 5
0184595ccc
Harness governance / validate (push) Has been cancelled
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>
64 lines
4.8 KiB
Markdown
64 lines
4.8 KiB
Markdown
# 技术栈(Tech Stack)
|
|
|
|
> "用什么"的统一速查表。选型与理由在此集中维护;"怎么把它们搭起来"见 [架构设计](04-architecture.md)。
|
|
> 未定项必须标为待定,不要让 agent 在代码里自行决定。
|
|
|
|
## 一、技术栈一览
|
|
|
|
| 维度 | 选型 | 状态 | 理由 / 说明 |
|
|
| --- | --- | --- | --- |
|
|
| 语言 | Go | 已定 | 网络、并发、校验、单二进制交付、可测试性强 |
|
|
| UI 框架 | Gio(纯 Go 立即模式 GUI) | 已定 | 无 CGO、单 EXE、跨版本可锁定;仅限 UI 层 |
|
|
| 现代版工具链 | Go 1.25(锁定已验证版本) + Gio v0.10.1 | 已定 | 当前受支持工具链;支持 Win10/Win11 x64 |
|
|
| Win7 版工具链 | Go 1.20.14(最终补丁) + Gio v0.6.0 | 已定 | Go 1.20 是最后支持 Win7 的版本;Gio v0.6.0 可由 Go 1.20 构建 |
|
|
| 模块结构 | go.work + 三个 go.mod(core / app-modern / app-win7) | 已定 | 共享核心,双构建互不污染工具链要求 |
|
|
| 依赖管理 | 版本锁定 + vendor(Gio 及相关依赖) | 已定 | 防止 Win7 构建被隐式升级到要求 Go 1.21+ 的依赖 |
|
|
| 存储 | JSON 文件 + 临时文件原子替换 | 已定 | 数百款软件规模足够;SQLite 仅在历史/搜索/事务需求出现后评估 |
|
|
| 软件包格式 | ZIP(标准软件包协议 v1) | 已定 | 避免 UnRAR.dll;协议见 [api.md](api.md) |
|
|
| 清单/许可证签名 | Ed25519(客户端只内置公钥) | 已定 | 离线可验证;私钥不进客户端与仓库 |
|
|
| 包完整性 | SHA-256 | 已定 | 下载后、执行前强制校验 |
|
|
| 传输 | HTTPS | 已定 | 清单与软件包一律 HTTPS |
|
|
| Windows API | golang.org/x/sys/windows + 动态加载(LoadLibrary) | 已定 | Win10 专属 API 动态加载并降级,不进导入表 |
|
|
| EXE 签名 | Authenticode | 已定 | 主程序与 Updater 均签名;证书采购待确认 |
|
|
| 测试 | go test(core 无头可测) + fake/stub 注入 | 已定 | domain/application 不依赖 Gio 与 Windows API |
|
|
| CI | 待定(Gitea Actions 或本地脚本) | 待定 | 需同时编译 modern 与 win7 双目标 |
|
|
| 静态检查 | go vet(+ 待定 golangci-lint) | 部分已定 | vet 必跑;lint 工具后续确认 |
|
|
|
|
## 二、决策记录与演进
|
|
|
|
- **双版本策略**:不维护两个长期开发分支;一个 main 主分支 + 共享 core + 两个 go.mod + 两个更新通道。仅当 Win7 版冻结、只接受严重修复时,才考虑建立 `release/win7-legacy` 维护分支。
|
|
- **core 兼容基线**:core 保持 Go 1.20 语法和依赖兼容,使两个版本复用同一业务实现;现代版可用新 Gio 和现代 Windows 能力,但这些依赖不得反向进入 core。
|
|
- **存储**:现在选择 JSON + 原子写入,避免早期引入 SQLite 的复杂度;在出现历史记录、全文搜索、大量事务需求时再评估。
|
|
- **软件包**:现在只支持 ZIP;不在 v1 开放任意安装脚本(install.bat/PowerShell 钩子),未来如需运行库安装,走受审核的 prerequisites 声明。
|
|
- **授权**:不复用旧盒子的 MD5/SHA-1 隐藏常量注册码设计;采用服务端 Ed25519 签名许可证 + machine_hash 绑定。
|
|
- **Win7 x86**:默认不提供;仅在真实用户占比支撑时增加 win7-386 构建目标。
|
|
|
|
## 三、构建与运行命令
|
|
|
|
> 工程骨架由 T-001 建立;骨架完成前以下命令不可运行,`init.sh`/`init.ps1` 会主动失败提示。骨架完成后,T-001 必须把真实命令回填到本表、`00-ai-start-here.md`、`current-state.md` 和 init 脚本顶部三个变量。
|
|
|
|
| 用途 | 命令(计划) |
|
|
| --- | --- |
|
|
| 同步工作区依赖 | `go work sync` |
|
|
| core 测试 | `cd core && go test -count=1 ./...` |
|
|
| core 静态检查 | `cd core && go vet ./...` |
|
|
| 现代版构建 | `cd app-modern && GOOS=windows GOARCH=amd64 go build -o ../dist/SoftBox.exe ./cmd/softbox` |
|
|
| Win7 版构建 | `cd app-win7 && GOTOOLCHAIN=go1.20.14 GOOS=windows GOARCH=amd64 go build -o ../dist/SoftBox-win7.exe ./cmd/softbox` |
|
|
| 本地运行(开发) | Windows 下直接 `go run ./cmd/softbox`(WSL 中构建 EXE 后到 Windows 侧运行) |
|
|
|
|
工具链矩阵:
|
|
|
|
| 构建目标 | 工具链 | Gio | 支持系统 | 维护策略 |
|
|
| --- | --- | --- | --- | --- |
|
|
| modern-amd64 | Go 1.25(锁定) | v0.10.1 | Win10/Win11 x64 | 正常新增功能 |
|
|
| win7-amd64 | Go 1.20.14 | v0.6.0 | Win7 SP1 x64 及更高 | 兼容与严重修复 |
|
|
| win7-386 | Go 1.20.14 | v0.6.0 | Win7 SP1 x86 及更高 | 仅真实需求时提供 |
|
|
|
|
## 四、依赖纪律
|
|
|
|
- 新增第三方依赖前,先说明用途、替代方案和维护成本,并确认其 go.mod 的 `go` 指令不超过对应模块的工具链基线(core 与 app-win7 为 1.20)。
|
|
- core 禁止依赖 Gio、SQLite 驱动、Windows 专属包;平台能力一律接口注入。
|
|
- Gio 及 UI 相关依赖锁定版本并 vendor;升级 Gio 只允许在 app-modern,且需单独任务评估。
|
|
- 不确定的技术选型先更新本文,再进入代码。
|
|
- 不允许同一职责并存两套实现(如两套下载器、两套配置读写)。
|