Pyscn：Python 代码质量自动检测工具 | 前端进阶之旅

Pyscn：Python 代码质量自动检测工具 | 前端进阶之旅

Full translation

完整中文译文

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

一款面向 Python vibe coder 的代码质量分析工具。

正在使用 Cursor、Claude 或 ChatGPT 构建项目？pyscn 会执行结构化分析，帮助你的代码库保持可维护性。

还在使用其他语言？pyscn 是 polyscan 的一部分——后者提供面向 JavaScript/TypeScript 等语言的代码质量分析工具。

# 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 随附 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：

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

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

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

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

“找出复杂代码并帮我简化”

“找出复杂代码并帮我简化”

MCP Server（可选）

如需更紧密的集成，随附的 pyscn-mcp Server 会将相同的分析能力作为 MCP tools 提供给 Claude Code、Cursor、ChatGPT 及其他 MCP 客户端。

Claude Code 插件（同时配置 MCP Server 和 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

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

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

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

pyscn analyze .                              # All analyses with HTML report
pyscn analyze --json .                       # Generate JSON report
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

适用于 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                         # Generate .pyscn.toml

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

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

# .pyscn.toml
[complexity]
max_complexity = 15

[dead_code]
min_severity = "warning"

[output]
directory = "reports"

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

Pyscn Bot（GitHub App）

Pyscn Bot 会自动监控 Python 代码质量。

PR 代码审查——针对每个 pull request 自动进行代码审查

每周代码审计——扫描整个 repository，并针对架构问题创建 issue

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

面向贡献者：开发指南 • 架构 • 测试

如需商业支持、定制集成或咨询服务，请通过 contact@ludo-tech.org 联系我们。

MIT License——详见 LICENSE

使用 Go 和 tree-sitter，以 ❤️ 构建