🏗️ SpecFlow 主技能与子技能架构分工与资产流转指南

知识库归档：site/ai/specflow-skill-architecture.md
适用对象：58 业财产研架构组、前端/后端 AI 辅助开发工程师、Agent 技能治理团队

---

📌 一、 核心架构设计哲学 (Architecture Philosophy)

SpecFlow 技能生态采用了 全局门面 (Global Gateway) + 阶段插件化扩展 (Phase Plugins) 的微内核扩展架构：

• 部门主技能 (specflow)：存储在 58 SkillHub 远程市场，负责全局探针检测、CLI 物理自愈安装、环境一键初始化与门面调度；
• 规范仓局部子技能 (specflow-*)：物理保存在当前项目的 <project>-spec/.agents/skills/ 目录下，负责 IDE / 快捷菜单智能补全、P1~P7 按节点灵活分步研发、以及单项目专属 Prompt 规则扩展。

---

🔄 二、 三层资产流转与安装链路 (Asset Flow Architecture)

SpecFlow 的全量子技能采用了 “集中开发 -> CLI 编译打包 -> init 离线解包 -> wuba-skill-updater 运行时热更新” 的闭环分发机制：

🔍 三大关键环节的技术实现

1. 源头集中开发 (specflow-hub)：

   • 所有的 SDD 规则 (.agents/rules/) 与全量子技能（specflow-specify, specflow-plan, specflow-task, specflow-testcase, specflow-review, specflow-report, specflow-sddx, specflow-mr）统一在 specflow-hub 仓库中进行版本迭代与治理。

2. CLI 打包与 init 离线物理解包 (@specflow/cli)：

   • 每次发布新版本时，构建脚本会物理将 specflow-hub 里的全量子技能编译打包进 @specflow/cli npm 包中（存储在 src/assets/skills/）；
   • 当开发者在终端或 AI 会话中运行 specflow init 初始化规范仓时，CLI 负责把内置的最新全量子技能直接物理解压落盘到当前规范仓的 <project>-spec/.agents/skills/ 实体目录中。
   • 架构价值：保障在断网或无 SkillHub 权限的离线环境下，一键建仓即拥有全套完整的子技能！

3. wuba-skill-updater 运行时探针巡检与在线热更新：

   • 在 SDD 研发过程中，Agent 每次触发技能时，都会自动运行内嵌的 wuba-skill-updater 子技能；
   • wuba-skill-updater 会自动去 SkillHub 远程市场巡检是否有最新的 0.x.x 补丁更新；
   • 若检测到远端有新版本，会自动调用 wubahub install 物理覆盖重载本地规范仓中的 .agents/skills/，保障规范仓始终运行在最新的工程防护能力之下！

---

📊 三、 主技能与子技能功能对比矩阵

场景 / 维度	部门主技能 (specflow)	项目规范仓子技能 (specflow-*)
存储位置	58 SkillHub 官方技能市场	<project>-spec/.agents/skills/ 实体目录
核心职责	全局探针检测、环境自愈安装 CLI、一键初始化规范仓	IDE / 快捷菜单补全、按 P1~P7 节点灵活驱动
环境依赖	零依赖（自动安装 @specflow/cli@0.13.42）	依赖物理规范仓已经初始化
扩展性	部门级统一标准规范	支持单项目特化 Prompt / 校验规则定制