46 行
2.3 KiB
Markdown
46 行
2.3 KiB
Markdown
# 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 提交。
|