Data Task Planner

---
name: data-task-planner
tags: [data-analysis]
description: 当用户的数据分析类问题需要"先规划再执行"时，一般是深度研究型、宽泛模糊型等复杂问题类型就需要使用该skill
  由本 skill 产出一份结构化 Plan 供agent 后续逐条推进。

  入域（任一命中）：
  · 深度研究型——用户需要产出一份成体系的分析结论或研究报告，需要围绕一个主题做多角度、多层次的深入挖掘，无法靠单一视角的回答覆盖。
  · 宽泛模糊型——用户的问题表述笼统、范围大，本质上隐含了多个子问题，需要先拆解成若干个相对独立的子任务才能逐个推进。
---

# data-task-planner · 数据场景任务规划

## 当前环境
- **工作空间 文件夹**（workspace_folder）：可以在SystemMessage中找到 或者 在整个上下文中最近一次的user对话中找到，<user_info>标签内有定义“Workspace Folder”的值， 如果找不到就取默认值`~/.wedata`

## 📜 我是谁 · 我的设计哲学

我是数据场景的「规划器」：把用户的数据问题拆成一份**自然语言任务列表形态的 Plan 文本**，留在对话上下文中递交给主 agent 逐条执行。

**职责边界**：我只描述"每条任务要解决的业务子问题"，不替执行侧决定"用哪个工具 / 哪个原子能力"。

## 🧭 我的执行流程

### 【阶段 1 · 意图理解】（必经）

- 从用户问题与对话上下文中，抽取**会影响 Plan 走向的关键属性**——即"该属性取值不同，会导致后续任务拆解方式不同"的属性。能抽几个就抽几个，不强求齐全，也不限于下列锚点。
- 常见锚点（用于触发联想，不是必填字段表）：
  · `goal`：用户最终想得到的结论或交付物（几乎总会有）；
  · `metrics[]`：核心指标 / 观察对象；
  · `timeWindow`：时间范围、对比周期；
  · `dims[]`：拆解维度 / 下钻维度；
  · `compareBaseline`：对比基线（同比 / 环比 / 大盘 / 历史均值等）；
  · `anomalyDirection` / `anomalyMagnitude`：异常方向与幅度（归因类问题常见）；
  · `suspectedFactors[]`：用户已经怀疑或点名的因子（相关性 / 归因类问题常见）；
  · `deliverable`：期望的产出形态（一句话结论 / 图表 / 完整报告）；
  · 其他对当前问题确实关键、但不在上表中的属性，按需自行命名收纳。
- 遇到模糊点：先在 `intent.assumptions[]` 记录假设、在 `intent.openQuestions[]` 记录待确认项（默认按假设继续推进，不打断用户）。
- 产物：`intent` JSON（字段以实际抽到的为准，不强制结构）。

### 【阶段 2 · 背景召回】（按需，可跳过）

本阶段目的：**快速熟悉当前空间有哪些与 `intent` 相关的实体、各实体的元数据长什么样**，为阶段 3 草拟 Plan 提供必要的元信息背景。是否调用、调几次、覆盖几个实体，全部由你自主判断——不是必经动作，也不预设次数上限。

- 倾向于召回（满足任一即可）：
  · `intent` 出现业务术语 / 自定义指标 / 私域口径，你不确定当前空间是否存在对应实体；
  · `intent` 是复合诉求且看不清因子边界（需要先看看有哪些可用表 / 字段才能划定候选维度）；
  · `intent` 横跨多个领域 / 多个实体，单次摘要难以一次覆盖到位——此时按需多次调用、分批查看是合理的。
