pp-google-photos

Google Photos — Printing Press CLI

前提条件：安装 CLI

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

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

   npx -y @mvanhorn/printing-press-library install google-photos --cli-only
   

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

如果 npx 安装失败（例如没有 Node、处于离线状态等），请改用 Go 直接安装（要求 Go 1.26.6 或更高版本）：

go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-cli@latest

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

命令参考

albums — 管理由应用创建的 Google Photos 相册。

• google-photos-pp-cli albums add-enrichment — 为由应用创建的相册添加文本、位置信息或地图内容。
• google-photos-pp-cli albums batch-add-media-items — 将由应用创建的媒体项添加到由应用创建的相册。
• google-photos-pp-cli albums batch-remove-media-items — 从由应用创建的相册中移除由应用创建的媒体项。
• google-photos-pp-cli albums create — 在用户的 Google Photos 资料库中创建相册。
• google-photos-pp-cli albums get — 按 ID 获取由应用创建的相册。
• google-photos-pp-cli albums list — 列出由此应用创建的相册。
• google-photos-pp-cli albums patch — 更新由应用创建的相册标题或封面照片。

media-items — 管理由应用创建的 Google Photos 媒体项。

• google-photos-pp-cli media-items batch-create — 根据上传令牌创建媒体项。
• google-photos-pp-cli media-items batch-get — 按 ID 获取多个由应用创建的媒体项。
• google-photos-pp-cli media-items get — 按 ID 获取由应用创建的媒体项。
• google-photos-pp-cli media-items list — 列出由此应用创建的媒体项。
• google-photos-pp-cli media-items patch — 更新由应用创建的媒体项的说明。
• google-photos-pp-cli media-items search — 按相册或筛选条件搜索由应用创建的媒体项。

picker — 创建、轮询、清理并读取 Google Photos Picker 会话。

• google-photos-pp-cli picker create-session — 创建 Picker 会话并返回 Picker URI。
• google-photos-pp-cli picker delete-session — 在所选媒体的字节数据已取回后，删除 Picker 会话。
• google-photos-pp-cli picker get-session — 获取 Picker 会话状态。
• google-photos-pp-cli picker list-media-items — 列出用户在 Picker 会话中选取的媒体项。

手写命令

• google-photos-pp-cli upload file <path> — 上传原始照片或视频字节数据，并输出供 media-items batch-create 使用的上传令牌。
• google-photos-pp-cli picker wait <session-id> — 轮询 Picker 会话，直到所选媒体项准备就绪。
• google-photos-pp-cli schema --pretty — 输出机器可读的命令、标志、身份验证和安全策略元数据。
• google-photos-pp-cli auth list — 列出已存储的 OAuth 账号。
• google-photos-pp-cli auth use <account-email> — 设置默认 OAuth 账号。
• google-photos-pp-cli auth remove <account-email> — 移除已存储的 OAuth 账号。

Google Photos 范围限制

Google Photos Library API 的读取和编辑范围仅限于由应用创建的相册和媒体。对于由应用创建的内容、上传内容以及相册/媒体管理，请使用此处的 Library API 命令。如果用户需要从其更广泛的 Google Photos 资料库中选择媒体，请使用 Picker 命令。

查找合适的命令

知道想做什么，但不知道该用哪个命令时，可以直接询问 CLI：

google-photos-pp-cli which "<capability in your own words>"

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中找出最匹配的命令。退出码 0 表示至少找到一个匹配项；退出码 2 表示没有可信的匹配项，此时可改用 --help 或缩小查询范围。

身份验证设置

通过浏览器进行身份验证：

google-photos-pp-cli auth login --client-id "$GOOGLE_PHOTOS_CLIENT_ID"

令牌会存储在本地，并自动刷新。

如果有多个 Google 账号，可以将令牌按账号邮箱分别存储，并显式选择账号：

google-photos-pp-cli auth login [email protected] --client-id "$GOOGLE_PHOTOS_CLIENT_ID"
google-photos-pp-cli auth list --json
google-photos-pp-cli auth use [email protected]
google-photos-pp-cli --account [email protected] albums list --agent

账号选择顺序：--account、GOOGLE_PHOTOS_ACCOUNT、auth use 默认值，然后是旧版单令牌配置。

运行 google-photos-pp-cli doctor 验证设置。

Agent 模式

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

• 可通过管道传递 — JSON 输出到 stdout，错误输出到 stderr

• 可筛选 — --select 保留一部分字段。点分路径可深入嵌套结构；数组会逐元素遍历。对于冗长 API，缩小上下文至关重要：

  google-photos-pp-cli albums list --agent --select id,name,status
  

