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>
This commit is contained in:
Claude Fable 5
@@ -0,0 +1,110 @@
|
||||
# AI 开发入口
|
||||
|
||||
> 给 AI coding agent 的项目入口。这里负责导航和流程,硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
|
||||
|
||||
## 一句话定位
|
||||
|
||||
soft_quay_web 是 SoftBox 软件盒子的中央发布 / 登记系统:软件登记 + 构建包接收校验 + Ed25519 签名 + 双通道清单生成 + 对象存储发布 + 许可证/撤销签发 + Web 管理后台。产物是**静态签名文件**,信任根是私钥;客户端 `soft_quay` 只内置公钥、离线验签。
|
||||
|
||||
第一里程碑(M1):产出被 `soft_quay` 客户端验签通过、被 corpus + Schema 回归通过的 manifest——在任何 UI 之前达成。
|
||||
|
||||
## 上下文读取
|
||||
|
||||
首次接入、[`agent-context.json`](agent-context.json) 缺失或校验失败时,按这个顺序建立完整上下文:
|
||||
|
||||
1. [`01-vision.md`](01-vision.md):为什么做、为谁做、什么不做。
|
||||
2. [`02-requirements.md`](02-requirements.md):要什么、怎么算达成。
|
||||
3. [`03-tech-stack.md`](03-tech-stack.md):技术选型与待定项。
|
||||
4. [`04-architecture.md`](04-architecture.md):信任模型、组件边界、数据模型、发布流水线。
|
||||
5. [`05-coding-rules.md`](05-coding-rules.md):写代码前必须遵守的规则。
|
||||
6. [`06-tasks.md`](06-tasks.md):阶段路线图、里程碑、未定项裁定清单和待办池。
|
||||
7. [`tasks/README.md`](tasks/README.md):任务文件约定(一任务一文件);本轮任务从 `docs/tasks/` 领取。
|
||||
8. [`current-state.md`](current-state.md):当前代码现实、可运行命令、下一步任务。
|
||||
|
||||
日常会话不需要机械重读全部文档:
|
||||
|
||||
1. 读取仓库级规则(`AGENTS.md`)和 [`agent-context.json`](agent-context.json)。
|
||||
2. 读取 `bootstrap.always_read`。
|
||||
3. 读取本轮任务文件。
|
||||
4. 按任务类型读取 `routes` 中的文档;一个文件命中多个路由时只读一次。
|
||||
5. 记录默认分支头提交为 `context_ref`;同一会话中文件 SHA 未变化时复用已读内容。
|
||||
|
||||
清单的使用、缓存和断连降级规则见 [`agent-context.md`](agent-context.md)。
|
||||
|
||||
## 固定开工流程
|
||||
|
||||
1. `pwd`:确认在正确的仓库根目录。
|
||||
2. 读 [`current-state.md`](current-state.md) 和 `docs/tasks/` 中当前活跃任务,恢复已验证状态、下一步和当前 blocker。
|
||||
3. `git log --oneline -5`:看清最近发生了什么。
|
||||
4. 运行 `./init.sh`(Windows 原生 PowerShell 用 `./init.ps1`);W-001 完成前脚本会提示命令未替换并失败,属预期。
|
||||
5. W-002 之后:跑 corpus + Schema 回归闸门,确认基线没坏。
|
||||
6. **如果基线已坏,先修基线**,不要在坏的起点上叠新功能。
|
||||
7. 基线绿了,再从 `docs/tasks/` 领取唯一任务(路线图见 [`06-tasks.md`](06-tasks.md))。
|
||||
|
||||
## 当前阶段
|
||||
|
||||
项目处于**文档就绪、代码未起步**阶段:harness coding 文档集已建立,设计规格见 [`softbox-catalog-design.md`](softbox-catalog-design.md)。下一步按路线图落成并执行 Phase 0(W-001 骨架与权威源接入、W-003 私钥管理裁定)。
|
||||
|
||||
客户端 `soft_quay` 已完成 Phase 0~4,当前 blocker 之一是缺可信 Catalog 发布源——正是本仓库的 M2/M3 要解决的。
|
||||
|
||||
## 领取任务规则
|
||||
|
||||
任务以「一任务一文件」存放在 `docs/tasks/`(约定见 [`tasks/README.md`](tasks/README.md)):
|
||||
|
||||
- 单 Agent 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件,取编号最靠前的;项目同一时间只保留一个活跃任务。
|
||||
- 若 `docs/tasks/` 暂无可领任务,先按 [`06-tasks.md`](06-tasks.md) 路线图把下一个建议任务落成任务文件,再领取。
|
||||
- 开始前把该文件 frontmatter 的 `status` 改为 `DOING`;本轮只完成这一个任务;验收通过后改为 `DONE`。
|
||||
- **执行记录写进该任务文件的 `## 执行记录`**(改了什么、跑了什么验证、结果、决策)。
|
||||
- 项目现实变化(启动/验证路径、目录结构、blocker)覆盖更新 [`current-state.md`](current-state.md)。
|
||||
- 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
|
||||
- 做完即停,汇报验证结果,等待下一步指令。
|
||||
|
||||
如果代码实际状态和任务文件冲突,先说明冲突,不要擅自跳步或重排。
|
||||
|
||||
## 事实来源
|
||||
|
||||
项目事实只信:
|
||||
|
||||
- `soft_quay/docs/api.md` 与 `soft_quay/schemas/`、`soft_quay/testdata/catalog/canonical-vectors.json`:协议与签名域的**唯一权威源**。
|
||||
- [`api.md`](api.md):发布端视角摘要与本仓库特有接口合约。
|
||||
- [`04-architecture.md`](04-architecture.md):信任模型、组件边界、数据模型、流水线。
|
||||
- [`02-requirements.md`](02-requirements.md):功能范围与验收标准。
|
||||
- [`03-tech-stack.md`](03-tech-stack.md):选型与待定项。
|
||||
|
||||
不要把以下内容当事实来源:
|
||||
|
||||
- [`softbox-catalog-design.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`。
|
||||
|
||||
涉及上下文清单变化时运行:
|
||||
|
||||
```bash
|
||||
python3 scripts/validate_agent_context.py
|
||||
```
|
||||
Reference in New Issue
Block a user