一、问题与背景

大多数 Agent 项目的代码库里，都会看到这样的目录结构：

agent-ba/
  prompts/
    system.md
    examples.md
  tools/
    jira.py
    wiki.py
agent-sa/
  prompts/
    system.md
  tools/
    arch.py
agent-pm/
  ...

看似清晰，实则隐患重重：

• 重复：每个角色的 system prompt 都有一段"你是专业的 XXX"的套话，改一处要同步十几处。
• 隐式依赖：BA 的提示词里提到了某个 Jira 字段，但 SA 的工具集并不知道这件事，跨 Agent 调用就出错。
• 不可评估：没有版本号，没有变更记录，没有回归用例，“我也不知道这次改完效果是变好还是变坏”。
• 不可发现：新人想知道"团队里现在有哪些现成的能力"，只能挨个问同事。

这些还不是最要命的。最致命的是没有契约：当 BA 把一段 Markdown 交给 SA，SA 只能"猜"这段内容是什么格式、是结构化还是非结构化、是必填还是选填。这种"靠默契"的协作在前两个 Agent 之间还能跑通，一旦涉及五个、十个 Agent，整个系统就变成了一个巨大的隐藏耦合网络，任何一个角色的 prompt 改动都可能让另一端静默失效。

当 Agent 从 demo 走向生产，这些问题会被指数级放大。

二、产品规格

Agent Skill Warehouse（mcp.smartmoves.com.cn） 把上述散落的"能力碎片"重组为标准化的 Skill 资产。每个 Skill 是一个自描述的目录，核心文件结构如下：

ba-master/
  SKILL.md            # 元信息：name, version, owner, tags
  instruction/        # 指令层：角色定义、行为约束
  knowledge/          # 知识层：领域文档、FAQ
  execution/          # 执行层：MCP 工具、脚本、API
  evaluation/         # 评测层：基准用例与评分脚本
  CHANGELOG.md        # 变更日志

核心能力一览：

三、技术架构

整体技术栈选择了"轻后端、重前端、标准协议"的路线：

┌──────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Web 门户   │ ←→ │  FastAPI 后端    │ ←→ │   PostgreSQL     │
│  React+Vite  │    │  (Registry API)  │    │  (元数据)        │
└──────────────┘    └────────┬─────────┘    └──────────────────┘
                            │
                ┌───────────┼───────────┐
                ▼           ▼           ▼
          ┌──────────┐ ┌──────────┐ ┌──────────┐
          │  MinIO   │ │  Qdrant  │ │   MCP    │
          │ (文件)   │ │ (向量)   │ │ (运行时) │
          └──────────┘ └──────────┘ └──────────┘

关键设计取舍：

• 元数据进 PG，内容进 MinIO：目录索引、版本关系等结构化数据走关系型数据库；Skill 的大体积资源（文档、脚本、二进制）走对象存储，避免 DB 膨胀。
• 检索走 Qdrant：用户搜索"擅长画 UML 的技能"，后台把指令层和知识层内容 Embedding 后检索，召回排序由向量数据库完成。
• 消费走 MCP：运行时不必为每个 Agent 框架写适配层——只要支持 MCP，就能 pull 任意 Skill 到本地上下文。
• 评测本地化：评测用例随 Skill 一起发布，CI 流水线在 Agent 端执行，平台只负责版本打分，不接触业务数据。

这些拆分原则的共同出发点是让仓库保持轻：仓库只负责“指示与打分”，不负责“重计算与执行”。这一边界划定后，平台才有可能以开源的方式快速发展，而不是被某个重量级业务拖慢节奏。

还有一个容易被忽略的设计原则：Skill 不绑定模型。同一个 SKILL.md 既可以在 GPT-4 上跑，也可以在 Claude 上跑，还可以在本地开源模型上跑。仓库不关心你用谁家的大脑，只负责保证你拿到的能力描述是清晰的、可复现的、可对比的。这让平台在中立性上天然优于“某家模型厂商提供的 Agent 商店”。

四、成果与收获

把仓库跑起来后，几个有意思的变化出现了：

1. 冲突暴露在前：之前 BA 改了提示词、SA 不知道，等集成时才发现语义对不上。现在所有变更通过 PR 走仓库，跨角色影响一目了然。
2. Skill 出现了"明星"和"僵尸"：通过下载统计，团队清晰地看到了哪些 Skill 被高频复用、哪些无人问津，可以果断下架后者。
3. 评测分数成了"健康指标"：每次发布都跑基准，仓库首页就能看到分数趋势，质量回归立刻被发现。
4. 新人首日就上手：新人第一天 clone 仓库、跑评测、看 README，就能跑通端到端的演示。

更深入的变化是"能力交换"成为可能：当仓库里某个团队的 SA-Master 做得足够好，另一个团队可以直接复用，而不用重复造轮子。这种跨团队的知识复用才是 Skill 仓库真正的价值——它让 Agent 能力也像代码一样成为了可流动的资产。

五、实践成果

网站地址：plan.smartmoves.com.cn

这套架构已经在真实业务中跑通——该站点是 Agent Skill Warehouse（mcp.smartmoves.com.cn）的实践入口，把 BA-Master / SA-Master / PM-Master 三个技能集的能力具象化为可视化的智能规划工作台，欢迎访问体验。

访问站点时建议留意两点：一是各角色 Agent 的交付物是否清晰可读，二是交接处的格式是不是严格遵循了 output_contract。这两个点是衡量一个 Skill 仓库是否“上了轨道”的最直观信号。