6.1 挂架标准：工具接口与模块化解耦

6.1 挂架标准：工具接口与模块化解耦

本节摘要：外挂能不能安全挂上，取决于挂架是否标准、模块是否解耦。本节给出工具清单的必备字段（参数模式、权限等级、超时预算、副作用标注），把模块化与解耦的工程原则——依赖单向、接口稳定、信息隐藏——落到挂架设计上，并交代适配器模式与解耦的代价：接口稳定是要用版本纪律养出来的。

「挂载点」是航空工程里的老词：机翼下的每个挂架都有承重、供电与信号的标准接口，任何厂家的外挂件只要符合规格就能挂上，不必改装飞机。软件世界花了更长时间才学会这件事——早期机器人把每个技能焊死在主控程序里，加一个能力就要开膛破肚，改错一处全机返工。工具调用要规模化，第一件事不是学怎么调，而是定挂架标准：让"外挂"与"飞行器"之间的接触面标准化，让解耦从口号变成接口。

为什么解耦：换外挂不停飞

模块化与解耦的价值在换件时刻显形。外部系统会改版、会下线、会被替换——没有标准挂架时，每次变动都是手术；有挂架时，只是换件。落到工程原则上是三条，本节把它们钉在挂架设计上：

• 依赖单向：飞行器依赖工具清单，工具不依赖飞行器内部——外挂不知道状态板长什么样，它只接收请求、返回结果。反向依赖（工具回调飞行器内部字段）是耦合毒瘤，一出现就要掐。
• 接口稳定：挂架尺寸不许随意变。工具清单是飞行器与外挂之间的契约，契约的变更走版本化——新增可选字段不算破坏，删除或改义字段必须升主版本并留旧版过渡期。
• 信息隐藏：外挂的内部实现（数据库表结构、服务内部路由）对飞行器不可见。飞行器只需要知道"给什么参数、回什么结果、多慢、多险"。

这三条的代价要提前认账：解耦不是免费的——多一层适配就多一层转换开销与故障面，接口稳定要靠版本纪律与兼容性测试长期供养。为只有两三个调用的内部工具上全套挂架，是用大炮打蚊子；判断的分界线在变更频率与替换可能性——预期会换会变的外部依赖，值得全套挂架；稳定如疆界的内部函数，直接调用反而干净。

工具清单：挂架上的登记表

挂架标准的核心交付物是工具清单（tool manifest）——飞行器认识一件外挂的全部依据：

from dataclasses import dataclass, field

@dataclass
class ToolManifest:
    """挂架登记表：飞行器认识一件外挂的全部依据。"""
    name: str                       # 唯一名：skill 命名空间.工具名
    version: str                    # 语义化版本：破坏性变更升主版
    description: str                # 一句话说清用途（供技能匹配）
    params_schema: dict             # 参数模式：类型、范围、必填
    permission: str                 # 权限等级：read / write / danger
    timeout_s: float                # 超时预算：调用方按此设期限
    idempotent: bool                # 是否幂等：决定重试策略
    side_effects: list = field(default_factory=list)
    # 副作用标注：写库、下单、发消息、移动实体——审计与确认用

def register_tool(registry, manifest, adapter):
    """挂装流程：清单审查 -> 参数模式验证 -> 入注册表。"""
    validate_schema(manifest.params_schema)      # 模式合法性
    if manifest.permission == "danger":
        require_dual_confirm(manifest)           # 危险件：预挂双确认
    registry.put(manifest.name, (manifest, adapter))
    audit_log("tool_registered", manifest.name,
              manifest.version)                  # 挂装也是事件

class Adapter:
    """适配器：把异构外部接口翻译到统一挂架。"""

    def __init__(self, manifest, transport):
        self.manifest = manifest
        self.transport = transport     # 对接外部系统的传输细节

    def call(self, params):
        # 门口校验：按清单模式拒绝带病参数
        errors = check_against_schema(params,
                                      self.manifest.params_schema)
        if errors:
            return {"ok": False, "reason": f"参数校验失败：{errors}"}
        raw = self.transport.send(
            self.translate(params),
            timeout=self.manifest.timeout_s)     # 期限随清单走
        return self.translate_back(raw)          # 回执也翻译成统一形制
​

清单的字段每一项都有用途：参数模式喂给调用前校验，权限等级喂给 6.3 的闸门，超时预算喂给 6.2 的点火时序，副作用标注喂给审计与人工确认，幂等标注决定重试能不能直接上。登记不全的外挂不许挂——这条铁律的成本是登记的麻烦，收益是后面三章少出的事故。

图：挂架接口标注——清单字段与消费方一一对应

契约测试的骨架值得照抄——它测的是承诺，不是实现：

def contract_test(manifest, adapter, samples):
    """契约测试：清单宣称的每一项都要实测对账。"""
    result = {"name": manifest.name, "violations": []}
    for params, expect in samples:            # 按参数模式构造样本
        r = adapter.call(params)
        if expect.ok and not r.get("ok"):
            result["violations"].append(f"宣称可用实失败:{params}")
        spent = r.get("spent", 0)
        if spent > manifest.timeout_s:
            result["violations"].append("耗时超清单预算")
    if manifest.permission == "read":
        if probe_side_effects(adapter, samples):
            result["violations"].append("宣称只读实有写入")
    return result
​

联调测试与故障排查

挂架的联调用契约测试：给每件外挂建一份"清单与真实行为"的比对用例——参数模式宣称的类型逐个试、宣称的超时压着测、副作用标注与实际日志对账。外部系统改版后，契约测试是最早报警的哨兵——它测的是承诺，不是实现细节。

按症状排查：接口漂移（外挂升级后调用成片失败）查主版本变更是否走了公告流程——适配器按旧契约翻译新接口是止血，按新契约重登清单是根治；清单与实际不符（宣称只读却在写库）以副作用对账为准，清单立即修正并回溯审计；适配器堆积（翻译层比业务还厚）通常是接口稳定原则没谈拢——与其养三层翻译，不如推动外挂侧出标准接口。

⚠️ 常见坑：把适配器当成垃圾桶。每次外部接口变化就往适配器里补一个特判，三个月后没人说得清某行翻译为什么存在——特判要么变成清单字段（显式化），要么随外挂版本一起退役。

本节要点回顾

• 挂架类比：标准化接触面让外挂即挂即用，解耦的判据是变更频率与替换可能性，不是教条。
• 三原则落挂架：依赖单向（外挂不知飞行器内部）、接口稳定（清单版本化）、信息隐藏（实现不可见）。
• 清单七字段：名称版本、描述、参数模式、权限、超时、幂等、副作用——每个字段都有消费方。
• 契约测试是哨兵：测承诺而非实现，外部改版最早报警。
• 适配器有纪律：特判要么显式化为清单字段，要么退役，垃圾桶式堆积必被反噬。

外挂挂上了，下一节推点火按钮：调用从构建到回填的完整时序，以及慢、坏、丢三态的对应机制。