vyuh-labs/dxkit

# dxkit **AI 编写代码。dxkit 助您整洁交付。** _为任何代码库提供确定性护栏。默认支持老旧项目 (Brownfield)。_ dxkit 会确定性地为您的代码库评分，将当前的检测结果作为基线，并在每次推送时拦截新增的回归问题。它提供对话式技能，引导 AI 代理（和人类）完成修复。现有的技术债务会被保留并豁免。它完全不依赖 LLM 运行。所有操作均在本地执行。

``` npm init @vyuhlabs/dxkit ```

## 问题所在 代码库的衰退往往是渐进的，测试通常无法捕捉到这些问题。 一个典型的星期五。您的团队发布了一个修复。CI 通过了。代码审查也批准了。两周后，审计人员在 diff 中发现了一个新的硬编码密钥、三个未经测试的新分支，以及一个原本整洁的文件膨胀到了 800 行，还夹杂着三个 TODO。这些都没有导致测试失败，因为根本没有测试覆盖这些内容。 现在，将这种情况乘以您的团队使用的每一个 AI 代理。代理编写的代码数量超出了人类的审查能力。其中一部分没问题。另一部分则是表面上看起来没问题，但实际上却在悄悄破坏代码库的劣质代码。 常规的解决方案是“通过静态分析拦截任何新发现的缺陷”。但在真实的代码库中，这会因为一个可预见的原因而失败： - 如果拦截所有缺陷，您那拥有 5 年历史的代码库会瞬间暴露出数百个遗留问题。团队不到一周就会关闭这个拦截机制。 - 如果一个都不拦截，这个拦截机制就成了摆设。什么都不会改变。 您需要一个仅针对真正新增的问题触发的客观拦截机制。这正是 dxkit 所填补的空白。 ## dxkit 如何解决它 三个理念协同工作。 ### 1. 将当前状态捕获为基线 在 dxkit 拦截任何内容之前，它会为代码库中现有的每一个发现建立快照并生成指纹。这些指纹能够在文件重命名、格式化工具导致的行号偏移以及微小的无关编辑后依然有效。跨工具的重复结果（例如 gitleaks 和 semgrep 标记了同一行代码）会合并为一个结果。 从这一刻起，拦截机制仅针对新增的回归问题触发。您现有的技术债务会被豁免。团队可以按照自己的节奏修复旧问题。因为保持了合理性，拦截机制也始终有效。 基线文件提供三种模式： - `committed-full`：包含丰富细节的条目提交到 git 中。私有仓库的默认选项。 - `committed-sanitized`：精简为仅包含指纹和类型。适用于对合规性要求严格的团队。 - `ref-based`：完全不提交文件。通过 `git worktree add` 从 git ref 重新计算前序状态。公开仓库的默认选项。零信息暴露面。 ### 2. 确定性地为代码库评分 dxkit 会从六个维度生成 0 到 100 的评分：安全性、代码质量、测试、文档、可维护性和开发者体验。 该评分具有四个属性： | 属性 | 含义 | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **确定性** | 相同的代码每次都会得出相同的分数。评分过程中不使用 LLM。可在不同机器、运行和 CI 之间复现。可审计。 | | **可比性** | 质量相似的两个代码库会产生相似的分数。表面技巧无法改变分数。如果代码没有真正被记录文档，添加空洞的注释并不能提高文档评分。 | | **严重性加权** | 严重的安全漏洞对分数的影响远大于 TODO 注释。惩罚机制通过安全性的 CVSS 和测试、覆盖率、文件大小及其他维度的比例阈值，锚定到真实世界的影响程度上。 | | **可操作性** | 每项扣分都会明确指出文件、行号和建议的修复方案。输出为结构化 JSON。代理和人类读取的内容完全一致。“下一步该做什么”直接包含在分数本身中。 | ### 3. 以更低的 token 成本修复缺陷 检测只是工作的一半。dxkit 会构建代码库的确定性代码图谱（包括其符号、调用边和聚类模块），因此修复成本也很低。编程代理可以基于这种结构工作（“谁调用了这个？如果我修改它会破坏什么？”），而不是重新阅读整个文件，并且详细报告中的每一个缺陷都已经标明了其影响范围：依赖于它的文件。`dxkit-action` 技能会执行修复、重新评分并确认是否通过拦截机制。结果相同，但消耗的 token 大幅减少。 ### 这种组合带来的收益 单独的评分只是一个数字。单独的基线只是豁免了过去的遗留问题。两者结合在一起，就能产生一个您可以信任的客观叫停信号。 ``` Today: 16/100 E 644 findings, all baselined Next PR: 16/100 E 644 persisted, 0 new. Gate passes. Bad PR: 14/100 E 644 persisted, 2 new high-severity. Gate blocks. ``` 评分不会说谎。基线使其在真实的代码库中保持实用。这种组合对人类、AI 代理和 CI 运行器的作用方式完全相同。这才是能够规模化扩展的关键。一旦拦截机制触发，代码图谱就能让采取行动的成本变得低廉：代理可以基于结构进行修复，而不是逐个阅读文件。 ## 60秒演示 ``` $ npm init @vyuhlabs/dxkit ✓ Created: 14 files ✓ Git hooks: installed 1 file(s) .githooks/pre-push ✓ Devcontainer: installed 3 file(s) ✓ CI guardrails workflow: installed 1 file(s) .github/workflows/dxkit-guardrails.yml ✓ Done! Claude Code now has full project context. → Next: run `vyuh-dxkit baseline create` to capture today's state. $ npx vyuh-dxkit baseline create → Baseline mode=committed-full (auto: visibility not detectable via gh; defaulting to private posture) ✓ Wrote .dxkit/baselines/main.json — 644 findings, salt: deterministic (208.9s) $ npx vyuh-dxkit guardrail check ## Guardrail: PASSED No changes from baseline (644 pairs checked). ``` 随后，一个看起来无害的 PR 混入了一个回归问题。Pre-push 钩子被触发： ``` $ git push [hook] vyuh-dxkit guardrail check ## Guardrail: BLOCKED 2 new regressions found. | Status | Kind | Severity | Location | Reason | |---|---|---|---|---| | added | secret | high | src/config/secrets.ts:42 | gitleaks/aws-access-key | | added | code | medium | src/handlers/exec.ts:17 | semgrep/eval-use | 644 pre-existing findings persisted. Only the new changes blocked you. Fix or allowlist with `npx vyuh-dxkit allowlist add ...` ``` 原有的 644 个缺陷保持沉默。新增的 2 个缺陷阻止了推送。 ## 功能特性 ### 八种一等公民语言包 TypeScript / JavaScript、Python、Go、Rust、C# / .NET、Java、Kotlin、Ruby。每个包都附带了针对特定生态系统的分析器：semgrep 规则集、依赖漏洞扫描器、许可证工具和 lint 适配器。多语言仓库无需配置即可获得统一的报告。

