svcs (Markomanninen)

SVCS-语义对比##🌟 主要特点

• 🧠 五层语义分析 -从AST解析到AI驱动的模式识别
• 📁 存储库本地架构 -每个存储库都维护自己的语义数据库
• 🤝 Git集成团队协作 -通过git notes自动共享语义数据
• 🌍 多语言支持 -Python（完整）、PHP（现代）、JavaScript/TypeScript（基于AST）
• 🌐 交互式Web仪表板 -基于浏览器的现代语义数据探索界面
• 🤖 模型上下文协议（MCP）服务器 -VS Code、Claude等AI助手集成。
• ⚡ 实时Git钩子 -对每次提交进行自动语义分析
• 💬 对话式AI界面 -关于代码演化的自然语言查询
• 🛠️ 完整的CLI工具包 -丰富的命令行界面，支持所有功能
• 🔧 项目管理 -通过集中式注册系统提供多项目支持

SVCS是一种 存储库局部语义分析系统 它跟踪代码更改的含义，超越了传统的逐行差异。它使用一个5层分析系统，将抽象语法树（AST）分析与可选的人工智能语义理解相结合。

🚀 生产就绪 -具有CLI、web仪表板、MCP服务器和团队协作功能的完整系统。

目录

• 主要特点
• 为什么选择SVCS？价值主张
• 5层分析架构
• 语言支持
• 安装
• 快速开始
• 完整的CLI参考
• Web仪表板
• MCP服务器接口
• 高级功能
• 开发设置
• 系统要求
• 局限性
• 贡献

🌟 主要特点

• 🧠 五层语义分析 -从AST解析到可选的AI理解
• 📁 存储库本地架构 -每个存储库都维护自己的语义数据库
• 🤝 Git集成团队协作 -通过git notes共享语义数据
• 🌍 多语言支持 -Python（完整）、PHP（现代）、JavaScript/TypeScript（基于AST）
• 🤖 模型上下文协议（MCP）服务器 -VS Code、Claude等AI助手集成。
• ⚡ 实时Git钩子 -提交的自动语义分析
• 💬 对话式AI界面 -关于代码演化的自然语言查询
• 📊 交互式Web仪表板 -可视化语义模式和演变
• � 完整的CLI工具包 -丰富的命令行界面，支持所有功能

🚀 为什么选择SVCS？价值主张

超越传统Git：语义鸿沟

Git跟踪 *什么* 更改（行、文件），SVCS理解 *这些变化意味着什么*:

• Git显示: +def calculate_score(items): return sum(x.value * x.weight for x in items)
• SVCS透露：“增加了加权计算算法，引入了函数式编程模式，改进了数学抽象”

非常适合人工智能增强开发

现代AI助手（GitHub Copilot、Claude、GPT）擅长即时代码分析，但缺乏 时间上下文.SVCS提供了缺失的历史维度：

用例

• 🎯 代码学习与调查 -跟踪您的编码演变并确定改进模式
• 🔗 完整的Git集成 -每个语义事件都链接到其确切的git提交，以实现完全可追溯性
• 🤝 团队协作 -用于自然语义数据共享的Git集成工作流
• 🏢 企业应用程序 -代码审查增强、技术债务管理、CI/CD集成

🧠 5层分析架构

SVCS采用多层分析系统，提供日益复杂的语义理解：

第1-4层：结构和句法分析

• 第1-2层：AST解析和结构更改（函数、类、导入）
• 第3-4层：行为模式（控制流、数据访问、复杂性）

第5a层：基于规则的模式识别

• 使用编程规则进行模式检测
• 确定架构和质量改进
• 检测错误处理模式和函数式编程采用情况

第5b层：LLM驱动分析🤖

