企业官网建设流程全解析

1. 从单体到生态：为什么Agent需要一套扩展体系

做过Agent项目的人大概都有过这种体验：第一版跑得挺爽，一个主循环加几个工具函数就能干活。等到业务方开始提需求——“能不能让它每天自动跑一遍数据”、“能不能在调用工具前先做一次敏感词过滤”、“能不能把公司内部的API接进去”——你就发现原来的代码结构开始扛不住了。每加一个功能就要动核心逻辑，改一处崩三处，测试覆盖率直线下降。

Hermes Agent的进化方向，本质上就是在解决这个问题。它把Agent的能力拆成了四个独立的扩展维度：Skills（技能）、Hooks（钩子）、Plugins（插件）、Cron（定时任务）。这四个东西各管各的，互不干扰，但组合起来又能覆盖绝大多数实际场景。你可以把它理解成一台电脑：Skills是你装的软件，Hooks是系统层面的拦截器，Plugins是驱动程序，Cron是计划任务。每个部分都有自己的生命周期和加载机制，核心引擎只负责调度，不负责具体实现。

这套体系适合谁？如果你正在做Agent相关的产品或者内部工具，已经过了“跑通Demo”的阶段，开始面对多场景、多租户、多任务的复杂需求，那这套思路值得仔细看看。哪怕你用的不是Hermes，这种“核心+扩展”的架构设计本身也有很强的参考价值。接下来我会逐个拆解这四个维度的设计思路、实现要点和踩坑经验，尽量把每个环节讲透。

2. Skills：让Agent学会新把式的最小单元

2.1 Skill到底是什么，和普通函数有什么区别

很多人第一次看到Skill这个概念会觉得多此一举——不就是个函数吗？我直接注册一个工具不就行了。但实际用下来会发现，Skill和普通工具函数有本质区别。

普通工具函数是“裸”的，你注册进去，Agent直接调用，输入输出全靠约定。Skill则是一个自包含的能力单元，它至少包含四个部分：元信息描述、输入参数Schema、执行逻辑、以及可选的依赖声明。元信息描述告诉Agent这个技能是干什么的、什么时候该用；参数Schema定义了输入的结构和约束；执行逻辑是实际干活的代码；依赖声明则说明这个技能需要哪些环境变量、外部服务或者前置条件。

举个例子，你要做一个“查询天气”的技能。普通工具函数可能就是一个get_weather(city)，但Skill会写成这样：名称叫weather_query，描述是“根据城市名查询当前天气状况，适用于用户询问天气、温度、是否下雨等场景”，参数Schema里定义city是必填字符串，执行逻辑里处理API调用和错误返回，依赖声明里注明需要WEATHER_API_KEY环境变量。这样Agent在决定是否调用这个技能时，能获得更充分的上下文，调用成功率会高很多。

实操心得：Skill的描述字段非常关键，它直接决定了Agent能不能在正确的时机选中正确的技能。我一般会花至少五分钟来打磨这个描述，把“什么时候用”和“什么时候不用”都写清楚。比如“查询天气”的描述里会加一句“不适用于查询历史天气数据”，这样能避免Agent在错误场景下调用。

2.2 Skill的注册与加载机制

Skill的注册方式通常有两种：静态注册和动态发现。静态注册就是在启动时把所有Skill列出来，适合数量少、变动不频繁的场景。动态发现则是从指定目录扫描Skill定义文件，按需加载，适合技能数量多、需要热更新的场景。

Hermes采用的是混合模式。核心Skill走静态注册，保证启动速度；扩展Skill走动态发现，支持运行时加载。动态发现一般会约定一个目录结构，比如skills/下面每个子目录是一个Skill，里面包含manifest.json（元信息）和handler.py（执行逻辑）。启动时扫描这个目录，把manifest读进来注册到技能列表里。

这里有个细节值得注意：Skill的加载顺序会影响Agent的选择偏好。如果两个Skill的功能有重叠，先加载的会被优先考虑。所以我在实际项目里会把最常用、最稳定的Skill放在前面加载，把实验性的、可能出错的放在后面。这个顺序在manifest里可以通过priority字段来控制，数值越小优先级越高。

