opendeepcrew

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

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

• 工作区隔离：每个工作区独立配置 agent、MCP servers、hooks 和 skills
• 插件市场：从本地路径或 git 仓库加载 commands、agents、skills、hooks
• 会话管理：创建、监控、取消 agent 会话，实时流式日志
• 多 agent 初始化：workspace init 自动绑定工作区，默认生成所有 agent 配置，--agent 可限定为单一 agent 类型
• 飞书机器人：通过聊天驱动 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. 同时安装 acpx（agent 会话引擎）：
   npm install -g acpx@latest

3. 启动服务：
   odc server

   首次启动会自动运行初始化向导，引导你完成：
   - 设置服务端口（默认 4000）
   - 配置市场源（Marketplace Source）：本地路径或 git 仓库 URL

   配置保存在 ~/.opendeepcrew/.env，之后可通过 Web 控制台或
   odc config set <key> <value> 随时修改。

   服务启动后访问 http://localhost:4000 进入 Web 控制台。

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

5. （可选）飞书机器人集成：

   a. 在飞书开放平台（https://open.feishu.cn/）创建应用，获取 App ID 和 App Secret。

   b. 在 http://localhost:4000/settings 中配置飞书参数：
      - FEISHU_APP_ID：飞书 App ID（如 cli_xxx）
      - FEISHU_APP_SECRET：飞书 App Secret
      - FEISHU_BOT_NAME：机器人显示名称

   c. 为应用添加权限 — 在飞书开放平台的"权限管理"中导入以下 JSON：
      {"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"]}}

   d. 配置事件订阅（使用长连接方式，无需公网域名）：
      - 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（机器人自定义菜单事件）

   e. 配置回调：订阅方式选择"长连接"，已订阅回调添加 card.action.trigger（卡片回传交互）。

   f. 在飞书开放平台 → 机器人 → 自定义菜单中添加菜单项：
      - 菜单名称：自定义（如：提交需求）
      - 事件 ID：add_requirement（必须完全一致）
      用户点击菜单后，飞书推送 application.bot.menu_v6 事件，
      服务端通过 event_key: "add_requirement" 路由到对应工作流入口。

   g. （可选）团队模式 — 多机器人池：
      在 settings 中启用 TEAM_MULTIBOT_ENABLED=true，
      配置 TEAM_BOT_POOL=bot1:appId1:secret1,bot2:appId2:secret2
      池中机器人仅需 im:message 和 im:message:send_as_bot 两个权限，
      不需要事件订阅和回调配置。

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

安装

npm install -g @opendeepcrew/opendeepcrew@latest

或免安装直接运行：

npx @opendeepcrew/opendeepcrew@latest

快速开始

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

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

CLI 命令

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

Marketplace

# 从外部源拉取 atom 到本地 marketplace
odc marketplace add --type <type> <source>
# type: skill | command | hook | agent
# source: 本地路径、git URL 或 GitHub 子目录 URL
# 示例：
odc marketplace add --type skill /path/to/cool-skill
odc marketplace add --type agent https://github.com/someone/repo.git
odc marketplace add --type skill https://github.com/someone/repo/tree/main/path/to/skill

# 显示完整的 registry 数据（JSON 输出）
odc marketplace show

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

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

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

# 非交互式添加 plugin（通过参数直接传入数据）
odc marketplace plugin add <name> \
  --description "插件描述" \
  --category "分类" \
  --skills skill1,skill2 \
  --commands cmd1,cmd2 \
  --agents agent1,agent2 \
  --mcps '{"server-name": {"command":"xxx","args":["yyy"]}}'

# 增量修改已有 plugin（atoms + MCP servers）
odc marketplace plugin patch <name> \
  --skills-add skill3 --skills-remove skill1 \
  --commands-add cmd3 --commands-remove cmd1 \
  --agents-add agent3 --agents-remove agent1 \
  --hooks-add hook3 --hooks-remove hook1 \
  --mcp-add '{"new-server":{"command":"npx","args":["-y","tool"]}}' \
  --mcp-remove old-server,legacy-server

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

# Atom 管理
odc marketplace atom list                    # 列出所有 atom（含 description）
odc marketplace atom list --type skill       # 按类型过滤
odc marketplace atom show agent bot          # 查看 atom 内容
odc marketplace atom delete agent old-bot    # 删除 atom

# 版本管理（所有写操作自动 git commit，支持回退）
odc marketplace history                      # 查看变更历史
odc marketplace history -n 50                # 显示最近 50 条
odc marketplace rollback <commit-hash>       # 回退指定变更
odc marketplace sync                         # 与远程仓库同步（pull + push）

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）。

Config

# 显示全部配置（JSON 输出，按分组展示所有配置项及当前值）
odc config show

# 获取单个配置值（key 为环境变量名，如 PORT、FEISHU_APP_ID）
odc config get <key>

# 设置单个配置值（未知 key 会报错）
odc config set <key> <value>

Workspace

# 在当前目录初始化 plugin，并自动在 ~/.opendeepcrew/workspaces/ 下创建绑定的 workspace
# 不指定 --agent 时，默认生成所有启用 agent 的配置文件（.claude/、.kiro/、.cursor/ 等）
odc workspace init <plugin>

# 指定 agent 类型（只生成该 agent 的配置文件，适合只使用单一 IDE 的场景）
odc workspace init <plugin> --agent claude-code # 只生成 .claude/ 配置
odc workspace init <plugin> --agent kiro        # 只生成 .kiro/ 配置
odc workspace init <plugin> --agent cursor      # 只生成 .cursor/ 配置

# 指定 plugin 来源（本地或 subscription）
odc workspace init <plugin> --source local
odc workspace init <plugin> --source <subscription-name>

# Workspace 名称由当前目录自动派生（格式：<文件夹名>-<路径hash前6位>），例如 my-project-a3b4c5
# 同一目录重复执行（reinit）只同步初始化时记录的 agent 配置文件，其他 agent 目录不受影响
# 同一目录重复执行会跳过创建，直接重新初始化配置文件

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

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

# 更新 workspace 的 agent 权限模式或 agent 类型
odc workspace update <name> --permission-mode <mode>
# mode: approve-all（默认，自动批准所有操作）或 approve-reads（仅自动批准读操作）
odc workspace update <name> --agent kiro
# 修改立即生效，无需重启服务或重建 session

IDE 支持

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

| IDE | 检测命令 | |-----|---------| | Cursor | which cursor | | VS Code | which code | | Windsurf | which windsurf | | Kiro | which kiro | | Codex | which codex | | 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

# 飞书机器人（可选）
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_BOT_NAME=MyBot
# 会话
SESSION_TTL_MS=300000              # 会话空闲超时（毫秒）
HIDE_TOOL_CARDS=false              # 隐藏飞书中的工具调用状态卡片

# 团队模式（可选）
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              # 主机器人显示名称
HIDE_TOOL_CARDS=false              # 隐藏工具调用状态卡片（⏳/✅/❌）

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

相关项目

| 项目 | 说明 | |------|------| | marketplace | Atom 市场模板 — commands、agents、skills、hooks 的原子仓库 | | acpx-teams | agent 团队协调的 MCP server |

License

MIT