super-dev 2.0.0__py3-none-any.whl

super_dev/exceptions.py

@@ -0,0 +1,119 @@
+"""
+开发:Excellent(11964948@qq.com)
+功能:自定义异常类
+作用:提供结构化的异常处理体系
+创建时间:2025-01-29
+最后修改:2025-01-29
+"""
+
+from typing import Any
+
+
+class SuperDevError(Exception):
+    """Super Dev 基础异常类"""
+
+    def __init__(
+        self, message: str, code: str | None = None, details: dict[str, Any] | None = None
+    ):
+        self.message = message
+        self.code = code or self.__class__.__name__
+        self.details = details or {}
+        super().__init__(self.message)
+
+    def __str__(self):
+        if self.details:
+            return f"[{self.code}] {self.message} - {self.details}"
+        return f"[{self.code}] {self.message}"
+
+    def to_dict(self) -> dict[str, Any]:
+        """转换为字典格式"""
+        return {"error": self.code, "message": self.message, "details": self.details}
+
+
+# === 工作流异常 ===
+
+
+class WorkflowError(SuperDevError):
+    """工作流执行异常"""
+
+    pass
+
+
+class PhaseExecutionError(WorkflowError):
+    """阶段执行异常"""
+
+    def __init__(self, phase: str, message: str, details: dict[str, Any] | None = None):
+        super().__init__(message, "PHASE_EXECUTION_ERROR", details)
+        self.phase = phase
+
+
+class QualityGateError(WorkflowError):
+    """质量门禁检查失败"""
+
+    def __init__(self, score: float, threshold: float, details: dict[str, Any] | None = None):
+        message = f"质量分数 {score:.1f} 低于阈值 {threshold:.1f}"
+        super().__init__(message, "QUALITY_GATE_ERROR", details)
+        self.score = score
+        self.threshold = threshold
+
+
+# === 配置异常 ===
+
+
+class ConfigurationError(SuperDevError):
+    """配置异常"""
+
+    pass
+
+
+class ValidationError(SuperDevError):
+    """验证异常"""
+
+    def __init__(self, field: str, message: str, details: dict[str, Any] | None = None):
+        super().__init__(message, "VALIDATION_ERROR", details)
+        self.field = field
+
+
+# === 外部服务异常 ===
+
+
+class ExternalServiceError(SuperDevError):
+    """外部服务调用异常"""
+
+    def __init__(
+        self,
+        service: str,
+        message: str,
+        status_code: int | None = None,
+        details: dict[str, Any] | None = None,
+    ):
+        super().__init__(message, "EXTERNAL_SERVICE_ERROR", details)
+        self.service = service
+        self.status_code = status_code
+
+
+class OpenAIError(ExternalServiceError):
+    """OpenAI API调用异常"""
+
+    def __init__(self, message: str, details: dict[str, Any] | None = None):
+        super().__init__("openai", message, None, details)
+
+
+# === 文件系统异常 ===
+
+
+class FileSystemError(SuperDevError):
+    """文件系统操作异常"""
+
+    def __init__(self, path: str, message: str, details: dict[str, Any] | None = None):
+        super().__init__(message, "FILESYSTEM_ERROR", details)
+        self.path = path
+
+
+# === 输入输出异常 ===
+
+
+class IOError(SuperDevError):
+    """输入输出异常"""
+
+    pass

super_dev/experts/__init__.py

@@ -0,0 +1,19 @@
+"""专家建议服务导出。"""
+
+from .service import (
+    has_expert,
+    list_expert_advice_history,
+    list_experts,
+    read_expert_advice,
+    render_expert_advice_markdown,
+    save_expert_advice,
+)
+
+__all__ = [
+    "list_experts",
+    "has_expert",
+    "render_expert_advice_markdown",
+    "save_expert_advice",
+    "list_expert_advice_history",
+    "read_expert_advice",
+]

super_dev/experts/service.py

