cotutor 0.2.0 → 0.4.0

package/skills/chalk-verify/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: chalk-verify
+description: 检验课包(逐笔画出的讲解动画)的质量:keyframe 截图逐张对照讲稿评审,输出通过结论或可执行的问题清单(步 / 元素 id / 期望 vs 实际 / 修复建议)。触发:生成后的独立把关、家长验收前的最后一道、改动后的回归检查、"检查这个场景"。不是:修改场景(评审与修改分离,问题清单交回生成方)、教学正确性裁量(那是家长验收)。
+---
+
+# 检验动画质量
+
+输入:场景 TS 路径(`scenes/<id>.ts`)或已 build 的课包 id;同名说明文件 `scenes/<id>.md`(格式见 chalk-teaching)若在,
+它每步的「检验」行就是对照物。评审者应是**另一个上下文**(子 agent 或独立进程)——生成方自己加载本 skill 自评不算独立检验。工作区与命令见 chalk-cli。
+评判清单在本 skill `references/评判标准.md`。
+
+## 流程
+
+1. 输入是 `.ts` 时先 `cotutor chalk check <path> --json`;有 error 直接把 findings
+   整理成问题清单返回,不必截图(层 2–3 的错误截图也救不了)。
+
+2. `cotutor chalk snap <目标> --no-cursor` → `snaps/<id>/`:`step-<n>.png` + `index.json`。
+   `--no-cursor` 不画笔尖,帧里只剩笔迹;不加也行,但要知道笔尖停在本步末笔处,不算画面元素。
+   index.json(v2)的 shots[] 已把每张图和该步讲稿配好对,**并列出该步新增元素**
+   (`added[]`:id / type / strokeColor / backgroundColor / text / bbox)与画板 `board.viewBox`——
+   报问题按 id 说话,数数对着 added 数,越界对着 viewBox 判(bbox 是场景坐标,图像像素 =
+   (坐标 − viewBox 原点) × 图宽 / viewBox 宽)。评审按它走,不要自己翻场景源码猜。
+   换过画板的课每张图带自己的 `viewBox`(按它换算);`added` 里的动作(type `erase` / `board`)没有 bbox,
+   `erases` 列出它擦掉的元素——这一步的图上它们应该已经不在了。
+
+3. **逐张评审**(step-0 是空板配题面,从它开始),参考 `references/评判标准.md` 的视角:
+   - **检验点**(有说明文件时先做):逐步核它的「检验」行——数量、位置、心算;讲稿行与 TS `line` 逐字一致,不一致直接列问题
+   - **对应**:画面是否就是该步讲稿所述,有没有多画、少画、提前画;讲稿里的动作词
+     (数、指、连、划、圈)画面有没有对应笔迹;口头计数"1、2……"不要求画面出数字
+   - **计数**:圈住的、划掉的、添画的对象逐个数,与讲稿和题目里的数字核对;还要核**位置**
+     (涂色的是第几个、圈的是不是第 1、3、5 位)——经验上计数与位置是最常见的错误来源。
+     对象多(≥15)时把图局部放大再数,别凭感觉
+   - **布局**:文字重叠、越界截断(对着 viewBox)、疏密;圈两端是否擦到相邻对象、被圈对象是否完整在圈内;
+     颜色是否用在讲稿强调处;衍生行(数列分行、竖式)与源行是否同列
+   - **板书感**:paper-strict 下效果是否纸上可复现;笔顺是否自然(先主体后标注);
+     强调笔迹应保留到终帧(纸上画了不会消失)
+   - **跨帧一致**:同一场景里"捆/圈/框"只用一种画法、措辞一致;对象状态变了旧标签是留是改;
+     分段标注是"每段"还是"累计"要与讲稿口径一致
+   - **段落**:作答段像书本答案(算式 / 答 / 结论),与前面草稿段的结论一致——判断项,不拦;草稿段自由,不按此挑毛病
+
+4. **输出报告**:
+   - 通过:说明"逐张核对通过",附每步一句话摘要(画了什么、对上哪句讲稿)
+   - 有问题:每条尽量给全——**步 n / 元素 id / 期望 vs 实际 / 修复建议**,
+     让生成方(agent 或人)拿到就能改
+5. 修复后重跑本流程;之后进家长验收。
+
+## 评审经验
+
+- 拿不准就列出来标"存疑",让人裁量,不拦流程
+- 说明文件在时先对它的检验点,再看讲稿:它是生成方承诺的清单,比从讲稿反推省事也更准
+- 不要只看终帧:中间步的"讲到哪画到哪"才是产品灵魂(图的价值在生成过程,不在成品)
+- 教学正确性(这道题该不该这么讲)是家长验收的事;本 skill 聚焦"画得对不对";
+  但讲稿或画面有明显数学错误、讲稿与画面口径不一(讲稿"又走了 1 层"画面标"2 层")要指出
+- 默认分工是评审与修改分离(发现问题交回生成方);试跑期这个分工本身也可以调
+- 定格帧不能看出批内笔顺方向(从右起划还是从左起划);要核对方向就看源码顺序或回放,标明是这样看的
+- 第一批真题(2026-08-17,12 题)里检验方抓到生成方自检漏掉的:半截虚线没连到对象、最右侧文字被裁、
+  两种"捆"画法并存、新添对象没区别色——这几类都是"逐帧看单张"看不出来、要跨帧/跨元素比对的