2.3 参数Schema的设计要点

参数Schema看起来简单，实际上是最容易出问题的地方。我见过太多因为Schema设计不合理导致Agent调用失败的案例。几个核心原则：

第一，必填参数越少越好。每多一个必填参数，Agent调用失败的概率就增加一分。能通过上下文推断的参数就不要让Agent填。比如用户说“帮我查一下北京的天气”，Agent已经知道城市是北京了，就不需要再让它在参数里重复填一遍。

第二，参数类型要明确。字符串就是字符串，数字就是数字，不要用“字符串或数字”这种模糊类型。Agent在生成参数时对类型很敏感，模糊类型会导致它反复尝试。

第三，枚举值要列全。如果一个参数只接受几个固定值，一定要在Schema里用enum列出来。这样Agent就知道只能从这几个里面选，不会瞎编。

第四，默认值要合理。非必填参数给一个合理的默认值，能大幅降低Agent的决策负担。比如“查询天气”的unit参数，默认给celsius，用户不指定就用摄氏度。

{ "name": "weather_query", "description": "根据城市名查询当前天气状况", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，如北京、上海" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius", "description": "温度单位" } }, "required": ["city"] } }

2.4 Skill的版本管理与灰度发布

当Skill数量多起来之后，版本管理就成了刚需。你改了一个Skill的逻辑，不能保证所有调用方都能兼容新版本。这时候就需要版本管理机制。

我的做法是在Skill的manifest里加一个version字段，遵循语义化版本规范。Agent在调用时可以选择指定版本，不指定就用最新稳定版。同时维护一个changelog，记录每个版本的变化。灰度发布则是通过canary标记来实现，新版本先标记为canary，只有特定条件的请求才会路由到新版本，观察一段时间没问题再全量。

这个机制在多人协作的场景下特别有用。A同学改了天气查询Skill，B同学还在用旧版本做测试，互不影响。等A同学确认新版本稳定了，再通知B同学升级。

3. Hooks：在关键节点插入你的逻辑

3.1 Hook的触发时机与类型

Hooks的本质是在Agent执行流程的关键节点上预留的扩展点。你可以把它理解成高速公路上的服务区——主路照常通行，但你想停就停，想加个油、买个水都行，不影响主路的路况。

Hermes的Hook体系一般覆盖这几个关键节点：

• before_agent_start：Agent开始处理请求之前触发，适合做请求预处理、权限校验、日志记录
• before_tool_call：每次调用工具之前触发，适合做参数校验、敏感词过滤、调用计数
• after_tool_call：工具调用返回之后触发，适合做结果后处理、缓存写入、异常上报
• before_agent_end：Agent处理完请求准备返回之前触发，适合做结果格式化、脱敏处理
• on_error：发生异常时触发，适合做错误兜底、告警通知

每个Hook节点可以注册多个处理函数，按注册顺序依次执行。如果某个Hook返回了特定信号（比如abort），可以中断后续流程。这个设计给了很大的灵活性——你可以在不修改核心代码的前提下，插入任意多的自定义逻辑。

3.2 Hook的执行顺序与优先级

多个Hook注册在同一个节点上时，执行顺序就变得很重要。Hermes通过priority字段来控制，数值越小越先执行。默认优先级是100，你可以根据需要调整。

这里有个经验：前置校验类的Hook优先级设高一些（数值小），后置处理类的Hook优先级设低一些（数值大）。比如敏感词过滤应该在参数校验之前执行，因为如果参数里有敏感词，后面的校验就没必要做了。而结果缓存写入应该在结果格式化之后执行，因为缓存的是格式化后的结果。

# 注册一个before_tool_call的Hook，优先级50，先于默认的100执行 @hook("before_tool_call", priority=50) def sensitive_word_filter(context): params = context.get("params", {}) for key, value in params.items(): if isinstance(value, str) and contains_sensitive(value): return {"action": "abort", "reason": "参数包含敏感词"} return {"action": "continue"}

