7.1 总装车间：开发工具与工程栈

7.1 总装车间：开发工具与工程栈

本节摘要：舱段是零件，工程栈是车间。本节按四层盘点智能体的工程栈——仿真与测试设施、中间件与框架、舱段实现、观测栈——给出"与舱段架构对齐"的选型判据而非热度榜，讲小步开发循环与版本配置管理如何保证"每一架出厂飞行器都能精确复现"，并交付装配根代码骨架。

机器人学史上有个漫长的重复造轮子时期：几乎每个实验室都在自己重写导航、避障与通信，同一个"感知-规划-行动"循环被以几十种姿势反复实现。共享中间件出现之后，行业才把精力从造轮子挪到造飞行器。今天轮到智能体工程面对同样的分岔：前六章设计好的舱段，用什么车间装配？本节不带货任何具体产品——选型判据比选型结论值钱，判据对了，货架上的商品怎么换都不迷路。

工程栈的四层盘点

智能体工程栈自下而上分四层，每层都有明确的"它替你解决了什么"：

选型的头号判据写在最后一列：与舱段架构对齐。一个再流行的框架，若把调度循环藏进黑盒、不容许你实现 1.2 节的节拍预算，就是在跟你的架构打架；一个再朴素的中间件，只要消息带时间戳、支持回放，就与全册的纪律天然亲和。第二判据是退出成本：框架会不会把舱段实现绑死在自己的基类上——绑得越深，将来搬迁越疼。本册一路坚持的接口优先风格（依赖抽象清单而非具体类），正是为退出留门。

开发流程：小步循环与可复现

装配流程按小步循环推进：设计（改哪个舱段的哪份契约）→ 实现（带着契约测试写）→ 仿真（在仿真环境过剧本与故障注入）→ 实机（限速、限范围验证）→ 回到设计。循环的关键阀门是仿真：实机验证昂贵且有风险，能仿真的绝不实机首试——这是 7.2 节的主题，流程上先把门。

可复现是总装车间的铁律：任何一架出厂的飞行器，都要能从版本库里精确重建——代码版本、配置版本、模型与参数版本、数据版本，四位一体地打标。做不到复现，调试就成了猜谜：你修的和你测的可能根本不是同一架机器。配置管理上的实用纪律是配置即数据：节拍预算、阈值带、权限矩阵、清单，全部落成可版本化的数据文件，改参数等于改代码一样走评审与回归。

算法实现：装配根

工程栈的装配最终落在一个组合根上——所有抽象在此绑定到具体实现，全机只有此处知道"具体用的是谁"：

def build_agent(config):
    """装配根：全机唯一知道具体实现的地方。

    config 来自版本化配置文件，含栈选型与全部参数。
    """
    # 观测栈最先就位：后面所有舱段都要往里写
    audit = config.observation_stack.build_audit()
    log_store = config.observation_stack.build_log(audit)

    # 黑匣子舱：持久化优先于一切有状态舱段（第 5 章）
    memory = MemoryBay(
        log_store=log_store,
        knowledge_base=config.kb.build(log_store))

    # 感知舱：探头清单与融合参数全部来自配置
    sensors = [spec.build() for spec in config.sensor_array]
    perception = PerceptionCabin(sensors,
                                 noise_model=config.noise_model)

    # 规划舱：程序库与搜索权重按空域属性选配
    planning = PlanningCabin(
        method_lib=config.method_lib,
        search_weights=config.search_weights)

    # 行动舱：执行器接口与复飞阶梯
    executor = ExecutorInterface(config.actuator.build())
    tower = TowerChannel(board=None)      # 状态板先建，塔台后接

    board = FlightBoard(stale_after=config.stale_after)
    tower.board = board                   # 单一事实源接进塔台

    agent = AgentCore(perception, planning,
                      ActionCabin(executor, tower), memory, board)
    smoke_test(agent)                     # 出厂前空转冒烟（1.1 节）
    return agent
​

装配根的价值在换件时刻：换仿真器、换中间件、换某个舱段实现，改的是配置与绑定，不是舱段代码。它也是测试的支点——7.2 节的仿真测试，本质就是用同一份装配根把真实执行器换成 mock、把真实探头换成录制数据。

出厂冒烟与版本打标的骨架如下：

def smoke_test(agent, ticks=32):
    """出厂冒烟：空转若干拍，校验接线与状态板流动。"""
    assert agent.board is not None, "单一事实源未接线"
    for _ in range(ticks):
        agent.run_tick(FakeWorld())           # 假数据空转
    assert agent.board.read("belief"), "信念未更新"
    assert agent.board.read("behavior"), "行为未指派"
    return True

def stamp_build(code_ver, config_ver, model_ver, data_ver):
    """四位一体打标：可复现是调试与验收的前提。"""
    stamp = {"code": code_ver, "config": config_ver,
             "model": model_ver, "data": data_ver,
             "t": time.strftime("%Y%m%d%H%M%S")}
    audit_log("build_stamp", stamp)           # 入版本档案
    return stamp
​

联调与故障排查

栈的联调从冒烟测试开始：装配根每次构建后自动空转若干拍，校验各舱段接线与状态板流动；再跑栈级契约——消息带时间戳、日志可回放、配置变更走版本，三条纪律在栈层断言。按症状排查：**"在我机器上没问题"**是可复现失守，查四位版本标是否齐全；栈升级后节拍紊乱是中间件把调度藏进了黑盒，把频率预算显式交还给配置层；日志缺失断片查观测栈的采样策略与落盘路径——观测栈自身也在第 5 章的持久化纪律管辖之内。

💡 关键直觉：工程栈选型是在给未来三年的自己挑同事。热度会退，接口会老化，唯一长期有效的标准是：它是否让你的架构更清晰、你的纪律更容易执行。

本节要点回顾

• 四层栈：仿真测试设施、中间件框架、舱段实现、观测栈，各层"替你解决什么"要能说出口。
• 对齐优于热度：选型看是否尊重频率分层、单一事实源与日志契约，看退出成本高低。
• 可复现铁律：代码、配置、模型、数据四位一体打标；配置即数据，改参数走评审回归。
• 装配根唯一：具体实现只在组合根绑定，换件与测试都以它为支点。
• 冒烟先于一切：每次构建空转校验接线，栈级三条契约在栈层断言。

车间就绪，飞行器可以进风洞了。下一节把仿真、测试与调试的方法论一次讲透：怎么让失败变成资产。