PN 中台 AI 数据分析

Cursor Agent Skill — 通过 pn_mid_v2 中台 pn_data_analysis 接口（SkillManager::pnDataAnalysis）查询项目的数数付费、审计流水、审计快照、游戏预约统计（gameReservation）、订单统计列表（orderList，order_state）、生成单张订单统计任务（buildOrderForClaw）、广告概览、广告概览按 Campaign（adCampaign）、素材报告（material）、素材列表（materialList）、支付渠道、港币收入、活跃、留存、来源、LTV、客诉分析报告（customerService）、协助工单最早一批（oldestWaitingWorkOrder，skill_for_customer_service / getOldestWaitingWorkOrder，至多 3 条）、Google Play 评论、Apple 评论等。客诉工单列表、详情、发帖不在本 Skill（见 customer-service；正式回复客诉可用其 replyTroubleBySubjectId）。

企业 ID 约定：好玩(PN)=1，心动(XD)=5（企业审计 enterprise audit 使用 --enterpriseId 传入）。

Skill 版本：v0.0.57（与 pn-data-analysis/SKILL.md 顶部及 package.json 的 version 一致）。
完整约定、返回结构与字段说明见 pn-data-analysis/SKILL.md。
解读与输出约定：audit / auditSnapshot 返回已由服务端做字段清洗：删除 method=第三方、删除 _ta 字段；海外移除 tax_ 税后字段，国内在存在 tax_xxx 时移除对应 xxx 税前字段；同类字段按优先级仅保留最高一项。展示利润时须带计算过程（公式 + 代入数值）；得到查询结果后直接展示数据，勿对结果做二次计算或加工，详见 SKILL。

企业审计全周期（python3 … enterprise audit --year=0 --monthNum=0 --enterpriseId=…）汇总主结论：enterpriseId=1（好玩 PN）为税前，enterpriseId=5（心动 XD）为税后（与 client/src/enterprise/Audit.vue 一致；pn_query.py 仅在此场景对心动传 xd_post_tax，非 JSON 输出会带标题与口径说明）。非全周期企业审计的脚本列表汇总仍为税前链。

• PN（1）税前：收入 Σ(income_store ?? income_ta)，分成 Σ(share ?? share_store_method ?? share_ta_method ?? share_store ?? share_ta)，利润 收入 − 分成 − cost_ad − cost_man − cost_other（非 tax_* 主口径）。
• XD（5）税后：国内行用 tax_* 链汇总收入/分成/广告/其他（其他成本国内优先 tax_cost_other_*），海外行仍用商店/数数 income/share/cost 链；利润同上公式但各项取税后分支；详见 pn-data-analysis/SKILL.md「企业整体利润」。

全周期查询（--year=0 --monthNum=0 或等价全周期 timeSpan）时，回复里必须明确两点：

1. 是否包含人力成本（cost_man）；
2. 税前/税后：企业审计全周期须按 enterpriseId 写死（1=税前，5=税后）；非全周期企业审计注明脚本为税前链；其他查询再按返回字段说明。

环境变量

脚本和 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 新会话不会继承。

校验是否生效

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 留存 / 活跃 / 来源 / 广告概览 / 广告按 Campaign / 素材报告」
• 「用 pn 查 2088 本月素材」「用中台看 XX 项目 2026 年 1 月素材报告」→ material（需时间范围；输出时会显示查询时间周期）
• 「用 pn 查 2088 素材列表」「用中台看 XX 项目 2026 年 1 月素材列表」→ materialList（需时间范围；返回 key、author、filePath）
• 「用 pn 查 2088 游戏预约」「看项目 XX 预约渠道统计」→ gameReservation（需时间范围 + --reserveId，可选 --fuid）
• 「用 pn 查项目 XX 的 LTV / 客诉分析 / 订单统计 / order_state / 生成订单统计 / 谷歌评论 / Apple 评论」
• 「用 pn 按企业查审计」（--enterpriseId=1|5，企业审计走 AuditV2::getDataForEnterprise）
• 「用 pn 合并流水/合并成本/合并利润」（按项目名 . 前缀分组后求和显示）
• 「用 pn 查支付渠道列表」「支付渠道有哪些」→ listPaymentMethod（无需 pid/月份）
• 「用 pn 查港币收入」「2026 年 1 月港币收入」→ hkdRevenue（不需要 pid，需时间范围 + 必传 --paymentMethod；可先 listPaymentMethod 取枚举）

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

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

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

命令行概要

# 项目列表（无月份）
python3 <SKILL_DIR>/pn_query.py projects

# 支付渠道列表（无 pid/月份，供港币收入选 payment_method）
python3 <SKILL_DIR>/pn_query.py listPaymentMethod

