edu-content/docs/conventions.md

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/。

校验与提交

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 提交。