mcpField
P
pp-roam

pp-roam

github.com/mvanhorn生产力2.1k42 次安装今天更新
代码仓库

关于 pp-roam

pp-roam 是使用 roam-pp-cli 脚本化操作 Roam HQ 的技能，适用于需要命令行管道、定时任务或本地优先搜索的团队和 Agent，支持会议记录分析、Webhook 检查及成员核对。

主要功能

  1. 01搜索聊天消息和会议记录
  2. 02提取带引用的决策类内容
  3. 03比较 On-Air 邀请名单与出席情况
  4. 04查看近期 Webhook 投递记录
  5. 05根据名册核对 SCIM 成员
  6. 06将输入流转发到 Roam 群组

适用场景

  1. 01搜索过往会议中的特定主题
  2. 02整理近期决策摘要
  3. 03无需搭建监听器即可排查 Webhook 投递
  4. 04根据 HRIS 名册同步 Roam 成员

MCP 相关

README 提及 api.ro.am/mcp 上的远程 MCP，适用于临时 Agent 对话。该 CLI 面向脚本化管道、定时任务和本地优先搜索。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mvanhorn/printing-press-library --skill pp-roam

安装后在 Claude Code 中输入/pp-roam确认已加载。

详细介绍

Roam — Printing Press CLI

前置条件：安装 CLI

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

  1. 通过 Printing Press 安装程序安装。默认情况下，二进制文件会安装到 macOS/Linux 上的 $HOME/.local/bin，以及 Windows 上的 %LOCALAPPDATA%\Programs\PrintingPress\bin： 
    npx -y @mvanhorn/printing-press-library install roam --cli-only
  2. 验证：roam-pp-cli --version
  3. 确保报告的安装目录位于将调用此技能的 Agent/运行时的 $PATH 中。

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

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

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

何时使用此 CLI

需要通过 shell 或 Agent 编写 Roam HQ 脚本时，可使用 roam-pp-cli：跟踪 webhook 投递、发布部署通知、一次搜索多场会议的转录内容、将 SCIM 成员资格与 HRIS 名册核对，或从上周的录音中提取决策。api.ro.am/mcp 上的远程 MCP 适合临时的 Agent 对话；如果需要流水线、cron 或本地优先搜索，则应选择此 CLI。

独特功能

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

可持续积累的本地状态

  • grep — 一次搜索所有聊天消息和会议转录内容，并支持 --since、--from-user、--in-meeting、--in-group 过滤器。

    当 Agent 需要回想多场会议中讨论过的内容，而又不想反复请求受速率限制的转录 API 时，可使用此功能。

    roam-pp-cli grep "pricing" --since 14d --in-group eng --json --select transcript_id,line

  • decisions — 从已同步的转录内容中找出类似决策的语句（“我们决定”“行动项”“已达成一致”“就按这个方案来”）。

    当 Agent 需要为团队准备周一摘要时，可使用此功能；结果确定且附带引用。

    roam-pp-cli decisions --since 7d --in-group product --agent

  • onair-attendance-drift — 比较 On-Air 活动的受邀嘉宾与实际出席情况；输出受邀但未出席者和未受邀但到场者名单。

    当 Agent 被问到谁未出席或谁未受邀却到场时，可使用此功能。

    roam-pp-cli onair-attendance-drift --event evt_123 --json

  • webhook-tail — 从本地订阅注册表跟踪近期 webhook 投递，并支持 --since 过滤。

    无需启动监听器即可调试 webhook 集成。

    roam-pp-cli webhook-tail --since 1h --json

  • mention-inbox — 在 messages.text 中本地全文搜索 @user 标记，并支持 --since 过滤；采用跟踪输出格式。

    当 Agent 需要查看所有群组中未读的提及，而不想针对每个群组分别请求 API 时，可使用此功能。

    roam-pp-cli mention-inbox --user @me --since 7d --agent
