weplay-config-query
SKILL.md
WePlay 配置读取(ox 通道)
概述
该 skill 从代码中自动解析 namespace/key/path,然后通过 oxAgent 认证通道调用 WePlay 配置中心接口查询配置值和 i18n 文本。
当配置包含 i18n key 时会联动查询对应文案;当配置包含礼物/道具 ID 时会查询对应中文名称。
关键约束
- 支持测试/线上环境切换(默认测试,只有明确线上场景才使用线上)
config/get_key_with_query_path禁止查询system、server、gift、propnamespace- 触发限频(429)时立刻停止后续接口调用
- 当结果中出现疑似礼物/道具 ID 时,仅通过
/lang/search查中文名,不继续展开查礼物/道具配置 - 执行脚本时必须带
--json-output,以便稳定识别错误码和终止标记 - AI 行为约束:如果用户没有提供明确的
namespace/key/path,默认仅基于wespy-http-go和wespy_tcpgo项目代码推导;只有当前对话已明确指定其他代码仓库时,才允许切换到对应仓库推导,不做跨仓库盲搜。该条不是脚本强制限制
终止规则(最高优先级)
- 若脚本输出满足任一条件:
terminal=true、retryable=false、action=STOP_AND_REPLY、或文本包含TERMINAL_STOP,必须立即结束本轮流程并直接回复用户提示,不得再执行任何命令。 - 严禁绕过终止规则:不得拆分区服重查、不得改
namespace/key/path/scene/language重查、不得用额外 Python 脚本做二次查询。 - 命中终止规则后,本轮对话内不得再次执行
query_weplay_config.py。
工作流程
- 获取
namespace/key/path
- 支持两种方式:
- 直接传入
--namespace/--key - 通过代码位置推导(字段访问 -> getter(
GetXXX) ->GetData(NamespaceX, lang)-> 结构体字段 json tag)
- 直接传入
- 也支持混合模式:例如只传
--namespace,由代码推导补全key - 若两种方式都无法确定
namespace/key,提示补充参数或代码定位信息
- 调用配置接口
- 接口:
POST /config/get_key_with_query_path - 认证:按内部约定注入鉴权参数
- 场景:
- 默认
test:https://config-admin-dev-api.weplayapp.com - 明确线上场景才用
online:https://config-admin-api.weplayapp.com
- 默认
- 脚本查询时会默认把
center一并加入regions - 若目标区服返回
namespace not exist,脚本会自动回退使用中心服返回的同一配置 - 支持一次传多个区服,并可通过
query_path让服务端仅返回一级字段或过滤表达式命中的子集 query_path仅适用于非数组配置,且不支持a.b[0].c这类下钻路径;遇到对象根节点下钻路径时,脚本会先用一级字段(如a)做服务端裁剪,再由客户端提取剩余路径(如b[0].c);遇到数组根节点时则完全跳过服务端query_path- 返回
result[],每项包含region和config.value - 10KB 限制校验的是最终返回给模型的提取结果,而不是原始完整配置;目标是避免把过大的结果继续传给模型
- 若命中限频(429 或 frequency limit),立即报错并停止
- 若返回
errorType=CONFIG_TOO_LARGE或errorCode=41301,提示用户“配置过大(>10KB),无法查询/分析”,并停止后续 i18n 与礼物/道具名称联动查询
错误处理(必须遵守)
- 单轮对话内,配置查询脚本最多执行一次;禁止因报错自动重试。
- 若脚本返回
terminal=true或retryable=false,必须立即结束本轮查询流程,不得再次发起任何配置/i18n 查询请求。 - 当
errorType=CONFIG_TOO_LARGE(errorCode=41301)时,直接告知用户“配置过大,当前无法查询,请缩小查询范围后重新发起对话”。 - 当
errorType=RATE_LIMITED(errorCode=429)时,直接告知用户“触发接口限流,请稍后重新发起一次新对话再重试”。 - 可直接使用脚本返回的
userMessage作为对用户的最终回复,不再追加后续查询计划。
- 礼物/道具 ID 中文名查询(按需)
- 若结果中包含数字 ID,优先按前缀判断:
12...优先按礼物查询:namespace=gift,key=gift_name_<id>17...优先按道具查询:namespace=prop,key=prop_name_<id>
- 若优先路径未命中,会再尝试另一类(gift/prop)
- 两类都查不到则标记为非礼物/道具 ID,不再继续查该 ID
- i18n 查询(按需)
- 当取值结果中包含 i18n tag 时,调用
POST /lang/search - 若未指定语言,提示用户输入语言代码(例如
zh_hans/en/ja) - 同样走 ox 认证通道,并在限频时立即停止
执行脚本
python3 scripts/query_weplay_config.py \
--namespace gift \
--key gift_panel_conf \
--scene test \
--regions C,J \
--json-output
常用参数:
--namespace <ns>/--key <key>:直接指定配置项--code-file <path> --line <line>:按代码推导配置项(不传 namespace/key 时使用)--register-files <path1,path2>:显式指定 getter 所在 register 文件--path <path>:优先映射到服务端query_path。服务端仅支持非数组配置的一层字段或过滤表达式;若传入对象根节点下钻路径(如season_time_list[0].start_time),脚本会先传season_time_list给服务端,再在客户端提取[0].start_time;若为数组根节点,则完全由客户端提取--scene <test|online>:默认test,只有明确线上场景时才传online--language <lang>:直接查询 i18n 文本语言,例如zh_hans--lang-namespace <ns>:i18n 查询 namespace(默认同配置 namespace)
需要向用户确认的场景
- 未提供区服
- 结果包含 i18n 且未提供语言代码
- 既未提供 namespace/key,代码解析器也无法解析
- 未提供 getter 文件、namespace 常量文件或结构体定义文件路径
参考
- API 说明与区服代码列表:
references/interfaces.md - 配置查询脚本:
scripts/query_weplay_config.py