cotutor 0.1.0 → 0.3.0

package/skills/cotutor-board/references/README.md

@@ -0,0 +1,38 @@
+# 卡的种类(索引)
+
+每种卡一份协议:是什么、什么时候用 / 别用、写法、例子、反例、孩子看到什么、你会收回什么、状态的形状。讲解前只读需要的那一两张;总表在 ../SKILL.md。机器文件,init / upgrade 刷新。
+
+- **text**(text.md)—— 板上的一段字:定义、结论、公式、一句要记住的话、题面。一张卡一个意思,能独立被指着讲三句。
+  - 用在:给一个概念下定义、放一个公式、写一句要记住的话、写题面(没有选项、不用孩子填)。
+  - 用在:小节标题——只写一行 `# 标题`,板上出一行无底的字,不算卡。
+- **read**(read.md)—— 一行一段、点哪段听哪段的卡:原文、古诗、课文、生词、单词表。每段会在后台配成一段音(你配了音色的话),孩子点了就念。
+  - 用在:要孩子反复听、跟着读的东西——古诗、课文原句、单词(英文后面可以跟中文)。
+  - 用在:超过两行的原文。`text` 卡是给你讲的,这张是给孩子读的。
+- **choice**(choice.md)—— 一道选择题:问题 + 几个选项,答案只有你知道。孩子在舞台里点大按钮选,选了「交给老师」就到你下一轮的上下文包里。
+  - 用在:一节讲完,要孩子回答一个能选的问题;放在这节**末尾**,末句讲稿就是这个问题,停下等孩子。
+  - 用在:选项都短(数字、几个字)最好——短选项会横排成一行胶囊。
+- **image**(image.md)—— 一张图 + 图注:孩子拍的作业、产物里的图、网上的图。
+  - 用在:讲孩子拍来的作业(上下文包 `photos:` 里的路径),指着图讲。
+  - 用在:一张现成的插图能说清的概念。
+- **tianzige**(tianzige.md)—— 田字格:孩子问「这个字怎么写」时用的卡,一到四个汉字,每个字一个格,讲到这张卡时逐笔写一遍,之后孩子点哪个字,哪个字再写一遍。笔顺是现成的数据,不是你写的。
+  - 用在:孩子问「X 怎么写」「X 的笔顺」;讲生字、讲词语时要孩子看清怎么落笔。
+  - 用在:一个词就写一张,`鼓励` 两个字放一张,孩子看得到它们是一个词。
+- **word**(word.md)—— 单词卡:孩子问「X 英语怎么说」、一节里教新词时用的卡。一张卡一个英文单词,写在四线三格里,讲到这张卡时一笔一笔写一遍。卡上没有中文。点开是慢速:慢念,再按自然拼读一段一段慢写。
+  - 用在:孩子问「X 英语怎么说」「X 怎么拼」。
+  - 用在:一节里的新词,一个词一张。
+  - 用在:短词组也行,如 `ice cream`、`T-shirt`。
+- **lecture**(lecture.md)—— 孩子看过的小课堂里的一段,铺满放,带课里原来的声音。上下文包有 `lecture:` 才有课可放。
+  - 用在:孩子问的道理课里讲过。放那一段,别自己再讲一遍。
+  - 用在:孩子画了一处(`marks:`),放画的那一刻所在的一段。
+- **canvas**(canvas.md)—— 孩子自己在上面画的一块板:笔、橡皮、黑红蓝三色、撤销、清空。可以给一幅底图(课包的终帧、几个骨架元素,或孩子刚拍的作业照片)让孩子在上面标画,也可以空白只给题目。「给老师看」会导出一张 png 给你。
+  - 用在:「画一画」「标出来」「圈出来」这类要孩子动手的题:画高、标直角、圈出错的那步。
+  - 用在:一节末尾,末句讲稿就是这个要求。
+  - 用在:上下文包里有 photos 时,把那张照片做底图,让孩子在自己的作业上圈出错的那道、把答案写上去。
+- **paint**(paint.md)—— 孩子说清楚的一个故事,分好幅交给画家,应用画成一张连环画(四幅时 2×2,像练习册)。出题时带上题干和词语宝库,就是一道看图说话题。
+  - 用在:「你说我画」里,孩子把整段连着说过一遍、和你分好幅以后。
+  - 用在:「我来出题」里,词都落到了幅上、题干也定了。
+- **photo**(photo.md)—— 请孩子拍一张照片发给你:看图说话的那幅图、写好的那一页、做完的那道题。
+  - 用在:要看孩子手边的东西(书上的图、作业),请他拍下来发给你。
+  - 用在:孩子写完了、画完了,请他拍给你看。
+- **code**(code.md)—— 原样显示、不念的一块字:代码、要保留缩进与符号的东西。
+  - 用在:教编程时的代码;要孩子一字不差看的东西(竖式、表格)。

