牛马系统 (Agent API) 说明文档

# 牛马系统 (Agent API) 说明文档

## 快速启动

```bash
# 基本启动命令
/Users/xyz/Downloads/agentapi -c /Users/xyz/Downloads/config.json

# 启动参数说明：
# -c: 指定配置文件路径
```

**注意**: MCP子进程会自动启动，无需手动执行。

## 系统概述

**牛马系统**是我们内部对 Agent API 进程的称呼，是一个基于 Telegram 的智能助手系统，整合了 Claude AI、OpenAI Realtime API、MCP (Model Context Protocol) 等多种服务。

## 进程信息

### 主进程
```bash
/Users/xyz/Downloads/agentapi -c /Users/xyz/Downloads/config.json
```
- **进程ID**: 730
- **二进制文件**: `/Users/xyz/Downloads/agentapi`
- **配置文件**: `/Users/xyz/Downloads/config.json`

### MCP子进程
```bash
/Users/xyz/Downloads/agentapi mcp -c /Users/xyz/Downloads/config.json
```
- **进程ID**: 732
- **功能**: 提供 MCP (Model Context Protocol) 服务支持

## 核心配置

配置文件位置: `/Users/xyz/Downloads/config.json`

主要配置项：
- **HTTP端口**: 8085
- **Bus服务器**: bus.kt8899.org:443
- **授权用户**: 支持多个Telegram用户/群组
- **AI模型**: Claude Sonnet + OpenAI GPT-4o Realtime
- **工作模式**: 产品经理+Claude编程助手双模式

## 系统架构

```mermaid
graph TB
 TG[Telegram Bot 消息接口]
 
 TG --> AgentAPI[AgentAPI 主进程 PID: 730]
 
 AgentAPI <--> Bus[Bus总线 bus.kt8899.org:443 消息中心/心跳监控]
 
 AgentAPI --> MCP[MCP子进程 PID: 732 工具协议服务]
 AgentAPI --> Claude[Claude API Sonnet模型 编程任务]
 AgentAPI --> OpenAI[OpenAI Realtime gpt-4o-realtime 语音交互]
 
 MCP --> Tools[MCP工具生态]
 
 Tools --> CDP[CDP工具 浏览器自动化]
 Tools --> MrDoc[MrDoc 文档管理]
 Tools --> TGTools[Telegram工具 消息收发]
 Tools --> ChatGPT[ChatGPT AI对话]
 Tools --> Scheduler[Scheduler 定时任务]
 
 style AgentAPI fill:#e1f5ff
 style MCP fill:#ffe1e1
 style Bus fill:#fff4e1
 style Tools fill:#e8f5e8
```

## 功能特性

1. **多AI引擎支持**
   - Claude (Sonnet模型) - 编程和复杂任务
   - OpenAI GPT-4o Realtime - 语音交互

2. **MCP工具生态**
   - CDP (Chrome DevTools Protocol) - 浏览器自动化
   - MrDoc - 文档管理
   - Telegram - 消息收发
   - ChatGPT - AI对话集成
   - Scheduler - 定时任务
   - Bus - 消息总线

3. **智能语音交互**
   - 实时语音识别 (gpt-4o-transcribe)
   - 自动纠错
   - 语音+文字混合输入

4. **团队协作**
   - 多用户/群组支持
   - 会话隔离
   - 工作目录独立管理

## 运维说明

### 启动方式
```bash
cd /Users/xyz/Downloads
./agentapi -c config.json
```

### 配置修改
- 配置文件: `/Users/xyz/Downloads/config.json`
- 修改后需要重启进程生效

### 进程管理
```bash
# 查看进程状态
ps aux | grep agentapi

# 查找主进程
ps aux | grep "agentapi -c"

# 查找MCP子进程
ps aux | grep "agentapi mcp"
```

### 注意事项
- 重启系统后进程会退出，需要手动重启
- 配置文件包含敏感信息（Token、API Key），需妥善保管
- HTTP服务运行在 8085 端口，注意防火墙配置

## 日志与调试

- 工作目录存储在各会话配置的 `working_dir` 中
- 每个聊天会话有独立的工作空间
- 支持实时查看工具调用情况 (`show_tool_calls`)

## CDP 连接故障排查

### 典型报错
- `failed to list targets after 3 attempts: Get "http://localhost:9222/json": dial tcp [::1]:9222: connect: connection refused`
- `Failed to connect to launched Chrome: no page with title found (only blank pages available, please open a webpage first)`

### 根因
- 本地 Chrome 未以 `--remote-debugging-port=9222` 运行，CDP 菜单默认重连 `localhost:9222`，因此端口未监听或只有空白页。

### 修复步骤
1. 在终端执行以下命令，启动一个 headless Chrome 会话监听 9222 端口：
```bash
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
 --remote-debugging-port=9222 \
 --user-data-dir=/Users/xyz/.cdp/headless \
 --no-first-run --no-default-browser-check \
 --disable-gpu --headless=new \
 --window-size=1920,1080 \
 https://example.com >/tmp/cdp_chrome.log 2>&1 &
```
2. 通过 `lsof -i tcp:9222` 或 `curl http://localhost:9222/json/version` 确认端口已监听。
3. 在 Telegram 菜单点击 `🔌 CDP → 重新连接`，或在 Codex 里执行 `cdp_connect_remote` 连接 `localhost:9222`。
4. 调试完成后如需释放资源，`kill <PID>` 结束对应 Chrome 进程并清理 `/Users/xyz/.cdp/headless`。

### 备注
- 独立的 profile 避免污染个人 Chrome，会在 `~/.cdp/headless` 下生成。
- 如需访问其他页面，可修改命令中的 URL，或在连接成功后使用 `Page.navigate` 跳转。

---

*最后更新: 2025-10-14*
*维护者: 内部团队*