67 行
2.6 KiB
Markdown
67 行
2.6 KiB
Markdown
# sources/ — L1 资源清单（全库唯一锚点）
|
||
|
||
`sources/` 回答：**数据从哪来、什么 license、原始文件在 OSS 哪里**。任何原始文件（PDF/ZIP/MP3/原始 JSON）进 OSS 前，必须在此先登记。
|
||
|
||
## 文件组织
|
||
|
||
- 一个 YAML 文件 = 一个**域**，内含多条 `source`。
|
||
- 域分三类目录：`china/`（国内课内 + 开源数据集）、`exams/`（考试来源）、`internal/`（自制无来源课件）。
|
||
- 文件名用 kebab-case，如 `cepoc.yaml`、`cambridge-official.yaml`、`smartedu.yaml`。
|
||
|
||
## 两级结构
|
||
|
||
```
|
||
source（引用单位，血缘根 id）
|
||
└─ items[]（具体文件 = OSS 对象）
|
||
```
|
||
|
||
- L3 结构化记录引用 `source_id`（必填）+ 可选 `source_item_id`（精确到文件）。
|
||
- `internal` 类 source：`url: null`，`license: internal-only`，`oss_key` 指向归档对象。
|
||
|
||
## 字段（详见 `source.schema.json`）
|
||
|
||
| 字段 | 必填 | 说明 |
|
||
|---|---|---|
|
||
| `id` | ✅ | 全局唯一 kebab-case，血缘链根 id |
|
||
| `title` | ✅ | 人类可读 |
|
||
| `publisher` | ✅ | 发布方 |
|
||
| `type` | ✅ | `dataset`/`website`/`book`/`internal`/`tool` |
|
||
| `url` | ⚠️ | internal 可 null |
|
||
| `license` | ✅ | 见 `../LICENSES.md` 枚举 |
|
||
| `license_note` | ❌ | 许可说明（如"研究/教育用途"） |
|
||
| `fetch_method` | ❌ | `curl`/`git-clone`/`manual-download`/`manual-export`/`generated` |
|
||
| `status` | ✅ | `planned`→`fetching`→`fetched`/`failed`；`archived` 保留合规记录 |
|
||
| `fetched_at` | ❌ | 下载日期 `YYYY-MM-DD` |
|
||
| `items[]` | ❌ | 具体文件，每项含 `id`/`title`/`oss_key`/`sha256`/`size`/`media_type`/`fetch_date` |
|
||
|
||
`items[].oss_key` 在 `fetched` 后必填；`sha256`/`size` 由 `tools/oss_sync.py` 上传时自动回填。
|
||
|
||
## 示例
|
||
|
||
```yaml
|
||
sources:
|
||
- id: cepoc
|
||
title: CEPOC 剑桥机读完形题库
|
||
publisher: Cambridge ALTA, University of Cambridge
|
||
type: dataset
|
||
url: https://github.com/CambridgeALTA/cepoc
|
||
license: cc-nc-education
|
||
license_note: "研究/教育用途，非商业（见仓库 licence.txt）"
|
||
fetch_method: git-clone
|
||
status: fetched
|
||
fetched_at: "2026-08-21"
|
||
items:
|
||
- id: cepoc-ket-json
|
||
title: KET.json（6套68空）
|
||
oss_key: edu-raw/exams/ket/questions/cepoc/KET.json
|
||
sha256: "a1b2c3..." # oss_sync.py 自动回填
|
||
size: 12345
|
||
media_type: application/json
|
||
fetch_date: "2026-08-21"
|
||
status: fetched
|
||
```
|
||
|
||
## 状态生命周期
|
||
|
||
`planned`（调研发现，未下载）→ `fetching` → `fetched`/`failed`。调研报告迁移时大量条目初始为 `planned`。`unknown` 状态超过 30 天 lint 报 warning。
|