package/skills/chalk-verify/references//350/257/204/345/210/244/346/240/207/345/207/206.md

@@ -0,0 +1,69 @@
+# 评判标准
+
+chalk-verify 的参考清单(随试跑修订;第一批真题 2026-08-17 后补了不少条)。评审对象:`snaps/<id>/` 的
+keyframe 序列 + index.json 的图↔讲稿对照与每步新增元素清单;同名说明文件 `scenes/<id>.md` 在时,它每步的「检验」行是首要对照物
+(格式见 chalk-teaching `references/说明文件.md`)。一般先过 `cotutor chalk check`,层 2–3 的问题不必进视觉评审。
+
+## 不算问题(渲染事实,先排除)
+
+- 每张图底部一行是当步讲稿字幕(左侧蓝点是气口提示,终帧有绿勾);字幕折行会让帧高不同
+- 未加 `--no-cursor` 时,笔尖图标停在本步末笔处,不是画面元素
+- 播放器按整场包围盒等比缩放,前几步画面偏空
+- 行首标签、算式、"辅助标注"(如"爸爸吃了 4 个")讲稿未必逐句提到,不算多画;但**内容元素**(被数的对象、圈、划痕)必须与讲稿对应
+
+## 视角(1–4 拦,5 只判断)
+
+### 1. 对应(画面 ↔ 讲稿)
+
+- [ ] 有说明文件:该步「检验」行说的数量 / 位置 / 心算逐条成立;讲稿与 TS `line` 逐字一致
+- [ ] 该步新出现的元素(index.json 的 `added[]`),讲稿都提到了或属辅助标注;讲稿提到的动作,画面都发生了
+- [ ] 讲稿含动作词(数、指、连、划、圈、搬)的步,画面有对应可见笔迹;口头计数"1、2……"不要求画面出数字记号
+- [ ] 没有"提前画"(后面步骤的内容出现在当前帧)——对照上一帧核对新增量
+- [ ] step-0 空板只配题面;终帧包含答案文本
+- [ ] 算式出现的步 = 讲稿说出该算式的步;算式必须心算一遍
+
+### 2. 计数与位置(有数字就必须数)
+
+- [ ] 添画的对象数量 = 题目/讲稿的数字
+- [ ] 圈起来的对象:逐个数圈内元素,核对讲稿("圈出没划掉的"→ 圈内不得含划掉的)
+- [ ] 划掉的对象:数划掉记号的数量,且划的是正确的那一批(位置核对);划掉后剩余数 = 下一步讲稿说的剩余数
+- [ ] **位置索引**:涂色/标记的是第几个、圈的是不是第 1、3、5…位,与讲稿一致
+- [ ] 一一对应类:两行对象逐列对齐(容差 ≤2px 或 ≤ 间距 10%);连线**两头都到**(两端距对象几个笔宽内)
+- [ ] 分解式(5 → 3、2)的两个数分别对应画面上"搬走/划掉的"和"剩下的"
+- [ ] 数轴刻度与标签一一对应,时刻推算正确;箭尖停在讲稿所说的线/刻度上;分段标注是"每段"还是"累计",与讲稿口径一致
+- [ ] 同一行"原有 + 添画"没有可见分界时,列为存疑
+
+### 3. 布局
+
+- [ ] 文字互不重叠、不被图形意外遮盖(刻意圈选除外)、不越出画面——越界按 index.json 的 `board.viewBox` 判,
+      不要只看图片边缘(墨迹在边缘被硬裁而背景色延续,肉眼难察觉)
+- [ ] 圈选的对象**完整**落在圈内:椭圆两端垂直空间收窄,边缘对象容易穿出;圈两端与相邻对象/相邻标记
+      ≥ 半个对象间距、上下 ≥ 对象高的 1/3,低于就列存疑(第一批真题里最常见的返工)
+- [ ] 圈与圈、圈与容器不贴边:要么完整在里面(≥8px)要么完整穿出;同色相邻(红圈紧挨红涂色)缩略下会粘连,列存疑
+- [ ] 衍生行与源行同列对齐(数列分行、竖式对位)
+- [ ] 疏密合理:一行之内等距,行与行有呼吸;留白/重心只作存疑,不拦
+- [ ] 颜色与用色政策一致(单一真相在 chalk-teaching「用色」):主笔迹墨色,红 = 讲稿强调处,
+      橙 = 划掉;不出现无来由的颜色;未定政策的(搬移箭头、"新添的"对象)同一场景内保持一致即可
+- [ ] 字幕不被裁切、换行合理(数字与量词不拆开)——字幕不是笔迹但是孩子读的内容
+
+### 4. 板书感(paper-strict)
+
+- [ ] 每个效果都能用铅笔在纸上复现(无渐变、无移动残影、无不可解释的图形)
+- [ ] 笔顺自然:先主体后标注,先轴后刻度,先物后圈
+- [ ] 单帧信息量适合孩子:一步一个新意思,不塞两件事
+- [ ] 强调笔迹保留到终帧(纸上画了不会消失)
+- [ ] 跨帧一致:同一场景里"捆 / 圈 / 框"只用一种画法、讲稿措辞与画法一致;对象状态变了(拆开、划掉)之后旧标签留不留要说得通
+
+### 5. 段落(草稿 / 作答;判断项,不拦)
+
+- [ ] 作答段像书本答案:算式、答、结论(需要作图的题作图也算),一行一句;与前面草稿段的结论一致
+- [ ] 草稿段自由——不按整齐与否挑毛病;只在它与讲稿 / 检验点对不上时才列
+
+## 结论怎么给
+
+- **通过**:各视角没发现问题。报告写"逐张核对通过"+ 每步一句摘要。
+- **有问题**:每条尽量给全:步 n / 元素 id(取自 index.json `added[]`)/ 期望 vs 实际 / 修复建议。
+- **存疑**:近似判断拿不准的(疏密、美感、同色相邻),列出来标"存疑"交人裁量,不拦流程。
+
+教学正确性(该不该这么讲、用词是否合适)不在本清单——那是家长验收的事;
+但明显的数学错误、讲稿与画面口径不一,要指出。

