soft_quay_web/docs/00-ai-start-here.md

# 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 文档集已建立(原始设计规格已完整拆分进编号文档后删除,需要时查 git 历史)。下一步按路线图落成并执行 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):选型与待定项。

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

- git 历史中已删除的原始设计规格 `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
```