feat(mtc): .mt 脚本编译器落地 + pybot 扬声器静音语义

mtc 新模块：命令式动作脚本（Python DSL）→ .mt 矩阵编译器，非阻塞时间轴 IR（重叠截断/rest 静止值）+ 10ms 栅格化，产物可由 pybot/bot4cj 直接执行；34 测试全绿（含 pybot parser e2e）。

pybot speaker.py：frequency<=0 改为静音节拍（仅 sleep 保时序，不再钳到 min_f 低鸣），对齐仓颉版 sleep 占位语义；mtc Beep 通道 rest=0，段前/段间/段后回落静音，两侧语义闭环。

修复 test_actpred_compatibility 过时断言（99c1bc1 首行分解为重复微步 19→20 帧时漏改，14→15）。

文档三处同步：根 README 回填 memdb/pybot/actpred 并新增 mtc（模块表+端口一览+章节），MODULES/ARCHITECTURE 同步 mtc，新建 mtc/README.md。

mtc/README.md

@@ -0,0 +1,127 @@
+# mtc（.mt 脚本编译器）
+
+命令式动作脚本（Python DSL）→ `.mt` 矩阵脚本编译器。零第三方依赖（纯标准库），产物可直接由 [pybot](../pybot/) / [bot4cj](../bot4cj/) 解析执行。
+
+## 定位与管线
+
+手写 `.mt` 矩阵脚本需要心算 10ms 栅格上的全通道快照，冗长且易错。mtc 让动作用命令式 Python 描述（`Action("s1", 10, 100)`），编译器负责展开为栅格矩阵：
+
+```
+script.py ──exec(注入命名空间)──► 事件收集 ──► 时间轴 IR ──► 10ms 栅格化 ──► out.mt
+                                            （相对→绝对、重叠截断）
+```
+
+## 用法
+
+```bash
+cd mtc                                # 须在本目录运行（外层目录会被识别为 namespace package）
+python -m mtc walk.py                 # 编译到 stdout（可管道：python -m mtc walk.py | python -m pybot --dry-run /dev/stdin）
+python -m mtc walk.py -o walk.mt      # 写文件
+```
+
+也可设 `PYTHONPATH=mtc` 后在任意目录运行。诊断（编译告警/错误）走 stderr，stdout 保持纯净 .mt 文本。
+
+## DSL 参考
+
+脚本即 `.py`，`exec` 注入两类函数。
+
+### 硬件声明（函数名 = .mt 块名，位置参数 = 表头列，严格一一对应）
+
+```python
+I2C("i2c-1", "/dev/i2c-1")
+PCA9685("pca9685-0", "i2c-1", "0x40")
+Servo("s1", 180, 0, 0, "pca9685-0", 0)      # name,max,min,offset,controller,channel
+Speaker("spk", 2, 48000, 0.6, 5000, 20)     # name,channels,sample_rate,volumn,max_f,min_f
+Camera("cam0", 640, 480, 30, 8)
+MPU6050_BIND("imu0", "i2c-1", "0x68")
+Alias("A", "angle")
+register_block("ADS1115", ["name", "I2C", "addr"])   # 开放扩展（首列恒为 name）
+```
+
+### 时间轴指令（编译期求值，不产生 .mt 行）
+
+| 函数 | 语义 |
+|------|------|
+| `Action(dev, delta, dur)` | 相对运动：当前游标处注册，dur ms 内走 delta |
+| `SetTo(dev, angle, dur)` | 绝对运动（糖：delta = angle − 已注册目标值） |
+| `Beep(freq, dur, dev="spk")` | 扬声器频率段：dur ms 内恒为 freq（阶跃段） |
+| `Delay(ms)` | 游标推进固定量 |
+| `Wait()` | 汇合：游标推进到所有在途运动的最晚完成时刻 |
+| `Pose(dev, angle)` | 声明编译期初始姿态（不产生运动段，须在 Action 之前） |
+
+`dur` / `Delay` 必须是正的 10 的倍数（.mt 栅格与 pybot 微步节拍均为 10ms）。
+
+## 语义规则
+
+- **非阻塞时间轴**：`Action`/`SetTo`/`Beep` 在当前游标处注册运动段并立即返回，`Delay`/`Wait` 才推进游标。不同设备段在同一时间窗重叠即并发运动。
+- **重叠截断**：同通道新段与未完结末尾段重叠时，前段截断至新段起点，新段基准取前段**目标值**（编译期确定，不依赖运行时实际姿态），并产出告警（stderr）。
+- **静止值（rest）**：姿态通道（舵机等）段外保持前段目标值；`spk.frequency` 通道段前/段间空隙/段后统一回落 0 = 静音（对齐 pybot speaker 静音语义：`freq<=0` 不出声仅保节拍）。
+- **节拍列**：`spk.delay` 由编译器管理（恒 10），脚本不能直接写；无 Speaker 块则无节拍列（pybot 执行时行间隔不等待，编译器给出告警）。`spk.frequency` 无段时自动补恒 0 列（pybot 契约：frequency/delay 两列成对出现）。
+- **栅格行语义**：格点 t=10,20,…,T，每行代表该 10ms 结束时刻的绝对姿态；pybot `run()` 对 delay=10 的行分解为 1 个微步且插值系数 1.0，即直接到位——与栅格语义严格等价。
+
+## 示例
+
+```python
+Servo("s1", 180, 0, 0, "pca9685-0", 0)
+Servo("s2", 180, 0, 0, "pca9685-0", 1)
+Speaker("spk", 2, 48000, 0.6, 5000, 20)
+Action("s1", 10, 100)     # s1 在 [0,100ms) 走 10°
+Delay(50)                 # 游标推进到 50ms
+Action("s2", 20, 50)      # s2 在 [50,100ms) 走 20°（第 6 行起步）
+```
+
+编译产物：
+
+```
+@Servo
+name max min offset controller channel;
+s1 180 0 0 pca9685-0 0;
+s2 180 0 0 pca9685-0 1;
+@
+
+@Speaker
+name channels sample_rate volumn max_f min_f;
+spk 2 48000 0.6 5000 20;
+@
+
+@Action
+s1.angle s2.angle spk.frequency spk.delay;
+1 0 0 10;
+2 0 0 10;
+3 0 0 10;
+4 0 0 10;
+5 0 0 10;
+6 4 0 10;
+7 8 0 10;
+8 12 0 10;
+9 16 0 10;
+10 20 0 10;
+@
+```
+
+## 输出契约（与 pybot parser 对齐）
+
+- `@块名` / `@` 定界；行 0 表头；行尾 `;`；列间空格分隔；相邻同名块合并为一个块多行。
+- `@Action` 表头为 `设备.参数` 长名（恰含一个 `.`，Q05 校验），末列 `<speaker>.delay` 恒 10。
+- 数值格式化：整数无小数点，小数至多 3 位。
+
+## 测试
+
+```bash
+cd mtc && python -m pytest tests/ -q
+```
+
+含 e2e 闭环验证：编译产物经 pybot `MatrixParser` 零修改解析（列数一致、Q05 表头契约、栅格行数值逐一比对、roundtrip 自检）。pybot 与 mtc 的 `tests/` 目录同名，两套测试须分进程运行。
+
+## 目录结构
+
+```
+mtc/
+├── mtc/
+│   ├── __init__.py      # 包入口（compile_script / CompileError）
+│   ├── __main__.py      # CLI：python -m mtc script.py [-o out.mt]
+│   ├── dsl.py           # DSL 命名空间 + 事件收集（Collector）
+│   ├── timeline.py      # 时间轴 IR：Segment/Channel、重叠截断、rest 静止值
+│   └── emit.py          # .mt 序列化：硬件块合并 + 10ms 栅格矩阵
+└── tests/               # pytest（含 pybot parser e2e 闭环）
+```

