@pn-data/pn-data-analysis 0.0.1 → 0.0.3

package/README.md

@@ -1,13 +1,31 @@
-# @pn/pn-data-analysis
+# PN中台 AI数据分析
 
 Cursor Agent Skill — 通过 pn_mid_v2 中台 API 查询项目的**流水、活跃、留存、来源**数据。
 
+## 环境变量配置
+
+使用前需配置认证密钥。
+
+密钥在**中台右上角 -> 生成数据分析密钥**中可以获取。
+
+### 必需变量
+
+密钥必须写入 shell 配置文件（zsh 用户写 `~/.zshrc`，bash 用户写 `~/.bashrc`），以确保所有终端会话和 AI 工具都能读取到：
+
+```bash
+export PN_DATA_ANALYSIS_TOKEN="your-token-here"   # 数据分析密钥
+```
+
+将上面内容写入对应的 shell 配置文件后执行 `source` 使其生效。
+
+> **注意**：仅在当前终端 `export` 而不写入配置文件的话，新终端窗口或 AI Agent 启动的 shell 会话将无法读取到密钥。Skill 在每次会话首次使用时会自动检查配置文件中是否存在密钥，如果缺失会自动写入。
+
 ## 安装
 
 ```bash
 # 作为项目 Cursor Skill
-npm install @pn/pn-data-analysis
-# 将 node_modules/@pn/pn-data-analysis/pn-data-analysis/ 复制或链接到 .cursor/skills/
+npm install @pn-data/pn-data-analysis
+# 将 node_modules/@pn-data/pn-data-analysis/pn-data-analysis/ 复制或链接到 .cursor/skills/
 ```
 
 ## 使用方式

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pn-data/pn-data-analysis",
-  "version": "0.0.1",
-  "description": "Cursor Agent Skill for querying pn_mid_v2 project data (pay, activity, retention, source)",
+  "version": "0.0.3",
+  "description": "Cursor Agent Skill for querying pn_mid_v2 project data",
   "keywords": [
     "cursor",
     "cursor-skill",

package/pn-data-analysis/SKILL.md

@@ -3,6 +3,18 @@ name: pn-data-analysis
 description: Analyzes project data on the middle platform (pn_mid_v2). Use when querying 收入, 流水, 商店流水, 活跃, 留存, 来源, project revenue, activity, retention, or source data by project and month.
 ---
 
+> Skill 版本：v0.0.3
+
+# Skill 更新
+
+```bash
+npm view @pn-data/pn-data-analysis version --registry https://registry.npmjs.org/
+```
+
+与本文件顶部 `Skill 版本` 对比，不同则更新本 Skill
+
+更新后**重新读取** `<SKILL_DIR>/SKILL.md`，以新版本为准。告知用户"中台数据分析 Skill 已更新到 vX.X.X"。
+
 # 中台项目数据分析
 
 通过 `pn_query.py` 远程查询 pn_mid_v2 中台各项目数据，支持**流水、活跃、留存、来源**四类查询。
@@ -13,19 +25,55 @@ description: Analyzes project data on the middle platform (pn_mid_v2). Use when
 - **关键词**：用pn、用中台
 - **数据类型词**：收入、流水、商店流水、活跃、留存、来源
 
-## 项目名称解析
+## 执行顺序：先取 listProject 学习 id 与名称
 
-- 项目 ID 直接使用（如「2023项目」→ pid=2023）
-- 「项目10」→ pid=2023
+**在跑任何按项目查询（pay/activity/retention/source）之前**，先取一次项目列表，建立「项目 id ↔ 名称」对应关系：
+
+1. **先执行**：`python3 <SKILL_DIR>/pn_query.py projects`（或 `--json` 取原始列表）
+2. **从返回中学习**：每条为 `id | name | tag`，记下 id、name、tag 的对应关系
+3. **再解析用户请求**：用户提到「项目名」「项目X」「tag」或数字 id 时，用该列表解析出**真实的项目 id (pid)**，再调用 `pn_query.py <pid> <dataType> <YYYY-MM>`
+
+未先取 listProject 时，不要猜测 pid；名称/别称与 id 的对应关系以当次 listProject 结果为准。
+
+## 项目名称解析（依赖上面 listProject 结果）
+
+- 用户说**数字 id**（如 2023、2088）→ 直接作为 pid
+- 用户说**项目名称或 tag** → 用已获取的项目列表按 name/tag 匹配，取对应 id 作为 pid
+- 仅当列表中存在明确对应时再发起数据查询；无法匹配时提示用户说明项目 id 或名称
+
+---
+
+## 执行前：检查 PN_DATA_ANALYSIS_TOKEN
+
+**每次执行查询前**必须确保环境变量 `PN_DATA_ANALYSIS_TOKEN` 已存在：
+
+1. **先检查**：`printenv PN_DATA_ANALYSIS_TOKEN` 或 `echo $PN_DATA_ANALYSIS_TOKEN`
+2. **若为空或未设置**：先执行 `source` 加载用户 shell 配置
+3. **再执行**下面的查询命令
+
+密钥需用户在中台右上角 -> 生成数据分析密钥 获取并写入 `~/.zshrc` 或 `~/.bashrc`：`export PN_DATA_ANALYSIS_TOKEN="..."`
 
 ---
 
 ## 查询命令
 
-脚本位置：`.cursor/skills/pn-data-analysis/pn_query.py`
+脚本位置：`<SKILL_DIR>/pn_query.py`
+
+### 获取项目列表（id、name、tag）
+
+无需 pid/月份，直接获取当前密钥对应用户可访问的项目列表，用于学习 **id、name、tag** 的对应关系：
 
 ```bash
-python3 .cursor/skills/pn-data-analysis/pn_query.py <pid> <dataType> <YYYY-MM> [选项]
+python3 <SKILL_DIR>/pn_query.py projects
+python3 <SKILL_DIR>/pn_query.py projects --json
+```
+
+输出格式：`id | name | tag`，每行一个项目。
+
+### 按项目与月份查询数据
+
+```bash
+python3 <SKILL_DIR>/pn_query.py <pid> <dataType> <YYYY-MM> [选项]
 ```
 
 ### 四类数据
@@ -59,23 +107,26 @@ python3 .cursor/skills/pn-data-analysis/pn_query.py <pid> <dataType> <YYYY-MM> [
 ## 示例
 
 ```bash
+# 获取项目列表
+python3 <SKILL_DIR>/pn_query.py projects
+
 # 流水
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 pay 2026-01
+python3 <SKILL_DIR>/pn_query.py 2023 pay 2026-01
 
 # 活跃（全平台）
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 activity 2026-01
+python3 <SKILL_DIR>/pn_query.py 2023 activity 2026-01
 
 # 留存（全平台）
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 retention 2026-01
+python3 <SKILL_DIR>/pn_query.py 2023 retention 2026-01
 
 # 来源
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 source 2026-01
+python3 <SKILL_DIR>/pn_query.py 2023 source 2026-01
 
 # 仅 iOS 活跃
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 activity 2026-01 --appPlatform=1
+python3 <SKILL_DIR>/pn_query.py 2023 activity 2026-01 --appPlatform=1
 
 # 原始 JSON
-python3 .cursor/skills/pn-data-analysis/pn_query.py 2023 retention 2026-01 --json
+python3 <SKILL_DIR>/pn_query.py 2023 retention 2026-01 --json
 ```
 
 ## 默认行为

package/pn-data-analysis/pn_query.py

@@ -2,9 +2,10 @@
 """
 pn_query.py - 远程查询 pn_mid_v2 中台数据
 
-通过 HTTP API 调用 pnDataAnalysis 接口，查询项目的流水、活跃、留存、来源数据。
+通过 HTTP API 调用 pnDataAnalysis 接口，查询项目的流水、活跃、留存、来源数据，或获取项目列表。
 
 用法:
+  python3 pn_query.py projects                    # 获取项目列表
   python3 pn_query.py <pid> <dataType> <YYYY-MM> [选项]
   python3 pn_query.py 2023 pay 2026-01
   python3 pn_query.py 2023 activity 2026-01
@@ -14,20 +15,66 @@ pn_query.py - 远程查询 pn_mid_v2 中台数据
 选项:
   --appPlatform=N    0=全平台(默认) 1=iOS 2=Android
   --group=N          分组类型，默认2(日期)。留存默认8(账号)
+  --json             输出原始 JSON
 """
 
 import argparse
 import json
+import os
 import sys
 import urllib.request
 from calendar import monthrange
 from datetime import datetime
 
-API_BASE = "https://pnv2.17995api.net"
+# API_BASE = "https://pnv2.17995api.net"
+API_BASE = "http://localhost:811" # 本地测试
 API_PATH = "/service/pn_data_analysis"
+ENV_TOKEN = "PN_DATA_ANALYSIS_TOKEN"
+
+
+def list_projects() -> list:
+    """获取当前用户可访问的项目列表。"""
+    token = os.environ.get(ENV_TOKEN)
+    if not token:
+        raise SystemExit(
+            f"未配置 {ENV_TOKEN}。请在中台右上角 -> 生成数据分析密钥 获取后写入 shell 配置（如 ~/.zshrc）并 source 生效。"
+        )
+    url = f"{API_BASE}{API_PATH}"
+    payload = {"dataType": "listProject"}
+    headers = {
+        "Content-Type": "application/json;charset=UTF-8",
+        "X-Pn-Token": token,
+    }
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers=headers,
+        method="POST",
+    )
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        out = json.loads(resp.read().decode("utf-8"))
+    return out if isinstance(out, list) else out.get("list", out)
+
+
+def format_projects(data: list) -> str:
+    if not data:
+        return "无项目数据"
+    lines = ["项目列表 (id | name | tag):"]
+    for p in data:
+        pid = p.get("id", "")
+        name = p.get("name", "")
+        tag = p.get("tag", "")
+        lines.append(f"  {pid} | {name} | {tag}")
+    return "\n".join(lines)
 
 
 def query(pid: int, data_type: str, month: str, app_platform: int = 0, group: int = 2) -> dict:
+    token = os.environ.get(ENV_TOKEN)
+    if not token:
+        raise SystemExit(
+            f"未配置 {ENV_TOKEN}。请在中台右上角 -> 生成数据分析密钥 获取后写入 shell 配置（如 ~/.zshrc）并 source 生效。"
+        )
+
     st_date = datetime.strptime(f"{month}-01", "%Y-%m-%d")
     y, m = st_date.year, st_date.month
     _, last = monthrange(y, m)
@@ -43,7 +90,10 @@ def query(pid: int, data_type: str, month: str, app_platform: int = 0, group: in
         "useCache": True,
     }
     url = f"{API_BASE}{API_PATH}"
-    headers = {"Content-Type": "application/json;charset=UTF-8"}
+    headers = {
+        "Content-Type": "application/json;charset=UTF-8",
+        "X-Pn-Token": token,
+    }
     req = urllib.request.Request(
         url,
         data=json.dumps(payload).encode("utf-8"),
@@ -114,19 +164,36 @@ def format_source(data: list) -> str:
 
 def main():
     parser = argparse.ArgumentParser(description="pn_mid_v2 远程数据查询")
-    parser.add_argument("pid", type=int, help="项目 ID")
-    parser.add_argument("dataType", choices=["pay", "activity", "retention", "source"], help="数据类型")
-    parser.add_argument("month", help="月份 YYYY-MM")
+    parser.add_argument("pid", nargs="?", help="项目 ID，或写 projects 获取项目列表")
+    parser.add_argument("dataType", nargs="?", choices=["pay", "activity", "retention", "source"], help="数据类型")
+    parser.add_argument("month", nargs="?", help="月份 YYYY-MM")
     parser.add_argument("--appPlatform", type=int, default=0, help="0=全平台 1=iOS 2=Android (默认0)")
     parser.add_argument("--group", type=int, default=None, help="分组类型，默认2(日期)，留存默认8(账号)")
     parser.add_argument("--json", action="store_true", help="输出原始 JSON")
     args = parser.parse_args()
 
+    # 获取项目列表
+    if (args.pid or "").lower() in ("projects", "listproject", "list"):
+        try:
+            result = list_projects()
+        except Exception as e:
+            print(f"查询失败: {e}", file=sys.stderr)
+            sys.exit(1)
+        if args.json:
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+        else:
+            print(format_projects(result))
+        return
+
+    if args.pid is None or args.dataType is None or args.month is None:
+        parser.error("查询数据时需指定 pid dataType month，或使用 pid=projects 获取项目列表")
+
+    pid = int(args.pid)
     if args.group is None:
         args.group = 8 if args.dataType == "retention" else 2
 
     try:
-        result = query(args.pid, args.dataType, args.month, args.appPlatform, args.group)
+        result = query(pid, args.dataType, args.month, args.appPlatform, args.group)
     except Exception as e:
         print(f"查询失败: {e}", file=sys.stderr)
         sys.exit(1)