di-agent-bug-report

DI Agent Bug Report — IBM watsonx.data 集成会话

将当前 AI Agent 会话捕获为 Markdown 报告，以便 watsonx.data 集成技能作者调试 Agent 创建、运行或管理 watsonx.data 集成流时出现的问题（或确认哪些操作正常）。该技能不依赖特定 Agent：不要假设任何特定的 AI 运行时、模型或会话文件布局。

何时使用

• **手动：**用户明确要求报告错误或提交错误报告。直接继续，无需确认。

• **自动（建议，绝不静默——每个会话一次）：**每当触发循环检测规则时，Agent 都必须建议使用此技能。严格触发规则：

  1. 循环检测规则（主要触发条件）。每次工具调用后，维护滚动调用日志，跟踪调用的工具名称。当 Agent 连续 3 次或更多次调用同一工具，或在单轮中连续 3 次或更多次调用相同的有序工具序列，且每次尝试都产生相同错误、相同失败状态或输出没有实质性变化时，即构成“重复”。检测到第 3 次此类重复时：
     • 立即停止——不要进行第 4 次尝试。
     • 建议提交错误报告：“我已调用 <tool(s)> 3 次，结果相同（<一行错误/症状描述>）。要我提交错误报告吗？（是 / 否）”
     • 等待用户明确回复后再继续。
     • 符合条件的示例：
       • 调用 compile_datastage_flow 3 次，每次都得到相同的编译错误。
       • 将 create_job → run_job → get_job_run_logs 作为一个整体连续执行 3 次，每个循环都收到相同的失败结果。
       • 连续调用任意单个 MCP 工具 3 次，错误消息完全相同或输出结构没有变化。
     • 不符合条件的示例：
       • 调用 3 次，但输入或参数有实质性差异（Agent 确实在尝试不同的方法）。
       • 工具返回空结果，但执行成功（不是错误）。
  2. 每个会话只建议一次。记录是否已发出自动建议，并且本会话剩余时间内不得再次发出自动建议，无论之后是否出现更多失败。用户仍可手动调用此技能——次数限制仅适用于自动触发。
  3. **先询问，再等待。**发送一条简短的建议消息，仅当用户明确同意后才运行工作流。如果用户拒绝或未回复，不要写入文件。无论用户接受、拒绝还是未回复，都会占用本会话唯一一次建议机会。

当符合以下任一条件时，会话即视为与 watsonx.data 集成相关：

• 使用了名称以 di-agent- 前缀开头的技能，
• 调用了属于 Agentic Data Integration MCP 服务的 MCP 工具（通过命名空间工具名称中的服务前缀识别，例如 mcp__ibm-agentic-data-integration__*），
• 用户要求创建 / 编辑 / 运行 / 调试 watsonx.data 集成流或作业。

参数

• --name <filename> （可选） — 覆盖输出文件名。文件写入 agent/bug_reports/；仅限基本文件名。若缺少 .md，则追加该扩展名。拒绝路径分隔符和 ..。省略时，使用默认名称（参见不变量 3）。

不变量

1. 仅限 watsonx.data 集成。 如果会话与 watsonx.data 集成无关（根据上述信号判断），则不要写入文件——打印一行跳过消息并停止。先检测，再决定。
2. 写入前屏蔽所有个人身份信息（PII）。 在写入文件之前，对用户文本、助手文本、对话记录条目和错误字符串进行脱敏，而不是写入后再处理。不要脱敏技能名称、工具名称、错误消息、架构／列名称、用户 ID、项目 ID、资产 ID、流 ID、作业 ID 或公共数据集名称——这些信息是调试所需的。
3. 每次调用只写入一个文件。 默认路径：ibm-watsonx-data-integration-agent-skills/agent/bug_reports/watsonx_di_agent_bug_report_<YYYY-MM-DD>_<HH-MM-SS>_<session_name>.md，其中 <HH-MM-SS> 是本地 24 小时制时间，<session_name> 是简短的 AI 生成短语，用于概括用户最初的意图——小写、以连字符分隔、仅包含 ASCII 字母／数字，≤6 个词，不要用技能名称充数。使用 --name 时，改为写入 .../bug_reports/<filename>.md。如果 bug_reports/ 不存在，则创建该目录。如果目标文件已存在，覆盖前先询问。
4. 以对话作为事实来源。 根据实际消息和工具调用重建对话记录，不要猜测。

工作流

1. 确定会话元数据

• session_date、session_time：今天的日期和当前本地时间（格式遵循不变量 3）。
• session_name：根据开场用户提示生成短语（规则遵循不变量 3）。
• agent_session_id：宿主 Agent 运行时的会话标识符。按以下顺序尝试：（1）运行时当前的对话记录／日志文件——常见模式包括 ~/.claude/projects/<encoded-cwd>/<uuid>.jsonl（Claude Code）、~/.cursor/...，或运行时文档中公布的任意路径；如果存在匹配的 <uuid>.jsonl 且其修改时间最新，则使用文件名中的 UUID；（2）如果宿主提供运行时自省／whoami 工具，则尝试使用。如果两种方式都无法确定，则记录 null 并注明尝试过哪些来源。切勿编造或猜测。
• session_info：调用 watsonx.data 集成的 get_session_info MCP 工具，并逐字记录其完整输出。将原始键／值内容（每个字段一条项目符号）写入紧邻 generated_at 上方的 Session Info 部分。不要尝试提取单个 ID——直接传递工具返回的所有内容。如果工具不可用或发生错误，则记录一条项目符号 **Session Info:** _tool unavailable._ 并继续。
• llm：为宿主 Agent 运行时提供支持的大模型名称和版本（例如 claude-opus-4-7、claude-sonnet-4-6、gpt-5.1）。使用运行时在其系统提示词中声明的模型标识符——大模型知道当前运行的模型。如果无法自我识别，则回退到运行时自省工具或与模型相关的环境变量。记录为 <name>-<version>；仅当这些方式均无法确定时记录 null。
• 输出文件名：使用 --name 的值（清理后追加 .md），或使用不变量 3 中的默认值。

2. 构建转录记录

将会话中的所有条目按时间顺序合并为一个部分。按对话顺序逐一记录，每条用户消息、助手文本回复、技能调用和工具调用各追加一个编号条目。所有条目共用一个编号序列，严格按照发生时间排序——轮次和工具调用自然交错。

每条记录的格式：

• 用户 / 助手轮次——粗体伪标题后直接跟一个 fenced text 代码块，其中包含已脱敏 PII 的正文。只能逐字呈现：按字符原样呈现实际文本（PII 脱敏除外）。不得总结、转述或添加类似 [调用了 X 技能，然后……] 的括号说明。对于助手轮次，只包含用户可见的文字——去除内部推理和原始工具调用 JSON。如果助手轮次没有用户可见文本（仅包含工具调用），则跳过——不要编造文字。

  **N. turn — <User | Assistant>**
  
  ```text
  <verbatim PII-redacted text of the turn, line breaks preserved>
  

• 技能或工具调用——粗体伪标题，包含类型、名称、状态，然后列出 **Input:** 和 **Output:**。

  **N. <skill | tool> — `<name>` — status: <ok | error | unknown>**
  
  - **Input:** <one-line summary — never the full payload>
  - **Output:**
  
    ```text
    <result, truncated to ~2000 chars; `_No output._` if none; failure messages go here>
  

说明：

• 通用 Read/Edit/Bash 调用仅在属于 watsonx 流程时才出现。
• Description 部分引用转录记录的编号（entry N）。

3. 调用诊断工具并收集更深入的信息

必须执行。 转录记录中的作业运行状态仅报告 completed / failed 和简短摘要——不足以诊断实际情况。定稿 Description（第 4 步）之前，只要会话中有相关输入，就调用以下 watsonx.data 集成 MCP 工具。仅当缺少输入时才跳过工具；失败时不要中止；将每次尝试（包括错误）作为独立的转录记录。