mtc/mtc/__init__.py

@@ -0,0 +1,14 @@
+"""mtc —— 命令式动作脚本（Python DSL）→ .mt 矩阵脚本编译器
+
+管线：script.py --exec--> 事件收集 --> 时间轴 IR（相对→绝对，
+重叠截断）--> 10ms 栅格化 --> out.mt --> pybot 解析/执行。
+
+用法：
+    python -m mtc walk.py              # 编译到 stdout（管道风格）
+    python -m mtc walk.py -o walk.mt   # 写文件
+    python -m pybot --dry-run walk.mt  # 交给 pybot 验证/执行
+"""
+
+__version__ = "0.1.0"
+
+from .dsl import CompileError, compile_script  # noqa: F401

mtc/mtc/__main__.py

@@ -0,0 +1,54 @@
+"""CLI 入口：python -m mtc script.py [-o out.mt]
+
+诊断（编译告警/错误）走 stderr，stdout 保持纯净 .mt 文本
+（对齐 pybot 的 S02 日志规范，支持 mtc walk.py | pybot --dry-run 管道）。
+"""
+
+import argparse
+import logging
+import sys
+
+from .dsl import CompileError, compile_script
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(
+        prog="mtc",
+        description="命令式动作脚本（Python DSL）→ .mt 编译器")
+    p.add_argument("script", help="DSL 脚本路径（.py）")
+    p.add_argument("-o", "--output", default=None,
+                   help="输出 .mt 路径（缺省写 stdout）")
+    p.add_argument("--verbose", action="store_true", help="DEBUG 日志")
+    args = p.parse_args(argv)
+    logging.basicConfig(stream=sys.stderr,
+                        level=logging.DEBUG if args.verbose else logging.INFO,
+                        format="%(levelname)s %(name)s: %(message)s")
+
+    try:
+        with open(args.script, encoding="utf-8") as f:
+            source = f.read()
+    except OSError as e:
+        logging.error("无法读取脚本: %s", e)
+        return 2
+
+    try:
+        text, warnings = compile_script(source, filename=args.script)
+    except CompileError as e:
+        logging.error("编译失败: %s", e)
+        return 2
+
+    for w in warnings:
+        logging.warning("%s", w)
+
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            f.write(text)
+        logging.info("written: %s (%d lines)", args.output,
+                     text.count("\n"))
+    else:
+        sys.stdout.write(text)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

mtc/mtc/dsl.py