package/skills/cotutor-board/references/canvas.md

@@ -0,0 +1,68 @@
+# canvas — 画板
+
+## 是什么
+
+孩子自己在上面画的一块板:笔、橡皮、黑红蓝三色、撤销、清空。可以给一幅底图(课包的终帧、几个骨架元素,或孩子刚拍的作业照片)让孩子在上面标画,也可以空白只给题目。「给老师看」会导出一张 png 给你。
+
+## 什么时候用 / 别用
+
+- 用:「画一画」「标出来」「圈出来」这类要孩子动手的题:画高、标直角、圈出错的那步。
+- 用:一节末尾,末句讲稿就是这个要求。
+- 用:上下文包里有 photos 时,把那张照片做底图,让孩子在自己的作业上圈出错的那道、把答案写上去。
+- 别用:答案是一个数或一个词 → 讲稿里问,孩子开口说;能选的 → `choice`。
+- 别用:一节里放两张画板。
+
+## 写法
+
+- 第一行是底,后面的行是题目。标签后面的词也可以当题目。
+- 底有四种:
+  - 课包 id:那幅图的终帧做底,孩子在上面标画。
+  - 一张图的路径:照 `photos:` 里那样的 `captures/…` 相对路径写,照片做底。
+  - 一段行内骨架 JSON:`{"skeletons":[…]}`,课包场景的元素写法(chalk),不超过 40 个。
+  - 什么底都没有:只写题目,就是空白画板。
+
+## 例子
+
+<!-- expect {"kind":"canvas","props":{"base":null,"prompt":"画一个三角形,标出它的一条高。"}} -->
+```canvas
+画一个三角形,标出它的一条高。
+```
+
+<!-- expect {"kind":"canvas","props":{"base":{"bundle":"2026-09-10-guilv"},"prompt":"把每次少的那个数圈出来。"}} -->
+```canvas
+2026-09-10-guilv
+把每次少的那个数圈出来。
+```
+
+<!-- expect {"kind":"canvas","props":{"base":{"image":"captures/2026-09-14/1620-1.jpg"},"prompt":"把算错的那道圈出来。"}} -->
+```canvas
+captures/2026-09-14/1620-1.jpg
+把算错的那道圈出来。
+```
+
+## 反例
+
+行内骨架不是合法 JSON,解析不成:
+
+<!-- expect {"kind":"text","warning":true} -->
+```canvas
+{"skeletons": [
+```
+
+## 孩子看到什么
+
+紫色卡:题目 + 「点开画一画」(照片做底的,卡上先是那张照片的小图)。点开铺满整屏:顶栏是题目一行和「给老师看」;左边一列七个大钮(笔 / 橡皮 / 黑红蓝 / 撤销 / 清空),最底下是你的小头像;你给的底图是灰的。
+
+他画的时候可以按住你的小头像说话,嘴看着画接一句,不交给你。嘴有时也会主动看着画说一句、问一句。轻点「给老师看」是交画;按住它说话,是画和这句话一起交给你。
+
+交过之后卡上就是孩子画的那张图,锁住了,只能看、不能再画;要他再画,出一张新卡。
+
+## 你会收回什么
+
+`<job>/<n> canvas「题目」 画了 12 笔(红 8、蓝 4),画了约 3 分钟,清空重画过 1 次,清掉的那几版:/…/captures/2026-09-10/1621-2.jpg(用 Read 看),图:/…/conversations/math-tutor/2026-09-10.1620-1.cards/3.png(用 Read 看)`。没清空过就没有那一段。
+
+图是绝对路径,交了画的那轮有 Read,先看图再回;看不了图就靠笔数。他画的时候说过的话在上下文包 `live:` 的 `draw:` 里。
+
+## 状态的形状
+
+`{"ink": [...], "image": "conversations/…/3.png", "cleared": [{"at": …, "from": …, "strokes": 12, "image": "captures/…jpg"}]}` —— 孩子画的元素(画板的 ink 层)、导出的 png 路径(服务端写)、清空过的几版(清空的时刻、那一版第一笔的时刻、几笔、清空前存的图)。

