ludo-technologies/pyscn

pyscn – Python용 AI 인식 코드 품질 분석기

기능

• 전체 Python 코드베이스에 대한 빠른 정적 분석을 실행하고 단일 품질 점수(0-100)와 A-F 등급을 생성합니다.
• 가장 긴급한 문제를 강조하는 대화형 HTML 보고서(또는 JSON)를 생성합니다.

작동 방식

• 엔진은 Go로 작성되었으며 tree-sitter 파서를 사용하여 >100k 行/秒的速度遍历 Python AST。
• 应用五个分析“角度”：
  1. 死代码 – 可删除的不可达语句。
  2. 重复代码 – 克隆检测（Type 1-4）以发现复制粘贴的代码块。
  3. 复杂度 – 函数和类的圈复杂度和认知复杂度指标。
  4. 热点 – 按文件和目录的质量/复杂度汇总，以优先进行重构。
  5. 架构 – 循环导入、层规则违规（clean、hexagonal、MVC 预设）以及自动发现的模块社区。
  6. 类设计 – 耦合（CBO）和内聚（LCOM4）检查。
• 结果在单个 HTML 页面中可视化，对文件进行颜色编码，显示模块关系图，并列出可操作的建议。

为什么对 AI 辅助编码很重要

• 现代 AI 结对编程器（Claude、Cursor、GitHub Copilot、Gemini 等）可能会建议能工作但难以维护的代码。pyscn 让您可以验证 AI 生成的代码保持干净、低复杂度和结构良好。
• 该工具附带 Agent Skills，教编码代理何时调用每个分析（例如，“提交前运行死代码检查”）。
• 可选的 MCP 服务器（pyscn-mcp）通过 Model-Code-Protocol 公开相同的分析，因此像 Claude Code 或 Cursor 这样的代理可以直接从聊天界面调用它们。

快速开始

# 一行命令，无需安装
uvx pyscn@latest analyze .
# 或使用 pipx 安装后
pipx install pyscn
pyscn analyze .   # HTML 报告自动打开

• 在 CI 管道中使用 pyscn check 进行快速通过/失败门禁（例如，最大复杂度 ≤ 15，无循环依赖）。
• 配置位于 .pyscn.toml（或 pyproject.toml 中的 [tool.pyscn] 下）。

集成点

• Polyscan App – 一个免费的 GitHub 应用，为公共仓库每周发布审计报告作为 issue。
• Claude Code 插件 – 自动安装 MCP 服务器并注册 Skills。
• Cursor / 其他代理 – 将 MCP 服务器条目添加到代理的配置 JSON 中。

安装选项

• 首选：pipx install pyscn（或 uv tool install pyscn）。
• macOS Intel 用户需要使用 Homebrew 或 go install 方式，因为预构建的 wheel 针对 Apple Silicon。
• 您也可以使用 make build 从源码构建。

谁可能使用它

• 严重依赖 AI 代码生成器并希望自动防止技术债务的团队。
• 希望快速、可视化检查 Python 项目健康状况的个人开发者。
• 需要语言无关质量门禁的 CI/CD 管道（通过底层 polyscan 支持其他语言）。

了解更多

• 完整文档：https://docs.codescan.dev/pyscn/
• 介绍该工具的博客文章：https://dev.to/daisukeyoda/pyscn-the-code-quality-analyzer-for-vibe-coders-18hk
• 源代码和贡献指南位于仓库的 docs/ 文件夹中。

---

许可证：MIT