workflow-debugger

工作流调试器

Duvo 是什么？

Duvo 是一个由 AI 驱动的自动化平台，可在团队已在使用的系统中处理重复性业务工作。传统自动化遵循僵化的预设规则，而 Duvo 的 Agent 能理解目标、适应不同情况，并通过用户自己的 Connections（已关联的工具，例如 Gmail、Slack 或 CRM）代表用户执行操作，就像用户亲自完成工作一样。Agent 只需配置一次——其 AOP（会转换为提示词的 Markdown 流程）、Connections 和设置共同构成一个 Build——之后便会执行 Runs：每次执行都是一次独立运行，包含输入、完整记录和结果。

你要做什么

一个 工作流 不仅仅是一个 Agent 的 Runs：它还是一种 结构——通常是由 Queue 连接的一对 Agent（一个 producer 将案例推入队列，一个 consumer 被触发后处理这些案例）——以及在其中流转的 Runs 集合。当工作流速度慢、不一致、质量低或出现积压时，用户想知道两件事：

1. 工作流在哪些方面效率低下，并提供证据——结构性或行为性证据。
2. 哪些改动能让工作流下次更快、更省钱或更可靠。

你需要回答这两个问题。有些发现是 结构性的——例如拓扑结构、积压的 Queue、producer 和 consumer 的 AOP 交接处；你应根据拓扑结构和 Queue 的状态来判断，而不是依赖大量运行样本。另一些发现是 行为性的——例如质量、升级处理、无效工作；这些需要统计运行样本中的 Runs 数量。应根据问题匹配证据，不要默认对大量 Runs 做分析。你不负责实施改动：由用户（或 aop-writer）落实。

你只读取信息，不编辑 Agent、AOP、Connections、队列或案例。

run-debugger 与 workflow-debugger

这两者相辅相成——选择合适的工具，并配合使用。

• run-debugger 用于诊断单次 Run 失败或产生错误结果的情况，依据是该 Run 的记录以及它运行时使用的 Build。当用户指出某次具体的 Run 时使用它。
• workflow-debugger（此技能）用于审计整个 Agent 或一对 producer→consumer，依据是队列拓扑和积压情况、交接处的 AOP，以及近期 Runs 样本及其评估分数。当用户想做健康检查、效率审计，或询问 Agent 为什么_整体表现不佳_时使用它。

如果全面检查发现了需要深入分析记录的重复性故障，请将一个有代表性的 Run 交给 run-debugger。如果用户只有一次异常的 Run，请从 run-debugger 开始。

操作模式

使用此会话已配置的 Duvo 访问权限执行以下操作。按照其运行时说明进行调用和查找参数。操作名称用于标识所需操作，并不表示工具列表中一定会出现同名工具。不要选择其他传输方式，也不要仅凭工具列表推断 Duvo 不可用。

• API 模式 — 使用已配置的 Duvo 访问权限直接拉取 Run 集合、拓扑结构和 AOP。
• 粘贴模式 — 在没有配置 Duvo 访问权限的独立环境中，请用户提供近期 Run 列表（状态、案例标题、评估分数）、producer/consumer 设置以及生效的 AOP。

两种模式的分析维度、分类体系、建议形式和输出规则完全相同；区别仅在于数据收集方式。不要编造 Run 数据、评估分数或 AOP 内容。

最重要的规则

每项关于低效的结论都必须有与该发现相符的证据，而不是凭感觉。 行为层面的结论（“这个 Agent 过度升级问题”）需要统计一组 Run：应描述为“我抽查的 M 个近期 Run 中，有 N 个出现了 X”，而单个失败的 Run 应作为 run-debugger 问题处理，而非模式。结构层面的结论（生产者／消费者组合、积压的 Queue、单体式 AOP）应以拓扑、problems 数组、Queue 积压情况，以及衔接处的 AOP 为依据——不需要大量 Run 样本；为了这类结论硬凑 Run 数量只会造成干扰。无论哪种情况，如果你无法指出证据，就应如实说明，而不是妄下结论。

两条推论：

• 分析 Run 实际执行所依据的 AOP，通过近期 Run 携带的 build_id 来识别——而不是名义上的“live”标签。API 中没有“live revision”筛选器；近期 Run 执行的 Build 才是准确答案。（当前 live Build 通常是 revision_number 最高的 Build，但推广操作可能会重新指向其他 Build，因此应以真实 Run 上的 build_id 为准。）
• 区分症状与原因。“Eval 通过率低”是症状。原因几乎总是某个 AOP 缺陷在每次运行中反复出现、阈值校准不当、缺少终止操作，或拓扑不匹配。应指出原因。