安全变更

  • onair-reaper — 查找 N 天内出席人数为零的周期性 On-Air 活动。--apply 会通过已吸收的取消端点取消这些活动。

    清理已失效的周期性活动时可使用此功能；默认安全。

    roam-pp-cli onair-reaper --stale-days 60 --dry-run

  • scim-diff — 将 CSV/JSON HRIS 名册与 /Users SCIM 列表进行差异比较；输出新增、更新和移除名单。--apply 会执行 SCIM CRUD 操作。

    当 Agent 需要将外部名册与 Roam 成员名单核对，而不想通过管理界面逐项操作时，可使用此功能。

    roam-pp-cli scim-diff --roster hris.csv --apply --dry-run
面向 Agent 的基础设施

  • transcript-fanout — 针对日期范围内的每份转录内容运行同一个问题；每份转录内容输出一行，包含答案和引用。

    当 Agent 需要用一个问题扫描多场会议，而不想对每场会议重复提示时，可使用此功能。

    roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent

  • relay — 将任意标准输入行通过 /chat.post 发送到 Roam 群组，并使用确定性的幂等键和 429 退避机制。

    当 Agent 需要将流（CI、告警、日志）转发到 Roam，而不想编写自定义 webhook 时，可使用此功能。

    tail -F deploys.log | roam-pp-cli relay --to eng-deploys --idempotent-key-prefix deploys
连通性排查

  • doctor token — 针对每个规范系列（HQ、On-Air、Chat、SCIM、Webhooks）探测一个代表性的 GET 请求，并输出此密钥可访问的系列。

    当 Agent 需要在尝试执行命令前确认现有凭据支持哪些 Roam 命令时，可使用此功能。

    roam-pp-cli doctor token

命令参考

addr-info — 管理地址信息

  • roam-pp-cli addr-info — 获取聊天地址的信息。聊天地址是任何可能参与聊天的实体的名称，例如……

app-uninstall — 管理应用卸载

  • roam-pp-cli app-uninstall — 撤销访问令牌并卸载应用。成功响应后，您的访问令牌将不再……

chat-delete — 管理聊天删除

  • roam-pp-cli chat-delete — 删除先前发布的机器人消息。机器人必须拥有要删除的消息（按地址 ID 匹配）。个人……

chat-history — 管理聊天历史记录

  • roam-pp-cli chat-history — 按日期范围（之后／之前）筛选并列出聊天中的消息。结果的排序取决于筛选条件……

chat-list — 管理聊天列表

  • roam-pp-cli chat-list — 列出所有可访问的聊天，包括已添加机器人的所有私信、多方私信和频道……

chat-post — 管理聊天发布

  • roam-pp-cli chat-post — 向聊天发布消息。消息可以是纯 Markdown 文本、丰富的 Block Kit 布局，也可以是……

chat-send-message — 管理聊天消息发送

  • roam-pp-cli chat-send-message — 向指定收件人发送给定消息。目前，我们仅支持发送到单个群组……

chat-typing — 管理聊天输入状态

  • roam-pp-cli chat-typing — 通知其他聊天参与者您正在准备回复。如果他们打开了聊天，就会看到“（机器人……

