企业官网建设流程全解析

VibeSkills 代码结构深度解析：runtime-core、verification-core 等 6 大核心包的分工与协作

【免费下载链接】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

VibeSkills 是一个面向 AI Agent 的智能技能路由与工作流编排框架，它在 SkillsBench 基准上实现了 +21.12 pp 的奖励提升与 29.6% 的 token 节省。想读懂这个项目？关键就是搞清packages/目录下runtime-core、verification-core 等 6 大核心包的分工与协作方式。本文带你快速建立全局认知，无需逐行读代码。

一分钟看懂仓库顶层结构

VibeSkills 采用"Python 多包（monorepo）+ 数据面分离"的布局，顶层目录各司其职：

6 大核心包：各自的职责边界

packages/下的 6 个包版本统一为4.1.0，要求 Python ≥ 3.10，是理解 VibeSkills 代码结构的主线。

1. runtime-core —— 工作内核（语义核心）

包名vgo-runtime，自述为 "Runtime core for Vibe-Skills clean architecture"，是整个系统的"大脑"。

• 源码主入口：packages/runtime-core/src/vgo_runtime/kernel/
• 内核负责任务理解 → 技能查找 → 计划构建 → 执行 → 验证 → 证据留存的完整闭环
• 关键模块一览：
  • task_card.py：把目标固化为"任务卡片"
  • planner.py：构建有界工作计划
  • executor.py：执行工作单元
  • verifier.py：验证运行结果
  • run_state.py：持久化运行状态
• 内核外的 runtime-core 顶层模块（如governance.py、memory.py、stage_machine.py）负责治理、工作区记忆与阶段状态机

设计哲学：内核应保持短小、可读——"如果一个改动让系统比这条主线更难解释，设计就在漂移"（见 docs/architecture.md）。

2. verification-core —— 验证核心（质量守门员）

包名vgo-verify，即 "Verification core for Vibe-Skills clean architecture"。

• 源码：packages/verification-core/src/vgo_verify/
• 核心职责：判断现有证据能证明什么、不能证明什么，把"绑定了"与"用过了"、"脚手架输出"与"完成的工作"严格区分开
• 关键模块：
  • gate_engine.py：门禁引擎
  • scenario_runner.py + scenarios/：场景化验证矩阵（install/runtime 双矩阵）
  • runtime_delivery_acceptance.py：运行时交付验收
  • test_baseline_audit.py：测试基线审计

3. contracts —— 契约层（权威数据模型）

包名vgo-contracts，"Authoritative contracts for Vibe-Skills clean architecture"。

• 源码：packages/contracts/src/vgo_contracts/
• 17 个契约模块定义了包与包之间的权威数据形状，例如 adapter_descriptor.py（宿主适配描述）、runtime_packet.py（运行时输入包）、verification_scenario.py（验证场景）、install_ledger.py（安装台账）
• 它是"共享词汇表"：runtime 与 verification 之间传递的每个结构体，都以这里的定义为唯一事实来源

4. installer-core —— 安装核心（文件落盘与更新安全）

包名vgo-installer。

• 源码：packages/installer-core/src/vgo_installer/
• 职责：文件放置 + 回执（receipt）驱动的更新安全，即"installer owns file placement and receipt-owned update safety"
• 关键模块：install_plan.py / install_runtime.py（安装计划与落地）、uninstall_service.py（卸载）、repair.py（修复）、ledger_service.py（台账服务）

5. adapter-sdk —— 宿主适配 SDK（环境边缘层）

包名vgo-adapters。

• 源码：packages/adapter-sdk/src/vgo_adapters/
• 只有 3 个精简模块：descriptor_loader.py（读取adapters/下的宿主描述）、target_root_resolver.py（解析目标安装根目录）
• 边界纪律：宿主层可以执行，但不可以解释——PowerShell 脚本等宿主细节在此层止步，不再决定工作语义

6. skill-catalog —— 技能目录（独立能力面）

包名vgo-skill-catalog，"Detached skill catalog package"，强调解耦。

• 目录数据：packages/skill-catalog/catalog/，含 profiles/（full/minimal两种分发包）与 metadata/（含 official-skill-contracts.json）
• 源码：exporter.py 负责目录导出
• 设计原则：技能应在自己附近自描述，"新增一个普通技能不应该需要动路由器"

协作全景：一次任务如何穿越 6 个包

VibeSkills 的官方架构主线只有一条（摘自 docs/architecture.md）：

task card -> build work model -> bind skills -> produce evidence -> verify scope -> prove only what is proven

对应到包协作就是：

1. skill-catalog / bundled提供能力原料 → 2.contracts统一双方数据结构 → 3.runtime-core的任务卡片 + 内核完成计划与执行 → 4.verification-core对证据做范围验证并产出证明 → 5.installer-core保证技能文件正确落盘且可安全更新 → 6.adapter-sdk屏蔽 Windows/macOS/Linux 与不同 AI 宿主的差异。

边界规则（Boundary Rule）是理解分工的钥匙：

内核拥有语义；兼容层可以翻译但不能决定；宿主层可以运行但不能解释；技能层可以贡献能力但不能接管工作流。

迁移期哪些旧路由/治理面还算"权威"、哪些只是外壳，统一记录在 config/kernel-boundary-demotion-matrix.json，这是阅读config/下数百份治理 JSON 前最值得先看的一份文件。

架构效果：基准数据佐证

这套"内核 + 验证"的分工并非纸上谈兵。在 SkillsBench 上，接入 VibeSkills 技能编排后任务奖励从 50.3% 提升到 71.4%，且 96% 的任务奖励持平或更高：

同时 token 总消耗从 4.91 亿降至 3.46 亿（约 −29.6%），工具调用量降至 0.67 倍，详见 docs/ 与 docs/architecture.md。

新手上手路径建议

按这个顺序读代码，效率最高：

1. 先读 docs/architecture.md（160 行，讲清分层与边界）
2. 再看 core/README.md：7 个首批冻结契约技能（vibe、tdd-guide、systematic-debugging 等）的入口约定
3. 然后按kernel/__init__.py的导出顺序（见 kernel 入口：TaskCard → WorkPlan → execute_work_unit → verify_run）走一遍内核主线
4. 最后用 tests/runtime_neutral/（100 个测试文件）反查各包的行为契约

一句话总结：VibeSkills 的代码结构 = 一个短小的工作内核（runtime-core）+ 一个严格的证据守门员（verification-core）+ 三个各司其职的支撑包（contracts / installer-core / adapter-sdk / skill-catalog）。读懂这条主线，你就掌握了它 80% 的设计。

【免费下载链接】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