@mdsfe/mds-cli

MDS 命令行工具，旨在高效完成项目初始化、规范配置及环境维护。

🚀 快速开始

安装/更新

# 安装
npm install -g @mdsfe/mds-cli

# 快捷更新
mds up

常用命令

• 项目初始化: mds init <project-name>
  根据 MDS 标准模板快速创建应用。
• SDD 初始化: mds sdd
  一键配置业务项目内的 SDD 工作流环境（生成 .agent、.specify、项目宪法等）。默认补齐工作流必需的局部 skills，其余共享 skills 仍建议走全局安装。
• 全局 Skills 管理: mds skills
  远程罗列、单个安装或全量安装 MDSFE 标准 skills，并自动分发到已检测到的用户级技能目录。
• 版本更新: mds upgrade (别名: up)
  检测并升级 CLI 到最新版本。默认会自动兼容 npm cache 权限异常，并在全局目录不可写时回退到用户级安装目录。
• 环境诊断: mds doctor
  检查当前网络、Registry 认证及 NodeJS 环境。

🛠 开发流程 (SDD)

1. 初始化: 在项目根目录下运行 mds sdd。
2. 编写规范: 遵循提示在 .specify 中定义需求。
3. AI 辅助: 利用生成的工作流（如 /speckit.plan）进行自动化开发。

职责边界

• mds sdd 面向项目内资产：.specify、.agent/workflows、.agent/rules、.cursor/commands、.cursor/rules 等与当前仓库直接绑定的工作流配置。
• mds skills 面向用户级共享资产：~/.codex/skills、~/.cursor/skills 等全局 skills 目录。
• 为避免用户同时执行 mds sdd 和 mds skills 时重复加载同名技能，mds sdd 默认只复制工作流必需的局部 skills（当前包括 cbm-preflight、igit-mcp-preflight、init-vitepress、node-env-guide）；如果确实需要项目内全部共享 skills，可显式使用 mds sdd --with-project-skills。

🧠 全局 Skills

mds skills 会优先拉取 mdsfe-agent-workflows 的远程 skills registry，网络不可用时自动回退到 CLI 内置 snapshot。CLI 内置 snapshot 现在可通过 npm run skills:sync 从远端显式同步。

常用命令

# 远程查看当前可用 skills
mds skills --list

# 从指定远程分支预览 skills registry
mds skills --list --registry-branch codex/58publish-skill-migration

# 安装当前语言的全部 skills 到已检测到的工具目录
mds skills --clone

# 初始化项目工作流，并默认补齐工作流必需的局部 skills
mds sdd --cursor

# 如需同时复制项目内全部共享 skills，再显式开启
mds sdd --cursor --with-project-skills

# 单个安装 init-vitepress
mds skills init-vitepress

# 安装 igit-mr-review
# 会自动委托 @epfe/igit-mr-skills-installer 完成完整 bootstrap，
# 包括 review 相关 skill 套件、PlanB launcher、自检与 best-effort MCP 接入
mds skills igit-mr-review

# 也可通过环境变量指定远程 skills 分支
MDS_SKILLS_BRANCH=codex/58publish-skill-migration mds skills igit-mr-review

# 仅安装到 Codex
mds skills init-vitepress --tool codex

# 一次安装到多种 IDE / Agent 工具
mds skills --clone --tool codex,cursor,openclaw,gemini,antigravity,vscode

# 额外安装到自定义目录
mds skills init-vitepress --dir ~/.codex/skills

目标路径扩展

CLI 默认会尝试检测内置目标：Codex、Cursor、OpenClaw、Gemini、Antigravity、VS Code。同时兼容 codex_root、cursor_root、openclaw_root、gemini_root、antigravity_root、vscode_root 这类显式别名，也支持通过 ~/.mdsrc 中的 skillTargets 配置更多工具路径，例如：

{
  "skillTargets": [
    {
      "name": "codex",
      "label": "Codex",
      "detectDir": "~/.codex",
      "path": "~/.codex/skills"
    },
    {
      "name": "my-tool",
      "label": "My Tool",
      "detectDir": "~/my-tool",
      "path": "~/my-tool/skills"
    }
  ]
}

预览指定 Skills 分支

默认情况下，mds skills 会拉取 mdsfe-agent-workflows 的 master 分支。

如果某个 skill 还在临时分支验证中，可以显式指定远程 registry 分支：

mds skills --list --registry-branch codex/58publish-skill-migration
mds skills igit-mr-review --registry-branch codex/58publish-skill-migration

也可以用环境变量：

export MDS_SKILLS_BRANCH=codex/58publish-skill-migration
mds skills --list

如果需要把 CLI 内置 snapshot 同步到某个远程分支，也可以执行：

npm run skills:sync -- --registry-branch codex/58publish-skill-migration

iGit MR 特殊说明

mds skills igit-mr-review 不再只是复制单个 skill 目录。

当命中 igit-mr-review 这类 igit-mr 托管技能时，CLI 会直接委托 @epfe/igit-mr-skills-installer，从而统一到与 CDN 脚本相同的安装链路，自动补齐：

• igit-mr-skills
• igit-mr-review
• igit-mr-review-mcp
• igit-mr-report
• igit-mr-bootstrap
• ~/.igit-mr/bin/igit-mr-bootstrap
• ~/.igit-mr-mcp.env
• best-effort MCP auto-registration 与自检

在较老的 Node 运行时（例如 Node 14）下，mds-cli 会自动回退到官方 CDN 安装脚本；在 Node 16+ 下则优先走私有 npm installer。对用户而言，mds skills igit-mr-review 与 curl -sSL https://j1.58cdn.com.cn/epfe/scripts/igit-mr-skills-install.sh | bash 的最终安装结果应保持一致。

📦 发布指南 (核心维护者)

# 修订号更新 (0.0.x)
npm run release:patch

# 特性更新 (0.x.0)
npm run release:minor

注意: 发布前请确保已配置 .npmrc 且具有 @mdsfe作用域权限。

❓ 常见问题排查 (Troubleshooting)

如果您在安装或升级时遇到问题，请先运行 mds doctor 进行快速诊断。

1. 权限不足 (EACCES)

如果在执行 mds upgrade 或 npm install -g 时报 EACCES 错误：

• mds up 现在会优先自动回退到用户级安装目录（默认 ~/.npm-global），并在需要时自动补 PATH。
• 如果是手动执行 npm install -g 报错，优先改用 mds up。
• 如果你的机器策略禁止用户级全局安装，再考虑修复 npm 全局目录权限或使用 sudo。

2. 文件冲突 (EEXIST)

如果报错 EEXIST: file already exists, symlink...：

• 方案: 执行强制覆盖安装：npm install -g @mdsfe/mds-cli --force

3. 命令不存在 (Command Not Found)

如果安装后提示 mds: command not found：

• 请检查您的环境变量 PATH 是否包含了 npm 的全局 bin 目录。您可以运行 npm config get prefix 来查看安装位置。
• 如果刚执行过 mds up 且 CLI 已自动回退到 ~/.npm-global，重新打开终端即可加载新 PATH；也可以手动执行 source ~/.zshrc。

4. npm 缓存目录权限异常

如果日志里出现 ~/.npm/_cacache、root-owned files 或类似缓存权限错误：

• mds up 现在会自动改用 ~/.mds-cli/npm-cache 作为独立缓存目录，避免历史脏缓存影响升级。
• 如需彻底修复旧缓存，再按 npm 提示处理原始 ~/.npm 目录权限。