🌟 Super Gemini Framework

为 Google Gemini AI 打造的元编程配置框架
AI-Enhanced Development Framework for Google Gemini

快速开始 • 核心特性 • 核心组件 • 中文特性 • 文档 • 构建难题

---

📖 项目简介

Super Gemini Framework 是一个元编程配置框架，将 Google Gemini AI 转换为结构化的开发平台。通过行为指令注入和组件编排，提供系统化的工作流自动化，配备强大的工具和智能代理。

┌─────────────────────────────────────────────────────────────────┐
│                    Super Gemini Framework                        │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │ 🤖 代理  │  │ ⚡ 命令  │  │ 🎯 模式  │  │ 🔌 MCP  │            │
│  │  16+    │  │  36+    │  │   7+    │  │   8+    │            │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘            │
│                         ↓                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              🎨 Gemini AI 增强开发平台                    │   │
│  │    • 行为指令注入  • 组件编排  • 工作流自动化              │   │
│  └─────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

✨ 核心特性

🤖 16+ 专业化 AI 代理 涵盖架构、开发、测试、文档等领域的专业代理 ⚡ 36+ 斜杠命令 覆盖完整开发生命周期的工作流命令 🎯 7+ 行为模式 适应不同工作上下文的智能切换模式 🔌 8+ MCP 服务器集成 扩展功能，提升效率 30-50%

🇨🇳 完整中文支持 中文优先，为中国开发者优化 🎨 个人品牌定制 集成 AimerFeng 的开发风格和工作流 📝 博客集成 一键导出项目内容到个人博客 🧪 属性测试驱动 33 个属性测试确保代码正确性

🚀 快速开始

📦 安装

使用 pipx（推荐）

pipx install supergemini

使用 pip

pip install supergemini

从源码安装

git clone https://github.com/aimerfeng/gemini-.git
cd gemini-
pip install -e .

🎮 基本使用

# 1️⃣ 安装命令到 Gemini 环境
supergemini install

# 2️⃣ 查看可用命令
supergemini install --list

# 3️⃣ 安装 MCP 服务器
supergemini mcp --servers tavily context7 sequential-thinking

# 4️⃣ 健康检查
supergemini doctor

# 5️⃣ 在 Gemini 中使用
/sg:research "深度学习最新进展"
/sg:implement "实现一个 REST API"
/sg:test "编写单元测试"

📚 核心组件

🤖 专业化代理

┌────────────────────────────────────────────────────────────────┐
│                      专业化 AI 代理体系                          │
├────────────────────────────────────────────────────────────────┤
│                                                                 │
│  🏗️ 架构类                    🔧 开发类                         │
│  ├── backend-architect        ├── python-expert                │
│  ├── frontend-architect       └── refactoring-expert           │
│  ├── system-architect                                          │
│  └── devops-architect         📊 分析类                         │
│                               ├── requirements-analyst          │
│  ✅ 质量类                    └── root-cause-analyst           │
│  ├── quality-engineer                                          │
│  ├── security-engineer        📝 文档类                         │
│  └── performance-engineer     └── technical-writer             │
│                                                                 │
│  🔬 研究类                    🎓 教育类                         │
│  └── deep-research-agent      ├── learning-guide               │
│                               └── socratic-mentor              │
│  📋 管理类                                                      │
│  └── pm-agent                                                   │
│                                                                 │
└────────────────────────────────────────────────────────────────┘

⚡ 斜杠命令

类别	命令	描述
📐 规划与设计	/sg:brainstorm	协作式头脑风暴
	/sg:design	系统设计
	/sg:estimate	工作量估算
	/sg:spec-panel	规格说明面板
💻 开发	/sg:implement	功能实现
	/sg:build	构建项目
	/sg:improve	代码改进
	/sg:cleanup	代码清理
	/sg:explain	代码解释
🧪 测试与质量	/sg:test	测试生成
	/sg:analyze	代码分析
	/sg:troubleshoot	问题排查
	/sg:reflect	反思总结
📖 文档	/sg:document	文档生成
	/sg:help	帮助信息
🔀 版本控制	/sg:git	Git 操作
📋 项目管理	/sg:pm	项目管理
	/sg:task	任务管理
	/sg:workflow	工作流管理
🔍 研究与分析	/sg:research	深度研究
	/sg:business-panel	商业分析
🛠️ 实用工具	/sg:agent	代理管理
	/sg:load / /sg:save	会话管理
	/sg:sg	显示所有命令

🎯 行为模式

┌─────────────────────────────────────────────────────────────┐
│                       行为模式系统                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  💡 MODE_Brainstorming      协作式发现和创意生成              │
│  📊 MODE_Business_Panel     多专家战略分析                    │
│  🔬 MODE_DeepResearch       自主网络研究（多跳推理）          │
│  🎯 MODE_Orchestration      高效工具协调                      │
│  💰 MODE_Token_Efficiency   30-50% 上下文节省                 │
│  📋 MODE_Task_Management    系统化任务组织                    │
│  🧠 MODE_Introspection      元认知分析                        │
│                                                              │
└─────────────────────────────────────────────────────────────┘

🔌 MCP 服务器

服务器	功能	用途
🔍 Tavily	网络搜索	深度研究
📚 Context7	文档查询	官方文档
🧠 Sequential-Thinking	多步推理	复杂问题
💾 Serena	会话持久化	内存管理
🎭 Playwright	浏览器自动化	跨浏览器测试
✨ Magic	UI 生成	组件创建
🔧 Morphllm	代码修改	上下文感知
🔬 Chrome DevTools	性能分析	调试优化