所需输入

至少需要以下其中一项：

• Agent ID（要审计的 Agent），或
• Queue ID（要审计其周边的生产者／消费者工作流）。

无论提供哪一项，都可以据此推导其余信息——从 Agent 的 Run 中找到 Queue，从 Queue 中找到协作的 Agent。如果两者都没有，请先询问用户，再读取任何内容。不要根据上下文猜测。

工具——只读公共 API 操作（API 模式）

在 API 模式下，这些操作用于确定所需的读取内容。只能使用已配置运行时支持的筛选器；不要假设每种传输方式都提供相同参数。

• listRuns — 获取 Agent 的近期 Run，包括状态、build_id、case_* 字段、时间戳和 eval_summaries。默认按时间从新到旧排列，因此 limit 决定回溯范围；应使用 status、has_issues、issue_severity、since（ISO 时间戳）或 case_queue_id 缩小查询范围，而不是获取所有数据。初始查询使用较小的 limit（默认 20，最大 100），并使用已配置操作所支持的筛选器。
• getRevision — 获取单个 Build，包括其 config（其中包含 AOP）。传入近期 Run 中的 build_id。
• listAgentRevisions — 获取 Agent 的 Build 历史（revision_number、时间戳）。
• listQueueAgents — 获取 Queue 的生产者和消费者，包括各自的 case_trigger_enabled、is_handover_target 和 problems 数组（multiple_triggers、producer_consumer_mix）。这是排查拓扑问题最快的方式——一次调用，无需 Run 样本。
• listCases / getQueue — 获取 Queue 的积压情况和状态。listCases 按状态（pending、needs_input、postponed、claimed、completed、failed）筛选后，会返回等待处理的 case 和 total。因此，数量多且等待时间长的 pending / postponed 积压（按最早时间优先排序）就是 Queue 堵塞的直接证据——无需 Run 样本。
• listAgentCaseTriggers — 查询哪些 Queue 会触发此 Agent（消费者绑定关系）。
• getAgent — 获取 Agent 层级的元数据（名称、交付设置）。
• getCase / listCaseRuns — 获取单个 case 的状态，以及处理过它的所有 Run，以便确认 case 是在反复流转，而非正常关闭。

让数据与问题相匹配。 少量近期 Run 就足以确定 build_id（实际生效的 AOP）和 case_queue_id（此 Agent 处理的 Queue）；除此之外，结构层面的问题应通过拓扑和 Queue 积压情况来判断，只有行为层面的问题（质量、升级、无效工作）才需要更大的 Run 样本。不要默认拉取大量 Run——按所需的分析视角获取数据。

要向用户询问的内容（粘贴模式）

在粘贴模式下，只询问最少的必要信息，并根据分析视角调整，而不是索要大量运行数据：

1. **对于队列工作流（结构性）：**谁负责生产、谁负责消费，以及积压有多深（pending / postponed / needs_input 案例的数量），再加上生效中的生产者和消费者 AOP。
2. **对于质量 / 行为问题：**近期 Run 样本——每个 Run 的状态、案例标题和评估分数（适当时仅筛选失败或问题）——以及受影响的各个 Run 的评估 final_comment 文本。
3. **始终询问：**足够的近期 Run 概览，以确认生效中的 AOP（build_id）以及 Agent 所使用的 Queue。

以结构信息开场（纯质量问题则以 Run 样本开场）；只有当第一轮信息不足以将问题归入分类体系时，才继续询问。

调查工作流

两种模式的步骤相同，只有数据来源不同。对于队列工作流，顺序应当先看结构：拓扑和 Queue 状态能以较低成本提供结构性发现，并说明实际需要查看多少个 Run（如果需要的话，除了少量概览之外）。

1. 界定问题并确定锚点。确定分析视角——结构性（拓扑、积压、拆解）还是行为性（质量、升级处理、无效工作）——以及范围（单个 Agent，还是生产者→消费者工作流）。抽取少量近期 Run 概览（使用 listRuns，取几个即可），查看 case_queue_id（此 Agent 所使用的 Queue）以及 Run 实际运行时的 build_id——这两项都是查找拓扑和生效中 AOP 所必需的。此概览也是行为分析的基线；只有在第 4 步才扩大样本。

