ray-metrics

name	ray-metrics
description	X(Twitter)账号数据周报:通过 xapi 拉近 7 天(可选 30 天对比)推文与指标,算周环比、挑出 top/bottom 推,把表现归因到声部/话题/hook 形式/发布时段这些可复现的规律,再给下周 2-3 条可执行的内容动作(加什么、停什么、测什么)。当用户要做 X/Twitter 数据周报或内容复盘、想知道哪条推表现好以及为什么、要基于数据(而不是拍脑袋)定下周内容方向、或说「看看我这周推文数据」「帮我复盘账号」时使用。触发:/ray-metrics 或 /ray-metrics 「@handle 或 时间范围」。xapi 拉不到数据时必须诚实报告并给替代路径(X Analytics 导出 csv / 浏览器读 analytics 页),绝不编造数据充数。不用于:生成或撰写推文(用 ray-tweet)、拆解别人账号做对标(用 ray-benchmark)。

ray-metrics:X 账号数据周报

拉推文表现数据,算增长,找规律,给下周可执行方向。数据驱动,不拍脑袋。

把个人 X 账号的内容复盘从「发了就发了、凭感觉猜哪条火」升级到「每周拉数据、找出可复现的规律、用规律定下周方向」。这个 skill 的价值不在漂亮的数字表,而在从数字里读出下一步该干什么。

用法

/ray-metrics                    # 默认:本账号近 7 天周报
/ray-metrics @youraccount       # 指定 handle
/ray-metrics @youraccount 30d   # 近 30 天,含周环比对比
/ray-metrics 6/28-7/4           # 指定时间窗

没给 handle 就用默认账号(问用户,或读上次记录)。时间窗默认「近 7 天 vs 上一个 7 天」以便算周环比。

铁律:数据要么是真的,要么明说没有

这条排在最前,因为它是这个 skill 唯一不能违背的。xapi 不稳定(常见 transport error / 超时 / 空返回)。任何一步拉数失败,都不许用估计值、往期印象、或"合理推测"填坑冒充真实数据。 拉不到就走 Step 1b 的 fallback,把缺口如实标在报告里。一份诚实的"半张表 + 缺口说明",比一份编圆了的"完整周报"值钱一百倍——后者会让你基于假数据定错方向。

Step 1:拉数据

1a. 正常路径(xapi 可达)

先拿 user id 和账号级指标:

mcp__xapi__get_users_by_username(
  username="youraccount",
  user.fields="public_metrics,created_at,description"
)
→ 拿到 id、followers_count、following_count、tweet_count

用 id 拉时间窗内的推文(含每条的 public_metrics):

mcp__xapi__get_users_posts(
  id="<上一步的 id>",
  max_results=100,                         # 单页上限 100,不够就翻 pagination_token
  start_time="2026-06-28T00:00:00Z",       # 近 14 天,ISO 8601 UTC,覆盖本周+上周
  end_time="2026-07-12T00:00:00Z",
  exclude="retweets",                      # 默认排除转推;是否含 replies 见下
  post.fields="created_at,public_metrics,text,referenced_tweets"
)

要点:

• 拉 14 天(本周 + 上周),按 created_at 切成两段算周环比。
• exclude="retweets":转推不是自己的产出。回复(replies)默认保留但单独归类——纯回复的传播逻辑和原创推不同,混在一起算均值会污染归因。
• 单账号推文时间线最多回溯约 3200 条;近期窗口够用。
• 每条 public_metrics 含 impression_count / like_count / retweet_count / reply_count / quote_count / bookmark_count。注意 impression_count 只在自己账号的推文上可得,且有时间窗限制——口径细节见 references/metrics-glossary.md。
• 用 search_posts_all(query="from:youraccount") 可作交叉校验或补历史,但全archive检索对权限敏感,失败很正常,别把它当主路径。

1b. Fallback(xapi 不可达)

只要上面任一调用报错、超时、或返回明显不完整,停下来,不要假装拉到了。如实告诉用户,并给替代路径:

1. 让用户导 CSV(首选):X → Premium/Analytics → 按时间范围导出 tweet-level CSV,把文件路径给你。CSV 的列名到指标的映射见 references/metrics-glossary.md,拿到就能照常跑 Step 2-4。
2. 浏览器读:若装了浏览器 MCP,可打开 x.com/i/account_analytics 的 Content 页,按时间窗读表格数(适合少量推、无法导出时)。
3. 降级交付:用户手头有几条关键推的截图/数字也行——明确标注"数据来源=用户手工提供",样本少时按 Step 3 的最小样本规则处理。

无论走哪条 fallback,报告开头都要写清实际数据来源,不含糊。

Step 2:算——增长与分布

有了原始推文数组,算这几样(计算口径、互动率公式、impression 定义统一见 references/metrics-glossary.md,执行到这步或遇到字段缺失时读):

