测试-claude
牛马系统 (Agent API) 说明文档
本文档使用 MrDoc 发布
-
+
首页
牛马系统 (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<br/>消息接口] TG --> AgentAPI[AgentAPI 主进程<br/>PID: 730] AgentAPI <--> Bus[Bus总线<br/>bus.kt8899.org:443<br/>消息中心/心跳监控] AgentAPI --> MCP[MCP子进程<br/>PID: 732<br/>工具协议服务] AgentAPI --> Claude[Claude API<br/>Sonnet模型<br/>编程任务] AgentAPI --> OpenAI[OpenAI Realtime<br/>gpt-4o-realtime<br/>语音交互] MCP --> Tools[MCP工具生态] Tools --> CDP[CDP工具<br/>浏览器自动化] Tools --> MrDoc[MrDoc<br/>文档管理] Tools --> TGTools[Telegram工具<br/>消息收发] Tools --> ChatGPT[ChatGPT<br/>AI对话] Tools --> Scheduler[Scheduler<br/>定时任务] 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* *维护者: 内部团队*
shasha
2025年11月12日 09:50
转发文档
收藏文档
手机扫码
复制链接
手机扫一扫转发分享
复制链接
Markdown文件
PDF文档(打印)
分享
链接
类型
密码
更新密码