sauremilk/drift

``` pip install drift-analyzer drift analyze --repo . ``` ``` ╭─ drift analyze myproject/ ──────────────────────────────────────────────────╮ │ DRIFT SCORE 0.52 Δ -0.031 ↓ improving │ 87 files │ AI: 34% │ 2.1s │ ╰──────────────────────────────────────────────────────────────────────────────╯ Module Score Bar Findings Top Signal src/api/routes/ 0.71 ██████████████░░░░░░ 12 PFS 0.85 src/services/auth/ 0.58 ███████████░░░░░░░░░ 7 AVS 0.72 src/db/models/ 0.41 ████████░░░░░░░░░░░░ 4 MDS 0.61 ◉ PFS 0.85 Error handling split 4 ways → src/api/routes.py:42 → Next: consolidate into shared error handler ◉ AVS 0.72 DB import in API layer → src/api/auth.py:18 → Next: move DB access behind service interface ``` ## 从这里开始 Drift 能够发现 AI 生成的代码悄悄引入的架构侵蚀：模式碎片化、边界违规、近重复工具，以及通过了测试但削弱了代码库的结构热点。 专为希望在分析路径中不引入 LLM 即可获得快速结构反馈的 Python 团队而设计。 ### 三种好的开始方式 - **运行：** [快速入门](docs-site/getting-started/quickstart.md) 和 [配置](docs-site/getting-started/configuration.md) - **评估：** [示例发现](docs-site/product/example-findings.md)、[信任与证据](docs-site/trust-evidence.md)、[稳定性](docs-site/stability.md) - **贡献：** [CONTRIBUTING.md](CONTRIBUTING.md)、[DEVELOPER.md](DEVELOPER.md)、[POLICY.md](POLICY.md) ### CI（从仅报告开始，之后再收紧） ``` - uses: sauremilk/drift@v1 with: fail-on: none upload-sarif: "true" ``` ## Vibe-Coding 工作流 为 AI 辅助的编码会话而构建，在这些会话中 LLM 编写大部分代码，而你来掌控方向。 ``` drift scan --repo . --max-findings 5 # session start: agent learns baseline drift diff --uncommitted # before commit drift diff --staged-only # index only drift diff --diff-ref main # compare against main drift check --repo . --fail-on high # CI gate ``` 每次调用都会返回 `accept_change: true | false`，并附带 agent 可以直接处理的原因。 ## MCP 集成 Drift 可以作为 MCP (Model Context Protocol) 服务器运行，这样 AI agent 就可以直接通过 stdio 调用分析工具。 安装 MCP 支持： ``` pip install drift-analyzer[mcp] ``` 启动服务器： ``` drift mcp --serve ``` 在 `.vscode/mcp.json` 中的最小 VS Code 设置： ``` { "servers": { "drift": { "type": "stdio", "command": "drift", "args": ["mcp", "--serve"] } } } ``` 常见的 agent 原生调用： ``` drift scan --repo . drift diff --staged-only drift validate --repo . drift fix-plan --repo . ``` 详见 [集成](docs-site/integrations.md) 和 [API 与输出](docs-site/reference/api-outputs.md)。 ### CI ``` - run: drift check --repo . --fail-on high ``` 相同的信号，相同的确定性引擎 —— 分析时不涉及 LLM。 ## 为什么团队使用 drift 你的 linter、类型检查器和测试套件可以告诉你代码是否有效。它们不会告诉你仓库是否正悄悄分裂成跨模块的不兼容模式。 Drift 专注于这个盲区： - **Ruff / formatters / type checkers：** 局部的正确性和风格，而非跨模块的一致性。 - **Semgrep / CodeQL / security scanners：** 有风险的流程和策略违规，而非架构一致性。 - **可维护性仪表板：** 宽泛的质量启发式指标，而非带有可重现信号族的特定漂移得分。 当前的公开证据：研究语料库中有 15 个真实世界的代码仓库，15 个评分信号，以及在 runtime 重新平衡权重的自动校准机制。[完整研究 →](docs/STUDY.md) · [信任与局限性](docs-site/benchmarking.md) ## 使用场景 ### 连接器层中的模式碎片化 **问题：** 一个 FastAPI 服务有 4 个 connector，每个都以不同的方式实现错误处理 —— 裸 `except`、自定义异常、重试装饰器和静默回退。 **解决方案：** ``` drift analyze --repo . --sort-by impact --max-findings 5 ``` **输出：** 得分为 0.96 的 PFS 发现 —— “connectors/ 中有 26 个 error_handling 变体” —— 准确显示哪些文件存在偏差并建议进行整合。 ### 单体仓库中的架构边界违规 **问题：** 一个数据库模型文件直接从 API 层导入，造成了破坏测试隔离的循环依赖。 **解决方案：** ``` drift check --fail-on high ``` **输出：** AVS 发现 —— “API 层在 src/api/auth.py:18 处存在 DB 导入” —— 阻塞 CI pipeline，直到修复导入方向。 ### AI 生成脚手架产生的重复工具代码 **问题：** AI 代码生成在独立的任务文件中创建了 6 个相同的 `_run_async()` 辅助函数，而不是去寻找已有的共享工具。 **解决方案：** ``` drift analyze --repo . --format json | jq '.findings[] | select(.signal=="MDS")' ``` **输出：** MDS 发现列出了所有 6 个位置，相似度得分 ≥ 0.95，从而实现单次的“提取至共享模块”重构。 ## 设置与推行方案 ### 完整 GitHub Action（推荐：从仅报告开始） ``` name: Drift on: [push, pull_request] jobs: drift: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: sauremilk/drift@v1 with: fail-on: none # report findings without blocking CI upload-sarif: "true" # findings appear as PR annotations ``` 一旦团队在几个 sprint 中审查了这些发现，就可以收紧门禁： ``` - uses: sauremilk/drift@v1 with: fail-on: high # block only high-severity findings upload-sarif: "true" ``` ### CI 门禁（本地） ``` drift check --fail-on none # report-only drift check --fail-on high # block on high-severity findings ``` ### pre-commit 钩子 将 drift 添加到工作流的最快方法： ``` # .pre-commit-config.yaml repos: - repo: https://github.com/sauremilk/drift rev: v0.10.2 hooks: - id: drift-check # blocks on high-severity findings # - id: drift-report # report-only alternative (start here) ``` 或者在你已经安装了 drift 的情况下使用本地钩子： ``` # .pre-commit-config.yaml repos: - repo: local hooks: - id: drift name: drift entry: drift check --fail-on high language: system pass_filenames: false always_run: true ``` 更多设置路径： - [快速入门](docs-site/getting-started/quickstart.md) - [配置](docs-site/getting-started/configuration.md) - [团队推行](docs-site/getting-started/team-rollout.md) 如果你想在集成前查看示例发现，请从 [docs-site/product/example-findings.md](docs-site/product/example-findings.md) 开始。 ## 你会得到什么 ``` ╭─ drift analyze myproject/ ──────────────────────────────────────────────────╮ │ DRIFT SCORE 0.52 Δ -0.031 ↓ improving │ 87 files │ AI: 34% │ 2.1s │ ╰──────────────────────────────────────────────────────────────────────────────╯ Trend: 0.551 → 0.548 → 0.520 (3 snapshots) Module Drift Ranking Module Score Bar Findings Top Signal ───────────────────────────────────────────────────────────────────────────────── src/api/routes/ 0.71 ██████████████░░░░░░ 12 PFS 0.85 src/services/auth/ 0.58 ███████████░░░░░░░░░ 7 AVS 0.72 src/db/models/ 0.41 ████████░░░░░░░░░░░░ 4 MDS 0.61 ┌──┬────────┬───────┬──────────────────────────────────────┬──────────────────────┐ │ │ Signal │ Score │ Title │ Location │ ├──┼────────┼───────┼──────────────────────────────────────┼──────────────────────┤ │◉ │ PFS │ 0.85 │ Error handling split 4 ways │ src/api/routes.py:42 │ │◉ │ AVS │ 0.72 │ DB import in API layer │ src/api/auth.py:18 │ │○ │ MDS │ 0.61 │ 3 near-identical validators │ src/utils/valid.py │ └──┴────────┴───────┴──────────────────────────────────────┴──────────────────────┘ ``` Drift 对 15 个信号族进行评分。有关完整列表、权重和评分细节，请参见： - [信号参考](docs-site/algorithms/signals.md) - [算法深入解析](docs-site/algorithms/deep-dive.md) - [评分模型](docs-site/algorithms/scoring.md) ## drift 的对比 数据来源于 [STUDY.md](docs/STUDY.md) §9 和 [benchmark_results/](benchmark_results/)。 | 功能 | drift | SonarQube | pylint / mypy | jscpd / CPD | |---|:---:|:---:|:---:|:---:| | 跨模块的模式碎片化 | 是 | 否 | 否 | 否 | | 近重复检测 | 是 | 部分 (文本) | 否 | 是 (文本) | | 架构违规信号 | 是 | 部分 | 否 | 否 | | 时间 / 变更历史信号 | 是 | 否 | 否 | 否 | | 通过 SARIF 进行 GitHub Code Scanning | 是 | 是 | 否 | 否 | | 零服务器设置 | 是 | 否 | 部分 | 是 | | TypeScript 支持 | 可选 ¹ | 是 | 否 | 是 | ¹ 通过 `drift-analyzer[typescript]` 提供，尚处于实验阶段。Python 是主要目标。 Drift 旨在**补充** linter 和安全扫描工具，而不是取代它们。推荐技术栈：linter (风格) + type checker (类型) + drift (一致性) + security scanner (SAST)。 完整对比：[STUDY.md §9 — 工具全景对比](docs/STUDY.md) ## drift 适合你吗？ Drift 非常适合以下场景： - 在注重架构的仓库中使用 AI 编码工具的 Python 团队 - 拥有 20 个以上文件且经常进行跨模块重构的代码库 - 希望在本地运行和 CI 中获得确定性架构反馈的团队 如果符合以下情况，请谨慎开始或暂缓使用： - 代码库非常小，少数发现就会主导整体得分 - 你需要的是缺陷查找、安全审查或类型安全强制执行，而不是结构分析 - 你的本地和 CI 执行路径中尚不支持 Python 3.11+ 最安全的推行路径是循序渐进的： 1. 首先在本地运行 `drift analyze` 并审查最重要的发现。 2. 在 CI 中添加 `drift check --fail-on none` 作为仅报告的规范。 3. 在团队理解了输出内容之后，仅针对 `high`（高）级别的发现设置门禁。 4. 在审查了代码库中的真实发现后，忽略生成的或供应商的代码，并仅在此基础上调整配置。 推荐指南： - [团队推行](docs-site/getting-started/team-rollout.md) - [发现分类](docs-site/getting-started/finding-triage.md) - [基准测试与信任](docs-site/benchmarking.md) ## 信任与局限性 Drift 旨在通过确定性和可重现性赢得信任： - 检测 pipeline 中不使用 LLM - 可重现的 CLI 和 CI 输出 - 针对特定信号的解释，而非纯分数信息 - 明确的基准测试和已知局限性的文档 ### 解读得分 Drift 得分衡量的是**结构熵**，而非代码质量。请牢记以下原则： - **解读增量，而不是快照。** 使用 `drift trend` 随时间跟踪变化。孤立的单一得分意义有限。 - **在迁移期间得分出现暂时性增长是正常的。** 共存的两种模式（新旧）将引发 PFS/MDS 信号。这是正在发生的迁移，而不是一个问题。 - **深思熟虑的多态性不是侵蚀。** Strategy、Adapter 和 Plugin 模式会产生被 MDS 标记为重复的结构相似性。发现中包含一个 `deliberate_pattern_risk` 提示 —— 在采取行动前请验证意图。 - **该得分奖励的是结构的减少，而非正确性。** 删除代码会像重构一样降低得分。不要为了低分而优化 —— 应为了可理解的、有意图的结构而优化。 有关认识论边界（drift 能看到和不能看到的内容）的详细讨论，请参见 [STUDY.md §14](docs/STUDY.md)。 从最有力、最具可操作性的发现开始。如果某个信号对你的代码库结构来说干扰太大，请调整它或降低其权重，而不是强行设置过早的严格门禁。 延伸阅读： - [基准测试与信任](docs-site/benchmarking.md) - [完整研究](docs/STUDY.md) - [案例研究](docs-site/case-studies/index.md) ## 发布状态 PyPI 分类器有意保持为 `Development Status :: 3 - Alpha`。 这是一个保守的发布信号，而不是说核心工作流不可用。当前最稳妥的路径是确定性的 Python 分析和仅报告的 CI 推行；一些周边功能仍被有意标记为实验性的。 当前的发布态势： - 核心 Python 分析：稳定 - CI 和 SARIF 工作流：稳定 - TypeScript 支持：实验性 - 基于 embeddings 的部分：可选 / 实验性 - 基准测试方法：发展中 完整理由和矩阵：[稳定性与发布状态](docs-site/stability.md) ## 贡献 Drift 最大的盲区是由那些在维护者从未见过的代码库上运行它的人发现的。**你的真实世界经验是对信号质量的直接贡献** —— 无论你是否编写代码。 如果 Drift 给出了一个让你意外的结果，那这就是有价值的反馈：[发起一个 issue](https://github.com/sauremilk/drift/issues) 或发起一次 [讨论](https://github.com/sauremilk/drift/discussions)。一份记录详实的假阳性可能比一个新功能更有价值。 | 我想… | 前往这里 | |---|---| | 提出使用问题 | [讨论](https://github.com/sauremilk/drift/discussions) | | 报告假阳性 / 假阴性 | [FP/FN 模板](https://github.com/sauremilk/drift/issues/new?template=false_positive.md) | | 报告 Bug | [Bug 报告](https://github.com/sauremilk/drift/issues/new?template=bug_report.md) | | 提出新功能建议 | [功能请求](https://github.com/sauremilk/drift/issues/new?template=feature_request.md) | | 在编写代码前提出贡献意向 | [贡献提案](https://github.com/sauremilk/drift/issues/new?template=contribution_proposal.md) | | 报告安全漏洞 | [SECURITY.md](SECURITY.md) — 而不是公开的 issue | ### 新手？从这里开始贡献 你不需要理解整个分析器就能提供帮助。请从适合你时间安排的层次开始： 1. **15 分钟：** 修复错别字或阐明文档示例 → 直接提交 PR 2. **30 分钟：** 带着复现步骤报告一个意外的发现 → [FP/FN 模板](https://github.com/sauremilk/drift/issues/new?template=false_positive.md) 3. **1 小时：** 添加一个边缘情况测试 → 挑选一个 [`good first issue`](https://github.com/sauremilk/drift/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 4. **2 小时以上：** 改进信号逻辑或发现解释 → 参见 [CONTRIBUTING.md](CONTRIBUTING.md) ``` git clone https://github.com/sauremilk/drift.git && cd drift && make install make test-fast # confirm everything passes, then start ``` **首次贡献？我们会帮你界定范围。** 如果你不确定从哪里开始，请发起一个 [贡献提案](https://github.com/sauremilk/drift/issues/new?template=contribution_proposal.md) 或在 [讨论区](https://github.com/sauremilk/drift/discussions) 提问。 **典型的首次贡献：** - 带着复现步骤报告假阳性或假阴性 - 为信号的边缘情况添加真实基准 fixture - 改进某个发现的解释文本，使其更具可操作性 - 为未测试的边缘情况编写测试 - 完善文档或添加配置示例 **我们最看重的：** 可重现性、可解释性、误报减少**我们会降低优先级的：** 没有洞察价值的输出格式、舒适性功能、不能提升分析质量的复杂性。 完整指南、贡献者类型和贡献阶梯请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。当前优先级请参见 [ROADMAP.md](ROADMAP.md)。 ## 文档导航 - [入门指南](docs-site/getting-started/quickstart.md) - [工作原理](docs-site/algorithms/deep-dive.md) - [基准测试与信任](docs-site/benchmarking.md) - [产品策略](docs-site/product-strategy.md) - [贡献者指南](CONTRIBUTING.md) - [开发者指南](DEVELOPER.md) ## 许可证 MIT。详见 [LICENSE](LICENSE)。

标签：AI代码治理, AI生成代码检测, DevSecOps, Python, SARIF, 上游代理, 代码安全, 代码审查工具, 变异重复代码, 技术债务治理, 数据管道, 无后门, 架构侵蚀, 架构违规, 模式碎片化, 漏洞枚举, 确定性分析, 软件工程, 错误基检测, 静态代码分析