andyzengmath/soliton

# Soliton [](LICENSE) [](https://github.com/andyzengmath/soliton) [](https://cursor.com/marketplace) [](agents/) **你的 AI 编码代理写代码的速度比你审查快 10 倍。Soliton 为你审查代码。** 一个 Claude Code 与 Cursor 插件，能够并行运行 **2-7 个**专用审查代理，并根据 PR 的实际风险水平自适应调整。低风险的 README 修复？两个快速代理，几秒完成。关键的身份验证重构？全套 7 代理阵容，包含安全数据流分析与幻觉检测。 ## 为什么要用 Soliton？ | 问题 | Soliton 的解决方案 | |------|-------------------| | AI 代理生成代码的速度快于你的审查速度 | 并行多代理审查在数秒而非数小时内捕获问题 | | 代理生成的代码会幻觉 API 或错误的签名 | 专用幻觉检测器验证每一次新导入与函数调用 | | 通用审查工具在低风险变更上浪费时间 | 风险自适应调度：简单 PR 仅用 2 个代理，复杂 PR 使用 7 个 | | 审查结果模糊（如“建议改进……”） | 每个发现都附带置信度分数、精确位置与可修复代码 | | 无法将审查结果反馈给编码代理 | `--feedback` 模式输出机器可执行的指令，供你的代理执行 | ## 快速开始 ``` # 步骤 1：添加市场（仅一次） /plugin marketplace add andyzengmath/soliton # 步骤 2：安装插件 /plugin install soliton@soliton # 查看当前分支 /pr-review # 查看 GitHub 拉取请求 /pr-review 123 ``` 仅此而已。Soliton 会自动识别基准分支，计算风险分数，派发合适的代理，并展示结果。 ## 安装 **Claude Code（推荐）：** ``` # 添加市场 /plugin marketplace add andyzengmath/soliton # 安装插件 /plugin install soliton@soliton ``` **本地开发：** ``` # 克隆并直接加载（非缓存 — 适用于开发） git clone https://github.com/andyzengmath/soliton.git claude --plugin-dir ./soliton ``` **Cursor：**可在 [Cursor 市场](https://cursor.com/marketplace) 搜索 “soliton” 或从仓库安装。 ## 更新 ``` # 刷新市场列表，然后更新插件 /plugin marketplace update soliton /plugin update soliton@soliton ``` 如果更新未识别最新版本（GitHub CDN 缓存），请清除本地缓存并重新安装： ``` rm -rf ~/.claude/plugins/cache/soliton /plugin install soliton@soliton ``` ## 使用 ``` # 本地分支审查（最常见 — 推送前审查） /pr-review # 通过编号或 URL 的 GitHub PR /pr-review 123 /pr-review https://github.com/org/repo/pull/123 # 机器可读的 JSON 输出 /pr-review --output json # 将结果反馈给您的编码代理 /pr-review --output json --feedback # 仅强制特定代理 /pr-review --agents security,hallucination # 跳过不需要的代理 /pr-review --skip consistency,historical-context # 查看更多结果（降低置信度阈值） /pr-review --threshold 60 ``` ### 示例输出 ``` Risk Score: 72/100 (HIGH) Dispatching 6 review agents... ├── correctness ├── security ├── test-quality ├── consistency ├── hallucination └── cross-file-impact ## 摘要 12 files changed, 347 lines added, 42 deleted. 4 findings (1 critical, 2 improvements, 1 nitpick). Auth refactor with 1 critical SQL injection. ## 关键 🔴 [security] SQL injection via string concatenation in user_query.py:42 (confidence: 94) User input from request.args["username"] flows directly into SQL query without parameterization. ```suggestion cursor.execute("SELECT * FROM users WHERE username = ?", (username,)) ``` 参考资料：[OWASP A03](https://owasp.org/Top10/A03_2021-Injection/)、CWE-89 ## 改进建议 🟡 [幻觉] `requests.get_async()` 在 user_service.py:18 不存在（置信度：91） 你可能想要 `aiohttp.ClientSession.get()` 或 `httpx.AsyncClient.get()`？ 依据：检索 requests 库源码，未发现 `get_async` 方法。 🟡 [测试] validators.py:30 的 validate_input() 缺少测试覆盖（置信度：85） 该新函数包含 3 个分支与可空输入，需要边界测试。 ## 风险元数据 风险分数：72/100（高）| 影响范围：8 个依赖项 | 敏感路径：auth/ AI 生成可能性：中 （另有 2 个低于阈值的发现） ``` ## 架构 ``` /pr-review [目标] [标志] │ ├── 步骤 1：输入标准化 │ ├── 本地模式：git diff、git 日志、分支检测 │ └── PR 模式：gh pr view --json、gh pr diff │ ├── 步骤 2：配置解析 │ └── 硬编码默认值 < .claude/soliton.local.md < CLI 标志 │ ├── 步骤 2.5：边界情况 │ ├── 空/平凡差异 → 快速路径 │ ├── 二进制/生成文件 → 自动过滤 │ └── 仅删除的 PR → 缩减代理集合 │ ├── 步骤 2.75：大 PR 分块 │ └── >1000 行 → 拆分为 <500 行的块，并行审查 │ ├── 步骤 3：风险评分（单代理快速评估） │ └── 6 个加权因子 → 0-100 分 → 代理派遣列表 │ ├── 步骤 4：自适应代理派遣（并行） │ └── 根据风险等级派遣 2-7 个代理，同时运行 │ ├── 步骤 5：综合处理 │ └── 去重、按置信度过滤、冲突检测、分类 │ └── 步骤 6：输出 ├── Markdown（人类可读，默认） ├── JSON（机器可读） └── 代理反馈（用于编码代理修复） ``` ### 风险自适应调度 The risk scorer computes a 0-100 score from 6 weighted factors: | Factor | Weight | How It's Computed | |--------|--------|-------------------| | Blast radius | 25% | Count files importing changed files | | Change complexity | 20% | Control-flow changes vs cosmetic | | Sensitive paths | 20% | Matches auth/, payment/, *.env, etc. | | File size/scope | 15% | Total lines changed | | AI-authored signals | 10% | Agent commit signatures, uniform style | | Test coverage gap | 10% | Production files without test changes | The score determines how many agents are dispatched: | Risk | Score | Agents | Typical Latency | |------|-------|--------|-----------------| | LOW | 0-30 | 2 (correctness, consistency) | ~15s | | MEDIUM | 31-60 | 4 (+security, test-quality) | ~30s | | HIGH | 61-80 | 6 (+hallucination, cross-file-impact) | ~45s | | CRITICAL | 81-100 | 7 (+historical-context) | ~60s | ### 7 个审查代理 | Agent | Model | What It Catches | |-------|-------|-----------------| | **correctness** | Sonnet | Off-by-one, null dereference, race conditions, infinite loops, missing returns | | **security** | Opus | OWASP Top 10, SQL/XSS/SSRF injection, hardcoded secrets, auth bypass | | **hallucination** | Opus | Non-existent APIs (`fs.readFileAsync`), wrong signatures, deprecated methods | | **test-quality** | Sonnet | Missing coverage, mock-only tests, assertion-free tests, missing edge cases | | **consistency** | Sonnet | Naming violations, import ordering, style deviations from project patterns | | **cross-file-impact** | Sonnet | Changed signatures breaking callers, removed exports, type mismatches | | **historical-context** | Sonnet | Files with high bug-fix frequency, recently reverted changes, code churn | Security and hallucination agents use **Opus** for deepest reasoning. All others use **Sonnet** for speed. ### 输出格式 | Format | Flag | Use Case | |--------|------|----------| | **Markdown** | (default) | Human review in terminal | | **JSON** | `--output json` | Pipe to CI tools, dashboards, or custom scripts | | **Agent Feedback** | `--output json --feedback` | Feed back to coding agents for automated remediation | The Agent Feedback format transforms each finding into an `AgentInstruction` with `action` (fix/replace/remove/add-test/investigate), exact file/line references, `currentCode`, `suggestedCode`, and priority — so a coding agent can execute fixes without human translation. ## CI/CD 集成（GitHub Actions） Run Soliton automatically on every pull request. Add this workflow to your repo: ```yaml # .github/workflows/soliton-review.yml name: Soliton PR Review on: pull_request: types: [opened, synchronize] concurrency: group: soliton-${{ github.event.pull_request.number }} cancel-in-progress: true jobs: review: runs-on: ubuntu-latest timeout-minutes: 10 permissions: contents: read pull-requests: write issues: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - name: Clone Soliton run: git clone --depth 1 --branch v0.0.2 https://github.com/andyzengmath/soliton.git /tmp/soliton - uses: anthropics/claude-code-action@v1 env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} claude_args: --plugin-dir /tmp/soliton prompt: | Run /pr-review ${{ github.event.pull_request.number }} After the review completes, post the full markdown review output as a PR comment using: gh pr comment ${{ github.event.pull_request.number }} --body "" allowed_tools: | Read Grep Glob Bash(git diff *) Bash(git log *) Bash(git show *) Bash(git branch *) Bash(gh pr comment *) Bash(gh pr diff *) Bash(gh pr view *) Agent ``` **先决条件**：在仓库 Secrets 中添加 `ANTHROPIC_API_KEY`（设置 → 密钥 → 动作）。 **更多策略**（CI 拦截、交互式 `@claude` 提及、Bedrock/Vertex 认证、成本优化）： 请参阅[完整 CI/CD 集成指南](docs/ci-cd-integration.md)与[示例工作流](examples/workflows/)。 ## 配置 在项目根目录创建 `.claude/soliton.local.md`： ``` --- threshold: 80 # Min confidence to surface findings (0-100) agents: auto # 'auto' for risk-adaptive, or comma-separated list sensitive_paths: # Glob patterns that increase risk score - "auth/" - "payment/" - "*.env" - "*secret*" skip_agents: [] # Agents to always skip default_output: markdown # 'markdown' or 'json' feedback_mode: false # Generate agent-consumable instructions --- ``` CLI 标志始终覆盖配置文件中的值。模板位于 `templates/soliton.local.md`。 ## 标志参考 | 标志 | 类型 | 默认值 | 描述 | |------|------|--------|------| | `--threshold N` | 0-100 | 80 | 最低置信度阈值 | | `--agents list` | 逗号分隔 | auto | 强制指定特定代理 | | `--skip list` | 逗号分隔 | none | 跳过指定代理 | | `--sensitive-paths glob` | 逗号分隔 | 见配置 | 覆盖敏感路径模式 | | `--output format` | markdown/json | markdown | 输出格式 | | `--feedback` | 标志 | false | 代理反馈模式（需 `--output json`） | | `--branch name` | 字符串 | auto | 覆盖目标分支 | ## 项目结构 ``` .claude-plugin/ plugin.json Claude Code plugin manifest marketplace.json Marketplace listing metadata .cursor-plugin/plugin.json Cursor Marketplace manifest skills/pr-review/SKILL.md Main orchestrator (input → risk → dispatch → synthesize → output) agents/ risk-scorer.md Risk scoring engine (6 weighted factors) correctness.md Logic & correctness reviewer security.md OWASP Top 10 security reviewer (Opus) hallucination.md AI hallucination detector (Opus) test-quality.md Test coverage & quality reviewer consistency.md Code style & convention reviewer cross-file-impact.md Cross-file breakage detector historical-context.md Git history risk analyzer synthesizer.md Finding merger & deduplicator rules/ risk-factors.md Factor definitions and weights sensitive-paths.md Default sensitive file patterns generated-file-patterns.md Auto-generated/binary file patterns templates/ soliton.local.md Sample config file examples/workflows/ soliton-review.yml GitHub Actions — plugin directory (recommended) soliton-review-direct.yml GitHub Actions — direct prompt (fallback) soliton-review-gated.yml GitHub Actions — CI gate (block on critical) soliton-review-interactive.yml GitHub Actions — auto + @claude mentions docs/ ci-cd-integration.md Full CI/CD integration guide tests/fixtures/ 5 test fixtures with synthetic diffs ``` ## 贡献 欢迎提交 PR。该插件完全由 Markdown/JSON 构成，无构建步骤，无依赖项。 要测试更改，请复制仓库到 `~/.claude/plugins/soliton/` 并对任意有变更的分支运行 `/pr-review`。 ## 许可证 MIT

标签：AI代码审查, AI幻觉检测, Claude Code插件, Cursor插件, Homebrew安装, PyRIT, 代码审查, 多智能体系统, 威胁情报, 安全漏洞检测, 并行处理, 开发效率工具, 开发者工具, 技术博客插件, 机器学习代码审查, 模块化设计, 编程辅助, 自动化修复, 软件安全分析, 防御加固, 风险自适应