cotutor 0.2.0 → 0.4.0

package/package.json

@@ -1,33 +1,38 @@
 {
   "name": "cotutor",
-  "version": "0.2.0",
-  "description": "家里的 AI 老师团,和家长一起教:老师 = 可直接对话的 agent 文件 + 自己的会话;一孩一 workspace",
+  "version": "0.4.0",
+  "description": "AI tutors that co-teach with parents at home: real-time voice, an interactive whiteboard, and learning memory in your own Obsidian vault. Self-hosted; built for China's elementary curriculum.",
   "type": "module",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE",
   "repository": "github:TarsLab/cotutor",
   "homepage": "https://github.com/TarsLab/cotutor#readme",
   "bugs": "https://github.com/TarsLab/cotutor/issues",
   "keywords": [
     "ai",
     "agent",
-    "claude-code",
     "qwen-code",
     "tutor",
     "education",
-    "homeschool",
+    "elementary",
+    "realtime",
+    "voice",
+    "obsidian",
     "cli"
   ],
   "bin": {
     "cotutor": "bin/cotutor.js"
   },
+  "sideEffects": [
+    "*.css"
+  ],
   "exports": {
     "./schema": {
       "types": "./dist/schema/index.d.ts",
       "default": "./dist/schema/index.js"
     },
     "./workspace": {
-      "types": "./dist/cli/workspace.d.ts",
-      "default": "./dist/cli/workspace.js"
+      "types": "./dist/app/workspace.d.ts",
+      "default": "./dist/app/workspace.js"
     },
     "./lib": {
       "types": "./dist/lib/index.d.ts",
@@ -38,11 +43,17 @@
   "files": [
     "bin",
     "dist",
-    "agents",
+    "grades",
+    "themes",
+    "avatars",
+    "cards",
+    "skills",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "NOTICE"
   ],
   "scripts": {
+    "gen:skills": "node --experimental-strip-types scripts/gen-skills.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types scripts/test.ts",
     "build": "rm -rf dist && tsc -p tsconfig.build.json",
@@ -54,18 +65,19 @@
     "node": ">=22.18"
   },
   "dependencies": {
+    "@ai-sdk/alibaba": "2.0.78",
     "@excalidraw/excalidraw": "0.18.1",
-    "drawtell": "^0.6.1",
-    "drawtell-skills": "^0.1.0",
+    "ai": "7.0.155",
+    "hanzi-writer-data": "2.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/node": "^22.20.1",
     "@types/react": "^18.3.31",
     "@types/react-dom": "^18.3.7",
-    "esbuild": "^0.28.2",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "typescript": "^5.6.0"
+    "esbuild": "^0.28.2"
   }
 }

package/skills/chalk-cli/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: chalk-cli
+description: 做课包的命令 cotutor chalk 怎么用:反馈阶梯(check / snap)与 index.json 契约、build 出课包、烤画面 bake、配音 dub、在舞台上预览。跑工具、自检截图、配音、预览时读。不是:这道题怎么讲(→ chalk-teaching)、场景怎么写(→ chalk-scene)、截图怎么评(→ chalk-verify)。
+---
+
+# 工具用法
+
+## 在哪儿跑
+
+在孩子的 workspace 里跑 `cotutor chalk …`(或任何目录下加 `--workspace <dir>`)。
+课包出到 workspace 的 `bundles/<id>/`(`--bundles <dir>` 换),孩子端的小课堂、lecture 卡就从这里放;
+截图出到 `bundles/` 旁边的 `snaps/<id>/`(`--out` 换)。`bundles/`、`snaps/` 是派生物,能随时重出,**别往里放手写文件**。
+场景源放哪都行(workspace 的 `scenes/`,或单独一个做课的目录),位置参数与 `--out` / `--bundles` 的相对路径按当前目录。
+每条命令都有 `--json`(路径里的家目录脱敏成 `$HOME`)。
+
+## 反馈阶梯(便宜层先消化)
+
+1. 类型层:`cotutor chalk check` 自带(内嵌 tsc,把场景里的 `import type … from 'cotutor/chalk'` 映射到包内类型;工作区不需要
+   tsconfig、不需要装 typescript),类型错误与结构错误一起出在 findings 里(rule `types`,带 文件:行:列 TS 号);
+   `--no-types` 可跳过
+2. `cotutor chalk check scenes/<id>.ts --json`——修到 0 错误;警告逐条判断。文字宽按字宽表算
+   (真播放器量的:汉字 1em,数字、字母各有各的宽;行高 1.25),和真实渲染差不到 2%,排版按同一把尺子算
+3. `cotutor chalk snap scenes/<id>.ts --no-cursor` → `snaps/<id>/step-*.png` + `index.json`(先 check + build;要本机的 Chrome)。
+   `--no-cursor` 不画笔尖,帧里只剩笔迹;不加也行,但要知道笔尖停在本步末笔处,不算画面元素。
+   index.json(v2)的 shots[] 把每张图和该步讲稿配好对,并列出该步新增元素
+   (`added[]`:id / type / strokeColor / backgroundColor / text / 近似 bbox)与画板 `board.viewBox`——
+   数数对着 added 数,越界对着 viewBox 判(bbox 是场景坐标,图像像素 =
+   (坐标 − viewBox 原点) × 图宽 / viewBox 宽)。
+   修单步后 `--step <n>` 只重截那一步(index.json 合并写入);若改动影响了整体包围盒
+   (播放器按整场等比缩放),其他帧比例会陈旧,最后再全量截一次
+
+## 出课包 build
+
+`cotutor chalk build scenes/<id>.ts` → `bundles/<id>/`(scene.json + manifest.json;先 check,有错不出)。
+背景图拷进课包。已有的 `audio/` 不动:讲稿没改的步,build 照旧挂上那一步的配音;改了的步等重新 dub。
+
+## 烤画面 bake
+
+`cotutor chalk bake <id>`(或 `scenes/<id>.ts`,先 check + build)→ `bundles/<id>/bake.json`:画面在本机 Chrome 里静态导出一次,
+存每一笔的路径与长度、笔尖轨迹、内嵌字体。孩子端照它现画,不再在孩子的设备上跑 excalidraw。
+
+- **snap 会顺手烤**:没烤过或画面改过才烤。走完反馈阶梯,课包就是烤好的;截图用的就是孩子端那套渲染。
+- **只改了讲稿、配音,不用重烤**;改了画面(元素、背景图)要重烤,不重烤应用会当它没烤过(服务端发现了会在后台补烤)。
+
+## 配音 dub
+
+`cotutor chalk dub <id>`:音色用 `--voice <音色 id>`,或 `--tutor <老师>`(缺省 math-tutor)在 cotutor.json 里配的卡的音色;
+语气 `--instruction <一句话>` 可选。先 `--dry-run` 算账;讲稿与音色都没变的步不重配。
+dub 会报每步"音 X s / 画 Y s → 拉伸 ×n":播放器把该步笔画拉伸到
+讲稿长度(只拉不缩,封顶 5 倍),"一边画一边数"就真的一个一个出来;超过 5 倍怎么办是讲法问题,
+口径在 chalk-teaching 讲稿套路。
+
+## 预览
+
+`cotutor serve` 起着时,在电脑上打开 `/stage/?bundle=/api/bundles/<id>/&autoplay=1`,就是孩子看到的小课堂(从头放、能拖)。
+要孩子在首页看到它,挂到首页(cotutor-home 技能)。
+
+## 待引擎(写场景时按现状)
+
+- 播放器按整场包围盒等比缩放,**不按宽缩放、不跟笔滚动**——试卷式布局(chalk-scene)先把高度控制在一屏内。
+- `snap` 的 index.json `added[]` 不带 `customData`(role 看不到);verify 按位置与类型判段落。
+- `check` 不核 `steps[].line` 与说明文件的讲稿是否一致——试跑期靠纪律。

package/skills/chalk-scene/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: chalk-scene
+description: 课包场景的技术契约领域:场景怎么写才合法、画得下。ChalkScene 元素模型与纯数据模块写法、场景 id 约定、笔顺即步序、steps 覆盖约束、单笔时长经验、试卷式布局(页宽固定、草稿段 / 作答段自上而下、customData.role 可选)、布局经验、「数量与画面」几何、渲染事实、种子与真题参考。从说明文件写场景 TS 前读。不是:怎么讲(→ chalk-teaching)、工具怎么跑(→ chalk-cli)。不拥有交付物,由工作流按需加载。
+---
+
+# 场景契约
+
+场景是纯数据 TS 模块:`import type { ChalkScene, ChalkSkeleton } from 'cotutor/chalk'`(运行时被擦除;
+并进 cotutor 之前写的 `from 'drawtell'` 照认)。确定性约束(append-only、笔顺即步序、
+text-overlap 等)由 `cotutor chalk check` 强制——机制在 cotutor 的 src/chalk,本 skill 只写怎么写得对。
+
+## 结构契约
+
+- 场景文件 `scenes/<id>.ts`,id:小写字母数字连字符。**工作区场景的 id 约定 `<YYYY-MM-DD>-<题眼>`**
+  (生成日 + 1–2 个拼音词,如 `2026-08-25-wazi`;同日同题眼加 `-2`,写前查一下文件是否已存在)——
+  id 是机器引用,人读的是 `title`,日期段管唯一性与排序。工具仓种子(dengche 等)是教学参考,不入此规
+- 导出用 `export default`(或任一单个具名导出;loader 不要求导出名等于 id——日期开头的 id 不是合法标识符)
+- skeletons 数组顺序 = 笔顺;steps 的 elementIds 按顺序连续覆盖全部元素(笔顺即步序);
+  每步至少 1 个元素——"只说不画"的验证步(倒着数回来核对)要挂一条文字才成立
+- `pauseAfter` 默认每步 `true`(气口:孩子点一下才继续)
+- 单笔时长用 `animateDuration` 字段(毫秒),经验值:主笔画 600–1400,小元素 200–450
+- 笔顺里还可以放两种**动作**(和画一笔一样进 steps、占时间,只是不画东西;不用写 x / y):
+  `{ type: 'erase', id, targets: [...] }` 擦掉前面画过的几样(经验 800–1400);
+  `{ type: 'board', id, background? }` 换一块画板(经验 1200–1800)。类型 `ChalkErase` / `ChalkBoard`,
+  check 查:只能擦前面画过、还在这块板上的;第一笔不能是 board(第一块画板的背景图写在场景的 background 上)
+- 重复图形写辅助函数(小人、成排圆圈、划掉斜线),坐标尽量用算式不用魔数;辅助函数暂时写在各自文件里
+- 场景 TS 从同名说明文件 `scenes/<id>.md` 来(格式在 chalk-teaching):`steps[].line` **逐字抄**它的讲稿;
+  文件头注释写题面、表征、假设与参考的范例
+
+## 给画面上的东西起名字(groups、label)
+
+孩子看课时会停下来圈一处,应用要说出他圈的是什么。不起名字,只能说「第 1 步画的 3 条线」;起了名字,就能说「散的 3 根小棒」。
+
+- 合起来是一样东西的几笔,写一个分组:`groups: [{ id: 'loose', label: '散的 3 根小棒', elementIds: ['s-1', 's-2', 's-3'] }]`
+- label 用讲稿里的说法,孩子听到的和老师说的是一个词。
+- 一个元素可以在几组里(「一捆 10 根」「13 根小棒」);圈住哪一组的大半,就说哪一组。
+- 单独一笔有自己的意思(圈出答案的红圈、划掉的斜线),写在元素上:`label: '圈出剩下的 2 根'`。
+- 文字不用起名字,应用说的就是字本身。
+- 只是名字,不改画法、不改笔顺;`cotutor chalk check` 查分组的 id 不重、成员都在。
+
+## 试卷式布局(自上而下)
+
+像试卷:**页宽固定(~720),高度随内容长**,说明文件的段落自上而下一段接一段,段间留呼吸(≥24)。
+草稿段(图)排布自由;作答段像书写行——左对齐、一行一句、字号一致,放在它对应的草稿段下方。
+元素可选打 `customData: { role: 'draft' | 'answer' }`(协议只认领 `layer`,其余透传,零引擎改动)方便 verify 数;
+不打不算错,check 不管。
+**引擎现状**:播放器按整场包围盒等比缩放、不跟笔滚动——所以高度先控制在一屏内(约 ≤350,两三段);
+更长的题拆成多个场景,或等 CLI 仓做完"按宽缩放 + 跟笔滚动"(camera-free 的收窄定义,见 teaching 讲解模板三档)。
+
+## 背景图(在原题照片上圈画)
+
+场景可选 `background: { src, width, height }`:一张图垫在笔迹底下(题目原图、课本照片)。
+`src` 相对场景文件,`cotutor chalk build` 把图拷进课包(`background.<ext>`);`width` / `height` 是图片像素。
+**有背景图时画板 = 图片**:场景坐标 (0,0)–(width,height) 就是图片像素,圈、下划线直接按像素量;
+画到图外的笔迹会被裁掉(check 报 `background-bounds` 警告)。图片上要圈的字贴边时,先给图片补边再量。
+荧光笔 = 矩形 `fillStyle: 'solid'` + `opacity: 45`(半透明,底下的字还看得清)。
+读题用背景图、做题换白板:做题那段前面放一个 `{ type: 'board', id: 'clean' }`,之后照白板的坐标写
+(新板的视口按它上面的东西自己算,不用缩放、不用避开照片的坐标)。下一页还是照片就写 `background`。
+每块画板各自查重叠、出界;擦掉以后在同一处写的字不算重叠。
+
+## 布局经验
+
+- 页宽 ~640–760(试卷式取 720)、高 ~250–350(引擎跟笔滚动前);干扰项分行隔离;答案在作答段(下方);
+  竖的东西(楼、竖式)把说明文字放右侧把画面拉宽
+- 要圈算式里的一个数,把它拆成单独的 text 元素(如 `'27 + 4 ='` 与 `'31'`),间距 ≥22;
+  "括号留空后来填"等标准小件的写法见 chalk-teaching
+- 用色是政策不是几何,单一真相在 chalk-teaching「用色」,同一批课包里保持一致
+
+## 数量与画面(经验值,画面宽约 700–760)
+
+- 被计数的对象一行 ≤18 个用直径 26、列距 40 很舒服(圈还能留边);≤25 个用直径 22、列距 28 勉强;
+  干扰项可以更小(16 / 22)到 30 个一行。**超过 20 个且不需要逐个数 → 线段图**。
+- 要在一行中间"停圈"(圈住前 k 个),列间空隙 ≥14px,否则圈尖必蹭到第 k+1 个。
+- 圈的几何:椭圆要装下一排圆,高度约 ≥3.5× 圆径;圈矩形区域时半轴 = 半边 × √2 + 留边;
+  椭圆越长两端越尖,粗略"每多 3 个对象 padX +4"。圈要么完整落在容器里(≥8px),要么完整穿出去(≥8px),别贴边。
+  名字/标签与圈顶留 ≥12px。
+- 捆怎么画最省元素:不拆的捆 = 竖长矩形 + hachure + 标 10(2 元素);要拆开从里面减的捆 =
+  方框 + 10 根可见小棒 + 标 10(12 元素,方框上下留 ≥24 给后面的圈);新捆成的一捆 = 红色矩形框圈 10 根 + 标 10。
+
+## 渲染事实(不算错,先知道)
+
+- `dashed` 短于 ~50px 只剩两段;涂色会盖住同位置先画的线;字幕超 ~38 个汉字折行;
+  播放器按整场包围盒定比例,前几步画面偏空是设计使然(试卷式的"按宽缩放"待引擎)
+
+## 种子与真题参考
+
+- 本包里的完整例子:`grades/grade-2/examples/2026-10-27-pingjunfen.ts`(平均分,实物分组);
+  更早的种子场景 `dengche.ts`(时间数轴)、`zuqiu.ts`(实物图 + 辅助函数写法)、`bimoduo.ts`(比多少变体:对齐 + 虚线一一对应)
+  留在已归档的 drawtell 仓 `scenes/`
+- 第一批真题跑过 12 个场景(排队点阵、线段图、凑十、破十、小棒进位、数列分行、爬楼),
+  下面的经验都是从那一批里长出来的

package/skills/chalk-teaching/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: chalk-teaching
+description: 做课包的教学知识领域:这道题怎么讲。说明文件格式(references/说明文件.md:每步 讲稿 · 草稿 · 作答 · 检验点)、草稿 / 作答两种段落、画布词汇表(动作 → 引擎写法)、表征库(models/ 一种草稿画法一文件 + models-index.md 索引;文件名即表征名)、讲解模板三档、讲法设计原则、讲稿套路、用色政策、表征准入。写说明文件、挑表征、设计讲法、写讲稿、定用色时读。不是:家长的个人口径(由调用方在转交单 / 上下文里给,优先于本 skill 缺省)、场景怎么写(→ chalk-scene)、工具怎么跑(→ chalk-cli)。不拥有交付物,由调用方按需加载。
+---
+
+# 讲解知识
+
+讲法先落成**说明文件**(`scenes/<id>.md`,格式见 [references/说明文件.md](references/说明文件.md)),再写坐标。
+草稿画法(**表征**:点阵、线段图、数轴、小棒、分解式……)是有限集,一表征一文件在 `models/`;
+库里有现成骨架就照骨架讲——数学正确性与笔顺跟着骨架走,比自由发挥稳;没有就按知识点 + 范例 + 画布词汇自己设计,
+说明文件标 `表征: ★新`,不停下来问。
+
+## 查什么读哪
+
+| 想… | 读 |
+|---|---|
+| 写说明文件(格式、两种段落、给家长看一眼) | `references/说明文件.md` |
+| 按知识点 / 题面挑表征 | `models-index.md`(先看转交单的讲法要点与同知识点已验收的课包) |
+| 读一种表征的完整骨架 | `models/<名>.md` |
+| 选模板档(paper-strict / camera-free / motion) | `references/讲解模板三档.md` |
+| 圈的几何余量、数量上限、画得下画不下 | chalk-scene 的「数量与画面」 |
+
+## 画布词汇表(动作优先从这里选)
+
+添画 · 划掉(=减)· 圈起来(=聚焦)· 连箭头 · 分行(=分类)· 虚线 · 涂色 · 擦掉(橡皮)
+
+引擎里的对应写法(第一批真题验证过):
+
+- **涂色** = 元素加 `backgroundColor` + `fillStyle: 'hachure'`(斜线填充),能画能播;标记"第几个人"、"多出的一段"都用它
+- **圈起来**:椭圆或**矩形**都算圈。椭圆两端收窄,圈一排对象时要靠高度换余量;
+  要圈"一排里的前 k 个"而右边紧挨着第 k+1 个、或圈的东西本身是排/捆时,矩形圈一次到位(且与"捆 = 矩形"同形)
+- **擦掉** = 笔顺里放一个动作 `{ type: 'erase', id, targets: ['要擦的元素 id'] }`:橡皮在它们上面来回走、它们淡掉,
+  擦完就不在画面上了(圈住了什么也不算它),背景图上也擦得干净。擦掉的东西后面还要用就再画一遍(新 id)。
+  只擦一笔的一部分时,才用老办法:一条沿旧笔迹走的粗线(`strokeWidth` ≥ 12)加 `customData: { tool: 'eraser' }`(纸色盖住)
+- **换一块画板**(读完题换白板做题、一道题换下一页)= 动作 `{ type: 'board', id }`(可带新的 `background`):
+  旧板上的连背景图一起擦干净,新板自己的坐标、自己的视口——不用拆成两个场景,也不用把做题那段缩放挤进照片的坐标
+- **虚线** `strokeStyle: 'dashed'`;短于 ~50px 只剩两段,像冒号——一一对应的连线要够长、两头都到
+- 涂色会盖住同位置在先画的线条(按顺序叠放),先画的虚线别指望从涂色块里透出来
+
+## 两种段落:草稿与作答
+
+草稿段 = 图,灵活、个性化,用图形表达思路;作答段 = 偏书本答案(算式、答、结论,需要作图的题作图也算)。
+竖向交替,一步可以只有草稿、只有作答或先草稿后作答——是引导不是分区,细则在 `references/说明文件.md`。
+
+## 标准小件
+
+两个反复用到的**标准小件**(没有名字,靠基本元素手搭,写法见种子/工作区场景):
+
+- **分解式**:数下面分出两个数(如 5 → 3、2):两条短 line + 两个 text;凑十/破十都要
+- **括号留空后来填**:"( )" 拆成两个 text(左括号、右括号)留出空位,答案填进去时才不会触发 check 的 text-overlap
+
+## 讲法设计原则
+
+- 先写说明文件,再写坐标。缺省 3–6 步(数列分行这类可到 7)——步多了孩子跟不上,少了一步塞两件事;
+  每步一个想法、一句讲稿,可有草稿、作答两拍
+- 讲稿短句、面向孩子、讲到什么画什么;讲稿说"从右边起"就真的从右往左落笔——批内笔顺跟着讲稿的方向走
+- 数学正确性优先于画面好看;讲法以"孩子看完能在纸上照着画"为目标(paper-strict 的初衷)
+- 画面本身也会教错东西:楼画成一格一格的、"1 楼"标在格子里,孩子就会把"到 3 楼"数成 3 层——
+  先想"这张图会不会被读成别的意思",再想好看
+
+## 用色(政策,单一真相)
+
+主笔迹 `#1e1e1e`,强调红 `#e03131`,划掉橙 `#e8590c`;红用在讲稿强调处、橙 = 划掉,不出现无来由的颜色。
+搬移箭头、"新添的"对象用什么色还没定(家长政策),同一批课包里保持一致。
+
+## 讲稿套路(各模型通用)
+
+- 每步一句,短句,直接对孩子说;先说动作再说含义("划掉 5 个——送出去的就不是他的了")
+- 数数环节让孩子跟着数("1、2……9"),这是接力交互的钩子
+- 最后一段通常是作答:算式、答写在作答段;草稿里圈出答案可选(缺省圈,家长口径可改)
+- 涉及"我 / 某人自己"的排队类,必有一句"别忘了他自己 / 他被数了两次"
+- 应用题按册子习惯把算式写进作答段;算式是单独一步还是并进末步,同一批课包里保持一致(家长定)
+- 讲稿超过一行(~38 个汉字)字幕会折行,尽量控制在一行内;换行会把"数字 + 量词"拆开
+- 一升二读不了字幕,讲稿就是孩子听到的全部;每句 TTS 约 3 字/秒,一步 10 秒左右为宜。
+  dub 报"拉伸超过 5 倍"说明这步讲稿太长或画得太少——回讲法层修(讲稿拆步、多画几笔),别指望时钟
+
+## 表征怎么进库(当前做法)
+
+生成时遇到库里没有合适表征的题:**不停**,按知识点 + 画布词汇 + 邻近范例自己设计草稿,说明文件 `表征: ★新`,
+给家长看时点明。家长认可(验收通过,或纸上手绘验证)后再进库:`models/<名>.md`(适用知识点 / 画法骨架 / 已验收范例)
++ `models-index.md` 一行;文件名就是表征名。
+第一批真题(一升二暑假每日一练 12 题)一次就进了 8 个——表征库主要靠真题批量长出来,不靠预先设计。

package/skills/chalk-teaching/models//344/272/244/351/224/231/346/225/260/345/210/227/345/210/206/350/241/214.md

@@ -0,0 +1,8 @@
+# 交错数列·分行
+
+- **适用知识点**:找规律(数列)
+- **常见题型**:两串数交错的找规律
+- **画法骨架**:原数列抄一行 → 隔一个圈一个 → 单数位抄第二行、与原行同列对齐,相邻连箭头标差、填空 →
+  双数位抄第三行同法 → 写回括号 + 圈答案句。用下一个已知数验算("再少 2 正好是 3,对上了")
+  是天然的接力钩子
+- **已验收范例**:✓ 真题:15、11、13、13、11、15…;单条等差数列 = 去掉分行的退化版

package/skills/chalk-teaching/models//345/207/221/345/215/201.md

@@ -0,0 +1,7 @@
+# 凑十
+
+- **适用知识点**:20 以内进位加法
+- **常见题型**:20 以内进位加
+- **画法骨架**:大数一行、小数一行对齐 → 从小数行划掉 k 个 + 箭头 + 大数行添画 k 个("搬"去凑十)→
+  圈满十标 10 + 写分解式 → 先算 N+k=10、再算 10+r → 圈答案
+- **已验收范例**:✓ 真题:7+5

package/skills/chalk-teaching/models//345/221/250/346/234/237/350/247/204/345/276/213.md

@@ -0,0 +1,6 @@
+# 周期规律
+
+- **适用知识点**:找规律(图形)
+- **常见题型**:一组一组重复的找规律(如花朵图)
+- **画法骨架(草案)**:一组一组圈,数一组几个
+- **已验收范例**:无——骨架未验证;生成时可按草案自由设计,说明文件标 `表征: ★新`,家长认可后按 SKILL.md「表征怎么进库」补骨架

package/skills/chalk-teaching/models//345/256/236/347/211/251/345/233/276-/345/242/236/345/207/217.md

@@ -0,0 +1,6 @@
+# 实物图·增减
+
+- **适用知识点**:10 / 20 以内加减的应用
+- **常见题型**:数量增减、送给/买来/吃掉、干扰项
+- **画法骨架**:分行画物(干扰项另起一行)→ 减 = 划掉 + 箭头、增 = 添画 → 圈出答案数一遍 → 写算式
+- **已验收范例**:✓ 种子:足球(`scenes/zuqiu.ts`);真题:苹果还剩几个

package/skills/chalk-teaching/models//345/256/236/347/211/251/345/233/276-/346/257/224/345/244/232/345/260/221-/346/261/202/345/244/247/346/225/260/346/261/202/345/260/217/346/225/260.md

@@ -0,0 +1,7 @@
+# 实物图·比多少·求大数 / 求小数
+
+- **适用知识点**:比多少(求大数 / 求小数)
+- **常见题型**:乙比甲多 n,乙有几 / 少 n
+- **画法骨架**:小数一行 → 大数另起一行先画"和它一样多的"(同列)→ 虚线一一对应 →
+  再添画多出的 n 个(求小数则划掉 n 个)→ 圈全部数一遍
+- **已验收范例**:✓ 真题:鸭有几只(13+12)

package/skills/chalk-teaching/models//345/256/236/347/211/251/345/233/276-/346/257/224/345/244/232/345/260/221-/346/261/202/345/267/256.md

@@ -0,0 +1,6 @@
+# 实物图·比多少·求差
+
+- **适用知识点**:比多少(求差)
+- **常见题型**:甲比乙多几
+- **画法骨架**:两行**对齐**(同列同 x)→ 虚线一一对应 → 圈出没对上的
+- **已验收范例**:✓ 种子:铅笔比多少(`scenes/bimoduo.ts`)

package/skills/chalk-teaching/models//345/260/217/346/243/222/350/277/233/344/275/215/345/212/240.md

@@ -0,0 +1,7 @@
+# 小棒进位加
+
+- **适用知识点**:100 以内加法(进位)
+- **常见题型**:两位数加一位数进位(27+4、38+5…)
+- **画法骨架**:捆(竖长矩形 + hachure 涂色 + 标 10)与散棒画出被加数 → 添画加数的散棒 →
+  散的满十用矩形框圈成新捆、标 10 → 写"先算个位、再算整十"→ 圈答案
+- **已验收范例**:✓ 真题:27+4

package/skills/chalk-teaching/models//345/260/217/346/243/222/351/200/200/344/275/215/345/207/217.md

@@ -0,0 +1,6 @@
+# 小棒退位减
+
+- **适用知识点**:100 以内减法(退位)
+- **常见题型**:两位数减一位数退位(32−5)
+- **画法骨架(草案)**:小棒进位加的捆画法 + 破十的拆捆划掉
+- **已验收范例**:无——骨架未验证;生成时可按草案自由设计,说明文件标 `表征: ★新`,家长认可后按 SKILL.md「表征怎么进库」补骨架

package/skills/chalk-teaching/models//346/216/222/351/230/237/347/202/271/351/230/265.md

@@ -0,0 +1,7 @@
+# 排队点阵
+
+- **适用知识点**:20 以内加减、数数
+- **常见题型**:前 m 后 n 求总数;左数第 a 右数第 b 求总数或中间人数;报数
+- **画法骨架**:一行小圆代表人 → 先画锚点人(涂色 + 名字)→ 按题意往两侧添画、边画边数 →
+  圈全部(或目标段)数一遍写答案 → 单独一步写算式,红字点破"锚点人只数一次(+1 / −1)"
+- **已验收范例**:✓ 真题 4 题:两人之间几人、前 4 后 4、左 4 右 8、正 7 倒 9

package/skills/chalk-teaching/models//346/227/266/351/227/264/346/225/260/350/275/264.md

@@ -0,0 +1,6 @@
+# 时间数轴
+
+- **适用知识点**:认识钟表、时间的计算
+- **常见题型**:时刻与时长、班次间隔
+- **画法骨架**:画轴 → 标已知时刻 → 添画推算出的时刻 → 圈出目标区间,数格
+- **已验收范例**:✓ 种子:等车(`scenes/dengche.ts`)

package/skills/chalk-teaching/models//346/245/274/345/261/202/351/227/264/351/232/224/345/233/276.md

@@ -0,0 +1,7 @@
+# 楼层(间隔)图
+
+- **适用知识点**:间隔问题(数数)
+- **常见题型**:爬楼、锯木头、植树、敲钟等"间隔"题
+- **画法骨架**:楼是线、层是段:两面墙 + 楼线自下而上标 1 楼…→ 每人一列箭头逐段数(每段标层数)→
+  推另一人层数 → 停在哪条线 → 圈楼标写答案。与时间数轴同构(刻度 = 楼,间隔 = 层)
+- **已验收范例**:✓ 真题:爬楼(小宏 3 楼爸爸几楼)

package/skills/chalk-teaching/models//347/240/264/345/215/201.md

@@ -0,0 +1,7 @@
+# 破十
+
+- **适用知识点**:20 以内退位减法
+- **常见题型**:20 以内退位减
+- **画法骨架**:十几画成"方框 10 根 + 散的几根"(标 10、标几)→ 散的不够减,拆开这捆:
+  框内划掉 n 根、写 10−n → 框内剩的圈起来标数、散的圈起来 → 写 (10−n)+几 → 圈答案
+- **已验收范例**:✓ 真题:12−7

package/skills/chalk-teaching/models//347/253/226/345/274/217/351/200/200/344/275/215.md

@@ -0,0 +1,6 @@
+# 竖式退位
+
+- **适用知识点**:100 以内减法(退位)
+- **常见题型**:两位数减两位数
+- **画法骨架(草案)**:竖式逐位写,退位标记用划掉 + 小字
+- **已验收范例**:无——骨架未验证;生成时可按草案自由设计,说明文件标 `表征: ★新`,家长认可后按 SKILL.md「表征怎么进库」补骨架

package/skills/chalk-teaching/models//347/272/277/346/256/265/345/233/276.md

@@ -0,0 +1,7 @@
+# 线段图
+
+- **适用知识点**:100 以内加减的应用;两步应用题
+- **常见题型**:数 >20 的比多少;两步"先求另一个再求和/差"
+- **画法骨架**:一人一条纸带,左端对齐 → 长出的一段虚线隔开 + 涂色标差 → 先求另一段写进条里 →
+  圈两条求和,算式写右侧
+- **已验收范例**:✓ 真题:姐妹做花(32、比多 8、一共)

package/skills/chalk-teaching/models-index.md

@@ -0,0 +1,24 @@
+# 表征库索引
+
+一种草稿画法一文件(`models/<名>.md`:适用知识点 / 画法骨架 / 已验收范例);文件名即表征名。
+挑表征的顺序:同知识点已验收的范例(说明文件 + 课包)→ 题面 → 本表。库里没有合适的:自己设计,说明文件标 `表征: ★新`,
+不停下来问(准入见 SKILL.md「表征怎么进库」)。
+
+| 表征 | 适用知识点 | 常见题型 | 学段 | 状态 |
+|---|---|---|---|---|
+| [实物图·增减](models/实物图-增减.md) | 10 / 20 以内加减的应用 | 数量增减、送给/买来/吃掉、干扰项 | 一二年级 | ✓ 已验证 |
+| [实物图·比多少·求差](models/实物图-比多少-求差.md) | 比多少(求差) | 甲比乙多几 | 一二年级 | ✓ 已验证 |
+| [实物图·比多少·求大数 / 求小数](models/实物图-比多少-求大数求小数.md) | 比多少(求大数 / 求小数) | 乙比甲多 n,乙有几 / 少 n | 一二年级 | ✓ 已验证 |
+| [线段图](models/线段图.md) | 100 以内加减的应用;两步应用题 | 数 >20 的比多少;"先求另一个再求和/差" | 一二年级起,通用 | ✓ 已验证 |
+| [排队点阵](models/排队点阵.md) | 20 以内加减、数数 | 前 m 后 n;左数第 a 右数第 b;报数 | 一二年级 | ✓ 已验证 |
+| [时间数轴](models/时间数轴.md) | 认识钟表、时间的计算 | 时刻与时长、班次间隔 | 一二年级起,通用 | ✓ 已验证 |
+| [楼层(间隔)图](models/楼层间隔图.md) | 间隔问题(数数) | 爬楼、锯木头、植树、敲钟 | 一二年级 | ✓ 已验证 |
+| [凑十](models/凑十.md) | 20 以内进位加法 | 9 加几、8 加几… | 一年级 | ✓ 已验证 |
+| [破十](models/破十.md) | 20 以内退位减法 | 十几减几 | 一年级 | ✓ 已验证 |
+| [小棒进位加](models/小棒进位加.md) | 100 以内加法(进位) | 两位数加一位数进位(27+4、38+5…) | 一年级 | ✓ 已验证 |
+| [交错数列·分行](models/交错数列分行.md) | 找规律(数列) | 两串数交错;单条等差数列 | 一二年级 | ✓ 已验证 |
+| [竖式退位](models/竖式退位.md) | 100 以内减法(退位) | 两位数减两位数 | 二年级 | 骨架未验证 |
+| [小棒退位减](models/小棒退位减.md) | 100 以内减法(退位) | 两位数减一位数退位(32−5) | 一年级 | 骨架未验证 |
+| [周期规律](models/周期规律.md) | 找规律(图形) | 一组一组重复(如花朵图) | 一年级 | 骨架未验证 |
+
+知识点列写教材单元名(与教材目录的单元标题一致,如「100以内数的认识」),一个表征可对多个知识点;学段是缺省值,以大纲为准。

package/skills/chalk-teaching/references//350/256/262/350/247/243/346/250/241/346/235/277/344/270/211/346/241/243.md

@@ -0,0 +1,32 @@
+# 讲解模板三档
+
+本文件是这三档的单一真相。
+"纸上可复现"从引擎公理降为模板属性;放松的第一选择是镜头,不是元素。
+
+## paper-strict(默认)
+
+纸上合法操作集:**添画、划掉、圈、箭头、分行**(另有虚线、涂色,见画布词汇表)。
+孩子看完能在纸上照着画出来——这是产品灵魂。图的价值在生成过程,不在成品。
+
+## camera-free(试卷式滚动)
+
+2026-09-04 收窄:不做通用运镜,只做**试卷式滚动**——页宽固定、高度随段落长,播放器按宽缩放、跟笔滚动(笔到哪滚到哪);
+**元素仍 append-only**,写法与 paper-strict 完全一样,只是不再受"一屏"限制。缩放(凑近看)不在此档。
+⚠ 引擎尚未实现;实现前一屏装不下的题拆成多个场景。当前 check 只按 paper-strict 的机制约束把关。
+
+## motion(极少数)
+
+移动本身承载语义时才用,如"送给"= 足球移过去。
+默认先用 paper-strict 的替代表达:划掉 + 箭头(种子场景"足球"就是这么讲"送给"的)。
+⚠ 引擎尚未实现元素移动。
+
+## 怎么选
+
+先问"paper-strict 能不能讲清楚"——种子两题都能,预期绝大多数一二年级题都能。
+讲不清是因为"画面装不下"→ camera-free;是因为"语义必须靠移动"→ motion;
+升档时把理由写进场景文件头部注释,方便回看。
+
+## 机制与政策的分界
+
+`template` 枚举、paper-strict 的确定性约束(append-only、笔顺即步序)由 `cotutor chalk check`
+强制——那是机制,在 cotutor 的 src/chalk。本文件只回答"何时用哪档、怎么写"。

package/skills/chalk-teaching/references//350/257/264/346/230/216/346/226/207/344/273/266.md

@@ -0,0 +1,102 @@
+# 说明文件:scenes/<id>.md
+
+一道题的讲法,写给**不懂画课包的人**看的:家长、别的模型、将来的孩子端都能读、能改。它是阶段 1 的产物、阶段 2 的输入、
+verify 的对照物、验收后的范例(最佳实践的单位)。与场景 TS 同名同居:`scenes/<id>.md` ↔ `scenes/<id>.ts`。
+
+## 粒度:画布词汇那一层
+
+写"画一个红色的圈",不写圈的粗细、时长、坐标。允许出现的词:
+
+- 动作:画布词汇表(添画 / 划掉 / 圈 / 箭头 / 分行 / 虚线 / 涂色)+ 写字
+- 对象与数量:"4 个圆""13 个""三个空"
+- 颜色角色:主笔迹 / 强调(红)/ 划掉(橙)——不写色值
+- 相对位置:一行、下一行、左侧、右侧、下方、对齐、同列
+
+**不写**:px、ms、元素 id、椭圆还是矩形、直径列距——那是阶段 2(chalk-scene)的决定。说明文件说"圈住全部 13 个",
+用椭圆还是矩形由几何决定。
+
+## 两种段落:草稿与作答
+
+贴近孩子真实的做题体验:草稿纸上画图想思路,卷子上写答案。
+
+- **草稿段**:图。灵活、个性化,用图形表达思路——点阵、线段、数轴、小棒、划掉、圈,怎么想就怎么画。
+- **作答段**:偏书本里的答案——算式、答、结论文字;需要作图的题(画角、画线段)作图也算作答。像书写行:一行一句。
+
+竖向交替:草稿 → 作答 → 草稿 → 作答……**这是引导,不是分区**:一步可以只有草稿、只有作答,或先草稿后作答;
+不强求每步都分、不强求二者数量对等。多数题的形状是"几步草稿 + 最后一段作答"。
+
+## 形状
+
+```markdown
+---
+id: 2026-08-30-guilv                 # = 场景 id
+tags: [册子/人教数学一下/4, 题型/交错数列分行, 孩子/Ray]   # 知识点(册子/<册>/<节>)必备;题型、孩子可选
+表征: 交错数列分行                    # = models/<名>.md;库里没有合适的写 ★新,并在步里写清自己的画法
+template: paper-strict
+范例: 2026-08-25-xxx                  # 参考过的已验收说明文件(可省)
+假设: []                              # 缺图 / 看不清处的假设,一行一条
+---
+## 题面
+53、50、47、__、__、__
+
+## 步 1
+- 讲稿:先把这串数抄下来:53、50、47,后面三个空要我们填。
+- 草稿:一行抄数列,三个空画短横线
+- 检验:数列 3 个数 + 3 条横线
+
+## 步 2
+- 讲稿:从 53 到 50 少了 3,从 50 到 47 又少了 3——每次都少 3!
+- 草稿:相邻两数之间连弧形箭头,箭头上标「−3」,主笔迹
+- 检验:2 个箭头,标注 −3
+
+## 步 3
+- 讲稿:47 再少 3 是几?减 3 等于 44,填进第一个空。
+- 草稿:第一个空上方写 44(强调红)
+- 检验:第一个空填 44
+
+## 步 4
+- 讲稿:44 再少 3,等于 41,填进第二个空。
+- 草稿:第二个空上方写 41(强调红)
+- 检验:第二个空填 41
+
+## 步 5
+- 讲稿:41 再少 3,等于 38,填进第三个空。
+- 草稿:第三个空上方写 38(强调红)
+- 检验:第三个空填 38
+
+## 步 6
+- 讲稿:圈出三个答案。倒着检查:38 加 3 是 41,加 3 是 44,再加 3 正好回到 47!
+- 草稿:圈出三个答案(强调红)
+- 作答:44、41、38
+- 检验:3 个圈;倒推心算成立
+```
+
+每步:**讲稿**(一句,孩子听到的全部;≤ 38 字为宜)必有;**草稿** / **作答** 至少一栏;**检验**(这一步画完该数出什么:数量、位置、心算)必有。
+
+## 讲稿行是两个文件的 join key
+
+TS 的 `steps[].line` 与说明文件的讲稿**逐字一致**(dub 按行 hash 音频,改一句只重合成一句)。改讲法先改说明文件,再改 TS;
+试跑期靠这条纪律,稳定后 `cotutor chalk check` 会拦。
+
+## 怎么写(阶段 1 该想到的六件事)
+
+按顺序:知识点 → 表征 → 口径 → 历史 → 范例 → 段落。
+
+1. **知识点**(转交单与上下文包的 profile):这题在教什么;孩子已学到哪、哪些工具不能用(没学竖式就别上竖式)。
+2. **表征**:先看同知识点的已验收范例与题面,再翻 `models-index.md`;库里有骨架照骨架,
+   没有就按画布词汇自己设计,frontmatter `表征: ★新`,给家长看时点明"这是新画法"。**不停下来问,不硬套别的骨架。**
+3. **口径**(转交单 why 里的讲法要点、教材那一节的口径):用词、算式写法、忌讳,压倒本 skill 的缺省。
+4. **历史**(转交单里孩子刚才的话、上下文包的 recent):上次错在哪、讲过什么,讲稿里点一句,别重复上次的讲法问题。
+5. **范例**:结构照抄验收过的那份,只换数字与讲稿——比自由发挥稳。范例层空、拿现成的 `.ts` 当结构参考时,
+   **只抄步骤结构与讲稿套路**,代码里的形状与几何(椭圆 / 矩形 / 直径 / 坐标)一个词都不带进说明文件——写回画布词汇「圈住」。
+6. **段落**:哪几步草稿、哪一步作答;检验点带数字。
+
+## 给家长看一眼(对话模式)
+
+直接做课包时,说明文件写完先给家长一条消息:题面一行 + 每步一句讲稿 + 一句"草稿画什么、作答写什么" + "回「好」就画,要改直接说"。
+不带坐标、不带文件名以外的机器词。家长改了任何一句 → 改说明文件后**重呈现**,不直接画(修订 ≠ 确认)。
+应用无人值守跑(如 cotutor 的 scene-maker)不设这道门:一口气写说明文件 + TS,说明文件照样落盘。
+
+## 验收后
+
+家长验收通过(工作区 `reviews.json` accepted)的说明文件就是**范例**:下次同知识点的题先翻它,取最近 2–3 份。不删旧范例——限的是取用数,不是存量。家长点名"这个讲得好"的排前。