Skip to main content
Glama
Adrninistrator

volc-aibot

by Adrninistrator
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

火山引擎智能外呼 剧本操作与文本测试工具集

把火山引擎智能外呼控制台（console.volcengine.com/aibot）的网页功能转换为 Python 脚本与 MCP 服务，供 AI 通过自然语言完成剧本的查询、修改、导入、发布与对话测试闭环。

17 个功能脚本 + Web 快捷工具：获取当前登录账号、查询项目组、查询项目组下的剧本、按剧本ID查询、按名称搜索、导出剧本、导入剧本、发布测试版本、查询剧本变量、变量增删改、测试版本变量赋值、文本对话测试、查询剧本基本信息（含 Sub Agent）、查询分析Agent、获取分析Agent内容、批量导出剧本、搜索已导出剧本内容关键字、查询通话明细、删除剧本（仅 _由AI修改 后缀）、修改剧本 json HASH；Web 快捷工具：批量查询剧本信息、批量搜索剧本内容、批量下载搜索分析Agent、批量删除剧本。

目录结构

volcengine_aibot_scripts/
├─ volc_aibot/                  # 公共包（所有脚本与 MCP 共用）
│  ├─ client.py                 # 控制台 API 客户端（全部接口封装+账号守卫）
│  ├─ cookie_client.py          # chrome_capture_operate Cookie 查询客户端
│  ├─ global_config.py          # 全局配置（~/.volcengine_aibot_scripts/global.json）
│  ├─ web/                      # 页面独立文件（2026-09-10 从 web_server.py 拆出）
│  │  └─ index.html             # 整页 HTML（含内联样式与脚本，改后刷新即生效）
│  ├─ web_server.py             # Web 配置页（与 MCP SSE 同端口）
│  ├─ tray.py                   # 系统托盘（双击开页面/右键退出，无窗口运行）
│  ├─ config.py                 # 常量（基址/产品线/变量类型表）
│  ├─ logging_util.py           # 日志（log/ 每天一个文件）
│  └─ result.py                 # 结果目录（result/{日期}/{时间_账号_功能}/）
├─ scripts/                     # 20 个独立可执行脚本（一功能一脚本）
│  ├─ get_current_user.py       # 获取当前登录的账号（--save-allowed 写配置）
│  ├─ query_project_groups.py   # 查询项目组
│  ├─ list_group_scripts.py     # 查询项目组下的剧本
│  ├─ query_script.py           # 根据剧本ID查询剧本
│  ├─ search_script.py          # 根据剧本名称搜索剧本
│  ├─ export_script.py          # 导出剧本
│  ├─ import_script.py          # 导入剧本
│  ├─ publish_preview.py        # 发布剧本测试版本
│  ├─ query_variables.py        # 查询剧本变量
│  ├─ modify_variables.py       # 剧本变量新增/修改/删除
│  ├─ set_preview_variables.py  # 测试版本全局变量赋值
│  ├─ text_chat_test.py         # 文本对话测试（固定话术文件模式）
│  ├─ query_script_info.py      # 查询剧本基本信息（含 Sub Agent/分析Agents）
│  ├─ query_analysis_agents.py  # 查询分析Agent列表（CloudLadder 域）
│  ├─ get_analysis_agent.py     # 获取分析Agent内容（提示词/状态/模型）
│  ├─ batch_export_scripts.py   # 批量导出剧本（按项目组/全部）
│  ├─ search_exported_scripts.py # 搜索已导出剧本内容关键字
│  ├─ query_call_records.py      # 查询通话明细（过滤/分页/参数留档）
│  ├─ delete_script.py           # 删除剧本（仅 _由AI修改 后缀；ID或名称）
│  └─ update_script_hash.py      # 剧本 json HASH（checksum）校验/重算
├─ mcp_server.py                # 服务入口（同端口：Web 配置页 + MCP SSE；托盘）
├─ md/                          # 文档（Web 页面内容：使用说明/适用场景/提示词示例；非技术人员AI协助部署指南）
├─ install.bat                  # 安装依赖（虚拟环境 .venv）
├─ start.bat                    # 启动服务（pythonw 无窗口 + 系统托盘）
├─ requirements.txt             # Python 依赖
├─ queries.txt                  # 文本对话测试示例话术（每行一句）
├─ log/                         # 运行日志（每天一个文件，运行时生成）
└─ result/                      # 结果输出（每次运行一个子目录，运行时生成）

完整文档（项目架构、火山引擎接口协议、用法说明）在服务页面的「使用说明」等标签页中查看（启动后浏览器打开）。

非技术人员部署：电脑上未安装 Git、Python 时，将 md/非技术人员AI协助部署指南.md 的文件路径发给 AI（如 Claude Code）即可，AI 可自行读取该文档并按其协助完成部署，无需复制全文。文档包含已实测验证的下载地址与国内镜像（Python 安装包、项目 ZIP、pip 依赖）、AI 可自动完成与必须人工完成的步骤划分（人工仅 3 项：安装 Chrome 插件、配置 Cookie 推送范围、登录火山引擎控制台）。

Related MCP server: magic-api-mcp-server