@@ -0,0 +1,204 @@
+"""mtc DSL —— 命令式动作脚本（Python）→ 事件收集
+
+脚本即 .py，通过 exec(source, make_namespace(collector)) 执行，
+命名空间内注入两类函数：
+
+硬件声明（函数名 = .mt 块名，位置参数 = 表头列，严格一一对应）：
+    I2C("i2c-1", "/dev/i2c-1")
+    PCA9685("pca9685-0", "i2c-1", "0x40")
+    Servo("s1", 90, 0, 0, "pca9685-0", 0)   # name,max,min,offset,controller,channel
+    Speaker("spk", 2, 48000, 0.6, 5000, 20)
+    Camera("cam0", 640, 480, 30, 8)
+    MPU6050_BIND("imu0", "i2c-1", "0x68")
+    Alias("A", "angle")
+    register_block("ADS1115", ["name", "I2C", "addr"])  # 开放扩展
+
+时间轴指令（编译期求值，不直接出现在 .mt 行中）：
+    Action(dev, delta, dur)   # 相对运动：当前游标处注册，dur ms 内走 delta
+    SetTo(dev, angle, dur)    # 绝对运动（糖：delta = angle - 已注册目标值）
+    Delay(ms)                 # 游标推进固定量
+    Wait()                    # 游标推进到所有在途运动的最晚完成时刻（汇合）
+    Beep(freq, dur)           # 扬声器频率段（默认设备 spk）
+    Pose(dev, angle)          # 声明编译期初始姿态（默认 0，不产生运动段）
+
+dur/Delay 必须是 10 的倍数（.mt 栅格与 pybot 微步节拍均为 10ms）。
+"""
+
+from .timeline import STEP_MS, Channel, total_ms
+from .emit import emit_mt
+
+# 已知块 → 表头列（位置参数顺序；首列恒为 name）
+_BLOCK_SCHEMAS = {
+    "Alias": ["name", "alias"],
+    "I2C": ["name", "path"],
+    "PCA9685": ["name", "I2C", "address"],
+    "MPU6050_BIND": ["name", "I2C", "addr"],
+    "Speaker": ["name", "channels", "sample_rate", "volumn", "max_f", "min_f"],
+    "Servo": ["name", "max", "min", "offset", "controller", "channel"],
+    "Camera": ["name", "width", "height", "framerate", "capacity"],
+}
+
+
+class CompileError(Exception):
+    """脚本编译错误（携带可读信息，CLI 原样输出）"""
+
+
+class Collector:
+    """一次编译的全部状态：硬件块 + 通道时间轴 + 游标 + 告警"""
+
+    def __init__(self):
+        self.blocks = []        # [(block_name, columns, row_values)]
+        self.channels = {}      # {通道名(dev.param): Channel}（注册序）
+        self.cursor = 0.0       # 当前时间游标 ms（单调推进）
+        self.warnings = []
+
+    # ---------------- 硬件 ----------------
+
+    def add_block(self, block_name, columns, values):
+        self.blocks.append((block_name, columns, [str(v) for v in values]))
+
+    def device_names(self):
+        """已声明硬件变量名集合（每块首列恒为 name）"""
+        return {row[0] for _, _, row in self.blocks}
+
+    def first_speaker(self):
+        """第一个 Speaker 块声明的设备名（delay 节拍列所属），无则 None"""
+        for block_name, _, row in self.blocks:
+            if block_name == "Speaker":
+                return row[0]
+        return None
+
+    # ---------------- 时间轴 ----------------
+
+    def channel(self, name):
+        ch = self.channels.get(name)
+        if ch is None:
+            ch = self.channels[name] = Channel(name)
+        return ch
+
+    def check_device(self, dev):
+        if dev not in self.device_names():
+            raise CompileError(
+                f"设备 '{dev}' 未声明（先用 Servo/Speaker/插件块声明）")
+
+    def warn_overlaps(self):
+        for ch in self.channels.values():
+            self.warnings.extend(ch.overlap_warns)
+
+    # ---------------- 编译 ----------------
+
+    def compile(self):
+        """归一化 IR 并序列化为 .mt 文本，返回 (mt_text, warnings)"""
+        self.warn_overlaps()
+        active = [ch for ch in self.channels.values() if ch.segments]
+        t_total = total_ms(self.channels, self.cursor)
+        if not active and t_total <= 0:
+            raise CompileError("脚本没有任何动作（@Action 将为空）")
+        if self.first_speaker() is None:
+            self.warnings.append(
+                "无 Speaker 块：.mt 无 delay 节拍列，pybot 执行时行间隔"
+                "不等待（时间轴语义丢失，仅 --loop/解析场景可用）")
+        text = emit_mt(self.blocks, active, t_total,
+                       speaker=self.first_speaker())
+        return text, self.warnings
+
+
+def _check_dur(ms, what):
+    if float(ms) <= 0 or float(ms) % STEP_MS != 0:
+        raise CompileError(f"{what} 必须是正的 {STEP_MS} 的倍数，got {ms!r}")
+
+
+def make_namespace(collector):
+    """构建脚本 exec 命名空间（硬件函数 + 时间轴指令）"""
+    ns = {}
+    schemas = dict(_BLOCK_SCHEMAS)
+
+    def _make_block_fn(block_name, columns):
+        def fn(*args):
+            if len(args) != len(columns):
+                raise CompileError(
+                    f"{block_name}() 需要 {len(columns)} 个参数 "
+                    f"({', '.join(columns)})，got {len(args)}")
+            collector.add_block(block_name, columns, args)
+        fn.__name__ = block_name
+        return fn
+
+    for block_name, cols in schemas.items():
+        ns[block_name] = _make_block_fn(block_name, cols)
+
+    def register_block(block_name, columns):
+        """注册自定义块（插件扩展）：register_block("ADS1115", [...])"""
+        if not columns or columns[0] != "name":
+            raise CompileError("register_block: 首列必须是 name")
+        ns[block_name] = _make_block_fn(block_name, list(columns))
+
+    def _register(dev, param, value, dur, absolute):
+        collector.check_device(dev)
+        _check_dur(dur, f"{dev}.{param} 的 dur")
+        if param == "delay":
+            raise CompileError("spk.delay 列由编译器管理（恒 10），"
+                               "节拍请用 Delay()/Wait()")
+        ch = collector.channel(f"{dev}.{param}")
+        v0 = ch.target          # 重叠时基准 = 前段目标值（编译期确定）
+        v1 = float(value) if absolute else v0 + float(value)
+        ch.add(collector.cursor, float(dur), v0, v1)
+
+    def Action(dev, delta, dur, param="angle"):
+        """相对运动：dur ms 内走 delta（可正可负）"""
+        _register(dev, param, delta, dur, absolute=False)
+
+    def SetTo(dev, angle, dur, param="angle"):
+        """绝对运动：dur ms 内到达 angle"""
+        _register(dev, param, angle, dur, absolute=True)
+
+    def Delay(ms):
+        """游标推进固定量"""
+        _check_dur(ms, "Delay")
+        collector.cursor += float(ms)
+
+    def Wait():
+        """汇合：游标推进到所有在途运动的最晚完成时刻"""
+        busy = [ch.busy_until for ch in collector.channels.values()]
+        collector.cursor = max([collector.cursor] + busy)
+
+    def Beep(freq, dur, dev="spk"):
+        """扬声器频率段：dev.frequency 在 dur ms 内恒为 freq（阶跃段）
+
+        通道静止值设为 0：段前/段间空隙/段后回落 0 = 静音
+        （对齐 pybot speaker 静音语义：freq<=0 不出声仅保节拍）。
+        """
+        collector.check_device(dev)
+        _check_dur(dur, f"Beep({freq}) 的 dur")
+        ch = collector.channel(f"{dev}.frequency")
+        ch.rest = 0.0
+        ch.add(collector.cursor, float(dur), float(freq), float(freq))
+
+    def Pose(dev, angle, param="angle"):
+        """声明编译期初始姿态（不产生运动段；须在 Action 之前）"""
+        collector.check_device(dev)
+        ch = collector.channel(f"{dev}.{param}")
+        if ch.segments:
+            raise CompileError(
+                f"Pose({dev}) 必须在任何 Action 之前声明")
+        ch.set_initial(angle)
+
+    ns.update(Action=Action, SetTo=SetTo, Delay=Delay, Wait=Wait,
+              Beep=Beep, Pose=Pose, register_block=register_block)
+    return ns
+
+
+def compile_script(source, filename="<script>"):
+    """编译 DSL 脚本 → (mt_text, warnings)
+
+    脚本语法错误包装为 CompileError（携带文件/行号）。
+    """
+    collector = Collector()
+    ns = make_namespace(collector)
+    try:
+        code = compile(source, filename, "exec")
+        exec(code, ns)
+    except CompileError:
+        raise
+    except Exception as e:
+        raise CompileError(f"{filename}: {type(e).__name__}: {e}") from e
+    return collector.compile()

