| name | runtime-guide |
| description | 提供数据分析任务执行的强制性通用规范。在计划完成准备执行数据分析任务、或执行过程中涉及产物落盘、数据复用、异常处理、计划调整、质量自检时，必须优先调用此技能。 |
runtime-guide
1. 产物落盘规范
1.1 工作目录
每次执行都使用 QwenPaw Data runtime 指定的当前产物目录。本文用
<current_artifacts> 表示：
普通对话： <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 产出最终结果，包含：
- 完成状态：全部完成 / 部分完成 / 失败
- 核心结论：对分析目标的直接回答
- 支撑数据：结论依赖的数据文件
- 未解决问题：数据缺失、结果矛盾、未追踪的线索
- 后续建议：建议深入分析的方向
结论中区分三类内容：
- 数据事实（客观计算结果）
- 分析解读（对数据的推理判断）
- 不确定性标注（数据不足或置信度低时明确提示）
2. 执行原则
2.1 复用优先
避免重复获取数据和重复计算，节省执行成本并保证结果一致性。
- 数据级复用：
- 同一份基础数据只获取一次，后续需要时直接引用已有文件
- 已计算过的中间结果（如衍生指标、趋势数据）直接复用，不重复计算
- 复用时标注来源文件，便于溯源
- 任务级复用：
- 不同分析步骤/条目涉及相同的指标或计算时，复用已有结果，跳过重复执行（如 BI 分析中多个模块都涉及 DAU 指标，只需分析一次）
- 复用前检查数据口径和时间范围是否一致，不一致则重新计算
2.2 异常处理与自排障
执行过程中会遇到各种异常情况，核心原则是：先自行排障，尽可能继续执行，无法解决时才求助用户。
自排障流程（强制）
遇到节点执行失败时，按以下顺序处理：
- 分析原因：读取报错信息，判断是参数错误、数据不存在、权限不足还是逻辑错误
- 第 1 轮重试：调整参数/策略重试（如换维度筛选、换数据源、放宽时间范围）
- 第 2 轮重试：尝试替代方案（如换等价指标、换表、降级分析粒度）
- 仍失败：判断影响范围：
- 非关键节点 → 跳过并标注原因，继续后续节点
- 关键节点且影响最终结论 → 停下来向用户求助（参照
interaction-strategy skill Type 1）
求助时必须提供
- 已尝试的方案和失败原因
- 当前阻塞点的具体描述
- 建议的解决方向（如有）
数据层异常处理
- 数据不可用：
- 单项缺失 → 跳过该项并标注原因，继续其余分析
- 大面积缺失但仍有部分可用 → 基于可用数据产出结论，明确标注覆盖范围和局限性
- 核心数据全部不可用 → 终止分析并说明原因
- 原则：不因局部数据缺失而阻塞整体执行
- 计算异常：
- 遇到异常（如除以零、超出常理范围等）时保留结果并标注原因
- 不静默丢弃异常数据，不用默认值替代
- 结果矛盾：
- 不同分析过程对同一现象产出矛盾结论时，保留所有结果
- 列出可能的原因（口径不同、时间范围不同、数据源不同等）
- 不替用户做取舍，由用户判断采信哪个
- 局部失败：
- 记录失败的步骤和原因
- 不依赖该结果的后续分析继续执行
- 依赖该结果的后续分析一并跳过，并标注跳过原因和依赖关系
2.3 新线索追踪
执行过程中可能发现计划外的有价值信息（如意料之外的异常、未预期的相关性），按如下标准判断是否追踪：
- 与分析目标直接相关 → 追踪；
- 数据信号显著且可快速验证 → 追踪；
- 与目标无关或需要大量额外工作 → 记录但不追踪，标注"建议后续深入"
2.4 计划调整
执行过程中可能需要调整原始计划，调整后生成新版本的 plan 文件（参见 1.1 工作目录）。
- 何时调整：
- 关键数据不可用，导致核心分析目标无法达成
- 用户中途明确变更需求
- 执行过程中发现原始计划的前提假设不成立，或出现新线索可以额外深入探索（参见 2.4）
- 何时不调整：
- 非关键数据缺失 → 跳过即可，不需要改计划
- 执行慢或资源不足 → 降级执行深度（如减少维度遍历），不改分析目标
- 调整原则：
- 只改必须改的部分，保持计划的稳定性
- 记录调整原因和触发事件
2.5 质量自检
交付分析结果前，逐项检查产出质量：
- 结论一致性：所有结论必须有数据支撑，与计算结果一致，无逻辑跳跃
- 不确定性标注：数据不足或置信度低的结论是否已明确标注
- 推测标注：无数据支撑的主观判断是否已标注为推测
- 完整性：未完成的部分是否已列出并说明原因
- 约束遵守：是否遵守了所有相关约束，包括：
- 用户在对话中提出的要求和限定条件
- 域知识包（若存在）中的分析规范
- plan 中指定的约束条件
- 各 skill 中定义的规则
