牛马系统 (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`)

---

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