@@ -0,0 +1,161 @@
+"""专家建议服务。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+_EXPERT_META: list[dict[str, str]] = [
+    {"id": "PM", "name": "产品经理", "description": "需求分析、PRD编写"},
+    {"id": "ARCHITECT", "name": "架构师", "description": "系统设计、技术选型"},
+    {"id": "UI", "name": "UI设计师", "description": "视觉设计、设计规范"},
+    {"id": "UX", "name": "UX设计师", "description": "交互设计、用户体验"},
+    {"id": "SECURITY", "name": "安全专家", "description": "安全审查、漏洞检测"},
+    {"id": "CODE", "name": "开发专家", "description": "代码实现、最佳实践"},
+    {"id": "DBA", "name": "数据库专家", "description": "数据库设计、优化"},
+    {"id": "QA", "name": "测试专家", "description": "质量保证、测试策略"},
+    {"id": "DEVOPS", "name": "运维专家", "description": "部署、CI/CD"},
+    {"id": "RCA", "name": "故障侦探", "description": "根因分析、复盘改进"},
+]
+
+
+_EXPERT_PLAYBOOKS: dict[str, list[str]] = {
+    "PM": [
+        "明确目标用户、核心场景与北极星指标。",
+        "将需求拆分为 MUST/SHOULD/COULD，并定义验收标准。",
+        "补充边界条件与失败场景，避免需求歧义。",
+    ],
+    "ARCHITECT": [
+        "先定义系统边界与模块职责，再确定通信契约。",
+        "对关键链路做容量估算与扩展策略（缓存/队列/分片）。",
+        "沉淀可演进架构决策记录（ADR），降低后续返工风险。",
+    ],
+    "UI": [
+        "统一设计 token（颜色、间距、字体）并固化到组件层。",
+        "优先实现高频核心页面，保证视觉一致性和可读性。",
+        "在桌面与移动端分别验证层级、对比度和可触达性。",
+    ],
+    "UX": [
+        "梳理关键任务流并减少不必要步骤。",
+        "定义空状态、错误态与加载态，避免流程中断。",
+        "通过可观测埋点验证转化漏斗并持续迭代。",
+    ],
+    "SECURITY": [
+        "建立威胁模型并优先修复高危攻击面。",
+        "对认证、授权、输入校验和密钥管理做最小权限设计。",
+        "将 SAST/依赖漏洞扫描纳入 CI 阶段阻断高风险变更。",
+    ],
+    "CODE": [
+        "保持单一职责与清晰边界，减少隐式耦合。",
+        "核心逻辑补充单元测试和回归测试用例。",
+        "对异常处理、日志与可观测性做统一约束。",
+    ],
+    "DBA": [
+        "先建模实体关系，再补充索引和约束策略。",
+        "对高频查询设计覆盖索引并验证执行计划。",
+        "迁移脚本确保可回滚，发布时采用灰度策略。",
+    ],
+    "QA": [
+        "按风险优先级制定测试策略（冒烟/回归/性能）。",
+        "建立关键路径自动化测试并接入质量门禁。",
+        "输出缺陷分级和修复 SLA，形成闭环。",
+    ],
+    "DEVOPS": [
+        "统一环境配置与密钥管理，减少环境漂移。",
+        "构建 CI/CD 流水线并开启发布审计与回滚策略。",
+        "完善监控告警与容量基线，保障上线稳定性。",
+    ],
+    "RCA": [
+        "先确认用户影响范围，再聚焦首个异常时间点。",
+        "使用时间线 + 5 Whys 还原根因链路。",
+        "输出可执行改进项并设置验证指标防止复发。",
+    ],
+}
+
+
+def list_experts() -> list[dict[str, str]]:
+    return list(_EXPERT_META)
+
+
+def has_expert(expert_id: str) -> bool:
+    return expert_id in _EXPERT_PLAYBOOKS
+
+
+def render_expert_advice_markdown(expert_id: str, prompt: str = "") -> str:
+    suggestions = _EXPERT_PLAYBOOKS.get(expert_id, [])
+    lines = [
+        f"# {expert_id} 专家建议",
+        "",
+        f"**输入问题**: {prompt or '(未提供，输出通用建议)'}",
+        "",
+        "## 建议清单",
+        "",
+    ]
+    for idx, item in enumerate(suggestions, 1):
+        lines.append(f"{idx}. {item}")
+    lines.extend(
+        [
+            "",
+            "## 下一步执行",
+            "",
+            "1. 将建议映射到当前 Spec 或任务清单。",
+            "2. 标注优先级并安排负责人。",
+            "3. 完成后运行 `super-dev quality --type all` 复核。",
+            "",
+        ]
+    )
+    return "\n".join(lines)
+
+
+def save_expert_advice(project_dir: Path, expert_id: str, prompt: str = "") -> tuple[Path, str]:
+    project_dir = Path(project_dir).resolve()
+    output_dir = project_dir / "output"
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    content = render_expert_advice_markdown(expert_id=expert_id, prompt=prompt)
+    file_path = output_dir / f"expert-{expert_id.lower()}-advice.md"
+    file_path.write_text(content, encoding="utf-8")
+    return file_path, content
+
+
+def list_expert_advice_history(project_dir: Path, limit: int = 20) -> list[dict[str, str]]:
+    project_dir = Path(project_dir).resolve()
+    output_dir = project_dir / "output"
+    if not output_dir.exists():
+        return []
+
+    items: list[dict[str, str]] = []
+    files = sorted(
+        output_dir.glob("expert-*-advice.md"),
+        key=lambda p: p.stat().st_mtime,
+        reverse=True,
+    )
+    for file_path in files[:limit]:
+        name = file_path.name
+        expert_id = name.removeprefix("expert-").removesuffix("-advice.md").upper()
+        items.append(
+            {
+                "file_name": name,
+                "file_path": str(file_path),
+                "expert_id": expert_id,
+                "updated_at": datetime.fromtimestamp(file_path.stat().st_mtime).isoformat(),
+            }
+        )
+    return items
+
+
+def read_expert_advice(project_dir: Path, file_name: str) -> tuple[Path, str]:
+    project_dir = Path(project_dir).resolve()
+    output_dir = project_dir / "output"
+    if "/" in file_name or "\\" in file_name:
+        raise ValueError("invalid file name")
+    if not (file_name.startswith("expert-") and file_name.endswith("-advice.md")):
+        raise ValueError("invalid file name")
+
+    file_path = (output_dir / file_name).resolve()
+    if not file_path.exists():
+        raise FileNotFoundError(file_name)
+    if output_dir.resolve() not in file_path.parents:
+        raise ValueError("invalid file path")
+
+    return file_path, file_path.read_text(encoding="utf-8")

super_dev/integrations/__init__.py

@@ -0,0 +1,7 @@
+"""
+多平台集成模块
+"""
+
+from .manager import IntegrationManager
+
+__all__ = ["IntegrationManager"]

super_dev/integrations/manager.py

@@ -0,0 +1,264 @@
+"""
+多平台 AI Coding 工具集成管理器
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class IntegrationTarget:
+    name: str
+    description: str
+    files: list[str]
+
+
+class IntegrationManager:
+    """为不同 AI Coding 平台生成集成配置"""
+
+    TARGETS: dict[str, IntegrationTarget] = {
+        "claude-code": IntegrationTarget(
+            name="claude-code",
+            description="Claude Code CLI 深度集成",
+            files=[".claude/CLAUDE.md"],
+        ),
+        "codex-cli": IntegrationTarget(
+            name="codex-cli",
+            description="Codex CLI 项目上下文注入",
+            files=[".codex/AGENTS.md"],
+        ),
+        "opencode": IntegrationTarget(
+            name="opencode",
+            description="OpenCode CLI 项目规则注入",
+            files=[".opencode/AGENTS.md"],
+        ),
+        "cursor": IntegrationTarget(
+            name="cursor",
+            description="Cursor IDE 规则注入",
+            files=[".cursorrules"],
+        ),
+        "qoder": IntegrationTarget(
+            name="qoder",
+            description="Qoder IDE 规则注入",
+            files=[".qoder/rules.md"],
+        ),
+        "trae": IntegrationTarget(
+            name="trae",
+            description="Trae IDE 规则注入",
+            files=[".trae/rules.md"],
+        ),
+        "codebuddy": IntegrationTarget(
+            name="codebuddy",
+            description="CodeBuddy IDE 规则注入",
+            files=[".codebuddy/rules.md"],
+        ),
+        "antigravity": IntegrationTarget(
+            name="antigravity",
+            description="Antigravity IDE 工作流集成（.agents/workflows/）",
+            files=[".agents/workflows/super-dev.md"],
+        ),
+    }
+
+    def __init__(self, project_dir: Path):
+        self.project_dir = Path(project_dir).resolve()
+        self.templates_dir = self.project_dir / "templates"
+
+    def list_targets(self) -> list[IntegrationTarget]:
+        return list(self.TARGETS.values())
+
+    def setup(self, target: str, force: bool = False) -> list[Path]:
+        if target not in self.TARGETS:
+            raise ValueError(f"Unsupported target: {target}")
+
+        written_files: list[Path] = []
+        integration = self.TARGETS[target]
+        for relative in integration.files:
+            file_path = self.project_dir / relative
+            if file_path.exists() and not force:
+                continue
+            file_path.parent.mkdir(parents=True, exist_ok=True)
+            content = self._build_content(target=target)
+            file_path.write_text(content, encoding="utf-8")
+            written_files.append(file_path)
+
+        return written_files
+
+    def setup_all(self, force: bool = False) -> dict[str, list[Path]]:
+        result: dict[str, list[Path]] = {}
+        for target in self.TARGETS:
+            result[target] = self.setup(target=target, force=force)
+        return result
+
+    def _build_content(self, target: str) -> str:
+        if target == "cursor":
+            cursor_template = self.templates_dir / ".cursorrules.template"
+            if cursor_template.exists():
+                body = cursor_template.read_text(encoding="utf-8")
+                return (
+                    f"{body}\n\n"
+                    "# Super Dev Pipeline Rules\n"
+                    "- Always read output/*-prd.md, output/*-architecture.md, output/*-uiux.md first.\n"
+                    "- Execute frontend-first delivery before backend/database tasks.\n"
+                    "- Meet the active quality gate threshold before release.\n"
+                )
+
+        if target == "antigravity":
+            return self._antigravity_workflow_rules()
+
+        if target in {"qoder", "trae", "codebuddy"}:
+            return self._generic_ide_rules(target)
+
+        if target in {"codex-cli", "opencode"}:
+            return self._generic_cli_rules(target)
+
+        if target == "claude-code":
+            return self._claude_rules()
+
+        return self._generic_cli_rules(target)
+
+    def _generic_cli_rules(self, target: str) -> str:
+        return (
+            f"# Super Dev Integration for {target}\n\n"
+            "Use Super Dev generated artifacts as source of truth.\n\n"
+            "## Required Context\n"
+            "- output/*-prd.md\n"
+            "- output/*-architecture.md\n"
+            "- output/*-uiux.md\n"
+            "- output/*-execution-plan.md\n"
+            "- .super-dev/changes/*/tasks.md\n\n"
+            "## Execution Order\n"
+            "1. Implement frontend modules first\n"
+            "2. Implement backend APIs and data layer\n"
+            "3. Run tests and quality gate\n"
+            "4. Prepare CI/CD and release\n"
+        )
+
+    def _generic_ide_rules(self, target: str) -> str:
+        return (
+            f"# Super Dev IDE Rules ({target})\n\n"
+            "## Working Agreement\n"
+            "- Read generated documents before coding.\n"
+            "- Respect Spec tasks sequence.\n"
+            "- Keep architecture and UIUX consistency.\n\n"
+            "## Delivery Criteria\n"
+            "- Frontend can be demonstrated early.\n"
+            "- Backend and migration scripts match specs.\n"
+            "- Security/performance checks are resolved.\n"
+            "- Quality gate threshold is met for the current scenario.\n"
+        )
+
+    def _claude_rules(self) -> str:
+        return (
+            "# Super Dev Claude Code Integration\n\n"
+            "This project uses a pipeline-driven development model.\n\n"
+            "## Before coding\n"
+            "1. Read output/*-prd.md\n"
+            "2. Read output/*-architecture.md\n"
+            "3. Read output/*-uiux.md\n"
+            "4. Read output/*-execution-plan.md\n"
+            "5. Follow .super-dev/changes/*/tasks.md\n\n"
+            "## Output Quality\n"
+            "- Keep security/performance constraints from red-team report.\n"
+            "- Ensure quality gate threshold is met before merge.\n"
+        )
+
+    def _antigravity_workflow_rules(self) -> str:
+        """
+        生成 Antigravity IDE 专属工作流配置。
+        文件写入 .agents/workflows/super-dev.md，
+        格式遵循 Antigravity Skill YAML frontmatter + markdown 规范。
+        """
+        return """\
+---
+description: Super Dev 流水线式 AI Coding 辅助工作流 - 从需求到交付的 12 阶段自动化流程
+---
+
+# Super Dev Pipeline Workflow
+
+## 角色定义
+
+本工作流激活 10 位专家角色自动协作：
+
+| 专家 | 职责 |
+|:---|:---|
+| PM | 需求分析、PRD 生成、用户故事 |
+| ARCHITECT | 架构设计、技术选型、API 契约 |
+| UI/UX | 设计系统、交互规范、原型设计 |
+| SECURITY | 红队审查、OWASP 检测、威胁建模 |
+| CODE | 代码实现、最佳实践、代码审查 |
+| DBA | 数据库设计、迁移脚本、索引优化 |
+| QA | 测试策略、质量门禁、覆盖率要求 |
+| DEVOPS | CI/CD 配置、容器化、监控告警 |
+| RCA | 根因分析、故障复盘、风险识别 |
+
+## 工作流步骤
+
+### 前置：读取必备文档
+
+在写任何一行代码前，必须先读取：
+
+1. `output/*-prd.md` — 产品需求和验收标准
+2. `output/*-architecture.md` — 技术栈和 API 设计
+3. `output/*-uiux.md` — 设计系统和组件规范
+4. `output/*-execution-plan.md` — 阶段任务路线图
+5. `.super-dev/changes/*/tasks.md` — 具体实现任务清单
+
+### 第 0 阶段：需求增强
+
+```bash
+super-dev pipeline "你的需求描述" --platform web --frontend react --backend node
+```
+
+- 解析自然语言需求，注入领域知识库
+- 联网检索补充市场和技术背景
+- 输出结构化需求蓝图
+
+### 第 1 阶段：专业文档生成
+
+自动生成：
+- `output/*-prd.md` — PRD（产品需求文档）
+- `output/*-architecture.md` — 架构设计文档
+- `output/*-uiux.md` — UI/UX 设计文档
+
+### 第 2-4 阶段：骨架构建
+
+- 前端可演示骨架（前端先行原则）
+- Spec 规范（OpenSpec 风格）
+- 前后端实现骨架 + API 契约
+
+### 第 5-6 阶段：质量保障
+
+- 红队审查（安全 + 性能 + 架构）
+- 质量门禁（统一标准：80+）
+
+### 第 7-8 阶段：交付准备
+
+- 代码审查指南
+- AI 提示词生成（直接传给 AI 开始开发）
+
+### 第 9-11 阶段：部署与交付
+
+- CI/CD 配置（GitHub/GitLab/Jenkins/Azure/Bitbucket）
+- 数据库迁移脚本（Prisma/TypeORM/SQLAlchemy 等 6 种 ORM）
+- 项目交付包（manifest + report + zip）
+
+## 执行规则
+
+- **前端先行**：先完成可演示前端，再实现后端 API
+- **禁止 emoji 图标**：使用 Lucide/Heroicons/Tabler Icons
+- **参数化查询**：禁止字符串拼接 SQL
+- **任务跟踪**：每完成一项在 tasks.md 标记 `[x]`
+- **质量门禁**：交付前运行 `super-dev quality --type all`
+
+## 常用命令
+
+```bash
+super-dev pipeline "需求"      # 完整 12 阶段流水线
+super-dev create "需求"        # 生成文档 + Spec
+super-dev quality --type all   # 质量检查
+super-dev expert SECURITY "需求"  # 单专家调用
+super-dev skill install super-dev --target antigravity  # 安装 Skill
+```
+"""

super_dev/orchestrator/__init__.py

@@ -0,0 +1,12 @@
+"""
+Super Dev Orchestrator Module
+"""
+
+from .engine import Phase, PhaseResult, WorkflowContext, WorkflowEngine
+
+__all__ = [
+    "WorkflowEngine",
+    "Phase",
+    "PhaseResult",
+    "WorkflowContext"
+]