投票鸭助手

触发词：易企秀、制作投票、创建投票、发起投票、在线投票、投票模板、评选投票、微信投票、 活动投票、投票系统、投票链接、二维码投票、投票活动怎么弄、怎么发起投票、 投票工具、投票网站、免费投票、作品评选、摄影投票、美食投票、萌娃投票

summary: 投票鸭技能，支持检索投票模板、创建投票活动（文字/图片/视频投票）、COS 素材上传与素材列表。 检索 search、创建 project create、作品列表 project list、投票数据 project vote-data、访问趋势 project view-data、上传 upload、素材列表 material list、选项读取/更新/新增（get_choices/update_choices/add_choices）、分组读取/新增/改名（get_groups/add_group/update_group）；实现位于 scripts/toupiaoya/ 包内，toupiaoya_cli.py 仅为入口。

read_when: - 用户提到投票、评选、投票活动、投票模板 - 用户想要创建投票链接/二维码投票/投票小程序 - 用户想找一个免费投票工具/网站/小程序 - 用户描述"我想做个投票让大家选…"

投票鸭技能说明

前置条件

1. 模板查询与 COS token 依赖 requests；upload 子命令另需 cos-python-sdk-v5。 2. 获取X-Openclaw-Token地址：https://www.toupiaoya.com/skillAccess/token 3. 建议先完成 token 登录：X-Openclaw-Token 存在 ~/.toupiaoya/config.json，后续命令自动复用。 4. 创建接口需准备 briefTitle 与 briefDesc。

认证与登录（推荐）

验证登录状态
python scripts/toupiaoya_cli.py auth status
交互式保存 token 到 ~/.toupiaoya/config.json，如果存在token，验证token有效性即可
python scripts/toupiaoya_cli.py login

auth status 会在请求头携带 X-Openclaw-Token 调用：

查询投票类模板

命令示例

python scripts/toupiaoya_cli.py search \
  --keywords "摄影大赛" \
  --pageNo 1 \
  --pageSize 10 \
  --sortBy "common_total|desc" \
  --color "紫色"

参数说明（对应 toupiaoya_cli.py）

输出示例（stdout JSON）

{
  "total": 123,
  "end": false,
  "results": [
    {
      "templateId": 1234,
      "title": "模板标题",
      "link": "https://www.toupiaoya.com/mall/detail-h5e/",
      "description": "模板描述",
      "pv": 9999
    }
  ]
}

若 total == 0，脚本返回 {}。对话输出时建议展示前 3-5 个模板的标题、链接、描述和热度。

创建投票作品

使用 scripts/toupiaoya_cli.py project create（作品以 project 子命令组织）。

请求体

必填：

可选：

说明：不传 timeStart/timeEnd 时，服务内部按“开始=当前，结束=当前+10天”处理。

命令示例

python scripts/toupiaoya_cli.py project create \
  --sponsor "投票主办方A" \
  --briefTitle "年度最佳作品投票" \
  --briefDesc "封面简介：本次活动由某某主办。" \
  --detailTitle "年度最佳作品投票" \
  --detailDesc "投票规则：每人每天可投一次。" \
  --voteType "textVote" \
  --templateId 19980321 \
  --multi \
  --groupList '[{"groupName":"默认组","choices":[{"name":"作品1"},{"name":"作品2"}]}]'

图片投票：

python scripts/toupiaoya_cli.py project create \
  --briefTitle "年度最佳作品投票" \
  --briefDesc "封面简介：本次活动由某某主办。" \
  --detailTitle "年度最佳作品投票" \
  --detailDesc "投票规则：每人每天可投一次。" \
  --voteType "imageVote" \
  --templateId 19980321 \
  --groupList '[{"groupName":"主推","choices":[{"name":"作品1","cover":"https://example.com/p1.png"},{"name":"作品2","cover":"https://example.com/p2.png"}]}]'

说明：project create 会自动在请求头中带 X-Openclaw-Token（来源：--access-token 或本地配置）。

