MathDoIt Client Skill v2.0

通过 MathDoIt 公网服务 (https://www.mathdoit.cn) 生成数学视频和 3D 场景。

⚠️ 重要注意事项

1. 所有 HTTP 请求必须包含 User-Agent 请求头，否则会被 Cloudflare 拦截返回 HTTP 403。
   • CLI 脚本和 MCP 服务器已内置处理（v2.0+），无需手动添加。
2. 账号额度：非订阅用户有免费生成次数限制，用完需订阅。登录时会返回额度信息。
3. 轮询间隔：建议 3 秒，避免频繁请求。
4. 视频处理时间：通常 2-5 分钟，最长 10 分钟。

安装指南

前置需求

• Python 3.8+（CLI 和 MCP 服务器需要）
• 依赖安装：

  pip install requests        # CLI 工具需要（可选，v2.0 使用标准库 urllib）
  pip install "mcp[cli]"      # MCP 服务器需要（可选，不装则自动用纯 stdio 模式）
  

• MathDoIt 账号：在 www.mathdoit.cn 注册（需要邀请码）

文件位置

本技能包位于 ~/.qclaw/skills/mathdoit-client/ 目录下。配置 MCP 时需要填写脚本的绝对路径，例如：

# Windows
C:Users你的用户名.qclawskillsmathdoit-clientscriptsmathdoit_mcp_server.py

# macOS / Linux
/home/你的用户名/.qclaw/skills/mathdoit-client/scripts/mathdoit_mcp_server.py

QClaw 配置步骤

1. 打开 QClaw 电脑客户端 → 设置 → MCP 服务器
2. 点击 添加服务器
3. 填写：
   • 服务器名称：mathdoit
   • 命令：python
   • 参数：["你的绝对路径/mathdoit_mcp_server.py"]
   • 环境变量：

     MATHDOIT_SERVER=https://www.mathdoit.cn
     MATHDOIT_USERNAME=你的邮箱或用户名
     MATHDOIT_PASSWORD=你的密码
     

4. 点击 测试连接，成功后保存

WorkBuddy 配置步骤

1. 打开 WorkBuddy → 侧边栏 插件 → 点击右上角 MCP 服务器
2. 在配置编辑器中粘贴以下内容（替换路径和账号信息）：

   {
     "mcpServers": {
       "mathdoit": {
         "command": "python",
         "args": ["你的绝对路径/mathdoit_mcp_server.py"],
         "env": {
           "MATHDOIT_SERVER": "https://www.mathdoit.cn",
           "MATHDOIT_USERNAME": "你的邮箱或用户名",
           "MATHDOIT_PASSWORD": "你的密码"
         }
       }
     }
   }
   

3. 保存后查看状态是否为 🟢 绿色
4. 在对话中直接说："帮我生成一个勾股定理的数学视频"

用户级配置（所有项目复用）：~/.workbuddy/mcp.json 项目级配置（仅当前项目）：<项目目录>/.workbuddy/mcp.json

Trae 配置步骤

1. 在项目根目录创建或编辑 .trae/mcp.json
2. 粘贴上述 JSON 配置
3. 重启 Trae，MCP 工具自动加载

Cursor 配置步骤

1. 编辑 .cursor/mcp.json（项目根目录）或全局配置
2. 粘贴上述 JSON 配置
3. 重启 Cursor，MCP 工具自动加载

Claude Desktop 配置步骤

1. 编辑 claude_desktop_config.json：
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json
2. 在 mcpServers 中添加 mathdoit 配置
3. 重启 Claude Desktop

验证 MCP 连接

配置完成后，在对应的 AI Agent 中发送以下消息验证：

"列出你当前可用的 MCP 工具"

如果配置成功，应该能看到 generate_math_video 和 check_video_status 两个工具。

直接使用 CLI 验证（无需 MCP 配置）

如果只需要用命令行测试，可以跳过 MCP 配置：

python ~/.qclaw/skills/mathdoit-client/scripts/mathdoit_client.py generate 
  --username your@email.com 
  --password your-password 
  --problem "勾股定理证明" 
  --type 2d

视频会自动下载到桌面。

使用流程

方法一：使用 CLI 脚本（推荐 QClaw Agent 使用）

Agent 直接调用 CLI 脚本执行完整流程（登录 → 提交 → 轮询 → 下载）：

python ~/.qclaw/skills/mathdoit-client/scripts/mathdoit_client.py generate 
  --username user@example.com 
  --password 123456 
  --problem "勾股定理的证明" 
  --type 2d

环境变量方式（避免在命令行暴露密码）：

export MATHDOIT_USERNAME=user@example.com
export MATHDOIT_PASSWORD=123456
python ~/.qclaw/skills/mathdoit-client/scripts/mathdoit_client.py generate 
  --problem "三角函数" --type 3d

上传手写题目图片：

python ~/.qclaw/skills/mathdoit-client/scripts/mathdoit_client.py generate 
  --username user@example.com --password 123456 
  --problem "解这道题" --image photo.jpg --type 2d

分步操作：

# 1. 登录获取 token
python mathdoit_client.py login --username user@example.com --password 123456

# 2. 提交任务（使用返回的 token）
python mathdoit_client.py submit --token  --problem "勾股定理" --type 2d

# 3. 查询状态
python mathdoit_client.py status --task-id 

# 4. 获取结果
python mathdoit_client.py results --task-id 

# 5. 下载文件
python mathdoit_client.py download --task-id 

方法二：使用 MCP 服务器（推荐外部 AI Agent 使用）

MCP 服务器通过标准协议暴露工具，WorkBuddy、QClaw、Trae、Cursor、Claude Desktop 等支持 MCP 的 AI Agent 均可使用。

配置方式（各 Agent 通用）：

{
  "mcpServers": {
    "mathdoit": {
      "command": "python",
      "args": ["path/to/mathdoit_mcp_server.py"],
      "env": {
        "MATHDOIT_SERVER": "https://www.mathdoit.cn",
        "MATHDOIT_USERNAME": "用户邮箱或用户名",
        "MATHDOIT_PASSWORD": "用户密码"
      }
    }
  }
}

暴露的工具：

工作流（Agent 执行指南）

当用户要求生成数学视频时，按以下步骤执行：

1. 收集需求：

   • 数学问题是什么？（如"勾股定理"、"函数图像"、"微积分"）
   • 想要 2D 动画视频还是 3D 交互场景？（默认 2D）
   • 有无手写题目图片要上传？（可选）
   • 提供 MathDoIt 账号的用户名/密码（或通过环境变量配置）

2. 执行生成：调用 CLI 脚本或 MCP 工具执行

3. 告知结果：告诉用户视频已下载到桌面，文件路径和答案

Agent 直接调用 CLI 的注意事项

当 Agent（如 QClaw）直接通过 exec 调用 CLI 脚本时：

1. Python 输出缓冲：CLI 脚本中所有 print 语句已添加 flush=True，确保实时输出
2. 超时设置：建议设置 600 秒超时（视频生成通常需要 2-5 分钟）
3. 后台运行：使用 yieldMs=30000 让命令后台运行，然后通过 process 工具轮询进度
4. 输出无内容时：如果 exec 返回 (no output)，可能是 Python 缓冲问题，写独立 .py 文件执行

环境变量

API 参考文档

详见 references/api.md。

版本历史