mspec-cli 4.0.0__py3-none-any.whl

mspec/templates/design-issues.md

@@ -0,0 +1,218 @@
+# 设计问题清单
+
+## 变更信息
+- **变更名称**: [change-name]
+- **当前阶段**: `analyzing` | `clarifying` | `clarified` | `resolved`
+- **最后更新**: [YYYY-MM-DD]
+- **下次检查**: [YYYY-MM-DD]
+
+---
+
+## 设计维度问题矩阵
+
+<!--
+说明：
+1. 按设计问题分类学维度组织
+2. 每个设计维度下列出具体问题
+3. 问题 ID 格式：D[维度序号]-[序号] 例如 D1-001
+-->
+
+---
+
+### 维度 1: 架构决策
+
+#### 问题列表
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D1-001 | [如：架构模式选择未定] | 🔴 High / 🟡 Medium / 🟢 Low | `open` / `clarifying` / `clarified` | [决策结论] |
+| D1-002 | [如：服务边界划分不清晰] | | | |
+
+**D1-001 详细说明**:
+- **问题类型**: 架构方案不确定
+- **具体表现**: [详细描述]
+- **影响范围**: [对系统的影响]
+- **可选方案**:
+  - A) [描述 + 优缺点]
+  - B) [描述 + 优缺点]
+  - C) [描述 + 优缺点]
+  - D) 自定义...
+- **决策结果**: [交互式澄清后的决策]
+- **决策理由**: [为什么选这个方案]
+- **澄清时间**: [YYYY-MM-DD]
+- **澄清人**: [@name]
+
+---
+
+### 维度 2: 技术选型
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D2-010 | [如：消息队列选型未定] | | | |
+| D2-011 | [如：缓存方案未确定] | | | |
+
+**D2-010 详细说明**:
+- **问题类型**: 核心框架/库未确定
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 3: 接口设计
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D3-020 | [如：API 版本管理策略未定] | | | |
+
+**D3-020 详细说明**:
+- **问题类型**: API 契约未定 / 数据流不清晰 / 异步处理机制
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 4: 数据与状态
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D4-030 | [如：订单状态机未定义] | | | |
+
+**D4-030 详细说明**:
+- **问题类型**: 数据模型未定 / 状态机未定义 / 数据迁移方案
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 5: 安全与合规
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D5-040 | [如：权限模型未设计] | | | |
+
+**D5-040 详细说明**:
+- **问题类型**: 认证授权未设计 / 数据安全 / 审计与日志
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 6: 性能与可靠性
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D6-050 | [如：缓存一致性策略未定] | | | |
+
+**D6-050 详细说明**:
+- **问题类型**: 性能瓶颈未识别 / 缓存策略未定 / 降级与熔断
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+### 维度 7: 部署与运维
+
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 决策结果 |
+|---------|----------|----------|------|----------|
+| D7-060 | [如：灰度发布策略未定] | | | |
+
+**D7-060 详细说明**:
+- **问题类型**: 部署方案未定 / 监控告警 / 配置管理
+- **具体表现**:
+- **影响范围**:
+- **可选方案**:
+- **决策结果**:
+- **决策理由**:
+
+---
+
+## 问题统计
+
+| 设计维度 | 总计 | 已澄清 | 待澄清 | 已解决 |
+|----------|------|--------|--------|--------|
+| 架构决策 | 0 | 0 | 0 | 0 |
+| 技术选型 | 0 | 0 | 0 | 0 |
+| 接口设计 | 0 | 0 | 0 | 0 |
+| 数据与状态 | 0 | 0 | 0 | 0 |
+| 安全与合规 | 0 | 0 | 0 | 0 |
+| 性能与可靠性 | 0 | 0 | 0 | 0 |
+| 部署与运维 | 0 | 0 | 0 | 0 |
+| **总计** | 0 | 0 | 0 | 0 |
+
+---
+
+## 澄清记录
+
+### 交互式澄清会话 1: [YYYY-MM-DD]
+- **参与者**: [@name1, @name2, ...]
+- **澄清模式**: 命令行交互式
+- **澄清的问题**: [问题 ID 列表]
+- **设计决策**:
+  1. [决策 1]
+  2. [决策 2]
+- **设计变更**: [design.md 的更新内容]
+- **任务调整**: [tasks.md 的调整]
+
+### 交互式澄清会话 2: [YYYY-MM-DD]
+
+[同上结构...]
+
+---
+
+## 状态流转说明
+
+```
+analyzing:      AI 正在分析设计方案，发现问题
+                → 发现问题后自动转为 clarifying
+
+clarifying:     问题已列出，等待交互式澄清
+                → 使用命令行界面一问一答澄清
+                → 每题回答后立即同步到本文档
+                → 支持 'q' 退出，下次自动恢复
+                → 支持 's' 跳过 Low 优先级问题
+
+clarified:      所有 High 和 Medium 问题已澄清
+                → 可以创建/更新 tasks
+                → 根据澄清更新 design.md
+                → 状态可转为 resolved
+
+resolved:       设计已根据澄清更新，问题已解决
+                → 可以创建/更新 tasks
+```
+
+**当前状态**: `[current-status]`
+
+**状态变更历史**:
+- [YYYY-MM-DD]: `analyzing` → `clarifying` (AI 完成问题分析)
+- [YYYY-MM-DD]: `clarifying` → `clarified` (完成澄清会话 1)
+- [YYYY-MM-DD]: `clarified` → `resolved` (design.md 已更新)
+
+---
+
+## 关联文档
+
+- **技术方案**: `design.md`
+- **实施任务**: `tasks.md`
+- **需求问题清单**: `spec/requirement-issues.md`
+- **分类学参考**: `openspec/templates/design-issue-taxonomy.md`
+
+---
+
+## 备注
+
+<!-- 任何补充说明 -->

