# AGENTS.md

> AI coding agent 的仓库级入口。进入本仓库后,先读本文,再进入 `docs/00-ai-start-here.md`。

## 项目定位

本仓库是 **SoftBox 软件盒子** 主程序:使用 Go + Gio 开发的 Windows 软件盒子,覆盖软件发现、下载、安装、更新、启动和授权,兼容部分 Windows 7 用户。

采用「单仓库、单主分支、双构建」方案:

- `core/`:共享业务核心(清单、下载、安装、更新、授权、存储),保持 Go 1.20 语法兼容,禁止 import Gio。
- `app-modern/`:现代版(Win10/Win11 x64),当前受支持 Go + 当前 Gio。
- `app-win7/`:Win7 遗留版(Win7 SP1),锁定 Go 1.20 + Gio v0.6.0。

本仓库不包含子软件(app-*)业务源码,也不包含服务端私钥。

## 必读顺序

每次开始工作前:

1. 本文件。
2. `docs/agent-context.json`:上下文路由清单。
3. 清单 `bootstrap.always_read` 中的文件(`docs/00-ai-start-here.md`、`docs/05-coding-rules.md`、`docs/current-state.md`)。
4. 本轮任务文件(`docs/tasks/T-<编号>.md`)。
5. 按任务类型读取清单 `routes` 中的文档;重复路径只读一次。

首次接入或清单校验失败时,按 `docs/00-ai-start-here.md` 的完整顺序读取 01→06。

## 硬性架构边界(违反即返工)

- `core/` 的 domain 与 application 不得 import Gio、SQLite 或 Windows API;依赖只进不出:`app-modern`/`app-win7` → `core`,不得反向。
- `core/` 只使用 Go 1.20 可编译的语法和依赖;`app-win7` 不得引入要求 Go 1.21+ 的依赖。
- Gio 只出现在 `ui/gio/`;Windows 能力只出现在 `platform/windows/`,并提供非 Windows stub 保证核心可无头测试。
- Gio Layout 中不得读磁盘、访问网络、计算哈希;后台任务只发布事件,不直接改控件。
- 下载内容未经 SHA-256 与签名验证不得执行;解压必须防路径穿越;更新必须走 staging → current → backup 可回滚流程。
- 程序更新不得覆盖 `data/` 和 `licenses/`。

完整规则见 `docs/05-coding-rules.md`,协议细节见 `docs/api.md`。

## 工作规则

- 一次只领取一个任务(`docs/tasks/` 中 `status: TODO` 且依赖全 `DONE`、编号最靠前的),按 `docs/tasks/README.md` 约定流转状态。
- 执行记录写进该任务文件的 `## 执行记录`;项目现实变化(启动/验证路径、目录、blocker)覆盖更新 `docs/current-state.md`。
- 需求变化先改文档再改代码;不在代码里发明文档没有的接口、字段和状态。
- **发现需求冲突必须暂停**:实现中若发现需求之间、或需求与已冻结协议/架构之间无法同时满足(例如需求要求某能力,而协议结构上无法表达),**立即停止该方向的实现**,把冲突写进当前任务文件的 `## 执行记录`(冲突双方的文档出处 + 技术原因),并向用户**请求裁定**。不得自行取舍、不得静默缩范围、不得为绕开冲突而修改已冻结协议。
- **裁定后文档先行**:拿到裁定后,先把结论同步到**所有**受影响文档(需求、验收标准、架构、协议、路线图、任务边界),再继续实现或拆出新任务。只更新架构/任务文档而不回头修订 `docs/02-requirements.md` 会造成验收标准失效——这是已发生过的漂移(见 `docs/review/phase5-review.md` 的试用冲突)。
- 密钥、许可证私钥、真实注册码、真实下载 URL 一律不入库;示例只用占位符。
- 提交信息使用英文祈使句,任务相关提交带上 `T-<编号>`。

## Agent 执行模式

- 后续任务默认且持续使用**单 Agent 串行执行**;当前 Agent 独立完成任务落文档、实现、审查、自测、状态更新和 Git 提交。
- 不启动子 Agent,不把测试设计、安全审查或代码审查委派给其他 Agent;需要复核时由当前 Agent 分阶段自行检查。
- 项目同一时间只保留一个活跃任务。T-301 → T-302 → T-303 这类依赖链严格按顺序完成和提交,不得提前并发实现后置任务。
- `write_paths` 继续作为单任务修改边界,用于限制任务范围和提交内容,不再用于安排并行写入。
- T-301 的多 Agent 执行记录保留为历史事实,不代表后续默认方式。
- 只有用户以后再次明确要求多 Agent,才允许先修改并提交本节及相关任务文档,再启动子 Agent;对话中的临时建议不能覆盖本规则。

## 验证

```bash
# core(必须可在无头 Linux/CI 运行)
cd core && go vet ./... && go test -count=1 ./...

# 现代版构建(交叉编译)
cd app-modern && GOOS=windows GOARCH=amd64 go build ./cmd/softbox

# Win7 版构建(强制 Go 1.20 工具链)
cd app-win7 && GOTOOLCHAIN=go1.20.14 GOOS=windows GOARCH=amd64 go build ./cmd/softbox
```

统一入口为根目录 `./init.sh` / `./init.ps1`;骨架未建成前(T-001 之前)脚本会提示命令未替换,属预期行为。

修改文档链接或文件名后,用 `rg` 搜索旧名称确认引用一致;涉及上下文清单或任务协议时运行:

```bash
python3 scripts/validate_agent_context.py
python3 scripts/validate_harness_governance.py
```