帮助中心 >

Skill

huayoungtk-cli 技能文档

花漾TK 官方 CLI，供 AI Agent 调用花漾TK平台 API。覆盖达人建联、达人CRM、买家管理、索样管理、商品/订单查询等核心功能。

前置条件

huayoungtk-cli auth login --token <api-token>

保存 API Token 后即可使用所有命令。用 auth status 查看状态，auth check 验证有效性。

通用规则

  • 所有输出默认 JSON，可用 -o ndjson 切换，或用 --jq 表达式过滤
  • 分页：--page（页码）、--page-size（每页数量）、--page-token
  • 写入操作支持 --dry-run 预览
  • 确认操作支持 -y 跳过提示

店铺 (shop)

shop list

查询有权限的店铺列表。不加参数返回全部。

huayoungtk-cli shop list
huayoungtk-cli shop list --type Local           # 本土店
huayoungtk-cli shop list -q "关键词"             # 按名称搜索

shop get

通过 ID 或精确名称查询单个店铺。

huayoungtk-cli shop get --shop-id <id>
huayoungtk-cli shop get --shop-name "店铺名"

shop sync

发起异步任务同步店铺信息，返回 jobId。

# 流程：找店铺 → 找在线设备 → 发起同步
huayoungtk-cli shop list
huayoungtk-cli device list --shop-id <shopId> --online
huayoungtk-cli shop sync --shop-id <shopId> --device-id <deviceId>
# 指定同步类型（默认全部）
huayoungtk-cli shop sync --shop-id <shopId> --device-id <deviceId> --sync product,order

同步类型：product(商品)、order(订单)、sample-apply(样品申请)、creator(达人)、target-plan(目标计划)

达人 (creator)

达人是可通过视频、直播推广商品的 TikTok 用户。

合作状态： NotContacted(0) 未接触 | Contacted(1) 已触达 | Collaborating(2) 合作中 | HasOrder(9) 已出单

查找方式（三选一）： --id（数据库ID）、--handle（TikTok handle）、--cid（TikTok Creator ID）

creator list

列出团队达人库。

huayoungtk-cli creator list
huayoungtk-cli creator list --status HasOrder
huayoungtk-cli creator list --region TH --sort totalGmv:desc
huayoungtk-cli creator list --person-in-charge <userId>

排序字段：id, createTime, followerCnt, totalGmv, totalItemsSold, orderCount, roi, cancelRate, rating, level, handle, region, status, liveCount, videoCount

creator get

查看达人详情。

huayoungtk-cli creator get --handle ashfarienaz
huayoungtk-cli creator get --id 363364238753849

creator videos

查看达人的带货视频列表。店铺名称和跟进人自动填充。

huayoungtk-cli creator videos --handle ashfarienaz
huayoungtk-cli creator videos --handle ashfarienaz --from 2026-04-01 --to 2026-04-30
huayoungtk-cli creator videos --handle ashfarienaz --authorization-status authorized
huayoungtk-cli creator videos --handle ashfarienaz --tag "标签名"

creator lives

查看达人的带货直播列表。

huayoungtk-cli creator lives --handle suphap2539
huayoungtk-cli creator lives --handle suphap2539 --last-days 30

creator capability

评估达人公开市场的带货能力（GMV、GPM、预计发文率等）。

huayoungtk-cli creator capability --handle sahabatpadienterprise

creator shops

查看达人合作的店铺及对应合作状态。

huayoungtk-cli creator shops --handle ashfarienaz

creator note

修改达人备注。--remark "" 清除。

huayoungtk-cli creator note --handle ashfarienaz --remark "转化率不错"
huayoungtk-cli creator note --handle ashfarienaz --remark "test" --dry-run

creator status

修改达人与指定店铺的合作状态。--shop-id 必填。

huayoungtk-cli creator status --handle ashfarienaz --shop-id 123456 --status Collaborating
huayoungtk-cli creator status --handle ashfarienaz --shop-id 123456 --status Contacted --dry-run

