157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# AI 开发入口
|
||
|
||
> 给 AI coding agent 的项目入口。这里负责导航和流程,硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||
|
||
## 一句话定位
|
||
|
||
SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,为自家软件产品家族提供「发现 → 下载 → 安装 → 更新 → 启动 → 授权」的一站式安全闭环,并以独立遗留版兼容 Win7 SP1 用户。
|
||
|
||
第一版 MVP 只做:签名清单、列表/搜索、下载队列、ZIP 安全安装、更新与回滚、启动与运行检测、盒子自更新、机器绑定许可证、现代版 + Win7 版双构建。
|
||
|
||
## 上下文读取
|
||
|
||
首次接入、[`agent-context.json`](agent-context.json) 缺失或校验失败时,按这个顺序建立完整上下文:
|
||
|
||
1. [`01-vision.md`](01-vision.md):为什么做、为谁做、什么不做。
|
||
2. [`02-requirements.md`](02-requirements.md):MVP 要什么、怎么算达成。
|
||
3. [`03-tech-stack.md`](03-tech-stack.md):既定技术选型与双工具链矩阵。
|
||
4. [`04-architecture.md`](04-architecture.md):分层结构、目录、数据模型和关键安全流程。
|
||
5. [`05-coding-rules.md`](05-coding-rules.md):写代码前必须遵守的规则。
|
||
6. [`06-tasks.md`](06-tasks.md):阶段路线图、里程碑和待办池。
|
||
7. [`tasks/README.md`](tasks/README.md):任务文件约定(一任务一文件);本轮任务从 `docs/tasks/` 领取。
|
||
8. [`current-state.md`](current-state.md):当前代码现实、可运行命令、下一步任务。
|
||
|
||
遇到 `unsafe_cache` 或需要人工处理图标缓存时,只使用 [`troubleshooting.md`](troubleshooting.md) 的不跟随链接 runbook;不要在任务中临时发明递归清理命令。
|
||
|
||
日常会话不需要机械重读全部文档:
|
||
|
||
1. 读取仓库级规则(`AGENTS.md`)和 [`agent-context.json`](agent-context.json)。
|
||
2. 读取 `bootstrap.always_read`。
|
||
3. 读取本轮任务文件。
|
||
4. 按任务类型读取 `routes` 中的文档;一个文件命中多个路由时只读一次。
|
||
5. 记录默认分支头提交为 `context_ref`;同一会话中文件 SHA 未变化时复用已读内容。
|
||
|
||
清单的使用、缓存和断连降级规则见 [`agent-context.md`](agent-context.md)。
|
||
|
||
## 固定开工流程
|
||
|
||
读完上述文档后,每轮会话按这个机械顺序进入,恢复持久状态再动手:
|
||
|
||
1. `pwd`:确认在正确的仓库根目录。
|
||
2. 读 [`current-state.md`](current-state.md) 和 `docs/tasks/` 中当前 agent 的活跃任务,恢复已验证状态、下一步和当前 blocker。
|
||
3. `git log --oneline -5`:看清最近发生了什么。
|
||
4. 运行 `./init.sh`(Windows 原生 PowerShell 用 `./init.ps1`):统一安装、验证、打印启动命令;T-001 完成前脚本会提示命令未替换,属预期。
|
||
5. 跑一条基础 smoke 路径(core 测试 + 双目标编译),确认基线没坏。
|
||
6. **如果基线已坏,先修基线**,不要在坏的起点上叠新功能。
|
||
7. 基线绿了,再从 `docs/tasks/` 领取唯一任务(路线图见 [`06-tasks.md`](06-tasks.md))。
|
||
|
||
## 当前阶段
|
||
|
||
当前项目已完成 Phase 0～2、T-301～T-303、T-615 与审核整改 `T-604`～`T-617`。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、`VisibleItems` 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook、ZIP 中央目录/EOCD(含 ZIP64)预扫描、安装文件/目录/journal 的代码层耐久顺序、Catalog canonicalization/签名静态 corpus，以及同句柄 Catalog size/SHA→严格 app.json→staging/switch/回滚安装链均已关闭；T-303 已将 verified-package 的 staging 前磁盘/运行状态预检和稳定失败码落实到 core，T-615 已将 ZIP 输入/staging 输出 I/O 分界、平台磁盘满分类和清理失败落实到 core。T-401 已完成完整路径进程检测、受控启动和 Switcher 临界区复查；T-402 已完成子软件更新编排；T-403 已完成受限 SoftBoxUpdater、自身 EXE 健康确认与可恢复切换；T-616 已完成 production cmd 的 Catalog 快照事件投递和明确空态诊断；T-617 已修复 prepared rename+sync 后的自更新恢复不一致并补足无头故障恢复/health flag 测试。T-501 已完成 machine_hash v1：严格 MachineGuid 与 Windows 目录所在卷序列号构成带域分隔的 SHA-256，任一来源不可用即拒绝且不保存原始标识。物理断电、文件锁与杀毒软件干扰验证保留到 T-601 发布前环境验证。
|
||
|
||
优先路径:
|
||
|
||
1. 已完成 Phase 0:monorepo 骨架 + 双目标编译 + 空 Gio 窗口。
|
||
2. 已完成 Phase 1:清单验签、ZIP 安全解压、原子切换回滚原型。
|
||
3. 已完成 Phase 2 与 T-301:清单/列表/详情/图标缓存 + 可恢复下载队列。
|
||
4. 已完成 T-604:modern/Win7 workspace 与 Gio 版本解析彻底隔离。
|
||
5. 已完成 T-606～T-615:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、`VisibleItems` generation 生命周期、双端 `shell.go` 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引、ZIP 中央目录/EOCD 预扫描、安装耐久顺序、Catalog 静态签名向量，以及 staging 输出 I/O 根因与磁盘满诊断;已完成 T-302/T-303:已验签 Catalog 选择与同句柄 size/SHA、严格 app.json、安全 staging/switch/健康与记录写回滚链路，以及 staging 前磁盘/运行状态预检与稳定失败码。T-401 已完成进程检测、受控启动与切换临界区复查；T-402 已完成关闭确认、自然退出等待和更新编排；T-403 已完成 SoftBoxUpdater 的受限 transaction、PID 自然退出、固定健康启动与恢复；T-616 已完成 Catalog 快照启动投递与明确空态诊断；T-617 已完成 prepared rename+sync 的恢复修复、五 phase Recover 与双端 health flag 参数拒绝测试；T-501 已完成严格双来源的 machine_hash v1。下一步按路线图正式落成 Phase 5 的 T-502。T-601 仍须补真实 Windows 环境的断电/干扰注入。
|
||
|
||
## 领取任务规则
|
||
|
||
任务以「一任务一文件」存放在 `docs/tasks/`(约定见 [`tasks/README.md`](tasks/README.md)):
|
||
|
||
- 单 Agent 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件,取编号最靠前的;项目同一时间只保留一个活跃任务。
|
||
- 若 `docs/tasks/` 暂无可领任务,先按 [`06-tasks.md`](06-tasks.md) 路线图把下一个建议任务落成任务文件,再领取。
|
||
- 开始前在独立分支 / worktree 把该文件 frontmatter 的 `status` 改为 `DOING`。
|
||
- 本轮只完成这一个任务;验收通过后改为 `DONE`。
|
||
- **执行记录写进该任务文件的 `## 执行记录`**(改了什么、跑了什么验证、结果、决策)。
|
||
- 若项目现实发生变化(启动/验证路径、目录结构、blocker),覆盖更新 [`current-state.md`](current-state.md)。
|
||
- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md),确保下一轮无需人工修复即可开工。
|
||
- 做完即停,汇报验证结果,等待下一步指令。
|
||
|
||
如果代码实际状态和任务文件冲突,先说明冲突,不要擅自跳步或重排。
|
||
|
||
## MVP 边界
|
||
|
||
MVP 只做:
|
||
|
||
- 签名清单获取、缓存与过滤;列表、分类、搜索。
|
||
- 下载队列(并发/暂停/续传/恢复)与 ZIP 安全安装(staging/backup/回滚)。
|
||
- 版本检测、子软件更新、软件启动与进程检测。
|
||
- SoftBoxUpdater 盒子自更新。
|
||
- Ed25519 机器绑定许可证(导入、离线验证、试用)。
|
||
- 现代版(Win10/11 x64)+ Win7 遗留版(SP1 x64)双构建、双更新通道。
|
||
|
||
MVP 不做:
|
||
|
||
- 评论/评分/社区、在线支付、多账号云同步。
|
||
- 皮肤市场、插件脚本执行、驱动安装。
|
||
- files.json 修复、命名管道优雅退出、便携模式、beta 通道、Win7 x86(见 Backlog)。
|
||
|
||
## 事实来源
|
||
|
||
项目事实只信:
|
||
|
||
- [`02-requirements.md`](02-requirements.md):功能范围与验收标准。
|
||
- [`api.md`](api.md) 与 `schemas/`:清单、软件包、许可证、事件、CLI 的协议合约。
|
||
- [`04-architecture.md`](04-architecture.md):分层边界、目录布局、状态机、安全流程。
|
||
- [`03-tech-stack.md`](03-tech-stack.md):工具链矩阵与依赖纪律。
|
||
- 现有代码中的 `core/domain` 与 `core/application`(骨架建立后)。
|
||
|
||
不要把以下内容当事实来源:
|
||
|
||
- 对旧商用盒子的逆向分析笔记(那是设计输入,不是本仓库协议)。
|
||
- 历史备份文件、旧导出文档、临时实验目录。
|
||
- 未被任务或需求引用的草稿。
|
||
|
||
## 常见任务该看哪里
|
||
|
||
做 Gio 页面 / UI:
|
||
|
||
- 先看 `02-requirements.md` 的对应验收标准。
|
||
- 再看 `routes.md` 的视图职责与交互硬约束。
|
||
- 最后看 `04-architecture.md` 的 UI 交互模式(事件驱动、无 IO Layout)。
|
||
|
||
做 core 业务模块(catalog/downloader/installer/licensing/updater):
|
||
|
||
- 先看 `api.md` 的协议合约与事件合约。
|
||
- 再看 `04-architecture.md` 的分层约束、状态机和安全流程。
|
||
|
||
做协议 / 数据结构:
|
||
|
||
- 先看 `api.md` 和 `schemas/`。
|
||
- 如果结构变化,必须同步更新 `api.md`、`04-architecture.md`、`schemas/`、`current-state.md` 和相关任务验收。
|
||
|
||
做平台层(platform/windows):
|
||
|
||
- 先看 `04-architecture.md` 的平台层约束(接口注入、非 Windows stub、动态加载降级)。
|
||
- 再看 `03-tech-stack.md` 的 Win7 API 兼容要求。
|
||
|
||
做构建 / 发布:
|
||
|
||
- 先看 `03-tech-stack.md` 的工具链矩阵和命令。
|
||
- 再看 `current-state.md` 的当前真实命令。
|
||
|
||
## 验证命令
|
||
|
||
统一启动与验证入口收敛到根目录 `./init.sh` / `./init.ps1`;脚本会分别同步根 modern/core workspace 与嵌套 win7/core workspace,再运行完整 Phase 0 闸门。也可直接运行 `bash scripts/verify_phase0.sh` / `./scripts/verify_phase0.ps1`。标准分项命令:
|
||
|
||
```bash
|
||
# core 测试(Linux 无头可跑)
|
||
cd core && go vet ./... && go test -count=1 ./...
|
||
|
||
# 现代版构建(从仓库根执行;GOWORK 必须是绝对路径)
|
||
GOTOOLCHAIN=go1.25.0 GOWORK="$(pwd)/go.work" CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go -C app-modern build -trimpath -ldflags="-H=windowsgui" ./cmd/softbox
|
||
|
||
# Win7 版构建(从仓库根执行;强制 Go 1.20)
|
||
GOTOOLCHAIN=go1.20.14 GOWORK="$(pwd)/app-win7/go.work" CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go -C app-win7 build -trimpath -ldflags="-H=windowsgui" ./cmd/softbox
|
||
```
|
||
|
||
说明:
|
||
|
||
- 改 core 后跑:core 测试 + 两个构建目标(防止 Go 1.20 兼容性破坏)。
|
||
- 改 UI 后跑:对应 app 构建 + UI 事件测试(fake submitter + ApplyEvent)。
|
||
- 改协议 / 数据结构后跑:core 测试 + `schemas/` 校验 + 同步文档。
|
||
- 如果命令当前不可运行(骨架未建成),必须在回复里如实说明原因。
|