soft_quay/docs/00-ai-start-here.md

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程,硬性编码规则见 05-coding-rules.md。

一句话定位

SoftBox 软件盒子是一个使用 Go + Gio 开发的 Windows 桌面客户端,为自家软件产品家族提供「发现 → 下载 → 安装 → 更新 → 启动 → 授权」的一站式安全闭环,并以独立遗留版兼容 Win7 SP1 用户。

第一版 MVP 只做:签名清单、列表/搜索、下载队列、ZIP 安全安装、更新与回滚、启动与运行检测、盒子自更新、机器绑定许可证、现代版 + Win7 版双构建。

上下文读取

首次接入、agent-context.json 缺失或校验失败时,按这个顺序建立完整上下文:

1. 01-vision.md:为什么做、为谁做、什么不做。
2. 02-requirements.md:MVP 要什么、怎么算达成。
3. 03-tech-stack.md:既定技术选型与双工具链矩阵。
4. 04-architecture.md:分层结构、目录、数据模型和关键安全流程。
5. 05-coding-rules.md:写代码前必须遵守的规则。
6. 06-tasks.md:阶段路线图、里程碑和待办池。
7. tasks/README.md:任务文件约定(一任务一文件);本轮任务从 docs/tasks/ 领取。
8. current-state.md:当前代码现实、可运行命令、下一步任务。

遇到 unsafe_cache 或需要人工处理图标缓存时,只使用 troubleshooting.md 的不跟随链接 runbook;不要在任务中临时发明递归清理命令。

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

1. 读取仓库级规则(AGENTS.md)和 agent-context.json。
2. 读取 bootstrap.always_read。
3. 读取本轮任务文件。
4. 按任务类型读取 routes 中的文档;一个文件命中多个路由时只读一次。
5. 记录默认分支头提交为 context_ref;同一会话中文件 SHA 未变化时复用已读内容。

清单的使用、缓存和断连降级规则见 agent-context.md。

固定开工流程

读完上述文档后,每轮会话按这个机械顺序进入,恢复持久状态再动手:

1. pwd:确认在正确的仓库根目录。
2. 读 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)。

当前阶段

当前项目已完成 Phase 0～2、T-301 与审核整改 T-604～T-612。Windows 安全路径阻断项、图标缓存资源边界、后台结果回 UI 线程的事件接线、双适配器交互契约、VisibleItems 快照生命周期、双端 Gio shell 职责拆分、unsafe cache 安全诊断/runbook 以及 ZIP 中央目录/EOCD(含 ZIP64)预扫描均已关闭;下一步按 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-612:图标缓存资源边界、UI 线程事件接线、双 Gio 适配器交互契约、VisibleItems generation 生命周期、双端 shell.go 同 package 镜像职责拆分、unsafe cache 诊断/人工恢复指引和 ZIP 中央目录/EOCD 预扫描;下一步串行处理 Phase 1 断电耐久性整改,再继续 T-302/T-303 与 Phase 4-6。

领取任务规则

任务以「一任务一文件」存放在 docs/tasks/(约定见 tasks/README.md):

• 单 Agent 只领取一个 frontmatter status: TODO 且依赖均 DONE 的任务文件,取编号最靠前的;项目同一时间只保留一个活跃任务。
• 若 docs/tasks/ 暂无可领任务,先按 06-tasks.md 路线图把下一个建议任务落成任务文件,再领取。
• 开始前在独立分支 / worktree 把该文件 frontmatter 的 status 改为 DOING。
• 本轮只完成这一个任务;验收通过后改为 DONE。
• 执行记录写进该任务文件的 ## 执行记录(改了什么、跑了什么验证、结果、决策)。
• 若项目现实发生变化(启动/验证路径、目录结构、blocker),覆盖更新 current-state.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:功能范围与验收标准。
• api.md 与 schemas/:清单、软件包、许可证、事件、CLI 的协议合约。
• 04-architecture.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。标准分项命令:

# 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/ 校验 + 同步文档。
• 如果命令当前不可运行(骨架未建成),必须在回复里如实说明原因。