Agent技能系统设计实践：从协议定义到多技能编排

做Agent开发的朋友应该都有过这种体验：功能写了一堆，最后全挤在主流程里，改一个功能要翻半天代码，新加一个能力又得动核心逻辑，测试起来更是头疼。我早期做某智能助手项目时就掉进过这个坑，后来把能力全部技能化——也就是项目里命名的agent-skills——整个架构才清爽起来。这篇文章就把我在技能系统上从设计到落地、再到排查问题的完整思路和代码实践分享出来，适合正在做Agent应用、或者准备把手头工具能力做成可复用模块的开发者参考。

1. 技能化的核心逻辑与设计思路

1.1 为什么不能让能力裸奔在代码里

大部分Agent项目起步阶段都很直接：用户在对话框里问一句，代码里if-else判断意图，然后调用对应函数。一开始只有三五个功能还行，一旦超过十个，主流程就开始失控。我见过一个项目，主文件三千多行，一个函数里塞了七八个功能的逻辑分支，每次加需求都像在做外科手术。

这背后的本质问题不是代码风格，而是能力和调用方式被耦合死了。技能化的第一个目的就是把"能做什么"和"怎么触发"分开。"能力"应该是一份独立的声明——包含功能描述、入参出参、运行环境、权限要求——而"触发"则由调度层统一处理。这样每个技能可以单独开发、单独测试、单独演进，主流程只负责路由。

我个人的理解里，Agent技能和普通的函数库有三个关键差异：

• 可描述性：技能必须自带一段面向模型或调度器的自然语言描述，说明"我擅长什么、什么时候用我、需要什么参数"。
• 可注册性：技能不是硬编码在代码里，而是通过注册表收集起来，运行时可查、可增、可替换。
• 可组合性：复杂任务由多个技能串联完成，技能之间通过标准化的输入输出衔接，而不是函数直接互相调用。

生活里类比一下就很清楚：普通函数像是你自己家里的工具箱，锤子放抽屉里，你知道在哪、直接用；技能系统则像一个公共工具房，每个工具都贴着标签、写着用途和使用方法，你需要的时候按标签取用，也可以把多个工具组合起来完成一个工程。这个工具房的"标签规范"就是技能协议。

1.2 技能粒度：太粗和太细都是坑

设计技能系统时第一个要拍板的问题就是粒度。我在模拟项目X里试过两种极端，都有明显代价。

技能定义得太粗，比如做一个"处理文档"技能，内部包含解析、摘要、翻译、格式转换——表面上看很省事，但模型很难准确描述自己到底需要哪个子能力，而且每次调用都要把整套逻辑加载进来，响应慢、资源占用高。技能定义得太细，比如把"打开文件"和"读取第一行"都拆成独立技能，注册表会膨胀到难以维护，调度器光是选技能就要费不少功夫，描述稍微模糊一点就选错。

我后来总结的粒度判断标准有三条，同时满足就拆，否则就合：

1. 这个技能是否对应一个完整的用户意图——用户说"总结这篇文档"，对应的是一个技能，而不是五个步骤。
2. 这个技能的输入输出是否足够稳定——如果参数集合经常变动，说明边界还没划清楚。
3. 这个技能是否会被多个场景复用——没人复用的功能做成技能是浪费，做成内部函数就好。

按照这个标准，我这个项目里最终把文档相关能力拆成了三个技能：文档解析、内容摘要、格式转换。"文档解析"对应"把PDF/Word变成纯文本"这个完整意图，参数只有文件路径；"内容摘要"对应"提炼要点"；"格式转换"则独立出来，因为它的输入输出模式和前两者差异很大。

1.3 自研协议还是跟框架走

当时团队里讨论过一个问题：直接用arXiv上那些现成Agent框架的技能机制，还是自己定义一套协议。现成框架的好处是省事，坏处是框架的技能描述格式、注册方式、调度策略都是设计者为你定好的，一旦你的场景比较特殊——比如技能需要长时间运行、需要多模态输入、需要人工审批环节——就可能被框架卡住。

我最终选择了轻量自研，核心协议只定义四件事：

• 技能元信息（名称、描述、版本、标签）
• 参数Schema（入参的JSON结构定义）
• 返回结构（统一的结果封装）
• 生命周期（初始化、执行、销毁的可选钩子）

