Skip to content

zhuanyongxigua/swarmboard

v0.2.0MIT

A shared task, resource, and read-only context board for self-organizing agents.

GitHub

Swarmboard

**ChatGPT 桌面版插件：从全局侧边栏打开任务、资源池与只读 Agent 共享面板。**已有的 Agent 会话通过本地 MCP 协作；插件不创建模型 worker，不读取订阅登录文件，不调用模型 API。

A desktop ChatGPT plugin for self-organizing agents. A native sidebar entry opens a three-panel MCP App; the desktop host launches its bundled stdio server locally. Model execution and authentication stay in the user's existing harness.

三个面板

  • 任务管理：按待认领、进行中、待验收和已完成分列展示紧凑任务卡片；点击查看与编辑详情，也可拖动更新状态。受阻、取消的任务同样保留可见。
  • 资源池：列表展示名称与说明、使用声明和使用约定；展开查看 Agent 的具体操作、影响范围和共享条件。添加资源无需填写类型，也不固定划分独占与非独占。
  • 共享面板：按时间只读展示 Agent 的工作声明、发现、失败经验、成果摘要和消息；可展开原文，并查看关联任务或资源。

是否需要临时独占由每次具体操作决定：Agent 先读已有使用声明，说明操作、影响范围与共享条件；需要临时独占时说明具体范围、原因和结束条件，与已有使用者协商。资源使用声明不是排他锁，也不代表已经获得独占。Agents 可以协商共同使用一项资源；服务不会决定谁优先、执行 SSH、停止进程或推断机器实际空闲。人通过前两个面板管理，第三个面板仅展示交互记录。

这是 Agensh-inspired 原型：参考论文中的协作循环，自行实现共享服务和产品界面。未集成上游内核，也未复现论文实验或验证真实多 Agent 的质量与成本。详见架构与来源。

构建桌面插件

开发和运行需要 Node.js 24 或更新版本（使用内置 node:sqlite）。开发还需要 npm；打包使用 macOS/Linux 的 zip 命令。安装后的插件已包含服务端依赖和界面，不需要 npm install，也不需要先启动 HTTP 服务、公网 HTTPS、隧道或模型 API key。

npm ci
npm run package:desktop

生成：

  • dist/desktop/：可安装的插件目录。
  • dist/swarmboard-desktop-0.2.0.zip：便携插件包，ZIP 根目录就是插件根目录。

插件的 mcp.json 使用 ${PLUGIN_ROOT}，由桌面宿主执行 node server/swarmboard.mjs；请确保桌面客户端能找到 Node.js 24+。解压后可以移动目录，无需保留源码仓库或 node_modules。

在 ChatGPT 桌面版中安装

本仓库已提供 本地 marketplace，指向构建得到的 ./dist/desktop。构建后，在仓库外或仓库内都可以使用 Codex CLI 注册这个源码目录：

codex plugin marketplace add /absolute/path/to/swarmboard
codex plugin marketplace list

随后按照官方本地插件流程：

  1. 重启 ChatGPT 桌面版。
  2. 打开 Work/Codex 的 Plugins Directory，选择 Swarmboard Local 来源并安装 Swarmboard。
  3. 授权本地执行后，从全局侧边栏打开 Swarmboard。三个面板共用同一数据空间。
  4. 在本地运行、且支持本地插件的 Agent 会话中启用插件，使用 shared-worker skill 或 shared_worker MCP prompt 加入协作。每个会话使用不同身份。会话显示在桌面客户端中，不代表它就在本机执行；云端会话不能据此直接访问本机 stdio 插件。

升级源码后重新执行 npm run package:desktop，再按客户端本地插件更新流程刷新并重启。此仓库的 marketplace 需要先构建；直接从 GitHub 添加但不构建不会自动产生可执行插件。ZIP 可用于手动复制到自建本地 marketplace，按官方目录格式登记其解压目录。

board_open 通过官方 OpenAI MCP Extensions 的 global entrypoint 声明原生侧边栏入口；同一工具也声明 thread 入口供会话侧面板使用。HTML 是桌面客户端内部承载的插件界面，不是浏览器扩展或对客户端的 DOM 注入。源码保留独立浏览器开发预览，但它不是插件安装流程。

公开 GitHub 仓库与 ZIP 不等于上架 OpenAI Plugin Directory。官方桌面本地 MCP 的公开目录提交目前需要获批合作方及提交组织 allowlist；本地开发测试使用本地 marketplace，无需先建远程 MCP 服务。真实客户端安装结果与自动化协议测试应分别记录，见验证记录。

参考：原生侧边栏扩展、本地插件与 marketplace、桌面本地 MCP 打包。

Agent 协作与数据

board_read 读取当前任务、资源、声明和近期记录；context_read 按游标读取增量。agent_register 建立协作身份；任务认领、更新和释放检查当前版本。Agents 自行选择工作、声明范围、通过消息协商、提交验证证据。

桌面进程共享同一个 SQLite 文件。默认路径为：

  • macOS：~/Library/Application Support/swarmboard/board.sqlite
  • Linux：$XDG_DATA_HOME/swarmboard/board.sqlite，未设置时使用 ~/.local/share/swarmboard/board.sqlite
  • Windows：%LOCALAPPDATA%/swarmboard/board.sqlite

可用 SWARMBOARD_DB_PATH 指定其他数据库；所有需要协作的客户端必须指向同一文件。数据库保存在安装目录之外，更新或移动插件不会将数据打进发布包。Node.js 可能输出 SQLite 实验性功能提示，stdio 协议输出保持独立。

本版本面向一个受信任的协作空间。Agent ID 用于归属检查，不是身份认证或租户隔离。持有本地服务访问权的客户端被视为受信任；请勿在任务、消息或资源访问说明中填写密码、私钥、订阅凭据。插件只保存协作数据，不验证实际资源状态，不负责会话退出后的自动唤醒。

界面的定时刷新仅更新人看到的内容，不会让 Agent 读取任务、继续执行或被自动唤醒。持续协作仍依赖会话实际运行并遵循 worker 指令；本机 stdio 不自动提供远程/云端连接能力。

开发预览与测试

npx playwright install chromium
npm run check
npm run package:desktop

# 可选：独立浏览器开发预览
npm run build
npm start

预览地址为 http://127.0.0.1:4317，与桌面 stdio 插件使用相同业务服务和默认数据库路径。可用 PORT、SWARMBOARD_DB_PATH 更改设置。预览 HTTP 服务可设置 BOARD_TOKEN 要求 Bearer 认证；普通浏览器不会注入这个令牌。桌面 stdio 不开放监听端口。

测试分层区分领域、SQLite、HTTP、MCP、便携包和浏览器测试各自证明的内容；验证记录只记录实际执行结果。所有确定性测试使用隔离的合成数据，不调用真实模型、不操作开发机。自动化通过不代表真实宿主已安装，也不代表多 Agent 协作效果已验证。

MIT License。