iWOD 健身门店数据助手

产品概述

把 Agent 变成你的 iWOD 门店数据助手。不用登录后台、不用导 Excel，说人话就能查数据。

适合谁用：店长、运营、财务、顾问、连锁督导。

能做什么：

首次使用：安装后说 「帮我配置 iWOD」，按提示提供 iWOD 开放 API 凭据即可（向 iWOD 商务申请 app_key、app_secret、studio_id）。凭据只存在本机，不会上传。

支持平台：WorkBuddy、Cursor、OpenClaw 等支持 Skill / MCP 的 Agent。

快速开始

1. 安装：skillhub install iwod-connector（或 WorkBuddy 输入 /install-skill iwod-connector）
2. 配置：对 Agent 说「帮我配置 iWOD」，填入凭据
3. 使用：直接提问，例如「查今日营收」

一次性提供凭据也可以：

帮我配置 iWOD：
app_key 是 xxx
app_secret 是 yyy
studio_id 是 1

常见问法（复制即用）

营收 / 退款

今天营业额多少？
本月营收按支付方式汇总
未来店今天退款多少钱？

签课 / 耗卡

今天未签课有哪些？
本周签课情况汇总
本月各卡种耗卡排名

会员 / 积分 / 会员卡

查手机号 13800138000 的会员和积分
7 天内要到期的会员卡有哪些？
次卡剩余不到 3 次的会员名单

多门店

我有哪些门店？
1 号和 99 店本月营收对比

Agent 技术参考

以下内容供 Agent / 开发者使用，SkillHub 用户可跳过。

触发词

营收 / 营业流水 / 今日营业额、预约 / 签课 / 未签课、耗卡 / 卡耗、查会员 / 查积分 / 会员卡 / 即将过期、iWOD / 思劢、退款、多门店

首次配置（Agent 流程）

1. 调 setup_status 检查是否已配置
2. 未配置则向用户收集 app_key、app_secret、studio_id
3. 调 configure_credentials 保存并测试连接
4. 返回门店列表与今日营收样本

手动安装（可选）

向 iWOD 商务 / 技术支持申请:

• app_key + app_secret (开放 API 凭证)
• studio_id (场馆 ID)

第 2 步: 配置 .env

在用户机器上执行:

mkdir -p ~/.workbuddy/connectors/iwod
cp /scripts/.env.example ~/.workbuddy/connectors/iwod/.env
# 编辑 .env, 填入 IWOD_APP_KEY / IWOD_APP_SECRET / IWOD_STUDIO_ID

第 3 步: 装依赖 (二选一)

方式 A：一键脚本 (推荐) — 自动装 Skill + MCP server + 注册 mcp.json + 装依赖

# 解压 zip
unzip iwod-connector.zip -d iwod-connector
cd iwod-connector
bash install.sh

方式 B：手动安装

pip install -r /scripts/requirements.txt

第 4 步: WorkBuddy 加载 MCP

如果走的是方式 B 手动安装，把 MCP server 注册到 ~/.workbuddy/mcp.json:

{
  "mcpServers": {
    "iwod": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "iwod_mcp"],
      "cwd": "/scripts",
      "env": {
        "IWOD_CONFIG_DIR": "~/.workbuddy/connectors/iwod"
      }
    }
  }
}

如果走的是方式 A 一键脚本，已自动注册，无需手动操作。

第 5 步: 重启 WorkBuddy

重启后右上面板 → MCP 标签页, iwod 状态应变绿。然后直接对 WorkBuddy 说"查今日营收"。

可用 Tools (15 个)

多门店: 先用 list_studios 查看绑定场馆, 其他 tool 传 studio_id 切换门店; 响应会附带 studio.studioName。

关键约束与已知差异

用户必须知道 (来自实测, 文档与实际不符):

安全提示:

• deduct_points / refund_points 是写操作, 调用前 AI 会先向用户确认
• app_secret 不随 Skill 包分发, 必须在用户本机 .env 填入

Token 管理（每日配额保护）

iWOD 对每日 /OAuth/requestToken 调用次数有限制（实测约 200 次/天），所以本 skill 用了三层缓存尽量复用同一个 token：

1. 进程内内存缓存 — 一次 token 取到后, 本 MCP server 进程内所有调用直接复用, 零 IO
2. 跨进程文件缓存 — token_cache.json 写到 ~/.workbuddy/connectors/iwod/, 用 fcntl 文件锁防止多个 WorkBuddy 进程同时去拿 token
3. 每日配额计数器 — 缓存文件里记 daily_count, 跨天自动重置; 接近 200 次上限时打印告警, 超限后强制复用已过期 token（避免被风控进一步锁账号, 此时部分接口可能 401）

token 生命周期:

• 启动时不主动拿 token, 首次调用 tool 时才去请求 /OAuth/requestToken
• iWOD 返回的 token 默认 2 小时有效
• 本地默认在过期前 5 分钟自动续, 一天理论上限 12 次

主动重置缓存: 如果发现 illegal session 类错误, 删掉 token_cache.json 让它重取:

rm ~/.workbuddy/connectors/iwod/token_cache.json

调整每日上限 (环境变量):

• IWOD_TOKEN_DAILY_LIMIT=200 (默认; 设小点更保守, 比如 50)

故障排查

资源结构

iwod-connector/
├── SKILL.md                      # 本文件
├── install.sh                    # 一键安装脚本 (推荐使用)
└── scripts/
    ├── .env.example              # 凭据模板 (key 留空)
    ├── requirements.txt
    └── iwod_mcp/                 # 完整 MCP server 代码
        ├── __init__.py
        ├── server.py             # FastMCP 入口
        ├── client.py             # HTTP 客户端 + token 管理
        ├── enums.py              # 枚举映射
        ├── utils.py              # 时间处理
        └── tools/
            ├── revenue.py
            ├── appointments.py
            ├── consumption.py
            └── members.py

代码位置不动, 用户只需在 mcp.json 里用 cwd 指向 scripts/, 即可让 python -m iwod_mcp 找到包。

分发给同事 / 客户

方式 1：发 zip (最直接)

• 直接把 iwod-connector.zip 发给同事
• 同事解压后 bash install.sh 一键安装
• 包内不含真实 key, 同事需自己去 iWOD 商务申请

方式 2：上传腾讯 SkillHub (skillhub.tencent.com, 国内免翻墙)

• 提交 zip, 腾讯审核通过后所有 WorkBuddy 用户都能搜到
• 适合面向公众发布

方式 3：公司内网文件服务器

• 把 zip 丢内网, 给个下载链接
• 适合公司内部分发, 无需外部审核

无论哪种方式, 流程都一样：

1. 拿到 zip
2. 解压并 bash install.sh
3. 编辑 ~/.workbuddy/connectors/iwod/.env 填入自己的 app_key / app_secret / studio_id
4. 重启 WorkBuddy