pp-clarity

PP Clarity — Printing Press CLI

前置条件：安装 CLI

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

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

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

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

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

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

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

何时使用此 CLI

当你需要添加、检查或说明 Microsoft Clarity 浏览器埋点时，请使用此 CLI。它最适合生成代码片段和审查本地 HTML；它不能替代 Clarity 控制面板。

何时不使用此 CLI

对于需要创建、更新、删除、发布、评论、点赞、邀请、订购、发送消息、预订、购买或更改远程状态的请求，请勿启用此 CLI。此打印版 CLI 仅提供用于检查、导出、同步和分析的只读命令。

独特功能

这些功能在此 API 的其他任何工具中都不可用。

埋点编写

• snippet install — 为项目 ID 生成完整的 Clarity 跟踪代码片段，并为每个有文档说明的客户端 API 调用生成专用代码片段。

  在网站中添加 Clarity，或将可直接用于实现的代码交给其他 Agent 时使用。

  clarity-pp-cli snippet install abc123 --format html
  

埋点审查

• audit html — 检查 HTML 文件中的 Clarity 标签脚本、屏蔽属性以及常见的 window.clarity 客户端 API 调用。

  在发布应包含 Clarity 埋点的页面变更前使用。

  clarity-pp-cli audit html ./index.html --json --select found_project_id,calls
  

命令参考

tag — 检查 Microsoft Clarity 跟踪标签脚本

• clarity-pp-cli tag <project_id> — 获取项目 ID 对应的 Clarity 跟踪标签脚本

手动编写的命令

• clarity-pp-cli snippet install — 为 Clarity 项目 ID 生成跟踪代码片段
• clarity-pp-cli snippet consent — 生成 Cookie 同意客户端 API 调用
• clarity-pp-cli snippet identify — 生成自定义标识符客户端 API 调用
• clarity-pp-cli snippet set — 生成自定义标签客户端 API 调用
• clarity-pp-cli snippet event — 生成自定义事件客户端 API 调用
• clarity-pp-cli snippet upgrade — 生成会话优先级客户端 API 调用
• clarity-pp-cli snippet mask — 生成 Clarity 屏蔽或取消屏蔽 HTML 属性
• clarity-pp-cli audit html — 检查 HTML 文件中的 Clarity 安装代码片段和客户端 API 调用
• clarity-pp-cli insights live — 获取 Microsoft Clarity Data Export API 实时洞察

查找合适的命令

当你知道要做什么，但不确定哪个命令可以实现时，可以直接向 CLI 提问：

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

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

示例

安装 Clarity

clarity-pp-cli snippet install abc123 --format html

生成应放在页面 head 中的跟踪代码片段。

添加自定义事件

clarity-pp-cli snippet event newsletterSignup

生成记录指定用户操作的有文档说明的事件调用。

仅审查高重力字段

clarity-pp-cli audit html ./index.html --json --select found_project_id,calls,mask_count,unmask_count

缩小审查输出范围，便于 Agent 使用。

身份验证设置

客户端侧代码片段命令只需要公开的 Clarity 项目 ID。

若要读取 Data Export API，请在环境中设置令牌。请勿将令牌值粘贴到聊天中或提交到文件：

export PP_CLARITY_API_TOKEN="..."
clarity-pp-cli insights live --days 1 --dimension OS --json

进行本地 Agent 测试时，建议使用本地令牌文件：

mkdir -p ~/.config/clarity-pp-cli
printf '%s' 'YOUR_TOKEN_HERE' > ~/.config/clarity-pp-cli/api-token
chmod 600 ~/.config/clarity-pp-cli/api-token

该命令还接受 MICROSOFT_CLARITY_API_TOKEN、CLARITY_API_TOKEN 或 PP_CLARITY_API_TOKEN_FILE。

运行 clarity-pp-cli doctor 以验证设置。

Agent 模式

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

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

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

  clarity-pp-cli tag mock-value --agent --select id,name,status
  

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

• 适合离线使用 — 有本地 SQLite 存储时，同步／搜索命令可以使用该存储

• 非交互式 — 从不提示；每项输入都通过标志传入

• 只读 — 请勿使用此 CLI 执行创建、更新、删除、发布、评论、点赞、邀请、下单、发送或其他会修改数据的请求

响应封装

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

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

解析 .results 获取数据，并查看 .meta.source 以判断数据来自实时来源还是本地来源。只有当 stdout 是终端时，才会向 stderr 输出可读的 N results (live) 摘要；通过管道接收数据的用户或 Agent 会在 stdout 上获得纯 JSON。

Agent 反馈

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

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

条目会保存在本地的 ~/.clarity-pp-cli/feedback.jsonl。只有在设置了 CLARITY_CLIENT_FEEDBACK_ENDPOINT 且传入 --send 或 CLARITY_CLIENT_FEEDBACK_AUTO_SEND=true 时，条目才会通过 POST 发送。默认行为仅在本地保存。

记录让你感到意外的地方，而不是提交 Bug 报告。简短、具体、单行描述：这部分会不断积累。

输出传递

每条命令都接受 --deliver <sink>。除了（或代替）stdout，输出还会发送到指定的接收端，这样 Agent 无需手动通过管道传递就能路由命令结果。支持三种接收端：

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

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

命名配置

配置文件是一组已保存的标志值，可在多次调用中重复使用。当定时运行的 Agent 每次都以相同配置调用同一命令时，可使用此功能——即 HeyGen 的“Beacon”模式。

clarity-pp-cli profile save briefing --json
clarity-pp-cli --profile briefing tag mock-value
clarity-pp-cli profile list --json
clarity-pp-cli profile show briefing
clarity-pp-cli profile delete briefing --yes

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

退出代码

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

参数解析

解析 $ARGUMENTS：

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

MCP 服务安装

1. 安装 MCP 服务：

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

2. 在 Claude Code 中注册：

   claude mcp add clarity-pp-mcp -- clarity-pp-mcp
   

3. 验证：claude mcp list

直接使用

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

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

4. 如果存在歧义，请查看子命令帮助：clarity-pp-cli <command> --help。