各语言包功能 (点击展开)

| 语言 | 检测方式 | 覆盖率导入 | 导入图型 | 原生工具 | Lint 严重性级别 | 漏洞严重性级别 | | -------- | ------------------------------------- | ------------------- | -------------------------------------------- | ----------------------------------- | ---------------------- | --------------------------------------------- | | TS / JS | `package.json` | ✅ Istanbul | ✅ import/require/re-export | eslint, npm audit, vitest-coverage | ✅ ESLint rule ID | ✅ npm audit native | | Python | `pyproject.toml`, `setup.py`, `*.py` | ✅ coverage.py | ✅ import/from | ruff, pip-audit, coverage | ✅ ruff code prefix | ✅ pip-audit + OSV.dev (CVSS v3+v4) | | Go | `go.mod` | ✅ coverprofile | ✅ import blocks | golangci-lint, govulncheck | ✅ `FromLinter` family | ✅ govulncheck embedded + OSV.dev | | Rust | `Cargo.toml` | ✅ lcov + cobertura | ⚠️ use statements, extracted only¹ | clippy, cargo-audit, cargo-llvm-cov | ✅ clippy group | ✅ cargo-audit native | | C# | `*.csproj`, `*.sln` | ✅ cobertura XML | ⚠️ using declarations, extracted only¹ | dotnet-format (formatter) | ⚠️ format-only² | ✅ dotnet list --vulnerable | | Kotlin | gradle/`*.gradle{.kts,}`, `*.kt` | ✅ JaCoCo XML | ⚠️ import statements, extracted only¹ | detekt, osv-scanner (Maven) | ✅ detekt severity | ✅ osv-scanner + OSV.dev (Maven) | | Java | `pom.xml`, `src/main/java/`, `*.java` | ✅ JaCoCo XML | ⚠️ import statements, extracted only¹ | PMD, osv-scanner (Maven) | ✅ PMD priority tiers | ✅ osv-scanner + OSV.dev (Maven) | | Ruby | `*.rb` | ✅ SimpleCov JSON | ⚠️ require/require_relative, extracted only¹ | rubocop, bundler-audit, osv-scanner | ✅ rubocop severity | ✅ bundler-audit + osv-scanner (Gemfile.lock) | ¹ Rust、C#、Kotlin、Java 和 Ruby 会填充 `imports.extracted`，但 文件级别的解析器是空操作。对于这些语言包，需要边图型的下游分析 （可达性、导入图型测试缺口评估）会降级为保守的 默认值。解析器已列入[路线图](docs/roadmap.md)。 ² C# 仅使用 `dotnet-format` 进行格式化违规检测。真正的 具备严重性层级的 C# linter（Roslyn analyzers 或 StyleCop）已列入 路线图。目前，每个 C# 格式化违规都会被计入 `low` 层级， 以免使其导致代码质量分数虚高。

