Activity Flow Visualizer

根据活动配置生成交互式数据流图，直观展示活动的完整链路。

数据流模型

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   触发器     │────▶│    碎片     │────▶│   消耗点    │────▶│    产出     │
│  Trigger    │     │    Chip     │     │  Consumer   │     │   Output    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

 - 送礼(gift)        - chip_id: 1      - lottery          - 道具(prop)
 - 充值(charge)      - chip_id: 2      - exchange_store   - 金币(coin)
 - 任务(task)        - ...             - direct_purchase  - 头像框(frame)
 - 签到(sign)                                              - 戒指(ring)

使用方式

方式1：指定活动 ID（推荐）

/activity-flow-visualizer act_id=6236 region=J

自动调用 fetch-game-config-clean 获取配置并生成可视化。

参数说明：

参数	必填	说明	示例
act_id	是	活动 ID	6236
region	是	区服代号	C/J/T/A/M/Q/P/O/V/G/U/I/B/N/S/R/Y/K
env	否	环境，默认 prod	prod/dev
code_dir	否	活动代码目录，用于代码扫描	/path/to/activity/2025/xxx

方式2：指定本地配置文件

/activity-flow-visualizer file=/path/to/config.json

读取本地 JSON 配置文件生成可视化，无需配置中心权限。

执行步骤

运行可视化脚本（二选一）：

方式1：从配置中心获取（推荐）

python ${CLAUDE_SKILL_DIR}/scripts/visualize.py \
  --act-id <活动ID> \
  --region <区服> \
  --env <prod|dev>

方式2：使用本地文件

python ${CLAUDE_SKILL_DIR}/scripts/visualize.py \
  --input <配置文件路径>

脚本会自动：

获取/读取配置
解析数据流关系
生成 HTML 可视化
打开浏览器展示

支持的组件

组件	数据流
`send_gift_hooker_v2`	送礼 → 碎片
`charge_hooker`	充值 → 碎片
`tasks`	任务 → 碎片
`collect_chip`	碎片定义
`lottery`	碎片 → 抽奖 → 奖励
`exchange_store`	碎片 → 兑换 → 商品
`rank` + `reward_pool`	排行 → 奖励

可视化说明

节点类型

颜色	类型	说明
绿色	Trigger	触发器（送礼、充值、任务等）
蓝色	Chip	碎片/代币
橙色	Consumer	消耗点（抽奖、兑换、商店）
紫色	Output	产出（奖励、道具、金币）

边标签

+N：产出数量（如送礼获得 +5 碎片）
-N：消耗数量（如抽奖消耗 -10 碎片）
N%：概率（如 30% 概率获得某奖励）

交互功能

拖拽节点调整布局
点击节点查看详情
鼠标悬停显示完整信息
支持缩放和平移

配置校验

生成可视化时会自动检查以下问题：

检查项	说明
孤立碎片	碎片有来源但无消耗点
无源碎片	碎片被消耗但无产出来源
概率总和	抽奖奖池概率是否为 100%
空奖池	抽奖配置但奖池为空

代码扫描增强（需设置 ACTIVITY_CODE_DIR）：

如果碎片在配置中无消耗但代码中有使用，会显示代码位置
扫描关键词：AddChip/SubChip/CostChip 等

输出文件

生成的 HTML 文件默认保存到桌面：

~/Desktop/activity-flow-{act_id}.html

可通过 --output 指定其他路径。文件可直接分享给他人查看（单文件，无需服务器）。

环境变量

变量	必填	说明
`ConfigSecret`	是	配置中心鉴权密钥

代码扫描功能（可选）

通过 --code-dir 参数指定活动代码目录，脚本会扫描代码检测碎片使用情况：

python visualize.py --act-id 5982 --region P \
  --code-dir /path/to/wespy-http-go/app/activity/2025/sea_magic_academy

重要：用户未提供 code_dir 时，只按配置生成可视化，不要猜测代码路径。

注意事项：

请确保本地代码分支是 master 或对应活动的开发分支
扫描结果会补充到验证警告中，例如："chip_1 配置无消耗点，但代码中有 3 处消耗"

依赖

Python 3.6+
requests（从配置中心获取时需要）
网络访问（加载 vis-network CDN）或离线模式

示例

# 查看日服猫咪日活动的数据流
/activity-flow-visualizer act_id=6236 region=J

# 查看本地配置文件
/activity-flow-visualizer file=./my_activity_config.json

# 查看测试服配置
/activity-flow-visualizer act_id=6236 region=J env=dev

# 带代码扫描（增强验证）
/activity-flow-visualizer act_id=5982 region=P code_dir=/path/to/wespy-http-go/app/activity/2025/annual_celebration