培智教材知识库（peizhi-jiaocai-zhishiku）
这是一个数据层技能，不是流程技能。 它不写教案、不生成文档，只做一件事：
把培智三科主科的课标与教材蒸馏成可检索、可引用、可追溯的结构化知识，
并用一个统一接口交给其他技能调用。
写作类技能（教学设计、二次备课、说课稿、IEP）是它的调用方；
本技能是它们的依据来源。
一、触发方式
1. 用户直接问（问答式）
| 用户说 | 走哪个子命令 |
|---|---|
"课标里 1-1-3 是什么？" / "第一学段常见的量有哪些要求？" |
curriculum |
| "《比厚薄》在教材第几页？教材上出了什么题？" | textbook |
| "三上生活数学第一单元有哪些课？" | textbook（不传 --lesson） |
| "《比厚薄》的重点难点是什么？分层怎么落？" | lesson |
| "哪些课跟'分类'有关？" | search |
| "帮我取《比厚薄》的设计依据" | match |
2. 被其他技能调用（主用途）
其他备课技能在进入写作之前，先调 match 拿依据包，再动笔。
调用契约见 references/检索协议.md。
3. 用户在别的技能里备课时的自动匹配
教学设计、二次备课等技能应当在"定位课题"这一步调用本技能，
拿到三层依据后写进教案的「课标对接」「教学内容分析」「重难点」字段。
二、三层数据结构
知识库按可信度与职责分三层，调用时必须分清层次，不可混用：
| 层 | 内容 | 性质 | 位置 |
|---|---|---|---|
| 课标层 | 内容标准条目、课程目标、教学/评价建议 | 事实，逐条来自课标原件 | references/课标结构化/ |
| 课本锚点层 | 教材页码、教材原题 | 事实，脚本从教材原件自动定标 | ../peizhi-jiaocai-beike/references/教材锚点/ |
| 逐课卡片层 | 知识点、重难点、A/B/C 分层落点、教具、活动建议 | 教学建议，可能有拟定成分 | ../peizhi-jiaocai-beike/references/教材/ |
当前覆盖（36 册逐课卡片已全量完成，共 741 条）：
| 学科 | 册次 | 条目 | 编排方式 | 卡片字段体系 |
|---|---|---|---|---|
| 生活数学 | 1–9 年级 18 册 | 346 | 一~三年级「单元+情境主题页+课题」；四~九年级「模块+子课+总复习」 | 知识点/重难点/分层落点 |
| 生活语文 | 1–9 年级 18 册 | 395 | 「单元+课文+语文小天地+口语交际+写话与习作+附录字词表」 | 字—词—句—文四层（认读字/书写字/词语/课文要点） |
| 生活适应 | — | 0 | 已有 18 册课本锚点，逐课卡片待蒸馏 | —— |
教材总索引：../peizhi-jiaocai-beike/references/教材/index.md（36 册 / 191 单元 / 741 课题）。
关键区分：课标层与锚点层是抄来的，可以直接引用；
卡片层的分层落点、康复落点属拟定建议，引用时必须连带声明
"使用前请按本班实际核定"（卡片头部 > 分层口径 / > 康复落点 行已写明）。
三层的关系：锚点必定有（三科 53 册已定标），卡片可以没有。
生活适应有锚点但无卡片，缺失时用「锚点页码 + 原题 + 课标条目」仍可支撑备课，
但必须在交付说明里讲明"该课尚未逐课蒸馏"。
粒度不一致是正常的：一~三年级锚点与卡片同为「课级」；
四~九年级锚点只到「模块级」（如「20以内的退位减法」），卡片拆到「子课」
（如「十几减9」）。这种情况接口会按页码覆盖回退，并在依据包里用
layers.textbook.scope = "模块级" 标出、在 gaps 里提示——
此时教材原题是模块级摘录，含本课以外的题目，引用前必须核对。
三、调用接口
唯一入口：scripts/kb_query.py。解释器统一用：
/Users/zhz/.workbuddy/binaries/python/envs/default/bin/python
子命令
<py> <SKILL_DIR>/scripts/kb_query.py <子命令> [参数] [--json]
| 子命令 | 作用 | 关键参数 |
|---|---|---|
subjects |
列出覆盖范围（三科课标统计 + 53 册锚点一览） | 无 |
curriculum |
查课标条目 | --subject --code --band --domain --keyword |
textbook |
查课本锚点（页码 + 原题） | --subject --volume --lesson（省略则列全册） |
lesson |
查逐课卡片 | --subject --volume --lesson |
search |
全库关键词检索（课标 + 锚点 + 卡片） | --keyword --subject(可选) |
match |
★ 一键取设计依据包 | --subject --volume --lesson |
别名容错
调用方不必对齐写法，接口自己做归一：
- 册次：
三上=三年级上册=3上 - 学段：
第一学段=低年级段=低段=1~3年级（三科原件用词不同，见第七节） - 学科：
数学/语文/适应皆可
数据源环境变量
数据位置可覆盖，便于迁移：
PEIZHI_KB_CURRICULUM_DIR # 课标结构化目录，默认本技能 references/课标结构化
PEIZHI_KB_ANCHOR_DIR # 课本锚点目录，默认 ../peizhi-jiaocai-beike/references/教材锚点
PEIZHI_KB_LESSON_DIR # 逐课卡片目录，默认 ../peizhi-jiaocai-beike/references/教材
退出码（调用方据此分支，不要只看 stdout）
| 码 | 含义 | 调用方应做 |
|---|---|---|
| 0 | 命中 | 正常使用结果 |
| 3 | 该册/该学科未收录 | 告知用户"这册还没定标"，不要凭记忆写页码 |
| 4 | 册内无此课题 | 请用户核对课题名是否与教材一致 |
| 5 | 无逐课卡片（锚点仍在） | 降级为"通用建议"，并在交付里声明 |
四、输出格式
4.1 设计依据包（match，主接口）
--json 输出结构（完整字段定义见 references/输出格式.md）：
{
"query": { "subject": "生活数学", "volume": "三年级上册",
"lesson": "比厚薄", "band_code": "1" },
"found": true,
"layers": {
"curriculum": [ { "code": "1-1-3", "band": "第一学段", "domain": "常见的量",
"text": "感知物体的粗细、厚薄、轻重、宽窄等量的特点，会比较并排序。" } ],
"textbook": { "volume": "生活数学-三年级上册", "unit": "第一单元 校园生活",
"lesson": "比厚薄", "pages": "P3–P4",
"items": ["练一练 1. 把薄的被子圈出来。"], "blanks": [] },
"lesson_card": { "knowledge_points": "…", "key_point": "…", "difficulty": "…",
"group_a": "…", "group_b": "…", "group_c": "…" }
},
"candidate_domains": [],
"card_meta": { "分层口径": "……使用前请按本班实际核定" },
"gaps": ["该课尚未逐课蒸馏，…"],
"citations": [ { "layer": "课程标准", "file": "课标结构化/生活数学.json",
"what": "1-1-3 第一学段·常见的量" } ],
"next_step": ["三层依据齐备，可直接进入教学设计/二次备课。"],
"generated_at": "2026-10-16T08:00:00"
}
调用方必须处理的两个字段：
gaps—— 非空时必须把这些提示带进交付说明，不能吞掉；card_meta—— 有值时必须把分层口径/康复落点的声明一并转述。
4.2 其余子命令
curriculum→{"subject","count","records":[{code, band, domain, sub_domain, topic, seq, optional, text}]}textbook→{"subject","volume","count","lessons":[{unit, name, pages, items, blanks, note}]}lesson→ 卡片字段：curriculum_link, pages, knowledge_points, key_point, difficulty, group_a, group_b, group_c, materials, rehab, life_link, assessment, activities, notessearch→{"keyword","count","curriculum":[],"textbook":[],"lesson":[]}
不加 --json 时输出同样内容的人类可读版，可直接展示给教师。
五、调用方集成约定（重要）
其他技能引用本技能时，遵守三条：
-
先 match 后动笔。进入写作前调用
match，把三层依据落到
教案的「课标对接」「教材页码」「教学重难点」「分层目标」字段。 -
引用不改写。课标条目、教材页码、教材原题一律照抄接口返回的原文；
需要加工时把加工内容放进自己的字段，不要覆盖原文字段。 -
缺口如实转述。
gaps里的每一条都要出现在交付说明中。
尤其"尚未逐课蒸馏"和"课标条目系关键词匹配，引用前请人工确认"这两条，
不得因为怕麻烦而省略。
六、红线
- 不虚构课标条目编号与页码。编号只有两个来源：课标结构化数据，
或卡片课标对接字段。接口返回「未收录」时就留空，禁止凭常识补。 - 不越过学段。三年级只对第一学段条目（
band_code=1）；
跨学段引用必须显式说明理由，不能因为"这条更贴切"就拉过来用。 - 区分事实与建议。锚点层与课标层是事实，卡片层的分层/康复落点是建议，
两者在交付物里必须能分辨。 - 不臆造对齐关系。课标条目匹配不上时，接口给的是
candidate_domains
（候选领域短名单），不是结论；请把短名单交给教师确认，不要自行选定。 - 教材版权。结构化产物仅供本校教学使用，不得对外分发原始教材内容。
七、三科课标的用词差异（调用前必读）
三科原件的学段用词不同，写教案引原文时用原件用词，检索时接口已做归一：
| 学科 | 领域（课标原件用词） | 学段原件用词 |
|---|---|---|
| 生活数学 | 常见的量、数与运算、图形与几何、统计、综合与实践 | 第一／第二／第三学段 |
| 生活语文 | 倾听与说话、识字与写字、阅读、写话与习作、综合性学习 | 低年级段／中年级段／高年级段 |
| 生活适应 | 个人生活、家庭生活、学校生活、社区生活、国家与世界 | 低段／中段／高段 |
> ⚠️ peizhi-jiaocai-beike/references/课标/_课标总览.md 中写"其余学科用
> 第一／第二／第三学段"，对生活语文与生活适应不准确——这两科原件用的是
> 「低年级段／低段」。以本技能的结构化数据为准。
条目编号约定：<学段>-<领域序>-<条序>，如 1-1-3
= 第一学段 · 常见的量（第 1 领域）· 第 3 条。条序是该（学段 × 领域）内的
连续序号，三个学科的元件编号方式不同（数学用 1.、语文用 1.、适应用 1.1），
统一成连续序号后跨学科引用才对得齐。此编号是检索用定位标记，不是课标官方编号；
正式文档引用时应写课标原文表述。
八、目录结构
peizhi-jiaocai-zhishiku/
├── SKILL.md
├── references/
│ ├── 检索协议.md # 调用方契约（其他技能读这个）
│ ├── 输出格式.md # 依据包字段定义
│ └── 课标结构化/
│ ├── _schema.md # JSON 字段定义
│ ├── _index.json # 三科覆盖总览（自动生成）
│ ├── <学科>.json # 结构化数据（机器用）
│ └── <学科>.md # 同内容可读版（人看/展示给教师）
├── scripts/
│ ├── kb_query.py # ★ 统一查询接口
│ ├── extract_curriculum_structured.py # 课标全文 → 结构化数据
│ └── selftest.py # 自检（改数据后跑这个）
└── assets/
九、维护知识库
课标数据（已全量完成）
三科内容标准均已结构化，重跑即可刷新：
<py> <SKILL_DIR>/scripts/extract_curriculum_structured.py --all \
-s <peizhi-jiaocai-beike>/references/课标 -o references/课标结构化
脚本会打印每科的条目统计与告警。必须核对统计数与本册/原件是否吻合；
生活适应的「分段目标」是启发式还原（原件是三栏表被 OCR 摊平），脚本已自动写告警。
教材数据（生活数学、生活语文已全量完成）
《生活数学》《生活语文》1–9 年级各 18 册卡片已全部完成。课本锚点由
peizhi-jiaocai-beike 维护，本技能直接复用；逐课卡片在源技能里维护，本技能只读。
> 锚点与卡片是两份文件，必须成对改。语文的单元结构、页码、课题名在很多册里
> 是人工从目录页重建的，改一处不改另一处就会让调用方拿到自相矛盾的依据包。
新增或修改卡片后，跑这三条：
py=/Users/zhz/.workbuddy/binaries/python/envs/default/bin/python
$py <peizhi-jiaocai-beike>/scripts/check_cards.py --subject 生活语文 # ★ 三方一致性
$py <SKILL_DIR>/scripts/selftest.py # 课标层 + 卡片层
$py <peizhi-jiaocai-beike>/scripts/build_index.py # 重建总索引
check_cards.py 检查卡片 ↔ 锚点 ↔ 课标三方是否自洽，报六类问题：
| 类别 | 说明 | 处置 |
|---|---|---|
| 编号不存在 | 引用了课标库里没有的条目 | ❌ 必须清零（＝编造依据） |
| 越学段 | 拿别年级的标准凑数 | ❌ 必须清零 |
| 条目粘连 | 「课标对接」里两条条目缺分号 | ❌ 必须清零（会让 *选学 归属错位） |
| 误标/漏标选学 | 与课标原件的选择性目标不一致 | ❌ 必须清零（误标＝把必学当可选） |
| 锚点伪条目 | 价签、OCR 噪声、空标题被当课题 | ❌ 必须清零（污染检索） |
| 条数／课题名差集 | 卡片与锚点粒度不同 | ⚠️ 属有意设计可保留，但要能解释 |
后四类是对错问题；「条数/差集」若属卡片拆到子课、锚点只到模块级等有意
差异可保留，但页码不一致一定要查明。
> 语文的「选择性目标」标记：课标原件里带 * 的条目是可选目标（142 条里 47 条），
> 与「选学课文」（标题前带 *）是两码事。卡片 课标对接 字段末尾的 *选学
> 指前者，引用时不要跟后者混淆。
锚点清洗工具（源技能里）
py=/Users/zhz/.workbuddy/binaries/python/envs/default/bin/python
$py <peizhi-jiaocai-beike>/scripts/clean_anchors.py --subject 生活数学 # 出建议
$py <peizhi-jiaocai-beike>/scripts/clean_anchors.py --subject 生活数学 --apply # 执行
$py <peizhi-jiaocai-beike>/scripts/lift_anchor_modules.py --subject 生活数学 --apply
$py <peizhi-jiaocai-beike>/scripts/check_yuwen_cite.py --fix # 语文引用格式
clean_anchors.py用卡片作真相源反查锚点：卡片是逐册回原件核对写的，
锚点是早期 OCR 自动定标的，前者可信度更高。只改编辑距离 ≤2 的明显错字，
其余列出人工判。lift_anchor_modules.py把锚点里被误写成课题（###）的模块名提升为##层。
这不是排版洁癖——match在课题名查不到时要按页码回退到上级条目，
模块层缺失时这条降级路径会失效。- 改完锚点必须重跑
check_cards.py与本节开头那三条，确认接口没退化。
验证清单
任何数据改动（重跑课标抽取、补充教材卡片）之后，跑一次自检：
<py> <SKILL_DIR>/scripts/selftest.py
它会验证 8 个子命令可用性、依据包三层完整性、三科学段用词归一、
异常分支退出码、两科各 18 册卡片齐备性与课标编号合法性（编号不存在＝编造依据、
编号越学段＝拿别年级的标准凑数），以及两条安全不变量（课标匹配不上时
只给候选不给结论、关键词提取不产出噪声词）。全部通过才说明数据层没坏。
跨册端到端抽查（确认 36 册都能取到三层依据）：
<py> <SKILL_DIR>/scripts/kb_query.py subjects
针对单个课题人工确认时：
<py> <SKILL_DIR>/scripts/kb_query.py match --subject <学科> --volume <册次> --lesson <课题>
确认三层都被命中、gaps 为空或只剩合理提示。
