pyscn

English | 日本語 | 简体中文 | Français

AI 编码时代的 Python 代码质量分析。

正在使用 Cursor、Claude 或 ChatGPT 构建项目？pyscn 通过结构分析，让 AI 生成的代码保持可维护。

快速开始

# Run analysis without installation
uvx pyscn@latest analyze .
# or
pipx run pyscn analyze .

演示

功能

只需一条命令，即可为整个代码库评分（0-100 分，等级为 A-F），并生成一份 HTML 报告，指出应优先修复的问题。

pyscn 从五个角度分析代码：

• 🧹 死代码 - 可以安全删除的不可达代码
• 📋 重复代码 - 值得合并的复制粘贴代码和结构相似代码（Type 1-4 克隆检测）
• 🌀 复杂度 - 难以阅读和测试的函数及可执行类代码块（圈复杂度和认知复杂度）
• 🔥 模块和目录热点 - 按文件统计代码质量，并按目录汇总复杂度，帮助确定重构优先级
• 🏗️ 架构 - 循环导入、分层规则违规（clean / layered / hexagonal / MVC 预设），以及自动检测模块群落，揭示代码的实际结构
• 🧩 类设计 - 职责过多或依赖过多的类（CBO 耦合度、LCOM4 内聚度）

每秒 100,000+ 行 • 使用 Go + tree-sitter 构建

其他语言

pyscn 是 polyscan 的 Python 分析器。要分析 JavaScript、TypeScript、Go、Rust 和 C++，请运行：

npx polyscan analyze .

同样的五个分析角度、同样的 0-100 分数，以及一份 HTML 报告。

Polyscan for GitHub

Polyscan App 会将每周审计报告作为 GitHub Issue 提交。公开仓库可免费使用。

AI Agent 集成

pyscn 附带 Agent Skills，用于指导 AI 编码 Agent 何时以及如何运行各项分析：健康检查、重构、架构审查，以及适用于 CI 的报告。

Agent Skills（推荐）

uvx add-skills ludo-technologies/pyscn

这会将 Skills 安装到你的项目中。它们适用于 Claude Code、Cursor、Codex、Gemini CLI 以及许多其他 Agent（添加 --agent cursor 等参数可指定目标 Agent，添加 --global 可应用于所有项目）。

然后只需向你的 Agent 提出请求：

1. “分析 app/ 目录的代码质量”

2. “找出重复代码并帮我重构”

3. “展示复杂代码并帮我简化”

MCP 服务（可选）

为实现更紧密的集成，捆绑的 pyscn-mcp 服务会将相同的分析作为 MCP 工具提供给 Claude Code、Cursor、ChatGPT 和其他 MCP 客户端。

Claude Code 插件（同时设置 MCP 服务和 Skills）：

claude plugin marketplace add ludo-technologies/pyscn
claude plugin install pyscn-mcp@pyscn-marketplace

Claude Code 手动设置：

claude mcp add pyscn-mcp uvx -- pyscn-mcp

Cursor / Claude Desktop： 将其添加到 MCP 设置中（~/.config/claude-desktop/config.json 或 Cursor 设置）：

{
  "mcpServers": {
    "pyscn-mcp": {
      "command": "uvx",
      "args": ["pyscn-mcp"],
      "env": {
        "PYSCN_CONFIG": "/path/to/.pyscn.toml"
      }
    }
  }
}

深入了解设置流程，请参阅 mcp/README.md；架构详情请参阅 docs/MCP_INTEGRATION.md。

安装

# Install with pipx (recommended)
pipx install pyscn

# Or with uv
uv tool install pyscn

macOS Intel（x86_64）： PyPI wheel 仅为 Apple Silicon 构建（Intel wheel 已在 v1.5.1 中移除），因此 uvx、pipx、uv 和 pip 无法在 Intel Mac 上安装 pyscn。请改用 brew install pyscn 或 go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest。

git clone https://github.com/ludo-technologies/pyscn.git
cd pyscn
make build

go install github.com/ludo-technologies/pyscn/cmd/pyscn@latest

常用命令

pyscn analyze

运行全面分析并生成 HTML 报告

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
pyscn analyze --json --output - . | jq       # JSON report on stdout
pyscn analyze --json --html --no-open .      # JSON and HTML reports from one run
pyscn analyze --select complexity .          # Only complexity analysis
pyscn analyze --select deps .                # Only dependency analysis
pyscn analyze --select complexity,deps,deadcode . # Multiple analyses
pyscn analyze --skip-communities .           # Skip module community detection

pyscn check

适用于 CI 的快速质量门禁

pyscn check .                         # Quick pass/fail check
pyscn check --max-complexity 15 .     # Custom thresholds
pyscn check --max-cycles 0 .          # Only allow 0 cycle dependency
pyscn check --select deps .           # Check only for circular dependencies
pyscn check --select di .             # Detect DI anti-patterns (opt-in)
pyscn check --allow-circular-deps .   # Allow circular dependencies (warning only)

pyscn init

创建配置文件

pyscn init                         # Generate .pyscn.toml

💡 运行 pyscn --help 或 pyscn <command> --help 查看完整选项

配置

创建 .pyscn.toml 文件，或在 pyproject.toml 中添加 [tool.pyscn]：

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

⚙️ 运行 pyscn init 生成包含所有可用选项的完整配置文件

文档

📖 pyscn 文档站点 — 安装、规则目录、CLI 参考、配置、输出规范

贡献者请参阅：开发指南 • 架构 • 测试

企业支持

如需商业支持、定制集成或咨询服务，请通过 [email protected] 联系我们

许可证

MIT 许可证 — 请参阅 LICENSE

使用 Go 和 tree-sitter 倾情打造 ❤️