3.3 用Hook实现审计日志与限流

Hook最实用的两个场景是审计日志和限流。审计日志记录谁在什么时候调用了什么工具、传了什么参数、返回了什么结果。这个在排查问题和合规审查时非常有用。限流则是控制单位时间内某个工具的调用次数，防止被滥用或者触发外部API的配额限制。

审计日志的实现很简单，在before_tool_call和after_tool_call各注册一个Hook，把上下文信息写到日志系统里就行。关键是要记录足够的信息：时间戳、用户标识、工具名、参数摘要、返回状态、耗时。参数摘要不要记全量，敏感字段要脱敏，否则日志本身就成了安全隐患。

限流稍微复杂一点，需要一个计数器。我一般用滑动窗口算法，在内存里维护一个时间窗口内的调用记录。每次before_tool_call时检查当前窗口内的调用次数是否超过阈值，超过就返回abort并附带提示信息。注意计数器要区分维度，按用户、按工具、按全局分别计数，否则一个用户就能把全局配额吃光。

注意事项：Hook里不要做耗时操作。Hook是在主流程里同步执行的，你在这里卡住，整个Agent就卡住了。如果需要做异步的事情（比如发告警、写远程日志），把任务丢到队列里，让后台worker去处理。

3.4 Hook的异常处理与降级策略

Hook本身也可能出错。比如你写了一个参数校验的Hook，结果里面有个bug抛异常了，这时候应该怎么办？是让整个请求失败，还是跳过这个Hook继续执行？

我的建议是区分Hook的类型来决定。如果是安全相关的Hook（比如敏感词过滤、权限校验），出错时应该保守处理，直接拒绝请求。如果是非关键的Hook（比如日志记录、指标上报），出错时应该降级处理，记录错误信息后继续执行主流程。

Hermes支持在注册Hook时指定on_error策略，可选abort、skip、retry。默认是abort，但你可以根据实际情况调整。我一般会把日志类的Hook设为skip，安全类的保持abort。

@hook("before_tool_call", priority=50, on_error="skip") def audit_log(context): # 即使这里出错了，也不影响主流程 write_audit_log(context) return {"action": "continue"}

4. Plugins：把外部能力接进来

4.1 Plugin与Skill的边界在哪里

这是被问得最多的问题：Plugin和Skill到底有什么区别？我什么时候该写Skill，什么时候该写Plugin？

简单来说，Skill是Agent自己能干的事，Plugin是Agent借助外部系统才能干的事。Skill的执行逻辑在Agent进程内，Plugin则是一个独立的服务或者库，Agent通过标准接口跟它通信。

举个例子：计算两个数的和，这是Skill，因为Agent自己就能算。查询数据库里的用户信息，这是Plugin，因为Agent需要连接外部数据库。调用公司内部的审批系统，这也是Plugin，因为Agent需要跟外部HTTP服务交互。

从技术实现上看，Skill通常是轻量级的函数，Plugin则可能是一个独立的进程、一个gRPC服务、或者一个动态链接库。Plugin的注册和发现机制也更复杂，需要处理连接管理、健康检查、超时重试等问题。

4.2 Plugin的通信协议与接口设计

Plugin和Agent之间的通信协议决定了扩展的灵活性和性能。常见的选择有几种：HTTP REST、gRPC、消息队列、以及进程内直接调用。

HTTP REST最简单，跨语言支持最好，但性能一般，适合调用频率不高的场景。gRPC性能好，支持流式传输，但需要定义proto文件，接入成本稍高。消息队列适合异步场景，但同步调用的请求-响应模式实现起来比较绕。进程内直接调用性能最好，但要求Plugin和Agent用同一种语言编写，而且耦合度高。

Hermes默认支持HTTP和gRPC两种协议，通过Plugin的manifest来声明。我一般建议：如果Plugin是公司内部服务，用gRPC；如果是第三方服务或者跨团队协作，用HTTP。gRPC的性能优势在调用频繁时很明显，但HTTP的通用性在跨团队时更重要。

