cotutor 0.1.0 → 0.3.0

package/cards/text/card.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/cards/tianzige/card.css

@@ -0,0 +1,17 @@
+/* 田字格(cards/tianzige/card.md):每字一个田字格,讲到时逐笔写,点了再写一遍 */
+.c.c-tianzige { flex-direction:row; flex-wrap:wrap; gap:10px; justify-content:center; align-items:flex-start; }
+.hz { position:relative; width:112px; height:112px; cursor:pointer; -webkit-tap-highlight-color:transparent; }
+.hz svg { display:block; width:100%; height:100%; }
+.hz .grid { stroke:var(--tint-sand-line); stroke-width:6; fill:none; }
+.hz .grid .mid { stroke-dasharray:24 18; }
+.hz .ghost { fill:#d9d5cc; }
+.hz .ghost.done { fill:var(--ink); }
+.hz .ink { stroke:var(--ink); stroke-width:200; fill:none; stroke-linecap:round; stroke-linejoin:round; }
+.hz .n { position:absolute; right:6px; bottom:2px; font-size:11px; color:#8a857c; line-height:1; }
+/* 带拼音的:一字一列,拼音在格子上方,像课本 */
+.hzc { display:flex; flex-direction:column; align-items:center; gap:2px; }
+.hzc .py { font-size:20px; line-height:1.2; color:var(--ink); letter-spacing:.5px; font-family:-apple-system,"Helvetica Neue",Arial,sans-serif; }
+#st-body .hz { width:180px; height:180px; }
+#st-body .hzc .py { font-size:26px; }
+#st-body .hz .n { font-size:13px; }
+@media (max-width: 480px) { .hz { width:96px; height:96px; } .hzc .py { font-size:18px; } }

package/cards/tianzige/card.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
+画蛇添足画蛇
+```
+
+## 孩子看到什么
+
+白底卡,每个字一个田字格,写了拼音的标在格子上方(像课本);格里先是淡淡的字形;讲到这张卡时一笔一笔写出来,鼓写完再写励,右下角标着几画。之后孩子点哪个格,哪个字再写一遍。没有舞台、没有按钮。数据里没有的字(生僻字)只显示字形、不动。讲稿的 `[词]` 落不到这张卡上,要标注写在别的卡里。
+
+## 你会收回什么
+
+没有——田字格不记状态(点了几遍不告诉你)。
+
+## 状态的形状
+
+没有。

package/cards/tutor/card.css

@@ -0,0 +1,66 @@
+/* 老师卡(cards/tutor/card.md):首页上一位老师一张,头像 + 名字 + 竖排的按钮 */
+.c.c-tutor { gap:12px; padding:16px; }
+.c-tutor .tt { display:flex; align-items:center; gap:12px; cursor:pointer; }
+.c-tutor .tt .av { width:64px; height:64px; font-size:30px; }
+.c-tutor .tt .nm { font-size:20px; font-weight:700; }
+.c-tutor .bts { display:flex; flex-direction:column; gap:12px; }
+/* 按钮(原型 B,https://claude.ai/artifact/HhpuLJXvNr94E9PqSNv6tj):大胶囊;孩子看到的字在 .btx */
+.c-tutor .bt { display:flex; align-items:center; gap:14px; width:100%; min-height:64px; padding:10px 20px; border-radius:32px; background:#fff; border:1.5px solid var(--line); color:var(--ink); font-size:20px; font-weight:600; text-align:left; line-height:1.3; }
+.c-tutor .bt:active { transform:scale(.98); }
+.c-tutor .bt .bi { flex:0 0 auto; width:28px; height:28px; display:grid; place-items:center; color:var(--accent); }
+.c-tutor .bt .bi svg { width:26px; height:26px; }
+/* 新话题:头像下面一个学科色大气泡(--sc,页面按老师给);不带尖角 */
+.c-tutor .bt-new { min-height:84px; padding:10px 20px 10px 22px; border:0; border-radius:24px; background:var(--sc, var(--accent)); color:#fff; }
+.c-tutor .bt-new .lb { display:flex; flex-direction:column; gap:2px; min-width:0; }
+.c-tutor .bt-new .btx { font-size:26px; font-weight:700; letter-spacing:1px; }
+.c-tutor .bt-new .ln { font-size:15px; font-weight:400; opacity:.9; }
+.c-tutor .bt-new .bi { margin-left:auto; width:40px; height:40px; color:#fff; }
+.c-tutor .bt-new .bi svg { width:36px; height:36px; }
+/* 新话题旁边的「一直听」:白底、学科色边和麦克风;和新话题并一行,窄了就换行 */
+.c-tutor .nl { display:flex; flex-wrap:wrap; gap:12px; }
+.c-tutor .nl > .bt-new { flex:1 1 260px; width:auto; }
+/* 新话题打头的名字首字:平板横着叠时后面的牌露出来的那一格就是它;右边一道竖线隔开「新话题」 */
+.c-tutor .bt-new .fc { flex:none; width:40px; padding-right:14px; border-right:2px solid rgba(255,255,255,.45); font-size:38px; font-weight:800; line-height:44px; text-align:center; box-sizing:content-box; }
+.c-tutor.off { pointer-events:none; }
+.c-tutor.off .av { filter:grayscale(1); opacity:.4; }
+/* 休息:次数用完 / 服务不通,C 的开口朝下(低头);点一下:手指按着时 C 扭一下,松开弹回(弹的那下是 .av 环上的 transition) */
+.c-tutor.off .av .ring circle { transform:rotate(126deg); }
+.c-tutor:active .av .ring circle { transform:rotate(8deg); transition-duration:.08s; }
+.c-tutor.off .nm, .c-tutor.off .bt { color:var(--dim); }
+.c-tutor.off .bt .bi { color:var(--dim); }
+.c-tutor.off .bt-new { background:var(--grey); }
+/* 小课堂:带预览图的海报,图上一个播放键,下面「小课堂 · 课名 · 课长」;挨着的几张收在 .lcs 里,够宽就并排 */
+.c-tutor .lcs { display:grid; grid-template-columns:repeat(auto-fit, minmax(220px, 1fr)); gap:12px; }
+.c-tutor .bt-lecture { flex-direction:column; align-items:stretch; gap:0; min-height:0; padding:0; border-radius:20px; overflow:hidden; }
+.c-tutor .bt-lecture .lp { position:relative; display:block; aspect-ratio:16 / 10; background:#fff3e8; }
+.c-tutor .bt-lecture .lp img, .c-tutor .bt-lecture .lp video { position:absolute; inset:0; width:100%; height:100%; display:block; object-fit:cover; }
+.c-tutor .bt-lecture .lp.nopic img { display:none; }
+.c-tutor .bt-lecture .pl { position:absolute; left:50%; top:50%; width:64px; height:64px; margin:-32px 0 0 -32px; border-radius:50%; background:rgba(255,255,255,.94); color:var(--accent); display:grid; place-items:center; box-shadow:0 4px 14px rgba(0,0,0,.22); }
+.c-tutor .bt-lecture .pl svg { width:28px; height:28px; margin-left:3px; }
+.c-tutor .bt-lecture .lm { display:flex; align-items:center; gap:8px; min-width:0; padding:12px 14px; }
+.c-tutor .bt-lecture .tg { flex:none; padding:2px 8px; border-radius:8px; background:#fdeee4; color:#b8541c; font-size:13px; font-weight:700; }
+.c-tutor .bt-lecture .btx { min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font-size:20px; font-weight:700; }
+.c-tutor .bt-lecture .ln { flex:none; margin-left:auto; font-size:14px; font-weight:400; color:var(--dim); }
+/* 常驻入口:听写、拍照听写、口语课,不经首页发布、一直在这位老师的卡上 */
+.c-tutor .bt-extra { text-decoration:none; color:var(--ink); border-color:var(--tint-sand-line); }
+.c-tutor .bt-extra .lb { display:flex; flex-direction:column; gap:1px; min-width:0; }
+.c-tutor .bt-extra .ln { font-size:14px; font-weight:400; color:var(--dim); }
+.c-tutor .bt-extra .bi { color:#c95a22; }
+/* 拍照听写的图标是一小格:语文田字格「字」、英语四线格「Aa」,右下角学科色的相机 */
+.c-tutor .bt-x-photo .pg { position:relative; flex:none; width:46px; height:46px; margin-right:4px; }
+.c-tutor .bt-x-photo .pg i { position:absolute; inset:0; display:grid; place-items:center; font-style:normal; font-size:28px; line-height:1; color:#c9b48a; border:1.5px solid #c9a660; background:repeating-linear-gradient(to bottom,#e3cc9a 0 3px,transparent 3px 6px) center/1.5px 100% no-repeat,repeating-linear-gradient(to right,#e3cc9a 0 3px,transparent 3px 6px) center/100% 1.5px no-repeat,#fff; }
+.c-tutor .bt-x-photo.en .pg { width:64px; height:40px; }
+.c-tutor .bt-x-photo.en .pg i { font-size:24px; font-family:"Chalkboard SE","Comic Sans MS","Marker Felt",sans-serif; color:#8fa0b2; border-color:#c9d2de; background:linear-gradient(#cdd6e2,#cdd6e2) 0 16%/100% 1.5px no-repeat,linear-gradient(#cdd6e2,#cdd6e2) 0 40%/100% 1.5px no-repeat,linear-gradient(#e39a9a,#e39a9a) 0 66%/100% 2px no-repeat,linear-gradient(#cdd6e2,#cdd6e2) 0 90%/100% 1.5px no-repeat,#fff; }
+/* 口语课:对话气泡「Hi」带相机角标(拍照屏同一个,src/ui/kid/photo-ui.ts 的 .pg.talk) */
+.c-tutor .bt-x-talk .pg { position:relative; flex:none; width:56px; height:42px; margin-right:4px; }
+.c-tutor .bt-x-talk .pg i { position:absolute; inset:0; display:grid; place-items:center; font-style:normal; font-size:22px; font-weight:700; line-height:1; font-family:"Chalkboard SE","Comic Sans MS","Marker Felt",sans-serif; color:var(--sc); border:1.5px solid color-mix(in srgb, var(--sc) 40%, #fff); border-radius:14px 14px 14px 4px; background:#fff; }
+.c-tutor .bt-x-photo .cam, .c-tutor .bt-x-talk .cam { position:absolute; right:-9px; bottom:-8px; width:26px; height:26px; border-radius:50%; background:var(--sc); color:#fff; display:grid; place-items:center; box-shadow:0 0 0 2px #fff; }
+.c-tutor .bt-x-photo .cam svg, .c-tutor .bt-x-talk .cam svg { width:15px; height:15px; }
+/* 听写:一整条,上面一排空格子(几个词几格;英文是四线三格),下面「听写 · 几个词」和「去写」 */
+.c-tutor .bt-x-dictation { flex-direction:column; align-items:stretch; gap:14px; padding:16px; border-radius:20px; background:var(--tint-sand-bg); }
+.c-tutor .bt-x-dictation .dg { display:flex; gap:8px; }
+.c-tutor .bt-x-dictation .dg i { flex:0 1 56px; aspect-ratio:1; border:1.5px solid #d9b97a; background:linear-gradient(var(--tint-sand-line), var(--tint-sand-line)) center / 1px 100% no-repeat, linear-gradient(var(--tint-sand-line), var(--tint-sand-line)) center / 100% 1px no-repeat, #fff; }
+.c-tutor .bt-x-dictation.en .dg i { flex-basis:104px; aspect-ratio:2; background:linear-gradient(to bottom, #fff 32%, var(--tint-sand-line) 32% 34%, #fff 34% 65%, var(--tint-sand-line) 65% 67%, #fff 67%); }
+.c-tutor .bt-x-dictation .dr { display:flex; align-items:center; gap:12px; }
+.c-tutor .bt-x-dictation .btx { font-size:22px; font-weight:700; }
+.c-tutor .bt-x-dictation .go { flex:none; margin-left:auto; height:48px; padding:0 22px; border-radius:24px; background:#c95a22; color:#fff; font-size:18px; font-weight:700; display:grid; place-items:center; }

package/cards/tutor/card.md

@@ -0,0 +1,148 @@
+# tutor — 老师卡
+
+## 是什么
+
+老师卡:首页上一位老师一张,卡上几个按钮,孩子点哪个就带着哪个意思进这位老师——新开一个话题、接着以前的某个话题、说一句开场话让老师照家长备好的讲法讲起来,或者先看一堂做好的小课堂。只用在首页。
+
+## 什么时候用 / 别用
+
+- 用:排首页时,给每位要推荐下一步的老师写一张:预习下一课、接着没讲完的、再练一练。
+- 用:同一位老师有两三件事,写在同一张卡上,一行一个按钮。
+- 别用:在板书里写老师卡 → 板书里退成一段文字;老师之间不互相推荐。
+- 别用:没什么要推荐的老师不必写 → 应用会补一张只有「新话题」的。
+- 别用:同一位老师写两张 → 只认第一张,检查会让你合并。
+
+## 写法
+
+围栏标签 `tutor <老师的键>`(cotutor.json tutors 里的英文名,如 `chinese-tutor`)。正文一行一个按钮,孩子看到的字就是这一行,最多 16 个字,孩子的口吻;最多 4 个按钮。
+
+- 普通的一行 = **开场按钮**:孩子点了,这行字就作为孩子的第一句发给老师,新开一个话题。
+- `接着 <日期> <话题> <孩子看到的字>` = **接着按钮**:接着那天的那个话题(话题 = 那个话题第一条消息的 job,如 `1930-1`,`cotutor show` 与对话索引里都有)。今天的话题就是接着聊;以前的新开一个会话,老师会拿到那个话题最后一节的讲稿与卡。
+- `小课堂 <课包或视频的 id> <孩子看到的字>` = **小课堂按钮**:孩子点了先铺满看这一课(课包 `bundles/<id>/`,或视频 `lectures/<id>/`),看完才能开口;开口那句新开一个话题,老师拿到课的每句原话与孩子看的情况。
+- `activity <名> [孩子看到的字]` = **activity 按钮**:进这位老师的一个 activity(`agents/<老师>/activities/<名>.md`,如你说我画)。字不写就是 activity 的名字。孩子点了和开场按钮一样,新开一个话题,老师照那个 activity 文件带。
+- 小课堂按钮下面可以挂一行 `activity: <名>`:孩子看完课开口那条起,老师照那个 activity 带(参数用缺省)。如看图说话的课,挂 `activity: 看图说话`。
+- activity 按钮下面 `名: 值` 的行是这个 activity 的参数(家长填的),一行一个。有哪些参数、什么类型、能不能空,看那个文件的「## 家长填的」;检查会对。孩子看不到。
+- `讲法: …` 挂在上一个按钮下面,写给老师的:从哪开始、重点是什么、讲到哪收。可以写多行。孩子看不到。
+- `留到: <日期>` 挂在上一个按钮下面:这个按钮留到那天(含那天),过了孩子就看不到。不写就一直留着。
+- `新话题` 不用写,应用永远放第一个。
+
+## 例子
+
+<!-- expect {"kind":"tutor","props":{"tutor":"chinese-tutor","buttons":[{"kind":"start","label":"我要预习小蝌蚪找妈妈","brief":"第 22 课。先带他把 1–3 自然段读顺,重点字 塘、脑、袋"},{"kind":"continue","label":"接着写看图写话","date":"2026-09-16","thread":"1930-1","brief":"上次第二句卡住了,先把他写的两句念给他听"}]}} -->
+```tutor chinese-tutor
+我要预习小蝌蚪找妈妈
+讲法: 第 22 课。先带他把 1–3 自然段读顺,重点字 塘、脑、袋
+接着 2026-09-16 1930-1 接着写看图写话
+讲法: 上次第二句卡住了,先把他写的两句念给他听
+```
+
+小课堂按钮(课包在 `bundles/` 里,或视频在 `lectures/` 里,检查会查):
+
+<!-- expect {"kind":"tutor","props":{"tutor":"math-tutor","buttons":[{"kind":"lecture","label":"13 减 8 怎么拆","bundle":"2026-09-18-po13-jian-8","brief":"他常把 13 当成 1 和 3"}]}} -->
+```tutor math-tutor
+小课堂 2026-09-18-po13-jian-8 13 减 8 怎么拆
+讲法: 他常把 13 当成 1 和 3
+```
+
+小课堂看完接着照 activity 带:
+
+<!-- expect {"kind":"tutor","props":{"tutor":"chinese-tutor","buttons":[{"kind":"lecture","label":"看图说话怎么说","bundle":"2026-10-08-kantu","activity":"看图说话"}]}} -->
+```tutor chinese-tutor
+小课堂 2026-10-08-kantu 看图说话怎么说
+activity: 看图说话
+```
+
+只今天用的开场按钮:
+
+<!-- expect {"kind":"tutor","props":{"tutor":"chinese-tutor","buttons":[{"kind":"start","label":"我要读课文","brief":"第 22 课,读顺 1–3 自然段","until":"2026-10-10"}]}} -->
+```tutor chinese-tutor
+我要读课文
+讲法: 第 22 课,读顺 1–3 自然段
+留到: 2026-10-10
+```
+
+activity 按钮(你说我画;填了「词」就是我来出题):
+
+<!-- expect {"kind":"tutor","props":{"tutor":"chinese-tutor","buttons":[{"kind":"activity","label":"你说我画","activity":"你说我画","params":{}},{"kind":"activity","label":"我来出题","activity":"你说我画","params":{"词":"播种、睡大觉、满满、羞愧"},"brief":"他上周把羞愧说成害羞,落到幅上时问一句"}]}} -->
+```tutor chinese-tutor
+activity 你说我画
+activity 你说我画 我来出题
+词: 播种、睡大觉、满满、羞愧
+讲法: 他上周把羞愧说成害羞,落到幅上时问一句
+```
+
+只要「新话题」的老师,正文空着(也可以不写这张卡):
+
+<!-- expect {"kind":"tutor","props":{"tutor":"english-tutor","buttons":[]}} -->
+```tutor english-tutor
+```
+
+## 反例
+
+按钮的字太长(要跟老师说的话写进了按钮)解析不成,整张卡退成一段文字,检查报「要改」:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor math-tutor
+再练两道退位减法,先让他说怎么想,跨十那一步慢一点
+```
+
+`接着` 没写日期和话题:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor chinese-tutor
+接着 小蝌蚪找妈妈
+```
+
+`小课堂` 后面只写了课名,没写课包 id:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor math-tutor
+小课堂 13减8怎么拆
+```
+
+课包 id 写错(或课包还没做),解析得过,首页检查报「要改」:`bundles/<id>/` 不在或读不出来。
+
+`留到:` 后面写的不是日期:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor chinese-tutor
+我要读课文
+留到: 明天
+```
+
+`activity` 后面没写名字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor chinese-tutor
+activity
+```
+
+`activity:` 挂在开场按钮下面(只能挂在小课堂按钮下面):
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor chinese-tutor
+我要看图说话
+activity: 看图说话
+```
+
+activity 的名字写错、参数写错或少了要填的,解析得过,首页检查报「要改」(对的是那个 activity 文件)。
+
+`讲法:` 前面没有按钮:
+
+<!-- expect {"kind":"text","warning":true} -->
+```tutor chinese-tutor
+讲法: 先读课文
+我要预习小蝌蚪找妈妈
+```
+
+## 孩子看到什么
+
+首页最上面,一位老师一张卡:头像、名字,下面一个学科色大气泡「新话题 · 想问我什么?」,然后是你写的(开场按钮与 activity 按钮是带 ▶ 的大胶囊,接着按钮带 ↻;小课堂是一张带预览图的海报,图上一个播放键,下面写课名与课长)。点开场或接着按钮,老师页打开、按钮上的字立刻发出去,老师接着就讲;点新话题是空白的老师页,等孩子开口。今天从同一个按钮聊过的,在老师页的空白板上接(新话题一个胶囊;activity、小课堂先问接着还是重新开始),不占按钮。今天的条数用完、或服务不通,整张卡变灰。讲法孩子永远看不到。
+
+## 你会收回什么
+
+没有卡上的状态。孩子点了哪个按钮,记在那条消息的 `via` 上(`cotutor home show` 汇总);老师那边,开场与接着按钮的那条消息的上下文包里有 `home:`(按钮的字与讲法),接着以前话题的还有 `continue:`,小课堂看完开口那条还有 `lecture:`(课的每句原话与看的情况);activity 按钮起的话题,每条都有 `activity:`(哪个 activity、家长填的参数、应用算的);那个文件「老师怎么带」一节就是这个话题的系统提示,人设、卡、记忆都是它自己的。
+
+## 状态的形状
+
+没有。

package/cards/word/card.css

@@ -0,0 +1,24 @@
+/* 单词卡(cards/word/card.md):四线三格里一个英文词,讲到时按笔顺写;舞台里分段两色、慢写 */
+.c.c-word { flex-direction:row; flex-wrap:wrap; align-items:center; gap:8px 14px; }
+.c-word .we { font-size:44px; line-height:1; }
+.c-word .wg { flex:0 1 auto; min-width:0; max-width:100%; }
+.c-word .wg svg { display:block; max-width:100%; height:auto; overflow:visible; }
+.c-word .wd-row { margin-left:auto; }
+.wg .grid line { stroke:var(--tint-sand-line); stroke-width:1.2; vector-effect:non-scaling-stroke; }
+.wg .grid .base { stroke:#b0a89a; }
+.wg .hit { fill:transparent; }
+.wg .gh, .wg .ink { fill:none; stroke-width:21; stroke-linecap:round; stroke-linejoin:round; }
+.wg .gh { stroke:#d9d5cc; }
+.wg .lt.done .gh, .wg .ink { stroke:var(--ink); }
+.wg .ft { fill:var(--ink); font-family:"Helvetica Neue",Arial,sans-serif; }
+#st-body .c-word { flex-direction:column; justify-content:center; gap:18px; padding:24px 16px; }
+#st-body .c-word .we { font-size:72px; }
+#st-body .c-word .wd-row { margin-left:0; }
+#st-body .c-word .lt { cursor:pointer; transition:transform .45s ease; }
+#st-body .c-word .gh { transition:stroke .45s; }
+#st-body .c-word .wg:not(.merged) .lt.k1.done .gh, #st-body .c-word .wg:not(.merged) .lt.k1 .ink { stroke:var(--accent); }
+@media (max-width: 480px) { .c-word .we { font-size:36px; } }
+/* 「听」「再听一遍」钮(原来借录音卡的 .rc-pl,录音卡 10-22 删了) */
+.wd-pl { display:inline-flex; align-items:center; gap:6px; height:36px; padding:0 14px; border-radius:18px; background:#ffffff; border:1.5px solid var(--tint-plum-line); color:var(--tint-plum-head); font-size:15px; font-weight:600; white-space:nowrap; }
+.wd-pl svg { width:18px; height:18px; }
+.wd-pl.on { background:var(--tint-plum-bg); border-color:var(--tint-plum-head); }

package/cards/word/card.md

@@ -0,0 +1,91 @@
+# word — 单词卡
+
+## 是什么
+
+单词卡:孩子问「X 英语怎么说」、一节里教新词时用的卡。一张卡一个英文单词,写在四线三格里,讲到这张卡时一笔一笔写一遍。卡上没有中文。点开是慢速:慢念,再按自然拼读一段一段慢写。
+
+## 什么时候用 / 别用
+
+- 用:孩子问「X 英语怎么说」「X 怎么拼」。
+- 用:一节里的新词,一个词一张。
+- 用:短词组也行,如 `ice cream`、`T-shirt`。
+- 别用:一串词一起跟读 → `read`。
+- 别用:句子、课文 → `read`。
+- 别用:中文意思写进卡里 → 说在讲稿里,英文在前、中文在后。
+
+## 写法
+
+- 第一行:emoji 和英文单词,如 `🍎 apple`。
+- 能画出来的东西配一个 emoji。抽象的词(like、the)不用配。
+- 第二行:自然拼读分段,用 `-` 隔开,如 `ap-ple`、`sh-ee-p`。
+- 分段拼起来要和单词一模一样。一个字母一段也行,如 `c-a-t`。
+- 一张卡一个词,最多三个词、16 个字母。
+- 只写字母、空格、撇号和连字符。不写音标,不写中文谐音。
+
+## 例子
+
+<!-- expect {"kind":"word","props":{"word":"apple","chunks":["ap","ple"],"emoji":"🍎"}} -->
+```word
+🍎 apple
+ap-ple
+```
+
+<!-- expect {"kind":"word","props":{"word":"sheep","chunks":["sh","ee","p"],"emoji":"🐑"}} -->
+```word
+🐑 sheep
+sh-ee-p
+```
+
+<!-- expect {"kind":"word","props":{"word":"ice cream","chunks":["ice ","cr","ea","m"],"emoji":"🍦"}} -->
+```word
+🍦 ice cream
+ice cr-ea-m
+```
+
+<!-- expect {"kind":"word","props":{"word":"like"}} -->
+```word
+like
+```
+
+## 反例
+
+写了中文意思,中文会被去掉,卡照常出:
+
+<!-- expect {"kind":"word","props":{"word":"apple","emoji":"🍎"}} -->
+```word
+🍎 apple 苹果
+```
+
+分段拼不回这个词,分段不要了,卡照常出:
+
+<!-- expect {"kind":"word","props":{"word":"apple"}} -->
+```word
+apple
+a-pl
+```
+
+整句写不进一张单词卡,会退成一段文字:
+
+<!-- expect {"kind":"text","warning":true} -->
+```word
+I like apples very much
+```
+
+只有中文也解析不成:
+
+<!-- expect {"kind":"text","warning":true} -->
+```word
+苹果
+```
+
+## 孩子看到什么
+
+卡上是 emoji 和四线三格里的单词,右边一个「听」。讲到这张卡时一笔一笔写一遍。点「听」按正常速度念这个词。点卡打开大的:一边慢念,一边按分段一段一段慢写,两段两个颜色,写完合拢成一个词、颜色退掉,再慢念一遍。孩子点哪一段,那段再慢写一遍。讲稿的 `[apple]` 落在这张卡上,讲到时这张卡亮起来,词上不画荧光。
+
+## 你会收回什么
+
+没有——单词卡不记状态(点了几遍不告诉你)。
+
+## 状态的形状
+
+没有。

package/cards//346/235/277/344/271/246/346/200/216/344/271/210/345/206/231.md

@@ -0,0 +1,159 @@
+<!-- 给人看
+谁读:有脸的老师。生成器(src/board/cards/docs.ts)把这篇和各 cards/<种类>/card.md 的「是什么 / 写法 / 例子」拼成 skills/cotutor-board/SKILL.md;
+     Qwen 运行时把它和老师正文一起放进系统提示;自定义运行时也可放进话题第一条的 <cotutor-board>
+能改:改这篇或 card.md,再跑 pnpm run gen:skills。独占一行的注释生成时剥掉,老师看不到;{{卡的种类}} 那一行由生成器替换;
+     {{有 x y}} 到 {{/有}} 之间的行,这位老师的卡里 x、y 都有才留(cotutor.json tutors.<老师>.cards,《卡片协议.md》「谁拿到哪些卡」)
+改了:tests/cards.test.ts、skills.test,再 cotutor replay 对照(《写提示词.md》§一)
+-->
+
+# 板书怎么写
+
+回复正文就是孩子看到的板书。板书里只有两种东西:你说的话,和板上的卡。
+
+## 普通段落 = 你说的话
+
+- 一行一句。每句会被念出来,显示在字幕行。
+- 所以不写标题、列表、粗体、括号注释。
+- 想强调某个词,用方括号标出来,如「这叫[底]」。那个词要在某张卡上出现。
+- 一句最多标两处,只标这句的重点。板上的重点只有你标的这些。
+- 末句缺省是一句陈述,说完就停。
+- 末句写成问句,孩子就得答你。什么时候问,见守则「答完就停」。
+- 末句是问句,播放器就停下等孩子。
+<!-- 为什么缺省不问:这篇在系统提示里,比守则(话题第一条)分量重;只写「问句就停下等」,老师读成每节都该问(2026-10-19 真跑)。 -->
+- **只有末句会停。** 中间的问句念完,接着念下一句,不等孩子。
+{{有 choice}}
+- 末句这一问能选,就配一张 `choice` 卡。卡在前,问句在后。
+{{/有}}
+- 答案是一个数、一个词,不配卡:孩子开口说。
+<!-- 为什么:孩子在 iPad 上打字难,拼音的声调打不出来。 -->
+- 开放的问题不用配卡。应用会把末句那一问补成板上的一张提问卡,你别自己再写一张。
+{{有 photo}}
+- 要孩子拍照片给你看,在节尾放一张 `photo` 卡,写要拍什么。末句请他拍下来发给你。
+{{/有}}
+
+## 围栏 = 板上的卡
+
+- 围栏的语言标签是卡的种类。正文按那种卡的写法写,见下面「卡的种类」。
+- 卡写在讲它的那句话前面,卡与话交错。
+- 卡上是**名词**:定义、公式、题、图、选项。讲稿是**动词**:你说的话。
+- 别把一句话切成一张卡。
+- 不认识的标签,当代码卡原样显示。
+- 正文写得不对的卡,退成一段文字,孩子端不会报错。
+
+## 一节多长
+
+- 出不出卡,见守则「卡宁缺毋滥」。
+- 出卡的一节 1–3 张卡、3–10 句话。
+- 一张卡至少能指着讲三句;讲不到三句的,别上卡。
+- 一次只讲一个想法,讲完就停。
+- 什么时候问孩子,见守则「答完就停」。
+- 随口问答就一两句话,没有卡。
+- **板书写完就停。** 后面不补总结,不再用工具。孩子看到的是你这轮最后一段话,再补的板书会丢。
+- 板书到第一个「## 」为止,后面的孩子看不到。
+
+## 孩子在卡上做了什么
+
+- 孩子在卡上做的事(选了、填了、画了),下一条消息的上下文包会在 `cards:` 段告诉你。
+- 一张卡一行:卡的编号、种类、标题、做了什么、答案。
+- 孩子只交答案、没说话时,消息正文是「(交了答案,没说话)」。
+- 孩子看到的卡上没有对错,对错由你口头说。
+- 上下文包里的 `focus.card`,是孩子发消息时正开着的那张卡。
+- 每种卡完整的协议(何时用、别用、反例、你会收回什么)在本技能目录的 references/<种类>.md,索引在 references/README.md。
+
+## 一节长什么样
+
+孩子说「三角形面积我不会算」,讲的第一节。卡与话交错,卡在讲它的那句前面,最后一句请他做卡上那道题:
+
+````
+我们拿两个一样的三角形拼一拼。
+
+```text
+# 拼
+把两个一样的三角形倒过来拼在一起,得到一个平行四边形
+```
+
+两个一样的三角形一拼,就是一个[平行四边形],它的底和高没变。
+
+```text formula
+三角形面积 = 底 × 高 ÷ 2
+```
+
+所以三角形的面积就是[底]乘[高],再除以 2。
+
+```choice
+底 6 厘米、高 4 厘米的三角形,面积是多少?
+- [ ] 24 平方厘米
+- [x] 12 平方厘米
+- [ ] 10 平方厘米
+```
+
+你来算算:底 6 厘米、高 4 厘米,面积是多少?
+````
+
+{{有 image}}
+## 作业照片
+
+上下文包里有 `photos:`,就是孩子拍了作业。
+
+两种路径:
+
+- `photos:` 是写在卡上的路径,相对 workspace 根。照原样抄进 `image` 或 `canvas` 卡。
+- `photoFiles:` 是同一批照片的绝对路径,顺序一一对应。**Read 用它**,不用 find,不自己拼。
+
+怎么看:
+
+1. 原图 Read **一次**。认出是哪本、哪页、哪道题、卡在哪。
+2. 照片上半透明的红线是孩子自己圈的,先讲圈住的那道。
+3. 孩子写的字认不清,不裁图、不放大(这轮没有能裁图的工具)。讲稿里请孩子指一下、念出来,或者再拍近一点。
+4. 别为了逐题核对答案,把整页看好几遍。一次只讲一道,其余的轮到了再看。
+<!-- 为什么只读一次、不裁图:每读一张图都是一轮工具调用,孩子在等。
+     2026-09-18 ray 的数学作业照片那轮(math-tutor 2101-3)裁了 5 次图,用了 130 秒、3 毛钱。
+     2026-10-17 起带照片的那轮只给 Read / Grep / Glob,没有 Bash:照片里一句话就能让老师拿 Bash 读写 workspace 外的东西。 -->
+
+怎么讲:
+
+1. 讲稿第一句说出你认出的:哪本、哪页、哪道题。
+2. 第一张卡放作业:`image` 卡引原图(路径照 `photos:` 原样写),或 `text` 卡抄题面。
+3. 一页有好几道,在这张卡后面放一张 `choice`,列出题号问孩子讲哪道。一次只讲一道。
+4. 拍糊了、拍不全、认不出,讲稿里请孩子再拍一张,或指一下。
+{{有 canvas}}
+
+要孩子在作业上圈、写,用 `canvas` 卡,第一行写照片路径。
+{{/有}}
+
+还要知道:
+
+- 孩子发之前可以裁剪、圈画。
+- 消息里的字,是孩子对这几张照片说的话。没说话就是「(拍了 N 张)」。
+- 几张一起来的,多半是同一份作业的几页。
+{{/有}}
+
+## 孩子的画
+
+孩子画了给你看,有两种:
+
+- 交了画板卡:`cards:` 里那张卡的一行写着几笔、画了多久、图的路径。
+- 从左栏的纸上交的:上下文包里有 `drawing:`,说图是 `photos:` 第几张。
+
+怎么看:
+
+1. 图 Read 一次,用 `photoFiles:` 或卡那行里的绝对路径。
+2. 清空重画过的,清掉的那几版也看一眼。
+3. 有 `live:` 的 `draw:`,是他画的时候和嘴说过的话。他说是什么,就是什么。
+
+怎么回:
+
+1. 讲稿第一句说你看见的:颜色、样子、画了多少、画得多用心。
+2. 认不准画的是什么,就问他,别照题目猜。
+3. 接着他画的时候说过的话说,别再问他答过的。
+4. 再回到这一科:把他说的连成一句话,或者对上要学的。
+<!-- 为什么:10-22 探针里照题目猜,把乌云说成山、大浪说成黄河;10-21 晚 Ray 画了 7 分半,最后没人看见。 -->
+
+还要知道:
+
+- 消息里的字,是他按住「给老师看」说的话。没说话就是「(画了一张,没说话)」。
+- 画不评对错。
+
+## 卡的种类
+
+{{卡的种类}}