十年匠心定制 · 商业建站与技术教学双线并行 咨询热线:400-886-1026 service@lmnt.cn
ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

OpenHuman Skill Executor Agent 深度解析:技能加载、运行时解析与 Handoff 交接机制

OpenHuman Skill Executor Agent 深度解析:技能加载、运行时解析与 Handoff 交接机制 OpenHuman Skill Executor Agent 深度解析技能加载、运行时解析与 Handoff 交接机制【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman导读Skill Executor Agent 是 OpenHuman 技能系统agentskills.io 风格中的专职执行 Agent它负责加载已安装技能的SKILL.md指令、读取绑定的脚本与资源、解析 Node.js/Python 运行时、逐步执行技能并在自身工具不足时通过标准化的 Handoff Plan 将剩余步骤交还主控 Agent。本文基于其系统提示词 prompt.md 与其配套实现完整讲解该 Agent 的角色边界、七步执行流程、输出契约、运行时解析命令、交接机制及底层skill_runtime基础设施帮助读者理解 OpenHuman 中技能编排与技能执行是如何被解耦并落地的。一、定位Skill Executor 在技能体系中的角色OpenHuman 的技能Skill以 agentskills.io 规范组织一个技能就是一个包含SKILL.mdYAML frontmatter Markdown 指令的目录可附带脚本、参考资料与资源文件。技能系统的发现、解析、作用域User / Project / Legacy解析、信任标记与安装卸载由 skills 域 负责而技能的实际执行则交给运行时runtime中的 Skill Executor Agent。从系统提示词第一段可以看出它的明确定位You are theSkill Executor Agent, a specialist in loading and executing installed agent skills.它是一个执行专家只负责加载和执行已安装的技能不负责发现、搜索或安装技能。这种职责分离在 Agent 目录中体现得很清楚——skill_setup agentdelegate_name setup_skills负责浏览社区注册表、搜索与安装而 skill_executor agentdelegate_name run_skill负责运行。用户按名称调用某个技能或要求运行某个已安装技能时就触发 Skill Executor。Agent 声明文件解读Skill Executor 的行为由与其提示词同目录的 agent.toml 声明关键配置如下配置项值含义idskill_executorAgent 唯一标识display_nameSkill Executor Agent展示名delegate_namerun_skill主控 Agent 调用它的入口名temperature0.4相对保守的采样温度保证执行过程的确定性max_iterations15单轮执行的工具迭代上限iteration_policyextended迭代策略sandbox_modenone不启用额外沙箱由上层执行环境保证安全agent_tierworkerWorker 级 Agent作为子 Agent 被主控调用omit_identitytrue提示词中不注入身份描述omit_memory_contexttrue不注入记忆上下文保持执行上下文干净model.hintagentic推荐使用 Agent 型模型工具集agent.toml的[tools] named列表声明了该 Agent 的刻意收窄的工具集仅包含技能执行所需的能力list_workflows列出已安装技能describe_workflow读取技能的SKILL.md指令read_workflow_resource读取技能引用的脚本、参考资料、资源文件skill_runtime_resolve_runtimes解析可复用的 Node/Python 运行时run_workflow触发后台技能运行shell执行 shell 命令file_read/file_write读写文件ask_user_clarification向用户澄清提示词中明确写道Your toolset is intentionally narrow (shell, files, skill loading, runtimes).——工具集是故意收窄的它不拥有邮件、聊天、日历等集成能力也没有用户记忆与类型化工具。这正是它需要 Handoff 机制的根本原因。二、七步执行流程从加载到报告提示词定义了一个严格的执行规程共有七个步骤加载指令使用describe_workflow读取技能的SKILL.md获取其操作说明读取资源使用read_workflow_resource读取技能引用的脚本、参考资料等资源解析运行时当技能引用了 Node.js、npm、npx、Python 或捆绑的.js/.py脚本时调用skill_runtime_resolve_runtimes解析可用的运行时逐步遵循严格按技能指令逐步执行完成所有拥有工具可执行的步骤执行命令按技能指示运行 shell 命令或脚本。关键约束Node.js 脚本必须使用 OpenHuman 的 Node 运行时runtime_nodePython 脚本必须使用 OpenHuman 的 Python 运行时runtime_python不得假设宿主机的 PATH交接任何当前工具无法完成的步骤交给上层处理见第三节 Handoff Plan而不是让整个技能失败报告汇报已完成的工作以及上交给上层的交接计划。注意第 5 步的运行时约束是 OpenHuman 本地优先架构的核心体现脚本执行不依赖宿主机环境而是通过 OpenHuman 统一管理的可复用运行时保证技能在任何平台Mac / Windows / Linux上行为一致。三、输出契约stdout 是唯一回传通道提示词用一段 Blockquote 明确规定了输出契约这是最容易踩坑的地方Output contract:only a commands stdout/stderr is captured back to you. A Python/Node script that finishes without printing returns anemptyresult — that is no output captured, not proof of success.只有命令的 stdout/stderr 会被捕获并回传给 Agent一个执行结束但不打印任何内容的 Python/Node 脚本返回的是空结果——这代表没有捕获到输出不等于成功因此技能脚本必须把需要的结果打印到 stdout例如 Python 的print(...)、Node 的console.log(...)如果脚本只写文件不打印执行后必须用read_workflow_resource或file_read读取该文件来获取结果。这一契约是技能作者编写脚本时必须遵守的规范确保输出可观测。无论脚本逻辑多正确只要结果没有以 stdout 或文件形式暴露出来对执行 Agent 而言就是没有结果。四、运行时解析Node / Python 的可复用运行时第 3 步提到的skill_runtime_resolve_runtimes是技能执行正确性的关键。其工具实现位于 runtime/tools.rs参数与行为如下参数runtime枚举all默认、node、python用于指定要解析的运行时权限级别ReadOnly只读返回结构来自 runtime/ops.rs 的ResolvedRuntimeSummary字段包括字段含义runtime运行时名称node/pythonenabled配置中是否启用对应config.node.enabled与config.runtime_python.enabledavailable是否实际解析成功source运行时来源system系统自带或managedOpenHuman 托管version解析到的版本号binary可执行文件路径bin_dir二进制所在目录Node 返回 bin 目录Python 返回解释器父目录error解析失败时的错误信息从 ops.rs 的RuntimeRequirement::from_optional可以看出参数别名node/nodejs/javascript都等价于 Nodepython/python3等价于 Python未知值会返回错误unknown runtime {other} (expected all, node, or python)。底层通过NodeBootstrap与PythonBootstrap完成解析两者都支持托管managed与系统system两种来源。CLI 与 RPC 视角skills/runtime/README.md 给出了生产环境下的烟雾测试命令openhuman skill_runtime schemas openhuman skill_runtime resolve_runtimes --runtime all openhuman skill_runtime run --skill_id git-helper --inputs {} openhuman skill_runtime recent_runs --limit 10其中skill_runtime命名空间对应的控制器定义在 runtime/schemas.rs共六个函数函数作用关键参数run后台启动技能运行返回run_id 日志路径skill_id必填、inputs可选 JSONcancel请求取消正在进行的技能运行run_idrecent_runs列出工作区运行日志目录中的近期运行skill_id可选过滤、limit默认 20上限 100read_run_log按run_id读取运行日志片段offset字节偏移、max_bytes默认 64 KiB上限 256 KiBresolve_runtimes解析 Node/Python 可复用运行时runtimeall/node/pythonschemas返回全部 skill_runtime 控制器 schema无该命名空间是技能执行的 CLI/RPC 友好接口。旧有的workflows run、workflows cancel与 run-log RPC 仍然可用以保持兼容但新脚本应优先直接调用skill_runtime_*。五、Handoff Plan诚实交接拒绝伪造当技能执行到某个需要 Skill Executor 不具备的能力的步骤时如发送邮件、读写用户记忆提示词给出了三条铁律禁止编造结果、假装成功或用无关 shell 命令伪造能力禁止因为一步无法完成就中止整个技能必须先用自有工具完成所有能完成的步骤必须在输出末尾附上## Handoff Plan只描述剩余步骤交由拥有完整工具集且在用户监督下运行的主控 Agent 完成。标准报告格式提示词规定了最终报告的精确格式## Completed - step you finished → result / where the output is ## Handoff Plan - remaining step, plain imperative - needs: capability, e.g. gmail_send integration, memory write - inputs: concrete values already resolved from the skill user使用要求Handoff Plan 必须紧凑且具体——它是给调用方执行的操作清单不是 SKILL.md 的复述inputs 必须解析为真实值让调用方无需重读技能文件即可直接执行每个交接步骤都是提议而非已执行——调用方会通过审批门approval gate执行它们因此必须诚实、精确地描述每个步骤的行为不得为了偷懒而向上推卸步骤——只有确实需要自己没有的工具时才上交如果所有步骤都自己完成了完全省略 Handoff Plan。这个机制保证了技能执行失败时依然有可追踪的、可交接的中间结果而不是全有或全无的脆断式失败。六、重要规则执行边界与安全约束提示词最后列出执行时必须遵守的规则这些规则定义了 Skill Executor 的安全边界严格遵循技能指令——技能自身的SKILL.md是权威指南捆绑脚本先读后跑——技能引用捆绑脚本如scripts/run.py时必须先用read_workflow_resource读取后再执行禁止修改——绝不修改技能的SKILL.md或捆绑文件凭据需询问——技能需要环境变量或凭据时必须先询问用户失败需报告——shell 命令失败时报告错误并询问是重试还是中止尊重allowed-tools声明——如果技能的 frontmatter 声明了allowed-tools必须遵守。该字段在 ops_types.rs 中定义为工具提示声明由 skills_create 写入 frontmatter只读技能不用 shell——技能是只读的无 shell 命令时不使用 shell 工具优先自己完成——只有确实缺少工具时才通过 Handoff Plan 上交且要精确、诚实地描述每个步骤调用方会在审批门下执行。七、底层基础设施技能如何在后台运行Skill Executor 由skill_runtime域托管该域的职责在 skills/runtime/README.md 中列出启动/取消技能运行、读取运行元数据与日志、在脚本型技能运行前解析可复用语言运行时、托管内置的skill_executorAgent。它刻意复用了runtime_node、runtime_python与workflows三个子系统。后台运行的实际执行由 run_machinery.rs 承载spawn_workflow_run_background通过tokio::spawn以分离方式启动一次自治的技能运行并立即返回run_id。从源码结构可以推断以下关键机制迭代预算自治技能运行的最大迭代数为WORKFLOW_RUN_MAX_ITERATIONS 200刻意设为有界而非无限以控制开销同时配合重复失败熔断器阻止死循环式空转前置门禁preflight gate目前存在 GitHub 门禁运行前同步校验失败时会把 FAILED 页脚写入workspace/skills/.runs/下的运行日志终止状态运行会以DONE/DEGENERATE/FAILED/CANCELLED四种页脚收尾其中DEGENERATE是detect_repeated_line检测到模型最终回复反复重复同一行低熵循环失败模式时的状态取消机制通过取消令牌实现skills_cancel触发令牌后运行在下一个 await 点被丢弃并记录CANCELLED页脚结果轮询await_run_outcome以 750ms 间隔轮询日志文件直到终止页脚落地或预算耗尽后自动分离、交回run_id让工作继续在后台运行。这些机制共同保证了即使运行失败或退化运行日志中仍有可审计的痕迹调用方CLI、RPC 或主控 Agent都能拿到明确的终止原因。八、小结一个窄工具、宽交接的执行专家Skill Executor Agent 是 OpenHuman 技能运行时中的专职执行者。它的设计核心可以概括为三点窄工具集只有 shell、文件、技能加载与运行时解析四类能力从声明层agent.toml杜绝了越权行为强输出契约所有结果必须通过 stdout 或文件暴露空输出不等于成功诚实交接能力不足时先完成所有可做步骤再以紧凑、具体、解析好输入的 Handoff Plan 交给主控 Agent 在审批门下收尾。配合skill_runtime的run/cancel/recent_runs/read_run_log/resolve_runtimes控制器与后台运行机制OpenHuman 实现了技能编排orchestrator— 技能执行skill_executor— 运行时runtime_node / runtime_python的完整链路。读者若想继续深入可以从 skill_executor/prompt.md 与其同目录的 agent.toml 出发依次阅读 runtime/README.md、runtime/schemas.rs 与 run_machinery.rs即可完整还原从技能加载到后台运行、日志审计、失败交接的整条执行路径。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表