# volcengine_aibot_scripts **Repository Path**: adrninistrator/volcengine_aibot_scripts ## Basic Information - **Project Name**: volcengine_aibot_scripts - **Description**: 火山引擎AI外呼管理台操作脚本，支持MCP服务 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-05 - **Last Updated**: 2026-09-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 火山引擎智能外呼 剧本操作与文本测试工具集 把火山引擎智能外呼控制台（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 推送范围、登录火山引擎控制台）。 ## 快速开始 ### 1. 安装依赖 ```bat 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. 运行脚本（示例） ```bat .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） ```bat 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 ```bash 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 忽略。