mtc/mtc/emit.py

@@ -0,0 +1,80 @@
+""".mt 序列化 —— 硬件块（依赖序/声明序）+ @Action 栅格矩阵
+
+输出契约（与 pybot parser 对齐）：
+    @块名 / @ 定界；行 0 表头；行尾 ';'；列间空格分隔；
+    @Action 表头为 '设备.参数' 长名（Q05 校验恰含一个 '.'），
+    末列 '<speaker>.delay' 恒 10（栅格节拍），无 Speaker 块则无此列。
+
+栅格行语义：t=10,20,…,T，行值为该 10ms 结束时刻的绝对姿态；
+pybot run() 对 delay=10 的行分解为 1 个微步且插值系数 1.0，
+即直接到位 —— 与栅格语义严格等价。
+"""
+
+from .timeline import STEP_MS
+
+
+def fmt_num(v):
+    """数值格式化：整数无小数点，小数保留至多 3 位（栅格插值值）"""
+    f = float(v)
+    if f == int(f):
+        return str(int(f))
+    return f"{f:.3f}".rstrip("0")
+
+
+def _fmt_block(lines, name, columns, rows):
+    lines.append(f"@{name}")
+    lines.append(" ".join(columns) + ";")
+    for row in rows:
+        lines.append(" ".join(str(v) for v in row) + ";")
+    lines.append("@")
+
+
+def emit_mt(blocks, active_channels, t_total, speaker=None):
+    """生成 .mt 全文
+
+    blocks:          [(block_name, columns, row_values_str)]（声明序）
+    active_channels: [Channel]（有运动段的通道，注册序）
+    t_total:         编译总时长 ms（10 的倍数）
+    speaker:         delay 节拍列所属设备名；None 则无节拍列
+    """
+    from .dsl import CompileError     # 避免环：dsl 依赖 emit
+
+    lines = []
+    merged = []                   # 相邻同名块合并为一个块多行（.mt 惯例）
+    for block_name, columns, row in blocks:
+        if merged and merged[-1][0] == block_name and merged[-1][1] == columns:
+            merged[-1][2].append(row)
+        else:
+            merged.append((block_name, columns, [row]))
+    for block_name, columns, rows in merged:
+        _fmt_block(lines, block_name, columns, rows)
+        lines.append("")          # 块间空行（MatrixSaver 风格）
+
+    delay_col = f"{speaker}.delay" if speaker else None
+    freq_col = f"{speaker}.frequency" if speaker else None
+    # pybot 契约：SpeakerVar.play 无条件读 frequency+delay 两键，
+    # delay 节拍列必须与同设备 frequency 列成对出现（std.mt 惯例：
+    # spk.F spk.delay；无发声需求时 frequency 恒 0，对齐 jump.mt 首行）
+    active_names = {ch.name for ch in active_channels}
+    fill_freq = bool(freq_col) and freq_col not in active_names
+
+    header = [ch.name for ch in active_channels]
+    if fill_freq:
+        header.append(freq_col)
+    if delay_col:
+        header.append(delay_col)
+    if not header:
+        raise CompileError("@Action 无列（既无运动通道也无 Speaker 节拍列）")
+
+    n = int(round(t_total / STEP_MS))
+    rows = []
+    for k in range(1, n + 1):
+        t = k * STEP_MS
+        row = [fmt_num(ch.value_at(t)) for ch in active_channels]
+        if fill_freq:
+            row.append("0")
+        if delay_col:
+            row.append(str(STEP_MS))
+        rows.append(row)
+    _fmt_block(lines, "Action", header, rows)
+    return "\n".join(lines) + "\n"

