qwenpaw-data-cli

name	qwenpaw-data-cli
description	指导外部自动化 agent 使用 QwenPaw Data CLI 发现 Data Bridge 数据源、通过自然语言规划与执行数据分析任务、复用 SOP YAML，并根据流式输出、执行摘要和错误信息验收结果。用于需要调用本地 `qwenpaw-data` 命令完成数据任务、选择 `run` 或 `plan`/`execute`、传入 `--datasource-id`、处理长任务输出或排查 CLI 失败的场景。

QwenPaw Data CLI

将 qwenpaw-data 作为外部任务执行入口。若当前 agent 已经运行在 QwenPaw Data 任务内部，不要递归启动另一个 qwenpaw-data 进程。

执行前检查

1. 运行 qwenpaw-data --help，确认命令存在且公开子命令为 plan、execute、run、chat 和 datasource。若命令不可用，报告需要先运行项目的 scripts/init_local.sh；不要搜索或直接调用 .venv/bin/qwenpaw-data，也不要自行安装或改写项目环境。

2. CLI 会自动加载项目根目录 .env 或 QWENPAW_DATA_ENV_FILE 指定的文件。不要读取、打印或手动 source dotenv 文件。模型命令会优先使用 QWENPAW_DATA_MODEL_*，未配置时回退到 LLM_MODEL、OPENAI_API_KEY 和 OPENAI_BASE_URL。

3. 使用 QWENPAW_DATA_CM_BASE_URL 指定 Data Bridge 地址；未配置时默认使用 http://127.0.0.1:8765。

4. 需要访问数据源时，先运行：

   qwenpaw-data datasource list
   

   从返回 JSON 的 items 中选择精确的 datasource_id。优先使用用户明确指定的 ID；名称或类型只有一个明确匹配时才自动选择；存在多个合理候选时向用户确认。不要从已掩码的凭据推断数据源。

5. 假定模型凭据和 MCP 配置已由运行环境提供。不要写入凭据或自行创建、覆盖 MCP 配置。

选择命令

直接完成普通任务

对不需要预先审阅或复用计划的一次性任务使用 run：

qwenpaw-data run --datasource-id "sales-prod" "分析最近 30 天销售额趋势"

需要传递较长、包含多行或容易被 shell 错误解释的请求时，将请求保存到文件并使用 --file：

qwenpaw-data run --file request.md --datasource-id "sales-prod"

位置 prompt 与 --file 互斥，不要同时传递。

审阅或复用计划

当用户要求先看计划、任务需要人工审阅，或 SOP 需要重复执行时，先生成 YAML：

qwenpaw-data plan --file request.md --datasource-id "sales-prod" --output plan.yaml

确认命令成功、plan.yaml 存在且内容符合任务目标后再执行：

qwenpaw-data execute plan.yaml --datasource-id "sales-prod"

在 plan 和 execute 中重复传入同一个 --datasource-id；该参数属于每次 CLI 请求的上下文，不要假定它已写入 SOP。

交互式对话

只在有人值守且终端支持标准输入时使用：

qwenpaw-data chat --datasource-id "sales-prod"

不要在无人值守的自动化流程中使用 chat，因为它会持续等待输入，直至收到 exit、quit 或 EOF。

选择输出模式

run 和 execute 默认启用流式输出。保留默认模式，持续读取文本增量、工具调用和工具结果，直至进程退出：

qwenpaw-data run --file request.md --datasource-id "sales-prod"
qwenpaw-data execute plan.yaml --datasource-id "sales-prod"

不要仅因短时间没有新输出就判定任务失败；使用支持长超时或会话轮询的命令执行工具，并确认进程是否仍在运行。

仅在同时满足以下条件时使用 --no-stream：

• 需要干净的最终回复以及 Execution summary；
• 调用方允许任务期间没有 stdout；
• 调用方提供足够长的超时或能够轮询进程状态。

qwenpaw-data run --no-stream --file request.md --datasource-id "sales-prod"
qwenpaw-data execute plan.yaml --no-stream --datasource-id "sales-prod"

plan 不支持 stream 选项。运行 plan 时预留长超时并轮询进程；不要添加 --stream 或 --no-stream。

当前流式路径在结束后不会追加 Execution summary。若任务必须严格检查节点状态和产物列表，应在执行前选择 --no-stream，不要为获取汇总而重复执行已经完成的任务。

验收结果

始终等待 CLI 进程结束并检查退出码：

• 0：CLI 正常结束；仍需检查任务内容是否完整。
• 1：运行时异常；读取 stderr 并按错误类型排查。
• 2：命令或参数无效；使用对应子命令的 --help 修正调用。
• 130：任务被中断；不要当作成功交付。

流式模式下，检查最终回复、工具结果和任何显式失败信息。由于该模式没有 execution summary，不能仅凭退出码 0 声称所有 DAG 节点成功；需要严格节点级验收时应预先选择非流式模式。

非流式模式下，额外检查 Execution summary：

1. 确认存在 graph_id。
2. 确认 completed: true。
3. 逐一检查节点状态。只有全部节点为 done 才视为完整成功；任何 failed 或 abandoned 都应标记为部分失败，即使 completed: true。
4. 检查 artifacts 中的路径，并在可访问时确认文件存在且可读。引用 CLI 返回的实际路径，不要虚构产物。

向用户交付时，说明使用的数据源、完成状态、失败或跳过的节点、核心结论和产物路径。

排查失败

• 参数错误：运行 qwenpaw-data <subcommand> --help，根据公开参数修正；不要猜测参数名。
• 模型未配置：报告错误中列出的缺少变量名称，不要读取 dotenv 文件，也不要输出、记录或构造 API Key。
• Data Bridge 不可用：检查 QWENPAW_DATA_CM_BASE_URL 指向的服务是否可达，再重试 qwenpaw-data datasource list。
• 数据源不存在或不明确：重新读取 datasource list，使用精确 ID；多个候选无法消歧时请求用户选择。
• MCP 不可用：说明运行环境需要预配置 MCP。公开 CLI 不提供 MCP 管理命令，不要调用 qwenpaw-data mcp 或自行覆盖配置文件。
• 节点执行失败：保留已有回复和产物，说明失败节点及影响。修正明确的暂时性问题后再重试，不要无条件重复整个任务。

禁止事项

• 不要调用不存在的 qwenpaw-data serve、qwenpaw-data mcp 或 qwenpaw-data data-source。
• 不要绕过公开命令去搜索或调用 .venv/bin/qwenpaw-data。
• 不要向 datasource list 传递不存在的 --base-url；通过 QWENPAW_DATA_CM_BASE_URL 配置地址。
• 不要打印模型密钥、数据库密码、AccessKey 或 STS Token。
• 不要为了获得 execution summary 重复执行一个已经通过流式模式完成的有副作用任务。