Files

T

ilaandClaude Fable 5 a89821a571 Initialize harness coding docs from design spec

Split docs/softbox-catalog-design.md into the numbered harness doc set
(00-06, api.md, current-state, agent-context, tasks) following the
harness_coding_docs template and soft_quay conventions. Register the
nine open decision items from the design spec into the 06-tasks
roadmap as W- tasks and backlog entries. Keep the original design
spec as an archived design input with a header note.

Recreated after the repository's previous git history was lost to an
external reset; content matches the original initial commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

2026-07-20 00:43:58 +08:00

4.6 KiB

Raw Blame History

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-*)业务源码,不包含盒子客户端的下载 / 安装 / 授权实现。

必读顺序

每次开始工作前:

本文件。
docs/agent-context.json:上下文路由清单。
清单 bootstrap.always_read 中的文件(docs/00-ai-start-here.md、docs/05-coding-rules.md、docs/current-state.md)。
本轮任务文件(docs/tasks/W-<编号>.md)。
按任务类型读取清单 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 搜索旧名称确认引用一致;涉及上下文清单时运行:

python3 scripts/validate_agent_context.py

4.6 KiB Raw Blame History