npm package: @opendeepcrew/opendeepcrew
Description: Server and CLI for orchestrating AI coding agent teams with OpenDeepCrew
Author: OpenDeepCrew
Latest version: 0.0.28

# opendeepcrew

[![npm version](https://img.shields.io/npm/v/@opendeepcrew/opendeepcrew.svg)](https://www.npmjs.com/package/@opendeepcrew/opendeepcrew)
[![npm downloads](https://img.shields.io/npm/dm/@opendeepcrew/opendeepcrew.svg)](https://www.npmjs.com/package/@opendeepcrew/opendeepcrew)
[![CI](https://github.com/open-deep-crew/opendeepcrew/actions/workflows/ci.yml/badge.svg)](https://github.com/open-deep-crew/opendeepcrew/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/node/v/@opendeepcrew/opendeepcrew.svg)](https://nodejs.org)

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

AI agent 团队的编排服务器和 CLI。管理工作区、会话、插件市场，可选飞书机器人集成 —— 底层通过 [acpx](https://github.com/openclaw/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 并启动服务。

```text
我需要你帮我安装和启动 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 能力
```

## 安装

```bash
npm install -g @opendeepcrew/opendeepcrew@latest
```

或免安装直接运行：

```bash
npx @opendeepcrew/opendeepcrew@latest
```

## 快速开始

```bash
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

```bash
# 从外部源拉取 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

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

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

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

### Workspace

```bash
# 在当前目录初始化 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` 文件覆盖。

```bash
# 服务基础
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 组合成工作流。

```bash
# 克隆官方模板
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 仓库](https://github.com/open-deep-crew/marketplace)。

## 飞书机器人配置

飞书集成是可选功能。如需使用，需要在[飞书开放平台](https://open.feishu.cn/)创建应用并配置以下权限。

### 应用权限（Scopes）

```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"
    ]
  }
}
```

### 事件订阅

| 事件 | 事件标识 |
|------|----------|
| 解散群 | `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 等），自动上传并以飞书文件/视频消息发送 |

### 环境变量

```bash
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](https://github.com/open-deep-crew/marketplace) | Atom 市场模板 — commands、agents、skills、hooks 的原子仓库 |
| [acpx-teams](https://pypi.org/project/acpx-teams/) | agent 团队协调的 MCP server |

## License

MIT