1. 从三个痛点说起为什么要造 Hermes 这个轮子先说结论Hermes Tools Runtime 不是一个炫技的框架它就是一套“工具管理运行时”。如果你的项目里有超过二三十个工具函数、插件、脚本并且它们散落在不同服务、不同仓库、甚至不同语言写的模块里你迟早会被三件事逼疯——人肉注册表维护不过来、接口签名悄悄变了没人知道、调用关系像蜘蛛网一样理不清。我最早接触到的场景其实很小某内部系统里有一堆工具函数有的是处理文本的有的是调第三方接口的有的是算指标的。一开始大家约定俗成写完了在某个配置文件里手动登记一下。等工具数量上来以后登记这件事就变成了一种可有可无的仪式。有人忘了写有人写错了路径有人把函数重命名了但没改配置结果就是线上调用一个 404排查老半天才发现是注册信息过期了。后来又尝试过运行时反射也就是服务启动后把所有实现了特定接口的类捞出来自动注册。这种方式比人肉登记省心但有个问题反射只能看到运行时存在的东西。如果你的工具是通过装饰器拼接、代码生成、或者从外部配置文件动态组装出来的反射拿到的元数据往往是不完整的甚至拿不到函数的参数名、默认值、docstring 这些关键信息。正是在这种背景下我们开始做 Hermes Tools Runtime。它的核心思路就三个词自注册、AST 发现、中央分发。简单说就是工具代码里通过一个轻量装饰器声明自己要上线系统在构建或启动阶段用 AST 静态扫描把工具的元数据抠出来生成一张“工具派系表”然后由一个中央分发器统一接收调用请求按派系路由到对应的工具实现上。这套东西适合谁适合那些正在从“工具堆”走向“工具平台”的团队也适合个人项目里工具函数多到需要统一管理的人。它不强制你用某个特定语言只要你的工具能被扫描、能被注册、能被分发都可以套用这套思路。下面我把每个环节拆开讲讲具体设计逻辑和落地时踩过的坑。2. 自注册机制让工具学会自己“报名”2.1 自注册的核心思路约定优于配置自注册的本质是把“工具上线”这个动作从“改配置文件”变成“在代码里声明”。年代久远一点的方案是写接口工具类实现某个基类运行时自动发现子类。这种方式的问题是太死板工具往往是一段函数而不是一个类强行套类反而增加心智负担。Hermes 采用的做法是装饰器注册。写工具的人只需要在函数上面加一行声明工具就算“报名”了。注册表是一个全局字典key 是工具的唯一标识value 是元数据入口。这样做的好处是工具编写者不需要关心注册表存在哪里、怎么写配置、怎么处理路径只需要关注自己的业务逻辑。一个最小实现长这样# registry.py _TOOL_REGISTRY: dict[str, dict] {} def register_tool(name: str, namespace: str default, version: str 1.0.0): def decorator(func): _TOOL_REGISTRY[f{namespace}.{name}] { name: name, namespace: namespace, version: version, handler: func, doc: func.__doc__ or , } return func return decorator def get_registry(): return _TOOL_REGISTRY这个实现足够跑通流程了但真实项目里不能这么简单。典型的问题是 import 时机如果工具模块没有被加载装饰器就不会执行注册表里自然什么都没有。所以自注册机制必须配套一个“模块收集器”在启动阶段显式导入所有工具模块。可以是遍历目录也可以读取一个模块清单。我见过很多人在这里翻车——装饰器写得没问题模块也写好了结果注册表是空的。原因就是入口文件只 import 了注册中心没有 import 工具模块。解决办法也比较机械在入口文件里统一import tools.all_tools或者在注册中心里写一个load_tools(package_name)函数去遍历包下的子模块。2.2 注册信息的元数据结构设计注册表里放什么直接决定了后续 AST 发现和中央分发能拿到多少料。我建议至少包含以下几类唯一标识namespace.name这个 id 是分发器路由的依据一旦发布就尽量不要改执行入口函数对象或者可调用对象的引用参数签名参数名、默认值、类型注解、是否必填说明信息docstring 摘要、负责人、更新时间运行属性超时时间、是否异步、幂等性标记、执行派系参数签名这一项如果全靠开发者手写很快就会过时。所以 Hermes 没有让注册者手动填签名而是在 AST 发现阶段把签名扫出来和装饰器注册的元数据合并。这就是后面第三章要做的事。这里有个设计上的经验注册信息尽量分成“静态信息”和“动态句柄”两部分。静态信息来自 AST 扫描是代码事实动态句柄是运行时才能拿到的函数引用或类实例。两者合并在一起但来源必须分开不然以后想缓存静态信息做离线分析时会比较痛苦。2.3 自注册的边界和避坑经验自注册不是银弹有几个边界要提前想清楚。第一个坑是重复注册。同一个函数因为模块被双重导入或者装饰器被多次执行导致注册表里出现两条同 key 记录。解决方式是在注册时做幂等校验如果 key 已存在就抛异常或者覆盖并打日志。我倾向于抛异常宁可启动失败也不要线上出现“你以为调用的是 A 实际执行的是 B”这种问题。第二个坑是装饰器不能丢失函数签名。很多从 Flask 或者其他 Web 框架转过来的朋友习惯用functools.wraps这没问题但要确保装饰器返回的对象在 AST 扫描时仍然能被识别出原始定义。如果你在装饰器里做了复杂的包装AST 可能只能看到一个wrapper扫不到内层的业务函数。Hermes 里对此保留了专门的“原始函数引用”也就是在装饰器内把func放在专门的属性里扫描时优先读取这个属性。第三个坑是“注册即服务”的误解。自注册只是让工具进入目录不等于它就能被安全调用。AB 测试、灰度、权限控制、限流这些能力属于中央分发器的范畴。别在注册阶段做太重的事情注册表就老老实实当目录。3. AST 发现从源码层把工具元数据“拎”出来3.1 为什么是 AST而不是反射大多数语言都有反射机制理论上也能拿到参数名、注解、甚至 docstring。但反射有一个“盲区”它只能识别到运行时真正加载进来的对象。如果你的项目里有的工具是通过工厂函数生成出来的有的工具定义在if __name__ __main__这种条件块里反射拿到的信息可能不完整。AST 发现的思路是在构建阶段直接分析源代码文件把工具的结构信息读取出来。它不执行代码所以能看到源码层面的所有事实——包括条件分支里定义的工具、装饰器参数、参数默认值、文档注释、类型注解。Hermes 早期在 Python 版本的实现用的是标准库ast模块。扫描流程是遍历指定目录下的.py文件找到所有带有register_tool装饰器调用的函数定义然后提取出装饰器的参数、函数签名和 docstring。import ast class ToolVisitor(ast.NodeVisitor): def visit_FunctionDef(self, node): for dec in node.decorator_list: if isinstance(dec, ast.Call) and getattr(dec.func, id, ) register_tool: name None namespace default for kw in dec.keywords: if kw.arg name: name kw.value.value if kw.arg namespace: namespace kw.value.value print(ffound tool: {namespace}.{name or node.name}, line {node.lineno}) self.generic_visit(node) with open(some_tool.py, r, encodingutf-8) as f: tree ast.parse(f.read()) ToolVisitor().visit(tree)这段代码只是演示原理。实际生产里要处理的情况更多register_tool可能是被import as重命名了装饰器参数可能是变量而不是字面量函数可能是异步函数甚至还有类方法作为工具的情况。这些都需要在扫描器里做额外处理。3.2 AST 发现与运行时注册的合并策略AST 扫描解决的是“事实采集”问题但它产出的静态信息里没有真正的函数引用只有函数名和源码位置。所以 Hermes 的流程分两步构建阶段跑 AST 扫描生成一份“静态工具清单”包含名称、参数、docstring、版本、来源文件启动阶段执行自注册拿到每个工具的运行时句柄以静态清单为主键把运行时句柄映射进去形成一张完整的工具表这么做有个额外的好处如果某个工具在静态清单里有但运行时没有注册或者反过来运行时注册了但静态清单里查不到都说明有问题属于“声明与事实不一致”可以在启动时直接报错。这一步相当于给工具体系上了一道编译期校验。合并时要注意版本差异。工具函数改了参数旧版本的调用方可能还在按旧签名传参。AST 发现可以顺带生成一份“接口版本快照”分发器再拿快照做兼容性检查。比如某个工具升级后新增了一个必填参数中央分发器就能在调用前判断出老调用方不符合要求直接返回参数错误而不是等函数跑到一半才抛异常。3.3 AST 发现带来的额外能力把 AST 发现做扎实之后等于免费获得了三样东西离线依赖分析可以静态分析某个工具依赖哪些外部模块、调用了哪些其他工具画调用关系图自动生成文档docstring 和签名都在手自动生成工具列表、参数说明、示例代码变更影响面分析改了一个工具的参数能看出哪些地方引用了这个工具方便做回归测试这些能力最初只是附带的但用起来之后基本回不去了。举个例子某次要升级一批工具的参数风格从位置参数改成关键字参数以往只能靠 grep 搜索所有调用点现在直接查静态调用关系把影响范围列出来批量改效率高很多。4. 中央分发器按“派系”路由一套调度全局生效4.1 分发的两种模式同步直调与事件订阅中央分发器是 Hermes Runtime 里最像“服务端”的部分。它接收外部请求按工具 id 查表找到对应句柄后执行并返回结果。最简单的实现是一个全局函数async def invoke(tool_id: str, params: dict): tool get_registry().get(tool_id) if tool is None: raise ToolNotFound(tool_id) return await tool[handler](**params)但实际中我发现只有同步直调是远远不够的。工具之间经常需要协作一个工具处理完数据要通知另一组工具做后续动作。这种场景如果全靠调用方去编排会形成一大串嵌套调用排查问题时顺着一层层的 trace 走很容易绕晕。所以在 Hermes 里我做了“双通道分发策略”同步通道适用于请求-响应式的工具调用调用方需要结果事件通道适用于发布-订阅式的联动某个工具完成后广播事件订阅了该事件的工具自动触发两个通道共享同一张工具表但路由语义不同。同步通道按工具 id 精确匹配事件通道按“事件类型 派系”做模糊匹配。派系在这里相当于一个业务分组标签用来控制事件扩散范围——不是所有工具都能收到所有事件只有同一派系或订阅了该事件派的工具才会被触发。4.2 分发器的路由表与执行控制中央分发器要干好的三件事找到对的工具、用对的参数、在受控的环境里执行。路由表不用单独建直接复用注册表但分发器里会维护一份“运行时路由缓存”因为每次调用都去注册表里做字符串匹配虽然有字典 O(1) 的复杂度但加上参数校验、权限判断、限流检查之后链路比较长缓存可以减少重复计算。执行控制这块有几个关键参数我强烈建议在分发器层统一管理参数作用建议默认值超时时间防止工具卡死拖垮调用方同步 10s事件 30s重试次数应对临时性故障幂等工具 2 次非幂等 0 次熔断阈值连续失败自动摘除工具5 次失败并持续 30s并发限制控制工具执行的最大并发按工具单独配置审计开关记录全量调用日志默认开启派系在路由里的作用很直接同一命名空间下的工具默认属于同一派系但可以通过注册参数覆盖。比如把“字符串处理”的工具放在text派系把“数据持久化”的工具放在storage派系。事件通道广播时分发器会检查订阅者的派系标签只有派系匹配的订阅者才会收到事件。这里要注意一个问题派系标签和权限不要混在一起。派系是逻辑分组权限是安全边界。有的人会把“某个派系的工具只能被某些调用方使用”这种规则直接写死在派系标签里短期方便长期就乱套了。权限校验应该是独立的一层在分发器执行调用之前统一做。4.3 从注册到分发一次调用的完整链路把前两章的东西串起来一次工具调用的链路大概长这样调用方请求分发器invoke(text.slugify, {text: Hello World!})分发器解析工具 id确认派系为text检查权限、限流、熔断状态从路由缓存拿到函数句柄和参数签名校验参数是否合法补默认值执行工具记录耗时和结果如果该工具声明了“完成后发布事件”则向事件通道广播结果返回结果给调用方这条链路里最容易出问题的就是第 5 步。很多工具函数对参数类型非常敏感比如接收int但调用方传了str。分发器在校验阶段如果只做存在性校验不做类型校验执行阶段就会炸。所以 Hermes 在注册表的“参数签名”基础上生成了一个轻量的参数校验器支持必填、类型、枚举范围、正则表达式这几种常见的校验能力。事件通道的链路要松散一些。发布者不关心事件被谁消费订阅者也不关心事件从谁那里来只管匹配到的派系和事件类型。这个设计在后面做灰度发布和 A/B 测试时非常有用——你可以通过修改订阅配置让同一事件只触发部分新版本工具跑几天再全量切。5. 落地实录从工具集合升级到 Hermes Runtime 的全过程5.1 第一阶段盘点存量工具建立静态清单任何技术升级的第一件事都不是写代码而是盘点现状。我在做这个项目时第一步就是跑了一个 AST 扫描脚本把仓库里所有疑似工具的函数全部找出来输出一份 CSV 清单列了函数名、文件路径、参数、docstring、装饰器状态。这个过程不需要改动任何业务代码就是一个只读扫描风险为零。扫出来的结果让人挺吃惊的。团队自己心里觉得大概有三四十个工具但实际扫描到一百多个函数符合“工具”的条件。很多是历史遗留的一次性脚本被反复 import还有一些是功能高度重复的版本变体。如果没有 AST 扫描直接上注册体系这一百多个函数会像地雷一样埋在系统里后面加注册的时候随时踩雷。所以第一步的产出不是代码而是一份“工具事实清单”用它和图谱工具把调用关系画出来确认核心工具的边界再开始设计注册模型。5.2 第二阶段逐步注入自注册装饰器盘点清楚之后不要一次性把一百多个函数全部加装饰器风险太大。我的做法是按派系分批推进每批只改一个命名空间下的工具。先挑影响面最小的开始比如text派系下处理字符串的几个纯函数把它们从普通函数改成register_tool(...)装饰器注册。这一步要保证改动是纯增量式的——原来的函数引用方式不变调用方继续直接调函数也能跑同时注册表里多了一条记录。等整批工具的 AST 扫描、参数校验、文档生成全跑通之后再切到中央分发器。这里有一个实操建议装饰器注册尽量做成“可进可退”。也就是在函数上加了装饰器之后函数本身仍然是一个普通函数可以被直接 import 调用注册只作为“额外入口”而不是唯一入口。等到分发器全部接管调用方都改了以后再收紧入口把直接 import 调用的方式禁掉。5.3 第三阶段全量切换中央分发灰度观察当注册表里覆盖了超过九成的工具后我开始让新的调用方统一走中央分发器。旧的调用方可以继续走老路径通过一个兼容适配层把老接口映射到新工具 id。这个过程很像数据库的“双写”阶段只不过这里双写的是调用请求。灰度期间重点关注三类指标调用成功率分发器和直调的结果是否一致耗时对比分发器的路由开销是否在可接受范围超时和重试熔断参数是否合理有没有误杀正常工具跑了两周后发现一个有意思的现象通过分发器调用比直调平均多了 3ms 左右但整体稳定性反而提升了因为超时控制和熔断机制能兜住底之前有些工具偶发卡死会把上游调用方拖到崩溃现在会被熔断器隔离开。数据稳定后就把旧路径删除全量切换到 Central Dispatcher。这个阶段最忌讳留着旧入口又没人维护两套逻辑只会让排查问题的人精神状态恶化。6. 常见问题与排查技巧实录6.1 典型问题速查表现象原因排查方法注册表为空但代码里有装饰器工具模块没有被 import自注册没执行检查入口是否遍历加载了所有工具模块AST 扫描出的工具名和注册不一致装饰器参数使用了变量而非字面量或者函数被包装过扫描器里补“原始函数引用”的提取逻辑调用时报参数不匹配参数校验器读的签名信息和函数实际定义不同步确认 AST 扫描在构建阶段是否覆盖了最新代码事件订阅了但没触发派系标签对不上或订阅逻辑放在了事件发布之后检查订阅者注册时机幂等加载工具模块熔断器误杀工具单次故障导致的连续失败阈值设置太敏感调大阈值放宽熔断恢复时间增加半开探测工具上线后找不到新注册的版本注册表有缓存新的 AST 清单未重建发布流程里加入构建阶段静态清单生成步骤6.2 两个值得细说的排查案例第一个案例某次升级后所有新注册的工具都能在启动日志里看到但调用时一直提示ToolNotFound。查了半天发现是路由缓存没有失效。注册表里明明有缓存里没有因为启动时注册动作发生在缓存初始化之后。解决办法是把缓存的构建时机改成“懒加载 失效刷新”每次注册或注销操作都标记缓存为 dirty并在下一次调用时刷新彻底抛弃启动时一次性 build cache 的旧逻辑。第二个案例AST 扫描出来的 docstring 总是乱码。原以为是什么编码问题后面发现是多个版本的 Python 代码混在同一个仓库里部分文件用的编码不是 UTF-8。扫描器在解析文件时没有指定编码导致在部分文件上崩了且静默失败。修复方法是扫描时统一encodingutf-8并增加异常兜底解析失败的文件要输出 warning 而不是直接跳过不然你会漏掉一整个子目录的工具。这个案例的教训是AST 发现工具的输出质量直接取决于输入文件的规范性。扫到的源码如果有语法错误工具会静默跳过最后问“为什么线上没有这个工具”时才追到源头。所以我在 Hermes 里专门加了“覆盖率统计”AST 扫描完成后会输出一个覆盖率指标说明扫描到的函数数占全部函数定义数的比例低于阈值就直接让构建失败宁可慢一点也不带着“半张地图”上线。6.3 不容易踩到但真踩到就很伤的细节还有一个高频问题事件派系的区分度。如果两个派系的事件类型命名相似比如data.updated和data.update.finished订阅data.*的工具可能会收到预期之外的触发。这件事的根治办法不是靠命名规范而是在分发器里引入“订阅匹配优先级”先做精确匹配再做通配匹配同一事件只触发最优匹配的一条订阅规则。命名规范只能作为团队约定不能作为程序的唯一保障。最后再补充一个经验注册表数据和路由缓存一定要有可视化排查入口。哪怕只是一个简单的内部页面能看到当前注册了多少工具、按派系分布、最近调用的成功率和耗时。我见过太多系统代码写得再优雅一旦出了线上问题排查入口却是一堆日志效率极低。Hermes 从第一天就把“可观测性”当作功能来做这一点在它逐渐成为平台上所有工具的咽喉要道之后回报非常大。这套自注册、AST 发现、中央分发三位一体的思路目前已经在我们内部的多个项目上跑了比较长的时间。从最初的百来个工具到现在支撑跨模块联动的分发网关最深的体会是工具平台化最大的成本从来不是写功能而是把工具的“所有权”从某个人脑子里转移到代码本身。自注册让工具自己说话AST 让事实变得可核对中央分发让执行变得可控。如果你也在被工具爆炸增长的问题困扰可以试试从存量工具的 AST 清单开始一步步建立起自己的运行时体系。
