Sourcery

Sourcery 快速入门

像一位随时在线的代码审查员,写完一行就告诉你哪里可以更优雅。

这是什么?适合谁?

Sourcery 是一款专注于”自动代码审查”的 AI 工具,主打实时代码重构建议。它不像 Copilot 那样主要生成代码,而是在你写完一段代码后,主动提出”这里可以更简洁”、“这个函数可以拆成两个”等具体建议。Sourcery 同时支持本地 IDE 插件、GitHub PR 审查、CI 流水线集成,适合想在写代码阶段就保持高质量的团队。

它适合:对代码质量要求高的企业研发团队、想养成良好编码习惯的初中级开发者、code review 任务繁重的 Tech Lead、需要在 PR 阶段就抓住低级错误的开源维护者。Sourcery 有免费版(个人开源项目)和付费版(团队/企业),定价相对友好。

准备工作

• 账号:GitHub 账号注册即可。
• IDE:VSCode、PyCharm 等主流 IDE 都有插件。
• 语言:Sourcery 对 Python 支持最好,JavaScript/TypeScript 次之,其他语言功能有限。
• 网络:需要稳定国际网络。

3 步快速上手

第 1 步:安装 VSCode 插件

打开 VSCode 扩展市场,搜索 Sourcery,点 Install。也可以在 https://marketplace.visualstudio.com/items?itemName=Sourcery.sourcery 找到。

第 2 步:登录账号

安装后,IDE 左下角会出现 Sourcery 图标,点击后用 GitHub 账号登录。登录成功后,Sourcery 会自动开始对你打开的 Python 文件做实时分析。

第 3 步:看第一条建议

打开或新建一个 Python 文件,写一段不那么”优雅”的代码:

def get_active_users(users):
    result = []
    for u in users:
        if u.is_active == True:
            result.append(u)
    return result

写完后,你会看到左侧或代码上方出现 Sourcery 的建议:“可以用列表推导式简化”、”== True 是冗余的”。点击 “Show Diff” 看具体改动,确认无误点 “Apply” 采纳。

常见踩坑

1. 看不到建议:检查文件后缀名是不是 .py,Sourcery 主要针对 Python。
2. 建议太啰嗦:在设置里把 “Quality Level” 调到 “Refactor only”,只显示真正的重构建议,过滤风格类。
3. 团队规则不适配:在项目根目录创建 .sourcery.yaml 配置规则,比如禁止某些模式。
4. PR 评论刷屏:在 GitHub 集成里把 Sourcery 设为 “评论者”而不是”必须修改者”,避免被 PR 工具要求回话。
5. 企业网络无法登录:部分公司网络限制 GitHub OAuth,需要让 IT 开放 sourcery.ai 域名。
6. 私有仓库不可用:免费版只支持公开仓库,私有项目需要订阅 Pro。

初级用法

• 行内建议:写完一段函数,Sourcery 自动在左侧出现 ⚡ 提示。
• 整文件 review:在命令面板输入 “Sourcery: Review File”,一次性给出全文件的改进建议。
• 解释代码:选中代码,右键 “Sourcery: Explain”,得到自然语言解释。

高级玩法

• GitHub PR 集成:在仓库里安装 Sourcery GitHub App,以后每个 PR 都会自动评论改进建议。
• 自定义规则:用 .sourcery.yaml 写自己的规则,比如”函数超过 50 行必须拆分”。
• CI 集成:在 GitHub Actions 里跑 sourcery-ci,把代码质量作为合并门槛。

小技巧

• 写完一段代码后按 Ctrl+Shift+P → “Sourcery: Suggest Refactorings” 强制触发一次。
• 在 .sourcery.yaml 里设置 refactor: true 让 AI 直接给出重构后代码,不只是建议。
• 用 “Skip Block” 注释包裹不需要检查的代码:# sourcery skip: avoid-builtin-shadowing。
• 团队统一配一份 .sourcery.yaml 比每个人都改 VSCode 设置更高效。
• 在 PR 描述里 @sourcery-bot,可以让它给出整 PR 的总结。
• 把团队”代码规范”翻译成 Sourcery 规则,新人上手直接被 AI 引导。
• 用 --quality-threshold 调高阈值,只在确实需要改进时才提示,减少噪音。
• Sourcery 的 GitHub 评论里点 “Apply Suggestion” 一键 commit,比手动改 PR 快。
• 在 IDE 里用快捷键 Ctrl+. 看 Sourcery 的所有重构建议,类似 ESLint 修复。
• Sourcery 支持 5 种语言,但 Python 支持最完善,先把 Python 项目跑通最划算。

团队落地方案

