【无标题】 - 技术栈

MSDD

Multi-repo Spec-Driven Development：多仓联动 + 规范驱动的开发工具。schema 驱动产物定义，AI skills 承载工作流，CLI 负责状态与校验。

📖 Commands & Skills 使用说明书 --- CLI 全命令、9 个 skills、斜杠命令与端到端工作流示例

多仓/单仓规范驱动开发工具

MSDD 是一个基于规范驱动开发（SDD）的工具，帮助你在编写代码之前先定义需求。与 OpenSpec 类似，MSDD 使用 proposal → specs → design → tasks 的工作流，但额外支持多仓开发模式。

特性

🔄 三种工作流模式：多仓（multi-repo）、子仓（story-driven）、单仓（single-repo）
🤖 30+ AI 工具支持：Claude Code、Cursor、Windsurf、Copilot、CodeArts、Fornecode、Hermes 等
📝 规范驱动：先定义需求，再编写代码
🔧 灵活可扩展：自定义 schemas、skills、commands

安装

bash 复制代码

npm install -g @cyzadyx/msdd

使用方法

初始化项目

bash 复制代码

# 在当前目录初始化
msdd init

# 指定目标目录
msdd init --target ./my-project

# 指定 schema 类型（兼容旗标，等价 --mode）
msdd init --target ./my-project --schema single-repo

# 指定工作模式（推荐）
msdd init --target ./my-project --mode multi-repo

# 指定 AI 工具目录
msdd init --target ./my-project --ai-cursor ~/.cursor/

检查设计完整性

bash 复制代码

msdd review --target ./my-project

更新包和 AI 工具配置

bash 复制代码

# 按 .env 记录的 AI 工具目录同步 skills/commands
msdd update --target ./my-project

# 首次配置或更换 AI 工具目录（写入 .env 并同步）
msdd update --target ./my-project --ai ~/.cursor/

工作流

命令一览

命令	说明
`msdd init`	初始化 MSDD 项目，复制 schemas/skills/commands 到目标目录
`msdd new change <name>`	创建 change 骨架（`.msdd.yaml` + 产物模板；`--skip-specs` 声明零 delta）
`msdd list --json`	列出进行中的 change（按最近修改排序）
`msdd status --change <name> --json`	查看 change 的产物图（完成/缺失/skipped 与下一步）
`msdd instructions <id> --change <name> --json`	输出产物生成指令（id 支持产物名与 `apply`/`archive`）
`msdd validate [change]`	校验 change 产物完整性与 spec delta 格式（零 delta 拒绝、Scenario 层级检查）
`msdd archive <change>`	归档：校验 → 合并 delta 进 `msdd/specs/` → 移入 `changes/archive/`（`--force` 跳过校验）
`msdd show [change]` / `msdd view`	人类可读的产物图查看
`msdd doctor`	项目健康检查（config/schema/changes/AI 工具目录）
`msdd context`	输出项目上下文（config、模式、capabilities、变更概览）
`msdd store list/add/remove`	管理本机注册的独立仓库（`--store <id>` 在各命令上定位）
`msdd update`	更新 MSDD 包，同步 skills/commands 到 AI 工具目录
`msdd review`	检查当前设计生成的完整性

mode 模式

mode 是唯一的模式判定来源，写入 msdd/config.yaml，由 CLI 与全部 skill 共同遵循。

mode	说明	产物
`multi-repo`	多仓主仓（默认）	requirement-proposal.md, specs/, requirement-design.md
`story-driven`	子仓（由主仓 apply 自动写入）	story-design.md, story-task.md
`single-repo`	单仓	proposal.md, design.md, tasks.md

配置分工

msdd/config.yaml = 执行依据 ：mode 判定、context（对 AI 的约束，不复制进产物）、repos（多仓子仓登记）。CLI 与 skill 都从这里读取模式。
msdd/.env = 安装/更新环境检测 ：仅存路径类变量（MSDD_ROOT、MSDD_AI_TOOL_DIR、MSDD_SKILLS_DIR、MSDD_COMMANDS_DIR）。旧项目仅存 .env 时，new change/review 会回退读取 MSDD_SCHEMA 并打印迁移提示------请尽快运行 msdd init 生成 config.yaml。

多仓工作区结构建议

推荐用容器仓 + git submodule 组织多仓项目：工作区命名 xx-MSDD-workspace（容器仓），各子仓统一放在 codebase/ 下并以 submodule 方式管理，长期沉淀的 specs 规范放在 knowledge/：

复制代码

xx-MSDD-workspace/            # 容器仓（主仓），msdd init 在这里执行
├── msdd/                     # 主仓配置与变更产物（config.yaml / changes/ / schemas/）
│   └── specs/                # 主仓合并后的长期规范
├── codebase/                 # 各子仓（git submodule，独立 git 仓）
│   ├── ai-vue/               #   前端子仓
│   └── ai-java/              #   后端子仓
└── knowledge/                # 团队知识库：specs 规范、领域约定、决策记录

config.yaml 的 repos[].path 指向 codebase/ 下的子仓：

yaml 复制代码

