pp-notion

Notion — Printing Press CLI

前提条件：安装 CLI

此 Skill 由 notion-pp-cli 二进制文件驱动。**在调用此 Skill 中的任何命令之前，必须确认 CLI 已安装。**如果尚未安装，请先安装：

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

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

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

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

go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-cli@latest

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

何时使用此 CLI

需要从终端管理 Notion 页面和块、检测过时页面，或跟踪自某个时间以来的变更时，请使用 notion-pp-cli。运行一次 sync 以填充本地存储，然后即可离线运行 stale 和 changed。它不能替代日常编辑所用的 Notion 网页版界面。

独特功能

其他任何用于此 API 的工具都不具备以下功能。

面向 Agent 的底层能力

• changed — 显示工作区中自上次同步或指定时间戳以来新增、编辑或删除的所有内容。

  在 Agent 会话开始时使用，以了解有哪些变更，再采取行动。

  notion-pp-cli changed --since 2h --json
  

持续积累的本地状态

• stale — 列出 N 天内未编辑的页面和记录，可按数据库、父级或标签筛选。

  用于在清理工作区前找出废弃页面，或标记逾期未审核的交付成果。

  notion-pp-cli stale --days 30 --db ProjectDB --agent
  

命令参考

blocks — 块端点

• notion-pp-cli blocks delete — 删除块
• notion-pp-cli blocks query-meeting-notes — 查询会议记录
• notion-pp-cli blocks get — 按 ID 获取块
• notion-pp-cli blocks update — 更新块
• notion-pp-cli blocks children list — 列出块或页面的子项
• notion-pp-cli blocks children append — 向页面或块追加块

comments — 评论端点

• notion-pp-cli comments create-a — 创建评论
• notion-pp-cli comments delete-a — 删除评论
• notion-pp-cli comments list — 列出评论
• notion-pp-cli comments retrieve — 获取评论
• notion-pp-cli comments update-a — 更新评论

custom-emojis — 自定义表情符号端点

• notion-pp-cli custom-emojis — 列出自定义表情符号

data-sources — 数据源端点

• notion-pp-cli data-sources create-a-database — 创建数据源
• notion-pp-cli data-sources retrieve-a — 获取数据源
• notion-pp-cli data-sources update-a — 更新数据源
• notion-pp-cli data-sources query post-database <data_source_id> — 查询数据源。注意：叶子命令是 post-database，而不是单独的 query——data-sources query 是一个中间分组，会显示帮助信息。这与 databases query <id> 不同，后者会直接执行。

databases — 数据库端点

• notion-pp-cli databases query <database_id> — 查询数据库中的记录，可选筛选和排序
• notion-pp-cli databases create — 创建数据库
• notion-pp-cli databases retrieve — 获取数据库
• notion-pp-cli databases update — 更新数据库

file-uploads — 文件上传端点

• notion-pp-cli file-uploads create-file — 创建文件上传
• notion-pp-cli file-uploads list — 列出文件上传
• notion-pp-cli file-uploads retrieve — 获取文件上传

notion-search — 管理 Notion 搜索

• notion-pp-cli notion-search — 按标题搜索

oauth — OAuth 端点（基本身份验证）

• notion-pp-cli oauth create-a-token — 使用授权码换取访问令牌和刷新令牌
• notion-pp-cli oauth introspect-token — 检查令牌
• notion-pp-cli oauth revoke-token — 撤销令牌

pages — 页面端点

• notion-pp-cli pages update — 更新页面
• notion-pp-cli pages create — 创建页面
• notion-pp-cli pages get — 按 ID 获取页面
• notion-pp-cli pages move — 移动页面
• notion-pp-cli pages markdown export — 将页面导出为 Markdown

users — 用户端点

• notion-pp-cli users get — 列出所有用户
• notion-pp-cli users get-self — 获取令牌对应的机器人用户
• notion-pp-cli users get-userid — 获取用户

views — 视图端点

• notion-pp-cli views create — 创建视图
• notion-pp-cli views delete — 删除视图
• notion-pp-cli views list — 列出视图
• notion-pp-cli views retrieve-a — 获取视图
• notion-pp-cli views update-a — 更新视图

sync pages — 将所有页面和数据库同步到本地 SQLite

