Neoswarm 初探：它不是另一个 AI 编程助手，而是 Agent 的终端工作区与调度层
“Neovim for controlling AI agents”很容易让人误以为 Neoswarm 是一个 Neovim 插件，或者是又一个自带模型的 AI 编程助手。实际情况更有意思：它的可执行程序叫 neosh，核心是 Rust 编写的终端工作区，试图把多个 AI Agent 的会话、项目目录、Git worktree、权限和终端视图放进一个持久进程里。官方也特别声明，它与 Neovim 项目没有隶属关系。
这个定位差异决定了使用方式。Neoswarm 不会替 Claude Code 或 Codex 重写工具调用循环，也不会自动接管这些 CLI 自己的沙箱和批准策略。它更像 Agent 的“终端窗口管理器与调度层”：负责让工作区持续存在，让多个终端附着到同一状态，并把不同模型或 Agent 接到统一的交互界面中。对于同时跑多个编码任务、经常切换 worktree 的终端用户，这比又增加一个聊天面板更实际。
先理解它的工作区模型
普通 Agent CLI 通常是“打开终端、启动进程、退出后状态随进程结束”。Neoswarm 采用了一个持久的 workspace process。多个终端可以附着到同一工作区，各自保留滚动位置、当前会话和面板状态；关闭一个终端只是 detach，不会自动停止仍在运行的 Agent turn。需要真正停止工作区时，使用 neosh stop。
会话与目录绑定。新建会话时，可以选择当前目录、新建 Git worktree、已有 worktree 或另一台机器上的工作区。这样，修复一个线上问题、尝试一个重构方案、让另一个 Agent 做测试，就可以分别放在不同目录中，而不是让多个 Agent 共享同一份未提交文件。
这里的 worktree 是隔离手段，不是自动合并系统。Neoswarm 不会替你解决两个分支的冲突，也不保证不同 Agent 修改同一模块时的设计一致性。它解决的是“每个任务在哪里运行、如何持续查看和切换”，合并仍然需要开发者和 Git 工具完成。
安装后先做三件事
官方安装页支持 macOS 和 Linux。最直接的安装方式是：
curl -fsSL https://neoswarm.dev/install.sh | sh neosh neosh init neosh paths
安装脚本会从源码构建 release binary，默认写入 ~/.local/bin；也可以使用 Homebrew 或 Cargo：
brew install neoswarm/tap/neosh cargo install --locked --git https://github.com/neoswarm/neosh neosh
把远程脚本直接交给 Shell 虽然方便，但在生产机器上不应跳过审阅。更稳妥的做法是先打开 https://neoswarm.dev/install.sh 检查脚本内容，确认安装目录和构建步骤，再执行。Windows 目前不在官方支持范围内；npm 包也只是平台二进制启动器，并不能改变这一限制。
neosh init 会生成起始配置、tsconfig.json 以及与当前二进制匹配的 API 类型；neosh paths 则用于确认配置、数据和状态目录究竟解析到了哪里。配置通常位于 ~/.config/neosh/，项目级配置则放在项目的 .neosh/ 目录。
接入本地模型与现有 Agent
Neoswarm 支持几种不同层次的接入：已经登录的 Claude 或 Codex CLI、直接使用 Anthropic 或 Google API、OpenAI-compatible 端点，以及文档列出的 ACP Agent。这里要区分“统一界面”和“统一执行策略”：当使用 claude-cli 或 codex-cli 驱动时，底层工具、沙箱和批准行为仍由供应商 CLI 决定，不能把 Neoswarm 描述成一个覆盖所有 Agent 权限的总闸门。
如果本地已经运行兼容 OpenAI API 的推理服务，可以在 ~/.config/neosh/config.toml 中声明 provider：
[[providers]]
id = "local"
driver = "openai-compat"
display_name = "llama.cpp"
base_url = "http://localhost:8080/v1"
auth = { kind = "none" }
这段配置只告诉 Neoswarm 去哪里访问兼容端点，并不会替你安装或启动 llama.cpp，也不会自动解决模型上下文长度、工具调用兼容性和推理速度问题。模型选择器能看到 provider，不代表每个模型都具备同样的工具调用能力；正式使用前应以一个小任务验证文本输出、文件操作和错误处理。
插件优先，而不是把 UI 写死
Neoswarm 的另一个技术重点是插件架构。官方 README 将侧栏、模型选择器、Git 操作、命令面板和批准提示等界面能力都放在公共 API 之上，用户配置中的 init.ts 本身也可以作为插件入口。插件目录可以放在：
~/.config/neosh/plugins//
这让它和普通“终端内嵌聊天框”拉开距离：开发者可以用 TypeScript 改造 Agent 操作台，而不必修改 Rust 核心或等待上游加入每个按钮。不过，插件意味着可执行代码。项目级 .neosh/init.ts、自定义 provider、插件目录和系统提示词等可能扩大能力的配置，需要先执行信任流程：
neosh init --project neosh trust neosh trust --list
官方的信任设计值得注意：项目配置不是因为来自某个路径就永久可信，而是按文件内容记录；文件或导入模块发生变化后，信任会自动撤销。它降低了“把一个陌生仓库拉下来就执行其中配置”的风险，但不等于 Agent 本身获得了形式化安全保证。提交前仍应阅读 init.ts、插件和 provider 配置，特别是涉及 Shell 权限的部分。
多机 Swarm 的边界比功能列表更重要
Neoswarm 还提供跨机器工作区可见性。两台机器配对时需要双方确认并核对指纹，文件、Shell 和凭据仍留在原机器，Agent 也不会随着会话在机器之间迁移。网络上传递的是 Agent 描述和请求，因此它不是把整个运行环境透明搬到另一台主机上的分布式执行框架。
运维上尤其要注意默认暴露面。官方文档说明 Swarm 默认监听 0.0.0.0:7717，使用 plain TCP，并且没有内建 NAT 穿透。局域网实验前也应该明确 allow-list；跨互联网使用时，官方建议把它放在 Tailscale、Nebula、NetBird 或 ZeroTier 等 Overlay 网络中，而不是直接把端口暴露到公网。若不需要 Swarm，可以在配置中关闭：
[swarm] enabled = false listen = ""
accepts_commands 与 accepts_approvals 也要分开理解：前者控制远端是否能在本机发起 Agent 指令，后者控制远端是否能回答权限提示。跨机协作时，最小权限配置比“先打开所有功能再说”更适合长期运行。
先把权限边界放在工作区之外
Neoswarm 的统一入口不等于统一安全策略。Claude CLI、Codex CLI 以及各类 ACP Agent 仍可能拥有自己的文件、网络和命令权限；工作区只是让这些状态更容易被观察和切换。实践中应把权限配置放在供应商 CLI 与项目本身两处，并用 Git worktree 隔离实验。对于含有密钥的目录、生产凭据和个人配置，不要因为界面看起来集中就默认允许所有 Agent 访问。
一个适合试用的工作流
第一次使用时，不要立即让多个 Agent 同时重构同一仓库。可以先创建一个独立 worktree，在其中启动一个小任务：让 Agent 阅读模块、提出修改计划，再只允许它运行测试和查看 Git 差异。确认输出符合预期后，再切换到允许写文件的权限模式。
同时保留三类记录：工作区的会话状态、Git 分支和提交历史、Agent 自己的运行日志。Neoswarm 解决的是会话与终端的持续可见性，不会替代 Git，也不会替代远程备份。遇到网络断开时，先确认原机器上的 turn 是否仍在运行，再决定重新附着，而不是盲目启动第二个 Agent。
还要记住项目很新。官方 GitHub 组织与主仓库创建于 2026 年 8 月，不能把它包装成已经历多年生产验证的基础设施。它更适合终端重度用户、需要并行管理多个编码任务、愿意维护 TypeScript 插件的人；如果你只运行一个简单 Agent，或者主要在 Windows 上工作，现阶段未必值得增加这一层。
Neoswarm 的价值不在于替换 Claude、Codex 或本地模型，而在于重新组织它们的运行上下文：一个持久工作区承载多个终端视图，worktree 提供任务隔离，插件提供可编程的控制面，Swarm 提供受信任机器之间的可见性。只要把这些能力与底层 Agent 的权限边界分开看，它就是一个值得试验的 Agent 工程工具，而不是又一个“万能 AI 编程助手”。