analysis-plan-builder

---

设计原则：行动优先

用户发出分析请求后最差的体验是"agent 一连串提问、什么都没做"。本 skill 要求：先收集上下文，再规划，最后根据信息充分性决定立即执行还是反问。 用户能看到信息不断收敛、分析在推进，同时保留随时打断纠偏的能力。

---

前置条件

开始规划前，确认以下信息已就绪：

• 用户问题的任务类型（如 BI 业务分析、数据探索、统计建模等）

Step 1: 上下文构建（Phase 1 — Context Gathering）

收集和补充构造分析计划所需的信息。本步骤应尽早执行，在向用户提问之前先通过工具获取尽可能多的上下文。

1.1 可用资源确认

确认当前可用的资源：

• 用户提供的数据文件或表
• 数据获取工具 / API
• 静态的域知识包
• 可获取业务领域模型的接口（后文称"语义层"），即能查询指标、维度及其关系的服务或工具

如果工具列表中包含 MCP 语义层工具（search_context / get_domain_overview / list_metrics 等），立即调用以获取域上下文：

• 推荐首个调用：search_context(query=用户原始问题, domain=识别出的业务域) — 一次调用返回匹配的指标、口径、数据集和相关维度。
• 补充调用 get_domain_overview(domain) 了解域全貌（当 search_context 返回不足时）。

实时向用户同步发现：将 MCP 返回的关键信息（指标名、口径定义、可用维度、数据表）以简洁文本输出到 assistant 消息。用户可随时打断纠偏。

如果没有 MCP 工具可用 → 跳过语义层调用，直接进入 1.2。

1.2 按任务类型补充上下文

• BI 业务分析 → 继续 1.3 ~ 1.5
• 其他任务类型（数据探索、统计建模等）→ 继续 1.6

---

BI 业务分析

若用户已明确指定了分析的指标（如"分析 DAU 变化"），可跳过 1.3 和 1.4，直接到 1.5 确认指标角色。

1.3 业务上下文识别

判定业务类型（ToB / ToC / ToD / Mixed）和业务子类型（如ToC 下的工具类 / 内容社区 / 电商 / 游戏），判定依据参考 references/bi-business-type-guide.md

1.4 分析范围确认

1. 根据业务类型和子类型，读取 references/modules 下对应的分析目录文件：

业务类型 + 子类型	文件
ToC 工具类	toc-tool.md
ToC 内容社区类	toc-content.md
ToC 电商交易类	toc-ecommerce.md
ToC 游戏类	toc-game.md
ToB 产品类	tob-product.md
ToD 开发者社区	tod-developer.md

2. 根据用户问题匹配具体的分析模块和分析内容：

• 命中分析内容条目（如"用户留存"）→ 仅匹配该条目
• 命中分析模块（如"用户趋势与规模"）→ 匹配该模块全量条目
• 语义意图匹配（如"增长分析"）→ 匹配相关模块的相关条目
• 宽泛问题（如"分析 3 月数据"）→ 匹配全量模块和条目

1.5 指标细化

根据匹配的分析内容条目，参照 references/bi-metric-specification.md，确定每个条目涉及的具体指标。

非 BI 任务（数据探索、统计建模等）

1.6 数据探查

对用户提供的数据进行初步探查，建立对数据的基本理解：

• 读取数据 schema（字段名、类型、数量）
• 查看数据规模（行数、时间跨度等）
• 采样查看数据内容，识别数据特征（缺失值、异常值、分布形态等）
• 结合用户问题，判断哪些字段/特征与分析目标相关

---

Step 2: 生成分析计划

将 Step 1 的结果组织为结构化的分析计划。

BI 业务分析的计划

包含以下内容：

• 意图：目标、分析对象、问题类型
• 已知条件：时间范围、数据来源、用户提到的指标/维度、约束条件
• 额外上下文：可用数据接口（取数或者语义层工具/API）、域知识约束（如有）
• 缺失信息：已识别但未解决的信息缺口
• 分析内容：每个分析模块的名称、分析条目、指标（名称、角色）

示例 — 用户："分析 产品A 3 月的访问趋势和对话情况"

task_type: bi_analysis

intent:
  goal: "分析访问趋势和对话情况"
  subject: "产品A"
  question_type: what

known_conditions:
  period: { start: "2026-03-01", end: "2026-03-31" }
  metric_mentions: ["访问用户数", "对话次数"]

