# 需求文档

## 简介

将 claude-teams MCP server 中所有 backend（claude 和 opencode）替换为使用 `acpx` CLI 工具，并完全去掉 tmux 依赖。`acpx` 是一个统一的 CLI 工具，通过 subprocess 调用来管理 AI agent session 的生命周期。迁移后，系统不再依赖 tmux 进行进程管理，改为通过 `acpx` CLI 的 session 机制来 spawn、通信和监控 teammate。

## 术语表

- **系统（System）**：claude-teams MCP server 整体
- **AcpxClient**：封装 `acpx` CLI 调用的 Python 模块（替代 opencode_client.py）
- **Spawner**：负责创建 teammate 进程的模块（spawner.py）
- **Session**：由 `acpx` 管理的 agent 运行实例，通过 session name 唯一标识
- **Session_Name**：格式为 `<name>@<team_name>` 的字符串，与现有 agent_id 一致
- **Agent**：`acpx` 支持的 AI agent 类型（如 `claude`、`codex` 等），对应现有的 `subagent_type`
- **TeammateMember**：代表一个 teammate 的数据模型
- **TeamLead**：团队 lead agent，不通过 acpx 管理
- **收件箱（Inbox）**：基于文件系统的消息队列，用于 agent 间通信

## 需求

### 需求 1：AcpxClient 模块

**用户故事：** 作为开发者，我希望有一个 AcpxClient 模块来封装 acpx CLI 调用，以便系统其他部分可以管理 agent session 而无需直接调用 subprocess 命令。

#### 验收标准

1. THE AcpxClient 应提供 `create_session(agent, session_name)` 函数，通过 subprocess 执行 `acpx <agent> sessions new --name <session_name>`
2. THE AcpxClient 应提供 `send_prompt(agent, session_name, prompt)` 函数，通过 subprocess 执行 `acpx <agent> -s <session_name> '<prompt>' --no-wait`
3. THE AcpxClient 应提供 `close_session(agent, session_name)` 函数，通过 subprocess 执行 `acpx <agent> sessions close <session_name>`
4. THE AcpxClient 应提供 `get_session_status(agent, session_name)` 函数，通过 subprocess 执行 `acpx <agent> status -s <session_name>` 并返回状态字符串
5. WHEN acpx subprocess 调用返回非零退出码，THE AcpxClient 应抛出 `AcpxError` 异常，并将 stderr 输出作为错误信息
6. WHEN `acpx` 二进制文件不在 PATH 中，THE AcpxClient 应抛出 `AcpxError`，并附带描述性错误信息说明二进制文件缺失
7. THE AcpxClient 应对所有 subprocess 调用使用可配置的超时时间（默认 30 秒）

### 需求 2：Session Name 格式

**用户故事：** 作为开发者，我希望 session name 遵循统一格式，以便 session 可以被唯一标识并与团队成员关联。

#### 验收标准

1. THE 系统 应使用 `<name>@<team_name>` 作为所有 acpx session 的 session name 格式
2. WHEN 创建 TeammateMember 时，THE 系统 应将 `acpx_session_name` 设置为 `<name>@<team_name>`
3. THE 系统 应确保 session name 与现有 `agent_id` 字段格式保持一致

### 需求 3：TeammateMember 数据模型更新

**用户故事：** 作为开发者，我希望 TeammateMember 模型能反映新的 acpx 架构，以便数据模型准确表示系统状态。

#### 验收标准

1. THE TeammateMember 应将 `tmux_pane_id`、`opencode_session_id` 和 `backend_type` 字段替换为单一的 `acpx_session_name` 字段
2. WHEN 创建 TeammateMember 时，THE 系统 应将 `acpx_session_name` 设置为字符串 `<name>@<team_name>`
3. THE 系统 应从 TeammateMember 中移除 `backend_type` 字段
4. THE ShutdownApproved 模型 应更新，移除 `pane_id`、`backend_type` 和 `session_id` 字段，替换为 `acpx_session_name`
5. THE LeadMember 模型 应移除 `tmux_pane_id` 字段

### 需求 4：Spawner 模块重写

**用户故事：** 作为开发者，我希望 spawner 使用 acpx 而非 tmux，以便 teammate 进程通过 acpx session 生命周期进行管理。

#### 验收标准