接口设计上，Plugin需要暴露一个标准的健康检查接口和一个能力描述接口。健康检查让Agent知道Plugin是否可用，能力描述让Agent知道这个Plugin能干什么、需要什么参数。这两个接口是Plugin能被正确调用的前提。

4.3 Plugin的生命周期管理

Plugin不是注册完就一劳永逸的。它需要经历注册、初始化、健康检查、调用、降级、注销这几个阶段。每个阶段都有需要注意的地方。

注册阶段，Agent需要知道Plugin的地址和协议。这个信息通常写在配置文件里，支持环境变量覆盖。初始化阶段，Agent会调用Plugin的初始化接口，传递必要的配置参数。健康检查阶段，Agent会定期ping Plugin，确认它还活着。调用阶段就是正常的请求-响应。降级阶段是当Plugin不可用时，Agent需要决定是报错还是走备用逻辑。注销阶段是Plugin下线时，Agent需要清理相关资源。

我踩过的一个坑是：Plugin的健康检查超时时间设得太短。默认设了1秒，结果Plugin偶尔因为GC停顿超过1秒，就被判定为不可用，触发了降级。后来把超时调到5秒，问题就消失了。这个值要根据Plugin的实际响应时间来定，不能拍脑袋。

4.4 一个Plugin的完整实现示例

下面是一个查询用户信息的Plugin示例，用HTTP协议，Python实现：

# plugin_server.py from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/health", methods=["GET"]) def health(): return jsonify({"status": "ok"}) @app.route("/capabilities", methods=["GET"]) def capabilities(): return jsonify({ "name": "user_info", "description": "查询用户基本信息", "parameters": { "type": "object", "properties": { "user_id": {"type": "string", "description": "用户ID"} }, "required": ["user_id"] } }) @app.route("/invoke", methods=["POST"]) def invoke(): data = request.json user_id = data.get("params", {}).get("user_id") if not user_id: return jsonify({"error": "user_id is required"}), 400 # 实际查询逻辑 user = query_user_from_db(user_id) if not user: return jsonify({"error": "user not found"}), 404 return jsonify({"result": user}) if __name__ == "__main__": app.run(host="0.0.0.0", port=8080)

Agent侧的配置：

plugins: - name: user_info protocol: http endpoint: http://localhost:8080 health_check_interval: 30 timeout: 5 fallback: error

这个Plugin实现了一个标准的查询接口，Agent通过/capabilities获取能力描述，通过/invoke执行调用，通过/health做健康检查。整个流程清晰且可扩展。

5. Cron：让Agent自己按时干活

5.1 Cron表达式的核心语法

Cron是定时任务的标准表达方式，五个字段分别代表分、时、日、月、周。很多人第一次接触Cron会被各种星号和斜杠搞晕，其实记住几个核心符号就够了：

• *：任意值，表示“每”
• ,：枚举，表示“和”
• -：范围，表示“从...到...”
• /：步长，表示“每隔...”

比如0 9 * * 1-5表示周一到周五每天早上9点。*/15 * * * *表示每15分钟。0 0 1 * *表示每月1号零点。

实操心得：Cron表达式最容易出错的地方是“日”和“周”同时指定的时候。很多Cron实现里，这两个字段是“或”的关系，不是“与”。比如0 0 1 * 1表示每月1号或者每周一，而不是每月1号且是周一的时候。如果你需要“且”的关系，得在任务逻辑里自己判断。

5.2 任务调度与并发控制

Cron任务最大的风险是任务重叠。如果一个任务执行时间超过了调度间隔，下一次调度触发时上一次还没跑完，就会出现两个实例同时跑的情况。轻则浪费资源，重则数据错乱。

Hermes提供了几种并发控制策略：skip（跳过本次调度）、queue（排队等待）、parallel（并行执行）。默认是skip，适合大多数场景。如果你的任务必须串行执行，用queue。如果任务之间没有依赖关系，用parallel提高吞吐。