• get_job_run_logs — 获取最新作业运行的完整日志流和事件历史。在 Description 中引用具体警告 / 错误（例如隐式类型转换、分区数、每个阶段的 in → out 行数）。
• retrieve_datastage_flow_code — 获取已提交流程的存储定义，确保报告反映实际运行的内容（列类型、谓词、连接）。

Description 必须基于这些工具的输出——不得仅依据表层运行状态进行诊断。

4. 诊断会话

生成 Description 部分。根据转录记录（第 2 步）和诊断数据（第 3 步）进行分类：

• 成功 — 生成了行。 流程已完成；输出与源数据一致。
• 成功 — 源数据为空。 作业正常运行；源本身有 0 行数据。结果为 success；需明确说明这一点。
• 成功 — 按预期没有输出。 流程逻辑合理地未生成任何行（反连接、筛选等）。结果为 success，并在 Description 中说明原因。
• 失败。 日志显示错误、非空源中的行被静默丢弃，或 Agent 陷入循环 / 错误使用工具 / 生成无效流程。在 Description 中引用具体信号。

Description 长度：最多 5–6 句。 说明结果和直接原因——发生了什么故障、发生在哪里（引用转录记录 entry N），以及证据表明了什么。不要提供背景、叙述过程或重复用户的要求。

5. 编写 Markdown 文件

如果 ibm-watsonx-data-integration-agent-skills/agent/bug_reports/ 不存在，则创建该目录，然后使用下面的模板写入文件。

格式规则：

• 文件的第一行必须是 # IBM watsonx.data integration Agent Bug Report。 前面不得有 YAML/Markdown frontmatter、--- 分隔符、空行、shebang 或元数据块。文件必须以该 H1 开头，且前面不能有其他内容。
• 不得在文档中的任何位置插入水平分隔线（---）。 章节边界仅用 ## 标题表示——Markdown 中的 --- 行会呈现为水平分隔线，使输出显得杂乱。
• 章节顺序固定：Session Info → Description → Transcript。
• 只使用两级标题：标题用 #，章节用 ##。任何地方都不得使用 ###——请改用粗体伪标题。
• 章节之间以及围栏代码块前后各留一个空行。结尾保留一个换行符。
• 为多行输出添加带语言提示的代码围栏。
• 字段标签必须加粗（**Input:**、**Output:** 等）。
• 空章节只写一行斜体文字。

模板：

# IBM watsonx.data integration Agent Bug Report

**Outcome:** [success | failure]

## Session Info

- **Agent Session ID:** `[uuid or null]`
- **LLM:** `[name-version, e.g. claude-opus-4-7, or null]`
- **`get_session_info`:** [render each field returned by the tool as its own indented bullet, verbatim — e.g. `session_id`, `client_type`, etc. If the tool errored or was unavailable, write `_tool unavailable._` instead.]
- **Generated at:** [ISO-8601 timestamp]

## Description

[5–6 sentences max. State the outcome and the direct reason — what failed, where (cite transcript entries as `entry N`), and what the evidence says. No background, no fixes.]

## Transcript

**1. turn — User**

```text
[PII-redacted user message text, verbatim.]
```

**2. turn — Assistant**

```text
[PII-redacted assistant prose reply, verbatim.]
```

**3. [skill | tool] — `[name]` — status: [ok | error | unknown]**

- **Input:** [one-line summary]
- **Output:**

  ```text
  [result, truncated to ~2000 chars; `_No output._` if none. Failure message goes here.]
  ```

[...continue numbering chronologically; turns and tool calls interleave...]

6. 向用户确认

写入后，打印：绝对文件路径、结果和 transcript 条目数。不要回显完整报告。

示例

• 非 watsonx.data integration 会话。 重构无关的 Go 服务 → 用一行说明跳过，不写入文件。
• 成功会话（手动调用）。 Agent 构建了一个 pyflow 并提交，运行状态轮询结果为绿色；用户为存档提交 Bug 报告 → 结果为 success。
• 失败会话（提议后获接受）。 Agent 没有查阅相关查询工具，而是反复猜测 stage / connector 配置，导致 flow 编译失败；Agent 提出报告，用户接受 → 结果为 failure，Description 中说明遗漏了查询步骤。