这四样东西加起来不到两百行代码，却能覆盖绝大多数技能场景。不依赖特定框架意味着技能模块本身是纯Python包，任何Agent调度器都能通过统一接口调用。而且自研协议还有一个隐性收益：排查问题的时候不用翻框架源码，整个调用链都是自己可控的。

2. 一套可落地的技能协议细节

2.1 技能元信息：模型靠这一段文字决定用不用你

技能注册表里最重要的字段不是技能函数本身，而是那一段给模型看的描述。我调试时发现，模型选错技能的案例里，七成问题出在描述写得含糊。早期我的"文档解析"技能描述是"处理文档，提取内容"，结果模型经常把"总结PDF"的请求也路由过来，因为"提取内容"和"总结"在语义上是模糊的。

后来我把描述改成了结构化写法，大致像这样：

当用户提供PDF、Word、TXT等文件路径，需要将文件内容转换为纯文本时使用。 输入参数是文件路径和可选的页数范围。 输出为规范化文本，文件不存在或格式不支持时返回明确错误。 如果用户要求总结要点、提炼结论、翻译，不要使用本技能，那属于其他技能的职责。

这段描述里包含了三层信息：触发条件（什么时候用）、入参出参（调用需要什么）、负面约束（什么时候不要用）。最后一点尤其关键。模型在意图模糊时倾向于随便选一个技能试，如果你把"不要用"的场景写清楚，能大幅降低错误路由率。

元信息里我还加了版本号、作者（团队内部用）、依赖标签。版本号用在技能热更新上——注册表里同一个技能可以存在多个版本，调度时默认取最新，出问题可以一键回滚。这个机制实现起来很简单，但救过我很多次。

2.2 参数Schema：让文档成为契约

参数的Schema我直接用JSON Schema规范。这样的好处是：第一，模型可以理解参数结构并根据用户输入填充；第二，校验逻辑可以标准化，每个技能执行前自动做一次参数校验，不合法就直接返回错误，不用等函数内部跑一半才发现缺字段。

实际项目中我把Schema分成两类：基础类型直接映射JSON Schema的string、number、boolean、array、object；扩展类型则自建了几个，比如file_path（校验文件是否存在）、url（校验格式并可选项做连通性检查）、duration（限定最小最大时长）。扩展类型在校验器里是自定义函数，这样技能作者写Schema时不用重复写存在性检查逻辑。

一个典型技能的参数定义大致长这样（节选）：

{ "type": "object", "properties": { "file_path": { "type": "string", "ext": "file_path", "description": "待解析的文件绝对路径" }, "page_range": { "type": "array", "items": {"type": "integer"}, "minItems": 2, "maxItems": 2, "description": "可选，解析指定页数范围，如 [1, 5]" } }, "required": ["file_path"] }

这里有个细节值得注意：description字段也要写清楚。它不只是给人看的注释，很多情况下模型或者上层规则会根据参数描述来构造参数值。比如page_range如果没写"可选"，校验器就会认为它是必填，而这个字段在某些调用场景下根本不需要。

2.3 返回结构：成也标准化，败也标准化

技能返回结构我统一成四段式：

• status:success/error/partial
• data: 成功时的结果数据
• error: 失败时的错误码和消息
• meta: 运行时长、token消耗、版本等调试信息

为什么要单独定义partial状态？因为很多真实场景不是非黑即白。比如文档有100页，第80页解析失败，前面79页都有内容——这时候返回纯错误会让上游丢失已有成果，返回成功又不诚实。partial状态表示"部分成功"，data里携带成功部分，error里标记失败页码。调度层拿到partial后可以根据业务决定是重试、忽略还是通知用户。

我踩过一个坑：早期返回结构只有成功和失败，某次批量解析任务里一个文件损坏导致整批任务全部标记失败，排查了很久才发现是"一颗老鼠屎坏了一锅汤"。引入partial状态后，批量任务的容错能力明显提升。

2.4 注册机制：集中注册表与懒加载

注册表我用了两层设计：静态注册表存技能元信息，动态执行器存技能代码。两者分离的好处是——元信息轻量，可以在服务启动时全部加载进内存，用来做路由判断；执行器代码则按需加载，技能真正被选中时才import。

SKILL_REGISTRY = {} def register_skill(skill_cls): meta = skill_cls.meta() SKILL_REGISTRY[meta["name"]] = { "meta": meta, "class": skill_cls, "loaded": False } return skill_cls def get_skill_executor(name): entry = SKILL_REGISTRY.get(name) if entry is None: raise SkillNotFoundError(name) if not entry["loaded"]: entry["executor"] = entry["class"]() entry["loaded"] = True return entry["executor"]

