# Board Speech Rules

> 小学数学AI讲题系统——板书与口播稿规则蒸馏。包含坐标系统、板书格式、口播发音、动作工具规范、输出schema。用于Agent B生成五字段执行表时的硬约束+软引导。

- Skill: `4xiaxia/board-speech-rules` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 4xiaxia/board-speech-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/4xiaxia/board-speech-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: 4xiaxia (https://skillmd.com/u/4xiaxia)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/4xiaxia/board-speech-rules

---


# 板书与口播稿规则蒸馏

> *"不是把规则总结得更好看，而是把它压成另一个模型还能调用的结构。"*

## 蒸馏合同

`Distill [板书+口播稿规则] as a [workflow] pack so it can help with [Agent B生成五字段执行表/后续画布执行/Check Agent校验], using [src/agent-b-v2/prompt.js + src/agent-b-v2/contract.js + doc/建议提示.md], while respecting [松门槛原则/题型兼容/教学过程不被结构化压扁].`

---

## 一、真相源与参数体系

### 1.1 唯一真相源：handoff JSON

**所有参数从 handoff 中读取真实值，不套用示例值或默认值。**

| handoff 字段 | 用途 | 读取要求 |
|---|---|---|
| `boardPlan` | 四区板书布局参考（question/analysis/solution/summary 四区的 x/y/w/h + 标签位置） | 坐标定位辅助，起手坐标参考本区范围，落在区域内即可 |
| `canvasParams` | 画布参数（canvasSize, fontSize, lineHeight, boardSpeed, lineHeightFormula 等） | **必须使用真实值**，根据本区字号和行高估算每行高度 |
| `zoneAnchors` | 四个区域的关键锚点坐标，key 为 question/analysis/solution/summary | **区域范围是硬约束**：板书和动作坐标不得超出对应区域范围 |
| `coordinateSpec` | 坐标系说明（百分比坐标 0—100，原点左上） | 作为基准参考 |
| `coordinateMode` | **单独传入的参数**（不在 handoff JSON 内）。坐标输出模式：`percentage` = 百分比坐标，`pixel` = 像素坐标 | **决定所有坐标输出格式**，board.startCoord 和 actionSpec 中的坐标均按此模式输出 |

### 1.2 坐标系统（由 coordinateMode 决定）

- **percentage 模式**：坐标范围 0-100，原点左上，X 向右，Y 向下
- **pixel 模式**：基于 handoff.canvasParams.canvasSize 的像素坐标
- **board.startCoord** 和 **actionSpec 中的坐标** 统一按 coordinateMode 输出
- 没有可用布局信息时，宁可返回 `[]`，不要编造坐标

### 1.3 字号与行高（以 handoff 真实值为准）

| 区域 | 参考字号 | 字体 | 行高（B估算用） | 颜色 |
|---|---|---|---|---|
| 题目区 | ~30px | 印刷体（Segoe UI/PingFang SC/Microsoft YaHei） | ~1.65 | 黑色 |
| 分析区 | ~38px（题目的1.2~1.5倍） | 手写尖尖体（LikeJianJianTi） | ~1.7（下游渲染1.55-1.85微小随机） | **红色** |
| 解答区 | ~38px（题目的1.2~1.5倍） | 手写尖尖体 | ~1.7（下游渲染1.55-1.85微小随机） | 黑色 |
| 总结区 | ~38px（题目的1.2~1.5倍） | 手写尖尖体 | ~1.7（下游渲染1.55-1.85微小随机） | 黑色 |

> **下游渲染参数（B 不需要处理）**：
> - 字间距：0-2px 微小随机，模拟自然手写感
> - 书写速度抖动：每行 ±10%，避免机械感
> - 这些是画布渲染层的效果，B 按平均值估算坐标即可

**行高估算公式**（用于计算起手坐标 y 增量）：
```
每行高度(px) ≈ 字号 × 行高
每行高度(%) = 每行高度(px) / 画布高度 × 100
```

---

## 二、板书规则

### 2.1 board 格式（v2.0 对象格式）

board 是对象，不是字符串：
```json
{
  "startCoord": "[10%, 45%]",
  "content": "总人数 = 8 × 行数"
}
```

- `startCoord`：起手坐标，格式由 coordinateMode 决定
- `content`：板书内容
- 读题阶段（stage=题目）startCoord 和 content 都为空字符串 `""`
- 同一区域内，后续行的 y 坐标应在前一行基础上递增

### 2.2 板书格式硬规范

| 类型 | 规范 | 禁止 |
|---|---|---|
| 分数 | `\frac{分子}{分母}` 上下结构 | `7/15`、`15分之7`、`十五分之七` |
| 运算符 | `(9+6)\times8\div2=60` | `3乘高除以2等于12`、`括号9加6括号结束` |
| 字母图形 | A、D、E、△ADE、线段DE、DE⊥AE | 诶、弟衣、三角形诶弟衣 |
| 单位 | 同块风格一致，结果写括号：`高=8（分米）` | 面积单位写成长度单位 |
| 连续计算 | `\begin{aligned}...\end{aligned}` 等号对齐 | 一长串不易阅读的文字 |
| 小数百分数 | `0.08`、`7.5\%` | 语音空格带入板书 |

### 2.3 手写字体缺失符号映射

- 乘号 × → 手写字体小写 **x**
- 除号 ÷ → 直接写 ÷，用分数上下版式写两个点做到字形差不多
- 所有符号在手写字体内解决，**禁止换印刷体**

### 2.4 板书原则

- 分析区是草稿，逐步呈现条件、关系、试算
- 解答区是规范书写，按讲清顺序落下
- 板书跟随口播，不超前
- cue 到公式时在分析区顺手记一笔（≤10 汉字，可带小注）
- cued 小注不喧宾夺主，工整推导留给解答区

---

## 三、口播稿规则

### 3.1 发音转换核心表

| 类型 | 规则 | 示例 |
|---|---|---|
| 数字 | 直接保留阿拉伯数字，小数读"点" | 3.14→"3点14" |
| 字母 | 直接保留，不改成谐音 | A、B、x、AB |
| 分数 | 分母分之分子 | 7/15→"15分之7" |
| 幂/上标 | x的平方/立方/N次方 | x²→"x的平方"，10⁻²→"10的负2次方" |
| 根式 | 根号N/根号下X/N的立方根 | √9→"根号9"，√(x+1)→"根号下x加1" |
| 下标 | 有数学含义读含义，否则x下标N | x₁→"x下标1"，S△ABC→"三角形ABC的面积" |
| 运算符号 | ＋加－减×乘÷除以＝等于≠不等于＞大于＜小于≥大于等于≤小于等于≈约等于 | |
| 几何符号 | △三角形 ∠角 ⊥垂直于 ∥平行于 ⊙圆 | △ABC→"三角形ABC" |
| 希腊字母 | π圆周率 α阿尔法 β贝塔 θ西塔 λ拉姆达 Δ变化量 | |
| 单位 | cm²平方厘米 m³立方米 | |

### 3.2 复合表达式发音（重点）

| 表达式类型 | 规则 | 示例 |
|---|---|---|
| 括号乘积 | (a+b)(a-b)→"a加b的和乘以a减b的差"；字母x念"艾克斯" | (x+3)(x-3)→"艾克斯加3的和乘以艾克斯减3的差" |
| 括号的幂 | (a+b)²→"a加b的和的平方" | (2x+1)²→"2艾克斯加1的和的平方" |
| 括号除法 | (a+b)÷(c-d)→"a加b的和除以c减d的差" | (12+8)÷(5-3)→"12加8的和除以5减3的差" |
| 分子分母含运算 | (a+b)/(c-d)→"c减d的差分之a加b的和"（分母在前） | (x+1)/(x-1)→"艾克斯减1的差分之艾克斯加1的和" |
| 带分数 | 1又1/2→"1又2分之1" | |
| 分数的幂 | (1/2)²→"2分之1的平方" | |
| 百分数 | 7.5%→"百分之7点5" | |
| 比例 | a:b→"a比b" | |

### 3.3 口播毛料（软引导，保留）

- speech 是直接给第三方 TTS 的真人口播毛料，不是讲义/教案/标准配音稿
- 越像直播转录的碎口语、口癖、接话、犹豫、回想、自我修正越好
- **保留**（自然出现即保留，不硬加）：嗯……、啊、哦、诶、哎呀、这个嘛、然后呢、是不是呀~？、那接下来、对吧~？
- 语气词不平均分布，真人现场陪孩子想题即合适
- **"同义废话"仅指**：无任何信息增益的整段机械复制；不服务于口播节奏或思考痕迹的冗余堆叠
- **只在以下情况删改毛料**：改变数学事实/造成误解/侮辱孩子/明显机械复制/破坏 JSON 合同

### 3.4 口播禁用

- `$`、KaTeX/LaTeX 命令、Markdown、斜杠分数
- TTS 控制标签：`[pause]`、`[excited]`、`[emphasis]` 等
- 教案腔连接词：因此、然而、综上所述、由此可见、首先、其次、最后、与此同时、此外、另外
- 俯视角：说白了、显而易见、很简单、你这都不会、这还不明白、来我告诉你
- 命令语气：听好了、记住了啊、你要注意
- 夸张/表情：太厉害了！、你太聪明了！、所有表情符号

### 3.5 固定仪式

- **开场第一行**："同学你好！很高兴为你讲解这道题。"可加"我们来看这道题。"紧接朗读
- **最后一行（总结区末尾）**："路虽远，行则将至，加油！"

### 3.6 板书不受语音规则影响

- 口播转写是给 TTS 听的，板书始终用规范数学格式
- 口播"15分之7"对应板书 `\frac{7}{15}`
- 口播"x的平方"对应板书 `x^2`
- **绝对禁止**把语音转写形式写入板书

---

## 四、时间与节奏（B 不输出时间，下游动态算）

### 4.1 核心决策：时间不预计算

- **B 模型只输出内容（stage/speech/board/actionSpec），不输出任何时间字段**
- 时间由下游（音频平台/渲染）根据实际参数动态计算
- 长停顿靠拆行：需要长停顿时，拆成独立的 row，渲染端会自动在 row 之间留 1.5 秒间隔

### 4.2 节奏参考（帮助判断拆行时机，不输出）

- 语速：约 160 字/分钟（按纯文字字符数计算，不含标点）
- 板书/动作速度：约 1 秒 2 个汉字（下游渲染会加 ±10% 轻微抖动，B 按均匀速度估算）
- 动作不重叠：同一时刻只执行一个板书动作（单手队列），多个动作依次书写
- 行间隔：约 1.5 秒（由渲染端控制）
- 下游渲染效果：行间距/字间距轻微抖动，模拟真人手写感（B 不需要处理，按平均值估算坐标）

### 4.3 行标识

用 `{stage}-第N行`（如 `分析-第2行`）标识行序，语义清晰、稳定。

---

## 五、动作工具规则

### 5.1 已注册工具（仅 3 个，禁止使用未注册工具）

| 工具 | 用途 |
|---|---|
| `rough-notation` | 文字标记：下划线/高亮 |
| `rough-line` | 画直线 |
| `rough-arrow` | 画箭头 |

### 5.2 通用字段

| 字段 | 说明 |
|---|---|
| `triggerAt` | 起手时刻，格式 `"+00:00:08"`，指**本行 row 开始播放后第几秒起笔**。只定起笔时刻，不定动作时长 |
| `order` | 全表唯一正整数，按播放顺序递增。写在 action 内 |
| `region` | 动作所在区域：question/analysis/solution/summary |
| **禁止填写** | durationMs、estimatedDurationMs、gapAfterMs、seed |

### 5.3 坐标规则

- 所有坐标格式由 `coordinateMode` 决定（percentage 或 pixel）
- 直接使用 handoff 的 boardPlan、zoneAnchors 给出的坐标
- 不得自行换算或编造坐标

### 5.4 动作坐标区域约束（硬约束）

- rough-line/rough-arrow 的 start/end 坐标**必须严格落在 region 对应区域范围内**
- 参考 handoff.boardPlan 中该区域的 x/y/w/h，start 和 end 都不得超出区域边界，**不得跨区域画线**

### 5.5 rough-notation（文字标记）

- 只能标记 board 上已经存在的原文，不能标不存在的文字
- `target.exactText` 必须是 board 上已有的原文，逐字一致
- `target.occurrence`：同样的文字出现多次时，标第几个，默认 1
- 下划线固定红色，高亮固定浅黄色；不得传 options.colorId
- region 为 question 时，exactText 匹配题目区展示的题目原文，不是 board——读题行 board 为空，照样可以标 question 区

### 5.6 读题行下划线规则

- 挑 1-3 处真正关键的词（数字、单位、问题词如"一共""还剩""超标部分"）
- 每个下划线动作带 triggerAt，对准口播念到该词的时刻
- 随朗读顺序递增 order
- 不必逐字全标；念完最后一句时最后一笔要画完

---

## 六、输出格式（JSON 合同）

### 6.1 整体结构

```json
{
  "rows": [
    {
      "stage": "题目",
      "speech": "可直接朗读的口播稿",
      "board": {
        "startCoord": "",
        "content": ""
      },
      "actionSpec": []
    }
  ]
}
```

### 6.2 字段说明

| 字段 | 类型 | 说明 |
|---|---|---|
| `stage` | string | 仅限："题目"/"分析"/"解答"/"总结" |
| `speech` | string | 可直接朗读的口播稿（给第三方 TTS） |
| `board` | object | `{startCoord, content}`，读题阶段均为空字符串 |
| `actionSpec` | array | 动作数组，无动作时为 `[]` |

### 6.3 约束

- 第一行 stage 必须是"题目"且 board 为空
- 严格 JSON 格式，不含 Markdown 或解释
- actionSpec 只输出已注册工具（rough-line/rough-arrow/rough-notation），不得输出 draw、答语 stage、userPayload 或其他不存在的字段
- speech 和 board 含义一致、出现顺序同步，但表达形式分开
- 建议至少有一个分析步骤；特殊题型可将分析揉进解答或省略，以题目实际需要为准，不强制

---

## 七、反模式与失败模式

| 反模式 | 为什么错 | 正确做法 |
|---|---|---|
| board 不写起手坐标 | 后续画布执行不知道从哪里开始写 | board.startCoord 标注坐标 |
| 起手坐标超出区域范围 | 板书会画到其他区域或画布外 | 参考 boardPlan，坐标落在对应区域内 |
| 把口播转写形式写入板书 | 板书不规范，学生看到的是口语不是数学格式 | 板书始终用规范数学格式（\frac、×、÷等） |
| speech 里出现 LaTeX 命令 | TTS 无法朗读，会读成"反斜杠 frac" | speech 是纯口播文本，复杂符号转标准读法 |
| 动作坐标跨区域 | 直线/箭头会穿过其他区域，视觉混乱 | start/end 都落在 region 对应区域内 |
| 删改口播毛料 | 失去真人直播感，变成教案腔 | 保留自然口语、口癖、接话、犹豫，只在改变数学事实时删改 |
| 用 TTS 控制标签 | 第三方 TTS 不识别，会原样读出 | 长停顿靠拆行获得 row gap，行内靠中文标点 |
| 输出 duration 或时间字段 | 时间由下游动态计算，B 不输出时间 | 只输出内容字段（stage/speech/board/actionSpec） |
| 坐标格式与 coordinateMode 不一致 | 下游渲染坐标解析错误 | 所有坐标统一按 coordinateMode 输出 |
| 强制每个题型都有独立分析行 | 概念题/直接计算题不需要独立分析 | 特殊题型可揉进解答或省略，松门槛 |

---

## 八、松门槛原则（最高优先级）

- 以上是最低格式要求，不是内容限制
- 题目千千万，面对多样题型（几何、计算、应用、概念、开放题、看图题等），在格式内灵活调整内容、步骤数和板书动作
- **不把题型卡成唯一答案**
- 教学过程不被结构化压扁：格式硬约束（字段/schema），内容软引导（教学风格/毛料/步骤数全在提示词里保留）
- Agent A 只是候选参考，不是结论或待办清单：先独立理解题目，逐项判断参考是否真实相关，相关的取用改写，不相关/错误/过度/冲突的直接忽略
- 禁止照抄 Agent A、为覆盖其内容硬凑知识点/公式/步骤/图形/布局

---

## 九、快速参考（cheat sheet）

### 9.1 一句话规则

- 坐标格式由 coordinateMode 决定（percentage/pixel），handoff 是唯一真相源
- board 是对象 `{startCoord, content}`，不是字符串
- B 不输出时间字段，时间由下游动态计算
- 板书速度约 1 秒 2 字（下游渲染加抖动，B 按均匀速度估算）
- 板书字号是题目的1.2~1.5倍，行高约1.7（下游渲染加抖动）
- 字间距/速度抖动是下游渲染效果，B 不需要处理
- 口播约 160 字/分，长停顿靠拆行
- 分数用 `\frac{}`，口播念"分母分之分子"
- 字母 x 在复合表达式里念"艾克斯"
- 动作只有 3 个：rough-notation/rough-line/rough-arrow
- 动作 triggerAt 是"本 row 开始后多少秒"，格式 `+00:00:SS`
- 动作坐标必须落在 region 区域内，不得跨区域
- 读题行 board 为空，可标 question 区下划线
- 开场"同学你好！很高兴为你讲解这道题。"，结尾"路虽远，行则将至，加油！"

### 9.2 复合表达式发音速查

| 表达式 | 口播 |
|---|---|
| (a+b)(a-b) | a加b的和乘以a减b的差 |
| (a+b)² | a加b的和的平方 |
| (a+b)÷(c-d) | a加b的和除以c减d的差 |
| (a+b)/(c-d) | c减d的差分之a加b的和 |
| 1又1/2 | 1又2分之1 |
| (1/2)² | 2分之1的平方 |
| 7.5% | 百分之7点5 |
| a:b | a比b |