我一般会在任务定义里显式指定并发策略，而不是依赖默认值。因为不同任务的特性不一样，统一默认值容易出问题。比如数据同步任务用skip，报表生成任务用queue，日志清理任务用parallel。

tasks: - name: daily_report cron: "0 8 * * *" concurrency: queue timeout: 3600 handler: generate_daily_report

5.3 任务失败重试与告警

Cron任务失败是常态，关键是怎么处理失败。我的策略是：区分可重试错误和不可重试错误。网络超时、临时性服务不可用，这些是可重试的，配置重试次数和退避策略。参数错误、权限不足，这些是不可重试的，直接告警。

重试策略一般用指数退避：第一次失败等1分钟重试，第二次等2分钟，第三次等4分钟，最多重试3次。超过重试次数还没成功，就触发告警。告警渠道可以是邮件、短信、或者内部IM。告警信息里要包含任务名、失败原因、重试次数、最后错误堆栈，方便快速定位。

@cron_task("0 8 * * *", concurrency="queue", max_retries=3, backoff="exponential") def generate_daily_report(): try: data = fetch_data() report = build_report(data) send_report(report) except RetryableError as e: raise # 触发重试 except FatalError as e: alert(f"日报生成失败: {e}") raise # 不再重试

5.4 分布式环境下的Cron挑战

单机环境下Cron很简单，但到了分布式环境就复杂了。多个实例同时跑Cron，同一个任务会被触发多次。这时候需要分布式锁来保证同一时间只有一个实例在执行任务。

常见的做法是用Redis或者数据库实现分布式锁。任务触发时先尝试获取锁，获取成功才执行，执行完释放锁。锁要设置过期时间，防止实例崩溃后锁一直不释放。过期时间要大于任务的最大执行时间，否则任务还没跑完锁就过期了，另一个实例会拿到锁开始执行。

另一个挑战是时钟同步。分布式环境下各实例的时钟可能有偏差，导致任务触发时间不一致。解决方案是用NTP同步时钟，或者在调度层统一时间源。Hermes的做法是让所有实例从同一个时间服务获取当前时间，避免本地时钟偏差的影响。

注意事项：分布式锁的过期时间不要设得太短。我见过一个案例，任务正常执行需要5分钟，锁过期时间设了3分钟，结果任务跑到一半锁过期了，另一个实例拿到锁开始跑同一个任务，数据就乱了。后来把过期时间调到10分钟，问题解决。

6. 四个维度的协同：一个完整的自动化场景

6.1 场景描述与需求拆解

假设我们要做一个“每日数据巡检”的Agent。需求是：每天早上8点自动触发，检查各个数据源的可用性，如果发现异常就调用告警Plugin发送通知，同时把巡检结果写入数据库。巡检过程中需要过滤敏感信息，并且记录完整的审计日志。

这个场景用到了全部四个维度：Cron负责定时触发，Skill负责执行具体的检查逻辑，Plugin负责连接数据库和告警服务，Hooks负责敏感信息过滤和审计日志。

6.2 实现步骤与配置

第一步，定义Cron任务：

tasks: - name: daily_data_inspection cron: "0 8 * * *" concurrency: skip timeout: 1800 handler: run_inspection

第二步，实现巡检Skill：

@skill("data_inspection", description="检查数据源可用性") def run_inspection(): sources = ["source_a", "source_b", "source_c"] results = [] for source in sources: status = check_source(source) results.append({"source": source, "status": status}) return results

第三步，注册告警Plugin：

plugins: - name: alert_service protocol: http endpoint: http://alert-service:9090 timeout: 10

第四步，注册Hooks：

@hook("before_tool_call", priority=50) def filter_sensitive(context): # 过滤敏感信息 pass @hook("after_tool_call", priority=200) def write_audit(context): # 写审计日志 pass

6.3 执行流程与关键节点

整个执行流程是这样的：早上8点Cron触发run_inspection任务。任务开始执行前，before_agent_startHook记录开始日志。执行过程中，每次调用check_source技能时，before_tool_callHook做敏感信息过滤，after_tool_callHook写审计日志。如果发现异常，调用alert_servicePlugin发送告警。任务结束后，before_agent_endHook做结果汇总和脱敏。

