# 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):当前代码现实、可运行命令、下一步任务。

日常会话不需要机械重读全部文档:

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-604`～`T-607`。Windows 安全路径阻断项、图标缓存资源边界与后台结果回 UI 线程的事件接线均已关闭;下一步按 Phase 2 交叉审核顺序落成 modern/win7 适配器交互契约任务,其余审核整改与 Phase 1 中央目录预扫描继续串行处理,T-302 暂后置。

优先路径:

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-607:图标缓存按 key 去重、流式有界读取、memory LRU、双 shell 图标剪枝,以及 Load/Decode→application event→有界 relay/Invalidate→UI ApplyEvent 的线程接线;下一步落成双适配器交互契约任务,再串行处理其余整改与 T-302/T-303、Phase 4-6。

## 领取任务规则

任务以「一任务一文件」存放在 `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/` 校验 + 同步文档。
- 如果命令当前不可运行(骨架未建成),必须在回复里如实说明原因。