Metadata-Version: 2.4
Name: mspec-cli
Version: 5.0.0
Summary: mspec-cli（Member Spec）- 会员组规范驱动开发工作流 CLI 工具
Author-email: shirayner <team@mspec.io>
License: MIT
Project-URL: Homepage, https://github.com/mspec-dev/mspec
Project-URL: Documentation, https://github.com/mspec-dev/mspec#readme
Project-URL: Repository, https://github.com/mspec-dev/mspec.git
Project-URL: Issues, https://github.com/mspec-dev/mspec/issues
Keywords: spec,workflow,cli,development,mspec-cli
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: requests>=2.28.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: semver>=3.0.0
Requires-Dist: questionary>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

# mspec-cli

[![PyPI version](https://badge.fury.io/py/mspec-cli.svg)](https://badge.fury.io/py/mspec-cli)
[![Python version](https://img.shields.io/pypi/pyversions/mspec-cli.svg)](https://pypi.org/project/mspec-cli/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

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

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

## 特性

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

## 文档

📚 **[完整文档 →](docs/)**

### 新手入门
- [📖 安装指南](docs/getting-started/installation.md) - 系统要求与安装步骤
- [⚡ 5分钟快速开始](docs/getting-started/quickstart.md) - 体验完整流程
- [🎯 第一个完整变更](docs/getting-started/first-change.md) - 从零到交付的详细教程

### 完整指南
- [💡 核心概念](docs/guide/concepts.md) - Change、Capability、问题分类学
- [🔧 CLI 命令详解](docs/guide/cli-commands.md) - init、update、doctor
- [📋 工作流详解](docs/guide/) - 探索 → 澄清 → 提案 → 设计 → 实施 → 归档

### 实战教程
- [🛠️ Todo 应用开发](docs/tutorial/todo-app/) - 从零开发完整项目

### 参考手册
- [📖 CLI 命令速查](docs/reference/cli-reference.md)
- [⚙️ 配置参考](docs/reference/config-reference.md)
- [🗂️ 问题分类学参考](docs/reference/taxonomy-reference.md)

### 其他
- [❓ 常见问题 (FAQ)](docs/faq.md)
- [🐛 故障排除](docs/troubleshooting.md)

## 快速开始

### 安装

```bash
pip install mspec-cli
```

### 初始化项目

```bash
# 进入项目目录
cd my-project

# 初始化 mspec 配置
mspec init
```

### 检查环境

```bash
mspec doctor
```

### 更新模板

```bash
mspec update
```

## 命令说明

### `mspec init [path]`

初始化 mspec 项目配置

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

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

### `mspec update`

更新模板到最新版本

**选项：**
- `--check` - 仅检查更新，不执行更新

**示例：**
```bash
mspec update          # 更新到最新版本
mspec update --check  # 仅检查是否有更新
```

### `mspec doctor`

诊断环境配置

**示例：**
```bash
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`，包含：

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

## 开发

```bash
# 克隆仓库
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](LICENSE)

## 贡献

欢迎提交 Issue 和 PR！

## 相关链接

- [GitHub](https://github.com/mspec-dev/mspec)
- [PyPI](https://pypi.org/project/mspec-cli/)
- [文档](https://docs.mspec.io)
