---
name: runtime-guide
description: 提供数据分析任务执行的强制性通用规范。在计划完成准备执行数据分析任务、或执行过程中涉及产物落盘、数据复用、异常处理、计划调整、质量自检时，必须优先调用此技能。
---
# runtime-guide

---

## 1. 产物落盘规范

### 1.1 工作目录

每次执行都使用 QwenPaw Data runtime 指定的当前产物目录。本文用
`<current_artifacts>` 表示：

```text
普通对话：       <workspace>/artifacts/<session_id>
TaskGraph 节点： <workspace>/artifacts/<session_id>/<graph_id>/<node_id>
```

当前执行目录内结构如下：

```
<current_artifacts>/
├── plan.yaml                 # 原始 plan（来自 planner，不修改）
├── plan_v1.yaml              # 第一次修改后的 plan（如有）
├── plan_v2.yaml              # 第二次修改后的 plan（如有）
├── steps/                    # 步骤结果（每步完成后写入）
├── data/                     # 数据产物
│   ├── raw/                  # 原始获取的数据（从数据源拉取的原始结果）
│   └── processed/            # 计算处理后的数据（衍生指标、数据清洗结果等）
└── result.yaml               # 最终结果（执行完成后写入）
```

- `plan.yaml` 是原始计划，始终保留不修改
- 执行过程中如需调整计划，生成 `plan_v1.yaml`、`plan_v2.yaml`... 按修改顺序递增
- 执行时始终以最新版本的 plan 为准
- `session_id` 必须使用 runtime 提供的当前值，不自行生成
- 仅当 runtime 明确提供当前 `graph_id` 和 `node_id` 时才使用节点子目录；普通
  对话直接使用 session 目录
- 不在 workspace 根或未隔离的 `artifacts/` 下创建任务目录

### 1.2 数据文件

| 类型     | 存放位置                         | 命名                            |
| -------- | -------------------------------- | ------------------------------- |
| 原始数据 | `<current_artifacts>/data/raw/`       | `<数据描述>.<ext>`               |
| 计算结果 | `<current_artifacts>/data/processed/` | `<分析内容>_<结果描述>.<ext>`   |

- 文件命名应自描述，能看出内容是什么
- 列名/字段名须有业务含义（如 `date, dau, dau_wow, is_anomaly`），不使用 `col1, col2`
- 每个关键的计算结果都要落盘到 `data/processed/`，包括清洗后的数据文件、衍生指标、归因结果、异常检测结果、维度交叉表等，确保结论可溯源、可复现

示例：

```
<current_artifacts>/data/raw/dau_daily_202603.csv
<current_artifacts>/data/processed/channel_attribution_result.csv
```

### 1.3 步骤结果

每个分析步骤完成后，落盘一份步骤结果，服务于过程审查和结果溯源。存放在当前执行
目录的 `steps/` 子目录下：

```
<current_artifacts>/steps/
├── step_01_<步骤描述>.yaml
├── step_02_<步骤描述>.yaml
└── ...
```

每份步骤结果包含：

- **做了什么**：本步骤执行的操作描述
- **产出文件**：涉及的数据文件、中间结果的路径索引
- **代码**：本步骤执行的关键代码或脚本（如有）
- **结论**：本步骤的分析结论或发现

### 1.4 最终结果

执行完成后，在 `<current_artifacts>/result.yaml` 产出最终结果，包含：

- **完成状态**：全部完成 / 部分完成 / 失败
- **核心结论**：对分析目标的直接回答
- **支撑数据**：结论依赖的数据文件
- **未解决问题**：数据缺失、结果矛盾、未追踪的线索
- **后续建议**：建议深入分析的方向

结论中区分三类内容：

- 数据事实（客观计算结果）
- 分析解读（对数据的推理判断）
- 不确定性标注（数据不足或置信度低时明确提示）

### 1.5 交付物版本化

`plan_v1.yaml` / `plan_v2.yaml` 的版本化约定同样适用于**所有重新生成的交付物**（报告、
数据文件、图表、`result.yaml`）。同一交付物被重做时，不原地覆盖，而是递增版本后缀：

```
<current_artifacts>/reports/gmv_analysis_v1.md
<current_artifacts>/reports/gmv_analysis_v2.md      # 修订后的版本
<current_artifacts>/data/processed/channel_attribution_result_v2.csv
```

- 首版即带 `_v1` 后缀，便于后续修订时保持命名一致
- 交付物被用户反馈驱动重做、口径修正、或依赖数据更新后重算时，一律新增版本
- 引用交付物时始终指向最新版本，但不删除历史版本——结论的演变过程本身是审查依据
- 仅当同一版本内的局部修正（如错别字）才允许原地修改

### 1.6 交付物在回复中可定位

落盘不等于交付。最终回复必须点名本次产出的交付物，并给出相对当前 session artifacts
根的路径，用户才能直接从对话定位文件：