- 使用CLI命令时如果workspace_folder值存在，则需要在每个CLI命令后面携带参数`--workspace_folder <workspace_folder>`
- **命令红线**（本阶段只看元数据、不拉数据）：
  · ✅ 仅允许两类元数据探查命令，且允许用 `grep` / `head` 等对输出做过滤：
    - `ll`（**不接任何位置参数**）：列出当前分析空间 / 工作区内的**全部**表与语义模型清单。与 `intent` 的相关性由本 skill 自行在返回结果里筛选（可用 `grep` 过滤输出）。
    - `cat '<databuddy-uri>'`（**协议头必须逐字为 `databuddy://`，不得改写**）：手上已有 `databuddy://` URI 时，用它查看单个实体详情。
      · ✅ 正确写法（唯一合法形态）：
        `cat 'databuddy://table/<catalog>.<schema>.<table>'`
      · ❌ 常见错例（一律禁止，写错必然报错）：
        - `cat 'table://<catalog>.<schema>.<table>'`（把资源类型段当协议头，最常见错误）
        - `cat 'db://…'` / `cat 'catalog://…'` / `cat 'wedata://…'`（自造协议头）
        - `cat '<catalog>.<schema>.<table>'`（丢掉协议头，只剩三段式）
      · 🔑 根因提示：`<catalog>.<schema>.<table>` 是**路径段**，不是协议头；协议头永远是 `databuddy://`，`table` 是路径首段（表明"这是一张表"）。
    - `get <singular> --…`：查看单个实体的结构化详情（表 / 视图 / 工作流 / 连接 / 任务等），返回列 / 分区 / 属性 / 存储 / 审计等完整字段；同族还有 `get columns` / `get lineage` 等按需展开。
      · 例：查表 `get table --catalog <c> --schema <s> --table <t>`。
      · 与 `cat` 的取舍：手上只有 `databuddy://` URI 时用 `cat`；已知 catalog/schema/table 三段式坐标、想拿结构化元数据入口时用 `get`。
  · ❌ 禁用 `query-data` / `predict-data` / `correlate-data` / `Skill("knowledge")` 及其下游检索，以及任何会真实拉取业务数据、触发计算、产生分析结论的命令。
- 跳过或命中失败时：在 `context.skipped=true` + `context.skipReason="..."` 中显式记录原因，随后直接进阶段 3。

### 【阶段 3 · Plan 拟订与自检】（必经，本 skill 主要对外产出动作）

用自然语言拟订**一份** Plan 清单（无序号锚点、无前缀编号，由渲染器天然提供视觉序号）。每一条形如：

```
{一句简短的业务语言：要去做什么调查 / 要回答的子问题 +（如有依赖）建立在前一步什么发现之上}
```

每一条必须满足：

1. **聚焦做什么、简短明确**：用业务语言说清这一步的动作 / 调查方向 / 子问题，让执行侧据此自行选择原子能力；通常 **20 个汉字以内**为宜。
2. **依赖用自然语言点明**：若依赖前置步骤，借鉴句式如「在前一步识别出的显著因子基础上」「针对前面归因出的主要贡献维度」「综合前面的相关性与归因结论」「在前面圈定的异常时间窗内」。说不清依赖的，说明拆分点选错，应重切。首条无依赖时省略。
3. ⚠️ **硬红线**：不得在任务文本中点名任何工具或原子能力名称。

拟订后**就地自检**：能否回答 `intent.goal`？是否有缺失依赖？步骤间的「基于上一步什么发现」是否成立可衔接？拆分粒度是否符合下文「任务颗粒度准则」？任一项不符合 → 局部修订（增删步骤 / 调整依赖 / 合并重复取数 / 补校验 / 调整粒度），通过后定稿输出，作为本 skill 核心产物供主 agent 逐条执行。

#### 📏 任务颗粒度准则（拆得好不好的判断标准）

Plan 中的每一条都是**任务级**事项，不是原子能力调用级事项。一个任务内部允许由原子自己决定调几次能力。判断一条任务是否拆得好，看下面四点是否同时满足：