### 匹配器 多维度指纹（位置、领域、内容、语义）可在文件重命名、行号偏移、工具版本更改或分支被强制推送的情况下，依然跨运行匹配缺陷。当位置匹配失败时，匹配器会回退到 git 感知的 diff 查找，然后是内容哈希，最后是仅限标识的多重集匹配。每一对匹配都带有一个置信度分数和一条原因链。 ### 按缺陷豁免 五种分类类型：`false-positive`（误报）、`test-fixture`（测试夹具）、`mitigated-externally`（已外部缓解）、`accepted-risk`（已接受风险）、`deferred`（已推迟）。每个条目都需要填写理由。随时间推移失效的分类需要设置有效期。 两种使用方式： - 内联注解：`// dxkit-allow:test-fixture reason="example placeholder"` - 文件级别：`.dxkit/allowlist.json`，通过 `vyuh-dxkit allowlist audit` 进行审计 孤立的注解会变成新的缺陷。这类似于将 TypeScript 的 `@ts-expect-error` 模型应用于豁免机制。从而防止产生大量陈旧的允许列表条目。 ### AI 代理集成 dxkit 在 `.claude/skills/dxkit-*` 下提供了一套 Claude Code 技能。它们将 CLI 封装为对话式流程： | Skill | 功能 | | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `dxkit-onboard` | 引导客户完成完整的首次安装旅程 | | `dxkit-reports` | 运行分析器并解释输出 | | `dxkit-action` | 读取报告，确定缺陷优先级，计划并运行修复，重新验证 | | `dxkit-ingest` | 将外部 SAST 缺陷（Snyk Code, CodeQL, SARIF）引入 dxkit | | `dxkit-fix` | 根据 doctor 的输出修复损坏的安装 | | `dxkit-allowlist` | 管理豁免生命周期：审计、移除、清理、导出到 Snyk | | `dxkit-test` | 编写缺失的测试以填补空白 + 提高测试分数 | | `dxkit-pr` | 开启一个包含以 diff 为依据的内容 + dxkit 信号 + 审查者清单的 PR | | `dxkit-feature`, `dxkit-docs`, `dxkit-hooks`, `dxkit-config`, `dxkit-learn`, `dxkit-update`, `dxkit-init` | 专注的特定流程 | 每次安装时也都会附带 `AGENTS.md`（这是 Codex、Cursor、Aider 等工具读取的开放标准）。目前技能流程是 Claude Code 专用的；但 AGENTS.md 上下文是可移植的。 这对于 AI 工作流至关重要：当代理修复 bug 时，您需要一个客观的信号来表明“是的，已经彻底修复了”或者“此次修复引入了四个新的回归问题”。dxkit 的确定性评分加上基线护栏就能产生这种信号。代理读取与人类相同的 JSON 封装数据，自行运行验证步骤，并在确认无误后停止。 ### 代码图谱上下文：以更低的 token 成本进行修复 dxkit 使用 graphify（`graphifyy` Python 包）构建代码库的确定性代码图谱（包括其符号、调用边和聚类模块）。重要的是代理能用它做什么。代理无需通过到处 grep 和阅读整个文件来发现结构，而是直接获取相关的切片信息： - **`vyuh-dxkit context `**（以及一个可选择的 PreToolUse 钩子）为代理提供了一个精简的结构图：相关的符号、它们的位置以及调用它们的代码。它通过图谱进行导航，而不是重新阅读文件，这在只消耗一小部分 token 的情况下完成了相同的工作。 - **`--graph-context`** 将每个缺陷所在的模块及其影响范围（哪些文件调用了它）直接写入详细报告中，这样 `dxkit-action` 修复技能就可以计划修改，并知道需要重新测试哪些调用者，而无需重新发现结构。 - **`vyuh-dxkit explore`** 和仪表板的图谱标签页让人类可以查询相同的，了解代码库的功能、某个特性在哪里，以及哪些文件是关键的承载文件。 这是一个附加的、失败时放行的层。当图谱缺失或无法解析某种语言的调用边时，每个命令的行为都与之前完全相同。它在 TypeScript、Python 和 Go 上是可靠的。在无法解析调用图的地方（如 C#），影响范围会被隐藏而不是被伪造，因此“没有调用者”的读取结果绝不会被误认为是“修改是安全的”。 ### 将缺陷和 PR 连接到熟悉代码的人 当您知道该向谁询问时，缺陷或 PR 就会变得更具可操作性。dxkit 基于此构建了 **活跃所有者模型** ——即经过近期加权的 git 历史记录，范围限定在仍然活跃的贡献者中，过滤掉机器人和已离开的贡献者，排除变更作者本人，并包含一个巴士因子信号。 - **`vyuh-dxkit reviewers`** 为变更建议审查者，根据对所涉及文件的活跃所有权进行排名，并结合 `CODEOWNERS` 进行融合——这比平台单纯的最后一次修改建议是更好的信号。`dxkit-pr` 技能会将其折叠到 PR 正文中。 - **`--attribute`** 在详细报告中添加了一个“咨询谁”的列：一个预先存在的缺陷会被追踪到其当前所有者（不活跃的作者会被路由到当前拥有该文件的人）。这是可选的且具有历史追溯性的——新增的缺陷是由您自己的更改引入的。 输出内容为姓名 + GitHub @handle，绝不包含原始电子邮件——@handle 既保护了隐私，又可以直接用于 @提及。 ### 深度 SAST：来自任何引擎的跨过程分析缺陷 dxkit 内置的 SAST（社区版 semgrep）是过程内的——它无法跨函数边界追踪污点数据，因此它漏掉了像 Snyk Code 或 CodeQL 这样的跨过程引擎所能捕捉到的路径遍历 / 信息泄露 / SSRF / 注入类问题。dxkit 并不试图重新检测这类问题；而是**摄取**它们并使其成为一等公民。 - **`vyuh-dxkit ingest --from-snyk`** 引入您的 Snyk Code 缺陷，并适用于所有的 Snyk 套餐：如果您拥有它，它将读取 REST API 而不消耗配额；在免费/团队套餐上会自动回退到 `snyk code test`（每次运行一次测试）。**`--sarif `** 可从任何引擎摄取 SARIF；**`--codeql`** 按需运行 CodeQL（开源 / GitHub Advanced Security）。 - 摄取的缺陷会进入与原生缺陷相同的处理流程：被指纹识别和去重，写入基线，由护栏强制执行，并在 `--graph-context` 下进行图谱关联，以便 `dxkit-action` 修复循环能够看到影响范围 + 调用者——这是源引擎自身的自动修复所不具备的上下文。 - 这些缺陷保存在已提交的 `.dxkit/external/` 快照中，因此仅在摄取时（最好是在一次按需执行的 CI 作业中）才需要引擎 token——每个开发者和 CI 运行都可以在没有它的情况下读取快照。 dxkit 并不与检测引擎竞争——它是建立在您能运行的任何引擎之上的治理 + 代理自动修复层。`dxkit-ingest` 技能将引导您完成设置，并根据许可证感知选择引擎（私有仓库使用您自己的 Snyk；开源 / GHAS 使用 CodeQL）。 ### 可复现环境 针对特定技术栈的 devcontainer 仅包含您的项目所使用的语言。自动安装扫描工具链。为 AI 代理 CLI 安装脚本（身份验证仍归用户所有）。通过 `vyuh-dxkit setup-prebuild` 连接 Codespaces 预构建，将冷启动时间从约 7 分钟缩短至约 30 秒。 ### 公开仓库的安全基线 `ref-based` 模式不提交任何基线文件。护栏检查在检查时通过 `git worktree add` 从 git ref 重新计算前序状态。零信息暴露面。文件路径、包名称和公告 ID 都不会留在 git 中。通过 `gh repo view --json visibility` 为公开仓库自动选择此模式。 ## 快速开始 ``` # 首次标准安装 npm init @vyuhlabs/dxkit # 捕获当前状态 npx vyuh-dxkit baseline create # 验证安装 npx vyuh-dxkit doctor # 提交并发布 git add . && git commit -m "chore: enable dxkit" && git push # 可选但推荐 npx vyuh-dxkit setup-branch-protection # mark guardrail as required CI check npx vyuh-dxkit setup-prebuild # Codespaces prebuild ``` 如果您只想要特定的部分，可以按需选择： ``` npx vyuh-dxkit init --with-dxkit-agents # just the dxkit-* Claude skills + AGENTS.md npx vyuh-dxkit init --with-hooks # just the pre-push hook npx vyuh-dxkit init --with-precommit-hook # add pre-commit (slow on large repos) npx vyuh-dxkit init --with-devcontainer # just the per-stack devcontainer npx vyuh-dxkit init --with-ci # just the PR-gate workflow ``` ## dxkit 分析什么 | 维度 | 工具 | 捕捉内容 | | -------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | 安全性 | gitleaks, semgrep, osv-scanner, npm-audit, pip-audit, govulncheck, cargo-audit, dotnet vulnerable, bundle-audit | 密钥、依赖漏洞、不安全的模式、TLS 绕过 | | 代码质量 | cloc, jscpd, graphify, lint adapters | 文件大小、重复代码、复杂度、代码卫生标记 | | 测试 | 各语言包的覆盖率适配器，测试文件检测器 | 缺失的测试、降级的测试、覆盖率缺口 | | 文档 | 文档注释比率，README 存在性 | 内联文档覆盖率、项目级文档 | | 可维护性 | graphify 调用图指标 | 上帝文件、死导入、内聚性、组件社区 | | 开发者体验 | git 钩子检测，CI 工作流检测，清单存在性 | Pre-push 钩子、CI 质量门禁、环境可复现性 | 每个分析器都会报告原始缺陷。dxkit 会聚合并跨工具去重，然后确定性地进行评分。 ## 老旧项目 vs 全新项目 | | 全新项目 (第一天) | 老旧项目 (多年债务) | | ---------------- | -------------------------------------- | ------------------------------------------------- | | 基线 | 捕获时几乎为零 | 将当前债务捕获为基准线 | | 行为 | 从第 1 次提交起，每一个回归都很重要 | 现有债务豁免；仅拦截新增内容 | | 清理压力 | 轻松保持整洁 | 逐步改进；无需强制进行清理冲刺 | 驱动拦截决策的状态分类法： | 状态 | 含义 | 默认行为 | | ------------------- | ----------------------------------------- | ---------- | | `added` | 由此更改引入的全新缺陷 | **拦截** | | `relocated` | 相同的缺陷，发生了移动（行偏移、重命名） | 放行 | | `persisted` | 相同的缺陷，相同的位置。已存在。 | 放行 | | `removed` / `fixed` | 曾经存在，现在消失了 | 放行 | | `tooling_drift` | 因扫描器版本更改而新增 | 警告 | | `config_drift` | 因 dxkit 配置更改而新增 | 警告 | | `uncertain` | 低于置信度阈值 | 警告 | 通过 [`.dxkit/policy.json`](docs/configuration/policy.md) 进行自定义。 ## 安全与信任 - **本地优先。** 每次扫描都在开发者的机器上运行。没有任何数据离开代码库。无遥测。无回传联网。 - **评分环节不使用 LLM。** 分数来源于确定性的分析器和算术运算。可复现。可审计。提高分数的唯一途径就是编写更好的代码。 - **Sigstore 溯源。** 每次 npm 发布都通过 GitHub Actions 的 OIDC 进行签名。使用 `npm audit signatures` 进行验证。 - **开源。** MIT 许可证。检查每一个分数的推导过程。 ## 真实验证 dxkit 在所有八个语言包中针对指定的生产级代码库进行交付。每次发布在打标签之前，都会在一个多语言参考库（TypeScript + Python）和一个 .NET 参考库上运行跨栈走查。跨栈回归测试套件是 CI 的一部分。 近期的交付验证 (`@vyuhlabs/dxkit@2.6.0`, 2026-05-23): - 110 个文件中的 1904 个测试 - 在 2.6 基线优化后，在一个包含 600 个源文件的多语言代码库中，许可证缺陷减少了 73% - 新的 `ref-based` 模式已在两个参考技术栈上进行了端到端验证 ## 文档 **从这里开始**: - [入门指南](docs/getting-started.md)：从安装到首次护栏检查的完整指南 - [更新日志](CHANGELOG.md)：发行说明。最新版本是 [2.6.0](https://github.com/vyuh-labs/dxkit/releases/tag/v2.6.0) **深度内容**: - [为什么选择 dxkit](docs/why-dxkit.md)：基本原理、与 SonarQube/Snyk/Semgrep 等的对比、开放的方法论 - [架构](docs/ARCHITECTURE.md)：数据流、感知 git 的匹配器、指纹维度 - [评分方法](docs/SCORING.md)：每个维度的计算方式，引用文献 - [路线图](docs/roadmap.md)：已交付 vs 计划中 **参考**: - [命令参考](docs/README.md)：一目了然地查看所有子命令 - [`baseline`](docs/commands/baseline.md)：捕获、显示、模式 - [`guardrail`](docs/commands/guardrail.md)：检查、分类、渲染 - [`allowlist`](docs/commands/allowlist.md)：按缺陷豁免 - [`.dxkit/policy.json`](docs/configuration/policy.md)：调整拦截与警告的内容 - [报告问题](docs/commands/issue.md)：`vyuh-dxkit issue --type=...` ## 贡献 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。该项目遵循 [CLAUDE.md](CLAUDE.md) 中的架构规则。添加新的语言包、新的缺陷类型或新的评分维度都有各自的一页式指南。 ## 许可证 MIT。详情见 [LICENSE](LICENSE)。

标签：AI编程助手, MITM代理, 云安全监控, 代码审查, 威胁情报, 开发者工具, 暗色界面, 自动化攻击, 静态分析