yingdao-RPA-mcp

<div align="center"> # yingdao-RPA-mcp **把影刀（ShadowBot）社区版机器人变成 AI 助手里的"原生工具"—— 微信里说一句话，就能列出、启动、停止你电脑上的 RPA 流程。** [](https://github.com/Seethelightdie/yingdao-RPA-mcp/actions/workflows/ci.yml) [](LICENSE) [](https://www.python.org/) [](https://www.yingdao.com/) English TL;DR: An MCP (Model Context Protocol) server that exposes Yingdao/ShadowBot **Community Edition** RPA robots to any AI client. Local `stdio` + remote `streamable-http` (Tailscale-friendly) with token auth, a built-in Mock mode, graceful-stop-only design (never kill processes), and 94 cross-platform tests. MIT licensed, unofficial, community-driven. </div> --- ## 为什么做这个 影刀社区版没有官方 API，机器人只能靠人点界面启动。已有的民间方案（见[致谢](#-致谢)）解决了 "远程一键启动"，但接到 AI 助手上还有四道坎：**协议不对口**（AI 助手说 MCP）、**跑完没下文**（拿不到结构化结果）、 **停止不可靠**（杀进程会烂尾）、**远程不安全**（裸端口）。 本项目把影刀社区版的四条"民间侦察通道"封装成 5 个标准 MCP 工具，在 52 台真实机器人的环境里、 通过微信 AI 助手完成了端到端验收。 ## 功能特性 - 🔧 **5 个 MCP 工具**：`list_robots` 列出 / `run_robot` 启动（支持中文传参、产出文件回收）/ `get_status` 三层日志验证 / `stop_robot` 优雅停止 / `tail_log` 排障 - 🔌 **双传输**：本地 `stdio`（Claude Desktop 即插即用）+ 远程 `streamable-http`（Tailscale 组网跨网操控） - 🔐 **安全边界**：静态 Bearer token、绑定地址可控、stateless-http（网关重启对客户端透明）、 Windows 防火墙仅放行 Tailscale 网段 - 🧪 **Mock 模式**：没有 Windows / 没装影刀也能体验全部工具，同时是 94 个自动化测试的替身 - 🛑 **只优雅停止，永不杀进程**：`keybd_event` 发送 Ctrl+Alt+Q（工具描述内置全局停止警告， AI 会先向你确认） - 🇨🇳 **中文友好**：机器人名/传参值支持中文原样，错误信息统一"code + 中文说明 + 下一步提示" - 📦 **Windows 一键安装**：一条命令完成 Python 探测、虚拟环境、token、防火墙、开机自启、自检 ## 5 个工具一览 | 工具 | 作用 | |---|---| | `list_robots` | 扫描影刀用户目录，返回 uuid/名称/版本/描述/路径（按修改时间排序） | | `run_robot` | 启动机器人，支持 `key=value` 传参（值支持中文）；可指定产出目录，返回运行期间新增的文件 | | `get_status` | 解析影刀当日日志 + 进程存活检测，返回 运行中/已退出/未知 与证据链 | | `stop_robot` | 发送 Ctrl+Alt+Q 优雅停止（⚠️ 全局生效——会停掉**所有**运行中的机器人，工具描述已强制警告） | | `tail_log` | 读取影刀当日日志尾部，排障用 | ## 快速开始 ### 前置条件 - 影刀社区版已安装（[官网](https://www.yingdao.com/)） - Python 3.10+（仅本地 stdio / 手动运行需要；一键安装脚本会自动引导） - 一个支持 MCP 的 AI 客户端（Claude Desktop、微信 AI 助手等） ### 形态一：Mock 模式（先体验，30 秒） 任何系统（含 Linux/macOS）都能跑，不需要影刀： ```bash pip install -e . python -m yingdao_rpa_mcp --mock # stdio，接到任意 MCP 客户端 ``` MCP Inspector 里看效果： ```bash npx @modelcontextprotocol/inspector python -m yingdao_rpa_mcp --mock ``` 你会看到 3 个演示机器人，所有返回都带 `"mock": true` 标识。 ### 形态二：本机 AI 客户端（Claude Desktop + 真实影刀，stdio） Claude Desktop 配置文件（`claude_desktop_config.json`）中加入： ```json { "mcpServers": { "yingdao-rpa-mcp": { "command": "python", "args": ["-m", "yingdao_rpa_mcp"] } } } ``` 重启 Claude Desktop，然后对它说："列出我的影刀机器人"。 （完整样例见 [examples/mcp.claude-desktop.json](examples/mcp.claude-desktop.json)） ### 形态三：远程 AI 助手（Tailscale + token，http）——微信操控家里的影刀 AI 助手在云服务器、影刀在你家 PC？两步： 1. **PC 上一键安装**（管理员 PowerShell，在仓库目录）： ```powershell .\scripts\install-windows.ps1 ``` 自动完成：Python 探测 → 虚拟环境 → token 生成 → **防火墙仅放行 Tailscale 网段** → 登录自启 → 401 自检 2. **组网与接线**：按 [examples/tailscale-setup.md](examples/tailscale-setup.md) 走（含一个必踩的 DNS 坑的解法） 之后在微信里说"列出我的影刀机器人"即可。完整配置样例见 [examples/mcp.cow-assistant.json](examples/mcp.cow-assistant.json)。 ## 配置参考 优先级：CLI 参数 > 环境变量（前缀 `YINGDAO_MCP_`）> `config.toml`。 全量带注释样例见 [examples/config.toml](examples/config.toml)，常用项： | 配置 | 默认 | 说明 | |---|---|---| | `mock` | `false` | Mock 演示模式 | | `transport` | `stdio` | `stdio` / `http` | | `host` / `port` | `127.0.0.1` / `8000` | http 监听地址（远程接入建议 `0.0.0.0` + 防火墙限定来源） | | `token` | 无 | http 模式建议必配（静态 Bearer）；stdio 无需 | | `wait_seconds` | 真实 5 / mock 0 | 启动/停止后的验证等待 | | `users_dir` / `log_dir` | 自动探测 | 影刀目录覆盖（多账号/自定义安装位置时使用） | | `output_dir` | 无 | 机器人产出文件的默认目录 | ## 架构 ``` MCP 工具层（FastMCP：协议、参数校验、等待编排、错误语义） │ ▼ ShadowBotGateway ←—— 唯一架构接缝（scan / launch / status / stop / tail_log） │ ├── MockGateway 产品功能（无 Windows 体验）兼全量自动化测试替身 └── WindowsGateway 真实侦察通道（目录扫描 / URL Scheme / 日志三层验证 / keybd_event） ``` 设计细节见 [SPEC.md](SPEC.md)；94 个自动化测试全部基于 Mock，任何 OS 可跑（CI 双矩阵验证）。 ## 踩坑 FAQ（全部来自真实部署） <details> <summary><b>装完 Tailscale 后，服务器/容器解析不了公网域名、AI 助手失联</b></summary> Tailscale Linux 端默认 `accept-dns=true`，会劫持 `/etc/resolv.conf`（指向 100.100.100.100）， 而 MagicDNS 不转发公网域名。解法（我们用裸 IP 连 PC，不需要 MagicDNS）： ```bash tailscale set --accept-dns=false # 用 Docker 跑 AI 助手的话，重启一次容器刷新 resolv.conf ``` </details> <details> <summary><b>机器人明明跑成功了，却返回 launched:false</b></summary> 瞬时任务（几秒内跑完）的日志由影刀<b>异步落盘</b>，可能晚于验证窗口。v0.1.0 起已内置有界重试； 若仍出现，可用 `tail_log` / `get_status` 二次确认——就像下面这个真实案例： > 启动检测窗口没赶上（launched: false），但日志显示 14:24:40 启动、14:24:41 正常退出（exitCode 0）。 </details> <details> <summary><b>AI 侧报 404 Session not found</b></summary> 网关进程在 AI 客户端两次调用之间被重启过（比如 PC 重启后计划任务拉起了新进程）。 当前版本已默认启用 <b>stateless-http</b>（无会话状态，重启透明）；旧版本遇到时重启 AI 客户端即可。 </details> <details> <summary><b>Windows 脚本报一串乱码解析错误</b></summary> Windows PowerShell 5.1 对无 BOM 的 UTF-8 脚本按 GBK 解码。仓库内的脚本已带 BOM； 如果你自己改编过脚本，请确保以"UTF-8 with BOM"保存。 </details> <details> <summary><b>为什么停止机器人必须用 Ctrl+Alt+Q，不能杀进程？</b></summary> 杀进程会让影刀内部状态机走不完，产出和日志烂尾，甚至不可恢复。Ctrl+Alt+Q 是影刀的全局停止快捷键， 必须用 `keybd_event` 发送（影刀靠全局键盘钩子监听，`SendInput` 触发不了）。 ⚠️ 它是<b>全局</b>停止——会停掉所有运行中的机器人，AI 调用前必须征得你确认。 </details> ## 与原仓库的关系 核心机制全部继承自 [yingdao_robot_run_api_manage_and_skill](https://github.com/HnBigVolibear/yingdao_robot_run_api_manage_and_skill)， 本项目是其 **MCP 化继任者**。继承/补齐逐项对照见 [docs/COMPARISON.md](docs/COMPARISON.md)—— 如果你只想要一个带界面的桌面工具 + 局域网 REST，原仓库仍然是不二之选；想让 AI 原生操控影刀，用本项目。 ## 🙏 致谢 本项目的核心机制并非发明，而是**继承**自湖南大白熊的 [yingdao_robot_run_api_manage_and_skill](https://github.com/HnBigVolibear/yingdao_robot_run_api_manage_and_skill)（MIT，含 [skills 技术文档](https://github.com/HnBigVolibear/yingdao_robot_run_api_manage_and_skill/tree/main/skills)）： - **「侦察代替 API」哲学**——不走企业版接口，用民间通道给社区版赋能 - **机器人发现**：`users\<ID>\apps` 目录扫描（4 个候选 package 路径、`_temp` 跳过、mtime 排序） - **启动与传参**：`shadowbot:Run?robot-uuid=…&key=value` URL Scheme（含"仅编码 `& = # %` 空格、中文原样"的实测口径） - **状态验证**：影刀主日志解析（TaskManager / engine running / exited LIFO 配对）+ `GetExitCodeProcess` 存活检测 - **优雅停止**：`keybd_event` 发送 Ctrl+Alt+Q（以及"SendInput 无法触发影刀全局钩子"的实测结论）， 还有"**严禁杀进程**"这条铁律 没有前人踩坑，就没有这个项目。如果你因本项目受益，请也给 [原仓库](https://github.com/HnBigVolibear/yingdao_robot_run_api_manage_and_skill) 一个 Star。 ## ⚠️ 免责声明 - 本项目为个人开源作品，与影刀官方（杭州分叉智能科技有限公司）**无任何关联**； "影刀 / ShadowBot"商标归其权利人所有 - 本项目使用未公开接口（URL Scheme、本地日志、全局快捷键）自动化操作影刀客户端， 这些通道可能随影刀版本更新失效，使用风险自担 - 仅供学习交流使用；`stop_robot` 会全局停止所有运行中的机器人，生产环境请自行评估 - 本项目继承的侦察机制同样继承原仓库的[免责立场](https://github.com/HnBigVolibear/yingdao_robot_run_api_manage_and_skill#%EF%B8%8F-免责声明) ## License [MIT](LICENSE) © 继承自 HnBigVolibear（原仓库）与 Seethelightdie（本项目）的贡献者