OpenHands 利用微代理为交互注入领域专长，并引导用户完成定制化工作流程。那么，我们该如何定义这些微代理呢？答案正藏在那由 YAML 前言包裹的 Markdown 文件中，这一部分决定了微代理的行为、触发条件和功能。本文将带你逐步了解微代理语法的核心要素和最佳实践。
📝 YAML 前言：你的微代理蓝图
每个微代理都以一个 YAML 前言块开始，这个区块用三条破折号（—）包裹。它充当元数据容器，指示 OpenHands 如何处理该文件。
前言中的关键字段
以下是在定义微代理时必须包含的主要字段：
- name
• 微代理的唯一标识符
• （所有类型均必填） - type
• 指定微代理的类型，可为repo、knowledge或task
• （所有类型均必填） - version
• 表示微代理的版本号（建议遵循语义化版本控制）
• （所有类型均必填） - agent
• 指定将处理该微代理的代理类型，通常为CodeActAgent
• 该代理必须在 OpenHands 系统中有效，否则微代理将无法使用
• （所有类型均必填） - author
• 微代理创建者（可选） - triggers
• 一个关键词列表，用于激活知识微代理
• 示例：triggers: - kubernetes - k8s - docker - security - containers cluster• 关键词可以是单个词或短语，匹配时一般不区分大小写
• （仅知识微代理必填） - inputs
• 专门用于任务微代理，它定义了在执行任务前需要用户提供的参数
• 每个输入项必须包含name、description，以及可选的required属性（默认为 true）
• 示例结构：inputs: - name: INPUT_NAME description: 'Description of what this input is for' required: true• 在微代理正文中，通过双大括号（例如{{ INPUT_NAME }}）引用输入值
• （任务微代理必填）
📂 如何组织你的微代理
YAML 前言不仅设定了行为准则，还决定了微代理的组织及触发方式：
- 仓库微代理：
• 存放在.openhands/microagents/repo.md中
• 提供针对特定仓库的上下文和指导，无需触发词即可自动加载 - 知识微代理：
• 存放在knowledge/目录下，例如：.openhands/microagents/knowledge/git.md
• 当对话中的关键词与指定触发词匹配时自动激活
• 需要使用清晰且独特的触发词，以避免错误激活 - 任务微代理：
• 存放在.openhands/microagents/tasks/目录中
• 用于引导用户完成交互式工作流程，需要明确调用
• 根据前言中定义的输入模式，提示用户提供所需的参数
🔍 制作高效微代理的最佳实践
在确保你的 YAML 前言中包含所有必需字段的同时，还应考虑以下设计建议，以确保微代理既实用又高效：
- 明确具体：
在微代理正文中提供清晰简洁的指导，聚焦于一个明确的目标，而非泛泛而谈的建议。 - 内容平衡：
保持内容的简明扼要——详细到足以有用，但又不过分扩展以免占用过多上下文窗口。如果必要，可以将大型微代理拆分成多个小而聚焦的微代理。 - 独特触发词：
为知识微代理选择独特且不常用的触发短语，这有助于避免在日常对话中频繁误触发。 - 清晰处理输入：
对于任务微代理，为每个输入项提供详细说明，并始终通过双大括号格式（例如{{ INPUT_NAME }}）在正文中引用。 - 指导方针和示例：
通过包括代码片段、分步说明以及实际使用示例，增强微代理的使用说明和易读性。
🛠 实际 Markdown 示例
下面是一个用于更新拉取请求描述的任务微代理前言示例：
---
name: update_pr_description
type: task
version: "1.0.0"
agent: CodeActAgent
author: "Your Name"
inputs:
- name: PR_ID
description: '拉取请求的标识符'
required: true
- name: CHANGE_SUMMARY
description: '代码更改的概要'
required: true
---
在上述 YAML 区块之后，你可以使用 Markdown 语法撰写微代理正文，其中包含分步指导、项目符号或编号步骤，帮助用户完成任务。
📚 总结
深入理解和有效运用 OpenHands 中的微代理语法，对于为你的开发环境量身定制各种指导至关重要。通过正确设置 YAML 前言并遵循 Markdown 最佳实践，你确保了每个微代理无论是增加仓库专用上下文、提供领域知识还是引导复杂工作流程，都能无缝集成，发挥最大的效能。
拥抱微代理的力量，用清晰而精准的方式定制和提升你的编码体验吧！
祝你编码愉快，愿你所设定的微代理在恰当的时刻精确触发，助你事半功倍！