mtc/mtc/timeline.py

@@ -0,0 +1,108 @@
+"""时间轴 IR —— 运动段、重叠截断、10ms 栅格化采样
+
+非阻塞时间轴模型（与 mtc 设计定稿一致）：
+    Action 在当前游标处注册运动段并立即返回，Delay/Wait 推进游标；
+    .mt 一行即全通道快照，段在不同通道上的重叠天然表达并发。
+
+栅格语义：格点 t=10,20,…,T，每行代表该 10ms 结束时刻的姿态。
+与 pybot 执行的等价性：delay=10 的行在 robot.run() 中分解为 1 个
+微步且插值系数 1.0（k=0,n=1），即直接到位 —— 栅格行语义严格成立。
+"""
+
+from dataclasses import dataclass, field
+
+STEP_MS = 10          # .mt 栅格步长，与 pybot run() 微步节拍一致
+
+
+@dataclass
+class Segment:
+    """一个运动段：[t0, t0+dur) 内从 v0 线性运动到 v1（绝对值）"""
+
+    t0: float
+    dur: float
+    v0: float
+    v1: float
+
+    @property
+    def end(self):
+        return self.t0 + self.dur
+
+    def value_at(self, t):
+        """t 时刻的值；段前取 v0、段后取 v1（保持语义）"""
+        if t <= self.t0:
+            return self.v0
+        if t >= self.end:
+            return self.v1
+        return self.v0 + (self.v1 - self.v0) * (t - self.t0) / self.dur
+
+
+@dataclass
+class Channel:
+    """单通道时间轴（如 s1.angle / spk.frequency）
+
+    段按注册序追加（游标单调 ⇒ t0 单调），因此任何时刻最多一个
+    未完结段（末尾段）。重叠规则：新段注册时若末尾段未完结，则
+    截断末尾段至 t0，新段基准取前段目标值 v1（编译期确定，不依赖
+    运行时实际姿态），由调用方在注册前取 target 作为新段 v0。
+
+    rest：静止值。None（舵机等姿态通道）段外保持前段目标值；
+    数值（如 frequency 通道 = 0）段前/段间空隙/段后统一回落该值
+    —— 对齐 pybot speaker 静音语义（freq<=0 不出声仅保节拍）。
+    """
+
+    name: str
+    initial: float = 0.0                # Pose() 声明的编译期初始姿态
+    rest: float = None                  # 静止值（None=保持前段目标值）
+    segments: list = field(default_factory=list)
+    overlap_warns: list = field(default_factory=list)   # 截断告警文本
+
+    @property
+    def target(self):
+        """已注册目标姿态（最后段 v1；无段取 initial）"""
+        return self.segments[-1].v1 if self.segments else self.initial
+
+    @property
+    def busy_until(self):
+        """最晚在途完成时刻"""
+        return self.segments[-1].end if self.segments else 0.0
+
+    def set_initial(self, angle):
+        if self.segments:
+            raise ValueError(
+                f"Pose({self.name}) 必须在任何 Action 之前声明")
+        self.initial = float(angle)
+
+    def add(self, t0, dur, v0, v1):
+        """注册运动段；与未完结末尾段重叠时截断之并记录告警"""
+        if self.segments and self.segments[-1].end > t0:
+            prev = self.segments[-1]
+            self.overlap_warns.append(
+                f"{self.name}: 段 [{prev.t0:g},{prev.end:g}) 与新段 "
+                f"[{t0:g},{t0 + dur:g}) 重叠，前段截断至 {t0:g}ms "
+                f"(新段基准取前段目标值 {prev.v1:g})")
+            prev.dur = t0 - prev.t0     # t0/t0 均为 10 倍数，截断后仍对齐栅格
+            if prev.dur <= 0:
+                self.segments.pop()
+        self.segments.append(Segment(t0, dur, v0, v1))
+
+    def _rest_or(self, v):
+        """段外取值：设定了 rest 则回落静止值，否则保持前段目标值"""
+        return self.rest if self.rest is not None else v
+
+    def value_at(self, t):
+        """格点采样：段内插值；段前/段间空隙/段后按 rest 规则取值"""
+        if not self.segments:
+            return self._rest_or(self.initial)
+        prev_v1 = self.initial
+        for seg in self.segments:
+            if t <= seg.t0:
+                return self._rest_or(prev_v1)      # 段前（含段间空隙）
+            if t <= seg.end:
+                return seg.value_at(t)             # 段内（端点连续）
+            prev_v1 = seg.v1
+        return self._rest_or(prev_v1)              # 全部段后
+
+
+def total_ms(channels, cursor):
+    """编译总时长：所有通道最晚完成时刻与游标的最大值"""
+    return max([ch.busy_until for ch in channels.values()] + [cursor])

mtc/tests/conftest.py

