opendeepcrew

OpenDeepCrew 处于 alpha 阶段，API 和配置格式可能会变。

AI agent 团队的编排服务器和 CLI。管理工作区、会话、插件市场，可选飞书机器人集成 —— 底层通过 acpx 驱动 agent 生命周期。

• 工作区隔离：每个工作区独立配置 agent、MCP servers、hooks 和 skills
• 插件市场：从本地路径或 git 仓库加载 commands、agents、skills、hooks
• 会话管理：创建、监控、取消 agent 会话，实时流式日志
• 多 agent 初始化：一键为 Claude Code 或 Kiro 生成工作区配置
• 飞书机器人：通过聊天驱动 agent 交互，支持图片/文件/视频，多机器人池
• 团队模式：spawn agent 团队，@mention 路由消息，按成员读取 inbox
• Web 控制台：浏览市场、管理工作区、监控会话、查看日志、编辑设置
• 优雅重启：设置变更触发零停机重启（exit code 120 协议）

快速上手 — 把这段发给你的 agent

复制下面这段文字，粘贴到 Claude Code、Kiro 或其他 agent 中。它会帮你安装 OpenDeepCrew 并启动服务。

我需要你帮我安装和启动 OpenDeepCrew，一个 AI agent 团队的编排服务器。

1. 全局安装（推荐）：
   npm install -g @opendeepcrew/opendeepcrew@latest

   或免安装运行：
   npx @opendeepcrew/opendeepcrew@latest

2. 启动服务：
   opendeepcrew server

   服务默认运行在 http://localhost:4000，包含 Web 控制台。

3. 同时需要安装 acpx（agent 会话引擎）：
   npm install -g @opendeepcrew/acpx@latest

4. 如果需要团队协作的 MCP server，安装 acpx-teams：
   uvx acpx-teams

5. 克隆 atom 市场模板，作为插件源：
   git clone https://github.com/open-deep-crew/marketplace.git
   cd marketplace
   npm install
   npm run generate-registry

   市场中的 atoms（commands、agents、skills、hooks）会在创建工作区时
   自动复制到 agent 配置中。你可以往 atoms/ 目录添加自己的原子，
   在 .claude-plugin/marketplace.json 中组合成 plugin。

6. 打开 http://localhost:4000/settings 完成服务配置（市场路径、飞书机器人等）。
   在 Marketplace Source 字段中填入第 5 步 clone 下来的目录绝对路径，
   将其设置为市场数据源。

7. 在飞书开放平台为机器人添加自定义菜单：
   - 菜单名称：自定义（如：提交需求）
   - 事件 ID：add_requirement（必须完全一致）

   用户点击菜单后，飞书推送 application.bot.menu_v6 事件，
   服务端通过 event_key: "add_requirement" 路由到对应工作流入口。

从现在开始，用 OpenDeepCrew 来管理工作区和 agent 会话。例如：
  - 在控制台创建工作区，选择 Claude Code 或 Kiro 作为 agent
  - 通过 acpx 与 agent 交互：acpx claude "修复测试"
  - 在控制台监控会话日志和状态
  - 往 marketplace 添加 atoms 来扩展 agent 能力

安装

npm install -g @opendeepcrew/opendeepcrew@latest

或免安装直接运行：

npx @opendeepcrew/opendeepcrew@latest

快速开始

opendeepcrew server              # 在 4000 端口启动服务
opendeepcrew server --port 8080  # 自定义端口

浏览器打开 http://localhost:4000 进入控制台。

CLI 命令

除了启动服务器，OpenDeepCrew 还提供 CLI 子命令来管理 marketplace 和 workspace。CLI 命令与 Web UI 互补：CLI 擅长拉取外部 atom、IDE 打开、交互式组合；Web UI 擅长浏览、可视化、workspace CRUD。

Marketplace

# 从外部源拉取 atom 到本地 marketplace
opendeepcrew marketplace add --type <type> <source>
# type: skill | command | hook | agent
# source: 本地路径或 git URL
# 示例：
opendeepcrew marketplace add --type skill /path/to/cool-skill
opendeepcrew marketplace add --type command https://github.com/someone/repo/atoms/commands/deploy.md

# 在 IDE 中打开 marketplace 仓库（自动探测已安装 IDE）
opendeepcrew marketplace edit

# 列出所有 plugin，上下键选择后编辑或创建新 plugin
opendeepcrew marketplace plugin list

# 直接创建新 plugin（交互式 tab 选择器勾选 atoms）
opendeepcrew marketplace plugin create

# 删除 plugin（交互选择或直接指定名称）
opendeepcrew marketplace plugin delete
opendeepcrew marketplace plugin delete <name>

marketplace plugin list / create 交互说明

进入 plugin 向导后：