# 协助工单：全库创建时间最早至多 3 条（skill_for_customer_service，与 pn_data_analysis 共用 Token，无需 pid）
python3 <SKILL_DIR>/pn_query.py oldestWaitingWorkOrder
python3 <SKILL_DIR>/pn_query.py oldestWaitingWorkOrder --json

# 需月份或时间段：pay / audit / ad / adCampaign / material / materialList / 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> [选项]

# 游戏预约统计（需 reserveId）
python3 <SKILL_DIR>/pn_query.py <pid> gameReservation <YYYY-MM> --reserveId=174
python3 <SKILL_DIR>/pn_query.py <pid> gameReservation --from=YYYY-MM-DD --to=YYYY-MM-DD --reserveId=174 [--fuid=渠道]

# 企业审计（1=好玩 PN，5=心动 XD）
python3 <SKILL_DIR>/pn_query.py enterprise audit <YYYY-MM> --enterpriseId=1
python3 <SKILL_DIR>/pn_query.py enterprise audit --year=0 --monthNum=0 --enterpriseId=5

# 合并查询：按项目名 '.' 前缀分组并汇总（如 A.1/A.2 合并为 A）
python3 <SKILL_DIR>/pn_query.py merge <dataType> <YYYY-MM>
python3 <SKILL_DIR>/pn_query.py merge <dataType> --from=<DATE> --to=<DATE>

# 审计快照（需 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]

# 港币收入（按月份汇总、不区分项目；不需要 pid；需时间范围 + 必传 --paymentMethod，如 29）
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

# 无需月份：订单统计、客诉分析报告、Google 评论；Apple 评论默认最近 14 天，可选月份或 --from/--to
python3 <SKILL_DIR>/pn_query.py <pid> orderList [--aid=APPID] [--etc=1|2|3|4] [--json]
python3 <SKILL_DIR>/pn_query.py <pid> customerService
python3 <SKILL_DIR>/pn_query.py <pid> googleReviews [--appid=...] [--packageName=...] [--nextToken=...] [--lang=cn] [--json]
python3 <SKILL_DIR>/pn_query.py <pid> appleReviews
python3 <SKILL_DIR>/pn_query.py <pid> appleReviews <YYYY-MM>
python3 <SKILL_DIR>/pn_query.py <pid> appleReviews --from=<DATE> --to=<DATE> [--json]

# 生成单张订单统计任务（必须给出开始/结束时间）
python3 <SKILL_DIR>/pn_query.py <pid> buildOrderForClaw --from=YYYY-MM-DD --to=YYYY-MM-DD --status=2,3 --t=1 --publish=2
python3 <SKILL_DIR>/pn_query.py <pid> buildOrderForClaw --from="YYYY-MM-DD HH:MM:SS" --to="YYYY-MM-DD HH:MM:SS" --status=2,3 --t=2

dataType 一览

