# 课程讲述与编辑原则

[English version](course-editorial-principles.md) · [统一课程设计](course-design.zh-CN.md) · [课程与补充资料](README.zh-CN.md)

> **状态：v0.1，2026-09-25。** 这是面向学习者的 K/L 课程页、讲解稿、字幕和后续实验报告共用的编辑契约。它吸收团队已有的课程分享原则，并针对系统辨识重新表达。不替代课程地图、数值实验契约或逐课评审。

## 为什么需要这份原则

机器人系统辨识很容易被讲成一串方程、仿真器设置和曲线。这样的讲法可以技术正确，却让学员不知道该看什么、某个结果究竟支持了什么，以及下一步应该怎样验证。

这套课程应该像一次有人带着走的调查。学员先看到具体偏差，提出预测，改变一个已经声明的条件，阅读证据，再说出有边界的结论。方程和实验都服务于这个判断过程，不变成脱离决策的定义章节。

团队已有原则提供编辑纪律：从具体对象开始，让学员不依赖讲师实时回复，区分示范与练习，诚实标注证据，让每一段回答学员眼前的问题。机器人课程保留自己的技术身份：动力学、信号可见性、可辨识性、模型失配和工作范围仍然是主线。

## 核心理念：从偏差走到有边界的下一次实验

每节课都沿着下面的小型调查推进：

```text
观察一个偏差
        → 预测原因或模式
        → 画出系统边界
        → 改变一个已声明条件
        → 阅读证据
        → 说明证据支持什么、还排除不了什么
        → 选择下一次能区分假设的实验
```

学员能够做出并解释这个判断，课程才算达到目标。记住方程、对齐一条曲线或接受最低拟合误差都不够。合格结论可以是参数估计、在一定范围内有效的行为模型、一个受约束的参数范围，也可以是说明为什么需要新实验。

## 学员与讲述者的角色

### 学员是调查者

写给正在看信号、图、表格或残差，并判断其含义的人。先让学员预测，再给解释。学员要采取动作时使用“你”，同时把完成这个动作所需的证据展示出来。

### 讲述者是共同观察者

讲述者负责引导注意力：“我们先看这个偏差”“保持姿态不变”“比较留出运动”。不要站在看不见的全知位置，在证据出现之前宣布结论。真实运行就解释实际输出；示例或计划契约就明确说明它们的状态。

### Oracle 与 Student 是实验角色

`Oracle` 与 `Student` 描述合成系统和待拟合的候选模型，是技术角色，不是“老师”和“学员”的替代词。把学员放在实验边界之外：隐藏真值可以用来解释结果，但不能悄悄成为拟合输入。

### 分开知识和可见性

一个事实可能只是作者知道、由 Oracle 生成、只对评估可见，或者真的提供给拟合器。要明确它属于哪一种。图和旁文不能悄悄把实验声明不提供的信号交给学员。

## 统一的课程节奏

六段页面结构继续作为课程导航，但每一段都承担具体的叙事任务：

### 1. 从可见偏差开始

先说清对象和反常现象。可以是一个姿态、动作、指令、残差或接触事件。不要一开头就列学习目标或宣布课程价值。

### 2. 先让学员预测，再给方程

先提出一个小判断：姿态、加速度、速度、延迟或接触变化后，什么应该发生？然后只引入解释这个预测所需的符号。

### 3. 画出边界，只推导够用的部分

说明什么进入系统、观测什么、隐藏什么、固定什么。工程推导要交代单位、依赖关系和假设。除非当前判断确实需要，完整证明放到补充材料。

### 4. 一次只改变一个已声明条件

把系统、控制器、观测和预算写清楚。隔离效应时，每次只改变一个有意义的条件。如果多个效应仍然耦合，就把这种耦合作为课程对象，不要假装已经完成了更多隔离。

### 5. 带着结论和边界阅读证据

让学员把观察连接到判断：

```text
我原本预期……
图或指标显示……
在这些条件下，它支持……
它仍然不能排除……
下一步我会测试……
```

明确区分拟合、开发和最终评估。更低的损失、恢复出的参数、较好的留出预测和更好的下游控制，属于不同的结论。

### 6. 用能区分假设的实验收束

结束时说清剩余歧义，以及最小的下一次实验。只说“再收集一些数据”不够，除非同时说明新增哪个条件、信号或动作会带来信息。

K 课可以使用概念示意或已经验证的实验材料来讲判断；L 课把判断放进已声明的实验中。两种课程不需要互相伪装成同一种形式。

## 讲述口吻与句子规则

- 从名词、动作或可见变化开始：“换向后关节变慢”“第 2 关节的残差在第 1 关节加速时变大”。
- 使用现在时和具体主语。优先说“保持姿态不变”，不要说“姿态应当被保持不变”。
- 讲述共同观察时用“我们”，要求学员判断时用“你”。只有在指代实验角色时才使用“Student”和“Oracle”。
- 一段集中说明一个观察、理由或动作。听者需要自己重建因果顺序时，把长句拆开。
- 把限制条件放在被限制的结论旁边，不要把工作范围藏在最后的免责声明里。
- 实验输出还不存在时，不要预写成功台词。实际运行产生什么曲线、指标或失败，就解释什么。
- 不用“不相信 AI”、不相信优化器或不相信某种拟合作为证据。只要条件和证据支持，接受一种方法也可以是正确结论。