```
已生成报告：<graph_id>/<node_id>/reports/gmv_analysis_v1.html
支撑数据：  <graph_id>/<node_id>/data/processed/channel_attribution_result_v1.csv
```

- 只说"报告已生成"、"图表已完成"而不给路径，视为交付不完整
- 路径与 `update_subtask(..., files=...)` 登记时的写法一致，不带 workspace、
  `artifacts` 或 `session_id` 前缀
- 有多个交付物时逐个列出，主交付物放在最前
- 按 §1.5，指向的始终是最新版本

---

## 2. 执行原则

### 2.1 复用优先

避免重复获取数据和重复计算，节省执行成本并保证结果一致性。

- **数据级复用**：
  - 同一份基础数据只获取一次，后续需要时直接引用已有文件
  - 已计算过的中间结果（如衍生指标、趋势数据）直接复用，不重复计算
  - 复用时标注来源文件，便于溯源
- **任务级复用**：
  - 不同分析步骤/条目涉及相同的指标或计算时，复用已有结果，跳过重复执行（如 BI 分析中多个模块都涉及 DAU 指标，只需分析一次）
  - 复用前检查数据口径和时间范围是否一致，不一致则重新计算

### 2.2 异常处理与自排障

执行过程中会遇到各种异常情况，核心原则是：**先自行排障，尽可能继续执行，无法解决时才求助用户**。

#### 自排障流程（强制）

遇到节点执行失败时，按以下顺序处理：

1. **分析原因**：读取报错信息，判断是参数错误、数据不存在、权限不足还是逻辑错误
2. **第 1 轮重试**：调整参数/策略重试（如换维度筛选、换数据源、放宽时间范围）
3. **第 2 轮重试**：尝试替代方案（如换等价指标、换表、降级分析粒度）
4. **仍失败**：判断影响范围：
   - 非关键节点 → 跳过并标注原因，继续后续节点
   - 关键节点且影响最终结论 → 停下来向用户求助（参照 `interaction-strategy` skill Type 1）

#### 求助时必须提供

- 已尝试的方案和失败原因
- 当前阻塞点的具体描述
- 建议的解决方向（如有）

#### 数据层异常处理

- **数据不可用**：
  - 单项缺失 → 跳过该项并标注原因，继续其余分析
  - 大面积缺失但仍有部分可用 → 基于可用数据产出结论，明确标注覆盖范围和局限性
  - 核心数据全部不可用 → 终止分析并说明原因
  - 原则：不因局部数据缺失而阻塞整体执行
- **计算异常**：
  - 遇到异常（如除以零、超出常理范围等）时保留结果并标注原因
  - 不静默丢弃异常数据，不用默认值替代
- **结果矛盾**：
  - 不同分析过程对同一现象产出矛盾结论时，保留所有结果
  - 列出可能的原因（口径不同、时间范围不同、数据源不同等）
  - 不替用户做取舍，由用户判断采信哪个
- **局部失败**：
  - 记录失败的步骤和原因
  - 不依赖该结果的后续分析继续执行
  - 依赖该结果的后续分析一并跳过，并标注跳过原因和依赖关系

### 2.3 新线索追踪

执行过程中可能发现计划外的有价值信息（如意料之外的异常、未预期的相关性），按如下标准判断是否追踪：

- 与分析目标直接相关 → 追踪；
- 数据信号显著且可快速验证 → 追踪；
- 与目标无关或需要大量额外工作 → 记录但不追踪，标注"建议后续深入"

### 2.4 计划调整

执行过程中可能需要调整原始计划，调整后生成新版本的 plan 文件（参见 1.1 工作目录）。

- **何时调整**：
  - 关键数据不可用，导致核心分析目标无法达成
  - 用户中途明确变更需求
  - 执行过程中发现原始计划的前提假设不成立，或出现新线索可以额外深入探索（参见 2.4）
- **何时不调整**：
  - 非关键数据缺失 → 跳过即可，不需要改计划
  - 执行慢或资源不足 → 降级执行深度（如减少维度遍历），不改分析目标
- **调整原则**：
  - 只改必须改的部分，保持计划的稳定性
  - 记录调整原因和触发事件

### 2.5 质量自检

交付分析结果前，逐项检查产出质量：

- **结论一致性**：所有结论必须有数据支撑，与计算结果一致，无逻辑跳跃
- **不确定性标注**：数据不足或置信度低的结论是否已明确标注
- **推测标注**：无数据支撑的主观判断是否已标注为推测
- **完整性**：未完成的部分是否已列出并说明原因
- **约束遵守**：是否遵守了所有相关约束，包括：
  - 用户在对话中提出的要求和限定条件
  - 域知识包（若存在）中的分析规范
  - plan 中指定的约束条件
  - 各 skill 中定义的规则