@pn-data/pn-data-analysis 0.0.2 → 0.0.4

package/README.md

@@ -1,4 +1,4 @@
-# @pn/pn-data-analysis
+# PN中台 AI数据分析
 
 Cursor Agent Skill — 通过 pn_mid_v2 中台 API 查询项目的**流水、活跃、留存、来源**数据。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pn-data/pn-data-analysis",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Cursor Agent Skill for querying pn_mid_v2 project data",
   "keywords": [
     "cursor",

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.4
+
+# 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,10 +25,21 @@ description: Analyzes project data on the middle platform (pn_mid_v2). Use when
 - **关键词**：用pn、用中台
 - **数据类型词**：收入、流水、商店流水、活跃、留存、来源
 
-## 项目名称解析
+## 执行顺序：先取 listProject 学习 id 与名称
+
+**在跑任何按项目查询（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 结果为准。
 
-- 项目 ID 直接使用（如「2023项目」→ pid=2023）
-- 「项目10」→ pid=2023
+## 项目名称解析（依赖上面 listProject 结果）
+
+- 用户说**数字 id**（如 2023、2088）→ 直接作为 pid
+- 用户说**项目名称或 tag** → 用已获取的项目列表按 name/tag 匹配，取对应 id 作为 pid
+- 仅当列表中存在明确对应时再发起数据查询；无法匹配时提示用户说明项目 id 或名称
 
 ---
 
@@ -34,10 +57,23 @@ description: Analyzes project data on the middle platform (pn_mid_v2). Use when
 
 ## 查询命令
 
-脚本位置：`.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> [选项]
 ```
 
 ### 四类数据
@@ -71,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,6 +15,7 @@ pn_query.py - 远程查询 pn_mid_v2 中台数据
 选项:
   --appPlatform=N    0=全平台(默认) 1=iOS 2=Android
   --group=N          分组类型，默认2(日期)。留存默认8(账号)
+  --json             输出原始 JSON
 """
 
 import argparse
@@ -30,6 +32,42 @@ 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:
@@ -126,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)