cawplan-metrics

CawPlan Metrics

Bootstrap

cawplan skill check

入口路由

输入	流程
要查询或绘制图表的业务指标趋势（订阅、CawPlan 工单、QA、工作流、令牌、API 使用量等）	A — 指标查询
记录／记录日志形式写入业务指标事件	B — 指标写入

此处没有设备／应用指标流程——过去通过 API key／CLI 提供安装量／崩溃率等数据的公共端点已停用。如果用户询问这类数据，请告知他们无法再通过此技能／CLI 获取，而不是猜测替代方案。

工作流 A — 指标查询

每个域都带有前缀 cawplan_。业务域及其指标名称不设上限（会随时间不断增加），但目前常见的域及指标——更重要的是，每个域中哪些指标目前确实有生产者在写入，哪些虽已定义但仍为空（查询空指标会返回零行，这看起来和“此时间范围内没有数据”完全一样，而不是“此指标尚未接入”——未核实此列表前，请勿猜测）：

• cawplan_ticket：ticket_created、ticket_updated、ticket_status_changed——均已接入。
• cawplan_qa_insight：test_point_created、test_point_updated、report_created、execution——均已接入。
• cawplan_subscription：new、renew（来自 Stripe invoice.paid，通过 billing_reason 区分）以及 cancel（用户主动取消并转为 Free）均已接入；winback、upgrade、downgrade 已定义，但目前没有任何调用方。
• cawplan_api：throttled（每次 429 响应写入一个数据点）已接入；request 已定义，但目前没有任何调用方。
• cawplan_ai_session_usage：usage_reported——已接入，每次上传每日 AI 编码工具使用情况报告时写入一个数据点（tokens/sessions/cost，按工作区范围统计）。这是 AI 编码工具的内部工程成本遥测数据（cawplan-coding-insights 管道），不是面向客户的 token/额度账本——不要与下方的 cawplan_token 混为一谈。
• cawplan_workflow（execution）、cawplan_token（consumed、recharged、refunded、cost）、cawplan_user（signup、active）、cawplan_csm、cawplan_purchase：均已定义，但尚未接入任何生产者——目前查询其中任意指标都会始终返回零行。

如果用户指定的指标明显无法映射到其中一个指标，请先询问，不要猜测 domain/metric 组合。

1. 确定时间范围。必须提供 --start 和 --end（RFC3339）；如果用户给出相对时间范围（如“过去 30 天”“本周”），请在客户端计算起止时间。此端点不支持 time_range 简写。

2. 如果用户想按产品或工作区筛选结果或拆分结果，先将产品名称解析为 ID（cawplan products list --search "<product name>"；匹配规则与其他技能相同：仅接受完全匹配或唯一的简称匹配，如有歧义则询问），然后传入 --tag product:<product_id> / --tag workspace_id:<workspace_id>，或在 --group_by 中包含 product/workspace_id——product 保存产品的 unique_id（与 cawplan products list 返回的值相同，而非显示名称）；workspace_id 是租户归属维度，如果查询应限定在单个工作区而非整个数据库，值得添加。特别是对于 cawplan_ticket 事件，--tag ticket_id:<ticket_id>（动态标签，并非标准维度）可区分同一产品下某个工单的一组突发数据点——如果不按 ticket_id 筛选或分组，影响多个不同工单的祖先状态传播级联，与同一工单被反复写入看起来完全相同。

3. 执行查询：

   cawplan metrics query \
     --domain <domain> [--metric <metric>] \
     --start <iso> --end <iso> \
     --granularity day \
     [--tag <key:value> ...] \
     [--group_by <k1,k2>] \
     [--fields value,count]
   

   默认的 --granularity raw 会返回每个未聚合的存储数据点；也可选择 day/hour/minute，改为按每种标签组合返回每个时间桶一行的汇总结果——用户想查看趋势而非原始事件列表时，请使用分桶粒度。

