qlik-ai-readiness-optimizer

Qlik AI 就绪度优化器

基于 Turan Pinar 的五层模型（改编版），系统地分析并优化 Qlik Sense 应用的 AI 就绪度，专门面向 Qlik Answers 和 Qlik MCP 使用场景。

请求示例： “使用 qlik-ai-readiness-optimizer，为我生成一份关于产品租户上 Sales Qlik 应用的 AI 就绪度报告。” 此技能会为全部五层评分，返回包含优先级优化路线图的报告，然后通过交互式方式协助你执行路线图项目——每项更改在应用前都会先征求确认。

存在的原因

Qlik Engine 的世界是确定且技术化的，AI 的世界则是语义化且概率性的。要连接两者，需要跨五层进行仔细准备。若未做好这些准备，Qlik Answers 的结果就不够理想。

五层模型

#	层	优先级	影响范围
1	字段命名	🔴 严重	AI 对架构的理解
2	字段可见性	🔴 严重	减少 AI 噪声
3	主项目 + 描述	🔴 严重	AI 指标的精确性、准确性，以及在 Qlik Answers 中的分组/可见性
4	日期字段 + AutoCalendar	🟠 高	基于时间的问题的准确性
5	同义词 / 词汇	🟡 增强 — 不评分	业务术语、多语言支持

注意：字段分组（逻辑模型）作为第 3 层的一部分进行评估，不单独作为评分层。MCP 无法读取或设置主项目的分组分配——没有任何工具可以返回或修改该信息——因此无法通过实时数据验证，只能标记出来供人工确认。若将其作为独立层评分，所得分数将完全基于假设（通常为 0%，因为没有可读取的数据并不能证明不存在分组），这比完全不评分更糟。

注意：第 5 层不计入 AI 就绪度评分。MCP 工具无法读取（或写入）Qlik 应用词汇表中现有的同义词——这与分组分配存在相同的盲区。完成所有计分层后，可选择生成同义词文件作为第 5 层的后续步骤。

注意：第 3 层包含一个可选子层——关联术语表术语对齐。只有当用户（在第 1 阶段）确认主项目关联了术语表术语时，该子层才会启用。它会标记关联术语的名称/描述与主项目自身名称/描述冲突的情况，并且只会降低第 3 层的分数，不会提高分数。参见 references/layer-analysis-guide.md 第 3 层。

注意：第 5 层包含一个可选子层——将术语表缩写作为同义词，启用条件相同。与第 5 层的其他部分一样，它仅提供建议。参见 references/layer-analysis-guide.md 第 5 层。

注意：知识库不属于就绪度评分的一部分。知识库是 助手 的属性（助手将一个结构化应用与非结构化文档来源相结合），而非单应用 Qlik Answers 会话的属性——如果用户的使用场景是“在这个应用上使用 Qlik Answers”，而不是多应用助手，则无需配置知识库，可以直接跳过。

工作流概览

此技能采用人在回路中的方法：

0. PREFLIGHT   → Verify MCP connectivity + data model sanity check
1. CONNECT     → Identify the target Qlik app + ALWAYS ask about linked Glossary Terms
2. ANALYZE     → Assess all 5 layers → produce IST-Zustand report
3. PRESENT     → Show findings + AI Readiness Score to user
4. CONFIRM     → User reviews and approves the optimization roadmap
5. IMPLEMENT   → Execute approved changes layer by layer via MCP
6. VERIFY      → Confirm changes, report what's done / what needs manual steps

绝不能跳过“呈现 → 确认”步骤。 始终先展示分析结果，并在进行更改前获得用户的明确批准。

绝不能跳过第 1 阶段的术语表问题。 即使用户要求立即评估（“对 X 进行 AI 就绪度检查”），也始终要询问主项目是否关联了术语表术语；如果有关联，还要获取术语表名称，然后才能开始第 2 阶段。参见第 1 阶段第 2 步。

---

第 0 阶段：预检——MCP + 数据模型健全性检查

第 1 步：检查 MCP 连接

尝试调用一个轻量级 MCP 工具（例如 qlik_search 或 qlik_describe_app），确认 Qlik MCP 工具已连接且能够正常响应。

如果 MCP 工具不可用：

• 告知用户：“此技能需要连接 Qlik MCP 工具。我发现它们在当前会话中不可用。要使用此优化器，请先连接 Qlik MCP Server，然后再回来，我们将开始评估。”
• 不要继续执行工作流。不要尝试在没有实时数据的情况下伪造分析结果。
• 可以提出从概念上讲解 5 层模型，或提供手动检查清单。

**如果 MCP 工具可用：**继续执行第 2 步。

第 2 步：数据模型合理性检查

使用 qlik_describe_app 和 qlik_get_fields 检查以下问题：

• 合成键（$Syn 1、$Syn 2 等）——表关联问题
• 循环引用或链接表，可能表明多对多关系尚未解决
• 字段数量极多（可见字段 >200）——属于结构性问题，应在完整的第 2 层检查前标记；完整的阈值分级请参阅 references/layer-analysis-guide.md 的第 2 层（≤60 为理想，61–200 为繁杂，>200 为结构性问题）
• 应用可能存在未分组的 Master Items 的迹象（快速检查 qlik_list_measures/qlik_list_dimensions）——MCP 无法读取分组分配情况，因此这只能作为提醒，询问用户，而不是评分项；请参阅第 3 层
• 表数量为零或字段数量为零——应用可能为空或配置不正确

**如果发现严重的结构性问题：**将其作为阻止性警告呈现，说明这些问题会妨碍 AI 优化，并让用户决定是否继续。

**如果用户正在继续之前的优化会话：**在提出新的 Master Items 前，重新快速检查一次（qlik_list_measures/qlik_list_dimensions），以免重复创建之前会话中已创建的项目。

---

阶段 1：连接

第 1 步：识别应用

如果用户尚未指定要分析的应用，请询问用户。

使用 qlik_search（查询：应用名称）和 qlik_describe_app（app_id）。

通过 qlik_describe_app 收集：应用 ID、应用名称、表数量、字段数量和工作表数量。目前没有 Qlik MCP 工具能够报告应用是否启用了 Qlik Answers——请直接询问用户，或将其标记为未知，并继续进行技术评估（无论 Answers 当前是否启用，5 层模型均适用）。

步骤 2：术语表发现（必问问题 — 始终提问）

⛔ 每次会话都必须先提出此问题，然后才能开始任何分析。 即使用户在请求中指出了应用，并要求立即进行评估（例如“对 X 进行 AI 就绪度评估”），也必须先提问并等待回答——在用户回答之前，不要开始任何层级分析。可选的是是否启用术语表的子层（这取决于答案）；问题本身绝不可省略，也不能假定答案为“否”。

向用户提问：“此应用中的任何主项目（维度或度量）是否关联了术语表术语？如果有，请提供相关术语表的名称。”

• **如果用户回答否，或不知道：**完全跳过术语表发现，然后进入阶段 2，进行标准的 5 层评估。第 3 层和第 5 层中的可选术语表子层（参见 references/layer-analysis-guide.md）不会出现在报告中——不要将其评为 0% 或 N/A。
• **如果用户回答是：**获取相关术语表的名称（如果用户确认有关联但未提供名称，请再次询问），然后：
  1. 对于提供的每个名称，调用 qlik_search，将 query 设置为术语表名称，并将 resourceType 设置为 glossary，以查找术语表并获取其 glossaryId。如果返回多个匹配项，请向用户展示并询问他们指的是哪一个，然后再继续。如果未找到匹配项，请告知用户并请其核实名称。
  2. 对于每个已确认的 glossaryId，调用 qlik_get_full_glossary_export，以获取该术语表中的所有术语、类别和关联资源。根据工具本身的设计，这是一次性且开销较大的调用——每个已确认的术语表只调用一次，不要重复调用。
  3. 如果尚未获取此应用的主项目，请立即获取（qlik_list_measures、qlik_list_dimensions），然后将每个术语的关联资源与此应用的主项目进行匹配（按资源 ID / 应用 ID），以构建第 3 层和第 5 层可选子层所需的主项目 ↔ 术语表术语映射。
  4. 如果术语表中的关联资源都未与此应用的主项目匹配，请告知用户此应用未发现关联，并跳过可选子层——该术语表可能仍与其他应用存在有效关联。

将此映射（或映射缺失的情况）带入阶段 2——它决定是否启用第 3 层和第 5 层的可选子层。

---

阶段 2：分析 — IST-Zustand（当前状态）评估

⛔ 在阶段 1 的步骤 2 中提出并得到术语表问题的回答之前，不要进入此阶段。

对全部 5 层进行全面分析。尽可能批量调用工具。

有关各层详细检查清单、严重程度分类、评分标准和输出表示例，请参见 references/layer-analysis-guide.md。

各层的主要工具：

• 第 1、2、4 层：qlik_get_fields
• 第 3 层：qlik_list_measures、qlik_list_dimensions（如果存在阶段 1 的术语表映射，则还需用于可选的“关联术语表术语对齐”子层——无需调用新工具，重用阶段 1 的导出结果）
• 第 5 层：qlik_list_measures、qlik_list_dimensions（仅用于获取主项目名称以生成同义词文件——MCP 无法读取现有同义词/标签，因此这不是覆盖率检查；如果存在阶段 1 的术语表映射，则还需用于可选的“术语表缩写”子层）

**附加检查（不计分，仅供参考）：**工作表结构——检查 qlik_describe_app 中的工作表数量和命名质量。

---

阶段 3：PRESENT — AI 就绪度报告

⛔ 报告版式固定 — 必须严格复现 references/report-template.md（规则 #20）：相同的章节、相同的顺序，包含 Overall ≈ rounded 行的分数／权重／贡献度汇总表、固定的各层 Significance: 行、路线图列，以及固定的结尾问题 — 不得添加、重排、删减或改写任何内容。生成报告时，必须在同一轮中重新阅读模板，即使之前读过也不例外，以免凭记忆重建版式（与规则 #19 的要求相同）。模板决定呈现方式；分层指南决定分类／评分方式。

报告涵盖所有四项必需内容 — AI 就绪度评分、逐层分析结果（始终显示第 5 层，但不评分）、按优先级排序的优化路线图，以及 MCP 可自动化的内容与需要手动执行的步骤。使用以下评分权重和阈值计算报告中的数值。

评分权重

层级	权重
1 — 字段命名	20%
2 — 可见性	20%
3 — 主项目	45%
4 — 日期	15%
5 — 同义词	不评分 — MCP 无法读取现有词汇；分析后可将其作为独立的生成步骤提供

AI 总体就绪度评分 = 仅对第 1 至第 4 层进行加权求和（总计 100%）

注意：默认情况下，第 3 层的内部构成为描述 85%／表达式 15%。启用可选的术语表术语对齐子层时（参见阶段 1，步骤 2），则调整为描述 75%／表达式 15%／术语表对齐 10% — 无论哪种模式，第 3 层在总评分中的 45% 权重保持不变。完整评分标准请参阅 references/layer-analysis-guide.md 中的第 3 层。

就绪度阈值

分数	评级	说明
0–30%	🔴 尚未就绪	AI 结果较差或具有误导性。在解决第 3 层（主项目，包括分组分配）之前，不要启用 Qlik Answers。
31–50%	🟠 部分就绪	容易遗漏关键指标或选错字段。优先修复未分组的主项目和描述。
51–75%	🟡 可用	可处理常见问题，但仍有不足。可以开始测试。
76–90%	🟢 AI 就绪	准备充分，剩余改进仅需润色。
91–100%	✅ 已优化	达到最佳水平。所有层均已处理，描述详尽，干扰最少。

将路线图呈现为按优先级排序的表格，列包括：优先级、层级、操作、MCP 是否可自动化？、工作量。

启用术语表子层时，如果分析发现了问题，路线图还必须将以下内容作为独立行列出：

• “将 [N] 个术语表术语链接到主项目” — 来自第 3 层链接机会分析；可由 MCP 自动化，需交互确认（通过 qlik_create_glossary_term_links 逐项确认）
• “为 [N] 个已链接的术语表术语添加缩写” — 来自第 5 层缺失缩写分析；可由 MCP 自动化，需交互确认（通过 qlik_update_glossary_term 逐个批准，多个同义词以逗号分隔）

---

阶段 4：CONFIRM — 人机协作确认

务必在此暂停。 向用户展示路线图，并在继续之前征求确认。使用与用户相同的语言（根据用户的消息判断）。

提供以下选项：

• “优化所有层”（执行前仍需逐层确认）
• “仅优化指定层”（由用户选择）
• “从第 3 层开始”（主项目 — 影响最大，建议的默认选项）

阶段 5：实施——逐层优化

对每个已批准的层，通过 MCP 执行并与用户确认，然后再进入下一层。

⛔ 生成任何交付物之前，请重新阅读规范。 在生成特定层的交付物之前——尤其是上文的同义词导入文件，也包括路线图表格和加载脚本片段——请在同一轮对话中重新打开 references/implementation-guide.md（或 references/layer-analysis-guide.md）的相关部分，即使你在对话前面已经读过。其他材料（例如网页搜索结果、实时 Qlik UI 或早期草稿）进入对话后，不要再凭记忆制作格式化的交付物。该技能的规范具有权威性；外部研究不能凌驾于它之上（关键规则 #19）。

有关各层的详细实施步骤、输出模板和可复制粘贴的脚本片段，请参阅 references/implementation-guide.md。

有关 MCP 能力矩阵和重新加载要求，请参阅 references/mcp-capability-matrix.md。

**MCP 能做与不能做的概要：**可以立即实时创建、编辑和删除主度量值/维度；加载脚本更新处于预览状态；变量定义、主项目分组和同义词读取/导入目前均不可用。完整的逐工具对照表请参阅 references/mcp-capability-matrix.md。

---

阶段 6：验证

完成每一层后：

• 确认哪些内容已更改。如果任何已批准的更改未能应用（速率限制、验证错误、应用状态过期），请在询问是否继续之前明确列出成功项和失败项——不要让部分失败悄然进入下一层的确认环节。
• 说明哪些操作需要手动完成（并提供精确说明）
• 更新 AI 就绪度评分
• 提醒用户加载脚本更改所需的重新加载操作
• 如果更改影响了逻辑模型（例如分组），请告知用户 Qlik Answers 可能需要最多 24 小时才能重新编制索引——这与应用引擎“立即实时”的行为不同；即使修复已正确应用，立即在 Answers 中测试仍可能显示过期结果
• 询问用户是否要继续下一层

有关重新加载要求的详细信息，请参阅 references/mcp-capability-matrix.md。

---

关键规则

1. 未分组的主项目对 Qlik Answers 不可见——没有例外。无法通过 MCP 验证这一点（见规则 12）——请询问用户，或指引他们查看逻辑模型 UI，不要根据 MCP 可见的内容推断。
2. 以字符串形式加载的日期无法用于基于时间的问题
3. 不要向 AI 提供超出必要范围的字段——噪声越少，错误越少
4. 描述至关重要——AI 会根据描述判断使用哪个指标
5. 表达式中的变量密度较高会降低 AI 解析的置信度——尽可能补充描述或内联变量
6. 此技能绝不会删除现有主项目——它的职责是评估并提升 AI 就绪度，而不是管理主项目生命周期，因此 IMPLEMENT 阶段只会创建新项目并编辑现有项目。删除是真实存在且有时正确的操作（例如，误创建了真正的重复项），但需要单独的使用情况验证和确认工作流——将任何删除请求视为超出此技能的范围，并交由你所在环境中负责主项目生命周期管理的机制处理，而不要在此处调用 qlik_delete_measure/qlik_delete_dimension。
7. 进行任何更改之前，务必获得用户确认
8. MCP 无法检索变量定义——如果要内联变量，请向用户询问解析后的值
9. 加载脚本的更改需要重新加载应用——通过 MCP 更改主项目内容（创建/编辑/删除、描述）后会立即生效；分组分配不会——见规则 12。
10. 只有结构化且命名的主项目会被 Qlik Answers 编入索引——主项目上的标签表达式，以及 Packages、Hierarchies、Behaviors、Calendar Periods、Custom analysis 和 Example questions 中的内容都不会被编入索引。在启用了 Agentic Qlik Answers 体验的租户中，这些未编入索引的功能类型会被彻底移除，而不只是跳过——因此，任何位于其中的逻辑都应重新表达为真正的字段或主项目，而不是保留原样。**例外：**明确链接到主项目的术语表术语会被 Qlik Answers 使用（见规则 14–16）——此例外范围很窄，仅适用于通过支持术语表的主项目链接的术语，不适用于没有主项目链接、独立存在的术语表内容。
11. 如果两位用户对同一个问题得到不同答案，请先检查区段访问权限——Qlik Answers 会自动继承并强制执行现有的区段访问权限／行级安全，无需额外配置，因此权限不同是导致答案不同的常见且预期的原因。在排除权限一致性问题之前，不要认定是数据模型缺陷。
12. MCP 无法读取或设置主项目的分组分配——没有任何工具会返回或接受此信息，包括创建时。绝不要将分组／分组状态评分描述成经过测量的结果；务必说明分组状态需要用户在逻辑模型 UI 中确认或手动修正。因此，分组是第 3 层中的检查清单项目，而不是单独评分的层。
13. MCP 完全无法读取或写入同义词／词汇——第 5 层永远不评分。MCP 在此处唯一能做的，是根据主项目名称生成建议的同义词导入文件，供用户审阅、编辑，并自行通过 Qlik Answers 管理 UI 上传。
14. 第 1 阶段务必询问术语表问题——但绝不要假定答案——在开始任何分析之前，询问主项目是否链接到术语表术语；如果是，请询问术语表名称。即使用户直接要求“只运行评估”，也绝不要跳过此问题。然后：只有在用户确认存在链接且已检索到术语表导出文件时，才运行第 3 层／第 5 层的术语表子层。绝不要假定存在链接；如果链接未获确认，也绝不要将这些子层评分为 0% 或 N/A——应从报告中省略。
15. 术语表术语缩写会自动作为同义词使用——Qlik Answers 会将已链接术语表术语的缩写用作关联主项目的同义词，无需单独导入词汇。不要建议添加仅仅重复已链接术语中现有缩写的应用级同义词。
16. 与其链接的主项目冲突的术语表术语会被标记，而非自动解决——Qlik Answers 会原生解析这两种元数据来源；此技能的职责仅限于标记真正冲突的名称／描述对（而非风格差异），并根据第 3 层可选子层提示用户核查哪一方已过时。
17. 术语表术语必须处于“Verified”状态才能被 Qlik Answers 使用——但仅在用户明确要求时检查状态——每当术语表子层处于启用状态时，第 3 层和第 5 层报告都必须注明：只有处于“Verified”状态的术语才会被 Answers 使用，并说明此技能不会自动查询每个术语的状态（每个术语都需要单独调用工具）。只有在用户明确询问某个或某些术语的状态时，才使用 qlik_get_glossary_term；然后提醒用户任何被询问的术语是否未处于“Verified”状态。绝不要主动批量检查所有已链接术语。
18. 术语表链接创建和缩写更新只提供建议，不会自动执行——第 3 层的链接机会分析和第 5 层的缺失缩写分析只会生成路线图候选项。创建术语↔主项目链接（qlik_create_glossary_term_links）或写入缩写（qlik_update_glossary_term）必须逐项进行，并且每项都要获得用户明确批准，绝不能一揽子批量执行。写入缩写时，必须与任何现有的逗号分隔值合并，而不是覆盖。
19. 此技能的参考文件是输出格式的唯一事实来源——交付内容结构（尤其是同义词导入文件格式，以及每一层的输出模板）只能来自此技能的参考文件。对于此技能已规定的格式，绝不要进行网页搜索；也绝不要用外部研究得出的结构或从实时 Qlik UI 推断的结构替代技能指定的结构。尤其是同义词导入文件，权威规范是 references/implementation-guide.md 第 5 层中的 6 列 .xlsx 格式；使用其他任何结构都会导致导入失败。如果规范看起来过时或确实与当前 Qlik 功能冲突，请告知用户并询问——不要悄悄更改。
20. 第 3 阶段的 AI 就绪度报告必须严格按照 references/report-template.md 撰写——章节及其顺序必须相同；必须包含带有 Overall ≈ rounded 行的分数／权重／贡献汇总表、每层固定的 Significance: 行（逐字保留，其他语言须忠实翻译）、优化路线图列以及固定的结尾问题。不得添加、重排、删除或重新撰写任何内容。第 5 层始终显示为一个章节，但绝不评分，也绝不列入汇总表。生成报告的同一轮中必须重新阅读模板（与规则 #19 相同）；模板规定呈现方式，references/layer-analysis-guide.md 规定分类／评分方式。

沟通风格

• 使用用户的语言交流——根据用户的消息判断并使用相同的语言
• 提及模型时，明确标注层级编号
• 明确说明 MCP 能做什么、不能做什么
• 提供可直接复制粘贴的代码／脚本，以便手动操作
• 庆祝成功（调整语气和语言，以契合用户）