🇨🇳 中文特性

Super Gemini Framework 为中国开发者提供完整的中文支持：

# ✅ 中文命令别名
/研究 "人工智能最新进展"
/实现 "用户认证系统"
/测试 "API 端点"
/文档 "项目架构"

# ✅ 中文 CLI 界面
supergemini --help  # 显示中英双语帮助

# ✅ 中文错误消息
# 所有错误和日志都支持中文显示

🔧 构建难题与解决方案

在构建 Super Gemini Framework 过程中，我们遇到并解决了以下技术难题：

难题 1: Hypothesis 属性测试与 pytest fixtures 冲突

问题描述: 使用 @given() 装饰器的属性测试与 pytest 的 tmp_path fixture 结合时，会触发 FailedHealthCheck 错误。

# ❌ 错误示例
@given(force=st.booleans())
def test_property(tmp_path, force):  # tmp_path 是 function-scoped fixture
    mock_home = tmp_path / "home"
    mock_home.mkdir()  # 第二次运行时会失败！

解决方案: 添加 suppress_health_check 并使用 exist_ok=True：

# ✅ 正确示例
from hypothesis import given, settings, HealthCheck

@settings(max_examples=100, suppress_health_check=[HealthCheck.function_scoped_fixture])
@given(force=st.booleans())
def test_property(tmp_path, force):
    mock_home = tmp_path / "home"
    mock_home.mkdir(exist_ok=True)  # 允许目录已存在
    
    # 清理之前的状态
    if (mock_home / ".gemini").exists():
        shutil.rmtree(mock_home / ".gemini")

难题 2: Hypothesis 测试超时问题

问题描述: 某些属性测试因为 I/O 操作导致超过默认 200ms 的 deadline。

# ❌ 错误
hypothesis.errors.DeadlineExceeded: Test took 257.90ms, which exceeds the deadline of 200.00ms

解决方案: 设置 deadline=None 禁用超时检查：

# ✅ 正确示例
@settings(max_examples=100, deadline=None)
@given(session_id=st.text(min_size=1, max_size=50))
def test_property_memory_persistence(session_id):
    # 涉及文件 I/O 的测试
    pass

难题 3: pytest-cov 配置冲突

问题描述: pyproject.toml 中的 pytest addopts 包含 coverage 选项，但 pytest-cov 未安装时会报错。

# ❌ 问题配置
[tool.pytest.ini_options]
addopts = [
    "--cov=supergemini",
    "--cov-report=term-missing",
]

解决方案: 运行测试时使用 --override-ini 覆盖配置：

# ✅ 正确命令
python -m pytest tests/unit/ -v --tb=short --override-ini="addopts="

难题 4: Windows 路径与 monkeypatch 问题

问题描述: 在 Windows 上使用 monkeypatch.setattr(Path, "home", ...) 时，路径处理不一致。

# ❌ 问题代码
monkeypatch.setattr(Path, "home", lambda: mock_home)
# Windows 上可能返回 WindowsPath 而非预期的 PosixPath

解决方案: 同时设置环境变量和 monkeypatch：

# ✅ 正确示例
mock_home = tmp_path / "home"
mock_home.mkdir(exist_ok=True)

# 同时设置两种方式确保兼容性
monkeypatch.setenv("HOME", str(mock_home))
monkeypatch.setattr(Path, "home", lambda: mock_home)

难题 5: Rich 库依赖缺失

问题描述: 测试时 rich 模块未安装导致导入失败。

# ❌ 错误
ModuleNotFoundError: No module named 'rich'

解决方案: 使用 conda 安装（绕过 pip SSL 问题）：

# ✅ 正确命令
conda install -c conda-forge rich -y

难题 6: 属性测试中的状态隔离

问题描述: Hypothesis 会多次运行同一测试，但 tmp_path fixture 不会重置。

解决方案: 在每次测试开始时清理状态：

# ✅ 正确示例
@settings(suppress_health_check=[HealthCheck.function_scoped_fixture])
@given(force=st.booleans())
def test_property(tmp_path, force):
    target_dir = tmp_path / "commands"
    
    # 清理之前的状态
    if target_dir.exists():
        shutil.rmtree(target_dir)
    
    # 现在可以安全地运行测试
    success, message = install_commands(target_dir, force=force)

📊 项目统计

┌─────────────────────────────────────────────────────────────┐
│                      项目统计数据                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  📁 代码行数          10,000+ LOC                            │
│  🧪 测试覆盖率        >70%                                   │
│  ✅ 属性测试          33 个全部通过                          │
│  🐍 Python 版本       3.10, 3.11, 3.12                       │
│  📦 依赖项            最小化，仅核心库                        │
│  📖 文档页面          50+ 页                                 │
│  🤖 AI 代理           16+                                    │
│  ⚡ 斜杠命令          36+                                    │
│  🎯 行为模式          7+                                     │
│  🔌 MCP 服务器        8+                                     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

🧪 测试

# 运行所有测试
pytest tests/unit/ -v --override-ini="addopts="

# 运行特定测试文件
pytest tests/unit/test_session_property.py -v

# 查看详细输出
pytest tests/unit/ -v --tb=long

🤝 贡献

欢迎贡献！请查看 贡献指南 了解详情。

# 开发设置
git clone https://github.com/aimerfeng/gemini-.git
cd gemini-
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"
pytest

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

👤 作者

AimerFeng
GitHub • Blog

🙏 致谢

本项目受 SuperClaude Framework 启发，感谢原作者的开源贡献。

---

如果这个项目对你有帮助，请给个 ⭐️ Star！
Made with ❤️ by AimerFeng