opc/soft_quay

Fork 0

Files

T

ilaandClaude Fable 5 0184595ccc

Harness governance / validate (push) Has been cancelled

Details

Add harness coding docs for SoftBox (Go + Gio dual-build)

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>

2026-07-16 14:33:54 +08:00

3.3 KiB

Raw Blame History

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-<编号>。

验证

# 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

3.3 KiB Raw Blame History