pp-tiktok-shop

TikTok Shop - Printing Press Safe v1

前提条件：安装 CLI

此技能由 tiktok-shop-pp-cli 二进制文件驱动。**调用此技能中的任何命令前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

1. 使用 Printing Press 安装程序安装。在 macOS/Linux 上，二进制文件默认安装到 $HOME/.local/bin；在 Windows 上，默认安装到 %LOCALAPPDATA%\Programs\PrintingPress\bin：

   npx -y @mvanhorn/printing-press-library install tiktok-shop --cli-only
   

2. 验证：tiktok-shop-pp-cli --version
3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用直接通过 Go 安装的方式（需要 Go 1.26.6 或更新版本）：

go install github.com/mvanhorn/printing-press-library/library/commerce/tiktok-shop/cmd/tiktok-shop-pp-cli@latest

如果安装后 --version 报告“command not found”，说明运行时无法在 $PATH 中找到二进制文件目录。验证成功前，不要继续执行技能命令。

官方来源范围

有关 API、身份验证、签名、权限范围、端点和速率限制的声明，仅使用 TikTok Shop Partner Center 官方文档：

• Seller API 概览：https://partner.tiktokshop.com/docv2/page/650b1f2ff1fd3102b93c6d3d
• 授权概览：https://partner.tiktokshop.com/docv2/page/678e3a3292b0f40314a92d75
• 授权指南：https://partner.tiktokshop.com/docv2/page/678e3a2dbd083702fd17455c
• 签名算法：https://partner.tiktokshop.com/docv2/page/678e3a3d4ddec3030b238faf
• 获取已授权店铺：https://partner.tiktokshop.com/docv2/page/6507ead7b99d5302be949ba9
• 获取活跃店铺：https://partner.tiktokshop.com/docv2/page/650a69e24a0bb702c067291c
• 获取订单列表：https://partner.tiktokshop.com/docv2/page/650aa8094a0bb702c06df242
• 获取订单详情：https://partner.tiktokshop.com/docv2/page/650aa8ccc16ffe02b8f167a0
• 搜索商品：https://partner.tiktokshop.com/docv2/page/6503081a56e2bb0289dd6d7d
• 获取商品：https://partner.tiktokshop.com/docv2/page/6509d85b4a0bb702c057fdda
• 搜索库存：https://partner.tiktokshop.com/docv2/page/650a9191c16ffe02b8eec161
• 更新库存，暂缓：https://partner.tiktokshop.com/docv2/page/6503068fc20ad60284b38858
• 获取仓库列表：https://partner.tiktokshop.com/docv2/page/650aa418defece02be6e66b6
• 搜索包裹：https://partner.tiktokshop.com/docv2/page/650aa592bace3e02b75db748
• 获取包裹详情：https://partner.tiktokshop.com/docv2/page/650aa39fbace3e02b75d8617

可查阅的官方文档中，速率限制仍不明确，因此不会将其编码为数值声明。

命令参考

已实现：

• tiktok-shop-pp-cli doctor - 检查配置、环境、身份验证就绪状态和官方文档依据，不会发送实时探测请求。
• tiktok-shop-pp-cli auth status - 显示应用凭据、令牌和店铺选择器是否已配置，不会泄露机密信息。
• tiktok-shop-pp-cli auth exchange --auth-code <code> - 将 Partner Center 授权码换成令牌；输出会隐藏令牌。
• tiktok-shop-pp-cli auth refresh - 刷新访问令牌；输出会隐藏令牌。
• tiktok-shop-pp-cli shops info - 列出已授权此应用／令牌的店铺，并获取店铺 cipher。
• tiktok-shop-pp-cli orders list - 搜索订单；响应包含买家／订单 PII。
• tiktok-shop-pp-cli orders get <order-id> - 获取订单详情；响应包含买家／订单 PII。
• tiktok-shop-pp-cli products list - 搜索产品／商品列表。
• tiktok-shop-pp-cli products get <product-id> - 获取产品详情。
• tiktok-shop-pp-cli inventory list --product-id <id> 或 --sku-id <id> - 搜索库存。
• tiktok-shop-pp-cli inventory get <sku-id> - 获取单个 SKU 的库存。
• tiktok-shop-pp-cli fulfillment list - 搜索履约包裹；响应可能包含履约 PII。
• tiktok-shop-pp-cli fulfillment get <package-id> - 获取包裹详情。
• tiktok-shop-pp-cli fulfillment warehouses - 列出卖家仓库。
• tiktok-shop-pp-cli which [query] - 将功能映射到命令。
• tiktok-shop-pp-cli agent-context - 为 Agent 输出 JSON 上下文。

暂缓实现：

• tiktok-shop-pp-cli inventory update - 已确认官方端点，但安全的 v1 版本会暂缓执行，直到设计好幂等性和不重试的变更行为。

身份验证设置

设置通过官方 TikTok Shop Partner Center 流程获取的值。切勿将机密信息硬编码。

export TIKTOK_SHOP_APP_KEY="<from Partner Center>"
export TIKTOK_SHOP_APP_SECRET="<from Partner Center>"
export TIKTOK_SHOP_ACCESS_TOKEN="<from official token exchange>"
export TIKTOK_SHOP_REFRESH_TOKEN="<from official token exchange>"
export TIKTOK_SHOP_SHOP_CIPHER="<from shops info>"

可选覆盖项：

export TIKTOK_SHOP_CONFIG="$HOME/.config/tiktok-shop-pp-cli/config.toml"
export TIKTOK_SHOP_BASE_URL="https://open-api.tiktokglobalshop.com"
export TIKTOK_SHOP_AUTH_BASE_URL="https://auth.tiktok-shops.com"

运行：

tiktok-shop-pp-cli doctor --json

令牌交换／刷新不会打印令牌值。仅当你有意将返回的令牌包以 0600 权限保存到 ~/.config/tiktok-shop-pp-cli/config.toml 时，才添加 --save。

Agent 模式

在任意命令中添加 --agent。它会展开为 --json --compact --no-input --no-color --yes。

适用于 Agent 的示例：

tiktok-shop-pp-cli doctor --agent
tiktok-shop-pp-cli shops info --agent --dry-run
tiktok-shop-pp-cli which --agent
tiktok-shop-pp-cli inventory update --agent

安全规则

• 将订单、履约、退货和买家标识符视为 PII。
• 使用 shops info 获取 shop_cipher；不要编造或解密店铺 cipher。
• 首次进行实时调用前使用 --dry-run，检查签名请求的形式，而不发送请求。
• 不要重试变更操作。安全的 v1 版本仅执行读取命令和身份验证令牌调用。
• 对于缺失的 API 行为，不要使用非官方端点、猜测 SDK、博客文章或复制的 Postman 集合。

退出代码

代码	含义
0	成功，包括有意输出的暂缓实现占位内容
1	未分类错误
2	用法错误
4	缺少身份验证／配置材料
5	上游 API 错误
7	请求频率受限
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、为 help 或 --help 时，显示 tiktok-shop-pp-cli --help。
2. 以 install 开头且以 mcp 结尾时，表示安装 MCP；否则表示安装 CLI。
3. 其他情况均表示使用 --agent 直接使用。

MCP 服务安装

go install github.com/mvanhorn/printing-press-library/library/commerce/tiktok-shop/cmd/tiktok-shop-pp-mcp@latest
claude mcp add tiktok-shop-pp-mcp -- tiktok-shop-pp-mcp

MCP 服务会开放相同的安全 v1 读取功能，并提供 inventory_update_status 说明工具，而不是库存变更工具。