# conventions.md — Agent 操作手册

本库供 agent（脚本/人类）规范操作。读完本文 + 根 `INDEX.json` 即可正确新增内容。

## 新增一个 source（L1）

1. 在 `sources/{china|exams|internal}/` 下选/建对应域 YAML。
2. 加一条 `source`，**必填** `id`(kebab-case 唯一)、`title`、`publisher`、`type`、`license`、`status`。
3. `license` 必须是 `LICENSES.md` 枚举值；不确定就先标 `unknown`，但 30 天内须核查。
4. 还没下载的条目 `status: planned`，**不要**先写 `oss_key`。
5. 下载后：`status: fetched`，`fetched_at: YYYY-MM-DD`，在 `items[]` 登记每个文件。

## 上传原始文件到 OSS（L2）

- 路径约定：`edu-raw/{k9|exams|internal}/{学科或考试}/{类目}/{source-id}/{filename}`
- 文件名**保持原始名**（便于法务比对原件）；清洗发生在 structured 层。
- 运行 `python tools/oss_sync.py`：上传 `sources/` 里标记待传的文件，自动回填 `oss_key`/`sha256`/`size`/`fetch_date`。

## 写结构化数据（L3）

- 落在 `structured/` 对应学科/考试目录。
- JSONL 记录必须带 `source.source_id`（指向 `sources/` 的 source id）+ `schema` 版本号。
- 记录级/字段级 license 标注沿用 vocab 的成功模式（见 `schemas/vocab-1.1.md`）。
- 每条 L3 记录的 `license` = 其引用 source 的最严格许可（lint 会重算并校验）。

## 衍生数据（L4）

- **不在此仓库**。去 `edu-derived`：生成资产 + 在 `manifest/assets.jsonl` 登记 `inputs[]`（指向本库 source_id 或具体文件路径）。
- 红线：L4 的 `inputs` 不得含 `restricted`/`internal-only`/`unknown`，否则 `edu-derived` 的 lint 直接失败。

## 命名

- source id / item id / 目录名：kebab-case。
- L3 记录 id：`{考试缩写}-{来源缩写}-{序号4位}`，如 `a2k-cepoc-0001`、`b1-official-0012`。
- OSS key 与 git 路径同构：`structured/exams/ket/vocab/` ↔ `edu-raw/exams/ket/vocab/`。

## 校验与提交

```bash
python tools/lint_sources.py      # source 登记合规
python tools/lint_structured.py   # 血缘 + license 继承
python tools/index_build.py       # 重新生成 INDEX.json
git add -A && git commit -m "..."
```
CI（Gitea Actions）会在 push 时自动跑上述 lint，失败则标红。**不要**绕过 lint 提交。