懒加载在技能数量多的时候特别重要。我见过一个项目注册了四十多个技能，启动时全部import，光加载依赖就花了几秒。懒加载之后，启动时间降到一秒以内，而且某些技能的第三方依赖（比如重型机器学习库）只有在真正使用时才会被load进内存。

3. 实操：从零实现一个"文档摘要"技能

3.1 技能类的基类设计

所有技能继承同一个基类，我把它设计成三个生命周期方法加一个元信息类方法：

class BaseSkill: @classmethod def meta(cls): """返回技能元信息字典，包含 name, description, parameters, returns 等""" raise NotImplementedError def validate(self, params: dict): """参数预处理与校验，在 execute 前调用""" return params def execute(self, params: dict, context: dict): """核心执行逻辑""" raise NotImplementedError def cleanup(self): """释放资源，如关闭文件句柄、断开连接""" pass

这里有一个设计决策：validate和execute分离。原因有两个。第一是校验逻辑通常会用到公共校验器，放在独立方法里方便复用；第二是技能作者写代码时会被迫思考"哪些是入参问题、哪些是执行问题"，错误分类会清晰很多。实践下来，validate阶段返回的错误信息可以统一格式化，用户体验比执行中抛异常好得多。

context参数是留给技能之间传递环境信息的，比如用户身份、地域、当前工作目录、调试标记。它不经过Schema校验，因为这是系统级信息而不是用户级参数。

3.2 完整技能代码示例

下面是我在模拟项目X里一个"文档摘要"技能的简化实现。它的功能是接收文本或者文件路径，返回一段摘要结果。

import hashlib from typing import Dict, Any class DocumentSummarizeSkill(BaseSkill): @classmethod def meta(cls): return { "name": "document_summarize", "version": "1.2.0", "tags": ["document", "summary", "nlp"], "description": ( "当用户需要获取文章、报告或文档的核心要点和结论时使用。" "输入为文本内容或文件路径，输出为不超过200字的要点摘要。" "如果用户要求翻译、改写或格式转换，不要使用本技能。" ), "parameters": { "type": "object", "properties": { "text": { "type": "string", "description": "待摘要的原始文本" }, "file_path": { "type": "string", "ext": "file_path", "description": "待摘要的文件路径，与 text 二选一" }, "max_length": { "type": "integer", "minimum": 20, "maximum": 800, "default": 200, "description": "摘要最大字数" } }, "oneOf": [ {"required": ["text"]}, {"required": ["file_path"]} ] }, "returns": { "type": "object", "properties": { "summary": {"type": "string"}, "source": {"type": "string", "enum": ["text", "file"]} } } } def validate(self, params: dict) -> dict: if "file_path" in params: params["text"] = read_file_as_text(params.pop("file_path")) if not params.get("text") or not params["text"].strip(): raise SkillParamError("待摘要文本不能为空") if len(params["text"]) < 50: raise SkillParamError("文本长度过短，不需要摘要") return params def execute(self, params: dict, context: dict) -> Dict[str, Any]: text = params["text"] max_length = params.get("max_length", 200) cache_key = hashlib.md5(text.encode("utf-8")).hexdigest() cached = cache_get(cache_key) if cached: return {"summary": cached, "source": "cache"} # 实际项目中这里会调用摘要模型或算法服务 summary = summarize_text(text, max_length=max_length) cache_set(cache_key, summary, ttl=3600) return {"summary": summary, "source": "model"} def cleanup(self): pass

几个值得展开的细节：

第一，validate里我做了文件读取和文本预处理。这样execute只面对纯文本，职责单一。oneOf的JSON Schema约束了"text和file_path必须二选一"，在元信息层面就已经约束了调用方式。

第二，缓存我放在了execute里面而不是validate里。因为缓存本身消耗少量内存，如果用户频繁调用同一个文本摘要，走缓存会快很多。实际项目中我对缓存做了TTL过期，避免旧文本长期占用内存。

第三，meta()的returns字段也写清楚了返回结构。这一步看起来冗余，但我在多技能编排时发现，调度器需要知道技能返回什么结构才能决定下一步怎么走——比如摘要技能返回的summary字段，可以直接作为翻译技能的text入参。

3.3 注册与调用链路

技能类写好后，注册就一行代码：

register_skill(DocumentSummarizeSkill)