context:
  business: { type: "ToC", sub_type: "工具类", domain: "product_a" }
  data: { semantic_layer: available, apis: ["semantic-layer", "fetch-data"] }
  domain_constraints: ["率值变动使用 pt 表达", "归因贡献度正/负各取 Top 3"]

scope:
  modules:
    - module_name: "用户趋势与规模"
      analysis_items: ["用户规模", "增长趋势", "增长归因"]
      	metrics:
        - name: "访问用户数"
          roles: [north_star]
        - name: "新增用户数"
          roles: [display]
    - module_name: "使用行为及体验"
      analysis_items: ["功能使用分析"]
      metrics:
        - name: "人均对话次数"
          roles: [north_star]
        - name: "对话次数"
          roles: [display]

非 BI 任务的计划

非 BI 任务没有固定的模块体系，需要根据用户问题与给定数据明确数据范围、条件约束以及识别未解决的信息缺口等前置信息，随后将用户问题分解为一系列可执行的原子子任务。每个子任务应当是具体的、可执行的操作（数据清洗、计算、检验、可视化等），而非笼统的分析方向。

未解决的信息缺口主要关注：

• 数据范围的歧义。例如，无法从问题和数据模式中准确推断出需要分析的数据子集。
• 语义的歧义。例如，数据中包含的数据列的含义不明确。

问题分解需要依照以下原则：

• 子任务必须包含可执行的数据检查、数据转换或计算操作；
• 子任务能够通过使用数据分析或数据科学库（如 pandas、numpy、scipy）执行 Python 代码来实现；
• 子任务考虑必要的数据清洗和预处理步骤（例如，缺失值的预处理/插补）；

最终，生成结构化的分析计划，计划包含：

• 意图：目标、分析对象、现象、问题类型
• 已知条件：数据来源、约束条件
• 数据概况：数据探查发现的关键信息（schema、数据量、数据质量等）
• 子任务序列：按执行顺序排列的原子任务，需考虑：
  • 必要的数据清洗和预处理（缺失值处理、类型转换、异常值过滤等）
  • 具体的计算或变换（分组统计、分布计算、相关性分析等）
  • 可执行的检验或判断（阈值检查、统计检验等）
• 缺失信息：已识别但未解决的信息缺口

示例 — 用户："帮我看看 user_behavior.csv，为什么 age 列分布这么不均匀？"

task_type: data_exploration

intent:
  goal: "分析 age 列分布不均的原因"
  subject: "user_behavior.csv 的 age 列"
  phenomenon: "分布不均"
  question_type: why

known_conditions:
  data_source: "user_behavior.csv"

data_profile:
  rows: 50000
  columns: 12
  age_column: { type: int, missing_rate: 3.2%, range: "0-120", median: 28 }

tasks:
  - "过滤 age 列的缺失值和明显异常值（<=0 或 >120），记录过滤比例"
  - "计算 age 列的分布直方图（bin=5），识别峰值和异常聚集区间"
  - "按 source 字段分组，分别计算各渠道的 age 均值和分布，对比差异"
  - "计算 age 与 registration_date 的相关性，判断是否存在注册批次效应"
  - "对分布不均的区间（如 age=0 或 age>100），抽样查看原始记录，判断数据质量问题"

missing_info:
  - "不清楚 age 列的业务含义（用户年龄？账号年龄？）"

---

产出

Step 2 的 YAML 即本 skill 的最终产出，作为 plan 草稿交付给 host。

信息充分性检查（强制）

交付 plan 草稿前，检查 missing_info 字段：

• missing_info 为空 → 信息充分，可以进入 create_plan
• missing_info 不为空 → 缺少关键信息，不应进入 create_plan，应先向用户反问缺失项（参照 interaction-strategy skill 的反问格式）

注意：当且仅当 missing_info 中的缺失项无法通过工具自行获取时才反问。如果 MCP 语义层工具可以消歧，应先调用工具解决，而不是停下来问用户。

Phase 3 — create_plan 后的行为（强制）

create_plan 完成后，根据 interaction-strategy skill 的 Type 2 触发条件判断：

• Type 2 未触发（默认情况）→ 输出 1-2 句 plan 概览，立即调用 update_subtask 开始执行第一个 ready 节点。不等待用户确认。
• Type 2 触发 → 输出详细计划 + 确认语，不调用工具，等待用户回复。

进入执行阶段后，还需 read_file skills/runtime-guide/SKILL.md 获取执行期通用策略（复用、异常处理、计划调整、质量自检、执行节奏、产出策略等）。