cc-devflow 1.0.1

package/.claude/docs/design/intent-driven-input-design.md

@@ -0,0 +1,380 @@
+# Intent-driven 输入解析机制设计
+
+> **设计时间**: 2025-01-20
+> **基于**: GitHub spec-kit Intent-driven 理念
+> **目标**: 支持从模糊想法到明确需求的完整转换
+
+---
+
+## 🎯 设计目标
+
+### 核心理念
+借鉴 spec-kit 的"从模糊想法开始，迭代开发综合PRD"理念，建立：
+- **低门槛启动**: 用户可以用自然语言描述模糊想法
+- **智能引导**: AI主动询问澄清问题，逐步完善需求
+- **迭代细化**: 支持多轮对话，逐步细化需求边界
+- **兼容现有**: 保持与现有 `/flow-new` 的完全兼容
+
+### 用户体验目标
+```text
+用户输入: "我想做一个用户管理系统"
+      ↓
+系统澄清: "这个系统主要面向哪些用户？内部员工还是外部客户？"
+      ↓
+用户回答: "主要是内部员工，包括不同部门和权限"
+      ↓
+系统澄清: "需要哪些核心功能？用户注册、权限管理、部门管理？"
+      ↓
+逐步细化，最终生成: REQ-001|内部员工权限管理系统|完整的需求描述
+```
+
+---
+
+## 🔄 输入模式设计
+
+### 模式1: 传统精确模式 (保持兼容)
+```bash
+/flow-new "REQ-123|支持用户下单|https://plan.example.com/Q1"
+```
+- **识别特征**: 包含管道符 `|` 的结构化输入
+- **处理方式**: 直接按现有流程处理
+- **优势**: 快速启动，无需交互
+
+### 模式2: Intent 模糊模式 (新增)
+```bash
+/flow-new "我想做一个用户管理系统"
+/flow-new "需要一个数据分析功能来帮助业务决策"
+/flow-new "希望优化当前的订单处理流程"
+```
+- **识别特征**: 自然语言描述，无结构化格式
+- **处理方式**: 启动智能澄清流程
+- **优势**: 降低门槛，支持探索
+
+### 模式3: 半结构化模式 (新增)
+```bash
+/flow-new "REQ-123|我想要一个用户管理的东西"
+/flow-new "|用户管理系统|"
+```
+- **识别特征**: 部分结构化，但有模糊元素
+- **处理方式**: 混合模式，保留明确部分，澄清模糊部分
+- **优势**: 平衡结构和灵活性
+
+---
+
+## 🧠 智能解析引擎
+
+### 输入分类算法
+```yaml
+解析步骤:
+  1. 格式检测:
+     - 检查是否包含管道符结构
+     - 识别REQ-ID模式
+     - 判断URL存在性
+
+  2. 内容分析:
+     - 自然语言处理
+     - 关键词提取
+     - 意图识别
+
+  3. 模式判定:
+     - 精确模式: 完整结构化
+     - 模糊模式: 自然语言描述
+     - 半结构化: 混合模式
+
+  4. 路由处理:
+     - 精确模式 → 现有流程
+     - 模糊模式 → 澄清流程
+     - 半结构化 → 混合流程
+```
+
+### 意图识别模式
+```yaml
+业务领域识别:
+  用户管理: ["用户", "权限", "角色", "登录", "认证"]
+  数据分析: ["分析", "报表", "统计", "图表", "指标"]
+  订单系统: ["订单", "购买", "支付", "商品", "库存"]
+  内容管理: ["文章", "内容", "编辑", "发布", "审核"]
+
+功能类型识别:
+  CRUD操作: ["增加", "删除", "修改", "查询", "管理"]
+  流程优化: ["优化", "改进", "提升", "简化", "自动化"]
+  新功能: ["新增", "开发", "实现", "支持", "添加"]
+  集成对接: ["集成", "对接", "连接", "同步", "导入"]
+
+复杂度评估:
+  简单: 单一实体CRUD
+  中等: 多实体关联，简单业务流程
+  复杂: 复杂业务逻辑，多系统集成
+```
+
+---
+
+## 💬 澄清问题生成策略
+
+### 问题分层体系
+```yaml
+第一层 - 核心定位问题:
+  业务领域: "这个功能主要解决什么业务问题？"
+  目标用户: "主要使用者是谁？内部员工还是外部用户？"
+  核心价值: "期望通过这个功能达到什么目标？"
+
+第二层 - 功能边界问题:
+  核心功能: "需要哪些核心功能？请按重要性排序"
+  数据实体: "涉及哪些主要的数据对象？"
+  业务流程: "主要的业务流程是怎样的？"
+
+第三层 - 技术约束问题:
+  性能要求: "对性能有什么特殊要求？"
+  安全要求: "有哪些安全或权限要求？"
+  集成要求: "需要与现有系统集成吗？"
+
+第四层 - 验收标准问题:
+  成功标准: "怎样算是成功实现了这个功能？"
+  验收条件: "有哪些具体的验收条件？"
+  时间要求: "期望的交付时间是？"
+```
+
+### 智能问题选择
+```yaml
+问题选择策略:
+  基于意图类型:
+    - 新功能开发: 关注功能范围和技术实现
+    - 流程优化: 关注现状分析和改进方向
+    - 系统集成: 关注接口和数据流
+
+  基于用户回答:
+    - 回答详细: 深入细节问题
+    - 回答模糊: 回到基础定位问题
+    - 回答偏离: 引导回到核心问题
+
+  基于复杂度:
+    - 简单需求: 3-5个关键问题
+    - 中等需求: 8-10个问题
+    - 复杂需求: 15-20个问题，分阶段提问
+```
+
+---
+
+## 🔄 交互流程设计
+
+### 澄清对话模式
+```yaml
+流程阶段:
+  1. 初始理解确认:
+     "我理解您想要[概括描述]，对吗？"
+
+  2. 核心问题澄清:
+     一次提出1-2个最关键问题
+
+  3. 细节补充:
+     基于回答逐步深入
+
+  4. 需求总结确认:
+     "基于我们的讨论，我总结如下..."
+
+  5. 生成结构化需求:
+     自动生成REQ-ID、标题和描述
+
+对话控制:
+  最大轮次: 10轮
+  最小信息: 业务领域 + 核心功能 + 目标用户
+  退出条件: 用户满意 + 信息充足
+```
+
+### 状态管理
+```yaml
+对话状态:
+  current_intent: 当前理解的用户意图
+  clarified_aspects: 已澄清的方面
+  pending_questions: 待询问的问题
+  confidence_score: 需求理解的置信度
+
+状态持久化:
+  临时文件: .claude/temp/intent-${session_id}.json
+  保存内容: 对话历史、提取信息、状态数据
+  清理策略: 24小时后自动清理
+```
+
+---
+
+## 📋 需求提取和结构化
+
+### 信息提取模型
+```yaml
+提取目标:
+  基础信息:
+    - 业务领域 (user_management, data_analysis, etc.)
+    - 功能类型 (crud, optimization, integration, etc.)
+    - 复杂度级别 (simple, medium, complex)
+
+  核心内容:
+    - 目标用户群体
+    - 核心功能列表
+    - 关键数据实体
+    - 主要业务流程
+
+  技术要求:
+    - 性能指标
+    - 安全要求
+    - 集成需求
+    - 技术约束
+
+  验收标准:
+    - 功能验收条件
+    - 性能验收标准
+    - 用户体验要求
+```
+
+### 自动 REQ-ID 生成
+```yaml
+生成规则:
+  格式: REQ-{YYYYMMDD}-{序号}
+
+  序号规则:
+    - 查询当日已有需求数量
+    - 自动递增编号
+    - 避免冲突
+
+  示例:
+    - REQ-20250120-001
+    - REQ-20250120-002
+
+备选方案:
+  用户可以自定义REQ-ID格式
+  支持项目前缀: PROJ-001, FEATURE-001
+```
+
+### 标题智能生成
+```yaml
+生成模式:
+  模板化:
+    "{业务领域}{功能类型}系统"
+    "基于{技术栈}的{业务功能}平台"
+
+  关键词组合:
+    提取用户描述中的关键业务词汇
+    结合功能类型形成标题
+
+  用户确认:
+    生成2-3个候选标题
+    用户选择或自定义
+```
+
+---
+
+## 🔧 技术实现架构
+
+### 组件划分
+```yaml
+输入解析器 (InputParser):
+  职责: 识别输入模式，分类处理
+  输入: 用户原始输入
+  输出: 解析模式 + 提取信息
+
+意图理解器 (IntentAnalyzer):
+  职责: 分析用户意图，生成澄清问题
+  输入: 模糊输入文本
+  输出: 意图分析 + 问题列表
+
+对话管理器 (DialogManager):
+  职责: 管理澄清对话流程
+  功能: 状态追踪、问题选择、会话控制
+
+需求构建器 (RequirementBuilder):
+  职责: 将澄清结果转换为结构化需求
+  输出: REQ-ID + 标题 + 详细描述
+```
+
+### 数据流
+```text
+用户输入 → InputParser → 模式判断
+    ↓
+[精确模式] → 现有流程
+    ↓
+[模糊模式] → IntentAnalyzer → 初始分析
+    ↓
+DialogManager → 澄清对话 → 收集信息
+    ↓
+RequirementBuilder → 结构化需求 → 进入现有流程
+```
+
+---
+
+## 🎛️ 配置和扩展
+
+### 可配置项
+```yaml
+澄清策略:
+  max_clarification_rounds: 10
+  min_confidence_threshold: 0.8
+  question_selection_strategy: "adaptive"
+
+问题库:
+  custom_questions: 支持自定义问题模板
+  domain_specific: 不同业务域的专门问题
+  language_preference: 中文/英文问题
+
+生成规则:
+  req_id_format: "REQ-{date}-{seq}"
+  title_generation_mode: "template" | "keyword" | "user_driven"
+  auto_proceed_threshold: 0.9
+```
+
+### 扩展接口
+```yaml
+问题生成器接口:
+  自定义业务域的问题生成逻辑
+  支持插件式扩展
+
+意图识别器接口:
+  支持外部NLP服务集成
+  可替换默认的关键词匹配
+
+需求模板接口:
+  支持不同项目类型的需求模板
+  可配置验收标准模板
+```
+
+---
+
+## 📊 效果评估
+
+### 成功指标
+```yaml
+用户体验:
+  - 模糊输入成功率 > 85%
+  - 澄清轮次平均 < 6轮
+  - 用户满意度 > 80%
+
+系统效率:
+  - 响应时间 < 2秒/轮
+  - 生成需求质量 > 现有方式
+  - 减少需求返工率 > 30%
+
+适用性:
+  - 支持业务域覆盖率 > 80%
+  - 复杂需求处理成功率 > 70%
+  - 与现有流程兼容性 100%
+```
+
+### 度量方式
+```yaml
+自动度量:
+  - 对话轮次统计
+  - 置信度分数追踪
+  - 成功转换率监控
+
+用户反馈:
+  - 澄清后满意度调查
+  - 生成需求质量评分
+  - 使用体验问卷
+
+质量评估:
+  - 生成需求的完整性
+  - 与最终实现的匹配度
+  - 后续变更率
+```
+
+---
+
+**设计原则**: 在保持现有 `/flow-new` 强大能力的基础上，降低使用门槛，让更多模糊想法能够顺利转化为明确的需求和高质量的实现。