mspec/templates/requirement-issue-taxonomy.md

@@ -0,0 +1,155 @@
+# 需求问题分类学
+
+## 如何使用
+
+AI 在分析需求时，应按以下分类维度逐一检查，确保不遗漏关键问题。
+
+---
+
+## 1. 功能完整性问题 (Functional Completeness)
+
+### 1.1 功能边界模糊
+- **症状**: "支持用户管理" — 具体包括哪些操作？
+- **检查点**:
+  - 功能的包含范围是否明确？
+  - 功能的排除范围是否明确？
+  - 与相邻功能的边界是否清晰？
+
+### 1.2 功能流程缺失
+- **症状**: 只描述了结果，没描述过程
+- **检查点**:
+  - 用户如何触发这个功能？
+  - 功能的完整流程是什么？
+  - 异常情况如何处理？
+
+### 1.3 功能依赖未说明
+- **症状**: 假设其他功能已存在
+- **检查点**:
+  - 该功能依赖哪些前置功能？
+  - 依赖的功能是否已实现？
+  - 依赖的接口是否已定义？
+
+---
+
+## 2. 数据相关问题 (Data Concerns)
+
+### 2.1 数据定义模糊
+- **症状**: "用户资料" — 包含哪些字段？
+- **检查点**:
+  - 核心数据实体有哪些？
+  - 每个实体的字段和类型是什么？
+  - 字段的约束条件（必填、唯一、格式）？
+
+### 2.2 数据量级未明确
+- **症状**: 没有考虑数据规模
+- **检查点**:
+  - 预计的数据量级？（条数/日增长）
+  - 是否有大数据量特殊处理需求？
+  - 数据保留策略？
+
+### 2.3 数据一致性问题
+- **症状**: 多系统数据同步场景
+- **检查点**:
+  - 数据是否需要跨系统一致？
+  - 一致性要求（强一致/最终一致）？
+  - 冲突解决策略？
+
+---
+
+## 3. 用户体验问题 (User Experience)
+
+### 3.1 用户场景缺失
+- **症状**: 没有具体的使用场景
+- **检查点**:
+  - 目标用户是谁？
+  - 用户在什么场景下使用？
+  - 用户的核心痛点是什么？
+
+### 3.2 交互方式未确定
+- **症状**: 界面交互细节缺失
+- **检查点**:
+  - 界面布局有要求吗？
+  - 关键操作的交互流程？
+  - 错误提示方式？
+
+### 3.3 性能体验要求
+- **症状**: 没有性能指标
+- **检查点**:
+  - 响应时间要求？
+  - 并发用户数？
+  - 可用性要求（SLA）？
+
+---
+
+## 4. 边界与异常 (Edge Cases & Exceptions)
+
+### 4.1 边界条件未定义
+- **症状**: 只考虑正常流程
+- **检查点**:
+  - 输入的边界值（最大/最小/空值）？
+  - 数量的边界（批量操作的最大值）？
+  - 时间的边界（超时、有效期）？
+
+### 4.2 异常场景缺失
+- **症状**: "用户会正确操作"
+- **检查点**:
+  - 网络异常如何处理？
+  - 第三方服务失败如何处理？
+  - 数据校验失败如何反馈？
+
+### 4.3 权限与安全
+- **症状**: 没有权限控制描述
+- **检查点**:
+  - 哪些角色可以使用？
+  - 数据权限如何控制？
+  - 敏感操作是否需要审计？
+
+---
+
+## 5. 集成与依赖 (Integration & Dependencies)
+
+### 5.1 外部系统集成
+- **症状**: 需要对接但未说明细节
+- **检查点**:
+  - 需要对接哪些外部系统？
+  - 对接的接口是否已确定？
+  - 外部系统的稳定性/可用性？
+
+### 5.2 内部模块依赖
+- **症状**: 与现有功能的关系不明
+- **检查点**:
+  - 需要修改哪些现有模块？
+  - 是否影响现有功能？
+  - 是否需要数据迁移？
+
+### 5.3 环境依赖
+- **症状**: 部署环境未明确
+- **检查点**:
+  - 目标部署环境？（开发/测试/生产）
+  - 环境配置要求？
+  - 基础设施依赖？
+
+---
+
+## 6. 优先级与范围 (Priority & Scope)
+
+### 6.1 必需 vs 可选
+- **症状**: 所有功能都"必须有"
+- **检查点**:
+  - MVP 必须包含哪些功能？
+  - 哪些是后续迭代功能？
+  - 功能优先级排序？
+
+### 6.2 时间约束
+- **症状**: 没有时间线
+- **检查点**:
+  - 期望的交付时间？
+  - 是否有硬性 deadline？
+  - 阶段性里程碑？
+
+### 6.3 资源约束
+- **症状**: 资源无限假设
+- **检查点**:
+  - 预算限制？
+  - 人力约束？
+  - 技术栈限制？

