dogfood

Dogfood 技能

VCS 提供方

此技能通过 Exarchos MCP 操作（create_issue 等）执行 VCS 操作。 这些操作会自动检测并路由到正确的 VCS 提供方（GitHub、GitLab、Azure DevOps）。 无需使用 gh/glab/az 命令——MCP 服务会处理提供方分发。

概述

对 Exarchos MCP 工具使用情况进行回顾性分析。将 MCP 服务自身的自助能力作为主要诊断工具——通过描述 API、视图、操作手册和运行手册，并将它们用于自身诊断故障。

这是较早的、仅基于对话记录的分类排查方法在运行时、事件溯源方面的对应方案：Agent 会通过 exarchos_workflow feedback 实时提交摩擦报告，这些报告会进入共享的 meta/feedback 流。Dogfood 将该流作为一级输入读取（步骤 1h）——每个 feedback.recorded 事件都是 Agent 在问题造成影响时已捕获的摩擦信号，而不是事后重建的记录。

三种不同的故障模式需要不同的修复方式——代码更改、文档更新或技能指令改进。混为一谈会浪费精力。

平台无关性

根据 docs/designs/archive/2026-03-09-platform-agnosticity.md：MCP 服务是一个自给自足、平台无关的核心。调试跟踪完全依赖 MCP 工具，而非对话内容审查，因此适用于任何 MCP 客户端。扫描对话是辅助方式。

**诊断自助工具：**用于 HSM 验证的 describe(topology)、用于遵循情况检查的 describe(playbook)、用于事件架构／目录比对的 describe(eventTypes, emissionGuide)、用于架构／门控元数据的 describe(actions)、用于步骤符合性检查的 runbook(phase)，以及用于健康指标的 pipeline/convergence/telemetry 视图。

触发条件

在以下情况下激活此技能：

• 用户运行 /dogfood 或 dogfood
• 用户询问“本次会话出了什么问题”或“检查失败情况”
• 用户希望对某次工作流运行中的错误进行分类排查
• 工作流会话结束时，用于记录经验教训

流程

步骤 1：通过 MCP 自助能力进行调试跟踪

查询 MCP 服务自身的自助能力，构建真实、准确的诊断图景。这是主要调查方法——它使用任何 MCP 客户端都能访问的同一组工具。

1a. 确定活跃工作流

使用 exarchos_view，并设置 action: "pipeline"，获取活跃工作流的汇总视图，其中包含各自的阶段和任务数量。该视图默认限定在仓库范围内（仅显示调用方所在仓库）；当响应中的 unscopedTotal 大于 page.total 时，其他仓库中的工作流会被隐藏——请使用 scope: "all" 重新查询，以检查完整的跨仓库清单。

如果 $ARGUMENTS 指定了工作流或功能 ID，则将范围限定到该工作流。否则，检查所有未处于终止状态的工作流。

1b. 检查工作流状态和拓扑

针对每个相关工作流：

1. 读取状态——使用 exarchos_workflow get 获取当前阶段、任务、审查结果和门控结果。
2. 读取拓扑——使用 exarchos_workflow describe(topology: "<workflowType>") 获取 HSM 定义。将 Agent 尝试进行的阶段转换与有效转换进行比较。无效的转换尝试 = 文档问题（技能指定了错误路径）或用户错误。
3. 检查守卫前置条件——对于 workflow.guard-failed 事件，在拓扑中查找相应的守卫，了解哪些前置条件未满足。

1c. Playbook 遵循情况检查

使用 exarchos_workflow describe(playbook: "<workflowType>") 获取各阶段的 playbook。对于执行过的每个阶段，将 playbook 的 tools、events、transitionCriteria、guardPrerequisites、humanCheckpoint 和 compactGuidance 与 Agent 的实际操作以及技能文档中的规定进行对比。

Playbook 违规是重要的诊断线索：

• Agent 有所偏离，而技能文档指示它这样做 → 文档问题（技能文档与 playbook 矛盾）
• Agent 有所偏离，而技能文档与 playbook 一致 → 用户错误
• Playbook 有误（规定了无效的工具或事件）→ 代码错误

1d. 事件日志分析

使用 exarchos_event query(stream) 查询工作流的事件流。检查以下情况：

• 被拒绝的事件 — 尽管 Agent 尝试发出，但日志中并不存在（结合对话中的错误进行佐证）
• 缺失的事件 — 对照 playbook 的 events 字段以及 exarchos_event describe(emissionGuide: true)。模型应发出但缺失的事件 = 文档缺口或用户错误。
• 序列异常 — 顺序错误、重复事件或时间线缺口
• 架构不匹配 — 使用 describe(eventTypes: [...]) 获取权威的 JSON Schema。将实际负载与架构对比，检查语义错误的字段。

