VibeSkills 宿主适配器开发教程：基于 host-profile.json 接入新 AI 应用的完整指南

VibeSkills 宿主适配器开发教程基于 host-profile.json 接入新 AI 应用的完整指南【免费下载链接】Vibe-SkillsIntelligent Skill routing and workflow orchestration for AI agents — 21.12 pp reward, −29.6% tokens on SkillsBench with DeepSeekV4Flash-VE.项目地址: https://gitcode.com/gh_mirrors/vi/Vibe-SkillsVibeSkills 是一个面向 AI Agent 的智能技能路由与工作流编排系统。本教程带你用它的宿主适配器Host Adapter机制基于host-profile.json把任意新的 AI 应用如 IDE、CLI 编程助手接入 VibeSkills 核心掌握适配器四件套与注册验证的完整步骤。一、什么是宿主适配器先懂三条铁律在 adapters/README.md 中项目对适配器定义了清晰边界铁律含义不替代官方运行时官方运行时始终是唯一的执行权威不拥有路由真相路由决策只属于 VibeSkills 核心诚实声明状态适配器只能是supported/preview/not-yet-proven绝不夸大未验证的能力所有适配器共用同一个安装接口install --skills-dir SkillsDir安装布局统一为SkillsDir/vibe。适配器只负责翻译宿主应用的原生目录、调用语法和可选的命令/代理投影。当前仓库已内置 7 个适配器都在 adapters/ 目录下codex/受治理governed的完整适配通道claude-code/受管理的设置面适配cursor/、windsurf/、openclaw/、opencode/preview 级适配generic/面向其他 Skills 类应用的契约消费者兜底路径二、接入前找到两个关键文件开发新适配器前先读这两份总目录适配器注册表adapters/index.json与 config/adapter-registry.json 内容一致列出每个适配器的状态、安装模式、host_profile/settings_map/closure三个契约文件路径。能力档案 Schemaschemas/host-capability.schema.json它规定了host-profile.json的最小必填字段。以 adapters/codex/host-profile.json 为最佳范本其结构如下{ adapter_id: codex, host_name: Codex, status: supported-with-constraints, runtime_role: official-runtime-adapter, source_evidence: [config/settings.template.codex.json, install.ps1], settings_surface: { path: ~/.agents/settings.json, managed_by_repo: true }, host_managed_surfaces: [provider credentials, plugin provisioning], capabilities: { fs.read: full, shell.exec: full, mcp.client: supported-with-constraints }, degrade_contract: { missing_host_plugins: degraded-but-supported } }新手要点adapter_id、host_name、status、runtime_role、capabilities、degrade_contract是 Schema 强制字段缺一即校验失败。三、完整接入六步走第 1 步创建适配器目录在 adapters/ 下新建你的宿主目录例如adapters/myapp/与现有codex/等目录平级。第 2 步编写 host-profile.json参照 adapters/generic/host-profile.json最简范本或 adapters/codex/host-profile.json完整范本重点填好三块settings_surface宿主设置文件路径如~/.myapp/settings.json并标注managed_by_repo是否由仓库托管。capabilities逐项如实声明能力等级如fs.read、shell.exec、mcp.client、agent.spawn、route.offline_fallback等。degrade_contract诚实声明降级场景。例如 codex 声明缺少宿主插件时降级但仍可用degraded-but-supported。第 3 步编写 closure.json边界与卸载契约参考 adapters/codex/closure.json声明四件事字段作用repo_managed_payload仓库负责写入哪些文件如skills/**、commands/**host_state_written会改动宿主哪些状态如settings.jsonhost_managed_boundaries哪些边界归宿主管凭据、插件等uninstall_contract卸载清单与账本路径保证可干净移除如果是轻量接入可参考 adapters/generic/closure.json 的runtime-core-only级别。第 4 步编写 settings-map.json设置映射以 adapters/codex/settings-map.json 为例定义仓库模板 → 宿主设置的映射{ adapter_id: codex, template: config/settings.template.codex.json, target: ~/.agents/settings.json, semantics: { vco.skill_roots.global: [~/.agents/skills] } }注意映射值只是运行时绑定不是跨宿主的规范真相项目在此有明确治理原则。第 5 步补充平台契约可选但推荐为每个支持平台建platform-linux.json/platform-macos.json/platform-windows.json参考 adapters/codex/platform-linux.json。内容包含安装/检查入口脚本、降级用例如无 pwsh 时降级但仍支持与晋升promotion要求。第 6 步注册并验证在 adapters/index.json 和 config/adapter-registry.json 中追加一条记录host_profile、settings_map、closure指向第 2~4 步产出的文件。运行验证门禁scripts/verify/vibe-host-adapter-contract-gate.ps1 校验契约完整性scripts/verify/vgo-adapter-closure-gate.ps1 校验闭合声明。用generic作为能力基线自检你的适配器声明的能力不得低于 adapters/generic/closure.json 所定义的runtime-core-only验证契约。四、常见状态速查status 取值适用场景full-authoritative全平台权威验证完成目前仅少数平台契约目标supported-with-constraints主路径可用部分依赖宿主侧能力如凭据preview安装/使用路径可用但无完整闭合声明degraded-but-supported降级可用须如实标注advisory-only仅契约消费不做宿主闭合声明五、总结接入一个新的 AI 应用本质就是回答四个问题它的能力是什么host-profile、边界在哪里closure、设置怎么映射settings-map、如何注册验证index 门禁脚本。遵循诚实声明、不夸大闭合的治理原则按 adapters/codex/ 目录的完整范式逐项落文件再通过 scripts/verify/ 下的契约门禁你的新宿主就能与 codex、claude-code 等适配器一样共享同一个 VibeSkills 核心技能库。 延伸阅读adapters/README.md、schemas/host-capability.schema.json、config/adapter-registry.json【免费下载链接】Vibe-SkillsIntelligent Skill routing and workflow orchestration for AI agents — 21.12 pp reward, −29.6% tokens on SkillsBench with DeepSeekV4Flash-VE.项目地址: https://gitcode.com/gh_mirrors/vi/Vibe-Skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考