很多团队把 Sourcery 当作”代码教练”使用:新人入职时 Sourcery 自动指出代码风格问题,2 周内上手团队规范;PR Review 时 Sourcery 先 review 一遍,人类 review 重点放在架构和业务逻辑;团队规范变成 .sourcery.yaml 文件,所有人遵守同一份规则;重构时 Sourcery 自动建议函数拆分、命名优化,加速技术债务清理。如果你是 Tech Lead,强烈建议把 Sourcery 集成到 CI 流水线,作为合并门槛之一。

与其他审查工具的对比

代码审查工具很多,Sourcery 的优势在于”实时代码改进”。ESLint/Prettier 针对风格和语法,不动业务逻辑;SonarQube 深度代码质量分析,但要部署服务器;CodeClimate 托管式代码质量平台,SaaS 收费;Sourcery 则是实时代码重构建议,本地 + 云端混合。简单说,如果你要”写代码时就保持高质量”,Sourcery 最好;如果你要”整库的质量仪表盘”,SonarQube 更专业。

适合什么人

Sourcery 适合:初中级开发者,被 AI 边写边教;资深开发者,减少重复劳动专注架构业务;Tech Lead,统一团队代码风格降低 review 成本;开源维护者,在 PR 里给改进建议降低维护负担;Python 项目,因为对 Python 支持最完善。不太适合完全独立、风格随性的个人项目,以及抗拒 AI 工具的纯粹主义者。

常见问题 FAQ

Q1: Sourcery 适合哪些编程语言?

A: Sourcery 通常支持主流编程语言(Python、JavaScript/TypeScript、Java、Go、C++、Rust 等)。支持程度因语言而异:Python/JavaScript/TypeScript 最佳,小众语言(如 Haskell、Elixir)可能较弱。

Q2: Sourcery 生成的代码可以直接用吗?

A: 简单的 CRUD、工具函数、单元测试可以直接用;复杂的业务逻辑、算法实现需要人工 review。永远不要盲目复制 AI 生成的代码——先理解再使用。

Q3: Sourcery 怎么收费?

A: 通常分免费版(基础功能,有限次数)、付费版(高级模型、无限次数、团队协作)。个人开发者 Pro 版约 $10-20/月,企业版 $30-50/用户/月。具体以 https://sourcery.ai 定价为准。

Q4: Sourcery 会上传我的代码到云端吗?有隐私问题吗?

A: 大部分 AI 编程工具会保存你的代码用于服务提供(模型推理)和模型改进(除非关闭)。敏感代码(企业核心、商业秘密)建议:1) 使用本地部署版本;2) 关闭”使用我的代码改进模型”选项;3) 考虑企业版(有更强隐私保护)。

Q5: 怎么让 Sourcery 生成更高质量的代码?

A: 关键技巧:1) 写清晰的 prompt,说明输入输出和约束;2) 提供代码示例(让 AI 学习你的风格);3) 拆分任务,不要一次生成太多;4) 用 TODO 注释让 AI 补充具体实现;5) review + 单元测试保证质量。

参考链接

• Sourcery 官网
• VSCode 插件
• PyCharm 插件
• 用户文档
• GitHub App 安装

配置实战：.sourcery.yaml 规则详解

Sourcery 的自定义规则通过 .sourcery.yaml 配置文件管理，放在项目根目录即可生效。以下是实际项目中常用的配置示例：

# .sourcery.yaml
rule_settings:
  enable:
    - default
    - django
    - flask
  disable:
    - require-parameter-annotation
  rule_thresholds:
    - high: 60
      medium: 40
      low: 20

rule_files:
  - .sourcery-rules/**/*.yaml