| dataType | 说明 | |----------|------| | projects / listProject | 取项目列表（无需 pid/月份）。返回 id、name、tag、isDomestic、enterpriseId、enterpriseName（好玩(PN)/心动(XD)），用于建立 pid↔项目 映射及按企业区分。 | | listPaymentMethod | 支付渠道列表（无需 pid/月份）。返回 value、name，港币收入前可查以选 payment_method。 | | oldestWaitingWorkOrder（CLI 伪 dataType，非 pn_data_analysis） | 协助工单：POST /service/skill_for_customer_service，Body api=getOldestWaitingWorkOrder；响应 JSON 数组（至多 3 条）；详见 pn-data-analysis/SKILL.md「协助工单」 | | pay | 数数付费 taPay（pay_usd / refund_* 等，listData） | | audit | 审计流水 getAuditList（pay_store / income_store / profit_store / 成本等，list）；服务端会清洗：删除 method=第三方、删除 _ta，并按项目国内/海外移除税前或税后字段，同类字段仅保留优先级最高一项；支持 --year/--monthNum（0/0=全周期，YYYY/0=年数据）。服务端 dataAnalysisAudit 会将全周期范围强制转为 year=0, month=0，整年范围转为 year=YYYY, month=0 后查询。按企业查询时会走 AuditV2::getDataForEnterprise。 | | auditSnapshot | 审计快照 getAuditSnapshot（按 startDate 取某日历史快照，list 与 audit 同结构）；需 --startDate=YYYY-MM-DD 或月份位置参数作月初 | | gameReservation | 游戏预约统计（Ga::op(OP_GA_RESERVE_COUNTER_STATE)）；需 pid + 时间范围 + --reserveId，可选 --fuid；返回按 fuid 聚合的 items(counter_type,sum) | | orderList | 订单统计列表 StatisticManager::getOrderList（order_state）；需 pid，无需月份/timeSpan；可选 --aid（按应用）、--etc 1～4（与前端一致：HP 币 / 福利 / 企业币 / 沙盒）；需统计权限（与 audit 同为 STATISTICS 管理员）。导出文件：https://pn.haoplay.com.cn/order/export/download?key=<aws_key>（每行返回的 aws_key），详见 SKILL | | buildOrderForClaw | 生成单张订单统计任务 StatisticManager::buildOrderListForClaw；不使用月份；需 pid + --from/--to。模式与参数见下节 「buildOrderForClaw 参数说明」（与 pn_query.py / query_build_order_for_claw 一致；完整字段表见 pn-data-analysis/SKILL.md 同名片段） | | ad | 广告概览 taAdvertisementOverview（成本、展示、点击、留存、付费、安装等 listData）；有广告关键词时默认用 ad。 | | adCampaign | 广告概览按 Campaign 维度（同 ad 接口，group=4）；从广告概览接口获取 Campaign 数据；需时间范围。 | | material | 素材报告 taAdvertisementMaterial（按作者/素材维度：author、impressions、installs、clicks、cost、files 等）；需时间范围；输出时会显示查询时间周期；可选 --mode（默认 1）、--group（默认 2）。 | | materialList | 素材列表 getMaterialList（GET_ADVERTISEMENT_MATERIAL_LIST）；需时间范围；返回 list 每行 key、author、filePath；可选 --group（默认 2）。 | | hkdRevenue | 港币收入（HKD 非沙盒，按月份汇总、不区分项目；不需要 pid）；需 timeSpan + 必传 --paymentMethod（枚举见 listPaymentMethod）。返回 list 每行含 month、total_price_usd（港币收入总计，美元）、total_price_usd_all（所有货币总计，美元），金额单位均为美元。 | | activity / retention / source | 活跃 / 留存 / 来源 | | ltv | LTV 累计付费；可选 --timezone、--area | | customerService / cs | 客诉分析报告（最新一条） | | googleReviews | Google Play 评论；可只传 pid（后端按 Google 包解析）；支持 --appid + --packageName；有 tokenPagination 时脚本会自动翻页并合并多页后展示 | | appleReviews | Apple App Store 评论；需 pid；默认最近 14 天，可选月份或 --from/--to；后端取项目下首个 iOS 应用 appStoreId 请求评论 |

buildOrderForClaw 参数说明

对应 StatisticManager::buildOrderListForClaw，请求 dataType=buildOrderForClaw。不使用 YYYY-MM 位置参数；时间范围仅通过 --from + --to（须成对）。时间格式：YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS；仅日期时开始、结束时刻均默认 00:00:00（与 pay/audit 等通用「--to 含当日 23:59:59」的语义不同）。

| 参数 | 请求体字段 | 何时必填 | 说明 | |------|------------|----------|------| | <pid> | pid | 始终 | 项目 id | | --from / --to | timeSpan | 始终 | 结束不得早于开始 | | --t | t | 可选 | 不传：普通订单生成（原 buildOrderList），须 --noSandbox + --aid 或 --etc。1：第三方 claw，须 --status + --publish。2：GooglePC claw，须 --status，不要 --publish | | --noSandbox | noSandbox | 仅当不传 --t | 0 含沙盒，1 排除沙盒 | | --aid | aid | 仅当不传 --t | 与 --etc 二选一：应用 id | | --etc | etc | 仅当不传 --t 且无 --aid | 1～4（HP 币 / 福利 / 企业币 / 沙盒），与 orderList 一致 | | --status | status | 当 --t=1 或 2 | 逗号分隔整数，至少一个；默认 2,3 | | --publish | publish | 仅当 --t=1 | 1 国内，2 海外；--t=2 时不应传 | | --json | — | 可选 | 原始 JSON |

模式：普通订单生成（不传 --t）｜第三方 claw（--t=1）｜GooglePC claw（--t=2）。更细的约束与示例命令见 pn-data-analysis/SKILL.md「buildOrderForClaw 参数说明」。

常用选项

