MykytaStel/repopilot

# RepoPilot [](https://crates.io/crates/repopilot) [](https://www.npmjs.com/package/repopilot) [](https://github.com/MykytaStel/repopilot/actions) [](https://github.com/MykytaStel/repopilot/releases) [](LICENSE) [](https://github.com/MykytaStel/repopilot) 在本地审计您的代码仓库，将结果转化为 AI 可读的修复上下文，并在不向托管扫描器发送源代码的情况下，发布更安全的变更。 RepoPilot 是一个本地优先的 CLI 工具，用于进行架构、安全、代码质量、测试和框架健康度检查。它为开发者提供有用的终端报告、CI 门控、用于 GitHub 代码扫描的 SARIF 报告，以及可粘贴到 Claude Code、ChatGPT、Cursor 或其他编码助手的 Markdown 简报。 版本 `0.11.0` 是一个信号质量和 CI 优化版本：它减少了低价值的自审计发现，增加了官方 Action 对优先级/规则过滤器的对等支持，并收紧了 `doctor -> scan/review -> ai context -> CI gate` 的循环，同时保持所有扫描为本地运行。 ## 为何选择 RepoPilot？ 大多数代码检查和审计工具止步于终端。RepoPilot 桥接了与 AI 助手的鸿沟： | | SonarQube / CodeClimate | ESLint / 语言检查工具 | **RepoPilot** | |---|---|---|---| | 离线运行 | ❌ | ✅ | ✅ | | 无需上传代码 | ❌ | ✅ | ✅ | | 跨语言架构分析 | ✅ | ❌ | ✅ | | LLM 可用输出 | ❌ | ❌ | ✅ | | 适配模型上下文窗口 | ❌ | ❌ | ✅ | | 仅对新发现设置 CI 门控 | ✅ | 部分支持 | ✅ | ``` repopilot ai context . | pbcopy # macOS: paste into your coding assistant ``` ## 功能 - 对项目、文件夹和单个文件进行仓库扫描 - 感知 `.gitignore` 的遍历，内置了对常见构建目录、缓存目录、供应商目录和原生平台目录的忽略规则 - 架构发现：超大文件、深层嵌套、深层相对导入、有风险的 barrel 文件、单目录内模块过多 - 耦合分析：扇出过多、高不稳定性枢纽、循环依赖 - 代码质量发现：圈复杂度密度、过长函数、TODO/FIXME/HACK 标记 - 安全发现：硬编码的密钥候选、已提交的私钥、已提交的 `.env` 文件 - 测试发现：缺失测试文件夹、源文件缺少对应的测试文件 - 针对 JavaScript、React、React Native、Expo 和 Django 项目的框架发现 - React Native 架构概览：项目类型、新架构、Hermes、Codegen、平台不匹配和包管理器信号 - 工作区扫描 (`--workspace`)，支持 npm、yarn、pnpm 和 Cargo 工作区，提供每个包的风险摘要 — 并行执行每个包的扫描 - 有证据支持的发现，包含稳定的规则 ID、严重级别、文件路径、行号和代码片段 - 46 个内置规则，带有标题、描述、建议和文档链接 - 由 `repopilot init` 生成的 `repopilot.toml` 配置文件 - 配置预设 (`--preset strict|balanced|lenient`)，用于快速调整阈值 - 基线工作流，用于在旧仓库中接受已有的发现 - CI 友好的失败阈值，使用 `--fail-on` - Git diff 感知的审查模式，优先处理由变更行引入的发现 - 医生采用指南，涵盖配置、基线、CI 门控、报告和收据就绪性检查 - 来自 `repopilot scan --receipt` 的审计收据 JSON，用于可重现的扫描证据 - 控制台、JSON、Markdown、HTML 和 SARIF (2.1.0) 扫描输出 — SARIF 包含每个结果的类别和工作区包属性 - 官方的 GitHub Action 封装，支持 `scan`、`review`、`compare` 和 `ai` 工作流，扫描支持可选的 SARIF 上传和收据输出 - 比较模式，用于比较两个 JSON 扫描报告的差异 - **`repopilot ai context`** — 将扫描输出格式化为 LLM 可用的 Markdown，粘贴到 Claude Code 或 ChatGPT 即可开始修复 - **`repopilot ai plan`** — 将发现转化为优先级排序的修复计划 - **`repopilot ai prompt`** — 导出包含 RepoPilot 上下文的 AI 可用修复提示 完整的规则和严重级别列表，请参阅 [docs/rulesets.md](docs/rulesets.md)。 ## 安装 ``` cargo install repopilot ``` 使用 npm 安装： ``` npm install -g repopilot ``` 使用 Homebrew 安装： ``` brew tap mykytastel/repopilot brew install repopilot ``` 使用 curl 安装 (Linux/macOS)： ``` curl -fsSL https://raw.githubusercontent.com/MykytaStel/repopilot/main/install.sh | bash ``` curl 安装程序会验证 GitHub Release 的 SHA256 校验和，如果无法下载或验证校验和，将中止安装。 升级： ``` cargo install repopilot --force npm update -g repopilot brew update && brew upgrade repopilot ``` 从源码构建： ``` git clone https://github.com/MykytaStel/repopilot.git cd repopilot cargo build --release ``` ## 快速入门 无需配置。在任何仓库中运行此命令，即可立即看到发现： ``` repopilot scan . ``` 然后获取一份可粘贴到 Claude Code、Cursor 或 ChatGPT 的 AI 可用简报： ``` repopilot ai context . | pbcopy # macOS — copies to clipboard repopilot ai context . # print to terminal ``` 这就是两分钟的循环。扫描、阅读输出、将上下文粘贴到助手、修复。 ### 深入探索 当您需要 CI 集成、基线跟踪或更严格的配置时： ``` repopilot init # generate repopilot.toml repopilot doctor . # check CI / baseline readiness repopilot scan . --min-priority p2 --rule security.secret-candidate repopilot ai context . --focus security # prepare local AI context repopilot baseline create . # accept existing findings as known debt repopilot review . --base origin/main --fail-on-priority p1 # CI gate on high-priority risk ``` 保存一份可分享的报告： ``` repopilot scan . --format markdown --output repopilot-report.md --receipt .repopilot/receipt.json ``` 在迭代过程中减少扫描噪音： ``` repopilot scan . --min-severity high repopilot scan . --workspace --min-severity medium repopilot scan . --exclude fixtures --max-file-size 1mb --max-files 500 ``` 默认情况下，RepoPilot 会跳过低信号审计路径，如测试、夹具、示例、生成文件和基准测试。如果您希望分析这些路径，请使用 `--include-low-signal`。 ## 本地优先 AI 工作流 RepoPilot 不会调用 LLM API。AI 命令会扫描本地文件并生成 Markdown，由您决定粘贴到何处。 `repopilot ai context` 会扫描项目并将所有发现格式化为结构化的 Markdown，可直接粘贴到 Claude Code、Cursor、ChatGPT 或任何 LLM 助手。它包含风险级别、技术栈摘要、按类别分组的发现（附带证据片段和修复建议），以及令牌数估算。 ``` # 粘贴到 Claude Code 或 ChatGPT repopilot ai context . # 只关注安全，保持简短 repopilot ai context . --focus security --budget 2k # 保存到文件 repopilot ai context . --output repopilot-context.md # 直接管道到剪贴板 (macOS) repopilot ai context . --no-header | pbcopy ``` ## 示例输出 ``` $ repopilot ai context . # RepoPilot 氛围检查 — my-app **Risk Level:** 🟠 ELEVATED **Tech Stack:** React Native (New Arch), Expo, TypeScript **Size:** 94 files · 8,340 LOC · ~42k tokens **Health:** 18 findings · 2.2/kloc — 4 high, 9 medium ## 安全 (2 高) 1. [HIGH] Possible secret detected — `src/config/api.ts:12` ``` const API_KEY = "sk_live_…" ``` > **Fix:** Move to environment variables or a secrets manager. ## 架构 (2 高) 1. [HIGH] Circular dependency detected — `src/store/index.ts` > **Fix:** Extract shared types to a separate module to break the cycle. ## 顶级推荐 1. **Move hardcoded API key** (src/config/api.ts:12) — use process.env or a vault 2. **Break circular dependency** (src/store/index.ts) — extract shared types --- *~3.8k tokens (budget: 4k) · scanned in 312ms — paste into Claude Code, Cursor, or ChatGPT* ``` 将此内容粘贴到编码助手中，并请求一个有针对性的补丁。对于大型仓库，从一个重点区域开始，而不是一次性请求处理所有发现。 ## 推荐的修复循环 RepoPilot 是 AI 辅助和“氛围编程”变更的本地安全层。在生成或重构代码后运行它，以捕获新引入的高风险发现、工作区热点、缺失的测试和架构漂移，而无需将源代码上传到外部服务。 ``` repopilot ai context . --focus security # get an LLM brief for Claude Code repopilot ai plan . --focus security # get a prioritized hardening plan repopilot ai prompt . --budget 8k # generate a paste-ready remediation prompt repopilot review . --base origin/main --baseline .repopilot/baseline.json --fail-on-priority p1 repopilot scan . --workspace --min-severity medium --format markdown --output repopilot-report.md ``` ## 命令 | 命令 | 别名 | 描述 | |---------|-------|-------------| | `repopilot scan ` | `s` | 扫描项目、文件夹或文件以发现 | | `repopilot review [path]` | `r` | 审查涉及 Git diff 变更行的发现 | | `repopilot ai context ` | — | 从扫描结果生成 LLM 可用的上下文 | | `repopilot ai plan ` | — | 优先级排序的修复计划 | | `repopilot ai prompt ` | — | AI 可用的修复提示 | | `repopilot compare ` | `cmp` | 比较两个 JSON 扫描报告并显示变化 | | `repopilot baseline create ` | `bl` | 扫描路径并将当前发现存储为已接受的债务 | | `repopilot doctor [path]` | `d` | 诊断审计就绪性 | | `repopilot init` | — | 生成默认的 `repopilot.toml` 配置文件 | 对任何命令使用 `--help` 可查看完整描述和示例： ``` repopilot --help repopilot scan --help repopilot review --help repopilot baseline create --help ``` ## 配置 RepoPilot 在运行 `scan` 时会自动从当前工作目录读取 `repopilot.toml`。 配置优先级： ``` CLI args > repopilot.toml > built-in defaults ``` 生成默认配置： ``` repopilot init repopilot init --force repopilot init --path ./repopilot.toml ``` 使用明确的配置路径： ``` repopilot scan . --config repopilot.toml ``` `repopilot.toml` 示例： ``` [scan] ignore = [ ".git", ".github", ".repopilot", "target", "node_modules", "dist", "build", ".next", ".nuxt", ".cache", "coverage", "vendor", "Pods", "DerivedData" ] max_file_bytes = 2097152 [architecture] max_file_lines = 300 huge_file_lines = 1000 max_directory_modules = 20 max_directory_depth = 5 max_function_lines = 50 max_fan_out = 15 instability_hub_min_fan_in = 5 instability_hub_min_instability_pct = 75 [testing] detect_missing_tests = true [security] detect_secret_like_names = true [output] default_format = "console" ``` CLI 阈值覆盖： ``` repopilot scan . --max-file-loc 500 repopilot scan . --max-directory-modules 25 repopilot scan . --max-directory-depth 6 repopilot scan . --max-file-size 1mb repopilot scan . --max-files 1000 repopilot scan . --exclude generated repopilot scan . --include-low-signal ``` `--max-file-size` 接受原始字节数或带 `kb`、`mb` 和 `gb` 后缀的值。`--exclude` 匹配相对于扫描根目录的精确路径或文件/目录名；重复使用可排除多个路径。 JSON 输出包含扫描输入统计字段：`files_discovered` 是忽略/排除过滤器后找到的文件数，`files_count` 是已分析的文本文件数，`files_skipped_low_signal` 是默认跳过的低信号文件数，`binary_files_skipped` 是不可读/二进制文件数。 ## 基线工作流 现有的仓库通常存在一些在采用新审计工具之前无法全部修复的发现。基线用于存储已接受的现有发现，以便未来的扫描能够区分新发现和已有发现。 ``` repopilot baseline create . repopilot scan . --baseline .repopilot/baseline.json repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high ``` 默认情况下，`baseline create` 会写入 `.repopilot/baseline.json`，并在需要时创建 `.repopilot/` 目录。使用 `--output ./baseline.json` 可指定自定义路径。除非传递 `--force`，否则不会覆盖现有的基线文件。 基线文件存储已接受的现有发现。未来的扫描可以将发现标记为 `new` 或 `existing`，这对旧仓库和 CI 很有用。除非团队将这些发现确认为技术债务，否则不要盲目刷新基线。 ## 审查工作流 当您希望 RepoPilot 专注于涉及 Git diff 变更行的发现时，请使用 `review`。 ``` repopilot review . repopilot review . --format json --output review.json repopilot review . --baseline .repopilot/baseline.json --fail-on new-high ``` 默认情况下，`review` 将工作树与 `HEAD` 进行比较，包括已暂存、未暂存和未跟踪的文件。对于分支或 CI 审查，请传递一个基准引用： ``` repopilot review . --base origin/main repopilot review . --base origin/main --head HEAD --format markdown ``` 审查模式仍然使用正常规则扫描仓库，但会将发现分为差异内组和差异外组。当导入耦合数据可用时，它还会显示“影响范围”：导入了变更文件的文件，可能需要额外审查。当使用 `--fail-on` 时，CI 门控仅评估差异内的发现。 ## 输出格式 ``` repopilot scan . --format console repopilot scan . --format json --output report.json repopilot scan . --format markdown --output report.md repopilot scan . --format html --output report.html repopilot scan . --format sarif --output repopilot.sarif ``` ### SARIF 输出 ``` repopilot scan . --format sarif --output repopilot.sarif ``` 如果您安装的 RepoPilot 版本不支持 `--output`，请改为重定向标准输出： ``` repopilot scan . --format sarif > repopilot.sarif ``` 当自定义脚本需要解析 RepoPilot 结果时使用 JSON。控制台、Markdown 和 HTML 报告包含 RepoPilot 版本、风险摘要、主要风险集群、主要规则以及供人工审查的分组发现。使用 SARIF 用于 CI 和代码扫描集成，包括 GitHub 代码扫描。 当 CI 或发布流程需要 RepoPilot 版本、Git 状态、扫描范围、发现计数、语言计数和健康分数的精确证据时，可在 `scan` 时使用 `--receipt `。 有关可复制粘贴的 GitHub Actions 工作流、所需权限和本地验证命令，请参阅 [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md)。 比较两个 JSON 报告： ``` repopilot scan . --format json --output before.json repopilot scan . --format json --output after.json repopilot compare before.json after.json repopilot compare before.json after.json --format markdown repopilot compare before.json after.json --format json --output diff.json ``` ## CI 用法 使用 `--fail-on new-high` 仅在引入新的高风险或严重发现时使 CI 失败。支持的新发现阈值包括 `new-low`、`new-medium`、`new-high` 和 `new-critical`。 当在没有 `--baseline` 的情况下使用 `--fail-on new-*` 时，RepoPilot 将所有当前发现视为新发现。对于基于基线的采用，请提交一个已接受的基线并在 CI 中对其进行扫描。 要将 RepoPilot 的发现上传到 GitHub 代码扫描，请生成 SARIF 并使用 `github/codeql-action/upload-sarif`。工作流必须包含 `security-events: write` 权限。 官方 Action 还可以运行 `command: doctor`、`command: ai-context`、`command: ai-plan` 或 `command: ai-prompt`；AI 命令会发出 Markdown，不产生 SARIF。建议使用类型化的 Action 输入，如 `path`、`config`、`baseline`、`fail-on`、`fail-on-priority`、`min-priority`、`rule`、`timing`、`focus`、`budget`、`output` 和 `receipt`；`args` 仍可用于高级标志。 ``` name: RepoPilot on: pull_request: permissions: contents: read security-events: write jobs: repopilot: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Install Rust uses: dtolnay/rust-toolchain@stable - name: Install RepoPilot run: cargo install repopilot - name: Run RepoPilot run: repopilot scan . --baseline .repopilot/baseline.json --fail-on new-high --receipt repopilot-receipt.json - name: Run RepoPilot (SARIF) run: repopilot scan . --format sarif --output repopilot.sarif - name: Upload to GitHub Code Scanning uses: github/codeql-action/upload-sarif@v4 if: always() with: sarif_file: repopilot.sarif - name: Upload audit receipt uses: actions/upload-artifact@v4 if: always() with: name: repopilot-receipt path: repopilot-receipt.json ``` ## 路线图 这些是计划中的想法，而非当前功能： - 变更风险图 - 更好的架构漂移检测 - 可选的、针对不同平台的 npm 二进制包以加快安装速度 ## 文档 | 文档 | 描述 | |---|---| | [docs/install.md](docs/install.md) | Cargo、npm、Homebrew、curl 和源码构建的安装选项 | | [docs/ai-workflows.md](docs/ai-workflows.md) | Claude Code、ChatGPT、Cursor 和 AI 修复工作流 | | [docs/security.md](docs/security.md) | 本地优先信任模型、安装程序安全和漏洞报告 | | [docs/configuration.md](docs/configuration.md) | `repopilot.toml`、预设、忽略文件和基线采用 | | [docs/language-support.md](docs/language-support.md) | 支持的语言/框架层级、规则族和限制 | | [docs/risk-engine.md](docs/risk-engine.md) | 风险评分、优先级桶、信号和校准策略 | | [docs/cli.md](docs/cli.md) | 完整的 CLI 参考 — 所有命令、标志和退出码 | | [docs/commands.md](docs/commands.md) | 面向任务的命令指南和常见模式 | | [docs/rulesets.md](docs/rulesets.md) | 已实现的审计规则、类别和严重级别 | | [docs/react-native.md](docs/react-native.md) | React Native 和 Expo 检测、发现和限制 | | [docs/integrations/github-code-scanning.md](docs/integrations/github-code-scanning.md) | GitHub 代码扫描 SARIF 工作流 | | [docs/release.md](docs/release.md) | 手动发布流程 | | [docs/release-checklist-0.11.md](docs/release-checklist-0.11.md) | 0.11.0 发布就绪检查清单 | | [docs/release-checklist-0.10.md](docs/release-checklist-0.10.md) | 0.10.0 发布就绪检查清单 | | [docs/distribution.md](docs/distribution.md) | 分发渠道 | | [docs/github-ruleset.md](docs/github-ruleset.md) | GitHub 分支规则集配置 | | [CHANGELOG.md](CHANGELOG.md) | 版本历史 | ## 许可证 RepoPilot 采用 MIT 或 Apache-2.0 许可。

标签：AI辅助修复, DevSecOps, GNU通用公共许可证, LLM就绪, Markdown输出, Node.js, Rust编程, SARIF报告, 上下文生成, 上游代理, 云安全监控, 仓库管理, 代码健康, 修复建议, 可视化界面, 威胁情报, 安全扫描, 安全门控, 开发者工具, 数据可视化, 文档结构分析, 时序注入, 本地优先, 架构分析, 测试框架, 离线扫描, 终端报告, 质量检查, 跨语言支持, 通知系统, 静态分析, 风险检测