creator tag

给达人打标签或取消标签。标签不存在会自动创建。

huayoungtk-cli creator tag --handle ashfarienaz --tag vip
huayoungtk-cli creator tag --handle ashfarienaz --tag vip --tag active
huayoungtk-cli creator tag --handle ashfarienaz --tag vip --remove

买家 (buyer)

买家是在 TikTok Shop 下单购买商品的用户。

查找方式（二选一）： --id（数据库ID）、--handle（买家handle）

buyer list

huayoungtk-cli buyer list
huayoungtk-cli buyer list --shop-id <shopId>
huayoungtk-cli buyer list --has-contact           # 有联系方式
huayoungtk-cli buyer list --tag "VIP" --region TH

buyer get

huayoungtk-cli buyer get --id 123456
huayoungtk-cli buyer get --handle some_buyer_handle

buyer note

huayoungtk-cli buyer note --id 123456 --remark "VIP 买家"
huayoungtk-cli buyer note --id 123456 --remark ""  # 清除

buyer tag

huayoungtk-cli buyer tag --id 123456 --tag "VIP"
huayoungtk-cli buyer tag --id 123456 --tag "VIP" --remove

带货视频 (video)

查找方式（二选一）： --id（数据库ID）、--media-id（TikTok mediaId）

video list

huayoungtk-cli video list
huayoungtk-cli video list --tab-type latest3day --page-size 5
huayoungtk-cli video list --authorization-status authorized
huayoungtk-cli video list --tag "标签名"

video get

huayoungtk-cli video get --id 123456
huayoungtk-cli video get --media-id 7493991083946247855

video note

huayoungtk-cli video note --media-id <mediaId> --remark "爆款"
huayoungtk-cli video note --media-id <mediaId> --remark ""  # 清除

video tag

huayoungtk-cli video tag --media-id <mediaId> --tag "爆款视频"
huayoungtk-cli video tag --media-id <mediaId> --tag "爆款视频" --remove

带货直播 (live)

查找方式（二选一）： --id（数据库ID）、--media-id（TikTok mediaId）

live list

huayoungtk-cli live list
huayoungtk-cli live list --last-days 7
huayoungtk-cli live list --shop-id <shopId> --gmv-from 100 --sort gmv:desc

live get

huayoungtk-cli live get --id 123456
huayoungtk-cli live get --media-id 7630462341809998613

live note

huayoungtk-cli live note --id <id> --remark "备注"
huayoungtk-cli live note --media-id <mediaId> --remark ""  # 清除

商品 (product)

商品状态： Live(1) 在售 | Deactivated(2) 下架 | Reviewing(3) 审核中 | Suspended(4) 暂停 | Draft(5) 草稿 | Deleted(6) 删除

product list

--shop-id 必填。

huayoungtk-cli product list --shop-id <shopId>
huayoungtk-cli product list --shop-id <shopId> --status Live
huayoungtk-cli product list --shop-id <shopId> -q "dress"
huayoungtk-cli product list --shop-id <shopId> --sort itemsSold:desc

product get

--shop-id 和 --product-id 必填。

huayoungtk-cli product get --shop-id <shopId> --product-id <productNo>

product note

huayoungtk-cli product note --shop-id <shopId> --product-id <productNo> --remark "备注"

评论 (review)

买家对 TikTok Shop 商品的评价，包含星级、文字、图片、视频、卖家回复等信息。

评论属性说明：

字段 说明
id 评论数据库 ID
rid TikTok 官方评论 ID
productId 商品 ID（productNo）
orderNo 关联订单号
reviewTime 评论提交时间
starLevel 星级 1-5
userName 买家昵称
reviewText 评论文字内容
replyText 卖家回复内容（如有）
replyTime 卖家回复时间
hasFollowReview 是否有追评
hasImg 是否包含图片
hasText 是否包含文字
hasVideo 是否包含视频
incentivized 是否为激励评论
skuSpec 购买商品的 SKU 规格
buyerHandle 买家 TikTok handle
buyerAlias 买家别名（团队内备注）
buyerRegion 买家所在地区
images 图片 URL 列表
videos 视频 URL 列表
lastSyncTime 最后从 TikTok 同步时间