chat-update — 管理聊天更新

  • roam-pp-cli chat-update — 编辑先前发布的机器人消息。更新后的消息可以包含纯 Markdown 文本或丰富的 [Block……

group-add — 管理群组成员添加

  • roam-pp-cli group-add — 添加一个或多个群组成员和／或管理员。如果满足以下任一条件，应用可以向群组添加成员……

group-archive — 管理群组归档

  • roam-pp-cli group-archive — 按 ID 归档群组。**访问权限：**仅限组织。所需范围： group:write --- OpenAPI 规范：……

group-create — 管理群组创建

  • roam-pp-cli group-create — 创建可用于聊天的群组地址。指定了管理员的群组将以“仅管理员”模式运行……

group-members — 管理群组成员

  • roam-pp-cli group-members — 列出群组成员。满足以下任一条件时，应用可以列出成员：1. 这是一个公开群组……

group-remove — 管理群组成员移除

  • roam-pp-cli group-remove — 移除一个或多个群组成员。满足以下任一条件时，应用可以从群组中移除成员：……

group-rename — 管理群组重命名

  • roam-pp-cli group-rename — 按 ID 重命名群组。应用只能重命名自己担任管理员的群组。**访问权限：**仅限组织……

groups — 管理群组

  • roam-pp-cli groups 02-create — 在您的 Roam 组织中创建新群组。必填字段： displayName（最多 64 个字符）。可选：……
  • roam-pp-cli groups 02-delete — 在 Roam 中归档群组。这是软删除——群组数据会保留，但变为非活动状态……
  • roam-pp-cli groups 02-get — 按 Roam 地址 ID 获取单个群组。响应包含群组的 displayName 和 members 数组……
  • roam-pp-cli groups 02-list — 返回 Roam 组织中的分页群组列表。**分页：**使用 startIndex（从 1 开始）和 count……
  • roam-pp-cli groups 02-patch — 部分更新群组。可使用此命令添加或移除成员，而无需替换整个群组。**支持的……
  • roam-pp-cli groups 02-replace — 完全替换群组属性。整个 members 列表将替换为提供的值。**必填……

groups-list — 管理群组列表

  • roam-pp-cli groups-list — 列出您所在 Roam 中所有公开且未归档的群组。**访问权限：**仅限组织。所需范围：……

item-upload — 管理项目上传

  • roam-pp-cli item-upload — 上传文件，以便将其作为聊天消息附件发送。返回的对象包含一个 item ID，可用于……

lobby-booking-list — 管理大厅预订列表

  • roam-pp-cli lobby-booking-list — 列出特定大厅配置的预订，并按日期范围（之后／之前）筛选。结果的排序……

lobby-list — 管理大厅列表

  • roam-pp-cli lobby-list — 列出账户中的活跃大厅。大厅 URL 的形式为 ro.am/{handle} 或 ro.am/{handle}/{slug}。- ……

magicast-info — 管理 magicast 信息

  • roam-pp-cli magicast-info — 按 ID 获取 magicast。**访问权限：**组织和个人。在个人模式下，仅可访问由……

magicast-list — 管理 magicast 列表

  • roam-pp-cli magicast-list — 列出 Roam 中的所有 magicast，按时间倒序排列。**访问权限：**组织和个人。在……

meeting-list — 管理会议列表

  • roam-pp-cli meeting-list — 列出 home Roam 中的所有会议，并按日期范围（之后／之前）筛选。结果的排序取决于……

meetinglink-create — 管理 meetinglink 创建

  • roam-pp-cli meetinglink-create — 创建会议链接。**访问权限：**组织和个人。在组织模式下，通过电子邮件指定主持人。在……

meetinglink-info — 管理 meetinglink 信息

  • roam-pp-cli meetinglink-info — 获取会议链接。**访问权限：**仅限组织。必需范围： meetinglink:read --- OpenAPI 规范：……

meetinglink-update — 管理 meetinglink 更新

  • roam-pp-cli meetinglink-update — 更新会议链接。**访问权限：**仅限组织。必需范围： meetinglink:write --- OpenAPI 规范：……

messageevent-export — 管理 messageevent 导出

  • roam-pp-cli messageevent-export — 获取每日消息事件导出，其中包含账户中的私信和群聊。对于使用归档功能的客户……

onair-attendance-list — 管理 onair 出席列表

  • roam-pp-cli onair-attendance-list — 返回 On-Air 活动的出席报告，汇总 RSVP 数据以及加入／时长信息。访客……

onair-event-cancel — 管理 onair 活动取消

  • roam-pp-cli onair-event-cancel — 取消 On-Air 活动。此操作无法撤销。**访问权限：**组织和个人。必需范围：……

onair-event-create — 管理 onair 活动创建

  • roam-pp-cli onair-event-create — 创建新的 On-Air 活动。日历主持人必须是组织成员。使用个人访问……

onair-event-info — 管理 onair 活动信息

  • roam-pp-cli onair-event-info — 返回单个 On-Air 活动的详情。**访问权限：**组织和个人。必需范围： onair:read……

onair-event-list — 管理 onair 活动列表

  • roam-pp-cli onair-event-list — 返回组织的分页 On-Air 活动列表。结果按开始时间降序排列……

onair-event-update — 管理 onair 活动更新

  • roam-pp-cli onair-event-update — 更新现有的 On-Air 活动。仅更新请求正文中提供的字段；未提供的字段保持不变……

onair-guest-add — 管理 onair 访客添加

  • roam-pp-cli onair-guest-add — 将一位或多位访客添加到 On-Air 活动。**访问权限：**组织和个人。必需范围： onair:write……

onair-guest-info — 管理 onair 访客信息

  • roam-pp-cli onair-guest-info — 返回单个 On-Air 活动访客的详情。**访问权限：**组织和个人。必需范围：……

onair-guest-list — 管理 onair 访客列表

  • roam-pp-cli onair-guest-list — 返回 On-Air 活动的分页访客列表。可按 RSVP 状态筛选。结果按……

onair-guest-remove — 管理 onair 访客移除

  • roam-pp-cli onair-guest-remove — 从 On-Air 活动中移除访客。**访问权限：**组织和个人。必需范围： onair:write ---…… onair-guest-update — 管理 onair 来宾更新

  • roam-pp-cli onair-guest-update — 更新来宾的 RSVP 状态。**访问权限：**组织和个人。所需范围：onair:write ---...

reaction-add — 管理 reaction 添加

  • roam-pp-cli reaction-add — 为聊天中的消息添加 reaction。**访问权限：**仅限组织。所需范围：chat:send_message 或...

recording-list — 管理录制列表

  • roam-pp-cli recording-list — 列出你所在 Roam 中的所有录制内容，可按日期范围（起始日期／结束日期）筛选。结果的排序取决于...

resource-types — 管理资源类型

  • roam-pp-cli resource-types — 返回 Roam 支持的资源类型列表：User 和 Group。此操作无需身份验证...

schemas — 管理架构

  • roam-pp-cli schemas 03-metadata-get — 根据 URN 标识符返回特定 SCIM 架构的定义。此操作无需身份验证...
  • roam-pp-cli schemas 03-metadata-list — 返回 Roam 支持的所有 SCIM 架构，包括核心 User 和 Group 架构以及 Roam 的自定义角色...

service-provider-config — 管理服务提供方配置

  • roam-pp-cli service-provider-config — 返回 Roam 的 SCIM 功能和支持的特性。使用此端点可了解支持哪些 SCIM 操作...

test — 管理测试

  • roam-pp-cli test — 测试端点

token-info — 管理令牌信息

  • roam-pp-cli token-info — 获取访问令牌的信息，例如 Chat Address。**访问权限：**组织和个人。**无...

transcript-info — 管理转录信息

  • roam-pp-cli transcript-info — 根据 ID 从你所在的 Roam 获取转录内容。适用于已结束和正在进行的会议。对于实时...

transcript-list — 管理转录列表

  • roam-pp-cli transcript-list — 列出你所在 Roam 中的所有转录内容，可按日期范围（起始日期／结束日期）筛选。此端点会返回转录...

transcript-prompt — 管理转录提示词

  • roam-pp-cli transcript-prompt — 针对特定会议转录内容提问，并根据其内容获取 AI 生成的回答。使用...

user-info — 管理用户信息

  • roam-pp-cli user-info — 根据 ID 获取单个用户的详细信息。**访问权限：**仅限组织。所需范围：user:read...

user-list — 管理用户列表

  • roam-pp-cli user-list — 列出账户中的所有用户。用户按加入账户的顺序返回。访问权限：...

user-lookup — 管理用户查找

  • roam-pp-cli user-lookup — 按电子邮件地址查找账户中的用户。**访问权限：**仅限组织。所需范围：user:read 和...

userauditlog-list — 管理用户审计日志列表

  • roam-pp-cli userauditlog-list — 获取账户的用户审计日志条目列表。**访问权限：**仅限组织。所需范围：...

users — 管理用户

  • roam-pp-cli users 01-create — 在你的 Roam 组织中创建新用户。必填字段：userName、name.givenName、...
  • roam-pp-cli users 01-delete — 在 Roam 中归档用户。这是软删除——用户数据会保留，但用户将失去访问权限。...
  • roam-pp-cli users 01-get — 根据 Roam Person ID 获取单个用户。响应包含所有用户属性、active 状态以及...
  • roam-pp-cli users 01-list — 返回你的 Roam 组织中的分页用户列表。**筛选：**支持 SCIM 筛选表达式，例如...
  • roam-pp-cli users 01-patch — 部分更新用户。Roam 支持针对 Users 的 SCIM PATCH，但语义有限。支持的操作： -...
  • roam-pp-cli users 01-replace — 完全替换用户属性。请求正文中必须提供所有必填字段。**Roam 特有的...

webhook-subscribe — 管理 Webhook 订阅

  • roam-pp-cli webhook-subscribe — 为指定事件创建或更新 Webhook 订阅。如果同一事件的订阅已存在且……

webhook-unsubscribe — 管理 Webhook 取消订阅

  • roam-pp-cli webhook-unsubscribe — 按 ID 移除 Webhook 订阅。**访问权限：**仅限组织。所需范围： webhook:write ---...
查找合适的命令

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

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

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

使用示例

每日站会摘要
roam-pp-cli decisions --since 1d --in-group standup --agent --select transcript_id,line,speaker

提取站会群组昨天的决策，并附上引用，以便 Agent 使用。

跨会议问题扫描
roam-pp-cli transcript-fanout --question "did anyone mention Q3 hiring?" --since 30d --agent

针对过去 30 天内的每份转录记录，提出同一个问题。

将 HRIS 名单与 Roam SCIM 对账
roam-pp-cli scim-diff --roster hris.csv --apply --dry-run

应用更改前查看新增、更新和移除项；去掉 --dry-run 即可执行。

将 CI 警报导入 Roam
tail -F /var/log/ci.log | roam-pp-cli relay --to eng-alerts --idempotent-key-prefix ci

将 CI 日志行流式传入 Roam 群组，并进行确定性去重。

精简深层嵌套的转录响应
roam-pp-cli transcript-info --id <id> --json --select segments.speaker,segments.text

使用 --select 和点分路径，在较长的转录记录中减少 Agent 上下文。

身份验证设置

通过 ROAM_API_KEY 使用 Bearer 身份验证。Roam 支持两类密钥：完全访问权限的组织密钥和个人访问令牌。部分 HQ v1 端点需要完全访问权限；Chat/Transcript v0 端点支持 PAT。运行 roam-pp-cli doctor token，查看你的密钥可访问哪些端点类别。

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

Agent 模式

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

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

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

    roam-pp-cli addr-info --agent --select id,name,status

  • 支持预览 — --dry-run 可显示请求，而不实际发送

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

  • 非交互式 — 不会提示输入；所有输入都通过标志提供

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

响应封装

从本地存储或 API 读取的命令会将输出封装在来源信息中：

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

解析 .results 获取数据，并查看 .meta.source 判断数据来自实时来源还是本地来源。只有当 stdout 是终端时，才会将便于阅读的 N results (live) 摘要打印到 stderr；通过管道接收或由 Agent 消费时，stdout 中只有纯 JSON。

Agent 反馈

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

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

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

记录让你感到意外的地方，而不是提交 Bug 报告。简短、具体、一行即可：这些反馈会不断累积，发挥更大作用。

输出传递

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

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

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

命名配置

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

roam-pp-cli profile save briefing --json
roam-pp-cli --profile briefing addr-info
roam-pp-cli profile list --json
roam-pp-cli profile show briefing
roam-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

从此 CLI 发布的公共库条目或预构建版本安装 MCP 二进制文件，然后注册：

claude mcp add roam-pp-mcp -- roam-pp-mcp

验证：claude mcp list

直接使用

  1. 检查是否已安装：which roam-pp-cli 如果未找到，提供安装选项（参见本技能开头的先决条件）。
  2. 将用户查询与上文“独特功能”和“命令参考”中的最佳命令匹配。
  3. 使用 --agent 标志执行： 
    roam-pp-cli <command> [subcommand] [args] --agent
  4. 如果存在歧义，深入查看子命令帮助：roam-pp-cli <command> --help。

评论

支持 Markdown