package/skills/cotutor-analyze/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: cotutor-analyze
+description: 在 cotutor workspace 里分析 AI 老师的对话:某一轮传了什么上下文、读了什么文件、为什么没看见档案或日记里的某句、改了老师文件 / 技能 / vault 之后回放对照、一天的 token 与延迟。家长或开发者在 workspace 根开编程助手问「老师为什么…」「这轮读了什么」「我改了 X 效果如何」「今天花了多少」时用。
+---
+
+<!-- 给人看
+谁读:家长在 workspace 根开的编程助手
+能改:机器件,upgrade 覆盖;references/命令与文件.md 由 src/app/skills/analyze-doc.ts 生成
+改了:在试用 workspace 里开编程助手问一句「老师为什么…」(《写提示词.md》§一)
+-->
+
+# 分析老师的对话
+
+你在一个 cotutor workspace 的根目录(有 cotutor.json)。这里的数据是孩子和 AI 老师的对话记录。你的活是**看**和**解释**,不是改。
+
+## 先知道的几件事
+
+- 一轮 = 一条消息 + 老师的回答。
+- 文件都在 conversations/<老师>/,按 `<日期>.<job>.*` 命名,job 形如 1620-1。
+- 索引 `<日期>.json` 一天一份。每条消息物化了讲稿与卡、读了什么(tools)、用时(timing)、token(tokens)、提醒。
+- 各文件是什么、命令怎么用,见 references/命令与文件.md。
+
+**老师看到的只有两样:**
+
+1. 上下文包:run.json 里的 prompt。每一行是什么,见 `.agents/skills/cotutor-tutor/references/上下文包.md`。
+2. 它自己 Read 的文件:消息的 tools。
+
+它看不到 cotutor.json,看不到别的老师,也看不到今天之前的对话。以前的事只有沉淀进 vault 的,它才看得到。
+
+## 禁区
+
+- agents/<name>.md 是老师文件,由 cotutor 读正文传给 Qwen。**不要把它们当子代理派(Task)**,也不要替老师回答孩子。
+- **不改** conversations/、evals/、ledger/ 里的任何文件。
+- **不写 vault**(日记、档案、计划、教材)。那是家长的长期记忆,要改也是家长自己动手。
+- 改老师文件、技能、cotutor.json,要先说清改什么、为什么、会影响哪些老师,得到同意再动。
+
+## 工具箱
+
+都在 workspace 根跑,精确用法在 references/命令与文件.md。
+
+| 想知道 | 跑 | 花钱 |
+|---|---|---|
+| 某一轮的全部:问句、上下文包、当时的老师文件与技能 hash、讲稿、卡、读了什么、token、用时、给家长的尾巴 | `cotutor show <老师> <job> <日期>`(--json 是全量) | 不 |
+| 现在发这句话,老师会看到什么;每段从哪个文件来、那里共几条、截了几条 | `cotutor pack <老师> "<消息>" [--from kid] [--at 时间]` | 不 |
+| 一轮每道工序的时刻:首卡、每句配音、就绪 | `cotutor trace <老师> <job> <日期> [--lane main,tts]` | 不 |
+| 改了老师文件、技能、vault 之后,**同一问答案怎么变** | `cotutor replay <老师> <job> <日期>`,跑完并排打印;`cotutor compare <老师> [evalJob] <日期>` 再看或列 | **是**,花一轮老师的钱(按 token 计),**跑前先问** |
+| 回放那轮自己的全部 | `cotutor show <老师> <evalJob> <日期> --evals` | 不 |
+| workspace 哪里坏了:路径、证书、技能、配置缺口 | `cotutor doctor` | 不(--live 花一分钱) |
+
+一天的 token 与延迟不用命令,读 conversations/<老师>/<日期>.json:
+
+- 每条的 `tokens` 是这轮老师用的 token(`in` 输入,含缓存读;`out` 输出);一天合计自己加。老数据里的 `costUsd` 是 claude 时代记的美元,不用管。
+- `timing` 是从 startedAt 起算的毫秒:`firstReadyMs` 首拍就绪,`doneMs` 老师写完,`dubbedMs` 配音齐。
+
+## 查「老师为什么没提 X」的顺序
+
+1. show 看那轮的上下文包里有没有 X。
+2. 没有:pack 干跑,看现在会不会有;来源里那一段是「读不到」还是「截掉」。
+3. 有:看 tools,它有没有去读、读到多少字。
+4. 都有:就是模型没用上。去看老师文件里那条规则怎么写的。
+
+## 常见问题怎么查
+
+**老师为什么没看见档案、入口文件里那句**
+
+- show 看 prompt 末尾的 `<vault-note>`。
+- 那轮是续聊、YAML 里写「未变」:原文在这个话题的第一条,去看第一条。
+- 不在:pack 看来源。
+  - 「没有 cotutor: profile 的笔记」「没有 subject / semester 的入口文件」:属性没写或写错。学期按档案的 school_start 算;subject 要和 cotutor.json 里这位老师的 subject 一字不差。
+  - 「截到 N」:被 `policyDefaults.contextPack.entryChars` 截了。长的挪到别的笔记,在入口文件里链过去。
+
+**老师为什么不知道上周的观察**
+
+- recent 段只抽最近 14 天日记里、H2 学科匹配的「- 观察:」行。
+- pack 的来源会说有几天的日记、这学科几条。
+- 日记的 H2 得是「## 数学 · 话题名」这种,「- 观察:」在行首。
+
+**这轮读了什么、贵在哪**
+
+- show 的「读了什么」,每条有字数。
+- 贵的一般是:派了子代理、读了大文件、或者轮数多。
+- 真要看它读到的原文,grep 那轮的 .log。
+
+**我改了老师文件,效果怎样**
+
+- 先 show,看原轮的老师文件 hash。
+- 再 replay 一次(先问),看 notes 里 hash 变没变、讲稿与卡的 diff。
+- 同一问什么都不改,回放两次也会不一样(模型抖动)。别把一次的差异当结论,拿不准就再回放一次。
+
+**我改了 vault,效果怎样**
+
+- pack 干跑就够,不花钱:上下文包变了什么,就是效果。
+- 要看老师会不会因此说得不一样,再 replay。
+
+**板上为什么没标重点、底色不对**
+
+- 重点只有老师在讲稿里写的 `[词]`:show 看老师原文里标了没有。
+- 底色、字形按卡的种类定,一行几张按卡的宽度排。老师没写,就是机械规则的样子。
+
+## 报告怎么写
+
+1. 先一句结论。
+2. 再给证据:引 run.json 的 prompt、tools 里的那条、索引里的字段,带文件名。
+3. 最后给改法:改哪个文件、要不要花钱、会影响哪几位老师。
+
+老师的回答是教学,好坏最终由家长判断。你给的是:它看见了什么、没看见什么、为什么。

