Activity Special Info Explainer

用于解释活动配置中的 special_info 字段，重点回答下面几类问题：

• 这个字段在当前活动里是什么意思
• 这个字段在哪里被解析、在哪里被使用
• 它的单位可能是什么
• 不配会怎样，配错会怎样
• 迁移旧玩法时哪些字段最危险

该 skill 的目标不是生成完整需求文档，而是生成一份 special_info 字段说明 + 风险提示文档，帮助后续开发、测试和迁移人员正确理解活动特殊配置。

典型场景

• 复用旧活动代码时，不清楚 special_info 每个字段的真实含义
• 遇到 target_amount、reward_rate、super_base、limit_time 这类名字不自解释的字段
• 线上事故后，需要回溯某个字段为什么会影响触发频率或奖励金额
• 准备把一个活动玩法迁移到新活动，想先补齐 special_info 字段认知

历史踩坑案例

案例：阈值字段单位混淆（真实线上事故）

背景：复用之前的玩法代码，配置"触发超级返金的全服累计奖池阈值"

问题：target_amount 字段值填写错误

• 正确含义：全服累计金币阈值 = 15000 金币
• 错误理解：礼物数量 = 2500 个
• 实际填写：2500（把金币数误填成礼物数）

后果：

• 预期：全服合计送出 2500 个礼物触发一次
• 实际：全服合计送出约 416 个礼物即触发一次
• 触发频率是预期的 6 倍

根因分析：

• 开发：复用旧代码时，盲目按照字段名理解含义，没有结合代码分析
• 测试：只做功能层面验证，未验证数值单位是否正确

如何避免：

1. 使用本 skill 生成字段说明文档，查看"候选单位"和"风险等级"
2. 追溯文档中"使用位置"的比较逻辑，确认比较对象是金币还是数量
3. 在测试环境用边界值验证（刚好触发、略小于阈值、略大于阈值）
4. 对于阈值、比例、数量类字段，必须结合代码确认单位

输入

优先支持以下两种输入方式：

方式 1：活动配置文件 + 代码目录

/activity-special-info-explainer file=/path/to/activity.json code_dir=/path/to/wespy-http-go/app/activity/2026/xxx

方式 2：活动 ID + 区服 + 代码目录

/activity-special-info-explainer act_id=6376 region=Q code_dir=/path/to/wespy-http-go/app/activity/2026/xxx

当用户只提供 act_id + region 时：

1. 先调用 fetch-game-config-clean 拉取 namespace=activity 的活动配置
2. 从配置中读取 special_info
3. 再结合 code_dir 进行解释

依赖缺失时的降级策略

如果本地没有 fetch-game-config-clean：

• 仍可使用本 skill，但请改为传本地配置文件：
  • --config /path/to/activity.json
• 或手动指定依赖脚本位置：
  • FETCH_GAME_CONFIG_CLEAN_SCRIPT=/abs/path/to/fetch_config.py

说明：act_id + region 拉配置模式依赖 fetch-game-config-clean；--config 本地模式不依赖该 skill。

如果用户没有提供 code_dir，按以下顺序定位：

1. 检查环境变量 $ACTIVITY_CODE_DIR
2. 兜底尝试当前工作目录下的 ../wespy-http-go
3. 根据活动 ID 搜索代码引用：

   grep -r "<活动ID>" $ACTIVITY_CODE_DIR/app/activity/ --include="*.go" -l
   

精确匹配方法：活动代码目录的 conf/conf.go 或 internal/conf/conf.go 中通常有 ActId = <活动ID> 的常量定义，可用于精确判断候选目录是否匹配：

# 检查候选目录的 conf.go 是否包含目标活动 ID
grep -r "ActId.*=.*5982" /path/to/candidate/conf/ --include="*.go"

如果搜索到多个候选目录，优先选择 conf.go 中 ActId 匹配的目录。

定位后必须先向用户展示并确认：

已定位到活动代码目录：
- 活动目录：app/activity/2026/south_east_asia/spring_festival/
- special_info 解析入口：conf/special_info.go:15
- 解析结构体：SpecialInfoConfig

请确认这是正确的活动代码目录，还是需要指定其他路径？

用户确认后才继续分析。如果用户说不对，请用户提供正确的目录路径。

输出

默认生成一份 Markdown 文档到桌面，命名规则：

~/Desktop/activity-special-info-{act_id_or_name}.md

文档至少包含以下内容：

1. 概览

• 活动 ID / 名称（若可获取）
• 代码目录
• special_info 根字段数量
• 高风险字段数量

2. 字段总览表

每个字段至少输出：

• 字段路径
• 当前值
• 值类型
• 候选单位
• 风险等级
• 主要代码位置

3. 字段逐项说明

每个字段建议按以下模板输出：

## special_info.xxx.yyy

