# Runtime Guide

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

- **Type:** Skill
- **Install:** `agentstack add skill-agentscope-ai-qwenpaw-data-runtime-guide`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agentscope-ai](https://agentstack.voostack.com/s/agentscope-ai)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [agentscope-ai](https://github.com/agentscope-ai)
- **Source:** https://github.com/agentscope-ai/QwenPaw-Data/tree/main/packages/datapaw-skills/skills/runtime/runtime-guide

## Install

```sh
agentstack add skill-agentscope-ai-qwenpaw-data-runtime-guide
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# runtime-guide

---

## 1. 产物落盘规范

### 1.1 工作目录

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

```text
普通对话：       /artifacts/
TaskGraph 节点： /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 数据文件

| 类型     | 存放位置                         | 命名                            |
| -------- | -------------------------------- | ------------------------------- |
| 原始数据 | `/data/raw/`       | `.`               |
| 计算结果 | `/data/processed/` | `_.`   |

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

示例：

```
/data/raw/dau_daily_202603.csv
/data/processed/channel_attribution_result.csv
```

### 1.3 步骤结果

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

```
/steps/
├── step_01_.yaml
├── step_02_.yaml
└── ...
```

每份步骤结果包含：

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

### 1.4 最终结果

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

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

结论中区分三类内容：

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

---

## 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 中定义的规则

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [agentscope-ai](https://github.com/agentscope-ai)
- **Source:** [agentscope-ai/QwenPaw-Data](https://github.com/agentscope-ai/QwenPaw-Data)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-agentscope-ai-qwenpaw-data-runtime-guide
- Seller: https://agentstack.voostack.com/s/agentscope-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.