1e. 编排操作与关卡分析

1. 架构验证 — 使用 exarchos_orchestrate describe(actions: [...]) 获取权威架构。将 Agent 的参数与架构对比，以发现过时的技能文档或即兴操作。
2. 关卡元数据 — Describe 输出包含 { blocking, dimension, autoEmits }。检查：Agent 是否正确处理了阻塞/非阻塞关卡？预期的自动发出事件是否触发？
3. 关卡收敛情况 — 使用 exarchos_view convergence 查看各维度（D1-D5）的通过率。收敛率低意味着可能存在系统性的关卡问题。

1f. 操作手册遵循情况检查

使用 exarchos_orchestrate runbook(phase) 获取相关操作手册。检查：步骤顺序、决策分支是否正确（含 decide 字段的步骤）、是否遵循 onFail 指令（stop/continue/retry），以及 templateVars 是否完整。

1g. 遥测审查

使用 exarchos_view telemetry 查看各工具的性能。标记：高错误率（系统性问题）、高调用次数（重试循环），以及 playbook 要求调用但从未调用的工具。

1h. 摩擦反馈通道（feedback.recorded）

使用 exarchos_event query(stream: "meta/feedback") 读取通过 exarchos_workflow feedback 提交的近期摩擦报告。这些是Agent 实时反馈的问题记录——Agent 遇到难用的功能时，会在失败调用期间将问题标记出来，而不是悄悄重试。将每条报告视为预先发现的问题：

• message — Agent 对所遇摩擦的描述。将其作为第 3 步中“出了什么问题”的说明，而不是从对话记录中重新推断。
• sessionContext（workflow / action / errorCode）— 将报告关联到发生问题的工作流和操作。与事件日志（1d）和遥测（1g）交叉核对，以寻找服务端佐证。
• upstreamDelivered — 如果已配置 configuredEndpoint，但该值为 false，这本身就是一个发现（联邦转发环节失败）。

每条报告仍需经过第 4 步分类（代码 / 文档 / 用户）。没有匹配服务端缺陷的 feedback.recorded 事件，不会因此自动被忽略——即使调用最终成功，Agent 遇到的摩擦也能提供有价值的信号（参见重试后成功反模式）。应将这些报告与调试跟踪中已发现的问题去重，确保反馈通道报告及其跟踪证据合并为同一条发现，而不是两条。

步骤 2：扫描会话中的工具调用失败

补充调试跟踪中的客户端上下文——检查对话中是否有 Exarchos 工具调用失败。

**注意：**此步骤取决于平台（需要对话历史记录）。在无法检查历史记录的平台上跳过；调试跟踪本身已足够。

目标工具：exarchos_workflow、exarchos_event、exarchos_orchestrate、exarchos_view、exarchos_sync

错误信号：INVALID_INPUT、VALIDATION_ERROR、BATCH_APPEND_FAILED、Zod 错误（invalid_type、invalid_enum_value、unrecognized_keys）、ENOENT、CLAIM_FAILED、SEQUENCE_CONFLICT、CAS 耗尽、重试序列、重试后成功的调用。

步骤 3：诊断每个故障

合并调试跟踪和会话扫描的发现。针对每个故障，记录：

1. 尝试了什么——操作、参数、意图
2. 出了什么问题——错误消息和验证路径
3. 服务端证据——事件日志、状态、describe 输出、视图
4. 权威参考——提供事实依据的自助查询（操作手册、拓扑、架构、运行手册）
5. 根本原因——参见 references/root-cause-patterns.md
6. 修复类别——代码、文档或用户行为

将只能通过服务端检查发现的差异标记为 仅跟踪记录中的发现。

步骤 4：归类到各个类别

将每个故障归入且仅归入一个根本原因类别：

类别 1：代码缺陷

MCP 服务、事件存储或工作流引擎存在缺陷。

**信号：**架构拒绝有效输入（通过 describe 确认）、没有并发写入者时发生 CAS 失败、门控执行过严、使用相同参数重试后成功（竞态条件）、状态损坏、拓扑与引擎不匹配、自动发出事件失败。

**操作：**提交缺陷问题，附上复现步骤、预期结果与实际结果，以及建议的修复方案。

类别 2：文档问题

技能文档有误、不完整，或与 MCP 服务的自助输出不同步。

