Communitygithub.com

ericrisco/rsc-harness

用于将真实的 TikTok 账号与代码连接,通过内容发布、展示和商业账号 API 实现 OAuth 认证、分块视频发布及状态轮询,并获取观看量、观看时长和展示来源数据,最终将性能数据记录到 wiki 中作为带日期的反馈记录。涵盖短命 token 导致定时任务失效、未经验证的 URL 拉取所有权以及速率限制等问题。不涉及发布内容和包装方式(由 `shortform-strategy` 和 `shortform-packaging` 处理)。

rsc-harness 是什么?

该技能用于将 TikTok 的 Content Posting API、Display API 和 Business Account API 集成到工作流中,实现从视频发布到性能数据获取的全链路自动化。它支持 OAuth v2 用户认证,处理短命访问令牌(24小时)的自动刷新,以及分块上传视频文件(5-64 MB 每块)并轮询异步发布状态。同时,它还能从 Display API 获取基本计数(观看、点赞、评论、分享),并通过 Business Account API 获取更深入的参与度指标(观看时长、完成率、展示来源)。最后,所有数据会结构化为带日期的 wiki 记录,方便策略和包装模块后续分析。技能明确区分了职责:仅负责数据传输和日志记录,不涉及内容策略、创意或发布排期。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ericrisco/rsc-harness/tree/HEAD/skills/tiktok-api

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

TikTok API — 传输与数据接入(真实账号)

你掌控连接:认证 TikTok 账号、发布视频、拉取数据并将数据写入 wiki 形成持久的反馈日志。你不决定制作什么、何时发布或如何编写标题——这些由短视频策略/包装家族负责。提供干净的传输和可查询的日志;让其他模块去解读。

TikTok 分为 三个 独立的 API,一个真实账号会涉及全部三个:

  • 内容发布 API — https://open.tiktokapis.com/v2/post/publish/... — 写入端:初始化发布、传输文件、轮询状态。需要审核。
  • 展示 API — https://open.tiktokapis.com/v2/video/... — 廉价读取端:你自己的资料和基本的单视频计数器(view_count, like_count, comment_count, share_count)。
  • TikTok Business API — 丰富读取端:观看时长、完成度、展示来源。需通过 独立的商业门户 启用,而非标准开发者应用。

认证是 通过 Login Kit 的用户 OAuth v2,永远不要使用服务令牌。人类拥有账号;你代表他们使用刷新令牌进行操作。没有官方的 TikTok SDK —— 你直接使用任何 HTTP 客户端调用 REST 端点。将访问令牌视为一个短命的、可刷新的凭据对象,永远不要硬编码。

何时使用 / 何时不使用

使用时机:

  • 将脚本或代理连接到账号进行发布:通过 /v2/post/publish/video/init/(或草稿使用 /inbox/)进行直接发布或上传到草稿,然后进行 FILE_UPLOAD 分块 PUT 或 PULL_FROM_URL,最后轮询 /v2/post/publish/status/fetch/。
  • 拉取账号自身的视频统计:通过 Display API POST /v2/video/query/(或 /v2/video/list/)获取计数器;通过 Business Account API 获取观看时长/完成度/展示来源。
  • 构建循环的“获取性能 → 写入 02-DOCS/wiki/shortform/”,将 API 响应转换为其他模块可读取的账号反馈日志。
  • 调试 TikTok 特定错误:scope_not_authorized、url_ownership_unverified、rate_limit_exceeded(每分钟6次请求)、24小时访问令牌过期、审核/video.publish 未批准、未审核应用的仅私人发布。

以下情况不要使用(交给负责的模块):

