OpenHuman Skills 子系統(tǒng)完全指南SKILL.md 發(fā)現(xiàn)、作用域解析、信任標(biāo)記與安全執(zhí)行【免費下載鏈接】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導(dǎo)讀本文以 OpenHuman 倉庫中 src/openhuman/skills/README.md 為核心系統(tǒng)拆解 Skills 子系統(tǒng)的完整能力邊界如何發(fā)現(xiàn)并解析 agentskills.io 風(fēng)格的技能包一個含 YAML frontmatter 與 Markdown 指令的SKILL.md目錄、User / Project / Legacy 三種作用域如何解析與沖突裁決、信任標(biāo)記trust marker如何門控項目級技能加載、資源讀取的安全邊界以及技能如何通過run_skill在隔離 worker 中執(zhí)行。讀完本文你將掌握技能包目錄布局、frontmatter 字段語義、安裝/卸載/資源讀取的 RPC 面、事件總線觸發(fā)機制以及倉庫源碼中對應(yīng)的實現(xiàn)與測試位置。注當(dāng)前倉庫已把技能領(lǐng)域內(nèi)部術(shù)語從 skill 遷移為 workflow如ops_types.rs中Workflow/WorkflowScope/WORKFLOW.md但SKILL.md仍是向后兼容的主定義文件RPC 面也保留skills.*命名全文按既有公開 API 名稱展開。Skills 子系統(tǒng)的職責(zé)邊界根據(jù) README 與 mod.rs 模塊文檔Skills 子系統(tǒng)只負(fù)責(zé)技能的發(fā)現(xiàn)、解析、作用域管理、信任標(biāo)記執(zhí)行、資源讀取與安裝/卸載明確不擁有運行時執(zhí)行內(nèi)部機制與通用工具執(zhí)行后者屬于tools//javascript/。發(fā)現(xiàn)與解析掃描目錄、讀取SKILL.md的 YAML frontmatter 與 Markdown 指令體見 ops_discover.rs 與 ops_parse.rs。作用域解析User vs Project vs Legacy以及后續(xù)新增的 Profile 作用域的優(yōu)先級裁決。信任標(biāo)記執(zhí)行項目級技能僅在workspace/.openhuman/trust存在時加載。資源讀取讀取技能捆綁的子資源scripts/、references/、assets/等并做路徑穿越/符號鏈接/大小/UTF-8 四重防護。安裝 / 卸載基于 HTTPS 的 URL 安裝與卸載見 ops_install_part_01.rs。技能最終以緊湊的## Installed Skills目錄形式暴露給 Agent并通過run_skill在隔離 worker 中執(zhí)行——技能正文不再被拼接進聊天輪次。README 明確bodies are no longer spliced into chat turns這是與早期提示詞拼接式技能實現(xiàn)的關(guān)鍵區(qū)別。從 mod.rs 還可以看到兩個重要架構(gòu)事實編譯期特性門控pub mod skills;始終編譯作為 facade而ops、bus、schemas、registry等行為性子模塊由默認(rèn)開啟的skillsCargo feature 門控關(guān)閉時由 stub.rs 提供同簽名空實現(xiàn)。類型不參與門控types與ops_types在兩種 feature 方向下都編譯因為ToolResult/ToolContent被tools::traits再導(dǎo)出為整個 crate 的統(tǒng)一工具結(jié)果類型約 236 個文件消費Workflow/WorkflowFrontmatter/WorkflowScope也出現(xiàn)在常開的 agent-harness 與提示詞簽名中。公開 API 面Public surfaceREADME 列出的公開 API 全部可在源碼中逐項確認(rèn)公開項位置說明pub enum SkillScope現(xiàn)為WorkflowScopeops_types.rs發(fā)現(xiàn)作用域User/Project/Legacy另有Profile決定同名沖突時的優(yōu)先級MAX_SKILL_RESOURCE_BYTES現(xiàn)為MAX_WORKFLOW_RESOURCE_BYTES 128 * 1024ops_types.rs單資源 RPC 載荷上限128 KBpub use ops::*mod.rs再導(dǎo)出發(fā)現(xiàn)、解析、安裝、卸載、資源讀取與 frontmatter 類型pub struct ToolResult/pub enum ToolContenttypes.rs技能/工具執(zhí)行返回的內(nèi)容塊pub mod busbus.rs在全局事件總線上發(fā)出技能事件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解析活動工作區(qū)因此 CLI 與 UI 看到的是同一份技能目錄調(diào)用方無需手動傳入工作區(qū)路徑。技能包格式SKILL.md frontmatter 捆綁資源目錄布局與定義文件一個技能就是一個目錄核心定義文件是SKILL.mdYAML frontmatter含name、description等必填字段 Markdown 指令體?？蛇x捆綁資源位于兄弟子目錄中。從 ops_types.rs 的RESOURCE_DIRS可以看到當(dāng)前支持的資源目錄scripts/、references/、assets/傳統(tǒng)三個templates/、examples/、prompts/Hermes 風(fēng)格技能常見目錄按可瀏覽資源處理不作為可執(zhí)行運行時入口此外 ops_types.rs 定義了向后兼容的文件名常量常量文件名狀態(tài)WORKFLOW_MDWORKFLOW.md當(dāng)前主定義文件create/update 寫入WORKFLOW_TOMLworkflow.toml當(dāng)前 sidecar 清單inputs / when_to_use / [github]SKILL_MDSKILL.md舊定義文件skills→workflows 重命名前編寫的技能仍會讀取SKILL_TOMLskill.toml舊 sidecar 清單向后兼容讀取SKILL_JSONskill.json更早的清單格式向后兼容讀取Frontmatter 字段語義WorkflowFrontmatterops_types.rs嚴(yán)格對齊 agentskills.io SKILL.md 規(guī)范字段必填說明name是技能名也是同名沖突的裁決鍵description是短描述用于目錄摘要license否許可證compatibility否兼容性說明platforms否平臺兼容提示Hermes 風(fēng)格缺省表示全平臺metadata否規(guī)范兼容的元數(shù)據(jù) mapversion、author、tags等非必填字段應(yīng)放這里allowed-tools否技能作者聲明的依賴工具非強制提示宿主決定暴露什么triggers否激活該技能的事件觸發(fā)模式見下文事件總線章節(jié)extra否規(guī)范擴展的落點#[serde(flatten)]舊式頂層version/author/tags會觸發(fā)遷移警告解析時對頂層遺留字段的兼容處理可參看 ops_types.rs 的extract_version/extract_author/extract_tags優(yōu)先讀metadata.*否則回退到頂層并在warnings中記錄棄用提示。frontmatter 解析實現(xiàn)ops_parse.rs 的parse_workflow_md/parse_workflow_md_str展示了解析細(xì)節(jié)以首行---開啟 frontmatter 塊以第二個---終止未終止的 frontmatter 塊返回None解析失敗。無 frontmatter 時整文件視為指令體返回默認(rèn)WorkflowFrontmatter。YAML 反序列化失敗不致命記錄frontmatter parse error警告并回退到默認(rèn) frontmatter保證技能仍可被發(fā)現(xiàn)。load_from_workflow_md同文件后半部分將SKILL.md組裝為完整的Workflow結(jié)構(gòu)inventory_resourcesops_parse.rs淺掃技能目錄枚舉資源——注意它用symlink_metadata拒絕符號鏈接資源根且walk_files遞歸時同樣跳過符號鏈接防止無限遞歸與目錄外泄漏。作用域Scope解析與沖突裁決三種作用域 ProfileREADME 描述的是三作用域模型當(dāng)前源碼已擴展為四作用域ops_types.rs作用域磁盤位置優(yōu)先級User默認(rèn)~/.openhuman/skills/name/或~/.agents/skills/name/1Projectworkspace/.openhuman/skills/name/或workspace/.agents/skills/name/需信任標(biāo)記2Legacyworkspace/skills/name/扁平舊布局0Profileworkspace/personalities/id/skills/僅活動 profile 的輪次可見3從源碼結(jié)構(gòu)看Profile 作用域是后來為按 Agent profile 私有技能新增的discover_workflows_with_profile掃描 profile 私有根目錄無需信任標(biāo)記目錄由 core 管理且對所屬 profile 在同名沖突中擁有最高優(yōu)先級會遮蔽同名的全局技能。默認(rèn)會話與其他 profile 完全不受影響None與discover_workflows逐字節(jié)等價。信任標(biāo)記Trust Marker項目級技能只有在workspace/.openhuman/trust存在時才加載。is_workspace_trustedops_discover.rs實現(xiàn)極簡文件內(nèi)容被忽略存在即信任。這是關(guān)鍵安全邊界——克隆一個陌生倉庫后skills/目錄中的項目級技能默認(rèn)不會進入 Agent 上下文用戶必須顯式放置信任標(biāo)記才會加載。發(fā)現(xiàn)順序與沖突裁決discover_filteredops_discover.rs的實現(xiàn)要點掃描順序User 根 → Project 根僅 trusted 時→ Legacyws/skills/→ Profile 根。HashMap以 name 為鍵后注冊者覆蓋先注冊者。優(yōu)先級函數(shù)precedenceLegacy0 User1 Project2 Profile3。同名沖突時高優(yōu)先級保留低優(yōu)先級技能被丟棄并在保留者的warnings中記錄遮蔽原因如shadowed Project-scope skill ... at path這些警告會浮現(xiàn)在目錄摘要中供用戶調(diào)試。穩(wěn)定性保證read_dir順序未定義為避免同名兄弟目錄跨運行產(chǎn)生非確定性勝者scan_root_inner先按磁盤目錄名排序再處理。排除規(guī)則EXCLUDED_SKILL_DIRS跳過.git、.github、node_modules、__pycache__、.venv等常見無關(guān)目錄點開頭的目錄名也跳過。符號鏈接防護用file_type()而非path.is_dir()判斷——is_dir()會解引用符號鏈接可能重新打開目錄外加載漏洞manifest 文件也要求是真實非符號鏈接常規(guī)文件。發(fā)現(xiàn)結(jié)果按name排序輸出。README 提到的 project-scope wins 在代碼中得到印證并且沖突警告中同時給出dir_name、name、作用域與磁盤位置方便定位。資源讀取的安全邊界read_workflow_resource/read_workflow_resource_with_profileops_discover.rs是 README 所述resource reading的實現(xiàn)核心防護層層遞進參數(shù)校驗skill_id與relative_path非空拒絕絕對路徑拒絕任何..、.、空組件與 Windows 前綴Component::ParentDir | CurDir | RootDir | Prefix。技能解析復(fù)用標(biāo)準(zhǔn)發(fā)現(xiàn)管線含信任標(biāo)記與 profile 根將讀取范圍限定在已安裝技能集合內(nèi)。根目錄校驗先canonicalize技能根要求真實目錄非符號鏈接。葉子檢查用symlink_metadata預(yù)先拒絕符號鏈接與非常規(guī)文件socket/fifo/目錄。大小門禁leaf_meta.len() MAX_WORKFLOW_RESOURCE_BYTES (128 KB)直接拒絕——先看元數(shù)據(jù)再讀文件避免為超大文件分配緩沖區(qū)。穿越校驗canonicalize完整路徑并斷言其仍在技能根之內(nèi)。嚴(yán)格 UTF-8非 UTF-8 內(nèi)容直接拒絕不做 lossy 替換寧可拒絕二進制文件也不靜默損壞。resolve_workflow_for_resource同文件 ops_discover.rs支持用dir_name磁盤目錄 id或namefrontmatter 顯示名定位技能二者歧義時報錯明確要求使用目錄 id。安裝 / 卸載HTTPS URL 安裝器install_workflow_from_urlops_install_part_01.rs 起實現(xiàn)了 README 所述的 URL 安裝核心常量常量值含義DEFAULT_INSTALL_TIMEOUT_SECS60s默認(rèn)拉取超時MAX_INSTALL_TIMEOUT_SECS600s調(diào)用方可請求的超時上限MAX_INSTALL_URL_LEN2048URL 長度上限MAX_WORKFLOW_MD_BYTES1 MiBSKILL.md 正文大小上限防御惡意/錯誤配置主機流式返回?zé)o限響應(yīng)網(wǎng)絡(luò) I/O 前的驗證URL 必須為https://拒絕回環(huán)、私網(wǎng)、link-local、組播、共享地址段、localhost及.local/.localhostmDNS 主機名。github.com/o/r/blob/b/p自動改寫為raw.githubusercontent.com/o/r/b/p方便用戶直接粘貼瀏覽器地址。路徑必須以.md結(jié)尾大小寫不敏感repo/tree URL 與 tarball 被拒絕unsupported url form:。timeout_secs被鉗制到MAX_INSTALL_TIMEOUT_SECS。運行時行為先查Content-Length頭下載后再校驗緩沖長度雙保險防謊報頭。frontmatter 校驗按 agentskills.io 規(guī)范要求name與description必填。slug 派生優(yōu)先metadata.id否則用清洗后的name。若目標(biāo)目錄已有SKILL.md視為冪等成功報告已安裝其他目錄沖突保持致命已有文件絕不靜默覆蓋。寫入原子化目標(biāo)目錄寫SKILL.md.tmp成功后rename。安裝完成后重新發(fā)現(xiàn)完整目錄返回自調(diào)用開始新出現(xiàn)的 skill slug 列表new_skills。安裝目的地為workspace/.openhuman/skills/slug/SKILL.md。README 所在模塊的注釋解釋了設(shè)計動因vercel-labsskillsCLI 寫入的 per-agent 目錄./claude-code/skills/、./cursor/skills/等與 OpenHuman 的技能布局不兼容因此直接拉取 SKILL.md 并寫入發(fā)現(xiàn)管線可見的布局。一個值得注意的運維細(xì)節(jié)HTTP localhost 安裝默認(rèn)被拒需顯式設(shè)置OPENHUMAN_SKILL_INSTALL_ALLOW_LOCAL_HTTP1僅用于本地 fixture。事件總線與觸發(fā)器bus.rsbus.rs 實現(xiàn)了 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無/匹配該域內(nèi)任何事件slug 為*也視為匹配整個域。TriggerPattern::matches先比對event.domain()slug 限定模式在DomainEvent暴露穩(wěn)定slug()之前暫不能精確匹配源碼留有TODO(#skills-triggers)實現(xiàn)上保守地避免靜默匹配整個域。TriggeredWorkflowIndexTriggeredSkillSubscriber啟動時為聲明triggers:的技能建立索引并注冊訂閱者匹配事件到達時記錄應(yīng)激活的技能。實際 agent-session 啟動有意不在此處——它需要完整 harness 上下文provider、memory、config由 channel runtime 在總線初始化后接線本模塊只提供類型管道與觀察者。運行時執(zhí)行catalog 與 runtime 兩個子模塊雖然 README 聲明Does NOT own runtime execution internals當(dāng)前倉庫已將技能領(lǐng)域進一步組織為兩個子模塊理解它們有助于定位源碼catalog技能注冊表catalog/README.md 說明skill_registry負(fù)責(zé)遠程技能目錄與已裝技能生命周期拉取并緩存遠程目錄默認(rèn)https://hermes-agent.nousresearch.com/docs/api/skills.json。核心啟動時異步強制刷新遠程目錄OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0可關(guān)閉不阻塞核心就緒。提供瀏覽/搜索、派生 Hermes 內(nèi)置與可選技能的安裝 URL、安裝到用戶技能目錄、卸載用戶作用域技能并托管內(nèi)置skill_setupagent?？捎铆h(huán)境變量覆蓋用于生產(chǎn)腳本與確定性測試OPENHUMAN_SKILL_REGISTRY_CATALOG_URLhttps://example.com/skills.json OPENHUMAN_SKILL_REGISTRY_DOWNLOAD_BASE_URLhttps://example.com/skills OPENHUMAN_SKILL_REGISTRY_REFRESH_ON_BOOT0生產(chǎn)冒煙示例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技能執(zhí)行runtime/README.md 說明skill_runtime擁有已裝SKILL.md工作流的執(zhí)行啟動與取消技能運行、讀取近期運行元數(shù)據(jù)與運行日志。腳本型技能運行前解析可復(fù)用的語言運行時復(fù)用runtime_nodeNode.js、npm、npx 與 PATH 注入與runtime_pythonPython 解釋器解析與進程啟動復(fù)用workflows的發(fā)現(xiàn)、元數(shù)據(jù)、資源與運行日志。托管內(nèi)置skill_executoragent。生產(chǎn)冒煙示例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 保持可用新腳本應(yīng)優(yōu)先使用skill_runtime命名空間。技能即帶輸入的 Agentregistry.rs 揭示了技能與 Agent 的關(guān)系一個技能就是一個AgentDefinition加上聲明的[[inputs]]。agent 字段id、system_prompt、tools、max_iterations、sandbox_mode等從同一skill.toml扁平化注入因此技能本質(zhì)是同時廣告自己所需輸入的、可運行的 Agent。WorkflowInputname/description/required/type在skill_run時取值并渲染進提示詞render_inputs_block。[github]塊含IdentityMatch枚舉Strict/Any/None是可選預(yù)檢門——存在且required true時orchestrator 啟動前會運行 GitHub 身份一致性預(yù)檢。與 Agent 層的交互點README 的 Calls into / Called by 章節(jié)說明了技能目錄如何進入 Agent 上下文## Installed Skills目錄渲染prompt.rs 渲染該章節(jié)數(shù)據(jù)源是PromptContext上的技能列表context.rs。每輪注入turn.rs 是 per-turn 注入點fork_context.rs 在 fork 上下文時傳播注入的技能。提示詞章節(jié)mod.rs 與 types.rs 渲染## Available Skills目錄章節(jié)。工具結(jié)果類型共享traits.rs 消費ToolResult/ToolContent。工作區(qū)引導(dǎo)ops.rs 在工作區(qū)啟動時觸碰技能目錄布局。集成 agentintegrations_agent/prompt.rs 讀取技能目錄。控制器注冊all.rs 完成all_skills_registered_controllers的接線。測試布局README 指出本領(lǐng)域沒有獨立*_tests.rs文件單測與實現(xiàn)同文件共存#[cfg(test)] mod tests。當(dāng)前倉庫結(jié)構(gòu)有所演進實測測試文件分布為頂層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?？缜忻嫘袨镽EADME 指出由 turn_tests.rs 與 runtime_tests.rs 間接覆蓋agent skill 的組合行為。小結(jié)一張圖看懂技能生命周期一個技能從落地到執(zhí)行完整經(jīng)過以下階段落地skills.install_from_url經(jīng) HTTPS 拉取SKILL.md校驗 URL 安全、大小與超時、frontmatter 必填項、slug 沖突原子寫入workspace/.openhuman/skills/slug/或由skills.create腳手架新技能或用戶手動放置到~/.openhuman/skills/。發(fā)現(xiàn)啟動/輪次時掃描 User / Project需信任標(biāo)記/ Legacy / Profile 根按優(yōu)先級吸收同名沖突產(chǎn)出按 name 排序的目錄。暴露技能以## Installed Skills緊湊目錄進入 Agent 提示詞skills.list/skills.describe含[[inputs]]供 UI 渲染動態(tài)表單。資源skills.read_resource以 128 KB 上限 路徑穿越/符號鏈接/UTF-8 防護讀取捆綁資源。觸發(fā)聲明triggers:的技能由事件總線訂閱者匹配DomainEvent記錄激活。執(zhí)行skill_runtime run/run_skill在隔離 worker 中運行復(fù)用 Node/Python 語言運行時skills.cancel取消運行日志經(jīng)run_log查詢。至此你已掌握 OpenHuman Skills 子系統(tǒng)的目錄規(guī)范、frontmatter 語義、四作用域裁決、信任標(biāo)記門控、資源讀取安全邊界、URL 安裝器的驗證鏈、事件觸發(fā)機制與運行時架構(gòu)——這些都可以直接對照 src/openhuman/skills/ 目錄下的源碼與測試?yán)^續(xù)深挖?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考