ilaandClaude Fable 5
a89821a571
Split docs/softbox-catalog-design.md into the numbered harness doc set (00-06, api.md, current-state, agent-context, tasks) following the harness_coding_docs template and soft_quay conventions. Register the nine open decision items from the design spec into the 06-tasks roadmap as W- tasks and backlog entries. Keep the original design spec as an archived design input with a header note. Recreated after the repository's previous git history was lost to an external reset; content matches the original initial commit. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
3.3 KiB
3.3 KiB
技术栈(Tech Stack)
"用什么"的统一速查表。未定项必须标为待定,不要让 agent 在代码里自行决定;裁定后更新本文再动代码。
一、技术栈一览
| 维度 | 选型 | 状态 | 理由 / 说明 |
|---|---|---|---|
| 后端语言 | Go | 建议(W-001 立项确认) | 与客户端同栈,可直接复用同一套 canonical/verify 实现思路与 Schema,天然字节对齐——这是选 Go 的最强理由。若改选其他语言,必须用 corpus 做严格字节回归 |
| 协议 Schema / corpus | 引用 soft_quay 仓库(git submodule 或版本化拷贝 + CI 一致性校验,方式 W-001 裁定) |
待定 | 权威源唯一,不另建;CI 必须证明本仓库消费的副本与客户端一致 |
| 签名算法 | Ed25519 | 已定 | 与客户端内置公钥配对;签名域规则见 api.md |
| 包完整性 | SHA-256 | 已定 | Ingestion 计算整包哈希写入清单 |
| 私钥保管 | KMS / HSM 或独立最小权限签名服务 | 待定(W-003) | 绝不入库、不进 Web 进程环境变量明文;首期用离线测试密钥对 |
| 发布记录存储 | 关系型库(候选 SQLite → PostgreSQL) | 待定(W-201) | 首期里程碑(协议对齐)不需要数据库;Registry 落地时定 |
| 产物托管 | 对象存储 / CDN | 待定(W-004) | 首期用本地静态 HTTP 服务模拟 |
| Web 框架 / UI | 待定 | 待定(W-501) | Phase 5 才启动 UI;先协议后界面 |
| 测试 | 单元测试 + corpus 字节回归 + Schema 校验闸门 | 已定原则 | corpus 断言为 CI 必跑项,期望值禁止自举 |
| CI | 待定(参考 soft_quay 的 Gitea Actions + 本地脚本双轨) | 待定(W-002) | 本地脚本先行,保证无 CI 也能跑同一套闸门 |
二、决策记录与演进
- 协议权威源:
soft_quay/docs/api.md、soft_quay/schemas/*.json、soft_quay/testdata/catalog/canonical-vectors.json是唯一权威;本仓库文档只做发布端视角摘要,冲突时以客户端仓库为准。 - 先协议后 UI:第一里程碑是"产出被客户端验签通过、被 corpus + Schema 回归通过的 manifest";Web 界面在流水线可信之后才开工。
- 首期本地模拟:本地生成签名清单 + 本地静态 HTTP 服务即可让客户端跑通闭环,不先建对象存储,避免过早绑定云厂商。
- 签名服务只签受控结构:清单 / 许可证 / 撤销名单三类;不对任意字节签名,防止被当通用签名 oracle。
- 单公钥时代不做轮换字段:客户端协议无 key ID;多公钥 / 轮换需先在客户端仓库做协议升级,本仓库不得抢跑。
三、构建与运行命令
工程骨架由 W-001 建立;根目录
init.sh/init.ps1为统一入口,W-001 完成前三个命令为占位符,运行会主动失败。
| 用途 | 命令 |
|---|---|
| 统一入口 | ./init.sh(PowerShell 用 ./init.ps1)——【W-001 替换真实命令】 |
| 依赖同步 | 【待定】 |
| 测试与 corpus 回归 | 【待定】 |
| 本地静态发布模拟 | 【待定,W-204】 |
四、依赖纪律
- 新增第三方依赖前,先说明用途、替代方案和维护成本。
- 加密实现优先使用语言标准库(Go 为
crypto/ed25519);不引入自定义或小众加密库。 - 不允许同一职责并存两套实现(如两套 canonicalizer、两套 Schema 校验)。
- 不确定的技术选型先更新本文,再进入代码。