# edu-content — 基础教育内容库（L1–L3）

私有的基础教育内容源库。为自学平台/内部服务提供**合法、可追溯、agentic friendly** 的基础学习内容。

## 四层数据模型

| 层 | 名称 | 存储 | 本仓库角色 |
|---|---|---|---|
| L1 | 资源清单 source registry | git（YAML） | ✅ `sources/` |
| L2 | 原始数据 raw | OSS `edu-raw/` | 仅登记（oss_key + sha256），不存文件 |
| L3 | 结构化清洗数据 | git（JSONL/JSON/MD） | ✅ `structured/` |
| L4 | 衍生私有数据 | git 清单 + OSS `edu-derived/` | ❌ 见 `edu-derived` 仓库 |

## 三条铁律（违反即 CI 红）

1. **先登记后下载**：任何原始文件必须先在 `sources/` 有登记（license 必填）才允许进 OSS。无登记 = 不存在。
2. **git 不进二进制大文件**：原始数据一律 OSS；git 里只有 `oss_key` + `sha256` + 元数据。
3. **血缘可机器校验**：L3 每条记录带 `source_id`，L4 每条资产带 `inputs[]`，`tools/lint_*` 全链路验证。

## 两个仓库

- **edu-content**（本仓库）：L1 资源清单 + L3 结构化数据。
- **edu-derived**（`fengjunchen/edu-derived`，同 Gitea）：L4 衍生私有数据（生成音频/图片/卷子 + 血缘 manifest）。从本仓库生成，不反向写入原始数据。

## 机器可读入口

- `INDEX.json` —— 工具生成，库的全貌/统计/红线摘要，agent 读它即可。
- 每个学科/考试目录的 `INDEX.md` —— 该域消费须知（优先序、坑、覆盖统计）。
- `LICENSES.md` —— license 枚举与红线权威定义，所有 lint 的依据。
- `docs/conventions.md` —— agent 操作手册（如何新增 source / 上传 raw / 写 structured）。

## 存储后端

- OSS bucket：`edu-content-hy`（oss-cn-heyuan，私有）。前缀 `edu-raw/`、`edu-derived/`。
- 与现有 `ai-gallery-aibeaver-hy`（公网 CDN 桶）**物理隔离**，restricted 原始数据不进公网暴露面。

## 快速开始（agent）

```bash
# 校验全库合规
python tools/lint_sources.py && python tools/lint_structured.py
# 重新生成 INDEX.json
python tools/index_build.py
# 上传原始文件到 OSS 并回填 sha256（需 OSS 凭据）
python tools/oss_sync.py --dry-run
```