口播应像同事带着你调查问题。页面可以使用紧凑标签和表格，讲稿要用自然过渡把它们连起来。屏幕标题和短标签不必添加装饰性的中文句号；完整说明、问题、条件和解答保留表达含义所需的标点。

## 证据状态与用语

每张图、每个数字、每段视频和每个结论都标明以下一种状态：

| 状态 | 含义 | 可以使用的说法 |
|---|---|---|
| 实测 | 由声明的运行生成并通过检查 | “这次运行显示……” |
| 回放 | 重新查看已完成结果，没有重新拟合 | “回放显示……” |
| 概念示意 | 用于解释的图或示例曲线 | “这个例子说明……” |
| 计划 | 为未来运行器或报告写的契约 | “这个实验将比较……” |
| 诊断 | 可用于生成或解释，但排除在拟合之外 | “Oracle 诊断表明……” |

不能把概念对照叫作实验结果，也不能把计划中的图叫作证据。新的 L 课还没有数值运行器时，要直接说明实验契约、预期阅读方式和缺少的产物。

## 方程与术语

把方程当作做判断的地图。在方程旁边说明输入、观测输出、未知量、固定量、单位和隐藏诊断信号。每个符号都应通过解释可见依赖关系或边界选择来证明自己有必要出现。

第一次出现时，用稳定英文加自然中文介绍术语，例如 `Student / 待辨识模型`、`Oracle / 真实系统` 和 `held-out evaluation / 留出评估`。之后可以使用较短的形式。`state`、`input`、`contact`、`delay` 等词在不同课程中的边界可能不同，要回到当前课程的系统边界解释。

## 页面与媒介契约

静态页面必须能够独立阅读。它要包含问题、边界、证据状态、练习与解答、局限和下一步。视频、Notebook 或浏览器交互可以帮助看清现象，但不能成为学员判断依据的唯一载体。

示范和练习承担不同责任。回放可以告诉学员该看哪里，练习要求学员自己做判断。参考实现是合格实现之一，不是正确性的定义。环境或仿真器不可用时，提供固定产物和回到真实操作的路径，但不能把观看回放说成已经获得动手证据。

保留六段结构作为导航，但允许重点和篇幅变化。K 课可以多花时间看图和推导，L 课可以多花时间做对比和读残差。统一结构是为了降低进入成本，不是让每页听起来都像由同一段模板生成。

## 双语契约

中英文页面共用课程编号、方程、单位、信号边界、证据状态和结论。中文页面应成为面向中文工程师的自然解释，不是逐句替换；英文页面在需要时保留稳定的可搜索术语。

内容或证据契约改变时，两种叙事一起更新。翻译可以使用更短的句子或更自然的例子，但不能强化结论、藏起不确定性，或改变某个信号是拟合可见、只用于评估还是诊断信号。

## 现有课程的 refactor 门槛

改写页面之前，先判断每一段当前承担什么任务，以及它对应哪一种证据状态。按以下顺序检查：

### 内容

学员在遇到一般方法之前，能否说出对象、偏差和当前判断？如果不能，把具体观察提前。每个方程是否都解释了依赖关系或边界？如果没有，缩短它，或移到补充材料。

### 口吻

学员能否知道讲述者正在看什么、自己应该预测什么、下一步会发生什么？把关于“学员应该……”的远距离陈述改成直接观察或动作。保留 Student 和 Oracle 作为模型角色。

### 证据

学员能否区分实测、回放、概念示意、计划和诊断材料？如果不能，先标注产物状态再解释。删除任何暗示尚不存在的运行、报告或仿真结果已经存在的句子。

### 练习

题目是否提供了足够的可见证据？解答是否说明推理、一个常见误判、补救入口和继续条件？如果没有，这只是让学员猜答案的提示，不是学习检查。

### 翻译

中英文是否保留了同一个边界、结论、不确定性和下一次实验？检查首次术语和两种语言口播时的自然节奏。

## 不做什么

这些原则不会把课程变得随意，不会删除方程，也不要求每课都配视频。每课仍必须声明素材状态（已有、计划中或无需视频），并为明确问题提供静态解释和可使用证据。它们不要求人为制造失败、每个问题只有一个解释、所有页面使用同一种视觉风格，或在讲清契约前先完成完整仿真器。它们也不替代数值验证、独立学员验收或逐课技术评审。

## 完成标准

一节完成 refactor 的课程达到以下条件后，才进入 review：

1. 开头呈现了具体偏差或问题；
2. 学员在主要解释之前做过预测；
3. 系统边界和证据状态清楚可见；
4. 练习可以根据页面回答，解答说明了为什么；
5. 结论同时写出证据支持什么和剩余不确定性；
6. 下一次实验具体到足以改变当前诊断；
7. 中英文保留同一个技术契约。