opc/soft_quay

Fork 0

Files

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

4.8 KiB

Raw Blame History

技术栈(Tech Stack)

"用什么"的统一速查表。选型与理由在此集中维护;"怎么把它们搭起来"见架构设计。未定项必须标为待定,不要让 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
清单/许可证签名	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,且需单独任务评估。
不确定的技术选型先更新本文,再进入代码。
不允许同一职责并存两套实现(如两套下载器、两套配置读写)。

4.8 KiB Raw Blame History

技术栈(Tech Stack)

一、技术栈一览

二、决策记录与演进

三、构建与运行命令

四、依赖纪律

4.8 KiB

Raw Blame History