// TraceEvent = Agent 内部发生的一条调试事件。
// 它不是聊天记录，而是工程排查用的“链路日志”。
type TraceEvent = {
  sessionId: string; // 哪个会话产生的事件。
  traceId: string;   // 当前事件 ID，方便串联一次任务里的多个步骤。
  time: string;      // 事件发生时间。
  phase:
    | "context_built"       // 已构建上下文：记录放了哪些 messages、token 多少。
    | "model_request"       // 准备调模型：记录模型名、工具列表、prompt 版本。
    | "model_response"      // 模型返回：记录文本、工具调用、usage、latency。
    | "tool_start"          // 工具开始执行：记录工具名和输入。
    | "tool_result"         // 工具成功返回：记录摘要、输出大小、是否截断。
    | "tool_error"          // 工具失败：记录错误码和错误信息。
    | "permission_decision" // 权限决策：allow/deny/ask 及原因。
    | "compaction"          // 上下文压缩：压缩前后 token 和摘要。
    | "final_answer";       // 最终回答：记录 stop reason 和摘要。
  data: unknown;            // 各阶段自己的结构化数据，真实系统要定义更细 schema。
};

// appendTrace = 把一条 trace 追加到本地 JSONL 文件。
// JSONL 一行一个 JSON，适合流式追加，也方便后续按行读取分析。
export async function appendTrace(event: TraceEvent) {
  await appendFile(
    // 每个 session 一个 trace 文件，便于按会话排查。
    `.agent/traces/${event.sessionId}.jsonl`,
    // 追加一行 JSON。注意真实系统要做敏感信息脱敏。
    JSON.stringify(event) + "\n"
  );
}

// traced = 给任意异步函数加 trace 的包装器。
// 用法：await traced(sessionId, "tool_start", { tool: "grep" }, () => runGrep())
export async function traced<T>(
  sessionId: string,             // 当前会话 ID。
  phase: TraceEvent["phase"],    // 当前阶段名，例如 model_request/tool_start。
  data: unknown,                 // 阶段相关数据，例如工具名、输入摘要。
  fn: () => Promise<T>           // 真正要执行的业务函数。
): Promise<T> {
  // 记录开始时间，用于计算耗时。
  const startedAt = Date.now();

  // 先记录 start 事件。即使后面卡住，也能知道卡在哪个阶段。
  await appendTrace({
    sessionId,
    traceId: crypto.randomUUID(),
    time: new Date().toISOString(),
    phase,
    data: { ...data, status: "start" }
  });

  try {
    // 执行业务函数。
    const result = await fn();

    // 成功后记录 success 和耗时。
    await appendTrace({
      sessionId,
      traceId: crypto.randomUUID(),
      time: new Date().toISOString(),
      phase,
      data: {
        status: "success",
        durationMs: Date.now() - startedAt
      }
    });

    // 把原函数结果原样返回，不改变业务行为。
    return result;
  } catch (error) {
    // 异常时记录 error 和耗时。
    await appendTrace({
      sessionId,
      traceId: crypto.randomUUID(),
      time: new Date().toISOString(),
      phase,
      data: {
        status: "error",
        durationMs: Date.now() - startedAt,
        // Error 对象取 message；非 Error 对象转字符串。
        error: error instanceof Error ? error.message : String(error)
      }
    });

    // 继续抛出，让上层按原本逻辑处理失败。
    throw error;
  }
}

// EvalCase = 一个固定测试用例。
// 每次改 prompt、工具策略、RAG 检索，都可以跑这些用例防回归。
type EvalCase = {
  id: string;    // 用例 ID，例如 tool-read-001。
  input: string; // 模拟用户输入。
  expected: {
    mustContain?: string[];    // 最终文本必须包含的关键词。
    mustNotContain?: string[]; // 最终文本不能出现的内容。
    toolCalls?: string[];      // 期望调用的工具名列表。
    stopReason?: StopReason;   // 期望停止原因，例如 final_answer。
  };
};

{
  "id": "tool-read-001",
  "input": "读取 README 并总结项目目标",
  "expected": {
    "toolCalls": ["read_file"],
    "mustContain": ["项目"],
    "stopReason": "final_answer"
  }
}