package/skills/cotutor-board/references/choice.md

@@ -0,0 +1,55 @@
+# choice — 选择题
+
+## 是什么
+
+一道选择题:问题 + 几个选项,答案只有你知道。孩子在舞台里点大按钮选,选了「交给老师」就到你下一轮的上下文包里。
+
+## 什么时候用 / 别用
+
+- 用:一节讲完,要孩子回答一个能选的问题;放在这节**末尾**,末句讲稿就是这个问题,停下等孩子。
+- 用:选项都短(数字、几个字)最好——短选项会横排成一行胶囊。
+- 别用:开放的问题(「你觉得为什么?」)→ 直接在讲稿里问,孩子说话答。
+- 别用:一节里放两道选择题;一节一问。
+
+## 写法
+
+第一行是问题,后面每行 `- [ ] 选项`,对的那项写 `- [x]`(标了多个就是多选)。答案孩子看不到。
+
+## 例子
+
+<!-- expect {"kind":"choice","props":{"question":"底 6 厘米、高 4 厘米的三角形,面积是多少?","options":["24 平方厘米","12 平方厘米","10 平方厘米"],"answer":[1]}} -->
+```choice
+底 6 厘米、高 4 厘米的三角形,面积是多少?
+- [ ] 24 平方厘米
+- [x] 12 平方厘米
+- [ ] 10 平方厘米
+```
+
+<!-- expect {"kind":"choice","props":{"options":["苹果","香蕉","西瓜"],"answer":[0,2],"multi":true}} -->
+```choice
+下面哪些是圆的?
+- [x] 苹果
+- [ ] 香蕉
+- [x] 西瓜
+```
+
+## 反例
+
+只有问题没有选项,解析不成,退成一段文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```choice
+只有问题没有选项?
+```
+
+## 孩子看到什么
+
+紫色卡:问题加粗,选项一行一个(都短就横排);卡上永远不画对错。点卡开舞台:大按钮,选一个(多选能选几个)就存下,底部「交给老师」。末句是问句、停下等孩子时,这张卡会自动推到舞台等答。交给老师以后这张卡锁住,改不了、不能再交;要他再选一次,出一张新卡。
+
+## 你会收回什么
+
+孩子选了、交了以后,下一条消息的上下文包 `cards:` 段里一行:`<job>/<n> choice「问题」 选了「B 12 平方厘米」(答案:「B 12 平方厘米」)`。对错由你口头说,卡上不显示。
+
+## 状态的形状
+
+`{"picked": [1]}` —— 选了的下标,按点的顺序;多选可以多个。

package/skills/cotutor-board/references/code.md