**信号：**技能负载与 describe 架构不匹配、技能文档与操作手册存在差异、技能文档记录了不存在的拓扑路径、缺少事件类型（对比事件发出指南）、通过重试发现字段、运行手册与技能文档矛盾、compactGuidance 不一致。

**操作：**提交文档问题，注明文件:行号、差异，以及 describe 输出中的正确信息。

类别 3：用户错误

Agent 对工具的使用有误，而文档和 describe 输出对此均有正确说明。

**信号：**格式不匹配（describe 与文档的说明一致）、序列无效（拓扑已确认）、缺少技能文档和操作手册都要求的上下文、无正当理由偏离运行手册。

**操作：**如果错误频繁发生，记录下来以改进技能。

步骤 5：生成报告

使用 references/report-template.md 中的模板生成报告。包括：

• 各类别的汇总计数
• 调试跟踪摘要（检查的工作流、查看的事件、发出的 describe 查询、查阅的视图）
• 每个故障的完整诊断（包括权威自助参考）
• 仅跟踪记录中的发现部分（仅通过服务端检查发现的问题）
• 操作手册/运行手册遵循情况摘要
• 可执行的后续步骤（缺陷/文档问题的草拟内容）

步骤 6：提出提交问题

对于 代码缺陷 和 文档问题 类别中的发现，提出创建 GitHub 问题：

exarchos_orchestrate({ action: "create_issue", title: "<type>: <summary>", body: "<issue body>", labels: ["bug"] })

仅在用户确认后提交问题——先展示草稿。

必需的输出格式

{
  "session_summary": {
    "total_tool_calls": 0,
    "failed_tool_calls": 0,
    "failure_rate": "0%",
    "debug_trace": {
      "workflows_inspected": 0,
      "events_reviewed": 0,
      "describe_queries": 0,
      "views_consulted": [],
      "feedback_reports_reviewed": 0,
      "trace_only_findings": 0
    }
  },
  "playbook_adherence": {
    "phases_checked": 0,
    "violations": [
      {
        "phase": "delegate",
        "field": "events",
        "expected": "team.spawned, team.task.assigned",
        "actual": "none emitted",
        "bucket": "documentation_issue"
      }
    ]
  },
  "runbook_conformance": {
    "runbooks_checked": 0,
    "deviations": []
  },
  "buckets": {
    "code_bug": [],
    "documentation_issue": [],
    "user_error": []
  },
  "findings": [
    {
      "id": 1,
      "bucket": "code_bug | documentation_issue | user_error",
      "tool": "exarchos_workflow",
      "action": "update",
      "error": "INVALID_INPUT: ...",
      "root_cause": "Schema rejects null branch on pending tasks",
      "trace_evidence": "describe(actions: ['update']) shows branch as required string; event log confirms no task.updated event",
      "authoritative_ref": "exarchos_workflow describe(actions: ['update']) → TaskSchema",
      "severity": "HIGH | MEDIUM | LOW",
      "suggested_fix": "Accept nullable branch in TaskSchema",
      "issue_draft": {
        "title": "bug: workflow task schema rejects null branch",
        "labels": ["bug"],
        "body": "..."
      }
    }
  ],
  "trace_only_findings": [
    {
      "id": "T1",
      "description": "State drift: agent assumed phase was 'delegate' but server shows 'plan'",
      "evidence": "exarchos_workflow get shows phase=plan; topology confirms plan→delegate requires planReviewComplete guard",
      "authoritative_ref": "exarchos_workflow describe(topology: 'feature') → guards",
      "bucket": "documentation_issue",
      "suggested_fix": "Skill should instruct agent to verify phase via get before proceeding"
    }
  ]
}

反模式

不要	应改为
跳过调试跟踪，只扫描对话	始终先查询 MCP 自助工具——扫描对话仅作补充
猜测架构预期的内容	使用 describe 获取权威架构——它们是事实依据
凭记忆评估操作手册的遵循情况	查询 describe(playbook)，获取实际规定的工具、事件和标准
未经检查就假定拓扑结构	查询 describe(topology)，获取有效的转换、守卫条件和效果
当技能文档与操作手册矛盾时责怪用户	如果技能文档与操作手册／describe 输出不一致，这是文档问题
提交重复问题	起草前先检查现有的开放和已关闭问题
将重试归类为单独的失败	将重试序列合并为单个发现
忽略重试后成功的调用	即使最终成功，这些调用也反映了摩擦
纳入 Exarchos 以外的失败	严格限定为 5 个 Exarchos 工具——其他 MCP 失败不在范围内
报告未经跟踪记录佐证、仅基于对话的发现	尽可能将每项发现与服务端状态交叉核对