| 选项 | 说明 | |------|------| | --appPlatform=N | 0 全平台 / 1 iOS / 2 Android | | --group=N | 2 日期 / 4 Campaign（adCampaign 默认 4）/ 8 账号（留存默认 8）等；ad 还支持 3 系统、5 地区、6 素材、11 作者 | | --from / --to | 时间段：YYYY-MM 或 YYYY-MM-DD；按北京时间（UTC+8）计算起止 | | --timezone | LTV 必用；pay 可选 | | --area | LTV 可选地区筛选 | | --appid / --packageName | googleReviews 可选，与后端请求体 data 一致 | | --nextToken | googleReviews 翻页（上页返回的 tokenPagination） | | --lang | googleReviews 翻译语言，默认 cn | | --startDate | auditSnapshot 快照日期 YYYY-MM-DD；不传时可用月份位置参数作月初 | | --year | audit 可选年份；需与 --monthNum 搭配，--year=0 --monthNum=0 表示全周期 | | --monthNum | audit 可选月份数字（0~12）；year>0 且 monthNum=0 表示该年全年 | | --enterpriseId | 企业查询：1=好玩(PN) 5=心动(XD)（用于 pid=enterprise 且 dataType=audit） | | appleReviews | 不传时间时默认最近 14 天；可传月份或 --from/--to | | --paymentMethod=N | hkdRevenue 必传，支付渠道枚举值（见 listPaymentMethod） | | --reserveId=N | gameReservation 必传，预约活动 id（后端字段 reserveId） | | --fuid=STR | gameReservation 可选，渠道标识；默认空字符串（全部渠道） | | --aid=N | orderList 可选；buildOrderForClaw 仅普通模式（不传 --t）时与 --etc 二选一，见「buildOrderForClaw 参数说明」 | | --etc | orderList 可选；buildOrderForClaw 仅普通模式且无 --aid 时：1～4（HP 币 / 福利 / 企业币 / 沙盒） | | --status | buildOrderForClaw：--t=1/2 时须至少一个状态，逗号分隔整数（默认 2,3）；详见专节 | | --t | buildOrderForClaw：1 第三方 / 2 GooglePC / 不传=普通订单；详见专节 | | --publish | buildOrderForClaw：仅 --t=1 时 1 国内 2 海外；--t=2 勿传 | | --noSandbox | buildOrderForClaw：仅普通模式（不传 --t）0 含沙盒 1 排除沙盒 | | --unitNum=N | ad / adCampaign 广告概览可选，数数 unitNum，默认 30 | | --mode=N | material 素材报告可选，数数查询模式，默认 1 | | --json | 原始 JSON |

示例

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 oldestWaitingWorkOrder
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 enterprise audit 2026-01 --enterpriseId=1
python3 pn-data-analysis/pn-data-analysis/pn_query.py enterprise audit --year=0 --monthNum=0 --enterpriseId=5
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 audit --year=0 --monthNum=0
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 audit --year=2026 --monthNum=0
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 ad 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 adCampaign 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 adCampaign --from=2026-01 --to=2026-02
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 material 2026-03
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 material --from=2026-03-01 --to=2026-03-15
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 materialList 2026-03
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 materialList --from=2026-03-01 --to=2026-03-15
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 gameReservation 2026-03 --reserveId=174
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2088 gameReservation --from=2026-03-01 --to=2026-03-15 --reserveId=174 --fuid=k_www.google.com
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 hkdRevenue 2026-01 --paymentMethod=29
python3 pn-data-analysis/pn-data-analysis/pn_query.py hkdRevenue --from=2026-01 --to=2026-02 --paymentMethod=29
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 orderList
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 orderList --aid=2051011
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 orderList --etc=3 --json
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 buildOrderForClaw --from=2026-01-01 --to=2026-01-31 --status=2,3 --t=1 --publish=2
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 buildOrderForClaw --from="2026-01-01 00:00:00" --to="2026-01-31 00:00:00" --status=2,3 --t=2
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 buildOrderForClaw --from=2026-01-01 --to=2026-01-31 --noSandbox=1 --aid=2051011
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 buildOrderForClaw --from=2026-01-01 --to=2026-01-31 --noSandbox=0 --etc=3
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
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 appleReviews
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 appleReviews 2026-01
python3 pn-data-analysis/pn-data-analysis/pn_query.py 2023 appleReviews --from=2026-01 --to=2026-01 --json

API

• 生产：https://pnv2.17995api.net + /service/pn_data_analysis
• 协助工单（最早至多 3 条）：同 host + /service/skill_for_customer_service，Body {"api":"getOldestWaitingWorkOrder"}（无 pid；与上项共用 X-Pn-Token）
• Header：X-Pn-Token: $PN_DATA_ANALYSIS_TOKEN
• 本地调试可在 pn_query.py 中改 API_BASE
• 各 dataType 与后端映射、返回字段以 pn-data-analysis/SKILL.md 为准；orderList 对应 StatisticManager::getOrderList（order_state），buildOrderForClaw 对应 StatisticManager::buildOrderListForClaw。

更新 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