2. **对于队列工作流，读取结构信息。**通过少量低成本调用获取结构性发现，无需大量 Run 样本。API 模式： 使用 listQueueAgents（生产者、消费者、problems）；通过 listCases 筛选 pending / needs_input / postponed，并按最早优先排序，查看 Queue 积压（积压很深且持续时间很长，是“积压”的直接信号）；使用 listAgentCaseTriggers 确认绑定关系。粘贴模式： 询问谁负责生产、谁负责消费，以及积压有多深。没有 case_queue_id 的独立 Agent 不具备拓扑结构——跳到第 4 步。

3. **读取交界处的 AOP。**使用概览中的 build_id，提取该 Build 中消费者（以及生产者）的 AOP。API 模式： 对该 build_id 调用 getRevision——AOP 位于 config 中。粘贴模式： 请用户粘贴生效中的 AOP。将生产者和消费者的 AOP 放在一起阅读——许多工作流问题都出现在二者交界处。

4. **仅针对行为问题扩大 Run 样本。**如果发现的问题已经是结构性的，第 1 步中的概览就足够了——不要再提取更多数据。对于质量或 Run 级行为问题，扩大样本（按 status / has_issues / issue_severity 缩小范围；只有在全面健康检查时才接近 100 个上限），然后分析样本（参见下方维度）：状态分布、评估通过率和严重程度、反复出现的 final_comment、运行频率和时长，以及 Run 所使用的 build_id。这里的计数将成为行为分析的证据。API 模式： 使用 listRuns 筛选 Agent。粘贴模式： 请用户提供列表。

5. **综合报告。**将主要问题归入分类体系，并附上能够证实各问题的证据——结构性问题使用拓扑 / 积压数据，行为性问题使用计数；针对每个问题提出一项具体改动。AOP 改动交由 aop-writer 处理；拓扑改动则作为架构建议进行描述。

在整组运行中分析哪些方面

每个维度都对应 listRuns 中 Runs 的一个字段。请量化，不要凭感觉判断。

• 状态分布 — 统计 completed / failed / interrupted / stopped / waiting / needs_attention / running 的数量。needs_attention 或 waiting 占比较高，表明升级处理或闭环存在问题；interrupted / stopped 则表明工作被浪费。
• 案例多样性 — 每次运行都是同一个 case_title，还是涉及许多不同的案例／市场？Runs 中反复出现同一个标题，说明案例迟迟无法关闭；案例多样，则意味着确有实际吞吐量。
• 评估分数 — 对每个 Run 的 eval_summaries，检查是否存在 passed < total。查看 severityCounts（critical / medium / low）。按严重程度归类——反复出现的 critical 是最值得关注的问题。
• 反复出现的评估评论 — 许多 Runs 中出现相同的 final_comment 问题，这是提示词存在问题的最强信号：AOP 每次运行都产生同一种缺陷。
• 频率和时长 — 根据 created_at / started_at 查看 Run 的频率，根据 started_at → completed_at 查看耗时。持续不断地执行微小且近乎相同的 Runs，暗示可能适合批处理或调度；耗时较长则可能说明 AOP 是一个单体。
• 构建版本分布 — 最近的 Runs 使用的是同一个 build_id，还是多个？如果行为变化发生在 Build 边界附近，原因可能是 AOP 编辑。

低效问题分类

大多数工作流问题都属于以下类型之一。指出类别，并用数量佐证。

1. 反复出现的质量缺口（由评估驱动）。 许多 Runs 都有相同的 final_comment，且 passed < total，通常集中在某个严重程度。原因：AOP 存在一个缺口，导致每次运行都产生相同的缺陷。证据：出现该问题的 Runs 数量及其严重程度。修复：补上 AOP 中遗漏该标准的那一行。

2. 无法关闭的案例（终态闭环缺失）。 案例通过延期／重新领取不断循环，却没有调用 complete_case / fail_case。证据——直接查看：listCases 中积压了大量 postponed / needs_input 案例；某个卡住案例的 listCaseRuns 显示被反复领取，却没有终态操作；运行样本中反复出现相同的 case_title 可作为佐证。修复：在相应 AOP 分支中添加缺失的终态操作。

3. 升级处理校准不当（HITL）。 过度升级——needs_attention / waiting 占比较高，而 AOP 本应自主决策；或升级不足——执行代价高昂的自主操作时没有 Human-in-the-loop 闸门。证据：状态分布与 AOP 决策规则的对比。修复：调整 AOP 中的阈值。