实际需求请使用
发布内容、节奏、细分领域、钩子策略shortform-strategy (catalog id)
视频创意、钩子、主题待办事项shortform-ideation (catalog id)
标题/封面/标题包装、A/B 文案shortform-packaging (catalog id)
剪辑/字幕/渲染实际视频文件shortform-editing (catalog id)
程序化渲染视频文件../remotion-video/SKILL.md
同时发布一个资源到 TikTok + IG + YouTube../social-publisher/SKILL.md
Instagram 的 Graph / Content Publishing API../instagram-api/SKILL.md
YouTube 的两个 API(同系列,不同平台)../youtube-api/SKILL.md
封装任意 REST 提供者,支持 OAuth + 重试api-connector-builder (catalog id)
跨工具链发布 → Notion 行 → Slackautomation-flows (catalog id)

一句话总结:该技能认证、调用并将 TikTok 的内容发布 + 展示 + 商业 API 数据摄取到 wiki 中。发布内容和包装方式属于 shortform-strategy / shortform-ideation / shortform-packaging 模块;多网络发布属于 social-publisher。

1. 一次性设置(在任何代码之前执行)

检查清单,因为遗漏每个步骤都会在后面产生不同且令人困惑的错误:

  1. 在开发者门户注册一个 TikTok 开发者应用。
  2. 添加你需要的产品:Login Kit(OAuth)、Content Posting API(发布)、Display API(读取计数)。洞察数据在 独立的 TikTok for Business 门户 中——如果你需要观看时长/完成度,也要启用该账号访问权限。
  3. 为 OAuth 流程设置一个准确的 重定向 URI。
  4. 在发布公共内容之前,提交应用进行审核。未审核的应用只能 私下 发布(SELF_ONLY)且仅限有限的测试用户。这是最常见的“在我机器上能用,生产环境就挂”的意外——参见下面的规则。
  5. 如果你通过 URL 发布(PULL_FROM_URL),在门户中验证域/URL 前缀(DNS TXT 或 URL 前缀),否则每次初始化都会返回 url_ownership_unverified。

三个关卡是独立的。不要认为一个批准覆盖一切:

错误:"我的应用已批准,所以发布和洞察都能用。"
正确:内容发布 *审核* 决定公共发布;
      展示 *scope*(video.list)决定自身视频计数;
      商业 *门户* 访问决定观看时长/完成度/展示来源。
      三个独立关卡——逐个检查。

权限范围表——只请求任务所需的内容:

范围授权用途
video.publish直接发布到公共动态/post/publish/video/init/(需审核)
video.upload上传到用户的草稿箱/收件箱,供用户完成/post/publish/inbox/video/init/
video.list读取你自己的视频 + 基本计数器展示 POST /v2/video/query/
user.info.basic读取资料(open_id, 显示名称, 头像)POST /v2/user/info/

完整的应用注册 + 产品启用操作指南、审核关卡和 scope_not_authorized 故障排除在 references/oauth-setup.md 中。

2. 获取已认证的客户端并保持令牌存活

OAuth v2:将用户引导至 https://www.tiktok.com/v2/auth/authorize/,在重定向 URI 接收 code,在 https://open.tiktokapis.com/v2/oauth/token/ 交换它,并存储刷新令牌。

生命周期是核心事实:访问令牌 24 小时后过期(expires_in: 86400);刷新令牌持续 365 天(refresh_expires_in: 31536000)并在没有用户重新同意的情况下续期。因此,每日拉取的定时任务每次运行必须刷新访问令牌,而长时间空闲的账号会在 365 天刷新边界静静失效。

# python: 原始 REST,无官方 TikTok SDK。requests/httpx 均可。
import time, json, os, requests

TOKEN_URL = "https://open.tiktokapis.com/v2/oauth/token/"
STORE = "tiktok_token.json"   # 已 gitignore — 保存轮换的 refresh_token

def load(): return json.load(open(STORE)) if os.path.exists(STORE) else {}
def save(t): t["obtained_at"] = int(time.time()); json.dump(t, open(STORE, "w"))