package/skills/cotutor-analyze/references//345/221/275/344/273/244/344/270/216/346/226/207/344/273/266.md

@@ -0,0 +1,31 @@
+# 命令与文件(机器生成,别改)
+
+## 分析用的命令(在 workspace 根跑;完整用法 cotutor --help)
+
+```
+  cotutor doctor [--workspace <dir>] [--json] [--live]                 逐项体检;--live 真连一次百炼实时模型、真合成一句配音(花一分钱)把 API 层的坑摆出来(真跑老师用 cotutor send)
+  cotutor send <老师> [<消息>] [--from kid|system] [--runtime <名>] [--new] [--photo a.jpg,b.png] [--activity <名> [--param '名=值;名=值']] [--lane main,tts] [--quiet]   终端里发一条,现场按道打印每道工序的事件,说完打印结果(孩子的话照实时写,同孩子端:上下文包带 live:、不补提问卡,只是没有嘴;--from system 不算;--new 开新话题;--photo 带作业照片,拷进 captures/,有照片时消息可以空;--activity 像孩子点了首页的 activity 按钮,新开话题,参数同按钮下面那几行;--quiet 只要结果)
+  cotutor pack <老师> [<消息>] [--from kid|system] [--at <ISO时间>] [--activity <名> [--param '名=值;名=值']] [--json]   干跑上下文包(--activity 看 activity 话题第一条老师拿到什么):不起模型,打印现在会发给老师的那份 + 每段来自哪个文件、那里一共几条、按政策带了几条(改了档案 / 日记 / 计划立刻看效果)
+  cotutor replay <老师> <job> [<日期>] [--runtime <名>] [--json]   回放一轮:同一问按现在的 vault 与提示词再跑一遍(落 evals/,不进孩子的对话、不配音),跑完并排打印上下文包 / 讲稿 / 卡 / 读了什么的 diff
+  cotutor compare <老师> [<evalJob>] [<日期>] [--json]                   再看一次回放的对照(不给 evalJob 就列这天回放过哪些)
+  cotutor show <老师> <job> [<日期>] [--json] [--evals] [--workspace <dir>]   看一轮:问了什么、上下文包、当时的老师文件与技能 hash、讲稿与卡、读了什么、token 与用时、给家长的尾巴;--json 是家长端「看原文」同一份数据,给编程助手分析用
+  cotutor trace <老师> <job> [<日期>] [--lane …] [--workspace <dir>]     回放一轮的事件(<日期>.<job>.events.jsonl;排查昨天那轮用)
+  cotutor rate <老师> <话题> <1-5> [--date <日期>]                       给一个话题打星(与家长端同一条路;≥ vault.keepScore 的话题记账时摘要才进日记)
+  cotutor bookkeep <老师> [--date <日期>] [--thread <话题>]...           记账:这天每个还没记过的话题各起一轮记账任务,老师回「## 记账」,应用写进 vault 的日记(话题名、孩子问、摘要、观察)
+```
+
+## 一轮的文件(conversations/ 下;回放的在 evals/ 下,同一套名字)
+
+job 形如 1620-1(时分-当天序号)。
+
+| 文件 | 是什么 |
+|---|---|
+| `conversations/<老师>/<日期>.json` | 一天的索引:每条消息物化了 text / kidText / section(卡与讲稿)/ tools(读了什么)/ timing / tokens(这轮老师用的 token:输入 / 输出)/ warnings / bookkeeping;顶层 sessions / ratings / booked(老数据里还有 costUsd,是 claude 时代的美元,不用管) |
+| `conversations/<老师>/<日期>.<job>.run.json` | 这轮发给老师的:prompt(上下文包 + 消息)、argv(完整命令行)、resume / session、sources(当时的老师文件正文与 hash、技能 SKILL.md 的 hash) |
+| `conversations/<老师>/<日期>.<job>.log` | 老师进程的 stdout 原样(stream-json):每次 tool_use 的完整参数、tool_result 的内容、文本、result(token、轮数)。最大最全,别整个读,按 job 与关键字 grep |
+| `conversations/<老师>/<日期>.<job>.err.log` | stderr |
+| `conversations/<老师>/<日期>.<job>.events.jsonl` | 这轮的事件流,一行一条 {t, lane, kind, …}:main 老师 / tts 配音 / ready 就绪 / index / ledger;cotutor trace 读它 |
+| `conversations/<老师>/<日期>.<job>.cards/<n>.json` | 第 n 张卡的状态(孩子在卡上做的):{at, turn, state} |
+| `conversations/<老师>/<日期>.<job>.cards/<n>/<k>.mp3` | 卡的资产(点读段配音) |
+
+上下文包里每一行是什么、路径后面的状态怎么看,见 `.agents/skills/cotutor-tutor/references/上下文包.md`;截断的上限是哪个政策旋钮,见 cotutor-tune 的 references/字段.md。

