cc-devflow 4.2.0 → 4.4.1

package/.claude/docs/design/consistency-conflict-detection-algorithms.md

@@ -1,658 +0,0 @@
-# 一致性检查冲突检测算法设计
-
-> **设计目标**: 建立智能的冲突检测和解决机制
-> **创建时间**: 2025-01-20
-> **版本**: v1.0
-
-## 📋 概述
-
-为 cc-devflow 的一致性检查系统设计高效的冲突检测算法，能够自动识别文档间的冲突、需求的矛盾以及实现的偏差，并提供智能的解决建议。
-
-## 🎯 核心目标
-
-### 检测能力
-1. **语义冲突检测**: 识别表达不同但含义冲突的需求
-2. **逻辑矛盾发现**: 发现业务规则和技术约束间的矛盾
-3. **实现偏差识别**: 检测代码实现与规格说明的偏差
-4. **版本不一致性**: 发现文档间的版本同步问题
-
-### 算法特性
-- **准确性**: 减少误报，提高检测精度
-- **效率性**: 支持大规模项目的快速检查
-- **可扩展性**: 支持自定义规则和新的检测维度
-- **智能性**: 基于上下文理解进行智能判断
-
-## 🏗 算法架构
-
-### 整体框架
-```yaml
-冲突检测流水线:
-  1. 数据预处理: 文档解析和结构化
-  2. 特征提取: 关键信息识别和抽取
-  3. 冲突分析: 多维度冲突检测
-  4. 结果评分: 冲突严重程度评估
-  5. 解决建议: 智能修复方案生成
-
-算法分层:
-  语法层: 格式和结构冲突
-  语义层: 含义和逻辑冲突
-  实现层: 代码和规格冲突
-  业务层: 需求和约束冲突
-```
-
-## 🔍 核心检测算法
-
-### 1. 语义冲突检测算法
-
-#### 1.1 需求描述矛盾检测
-```python
-class RequirementConflictDetector:
-    def __init__(self):
-        self.semantic_analyzer = SemanticAnalyzer()
-        self.conflict_patterns = ConflictPatternLibrary()
-
-    def detect_semantic_conflicts(self, requirements: List[Requirement]) -> List[Conflict]:
-        """
-        检测需求间的语义冲突
-        """
-        conflicts = []
-
-        # 1. 构建语义向量空间
-        semantic_vectors = self.build_semantic_vectors(requirements)
-
-        # 2. 识别相似但矛盾的需求
-        for i, req_a in enumerate(requirements):
-            for j, req_b in enumerate(requirements[i+1:], i+1):
-                similarity = self.calculate_semantic_similarity(
-                    semantic_vectors[i], semantic_vectors[j]
-                )
-
-                # 高相似度但逻辑矛盾
-                if similarity > 0.7 and self.is_logically_contradictory(req_a, req_b):
-                    conflict = self.create_semantic_conflict(req_a, req_b, similarity)
-                    conflicts.append(conflict)
-
-        return conflicts
-
-    def is_logically_contradictory(self, req_a: Requirement, req_b: Requirement) -> bool:
-        """
-        检测两个需求是否存在逻辑矛盾
-        """
-        # 提取动作和约束
-        actions_a = self.extract_actions(req_a)
-        constraints_a = self.extract_constraints(req_a)
-
-        actions_b = self.extract_actions(req_b)
-        constraints_b = self.extract_constraints(req_b)
-
-        # 检测矛盾模式
-        contradictory_patterns = [
-            self.check_exclusive_actions(actions_a, actions_b),
-            self.check_conflicting_constraints(constraints_a, constraints_b),
-            self.check_temporal_conflicts(req_a, req_b),
-            self.check_access_control_conflicts(req_a, req_b)
-        ]
-
-        return any(contradictory_patterns)
-```
-
-#### 1.2 业务规则冲突检测
-```python
-class BusinessRuleConflictDetector:
-    def __init__(self):
-        self.rule_parser = BusinessRuleParser()
-        self.logic_engine = LogicInferenceEngine()
-
-    def detect_rule_conflicts(self, business_rules: List[BusinessRule]) -> List[RuleConflict]:
-        """
-        检测业务规则间的冲突
-        """
-        conflicts = []
-
-        # 1. 解析业务规则为逻辑表达式
-        logical_rules = [self.rule_parser.parse(rule) for rule in business_rules]
-
-        # 2. 构建规则依赖图
-        dependency_graph = self.build_rule_dependency_graph(logical_rules)
-
-        # 3. 检测循环依赖
-        cycles = self.detect_circular_dependencies(dependency_graph)
-        for cycle in cycles:
-            conflicts.append(CircularDependencyConflict(cycle))
-
-        # 4. 检测逻辑矛盾
-        for rule_set in self.generate_rule_combinations(logical_rules):
-            if not self.logic_engine.is_satisfiable(rule_set):
-                conflicts.append(LogicalContradictionConflict(rule_set))
-
-        return conflicts
-
-    def generate_rule_combinations(self, rules: List[LogicalRule]) -> Iterator[List[LogicalRule]]:
-        """
-        生成可能产生冲突的规则组合
-        """
-        # 基于规则复杂度和相关性的智能组合生成
-        for size in range(2, min(len(rules) + 1, MAX_COMBINATION_SIZE)):
-            for combination in itertools.combinations(rules, size):
-                if self.is_potentially_conflicting(combination):
-                    yield list(combination)
-```
-
-### 2. 实现偏差检测算法
-
-#### 2.1 API 规格一致性检测
-```python
-class APIConsistencyDetector:
-    def __init__(self):
-        self.spec_parser = APISpecParser()
-        self.code_analyzer = CodeAnalyzer()
-
-    def detect_api_inconsistencies(self,
-                                   api_spec: APISpecification,
-                                   implementation: CodeBase) -> List[APIInconsistency]:
-        """
-        检测 API 规格与实现的不一致
-        """
-        inconsistencies = []
-
-        # 1. 解析 API 规格
-        spec_endpoints = self.spec_parser.extract_endpoints(api_spec)
-
-        # 2. 分析实现代码
-        impl_endpoints = self.code_analyzer.extract_endpoints(implementation)
-
-        # 3. 检测各种不一致类型
-        inconsistencies.extend(self.detect_missing_endpoints(spec_endpoints, impl_endpoints))
-        inconsistencies.extend(self.detect_extra_endpoints(spec_endpoints, impl_endpoints))
-        inconsistencies.extend(self.detect_signature_mismatches(spec_endpoints, impl_endpoints))
-        inconsistencies.extend(self.detect_response_format_mismatches(spec_endpoints, impl_endpoints))
-
-        return inconsistencies
-
-    def detect_signature_mismatches(self,
-                                   spec_endpoints: List[EndpointSpec],
-                                   impl_endpoints: List[EndpointImpl]) -> List[SignatureMismatch]:
-        """
-        检测方法签名不匹配
-        """
-        mismatches = []
-
-        for spec_endpoint in spec_endpoints:
-            impl_endpoint = self.find_matching_endpoint(spec_endpoint, impl_endpoints)
-            if impl_endpoint:
-                # 检测参数不匹配
-                param_mismatches = self.compare_parameters(
-                    spec_endpoint.parameters,
-                    impl_endpoint.parameters
-                )
-
-                # 检测返回类型不匹配
-                return_mismatches = self.compare_return_types(
-                    spec_endpoint.return_type,
-                    impl_endpoint.return_type
-                )
-
-                if param_mismatches or return_mismatches:
-                    mismatch = SignatureMismatch(
-                        endpoint=spec_endpoint.path,
-                        parameter_issues=param_mismatches,
-                        return_type_issues=return_mismatches
-                    )
-                    mismatches.append(mismatch)
-
-        return mismatches
-```
-
-#### 2.2 数据模型一致性检测
-```python
-class DataModelConsistencyDetector:
-    def __init__(self):
-        self.schema_analyzer = SchemaAnalyzer()
-        self.field_matcher = FieldMatcher()
-
-    def detect_model_inconsistencies(self,
-                                    specification_models: List[DataModel],
-                                    implementation_models: List[DataModel]) -> List[ModelInconsistency]:
-        """
-        检测数据模型的不一致性
-        """
-        inconsistencies = []
-
-        # 1. 建立模型映射关系
-        model_mappings = self.establish_model_mappings(specification_models, implementation_models)
-
-        # 2. 检测各种不一致类型
-        for spec_model, impl_model in model_mappings:
-            inconsistencies.extend(self.check_field_consistency(spec_model, impl_model))
-            inconsistencies.extend(self.check_relationship_consistency(spec_model, impl_model))
-            inconsistencies.extend(self.check_constraint_consistency(spec_model, impl_model))
-            inconsistencies.extend(self.check_validation_consistency(spec_model, impl_model))
-
-        # 3. 检测孤立模型
-        inconsistencies.extend(self.detect_orphaned_models(specification_models, implementation_models))
-
-        return inconsistencies
-
-    def check_field_consistency(self, spec_model: DataModel, impl_model: DataModel) -> List[FieldInconsistency]:
-        """
-        检测字段级别的不一致性
-        """
-        inconsistencies = []
-
-        spec_fields = {field.name: field for field in spec_model.fields}
-        impl_fields = {field.name: field for field in impl_model.fields}
-
-        # 检测缺失字段
-        missing_fields = set(spec_fields.keys()) - set(impl_fields.keys())
-        for field_name in missing_fields:
-            inconsistencies.append(MissingFieldInconsistency(
-                model=spec_model.name,
-                field=field_name,
-                specification=spec_fields[field_name]
-            ))
-
-        # 检测额外字段
-        extra_fields = set(impl_fields.keys()) - set(spec_fields.keys())
-        for field_name in extra_fields:
-            inconsistencies.append(ExtraFieldInconsistency(
-                model=impl_model.name,
-                field=field_name,
-                implementation=impl_fields[field_name]
-            ))
-
-        # 检测字段类型不匹配
-        common_fields = set(spec_fields.keys()) & set(impl_fields.keys())
-        for field_name in common_fields:
-            spec_field = spec_fields[field_name]
-            impl_field = impl_fields[field_name]
-
-            if not self.are_types_compatible(spec_field.type, impl_field.type):
-                inconsistencies.append(FieldTypeMismatchInconsistency(
-                    model=spec_model.name,
-                    field=field_name,
-                    spec_type=spec_field.type,
-                    impl_type=impl_field.type
-                ))
-
-        return inconsistencies
-```
-
-### 3. 版本不一致性检测算法
-
-#### 3.1 文档版本同步检测
-```python
-class DocumentVersionConsistencyDetector:
-    def __init__(self):
-        self.version_extractor = VersionExtractor()
-        self.dependency_analyzer = DocumentDependencyAnalyzer()
-
-    def detect_version_inconsistencies(self, documents: List[Document]) -> List[VersionInconsistency]:
-        """
-        检测文档间的版本不一致性
-        """
-        inconsistencies = []
-
-        # 1. 提取所有文档的版本信息
-        document_versions = self.extract_all_versions(documents)
-
-        # 2. 构建文档依赖关系图
-        dependency_graph = self.dependency_analyzer.build_dependency_graph(documents)
-
-        # 3. 检测版本不兼容
-        for doc_a, doc_b in dependency_graph.edges():
-            version_a = document_versions[doc_a.id]
-            version_b = document_versions[doc_b.id]
-
-            if not self.are_versions_compatible(version_a, version_b, dependency_graph.get_edge_data(doc_a, doc_b)):
-                inconsistency = VersionIncompatibilityInconsistency(
-                    source_document=doc_a,
-                    target_document=doc_b,
-                    source_version=version_a,
-                    target_version=version_b,
-                    dependency_type=dependency_graph.get_edge_data(doc_a, doc_b)['type']
-                )
-                inconsistencies.append(inconsistency)
-
-        return inconsistencies
-
-    def are_versions_compatible(self, version_a: Version, version_b: Version, dependency_info: Dict) -> bool:
-        """
-        检查两个版本是否兼容
-        """
-        dependency_type = dependency_info.get('type', 'reference')
-
-        if dependency_type == 'strict_dependency':
-            # 严格依赖要求精确版本匹配
-            return version_a == version_b
-        elif dependency_type == 'compatible_dependency':
-            # 兼容依赖允许向后兼容的版本
-            return version_a.is_compatible_with(version_b)
-        else:
-            # 一般引用允许较大的版本差异
-            return version_a.major == version_b.major
-```
-
-### 4. 智能冲突解决算法
-
-#### 4.1 冲突优先级评估
-```python
-class ConflictPriorityEvaluator:
-    def __init__(self):
-        self.impact_analyzer = ImpactAnalyzer()
-        self.complexity_evaluator = ComplexityEvaluator()
-
-    def evaluate_conflict_priority(self, conflict: Conflict) -> ConflictPriority:
-        """
-        评估冲突的解决优先级
-        """
-        # 1. 影响分析
-        business_impact = self.impact_analyzer.assess_business_impact(conflict)
-        technical_impact = self.impact_analyzer.assess_technical_impact(conflict)
-        user_impact = self.impact_analyzer.assess_user_impact(conflict)
-
-        # 2. 复杂度评估
-        resolution_complexity = self.complexity_evaluator.assess_resolution_complexity(conflict)
-
-        # 3. 风险评估
-        risk_level = self.assess_risk_level(conflict)
-
-        # 4. 计算综合优先级分数
-        priority_score = self.calculate_priority_score(
-            business_impact=business_impact,
-            technical_impact=technical_impact,
-            user_impact=user_impact,
-            resolution_complexity=resolution_complexity,
-            risk_level=risk_level
-        )
-
-        return ConflictPriority(
-            score=priority_score,
-            level=self.score_to_level(priority_score),
-            rationale=self.generate_priority_rationale(conflict, priority_score)
-        )
-
-    def calculate_priority_score(self, **factors) -> float:
-        """
-        基于多个因素计算优先级分数
-        """
-        weights = {
-            'business_impact': 0.3,
-            'technical_impact': 0.25,
-            'user_impact': 0.2,
-            'resolution_complexity': -0.15,  # 复杂度越高，优先级越低
-            'risk_level': 0.2
-        }
-
-        weighted_score = sum(
-            factors[factor] * weight
-            for factor, weight in weights.items()
-            if factor in factors
-        )
-
-        return min(max(weighted_score, 0.0), 1.0)  # 归一化到 [0, 1]
-```
-
-#### 4.2 自动解决方案生成
-```python
-class AutoResolutionGenerator:
-    def __init__(self):
-        self.resolution_strategies = ResolutionStrategyLibrary()
-        self.feasibility_checker = FeasibilityChecker()
-
-    def generate_resolution_options(self, conflict: Conflict) -> List[ResolutionOption]:
-        """
-        为冲突生成可能的解决方案
-        """
-        options = []
-
-        # 1. 基于冲突类型获取候选策略
-        candidate_strategies = self.resolution_strategies.get_strategies_for_conflict_type(conflict.type)
-
-        # 2. 为每个策略生成具体的解决方案
-        for strategy in candidate_strategies:
-            resolution_option = self.generate_resolution_from_strategy(conflict, strategy)
-
-            # 3. 评估可行性
-            feasibility = self.feasibility_checker.assess_feasibility(resolution_option)
-
-            if feasibility.is_feasible:
-                resolution_option.feasibility = feasibility
-                options.append(resolution_option)
-
-        # 4. 按预期效果排序
-        options.sort(key=lambda opt: opt.expected_effectiveness, reverse=True)
-
-        return options
-
-    def generate_resolution_from_strategy(self, conflict: Conflict, strategy: ResolutionStrategy) -> ResolutionOption:
-        """
-        基于策略生成具体的解决方案
-        """
-        if strategy.type == "merge_conflicting_requirements":
-            return self.generate_merge_solution(conflict, strategy)
-        elif strategy.type == "prioritize_and_exclude":
-            return self.generate_prioritization_solution(conflict, strategy)
-        elif strategy.type == "introduce_conditional_logic":
-            return self.generate_conditional_solution(conflict, strategy)
-        elif strategy.type == "refactor_architecture":
-            return self.generate_refactoring_solution(conflict, strategy)
-        else:
-            return self.generate_generic_solution(conflict, strategy)
-```
-
-## 📊 算法性能优化
-
-### 1. 并行处理优化
-```python
-class ParallelConflictDetector:
-    def __init__(self, max_workers: int = None):
-        self.max_workers = max_workers or cpu_count()
-        self.executor = ThreadPoolExecutor(max_workers=self.max_workers)
-
-    def detect_conflicts_parallel(self, documents: List[Document]) -> List[Conflict]:
-        """
-        并行执行冲突检测
-        """
-        # 1. 将文档分组以减少内存使用
-        document_groups = self.partition_documents(documents)
-
-        # 2. 并行检测每组内的冲突
-        intra_group_futures = [
-            self.executor.submit(self.detect_intra_group_conflicts, group)
-            for group in document_groups
-        ]
-
-        # 3. 并行检测组间冲突
-        inter_group_futures = [
-            self.executor.submit(self.detect_inter_group_conflicts, group_a, group_b)
-            for group_a, group_b in itertools.combinations(document_groups, 2)
-        ]
-
-        # 4. 收集结果
-        all_conflicts = []
-        for future in concurrent.futures.as_completed(intra_group_futures + inter_group_futures):
-            all_conflicts.extend(future.result())
-
-        return all_conflicts
-```
-
-### 2. 缓存和增量检测
-```python
-class IncrementalConflictDetector:
-    def __init__(self):
-        self.cache = ConflictDetectionCache()
-        self.change_tracker = DocumentChangeTracker()
-
-    def detect_conflicts_incremental(self,
-                                   documents: List[Document],
-                                   last_check_timestamp: datetime) -> List[Conflict]:
-        """
-        增量冲突检测
-        """
-        # 1. 识别自上次检查以来的变更
-        changed_documents = self.change_tracker.get_changed_documents(last_check_timestamp)
-
-        # 2. 从缓存中获取未变更文档的检测结果
-        cached_conflicts = self.cache.get_conflicts_for_unchanged_documents(
-            set(documents) - set(changed_documents)
-        )
-
-        # 3. 只对变更的文档及其依赖文档进行重新检测
-        affected_documents = self.get_affected_documents(changed_documents, documents)
-        new_conflicts = self.detect_conflicts_for_documents(affected_documents)
-
-        # 4. 更新缓存
-        self.cache.update_conflicts(affected_documents, new_conflicts)
-
-        return cached_conflicts + new_conflicts
-```
-
-## 🎯 质量保证
-
-### 算法测试框架
-```python
-class ConflictDetectionTestSuite:
-    def __init__(self):
-        self.test_data_generator = TestDataGenerator()
-        self.ground_truth_validator = GroundTruthValidator()
-
-    def run_comprehensive_tests(self):
-        """
-        运行全面的算法测试
-        """
-        test_results = TestResults()
-
-        # 1. 准确性测试
-        accuracy_results = self.test_detection_accuracy()
-        test_results.add_accuracy_results(accuracy_results)
-
-        # 2. 性能测试
-        performance_results = self.test_performance()
-        test_results.add_performance_results(performance_results)
-
-        # 3. 鲁棒性测试
-        robustness_results = self.test_robustness()
-        test_results.add_robustness_results(robustness_results)
-
-        # 4. 可扩展性测试
-        scalability_results = self.test_scalability()
-        test_results.add_scalability_results(scalability_results)
-
-        return test_results
-
-    def test_detection_accuracy(self) -> AccuracyResults:
-        """
-        测试检测精度
-        """
-        # 生成包含已知冲突的测试数据
-        test_datasets = self.test_data_generator.generate_conflict_datasets()
-
-        accuracy_metrics = []
-        for dataset in test_datasets:
-            detected_conflicts = self.detector.detect_conflicts(dataset.documents)
-
-            # 计算精确率、召回率和F1分数
-            precision = self.calculate_precision(detected_conflicts, dataset.ground_truth)
-            recall = self.calculate_recall(detected_conflicts, dataset.ground_truth)
-            f1_score = 2 * (precision * recall) / (precision + recall) if (precision + recall) > 0 else 0
-
-            accuracy_metrics.append(AccuracyMetric(
-                dataset_name=dataset.name,
-                precision=precision,
-                recall=recall,
-                f1_score=f1_score
-            ))
-
-        return AccuracyResults(accuracy_metrics)
-```
-
-## 📚 配置和扩展
-
-### 自定义冲突检测规则
-```yaml
-# .claude/conflict-detection-rules.yml
-conflict_detection_rules:
-  semantic_conflicts:
-    similarity_threshold: 0.7
-    contradiction_patterns:
-      - exclusive_actions: ["create", "delete"]
-      - temporal_conflicts: ["before", "after"]
-      - access_conflicts: ["public", "private"]
-
-  business_rule_conflicts:
-    max_combination_size: 5
-    logic_timeout: 30  # seconds
-    cyclic_dependency_detection: true
-
-  implementation_consistency:
-    api_signature_strictness: "strict"  # strict|moderate|relaxed
-    data_model_validation: true
-    version_compatibility_check: true
-
-  custom_patterns:
-    domain_specific_rules:
-      - name: "financial_compliance"
-        pattern: "audit_trail_required"
-        conflict_with: ["data_anonymization"]
-      - name: "security_requirements"
-        pattern: "encryption_required"
-        conflict_with: ["performance_optimization"]
-```
-
-### 插件扩展接口
-```python
-class ConflictDetectionPlugin:
-    """
-    冲突检测插件基类
-    """
-    def __init__(self, name: str):
-        self.name = name
-
-    def detect_conflicts(self, context: DetectionContext) -> List[Conflict]:
-        """
-        插件的冲突检测入口点
-        """
-        raise NotImplementedError
-
-    def get_supported_conflict_types(self) -> List[str]:
-        """
-        返回插件支持的冲突类型
-        """
-        raise NotImplementedError
-
-    def configure(self, config: Dict[str, Any]) -> None:
-        """
-        配置插件参数
-        """
-        pass
-
-# 示例：领域特定的冲突检测插件
-class FinancialComplianceConflictDetector(ConflictDetectionPlugin):
-    def __init__(self):
-        super().__init__("financial_compliance")
-
-    def detect_conflicts(self, context: DetectionContext) -> List[Conflict]:
-        conflicts = []
-
-        # 检测财务合规相关的冲突
-        audit_requirements = self.extract_audit_requirements(context.documents)
-        privacy_requirements = self.extract_privacy_requirements(context.documents)
-
-        for audit_req in audit_requirements:
-            for privacy_req in privacy_requirements:
-                if self.are_conflicting_compliance_requirements(audit_req, privacy_req):
-                    conflict = ComplianceConflict(
-                        type="audit_privacy_conflict",
-                        description=f"Audit requirement conflicts with privacy requirement",
-                        audit_requirement=audit_req,
-                        privacy_requirement=privacy_req,
-                        severity="high"
-                    )
-                    conflicts.append(conflict)
-
-        return conflicts
-```
-
----
-
-**总结**: 这套冲突检测算法为 cc-devflow 提供了企业级的一致性保证能力，通过多层次、多维度的智能检测，确保从需求到实现的全链路质量，支持大规模项目的高效开发和维护。