• 需要Google Gemini API密钥 (GOOGLE_API_KEY 环境变量）
• 智能过滤：仅分析非琐碎、复杂的更改
• 没有API密钥：SVCS使用1-5a层（仍然非常强大！）
• 检测抽象概念，如：

- 架构改进和设计模式采用 - 性能优化和可维护性增强 - 代码可读性改进和抽象改进 - 错误处理策略更改

🌍 语言支持

解析器架构和鲁棒性

SVCS使用 多层回退系统 为了获得最大的可靠性：

PHP分析

1. 主要的，重要的：树型PHP解析器（支持PHP 7.4+和8.x）

- 现代功能：枚举、属性、类型化属性、联合类型 - 基于AST的精确解析，具有完整的语义理解

1. 后备方案：phply解析器（支持PHP 5.x-7.3）

- 保持与旧代码库的兼容性

1. 最后的退路：用于基本结构检测的正则表达式解析

JavaScript/TypeScript分析

1. 主要的，重要的：具有容差模式的esprima AST解析器

- 完整的ES6+语法支持，包括类、箭头函数、async/await - 详细的参数和继承跟踪 - 同时支持JavaScript（.js）和TypeScript（.ts）语法

1. 后备方案：使用现代JS模式增强正则表达式解析

- 各种函数声明的全面模式匹配

按语言检测到的更改类型

Python（完全支持）:

• ✅ 函数、类、方法、属性、装饰器
• ✅ 异步/等待模式、生成器、推导式
• ✅ 类型注释、继承跟踪
• ✅ 进口报表、异常处理
• ✅ 31+不同的语义事件类型

PHP（现代支持）:

• ✅ 类、接口、特征、枚举（PHP 8.1+）
• ✅ 方法签名更改，属性类型更改
• ✅ 继承跟踪(extends, implements)
• ✅ 现代特性：属性（PHP 8.0+）、类型化属性
• ✅ 命名空间和使用语句跟踪
• ✅ 可见性修改器更改(public, private, protected)

JavaScript/TypeScript（基于AST的支持）:

• ✅ 函数声明、表达式和箭头函数
• ✅ 类继承跟踪(extends 关系）
• ✅ 构造函数参数更改
• ✅ 类内方法的添加/删除
• ✅ 带有函数赋值的变量声明
• ✅ ES6+语法支持（类、箭头函数、async/await）
• ✅ TypeScript语法兼容性
• ✅ 变量范围和声明更改

备注Python提供了最全面的语义分析。PHP和JavaScript提供了强大的结构和语义变化检测，适用于git钩子的生产使用。

🛠️ 安装

需求：Python 3.8+、Git、基于Unix的系统（Linux、macOS或Windows WSL）

1.安装SVCS

# Clone the repository
git clone https://github.com/markomanninen/svcs.git
cd svcs

# Install SVCS globally (creates 'svcs' command)
pip install -e .

# Install enhanced language parsing (optional but recommended)
pip install tree-sitter tree-sitter-php esprima

# Verify installation
svcs --help

2.可选：AI分析设置

对于第5b层人工智能分析，请设置Google Gemini API：

# Get your API key from: https://makersuite.google.com/app/apikey
export GOOGLE_API_KEY="your-api-key"

# Or add to your shell profile (.bashrc, .zshrc, etc.)
echo 'export GOOGLE_API_KEY="your-api-key"' >> ~/.bashrc

备注：在没有API密钥的情况下，SVCS仍然通过1-5a层提供强大的语义分析。

🚀 快速开始

1.在存储库中初始化SVCS

# Navigate to your git project
cd your-project

# Initialize SVCS (installs git hooks automatically)
svcs init

# For new projects, SVCS can initialize git too
svcs init --git-init

2.使用正常的Git工作流

# Make changes to your code
echo "def new_function(): pass" >> code.py

# Commit as usual - SVCS analyzes automatically
git add code.py
git commit -m "Add new function"
# 🔍 SVCS: Analyzing semantic changes...
# ✅ SVCS: Detected semantic events stored locally and in git notes

3.探索你的代码进化

# View recent semantic changes
svcs events --limit 10

# Search for specific patterns
svcs search "authentication"

# Track function evolution
svcs evolution "func:new_function"

# Check repository status
svcs status

4.探索高级界面

# Interactive web dashboard
svcs web start
# Open http://127.0.0.1:8080 in your browser

# Start MCP server for AI integration
svcs mcp start --background

# Conversational interface
svcs discuss --query "summarize recent changes"

📋 完整的CLI参考

快速参考表

核心存储库管理

svcs init                    # Initialize SVCS in current repository
svcs init --git-init         # Initialize git repository + SVCS
svcs status                  # Show repository status and semantic stats
svcs cleanup                 # Repository maintenance and optimization

语义数据探索

# View semantic events
svcs events                  # Recent semantic events (default: 20)
svcs events --limit 50       # Show more events
svcs events --branch main    # Events for specific branch
svcs events --type "function_added"  # Filter by event type

# Advanced search
svcs search "authentication"               # Search semantic events
svcs search --author "john@example.com"    # Filter by author
svcs search --since "1 week ago"           # Time-based filtering
svcs search --pattern-type performance     # Search for patterns

# Track evolution
svcs evolution "func:authenticate"   # Track specific function
svcs evolution "class:UserManager"   # Track class evolution

分析和见解

svcs analytics               # Generate analytics report
svcs quality                 # Code quality analysis
svcs compare main develop    # Compare branches

Web和AI界面

# Web dashboard
svcs web start               # Start interactive web dashboard
svcs web start --port 9000   # Custom port
svcs dashboard               # Generate static HTML dashboard

# AI-powered interfaces
svcs discuss                 # Start interactive conversation
svcs discuss --query "what changed recently?"  # Start with query
svcs query "show performance improvements"     # One-shot query

# MCP server for AI assistants
svcs mcp start               # Start MCP server (foreground)
svcs mcp start --background  # Background mode
svcs mcp status              # Check server status
svcs mcp stop                # Stop server

Git集成

svcs notes sync              # Sync semantic notes with remote
svcs notes fetch             # Fetch team semantic data
svcs notes show --commit abc123  # View semantic note for commit

项目参观和帮助

svcs init-project            # Interactive project setup tour
svcs init-project MyProject --non-interactive  # Automated setup
svcs workflow               # Show workflow guide
svcs help                   # Quick help and examples

高级Git集成和同步命令

# Enhanced git operations with automatic semantic sync
svcs pull                    # Enhanced git pull with semantic notes sync
svcs push [remote] [branch]  # Enhanced git push with semantic notes sync  
svcs merge 
          # Enhanced git merge with semantic event transfer
svcs sync                    # Sync semantic data with remote repository
svcs sync-all                # Complete sync after complex git operations
svcs merge-resolve           # Resolve post-merge semantic event issues
svcs auto-fix                # Auto-detect and fix common SVCS issues

# Configuration management
svcs config set auto-sync true     # Configure automatic sync behavior
svcs config get auto-sync          # View current configuration
svcs config list                   # List all configuration settings

# CI/CD integration
svcs ci pr-analysis          # Analyze pull request semantic impact
svcs ci quality-gate         # Run quality gate checks
svcs ci report               # Generate CI reports

# Project management
svcs init-project            # Interactive project creation with guided tour
svcs delete-project          # Remove project from SVCS tracking

# Internal/Hook commands (typically used by git hooks)
svcs process-hook post-commit       # Process git post-commit hook

🌐 Web仪表板

SVCS提供了一个全面的基于web的界面，用于探索语义数据、项目管理和分析。

快速开始

# Start the interactive web dashboard  
svcs web start

# Custom port
svcs web start --port 9000

# Open in browser
# http://127.0.0.1:8080

仪表板功能

🔍 语义搜索与分析

• 按作者、日期范围、置信度和分析层进行高级过滤
• 用于常见搜索的快速操作按钮（性能、架构、错误处理）
• 实时结果，带格式化显示和置信度评分

📝 Git集成

• 通过语法高亮显示查看任何提交的更改文件
• 通过全面的提交分析显示原始git差异
• 使用语义上下文和演化跟踪浏览最近的提交

📈 代码演化与分析

• 跟踪特定功能/类随时间的变化，并提供详细的演变历史
• AI检测模式分析（性能、架构、错误处理）
• 基于置信度的滤波和时间模式分析

🗂️ 项目管理

• 通过集中式存储库发现和管理提供多项目支持
• 项目统计、健康监测和综合分析
• 具有清理和优化功能的数据库维护工具

📊 交互式可视化

• 语义进化的时间线可视化
• 事件类型分布图和分析仪表板
• 显示代码结构和依赖关系的网络图

静态仪表板生成

# Generate standalone HTML dashboard
svcs dashboard --output my_report.html

# Open the generated file in any browser
# No server required - fully self-contained

🤖 MCP服务器接口

SVCS提供 模型上下文协议（MCP）服务器 它与Claude、VS Code Copilot和其他MCP兼容工具等人工智能助手集成。

快速开始

# Start MCP server
svcs mcp start --background

# Check status
svcs mcp status

# View logs
svcs mcp logs

# Stop server
svcs mcp stop

可用的MCP工具

项目管理

• list_projects -列出所有SVCS存储库
• get_project_statistics -获取项目的语义统计信息

语义分析

• search_events_advanced -具有全面过滤功能的高级搜索
• get_recent_activity -获取最近的语义更改
• search_semantic_patterns -人工智能模式搜索
• get_filtered_evolution -跟踪特定代码元素的演变

Git集成

• get_commit_changed_files -列出提交中更改的文件
• get_commit_summary -基于语义事件的全面提交分析

AI助手的使用

MCP服务器运行后，您可以在兼容的AI界面中提出自然语言问题：

VS代码/光标与副驾驶聊天：

@copilot Show me all registered SVCS projects
@copilot What semantic patterns were detected in the last week?
@copilot Get a summary of commit abc123 including all semantic events
@copilot How has the authenticate function evolved over time?
@copilot Find all performance optimizations in my code
@copilot Show recent architecture improvements with high confidence

克劳德桌面：

*“显示所有已注册的项目”*\ *“上周检测到了哪些语义模式？”*\ *“获取提交abc123的摘要，包括所有语义事件”*\ *“身份验证功能是如何随着时间的推移而发展的？”*

IDE集成

MCP服务器与现代开发环境无缝集成：

• 克劳德桌面 -将SVCS服务器添加到MCP配置中，以进行自然语言语义查询
• VS代码与副驾驶聊天 -使用 @copilot 直接在编辑器中访问SVCS语义见解的命令
• 光标IDE -原生MCP支持AI驱动的语义代码分析
• 任何与MCP兼容的AI接口 -标准模型上下文协议支持确保了广泛的兼容性

🔬 高级功能

团队协作

SVCS通过语义注释提供git集成团队协作：

# Share semantic insights with team
svcs notes sync                  # Push semantic data to remote
git push origin main             # Semantic notes included automatically

# Receive team insights
git pull origin main             # Semantic notes synced automatically
svcs notes fetch                 # Explicit fetch if needed

# View team semantic data
svcs notes show --commit abc123  # See semantic note for specific commit

分支比较

# Compare semantic evolution between branches
svcs compare main develop        # See semantic differences
svcs compare --limit 20          # Show more comparison data

模式分析

# Search for specific semantic patterns
svcs search --pattern-type performance     # Performance improvements
svcs search --pattern-type architecture    # Architectural changes
svcs search --pattern-type error_handling  # Error handling patterns

CI/CD集成

# Analyze pull request semantic impact
svcs ci pr-analysis --target main

# Run quality gate checks
svcs ci quality-gate --strict

# Generate CI reports
svcs ci report --format json

配置管理

# View current configuration
svcs config list

# Configure automatic sync with remotes
svcs config set auto-sync true

# Set AI analysis confidence threshold
svcs config set ai-threshold 0.8

# Configure web dashboard settings
svcs config set web-port 9000
svcs config set web-host 0.0.0.0

项目管理

# Interactive project creation and setup
svcs init-project MyNewProject

# Non-interactive project creation
svcs init-project MyProject --path /path/to/project --non-interactive

# Remove project from SVCS tracking
svcs delete-project --path /path/to/project

# List all registered projects
svcs list

# Project cleanup and maintenance
svcs cleanup --git-unreachable
svcs cleanup --show-stats

🧑‍💻 开发设置

# Clone and setup development environment
git clone https://github.com/markomanninen/svcs.git
cd svcs

# Install in development mode with all dependencies
pip install -e .

# Install enhanced language parsing (recommended)
pip install tree-sitter tree-sitter-php esprima

# Install development dependencies
pip install pytest black pre-commit

# Install git hooks for development
pre-commit install

# Verify installation
svcs --help

运行测试

# Core functionality tests
python -m pytest tests/

# Comprehensive integration tests
python tests/test_complete_functionality.py

# GitHub collaboration workflow tests
python tests/test_github_collaboration.py

# MCP server functionality tests
python tests/test_mcp_tools.py

# Web dashboard tests
python tests/test_comprehensive_dashboard.py

🖥️ 系统要求

核心要求

• python：3.8+（建议：3.11+）
• Git: 2.0+
• 操作系统：基于Unix的系统（Linux、macOS或Windows WSL）
• 记忆：2GB+RAM
• 存储：100MB+用于数据库和日志

依赖项

SVCS会自动安装所需的依赖关系：

# Essential (auto-installed)
rich>=12.0.0                    # Terminal UI and formatting
click>=8.0.0                    # CLI framework  
sqlite3                         # Database (built-in)
google-generativeai>=0.3.0      # Gemini AI integration
tenacity>=8.0.0                 # Retry logic for API calls

# Language parsing (auto-installed)
tree-sitter>=0.20.0             # Modern parsing engine
tree-sitter-php>=0.20.0         # PHP AST support
esprima>=4.0.1                  # JavaScript/TypeScript support
phply>=1.2.6                    # PHP fallback parser

# Web dashboard (optional)
Flask>=2.0.0                    # Web server
Flask-CORS>=3.0.0               # Cross-origin requests

# MCP server (optional)
mcp                             # Model Context Protocol

API要求

• Google Gemini API （可选）-第5b层AI分析所需

- 获取免费密钥：https://makersuite.google.com/app/apikey - 免费等级：1000次请求/天 - 没有API密钥：SVCS使用1-5a层（仍然非常强大！）

性能特征

• 第1-4层分析：每次提交约100-200ms（基于AST的快速分析）
• 第5a层分析：每次提交约200-500ms（基于规则的模式检测）
• 第5b层分析：每次提交约2-10s（AI分析，仅用于复杂的更改，需要API密钥）
• 数据库查询：~10-50ms（根据指标优化）
• Web仪表板启动：~1-3s（包括项目发现）
• MCP服务器响应：每个查询约100-500ms（取决于复杂性）

⚠️ 局限性

当前限制

• Windows支持：由于git挂钩和shell脚本依赖关系的符号链接使用，需要WSL
• 数据库规模：对于非常大的存储库（>10万次提交），基于SQLite的存储可能需要优化
• API依赖项：第5b层人工智能分析需要外部Google Gemini API访问并消耗API令牌
• 实时分析：基于Git钩子的方法需要提交来触发分析（没有实时代码分析）
• 内存使用：大型存储库可能需要2-4GB RAM进行全面分析

语言支持状态

• python：31种以上事件类型的全面语义分析，完全支持AST
• PHP程序：现代语言支持（PHP 7.4+/8.x），带Tree sitter解析器+phply回退
• JavaScript/TypeScript：基于AST的分析，具有全面的ES6+语法支持
• 其他语言：计划支持Go、Rust、Java、C++和其他流行语言

可扩展性考虑因素

• 存储库大小：针对典型项目规模（1k-10k提交）进行了优化
• 团队规模：存储库本地架构随分布式团队自然扩展
• 性能影响：Git钩子方法根据分析层增加了约200ms-2s的提交时间
• 存储需求：语义数据每1000次提交可额外存储约10-50MB
• 网络使用率：Git注意到同步为Git操作增加了最小的开销

🆘 获取帮助

内置帮助命令

# Quick help and examples
svcs help

# Show SVCS workflow guide  
svcs workflow

# Show team collaboration workflow
svcs workflow --type team

# Show troubleshooting guide
svcs workflow --type troubleshooting

# Get help for specific commands
svcs init --help
svcs search --help
svcs web --help

常见问题及解决方案

安装问题

# Verify installation
pip install -e .
svcs --version

# Install with optional dependencies
pip install -e ".[ai,web,mcp]"

设置问题

# Initialize SVCS in existing repository
svcs init

# Check repository status
svcs status

# Run diagnostics
svcs auto-fix

性能问题

# Clean up database
svcs cleanup --show-stats

# Optimize repository
svcs cleanup --git-unreachable

文档和资源

• 快速开始：按照“🚀 上面的“快速入门”部分
• 完整的CLI参考：请参阅上述命令表和详细章节
• Web仪表板：带有内置帮助工具提示的交互式界面
• MCP集成：用于自然语言查询的内置AI辅助工具
• 项目范例：使用 svcs init-project 通过真实示例进行引导设置

🤝 贡献

我们欢迎捐款！以下是如何开始：

开发工作流程

# Fork and clone
git clone https://github.com/yourusername/svcs.git
cd svcs

# Set up development environment
pip install -e .
pip install pytest black pre-commit

# Install pre-commit hooks
pre-commit install

# Make changes and test
python -m pytest tests/
python tests/test_complete_functionality.py

# Submit pull request

贡献领域

• 语言支持：为新的编程语言（Go、Rust、Java、C++）添加解析器
• 人工智能集成：改进语义模式检测算法和置信度评分
• 性能优化：提高分析速度、内存使用率和数据库效率
• Web仪表板：添加新的可视化、分析功能和用户界面改进
• 文档：改进用户指南、API文档和示例项目
• 测试：扩大边缘案例、多语言项目和大型存储库的测试覆盖范围
• 平台支持：不依赖WSL的原生Windows支持

代码的风格

• Python代码遵循PEP 8
• 尽可能使用类型提示
• 为公共函数添加文档字符串
• 跑 black 用于代码格式化
• 彻底测试您的更改

报告问题

• 错误报告：使用GitHub Issues，尽量减少复制示例和系统信息
• 功能请求：清楚地描述用例和预期行为
• 性能问题：包括存储库大小、提交频率和分析时间数据
• 文件问题：建议需要的具体改进或澄清
• 系统要求：始终包括SVCS版本、Python版本和操作系统详细信息

📄 许可证

MIT许可证 -有关详细信息，请参阅LICENSE文件。

______________________________________________________________________

软件版本控制系统 -通过存储库本地分析、团队协作和AI集成将语义理解带入版本控制。内置于❤️ 对于那些关心理解传统差异之外的代码演化的开发人员来说。