# acpx-teams

[![PyPI](https://img.shields.io/pypi/v/acpx-teams)](https://pypi.org/project/acpx-teams/)
[![npm](https://img.shields.io/npm/v/@opendeepcrew/acpx-teams-monitor)](https://www.npmjs.com/package/@opendeepcrew/acpx-teams-monitor)

`acpx-teams` 是一个 MCP Server，用来做多智能体团队编排（团队、任务、消息、状态追踪），底层会调用 [acpx](https://github.com/openclaw/acpx) 管理 ACP 会话。

> 不是 tmux 方案。队友生命周期由 `acpx` 会话管理。

**包地址：**
- PyPI: https://pypi.org/project/acpx-teams/
- npm (监控面板): https://www.npmjs.com/package/@opendeepcrew/acpx-teams-monitor
- GitHub: https://github.com/open-deep-crew/acpx-teams-mcp

---

## 核心能力

- 团队管理：创建/删除团队，读取团队配置
- 队友管理：按后端拉起队友、检查状态、优雅关闭或强制移除
- 任务协作：创建任务、分配 owner、状态推进、依赖关系
- 消息通信：点对点消息、广播、收件箱读取、协议响应

---

## 安装

> 建议固定发布版本（例如 `@0.2.0` 或 Git tag），避免直接跟 `main`。

### PyPI（推荐）

Claude Code（`.mcp.json`）：

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": ["acpx-teams@0.2.0"]
    }
  }
}
```

OpenCode（`~/.config/opencode/opencode.json`）：

```json
{
  "mcp": {
    "acpx-teams": {
      "type": "local",
      "command": ["uvx", "acpx-teams@0.2.0"],
      "enabled": true
    }
  }
}
```

### Git tag

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/open-deep-crew/acpx-teams-mcp@v0.2.0",
        "acpx-teams"
      ]
    }
  }
}
```

---

## 运行要求

- Python `3.12+`
- 已安装 `acpx`（例如 `npm install -g acpx`）
- 你准备使用的后端 CLI 在 `PATH` 可执行

---

## 支持的后端（来自 `_AGENT_REGISTRY`）

当前代码中内置的后端键为：

- `pi`
- `openclaw`
- `codex`
- `claude`
- `gemini`
- `cursor`
- `copilot`
- `droid`
- `iflow`
- `kilocode`
- `kimi`
- `kiro`
- `opencode`
- `qwen`

实际可用集合由 `list_agents` 动态返回：仅当对应 CLI 可执行时才会出现。

---

## 快速工作流

1. `team_create` 创建团队  
2. `list_agents` 查看当前机器可用后端  
3. `spawn_teammate` 指定 `subagent_type` 拉起队友  
4. `task_create` + `task_update(owner=...)` 分配任务  
5. `send_message` 协作推进  
6. `check_teammate` / `team_status` 查看会话状态  
7. `read_inbox` 收集结果  
8. `team_delete` 清理团队（需先移除非 lead 成员）

---

## 监控面板

配合 [@opendeepcrew/acpx-teams-monitor](https://github.com/open-deep-crew/acpx-teams-monitor) 使用，可在浏览器中实时查看团队状态。

### 启动监控服务

```bash
npx @opendeepcrew/acpx-teams-monitor
```

默认监听 `http://localhost:7201`。

### 自动获取监控链接

`team_create` 返回结果中包含 `monitor_url` 字段，直接点击即可查看该团队的监控面板：

```
http://localhost:7201/?teamname=my-team&cwd=%2FUsers%2Fme%2Fproject
```

### 自定义端口

如果监控服务使用了非默认端口，在 MCP 配置中设置 `ACPX_MONITOR_URL` 环境变量：

```json
{
  "mcpServers": {
    "acpx-teams": {
      "command": "uvx",
      "args": ["acpx-teams@0.2.0"],
      "env": {
        "ACPX_MONITOR_URL": "http://localhost:9999"
      }
    }
  }
}
```

---

## MCP 工具

| 工具 | 说明 |
| --- | --- |
| `team_create` | 创建团队 |
| `team_delete` | 删除团队（有非 lead 成员时会失败） |
| `read_config` | 读取团队配置 |
| `list_agents` | 列出当前机器可用后端 |
| `spawn_teammate` | 通过 acpx 创建队友会话 |
| `send_message` | 私信/广播/关闭响应/计划响应 |
| `read_inbox` | 读取指定成员收件箱 |
| `task_create` | 创建任务 |
| `task_update` | 更新任务状态、owner、依赖、metadata |
| `task_list` | 列出全部任务 |
| `task_get` | 读取任务详情 |
| `team_status` | 查看全队会话状态 |
| `check_teammate` | 查看单个队友状态和待处理消息 |
| `force_kill_teammate` | 强制关闭队友会话并移除 |
| `process_shutdown_approved` | 处理已批准的优雅关闭 |

---

## 数据目录

```text
~/.acpx/
├── teams/<team>/
│   ├── config.json
│   └── inboxes/
│       ├── team-lead.json
│       ├── <member>.json
│       └── .lock
└── tasks/<team>/
    ├── 1.json
    ├── 2.json
    └── .lock
```

---

## 排障

- `acpx binary not found`：先安装 `acpx`，并确认在 `PATH`
- `list_agents` 为空：对应后端 CLI 未安装或不可执行
- `spawn_teammate` 后长期 `no-session`：检查后端命令可执行性与工作目录权限
- `team_delete` 失败：先关闭并移除所有非 `team-lead` 成员

---

## 许可证

[MIT](./LICENSE)