• 可预览 — --dry-run 显示请求，但不发送

• 适合离线使用 — 如果本地 SQLite 存储可用，同步/搜索命令可以使用它

• 非交互式 — 从不发出提示，所有输入都通过标志传入

• 带防护措施 — 使用带点分隔的命令路径配合 --enable-commands / --disable-commands：

  google-photos-pp-cli --enable-commands albums.list albums list --agent
  google-photos-pp-cli --disable-commands picker.delete-session picker delete-session SESSION_ID --agent
  

• 可内省 — 使用 schema --pretty 或 agent-context --pretty 查看完整的 JSON 命令约定。

内置安全配置

向自主 Agent 开放此 CLI 或 MCP 服务时，可构建更严格的本地防护措施：

make build-readonly
make build-agent-safe
make build-mcp-readonly
make build-mcp-agent-safe

safety_readonly 允许读取/列出/搜索/导出/查询架构类命令，并阻止对 Google Photos 的修改操作。safety_agent_safe 允许读取和本地归档/搜索工作流，同时阻止身份验证写入、上传、创建、修补、删除，以及相册/媒体修改操作。

响应封装

从本地存储或 API 读取数据的命令会将输出封装在一个溯源信封中：

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

解析 .results 获取数据，并查看 .meta.source 以确定数据来自实时来源还是本地来源。只有当 stdout 连接到终端时，才会将人类可读的 N results (live) 摘要输出到 stderr；通过管道传递或由 Agent 消费时，stdout 仅包含纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有不妥之处时，请记录下来：

google-photos-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
google-photos-pp-cli feedback --stdin < notes.txt
google-photos-pp-cli feedback list --json --limit 10

条目会存储在本地的 ~/.google-photos-pp-cli/feedback.jsonl。只有在设置了 GOOGLE_PHOTOS_FEEDBACK_ENDPOINT，并且传入了 --send 或 GOOGLE_PHOTOS_FEEDBACK_AUTO_SEND=true 时，才会 POST 这些条目。默认行为仅在本地存储。

记录让你感到意外的地方，而不是提交错误报告。简短、具体、一行即可：这些细节会不断累积。

输出传递

每个命令都接受 --deliver <sink>。输出会发送到指定的接收端，也会发送到 stdout，或取代 stdout；因此，Agent 可以路由命令结果，无需手动通过管道传递。支持三种接收端：

接收端	效果
stdout	默认值；仅写入 stdout
file:<path>	将输出原子性地写入 <path>（临时文件 + 重命名）
webhook:<url>	将输出正文 POST 到该 URL（使用 application/json，或在传入 --compact 时使用 application/x-ndjson）

遇到未知方案时会拒绝执行，并返回结构化错误，列出支持的方案。Webhook 失败时会返回非零状态，并将 URL 和 HTTP 状态记录到 stderr。

命名配置

配置是保存的一组标志值，可在多次调用中重复使用。如果计划任务中的 Agent 每次运行都以相同配置调用同一命令，可使用配置——这就是 HeyGen 的“Beacon”模式。

google-photos-pp-cli profile save briefing --json
google-photos-pp-cli --profile briefing albums list
google-photos-pp-cli profile list --json
google-photos-pp-cli profile show briefing
google-photos-pp-cli profile delete briefing --yes

显式标志始终优先于配置值；配置值优先于默认值。agent-context 会在 available_profiles 下列出所有可用配置，以便进行内省的 Agent 在运行时发现这些配置。

退出代码

代码	含义
0	成功
2	用法错误（参数错误）
3	未找到资源
4	需要身份验证
5	API 错误（上游问题）
7	请求频率受限（等待后重试）
10	配置错误

参数解析

解析 $ARGUMENTS：

1. 为空、help 或 --help → 显示 google-photos-pp-cli --help 输出
2. 以 install 开头 → 以 mcp 结尾 → 安装 MCP；否则 → 参见上文的先决条件
3. 其他任何内容 → 直接使用（作为带有 --agent 的 CLI 命令执行）

安装 MCP 服务

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/google-photos/cmd/google-photos-pp-mcp@latest
   

2. 注册到 Claude Code：

   claude mcp add google-photos-pp-mcp -- google-photos-pp-mcp
   

3. 验证：claude mcp list

直接使用

1. 检查是否已安装：which google-photos-pp-cli 如果未找到，则提供安装选项（参见此技能顶部的先决条件）。
2. 根据用户查询，从上方的独特功能和命令参考中选择最合适的命令。
3. 使用 --agent 标志执行：

   google-photos-pp-cli <command> [subcommand] [args] --agent
   

4. 如果不明确，请查看子命令帮助：google-photos-pp-cli <command> --help。