快速开始

1. 安装依赖

install.bat          # 创建/复用 .venv 并安装 requests/mcp/uvicorn/sse-starlette/websockets

2. 运行前提（关键）

  • chrome_capture_operate 服务已启动（默认 http://127.0.0.1:33445），Chrome 插件已安装且允许推送 volcengine.com 的 Cookie；

  • 日常 Chrome 已登录火山引擎智能外呼控制台。脚本不写死任何 Cookie，登录态每次运行时实时查询获取。

chrome_capture_operate 的安装与配置说明见其项目 README（github.com/Adrninistrator/chrome_capture_operate 或 gitee.com/adrninistrator/chrome_capture_operate）。

3. 运行脚本（示例）

.venv\Scripts\python.exe scripts\query_script.py llm_xxx
.venv\Scripts\python.exe scripts\export_script.py llm_xxx
.venv\Scripts\python.exe scripts\publish_preview.py llm_xxx --description "发布测试"
.venv\Scripts\python.exe scripts\text_chat_test.py llm_xxx queries.txt

（llm_xxx 替换为实际的剧本ID。）脚本可在任意目录下执行（内部自动把项目根加入 sys.path，PyCharm 与命令行包引用均正确）；每个脚本支持 --help 查看参数。

4. 启动服务（pythonw 无窗口 + 系统托盘；同端口 Web 配置页 + MCP SSE）

start.bat                              # 默认端口（全局配置，缺省 19000）
start.bat 19001                        # 本次覆盖端口

  • 系统托盘：双击打开配置页（http://127.0.0.1:19000/），右键菜单可退出；

  • 配置页（与 MCP SSE 同端口）：快捷工具（批量查询剧本信息、批量搜索剧本内容、批量下载搜索分析Agent，结果支持复制与导出 Excel（首行冻结+筛选，文件名含导出时间）；页面上方可折叠的执行状态面板经 WebSocket 实时展示当前请求、剧本ID/名称与百分比进度，完成时提醒）、设置监听端口（改后需重启）与 允许操作的账号（唯一），显示当前可用的 MCP SSE URL（带复制按钮）；

  • 全局配置文件：C:\Users\<用户名>\.volcengine_aibot_scripts\global.json；

  • 修改守卫：修改类操作执行前先检查「是否允许执行修改操作」开关（默认关闭，未开启一律拒绝），再校验当前 Chrome 登录账号（/console/api/v2/user 的 id）是否为允许账号，不一致拒绝执行；同一 Cookie 未变化时免重复检查；开关未开启或账号未配置时报错并提示到配置页设置（可用 scripts\get_current_user.py --save-allowed 直接写入当前账号）。

5. 安装 MCP 服务到 Claude Code

claude mcp add --scope user --transport sse volc-aibot http://127.0.0.1:19000/sse

MCP 服务共 28 个工具（含 get_current_user 账号工具与 usage_guide 使用说明工具——返回运行前提、各工具用法与典型调用序列，AI 不确定怎么用时先调它）。

新增的剧本信息与分析 Agents 工具：query_script_info（剧本基本信息：类型/最大轮次/模型/ASR/分析Agents挂载/发布状态）、get_sub_agents / get_sub_agent_info（Multi Agents 剧本的 Sub Agent 清单与配置）、query_analysis_agents / get_analysis_agent（分析Agent 列表与内容：系统/用户提示词、发布状态）、batch_export_scripts（批量导出）与 search_exported_scripts（导出内容关键字搜索）。

对话测试提示词示例（⚠ 对话测试占用生产实际外呼资源：请勿同时发起大量会话，避免业务高峰，建议晚上测试——MCP 的 usage_guide 与 Web 配置页均有此提示）：

使用 volc-aibot MCP，先调用 usage_guide 工具了解怎么用，然后与机器人进行任意对话，对话5轮，剧本ID：llm_xxx

典型链路

  • 改剧本变量并测试：query_variables.py → modify_variables.py --op update ... → publish_preview.py（发布后生效）→ text_chat_test.py

  • 复制剧本：export_script.py → import_script.py <文件> <项目组名> → 得到新剧本ID → publish_preview.py（新剧本未发布，对话前必须发布）

  • 变量赋值后对话：set_preview_variables.py --set 变量名=值 → text_chat_test.py（对话 context 默认使用测试版本变量值）

  • 批量导出并检查关键字：batch_export_scripts.py（按项目组导出全部剧本）→ search_exported_scripts.py --dir <导出目录> --keyword <关键字> [--count]（按行搜索是否出现/出现次数）

  • 剧本配置体检：query_script_info.py llm_xxx（类型/轮次/模型/ASR/分析Agents/发布状态一览）；Multi Agents 剧本可用 MCP get_sub_agents/get_sub_agent_info 查各 Sub Agent 的模型与提示词

说明

  • 测试版本全局变量赋值：必填变量（is_required=true）赋值时值不能为空，传空值会被拒绝；

  • 修改类操作执行前会自动备份剧本与变量当前值到 result 目录；

  • 运行产物（log/、result/）运行时生成，已默认 git 忽略。

This server cannot be deployed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers