Indicator Query

数据资源说明（indicator）

本 Skill 基于 indicator 资源（一个个预置指标的 API）执行查询：

• 内容覆盖度：数量较少，主要覆盖占比、比例、均值等有上级组织对比分析需求的指标。
• 授权特点：授权角色有限，主要授予 BP 相关角色。行权限在负责组织范围基础上，支持上级组织指标查询——如负责某部门的 BP，可通过本路径查询上级线、BG 的对比数据（这是相对 table/SQL 的关键优势）。
• 查询特点：支持基于每个指标预定义好的维度进行条件查询或分组统计，相比 SQL 查询更简单、高效。

当问题涉及「向上对比 / 本组织范围外的统计」而 table 行权限不足时，应优先选择本路径。

slang_query（业务术语）的使用边界

• 指标整体统计口径无需查询术语：indicator 每个指标的统计口径（分子/分母定义、计算公式，如"离职率"的分子分母如何界定）已由其 api_code 在系统内封装完毕，直接调用即得到准确结果，不需要像 hr-data-sql-builder 那样再调用 slang_query 去确认整体统计口径。
• 仅用于参数取值环节的业务术语映射：当 Step-3 处理某个参数的值时，若用户问题中使用的是业务简称/俗称（而非维度表规范码值本身），应调用 slang_query 查询该术语定义，据此确定其对应的规范维度值，再进行取值匹配——例如用户问"校招离职率"，"校招"本身不是 recruitmentType（招聘类型）维度下的字面码值，需先用 slang_query 确认"校招"对应"校园招聘"，再以"校园招聘"去匹配维度取值，而不是直接拿"校招"两字去模糊匹配码值表，避免匹配不准。

指标权限项编码对照表

各指标在权限中台对应有独立的权限项编码，可用于在已知用户身份的情况下核实用户是否拥有对应指标的访问权限：

当前尚无独立的权限项编码查询工具，本表暂作为参考映射维护；待具备基于编码核实用户权限的查询能力后，可将其补充为 Step-1 指标匹配后的前置权限判断依据。现阶段指标的实际授权情况仍以 Step-6 对 rowPowerResult/checkPowerResult 的实时校验结果为准。

指标查询工作流

加载本 Skill 后，严格按以下工作流顺序执行，禁止跳步。

Step-1：读取指标列表 + 匹配（含指标簇识别与候选排序）

执行动作：

1. 检查 MCP 服务 hr_data_service_v1 是否可用（不可用 → 引导用户连接，终止）
2. 读取 MCP resource data-view://indicators（可用指标列表），将用户问题与返回的 indicator_name / indicator_definition 语义匹配，找到合适的指标及其 api_code、table_name
3. 通过 data-view://indicators/{api_code} 获取该指标的详细参数定义（parameters[]）

⚠️ 匹配范围要宽松，不要用字面关键词卡死：语义匹配应基于 indicator_name/indicator_definition 的含义判断，而非要求用户问题逐字命中指标名。例如"离职率""流失率"等问题应命中名为"离职率"的指标，不要求问题中出现"率"以外的额外字面提示词。若第一次匹配为空，应再检查是否因用词差异（同义词、简称）导致漏判，而非直接判定无匹配。

分支：

• 无任何匹配 → 终止本 Skill，切换到 hr-data-sql-builder
• 匹配成功，且仅一个候选 → 记录 api_code、table_name、parameters[]，并对照「指标权限项编码对照表」记录该指标的权限项编码（供参考，暂不作为前置判断依据），进入 Step-2
• 匹配成功，且存在「指标簇」（同一核心指标的多个版本） → 执行下方「指标簇识别与候选排序」，产出有序候选列表，取列表首位进入 Step-2；其余候选保留供 Step-6 权限失败时依次重试

指标簇识别与候选排序

识别规则：若语义匹配命中的多个指标，其核心统计口径相同、仅命名上存在"基础版"与"扩展版"关系（扩展版名称通常在基础版名称后追加括注，如"XX（带梯队分析）"），则判定为同一「指标簇」。典型示例（参见「指标权限项编码对照表」）：

• 离职率 / 离职率（带梯队分析）
• 离职人次数各维度占比 / 离职人次数各维度占比（带梯队分析）

候选排序规则：

1. 若用户问题明确提及扩展版对应的额外维度语义（如提到"梯队""九宫格"等）→ 扩展版排在候选列表首位，基础版排第二。
2. 若用户问题未提及扩展版的额外维度语义 → 基础版排候选列表首位（维度更通用、权限覆盖角色通常更广），扩展版排第二作为备选（当基础版权限失败时，扩展版的更大维度集合仍有机会覆盖同一统计需求）。
3. 两个候选均保留在列表中，不因排序丢弃任一候选。

产出：candidates = [{api_code, table_name, parameters[]}, ...]（按上述规则排序），进入 Step-2 时仅处理 candidates[0]，并记录 triedIndex = 0 供 Step-6 使用。

Step-2：理解用户意图

执行动作： 分析用户问题，提取三类信息：

1. 统计范围：在什么范围内计算？
   → 组织（如"人力资源平台部"）、时间（如"2025年Q1"、"当月"）
   
2. 筛选子集：用户关心的是哪个子集？
   → 如"校招员工""女性""T9以上"
   → 若无特定子集 → 标记为"无筛选"

3. 分组维度：用户是否要按某维度拆分查看？
   → 识别关键词："各XX""按XX""XX分布""XX维度"
   → 如"各部门""按职级""各离职原因"
   → 若无分组需求 → 标记为"无分组"

产出： 三元组（范围、筛选、分组）的自然语言描述

Step-3：逐参数处理

执行动作： 读取 MCP resource data-view://dimensions。然后遍历 Step-1 中匹配指标的 parameters，对每个参数一次性完成取值、定角色、放位置三件事。

跳过 staffId（工具自动注入）。

对每个参数，执行以下流水线：

─── ① 该参数与用户问题有关吗？ ───
    特殊参数优先判断（命中即按对应规则处理，不进入下方"无关/相关"通用判断）：

    a) org（组织）参数：必填，固定对应维度表 `a370651772b848cfa5dc7ef602243d69`
        → 跳过本步其余判断及①.5，直接进入②按「取值优先级」取值

    b) 默认口径参数（managerUnit / staffSubType）：
        IF 用户问题中未显式提及该参数对应内容（即未主动指定管理主体/员工子类型，如未说"外包""子公司"等）：
            → 直接注入固定默认值：managerUnit = ["腾讯集团本部"]，staffSubType = ["正式聘用制"]
            → 跳过①.5、②（默认值为固定字符串，无需术语映射/查库），带值直接进入③
            → 进入③后按该参数自身的 common_query / is_required 属性走正常分支判断（可能落入 commonParam，也可能落入角色判断），
              **唯一强制要求**：若最终落入角色判断分支，必须归为角色A"范围"，且不得被③末尾"用户没有提到的非必填参数→跳过"兜底规则跳过（该值已由①强制赋值，视同"已有值"，不属于兜底规则适用范围）
        ELSE（用户显式提及，要求放开默认口径）：
            → 视为用户已提供该参数取值，正常进入①.5→②→③（按用户实际指定值处理，不再套用默认值）

    其余参数，按下方通用规则判断：
    无关且非必填 → SKIP
    无关但必填   → 使用 default_value（无则向用户确认）

─── ①.5 参数值是否为业务简称/俗称？（先于②取值） ───
    IF 用户问题中该参数对应的值是业务简称/俗称（非维度表规范码值本身，如"校招""T9+"）：
        → 调用 slang_query 查询该术语定义，确认其对应的规范维度值
        → 用规范值替换简称，再进入②按规范值取值/匹配
    ELSE（用户已用规范表述，或该参数是org/时间等无需术语映射的类型）：
        → 跳过，直接进入②

    ⚠️ 此处 slang_query 仅用于**参数取值的术语映射**，不用于确认指标整体统计口径
      （指标口径已由 api_code 封装完毕，无需重复查术语定义，详见文首「slang_query 的使用边界」）

─── ② 取值 ───
    IF parameter_type == "List<String>":
        绝对禁止用中文名！
        在 data-view://dimensions 中找 dimension_code == parameter_code 的记录
        取 sql_script + 添加 WHERE 条件匹配用户关键词（若①.5已转换为规范值，用规范值匹配）
        调用 starrocks_query 执行 → 提取 ID
        值 = ["ID"]（数组格式）
    
    ELSE (string/date/int/Float):
        先在 data-view://dimensions 中查找 dimension_code == parameter_code 的记录
        IF 找到且有 sql_script 或 dimension_desc:
            → 参考 sql_script 查询可用值，或参考 dimension_desc 了解取值规则
        ELSE:
            → 从用户输入直接提取
        值 = "字符串" 或 数字

        ⚠️ 若该参数为 org（组织）类型（已在①中确认跳过其余判断，直接进入本步取值）：
        indicator API 内部使用 8 位补零组织码（orgId8，如 "00002234"）。

        取值优先级（命中即停，不再往下走）：
        1. **会话级缓存**：本轮对话中此前已解析过的"组织名→orgId8"映射，直接复用（首次通过②③级拿到值后即记入此缓存，仅本轮对话有效；候选簇重试时同样优先查此缓存，见 Step-6）。
        2. **静态缓存表**：见文末「附录：组织ID静态缓存表」（覆盖顶级节点+9个BG/职能线+40个线级/子公司实体，共50个组织），命中直接用缓存ID，无需查库。
        3. **查库**：①②均未命中时（如具体部门/中心/组等更细粒度组织），才查 `sql_script` → `starrocks_query`；若问题涉及**多个**组织名，须**合并为一次SQL**批量取值（`IN` 精确匹配或多个 `LIKE` 以 `OR` 拼接），禁止逐个查询；查得结果记入会话级缓存供后续复用。

        无论通过以上哪一级拿到的原始ID，若来源非 orgId8 格式（如来自 `get_current_user_data_permission` 返回的 dataScopes.Org 短码"2234"），必须先左侧补 "0" 转换为8位后再赋值（"2234" → "00002234"）。特殊值 "Org-All"、"global" 按原样处理，不参与补零。

─── ③ 定角色 + 放位置 ───
    IF parameter.common_query == true:
        → commonParam[code] = 值（结束）

    ELSE IF parameter.is_required == true AND (parameter.fenzi_query == true OR parameter.fenmu_query == true):
        → 必填参数优先规则，跳过下方角色判断：
        → numeratorParams[code] = 值
        → denominatorParams[code] = 值（与分子同值）

    ELSE 根据该参数在用户问题中的角色：
    
        角色A "范围"（org、时间、managerUnit、staffSubType 参数 — 界定统计范围）：
            → numeratorParams[code] = 值
            → denominatorParams[code] = 值
        
        角色B "筛选"（用户要看占比的那个子集，如招聘类型、性别）：
            → numeratorParams[code] = 值
            →（不放 denominatorParams）
        
        角色C "分组"（用户说"各XX"要按此维度拆分）：
            前置校验：parameter.group_by_flag == true？
            校验通过 → groupByList.push(code)
            同时根据指标类型决定是否也作为范围条件放入分子分母

    ※ 角色判断规则：
    - common_query==true 的参数 → 无需判断角色，直接放 commonParam
    - is_required==true 且 fenzi_query/fenmu_query 任一为 true → 分子分母都放且同值，不进入角色判断
    - org、时间、managerUnit、staffSubType 参数 → 永远是"范围"（后两者的默认值注入已在①处理，此处不受"用户没提到→跳过"兜底规则影响）
    - 用户没有提到的非必填参数（不含 managerUnit/staffSubType，二者已由①保底注入默认值） → 跳过
    - 占比/率类指标中，用户提到的人群特征（校招/女性/T9等）→ "筛选"
    - 用户说"各XX"对应的维度 → "分组"

💡 在本流程中使用 starrocks_query 查维度表是正常步骤，不是切换到 hr-data-sql-builder。

产出：

{
  "commonParam": { ... },
  "numeratorParams": { ... },
  "denominatorParams": { ... },
  "groupByList": [ ... ]
}

Step-4：自检

逐条确认，全部通过才可调用：

1. 所有 List<String> 值为 ID 格式且用 [] 包裹？ → 否：回 Step-3 ②
2. 所有 is_required=true 参数已有值？ → 否：补充
3. is_required=true 且支持分子/分母查询的参数，是否已同时放入 numeratorParams 和 denominatorParams 且值相同？ → 否：补齐两边
4. 占比/率类指标：用户的筛选子集条件只在分子、未误入分母？ → 否：从 denominatorParams 移除
5. groupByList 中的 code 在 parameters 中 group_by_flag=true且是否需要分组查询？ → 否：修正
6. 未包含 staffId？ → 否：删除
7. org 类型参数是否已转换为8位补零格式（orgId8），而非来自权限元数据的短码直传？ → 否：按补零规则转换后再赋值
8. **默认口径已注入？**指标若支持 managerUnit/staffSubType，是否已注入默认值 ["腾讯集团本部"]/["正式聘用制"]（或用户已显式放开）？ → 否：补注入
9. 分子分母键名对称校验？ numeratorParams 与 denominatorParams 中"范围"类参数的键名必须逐字一致（严防把 managerUnit 误写成 managerType、flowInBeginDate 写错等 typo 只污染一侧导致口径不对齐）。逐一比对两侧的 key 集合是否完全相同、同名 key 的值是否一致。 → 否：修正拼写并对齐两侧

