使用说明
PatternSphere
备注：韩语版本可用： README_KR.md
软件设计模式的统一知识库
版本1.0.0 -生产就绪
概述
PatternSphere是一个强大的命令行工具，用于搜索、浏览和探索软件设计模式。第一阶段的重点是 面向对象的再造模式（OORP） 共有8个类别的61种综合模式。
主要特点
- 快速关键字搜索：相关结果的加权现场评分（<10ms）
- 类别浏览：按8个OORP类别探索模式
- 标签筛选：使用OR逻辑按多个标签过滤
- 丰富的终端用户界面：漂亮的表格和格式化的输出
- 图案细节：完整的模式信息（问题、解决方案、后果）
- 相关模式：发现模式之间的联系
- 61 OORP模式：全面介绍面向对象的再造模式
- MCP集成：在Claude Code中用作MCP服务器，用于AI辅助模式发现
快速开始
安装
# Clone or extract the repository
cd PatternSphere
# Install dependencies
pip install -r requirements.txt
# Install the package
pip install -e .
验证安装
patternsphere --version
# Output: PatternSphere v1.0.0
第一个命令
# Get system information
patternsphere info
# List all categories
patternsphere categories
# Search for patterns
patternsphere search refactoring
# View pattern details
patternsphere view "Read all the Code in One Hour"
# List patterns in a category
patternsphere list --category "First Contact"
MCP集成（克劳德）
PatternSphere可以用作Claude Desktop和Claude Code中的MCP（模型上下文协议）服务器：
# 1. Complete the installation above
# 2. Configure Claude Desktop or Claude Code
# 3. Use natural language in Claude:
# "Find patterns for refactoring legacy code"
# "Show me the 'Read all the Code in One Hour' pattern"
# "Recommend patterns for dealing with a God Class"
📖 安装说明：
- 克劳德桌面： Claude桌面设置指南
- 克劳德代码（VSCode）： MCP快速入门 (韩文)
用法
搜索模式
使用加权评分在所有模式字段中搜索：
# Simple search
patternsphere search refactoring
# Search with category filter
patternsphere search "code quality" --category "First Contact"
# Search with tag filter
patternsphere search testing --tags "quality,testing"
# Limit results
patternsphere search pattern --limit 10
# Hide relevance scores
patternsphere search code --no-scores
搜索算法：
- 加权字段评分（名称：5.0，标签：4.0，意图：3.0等）
- 精确单词匹配：1.0分，部分匹配：0.5分
- 按相关性排序的结果
列出模式
通过过滤和排序浏览所有模式：
# List all patterns
patternsphere list
# List by category
patternsphere list --category "First Contact"
# Sort by category
patternsphere list --sort category
查看图案详细信息
显示完整的图案信息：
# View by name
patternsphere view "Read all the Code in One Hour"
# View by ID
patternsphere view OORP-001
显示：
- 元数据（ID、类别、标签、源）
- 意图
- 问题
- 解决方案
- 后果
- 相关模式
浏览分类
探索可用类别：
patternsphere categories
显示所有8个具有图案计数的OORP类别：
- 详细模型捕获（10种模式）
- 第一次接触（6种模式）
- 初步理解（6种模式）
- 迁移策略（8种模式）
- 重新分配责任（10种模式）
- 设置方向（10种图案）
- 测试：你的人寿保险！（6种图案）
- 将条件转换为多态性（5种模式）
系统信息
显示应用程序信息和统计数据：
patternsphere info
显示：
- 版本信息
- 总模式和类别
- 加载性能
- 数据源信息
图案类别
1.首次接触（6种模式）
对陌生代码库的初步探索。
关键模式：
- 在一小时内阅读所有代码
- 浏览文档
- 演示期间的面试
- 进行模拟安装
- 与维护人员聊天
- 在一小时内阅读所有代码
使用时间：
- 开始新项目的工作
- 加入传统系统
- 进行初步评估
2.初步理解（6种模式）
加深对系统结构的理解。
关键模式：
- 分析持久数据
- 研究例外实体
- 重构以理解
- 推测业务规则
- 查看合同
- 将业务规则记录为测试
使用时间：
- 需要了解数据模型
- 调查系统架构
- 规划重构工作
3.详细模型捕获（10种模式）
捕获系统的详细模型。
关键模式：
- 从过去学习
- 将代码可视化为点图
- 推测设计
- 演示期间的面试
- 在一小时内阅读所有代码
使用时间：
- 创建文档
- 逆向工程架构
- 规划重大变革
4.重新分配责任（10种模式）
改进类和模块设计。
关键模式：
- 拆分神类
- 将行为移到数据附近
- 提取方法对象
- 删除导航代码
- 封装字段
使用时间：
- 重构大型类
- 提高凝聚力
- 异径接头
5.将条件转换为多态性（5种模式）
用多态设计替换条件句。
关键模式：
- 用多态性替换条件
- 引入Null对象
- 排除州因素
- 制定战略
使用时间：
- 简化复杂的条件
- 实施战略模式
- 提高可扩展性
6.移徙战略（8种模式）
迁移遗留系统的策略。
关键模式：
- 始终有一个运行版本
- 逐步迁移系统
- 展示正确的界面
- 区分公共界面和已发布界面
- 弃用过时的接口
使用时间：
- 规划系统迁移
- 对遗留代码进行现代化改造
- 管理技术债务
7.设置方向（10种图案）
再造项目的战略模式。
关键模式：
- 任命一名领航员
- 建立信心
- 最有价值第一
- 先修复损坏的部分
- 如果它没有坏，就不要修理它
使用时间：
- 开始再造项目
- 管理利益相关者
- 规划重点
8.测试：你的人寿保险！（6种图案）
遗留系统的测试策略。
关键模式：
- 编写测试以实现进化
- 编写测试以理解
- 测试模糊特征
- 重新测试持续存在的问题
- 测试接口，而不是实现
使用时间：
- 使用未经测试的代码
- 增加测试覆盖率
- 实现安全重构
常见工作流
1.探索新的代码库
# Start with First Contact patterns
patternsphere list --category "First Contact"
# View key patterns
patternsphere view "Read all the Code in One Hour"
patternsphere view "Interview During Demo"
# Search for specific techniques
patternsphere search documentation --category "First Contact"
2.规划重构
# Find refactoring patterns
patternsphere search refactoring --limit 15
# Explore responsibility redistribution
patternsphere list --category "Redistribute Responsibilities"
# View specific refactoring patterns
patternsphere view "Split Up God Class"
patternsphere view "Move Behavior Close to Data"
3.向旧代码添加测试
# Find testing patterns
patternsphere search test --tags "testing,quality"
# View testing category
patternsphere list --category "Tests: Your Life Insurance!"
# Learn specific techniques
patternsphere view "Write Tests to Enable Evolution"
patternsphere view "Test Fuzzy Features"
4.模式发现
# Browse by category
patternsphere categories
# List all patterns sorted by category
patternsphere list --sort category
# Search broad topics
patternsphere search "code quality"
# Explore related patterns (shown in view output)
建筑
组件概览
PatternSphere
├── Models (Pattern data model with Pydantic validation)
├── Repository (Pattern storage with O(1) lookups)
├── Search Engine (Weighted keyword search)
├── Loaders (OORP pattern loader)
├── Storage (File-based persistence with atomic writes)
├── CLI (Command-line interface)
│ ├── Commands (5 main commands)
│ ├── Formatters (Output formatting)
│ └── AppContext (Dependency injection)
└── Config (Settings and configuration)
设计原则
PatternSphere的构建如下 SOLID原则 干净的建筑：
单一责任
- 每个组件都有一个明确的目的
- 模式模型：仅数据结构和验证
- 存储库：集合管理和查询
- 存储：仅文件I/O操作
- 格式化程序仅格式化，搜索仅搜索
打开/关闭
- 可扩展到新的模式源（PDF、web等）
- 通过装饰器轻松添加新命令
- IStorage接口允许新的存储后端
- IPatternRepository允许替代实现
里氏替换
- 存储库接口支持多种实现
- 任何IStorage实现都可以互换使用
- 未来可能的存储后端（SQLite、PostgreSQL）
接口隔离
- 聚焦接口（IPatternpository、IStorage）
- 没有臃肿的接口
- IStorage具有最小、专注的界面
依赖倒置
- 组件依赖于抽象
- AppContext管理所有依赖关系
- 存储库依赖于IStorage抽象
- 允许使用模拟存储进行测试
关键设计模式
存储库模式
- 抽象模式数据访问
IPatternRepository接口InMemoryPatternRepository实施- 具有多个索引的集合式界面
单例模式
AppContext管理应用程序状态- 跨CLI会话的单个实例
策略模式
- 加权搜索评分算法
- 可扩展到新的评分策略
依赖注入
- 组件通过构造函数接收依赖关系
- 可测试和可维护
- 无全局状态
演出
PatternSphere针对速度进行了优化：
| 操作 | 性能 | 要求 | 结果 |
|---|---|---|---|
| 模式加载 | ~2ms | <500ms | 250倍快✅ |
| 搜索（平均） | <10ms | <100ms | 快10倍✅ |
| CLI启动 | ~650ms | <1s | 快35%✅ |
| 内存使用率 | <100KB | 最低 | 优秀✅ |
所有要求超出10-250x！
测试
全面的测试套件可确保可靠性：
# Run all tests
pytest
# Run with coverage
pytest --cov=patternsphere --cov-report=html
# Run specific test types
pytest tests/unit/
pytest tests/integration/
pytest tests/performance/
测试统计：
- 总测试: 248
- 测试覆盖率: 91%
- 所有测试：通过✅
- 执行时间：约1.6秒
测试类别：
- 单元测试（178）-模型、存储库、存储、搜索、加载器、CLI
- 集成测试（55）-搜索流、CLI命令、端到端工作流
- 性能测试（15）-加载、搜索、可扩展性
覆盖范围细分：
- 图案模型：100%
- 存储库：97%
- 搜索引擎：97%
- 装载机：92%
- CLI组件：86-100%
- 总体：91%
配置
环境变量
通过环境变量配置PatternSphere：
export PATTERNSPHERE_DATA_DIR=/custom/data/path
export PATTERNSPHERE_DEFAULT_LIMIT=50
export PATTERNSPHERE_TERMINAL_WIDTH=100
可用变量：
PATTERNSPHERE_DATA_DIR：数据目录路径PATTERNSPHERE_DEFAULT_LIMIT：默认搜索结果限制PATTERNSPHERE_TERMINAL_WIDTH：用于格式化的端子宽度
配置文件
创建 .env 项目根目录中的文件：
PATTERNSPHERE_DATA_DIR=data
PATTERNSPHERE_DEFAULT_LIMIT=20
PATTERNSPHERE_TERMINAL_WIDTH=80
项目结构
PatternSphere/
├── patternsphere/ # Main package
│ ├── models/ # Pattern data models (Pydantic)
│ ├── repository/ # Repository pattern implementation
│ ├── storage/ # File storage
│ ├── search/ # Search engine
│ ├── loaders/ # Pattern loaders
│ ├── config/ # Configuration
│ ├── cli/ # CLI interface
│ └── mcp/ # MCP server implementation
├── data/ # Pattern data
│ └── sources/oorp/ # OORP patterns (61 patterns)
├── tests/ # Test suite (248 tests)
│ ├── unit/ # Unit tests (178)
│ ├── integration/ # Integration tests (55)
│ └── performance/ # Performance tests (15)
├── docs/ # Documentation
│ ├── mcp/ # MCP server documentation
│ │ ├── MCP_QUICKSTART.md
│ │ └── MCP_TEST_GUIDE.md
│ ├── development/ # Development guides
│ │ ├── CLAUDE.md
│ │ └── PATTERN_ANALYSIS.md
│ ├── CLI_Reference.md
│ ├── PRD.md
│ └── Phase1_Product_Specification.md
├── config/ # Configuration files
│ └── examples/ # Example configurations
├── scripts/ # Utility scripts
│ ├── test_mcp_server.py
│ ├── demos/ # Demo scripts
│ └── utils/ # Utility scripts
├── README.md # This file
├── CHANGELOG.md # Version history
├── requirements.txt # Dependencies
├── setup.py # Package setup
└── run_mcp_server.py # MCP server entry point
文档
用户文档
- CLI 参考：完整的命令参考和示例
- Claude桌面设置：Claude Desktop的MCP服务器设置
- MCP快速入门：克劳德代码（VSCode）的MCP服务器设置(韩文)
- MCP测试指南：MCP服务器测试和故障排除(韩文)
- 文件结构：项目组织和文件参考(韩文)
开发文档
- 开发指南：AI配对编程和转换模式(韩文)
- 模式分析：项目模式分析和建议(韩文)
- 组织概述：项目重组详情(韩文)
- 更新日志：版本历史和更改
- 产品需求文档：产品要求（包括第2阶段PDF支持）
- 产品规格：第1阶段规范
- Sprint报告：SPRINT1_COMPLETE.md、SPRINT2_COMPLETE.md和SPRINT3_COMPLETE.md
发展
设置开发环境
# Clone repository
cd PatternSphere
# Create virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Install in development mode
pip install -e .
# Run tests
pytest
代码质量
# Format code
black patternsphere/
# Type checking
mypy patternsphere/
# Linting
flake8 patternsphere/
运行测试
# All tests
pytest
# With coverage
pytest --cov=patternsphere
# Specific test file
pytest tests/unit/test_search_engine.py
# Performance tests
pytest tests/performance/ -v
# Integration tests
pytest tests/integration/ -v
项目统计
| 度量 | 值 |
|---|---|
| 源线总数 | 2638 |
| 总测试线 | 4037 |
| 测试/代码比 | 1.53:1 |
| 总图案数 | 61 |
| 类别 | 8 |
| 命令 | 5 |
| 测试覆盖率 | 91% |
需求
运行时间：
- python：3.9或更高
- 依赖项:
- pydantic>=2.0.0（数据验证）
- 复制设置>=2.0.0（配置）
- pyyaml>=6.0（支持YAML）
- typer>=0.9.0（CLI框架）
- rich>=13.0.0（终端格式化）
发展：
- pytest>=7.4.0
- pytest冠状病毒>=4.1.0
- 黑色>=23.0.0
- mypy >= 1.5.0
- 薄片8>=6.1.0
路线图
第一阶段（完成）✅
- OORP模式加载
- 加权评分关键字搜索
- 带有5个命令的CLI界面
- 61个带有全面标签的OORP模式
- 基于文件的存储，具有原子写入功能
- 248项综合测试
- 完整的文件
第二阶段（未来-规划在珠三角）
-
PDF集成:
- PDF模式提取
- 四人帮（GoF）模式
- 企业集成模式
- 面向模式的软件体系结构（POSA）
- 手动模式定义工作流程
- PDF页面链接
-
多源架构:
- 知识源抽象层
- 源插件架构
- 冲突解决
- 多个来源同时
第三阶段（未来）
- 基于嵌入的语义搜索
- 模式关系可视化
- 网络界面
- 基于代码分析的模式推荐
- 代码示例集成
第四阶段（未来）
- 用户贡献模式
- 模式比较工具
- 导出为各种格式
- IDE插件
- 协同模式策划
贡献
PatternSphere旨在实现可扩展性：
添加新模式源：
- 在中创建加载器
patternsphere/loaders/ - 机具装载机跟随
OORPLoader结构 - 添加图案
data/sources/<source-name>/ - 在配置中注册源
添加新命令：
- 在中添加命令功能
patternsphere/cli/commands.py - 使用
@app.command()装饰器 - 遵循现有的命令模式
- 在中添加测试
tests/integration/test_cli.py
添加测试：
- 单元测试：
tests/unit/ - 集成测试：
tests/integration/ - 性能测试：
tests/performance/ - 遵循现有的测试结构
许可证
MIT许可证-有关详细信息，请参阅许可证文件
致谢
图案来源：
- OORP：Serge Demeyer、Stéphane Ducasse和Oscar Nierstrasz的《面向对象的再造模式》（2003）
技术：
支持
获取帮助：
# Main help
patternsphere --help
# Command help
patternsphere search --help
# System info
patternsphere info
文档：
- 检查 CLI 参考 获取详细的命令帮助
- 查看中的测试示例
tests/目录 - 请参阅中的演示脚本
scripts/demos/：demo_sprint1.py、demo_sprint2.py、demo_siprint3.py
PatternSphere v1.0.0 软件设计模式的统一知识库
建于❤️ 遵循SOLID原则和干净的架构。
