4.1 舵面指令：执行器接口与动作原语

4.1 舵面指令：执行器接口与动作原语

本节摘要：行动舱的门面是执行器接口与动作原语。本节按五段展开：从"指令发了没人管"的事故现场出发，定义原子、可校验、幂等、带期限回执的原语四纪律，讲清指令层与伺服层的分工及比例-积分-微分控制的底座角色，最后交付统一的动作接口表白名单与台架联调法。

「执行器」在项目汇报里常被排到最后一个词，仿佛指令一发出事情就自然办成了。真实的事故复盘不长这样：某分拣机器人的抓取指令因通信抖动重复送达，夹爪开合两次，货物掉落；某软件智能体的下单接口在超时后重发，结果下了双份订单。病灶同源——把"指令已发送"当成了"动作已完成"，且指令本身没有防重发的铠甲。规划舱把动作序列交给行动舱之后，能不能不折不扣落地，全看本节定义的这套接口纪律。

飞行问题：指令与执行之间隔着什么

从导航计算机的航线到真实世界的变化，中间隔着三层：指令层（做什么——选哪个动作、带什么参数）、伺服层（怎么稳——把目标量连续逼近到位）、执行器本体（电机、液压、夹爪，或软件世界的接口调用）。规划舱的输出是第一步的输入，而事故高发区恰在三者交界的模糊地带：指令重发没有幂等保护、参数越界没人拦截、执行器卡死没有期限、做没做成没有回执。每一类空洞后面都躺着一类事故，本节的四条纪律逐一对应。

舱段设计：原语四纪律

动作原语是行动舱的最小执行单元，四条纪律缺一不可。原子性：一条原语只做一件事，"抓取并转运"不是原语而是程序（回 3.3 节展开）。参数校验：越界参数在接口门口拦下——目标点在障碍内、速度档不存在、载荷超限，都在进入执行器之前否决，带着清晰错误码返回，绝不带病下机。幂等性：同一指令重发不产生二次效果——用指令唯一号去重，执行器侧记"已处理的最近指令号"。期限与回执：每条指令自带超时期限，执行结果以回执返回（成功、失败、原因码、实际达成量），回执写进状态板供监控与日志消费。

物理执行器与软件执行器共用这套纪律，正是本册"同构"主张的体现：对外部系统的接口调用就是一对看不见的舵面，4.4 节的塔台、第 6 章的外挂都沿用同一张契约。

算法实现：接口骨架与伺服底座

import time, itertools
from dataclasses import dataclass

@dataclass
class Command:
    """动作指令：唯一号、原语名、参数、期限。"""
    seq: int
    name: str
    params: dict
    timeout_s: float = 5.0

@dataclass
class Receipt:
    """结构化回执：结果与达成量，绝不返回裸布尔。"""
    seq: int
    ok: bool
    reason: str = ""
    achieved: dict = None

class ExecutorInterface:
    """原语接口表：白名单即行动舱的全部合法入口。"""

    PRIMITIVES = {                    # 原语名 -> (参数校验器, 执行函数)
        "move_to":  (validate_target, servo_move),
        "grasp":    (validate_grip,   servo_grip),
        "release":  (validate_grip,   servo_release),
        "wait":     (validate_delay,  do_wait),
    }

    def __init__(self, actuator):
        self.actuator = actuator
        self._seq = itertools.count(1)
        self.last_done = -1              # 幂等去重：已处理的最近指令号

    def submit(self, name, params):
        if name not in self.PRIMITIVES:
            return Receipt(-1, False, f"未知原语：{name}")
        validator, runner = self.PRIMITIVES[name]
        if not validator(params):        # 校验在门口，不带病下机
            return Receipt(-1, False, "参数校验失败")
        cmd = Command(next(self._seq), name, params)
        return self._dispatch(cmd, runner)

    def _dispatch(self, cmd, runner):
        if cmd.seq <= self.last_done:    # 重发去重：幂等保护
            return Receipt(cmd.seq, True, "重复指令，已忽略")
        deadline = time.monotonic() + cmd.timeout_s
        result = runner(self.actuator, cmd, deadline)
        self.last_done = cmd.seq
        return result