mspec/templates/requirement-issues.md

@@ -0,0 +1,214 @@
+# 需求问题清单
+
+## 变更信息
+- **变更名称**: [change-name]
+- **当前阶段**: `discovering` | `clarifying` | `clarified` | `superseded`
+- **最后更新**: [YYYY-MM-DD]
+- **下次检查**: [YYYY-MM-DD]
+
+---
+
+## 功能点问题矩阵
+
+<!--
+说明：
+1. 按 OpenSpec Capabilities 结构组织
+2. 每个功能点下按问题分类维度列出具体问题
+3. 问题 ID 格式：R[功能点序号]-[分类序号][序号] 例如 R1-001
+-->
+
+---
+
+### 功能点 1: [功能点名称]
+
+#### 基本信息
+- **功能点 ID**: [kebab-case-id]
+- **对应 Spec**: `specs/[功能点ID]/spec.md`
+- **优先级**: P0 / P1 / P2
+- **负责人**: [@name]
+
+#### 问题列表
+
+##### 1. 功能完整性问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-001 | [一句话描述问题] | 🔴 High / 🟡 Medium / 🟢 Low | `open` / `clarifying` / `clarified` | [澄清后的结论] |
+| R1-002 | | | | |
+
+**R1-001 详细说明**:
+- **问题类型**: 功能边界模糊 / 功能流程缺失 / 功能依赖未说明
+- **具体表现**: [详细描述问题现象，引用需求原文]
+- **影响范围**: [如果不澄清会导致什么后果]
+- **建议选项**:
+  - A) [选项A描述]
+  - B) [选项B描述]
+  - C) [选项C描述]
+  - D) 自定义...
+- **澄清后**: [交互式澄清后自动填写]
+- **澄清时间**: [YYYY-MM-DD]
+- **澄清人**: [@name]
+
+---
+
+##### 2. 数据相关问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-010 | | | | |
+| R1-011 | | | | |
+
+**R1-010 详细说明**:
+- **问题类型**: 数据定义模糊 / 数据量级未明确 / 数据一致性问题
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 3. 用户体验问题
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-020 | | | | |
+| R1-021 | | | | |
+
+**R1-020 详细说明**:
+- **问题类型**: 用户场景缺失 / 交互方式未确定 / 性能体验要求
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 4. 边界与异常
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-030 | | | | |
+| R1-031 | | | | |
+
+**R1-030 详细说明**:
+- **问题类型**: 边界条件未定义 / 异常场景缺失 / 权限与安全
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 5. 集成与依赖
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-040 | | | | |
+| R1-041 | | | | |
+
+**R1-040 详细说明**:
+- **问题类型**: 外部系统集成 / 内部模块依赖 / 环境依赖
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+##### 6. 优先级与范围
+| 问题 ID | 问题描述 | 严重程度 | 状态 | 澄清结果 |
+|---------|----------|----------|------|----------|
+| R1-050 | | | | |
+| R1-051 | | | | |
+
+**R1-050 详细说明**:
+- **问题类型**: 必需 vs 可选 / 时间约束 / 资源约束
+- **具体表现**:
+- **影响范围**:
+- **建议选项**:
+- **澄清后**:
+
+---
+
+### 功能点 2: [功能点名称]
+
+#### 基本信息
+- **功能点 ID**: [kebab-case-id]
+- **对应 Spec**: `specs/[功能点ID]/spec.md`
+- **优先级**: P0 / P1 / P2
+- **负责人**: [@name]
+
+#### 问题列表
+
+[同上结构...]
+
+---
+
+## 问题统计
+
+| 分类 | 总计 | 已澄清 | 待澄清 | 已解决 |
+|------|------|--------|--------|--------|
+| 功能完整性 | 0 | 0 | 0 | 0 |
+| 数据相关 | 0 | 0 | 0 | 0 |
+| 用户体验 | 0 | 0 | 0 | 0 |
+| 边界与异常 | 0 | 0 | 0 | 0 |
+| 集成与依赖 | 0 | 0 | 0 | 0 |
+| 优先级与范围 | 0 | 0 | 0 | 0 |
+| **总计** | 0 | 0 | 0 | 0 |
+
+---
+
+## 澄清记录
+
+### 交互式澄清会话 1: [YYYY-MM-DD]
+- **参与者**: [@name1, @name2, ...]
+- **澄清模式**: 命令行交互式
+- **澄清的问题**: [问题 ID 列表]
+- **达成的决策**:
+  1. [决策 1]
+  2. [决策 2]
+- **更新后的状态**: `clarifying` → `clarified`
+- **下一步行动**: [如果有]
+
+### 交互式澄清会话 2: [YYYY-MM-DD]
+
+[同上结构...]
+
+---
+
+## 状态流转说明
+
+```
+discovering:    AI 正在分析需求，发现问题
+                → 发现问题后自动转为 clarifying
+
+clarifying:     问题已列出，等待交互式澄清
+                → 使用命令行界面一问一答澄清
+                → 每题回答后立即同步到本文档
+                → 支持 'q' 退出，下次自动恢复
+                → 支持 's' 跳过 Low 优先级问题
+
+clarified:      所有 High 和 Medium 问题已澄清
+                → 可以创建/更新 proposal
+                → AI 检查是否发现新问题（可能回到 discovering）
+
+superseded:     需求已变更，本文档已过时
+                → 创建新的问题清单
+```
+
+**当前状态**: `[current-status]`
+
+**状态变更历史**:
+- [YYYY-MM-DD]: `discovering` → `clarifying` (AI 完成问题发现)
+- [YYYY-MM-DD]: `clarifying` → `clarified` (完成澄清会话 1)
+- ...
+
+---
+
+## 关联文档
+
+- **提案文档**: `proposal.md`
+- **功能规格**: `specs/*/spec.md`
+- **设计问题清单**: `spec/design-issues.md`
+- **分类学参考**: `openspec/templates/requirement-issue-taxonomy.md`
+
+---
+
+## 备注
+
+<!-- 任何补充说明 -->

