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

5.9 KiB

Raw Blame History

AI 开发入口

给 AI coding agent 的项目入口。这里负责导航和流程,硬性编码规则见 05-coding-rules.md。

一句话定位

soft_quay_web 是 SoftBox 软件盒子的中央发布 / 登记系统:软件登记 + 构建包接收校验 + Ed25519 签名 + 双通道清单生成 + 对象存储发布 + 许可证/撤销签发 + Web 管理后台。产物是静态签名文件,信任根是私钥;客户端 soft_quay 只内置公钥、离线验签。

第一里程碑(M1):产出被 soft_quay 客户端验签通过、被 corpus + Schema 回归通过的 manifest——在任何 UI 之前达成。

上下文读取

首次接入、agent-context.json 缺失或校验失败时,按这个顺序建立完整上下文:

01-vision.md:为什么做、为谁做、什么不做。
02-requirements.md:要什么、怎么算达成。
03-tech-stack.md:技术选型与待定项。
04-architecture.md:信任模型、组件边界、数据模型、发布流水线。
05-coding-rules.md:写代码前必须遵守的规则。
06-tasks.md:阶段路线图、里程碑、未定项裁定清单和待办池。
tasks/README.md:任务文件约定(一任务一文件);本轮任务从 docs/tasks/ 领取。
current-state.md:当前代码现实、可运行命令、下一步任务。

日常会话不需要机械重读全部文档:

读取仓库级规则(AGENTS.md)和 agent-context.json。
读取 bootstrap.always_read。
读取本轮任务文件。
按任务类型读取 routes 中的文档;一个文件命中多个路由时只读一次。
记录默认分支头提交为 context_ref;同一会话中文件 SHA 未变化时复用已读内容。

清单的使用、缓存和断连降级规则见 agent-context.md。

固定开工流程

pwd:确认在正确的仓库根目录。
读 current-state.md 和 docs/tasks/ 中当前活跃任务,恢复已验证状态、下一步和当前 blocker。
git log --oneline -5:看清最近发生了什么。
运行 ./init.sh(Windows 原生 PowerShell 用 ./init.ps1);W-001 完成前脚本会提示命令未替换并失败,属预期。
W-002 之后:跑 corpus + Schema 回归闸门,确认基线没坏。
如果基线已坏,先修基线,不要在坏的起点上叠新功能。
基线绿了,再从 docs/tasks/ 领取唯一任务(路线图见 06-tasks.md)。

当前阶段

项目处于文档就绪、代码未起步阶段:harness coding 文档集已建立,设计规格见 softbox-catalog-design.md。下一步按路线图落成并执行 Phase 0(W-001 骨架与权威源接入、W-003 私钥管理裁定)。

客户端 soft_quay 已完成 Phase 0~4,当前 blocker 之一是缺可信 Catalog 发布源——正是本仓库的 M2/M3 要解决的。

领取任务规则

任务以「一任务一文件」存放在 docs/tasks/(约定见 tasks/README.md):

单 Agent 只领取一个 frontmatter status: TODO 且依赖均 DONE 的任务文件,取编号最靠前的;项目同一时间只保留一个活跃任务。
若 docs/tasks/ 暂无可领任务,先按 06-tasks.md 路线图把下一个建议任务落成任务文件,再领取。
开始前把该文件 frontmatter 的 status 改为 DOING;本轮只完成这一个任务;验收通过后改为 DONE。
执行记录写进该任务文件的 ## 执行记录(改了什么、跑了什么验证、结果、决策)。
项目现实变化(启动/验证路径、目录结构、blocker)覆盖更新 current-state.md。
结束会话前过一遍 clean-state-checklist.md。
做完即停,汇报验证结果,等待下一步指令。

如果代码实际状态和任务文件冲突,先说明冲突,不要擅自跳步或重排。

事实来源

项目事实只信:

soft_quay/docs/api.md 与 soft_quay/schemas/、soft_quay/testdata/catalog/canonical-vectors.json:协议与签名域的唯一权威源。
api.md:发布端视角摘要与本仓库特有接口合约。
04-architecture.md:信任模型、组件边界、数据模型、流水线。
02-requirements.md:功能范围与验收标准。
03-tech-stack.md:选型与待定项。

不要把以下内容当事实来源:

softbox-catalog-design.md 中与编号文档冲突的部分(它是拆分前的原始规格,冲突时以编号文档为准)。
客户端仓库中对发布侧的历史称呼(softbox-catalog)所暗示的另一个仓库——就是本仓库。
未被任务或需求引用的草稿。

常见任务该看哪里

做 canonicalization / 签名:

先看 api.md §签名域,再看客户端 corpus 向量;05-coding-rules.md §2 的自举禁令必须遵守。

做 Registry / Ingestion / Manifest Generator:

先看 api.md 的清单与包协议,再看 04-architecture.md 的组件职责、数据模型和流水线。

做签名服务 / 密钥:

先看 04-architecture.md §五与 W-003 裁定结论;私钥隔离规则见 05-coding-rules.md §3。

做 Web 管理端(Phase 5):

先看 02-requirements.md 对应验收标准与 W-501 裁定结论;UI 文档届时按模板补齐。

做发布 / 部署:

先看 03-tech-stack.md 与 current-state.md 的当前真实命令。

验证命令

统一入口为根目录 ./init.sh / ./init.ps1。当前(W-001 前)三个命令为占位符,运行会主动失败并提示;W-001 用真实命令替换后同步本节、03-tech-stack.md 与 current-state.md。

涉及上下文清单变化时运行:

python3 scripts/validate_agent_context.py

5.9 KiB Raw Blame History