1. WHEN 调用 `spawn_teammate` 时，THE Spawner 应调用 `AcpxClient.create_session(subagent_type, session_name)` 创建新的 acpx session
2. WHEN 调用 `spawn_teammate` 时，THE Spawner 应调用 `AcpxClient.send_prompt(subagent_type, session_name, wrapped_prompt)` 发送初始 prompt
3. THE Spawner 应移除所有 tmux 相关代码，包括 `build_tmux_spawn_args`、`kill_tmux_pane`、`use_tmux_windows` 和 `build_spawn_command`
4. THE Spawner 应移除所有 opencode 特定代码，包括 `build_opencode_attach_command` 和 opencode_client 导入
5. WHEN `spawn_teammate` 在创建 session 后失败，THE Spawner 应调用 `AcpxClient.close_session` 清理 session
6. THE Spawner 应从 `spawn_teammate` 中移除 `backend_type`、`opencode_binary`、`opencode_server_url` 和 `opencode_agent` 参数
7. THE Spawner 应使用 prompt 包装模板（适当重命名）来包装通过 acpx 发送的 prompt

### 需求 5：Server 模块更新

**用户故事：** 作为开发者，我希望 MCP server 使用新的 acpx 架构，以便所有工具处理器能与新 backend 正确协作。

#### 验收标准

1. THE Server 应将所有 `opencode_client` 导入替换为 `acpx_client` 导入
2. THE Server 应移除所有 tmux 相关导入，包括 `kill_tmux_pane`、`use_tmux_windows` 和 `tmux_introspection`
3. THE Server 应移除 `_push_to_opencode_session`、`_push_to_lead`、`_cleanup_opencode_session` 和 `_discover_lead_opencode_session` 函数
4. THE Server 应移除与 backend 选择相关的 `KNOWN_CLIENTS`、`_VALID_BACKENDS`、`_parse_backends_env` 逻辑
5. WHEN 调用 `check_teammate` 时，THE Server 应使用 `AcpxClient.get_session_status` 判断 teammate 是否存活
6. WHEN 调用 `force_kill_teammate` 时，THE Server 应调用 `AcpxClient.close_session` 终止 session
7. WHEN 调用 `process_shutdown_approved` 时，THE Server 应调用 `AcpxClient.close_session` 终止 session
8. THE Server 应从 `check_teammate` 中移除 `notify_after_minutes` 参数和推送通知逻辑
9. THE Server 应简化 `spawn_teammate_tool`，移除 `backend_type` 参数和 opencode 特定逻辑
10. THE Server 应更新 `send_message`，移除 opencode 推送通知调用

### 需求 6：移除 tmux_introspection.py

**用户故事：** 作为开发者，我希望完全移除 tmux 依赖，以便系统不再依赖 tmux 的安装。

#### 验收标准

1. THE 系统 不应导入或使用 `tmux_introspection.py` 中的任何函数
2. THE 系统 应删除 `tmux_introspection.py` 文件

### 需求 7：acpx 二进制发现

**用户故事：** 作为开发者，我希望系统在启动时验证 acpx 是否可用，以便用户在 acpx 未安装时能收到清晰的错误信息。

#### 验收标准

1. WHEN MCP server 启动时，THE 系统 应使用 `shutil.which` 检查 PATH 中是否存在 `acpx` 二进制文件
2. IF `acpx` 二进制文件未找到，THEN THE 系统 应抛出 `FileNotFoundError`，并附带描述性错误信息
3. THE Server 应将发现的 `acpx` 二进制路径存储在 lifespan state 中

### 需求 8：check_teammate 状态检查

**用户故事：** 作为开发者，我希望 check_teammate 使用 acpx status 而非 tmux，以便在不依赖 tmux 的情况下判断 teammate 的存活状态。

#### 验收标准

1. WHEN 调用 `check_teammate` 时，THE Server 应调用 `AcpxClient.get_session_status(agent, session_name)` 检查 session 是否存活
2. THE Server 应在状态为 `"alive"` 时认为 session 存活，在状态为 `"dead"` 或抛出 `AcpxError` 时认为 session 已终止
3. THE Server 应从 `check_teammate` 中移除 `include_output` 和 `output_lines` 参数，因为 acpx 不再提供终端输出访问