1. 基本信息：依次输入名称、描述、分类，Enter 确认进入下一步
2. 组件选择：Tab/←/→ 切换分类（Commands、Skills、Hooks、Agents、MCP），↑/↓ 导航，Space 勾选/取消，支持输入搜索过滤
3. 保存：Enter 进入确认，输入 yes 保存，no 回到选择
4. 退出：Esc 进入退出确认，输入 yes 放弃修改退出，no 回到选择

如果输入的 plugin 名称已存在，自动进入编辑模式（预填充描述、分类，预勾选已有 atoms）。

Workspace

# 列出所有 workspace，上下键选择后在 IDE 中打开
opendeepcrew workspace list

# 直接在 IDE 中打开指定 workspace
opendeepcrew workspace open <name>

IDE 支持

CLI 自动探测以下 IDE，多个时上下键选择：

| IDE | 检测命令 | |-----|---------| | Cursor | which cursor | | VS Code | which code | | Windsurf | which windsurf | | Kiro | which kiro | | WebStorm | which webstorm | | IDEA | which idea |

架构

┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
│  Web UI      │────▸│  opendeepcrew    │────▸│  acpx       │
│  (React)     │◂────│  (Express API)   │◂────│  (sessions) │
└──────────────┘     └──────┬───────────┘     └──────┬──────┘
                            │                        │
                     ┌──────▼───────────┐     ┌──────▼──────┐
                     │  Marketplace     │     │  Claude,    │
                     │  (plugins/atoms) │     │  Kiro, ...  │
                     └──────────────────┘     └─────────────┘

1. Marketplace 从本地路径或 git 仓库解析插件，将 commands/agents/skills/hooks 暴露为 atoms
2. Workspaces 是隔离目录。创建工作区时复制市场 atoms 并生成 agent 专属配置（.claude/ 或 .kiro/）
3. Sessions 是 acpx 管理的 agent 进程。API 封装了 acpx 的 createSession、sendSession、closeSession，提供 REST 端点和日志流
4. 飞书插件（可选）将飞书机器人连接到服务器，支持聊天驱动的 agent 交互，包括图片/文件/视频

API

| 方法 | 路径 | 说明 | |------|------|------| | GET | /api/health | 服务器运行时间、内存、状态 | | GET | /api/marketplace/plugins | 列出所有插件和 atoms | | POST | /api/marketplace/refresh | 从源重新加载市场 | | GET | /api/workspaces | 列出所有工作区 | | POST | /api/workspaces | 创建工作区并初始化 agent 配置 | | DELETE | /api/workspaces/:name | 删除工作区 | | POST | /api/workspaces/:name/reinit | 重新初始化 agent 配置 | | GET | /api/sessions | 列出所有活跃会话 | | GET | /api/sessions/:id/logs | 流式读取会话日志（自动折叠） | | POST | /api/sessions/:id/cancel | 取消正在运行的 prompt | | DELETE | /api/sessions/:id | 关闭会话 | | GET | /api/settings | 读取分组配置 | | PUT | /api/settings | 更新配置（仅限 localhost） | | POST | /api/settings/restart | 触发优雅重启 |

配置

所有配置通过 ~/.opendeepcrew/.env 文件管理（也可通过 Web 控制台设置页面编辑）。.env 文件是唯一的配置来源，shell export 的同名环境变量会被 .env 文件覆盖。

PORT=4000                          # 服务端口
MARKETPLACE_SOURCE=./marketplace   # 插件源，本地路径或 git URL
OPENDEEPCREW_ROOT=~/.opendeepcrew # 数据目录

# 飞书机器人（可选）
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_BOT_NAME=MyBot

# 会话
SESSION_TTL_MS=300000              # 会话空闲超时（毫秒）

# 团队模式（可选）
TEAM_MULTIBOT_ENABLED=false
TEAM_BOT_POOL=bot1:appId1:secret1,bot2:appId2:secret2

Atom 市场

OpenDeepCrew 通过 atom 市场管理插件。市场是一个 git 仓库，包含 commands、agents、skills、hooks 四类原子，通过 plugins 组合成工作流。

# 克隆官方模板
git clone https://github.com/open-deep-crew/marketplace.git ~/my-marketplace

# 在配置文件中指向你的市场（必须是绝对路径）
# 编辑 ~/.opendeepcrew/.env，添加：
# MARKETPLACE_SOURCE=/Users/你的用户名/my-marketplace

也可以通过 Web 控制台 http://localhost:4000/settings 的 Marketplace Source 字段设置。

创建工作区时，OpenDeepCrew 自动从市场拉取 atoms 并生成 agent 配置（.claude/ 或 .kiro/）。

详见 marketplace 仓库。

飞书机器人配置

飞书集成是可选功能。如需使用，需要在飞书开放平台创建应用并配置以下权限。