def access_token():
    t = load()
    fresh = t.get("access_token") and time.time() - 60 < t.get("obtained_at", 0) + t["expires_in"]
    if fresh:
        return t["access_token"]
    r = requests.post(TOKEN_URL, data={                 # 每次运行刷新,24h 过期
        "client_key": os.environ["TIKTOK_CLIENT_KEY"],
        "client_secret": os.environ["TIKTOK_CLIENT_SECRET"],
        "grant_type": "refresh_token",
        "refresh_token": t["refresh_token"],            # 365 天有效期;会轮换
    }, headers={"Content-Type": "application/x-www-form-urlencoded"})
    r.raise_for_status()
    new = r.json()
    save(new)                                           # 持久化新的 refresh_token
    return new["access_token"]
// node: 内置 fetch,无需 SDK。
import fs from "node:fs";
const STORE = "tiktok_token.json";

async function accessToken() {
  const t = JSON.parse(fs.readFileSync(STORE, "utf8"));
  if (t.access_token && Date.now() / 1000 < t.obtained_at + t.expires_in - 60) return t.access_token;
  const r = await fetch("https://open.tiktokapis.com/v2/oauth/token/", {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      client_key: process.env.TIKTOK_CLIENT_KEY,
      client_secret: process.env.TIKTOK_CLIENT_SECRET,
      grant_type: "refresh_token",
      refresh_token: t.refresh_token,
    }),
  });
  const n = await r.json();
  n.obtained_at = Math.floor(Date.now() / 1000);
  fs.writeFileSync(STORE, JSON.stringify(n));          // 持久化轮换后的 refresh_token
  return n.access_token;
}

规则:持久化刷新令牌并在每次运行时重新读取它,永远不要使用裸的 access_token。硬编码的 access_token=... 标志在 24 小时内必定失败——这正是 verify.sh 会标记的。

完整的令牌交换流程(授权 URL 参数、PKCE、code 交换)在 references/oauth-setup.md 中。

3. 发布视频(初始化 → 传输 → 轮询)

发布始终是三步:初始化发布、传输字节、轮询直到处理完成(它是异步的)。首先选择传输模式:

情况来源端点
文件在本地/你控制中FILE_UPLOAD/post/publish/video/init/
文件在 已验证 的 HTTPS URLPULL_FROM_URL/post/publish/video/init/
应作为草稿落地,由用户最终发布FILE_UPLOAD/post/publish/inbox/video/init/

初始化(FILE_UPLOAD)——返回 publish_id 和 upload_url:

import math, requests

CHUNK = 10 * 1024 * 1024                      # 10 MB,在 5–64 MB 窗口内
size = os.path.getsize("clip.mp4")
chunk_count = 1 if size < 5 * 1024 * 1024 else math.ceil(size / CHUNK)

init = requests.post(
    "https://open.tiktokapis.com/v2/post/publish/video/init/",
    headers={"Authorization": f"Bearer {access_token()}",
             "Content-Type": "application/json; charset=UTF-8"},
    json={
        "post_info": {"title": "caption #fyp", "privacy_level": "SELF_ONLY"},  # 公共发布需要审核
        "source_info": {
            "source": "FILE_UPLOAD",
            "video_size": size,
            "chunk_size": CHUNK if size >= 5 * 1024 * 1024 else size,
            "total_chunk_count": chunk_count,
        },
    }).json()
publish_id = init["data"]["publish_id"]
upload_url = init["data"]["upload_url"]

传输——顺序 对 upload_url 进行 PUT 操作并附加 Content-Range 头。每个分块 最小 5 MB,最大 64 MB(最后一个分块最大 128 MB),1–1000 个分块;小于 5 MB 的文件作为一个分块,大小等于文件大小。每个 PUT 返回 206(还有更多要发送)或 201(接受最后一个分块):

with open("clip.mp4", "rb") as f:
    for i in range(chunk_count):
        first = i * CHUNK
        data = f.read(CHUNK)
        last = first + len(data) - 1
        r = requests.put(upload_url, data=data, headers={
            "Content-Type": "video/mp4",
            "Content-Range": f"bytes {first}-{last}/{size}",  # 精确字节范围
        })
        assert r.status_code in (206, 201), r.text     # 206 = 继续,201 = 完成

