SkillHub Pay Skill 数据中心
Overview
一个部署型、开源的数据中心 skill，让 SkillHub 创作者把 Pay Skill / 专家团的运营数据掌握在自己手里。它包含一个独立运行的 FastAPI 服务（metrics_api.py，默认端口 8101），提供埋点接收、看板渲染、订单库桥接、历史对账与可选 LLM 洞察。零侵入：不修改用户既有网关代码，仅通过 nginx 反代挂在同一域名下。
When To Use
- 用户抱怨"SkillHub 后台看不到完整数据"或想自建数据看板、数据中心。
- 用户要在自有服务器统计 Pay Skill 的下载、激活、调用、付费、收入、退款。
- 用户需要对网关订单做历史对账，且担心"待支付被误判成收入"这类 bug。
- 用户想在发布的 skill 里加轻量埋点（激活/调用/下载），且要求不影响主功能、不收集隐私。
部署流程（服务端）
- 将
scripts/下全部文件复制到用户的网关服务目录（与原有main.py同级即可）。 - 复制
assets/skills.example.json为同目录skills.json，改成用户真实资产（slug/name/category/price_cny）。seed_skills.py读取它做幂等注入。 - 复制
.env.example为.env，强制要求用户替换TRACK_SECRET/DASH_PASS/SYNC_KEY三个占位符为随机强口令（绝不在源码或对话中硬编码真实值）。 - 安装依赖：
pip install fastapi uvicorn（仅这两项硬依赖；Chart.js 走 CDN）。 - 初始化数据库并注入资产：
bash python3 scripts/init_metrics_db.py python3 scripts/seed_skills.py - 启动主服务（独立端口，例如 8101）：
uvicorn metrics_api:app --host 127.0.0.1 --port 8101（生产用 systemd / nohup 常驻）。 - nginx 反代
/api/track、/dashboard、/sync、/api/insight到127.0.0.1:8101。 - 看板访问：
https://用户域名/dashboard，Basic Auth 用户名随意、密码为DASH_PASS。
桥接订单库（让看板看到付费/退款）
看板付费数据来自用户自有网关订单库。让用户在 .env 填 SYNC_CONFIG（先 sqlite3 <订单库> ".schema" 看列名），参考 references/schema.md 第二节。然后用定时任务每 5 分钟调一次：
curl -X POST https://用户域名/sync -H "X-Sync-Key: $SYNC_KEY"
若 SYNC_CONFIG 未填，调用 /sync 会探测候选订单表并返回结构提示，不会误写。slug 解析优先级：skill 列 > result JSON 里的 skill/resource_id > resource 列 > unknown。
在 skill 里埋点
把 scripts/skill_track.py 放进用户每个 skill 目录，入口调用 track_activate(slug) / track_call(slug)。部署环境设 TRACK_URL=https://用户域名/api/track 与 TRACK_SECRET（与 .env 一致）。上报失败静默跳过，不影响 skill 主功能；anon_id 为本地随机 uuid，不收集任何隐私。
历史付款对账
python3 scripts/reconcile_payouts.py --db /path/to/orders.db # 读订单库
python3 scripts/reconcile_payouts.py --file payouts.csv # 或读结算单
python3 scripts/reconcile_payouts.py --reset --db /path/to/orders.db # 纠错：先清 payouts 再重跑
关键：对账使用精确状态判定（见 references/schema.md 第三节），负态黑名单优先 + 正态白名单，绝不靠 "paid" 子串模糊匹配——否则 PENDING_PAYMENT 会被误判为已付、灌入假收入。有 fulfill_status 列时以它为权威完成标志。不确定字段时先不加 --reset 跑一次看报告。
本地自检（无需服务器）
python3 scripts/selftest.py
模拟 4 种订单库结构验证判定逻辑，确认"仅真付订单进入 payouts，待支付/关闭/退款均被排除"。
可插拔 LLM 洞察（默认关闭）
/api/insight 在配置了 LLM_API_KEY + LLM_BASE_URL（OpenAI 兼容）+ LLM_MODEL 后生效；未配置时返回 enabled:false，看板主渲染零依赖、零成本。LLM_API_KEY 须为能调大模型的 key，不是 SkillHub 上架/付费密钥。
资源
scripts/
metrics_api.py— 看板主服务（/api/track /dashboard /sync /api/insight /health）init_metrics_db.py— 建 metrics.db 四表（skills/events/daily_rollup/payouts）metrics_recorder.py— 事件入库函数库（pay/refund/activate/call/download）seed_skills.py— 从 skills.json 幂等注入资产主表skill_track.py— 【skill 端用】埋点上报模块（不进服务端目录）reconcile_payouts.py— 历史付款对账（防误判收入）selftest.py— 本地自检
references/
schema.md— 数据库结构、SYNC_CONFIG 字段含义、付费判定逻辑、部署拓扑、去敏感化说明
assets/
skills.example.json— 示例资产配置（部署时复制为 skills.json 改值）
去敏感化约束（对外开源必须遵守）
- 源码不含任何作者真实姓名、服务器路径、域名、账号；默认路径改为"脚本同目录"，默认域名改为
your-gateway.example.com占位。 - 所有密钥经环境变量注入，绝不在源码硬编码；
.env切勿提交公开仓库。 - 本 skill 已按上述规则脱敏，二次分发时保持即可。