应用权限（Scopes）

{
  "scopes": {
    "tenant": [
      "cardkit:card:write",
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "helpdesk:all:readonly",
      "im:chat",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": [
      "contact:user.employee_id:readonly",
      "im:chat",
      "im:chat.members:read",
      "im:chat:read",
      "im:chat:readonly"
    ]
  }
}

事件订阅

| 事件 | 事件标识 | |------|----------| | 解散群 | im.chat.disbanded_v1 | | 机器人进群 | im.chat.member.bot.added_v1 | | 机器人被移出群 | im.chat.member.bot.deleted_v1 | | 消息已读 | im.message.message_read_v1 | | 接收消息 | im.message.receive_v1 | | 收到服务台消息 | helpdesk.ticket_message.created_v1 | | 机器人自定义菜单事件 | application.bot.menu_v6 |

自定义菜单配置

飞书机器人必须创建自定义菜单，菜单是触发工作流的唯一入口。

在飞书开放平台 → 机器人 → 自定义菜单中添加菜单项：

| 配置项 | 值 | |--------|-----| | 菜单名称 | 自定义（如：提交需求） | | 事件 ID | add_requirement（必须完全一致） |

注意：事件 ID 必须是 add_requirement，服务端通过此 ID 识别并调起对应工作流。其他 ID 不会触发任何处理逻辑。

用户点击菜单后，飞书会向服务端推送 application.bot.menu_v6 事件，事件 payload 中携带 event_key: "add_requirement"，服务端据此路由到对应工作流入口。

回调配置

| 配置项 | 值 | |--------|-----| | 订阅方式 | 长连接（推荐，无需公网域名） | | 已订阅回调 | card.action.trigger（卡片回传交互） |

机器人池（团队模式）

启用 TEAM_MULTIBOT_ENABLED=true 后，池中的每个机器人只需最小权限：

{
  "scopes": {
    "tenant": [
      "im:message",
      "im:message:send_as_bot"
    ],
    "user": []
  }
}

池中机器人不需要事件订阅和回调配置，仅主机器人需要。

消息流支持

入站（用户 → agent）

| 消息类型 | 处理方式 | 说明 | |---------|---------|------| | 纯文本 text | 直接传递 | 原样发送给 agent | | 富文本 post | 提取文本 + 下载图片 | 文本拼接，图片保存为本地文件，以 [media:image path] 占位符传给 agent | | 图片 image | 下载保存 | 通过飞书 API 下载，保存到 media/inbound/，以 [media:image path] 传给 agent | | 视频 video / media | 下载保存 | 同上，以 [media:video path] 传给 agent | | 音频 audio | 下载保存 | 同上，以 [media:audio path] 传给 agent | | 文件 file | 下载保存 | 同上，以 [media:document path] 传给 agent | | 飞书文档链接 | 拉取内容保存 | 通过飞书 Open API 获取文档纯文本，保存为 .md 文件，以 [media:document path] 传给 agent。支持 docx 和 wiki（底层为 docx）；docs（旧版）和 sheets 暂不支持 | | file:// 本地文件链接 | 路径透传 | 校验文件存在且为文本类型后，以 [media:document path] 传给 agent |

所有媒体文件保存在 media/inbound/ 目录，文件名为 UUID，自动清理（默认 2 分钟 TTL）。agent 通过文件路径按需读取内容。

出站（agent → 用户）

| 内容类型 | 处理方式 | |---------|---------| | 文本回复 | 以飞书卡片（AI Response）发送，支持 Markdown，自动防抖合并更新 | | 工具调用 | 每个 tool call 单独发一张状态卡片（⏳运行中 / ✅完成 / ❌失败），可通过 HIDE_TOOL_CARDS=true 关闭 | | 图片路径 | 检测 agent 输出中的图片路径，自动上传并以飞书图片消息发送 | | 文件路径 | 检测 agent 输出中的文件路径（pdf、docx、mp4 等），自动上传并以飞书文件/视频消息发送 |

环境变量

FEISHU_APP_ID=cli_xxx              # 主机器人 App ID
FEISHU_APP_SECRET=xxx              # 主机器人 App Secret
FEISHU_BOT_NAME=MyBot              # 主机器人显示名称

# 团队模式（可选）
TEAM_MULTIBOT_ENABLED=false        # 启用多机器人池
TEAM_BOT_POOL=bot1:appId1:secret1,bot2:appId2:secret2  # 池中机器人列表

相关项目

| 项目 | 说明 | |------|------| | marketplace | Atom 市场模板 — commands、agents、skills、hooks 的原子仓库 | | @opendeepcrew/acpx | Agent Client Protocol 的 headless CLI 客户端 | | acpx-teams | agent 团队协调的 MCP server |

License

MIT