内容
<!-- delx header v2 -->
<h1 align="center">YouTube Shorts 代理</h1>
<div align="center">
<img src="assets/banner.png" alt="YouTube Shorts 代理" width="85%" />
</div>
<h3 align="center">
适用于 YouTube Data API 的代理优先的 YouTube Shorts 上传工具。<br>支持 dry-run 安全、OAuth 准备就绪检查、适用于 Codex / Claude / Cursor / Hermes 的 MCP 准备就绪。
</h3>
<p align="center">
<a href="https://www.npmjs.com/package/youtube-shorts-agent"><img src="https://img.shields.io/npm/v/youtube-shorts-agent?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm 版本" /></a>
<a href="https://www.npmjs.com/package/youtube-shorts-agent"><img src="https://img.shields.io/npm/dm/youtube-shorts-agent?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/youtube-shorts-agent/stargazers"><img src="https://img.shields.io/github/stars/davidmosiah/youtube-shorts-agent?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub 星标" /></a>
<a href="https://github.com/davidmosiah/youtube-shorts-agent/actions/workflows/ci.yml"><img src="https://github.com/davidmosiah/youtube-shorts-agent/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/youtube-shorts-agent"><img src="https://img.shields.io/badge/CATEGORY-Reach-FF0000?style=for-the-badge&labelColor=0F172A" alt="类别" /></a>
</p>
> ⭐ **如果此代理优先的工具能帮助您的 workflow，请为仓库加星。** 星标使该工具对其他构建者更容易发现，并帮助 Delx 继续提供开放的基础设施。<br>
> 🧱 [Delx 代理栈](https://github.com/davidmosiah) 的一部分 — 适用于 **body, reach 和 coordination** 的 15 个开源 MCP 服务器。
---
<!-- /delx header v2 -->
适用于 YouTube Data API 的代理优先的 YouTube Shorts 上传工具。它适用于 Codex、Claude、Cursor、Hermes、OpenClaw 和任何需要可预测上传工作流的 MCP 客户端，支持 dry-run 安全、OAuth 准备就绪检查和结构化输出。
在需要通过官方 API 上传 Shorts 而无需触及 YouTube Studio UI 时使用它。
## 代理可获得的功能
- `youtube_agent_manifest` 用于安装/运行时指导
- `youtube_connection_status` 在上传尝试之前
- `youtube_privacy_audit` 用于本地令牌和媒体边界
- `youtube_oauth_authorize_url` 带有本地 PKCE 会话存储
- `youtube_upload_short` 支持 `containsSyntheticMedia`
- `youtube_list_recent_videos` 用于轻量级上传后检查
## 安装
```bash
npm install -g youtube-shorts-agent
```
或直接运行：
```bash
npm exec --yes --package=youtube-shorts-agent -- youtube-shorts-agent doctor
```
## 命令行界面
```bash
youtube-shorts-agent manifest --client codex
youtube-shorts-agent doctor
youtube-shorts-agent privacy-audit
youtube-shorts-agent auth-url --redirect-uri http://localhost:8787/callback
youtube-shorts-agent upload-short --video ./short.mp4 --title "启动标题" --caption-file copy.txt
youtube-shorts-agent list-recent --max-results 10
```
默认启用 dry-run。只有当 `doctor` 报告完整的 OAuth 设置并且您打算调用实时 API 时，才设置 `YOUTUBE_DRY_RUN=false`。
## 首次上传（dry-run 演练）
这是完整的首次运行路径。 此处的每个步骤都是 **dry-run 安全的** — 不需要凭证，也不会向 YouTube 发送任何内容。 以下输出是实际运行的逐字记录。
**1. 检查就绪状态。** 如果没有配置 OAuth，`doctor` 会确认您处于 dry-run 模式：
```bash
youtube-shorts-agent doctor
```
```json
{
"ok": true,
"dry_run": true,
"configured": {
"client_credentials": "missing",
"access_token": "missing",
"refresh_token": "missing"
},
"missing_count": 3,
"ready_for_live_upload": false,
"next_steps": [
"当前模式是 dry-run。在进行实时上传之前，请验证元数据和代理流程。"
]
}
```
**2. 准备 Short 及其字幕。**
```bash
printf '启动代理优先的 Shorts 上传工具。\n#shorts #ai #agents' > copy.txt
# short.mp4 是您的垂直 9:16 视频
```
**3. 在 dry-run 中运行上传。** 不会进行网络调用；该工具会返回它将发布的确切作业和结果，以便代理可以在实时上传之前验证元数据：
```bash
youtube-shorts-agent upload-short \
--video ./short.mp4 \
--title "代理优先的 Shorts 上传" \
--caption-file copy.txt \
--tags ai,agents \
--duration 24
```
```json
{
"ok": true,
"dry_run": true,
"job": {
"id": "youtube_1780082215631",
"platform": "youtube",
"status": "queued",
"createdAt": "2026-05-29T19:16:55.631Z",
"caption": "启动代理优先的 Shorts 上传工具。\n#shorts #ai #agents",
"targetUrl": "",
"mediaPaths": ["./short.mp4"],
"metadata": {
"title": "代理优先的 Shorts 上传",
"youtube_title": "代理优先的 Shorts 上传",
"youtube_tags": ["ai", "agents"],
"youtube_contains_synthetic_media": true,
"video_duration_sec": 24,
"video_aspect_ratio": "9:16"
}
},
"result": {
"provider": "youtube_official",
"platformPostId": "dryrun_1780082215631",
"releaseUrl": "https://www.youtube.com",
"raw": { "dryRun": true, "jobId": "youtube_1780082215631" }
}
}
```
`platformPostId` 以 `dryrun_` 为前缀，`releaseUrl` 是 YouTube 根目录 — 这两个都表明没有上传任何内容。`id`、`createdAt` 和 `dryrun_*` 值每次运行都会变化。
**4. 确认频道列表路径** （在 dry-run 中返回空列表）：
```bash
youtube-shorts-agent list-recent --max-results 5
```
```json
{ "items": [] }
```
**转为实时。** 配置 OAuth（`youtube-shorts-agent auth-url --redirect-uri http://localhost:8787/callback`，然后用令牌交换回调代码），在 `.env` 中设置 `YOUTUBE_CLIENT_ID` / `YOUTUBE_CLIENT_SECRET` / `YOUTUBE_ACCESS_TOKEN` / `YOUTUBE_REFRESH_TOKEN`，重新运行 `doctor` 直到 `ready_for_live_upload` 为 `true`，然后设置 `YOUTUBE_DRY_RUN=false` 并重新运行相同的 `upload-short` 命令。
## MCP
```bash
youtube-shorts-mcp
```
HTTP 传输：
```bash
YOUTUBE_MCP_TRANSPORT=http youtube-shorts-mcp
```
Hermes 样式配置：
```yaml
mcp_servers:
youtube_shorts:
command: npx
args: ["-y", "youtube-shorts-agent"]
sampling:
enabled: false
```
推荐的首批调用：
1. `youtube_connection_status`
2. `youtube_privacy_audit`
3. `youtube_upload_short`
## 代理接口
| 工具 | 用途 |
|---|---|
| `youtube_agent_manifest` | Codex、Claude、Cursor、Hermes 和 OpenClaw 的安装/运行时指导 |
| `youtube_connection_status` | 无令牌值的 OAuth 和 dry-run 就绪状态检查 |
| `youtube_privacy_audit` | 上传范围、合成媒体和本地文件边界 |
| `youtube_oauth_authorize_url` | 带有本地会话存储的 PKCE 授权 URL |
| `youtube_upload_short` | Dry-run 或实时 Shorts 上传 |
| `youtube_list_recent_videos` | 轻量级频道验证 |
## 复制粘贴代理提示
```text
使用 youtube-shorts-agent。首先调用 youtube_connection_status 和 youtube_privacy_audit。
如果上传 AI 生成的媒体，请保持 containsSyntheticMedia=true。永远不要打印令牌值。
```
## 配置
复制 `.env.example` 到 `.env`。 将 `.env` 和 `.agent-data/` 存放在 Git 之外。
上传工具默认情况下为 AI 生成或 AI 编辑的视频设置 `containsSyntheticMedia=true`。 仅在资产不为真时覆盖。
## 安全模型
- CLI 或 MCP 工具永远不会返回 OAuth 令牌。
- PKCE 验证器存储在 `.agent-data/` 中。
- 实时上传需要 `YOUTUBE_DRY_RUN=false`。
- 该软件包使用官方的 YouTube Data API，不会自动化 Studio UI。
## 开发
```bash
npm install
npm test
npm run check
```
---
## 📧 联系与支持
- 📨 **support@delx.ai** — 一般问题、集成帮助、合作伙伴
- 🐛 **错误报告/功能请求** — [GitHub 问题](https://github.com/davidmosiah/youtube-shorts-agent/issues)
- 🐦 **更新** — [@delx369](https://x.com/delx369) 在 X 上
- 🌐 **网站** — [wellness.delx.ai](https://wellness.delx.ai)
