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-*)业务源码,也不包含服务端私钥。

必读顺序

每次开始工作前:

本文件。
docs/agent-context.json:上下文路由清单。
清单 bootstrap.always_read 中的文件(docs/00-ai-start-here.md、docs/05-coding-rules.md、docs/current-state.md)。
本轮任务文件(docs/tasks/T-<编号>.md)。
按任务类型读取清单 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。
需求变化先改文档再改代码;不在代码里发明文档没有的接口、字段和状态。
密钥、许可证私钥、真实注册码、真实下载 URL 一律不入库;示例只用占位符。
提交信息使用英文祈使句,任务相关提交带上 T-<编号>。

多 Agent 协作

任务依赖仍是硬门槛:T-301 → T-302 → T-303 这类依赖链不得把后置任务提前并发实现。
同一个任务默认只有一个写入 Agent拥有任务文件 write_paths;其他 Agent 可并行进行只读测试设计、安全审查或代码审查,但不得修改文件、暂存或提交。
主 Agent / coordinator 负责领取、分配角色、汇总只读意见、执行最终验证与创建该任务唯一提交;审查 Agent 只通过消息返回发现和建议。
只有先把大任务拆成独立 T-<编号><后缀>.md、冻结共享接口并提交,且各子任务 write_paths 无目录前缀重叠时,才允许多个写入 Agent 并行编码。
多 Agent 角色、写入所有权、只读边界和汇总结果必须记录到当前任务的 ## 协作约束 / ## 执行记录,不能只存在于对话。

验证

# 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 搜索旧名称确认引用一致;涉及上下文清单或任务协议时运行:

python3 scripts/validate_agent_context.py
python3 scripts/validate_harness_governance.py

4.1 KiB Raw Blame History