调用链路则是：请求进来 → 参数解析 → 路由选择技能 → 校验 → 执行 → 格式化返回。路由选择这一步我单独讲一下，因为它是技能系统的神经中枢。

最简单的路由算法是：把技能元信息里的description和参数描述全部拼接成一份技能清单，让模型从清单里选一个。这个方案在技能少于十个时效果不错，但技能多了之后清单会变得很长，模型的选择准确率会下降。

我在项目里做了一层预筛：根据用户输入里的关键词和技能标签做一次粗略匹配，把候选技能缩小到三到五个，再让模型从这几个里面精确选择。预筛代码大概长这样：

def prefilter_candidates(user_input: str, top_k=5): scores = {} for name, entry in SKILL_REGISTRY.items(): meta = entry["meta"] score = 0 for tag in meta.get("tags", []): if tag in user_input: score += 2 for kw in meta.get("keywords", []): if kw in user_input: score += 1 if score > 0: scores[name] = score ranked = sorted(scores.items(), key=lambda x: -x[1]) return [name for name, _ in ranked[:top_k]]

预筛不是必须的，但能明显降低模型选错概率，也减少了传递给模型的token量。在用户输入明确包含"文档""PDF""总结"等关键词时，预筛基本一步到位。

3.4 参数校验的细节与边界

参数校验看着简单，实际写起来容易漏边界。我归纳了几个必查项：

• 类型是否合法：字符串是不是真的字符串，数字是不是在范围内。JSON Schema自带这些能力，直接复用。
• 互斥字段：text和file_path不能同时传，用oneOf定义。
• 文件存在性：自定义的file_path扩展类型会主动检查文件路径是否存在、是否有读权限。
• 大小限制：文本长度、文件大小都要有限制，防止恶意构造超大参数导致内存溢出。

还有一类边界属于业务语义边界。比如摘要技能里，文本长度小于50字我不让执行，因为正常来说这么短的内容本身就没有"摘要"的必要，返回提示比跑一遍模型更合理。这类判断没有标准答案，需要根据每个技能的实际场景设定，但它能省下大量无意义的计算资源。

异常处理方面，我统一封装了SkillParamError、SkillExecuteError、SkillTimeoutError三类。返回给上层时，错误码格式是SKILL_xxx，方便日志聚合和监控告警。有一次线上排查问题，我就是通过错误码统计发现某个技能超时率异常高，进而定位到第三方接口的慢查询。

4. 多技能编排与调度策略

4.1 让模型选还是让规则选

技能多了以后，下一个问题是多步任务怎么编排。比如用户的需求是"把这份PDF的要点总结成英文并发到指定邮箱"，这明显需要至少三个技能：文档解析、摘要、翻译、邮件发送——其中还有依赖顺序。

我实验过的编排方案有三种：

规则编排：提前写好流程模板，固定执行顺序。优点是稳定可控，缺点是没有弹性，用户需求稍微偏离模板就处理不了。

模型编排：把技能清单和用户需求一起交给模型，让模型决定调用顺序和参数。优点是灵活，缺点是模型可能给出不存在的技能名或错误的参数结构，需要大量兜底校验。

混合编排：对高频路径用规则模板，对低频复杂路径用模型编排。我最终采用的是这个方案。

混合编排实现上其实不复杂。规则模板是一组DAG描述：

PIPELINES = { "pdf_summarize_translate_email": { "steps": [ {"skill": "document_parse", "output_key": "text"}, {"skill": "document_summarize", "input_key": "text", "output_key": "summary"}, {"skill": "translate_text", "input_key": "summary", "output_key": "translated"}, {"skill": "send_email", "input_key": "translated"} ] } }

调度器按步骤顺序执行，每步的输出存到共享的outputs字典里，下一步可以从这个字典里取字段作为入参。实现不到100行，但把最常见的多技能协作场景覆盖掉了。

4.2 技能串联、并联与条件分支

实际业务里技能之间的关系不只是简单的串联。我总结了三类常见组合：

串联：A的输出是B的输入，必须严格按顺序执行。上面那个PDF摘要翻译邮件的例子就是典型串联。串联的容错策略是：某一步失败，后续步骤全部跳过并返回错误位置。

并联：多个技能彼此独立，可以同时执行，最后汇总结果。比如同时查天气、查日程、查交通，然后合并输出。并联的容错策略是：某一路失败不影响其他路，汇总时用partial标记有失败项。