排序字段： reviewTime（评论时间，默认）、starLevel（星级）

review list

查询商品评论列表。--shop-id 不指定时查询所有可访问店铺。

常用筛选：

huayoungtk-cli review list --shop-id <shopId> --star 1 --star 2 --last-hours 24  # 最近24小时差评巡检
huayoungtk-cli review list --shop-id <shopId> --product-id <productNo>           # 按商品查评论
huayoungtk-cli review list --shop-id <shopId> --has-img --last-hours 168         # 最近7天带图评论
huayoungtk-cli review list --shop-id <shopId> --order-no <orderNo>               # 按订单查评论
huayoungtk-cli review list --shop-id <shopId> -q "关键词"                         # 模糊搜索（商品ID或订单号）
huayoungtk-cli review list --shop-id <shopId> --sort starLevel:asc               # 按星级从低到高排序

布尔筛选标志（默认不启用，显式传入才生效）：

  • --has-img — 只看有图片的评论
  • --has-video — 只看有视频的评论
  • --has-text — 只看有文字的评论
  • --has-follow-review — 只看有追评的评论
  • --incentivized — 只看激励评论

review stat

统计时间范围内评论按星级的分布总数。

huayoungtk-cli review stat --shop-id <shopId> --last-days 7
huayoungtk-cli review stat --shop-id <shopId> --from 2026-05-01 --to 2026-05-18
huayoungtk-cli review stat --shop-id <shopId> --product-id <productNo> --last-days 30

输出字段： totalCount、oneStarCount、twoStarCount、threeStarCount、fourStarCount、fiveStarCount

review daily-stat

按天统计评论趋势，返回每天各星级的分布。

huayoungtk-cli review daily-stat --shop-id <shopId> --last-days 30
huayoungtk-cli review daily-stat --shop-id <shopId> --from 2026-05-01 --to 2026-05-18

输出： 数组，每项包含 day 和按星级分布的计数

订单 (order)

订单状态： to_ship 待发货 | shipped 已发货 | pending 待处理 | completed 已完成 | cancellation 已取消 | fail_delivery 发货失败

order list

huayoungtk-cli order list --shop-id <shopId>
huayoungtk-cli order list --shop-id <shopId> --status to_ship
huayoungtk-cli order list --last-days 7 --sort amount:desc
huayoungtk-cli order list --shop-id <shopId> --creator "handle"
huayoungtk-cli order list --shop-id <shopId> --promotion-type Video

推广类型：Showcase(1) 橱窗 | Video(2) 视频 | Livestream(3) 直播 | AffiliateProductPage(5) 联盟商品页 | ExternalTrafficProgram(6) 外部流量

order get

huayoungtk-cli order get --order-no <orderNo>

索样 (sample-request)

达人在 TikTok Shop 向商家申请免费样品。

索样状态： ToReview 待审核 | ReadyToShip 已批准待发货 | Shipped 已发货 | InProgress 已收货待产出 | Completed 已完成 | Cancelled 已取消 | Reject 已拒绝 | Expired 已过期 | Overdue 已逾期

预定义视图（--table-type）： ReadyToShip 待发货 | Shipped 已发货未签收 | NeedOutput 待产出 | Completed 已产出 | OutputLessThanN 产出不足 | Unfulfilled 未履约 | Cancelled 已取消/拒绝/过期 | All 全部（排除待审核）

查找方式（二选一）： --id（数据库ID）、--request-id（TikTok 官方申请ID）

sample-request list