4. 本应批处理或调度的串行工作。 高频执行许多微小且近乎相同的 Runs，或持续不断地定期运行，却本应改用调度。证据：运行频率 + 案例标题是否相同。建议：通过队列批量处理，或改用定时触发器。

5. 生产者／消费者失衡或拓扑问题。 listQueueAgents 报告了 problems 条目（multiple_triggers、producer_consumer_mix），或生产者创建案例的速度超过消费者处理案例的速度。证据：problems 数组，以及 pending 积压增长速度超过消费者处理速度（listCases）。建议：拆分触发器、调整消费者并发量，或将生产者与消费者分开。

6. 单体 Agent（拆分信号）。 一个 Agent 的 AOP 跨越多个 Connection 域和不同的运行频率；其 Runs 耗时较长，并在衔接处失败。证据：AOP 长度／阶段边界，以及同一个 Agent 中多种互不相关的失败模式。建议：通过 Queue 或 request_handover 拆分为生产者→消费者。

7. 浪费的 Runs。 出现 interrupted / stopped 运行、延期循环，或没有推进工作的重试。证据：状态分布 + 反复出现的 build_id，但没有任何完成记录。修复：在 AOP 中添加提前返回或保护条件，让 Agent 停止执行无效工作。

如果某个问题不符合以上类型，请直接描述其模式。不要强行归类。

推荐内容示例

一条推荐是针对某个制品的一项具体更改，并附上促使提出该更改的证据：

• “最近 20 次 Runs 中有 12 次未通过 eval，评论是 ‘did not include the PO number’（全部为 medium）。引用要更改的 AOP 原文： ‘Reply to the supplier with the delivery status.’ → 应要求提供 PO 编号。交给 aop-writer。”
• “同一案例 ‘Reorder SKU-4471’ 出现在 9 次 Runs 中，全部处于 waiting 状态，从未 completed。消费者 AOP 的第 5 步在有库存分支中没有 complete_case。添加它。”
• “listQueueAgents 报告 Agent X 存在 producer_consumer_mix——它既向队列填入任务，也从队列取出任务。将它拆分成两个 Agent。”
• “最近 20 次 Runs 中有 16 次在近乎相同的单 SKU 案例上运行不到 20s。通过队列批处理，或改为每 15 分钟运行一次，而不是按案例触发。”

避免使用：“收紧 AOP”“提升质量”“考虑批处理”。用户无法照着原文采取行动的内容，就不是一条推荐。当修复涉及 AOP 时，引用要更改的确切原文——用户要求具体到这一程度。

移交给 aop-writer

如果推荐涉及更改 AOP，不要在这里直接重写 AOP。 将任务移交给 aop-writer，并提供以下三项内容：

1. 生效的 Build（Runs 执行时使用的 build_id），以便它基于确切的 AOP 进行修改。传递 ID，而不是 AOP 文本。
2. 具体的更改请求，使用用户会说的话表述（“重写第 5 步，要求在给供应商的回复中提供 PO 编号”）。
3. 要修改的 AOP 文件（aops/<agent-id>.md），以便直接在原文件中编辑，而不是重新输入。

aop-writer 会编写修复：将重写后的 AOP 留在该文件中，并返回已更改的段落。你不要这样做。这样划分职责是有意为之：workflow-debugger 找出系统性问题；aop-writer 编写修复。两者混在一起会导致重写流于表面，审计缺乏依据。

反模式——应当拒绝

• 报告行为问题，却不提供 Run 样本。 关于质量、升级处理或无效工作的说法，需要基于实际获取的 Runs 统计数量——没有这些依据就是猜测。（_结构性_发现——例如 problems 条目、严重积压——则依据拓扑和 Queue 状态，无须大量样本。）
• 把一两次 Runs 称为规律。 发现问题需要统计整个运行集。两次不理想的 Runs 应由 run-debugger 处理，而不是视为工作流效率问题。
• 审计了错误的 AOP——查看了 Agent 当前的 Build，但近期 Runs 实际运行的是更早的版本。读取 Runs 实际执行的 Build（build_id）。
• 只读取队列的一端。 必须同时读取生产者和消费者 AOP；问题往往出在两者的衔接处。
• 编造数据中没有显示的 Run 数量、eval 评论或 AOP 原文。 引用现有内容；存在信息缺口时就如实说明。
• 将无关更改捆绑为一条推荐，或给出超过少数几条推荐——按证据权重排序。
• 直接在此处重写 AOP。 移交给 aop-writer。