条件分支：根据某一步的结果决定走哪个方向。比如文档解析后，如果识别出是合同文件就走"合同审核"流程，是论文就走"学术摘要"流程。这个用普通的if-else就能实现，但我会把条件判断封装成一个小函数，方便复用。

实现并联时我用了Python的concurrent.futures：

from concurrent.futures import ThreadPoolExecutor, as_completed def run_parallel(skill_calls): results = {} with ThreadPoolExecutor(max_workers=3) as executor: future_map = { executor.submit(execute_one, call): call["id"] for call in skill_calls } for future in as_completed(future_map): call_id = future_map[future] try: results[call_id] = {"status": "success", "data": future.result()} except Exception as e: results[call_id] = {"status": "error", "error": str(e)} return results

线程池的max_workers我一般控制在3到5。太大会导致下游接口被并发打爆——我踩过一次，三个技能同时调用同一家外部服务，直接把对方限流阈值触发，全部失败。后来我在技能调用层加了全局并发信号量，统一控制对每个外部服务的并发数。

4.3 上下文管理与技能记忆

多技能编排有个容易被忽略的问题：每个技能执行时怎么拿到必要的上下文。比如翻译技能需要知道目标语言，这个信息可能在用户最初的请求里，也可能在摘要技能的输出里。我统一维护了一个context对象，执行链上的每个技能都可以读和写。

class ExecutionContext: def __init__(self, user_id=None, meta=None): self.user_id = user_id self.meta = meta or {} self.shared = {} # 技能之间共享数据的区域 def get(self, key, default=None): return self.shared.get(key, default) def set(self, key, value): self.shared[key] = value

技能执行时，如果发现需要的信息不在参数里，可以通过context.get()去取。这样编排层的代码可以保持干净，不需要每个技能都显式接收上游所有输出。但这里有个约束：共享数据区域只能放可序列化的对象，不能放文件句柄、数据库连接这类资源，否则不同技能之间没法安全传递。

关于技能记忆，我的做法很简单：每个技能可以声明自己是否对结果做缓存、缓存多久，调度器统一管理缓存键。比如文档解析技能对同一个文件解析两次结果一样，我就缓存它的输出；而邮件发送技能绝不能缓存，否则就出大事了。缓存策略做成技能元信息的一个字段，而不是技能内部自己实现，这样方便统一监控缓存命中率。

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

5.1 模型选错技能：描述精准化改造

这是我在项目里遇到频率最高的问题。症状是用户输入明明说的是"翻译"，系统却调用了"摘要"技能。我排查时先看日志里模型的技能选择理由，发现模型会拆解用户意图，把"翻译这篇报告并总结要点"拆成两步。按理说这没错，但它第一步先调了摘要技能，把原文内容丢了一部分，第二步翻译时缺上下文。

根治方法有两层。第一层是技能描述加免责声明，明确写"如果用户要求翻译，不要使用本技能，请调用translate_text技能"。这类负面提示在模型路由上效果显著。第二层是预筛阶段把候选技能按语义相似度排个序，翻译和摘要虽然相关，但相似度不会太高，预筛阶段可以把翻译技能排在前面。

还有一个技巧是给相似技能加差异化示例。我在元信息里加了一个examples字段，每个技能放两个典型调用示例，比如：

examples: [ "用户：把这段文字翻译成英文 -> 应该选择 translate_text，参数 text=..., target_lang=en", "用户：总结一下这篇文档 -> 应该选择 document_summarize，参数 file_path=..." ]

路由时把示例拼到技能描述后面，模型的选择准确率能提升不少。这个字段不用太长，两三条就够。

5.2 参数Schema不一致导致的隐蔽错误

技能系统的错误里，最隐蔽的是上游传参和下游Schema对不上。比如摘要技能返回的是{"summary": "..."}，翻译技能读的是text字段，如果编排时把summary当作text传进去，翻译技能接收到的就是空值，而且很难发现——因为校验阶段检查的是"text是否存在于参数中"，它确实存在，只是值为空。

我在编排层加了一个字段映射声明，明确每一步取上游哪个字段：

{"skill": "translate_text", "input_map": {"text": "summary"}, "output_key": "translated"}

有了input_map，执行到翻译技能时会把当前上下文按映射关系构造参数。这样不会再出现"字段名碰巧对不上"的问题。开发过程中我们内部有个约定：所有技能返回的字段名必须小写蛇形命名，且语义上尽量通用，比如文本统一叫text，结果统一叫result，不要用content、body、text_content这种同义异名的花活。