4. 检查响应中的 data.truncated。如果其值为 true，则结果已被截断——请缩小时间范围或收紧筛选条件（或提高 --limit，但不能超过服务端自身的上限）后再报告总数；不要将截断后的数量作为完整结果呈现。

工作流 B — 指标写入

仅当用户明确要求记录/写入指标事件时才使用此工作流 — 不要用它批量回填或更正历史数据（写入端点会验证批次中的数据，并在遇到第一条错误数据时拒绝整个批次；它不是批量加载工具）。

cawplan metrics ingest --domain <domain> --metric <metric> --value 1 \
  [--dimensions '{"product":"<product_id>"}'] \
  [--tags '{"from_plan":"basic","to_plan":"pro"}']

写入前，先与用户确认 domain/metric 组合以及任何维度/标签 — 已写入的数据点无法撤销（参见 references/CAWPLAN_OPEN_API.md §7）。

输出

工作流 A：

• query 会返回完整的结构化 data.rows — 通常这些数据就够用了。对于用户只想在当前对话中查看的图表（而不是要保存为文件），完全不需要使用 CLI 渲染标志：自行读取 data.rows 并直接绘制/描述图表（或交给 dataviz 技能生成内嵌/交互式可视化）。将 time 映射到 x 轴，按区分系列的标签组合分组，并将请求的字段映射到 y 轴。无需将任何内容写入磁盘。
• 如果用户要的是数字/摘要，而不是图表：直接报告每个分桶/标签组合的总数。
• 如果用户要的是可单独保存/分享的图表文件（而不只是现在查看）：添加 --chart <path>.svg（如果不是 value，还要添加 --chart-field <value|count|cost|credit>），然后提供文件路径。
• 如果该文件需要在此聊天中以内嵌图片的形式实际显示（例如通过 Read 工具，它能解码栅格图片，但会将 SVG 视为纯文本）：在同一次 query 调用中添加 --png <path>.png，然后用 Read 读取该路径以显示图片。它会基于与 --chart 相同方式生成的 SVG 进行栅格化，并使用环境中可用的工具（macOS 上的 qlmanage，其他系统上的 rsvg-convert）— 无需单独的渲染步骤。如果没有可用的栅格化工具，该命令会报错退出，而不会写入损坏的文件。注意：即使 Read 能成功解码 PNG，也不一定会将其显示给用户（在一次 iTerm2-direct 会话中观察到：在同一窗口手动运行 imgcat <path>.png 能正确渲染，但通过 Read 读取同一文件时，图片并未显示在用户屏幕上）。如果用户表示在你用 Read 读取后仍看不到图片，请让他们直接尝试运行 imgcat <path>.png（或其终端支持的其他命令），而不要依赖 Read。
• --preview（通过 iTerm2/Kitty/chafa 显示内嵌图片）适用于在自己的终端中直接运行 cawplan 的人 — 你运行时无法使用：它输出的转义码只有在真实终端模拟器读取原始标准输出时才会渲染为图片，而此聊天中的工具输出会被捕获为文本，因此会显示成乱码般的转义序列文本。不要在此处使用它；请自行读取 data.rows，或改用 --png。
• 始终注明所用的时间范围和粒度，并指出 data.truncated 是否为 true。

工作流 B： 确认写入了什么（domain、metric、字段、维度/标签），并说明此指标存储用于报告，并非记录系统 — 对于具有财务或合规影响的数据（例如 token/credit），权威账本存储在其他位置；此处写入仅用于仪表板。

决策指南

• 对于 Support Ops Google Sheet 导出、CSM 工单计数回填、更正或对账：使用 cawplan-support-metrics。
• 对于综合产品健康概览（反馈 + 严重问题，不包括设备指标；此 CLI 已无法获取设备指标）：使用 cawplan-product-insights。
• 仅查看由 AI 分类的反馈趋势：cawplan analytics get <product_id>。
• 对于日期范围内的活动/进度报告：使用 cawplan-product-report。

参考资料

• references/CAWPLAN_OPEN_API.md