// runEval = 批量运行评测用例。
// 输入固定测试集，输出通过/失败统计。
export async function runEval(cases: EvalCase[]) {
  const results: EvalResult[] = [];

  for (const item of cases) {
    // query(item.input) 会产生 Agent 事件流：文本、工具调用、工具结果等。
    const events = await collectEvents(query(item.input));

    // judge 根据 expected 判断这次运行是否达标。
    const result = judge(item, events);

    // 收集每个用例结果。
    results.push(result);
  }

  return {
    total: results.length,                         // 总用例数。
    passed: results.filter(r => r.passed).length,  // 通过数量。
    failed: results.filter(r => !r.passed)         // 失败明细。
  };
}

// collectEvents = 把 Agent 的异步事件流收集成数组。
// Eval 需要完整事件列表，才能判断文本内容和工具调用。
async function collectEvents(stream: AsyncGenerator<AgentEvent>) {
  const events: AgentEvent[] = [];

  // for await 可以消费流式输出。
  for await (const event of stream) {
    events.push(event);
  }

  return events;
}

// judge = 最小评测判定器。
// 它不理解语义，只检查文本包含关系和工具调用是否符合预期。
function judge(test: EvalCase, events: AgentEvent[]): EvalResult {
  // 把所有文本增量拼成最终回答文本。
  const text = events
    .filter(e => e.type === "text_delta")
    .map(e => e.text)
    .join("");

  // 从事件里提取实际调用过的工具名。
  const toolCalls = events
    .filter(e => e.type === "tool_start")
    .map(e => e.call.name);

  // failures 为空表示通过；非空表示失败原因列表。
  const failures: string[] = [];

  // 检查必须出现的关键词。
  for (const needle of test.expected.mustContain ?? []) {
    if (!text.includes(needle)) {
      failures.push(`Missing text: ${needle}`);
    }
  }

  // 检查禁止出现的内容。
  for (const forbidden of test.expected.mustNotContain ?? []) {
    if (text.includes(forbidden)) {
      failures.push(`Forbidden text found: ${forbidden}`);
    }
  }

  // 检查期望工具是否被调用。
  for (const tool of test.expected.toolCalls ?? []) {
    if (!toolCalls.includes(tool)) {
      failures.push(`Expected tool not called: ${tool}`);
    }
  }

  return {
    id: test.id,                 // 用例 ID。
    passed: failures.length === 0, // 没有失败原因就算通过。
    failures                     // 失败原因，给调试报告用。
  };
}

几个名字展开说一下:BFCL 是 Berkeley Function Calling Leaderboard,专测模型会不会正确选函数、填参数;
ToolBench 和 API-Bank 测模型读了 API 文档后能不能把一串工具调用串对;
GAIA 是一套要靠搜索、读文件、多步推理才答得出来的综合助手题;
WebArena 让 Agent 在仿真网站上完成订票、购物这类真实网页任务;
SWE-bench 从 GitHub 真实 issue 出题,判定标准是修完之后项目测试能不能跑过;

type HarnessFingerprint = {
  model: string;
  systemPromptHash: string;
  toolSchemaHash: string;
  skillSetHash: string;
  contextPolicyVersion: string;
  permissionPolicyVersion: string;
  recoveryPolicyVersion: string;
};

// DebugReport = 一次失败任务的结构化复盘报告。
// 适合保存到 Obsidian，之后能按“上下文/工具/模型/验证”逐项排查。
type DebugReport = {
  sessionId: string;       // 会话 ID。
  userInput: string;       // 用户原始问题。
  model: string;           // 使用的模型。
  promptVersion: string;   // 使用的 prompt 版本，方便回归定位。
  contextParts: string[];  // 本轮上下文包含哪些部分：memory、git、files、rag 等。
  toolCalls: Array<{
    name: string;      // 工具名。
    ok: boolean;       // 工具是否成功。
    summary?: string;  // 成功摘要。
    error?: string;    // 失败错误。
  }>;
  stopReason: StopReason; // 模型停止原因。
  tokenUsage: TokenUsage; // token 用量，排查成本和上下文压力。
};

