mpdt — 公众号运营数据，抓回本机，一键周报

WeChat Official Account analytics, fully local — fetch, store, and report your own data via one CLI.

公众号后台（mp.weixin.qq.com）的运营数据散落在三个页面，官方不提供导出，mpdt 把它们自动抓回本机 SQLite，并生成 Markdown 周报：

• 发表列表：阅读 / 分享 / 点赞 / 评论（实时累计口径）
• datacube 文章级：完读率 / 阅读率 / 送达 pv（发表后 7 天窗口，T+1）
• 单篇渠道页：逐篇阅读人数、完读率、平均时长、渠道构成（推荐 / 搜一搜 / 公众号消息…，30 天窗口）

为什么做这个

• 官方不提供导出：后台数据只能一屏一屏翻页看，换设备、离职交接、跨年对比都无从下手
• 商业工具 ¥99/月起：第三方 SaaS 要么按月收费，要么要求交出账号托管，个人号主用不起也不敢用
• 个人号主被忽视：官方与商业工具都面向机构运营团队，一个人打理的号缺少趁手的本地工具

mpdt 的答案：数据 100% 留在本机（SQLite + 本地文件），复用你已登录的 Chrome，不托管、不上传、不收费。

⚠️ 口径警告：三源同名指标口径不同（统计窗口 / 分母各异）——发表列表是实时累计，datacube 是发表后 7 天窗口 T+1，单篇渠道页是 30 天窗口。跨源比较前先对齐口径，周报文首附完整口径说明。

特性

• 零扫码：复用本机已登录 Chrome 的登录态（CDP 远程调试），token 从页面 URL 自动刷新
• 全本地：数据只存本机 SQLite（~/.mpdt/mpdt.sqlite3），凭据文件 600 权限、打印永不回显
• 幂等：同一天重复抓取 upsert 不重复；log_run 记录每次运行
• 礼貌限速：请求间隔 ≥ 1s
• 错误语义明确：退出码 0 成功（含空数据）｜2 配置问题｜3 凭据/登录态问题｜4 上游接口异常（附原始返回片段）｜130 用户中断（幂等设计，重跑安全）
• 机器可读输出：全局 --json 参数——stdout 恰好一行 JSON（{ok, cmd, data, meta}），适合脚本/管道串联
• 非交互友好：stdout 非 TTY（管道 / 重定向 / cron）时自动静默过程输出
• 零框架测试：98 个 unittest，零第三方测试依赖，python3 tests/test_fetchers.py 直跑

安装

# 推荐：pip 安装
pip install mpdt

# 或本地安装
git clone https://github.com/ttxs69/mpdt.git
cd mpdt && pip install .

未安装到环境时，python3 -m mpdt 与 mpdt 命令完全等价——从仓库根目录直接运行即可。

依赖：Python 3.10+、requests、websocket-client（其余全标准库）。

Quick Start（30 秒）

# ① 以调试端口启动 Chrome 并登录公众号后台
google-chrome --remote-debugging-port=9222
#    打开 https://mp.weixin.qq.com 扫码登录，保持该标签页存在

# ② 初始化配置（生成 ~/.mpdt/config.json，600 权限）
mpdt init

# ③ 抓数据 → 出周报
mpdt fetch --backfill 7   # 抓最近 7 天（默认仅昨天，T+1 口径）
mpdt detail --recent 7    # 单篇渠道构成（最近 7 天发表的）
mpdt report               # → mpdt-reports/weekly-YYYY-Www.md

已在跑的 Chrome 需先完全退出再用该参数重启；介意隔离可用独立 profile： --user-data-dir=/tmp/mpdt-chrome --remote-debugging-port=9222

命令一览

所有命令支持全局 --json（stdout 恰好一行 JSON）。

指标口径（CONCEPTS · 按概念分组）

完读率（read_completion，单位：比例(0-1)）

完读率是同一概念下的两个口径，窗口与分母均不同

阅读量（read_volume，单位：人次/次/人（按 series 而定））

三个 series 口径不同：实时累计 vs 7 天 pv vs 30 天 uv

分享（share，单位：次/人（按 series 而定））

点赞（like，单位：次）

在看（wow，单位：次）

评论（comment，单位：条）

送达人数（delivery，单位：人）

完读次数（finish_count，单位：次）

阅读率（read_rate，单位：比例(0-1)）

阅读后关注人数（follow_after_read，单位：人）

收藏人数（collection，单位：人）

听读人数（listen_people，单位：人）

听读次数（listen_plays，单位：次）

平均阅读时长（avg_read_time，单位：秒）

赞赏金额（praise_money，单位：上游金额单位）

元数据字段（非指标：快照日 / 派生列 / 结构列）

旧版字段（保留登记；不参与对照 / 不出现在 metrics 视图）

旧版字段保留在注册表里是为了让 mpdt/metrics.py 仍能识别上游接口历史返回的字段（CSV 导出元数据 *.metrics.csv 会标出口径），但不参与周报对照、metrics 视图与自动配对。

• old_like_num → like_num：旧版字段（保留登记），口径与 like_num 相当

自动推导的易混淆配对（同一概念多 series）

本节由 mpdt/metrics.py CONCEPTS 自动生成（python3 -c "from mpdt.metrics import readme_section; print(readme_section())"）。改口径请改 CONCEPTS，再运行 mpdt metrics 校对。

FAQ

• fetch 提示「该日期范围无数据」：不是错误（退出码 0）。datacube 为 T+1 口径，当天数据明天可得。
• 退出码 3（AuthError）：CDP 9222 上没有已登录的 mp.weixin 标签页——回 Quick Start ① 检查 Chrome 参数与登录态。
• 退出码 4（UpstreamError）：微信接口返回了未识别结构——错误信息附原始返回片段，提 issue 时请一并贴出。
• 换机器 / 重置：删除 ~/.mpdt/ 后重跑 mpdt init。数据库与配置都在该目录（除非 --db 另指定）。
• 会碰我的 Chrome 吗：只通过 CDP 读取已登录标签页的 URL 与发起后台 API 请求，不注入脚本、不改动页面。

文档

• 需求背景
• 产品需求（PRD）
• 技术设计
• 冷启动记录
• 答疑：提 issue

边界与合规

• 只读取你自己公众号后台的数据；不提供任何刷量 / 代抓他人数据能力
• 自动化访问后台属微信 ToS 灰色地带，本项目仅限个人备份分析用途，风险自担

License

MIT © ttxs69