- name
- toupiaoya-creator
- description
- |
- summary
- 投票鸭技能，支持检索投票模板、创建投票活动（文字/图片/视频投票）、COS 素材上传与素材列表。
- read_when
投票鸭技能说明
前置条件
- 模板查询与 COS token 依赖
requests；upload子命令另需cos-python-sdk-v5。 - 获取
X-Openclaw-Token地址：https://www.toupiaoya.com/skillAccess/token - 建议先完成 token 登录：
X-Openclaw-Token存在~/.toupiaoya/config.json，后续命令自动复用。 - 创建接口需准备
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 调用：
- 返回
{"success": true, "code": 200, ...}表示 token 有效 - 返回
{"success": false, "code": 1002, "msg":"认证失败", ...}表示 token 无效
查询投票类模板
命令示例
python scripts/toupiaoya_cli.py search \
--keywords "摄影大赛" \
--pageNo 1 \
--pageSize 10 \
--sortBy "common_total|desc" \
--color "紫色"参数说明（对应 toupiaoya_cli.py）
--keywords：关键词（可选）--pageNo：页码，默认1--pageSize：每页条数，默认10--sortBy：排序，默认common_total|desc--color：颜色筛选（可选，例：紫色/蓝色/粉色）
输出示例（stdout JSON）
{
"total": 123,
"end": false,
"results": [
{
"templateId": 1234,
"title": "模板标题",
"link": "https://www.toupiaoya.com/mall/detail-h5e/<templateId>",
"description": "模板描述",
"pv": 9999
}
]
}若 total == 0，脚本返回 {}。对话输出时建议展示前 3-5 个模板的标题、链接、描述和热度。
创建投票作品
使用 scripts/toupiaoya_cli.py project create（作品以 project 子命令组织）。
请求体
必填：
briefTitle：封面标题briefDesc：封面简介
可选：
sponsor: 投票主办方detailTitle: 详细的标题，不超过20字detailDesc: 详细的描述，例如规则，投票时间等介绍voteType：imageVote|textVote(默认) |videoVotetimeStart、timeEnd：格式yyyy-MM-dd HH:mmgroupListtemplateId（默认19980321代表空白模版），可以使用搜索出的templateId- 单双选控制：默认单选；传
--multi表示多选。 --access-token：可显式传 token；不传则默认读取~/.toupiaoya/config.json。
说明：不传 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常用参数：
--id：作品 id（必填）--startTime：开始时间（可选，默认空字符串，格式：yyyy-MM-dd）--endTime：结束时间（可选，默认空字符串，格式：yyyy-MM-dd）--pageNo：页码（默认1）--pageSize：每页条数（默认10）--showTrash：是否展示回收站数据（默认1）
返回结构说明：
obj：表头字段数组map：分页统计（total/pageNo/pageSize/end/todayCount等）list：二维数据行（首行为表头，后续为每条投票记录）
作品访问趋势（project view-data）
python scripts/toupiaoya_cli.py project view-data --id 20613397 --startDay 2026-04-08 --endDay 2026-04-22常用参数：
--id：作品 id（必填）--startDay：统计开始日期（可选，格式yyyy-MM-dd）--endDay：统计结束日期（可选，格式yyyy-MM-dd）
日期默认策略：
- 不传
--endDay时，默认今天 - 不传
--startDay时，默认endDay-14天（即最近 15 天窗口）
返回字段（obj）说明：
time：日期序列（与各指标一一对应）uv：新增访客数pv：新增浏览量spv：新增转发数fpv：新增表单数
上传素材
依赖：本仓库根目录 requirements.txt 中的 cos-python-sdk-v5（与 requests）；单独使用技能目录时可 pip install cos-python-sdk-v5 requests。
- 使用
X-Openclaw-Token请求 - 使用返回的
tmpSecretId/tmpSecretKey/sessionToken/region初始化 COS SDK，对本地文件执行PutObject。 - 将
path/tmbPath（默认与 COSkey相同）、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": ... }成功常见：
- 含
id
- editUrl: https://www.toupiaoya.com/fe/<id>,代表编辑链接 - previewUrl: https://forms.ebdan.net/ls/<code>, 代表手机预览链接
id == 0分支
- 仅返回工具层 data（无 id） - 预览链接可拼：https://forms.ebdan.net/ls/ + data.code
失败常见：
- 404（业务异常）
- 400 (参数缺失)
选项管理（Python 调用方式）
获取作品全部选项（get_choices）
- 语义：按作品
id读取当前投票组件中的所有选项，不再是“根据 groupList 生成选项”。 - CLI 命令：
python scripts/toupiaoya_cli.py project choice get --id <project_id> [--access-token <token>]- 成功返回的
data：
- choices：当前全部选项（来自 voteSettings.list） - groupList：分组信息（来自 voteSettings.groupsList） - seq：选项数量
示例：
{
"success": true,
"code": 200,
"msg": "ok",
"data": {
"choices": [{ "id": 1, "content": "选项A", "groupId": 1 }],
"groupList": [{ "id": 1, "name": "默认分组" }],
"seq": 1
}
}更新单个选项（update_choices）
- 语义：更新某个指定选项（按
choiceId定位），不是整包覆盖所有选项。 - CLI 命令：
python scripts/toupiaoya_cli.py project choice update \
--id <project_id> \
--choiceId <choice_id> \
[--groupId <target_group_id>] \
--choice '{"content":"新的选项名","cover":"material/xxx.png"}' \
[--access-token <token>]--choice 的 JSON 对象等价于请求体中的 choice 字段。对应结构示例：
{
"id": 123,
"choiceId": 2,
"choice": {
"content": "新的选项名",
"cover": "material/xxx.png"
}
}也可直接使用可选 groupId 把该选项移动到目标分组（无需在 --choice 里写 groupId）：
python scripts/toupiaoya_cli.py project choice update \
--id 123 \
--choiceId 2 \
--groupId 3 \
--choice '{"content":"新的选项名"}'- 说明：
- id：作品 id（必填） - choiceId：待更新选项 id（必填） - groupId：可选，目标分组 id；传入后会把该 choice 移到对应分组 - choice：更新字段对象（至少一个字段），当前支持：content、cover、desc、groupId、rank、num
新增选项（add_choices）
- 语义：在指定分组下新增一个选项，
choice.id由服务端自动递增分配（当前最大id + 1）。 - CLI 命令：
python scripts/toupiaoya_cli.py project choice add \
--id <project_id> \
--groupId <target_group_id> \
--choice '{"content":"新增选项","cover":"material/xxx.png"}' \
[--access-token <token>]- 说明：
- id：作品 id（必填） - groupId：目标分组 id（必填） - choice：新增字段对象（必填），至少应包含 content；可选 cover、desc、rank、num
分组管理
优先使用 CLI：
获取分组（get_groups）
python scripts/toupiaoya_cli.py project group get --id <project_id> [--access-token <token>]- 返回：当前作品的
groupsList数组（每项含id、name）
新增分组（add_group）
python scripts/toupiaoya_cli.py project group add \
--id <project_id> \
--groupName "新分组" \
[--access-token <token>]- 必填参数：
- id：作品 id - groupName：分组名称
- 行为：自动分配递增
groupId（max(id)+1）
修改分组名（update_group）
python scripts/toupiaoya_cli.py project group update \
--id <project_id> \
--groupId <group_id> \
--groupName "新分组名" \
[--access-token <token>]- 必填参数：
- id：作品 id - groupId：分组 id - groupName：新分组名