64 lines
4.6 KiB
Markdown
64 lines
4.6 KiB
Markdown
 
|
# AGENTS.md
|
||
|
|
|
||
|
|
> AI coding agent 的仓库级入口。进入本仓库后,先读本文,再进入 `docs/00-ai-start-here.md`。
|
||
|
|
|
||
|
|
## 项目定位
|
||
|
|
|
||
|
|
本仓库是 **soft_quay_web**:SoftBox 软件盒子的中央发布 / 登记系统(客户端仓库历史文档中也称 `softbox-catalog`,指同一系统)。职责:软件登记 + 构建包接收校验 + Ed25519 签名服务 + 双通道清单生成 + 对象存储发布 + 许可证/撤销签发 + Web 管理后台。
|
||
|
|
|
||
|
|
最终产物是放在对象存储 / CDN 上的**静态签名文件**(manifest、ZIP 包、许可证、撤销名单),不是面向客户端的动态 API;客户端 `soft_quay` 只内置公钥、离线验签。
|
||
|
|
|
||
|
|
本仓库不包含子软件(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/W-<编号>.md`)。
|
||
|
|
5. 按任务类型读取清单 `routes` 中的文档;重复路径只读一次。
|
||
|
|
|
||
|
|
首次接入或清单校验失败时,按 `docs/00-ai-start-here.md` 的完整顺序读取 01→06。
|
||
|
|
|
||
|
|
## 硬性边界(违反即返工,多数同时是安全事故)
|
||
|
|
|
||
|
|
- **私钥隔离**:Ed25519 私钥只存在于受控签名服务(KMS/HSM 或独立最小权限进程);绝不进 Web 进程、代码仓库、测试数据、环境变量明文或日志。仓库内一切签名示例只用与客户端 corpus `public_key_base64` 配对的**测试密钥对**。
|
||
|
|
- **协议以客户端为权威源**:清单 / 包 / 许可证协议以 `soft_quay/docs/api.md` 与 `soft_quay/schemas/*.json` 为准;字段变化必须先在客户端仓库定稿,本仓库不得单方面新增/修改协议字段。
|
||
|
|
- **canonicalization 不得自举**:规范化与签名的跨实现回归只消费 `soft_quay/testdata/catalog/canonical-vectors.json` 的静态期望值(bytes/公钥/签名);禁止用本仓库 canonicalizer 重新生成期望值。
|
||
|
|
- **不造第二套验签域**:单公钥协议升级前,不得为 package、图标或任何对象另造签名域;package `signature` 的独立语义是未定项(见 `docs/api.md`)。
|
||
|
|
- **通道隔离**:`manifest-modern.json` 与 `manifest-win7.json` 全程不交叉;win7 清单不得出现 Win7 无法启动的包。
|
||
|
|
- **发布原子性**:ZIP 包与图标必须先于引用它们的签名清单可用;任何"先切清单再传包"的捷径都不允许。
|
||
|
|
- **审计 append-only**:发布 / 下架 / 撤销 / 许可证签发的审计记录只追加,不可覆盖或删除。
|
||
|
|
- **不保存原始硬件标识**:许可证只处理 `machine_hash`;原始序列号 / MAC 不入库、不入日志。
|
||
|
|
- 真实私钥、真实注册码、真实生产 URL、云凭据一律不入库;示例只用占位符和测试数据。
|
||
|
|
|
||
|
|
完整规则见 `docs/05-coding-rules.md`,协议摘要见 `docs/api.md`。
|
||
|
|
|
||
|
|
## 工作规则
|
||
|
|
|
||
|
|
- 一次只领取一个任务(`docs/tasks/` 中 `status: TODO` 且依赖全 `DONE`、编号最靠前的),按 `docs/tasks/README.md` 约定流转状态。
|
||
|
|
- 任务编号使用 `W-<编号>`;引用客户端仓库任务时写全称(如 `soft_quay/T-614`),避免跨仓库混淆。
|
||
|
|
- 执行记录写进该任务文件的 `## 执行记录`;项目现实变化(启动/验证路径、目录、blocker)覆盖更新 `docs/current-state.md`。
|
||
|
|
- 需求变化先改文档再改代码;不在代码里发明文档没有的接口、字段和状态。
|
||
|
|
- 未定项(见 `docs/06-tasks.md` 裁定清单)未裁定前,不得在代码里替用户做决定;先落裁定任务。
|
||
|
|
- 提交信息使用英文祈使句,任务相关提交带上 `W-<编号>`。
|
||
|
|
|
||
|
|
## Agent 执行模式
|
||
|
|
|
||
|
|
- 默认**单 Agent 串行执行**;当前 Agent 独立完成任务落文档、实现、审查、自测、状态更新和 Git 提交。
|
||
|
|
- 不启动子 Agent,不把测试设计、安全审查或代码审查委派给其他 Agent;需要复核时由当前 Agent 分阶段自行检查。
|
||
|
|
- 项目同一时间只保留一个活跃任务;依赖链严格按顺序完成和提交。
|
||
|
|
- 只有用户明确要求多 Agent 时,才允许先修改并提交本节及协作规则,再启动子 Agent。
|
||
|
|
|
||
|
|
## 验证
|
||
|
|
|
||
|
|
统一入口为根目录 `./init.sh` / `./init.ps1`;W-001 工程骨架完成前,脚本顶部三个命令为占位符,运行会主动失败并提示,属预期行为。真实命令由 W-001 替换并同步到 `docs/03-tech-stack.md`、`docs/00-ai-start-here.md` 与 `docs/current-state.md`。
|
||
|
|
|
||
|
|
修改文档链接或文件名后,用 `rg` 搜索旧名称确认引用一致;涉及上下文清单时运行:
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 scripts/validate_agent_context.py
|
||
|
|
```
|