- 当前值：15000
- 类型：int
- 候选单位：金币阈值（推测）
- 风险等级：高
- 解析位置：
  - xxx/conf.go:12
- 使用位置：
  - xxx/service/sale.go:88
  - xxx/hook/sale.go:143
- 字段作用：
  - 用于判断……
- 生效条件：
  - 当……
- 不配置的影响：
  - 可能……
- 配错的影响：
  - 可能导致……
- 迁移注意事项：
  - 从旧玩法迁移时，需确认……
- 建议验证：
  - 用什么量级的数据验证单位和阈值

4. 高风险字段提醒

优先标记以下字段：

• 阈值类：target_amount、threshold、limit
• 比例类：rate、ratio、percent
• 时间类：time、duration、interval
• 数量/金额歧义类：amount、num、count
• 影响发奖频率、返奖频率、奖池触发的字段

执行步骤

步骤 1：获取活动配置

如果用户给的是 act_id + region，先使用 fetch-game-config-clean：

python ../fetch-game-config-clean/scripts/fetch_config.py \
  --namespace activity \
  --region <region> \
  --key <act_id> \
  --env <prod|dev> \
  --pretty

如果用户直接提供本地配置文件，则跳过此步骤。

步骤 2：提取 special_info

• 从活动配置根节点读取 special_info
• 若 special_info 是 JSON 字符串，先反序列化
• 若字段为空，直接说明当前活动未配置 special_info

步骤 3：扫描本地代码目录

重点查找以下内容：

• ParseSpecialInfo(...)
• 解析 special_info 的结构体定义
• 带 json:"xxx" tag 的字段定义
• 读取或比较这些字段的业务逻辑

重点目录：

• conf/
• service/
• hook/
• event/
• cron/
• store/

步骤 4：生成解释文档

将配置值、结构体字段、代码使用位置和风险提示整合成 Markdown 文档。

推荐脚本

优先使用本 skill 自带脚本：

python scripts/explain_special_info.py \
  --config /path/to/activity.json \
  --code-dir /path/to/activity/code

也支持直接使用 act_id + region：

python scripts/explain_special_info.py \
  --act-id 6376 \
  --region Q \
  --env prod \
  --code-dir /path/to/activity/code

如果未传 --code-dir，脚本会按以下顺序自动定位：

1. $ACTIVITY_CODE_DIR
2. 当前工作目录下的 ../wespy-http-go
3. 优先在 conf/conf.go / internal/conf/conf.go 中按 ActId 精确匹配
4. 若仍未命中，再根据 act_id 在 app/activity/**/*.go 中搜索引用

若匹配到多个活动目录，脚本会中断并提示使用 --code-dir 明确指定。

如果传入的 --code-dir 是大目录（例如 app/activity/2026），且同时提供了 --act-id， 脚本会自动按 ActId 收敛到具体活动目录，再执行字段分析。

输出要求

输出结论时，不要只说“字段含义不明确”，而要尽量给出：

• 来自代码的证据
• 推测依据
• 可能的单位
• 可能的故障后果

如果只能做推测，必须明确写出“推测”或“需人工确认”，不要把猜测写成确定事实。

---

前置依赖

本 skill 通过名称调用以下 skill，使用前需确保已安装：

依赖 skill	用途	必须
fetch-game-config-clean	根据 act_id + region 拉取活动配置 JSON	是（方式 2）

环境变量：

变量名	用途	必须	示例
ConfigSecret	配置中心鉴权密钥	是（方式 2）	export ConfigSecret=xxx
ACTIVITY_CODE_DIR	业务代码仓库路径	否（有默认兜底）	export ACTIVITY_CODE_DIR=/path/to/wespy-http-go

区服代码对照表（脚本支持中文名自动转换）：

代码	区服名称	常用别名
C	华语服	国服
T	泰服	泰国
M	马来服	马来西亚、马尼服
P	菲律宾服	菲服
V	越南服	越服
K	韩服	韩国
J	日服	日本
U	美服	美国
B	葡语服	巴西
S	西语服	西班牙
Y	意大利服	-
G	德语服	德国
R	俄语服	俄罗斯
A	阿语服	阿拉伯
Q	土语服	土耳其
O	Jackaroo	-
I	印度服	-
N	巴基斯坦服	-

---

注意事项

1. 单位歧义是最大风险：amount、num、count、target 等字段名无法直接看出是金币、礼物数量还是次数，必须结合代码确认
2. 比例字段注意口径：rate、ratio、percent 可能是百分比、千分比、万分比，看代码中除以的基数
3. 时间字段注意单位：time、duration、interval 可能是秒、毫秒、分钟，看代码中的时间比较逻辑
4. 代码定位失败时：提示用户设置 ACTIVITY_CODE_DIR 环境变量或直接提供路径
5. 报告语言：所有输出使用中文