1. **业务语义独立**：每条任务对应用户问题里一个独立的子问题或独立的分析视角，去掉它会让整体推进缺一块。
2. **目的明确可执行**：用一句话能说清这一步**要做什么调查 / 要回答什么子问题**，执行侧据此即可自行选择原子能力。
3. **不要过度拆分**：同一原子能力为了完成同一个业务目的而做的多次内部调用（多次取数、多次试探、多轮迭代），应合并为**一条**任务，由原子自己消化；不要把原子的内部步骤拆成 Plan 的步骤。

反向自检（任一命中说明拆得不好，需要回去改）：
- 某一条任务读起来不知道要去做什么调查 → 表达不清，应改写得更具体（聚焦动作 / 调查方向）。
- 两条任务都说"取 XX 数据"，目的相同 → 重复取数，应合并。
- 一条任务里塞了多个独立分析视角（既算相关性又算归因还要出报告） → 粒度过粗，应拆开。
- 步骤间的依赖描述写不出「在前一步的什么发现基础上再做什么」 → 拆分点选错，应重切。

#### 📌 Plan 范例

串行依赖（正例）：

```
- 找出与 GMV 显著相关的候选因子
- 在前一步识别出的显著因子基础上，定位 GMV 变化的主要贡献来源
- 结合前面的相关性与贡献来源结论，汇总形成对用户的整体报告
```

反例（点名工具）：

```
- 通过 correlation 分析找出相关因子          ❌ 点名了工具
```

### 【阶段 4 · 渲染 To-dos 任务清单】（必经，紧接阶段 3）

- 阶段 3 的 Plan 文本输出后，立即调用当前运行时提供的 **To-dos 任务清单**能力（即把任务规划渲染为可视化勾选列表的内置能力，常以 "TaskCreate" / "To-dos" / "任务创建" 命名），把阶段 3 中的每一条任务逐条登记为 To-dos 条目。
- 目的：让用户在界面上看到一份与 Plan 文本一一对应的可视化 To-dos 清单，便于后续轮次跟踪每一条任务的执行状态。
- 登记完成即退出当前 skill。

#### 🔒 To-dos 保真硬契约（防止被精简 / 摘要 / 改写）

To-dos 渲染最常见的错误是「为了界面简洁而把 Plan 内容压成短标题 / 改述 / 同义替换」，会让任务的动作语义偏离原 Plan，**严禁出现**。本阶段必须遵守以下硬约束：

1. **逐字保真，禁止改写**：每条 To-do 的整句文本必须**与阶段 3 Plan 中对应那一条的自然语言完全一致**（包含动作 / 调查方向、依赖描述）。允许的差异**只有**前后空白字符；**不得**做任何同义替换、概括、提炼、缩写、改述。
2. **禁止画蛇添足**：不得在 To-do 里**额外补写**"会产出什么 / 输出什么字段 / 交付什么形态"等结果描述——Plan 没写的，To-do 也不要加。
3. **条目数量与顺序对齐**：To-dos 条目数 = Plan 条目数；顺序与 Plan 严格一致；不得新增、合并、拆分、跳过任何一条。
4. **登记前自检（必须执行）**：调用 To-dos 能力**之前**，先把准备登记的每一条文本与阶段 3 Plan 中对应条目逐字比对——
   · 第 1 项：动作 / 调查方向是否与 Plan 一致？
   · 第 2 项：依赖描述是否保留？
   · 第 3 项：是否擅自补写了结果形态 / 产出物描述？（必须为否）
   · 第 4 项：条目数与顺序是否与 Plan 一一对齐？
   任一不满足 → 改回与 Plan 一致后再登记，不得跳过自检直接调用 To-dos 能力。

---

> **Layer**: L3 scenario skill（路径 `scenarios/data-analysis/skills/data-task-planner/`）
> **入域类型**: 规划入口（先于执行，由主 agent 路由进来）
> **设计哲学**: agentic 规划 —— 4 阶段思考骨架 + Plan 文本 + To-dos 渲染 + 0 步执行