OpenHuman Skills 子系统完全指南SKILL.md 发现、作用域解析、信任标记与安全执行【免费下载链接】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 仓库中 src/openhuman/skills/README.md 为核心系统拆解 Skills 子系统的完整能力边界如何发现并解析 agentskills.io 风格的技能包一个含 YAML frontmatter 与 Markdown 指令的SKILL.md目录、User / Project / Legacy 三种作用域如何解析与冲突裁决、信任标记trust marker如何门控项目级技能加载、资源读取的安全边界以及技能如何通过run_skill在隔离 worker 中执行。读完本文你将掌握技能包目录布局、frontmatter 字段语义、安装/卸载/资源读取的 RPC 面、事件总线触发机制以及仓库源码中对应的实现与测试位置。注当前仓库已把技能领域内部术语从 skill 迁移为 workflow如ops_types.rs中Workflow/WorkflowScope/WORKFLOW.md但SKILL.md仍是向后兼容的主定义文件RPC 面也保留skills.*命名全文按既有公开 API 名称展开。Skills 子系统的职责边界根据 README 与 mod.rs 模块文档Skills 子系统只负责技能的发现、解析、作用域管理、信任标记执行、资源读取与安装/卸载明确不拥有运行时执行内部机制与通用工具执行后者属于tools//javascript/。发现与解析扫描目录、读取SKILL.md的 YAML frontmatter 与 Markdown 指令体见 ops_discover.rs 与 ops_parse.rs。作用域解析User vs Project vs Legacy以及后续新增的 Profile 作用域的优先级裁决。信任标记执行项目级技能仅在workspace/.openhuman/trust存在时加载。资源读取读取技能捆绑的子资源scripts/、references/、assets/等并做路径穿越/符号链接/大小/UTF-8 四重防护。安装 / 卸载基于 HTTPS 的 URL 安装与卸载见 ops_install_part_01.rs。技能最终以紧凑的## Installed Skills目录形式暴露给 Agent并通过run_skill在隔离 worker 中执行——技能正文不再被拼接进聊天轮次。README 明确bodies are no longer spliced into chat turns这是与早期提示词拼接式技能实现的关键区别。从 mod.rs 还可以看到两个重要架构事实编译期特性门控pub mod skills;始终编译作为 facade而ops、bus、schemas、registry等行为性子模块由默认开启的skillsCargo feature 门控关闭时由 stub.rs 提供同签名空实现。类型不参与门控types与ops_types在两种 feature 方向下都编译因为ToolResult/ToolContent被tools::traits再导出为整个 crate 的统一工具结果类型约 236 个文件消费Workflow/WorkflowFrontmatter/WorkflowScope也出现在常开的 agent-harness 与提示词签名中。公开 API 面Public surfaceREADME 列出的公开 API 全部可在源码中逐项确认公开项位置说明pub enum SkillScope现为WorkflowScopeops_types.rs发现作用域User/Project/Legacy另有Profile决定同名冲突时的优先级MAX_SKILL_RESOURCE_BYTES现为MAX_WORKFLOW_RESOURCE_BYTES 128 * 1024ops_types.rs单资源 RPC 载荷上限128 KBpub use ops::*mod.rs再导出发现、解析、安装、卸载、资源读取与 frontmatter 类型pub struct ToolResult/pub enum ToolContenttypes.rs技能/工具执行返回的内容块pub mod busbus.rs在全局事件总线上发出技能事件RPCskills.{skills_list, skills_read_resource, skills_create, skills_install_from_url, skills_uninstall}schemas/mod.rs 与 controller_schemas.rs通过all_skills_controller_schemas/all_skills_registered_controllers注册RPC 控制器全部通过持久化配置层config::load_config_with_timeout解析活动工作区因此 CLI 与 UI 看到的是同一份技能目录调用方无需手动传入工作区路径。技能包格式SKILL.md frontmatter 捆绑资源目录布局与定义文件一个技能就是一个目录核心定义文件是SKILL.mdYAML frontmatter含name、description等必填字段 Markdown 指令体。可选捆绑资源位于兄弟子目录中。从 ops_types.rs 的RESOURCE_DIRS可以看到当前支持的资源目录scripts/、references/、assets/传统三个templates/、examples/、prompts/Hermes 风格技能常见目录按可浏览资源处理不作为可执行运行时入口此外 ops_types.rs 定义了向后兼容的文件名常量常量文件名状态WORKFLOW_MDWORKFLOW.md当前主定义文件create/update 写入WORKFLOW_TOMLworkflow.toml当前 sidecar 清单inputs / when_to_use / [github]SKILL_MDSKILL.md旧定义文件skills→workflows 重命名前编写的技能仍会读取SKILL_TOMLskill.toml旧 sidecar 清单向后兼容读取SKILL_JSONskill.json更早的清单格式向后兼容读取Frontmatter 字段语义WorkflowFrontmatterops_types.rs严格对齐 agentskills.io SKILL.md 规范字段必填说明name是技能名也是同名冲突的裁决键description是短描述用于目录摘要license否许可证compatibility否兼容性说明platforms否平台兼容提示Hermes 风格缺省表示全平台metadata否规范兼容的元数据 mapversion、author、tags等非必填字段应放这里allowed-tools否技能作者声明的依赖工具非强制提示宿主决定暴露什么triggers否激活该技能的事件触发模式见下文事件总线章节extra否规范扩展的落点#[serde(flatten)]旧式顶层version/author/tags会触发迁移警告解析时对顶层遗留字段的兼容处理可参看 ops_types.rs 的extract_version/extract_author/extract_tags优先读metadata.*否则回退到顶层并在warnings中记录弃用提示。frontmatter 解析实现ops_parse.rs 的parse_workflow_md/parse_workflow_md_str展示了解析细节以首行---开启 frontmatter 块以第二个---终止未终止的 frontmatter 块返回None解析失败。无 frontmatter 时整文件视为指令体返回默认WorkflowFrontmatter。YAML 反序列化失败不致命记录frontmatter parse error警告并回退到默认 frontmatter保证技能仍可被发现。load_from_workflow_md同文件后半部分将SKILL.md组装为完整的Workflow结构inventory_resourcesops_parse.rs浅扫技能目录枚举资源——注意它用symlink_metadata拒绝符号链接资源根且walk_files递归时同样跳过符号链接防止无限递归与目录外泄漏。作用域Scope解析与冲突裁决三种作用域 ProfileREADME 描述的是三作用域模型当前源码已扩展为四作用域ops_types.rs作用域磁盘位置优先级User默认~/.openhuman/skills/name/或~/.agents/skills/name/1Projectworkspace/.openhuman/skills/name/或workspace/.agents/skills/name/需信任标记2Legacyworkspace/skills/name/扁平旧布局0Profileworkspace/personalities/id/skills/仅活动 profile 的轮次可见3从源码结构看Profile 作用域是后来为按 Agent profile 私有技能新增的discover_workflows_with_profile扫描 profile 私有根目录无需信任标记目录由 core 管理且对所属 profile 在同名冲突中拥有最高优先级会遮蔽同名的全局技能。默认会话与其他 profile 完全不受影响None与discover_workflows逐字节等价。信任标记Trust Marker项目级技能只有在workspace/.openhuman/trust存在时才加载。is_workspace_trustedops_discover.rs实现极简文件内容被忽略存在即信任。这是关键安全边界——克隆一个陌生仓库后skills/目录中的项目级技能默认不会进入 Agent 上下文用户必须显式放置信任标记才会加载。发现顺序与冲突裁决discover_filteredops_discover.rs的实现要点扫描顺序User 根 → Project 根仅 trusted 时→ Legacyws/skills/→ Profile 根。HashMap以 name 为键后注册者覆盖先注册者。优先级函数precedenceLegacy0 User1 Project2 Profile3。同名冲突时高优先级保留低优先级技能被丢弃并在保留者的warnings中记录遮蔽原因如shadowed Project-scope skill ... at path这些警告会浮现在目录摘要中供用户调试。稳定性保证read_dir顺序未定义为避免同名兄弟目录跨运行产生非确定性胜者scan_root_inner先按磁盘目录名排序再处理。排除规则EXCLUDED_SKILL_DIRS跳过.git、.github、node_modules、__pycache__、.venv等常见无关目录点开头的目录名也跳过。符号链接防护用file_type()而非path.is_dir()判断——is_dir()会解引用符号链接可能重新打开目录外加载漏洞manifest 文件也要求是真实非符号链接常规文件。发现结果按name排序输出。README 提到的 project-scope wins 在代码中得到印证并且冲突警告中同时给出dir_name、name、作用域与磁盘位置方便定位。资源读取的安全边界read_workflow_resource/read_workflow_resource_with_profileops_discover.rs是 README 所述resource reading的实现核心防护层层递进参数校验skill_id与relative_path非空拒绝绝对路径拒绝任何..、.、空组件与 Windows 前缀Component::ParentDir | CurDir | RootDir | Prefix。技能解析复用标准发现管线含信任标记与 profile 根将读取范围限定在已安装技能集合内。根目录校验先canonicalize技能根要求真实目录非符号链接。叶子检查用symlink_metadata预先拒绝符号链接与非常规文件socket/fifo/目录。大小门禁leaf_meta.len() MAX_WORKFLOW_RESOURCE_BYTES (128 KB)直接拒绝——先看元数据再读文件避免为超大文件分配缓冲区。穿越校验canonicalize完整路径并断言其仍在技能根之内。严格 UTF-8非 UTF-8 内容直接拒绝不做 lossy 替换宁可拒绝二进制文件也不静默损坏。resolve_workflow_for_resource同文件 ops_discover.rs支持用dir_name磁盘目录 id或namefrontmatter 显示名定位技能二者歧义时报错明确要求使用目录 id。安装 / 卸载HTTPS URL 安装器install_workflow_from_urlops_install_part_01.rs 起实现了 README 所述的 URL 安装核心常量常量值含义DEFAULT_INSTALL_TIMEOUT_SECS60s默认拉取超时MAX_INSTALL_TIMEOUT_SECS600s调用方可请求的超时上限MAX_INSTALL_URL_LEN2048URL 长度上限MAX_WORKFLOW_MD_BYTES1 MiBSKILL.md 正文大小上限防御恶意/错误配置主机流式返回无限响应网络 I/O 前的验证URL 必须为https://拒绝回环、私网、link-local、组播、共享地址段、localhost及.local/.localhostmDNS 主机名。github.com/o/r/blob/b/p自动改写为raw.githubusercontent.com/o/r/b/p方便用户直接粘贴浏览器地址。路径必须以.md结尾大小写不敏感repo/tree URL 与 tarball 被拒绝unsupported url form:。timeout_secs被钳制到MAX_INSTALL_TIMEOUT_SECS。运行时行为先查Content-Length头下载后再校验缓冲长度双保险防谎报头。frontmatter 校验按 agentskills.io 规范要求name与description必填。slug 派生优先metadata.id否则用清洗后的name。若目标目录已有SKILL.md视为幂等成功报告已安装其他目录冲突保持致命已有文件绝不静默覆盖。写入原子化目标目录写SKILL.md.tmp成功后rename。安装完成后重新发现完整目录返回自调用开始新出现的 skill slug 列表new_skills。安装目的地为workspace/.openhuman/skills/slug/SKILL.md。README 所在模块的注释解释了设计动因vercel-labsskillsCLI 写入的 per-agent 目录./claude-code/skills/、./cursor/skills/等与 OpenHuman 的技能布局不兼容因此直接拉取 SKILL.md 并写入发现管线可见的布局。一个值得注意的运维细节HTTP localhost 安装默认被拒需显式设置OPENHUMAN_SKILL_INSTALL_ALLOW_LOCAL_HTTP1仅用于本地 fixture。事件总线与触发器bus.rsbus.rs 实现了 README 中 emits skill events on the global event bus 的承诺并进一步支撑了WorkflowFrontmatter::triggers字段TriggerPattern::parse将composio、composio/trigger_received、cron、channel/inbound_message等原始字符串解析为domain 可选event_slug。裸 domain无/匹配该域内任何事件slug 为*也视为匹配整个域。TriggerPattern::matches先比对event.domain()slug 限定模式在DomainEvent暴露稳定slug()之前暂不能精确匹配源码留有TODO(#skills-triggers)实现上保守地避免静默匹配整个域。TriggeredWorkflowIndexTriggeredSkillSubscriber启动时为声明triggers:的技能建立索引并注册订阅者匹配事件到达时记录应激活的技能。实际 agent-session 启动有意不在此处——它需要完整 harness 上下文provider、memory、config由 channel runtime 在总线初始化后接线本模块只提供类型管道与观察者。运行时执行catalog 与 runtime 两个子模块虽然 README 声明Does NOT own runtime execution internals当前仓库已将技能领域进一步组织为两个子模块理解它们有助于定位源码catalog技能注册表catalog/README.md 说明skill_registry负责远程技能目录与已装技能生命周期拉取并缓存远程目录默认https://hermes-agent.nousresearch.com/docs/api/skills.json。核心启动时异步强制刷新远程目录OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0可关闭不阻塞核心就绪。提供浏览/搜索、派生 Hermes 内置与可选技能的安装 URL、安装到用户技能目录、卸载用户作用域技能并托管内置skill_setupagent。可用环境变量覆盖用于生产脚本与确定性测试OPENHUMAN_SKILL_REGISTRY_CATALOG_URLhttps://example.com/skills.json OPENHUMAN_SKILL_REGISTRY_DOWNLOAD_BASE_URLhttps://example.com/skills OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0生产冒烟示例openhuman skill_registry schemas openhuman skill_registry browse --force_refresh true openhuman skill_registry search --query git openhuman skill_registry sources openhuman skill_registry install --entry_id git-helper openhuman skill_registry uninstall --name git-helperruntime技能执行runtime/README.md 说明skill_runtime拥有已装SKILL.md工作流的执行启动与取消技能运行、读取近期运行元数据与运行日志。脚本型技能运行前解析可复用的语言运行时复用runtime_nodeNode.js、npm、npx 与 PATH 注入与runtime_pythonPython 解释器解析与进程启动复用workflows的发现、元数据、资源与运行日志。托管内置skill_executoragent。生产冒烟示例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兼容性承诺既有openhuman workflows run、workflows cancel与运行日志 RPC 保持可用新脚本应优先使用skill_runtime命名空间。技能即带输入的 Agentregistry.rs 揭示了技能与 Agent 的关系一个技能就是一个AgentDefinition加上声明的[[inputs]]。agent 字段id、system_prompt、tools、max_iterations、sandbox_mode等从同一skill.toml扁平化注入因此技能本质是同时广告自己所需输入的、可运行的 Agent。WorkflowInputname/description/required/type在skill_run时取值并渲染进提示词render_inputs_block。[github]块含IdentityMatch枚举Strict/Any/None是可选预检门——存在且required true时orchestrator 启动前会运行 GitHub 身份一致性预检。与 Agent 层的交互点README 的 Calls into / Called by 章节说明了技能目录如何进入 Agent 上下文## Installed Skills目录渲染prompt.rs 渲染该章节数据源是PromptContext上的技能列表context.rs。每轮注入turn.rs 是 per-turn 注入点fork_context.rs 在 fork 上下文时传播注入的技能。提示词章节mod.rs 与 types.rs 渲染## Available Skills目录章节。工具结果类型共享traits.rs 消费ToolResult/ToolContent。工作区引导ops.rs 在工作区启动时触碰技能目录布局。集成 agentintegrations_agent/prompt.rs 读取技能目录。控制器注册all.rs 完成all_skills_registered_controllers的接线。测试布局README 指出本领域没有独立*_tests.rs文件单测与实现同文件共存#[cfg(test)] mod tests。当前仓库结构有所演进实测测试文件分布为顶层ops_tests.rs、ops_types.rstypes_tests.rs等、bus_tests.rs、registry_tests.rs、preflight_tests.rs、run_log_tests.rs、tools_tests.rs、schemas_tests.rs。作用域与解析专项ops_discover_include_skills_tests_tests.rs、ops_discover_profile_scope_tests_tests.rs、ops_create_render_skill_toml_tests_tests.rs、ops_install_install_fetch_tests_tests.rs。端到端e2e_plumbing_tests.rs 与 e2e_run_tests.rs。跨切面行为README 指出由 turn_tests.rs 与 runtime_tests.rs 间接覆盖agent skill 的组合行为。小结一张图看懂技能生命周期一个技能从落地到执行完整经过以下阶段落地skills.install_from_url经 HTTPS 拉取SKILL.md校验 URL 安全、大小与超时、frontmatter 必填项、slug 冲突原子写入workspace/.openhuman/skills/slug/或由skills.create脚手架新技能或用户手动放置到~/.openhuman/skills/。发现启动/轮次时扫描 User / Project需信任标记/ Legacy / Profile 根按优先级吸收同名冲突产出按 name 排序的目录。暴露技能以## Installed Skills紧凑目录进入 Agent 提示词skills.list/skills.describe含[[inputs]]供 UI 渲染动态表单。资源skills.read_resource以 128 KB 上限 路径穿越/符号链接/UTF-8 防护读取捆绑资源。触发声明triggers:的技能由事件总线订阅者匹配DomainEvent记录激活。执行skill_runtime run/run_skill在隔离 worker 中运行复用 Node/Python 语言运行时skills.cancel取消运行日志经run_log查询。至此你已掌握 OpenHuman Skills 子系统的目录规范、frontmatter 语义、四作用域裁决、信任标记门控、资源读取安全边界、URL 安装器的验证链、事件触发机制与运行时架构——这些都可以直接对照 src/openhuman/skills/ 目录下的源码与测试继续深挖。【免费下载链接】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），仅供参考
OpenHuman Skills 子系统完全指南：SKILL.md 发现、作用域解析、信任标记与安全执行
OpenHuman Skills 子系统完全指南SKILL.md 发现、作用域解析、信任标记与安全执行【免费下载链接】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 仓库中 src/openhuman/skills/README.md 为核心系统拆解 Skills 子系统的完整能力边界如何发现并解析 agentskills.io 风格的技能包一个含 YAML frontmatter 与 Markdown 指令的SKILL.md目录、User / Project / Legacy 三种作用域如何解析与冲突裁决、信任标记trust marker如何门控项目级技能加载、资源读取的安全边界以及技能如何通过run_skill在隔离 worker 中执行。读完本文你将掌握技能包目录布局、frontmatter 字段语义、安装/卸载/资源读取的 RPC 面、事件总线触发机制以及仓库源码中对应的实现与测试位置。注当前仓库已把技能领域内部术语从 skill 迁移为 workflow如ops_types.rs中Workflow/WorkflowScope/WORKFLOW.md但SKILL.md仍是向后兼容的主定义文件RPC 面也保留skills.*命名全文按既有公开 API 名称展开。Skills 子系统的职责边界根据 README 与 mod.rs 模块文档Skills 子系统只负责技能的发现、解析、作用域管理、信任标记执行、资源读取与安装/卸载明确不拥有运行时执行内部机制与通用工具执行后者属于tools//javascript/。发现与解析扫描目录、读取SKILL.md的 YAML frontmatter 与 Markdown 指令体见 ops_discover.rs 与 ops_parse.rs。作用域解析User vs Project vs Legacy以及后续新增的 Profile 作用域的优先级裁决。信任标记执行项目级技能仅在workspace/.openhuman/trust存在时加载。资源读取读取技能捆绑的子资源scripts/、references/、assets/等并做路径穿越/符号链接/大小/UTF-8 四重防护。安装 / 卸载基于 HTTPS 的 URL 安装与卸载见 ops_install_part_01.rs。技能最终以紧凑的## Installed Skills目录形式暴露给 Agent并通过run_skill在隔离 worker 中执行——技能正文不再被拼接进聊天轮次。README 明确bodies are no longer spliced into chat turns这是与早期提示词拼接式技能实现的关键区别。从 mod.rs 还可以看到两个重要架构事实编译期特性门控pub mod skills;始终编译作为 facade而ops、bus、schemas、registry等行为性子模块由默认开启的skillsCargo feature 门控关闭时由 stub.rs 提供同签名空实现。类型不参与门控types与ops_types在两种 feature 方向下都编译因为ToolResult/ToolContent被tools::traits再导出为整个 crate 的统一工具结果类型约 236 个文件消费Workflow/WorkflowFrontmatter/WorkflowScope也出现在常开的 agent-harness 与提示词签名中。公开 API 面Public surfaceREADME 列出的公开 API 全部可在源码中逐项确认公开项位置说明pub enum SkillScope现为WorkflowScopeops_types.rs发现作用域User/Project/Legacy另有Profile决定同名冲突时的优先级MAX_SKILL_RESOURCE_BYTES现为MAX_WORKFLOW_RESOURCE_BYTES 128 * 1024ops_types.rs单资源 RPC 载荷上限128 KBpub use ops::*mod.rs再导出发现、解析、安装、卸载、资源读取与 frontmatter 类型pub struct ToolResult/pub enum ToolContenttypes.rs技能/工具执行返回的内容块pub mod busbus.rs在全局事件总线上发出技能事件RPCskills.{skills_list, skills_read_resource, skills_create, skills_install_from_url, skills_uninstall}schemas/mod.rs 与 controller_schemas.rs通过all_skills_controller_schemas/all_skills_registered_controllers注册RPC 控制器全部通过持久化配置层config::load_config_with_timeout解析活动工作区因此 CLI 与 UI 看到的是同一份技能目录调用方无需手动传入工作区路径。技能包格式SKILL.md frontmatter 捆绑资源目录布局与定义文件一个技能就是一个目录核心定义文件是SKILL.mdYAML frontmatter含name、description等必填字段 Markdown 指令体。可选捆绑资源位于兄弟子目录中。从 ops_types.rs 的RESOURCE_DIRS可以看到当前支持的资源目录scripts/、references/、assets/传统三个templates/、examples/、prompts/Hermes 风格技能常见目录按可浏览资源处理不作为可执行运行时入口此外 ops_types.rs 定义了向后兼容的文件名常量常量文件名状态WORKFLOW_MDWORKFLOW.md当前主定义文件create/update 写入WORKFLOW_TOMLworkflow.toml当前 sidecar 清单inputs / when_to_use / [github]SKILL_MDSKILL.md旧定义文件skills→workflows 重命名前编写的技能仍会读取SKILL_TOMLskill.toml旧 sidecar 清单向后兼容读取SKILL_JSONskill.json更早的清单格式向后兼容读取Frontmatter 字段语义WorkflowFrontmatterops_types.rs严格对齐 agentskills.io SKILL.md 规范字段必填说明name是技能名也是同名冲突的裁决键description是短描述用于目录摘要license否许可证compatibility否兼容性说明platforms否平台兼容提示Hermes 风格缺省表示全平台metadata否规范兼容的元数据 mapversion、author、tags等非必填字段应放这里allowed-tools否技能作者声明的依赖工具非强制提示宿主决定暴露什么triggers否激活该技能的事件触发模式见下文事件总线章节extra否规范扩展的落点#[serde(flatten)]旧式顶层version/author/tags会触发迁移警告解析时对顶层遗留字段的兼容处理可参看 ops_types.rs 的extract_version/extract_author/extract_tags优先读metadata.*否则回退到顶层并在warnings中记录弃用提示。frontmatter 解析实现ops_parse.rs 的parse_workflow_md/parse_workflow_md_str展示了解析细节以首行---开启 frontmatter 块以第二个---终止未终止的 frontmatter 块返回None解析失败。无 frontmatter 时整文件视为指令体返回默认WorkflowFrontmatter。YAML 反序列化失败不致命记录frontmatter parse error警告并回退到默认 frontmatter保证技能仍可被发现。load_from_workflow_md同文件后半部分将SKILL.md组装为完整的Workflow结构inventory_resourcesops_parse.rs浅扫技能目录枚举资源——注意它用symlink_metadata拒绝符号链接资源根且walk_files递归时同样跳过符号链接防止无限递归与目录外泄漏。作用域Scope解析与冲突裁决三种作用域 ProfileREADME 描述的是三作用域模型当前源码已扩展为四作用域ops_types.rs作用域磁盘位置优先级User默认~/.openhuman/skills/name/或~/.agents/skills/name/1Projectworkspace/.openhuman/skills/name/或workspace/.agents/skills/name/需信任标记2Legacyworkspace/skills/name/扁平旧布局0Profileworkspace/personalities/id/skills/仅活动 profile 的轮次可见3从源码结构看Profile 作用域是后来为按 Agent profile 私有技能新增的discover_workflows_with_profile扫描 profile 私有根目录无需信任标记目录由 core 管理且对所属 profile 在同名冲突中拥有最高优先级会遮蔽同名的全局技能。默认会话与其他 profile 完全不受影响None与discover_workflows逐字节等价。信任标记Trust Marker项目级技能只有在workspace/.openhuman/trust存在时才加载。is_workspace_trustedops_discover.rs实现极简文件内容被忽略存在即信任。这是关键安全边界——克隆一个陌生仓库后skills/目录中的项目级技能默认不会进入 Agent 上下文用户必须显式放置信任标记才会加载。发现顺序与冲突裁决discover_filteredops_discover.rs的实现要点扫描顺序User 根 → Project 根仅 trusted 时→ Legacyws/skills/→ Profile 根。HashMap以 name 为键后注册者覆盖先注册者。优先级函数precedenceLegacy0 User1 Project2 Profile3。同名冲突时高优先级保留低优先级技能被丢弃并在保留者的warnings中记录遮蔽原因如shadowed Project-scope skill ... at path这些警告会浮现在目录摘要中供用户调试。稳定性保证read_dir顺序未定义为避免同名兄弟目录跨运行产生非确定性胜者scan_root_inner先按磁盘目录名排序再处理。排除规则EXCLUDED_SKILL_DIRS跳过.git、.github、node_modules、__pycache__、.venv等常见无关目录点开头的目录名也跳过。符号链接防护用file_type()而非path.is_dir()判断——is_dir()会解引用符号链接可能重新打开目录外加载漏洞manifest 文件也要求是真实非符号链接常规文件。发现结果按name排序输出。README 提到的 project-scope wins 在代码中得到印证并且冲突警告中同时给出dir_name、name、作用域与磁盘位置方便定位。资源读取的安全边界read_workflow_resource/read_workflow_resource_with_profileops_discover.rs是 README 所述resource reading的实现核心防护层层递进参数校验skill_id与relative_path非空拒绝绝对路径拒绝任何..、.、空组件与 Windows 前缀Component::ParentDir | CurDir | RootDir | Prefix。技能解析复用标准发现管线含信任标记与 profile 根将读取范围限定在已安装技能集合内。根目录校验先canonicalize技能根要求真实目录非符号链接。叶子检查用symlink_metadata预先拒绝符号链接与非常规文件socket/fifo/目录。大小门禁leaf_meta.len() MAX_WORKFLOW_RESOURCE_BYTES (128 KB)直接拒绝——先看元数据再读文件避免为超大文件分配缓冲区。穿越校验canonicalize完整路径并断言其仍在技能根之内。严格 UTF-8非 UTF-8 内容直接拒绝不做 lossy 替换宁可拒绝二进制文件也不静默损坏。resolve_workflow_for_resource同文件 ops_discover.rs支持用dir_name磁盘目录 id或namefrontmatter 显示名定位技能二者歧义时报错明确要求使用目录 id。安装 / 卸载HTTPS URL 安装器install_workflow_from_urlops_install_part_01.rs 起实现了 README 所述的 URL 安装核心常量常量值含义DEFAULT_INSTALL_TIMEOUT_SECS60s默认拉取超时MAX_INSTALL_TIMEOUT_SECS600s调用方可请求的超时上限MAX_INSTALL_URL_LEN2048URL 长度上限MAX_WORKFLOW_MD_BYTES1 MiBSKILL.md 正文大小上限防御恶意/错误配置主机流式返回无限响应网络 I/O 前的验证URL 必须为https://拒绝回环、私网、link-local、组播、共享地址段、localhost及.local/.localhostmDNS 主机名。github.com/o/r/blob/b/p自动改写为raw.githubusercontent.com/o/r/b/p方便用户直接粘贴浏览器地址。路径必须以.md结尾大小写不敏感repo/tree URL 与 tarball 被拒绝unsupported url form:。timeout_secs被钳制到MAX_INSTALL_TIMEOUT_SECS。运行时行为先查Content-Length头下载后再校验缓冲长度双保险防谎报头。frontmatter 校验按 agentskills.io 规范要求name与description必填。slug 派生优先metadata.id否则用清洗后的name。若目标目录已有SKILL.md视为幂等成功报告已安装其他目录冲突保持致命已有文件绝不静默覆盖。写入原子化目标目录写SKILL.md.tmp成功后rename。安装完成后重新发现完整目录返回自调用开始新出现的 skill slug 列表new_skills。安装目的地为workspace/.openhuman/skills/slug/SKILL.md。README 所在模块的注释解释了设计动因vercel-labsskillsCLI 写入的 per-agent 目录./claude-code/skills/、./cursor/skills/等与 OpenHuman 的技能布局不兼容因此直接拉取 SKILL.md 并写入发现管线可见的布局。一个值得注意的运维细节HTTP localhost 安装默认被拒需显式设置OPENHUMAN_SKILL_INSTALL_ALLOW_LOCAL_HTTP1仅用于本地 fixture。事件总线与触发器bus.rsbus.rs 实现了 README 中 emits skill events on the global event bus 的承诺并进一步支撑了WorkflowFrontmatter::triggers字段TriggerPattern::parse将composio、composio/trigger_received、cron、channel/inbound_message等原始字符串解析为domain 可选event_slug。裸 domain无/匹配该域内任何事件slug 为*也视为匹配整个域。TriggerPattern::matches先比对event.domain()slug 限定模式在DomainEvent暴露稳定slug()之前暂不能精确匹配源码留有TODO(#skills-triggers)实现上保守地避免静默匹配整个域。TriggeredWorkflowIndexTriggeredSkillSubscriber启动时为声明triggers:的技能建立索引并注册订阅者匹配事件到达时记录应激活的技能。实际 agent-session 启动有意不在此处——它需要完整 harness 上下文provider、memory、config由 channel runtime 在总线初始化后接线本模块只提供类型管道与观察者。运行时执行catalog 与 runtime 两个子模块虽然 README 声明Does NOT own runtime execution internals当前仓库已将技能领域进一步组织为两个子模块理解它们有助于定位源码catalog技能注册表catalog/README.md 说明skill_registry负责远程技能目录与已装技能生命周期拉取并缓存远程目录默认https://hermes-agent.nousresearch.com/docs/api/skills.json。核心启动时异步强制刷新远程目录OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0可关闭不阻塞核心就绪。提供浏览/搜索、派生 Hermes 内置与可选技能的安装 URL、安装到用户技能目录、卸载用户作用域技能并托管内置skill_setupagent。可用环境变量覆盖用于生产脚本与确定性测试OPENHUMAN_SKILL_REGISTRY_CATALOG_URLhttps://example.com/skills.json OPENHUMAN_SKILL_REGISTRY_DOWNLOAD_BASE_URLhttps://example.com/skills OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0生产冒烟示例openhuman skill_registry schemas openhuman skill_registry browse --force_refresh true openhuman skill_registry search --query git openhuman skill_registry sources openhuman skill_registry install --entry_id git-helper openhuman skill_registry uninstall --name git-helperruntime技能执行runtime/README.md 说明skill_runtime拥有已装SKILL.md工作流的执行启动与取消技能运行、读取近期运行元数据与运行日志。脚本型技能运行前解析可复用的语言运行时复用runtime_nodeNode.js、npm、npx 与 PATH 注入与runtime_pythonPython 解释器解析与进程启动复用workflows的发现、元数据、资源与运行日志。托管内置skill_executoragent。生产冒烟示例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兼容性承诺既有openhuman workflows run、workflows cancel与运行日志 RPC 保持可用新脚本应优先使用skill_runtime命名空间。技能即带输入的 Agentregistry.rs 揭示了技能与 Agent 的关系一个技能就是一个AgentDefinition加上声明的[[inputs]]。agent 字段id、system_prompt、tools、max_iterations、sandbox_mode等从同一skill.toml扁平化注入因此技能本质是同时广告自己所需输入的、可运行的 Agent。WorkflowInputname/description/required/type在skill_run时取值并渲染进提示词render_inputs_block。[github]块含IdentityMatch枚举Strict/Any/None是可选预检门——存在且required true时orchestrator 启动前会运行 GitHub 身份一致性预检。与 Agent 层的交互点README 的 Calls into / Called by 章节说明了技能目录如何进入 Agent 上下文## Installed Skills目录渲染prompt.rs 渲染该章节数据源是PromptContext上的技能列表context.rs。每轮注入turn.rs 是 per-turn 注入点fork_context.rs 在 fork 上下文时传播注入的技能。提示词章节mod.rs 与 types.rs 渲染## Available Skills目录章节。工具结果类型共享traits.rs 消费ToolResult/ToolContent。工作区引导ops.rs 在工作区启动时触碰技能目录布局。集成 agentintegrations_agent/prompt.rs 读取技能目录。控制器注册all.rs 完成all_skills_registered_controllers的接线。测试布局README 指出本领域没有独立*_tests.rs文件单测与实现同文件共存#[cfg(test)] mod tests。当前仓库结构有所演进实测测试文件分布为顶层ops_tests.rs、ops_types.rstypes_tests.rs等、bus_tests.rs、registry_tests.rs、preflight_tests.rs、run_log_tests.rs、tools_tests.rs、schemas_tests.rs。作用域与解析专项ops_discover_include_skills_tests_tests.rs、ops_discover_profile_scope_tests_tests.rs、ops_create_render_skill_toml_tests_tests.rs、ops_install_install_fetch_tests_tests.rs。端到端e2e_plumbing_tests.rs 与 e2e_run_tests.rs。跨切面行为README 指出由 turn_tests.rs 与 runtime_tests.rs 间接覆盖agent skill 的组合行为。小结一张图看懂技能生命周期一个技能从落地到执行完整经过以下阶段落地skills.install_from_url经 HTTPS 拉取SKILL.md校验 URL 安全、大小与超时、frontmatter 必填项、slug 冲突原子写入workspace/.openhuman/skills/slug/或由skills.create脚手架新技能或用户手动放置到~/.openhuman/skills/。发现启动/轮次时扫描 User / Project需信任标记/ Legacy / Profile 根按优先级吸收同名冲突产出按 name 排序的目录。暴露技能以## Installed Skills紧凑目录进入 Agent 提示词skills.list/skills.describe含[[inputs]]供 UI 渲染动态表单。资源skills.read_resource以 128 KB 上限 路径穿越/符号链接/UTF-8 防护读取捆绑资源。触发声明triggers:的技能由事件总线订阅者匹配DomainEvent记录激活。执行skill_runtime run/run_skill在隔离 worker 中运行复用 Node/Python 语言运行时skills.cancel取消运行日志经run_log查询。至此你已掌握 OpenHuman Skills 子系统的目录规范、frontmatter 语义、四作用域裁决、信任标记门控、资源读取安全边界、URL 安装器的验证链、事件触发机制与运行时架构——这些都可以直接对照 src/openhuman/skills/ 目录下的源码与测试继续深挖。【免费下载链接】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），仅供参考