huayoungtk-cli sample-request list --shop-id <shopId>
huayoungtk-cli sample-request list --shop-id <shopId> --status ToReview
huayoungtk-cli sample-request list --shop-id <shopId> --table-type NeedOutput
huayoungtk-cli sample-request list --last-days 7 --sort gmv:desc
huayoungtk-cli sample-request list --shop-id <shopId> --person-in-charge <userId>
huayoungtk-cli sample-request list --shop-id <shopId> --shelved   # 只看已搁置

列表输出字段包含 shelved（是否搁置）和 personInCharge（跟进人昵称）。

sample-request get

获取索样详情（含关联视频和直播）。

huayoungtk-cli sample-request get --id <id>
huayoungtk-cli sample-request get --request-id "xxx-xxx-xxx"

sample-request videos / lives

获取索样关联的视频或直播。

huayoungtk-cli sample-request videos --id <id>
huayoungtk-cli sample-request lives --request-id "xxx-xxx-xxx"

sample-request shelve

搁置或取消搁置索样。仅对 ToReview（待审核）状态生效。

huayoungtk-cli sample-request shelve --id <id>                  # 搁置
huayoungtk-cli sample-request shelve --id <id> --unshelve       # 取消搁置
huayoungtk-cli sample-request shelve --id <id> --dry-run        # 预览

输出：{"action":"搁置/取消搁置","id":...,"shelved":true/false,"success":true}

sample-request approve

同意索样，触发 RPA 自动化。不可撤销，务必先 --dry-run。

huayoungtk-cli sample-request approve --id <id> --device-id <deviceId> --dry-run
huayoungtk-cli sample-request approve --request-id "xxx" --device-id <deviceId>

sample-request reject

拒绝索样，触发 RPA 自动化。不可撤销，务必先 --dry-run。

huayoungtk-cli sample-request reject --id <id> --device-id <deviceId> --dry-run
huayoungtk-cli sample-request reject --request-id "xxx" --device-id <deviceId>

设备 (device)

用于执行 RPA 任务的设备。

设备类型： App（花漾客户端）| TeamRpaExecutor（团队RPA执行器）| Extension（浏览器插件分身）

device list

huayoungtk-cli device list
huayoungtk-cli device list --shop-id <shopId> --online   # 指定店铺的在线设备

任务 (job)

RPA 自动化任务。

任务状态： Pending(0) 等待调度 | Scheduled(1) 已分配设备 | Running(2) 执行中 | Succeed(8) 成功 | Failed(9) 失败 | Cancelled(10) 已取消

job get

huayoungtk-cli job get --job-id <id>
huayoungtk-cli job get --job-id <id> --alive=false   # 查历史任务

job cancel

huayoungtk-cli job cancel --job-id <id>
huayoungtk-cli job cancel --job-id <id> --dry-run

团队 (team)

team info

查看团队信息、套餐版本和配额。

huayoungtk-cli team info

常见工作流

达人索样审核流程

# 1. 查看待审核索样
huayoungtk-cli sample-request list --shop-id <shopId> --status ToReview

# 2. 查看索样详情和达人的带货能力
huayoungtk-cli sample-request get --id <srId>
huayoungtk-cli creator capability --handle <handle>

# 3. 搁置不需要的
huayoungtk-cli sample-request shelve --id <srId>

# 4. 同意/拒绝（先 dry-run）
huayoungtk-cli device list --online
huayoungtk-cli sample-request approve --id <srId> --device-id <deviceId> --dry-run
huayoungtk-cli sample-request approve --id <srId> --device-id <deviceId>

达人分析流程

# 1. 查找达人
huayoungtk-cli creator list --region TH --sort totalGmv:desc --page-size 10

# 2. 查看详情和带货能力
huayoungtk-cli creator get --handle <handle>
huayoungtk-cli creator capability --handle <handle>

# 3. 查看带货视频/直播
huayoungtk-cli creator videos --handle <handle> --sort gmv:desc
huayoungtk-cli creator lives --handle <handle> --last-days 30

# 4. 更新合作状态
huayoungtk-cli creator status --handle <handle> --shop-id <shopId> --status Collaborating
最后更新于 2026-05-23 14:56
回到顶部