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

package/README.md

@@ -2,12 +2,30 @@
 
 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.2",
+  "description": "Cursor Agent Skill for querying pn_mid_v2 project data",
   "keywords": [
     "cursor",
     "cursor-skill",

package/pn-data-analysis/SKILL.md

@@ -20,6 +20,18 @@ description: Analyzes project data on the middle platform (pn_mid_v2). Use when
 
 ---
 
+## 执行前：检查 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`

package/pn-data-analysis/pn_query.py

@@ -18,16 +18,25 @@ pn_query.py - 远程查询 pn_mid_v2 中台数据
 
 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 = "http://localhost:811" # 本地测试
 API_PATH = "/service/pn_data_analysis"
+ENV_TOKEN = "PN_DATA_ANALYSIS_TOKEN"
 
 
 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 +52,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"),