PN 中台 AI 数据分析

Cursor Agent Skill — 通过 pn_mid_v2 中台 pn_data_analysis 接口（SkillManager::pnDataAnalysis）查询项目的数数付费、审计流水、审计快照、广告概览、活跃、留存、来源、LTV、客诉、Google Play 评论，以及支付渠道列表、港币收入（无需项目 id）等。

Skill 版本：与 pn-data-analysis/SKILL.md 顶部及 package.json 的 version 一致（当前 0.0.30）。
完整约定、返回结构与字段说明见 pn-data-analysis/SKILL.md。
解读与输出约定：海外项目只展示税前口径、不展示税后；展示利润时须带计算过程（公式 + 代入数值）；得到查询结果后直接展示数据，勿对结果做二次计算或加工，详见 SKILL。

环境变量

脚本和 Cursor Agent 调用 pn_query.py 时，必须能读到环境变量 PN_DATA_ANALYSIS_TOKEN，否则会报错并提示未配置。

获取密钥

1. 登录 pn_mid_v2 中台
2. 点击右上角头像/菜单 → 生成数据分析密钥（或设置/密钥相关入口）
3. 复制生成的 token（仅展示一次，请妥善保存）

配置方式

方式一：写入 shell 配置文件（推荐，对本用户所有终端生效）

• macOS / Linux（zsh）：在 ~/.zshrc 末尾添加一行
  export PN_DATA_ANALYSIS_TOKEN="粘贴你的 token"
• bash：在 ~/.bashrc 或 ~/.bash_profile 末尾添加同一行

保存后执行一次：

source ~/.zshrc   # 或 source ~/.bashrc

方式二：仅当前终端会话

export PN_DATA_ANALYSIS_TOKEN="粘贴你的 token"

仅对当前 shell 有效，新开终端或 Cursor 新会话不会继承。

Docker 环境（龙虾）：在 Docker 环境下，密钥放在 Skill 对应目录下的 .env 文件中。即在 pn-data-analysis 所在目录（如 .cursor/skills/pn-data-analysis/.env）新建或编辑 .env，写入一行 PN_DATA_ANALYSIS_TOKEN=你的token，容器/Agent 会从该文件读取，无需写入 shell 配置。

校验是否生效

echo $PN_DATA_ANALYSIS_TOKEN
# 或
printenv PN_DATA_ANALYSIS_TOKEN

有输出一长串 token 即表示已配置；为空则需检查配置文件是否写对、是否已 source。
Cursor / Agent 执行查询前若未在配置里设置该变量，可能读不到，建议始终在 ~/.zshrc 或 ~/.bashrc 中配置并已 source。

安装

npm install @pn-data/pn-data-analysis
# 将 node_modules/@pn-data/pn-data-analysis/ 下 pn-data-analysis/ 复制或链接到 .cursor/skills/pn-data-analysis/

脚本路径：<SKILL_DIR>/pn_query.py（本仓库为 .cursor/skills/pn-data-analysis/pn-data-analysis/pn_query.py）。
时间范围（单月或 --from/--to）按北京时间（UTC+8）；请求体 timeSpan 为日期字符串数组 ["YYYY-MM", "YYYY-MM"] 或 ["YYYY-MM-DD", "YYYY-MM-DD"]，由服务端解析。请求失败时会打印响应头与 body 预览便于排查。

在 Cursor 中触发

• 「用 pn 查 2023 项目 2026 年 1 月流水 / 审计 / 利润」
• 「用 pn 查小镇海外 2026-03-08 审计快照」
• 「用中台看 2088 留存 / 活跃 / 来源 / 广告概览」
• 「用 pn 查项目 XX 的 LTV / 客诉 / 谷歌评论」
• 「用 pn 查支付渠道列表」「查港币收入 2026 年 1 月」

先 projects 再查：python3 pn_query.py projects 获取当前用户可访问的项目列表，建立 pid ↔ 名称/tag/企业（如测2 → 2023）。返回字段包括：id、name、tag、isDomestic（国内/海外）、enterpriseId、enterpriseName（好玩(PN) / 心动(XD)）。支付渠道用 listPaymentMethod；港币收入不需要 pid，需时间范围 + --paymentMethod（枚举值见 listPaymentMethod）。

备注：龙虾请求所有项目时的区分

当龙虾请求「所有项目」时，需按**好玩群(PN)与心动群(XD)**区分，分别给出对应项目列表（不要混在一起）；根据项目列表中的 enterpriseName（或 enterpriseId：1=好玩 PN，5=心动 XD）判断所属群，对两个群返回不同的项目集合。

命令行概要

# 项目列表、支付渠道列表（无需 pid/月份）
python3 <SKILL_DIR>/pn_query.py projects
python3 <SKILL_DIR>/pn_query.py listPaymentMethod

# 需月份或时间段：pay / audit / ad / activity / retention / source / ltv
python3 <SKILL_DIR>/pn_query.py <pid> <dataType> <YYYY-MM> [选项]
python3 <SKILL_DIR>/pn_query.py <pid> <dataType> --from=<DATE> --to=<DATE> [选项]