• 账号级周环比:本周 vs 上周的 净增粉、总曝光、总互动、发推条数。给绝对值 + 百分比。
• 单推互动率:每条 (like+RT+reply+quote+bookmark) / impression。互动率比绝对点赞数更能跨"大小推"比较——一条 500 曝光 50 赞的,可能比一条 5万曝光 200 赞的更该复制。
• Top 3 / Bottom 3:分别按 曝光 和 互动率 各排一次(两个榜单常常不一样,差异本身就是线索)。
• 分布感:本周是"一条爆款拉高全部" 还是 "整体均匀抬升"?中位数 vs 均值差多少?这决定归因该看单点还是看面。

Step 3:归因——找可复现的规律,不是给单条偶然编故事

这是全 skill 最容易翻车的一步。目标是找下周能照着复制的规律,不是为已经发生的爆款事后编一个动听的解释。

把本周(必要时并上近 30 天)的推按这几个维度分桶,看哪个桶的中位互动率明显高:

维度	分桶举例	看什么
声部	干货/观点/build-in-public/互动闲聊	哪种声部的中位互动率高、哪种在稀释
话题	AI Agent / 出海 / 基建 / 元反思…	哪个话题带量,哪个自嗨
Hook 形式	数字开头/反常识断言/提问/晒结果/清单体	哪种开头留得住人
发布时段	按 created_at 分早/午/晚 × 工作日/周末	有没有稳定的高峰时段
形态	单推/长推/带图/带链接/thread 首推	带图涨不涨,挂链接掉不掉

最小样本纪律(硬要求):一个桶里少于 2-3 条,不足以称之为"规律"——那是噪声。样本不够时,诚实说"本周数据量不支持在 X 维度上归因",给出要采多少数据才够(比如"再跑两周、或每个声部各发够 3 条"),而不是硬从 2 条推里拗出一条像模像样的规律。宁可只报一条"本周唯一显著离群是这条,原因待验证",也不假装看穿了一切。

一个爆款要成为"规律",至少满足其一:① 同类型在过去也重复过;② 有清晰的机制解释且可预先证伪。只出现一次、没机制的,标为"待验证",列进下周要测的假设,别写进结论。

Step 4:下周建议——2-3 条可执行动作

归因落到动作。每条建议是一个可执行、可验收的动作,不是"多发优质内容"这种正确的废话。用「增 / 停 / 测」三类:

• 增:把验证过的规律加码。例:"build-in-public 声部中位互动率是账号均值 2.1 倍,下周从 1 条加到 3 条。"
• 停:把持续拉低的停掉或改造。例:"纯转发带一句评论的 4 条互动率全部垫底,下周停,想转就改写成自己的观点推。"
• 测:把"待验证"假设设计成可证伪实验。例:"疑似晚 9-11 点是高峰,下周固定这个时段发 3 条同类型推,与其他时段对比验证。"

边界——不代笔:建议给到「方向 + 形式 + 该测的假设」这一层,这属于分析产出,可完整交付。但别在这里替作者写具体推文文案——那是 ray-tweet 的活,且涉及作者的对外声音。若建议里需要示范一条推,只给结构骨架和留空:【你的话:____】,血肉留给作者。

Step 5:输出——结构化周报

# X 数据周报 · @<handle>
数据来源:<xapi 实时 / 用户导出CSV / 手工提供>  |  抓取时间窗:<本周 6/28–7/4> vs <上周 6/21–6/27>  |  生成于:<时间>

## 一、账号大盘(周环比)
| 指标 | 本周 | 上周 | 环比 |
|---|---|---|---|
| 净增粉 | … | … | +X% |
| 总曝光 | … | … | … |
| 总互动 | … | … | … |
| 发推数 | … | … | … |
| 均互动率 | … | … | … |

## 二、Top / Bottom
- 🔥 Top(按互动率):<推文摘要> — 曝光X / 互动率Y% — 为什么好:<归因>
- 🧊 Bottom:<推文摘要> — 为什么差:<归因>
（曝光榜与互动率榜不一致时,两个都列并点出差异)

## 三、规律(可复现的才写这里)
- <维度>:<哪个桶显著高/低,附样本数> → <可复制的规律>
- 待验证假设:<只出现一次、机制未证的,列这里,进下周去测>

## 四、下周行动(增/停/测)
1. 增:…(可验收标准:…)
2. 停:…
3. 测:…（怎么算测成功:…）

## 五、数据说明
- 口径:互动率 = (赞+转+评+引+收藏)/曝光;<impression 可得性/缺失字段说明>
- 缺口:<哪些数没拉到、为什么、如何补>

纪律清单

• 真源优先:数拉不到就走 fallback 并标注来源,永不编数。报告里的每个数字都要能追到抓取源。
• 口径写清:注明时间窗、是否含 replies、impression 定义。口径不一致,周环比就是假的。
• 规律须过样本门槛:少于 2-3 条不算规律;单次爆款进"待验证"不进"结论"。
• 建议要可验收:每条下周动作带一个"怎么算做到了"的标准,否则下周无法复盘。
• 不代笔:文案血肉不写,留 【你的话:____】;这里只交数据、归因、方向。
• 敏感信息(粉丝画像、私有账号数据)提醒用户:初期私有,别直接公开贴表。