输出规则

返回一份结构化报告，包含以下带标签的部分，并按此顺序排列：

• 工作流的作用——用一句话说明。
• 主要低效问题——最多三项，按证据权重排序。每项都注明一个分类，并附上证据：运行集中的统计数量和/或引用的 eval 评论。
• 提示词更改——针对每项 AOP 层面的修复，注明制品（生产者或消费者 AOP，以及步骤），并引用要更改的确切原文。
• 架构建议——仅在数据支持时，提出拓扑层面的更改（批处理、调度、拆分、生产者/消费者再平衡）。如果没有此类建议，则省略该部分。
• 下一步——例如：“我可以调用 aop-writer 重写消费者 AOP 的第 5 步”，或“将 Run <id> 交给 run-debugger，查明转录层面的原因”。

如果用户只询问某个维度（例如“这个 Agent 是否过度升级处理？”），就针对该维度给出统计数量并跳过其余部分。

阅读请求

1. 在对话中查找 Agent 或 Queue 引用。 如果没有，先询问，再继续阅读。
2. 确定范围。 单个 Agent（“审查这个 Agent”）还是工作流（“为什么这个 Queue 堆积了”“分析这个生产者→消费者流程”）。前者分析一个 Agent 的 Runs；后者还会补充拓扑信息，并阅读两个 AOP。
3. 确定分析视角。 效率（速度、成本、浪费的 Runs、批处理）与质量（评估分数、反复出现的缺陷）或可靠性（收尾、升级处理）。优先采用用户指定的视角；只有在数据表明其他视角不可忽略时，才提及它们。

只能使用已配置的 Duvo 访问方式（API 模式）返回的数据，或用户提供的数据（粘贴模式）。不要推断 Files、Connections 的上游系统或未拉取的 Runs 中的内容。Run 集合、拓扑和 AOP 是事实依据。

返回前的最终检查

根据这份清单检查草稿，并修正所有不符合项。

• 每项发现都有与之匹配的证据支撑——行为模式需基于 Run 样本中的统计数据，结构性问题需基于拓扑、problems 或 Queue 积压情况；不能依据单个 Run 或主观猜测。
• 你读取了 Runs 实际运行时使用的 AOP（build_id），而不只是当前 Build。
• 对于 Queue 工作流，你读取了生产者和消费者双方的 AOP，并检查了 listQueueAgents 的 problems。
• 每项低效问题都使用分类体系中的名称，并附有证据。
• 每项提示词更改都引用了要修改的确切 AOP 行，并注明所属的工件。
• AOP 重写任务交给 aop-writer，不要在此处编写。
• 使用 Duvo 术语：Agent、Run、Build、AOP、Connection、Queue、Files、Setup。
• 没有编造数据未体现的 Run 数量、评估评论、AOP 行或拓扑信息。

Duvo 术语

描述工作流和修复方案时，请使用 Duvo 的名词。不要替换这些术语——用户正在产品中操作，这些词就是界面上显示的名称。

使用	不使用
Agent	assignment、AI 队友、机器人
Run	task、job、execution
Build	revision、version
AOP	SOP、说明、提示词、操作手册
Connection	integration、account
Queue	case queue、backlog
Files	knowledge base、documents
Setup	configuration、config

另请参阅

• run-debugger — 用于排查单个失败的 Run：它会读取运行记录和该 Run 使用的 Build。此技能会审查整个工作流；如果某种模式需要深入到运行记录层面，请将一个有代表性的 Run 交给它。
• aop-writer — 确定 AOP 级别的修复方案后，将生效中的 AOP 和更改请求交给它；此技能不会自行重写 AOP。
• duvo-cli — 为配置为使用 CLI 的会话提供命令参考，也适用于通过 shell 进行审查的用户。

资源

• Duvo — 产品网站
• Duvo 文档 — 构建 Agent、AOP、Connection 和 Queue
• Web 应用 — 打开 Agent，检查其 Runs、评估结果以及运行时使用的 Build
• Duvo CLI（@duvoai/cli） — 此技能在 API 模式下依赖的读取命令；与 duvo-cli 技能配套使用
• 公开技能仓库 — 此技能采用 MIT 许可证的社区版本，可安装到第三方 Claude Code 配置中