日常工作知识库

Appearance

MDS CLI Agent Skills 多源架构与智能回退解析机制 ​

在 AI Agent 生态中，技能（Skills）的跨终端分发与高效管理是提升 Pairs Programming 和自动化效率的关键环节。本文总结了 @mdsfe/mds-cli 的 Agent Skills 多源融合设计、动态 Registry 寻址、离线快照回退与单数快捷指令适配机制。

一、 背景与架构目标 ​

随着 79team 生产级技能库（如 prompt-standard-skill、imap-smtp-email、map-integration 等）从早期私有源逐步收敛托管至 GitHub 开源共享仓库 (79online/skillhub)，命令行工具 CLI 需要同时兼顾：

  1. 历史多源兼容：兼容公共基础设施源与最新的 GitHub 生产级共享源；
  2. 极简终端交互：提供 npx @mdsfe/mds-cli skill install <skill-name> 快捷单数指令；
  3. 网络高可用保障：在 GitHub / Gitee 连接阻断或代理不可达时，保证 100% 离线可安装。

二、 多源设计与解析工作流 ​

1. 统一 Registry 索引元数据 ​

mds-cli 维护了一个轻量化的 registry.json，集中登记全部可用的技能元数据：

  • repository: 声明主仓库 Remote URL（如 https://github.com/79online/skillhub.git）与 Raw Base URLs。
  • skills 数组: 记录技能的 name、titles、summaries、tags 以及多语言路径 paths。

2. 动态远端拉取 vs 离线 Snapshot 降级 ​

当用户执行 mds skill 时：

  1. CLI 优先尝试通过 Sparse Checkout 增量拉取远端最新的 skills/registry.json；
  2. 若远端 Git 拉取失败（例如遭遇网络连接超时或代理断连），CLI 会自动拦截 Error 并无缝回退至内置的 local-snapshot 静态快照；
  3. 提示信息显示 提示: 已回退到本地 snapshot，并继续保证安装流程 100% 顺畅完成。

3. 多重路径容错算法 (Multi-path Fallback) ​

由于不同的开源 Git 仓库在技能文件夹组织形态上可能存在差异（如 skills/zh-CN/name、skills/name 或根目录 name），mds-cli 内置了 4 级智能探针：

javascript
let sourceDir = relativePath ? path.join(sourceResult.sourceRoot, relativePath) : '';

if (!sourceDir || !fs.existsSync(sourceDir)) {
  const altPath1 = path.join(sourceResult.sourceRoot, 'skills', locale || 'zh-CN', skill.name);
  const altPath2 = path.join(sourceResult.sourceRoot, 'skills', skill.name);
  const altPath3 = path.join(sourceResult.sourceRoot, skill.name);

  if (fs.existsSync(altPath1)) sourceDir = altPath1;
  else if (fs.existsSync(altPath2)) sourceDir = altPath2;
  else if (fs.existsSync(altPath3)) sourceDir = altPath3;
}

三、 CLI 命令行使用指南 ​

在最新的 @mdsfe/mds-cli@0.3.5+ 中，支持以下标准化快捷指令：

bash
# 1. 罗列全量可用技能 (自动区分本地快照与远端)
npx @mdsfe/mds-cli@latest skill list

# 2. 一键安装指定技能至本地 Agent (自动部署至 ~/.gemini/config/skills/ 等路径)
npx @mdsfe/mds-cli@latest skill install prompt-standard-skill
npx @mdsfe/mds-cli@latest skill install imap-smtp-email
npx @mdsfe/mds-cli@latest skill install ai-resource-extractor

# 3. 强行使用内置离线快照安装 (无需网络请求)
npx @mdsfe/mds-cli@latest skill install book-to-skill --local-only

四、 总结与收效 ​

通过统一单数指令 + 动态多源索引 + 离线 Snapshot 降级 + 多路径容错，@mdsfe/mds-cli 实现了零摩擦的跨 Agent 技能一键分发。不仅彻底消除了对内部私有 CLI 命令的依赖，而且在网络环境受限时仍具备强鲁棒性。