关键节点在于Hook的执行顺序和Plugin的降级策略。敏感信息过滤必须在审计日志之前执行，否则敏感信息就被写进日志了。告警Plugin如果不可用，不能影响巡检任务本身的执行，所以降级策略设为skip。

6.4 监控与调优建议

上线之后需要监控几个关键指标：任务执行时长、成功率、Hook执行耗时、Plugin调用延迟。任务执行时长突然变长，可能是某个数据源响应变慢。成功率下降，可能是Plugin不稳定。Hook耗时增加，可能是审计日志写入变慢。

调优的方向：如果Hook耗时占比高，考虑把非关键的Hook改成异步执行。如果Plugin调用延迟高，考虑加缓存或者换协议。如果任务执行时长波动大，考虑拆分任务或者调整并发策略。

我自己的经验是，先跑一周收集基线数据，再根据基线做调优。没有基线数据就调优，很容易调过头或者调不到位。基线数据包括P50、P95、P99的耗时，以及各环节的耗时占比。有了这些数据，优化哪里、优化多少，心里就有数了。

7. 常见问题与排查技巧实录

7.1 Skill调用失败排查清单

7.2 Hook不生效的常见原因

Hook不生效通常有三个原因：注册时机不对、优先级冲突、或者返回值格式错误。注册时机方面，Hook必须在Agent启动之前注册，启动之后注册的Hook不会被加载。优先级方面，如果两个Hook的优先级相同，执行顺序是不确定的，需要显式指定不同的优先级。返回值方面，Hook必须返回特定格式的字典，返回None或者格式错误会导致Hook被跳过。

排查方法：在Hook函数里加一行日志，确认它有没有被调用。如果日志没输出，说明Hook没注册成功。如果日志有输出但效果不对，检查返回值格式。

7.3 Plugin连接超时的处理策略

Plugin连接超时是最常见的问题。处理策略分三层：第一层是重试，对于临时性超时，重试1-2次通常能解决。第二层是降级，重试后仍然超时，走备用逻辑或者返回缓存数据。第三层是熔断，连续多次超时后，暂时停止调用该Plugin，避免拖垮整个系统。

熔断器的参数需要根据实际情况调整。我一般设：连续5次失败触发熔断，熔断后30秒进入半开状态，半开状态下允许1次试探请求，成功则恢复，失败则继续熔断。

7.4 Cron任务不执行的排查思路

Cron任务不执行，按这个顺序排查：先看Cron表达式是否正确，用在线工具验证一下。再看任务是否被禁用，配置文件里有没有enabled: false。然后看调度器是否正常运行，日志里有没有调度记录。最后看任务是否被并发策略跳过，如果上一次还没跑完，skip策略会跳过本次调度。

还有一个容易忽略的点：时区。Cron表达式默认用系统时区，如果系统时区是UTC，你写的0 8 * * *就是UTC早上8点，对应北京时间下午4点。这个坑我踩过好几次，后来统一在配置里显式指定时区。

7.5 性能优化的几个实用技巧

第一个技巧：Skill的懒加载。不是所有Skill都需要在启动时加载，把不常用的Skill改成按需加载，能显著减少启动时间。

第二个技巧：Hook的批量执行。如果多个Hook的逻辑相似，合并成一个Hook批量处理，减少函数调用开销。

第三个技巧：Plugin的连接池。每次调用Plugin都新建连接开销很大，用连接池复用连接能大幅降低延迟。

第四个技巧：Cron任务的错峰调度。如果多个任务都在整点触发，会造成资源争抢。把任务分散到不同的分钟，比如一个在8:00，一个在8:05，一个在8:10。

最后分享一个小技巧：给每个Skill、Hook、Plugin都加上唯一的标识符，在日志里输出这个标识符。排查问题时，通过标识符能快速过滤出相关日志，比翻全量日志效率高得多。这个习惯我坚持了三年，每次排查问题至少省一半时间。