mode: multi-repo
repos:
  - name: ai-vue
    path: codebase/ai-vue
    desc: 前端
  - name: ai-java
    path: codebase/ai-java
    desc: 后端

submodule 常用操作：

bash 复制代码

git clone --recurse-submodules <workspace-url>   # 克隆时带上全部子仓
git submodule update --init codebase/ai-vue      # 按需初始化单个子仓
git submodule add <子仓url> codebase/<name>       # 新增子仓

说明：knowledge/ 与 msdd/specs/ 的分工------msdd/specs/ 是变更归档时自动合并的能力规范（工具读写的事实源）；knowledge/ 是人工维护的更宽泛知识库（领域约定、ADR、跨项目规范沉淀），MSDD 不直接读写它，仅作为团队约定共存于工作区。

项目结构

初始化后，项目目录结构如下：

复制代码

my-project/
├── msdd/
│   ├── .env                  # 仅路径类变量（安装/更新用）
│   ├── config.yaml           # 执行依据：mode + context + repos
│   ├── schemas/
│   │   ├── multi-repo/
│   │   ├── story-driven/
│   │   └── single-repo/
│   ├── changes/
│   └── specs/
└── proposal.md (或 requirement-proposal.md)

config.yaml（multi-repo 主仓示例）：

yaml 复制代码

version: 1
mode: multi-repo            # multi-repo | single-repo（子仓为 story-driven，由 apply 自动写入）
context: |
  项目背景、领域约束、团队约定。
repos:                      # 仅 mode: multi-repo 时必填
  - name: my-app            # 子仓 change 命名 <主change>-<name>
    path: ../my-app         # 相对主仓根或绝对路径（独立 git 仓）
    desc: 客户端应用

标准工作流

以 multi-repo 为例的完整链路（每步使用对应斜杠命令或 skill）：

探索与 UI 设计 --- /msdd-explore：自由探索想法、澄清需求；入口自动检测到 UI 设计（设计稿截图 / Figma 链接 / UI 关键词）时进入 UI 分析分支，产出 ux-code.md 设计文档，作为后续交互与需求的依据之一。
提出变更建议 --- /msdd-propose：生成该模式产物链（multi-repo：requirement-proposal / specs/ / requirement-design）。变更文档一定要全，并且要符合 ux-code 设计文档的规范。
审核变更建议 --- /msdd-review：按一致性/正确性/边界线维度审查变更建议，要包含所有可能的情况，包括边界情况和异常情况；产出带日期审查报告。
测试变更建议 --- /msdd-test：主仓 test-design（测试点与子仓职责分配）；测试要包含所有可能的情况，包括边界情况和异常情况。子仓 story-test 由下一步 story 派生时顺带生成（schema 依赖 story-test ← story-design）。
派生 story --- /msdd-story：依据 propose + test 生成的产物，给每个代码仓创建一个 story（story-design / story-test / story-task），描述变更的内容；前端仓必须包含 ux-code 设计文档的链接与 UCD 结构引用。
实现变更 --- /msdd-apply：主仓任务实现 + 按 repos 跨仓分发（子仓自动 init 为 story-driven 并创建 <主change>-<子仓> 骨架）；实现要包含所有可能的情况，包括边界情况和异常情况。
验证实现 --- 执行 story-test 用例，测试实现是否符合预期，重点核对边界与异常路径。
一致性审查 --- /msdd-code-review：检测所有实现仓的约束的一致性------字段是否一致、枚举值是否一致、是否符合 ux-code 设计文档的规范；产出审查报告。
补齐规范并同步实现 --- /msdd-sync-specs：使用 msdd-sync-specs 补充遗漏的规范文档（把审查中发现但未登记的约束补充进主仓 specs/），然后按规范实现。
归档 --- /msdd-archive：归档实现仓的代码变更，specs/ 留作长期契约。

single-repo 链路 ：/msdd-explore（+UI）→ /msdd-propose → /msdd-review → /msdd-test → /msdd-apply → /msdd-code-review → /msdd-sync-specs → /msdd-archive（省略 story 与跨仓分发步骤）。

断点续跑 ：流程中断后随时运行 /msdd-continue------扫描变更产物与任务勾选状态，判定当前阶段并路由到正确的下一步命令（只读，不生成产物）。

验收点：mode 判定来自 config.yaml；propose 产物名随 mode 变化；apply 跨仓分发按 repos 登记；.env 回退仅出现在无 config.yaml 的旧项目。

与 OpenSpec 对比

特性	OpenSpec	MSDD
定位	单仓 SDD	多仓/单仓 MSDD
目录	`openspec/`	`msdd/`
Schemas	`spec-driven`	`multi-repo`, `story-driven`, `single-repo`
多仓支持	❌	✅
AI 工具	30+	30+
自定义 Schema	✅	✅

快速开始

bash 复制代码

# 1. 安装
npm install -g @cyzadyx/msdd

# 2. 初始化
msdd init --target ./my-project --schema single-repo

# 3. 编写 proposal.md
vim my-project/proposal.md

# 4. 检查完整性
msdd review --target ./my-project

# 5. 开始开发
cd my-project

许可证

MIT