Step-5：调用 indicator_query

调用工具: indicator_query
参数:
  apiCode = Step-1 的 api_code
  queryParams = JSON.stringify(Step-3 产出的对象)
  userQuestion = 用户当前问题原文

Step-6：处理返回结果

说明：本步骤（尤其 indicatorPowerResult/checkPowerResult/rowPowerResult 判断）是 indicator 权限校验的唯一实时验证点——因 indicator 授权范围目前缺乏独立的前置查询工具（参考「指标权限项编码对照表」，待具备基于编码核实权限的能力后可补充为前置判断依据），故权限是否可用需通过实际调用结果确认。三者任一为 false 即代表探测到当前候选指标的真实权限边界，但不代表整条 indicator 路径不可行——若 Step-1 识别出该问题命中「指标簇」（存在未尝试的其余候选），必须先切换候选重试，簇内全部候选权限失败后才进入 Step-7 降级。

IF statusCode == 200 AND data.data 非空非null:
    → 表格展示 + 说明口径 + 洞察 → 结束

IF statusCode != 200:
    → 读 message，修正参数，回 Step-5 重试1次
    → 仍失败 → 走「候选簇重试判断」

IF statusCode == 200 BUT data.data 为空/null:
    → 检查 List<String> 参数是否误用了中文名？
      是 → 回 Step-3 ② 查维度表获取 ID，再回 Step-5
    → 检查 indicatorPowerResult / checkPowerResult
      false → 走「候选簇重试判断」
    → 重试1次仍为空 → 走「候选簇重试判断」

单个候选最多重试 1 次，禁止循环。

候选簇重试判断（权限失败/查询失败后，先于 Step-7 执行）

IF candidates 中存在 index > triedIndex 的未尝试候选:
    → triedIndex += 1
    → 取 candidates[triedIndex] 的 api_code / table_name / parameters
    → 回 Step-3 重新完成参数映射，但**仅需处理"新候选相对上一候选新增/不同的参数"**
      （同簇候选的 org、时间等"范围"类参数通常完全相同，直接复用上一候选已解析的值/已解析ID，
       不要重新查库；仅新候选独有的参数，如扩展版多出的"梯队"维度，需要新走一次①②③流水线）
    → 回 Step-5 调用
    → 结果按本 Step-6 规则重新判断（该候选同样只重试1次）
ELSE（候选簇已全部尝试，或本就只有单一候选无簇）:
    → 记录本次探测到的权限/查询失败原因（用于最终告知用户）
    → 进入 Step-7 降级

❌ 禁止在候选簇尚有未尝试候选时，就以"无权限"为由提前终止流程并直接告知用户；必须遍历完候选簇才可判定 indicator 路径不可行。 💡 同簇候选参数复用与「会话级动态缓存」共享同一份"组织名→orgId8"映射，无需重复维护。

Step-7：降级到 hr-data-sql-builder

触发条件： Step-6「候选簇重试判断」确认——候选簇（含单候选场景）已全部尝试且均失败。

执行动作：

1. 取最后一次尝试候选的 table_name（数据底表）
2. 切换到 hr-data-sql-builder，指定目标表为 table_name
3. 基于用户原始需求构建 SQL 并执行
4. 合并输出：无论 SQL 执行结果是成功、为空、还是脱敏，均需与"indicator 侧各候选的失败原因"合并组织成一份连贯回答呈现给用户，不要仅停留在"指标无权限"这一句就结束——SQL 兜底结果是本次回答的必要组成部分，而非可选项。

❌ 禁止未走完 Step-6「候选簇重试判断」就直接写 SQL。 ❌ 禁止在给出 SQL 结果前，先单独把"指标无权限"作为最终答案发给用户；两者必须合并为一次完整回答。

附录：组织ID静态缓存表（orgId8格式，Step-3②取值时直接查此表，命中无需查库）

覆盖范围：腾讯公司顶级节点、9个一级BG/职能线、40个线级/子公司实体，共50个组织。

匹配规则：用户提到"腾讯公司/全公司/集团整体" → 用 OA000001；提到BG/线/子公司的全称或简称（如"CSIG"、"云与智慧产业事业群"、"腾娱"）→ 模糊匹配上表「组织名称」列命中对应ID。

数据来源与维护：BG/职能线数据经 starrocks_query 实查组织维表 a370651772b848cfa5dc7ef602243d69 核实。