mick-gsk/drift

AI 编码工具编写的代码虽然能运行，但并不总是合适。错误处理分散在 4 种模式中，层级边界被侵蚀，几乎相同的工具类在悄悄堆积。**Drift 正是为此而生：** 秒级确定性结构分析，无需 LLM。 ``` 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 能捕捉到什么 Drift 能发现 AI 生成代码悄悄引入的结构问题：同样的错误处理用了 4 种不同的方式，数据库导入泄露到了 API 层，6 个文件中存在几乎相同的辅助函数。这些问题能通过所有测试，却会让代码库更难以修改。 ### 立即尝试 ``` drift analyze --repo . # see your top findings drift explain PFS # learn what a signal means drift fix-plan --repo . # get actionable repair tasks ``` ### 添加到 CI（从仅报告开始） ``` - uses: mick-gsk/drift@v1 with: fail-on: none # report findings without blocking upload-sarif: "true" # findings appear as PR annotations ``` 一旦团队信任其输出，可以收紧策略：`fail-on: high`。 更多信息：[快速开始](docs-site/getting-started/quickstart.md) · [示例发现](docs-site/product/example-findings.md) ·[团队推广](docs-site/getting-started/team-rollout.md) ## AI 辅助工作流 Drift 可与 AI 编码会话（Copilot、Cursor、Claude）及支持 MCP 的编辑器集成： ``` drift scan --repo . --max-findings 5 # session baseline for agents drift diff --staged-only # pre-commit check drift mcp --serve # MCP server for IDE integration drift fix-plan --repo . # agent-friendly repair tasks ``` 完整设置：[集成](docs-site/integrations.md) · [MCP](docs-site/integrations.md) · [Vibe-Coding 指南](examples/vibe-coding/README.md) ## 团队为何使用 Drift 你的 linter、type checker 和测试套件可以告诉你代码是否有效。它们无法告诉你代码库是否正悄然分裂成跨模块的不兼容模式。 Drift 专注于这一缺口： - **Ruff / formatters / type checkers：** 关注局部正确性和风格，而非跨模块一致性。 - **Semgrep / CodeQL / security scanners：** 关注风险流和策略违规，而非架构一致性。 - **可维护性仪表板：** 关注广泛的质量启发式指标，而非具有可复现信号系列的 drift 专用评分。 当前公开证据：研究语料库包含 15 个真实代码库，22 个信号系列（15 个评分活跃，7 个仅报告），以及可在运行时重新平衡权重的自动校准。[完整研究 →](docs/STUDY.md) · [信任与局限](docs-site/benchmarking.md) ## 使用场景 ### 连接器层中的模式碎片化 **问题：** 一个 FastAPI 服务有 4 个连接器，每个都实现了不同的错误处理方式 —— 裸 `except`、自定义异常、重试装饰器和静默回退。 **解决方案：** ``` drift analyze --repo . --sort-by impact --max-findings 5 ``` **输出：** 评分为 0.96 的 PFS 发现 —— “connectors/ 中存在 26 种 error_handling 变体” —— 确切显示哪些文件存在分歧并建议合并。 ### Monorepo 中的架构边界违规 **问题：** 一个数据库模型文件直接从 API 层导入，造成了破坏测试隔离的循环依赖。 **解决方案：** ``` drift check --fail-on high ``` **输出：** AVS 发现 —— “src/api/auth.py:18 处的 API 层中存在 DB 导入” —— 阻塞 CI 流水线，直到修复导入方向。 ### 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: mick-gsk/drift@v1 with: fail-on: none # report findings without blocking CI upload-sarif: "true" # findings appear as PR annotations ``` 一旦团队在几个 Sprint 中审查了发现结果，收紧关卡： ``` - uses: mick-gsk/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 hook 将 drift 添加到工作流的最快方式： ``` # .pre-commit-config.yaml repos: - repo: https://github.com/mick-gsk/drift rev: v1.4.2 hooks: - id: drift-check # blocks on high-severity findings # - id: drift-report # report-only alternative (start here) ``` 或者如果你已经安装了 drift，使用本地 hook： ``` # .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) 项目运作： - [贡献者指南](CONTRIBUTING.md) - [开发者指南](DEVELOPER.md) - [维护者手册](docs/MAINTAINER_RUNBOOK.md) - [代码库治理](docs/REPOSITORY_GOVERNANCE.md) 如果你想在集成前查看示例发现，请从 [docs-site/product/example-findings.md](docs-site/product/example-findings.md) 开始。 ## 全部 22 个信号 Drift 对 22 个信号系列进行评分（15 个评分活跃，7 个仅报告）—— 从模式碎片化和架构违规到时间波动性、默认安全检查和同变更耦合。每个发现都包含严重性、文件位置和具体的后续操作。 `drift explain ` 显示任何信号检测到的内容以及如何修复它。 [信号参考](docs-site/algorithms/signals.md) · [算法深入解析](docs-site/algorithms/deep-dive.md) · [评分模型](docs-site/algorithms/scoring.md) Agent 输出参考：[负向上下文](docs-site/reference/negative-context.md) ## Drift 对比 数据来源于 [STUDY.md](docs/STUDY.md) §9 和 [benchmark_results/](benchmark_results/)。 | Capability | drift | SonarQube | pylint / mypy | jscpd / CPD | |---|:---:|:---:|:---:|:---:| | Pattern Fragmentation across modules | Yes | No | No | No | | Near-Duplicate Detection | Yes | Partial (text) | No | Yes (text) | | Architecture Violation signals | Yes | Partial | No | No | | Temporal / change-history signals | Yes | No | No | No | | GitHub Code Scanning via SARIF | Yes | Yes | No | No | | Zero server setup | Yes | No | Partial | Yes | | TypeScript Support | Optional ¹ | Yes | No | Yes | ¹ 通过 `drift-analyzer[typescript]` 实验性支持。Python 是主要目标。 Drift 旨在**补充** linter 和安全扫描工具，而非取代它们。推荐技术栈：linter（风格）+ type checker（类型）+ drift（一致性）+ 安全扫描工具（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 旨在通过确定性和可复现性赢得信任： - 检测管道中不包含 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) ## 测试质量 - **1 645+ 测试**，0 回归 - **变异杀死率：100 %**（23/23 变异体已杀死） - 所有 5 个核心信号（PFS、AVS、MDS、EDS、GCD）达到 100 % - 基线：[`benchmark_results/mutation_baseline.json`](benchmark_results/mutation_baseline.json) ## 发布状态 PyPI 分类器为 `Development Status :: 4 - Beta`。 核心分析和 CI 工作流稳定；一些相邻表面仍被有意标记为实验性。 当前发布态势： - 核心 Python 分析：稳定 - CI 和 SARIF 工作流：稳定 - TypeScript 支持：实验性 - 基于 embeddings 的部分：可选 / 实验性 - 基准方法论：演进中 完整理由和矩阵：[稳定性与发布状态](docs-site/stability.md) ## 贡献 Drift 最大的盲点是由在维护者从未见过的代码库上运行它的人发现的。**你的真实世界经验是对信号质量的直接贡献** —— 无论你是否编写代码。 如果 Drift 给出了一个令你意外的结果，那就是有价值的反馈：[提出 Issue](https://github.com/mick-gsk/drift/issues) 或发起一个 [讨论](https://github.com/mick-gsk/drift/discussions)。一个记录详尽的假阳性可能比一个新功能更有价值。 | 我想… | 前往这里 | |---|---| | 提出使用问题 | [Discussions](https://github.com/mick-gsk/drift/discussions) | | 报告假阳性 / 假阴性 | [FP/FN template](https://github.com/mick-gsk/drift/issues/new?template=false_positive.md) | | 报告 Bug | [Bug report](https://github.com/mick-gsk/drift/issues/new?template=bug_report.md) | | 建议功能 | [Feature request](https://github.com/mick-gsk/drift/issues/new?template=feature_request.md) | | 在编码前提出贡献 | [Contribution proposal](https://github.com/mick-gsk/drift/issues/new?template=contribution_proposal.md) | | 报告安全漏洞 | [SECURITY.md](SECURITY.md) — 非公开 Issue | ### 新手？开始贡献 你不需要理解整个分析器就能提供帮助。从适合你时间的层级开始： 1. **15 分钟：** 修复拼写错误或阐明文档示例 → 直接提 PR 2. **30 分钟：** 报告带有复现步骤的意外发现 → [FP/FN template](https://github.com/mick-gsk/drift/issues/new?template=false_positive.md) 3. **1 小时：** 添加边缘情况测试 → 领取一个 [`good first issue`](https://github.com/mick-gsk/drift/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 4. **2+ 小时：** 改进信号逻辑或发现解释 → 参阅 [CONTRIBUTING.md](CONTRIBUTING.md) ``` git clone https://github.com/mick-gsk/drift.git && cd drift && make install make test-fast # confirm everything passes, then start ``` **第一次贡献？我们会帮你界定范围。** 如果你不确定从哪里开始，请提出 [贡献提案](https://github.com/mick-gsk/drift/issues/new?template=contribution_proposal.md) 或在 [讨论区](https://github.com/mick-gsk/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)。

标签：Agent, AI代码生成, LNA, MCP, Python, SARIF, 代码结构分析, 技术债务, 数据管道, 无后门, 架构腐化检测, 架构违规, 模式碎片化, 确定性行分析, 软件工程, 软件架构, 逆向工具, 重复代码检测, 错误基检测, 静态代码分析