@@ -0,0 +1,25 @@
+"""pytest 公共配置：mtc 根入 sys.path；pybot parser 独立加载（绕包 __init__）
+
+Windows 开发机无 fcntl：import pybot 会经 robot.py → hd/i2c.py 触发
+fcntl 导入失败。e2e 仅需 MatrixParser，而 parser.py 只依赖 logging，
+用 spec_from_file_location 独立加载即可（与 pybot tests/conftest.py
+的符号链接 fallback 同属 Windows 兼容层）。
+"""
+
+import importlib.util
+import sys
+from pathlib import Path
+
+MTC_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(MTC_ROOT))
+
+PYBOT_PARSER = MTC_ROOT.parent / "pybot" / "pybot" / "parser.py"
+
+
+def load_pybot_parser():
+    """独立加载 pybot/parser.py（不触发 pybot/__init__ 的硬件链）"""
+    spec = importlib.util.spec_from_file_location(
+        "pybot_parser_standalone", PYBOT_PARSER)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod

mtc/tests/test_dsl.py

@@ -0,0 +1,127 @@
+"""DSL 收集测试：硬件声明 / 时间轴指令 / 校验规则"""
+
+import pytest
+
+from mtc.dsl import Collector, CompileError, compile_script, make_namespace
+
+
+def run(source):
+    """exec 脚本并返回 collector"""
+    c = Collector()
+    exec(compile(source, "<test>", "exec"), make_namespace(c))
+    return c
+
+
+# ---------------- 硬件声明 ----------------
+
+def test_hw_blocks_collected_in_order():
+    c = run('I2C("i2c-1", "/dev/i2c-1")\n'
+            'Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Servo("s2", 180, 0, 0, "pca9685-0", 1)\n')
+    assert [b[0] for b in c.blocks] == ["I2C", "Servo", "Servo"]
+    assert c.blocks[1][2] == ["s1", "90", "0", "0", "pca9685-0", "0"]
+    assert c.device_names() == {"i2c-1", "s1", "s2"}
+
+
+def test_hw_block_arity_error():
+    with pytest.raises(CompileError, match="需要 6 个参数"):
+        run('Servo("s1", 90, 0)\n')
+
+
+def test_register_block_extension():
+    c = run('register_block("ADS1115", ["name", "I2C", "addr"])\n'
+            'ADS1115("ads0", "i2c-1", "0x48")\n')
+    assert c.blocks[0][0] == "ADS1115"
+    assert c.blocks[0][1] == ["name", "I2C", "addr"]
+
+
+def test_register_block_requires_name_first():
+    with pytest.raises(CompileError, match="首列必须是 name"):
+        run('register_block("Bad", ["addr"])\n')
+
+
+# ---------------- 时间轴指令 ----------------
+
+def test_action_delay_wait_cursor():
+    c = run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Servo("s2", 90, 0, 0, "pca9685-0", 1)\n'
+            'Action("s1", 10, 100)\n'
+            'Delay(50)\n'
+            'Action("s2", 20, 50)\n'
+            'Wait()\n')
+    assert c.cursor == 100.0           # Wait 推进到最晚完成时刻
+    assert c.channels["s1.angle"].segments[0].v1 == 10
+    assert c.channels["s2.angle"].segments[0].t0 == 50
+
+
+def test_action_relative_accumulates():
+    c = run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Action("s1", 10, 100)\n'
+            'Wait()\n'
+            'Action("s1", 10, 100)\n')
+    segs = c.channels["s1.angle"].segments
+    assert (segs[1].v0, segs[1].v1) == (10, 20)   # 相对叠加在前段目标值上
+
+
+def test_setto_absolute():
+    c = run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Pose("s1", 45)\n'
+            'SetTo("s1", 90, 100)\n')
+    seg = c.channels["s1.angle"].segments[0]
+    assert (seg.v0, seg.v1) == (45, 90)
+
+
+def test_beep_registers_frequency_channel():
+    c = run('Speaker("spk", 2, 48000, 0.6, 5000, 20)\n'
+            'Beep(1000, 50)\n')
+    assert "spk.frequency" in c.channels
+    assert c.channels["spk.frequency"].segments[0].v1 == 1000
+
+
+# ---------------- 校验 ----------------
+
+def test_action_undeclared_device_rejected():
+    with pytest.raises(CompileError, match="未声明"):
+        run('Action("s1", 10, 100)\n')
+
+
+def test_dur_must_be_positive_multiple_of_10():
+    with pytest.raises(CompileError, match="10 的倍数"):
+        run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Action("s1", 10, 15)\n')
+    with pytest.raises(CompileError, match="10 的倍数"):
+        run('Delay(5)\n')
+
+
+def test_delay_column_is_reserved():
+    with pytest.raises(CompileError, match="编译器管理"):
+        run('Speaker("spk", 2, 48000, 0.6, 5000, 20)\n'
+            'Action("spk", 10, 100, param="delay")\n')
+
+
+def test_pose_after_action_rejected():
+    with pytest.raises(CompileError, match="Action 之前"):
+        run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'Action("s1", 10, 100)\n'
+            'Pose("s1", 45)\n')
+
+
+def test_empty_script_rejected():
+    with pytest.raises(CompileError, match="没有任何动作"):
+        compile_script('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n')
+
+
+def test_python_loop_and_math_work():
+    """Python DSL 红利：for 循环与数学运算直接可用"""
+    c = run('Servo("s1", 90, 0, 0, "pca9685-0", 0)\n'
+            'for i in range(4):\n'
+            '    Action("s1", 5 if i % 2 == 0 else -5, 20)\n'
+            '    Wait()\n')
+    segs = c.channels["s1.angle"].segments
+    assert len(segs) == 4
+    assert [s.v1 for s in segs] == [5, 0, 5, 0]
+
+
+def test_syntax_error_wrapped():
+    with pytest.raises(CompileError, match="SyntaxError"):
+        compile_script("def broken(:\n")