ignore:
  - tests/*
  - migrations/*
  - */__pycache__/*

上述配置启用了默认规则集加 Django/Flask 专用规则，关闭了强制参数注解（适合不强制 type hint 的项目），并设置了高/中/低三级阈值。ignore 字段排除测试文件和数据库迁移文件，避免噪音。

自定义规则示例——禁止函数超过 50 行：

rules:
  - id: no-long-functions
    description: 函数体不应超过 50 行
    pattern: |
      def $FUNC(...):
          $BODY
    condition: |
      len($BODY.split('\n')) > 50
    message: 函数 {{$FUNC}} 超过 50 行，建议拆分
    severity: warning

团队可以将这份配置文件提交到仓库，所有成员的 IDE 插件和 CI 检查都会自动遵循同一套规则，无需各自手动配置。新人 clone 仓库后立刻获得与团队一致的代码审查体验，不需要额外学习成本。

不同规模团队的使用策略

个人开发者：安装免费版 VS Code 插件即可，开启 “Refactor only” 模式减少干扰，专注 Python 项目的实时重构建议。日常写代码时让 Sourcery 在后台运行，每完成一个函数手动触发一次检查。免费版对公开仓库完全无限制，个人开源项目零成本使用。

5-10 人小团队：订阅 Pro 版（$12/seat/月），将 .sourcery.yaml 提交到仓库统一规则，在 GitHub 安装 Sourcery App 实现 PR 自动审查。建议把 Sourcery 设为”建议者”而非”阻塞者”，避免 PR 流程卡顿。新人入职第一周强制使用 Sourcery 插件，借助实时反馈学习团队代码规范，两周内即可上手。

50+ 人企业团队：联系销售开通 Team/Enterprise 版，启用每日安全扫描（Team 档支持 200+ repos），配置 Bring Your Own LLM 使用自有 API Key 降低外部依赖。在 CI 流水线中加入 quality gate，未通过的 PR 不允许合并。同时利用自托管选项（Enterprise 档）满足数据合规要求，代码不离开内部网络。

CI/CD 集成指南

在 GitHub Actions 中集成 Sourcery CI 检查：

# .github/workflows/sourcery.yml
name: Sourcery Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install sourcery
      - run: sourcery review --check .
        env:
          SOURCERY_TOKEN: ${{ secrets.SOURCERY_TOKEN }}

配置后，每个 PR 都会自动触发 Sourcery 审查，在 PR 评论中列出改进建议。配合 .sourcery.yaml 中的阈值可以控制严格程度——设高则只报告严重问题，设低则覆盖所有建议。团队可以在 PR 模板中加入 @sourcery-bot 调用，让 Sourcery 给出整 PR 的变更摘要和高层反馈。

如果团队使用 GitLab CI，可以用类似方式在 .gitlab-ci.yml 中加入 sourcery review 命令，将输出解析为 MR 评论。对于 Jenkins 用户，可以在构建脚本中调用 sourcery review --json 输出 JSON 格式结果，再通过自定义脚本解析并展示在构建报告中。

安全扫描功能详解

Sourcery 的安全扫描是独立于代码重构的功能模块，覆盖常见 Python 安全漏洞：SQL 注入、硬编码密钥、不安全的反序列化、路径穿越等。Pro 版每两周扫描一次，Team 版每日扫描，结果汇总到 Dashboard 统一管理。

扫描结果按严重程度分级（Critical/High/Medium/Low），每条含漏洞描述、受影响代码位置和修复建议。与纯静态分析工具（如 Bandit）相比，Sourcery 的安全扫描基于 LLM 理解语义，能识别 Bandit 遗漏的上下文相关风险，例如变量追踪后的间接注入路径。

局限性：安全扫描目前仅支持 Python 项目，JS/TS 的安全扫描尚未上线。对于涉及敏感数据的场景，建议同时使用 Sourcery 安全扫描和专业 SAST 工具（如 Semgrep）形成纵深防御，单一工具无法覆盖所有安全场景。

常用快捷键与工作流优化

Sourcery 在 VS Code 中的常用操作都可以通过命令面板触发：

• Ctrl+Shift+P → Sourcery: Suggest Refactorings：对当前文件强制触发一次重构建议扫描
• Ctrl+Shift+P → Sourcery: Review File：一次性给出全文件的改进建议列表
• Ctrl+.：在光标位置查看所有可用的 Sourcery 快速修复（类似 ESLint 的 quick fix）
• Ctrl+Shift+P → Sourcery: Explain：选中代码后获取自然语言解释
• 右键 → “Sourcery: Skip Block”：用注释包裹当前代码块，排除检查

推荐工作流：写完一个函数后按 Ctrl+. 查看 Sourcery 建议，逐条评估是否采纳。对于团队规则禁止的模式，Sourcery 会直接标红提醒。定期运行 Review File 做全文件审查，在提交 PR 前用 Suggest Refactorings 做最后一轮检查，确保代码质量达标。

性能提示：Sourcery 的实时分析在大型文件（>1000 行）中可能略有延迟。如果感到卡顿，可以在设置中关闭实时分析改为手动触发。云端分析速度通常在 2-5 秒内返回结果，不会明显影响开发体验。

学习资源与进阶路径

Sourcery 官方文档（docs.sourcery.ai）包含完整的配置指南、规则列表和集成教程，是首选参考。GitHub 仓库的 Issues 区可以查看已知问题和功能请求，也能了解其他团队的使用经验。VS Code Marketplace 的评论区有用户反馈和实战技巧分享。

进阶学习路径建议分五步走：先跑通基本安装和实时建议，再配置 .sourcery.yaml 适配团队规则，然后集成 GitHub PR 审查，接着加入 CI quality gate，最后启用安全扫描。每一步验证通过后再进入下一步，避免一次性配置太多导致问题难以定位。遵循这个路径，一个 5 人团队通常在一周内即可完成全部集成。