ilaandClaude Fable 5
0184595ccc
Harness governance / validate (push) Has been cancelled
Initialize the full harness coding document set from the harness_coding_docs template, customized for the SoftBox project: - Vision, requirements, tech stack (modern Go 1.25 + Gio v0.10.1; Win7 legacy Go 1.20.14 + Gio v0.6.0), architecture, coding rules - Protocol contracts (signed catalog, package protocol v1, Ed25519 license, events, CLI) and Gio view structure - Roadmap Phase 0-6 with 20 suggested tasks; T-001 (monorepo skeleton) filed and ready to claim - Agent entry points (AGENTS.md, docs/00-ai-start-here.md), context manifest, governance scripts and tests - Merge Go gitignore with harness rules; keep go.work tracked Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
69 lines
3.3 KiB
Markdown
69 lines
3.3 KiB
Markdown
# 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`。
|
|
- 需求变化先改文档再改代码;不在代码里发明文档没有的接口、字段和状态。
|
|
- 密钥、许可证私钥、真实注册码、真实下载 URL 一律不入库;示例只用占位符。
|
|
- 提交信息使用英文祈使句,任务相关提交带上 `T-<编号>`。
|
|
|
|
## 验证
|
|
|
|
```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
|
|
```
|