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 产出最终结果，包含：

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

结论中区分三类内容：

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

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