• notion-pp-cli sync pages — 通过搜索 API 同步所有页面和数据库（在 stale/changed 之前运行）
• notion-pp-cli sync pages --full — 从头开始完全重新同步
• notion-pp-cli sync pages --type database — 仅同步数据库

查找合适的命令

当你知道要做什么，但不确定该用哪个命令时，可以直接询问 CLI：

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

which 会根据自然语言能力查询，从此 CLI 精选的功能索引中匹配最合适的命令。退出代码 0 表示至少找到一个匹配项；退出代码 2 表示没有可信的匹配项——请改用 --help 或使用更具体的查询。

操作示例

晨间检查：昨夜有哪些变更

notion-pp-cli changed --since 8h --json

显示过去 8 小时内编辑的所有内容——可在会话开始时使用，以便在采取行动前了解情况。

清理前查找过时页面

notion-pp-cli stale --days 30 --json --select id,title,days_since_edit,last_edited_time

列出超过 30 天未更新的页面，并按时间从旧到新排序。Notion UI 无法跨多个工作区使用同等筛选条件。

将页面导出为 Markdown

notion-pp-cli pages markdown export <page-id>

通过 Notion 原生 Markdown 端点获取页面内容，无需转换。

读取页面的块子项

notion-pp-cli blocks children list <page-id> --json --select id,type

列出页面上的所有顶层块及其类型和 ID。

身份验证设置

需要 Notion Internal Integration 令牌。在 notion.so/my-integrations 创建令牌，将顶层页面共享给该集成，然后在环境中设置 NOTION_BEARER_AUTH（或 NOTION_TOKEN）。

首次运行设置：

notion-pp-cli doctor          # verify auth
notion-pp-cli sync pages      # sync all pages + databases (~15k pages, takes 2-3 min)
notion-pp-cli stale --days 30 # now works
notion-pp-cli changed --since 24h

运行 notion-pp-cli doctor 验证设置。

Agent 模式

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

• 支持管道传输 — JSON 输出到 stdout，错误输出到 stderr

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

  notion-pp-cli comments list --block-id 550e8400-e29b-41d4-a716-446655440000 --agent --select id,name,status
  

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

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

• 非交互式 — 从不提示输入，所有输入均通过标志提供

• 显式重试 — 仅当已存在的创建结果应视为成功时使用 --idempotent；仅当缺失的删除目标应视为成功时使用 --ignore-missing

响应封套

从本地存储或 API 读取数据的命令会将输出包装在来源封套中：

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

从 .results 读取数据，并通过 .meta.source 判断数据来自实时 API 还是本地存储。只有当 stdout 是终端时，才会将易读的 N results (live) 摘要输出到 stderr；通过管道传输或由 Agent 消费时，stdout 仅包含纯 JSON。

Agent 反馈

当你（或 Agent）发现此 CLI 有问题时，请记录下来：

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

条目会保存在本地 ~/.notion-pp-cli/feedback.jsonl。只有设置了 NOTION_FEEDBACK_ENDPOINT，并且传入 --send 或设置了 NOTION_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认情况下仅保存在本地。

记录让你感到意外的地方，而不是提交 bug 报告。简短、具体、每行一条：这部分会不断积累价值。

输出传递

每个命令都接受 --deliver <sink>。输出会发送到指定目标，同时输出到 stdout，或取代 stdout 输出；这样 Agent 无需手动通过管道传输，就能路由命令结果。支持三种目标：

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

遇到未知方案时会拒绝处理，并返回结构化错误，指出支持的方案。Webhook 请求失败时会返回非零状态码，并在 stderr 中记录 URL 和 HTTP 状态码。

命名配置

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

notion-pp-cli profile save briefing --json
notion-pp-cli --profile briefing comments list --block-id 550e8400-e29b-41d4-a716-446655440000
notion-pp-cli profile list --json
notion-pp-cli profile show briefing
notion-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

   go install github.com/mvanhorn/printing-press-library/library/productivity/notion/cmd/notion-pp-mcp@latest
   

2. 在 Claude Code 中注册：

   claude mcp add notion-pp-mcp -- notion-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

   notion-pp-cli <command> [subcommand] [args] --agent
   

4. 如果有歧义，请进一步查看子命令帮助。需要机器可读的命令/标志说明时，使用 notion-pp-cli <command> --help --agent；纯 --help 输出仍面向人类阅读。