package/skills/cotutor-board/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: cotutor-board
+description: cotutor 的板书怎么写:讲稿一行一句,围栏是卡(种类:text / read / choice / image / tianzige / word / lecture / canvas / paint / photo / code)。应用已经递给老师,老师不用读;家长查阅用。每种卡完整的协议在 references/<种类>.md。机器生成,源在 cotutor 仓的 cards/,别在这里改。
+---
+
+# 板书怎么写
+
+回复正文就是孩子看到的板书。板书里只有两种东西:你说的话,和板上的卡。
+
+## 普通段落 = 你说的话
+
+- 一行一句。每句会被念出来,显示在字幕行。
+- 所以不写标题、列表、粗体、括号注释。
+- 想强调某个词,用方括号标出来,如「这叫[底]」。那个词要在某张卡上出现。
+- 一句最多标两处,只标这句的重点。板上的重点只有你标的这些。
+- 末句缺省是一句陈述,说完就停。
+- 末句写成问句,孩子就得答你。什么时候问,见守则「答完就停」。
+- 末句是问句,播放器就停下等孩子。
+- **只有末句会停。** 中间的问句念完,接着念下一句,不等孩子。
+- 末句这一问能选,就配一张 `choice` 卡。卡在前,问句在后。
+- 答案是一个数、一个词,不配卡:孩子开口说。
+- 开放的问题不用配卡。应用会把末句那一问补成板上的一张提问卡,你别自己再写一张。
+- 要孩子拍照片给你看,在节尾放一张 `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 厘米,面积是多少?
+````
+
+## 作业照片
+
+上下文包里有 `photos:`,就是孩子拍了作业。
+
+两种路径:
+
+- `photos:` 是写在卡上的路径,相对 workspace 根。照原样抄进 `image` 或 `canvas` 卡。
+- `photoFiles:` 是同一批照片的绝对路径,顺序一一对应。**Read 用它**,不用 find,不自己拼。
+
+怎么看:
+
+1. 原图 Read **一次**。认出是哪本、哪页、哪道题、卡在哪。
+2. 照片上半透明的红线是孩子自己圈的,先讲圈住的那道。
+3. 孩子写的字认不清,不裁图、不放大(这轮没有能裁图的工具)。讲稿里请孩子指一下、念出来,或者再拍近一点。
+4. 别为了逐题核对答案,把整页看好几遍。一次只讲一道,其余的轮到了再看。
+
+怎么讲:
+
+1. 讲稿第一句说出你认出的:哪本、哪页、哪道题。
+2. 第一张卡放作业:`image` 卡引原图(路径照 `photos:` 原样写),或 `text` 卡抄题面。
+3. 一页有好几道,在这张卡后面放一张 `choice`,列出题号问孩子讲哪道。一次只讲一道。
+4. 拍糊了、拍不全、认不出,讲稿里请孩子再拍一张,或指一下。
+
+要孩子在作业上圈、写,用 `canvas` 卡,第一行写照片路径。
+
+还要知道:
+
+- 孩子发之前可以裁剪、圈画。
+- 消息里的字,是孩子对这几张照片说的话。没说话就是「(拍了 N 张)」。
+- 几张一起来的,多半是同一份作业的几页。
+
+## 孩子的画
+
+孩子画了给你看,有两种:
+
+- 交了画板卡:`cards:` 里那张卡的一行写着几笔、画了多久、图的路径。
+- 从左栏的纸上交的:上下文包里有 `drawing:`,说图是 `photos:` 第几张。
+
+怎么看:
+
+1. 图 Read 一次,用 `photoFiles:` 或卡那行里的绝对路径。
+2. 清空重画过的,清掉的那几版也看一眼。
+3. 有 `live:` 的 `draw:`,是他画的时候和嘴说过的话。他说是什么,就是什么。
+
+怎么回:
+
+1. 讲稿第一句说你看见的:颜色、样子、画了多少、画得多用心。
+2. 认不准画的是什么,就问他,别照题目猜。
+3. 接着他画的时候说过的话说,别再问他答过的。
+4. 再回到这一科:把他说的连成一句话,或者对上要学的。
+
+还要知道:
+
+- 消息里的字,是他按住「给老师看」说的话。没说话就是「(画了一张,没说话)」。
+- 画不评对错。
+
+## 卡的种类
+
+### text — 一段字
+
+板上的一段字:定义、结论、公式、一句要记住的话、题面。一张卡一个意思,能独立被指着讲三句。
+
+- 围栏标签只写 `text`。
+- 正文第一行以 `# ` 开头,就是这张卡的标题,下面是正文。
+- 只有一行 `# 标题`、没有正文,就是小节标题。
+- 算式写 `text formula`:衬线居中,单独一行。
+- 样子(底色、字号、并不并排)不用管,应用按卡的种类定。
+
+```text
+# 认边
+两条短边叫直角边,最长的一条叫斜边
+```
+```text formula
+三角形面积 = 底 × 高 ÷ 2
+```
+```text
+# 两大类型
+```
+
+### read — 点读
+
+一行一段、点哪段听哪段的卡:原文、古诗、课文、生词、单词表。每段会在后台配成一段音(你配了音色的话),孩子点了就念。
+
+一行一段。英文后面可以跟中文(`apple 苹果`),念的时候整段一起念。
+
+```read
+床前明月光,疑是地上霜。
+举头望明月,低头思故乡。
+```
+```read
+apple 苹果
+banana 香蕉
+orange 橘子
+```
+
+### choice — 选择题
+
+一道选择题:问题 + 几个选项,答案只有你知道。孩子在舞台里点大按钮选,选了「交给老师」就到你下一轮的上下文包里。
+
+第一行是问题,后面每行 `- [ ] 选项`,对的那项写 `- [x]`(标了多个就是多选)。答案孩子看不到。
+
+```choice
+底 6 厘米、高 4 厘米的三角形,面积是多少?
+- [ ] 24 平方厘米
+- [x] 12 平方厘米
+- [ ] 10 平方厘米
+```
+```choice
+下面哪些是圆的?
+- [x] 苹果
+- [ ] 香蕉
+- [x] 西瓜
+```
+
+### image — 图片
+
+一张图 + 图注:孩子拍的作业、产物里的图、网上的图。
+
+- 第一行是图:workspace 里的相对路径,或 http(s) 地址。只认图片后缀。
+- 作业照片照 `photos:` 原样写,如 `captures/2026-09-10/1620-1.jpg`。照片在 workspace,不在 vault。
+- 后面几行是图注。
+
+```image
+captures/2026-09-10/1620-1.jpg
+你昨天写的这道题,看第二行。
+```
+```image
+https://example.com/brain.png
+```
+
+### tianzige — 田字格
+
+田字格:孩子问「这个字怎么写」时用的卡,一到四个汉字,每个字一个格,讲到这张卡时逐笔写一遍,之后孩子点哪个字,哪个字再写一遍。笔顺是现成的数据,不是你写的。
+
+- 第一行是要写的字:一到四个汉字,不要空格、标点。
+- 第二行写拼音:一字一个音节,空格隔开,带声调(`gǔ lì` 或 `gu3 li4`)。
+- 多音字写这句话里的读法,如「长大」写 `zhǎng dà`。
+- 拼音和字数对不上,卡上就只有字,不显示拼音。
+- 同音的词先给:先出这张卡,讲稿里说一句是哪个意思,如「鼓励,就是给人加油打气」。
+- 不先问,也不在末尾问「你说的是……吧」。写错了,孩子会说。
+
+```tianzige
+鼓励
+gǔ lì
+```
+```tianzige
+长大
+zhang3 da4
+```
+```tianzige
+鼓
+gǔ
+```
+
+### word — 单词卡
+
+单词卡:孩子问「X 英语怎么说」、一节里教新词时用的卡。一张卡一个英文单词,写在四线三格里,讲到这张卡时一笔一笔写一遍。卡上没有中文。点开是慢速:慢念,再按自然拼读一段一段慢写。
+
+- 第一行:emoji 和英文单词,如 `🍎 apple`。
+- 能画出来的东西配一个 emoji。抽象的词(like、the)不用配。
+- 第二行:自然拼读分段,用 `-` 隔开,如 `ap-ple`、`sh-ee-p`。
+- 分段拼起来要和单词一模一样。一个字母一段也行,如 `c-a-t`。
+- 一张卡一个词,最多三个词、16 个字母。
+- 只写字母、空格、撇号和连字符。不写音标,不写中文谐音。
+
+```word
+🍎 apple
+ap-ple
+```
+```word
+🐑 sheep
+sh-ee-p
+```
+```word
+🍦 ice cream
+ice cr-ea-m
+```
+```word
+like
+```
+
+### lecture — 放课里的一段
+
+孩子看过的小课堂里的一段,铺满放,带课里原来的声音。上下文包有 `lecture:` 才有课可放。
+
+- 第一行是课的 id 和一段时间,中间空一格。
+- id 照 `lecture.source` 抄,去掉前面的 `bundle ` 或 `video `。
+- 时间照 `lecture.lines` 抄:那一句的起点到下一句的起点,写成 `0:19-0:30`。
+- 只写起点,就放起点那一句。
+- 第二行可以写一句给孩子的话,写在卡上。
+- 讲稿里写 `[[play]]` 锚到它:念完这句,铺满放那一段,接着念下一句。
+- 放完画面停在那一段的末帧,不关。这句之后的话,对着末帧说。
+
+```lecture
+2026-09-18-po13-jian-8 0:19-0:30
+再看一遍拆开那一捆。
+```
+
+卡后面的讲稿这样写:
+
+> 你画的就是这一捆。我们回到那里再看一遍。[[play]]
+> 拿走 8 根,这一捆还剩几根?
+```lecture
+2026-09-18-po13-jian-8 0:30
+```
+
+### canvas — 画板
+
+孩子自己在上面画的一块板:笔、橡皮、黑红蓝三色、撤销、清空。可以给一幅底图(课包的终帧、几个骨架元素,或孩子刚拍的作业照片)让孩子在上面标画,也可以空白只给题目。「给老师看」会导出一张 png 给你。
+
+- 第一行是底,后面的行是题目。标签后面的词也可以当题目。
+- 底有四种:
+  - 课包 id:那幅图的终帧做底,孩子在上面标画。
+  - 一张图的路径:照 `photos:` 里那样的 `captures/…` 相对路径写,照片做底。
+  - 一段行内骨架 JSON:`{"skeletons":[…]}`,课包场景的元素写法(chalk),不超过 40 个。
+  - 什么底都没有:只写题目,就是空白画板。
+
+```canvas
+画一个三角形,标出它的一条高。
+```
+```canvas
+2026-09-10-guilv
+把每次少的那个数圈出来。
+```
+```canvas
+captures/2026-09-14/1620-1.jpg
+把算错的那道圈出来。
+```
+
+### paint — 画图
+
+孩子说清楚的一个故事,分好幅交给画家,应用画成一张连环画(四幅时 2×2,像练习册)。出题时带上题干和词语宝库,就是一道看图说话题。
+
+- `题:` 题干,出题才写。
+- `词:` 词语宝库,用顿号隔开,出题才写。画不出来的词(突然、终于)也放这里。
+- `角色:` 一行一个,写成「名字:样子、颜色、衣服」。每幅都照这个样子画。孩子说的颜色就用孩子的。
+- 孩子没说样子,只写名字:`角色: 小熊`。
+- `1.` 起一幅一行,一到四幅。每幅只写看得见的:时间和天气、地方、谁、动作、表情、东西。
+- 每幅都写出角色的名字,不用「他」。
+- 不写心里想的、说的话,也不写「羞愧」这种看不见的词:写成「低着头,脸红红的」。
+- 一幅最多三个角色,一幅只画一件事。
+
+```paint
+角色: 小熊:棕色,戴黄色草帽,穿绿色背带裤
+角色: 小猴:黄褐色,穿红背心
+1. 春天的早上,地里。小熊弯着腰把西瓜种子埋进土里;小猴坐在树下吃桃子。
+2. 中午,大太阳。小熊提着水壶给小苗浇水;小猴躺在树荫下睡大觉。
+3. 夏天,小熊的地里结满大西瓜,小熊抱着一个笑着;小猴的地里只长了草。
+4. 小熊推着满满一车西瓜,递给小猴一个;小猴低着头,脸红红的,挠着后脑勺。
+```
+
+出题版,带题干和词语宝库:
+```paint
+题: 图上画了谁?他们在干什么?结果怎么样?用上下面的词,写几句话。
+词: 播种、睡大觉、满满、羞愧
+1. 春天的早上,小熊在地里播种;小猴坐在树下吃桃子。
+2. 小猴低着头,脸红红的。
+```
+
+### photo — 拍给我看
+
+请孩子拍一张照片发给你:看图说话的那幅图、写好的那一页、做完的那道题。
+
+- 正文一行:要拍什么,最多 30 个字。
+- 放在一节的最后。一节只放一张。
+- 讲稿末句请孩子拍下来发给你。应用不再补提问卡。
+
+```photo
+看图说话的那幅图
+```
+```photo
+写好的那一页
+```
+
+### code — 代码或原样的文字
+
+原样显示、不念的一块字:代码、要保留缩进与符号的东西。
+
+- 围栏标签写语言名(```python),就是代码卡。
+- 不认识的标签,一律当代码卡原样显示,不报错。
+
+```python
+print(1 + 1)
+```
+```
+  3 4
++ 1 2
+-----
+  4 6
+```