内容
# YouTube 分析命令行工具
YouTube 分析 API 的命令行工具。它保留您的每日数据的本地副本，这使得它可以比较一个时间段与另一个时间段，将多个频道并排显示，并标记一个异常的日子。普通的 API 无法自行完成这些操作。
YouTube 分析 API 只有一个端点，即 `reports.query`，它返回一个列数组响应，难以阅读。此命令行工具将该端点包装在命名报告（概览、热门视频、流量、留存、收入、人口统计）中，并打印干净的标签表格。此外，它还将您的每日行同步到本地 SQLite 数据库。本地副本是重要的部分：它使得时间段差异、更改差异、异常检查和多频道汇总在不每次重新查询 API 的情况下工作。
在 [Google 的 YouTube 分析文档](https://developers.google.com/youtube/analytics) 中了解更多关于 API 的信息。
由 [@RyanCollinsAI](https://github.com/RyanCollinsAI) 构建。
## 安装
推荐的安装路径同时安装 `youtube-analytics-pp-cli` 二进制文件和 `pp-youtube-analytics` 代理技能（Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot 和其他上游 [`skills`](https://github.com/vercel-labs/skills) CLI 支持的代理） :
```bash
npx -y @mvanhorn/printing-press install youtube-analytics
```
仅限 CLI（无技能）：
```bash
npx -y @mvanhorn/printing-press install youtube-analytics --cli-only
```
仅限技能（此选项跳过 CLI 二进制文件，因此请使用它来更新或重新安装技能）：
```bash
npx -y @mvanhorn/printing-press install youtube-analytics --skill-only
```
要将技能安装限制为一个或多个特定代理（可重复；代理名称与 [`skills`](https://github.com/vercel-labs/skills) CLI 匹配）：
```bash
npx -y @mvanhorn/printing-press install youtube-analytics --agent claude-code
npx -y @mvanhorn/printing-press install youtube-analytics --agent claude-code --agent codex
```
### 无 Node
生成的安装路径在发布前是类别不可知的。如果 `npx` 在发布前不可用，请安装 Node 或使用公共库条目后的特定 Go 回退。
### 预构建二进制文件
从 [最新发布](https://github.com/mvanhorn/printing-press-library/releases/tag/youtube-analytics-current) 为您的平台下载预构建二进制文件。在 macOS 上，请清除 Gatekeeper 隔离：`xattr -d com.apple.quarantine <binary>`。在 Unix 上，请将其标记为可执行：`chmod +x <binary>`。
<!-- pp-hermes-install-anchor -->
## 为 Hermes 安装
从 Hermes CLI：
```bash
hermes skills install mvanhorn/printing-press-library/cli-skills/pp-youtube-analytics --force
```
在 Hermes 聊天会话中：
```bash
/skills install mvanhorn/printing-press-library/cli-skills/pp-youtube-analytics --force
```
## 为 OpenClaw 安装
告诉您的 OpenClaw 代理（复制此内容）：
```
安装 pp-youtube-analytics 技能，地址为 https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-youtube-analytics。该技能定义了其所需的 CLI 如何安装。
```
## 与 Claude Desktop 一起使用
此 CLI 提供了 [MCPB](https://github.com/modelcontextprotocol/mcpb) 包，这是 Claude Desktop 的标准格式，用于一键式 MCP 扩展安装（无需 JSON 配置）。
要安装：
1. 从 [最新发布](https://github.com/mvanhorn/printing-press-library/releases/tag/youtube-analytics-current) 为您的平台下载 `.mcpb` 文件。
2. 双击 `.mcpb` 文件。Claude Desktop 打开并引导您完成安装。
3. 在 Claude Desktop 提示您时，填写 `YOUTUBE_CLIENT_ID`、`YOUTUBE_CLIENT_SECRET` 和 `YOUTUBE_REFRESH_TOKEN`。
需要 Claude Desktop 1.0.0 或更高版本。预构建包适用于 macOS Apple Silicon (`darwin-arm64`) 和 Windows (`amd64`、`arm64`)。对于其他平台，请使用手动配置。
<details>
<summary>手动 JSON 配置（高级）</summary>
如果您无法使用 MCPB 包（较旧的 Claude Desktop、不支持的平台），请安装 MCP 二进制文件并手动配置。
从此 CLI 的公共库条目或预构建版本安装 MCP 二进制文件。
将以下内容添加到您的 Claude Desktop 配置（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"youtube-analytics": {
"command": "youtube-analytics-pp-mcp",
"env": {
"YOUTUBE_CLIENT_ID": "<您的OAuth客户端ID>",
"YOUTUBE_CLIENT_SECRET": "<您的OAuth客户端密钥>",
"YOUTUBE_REFRESH_TOKEN": "<您的刷新令牌>"
}
}
}
}
```
</details>
## 身份验证
YouTube 分析是私有、每个频道的數據，因此没有 API 密钥路径。CLI 使用 OAuth 2.0 刷新令牌进行身份验证。您提供客户端 ID、客户端密钥和刷新令牌，它会在每次运行时将刷新令牌兑换为短期访问令牌。运行时没有浏览器步骤，也没有令牌文件需要跟踪。
**推荐：环境变量。** 在 Google Cloud 项目中创建一个 OAuth 2.0 客户端，然后导出三个变量：
```bash
export YOUTUBE_CLIENT_ID=<您的OAuth客户端ID>
export YOUTUBE_CLIENT_SECRET=<您的OAuth客户端密钥>
export YOUTUBE_REFRESH_TOKEN=<您的刷新令牌>
```
将刷新令牌范围限定为 `https://www.googleapis.com/auth/yt-analytics.readonly`。如果您想要收入指标，请添加 `https://www.googleapis.com/auth/yt-analytics-monetary.readonly`。
**交互式替代：`auth login`。** 如果您不想手动生成刷新令牌，请运行浏览器 OAuth 流，让 CLI 将令牌存储在其配置文件中：
```bash
youtube-analytics-pp-cli auth login --client-id <id> --client-secret <secret>
```
身份验证子命令：
- `youtube-analytics-pp-cli auth setup` 打印注册 Google Cloud OAuth 应用的步骤（添加 `--launch` 以打开页面）。
- `youtube-analytics-pp-cli auth login --client-id <id> --client-secret <secret>` 运行浏览器 OAuth 流并保存令牌。
- `youtube-analytics-pp-cli auth status` 显示当前凭证状态。
- `youtube-analytics-pp-cli auth logout` 清除存储的令牌。
`YOUTUBE_ANALYTICS_OAUTH2C`（原始、预生成的访问令牌）也作为备用接受，但不是日常使用的路径。它过期很快，CLI 无法刷新它。
## 快速入门
```bash
# 在执行任何操作之前，请确认凭证已加载并且 API 可访问。
youtube-analytics-pp-cli doctor
# 将频道注册为友好名称，以便后续命令使用 --channel MyChannel。
youtube-analytics-pp-cli channels add --name MyChannel --channel-id UCxxxxxxxxxxxxxxxxxxxxxx
# 构建本地存档。每个趋势和比较都从中读取。
youtube-analytics-pp-cli sync --channel MyChannel
# 标题答案：上周的数字，以及与上一周的比较。
youtube-analytics-pp-cli report --channel MyChannel --last 7d
# 所有注册频道并排显示，按收入排序。
youtube-analytics-pp-cli rollup --last 28d --sort revenue
```
## 独特功能
没有其他此 API 的工具具有这些功能。
### 本地存档累积
- **`sync`** 将您的每日 YouTube 分析行拉入本地 SQLite 存档，以便离线进行趋势和比较。
_首先运行此命令。每个报告、比较和异常命令都读取它构建的存档。_
```bash
youtube-analytics-pp-cli sync --channel MyChannel
```
- **`report`** 显示某个期间的浏览量、观看时间、订阅者和收入，并显示每个指标的上一等值期间和更改。
_最快的查看频道表现以及是否上涨或下跌的方式。增量已经计算。_
```bash
youtube-analytics-pp-cli report --channel MyChannel --last 7d
```
- **`whatchanged`** 比较两个期间的每个同步维度，并对最大的变动进行排名：流量来源、视频、收入。
_告诉您下降是否是真实的，以及发生了什么变化，而无需人工比较两个仪表板。_
```bash
youtube-analytics-pp-cli whatchanged --channel MyChannel --period last-week
```
- **`anomaly`** 标记最新最终期间的任何指标，如果它超过其拖尾平均值和标准差。
_在 RPM 或浏览量崩溃早期发现问题，以免影响收入。_
```bash
youtube-analytics-pp-cli anomaly --channel MyChannel
```
- **`rpm`** 以稳定的序列报告每月 RPM、CPM 和货币化播放次数，在尾随重新同步结算延迟的收入调整后。
_回答“我的 RPM 在 2 月份是多少”并提供一个稳定的数字。_
```bash
youtube-analytics-pp-cli rpm --channel MyChannel --by month
```
- **`movers`** 按周环比变化对视频进行排名，显示增加和减少的视频。
_告诉您哪些视频有动力，而不仅仅是哪些视频最大。_
```bash
youtube-analytics-pp-cli movers --channel MyChannel --period last-week
```
### 多频道命令
- **`rollup`** 显示每个注册频道在同一期间并排显示，每行一个频道，按浏览量或收入排序。
_取代登录 YouTube Studio 每个频道一次。整个投资组合在一个表格中。_
```bash
youtube-analytics-pp-cli rollup --last 28d --sort revenue
```
- **`channels`** 将友好名称（如 MyChannel）映射到频道 ID，以便每个命令都可以使用 `--channel` 名称。
_注册一个频道，然后在每个地方使用其名称而不是 UC... ID。_
```bash
youtube-analytics-pp-cli channels list
```
### 代理原生管道
- **`sql`** 直接对本地分析存档运行只读 SQL，以进行任何聚合操作，而预设无法涵盖。
_当问题与预设不匹配时使用此功能。任意切片，无需额外 API 调用。_
```bash
youtube-analytics-pp-cli sql "SELECT day, views FROM report_rows ORDER BY day DESC LIMIT 7"
```
## 用法
运行 `youtube-analytics-pp-cli --help` 以获取完整的命令参考和标志列表。
## 命令
### group-items
管理组项目
- **`youtube-analytics-pp-cli group-items delete`** - 从组中删除项目。
- **`youtube-analytics-pp-cli group-items insert`** - 创建组项目。
- **`youtube-analytics-pp-cli group-items list`** - 返回与 API 请求参数匹配的组项目集合。
### groups
管理组
- **`youtube-analytics-pp-cli groups delete`** - 删除组。
- **`youtube-analytics-pp-cli groups insert`** - 创建组。
- **`youtube-analytics-pp-cli groups list`** - 返回与 API 请求参数匹配的组集合。例如，您可以检索所有者为已认证用户的所有组，或通过其唯一 ID 检索一个或多个组。
- **`youtube-analytics-pp-cli groups update`** - 修改组。例如，您可以更改组的标题。
### reports
管理报告
- **`youtube-analytics-pp-cli reports`** - 检索您的 YouTube 分析报告。
## 输出格式
```bash
# 人类可读表格（终端默认，JSON 输出时管道传输）
youtube-analytics-pp-cli group-items list
# 用于脚本和代理的 JSON
youtube-analytics-pp-cli group-items list --json
# 过滤到特定字段
youtube-analytics-pp-cli group-items list --json --select id,name,status
# 干运行：显示请求而不发送
youtube-analytics-pp-cli group-items list --dry-run
# 代理模式：JSON、紧凑且无提示，开启一个标志
youtube-analytics-pp-cli group-items list --agent
```
## 代理用法
此 CLI 是为 AI 代理调用而构建的：
- **非交互式**：它永远不会提示；每个输入都是标志。
- **可管道化**：`--json` 输出到 stdout，错误到 stderr。
- **可过滤**：`--select id,name` 只返回您要求的字段。
- **可预览**：`--dry-run` 显示请求而不发送。
- **显式重试**：添加 `--idempotent` 以创建重试，并添加 `--ignore-missing` 以删除重试，当操作数为 0 时应视为成功。
- **可确认**：`--yes` 显式确认破坏性操作。
- **支持离线**：同步和搜索命令在本地 SQLite 存储可用时使用它。
- **默认代理安全**：除非您传递 `--human-friendly`，否则无颜色和格式。
退出代码：`0` 成功，`2` 用法错误，`3` 未找到，`4` 身份验证错误，`5` API 错误，`7` 速率限制，`10` 配置错误。
## 健康检查
```bash
youtube-analytics-pp-cli doctor
```
验证配置、凭证和 API 连接性。
## 配置
配置文件：`~/.config/youtube-analytics-pp-cli/config.toml`
静态请求头可以在 `headers` 下配置；每个命令的头重写优先。
环境变量：
| 名称 | 必需 | 描述 |
| --- | --- | --- |
| `YOUTUBE_CLIENT_ID` | 是（推荐路径） | 来自 Google Cloud 项目的 OAuth 2.0 客户端 ID。 |
| `YOUTUBE_CLIENT_SECRET` | 是（推荐路径） | 与客户端 ID 配对的 OAuth 2.0 客户端密钥。 |
| `YOUTUBE_REFRESH_TOKEN` | 是（推荐路径） | 刷新令牌范围 `yt-analytics.readonly`（添加 `yt-analytics-monetary.readonly` 以获取收入）。CLI 自动将其兑换为访问令牌。 |
| `YOUTUBE_ACCESS_TOKEN` | 否 | 预生成的短期访问令牌；如果存在，则直接使用。 |
| `YOUTUBE_ANALYTICS_OAUTH2C` | 否（高级备用） | 原始预生成的访问令牌。不是推荐路径：它很快过期且无法刷新。 |
您可以运行 `youtube-analytics-pp-cli auth login --client-id <id> --client-secret <secret>` 一次；CLI 将生成的令牌存储在 `config.toml` 中。
## 故障排除
**身份验证错误（退出代码 4）**
- 运行 `youtube-analytics-pp-cli doctor` 检查凭证。
- 验证 OAuth 变量是否设置：`echo $YOUTUBE_CLIENT_ID $YOUTUBE_CLIENT_SECRET` 或运行 `youtube-analytics-pp-cli auth status`。
- 如果您尚未设置凭证，请运行 `youtube-analytics-pp-cli auth login --client-id <id> --client-secret <secret>`。
**未找到错误（退出代码 3）**
- 检查资源 ID 是否正确。
- 运行 `list` 命令查看可用项目。
### API 特定
- **收入指标返回 403 权限不足。** 重新颁发刷新令牌，范围为 `yt-analytics-monetary.readonly`，而不仅仅是 `yt-analytics.readonly`。
- **过去 2-3 天显示为零或缺失。** 这是预期的。YouTube 在 2-3 天的延迟后最终确定数据，因此像 `--last 7d` 这样的日期预设已经将窗口结束于 3 天前。传递 `--include-partial` 以覆盖它。
- **HTTP 400 出现未知指标或维度错误。** 该指标和维度组合不是有效的报告。使用命名预设，或检查指标是否允许使用该维度。
- **401 对每个调用的授权。** 刷新令牌已过期或被撤销。在 Google Cloud 控制台中生成一个新的令牌并更新 `YOUTUBE_REFRESH_TOKEN`。
---
## 更改日志
### 2026-05-21 - OAuth 令牌端点修复
初始 OAuth 实现中的两个错误导致身份验证失败。
首先，令牌交换端点设置为 `accounts.google.com/o/oauth2/token`，而 Google 已将其关闭以支持 `oauth2.googleapis.com/token`。任何尝试将授权代码兑换为令牌的操作都会从已关闭的端点返回错误。
其次，授权 URL 缺少 `access_type=offline` 和 `prompt=consent` 查询参数。没有 `access_type=offline`，Google 不会发出刷新令牌，因此 CLI 只能在短寿命访问令牌过期（约一小时）时进行 API 调用，而没有续期方法。没有 `prompt=consent`，以前已授予访问的用户不会看到后续登录的同意屏幕，也不会收到新的刷新令牌。
这两个问题已在 `internal/cli/auth.go`（授权 URL 参数和初始令牌交换端点）和 `internal/client/client.go`（令牌刷新端点用于访问令牌过期时）以及 `internal/config/config.go`（配置文件的 `token_url` 字段）中修复。
