Intrect-io/OpenSwarm

OpenSwarm – AI 驱动的 CI/CD 门控

它是什么 – OpenSwarm 是一个命令行工具（及 GitHub Action），它在你的 pull-request 或本地 diff 之前放置了一个大语言模型审查员。它可以：

• 审查：使用 OpenAI、OpenRouter、Claude 或本地托管模型审查代码变更。
• 修复：在隔离的沙箱中修复已确认的问题，然后重新审查结果。
• 验证：在允许合并之前进行确定性验证（运行测试/类型检查）。
• 持久化知识：为每个仓库保留知识，以便后续运行获得更好的提示词。
• 可选地挂钩到 Linear 进行问题跟踪，并向 Discord/Slack/Telegram 发送通知。

为什么重要 – 传统的 CI 只运行静态检查；OpenSwarm 增加了一个代理步骤，能够理解变更、建议并应用修复，并且只有在确定性验证成功时才通过门控。它旨在减少手动代码审查周期并尽早发现错误，同时通过为实现路由廉价模型、为诊断路由前沿模型来保持低成本。

---

核心概念

概念	描述
Provider	LLM 后端（Codex/GPT, OpenRouter, Claude, 本地 Ollama/LM Studio, Atlas Cloud）。该工具可以自动检测认证或运行登录向导。
Task backend	将问题元数据存储在本地 SQLite 数据库或 Linear (OAuth) 中。
Sandbox	Linux 沙箱 (bubblewrap) 或 macOS 沙箱，在模型生成的代码被应用之前对其进行隔离。
Deterministic verification	在沙箱中运行仓库范围的测试/类型检查（Node, Python, Rust, Go 等），并与合并基准进行比较，以确保不会引入新的失败。
Daemon	可选的长期运行服务，用于保持仓库记忆、Linear 集成和通知。基本审查门控不需要此功能。

---

快速入门 (CLI)

# 全局安装
npm install -g @intrect/openswarm

# 审查当前 diff（只读，无更改）
openswarm review --path . --read-only

# 全自动修复流程：审查 → 修复 → 重新审查 → 验证
openswarm review --max --fix --path .

• openswarm init 运行交互式向导以创建 .env、config.yaml 和可选的 openswarm.json（Linear 映射）。
• openswarm doctor 检查提供程序、沙箱和依赖项是否就绪。

---

在 CI 中使用 (GitHub Action)

steps:
  - uses: actions/checkout@v4
    with: { fetch-depth: 0 }
  - uses: actions/setup-node@v4
    with: { node-version: '22' }
  - id: review
    uses: unohee/OpenSwarm@main
    with:
      adapter: openrouter          # 使用哪个提供程序
      model: deepseek/deepseek-v4-flash
    env:
      OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}

• 该 action 返回 decision 和 gate-ran 输出，并以 0（通过）或 1（拒绝）退出。退出代码 2 表示门控无法运行（例如，配额耗尽）。

---

主要命令 (摘要)

命令	用途
openswarm (默认)	用于与模型进行临时对话的 TUI 聊天界面。
openswarm review …	在 diff 上运行 CI 门控；--max 审计整个仓库，--fix 应用沙箱修复。
openswarm fix …	运行特定语言的 CI 检查（lint, test 等）并自动修复失败。
openswarm pr …	与打开的 pull requests 交互 – 状态、修复、审查、创建、监视直到准备好合并。
openswarm exec …	执行单个任务或 Linear 问题流水线，可选择等待人工提升。
openswarm check …	扫描代码库，注册实体，检测“坏代码气味”模式，注释函数。
openswarm provider …	切换或显示活动的 LLM 提供程序。
openswarm doctor	诊断环境、缺失的依赖项、提供程序认证、沙箱可用性。

---

沙箱与安全说明

• 只读模式 (--read-only) 是默认设置；它禁用了模型工具集中任何可变工具。
• 在 Linux 上，该工具使用 bubblewrap；CI 运行器必须安装 bubblewrap 并启用非特权用户命名空间 (sysctl kernel.apparmor_restrict_unprivileged_userns=0)。
• 审查员在临时检出上运行，从不在运行器的工作目录上运行，防止恶意 PR 覆盖 action 自身的代码。

---

许可与社区

• 许可证：MIT
• 赞助商：Atlas Cloud（提供内置的 atlascloud 适配器和 API 额度）。
• 讨论：GitHub Discussions 用于路线图投票和功能构思。
• 基准测试：在 SWE-bench Lite 混合模式下声称 3/3 成功率，具有成本感知路由阶梯 (L0–L6)。

---

何时考虑 OpenSwarm

• 你已经使用 LLM 进行代码辅助，并希望在 CI 中自动化审查/修复循环。
• 你需要一个确定性门控，仅在自动修复后仓库测试成功时才通过。
• 你习惯于配置 OpenAI/OpenRouter/Claude 的 API 密钥或运行本地模型服务器。
• 你需要可选的 Linear 问题跟踪和通知渠道。

---

限制/注意事项

• 在 Linux 上需要一个可用的沙箱 (bubblewrap)；CI 镜像可能需要额外的 sysctl 调整。
• 成本感知路由取决于提供商的定价；对每次运行使用前沿模型可能会变得昂贵。
• 守护进程（用于长期记忆、Linear 同步、通知）是可选的，但增加了操作复杂性。
• 该工具是用 TypeScript/Node 编写的；不使用 Node 的项目可能仍然可以工作，但需要适当的测试发现适配器。

---

总结 – OpenSwarm 是一个真正的开源 AI 增强型 CI/CD 门控，允许 LLM 自动审查、修复和验证代码变更，具有沙箱执行环境以及与 Linear 和通知服务的可选集成。它适用于希望将 LLM 驱动的自动化嵌入到 pull-request 工作流程中，同时保持确定性安全网的团队。