【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载导读本文聚焦 Unreal Agent Harness项目目录unreal-agent中的技能Skill体系当模型需要处理特定任务时如何通过SkillUse工具加载一份SKILL.md指令文件以及技能文件内的相对路径如何被解析为绝对路径后再交给底层工具。文章以 skill-preamble.md 的三条核心指令为骨架结合 skills.go、skill_use.go 与 skill_use.go 的源码实现还原技能从注册、注入系统提示词、被模型调用、到异步读取文件并回传结果的完整链路。读完本文你将掌握在 Unreal Agent 中注册与调用技能的正确姿势、SKILL.md内部相对路径的解析规则以及该机制与异步工具调用模型的关系。技能前导Skill Preamble的三条核心指令skill-preamble.md 是一段极简但语义明确的模型指令文本全文只有三条规则技能的本质以下技能skills为特定任务提供专门的指令specialized instructions for specific tasks。技能不是可执行代码而是指令文件作用是告诉模型遇到这类任务时应该遵循哪套流程/规范。用 SkillUse 加载当任务与某个技能的描述description匹配时应当使用SkillUse工具加载该技能对应的文件。也就是说技能是按需懒加载的——技能文件的内容不会预先全部塞进上下文而是由模型在判断当前任务需要它之后通过工具调用动态读取。相对路径解析规则当技能文件内部引用了相对路径时必须以技能目录为基准解析——即SKILL.md所在目录的父目录等价于该路径的 dirname——并将解析后的绝对路径用于后续工具调用。这一条是技能体系与工作区文件系统衔接的关键约定。这条 preamble 不是写给人看的文档而是随每个模型请求一起发送的系统提示词的一部分通过//go:embed编译进二进制见 skills.go其作用是在每一轮对话开始前就为模型建立技能调用协议的心智模型。技能注册与系统提示词的动态拼接Skill 的三元组结构在工具层一个技能被建模为Name Description Path三元组见 tool.gotype Skill struct { Name string Description string Path string }Name技能的唯一标识模型在SkillUse参数中引用它Description技能用途描述模型据此判断当前任务是否匹配该技能Path技能指令文件的路径通常指向该技能目录下的SKILL.md。注册机制与提示词注入技能的注册由Registry接口管理tool.go提供RegisterSkill、UnregisterSkill、Skills()等方法说明技能可以在运行时动态注册/注销而不是静态写死的工具。当构建模型请求时builder.go 的NewBuilder(skills ...tool.Skill)会把已注册技能清单序列化后拼接到系统提示词中func NewBuilder(skills ...tool.Skill) Builder { currentPreamble : preamble if skillPrompt : formatSkillsForPrompt(skills); skillPrompt ! { currentPreamble \n\n skillPrompt } ... }XML 技能清单的生成skills.go 中的formatSkillsForPrompt负责把技能列表编码为 XML 片段追加在 skill-preamble 之后func formatSkillsForPrompt(skills []tool.Skill) string { if len(skills) 0 { return } ... encoded, err : xml.Marshal(availableSkills{Skills: promptSkills}) ... return skillPreamble \n\n string(encoded) }生成格式如下以 builder_test.go 的测试快照为例available_skills skill namego-review/name descriptionReview lt;Gogt; amp; tests/description location/skills/reviewers/SKILL.md/location /skill skill namedocuments/name descriptionEdit documents/description location/skills/documents/SKILL.md/location /skill /available_skills注意三个细节XML 中技能描述里的特殊字符、、会被自动转义保证注入提示词后模型仍然能正确解析location字段携带的是技能的完整文件路径通常以SKILL.md结尾它是Skill三元组中Path字段的直传若没有任何已注册技能formatSkillsForPrompt返回空串preamble 中不会出现available_skills段。由此模型在每轮请求中都能看到当前可用的技能清单名称、用途、文件位置并结合 skill-preamble 的规则决定何时调用SkillUse。SkillUse 工具加载已注册技能的指令工具定义SkillUse是 Unreal Agent 的三个内置静态工具之一与Bash、ViewImage并列见 registry.go其模型可见定义位于 static.go名称SkillUse描述Load the instructions for a registered skill.加载一个已注册技能的指令参数一个必填字符串参数name即要加载的技能的确切名称the exact name of the skill to load。从参数设计可以看出模型侧只需传递技能名文件路径完全由 harness 内部解析模型无需也不应猜测磁盘布局。参数校验与技能解析模型发起的工具调用由 skill_use.go 中的skillUseTranslator.Translate处理其校验链如下调用名必须与静态工具名SkillUse一致否则报错skill-use call name ... does not match static tool SkillUse参数为空时按{}处理容错设计随后解出{name: ...}结构name为空时报错skill-use argument name must be set在注册表中按名称解析技能未命中时报错skill ... is not registered命中后用技能文件的Path构造一个 skill-use 操作operation.NewSkillUseSpec(skill.Path)提交到协调器并返回WaitingFor状态——注意这里工具调用立即返回真正的文件读取是异步进行的这与该 harness 的整体 async-first 架构完全一致。未命中技能的容错若模型请求了未注册的技能名调用不会崩溃而是把错误文本直接作为工具结果返回给模型TranslateResult中status.Error ! 分支见 skill_use.go让模型在下一轮自行纠正。这正是技能清单需要被注入提示词的原因模型看到available_skills就知道该用哪个名字。SkillUse 操作底层异步读取状态机SkillUse在操作层被建模为一个可持久化的 operationTypeSkillUse/Version 1完整状态机位于 skill_use.gotype SkillUseState struct { Path string Content []byte TerminalError string }其状态流转为Ready → Awaiting → Completed / Failed / Canceledskill_use.goReady首次推进时派发一个IOReadprimitive读取SKILL.md的全部内容Count: math.MaxInt64即一次读完见 skill_use.go并把操作置为AwaitingAwaiting等待底层 IO 事件回流。每个IOReadOutput事件都会把读取到的数据块追加到Content直到收到IOReadCompleted事件——此时校验累计字节数与Content长度一致后操作进入Completedskill_use.goFailed / Canceled读取失败如路径不存在会写入TerminalError并以Failed终结收到取消事件则进入Canceled。任何来源不符、关联 ID 不符、输出偏移异常的事件都会导致操作失败保证异步读写的严格一致性。这种操作 primitive 事件的双层设计使得技能文件的读取可以跨多轮对话完成模型这一轮发起SkillUseharness 在后台读取文件读取完成后将文件全文作为工具结果回传给模型模型在下一轮拿到内容后即可遵循其中指令继续工作。加载中的占位结果由于读取是异步的若模型在读取完成前就结束回合TranslateResult会返回占位文本Skill is loading.skill_use.go读取完成后文件内容会被转换为 UTF-8 合法字符串非法字节以\uFFFD替换作为工具结果返回skill_use.go。这与 harness 的通用运行中工具占位Tool call is still running...builder.go逻辑一脉相承。SKILL.md 相对路径解析规则详解skill-preamble 中第三条指令是整个技能体系与文件系统交互的关键约定When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool calls.拆解这条规则基准目录技能目录 SKILL.md所在目录的父目录即dirname技能文件路径。例如技能文件位于/skills/reviewers/SKILL.md则技能目录是/skills/reviewers/。解析动作技能文件内凡是引用了相对路径比如指向同目录下的templates/task.md、scripts/run.sh都以此技能目录为基准解析成绝对路径而不是相对模型当前工作目录解析。使用方式解析出的绝对路径必须直接用于后续工具调用如Bash执行脚本、ViewImage查看截图等。之所以做此约定是因为技能文件是可移植的指令包技能作者在SKILL.md里写的路径天然相对于技能自身位置而模型的工作目录可能因任务而异。统一按技能目录解析能保证同一份技能在任何工作区下行为一致避免路径失效类幻觉。实战一次完整的技能加载流程综合上述实现一次典型的技能加载可以归纳为五步对应 builder.go、skill_use.go、skill_use.go 的调用链注入清单请求构建时NewBuilder把已注册技能序列化为available_skillsXML拼进系统提示词含 skill-preamble 三条规则模型决策模型发现当前任务与某技能的description匹配发起SkillUse调用参数为{name: 技能名}翻译与提交skillUseTranslator校验名称、查注册表拿到Path构造 skill-use 操作并异步提交本轮立即返回异步读取操作状态机派发IOReadprimitive 读取SKILL.md全文事件回流完成后把内容作为工具结果返回遵循执行模型拿到SKILL.md内容按其中指令工作文件内相对路径一律按技能目录解析为绝对路径后再调用Bash等工具。测试佐证方面skill_use_test.go 演示了构造SkillUse调用并断言其解析为对应技能文件路径的过程builder_test.go 则固化了下发到模型的技能清单 XML 快照。两者共同保证了注册 → 注入 → 调用 → 读取链路的行为稳定。小结Unreal Agent 的技能体系可以概括为一条简洁而完备的协议skill-preamble 定义规则用SkillUse按需加载、相对路径以技能目录为基准解析available_skillsXML 提供选择依据SkillUse工具 异步 IO 操作负责把SKILL.md内容安全送达模型。这一设计让技能成为可注册、可发现、可懒加载的指令扩展单元与 harness 的 async-first、操作可持久化架构深度契合。若要在你的 Unreal Agent 部署中接入自定义技能只需遵循三步把指令写进SKILL.md、以Skill三元组注册到 Registry、确保文件内部相对路径相对技能目录书写即可。赞分享【免费下载链接】unreal-agentAsync-first agent harness项目地址https://gitcode.com/gh_mirrors/un/unreal-agent点击查看免费下载相关推荐learn-claude-code 技能按需加载机制SkillLoader、SKILL.md 与 load_skill 工具实现解析learn claude code 技能按需加载机制SkillLoader、SKILL.md 与 load_skill 工具实现解析 本篇围绕 learn c示例工程AI Agent人工智能Agent Zero response 工具深度解析最终答复协议与任务收尾机制Agent Zero response 工具深度解析最终答复协议与任务收尾机制 导读 response 是 Agent Zero 框架中唯一负责向用户交付最人工智能大模型AI AgentAgent 框架自主智能体多智能体工具调用MCP 服务浏览器控制三步让 VRM 角色拥有番剧质感Three.js 中 MToon 卡通渲染实战三步让 VRM 角色拥有番剧质感Three.js 中 MToon 卡通渲染实战 three vrm 的 MToon 材质是 Three.js 生态里专为 VRCLI音视频创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考