@@ -0,0 +1,46 @@
+# code — 代码或原样的文字
+
+## 是什么
+
+原样显示、不念的一块字:代码、要保留缩进与符号的东西。
+
+## 什么时候用 / 别用
+
+- 用:教编程时的代码;要孩子一字不差看的东西(竖式、表格)。
+- 别用:普通的话 → `text`;要念出来的 → `read`。
+
+## 写法
+
+- 围栏标签写语言名(```python),就是代码卡。
+- 不认识的标签,一律当代码卡原样显示,不报错。
+
+## 例子
+
+<!-- expect {"kind":"code","props":{"lang":"python","text":"print(1 + 1)"}} -->
+```python
+print(1 + 1)
+```
+
+<!-- expect {"kind":"code","props":{"lang":null}} -->
+```
+  3 4
++ 1 2
+-----
+  4 6
+```
+
+## 反例
+
+没有——什么都能进代码卡。
+
+## 孩子看到什么
+
+深色卡,等宽字,原样;不念。讲稿的 `[词]` 能落在代码上(下划线)。
+
+## 你会收回什么
+
+没有。
+
+## 状态的形状
+
+没有。

package/skills/cotutor-board/references/image.md

@@ -0,0 +1,52 @@
+# image — 图片
+
+## 是什么
+
+一张图 + 图注:孩子拍的作业、产物里的图、网上的图。
+
+## 什么时候用 / 别用
+
+- 用:讲孩子拍来的作业(上下文包 `photos:` 里的路径),指着图讲。
+- 用:一张现成的插图能说清的概念。
+- 别用:要孩子自己画 → `canvas`。
+- 别用:路径不存在的图(孩子端只会空一块)。
+
+## 写法
+
+- 第一行是图:workspace 里的相对路径,或 http(s) 地址。只认图片后缀。
+- 作业照片照 `photos:` 原样写,如 `captures/2026-09-10/1620-1.jpg`。照片在 workspace,不在 vault。
+- 后面几行是图注。
+
+## 例子
+
+<!-- expect {"kind":"image","props":{"src":"captures/2026-09-10/1620-1.jpg","caption":"你昨天写的这道题,看第二行。"}} -->
+```image
+captures/2026-09-10/1620-1.jpg
+你昨天写的这道题,看第二行。
+```
+
+<!-- expect {"kind":"image","props":{"src":"https://example.com/brain.png"}} -->
+```image
+https://example.com/brain.png
+```
+
+## 反例
+
+不是图片文件,解析不成:
+
+<!-- expect {"kind":"text","warning":true} -->
+```image
+captures/2026-09-10/笔记.md
+```
+
+## 孩子看到什么
+
+白底卡,图铺满、下面一行图注;点开能双指放大看。讲稿的 `[词]` 只能落在图注上。
+
+## 你会收回什么
+
+没有。
+
+## 状态的形状
+
+没有。

package/skills/cotutor-board/references/lecture.md

@@ -0,0 +1,69 @@
+# lecture — 放课里的一段
+
+## 是什么
+
+孩子看过的小课堂里的一段,铺满放,带课里原来的声音。上下文包有 `lecture:` 才有课可放。
+
+## 什么时候用 / 别用
+
+- 用:孩子问的道理课里讲过。放那一段,别自己再讲一遍。
+- 用:孩子画了一处(`marks:`),放画的那一刻所在的一段。
+- 别用:上下文包里没有 `lecture:`。
+- 别用:课里没讲到他问的。这时照常讲解。
+- 别用:一节放两段。只放最要紧的那一段。
+
+## 写法
+
+- 第一行是课的 id 和一段时间,中间空一格。
+- id 照 `lecture.source` 抄,去掉前面的 `bundle ` 或 `video `。
+- 时间照 `lecture.lines` 抄:那一句的起点到下一句的起点,写成 `0:19-0:30`。
+- 只写起点,就放起点那一句。
+- 第二行可以写一句给孩子的话,写在卡上。
+- 讲稿里写 `[[play]]` 锚到它:念完这句,铺满放那一段,接着念下一句。
+- 放完画面停在那一段的末帧,不关。这句之后的话,对着末帧说。
+
+## 例子
+
+<!-- expect {"kind":"lecture","props":{"bundle":"2026-09-18-po13-jian-8","from":19000,"to":30000,"text":"再看一遍拆开那一捆。"}} -->
+```lecture
+2026-09-18-po13-jian-8 0:19-0:30
+再看一遍拆开那一捆。
+```
+
+卡后面的讲稿这样写:
+
+> 你画的就是这一捆。我们回到那里再看一遍。[[play]]
+> 拿走 8 根,这一捆还剩几根?
+
+<!-- expect {"kind":"lecture","props":{"bundle":"2026-09-18-po13-jian-8","from":30000}} -->
+```lecture
+2026-09-18-po13-jian-8 0:30
+```
+
+## 反例
+
+没写课包 id,只写了课名:
+
+<!-- expect {"kind":"text","warning":true} -->
+```lecture
+13减8 0:19-0:30
+```
+
+止写在起前面:
+
+<!-- expect {"kind":"text","warning":true} -->
+```lecture
+2026-09-18-po13-jian-8 0:30-0:19
+```
+
+## 孩子看到什么
+
+卡上是课名、那一段末尾的画面、「0:19–0:30 ▷」。点开是舞台:从那一段的开头放,带课里的声音,下面一条进度条。讲稿念到 `[[play]]` 那句,念完自己铺满放。
+
+## 你会收回什么
+
+`<job>/<n> lecture「…」 看完了这一段(0:19–0:30)` / `还没看完这一段(0:19–0:30)`。
+
+## 状态的形状
+
+`{"done": true}` —— 那一段放完过没有。

package/skills/cotutor-board/references/paint.md

@@ -0,0 +1,77 @@
+# paint — 画图
+
+## 是什么
+
+孩子说清楚的一个故事,分好幅交给画家,应用画成一张连环画(四幅时 2×2,像练习册)。出题时带上题干和词语宝库,就是一道看图说话题。
+
+## 什么时候用 / 别用
+
+- 用:「你说我画」里,孩子把整段连着说过一遍、和你分好幅以后。
+- 用:「我来出题」里,词都落到了幅上、题干也定了。
+- 别用:故事还没说清楚。先接着问,画是奖励。
+- 别用:现成的图 → `image`;要孩子自己画 → `canvas`。
+
+## 写法
+
+- `题:` 题干,出题才写。
+- `词:` 词语宝库,用顿号隔开,出题才写。画不出来的词(突然、终于)也放这里。
+- `角色:` 一行一个,写成「名字:样子、颜色、衣服」。每幅都照这个样子画。孩子说的颜色就用孩子的。
+- 孩子没说样子,只写名字:`角色: 小熊`。
+- `1.` 起一幅一行,一到四幅。每幅只写看得见的:时间和天气、地方、谁、动作、表情、东西。
+- 每幅都写出角色的名字,不用「他」。
+- 不写心里想的、说的话,也不写「羞愧」这种看不见的词:写成「低着头,脸红红的」。
+- 一幅最多三个角色,一幅只画一件事。
+
+## 例子
+
+<!-- expect {"kind":"paint","props":{"panels":["春天的早上,地里。小熊弯着腰把西瓜种子埋进土里;小猴坐在树下吃桃子。","中午,大太阳。小熊提着水壶给小苗浇水;小猴躺在树荫下睡大觉。","夏天,小熊的地里结满大西瓜,小熊抱着一个笑着;小猴的地里只长了草。","小熊推着满满一车西瓜,递给小猴一个;小猴低着头,脸红红的,挠着后脑勺。"],"cast":[{"name":"小熊","look":"棕色,戴黄色草帽,穿绿色背带裤"},{"name":"小猴","look":"黄褐色,穿红背心"}]}} -->
+```paint
+角色: 小熊:棕色,戴黄色草帽,穿绿色背带裤
+角色: 小猴:黄褐色,穿红背心
+1. 春天的早上,地里。小熊弯着腰把西瓜种子埋进土里;小猴坐在树下吃桃子。
+2. 中午,大太阳。小熊提着水壶给小苗浇水;小猴躺在树荫下睡大觉。
+3. 夏天,小熊的地里结满大西瓜,小熊抱着一个笑着;小猴的地里只长了草。
+4. 小熊推着满满一车西瓜,递给小猴一个;小猴低着头,脸红红的,挠着后脑勺。
+```
+
+出题版,带题干和词语宝库:
+
+<!-- expect {"kind":"paint","props":{"ask":"图上画了谁?他们在干什么?结果怎么样?用上下面的词,写几句话。","words":["播种","睡大觉","满满","羞愧"],"panels":["春天的早上,小熊在地里播种;小猴坐在树下吃桃子。","小猴低着头,脸红红的。"]}} -->
+```paint
+题: 图上画了谁?他们在干什么?结果怎么样?用上下面的词,写几句话。
+词: 播种、睡大觉、满满、羞愧
+1. 春天的早上,小熊在地里播种;小猴坐在树下吃桃子。
+2. 小猴低着头,脸红红的。
+```
+
+## 反例
+
+没有分幅,解析不成,会退成一段文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```paint
+小熊和小猴种西瓜,小猴很懒,最后很羞愧。
+```
+
+五幅太多,解析不成:
+
+<!-- expect {"kind":"text","warning":true} -->
+```paint
+1. 早上
+2. 中午
+3. 下午
+4. 晚上
+5. 第二天
+```
+
+## 孩子看到什么
+
+题干一行;画好前是分好的几幅(孩子说的话)和「画家在画」;画好了图淡入,每格左上角一个圆圈数字;下面是词语宝库。点开铺满,能双指放大。`角色:` 不显示。没画成就一直是分好的几幅,孩子端不说没画成。
+
+## 你会收回什么
+
+孩子下一条消息的 `cards:` 里有一行:画好了,或没画成。你看不到图:想知道画得怎样,问孩子「哪里和你想的一样?哪里不一样?」。
+
+## 状态的形状
+
+没有。

package/skills/cotutor-board/references/photo.md

@@ -0,0 +1,61 @@
+# photo — 拍给我看
+
+## 是什么
+
+请孩子拍一张照片发给你:看图说话的那幅图、写好的那一页、做完的那道题。
+
+## 什么时候用 / 别用
+
+- 用:要看孩子手边的东西(书上的图、作业),请他拍下来发给你。
+- 用:孩子写完了、画完了,请他拍给你看。
+- 别用:只要孩子说一句话 → 末句问他就行,不用卡。
+- 别用:给孩子看一张图 → `image`。
+
+## 写法
+
+- 正文一行:要拍什么,最多 30 个字。
+- 放在一节的最后。一节只放一张。
+- 讲稿末句请孩子拍下来发给你。应用不再补提问卡。
+
+## 例子
+
+<!-- expect {"kind":"photo","props":{"text":"看图说话的那幅图"}} -->
+```photo
+看图说话的那幅图
+```
+
+<!-- expect {"kind":"photo","props":{"text":"写好的那一页"}} -->
+```photo
+写好的那一页
+```
+
+## 反例
+
+写了两行,解析不成,退成一段文字(孩子端没有拍照键):
+
+<!-- expect {"kind":"text","warning":true} -->
+```photo
+看图说话的那幅图
+拍正一点,字要清楚
+```
+
+要拍什么写成一大段,同样退成文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```photo
+请你把练习册第二十三页上面那幅小白兔和小灰兔种萝卜的四幅连环画整页拍下来发给我看看
+```
+
+## 孩子看到什么
+
+紫色卡:左边一个相机,右边大字写要拍什么。它在最后一节时,卡下沿写「等你拍…」,旁边「拍照」「相册」两颗按钮;点了进发照片屏(能裁、能圈、能配一句话),发给你。拍来的照片缩在卡下沿,配的话跟在旁边,点照片看大图。
+
+## 你会收回什么
+
+卡上没有状态。孩子拍来的照片随下一条消息到你手里,和他自己拍的作业照片一样:上下文包里有 `photos:` 与 `photoFiles:`,照板书写法的「作业照片」读。他配的话就是这条消息的字;没配就是「(拍了 N 张)」。
+
+孩子没拍、直接说话(「我找不到那幅图」),那句话也写在这张卡下沿。
+
+## 状态的形状
+
+没有。照片在消息里,不在卡上。

package/skills/cotutor-board/references/read.md

@@ -0,0 +1,51 @@
+# read — 点读
+
+## 是什么
+
+一行一段、点哪段听哪段的卡:原文、古诗、课文、生词、单词表。每段会在后台配成一段音(你配了音色的话),孩子点了就念。
+
+## 什么时候用 / 别用
+
+- 用:要孩子反复听、跟着读的东西——古诗、课文原句、单词(英文后面可以跟中文)。
+- 用:超过两行的原文。`text` 卡是给你讲的,这张是给孩子读的。
+- 别用:你自己的解释、结论 → `text`。
+- 别用:一段里塞两句;一段就是孩子一次点的量。
+
+## 写法
+
+一行一段。英文后面可以跟中文(`apple 苹果`),念的时候整段一起念。
+
+## 例子
+
+<!-- expect {"kind":"read","props":{"segments":["床前明月光,疑是地上霜。","举头望明月,低头思故乡。"]}} -->
+```read
+床前明月光,疑是地上霜。
+举头望明月,低头思故乡。
+```
+
+<!-- expect {"kind":"read","props":{"segments":["apple 苹果","banana 香蕉","orange 橘子"]}} -->
+```read
+apple 苹果
+banana 香蕉
+orange 橘子
+```
+
+## 反例
+
+空的点读卡解析不成,会退成一段文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```read
+```
+
+## 孩子看到什么
+
+米色卡,每段一条白底的行;点一条就念那条(你配了音色就是你的声,配音还没生成好时先用浏览器的声),念的时候那条亮起来。讲稿的 `[词]` 落在段上是荧光笔。
+
+## 你会收回什么
+
+没有——点读不记状态(点了哪段不告诉你)。
+
+## 状态的形状
+
+没有。

package/skills/cotutor-board/references/text.md

@@ -0,0 +1,69 @@
+# text — 一段字
+
+## 是什么
+
+板上的一段字:定义、结论、公式、一句要记住的话、题面。一张卡一个意思,能独立被指着讲三句。
+
+## 什么时候用 / 别用
+
+- 用:给一个概念下定义、放一个公式、写一句要记住的话、写题面(没有选项、不用孩子填)。
+- 用:小节标题——只写一行 `# 标题`,板上出一行无底的字,不算卡。
+- 别用:原文、古诗、单词表(超过两行的要念的东西)→ 用 `read`,孩子能点哪段听哪段。
+- 别用:要孩子选、画的 → `choice` / `canvas`;`text` 卡上什么都做不了。要他说的在讲稿里问。
+- 别用:把讲稿写进卡。「第一步:13 的平方是多少」这种是你说的话,写在围栏外面,一行一句。
+
+## 写法
+
+- 围栏标签只写 `text`。
+- 正文第一行以 `# ` 开头,就是这张卡的标题,下面是正文。
+- 只有一行 `# 标题`、没有正文,就是小节标题。
+- 算式写 `text formula`:衬线居中,单独一行。
+- 样子(底色、字号、并不并排)不用管,应用按卡的种类定。
+
+## 例子
+
+<!-- expect {"kind":"text","props":{"title":"认边","text":"两条短边叫直角边,最长的一条叫斜边"}} -->
+```text
+# 认边
+两条短边叫直角边,最长的一条叫斜边
+```
+
+<!-- expect {"kind":"text","props":{"style":"formula","text":"三角形面积 = 底 × 高 ÷ 2"}} -->
+```text formula
+三角形面积 = 底 × 高 ÷ 2
+```
+
+<!-- expect {"kind":"text","props":{"title":"两大类型","heading":true}} -->
+```text
+# 两大类型
+```
+
+## 反例
+
+方括号是讲稿的标注语法,不写在卡里;写了会被剥掉,家长视图多一行提醒:
+
+<!-- expect {"kind":"text","props":{"text":"两条短边叫直角边"},"warning":true} -->
+```text
+两条短边叫[直角边]
+```
+
+要孩子填的,别写成文字卡再跟一行行「= 答案」。正文里有空(`___`、`( )`)时,`= ` 开头的行算答案,孩子看不到,家长视图多一行提醒。能选的出 `choice`;答案是一个词的,请他开口说:
+
+<!-- expect {"kind":"text","props":{"text":"( )穷( )尽,填两个字。\n= 山\n= 水"},"warning":true} -->
+```text
+( )穷( )尽,填两个字。
+= 山
+= 水
+```
+
+## 孩子看到什么
+
+一张带底色的卡:标题一行小字、正文一段;封面是深底大字;公式衬线居中。讲稿念到 `[词]` 时,词在卡上被标注(标题位画圈、正文里的词术语底、公式荧光)。点开只是看清,没有交互。
+
+## 你会收回什么
+
+没有——这种卡没有状态。
+
+## 状态的形状
+
+没有。

package/skills/cotutor-board/references/tianzige.md

@@ -0,0 +1,78 @@
+# tianzige — 田字格
+
+## 是什么
+
+田字格:孩子问「这个字怎么写」时用的卡,一到四个汉字,每个字一个格,讲到这张卡时逐笔写一遍,之后孩子点哪个字,哪个字再写一遍。笔顺是现成的数据,不是你写的。
+
+## 什么时候用 / 别用
+
+- 用:孩子问「X 怎么写」「X 的笔顺」;讲生字、讲词语时要孩子看清怎么落笔。
+- 用:一个词就写一张,`鼓励` 两个字放一张,孩子看得到它们是一个词。
+- 别用:给孩子读的整句、古诗 → `read`。
+- 别用:解释字义、讲来历 → `text`;田字格里只有字,没有别的。
+- 别用:部首、笔画数写进卡里 → 说在讲稿里;笔画数卡上会自己显示,你不用数,也别在讲稿里数。
+
+## 写法
+
+- 第一行是要写的字:一到四个汉字,不要空格、标点。
+- 第二行写拼音:一字一个音节,空格隔开,带声调(`gǔ lì` 或 `gu3 li4`)。
+- 多音字写这句话里的读法,如「长大」写 `zhǎng dà`。
+- 拼音和字数对不上,卡上就只有字,不显示拼音。
+- 同音的词先给:先出这张卡,讲稿里说一句是哪个意思,如「鼓励,就是给人加油打气」。
+- 不先问,也不在末尾问「你说的是……吧」。写错了,孩子会说。
+
+## 例子
+
+<!-- expect {"kind":"tianzige","props":{"chars":"鼓励","pinyin":["gǔ","lì"]}} -->
+```tianzige
+鼓励
+gǔ lì
+```
+
+<!-- expect {"kind":"tianzige","props":{"chars":"长大","pinyin":["zhǎng","dà"]}} -->
+```tianzige
+长大
+zhang3 da4
+```
+
+<!-- expect {"kind":"tianzige","props":{"chars":"鼓","pinyin":["gǔ"]}} -->
+```tianzige
+鼓
+gǔ
+```
+
+## 反例
+
+拼音和字写在同一行,或夹了标点,解析不成,会退成一段文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tianzige
+鼓励 gǔ lì
+```
+
+拼音和字数对不上,卡照常,只是不显示拼音:
+
+<!-- expect {"kind":"tianzige","props":{"chars":"鼓励"},"warning":true} -->
+```tianzige
+鼓励
+gǔlì
+```
+
+超过四个字也解析不成,拆成两张:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tianzige
+画蛇添足画蛇
+```
+
+## 孩子看到什么
+
+白底卡,每个字一个田字格,写了拼音的标在格子上方(像课本);格里先是淡淡的字形;讲到这张卡时一笔一笔写出来,鼓写完再写励,右下角标着几画。之后孩子点哪个格,哪个字再写一遍。没有舞台、没有按钮。数据里没有的字(生僻字)只显示字形、不动。讲稿的 `[词]` 落不到这张卡上,要标注写在别的卡里。
+
+## 你会收回什么
+
+没有——田字格不记状态(点了几遍不告诉你)。
+
+## 状态的形状
+
+没有。