# 广告概览（有广告关键词时默认用 ad）
python3 <SKILL_DIR>/pn_query.py <pid> ad <YYYY-MM> [--group=N] [--unitNum=N]

# 港币收入（不需要 pid；必传 --paymentMethod）
python3 <SKILL_DIR>/pn_query.py hkdRevenue <YYYY-MM> --paymentMethod=29
python3 <SKILL_DIR>/pn_query.py hkdRevenue --from=YYYY-MM --to=YYYY-MM --paymentMethod=29

# 审计快照（需 startDate）：月份作月初或 --startDate=YYYY-MM-DD
python3 <SKILL_DIR>/pn_query.py <pid> auditSnapshot <YYYY-MM> [--json]
python3 <SKILL_DIR>/pn_query.py <pid> auditSnapshot --startDate=YYYY-MM-DD [--json]

# 无需月份：客诉、Google 评论
python3 <SKILL_DIR>/pn_query.py <pid> customerService
python3 <SKILL_DIR>/pn_query.py <pid> googleReviews [--appid=...] [--packageName=...] [--nextToken=...] [--lang=cn] [--json]

dataType 一览

| dataType | 说明 | |----------|------| | projects / listProject | 取项目列表（无需 pid/月份）。返回 id、name、tag、isDomestic、enterpriseId、enterpriseName（好玩(PN)/心动(XD)），用于建立 pid↔项目 映射及按企业区分。 | | listPaymentMethod | 支付渠道列表（无需 pid/月份）。返回 value/name，供港币收入等选 --paymentMethod 用。 | | pay | 数数付费 taPay（pay_usd / refund_* 等，listData） | | audit | 审计流水 getAuditList（pay_ta / income_ta / 利润与成本等，list） | | auditSnapshot | 审计快照 getAuditSnapshot（按 startDate 取某日历史快照，list 与 audit 同结构）；需 --startDate=YYYY-MM-DD 或月份位置参数作月初 | | ad | 广告概览（成本、展示、点击、留存、付费、安装等）；有广告关键词时默认用 ad；可选 --group、--unitNum | | hkdRevenue | 港币收入（不需要 pid）；需时间范围 + 必传 --paymentMethod（枚举值，见 listPaymentMethod） | | activity / retention / source | 活跃 / 留存 / 来源 | | ltv | LTV 累计付费；可选 --timezone、--area | | customerService / cs | 客诉分析报告 | | googleReviews | Google Play 评论；可只传 pid（后端按 Google 包解析）；支持 --appid + --packageName；有 tokenPagination 时脚本会自动翻页并合并多页后展示 |

常用选项

| 选项 | 说明 | |------|------| | --appPlatform=N | 0 全平台 / 1 iOS / 2 Android | | --group=N | 2 日期 / 8 账号（留存默认 8）等 | | --from / --to | 时间段：YYYY-MM 或 YYYY-MM-DD；按北京时间（UTC+8）计算起止 | | --timezone | LTV 必用；pay 可选 | | --area | LTV 可选地区筛选 | | --appid / --packageName | googleReviews 可选，与 Google.vue 一致 | | --nextToken | googleReviews 翻页（上页返回的 tokenPagination） | | --lang | googleReviews 翻译语言，默认 cn | | --startDate | auditSnapshot 快照日期 YYYY-MM-DD；不传时可用月份位置参数作月初 | | --unitNum | ad 广告概览可选，数数 unitNum，默认 30 | | --paymentMethod | hkdRevenue 必传，支付渠道枚举值（见 listPaymentMethod） | | --json | 原始 JSON |

示例

# 项目与支付渠道（无需 pid）
python3 pn-data-analysis/pn-data-analysis/pn_query.py projects
python3 pn-data-analysis/pn-data-analysis/pn_query.py listPaymentMethod

# 付费、审计、广告概览、港币收入
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 pay 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 audit 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 ad 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py hkdRevenue 2026-01 --paymentMethod=29

# 审计快照、活跃、LTV、客诉、Google 评论
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2170 auditSnapshot 2026-03
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2170 auditSnapshot --startDate=2026-03-08
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 activity --from=2026-01 --to=2026-03
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 ltv 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 customerService
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 googleReviews
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 googleReviews --json

API

• 生产：https://pnv2.17995api.net + /service/pn_data_analysis
• Header：X-Pn-Token: $PN_DATA_ANALYSIS_TOKEN
• 本地调试可在 pn_query.py 中改 API_BASE

更新 Skill

检查 npm 最新版本并与本仓库 SKILL 顶部版本号对比：

npm view @pn-data/pn-data-analysis version --registry https://registry.npmjs.org/

若不一致则更新本 Skill 后重新读取 pn-data-analysis/SKILL.md。

依赖

• Python 3.9+（脚本仅用标准库与类型注解，无第三方依赖）

License

MIT