轮询——TikTok 异步处理;检查状态直到 PUBLISH_COMPLETE。请尊重下面的上限——不要紧密循环:

import time
while True:
    s = requests.post(
        "https://open.tiktokapis.com/v2/post/publish/status/fetch/",
        headers={"Authorization": f"Bearer {access_token()}",
                 "Content-Type": "application/json; charset=UTF-8"},
        json={"publish_id": publish_id}).json()
    status = s["data"]["status"]
    if status in ("PUBLISH_COMPLETE", "FAILED"):
        break
    time.sleep(10)                                      # 6/min 上限 — 休眠,不要空转

速率限制:每个用户访问令牌每分钟 6 次请求 → rate_limit_exceeded。限制初始化/状态调用并退避;紧密的状态轮询循环会在几秒内耗尽预算。

PULL_FROM_URL 要求域/URL 前缀在门户中已验证(仅 HTTPS,无重定向,1 小时下载超时),否则初始化返回 url_ownership_unverified。完整的 PULL_FROM_URL 初始化请求体和验证步骤在 references/metrics-and-publish.md 中。

4. 拉取性能数据(两个 API,一条规则)

核心区别:Display 提供计数器;只有 Business API 提供观看时长、完成度和流量来源。

# (a) Display API — 仅基本计数器。需要 scope video.list,每次最多 20 个 id。
counts = requests.post(
    "https://open.tiktokapis.com/v2/video/query/",
    params={"fields": "id,title,view_count,like_count,comment_count,share_count,duration,create_time"},
    headers={"Authorization": f"Bearer {access_token()}",
             "Content-Type": "application/json"},
    json={"filters": {"video_ids": ["<id1>", "<id2>"]}}).json()
# 返回:view_count, like_count, comment_count, share_count, duration, title, create_time
# (b) Business Account API — 真正的参与度信号。
# 返回 Display 无法提供的指标:average_time_watched, total_time_watched,
# full_video_watched_rate (完成率), impression_sources (FYP / 关注 / 个人资料 /
# 搜索), audience_countries。(端点格式在 references/metrics-and-publish.md 中。)
错误:期望从 /v2/video/query/ 获取 average_time_watched / full_video_watched_rate
正确:计数器来自 Display /v2/video/query/;
      观看时长 + 完成率 + 展示来源来自 Business Account API。

注意事项:商业洞察指标有 24–48 小时延迟,可能与应用内数字不同。将新拉取的数据视为临时数据——wiki 日志(下一节)是观察它们稳定的地方。按 API 划分的完整指标目录在 references/metrics-and-publish.md 中。

5. 摄入到 wiki —— 实际交付物

只打印到标准输出然后消失的数据拉取是浪费的。每次拉取都会在 02-DOCS/wiki/shortform/ 下追加一个带日期的条目,以平台命名空间区分,使得账号的数字成为可查询的历史记录,供策略/包装模块读取。

02-DOCS/wiki/shortform/
  index.md                       # 滚动指针,指向最新快照 + 未解决问题
  tiktok-account-2026-06-02.md   # 带日期的账号快照(每次拉取一个)
  videos/tiktok-<video_id>.md    # 每个视频的运行日志,最新条目在上方

文件名带有 tiktok- 前缀,因为同一个 shortform/ wiki 也可能包含 Instagram 和 YouTube 的数据拉取——命名空间可防止平台冲突。

每次拉取的条目模板。frontmatter 符合 OKF v0.1 规范——非空的 type 是唯一硬性要求;title/tags/timestamp 可选。YAML 之后,正文以当前日期为一级标题,然后是一段可选的摘要说明,接着是 TikTok 性能指标的结构化展示。

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

ericrisco/rsc-harness

