---
name: analysis-plan-builder
description: 将用户的数据分析需求转化为结构化的分析计划并与用户确认。用户提出 BI 业务分析、数据探索、统计建模等需要规划的分析任务时使用。简单数据查询、公式明确的定量计算等流程简单、无需规划的任务不使用。
---
# 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 月的访问趋势和对话情况"

```yaml

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 列分布这么不均匀？"

```yaml
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` 获取执行期通用策略（复用、异常处理、计划调整、质量自检、执行节奏、产出策略等）。