// PromptVersion = 一个 prompt 版本记录。
// prompt 一变，eval 结果可能变，所以必须可追踪。
type PromptVersion = {
  id: string;          // 版本 ID，例如 agent-base-2026-07-05。
  name: string;        // 人类可读名称。
  contentHash: string; // prompt 内容 hash，用来确认具体文本是否变过。
  createdAt: string;   // 创建时间。
};

{
  "phase": "model_request",
  "data": {
    "model": "default",
    "promptVersion": "agent-base-2026-07-05"
  }
}

// AgentEvalCase = 一个可重复执行的 Agent 评测样本。
// 它不仅描述“问什么”，还描述期望经过哪些中间行为。
type AgentEvalCase = {
  id: string;                         // 稳定 ID，失败报告和历史趋势都靠它关联。
  category: "rag" | "tool" | "safety" | "format" | "memory" | "workflow";
  task: string;                       // 用户输入，尽量接近真实任务而不是关键词测试。
  fixtureVersion: string;             // 知识库、工具 schema、prompt 的夹具版本。

  expected: {
    finalAnswerMustContain?: string[]; // 最终答案必须包含的事实或字段。
    finalAnswerMustNotContain?: string[]; // 防止编造、泄露、越权措辞。
    requiredToolCalls?: string[];      // 必须调用的工具名。
    forbiddenToolCalls?: string[];     // 安全用例中绝不能调用的工具名。
    requiredSources?: string[];        // RAG 用例要求命中的来源。
    shouldRefuse?: boolean;            // 无资料、越权、危险操作时必须拒答。
  };

  probes: {
    tracePhases: string[];             // 必须出现的 trace 阶段，例如 retrieve/tool_call/model_response。
    maxTurns?: number;                 // 防止工作流绕圈。
    maxToolCalls?: number;             // 防止工具滥用。
    maxTokens?: number;                // 成本预算。
  };

  regressionOf?: string;               // 如果来自历史事故，记录事故/debug report ID。
};

{
  "evalRunId": "run-2026-07-06-001",
  "promptVersion": "agent-base-2026-07-06",
  "retrieverVersion": "notes-index-v3",
  "toolSchemaVersion": "tools-2026-07-06",
  "caseId": "rag-no-evidence-refuse",
  "passed": false,
  "failureType": "rag_grounding",
  "expected": "shouldRefuse=true",
  "actual": "answered_without_source",
  "traceId": "trace-abc",
  "diff": {
    "selectedChunks": [],
    "toolCalls": ["search_notes"],
    "tokenUsage": 1840
  }
}

// IncidentRunbook = 一类 Agent 事故的处置脚本。
// 它把告警、证据、止血、根因、回归样本连在一起。
type IncidentRunbook = {
  id: string;                         // 稳定 ID，例如 rag-grounding-regression。
  alertName: string;                  // 告警名，和监控系统对应。
  severity: "P0" | "P1" | "P2";       // 严重程度，决定是否立即回滚。
  firstChecks: string[];              // 值班第一轮必须看的 trace/eval 字段。
  mitigation: string[];               // 止血动作，例如回滚、限流、关闭工具。
  rootCauseFields: string[];          // 根因分析要对比的版本和证据。
  regressionCaseTemplate: string;     // 事故复盘后沉淀成哪类 eval case。
};

{
  "id": "rag-grounding-regression",              // RAG 证据退化事故。
  "alertName": "groundedness_eval_drop",         // groundedness 指标下降。
  "severity": "P1",                              // 影响回答质量，需要快速止血。
  "firstChecks": [
    "promptVersion",                             // 是否刚改过 prompt。
    "retrieverVersion",                          // 是否刚重建索引或改检索策略。
    "selectedChunkIds",                          // 模型看到的证据是什么。
    "answerCitations"                            // 最终引用是否来自这些证据。
  ],
  "mitigation": [
    "rollback retrieverVersion",                 // 先回滚检索策略。
    "reduce traffic to new prompt",              // 新 prompt 降流。
    "force refusal when requiredSources missing" // 没证据时强制拒答。
  ],
  "regressionCaseTemplate": "rag_required_sources" // 事故沉淀成 RAG 来源命中回归用例。
}