作品列表（project list）

python scripts/toupiaoya_cli.py project list --pageNum 1 --pageSize 27

成功时 stdout 为接口完整 JSON（含 list、map、obj 等）。

作品投票数据

python scripts/toupiaoya_cli.py project vote-data --id 20613397 --pageNo 1 --pageSize 10 --showTrash 1

常用参数：

返回结构说明：

作品访问趋势（project view-data）

python scripts/toupiaoya_cli.py project view-data --id 20613397 --startDay 2026-04-08 --endDay 2026-04-22

常用参数：

日期默认策略：

返回字段（obj）说明：

上传素材

依赖：本仓库根目录 requirements.txt 中的 cos-python-sdk-v5（与 requests）；单独使用技能目录时可 pip install cos-python-sdk-v5 requests。

1. 使用 X-Openclaw-Token 请求 2. 使用返回的 tmpSecretId / tmpSecretKey / sessionToken / region 初始化 COS SDK，对本地文件执行 PutObject。 3. 将 path / tmbPath（默认与 COS key 相同）、name（本地文件名）、size、extName 等写入素材库；source 默认 P010238，可用 --source 覆盖。

python scripts/toupiaoya_cli.py upload --file ./photo.png --prefix "/material/"

常用参数：--bucket（默认 eqxiu）、--prefix（默认 '/material/'）、--name（COS 对象名，默认本地 basename）、--source（saveFile）、--tag-id、--file-type、--tmb-path（与 path 不一致时）。成功时 stdout 为 JSON，顶层含 cos（key、etag、assetUrl 等）与 material（接口 obj，如素材 id、path）。若 COS 已成功但 saveFile 失败，错误 JSON 内会附带 cos 字段便于排查。

素材列表（用户上传图片）

固定 fileType=1（图片），pageNo / pageSize / tagId 可调（默认 tagId=-1）

python scripts/toupiaoya_cli.py material list --pageNo 1 --pageSize 30 --tagId -1

成功时 stdout 为接口完整 JSON（含 list、map 分页信息等）。

返回值解析

统一形态：

{ "success": true|false, "code": 200|..., "msg": "...", "data": ... }

成功常见：

1. 含 id - editUrl: https://www.toupiaoya.com/fe/,代表编辑链接 - previewUrl: https://forms.ebdan.net/ls/, 代表手机预览链接 2. id == 0 分支 - 仅返回工具层 data（无 id） - 预览链接可拼：https://forms.ebdan.net/ls/ + data.code

失败常见：

python scripts/toupiaoya_cli.py project choice get --id  [--access-token ]

{
  "success": true,
  "code": 200,
  "msg": "ok",
  "data": {
    "choices": [{ "id": 1, "content": "选项A", "groupId": 1 }],
    "groupList": [{ "id": 1, "name": "默认分组" }],
    "seq": 1
  }
}

python scripts/toupiaoya_cli.py project choice update \
  --id  \
  --choiceId  \
  [--groupId ] \
  --choice '{"content":"新的选项名","cover":"material/xxx.png"}' \
  [--access-token ]

{
  "id": 123,
  "choiceId": 2,
  "choice": {
    "content": "新的选项名",
    "cover": "material/xxx.png"
  }
}

python scripts/toupiaoya_cli.py project choice update \
  --id 123 \
  --choiceId 2 \
  --groupId 3 \
  --choice '{"content":"新的选项名"}'

python scripts/toupiaoya_cli.py project choice add \
  --id  \
  --groupId  \
  --choice '{"content":"新增选项","cover":"material/xxx.png"}' \
  [--access-token ]

python scripts/toupiaoya_cli.py project group get --id  [--access-token ]

python scripts/toupiaoya_cli.py project group add \
  --id  \
  --groupName "新分组" \
  [--access-token ]

python scripts/toupiaoya_cli.py project group update \
  --id  \
  --groupId  \
  --groupName "新分组名" \
  [--access-token ]