mtc/tests/test_e2e.py

@@ -0,0 +1,64 @@
+"""端到端：mtc 编译产物 → pybot MatrixParser 解析断言
+
+验证闭环：编译产物必须被 pybot 零修改解析（列数一致、Q05 表头
+'设备.参数' 校验、栅格行数与数值逐一比对）。
+"""
+
+from mtc.dsl import compile_script
+from tests.conftest import load_pybot_parser
+from tests.test_emit import EXAMPLE
+
+
+def _parse(mt_text):
+    parser_mod = load_pybot_parser()
+    parser = parser_mod.MatrixParser(mt_text)
+    objects = []
+    while True:
+        obj = parser.parse()
+        if obj is None:
+            break
+        objects.append(obj)
+    return objects
+
+
+def test_compiled_mt_parses_with_pybot():
+    objs = _parse(compile_script(EXAMPLE)[0])
+    names = [o.name for o in objs]
+    assert names == ["Servo", "Speaker", "Action"]
+    action = objs[names.index("Action")]
+    assert action.size == 11           # 表头 + 10 栅格行
+    assert action.col == 4             # s1/s2 + spk.frequency + spk.delay
+    for row in action.values:          # 列数一致（DoesNotSync 不触发）
+        assert len(row) == action.col
+
+
+def test_compiled_action_grid_values():
+    objs = _parse(compile_script(EXAMPLE)[0])
+    action = [o for o in objs if o.name == "Action"][0]
+    assert action.values[0] == ["s1.angle", "s2.angle",
+                                "spk.frequency", "spk.delay"]
+    grid = action.values[1:]
+    assert [r[0] for r in grid] == [str(i) for i in range(1, 11)]
+    assert [r[1] for r in grid] == ["0"] * 5 + ["4", "8", "12", "16", "20"]
+    assert {r[2] for r in grid} == {"0"}       # 无 Beep：frequency 恒 0
+    assert {r[3] for r in grid} == {"10"}
+
+
+def test_compiled_mt_roundtrips_through_pybot():
+    """编译产物经 pybot 解析→序列化→再解析等价（roundtrip 自检）"""
+    import io
+    parser_mod = load_pybot_parser()
+    objs = _parse(compile_script(EXAMPLE)[0])
+    out = io.StringIO()
+    parser_mod.MatrixSaver(out).save(objs)
+    objs2 = _parse(out.getvalue())
+    assert [(a.name, a.values) for a in objs] == \
+           [(b.name, b.values) for b in objs2]
+
+
+def test_q05_header_contract_holds():
+    """@Action 全部列名恰含一个 '.'（pybot robot._validate_action 契约）"""
+    objs = _parse(compile_script(EXAMPLE)[0])
+    action = [o for o in objs if o.name == "Action"][0]
+    for col in action.values[0]:
+        assert col.count(".") == 1

mtc/tests/test_emit.py

@@ -0,0 +1,97 @@
+"""emit 测试：数值格式化 / .mt 文本结构 / 用户设计示例逐字比对"""
+
+from mtc.dsl import compile_script
+from mtc.emit import fmt_num
+
+# 用户设计示例（修正后）：非阻塞时间轴，s2 第 6 行起步
+EXAMPLE = '''
+Servo("s1", 180, 0, 0, "pca9685-0", 0)
+Servo("s2", 180, 0, 0, "pca9685-0", 1)
+Speaker("spk", 2, 48000, 0.6, 5000, 20)
+Action("s1", 10, 100)
+Delay(50)
+Action("s2", 20, 50)
+'''
+
+EXPECTED_MT = """\
+@Servo
+name max min offset controller channel;
+s1 180 0 0 pca9685-0 0;
+s2 180 0 0 pca9685-0 1;
+@
+
+@Speaker
+name channels sample_rate volumn max_f min_f;
+spk 2 48000 0.6 5000 20;
+@
+
+@Action
+s1.angle s2.angle spk.frequency spk.delay;
+1 0 0 10;
+2 0 0 10;
+3 0 0 10;
+4 0 0 10;
+5 0 0 10;
+6 4 0 10;
+7 8 0 10;
+8 12 0 10;
+9 16 0 10;
+10 20 0 10;
+@
+"""
+
+
+def test_example_matches_user_design_exactly():
+    text, warnings = compile_script(EXAMPLE)
+    assert warnings == []
+    assert text == EXPECTED_MT
+
+
+def test_fmt_num_integer_and_decimal():
+    assert fmt_num(10.0) == "10"
+    assert fmt_num(0) == "0"
+    assert fmt_num(-3.0) == "-3"
+    assert fmt_num(1.666666) == "1.667"
+    assert fmt_num(2.500) == "2.5"
+
+
+def test_non_integer_step_values():
+    """10°/6 步：栅格值保留 3 位小数（pybot parse_mt float 可解析）"""
+    text, _ = compile_script(
+        'Servo("s1", 180, 0, 0, "pca9685-0", 0)\n'
+        'Speaker("spk", 2, 48000, 0.6, 5000, 20)\n'
+        'Action("s1", 10, 60)\n')
+    rows = [l for l in text.splitlines() if l.endswith("10;")]
+    assert len(rows) == 6
+    assert rows[0].startswith("1.667 ")
+    assert rows[-1].startswith("10 ")
+
+
+def test_no_speaker_no_delay_column_and_warns():
+    text, warnings = compile_script(
+        'Servo("s1", 180, 0, 0, "pca9685-0", 0)\n'
+        'Action("s1", 10, 20)\n')
+    assert any("无 Speaker" in w for w in warnings)
+    assert "s1.angle;" in text        # 表头无 frequency/delay 列
+    assert "frequency" not in text
+
+
+def test_beep_gap_falls_back_to_zero_silence():
+    text, _ = compile_script(
+        'Speaker("spk", 2, 48000, 0.6, 5000, 20)\n'
+        'Beep(1000, 30)\n'
+        'Delay(50)\n')               # T = max(段尾30, 游标50) = 50 → 5 行
+    lines = text.splitlines()
+    assert "spk.frequency spk.delay;" in lines
+    rows = [l for l in lines if l.endswith(" 10;")]
+    # 段内 1000；段后回落 0 = 静音（对齐 pybot speaker freq<=0 语义）
+    assert [r.split()[0] for r in rows] == ["1000", "1000", "1000", "0", "0"]
+
+
+def test_pure_delay_script_fills_freq_zero_column():
+    """纯延时：自动补 spk.frequency 恒 0 列（SpeakerVar.play 两键契约）"""
+    text, _ = compile_script(
+        'Speaker("spk", 2, 48000, 0.6, 5000, 20)\n'
+        'Delay(50)\n')
+    assert "spk.frequency spk.delay;" in text
+    assert text.count("0 10;") == 5