5.3 技能超时与重试策略

技能执行超时是线上最常见的问题。第三方接口慢、数据量大、模型推理时间长，都会触发超时。我给每个技能设置了独立的超时时间，默认30秒，重试一次。为什么是30秒？因为测试下来，大多数正常技能调用都在10秒内完成，超过30秒基本是异常情况，没必要干等。

重试要区分场景：

• 可重试错误：网络抖动、上游临时不可用、超时。这类重试间隔用指数退避，第一次等1秒，第二次等2秒，最多三次。
• 不可重试错误：参数非法、文件不存在、无权限。这类重试多少次都一样失败，直接返回错误，不要浪费资源。

判断依据我写成了一个策略函数：

def should_retry(error): if isinstance(error, SkillTimeoutError): return True if isinstance(error, SkillExecuteError): return getattr(error, "retryable", False) return False

技能作者在抛SkillExecuteError时可以设置retryable=True，表明这个错误是临时的、可以重试。这个字段虽然只是一个布尔值，但让重试决策从"一刀切"变成了"按错误类型精细控制"。

超时还有一个关联问题：资源泄漏。技能执行超时被中断后，它可能已经打开了文件、建立了连接，如果不做清理，跑久了会被资源占满。我在调度器里用finally块统一调用每个技能的cleanup()，确保不管成功失败都释放资源。

5.4 排查速查表

我把常见问题整理成一个速查表，团队新成员排查时直接对照：

这张表看起来简单，但都是实战里一条条填出来的。排查问题时我最经常用的工具是日志里的meta字段——它记录了每次技能调用的耗时、缓存命中、版本号、错误码，配合请求ID可以完整还原一次调用的全链路。所以我在写技能基类时要求每个技能尽量在meta里塞入这些信息，刚开始觉得麻烦，后来排查问题全靠它。

5.5 安全与权限边界

技能系统做得越灵活，权限控制越要跟上。我在项目里加了三层限制：

技能注册限制：技能元信息里有一个required_permissions字段，比如"发送邮件"技能需要email:send权限，"删除文件"技能需要fs:write权限。调度器执行前先检查当前会话是否有对应权限，没有就直接拒绝，不让技能代码跑起来。

参数内容限制：file_path扩展类型默认只允许访问白名单目录，防止用户传任意路径触发目录穿越。我见过一个真实案例，某技能的file_path参数没有做目录限制，用户传了一个/etc/passwd，技能把系统文件读出来返回给了调用方——这种问题在技能化架构里尤其需要防范，因为技能的复用性意味着同一个漏洞会被所有接入方共享。

外部调用限制：技能执行过程中如果访问外部网络，我需要声明式的outbound_urls字段记录允许访问的域名，调度器在技能执行前加载对应的网络策略。这个机制看起来有点重，但对于那些将来要开放给第三方使用的技能，它是必须的。

安全边界设计上我的原则是"默认拒绝、显式放行"。新技能上线时默认没有权限，提交时填写权限申请，审批通过后才放行。这个流程在团队协作时可能让人觉得繁琐，但换来的是出问题时的责任边界和审计基线，长远看是划算的。

写在最后的个人体会

如果让我只说一条经验，那就是：技能系统的成败不在代码，而在定义能力边界时的克制。我会不自觉地想让一个技能覆盖更多场景，结果往往是描述越宽泛、模型越迷茫，校验越混乱。现在每写一个技能，我都会强迫自己回答三个问题：用户什么话会触发它？它一定不能处理什么？它返回什么结构让下游最舒服？这三个问题想清楚，技能系统的复杂度就能被控制在可维护范围内。

还有一个值得提的小技巧：给每个技能写一份"人类能读的README"，用一两段话说明这个技能的用途、参数、限制。我自己调试时不会直接看图表的调用记录，而是先看README回忆当初设计意图——很多"诡异问题"其实是因为后来某个技能被改得偏离了最初定义。README和元信息里的description保持同步更新，比任何代码注释都管用。

项目做到这个阶段，我最大的感受是技能化带来的不只是架构上的清爽，还有团队协作方式的改变：每个人负责一个或几个技能的迭代，接口稳定后互不干扰。这个状态在我看来，是Agent应用走向复杂化之后一个很理想的工作模式。如果你们团队也正在被主流程膨胀、能力复用困难这些问题困扰，不妨从定义一份技能协议开始，也许就是下一步最值得投入的事。