def servo_move(actuator, cmd, deadline, kp=2.0, ki=0.5, kd=0.1):
    """伺服层最小骨架：比例-积分-微分逼近目标位。"""
    integral = derivative = 0.0
    prev_err = actuator.position_error(cmd.params["target"])
    while (err := actuator.position_error(cmd.params["target"])) > 0.01:
        if time.monotonic() > deadline:  # 期限先于收敛：如实上报
            return Receipt(cmd.seq, False, "执行超时",
                           {"err": err})
        integral += err
        derivative = err - prev_err
        u = kp * err + ki * integral + kd * derivative
        actuator.drive(u)
        prev_err = err
    return Receipt(cmd.seq, True, "到位", {"err": err})
​

比例-积分-微分控制值得多说一句，因为它是伺服层最常青的底座：比例项按当前偏差出力（偏差越大劲越大），积分项累计历史偏差清零静差（总有那么一点过不去的余量靠它磨平），微分项看偏差变化趋势提前收力（防过冲震荡）。三项各治一种病，也各有一种过量副作用——比例过大震荡、积分过大超调、微分放大噪声。理解这三项，就理解了为什么执行器"稳不稳"是个可调、可测、可验收的工程量，而不是玄学。

联调测试：台架先行

原语接口的联调在台架上做，不接真实任务：每条原语单独过一遍正常流、边界流（参数取上下界）、异常流（执行器断联、超时到期），回执字段逐项核对。幂等性专项——同一指令连发多遍，效果只发生一次；校验专项——越界参数全部被门口拦截且错误码可读。台架全绿，才有资格进 4.2 节的执行链联调。

幂等与回执的台架专项也值得一段可复用的测试骨架：

def test_idempotency(executor, primitive, params):
    """幂等专项：同一指令连发多遍，效果只发生一次。"""
    first = executor.submit(primitive, params)
    repeats = [executor.submit(primitive, params)
               for _ in range(3)]
    return {"first_ok": first.ok,
            "deduped": all(r.ok and "重复" in r.reason
                           for r in repeats)}

def test_validation_gate(executor, bad_params_list):
    """校验专项：越界参数必须被门口拦下且带错误码。"""
    blocked = []
    for bad in bad_params_list:
        r = executor.submit("move_to", bad)
        if not r.ok and r.reason:
            blocked.append(bad)
    return {"blocked_all": len(blocked) == len(bad_params_list),
            "blocked": blocked}
​

故障排查：从抖动到假完成

执行抖动（舵面来回找不准）查比例增益是否过大、微分项是否放大了量测噪声——先降噪声（回 2.2 节调理）再降增益；失步（指令与实际动作脱节）查通信层重发与去重的配合，回执号对不上指令号是惯犯；假完成（回执说成功、实际没做到）查执行函数是否把"指令送达"当"动作完成"，伺服循环的收敛阈值要对应真实物理容差；静差磨不平是积分项被人为清零过频，或执行器物理饱和——前者放开积分、后者认账换方案。

⚠️ 常见坑：为了省事让原语带隐式副作用。"grasp 顺手记录库存"看着高效，实际上把执行器接口变成了数据库写入点，幂等与重试的语义全被打乱。副作用归副作用自己的通道，接口保持纯粹。

本节要点回顾

• 三层分界：指令层管做什么、伺服层管怎么稳、执行器本体管物理落地，事故高发在交界地带。
• 原语四纪律：原子性、参数校验、幂等、期限回执，逐一对应可复现的事故类型；软件接口调用与物理舵面同构。
• 伺服底座：比例治当下、积分治历史、微分治趋势，三项各有副作用，"稳"是可验收的工程量。
• 台架先行：正常、边界、异常三流过架，幂等与校验做专项，全绿才进执行链。
• 接口纯粹：原语不带隐式副作用，重试与幂等的语义才有立足点。

指令合格了，但"发出去"不等于"做成了"。下一节装上执行监控：状态机、阈值、看门狗与验收谓词，照亮发出与完成之间的黑暗地带。