mspec/utils/__init__.py

@@ -0,0 +1,17 @@
+"""mspec 工具模块"""
+
+from mspec.utils.console import (
+    print_banner,
+    print_error,
+    print_info,
+    print_success,
+    print_warning,
+)
+
+__all__ = [
+    "print_banner",
+    "print_success",
+    "print_error",
+    "print_warning",
+    "print_info",
+]

mspec/utils/console.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""终端输出工具"""
+
+from rich.console import Console
+from rich.text import Text
+
+console = Console()
+
+
+def print_banner():
+    """打印欢迎横幅"""
+    banner = Text()
+    banner.append("╔══════════════════════════════════════╗\n", style="blue")
+    banner.append("║     ", style="blue")
+    banner.append("mspec", style="bold cyan")
+    banner.append(" - 规范驱动开发      ║\n", style="blue")
+    banner.append("╚══════════════════════════════════════╝", style="blue")
+    console.print(banner)
+    console.print()
+
+
+def print_success(message: str):
+    """打印成功消息"""
+    console.print(f"[bold green]✓[/bold green] {message}")
+
+
+def print_error(message: str):
+    """打印错误消息"""
+    console.print(f"[bold red]✗[/bold red] {message}")
+
+
+def print_warning(message: str):
+    """打印警告消息"""
+    console.print(f"[bold yellow]⚠[/bold yellow] {message}")
+
+
+def print_info(message: str):
+    """打印信息消息"""
+    console.print(f"[dim]{message}[/dim]")