内容
<!-- delx header v2 -->
<h1 align="center">抖音智能发布工具</h1>
<div align="center">
<img src="assets/banner.png" alt="抖音智能发布工具" width="85%" />
</div>
<h3 align="center">
优先考虑智能代理的抖音内容发布 API 命令行工具 + MCP。<br>支持 dry-run 安全、OAuth 就绪检查、结构化输出，适用于任何智能代理运行时。
</h3>
<p align="center">
<a href="https://www.npmjs.com/package/tiktok-agent-publisher"><img src="https://img.shields.io/npm/v/tiktok-agent-publisher?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm 版本" /></a>
<a href="https://www.npmjs.com/package/tiktok-agent-publisher"><img src="https://img.shields.io/npm/dm/tiktok-agent-publisher?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm 下载量" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="MIT 许可证" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="为 MCP 而建" /></a>
</p>
<p align="center">
<a href="https://github.com/davidmosiah/tiktok-agent-publisher/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/tiktok-agent-publisher?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub 明星" /></a>
<a href="https://github.com/davidmosiah/tiktok-agent-publisher/actions/workflows/ci.yml"><img src="https://github.com/davidmosiah/tiktok-agent-publisher/actions/workflows/ci.yml/badge.svg" alt="CI 状态" /></a>
<a href="https://github.com/davidmosiah"><img src="https://img.shields.io/badge/PART_OF-Delx_Agent_Stack-0EA5A3?style=for-the-badge&labelColor=0F172A" alt="Delx 代理栈的一部分" /></a>
<a href="https://github.com/davidmosiah/tiktok-agent-publisher"><img src="https://img.shields.io/badge/CATEGORY-Reach-FE2C55?style=for-the-badge&labelColor=0F172A" alt="分类" /></a>
</p>
> ⭐ **如果这个优先考虑智能代理的工具能帮助你的工作流，请给仓库加星。** 星标使这个工具对其他构建者更容易发现，并帮助 Delx 继续提供开放的基础设施。<br>
> 🧱 [Delx 代理栈](https://github.com/davidmosiah) 的一部分 — 15 个开放源代码的 MCP 服务器，涵盖 **内容创作、传播和协调**。
---
<!-- /delx header v2 -->
本地优先的抖音内容发布 API 工具，适用于 AI 智能代理。它为 Codex、Claude、Cursor、Hermes、OpenClaw 和其他 MCP 客户端提供了一种安全的方式来检查就绪状态、构建 OAuth URL、dry-run 发布流程和仅在显式启用实时模式时上传抖音视频。
在智能代理需要发布或检查抖音内容而无需浏览器自动化、隐藏状态或令牌泄漏时使用。
## 为什么它存在
大多数社交发布脚本都是为人类终端用户设计的。智能代理需要不同的约定：
- 说明安装/运行时规则的清单
- 写操作前的连接状态工具
- 永不返回令牌值的隐私边界
- 默认 dry-run
- 用于计划、重试和审计跟踪的结构化 JSON 输出
此仓库围绕抖音官方内容发布 API 封装了该约定。
## 安装
```bash
npm install -g tiktok-agent-publisher
```
或在不安装的情况下运行：
```bash
npm exec --yes --package=tiktok-agent-publisher -- tiktok-agent-publisher doctor
```
## 第一次发布（Dry-Run）演练
不需要抖音凭证即可尝试此操作。没有 `.env` 的情况下，dry-run 默认启用，因此以下每个命令都返回结构化 JSON，而不触及实时 API。这是智能代理在首次实际发布之前应遵循的确切顺序。输出是实际的 CLI 运行结果，稍微修剪过。
**1. 检查就绪状态。** `doctor` 报告模式和仍缺失的内容 — 永远不会返回令牌值。
```bash
$ tiktok-agent-publisher doctor
{
"ok": true,
"dry_run": true,
"configured": {
"client_key": false,
"client_secret": false,
"access_token": false,
"refresh_token": false,
"public_media_base_url": false,
"supabase_storage": false
},
"missing": [
"TIKTOK_CLIENT_KEY",
"TIKTOK_CLIENT_SECRET",
"TIKTOK_ACCESS_TOKEN",
"TIKTOK_REFRESH_TOKEN"
],
"ready_for_live_publish": false,
"ready_for_direct_video_upload": false,
"next_steps": [
"当前模式是 dry-run。在实时发布前使用 dry-run 验证智能代理工作流。"
]
}
```
**2. 确认隐私边界。** `privacy-audit` 说明了哪些内容保留在本地，哪些内容发送到抖音，以便智能代理在任何写入操作前理解约定。
```bash
$ tiktok-agent-publisher privacy-audit
{
"project": "tiktok-agent-publisher",
"secrets_returned_to_agent": false,
"token_storage": "环境变量或本地 .env 文件，具有用户仅限权限；工具永远不会返回令牌值。",
"safety_rules": [
"Dry-run 是默认的。",
"仅发布用户拥有或有权限发布的内容。",
"在实时直接发布前使用显式确认。"
]
}
```
**3. 构建发布负载（dry-run）。** 验证作业形状和标题，而不上传任何内容。`result.platformPostId` 是一个合成的 `dryrun_*` ID，`raw.dryRun` 是 `true`，因此您可以安全地连接重试和审计日志。
```bash
$ tiktok-agent-publisher publish-video \
--video ./short.mp4 \
--caption "第一个智能代理发布 — 测试 dry-run 流程" \
--title "来自智能代理的问候"
{
"ok": true,
"dry_run": true,
"job": {
"id": "tiktok_1780082349025",
"platform": "tiktok",
"status": "queued",
"caption": "第一个智能代理发布 — 测试 dry-run 流程",
"mediaPaths": ["./short.mp4"],
"metadata": { "title": "来自智能代理的问候" }
},
"result": {
"provider": "tiktok_official",
"platformPostId": "dryrun_1780082349025",
"raw": { "dryRun": true, "jobId": "tiktok_1780082349025" }
}
}
```
**4. 轮询状态（dry-run）。** `publish-status` 返回 `DRY_RUN` 状态，以便可以端到端地练习轮询循环。
```bash
$ tiktok-agent-publisher publish-status --publish-id dryrun_1780082349025
{ "dryRun": true, "publishId": "dryrun_1780082349025", "status": "DRY_RUN" }
```
**5. 列出最近的视频（dry-run）。** 返回一个空的、结构良好的列表 — 与实时 API 返回的内容相同，因此发布后确认代码无需更改。
```bash
$ tiktok-agent-publisher list-videos --max-count 5
{ "dryRun": true, "videos": [], "cursor": null, "has_more": false }
```
**转为实时模式。** 填写 `TIKTOK_CLIENT_KEY` / `TIKTOK_CLIENT_SECRET`（并完成 OAuth — 参见 [`auth-url`](#cli)），确认 `doctor` 报告 `ready_for_live_publish: true`，然后设置 `TIKTOK_DRY_RUN=false`。然后，这五个命令将对真实的内容发布 API 进行操作。
## CLI
```bash
tiktok-agent-publisher manifest --client codex
tiktok-agent-publisher doctor
tiktok-agent-publisher privacy-audit
tiktok-agent-publisher auth-url --redirect-uri http://localhost:8787/callback
tiktok-agent-publisher publish-video --video ./short.mp4 --caption "启动复制"
tiktok-agent-publisher publish-status --publish-id <publish_id>
tiktok-agent-publisher list-videos --max-count 10
```
默认启用 dry-run。只有在 `doctor` 清洁且您准备好进行实时 API 调用时，才设置 `TIKTOK_DRY_RUN=false`。
## MCP
标准输入:
```bash
tiktok-agent-mcp
```
HTTP:
```bash
TIKTOK_MCP_TRANSPORT=http tiktok-agent-mcp
```
Hermes 样式配置:
```yaml
mcp_servers:
tiktok:
command: npx
args: ["-y", "tiktok-agent-publisher"]
sampling:
enabled: false
```
推荐的首批调用：
1. `tiktok_connection_status`
2. `tiktok_privacy_audit`
3. `tiktok_publish_video`
## 智能代理接口
| 工具 | 目的 |
|---|---|
| `tiktok_agent_manifest` | Codex、Claude、Cursor、Hermes 和 OpenClaw 的安装/运行时指南 |
| `tiktok_connection_status` | Dry-run、OAuth 和媒体托管就绪检查，无令牌值 |
| `tiktok_privacy_audit` | 本地文件、令牌和实时发布边界 |
| `tiktok_publish_video` | Dry-run 或实时视频发布流程 |
| `tiktok_publish_status` | 发布状态轮询 |
| `tiktok_list_videos` | 最近视频列表，用于发布后检查 |
## 复制粘贴智能代理提示
```text
使用 tiktok-agent-publisher。首先调用 tiktok_connection_status 和 tiktok_privacy_audit。
如果启用了 dry-run，请仅构建发布负载。不要请求或打印令牌值。
```
## 配置
将 `.env.example` 复制到 `.env` 并仅填写所需的值。不要提交 `.env`、令牌文件或 `.agent-data/`。
对于视频 inbox 上传，可以通过抖音的上传 URL 直接上传本地文件。对于照片和拉取 URL 的工作流，可以使用 Supabase Storage 或另一个公共媒体托管服务。
## 安全模型
- 令牌从环境或本地 `.env` 读取；工具响应永远不包含令牌值。
- 除非设置 `TIKTOK_DRY_RUN=false`，否则实时发布被禁用。
- OAuth PKCE 验证器在本地 `.agent-data/` 中持久化，不在 MCP 输出中返回。
- 包使用抖音官方的 API 接口；它不自动化浏览器会话。
## 开发
```bash
npm install
npm test
npm run check
```
---
## 📧 联系与支持
- 📨 **support@delx.ai** — 一般问题、集成帮助、合作伙伴
- 🐛 **错误报告 / 功能请求** — [GitHub 问题](https://github.com/davidmosiah/tiktok-agent-publisher/issues)
- 🐦 **更新** — [@delx369](https://x.com/delx369) 在 X 上
- 🌐 **网站** — [wellness.delx.ai](https://wellness.delx.ai)