mtc/tests/test_timeline.py

@@ -0,0 +1,91 @@
+"""时间轴 IR 测试：Segment 插值 / Channel 重叠截断 / 采样保持语义"""
+
+import pytest
+
+from mtc.timeline import Channel, Segment, total_ms
+
+
+# ---------------- Segment ----------------
+
+def test_segment_value_at_endpoints_and_midpoint():
+    s = Segment(t0=50, dur=100, v0=10, v1=30)
+    assert s.end == 150
+    assert s.value_at(50) == 10        # 段起点取 v0
+    assert s.value_at(100) == 20       # 中点线性
+    assert s.value_at(150) == 30       # 段尾取 v1
+    assert s.value_at(0) == 10         # 段前保持 v0
+    assert s.value_at(999) == 30       # 段后保持 v1
+
+
+# ---------------- Channel ----------------
+
+def test_channel_target_defaults_to_initial():
+    ch = Channel("s1.angle")
+    assert ch.target == 0.0 and ch.busy_until == 0.0
+    ch.set_initial(45)
+    assert ch.target == 45.0
+
+
+def test_channel_set_initial_after_segment_rejected():
+    ch = Channel("s1.angle")
+    ch.add(0, 100, 0, 10)
+    with pytest.raises(ValueError):
+        ch.set_initial(45)
+
+
+def test_channel_overlap_truncates_prev_and_warns():
+    """重叠：前段截断至新段 t0，基准取前段目标值（由调用方传 v0）"""
+    ch = Channel("s1.angle")
+    ch.add(0, 100, 0, 10)              # [0,100) 0→10
+    v0 = ch.target                     # 10（前段目标值）
+    ch.add(50, 100, v0, v0 + 10)       # [50,150) 10→20
+    assert len(ch.segments) == 2
+    assert ch.segments[0].dur == 50    # 前段截断至 t0=50
+    assert ch.segments[0].end == 50
+    assert ch.overlap_warns and "截断" in ch.overlap_warns[0]
+    # 截断点连续：前段尾值 == 新段起点值
+    assert ch.value_at(50) == 10
+    assert ch.value_at(100) == 15
+
+
+def test_channel_value_at_no_segment_uses_initial():
+    ch = Channel("s1.angle")
+    ch.set_initial(30)
+    assert ch.value_at(10) == 30
+    assert ch.value_at(9999) == 30
+
+
+def test_channel_value_at_holds_last_target_after_all_segments():
+    ch = Channel("s1.angle")
+    ch.add(0, 100, 0, 10)
+    ch.add(200, 100, 10, 5)
+    assert ch.value_at(150) == 10      # 段间空隙保持前段目标值
+    assert ch.value_at(100000) == 5    # 全部完结后保持最后目标值
+
+
+def test_channel_rest_value_falls_back_in_gaps():
+    """frequency 型通道（rest=0）：段前/段间空隙/段后统一回落静止值"""
+    ch = Channel("spk.frequency", rest=0.0)
+    ch.add(20, 30, 1000, 1000)         # [20,50) 阶跃段
+    ch.add(70, 20, 2000, 2000)         # [70,90)
+    assert ch.value_at(10) == 0        # 首段之前
+    assert ch.value_at(30) == 1000     # 段内
+    assert ch.value_at(50) == 1000     # 段尾端点仍属段内
+    assert ch.value_at(60) == 0        # 段间空隙回落 rest
+    assert ch.value_at(80) == 2000
+    assert ch.value_at(999) == 0       # 全部段后回落 rest
+
+
+def test_channel_rest_does_not_affect_in_segment_value():
+    """rest 仅作用段外：舵机通道设 rest 时段内插值不受影响"""
+    ch = Channel("s1.angle", rest=0.0)
+    ch.add(0, 100, 10, 20)
+    assert ch.value_at(50) == 15
+
+
+def test_total_ms_takes_max_of_channels_and_cursor():
+    a, b = Channel("a"), Channel("b")
+    a.add(0, 100, 0, 1)
+    b.add(50, 100, 0, 1)
+    assert total_ms({"a": a, "b": b}, cursor=0) == 150
+    assert total_ms({"a": a, "b": b}, cursor=500) == 500