OpenHuman Skill Creator 智能体深度解析面向 Node 运行时的 SKILL 创作、代码路径与验证指南【免费下载链接】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本文以 OpenHuman 仓库内置的 Skill Creator 系统提示词src/openhuman/agent/registry/agents/skill_creator/prompt.md为主体结合其 agent.toml、prompt.rs、node_exec.rs 与 skills 子系统 等源码为你还原这个“技能创作智能体”的完整职责、运行时规则、底层执行链路与验证闭环。读完本文你将掌握 OpenHuman 中 SKILL.md 技能包与 Node 支撑代码的正确创作姿势理解node_exec/npm_exec/javascript控制器三类真实执行面的用法以及如何通过定向测试保证技能可运行、可被编排器调用。一、Skill Creator 是谁定位与职责边界Skill Creator 是 OpenHuman 仓库中的一个内置built-in智能体核心职责是创建或更新 OpenHuman 技能skills以及支撑它们的 JavaScript 代码。它既不是泛泛的“写代码助手”也不是只管文档的“提示词写手”而是一个横跨三层交付物的专项角色SKILL.md技能包及相关捆绑资源bundled resources需要在 Node.js 下运行的 JavaScript / TypeScript 文件仓库接线repo wiring让编排器orchestrator或其他智能体能够使用新能力定向测试或验证命令证明技能/代码确实可用。这四类交付物在 prompt.md 的 What You Build 一节中被明确列出缺一不可——写一个只有说明没有可执行后端的SKILL.md或者写一段没人调用得上的 Node 脚本都不算完成任务。从注册表配置看该智能体的系统身份信息也很清晰agent.toml字段值含义idskill_creator注册表内唯一标识display_nameSkill Creator面向用户/日志的展示名delegate_namecreate_skill被编排器委托调用时的名称when_to_useJavaScript skill/runtime specialist编排器选择该智能体的触发条件描述temperature0.3偏保守采样减少创作中的随机发散max_iterations10单次会话最大迭代轮数iteration_policyextended允许更长的迭代执行策略max_result_chars16000单次返回结果上限sandbox_modesandboxed默认在沙箱模式下执行omit_identity/omit_memory_contexttrue省略身份与记忆上下文聚焦任务本身omit_safety_preamblefalse仍保留安全前导说明此外还为其注入了 17 个具名工具[tools] named段shell、file_read、file_write、git_operations、node_exec、npm_exec、python_exec、grep、glob、list、edit、apply_patch、todowrite、plan_exit、web_fetch、lsp、update_memory_md。这份工具清单本身就是创作技能的最小工作台读写文件 搜索浏览 执行验证Node/npm/Python/shell 代码编辑edit/apply_patch/lsp 计划与收尾todowrite/plan_exit。二、运行时规则QuickJS 退役后的真实执行面提示词开篇就定下了一条硬性红线Do not assume QuickJS exists.The old embedded QuickJS runtime is gone.这意味着旧的嵌入式 QuickJS 运行时已从仓库移除Skill Creator 必须面向当前仓库真实的执行面来创作技能而非假设某个历史运行时仍然可用。仓库确实用测试固化了这一约束——prompt_tests.rs 中的build_returns_nonempty_body明确断言生成的提示词正文包含字符串Do not assume QuickJS exists.防止未来有人误删这条关键规则。与之配套的是提示词给出的三个真实执行目标node_exec一次性 JS 执行inline 代码或脚本文件npm_exec包/脚本工作流依赖安装、npm run类任务javascript控制器当核心需要暴露工具列表tool listing或具名工具分发named tool dispatch时使用。这三者在源码中都有对应的实现落点node_exec与npm_exec都是系统工具层src/openhuman/tools/impl/system/mod.rs 中的pub use node_exec::NodeExecTool;/pub use npm_exec::NpmExecTool;而javascript则是核心对外暴露的一等语言槽位src/openhuman/runtime/javascript/README.md详见下文第四节。提示词还特别强调了SKILL.md的定位先把它当作元数据/指令metadata/instructions而不是可执行行为本身。如果用户要的是可执行行为就必须同时新增或更新真正运行它的 Node 支撑代码路径。这一原则与 skills 子系统的实现一致——skills/README.md 明确写着技能通过run_skill在隔离 worker 中执行“技能正文不再被拼接进聊天轮次”说明执行与说明在架构上是解耦的。三、工作风格先看模式再做小步组合提示词的 Working Style 一节给出了四条创作方法论直接决定了技能代码在仓库中的演进方式先检查既有模式再发明新范式Inspect existing patterns before inventing a new one偏好小而可组合的改动而非新建一套并行框架Prefer small, composable changes over a new parallel framework新增 JS 执行能力时走既有的 agent 与 tool 表面接进编排器/子智能体而不是隐藏的旁路wire it to orchestrator/subagents through the existing agent and tool surfaces instead of hidden side paths命名与仓库现有的javascript、tools、agent 定义保持一致行为变化时补充或更新测试。从仓库结构可以印证这套原则的落地技能与工具相关的命名确实高度统一——运行时模块统一叫javascriptsrc/openhuman/runtime/javascript/mod.rs工具实现集中在 src/openhuman/tools/impl/system/内置智能体则统一登记在 src/openhuman/agent/registry/agents/同目录下还有code_executor、tool_maker等兄弟智能体分工定位各异。Skill Creator 的任务边界正是“沿着这套既有表面做增量”而不是另起炉灶。四、node_exec/npm_exec/javascript控制器三类执行面的源码级剖析4.1node_exec受管的 Node.js 执行工具node_exec的实现位于 src/openhuman/tools/impl/system/node_exec.rs文档注释给出了两种输入模式模式参数最终调用形态Inline 代码inline_code: console.log(11)node -e code脚本路径script_path: scripts/run.jsargsnode path args...两条约束值得创作者注意inline_code与script_path必须二选一Exactly one of inline_code / script_path must be supplied两者同时提供或都缺失都会直接返回错误脚本必须位于工作区内script_path以工作区为根解析绝对路径、..逃逸、Windows 盘符前缀都会被拒绝见resolve_script_path实现node_exec.rs。node_exec的参数 schema可从工具的parameters_schema中看到完整字段如下{ inline_code: JavaScript source passed to node -e. Mutually exclusive with script_path., script_path: Path (relative to workspace) to a .js/.mjs/.cjs file. Mutually exclusive with inline_code., args: Positional arguments appended after the script. Ignored for inline_code., timeout_secs: Optional wall-clock timeout (seconds) before the process is killed. }超时策略是 Skill Creator 需要特别记住的一条设计node_exec默认无超时因为它要跑合法的长任务bundler、solver、测试运行不能被默认上限硬杀注释中引用了 issue #4023只有显式传入timeout_secs时才启用截止时间且上限封顶为NODE_TIMEOUT_MAX_SECS 1800秒node_exec.rs。node_timeout_policy与测试node_exec_tests.rs共同验证了这一行为不传或传0⇒ToolTimeout::Unbounded传99999⇒ 被钳制到 1800s。安全模型是另一层硬约束任意 JS 执行属于Write权限桶external_effect_with_args返回gate_decision(CommandClass::Write) GateDecision::Prompt在 ask-before-edit 模式下会走人工审批闸门只读模式下直接拒绝执行[policy-blocked] Action blocked: the agent is in read-only mode and cannot execute code.——注释指出这修复了历史上node -e绕过自治检查的问题执行前还有跨 profile 命令扫描check_cross_profile_command与速率限制is_rate_limited/record_action两道闸子进程环境使用白名单SAFE_ENV_VARSnode_exec.rs并env_clear()后重建保证密钥不会泄漏进 Node 子进程PATH会被前置受管 Node 的 bin 目录stdout/stderr 各有1MB 上限MAX_OUTPUT_BYTES 1_048_576超出部分截断并追加... [stdout truncated at 1MB]提示。Node 运行时从哪来node_exec不假设系统已装 Node而是通过NodeBootstrap解析——首次调用时解析若PATH上没有兼容的node会下载并解压一份受管managedNode.js 发行版后续调用复用缓存安装见 node_exec.rs 模块注释。这套解析/下载/解压逻辑集中在 src/openhuman/runtime/node/node_exec、npm_exec、shell都通过openhuman::runtime::javascript::NodeBootstrap复用见 runtime/javascript/README.md 的 Used by 一节。两条进阶执行路径源码注释均有标注沙箱路径当智能体的sandbox_mode为Sandboxed时Skill Creator 默认正是sandboxed执行会被路由到沙箱后端Docker / OS 级cwd_jail/ 文档化的 noop与ShellTool获得相同的隔离保证沙箱路径必须有有限截止时间未显式指定时用 24h 的“有效无界”上限兜底。运行时池runtime poolinline 代码在启用池时会被路由到一组常驻的nodeworkerissue #5106一个 fleet 只付一份解释器开销process.chdir相关的代码会自动降级走旧式逐次 spawn因为 Node 禁止在worker_threads内chdir池饱和时返回可重试的繁忙错误post-dispatch 失败则绝不重试以避免重复执行。最后工具描述中有一条对创作者至关重要的使用提醒只有程序的 stdout/stderr 会被捕获返回——你不console.log的值对智能体不可见退出码为 0 但不打印任何内容的脚本会返回空结果。因此创作 JS 技能时务必显式打印所需输出例如console.log(JSON.stringify(result))。4.2npm_exec包与脚本工作流npm_exec与node_exec是兄弟工具同在 src/openhuman/tools/impl/system/mod.rs 中导出面向包/脚本类工作流与node_exec共享同样的安全闸门、环境清洁策略以及NodeBootstrap的运行时解析runtime/javascript/README.md 确认npm_exec.rs同样 importNodeBootstrap。当技能需要安装依赖或运行 npm 脚本时Skill Creator 应优先选择它而不是用shell裸拼命令。4.3javascript控制器核心层的工具列表与具名分发javascript是核心对外暴露的一等语言槽位但它在架构上是一个纯重导出门面rename-only facadecrate::openhuman::runtime::javascript表面不拥有任何逻辑全部pub use自runtime_noderuntime/javascript/README.md这样未来若出现 Python/Ruby 或另一个 JS 后端无需改动调用方即可替换实现。该门面暴露两个 RPC 方法runtime/node/schemas.rs 定义经门面以all_javascript_*名称接入src/core/all.rs方法输入输出javascript.list_tools无tools工具元数据数组name、description、category、permission_level、scope、supports_markdown、parametersjavascript.execute_tooltool_name必填、args可选默认{}、prefer_markdown可选 booltool_name、elapsed_msu64、resultMCP 风格 ToolResult{content, is_error, markdownFormatted?}实现上runtime_node/rpc.rs/ops.rs处理器通过config::rpc::load_config_with_timeout加载配置、用tools::all_tools_with_runtime构建完整工具集然后按精确名称列出或分发工具每次execute_tool都会重建整个工具集没有持久工具缓存分发结果以RpcOutcomeCLI 兼容 JSON返回并在执行前后通过全局事件总线发布ToolExecutionStarted/ToolExecutionCompleted事件session_id为字面量javascript。对 Skill Creator 而言这条路径意味着当技能需要让核心以“工具”形态暴露 JS 能力工具列表 具名分发时接javascript控制器当只是跑一段一次性脚本或一个技能测试时用node_exec/npm_exec。五、SKILL.md 规范技能子系统的元数据契约既然 Skill Creator 的交付物之一是SKILL.md技能包就有必要理解仓库对技能格式的既有约定。skills/README.md 说明技能是 agentskills.io 风格的一个目录包含带 YAML frontmatter 和 Markdown 指令的SKILL.md。子系统负责发现与解析扫描技能目录并解析 frontmatter 与指令正文作用域解析SkillScope枚举区分User/Project/Legacy三种发现作用域名字冲突时决定优先级信任标记强制trust-marker enforcement与资源读取安装 / 卸载通过 RPCskills.{skills_list, skills_read_resource, skills_create, skills_install_from_url, skills_uninstall}暴露执行run_skill在隔离 worker中执行技能正文不再拼接进聊天轮次技能以紧凑的## Installed Skills目录形式呈现给智能体。资源边界上单个资源的 RPC 载荷上限为MAX_SKILL_RESOURCE_BYTES 128 * 1024128KBskills/ops.rs。因此 Skill Creator 创作的技能包应保持资源精简避免把大体积二进制捆进技能目录。六、验证要求与输出契约可证明地工作而非声称工作提示词的 Validation 与 Output Contract 两节构成了 Skill Creator 的完成标准验证Validation每次编辑后运行定向检查对技能验证SKILL.md的形态shape以及任何你触碰过的运行时代码路径对 JavaScript执行最窄的有用命令——node_exec、npm_exec或项目测试命令——并在停止前修复失败。这条“先跑最窄命令再收工”的纪律与node_exec的实现哲学完全一致默认无超时是为了长任务能跑完1MB 输出上限是为了结果可回传退出码 双流回显node_exec.rs是为了让智能体能就地诊断失败而不是盲目重跑注释引用 issue #4095。输出契约Output Contract收尾时三件事必须交代返回你改了什么Return what you changed说明编排器或其他智能体应如何调用它State how the orchestrator or another agent is expected to invoke it明确指出端到端执行还缺什么Call out anything still missing from full end-to-end execution。七、系统提示词是怎么组装出来的prompt.rs 源码视角Skill Creator 的最终提示词并非只有 prompt.md 一份静态文本而是由 prompt.rs 的build(ctx)在运行时按固定顺序拼装ARCHETYPEinclude_str!(prompt.md)将 prompt.md 的正文编译进二进制作为提示词骨架用户文件段render_user_files若上下文携带用户文件则追加工具段render_tools渲染可见工具列表安全段render_safety追加安全前导说明——与agent.toml中omit_safety_preamble false呼应工作区段render_workspace追加工作区上下文。也就是说你读到的 prompt.md 只是“骨架”实际运行时的提示词是骨架 用户文件 工具清单 安全说明 工作区上下文的组合。这也是为什么agent.toml中omit_identity true/omit_memory_context true会影响最终提示词形态——Skill Creator 被刻意设计为“轻身份、重任务”的专项角色。八、测试闭环规则如何被固化Skill Creator 相关的测试覆盖了两个层面提示词层面build_returns_nonempty_bodyprompt_tests.rs验证build()产出的提示词非空且包含Do not assume QuickJS exists.防止运行时规则被意外删改执行工具层面node_exec_tests.rssrc/openhuman/tools/impl/system/node_exec_tests.rs以单元测试固化shell_quote的单引号转义与元字符中和、node_timeout_policy的无界默认与 1800s 钳制、process.chdir片段走旧式 spawn 的降级逻辑、resolve_script_path对空路径/绝对路径/逃逸路径的拒绝。这两层测试分别对应提示词中“Add or update tests when behavior changes”和“For JavaScript: execute the narrowest useful … test command”的要求——规则不是口头约定而是被测试钉死的实现事实。九、实践速览创作一个技能的最小闭环综合以上全部约束Skill Creator以及人工开发者创作一个带可执行行为的技能可以遵循如下最小闭环观察先浏览 src/openhuman/skills/ 与 src/openhuman/tools/impl/system/ 的既有模式确认命名与结构写元数据创建含 YAML frontmatter 的SKILL.md内容先行声明技能意图与调用方式写执行代码新增 Node.js 支撑脚本.js/.mjs/.cjs置于工作区内并在脚本中显式console.log需要回传的结果接线若需被编排器或其他智能体调用走既有 agent/tool 表面接入必要时接javascript控制器的工具列表/具名分发不要发明隐藏旁路验证用node_execinline 或 script_path或npm_exec执行最窄命令必要时给长任务显式传timeout_secs上限 1800s收尾按输出契约汇报改动清单、调用方式与尚缺的端到端环节并补上相应测试。这套闭环既是对 prompt.md 六节内容的完整落地也是仓库源码prompt.rs、node_exec.rs、skills/README.md、runtime/javascript/README.md所支撑的、可验证可追溯的创作流程。对想在 OpenHuman 上扩展能力的开发者来说Skill Creator 的规则集本身就是一份“如何正确地给这个系统加新技能”的权威范本。【免费下载链接】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），仅供参考