Use when writing the words on a single conversion page — the hero headline and subhead, the offer, the proof and testimonials, and one primary CTA — or diagnosing a page that gets traffic and does not convert, as a copy problem rather than a layout one. NOT the paid ad that drives the click (that is `ads`), NOT the visual layout the words sit in (that is `design`), NOT the experiment that picks the winning variant (that is `ab-testing`).

ericrisco/rsc-harness

Use when you need to render an actual video file with Remotion — React compositions, the Composition/Sequence/TransitionSeries graph, transitions, burned-in word-by-word captions from a transcript, automatic silence removal, b-roll overlays, headless CI renders, and a final MP4 or MOV. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT mastering audio to LUFS or building an RSS feed (that is `podcast`), NOT structuring the narrative arc (that is `course-storytelling`).

ericrisco/rsc-harness

Use when you have raw 9:16 footage and need it cut into a post-ready vertical short — dead air removed, fast jump cuts, karaoke word-by-word burned-in captions from a transcript, cuts and zooms snapped to the music beat, safe-area placement so captions clear the platform UI, and a platform-correct MP4 export. NOT writing the script, hook, beats or caption text (that is `video-shorts`), NOT building a Remotion React composition codebase (that is `remotion-video`), NOT deciding when or where to post (that is `social-publisher`).

ericrisco/rsc-harness

Use when a Reels/TikTok/Shorts account needs its next video ideas scored into a ranked backlog, grounded in its own performance log plus dated trending sounds, each bet logged so its outcome feeds the next batch. NOT scripting a chosen idea (that is `video-shorts`), NOT pillars or cadence (that is `shortform-strategy`), NOT packaging a finished cut (that is `shortform-packaging`).

ericrisco/rsc-harness

Use when a vertical short is shot or scripted and you need the upload-form copy and cover that win the feed — the hook line, the first-frame on-screen text, the search-led caption, a tight hashtag set, and the cover frame; it learns from what performed via the 02-DOCS log. NOT inventing the idea (that is `shortform-ideation`), NOT scripting or directing the cuts (that is `video-shorts`), NOT executing the edit (that is `shortform-editing`), NOT scheduling the post (that is `social-publisher`).

ericrisco/rsc-harness

Use when the unit of work is a TikTok/Reels account, not one clip: positioning, sustainable cadence and format mix, ride-or-skip on a trend or sound, recurring series, diagnosing a flat account, and the dated learning loop. NOT the single script or hook variants (that is `video-shorts`), NOT the idea backlog (that is `shortform-ideation`).

ericrisco/rsc-harness

Use when planning a posting schedule, building a multi-platform content calendar, or reshaping one source asset into channel-native posts across X, LinkedIn, Instagram, Threads, Bluesky, TikTok, Facebook or YouTube — cadence, best-time slots, per-platform format limits, API publish caps, and a dated CSV or JSON calendar a scheduler can import. NOT the brand voice the posts speak in (that is `brand-voice`), NOT the editorial strategy of what to make (that is `content-engine`).

ericrisco/rsc-harness

Use when scripting or directing the edit of a single vertical short that has to hold attention from the first frame — turning a topic, a clip or a long video into a shot-by-shot script and an edit decision sheet, fixing a hook that dies in second three, generating hook variants to test, and planning cuts and on-screen text. NOT scheduling or cross-platform cadence (that is `social-publisher`), NOT running the editorial calendar (that is `content-engine`), NOT defining the durable brand tone (that is `brand-voice`).

ericrisco/rsc-harness

Use to judge whether a short-form clip is worth publishing — scores a reel, short or podcast excerpt 0-100 on ten weighted criteria with automatic penalties, then ranks a batch and says where the cut-off falls. Run it on transcript candidates before rendering. NOT writing the hook or caption (that is `shortform-packaging`), NOT inventing the idea (that is `shortform-ideation`), NOT executing the edit (that is `shortform-editing`).

相关技能