mspec-cli 5.1.1

mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具

mspec-cli

mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具

通过交互式命令行澄清机制，实现结构化问题发现与澄清；通过自发进化体系，使 AI 随着项目积累越来越了解你的项目。

特性

• 🚀 一键安装 - pip install mspec-cli 即可使用
• 🔄 批量式澄清 - 一次性列出所有问题，统一回答，高效不拖沓
• 💾 断点续传 - 支持随时中断，下次自动恢复
• 📚 结构化问题分类 - 6个需求维度 + 7个设计维度
• 🧬 自发进化体系 - 使用越久，整个 spec coding 流程越精准
• 🎨 美观界面 - 使用 Rich 库提供彩色终端输出

文档

📚 完整文档 →

新手入门

• 📖 安装指南 - 系统要求与安装步骤
• ⚡ 5分钟快速开始 - 体验完整流程
• 🎯 第一个完整变更 - 从零到交付的详细教程

完整指南

• 💡 核心概念 - Change、Capability、问题分类学
• 🔧 CLI 命令详解 - init、update、doctor
• 📋 工作流详解 - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档

实战教程

• 🛠️ Todo 应用开发 - 从零开发完整项目

参考手册

• 📖 CLI 命令速查
• ⚙️ 配置参考
• 🗂️ 问题分类学参考

其他

• ❓ 常见问题 (FAQ)
• 🐛 故障排除

快速开始

安装

pip install mspec-cli

初始化项目

# 进入项目目录
cd my-project

# 初始化 mspec 配置
mspec init

检查环境

mspec doctor

更新模板

mspec update

命令说明

mspec init [path]

初始化 mspec 项目配置

选项：

• --template, -t <url> - 使用自定义模板仓库
• --force, -f - 强制覆盖已有配置
• --dry-run - 模拟运行，不实际创建文件
• --yes, -y - 跳过确认，使用默认配置

示例：

mspec init                          # 初始化当前目录
mspec init ./my-project             # 初始化指定目录
mspec init --force                  # 强制覆盖已有配置
mspec init --template https://github.com/your-org/mspec-template

mspec update

更新模板到最新版本

选项：

• --check - 仅检查更新，不执行更新

示例：

mspec update          # 更新到最新版本
mspec update --check  # 仅检查是否有更新

mspec doctor

诊断环境配置

示例：

mspec doctor

工作流

需求输入
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 1: 需求澄清 (交互式)           │
│  - 生成 requirement-issues.md        │
│  - 交互式澄清 High/Medium 问题       │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 2: 提案创建                    │
│  - 创建 proposal.md                  │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 3: 规格定义                    │
│  - 创建 specs/*.md                   │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 4: 技术方案                    │
│  - 创建 design.md                    │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 5: 设计澄清 (交互式)           │
│  - 生成 design-issues.md             │
│  - 交互式澄清 High/Medium 问题       │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  阶段 6: 任务创建                    │
│  - 创建 tasks.md                     │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  实施 (apply)                        │
│  - 按任务清单逐步实施                │
│  - 可选：记录实施中的轻量观察        │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│  归档 (archive) + 进化               │
│  - 生成复盘报告（9个维度）           │
│  - 更新项目知识库（ADR/词汇/风险）   │
│  - 积累 3 次后自动触发进化分析       │
└─────────────────────────────────────┘

🧬 进化体系

mspec 内置 3层8维度 的完整进化体系，无需额外命令，每次 archive 自动推进：

Layer A — 项目事实（每次立即更新）

文件	内容	作用
openspec/decisions/adr.md	技术决策账本	不重复讨论已决定的事
openspec/glossary.md	领域词汇表	统一业务术语命名
openspec/risk-map.md	风险图谱	已知高风险区和 bug 模式

Layer B — 流程模式（积累 3+ 次后自动触发）

文件	内容	作用
openspec/templates/*.md	进化后的问题分类学	精准识别项目特有问题
openspec/task-patterns/	任务模板库	按 change 类型分解任务
openspec/config.yaml	用户偏好档案	减少重复对齐

Layer C — 元信号（长期积累）

文件	内容	作用
openspec/specs/CHANGELOG.md	规格演化日志	揭示业务边界稳定性
openspec/metrics.md	效率信号	发现系统性瓶颈

预期效果

时间点	效果
第 1 次 archive	ADR 建立，词汇表开始填充
第 3 次 archive	首次触发进化，分类学开始个性化
第 5-10 次	澄清轮次减少，apply 意外减少
长期（20+次）	项目知识库完备，AI 越来越了解项目

问题分类学

需求问题 (6个维度)

1. 功能完整性 - 功能边界、流程、依赖
2. 数据相关 - 数据定义、量级、一致性
3. 用户体验 - 用户场景、交互、性能
4. 边界与异常 - 边界条件、异常场景、权限
5. 集成与依赖 - 外部系统、内部模块、环境
6. 优先级与范围 - 必需vs可选、时间、资源

设计问题 (7个维度)

1. 架构决策 - 架构方案、服务边界、扩展性
2. 技术选型 - 框架、数据库、中间件
3. 接口设计 - API契约、数据流、异步处理
4. 数据与状态 - 数据模型、状态机、迁移
5. 安全与合规 - 认证授权、数据安全、审计
6. 性能与可靠性 - 性能瓶颈、缓存、降级熔断
7. 部署与运维 - 部署方案、监控告警、配置管理

交互式澄清

=================================================================
📋 需求澄清 - 批量确认（共 4 个问题：3 High，1 Medium）
=================================================================

需要确认 4 个问题，请一并回答：

1. 🔴 [功能完整性] 用户资料需要包含哪些字段？
   选项：A) 基础版：用户名、邮箱、手机号
         B) 标准版：用户名、邮箱、手机号、头像、昵称
         C) 完整版：基础 + 部门、职位、入职日期
         D) 自定义

2. 🔴 [数据相关] 手机号字段需要验证格式吗？
   选项：A) 不验证  B) 基础验证：11 位数字  C) 严格验证国内规则

3. 🟡 [用户体验] 用户注册后需要邮箱验证吗？
   选项：A) 不需要  B) 需要，否则无法登录  C) 需要，但可跳过

4. 🔴 [边界与异常] 用户名重复时的处理方式？
   选项：A) 报错提示  B) 自动加数字后缀  C) 让用户重新输入

请输入各题答案（如：1A 2B 3C 4A），或输入 q 退出保存：
=================================================================

操作指令：

• 按编号回答每道题，一次性提交所有答案（如：1A 2B 3C 4A）
• q - 退出保存，下次自动恢复

配置

mspec 配置文件位于 openspec/config.yaml，包含：

• 问题分类学引用
• 交互式澄清配置
• 各阶段规则定义

开发

# 克隆仓库
git clone https://github.com/mspec-dev/mspec.git
cd mspec

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 格式化代码
black src/
isort src/

# 类型检查
mypy src/

许可证

MIT

贡献

欢迎提交 Issue 和 PR！

相关链接

• GitHub
• PyPI
• 文档