@allbluecn/web-app 0.17.2 → 0.18.0

package/src/server/mcp/tools.ts

@@ -0,0 +1,1020 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// MCP 工具集（任务 21 六 bug 工具 + 任务 24 test 执行域四工具）：
+// bug 域 list_bugs / get_bug / claim_fix / report_progress / report_result / list_events；
+// test 域（§8.2 钉死）list_pending_execs / claim_exec / report_step / report_exec_result。
+// 注册表 {name, schema, handler}，inputSchema 由 zod 4 z.toJSONSchema() 生成
+//（tool-schemas.ts 单一事实源）；scope 分流（§8.1）在 protocol.ts TOOLS_BY_SCOPE。
+//
+// IO 边界分层（承任务 20 口径）：本模块与 protocol.ts 同属应用层——
+// tools/call 分发链只在服务端执行（路由层 server.handlers 内），可直接
+// import prisma 做数据访问；测试照 report-handler 样板全 mock。
+//
+// 数据边界：一切查询以 ctx.auth.projectId 收敛（token 为项目级凭证，
+// 越权 runCaseId 与不存在同话术返回，不泄漏存在性）。
+//
+// 信任模型（§10.2）：同项目 = 同信任域，report_* 按 runCaseId 定位活跃
+// ExecRun，不校验 agentName 归属（MVP 接受，断线重连按同名回池重抢 §8.3）。
+//
+// 防撞车（审查重点 2/4）：claim_exec 原子认领收拢在 server/testcase/exec-pool.ts
+// 的 claimExec（建 ExecRun 与条件回填 execRunId 同事务，count=0 → -32001，事务
+// 回滚撤销 ExecRun 创建）；超时回收（15min 无步/30min 无终局 → timeout_reclaimed
+// + RunCase 回 untested）由同模块 scanExpired + scheduleExecReap 惰性执行，
+// list_pending_execs 轮询入口触发；report_* 对 ExecRun 活跃态（claimed|running）
+// 条件更新，count=0 或读态非活跃即 -32002（超时回收后迟到上报被拒）。
+//
+// flaky 自动重试（任务 32，规格 §10）：report_exec_result fail 分支读 TestExecRun
+// 历史 finalVerdict 裁决（flaky-retry.ts）——首例失败回池重试一次（retryFailedExecOnce
+// 事务后 fire-and-forget，RunCase 回 untested 让 agent 重新认领）；两态不一致
+// mark_flaky（retest + flaky=true，不转 bug 不计指纹）；一致 failed triage（保持
+// failed 进归因队列）。uncertain 既有 retest 语义不参与 flaky 链。
+import { prisma } from "@allbluecn/database";
+import type { Prisma } from "@allbluecn/database";
+import type { McpRequestContext, McpToolCallResult, McpToolDefinition } from "./protocol";
+import {
+  claimExecSchema,
+  claimFixSchema,
+  getBugSchema,
+  listBugsSchema,
+  listEventsSchema,
+  listPendingExecsSchema,
+  reportExecResultSchema,
+  reportProgressSchema,
+  reportResultSchema,
+  reportStepSchema,
+} from "./tool-schemas";
+import { CODE_EXEC_REPORT_REJECTED, McpProtocolError } from "./tool-errors";
+import { claimExec, scheduleExecReap } from "@/server/testcase/exec-pool";
+import {
+  decideFlakyAction,
+  extractFinalVerdicts,
+  scheduleFailedExecRetry,
+} from "@/server/testcase/flaky-retry";
+import { runStepEventBus } from "@/server/testcase/step-events";
+import { finalizeRunIfComplete } from "@/server/testcase/run-finalize";
+import { fireTestRunWebhook } from "@/server/testcase/run-webhook";
+import { fireBugWebhook } from "@/server/bug-report/webhook-out";
+import { z } from "zod";
+
+/** 活跃修复任务状态集（BugFixRun 状态机 pending→claimed→in_progress→completed|failed|cancelled） */
+export const ACTIVE_RUN_STATUSES = ["pending", "claimed", "in_progress"] as const;
+
+/** ExecRun 活跃态（认领后回报窗口；终态/timeout_reclaimed 拒绝 report → -32002） */
+const ACTIVE_EXEC_RUN_STATUSES = ["claimed", "running"] as const;
+
+/** AI 终局判定 → RunCase 终态映射（§8.2 钉死；R16 教训：恒置写入不读现状） */
+const VERDICT_TO_RUN_CASE_STATUS = {
+  pass: "passed",
+  fail: "failed",
+  uncertain: "retest",
+} as const;
+
+const LIST_BUGS_DEFAULT_LIMIT = 20;
+const GET_BUG_EVENT_COUNT = 5;
+const LIST_EVENTS_DEFAULT_LIMIT = 20;
+const LIST_PENDING_DEFAULT_LIMIT = 20;
+
+export const TOOL_NAMES = {
+  listBugs: "list_bugs",
+  getBug: "get_bug",
+  claimFix: "claim_fix",
+  reportProgress: "report_progress",
+  reportResult: "report_result",
+  listEvents: "list_events",
+  listPendingExecs: "list_pending_execs",
+  claimExec: "claim_exec",
+  reportStep: "report_step",
+  reportExecResult: "report_exec_result",
+} as const;
+
+// ── 响应构造（§10.2：全部返回 content [{type:"text", text: JSON.stringify}]）──
+const ok = (payload: Record<string, unknown>): McpToolCallResult => ({
+  content: [{ type: "text", text: JSON.stringify({ ok: true, ...payload }) }],
+});
+
+/** 工具级错误：isError: true + 可读 message（不抛协议层错误，客户端可解析重试） */
+const toolError = (
+  message: string,
+  detail: Record<string, unknown> = {},
+): McpToolCallResult => ({
+  isError: true,
+  content: [{ type: "text", text: JSON.stringify({ ok: false, error: true, message, ...detail }) }],
+});
+
+/** JSON 字段落库类型收敛：unknown 深度结构经 JSON round-trip（照 report-handler） */
+const toJsonValue = (value: unknown): Prisma.InputJsonValue =>
+  JSON.parse(JSON.stringify(value)) as Prisma.InputJsonValue;
+
+// ── 数据访问助手（全部以 projectId 收敛）──
+
+/** 越权 bugId 与不存在同话术：findFirst({id, projectId}) 单步收敛边界 */
+const findBugInProject = (bugId: string, projectId: string) =>
+  prisma.bug.findFirst({ where: { id: bugId, projectId } });
+
+const findActiveRun = (bugId: string) =>
+  prisma.bugFixRun.findFirst({
+    where: { bugId, status: { in: [...ACTIVE_RUN_STATUSES] } },
+    orderBy: { createdAt: "desc" },
+  });
+
+const activeRunView = (run: {
+  id: string;
+  status: string;
+  triggerType: string;
+  agentName: string | null;
+  claimedAt: Date | null;
+}) => ({
+  id: run.id,
+  status: run.status,
+  triggerType: run.triggerType,
+  agentName: run.agentName,
+  claimedAt: run.claimedAt,
+});
+
+const requireBug = async (bugId: string, ctx: McpRequestContext) => {
+  const bug = await findBugInProject(bugId, ctx.auth.projectId);
+  if (!bug) {
+    return {
+      bug: null,
+      error: toolError(`BUG 不存在或无权访问：${bugId}`),
+    };
+  }
+  return { bug, error: null };
+};
+
+/** 活跃修复任务前置检查：不存在 / 未认领分别给出可操作引导 */
+const requireActiveClaimedRun = async (
+  bugId: string,
+  run: { status: string } | null,
+): Promise<string | null> => {
+  if (!run) return "无活跃修复任务：请先在 AllBlue 项目内创建 AI 修复任务（手动或自动入队），或调用 list_bugs 确认";
+  if (run.status === "pending") {
+    return "修复任务尚未认领：请先调用 claim_fix 认领后再上报进度/结果";
+  }
+  return null;
+};
+
+// ── 工具 handler ──
+
+async function listBugsHandler(
+  args: z.output<typeof listBugsSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const limit = args.limit ?? LIST_BUGS_DEFAULT_LIMIT;
+  const projectId = ctx.auth.projectId;
+  const includeActiveRun = {
+    fixRuns: {
+      where: { status: { in: [...ACTIVE_RUN_STATUSES] } },
+      orderBy: { createdAt: "desc" as const },
+      take: 1,
+    },
+  };
+  const baseWhere: Prisma.BugWhereInput = {
+    projectId,
+    archived: false,
+    ...(args.severity ? { severity: args.severity } : {}),
+  };
+
+  // 无 status：优先返回「有待修复任务」的（§10.2），两阶段查询保持各自 lastOccurAt 序
+  if (!args.status) {
+    const withRuns = await prisma.bug.findMany({
+      where: { ...baseWhere, fixRuns: { some: { status: { in: [...ACTIVE_RUN_STATUSES] } } } },
+      orderBy: { lastOccurAt: "desc" },
+      take: limit,
+      include: includeActiveRun,
+    });
+    const bugs = [...withRuns];
+    if (bugs.length < limit) {
+      const rest = await prisma.bug.findMany({
+        where: { ...baseWhere, fixRuns: { none: { status: { in: [...ACTIVE_RUN_STATUSES] } } } },
+        orderBy: { lastOccurAt: "desc" },
+        take: limit - bugs.length,
+        include: includeActiveRun,
+      });
+      bugs.push(...rest);
+    }
+    return ok({
+      total: bugs.length,
+      bugs: bugs.map((bug) => ({
+        id: bug.id,
+        identifier: bug.identifier,
+        title: bug.title,
+        state: bug.state,
+        severity: bug.severity,
+        env: bug.env,
+        url: bug.url,
+        totalCount: bug.totalCount,
+        lastOccurAt: bug.lastOccurAt,
+        fixRun: bug.fixRuns[0] ? activeRunView(bug.fixRuns[0]) : null,
+      })),
+    });
+  }
+
+  const bugs = await prisma.bug.findMany({
+    where: { ...baseWhere, status: args.status },
+    orderBy: { lastOccurAt: "desc" },
+    take: limit,
+    include: includeActiveRun,
+  });
+  return ok({
+    total: bugs.length,
+    bugs: bugs.map((bug) => ({
+      id: bug.id,
+      identifier: bug.identifier,
+      title: bug.title,
+      state: bug.state,
+      severity: bug.severity,
+      env: bug.env,
+      url: bug.url,
+      totalCount: bug.totalCount,
+      lastOccurAt: bug.lastOccurAt,
+      fixRun: bug.fixRuns[0] ? activeRunView(bug.fixRuns[0]) : null,
+    })),
+  });
+}
+
+async function getBugHandler(
+  args: z.output<typeof getBugSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const bug = await findBugInProject(args.bugId, ctx.auth.projectId);
+  if (!bug) return toolError(`BUG 不存在或无权访问：${args.bugId}`);
+
+  const [recentEvents, activeRun, story] = await Promise.all([
+    prisma.bugEvent.findMany({
+      where: { bugId: bug.id },
+      orderBy: { occurTime: "desc" },
+      take: GET_BUG_EVENT_COUNT,
+    }),
+    findActiveRun(bug.id),
+    bug.storyId
+      ? prisma.story.findUnique({
+          where: { id: bug.storyId },
+          select: { id: true, identifier: true, title: true, state: true },
+        })
+      : Promise.resolve(null),
+  ]);
+
+  return ok({
+    bug: {
+      id: bug.id,
+      identifier: bug.identifier,
+      sequenceId: bug.sequenceId,
+      title: bug.title,
+      description: bug.description,
+      reproduceSteps: bug.reproduceSteps,
+      state: bug.state,
+      severity: bug.severity,
+      source: bug.source,
+      env: bug.env,
+      url: bug.url,
+      userAgent: bug.userAgent,
+      stackSummary: bug.stackSummary,
+      totalCount: bug.totalCount,
+      firstOccurAt: bug.firstOccurAt,
+      lastOccurAt: bug.lastOccurAt,
+      repoHints: bug.repoHints,
+      createdAt: bug.createdAt,
+    },
+    recentEvents,
+    activeFixRun: activeRun ? activeRunView(activeRun) : null,
+    story,
+  });
+}
+
+async function claimFixHandler(
+  args: z.output<typeof claimFixSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const { bug, error } = await requireBug(args.bugId, ctx);
+  if (!bug) return error;
+
+  const run = await findActiveRun(bug.id);
+  if (!run) {
+    return toolError(
+      "无活跃修复任务：请先在 AllBlue 项目内创建 AI 修复任务（手动或自动入队）",
+      { bugId: bug.id, identifier: bug.identifier },
+    );
+  }
+
+  // 防撞车（审查重点 4）：条件更新原子认领——status 仍为 pending 才生效，
+  // 影响行数 = 0 即已被并发认领（无 findFirst+update 竞态窗口）
+  const claimed = await prisma.bugFixRun.updateMany({
+    where: { id: run.id, status: "pending" },
+    data: {
+      status: "claimed",
+      agentName: args.agentName,
+      claimedAt: new Date(),
+    },
+  });
+  if (claimed.count === 0) {
+    const current = await prisma.bugFixRun.findUnique({ where: { id: run.id } });
+    const holder = current?.agentName ?? null;
+    return toolError(
+      `认领冲突：该修复任务已被认领（当前状态 ${current?.status ?? "未知"}${holder ? `，认领者 ${holder}` : ""}）`,
+      { runId: run.id, status: current?.status ?? null, agentName: holder },
+    );
+  }
+
+  await prisma.bugActivity.create({
+    data: {
+      bugId: bug.id,
+      userId: null, // agent 产生的活动无登录用户（照 sdk_reported 先例）
+      actorType: "agent",
+      agentName: args.agentName,
+      action: "fix_claimed",
+      isAI: true,
+    },
+  });
+
+  return ok({
+    bugId: bug.id,
+    identifier: bug.identifier,
+    runId: run.id,
+    status: "claimed",
+    agentName: args.agentName,
+  });
+}
+
+async function reportProgressHandler(
+  args: z.output<typeof reportProgressSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const { bug, error: bugError } = await requireBug(args.bugId, ctx);
+  if (!bug) return bugError;
+
+  const run = await findActiveRun(bug.id);
+  const runError = await requireActiveClaimedRun(bug.id, run);
+  if (runError) return toolError(runError, { bugId: bug.id });
+  if (!run) return toolError("无活跃修复任务", { bugId: bug.id });
+
+  // 首次进度：claimed → in_progress（条件更新；已 in_progress 不重复转移）
+  if (run.status === "claimed") {
+    await prisma.bugFixRun.updateMany({
+      where: { id: run.id, status: "claimed" },
+      data: { status: "in_progress" },
+    });
+  }
+
+  await prisma.bugActivity.create({
+    data: {
+      bugId: bug.id,
+      userId: null,
+      actorType: "agent",
+      agentName: run.agentName,
+      action: "fix_progress",
+      isAI: true,
+      metadata: toJsonValue({ phase: args.phase ?? null, message: args.message }),
+    },
+  });
+
+  return ok({
+    bugId: bug.id,
+    runId: run.id,
+    status: run.status === "claimed" ? "in_progress" : run.status,
+    phase: args.phase ?? null,
+  });
+}
+
+async function reportResultHandler(
+  args: z.output<typeof reportResultSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const { bug, error: bugError } = await requireBug(args.bugId, ctx);
+  if (!bug) return bugError;
+
+  const run = await findActiveRun(bug.id);
+  const runError = await requireActiveClaimedRun(bug.id, run);
+  if (runError) return toolError(runError, { bugId: bug.id });
+  if (!run) return toolError("无活跃修复任务", { bugId: bug.id });
+
+  const summaryJson = {
+    result: args.result,
+    summaryText: args.summary,
+    commitUrl: args.commitUrl ?? null,
+    prUrl: args.prUrl ?? null,
+    changedFiles: args.changedFiles ?? [],
+  };
+
+  // 防重复落账：条件更新（claimed/in_progress 才可完成），count=0 即已终态
+  const completed = await prisma.bugFixRun.updateMany({
+    where: { id: run.id, status: { in: ["claimed", "in_progress"] } },
+    data: {
+      status: "completed",
+      completedAt: new Date(),
+      summary: toJsonValue(summaryJson),
+    },
+  });
+  if (completed.count === 0) {
+    return toolError("修复任务已完结（重复上报被拒）", { runId: run.id });
+  }
+
+  // 仅 result=fixed 联动 Bug.state；failed/cannot_reproduce 留人工裁决（§10.2）
+  const bugState = args.result === "fixed" ? "fixed" : bug.state;
+  if (args.result === "fixed") {
+    await prisma.bug.update({ where: { id: bug.id }, data: { state: "fixed" } });
+  }
+
+  await prisma.bugActivity.create({
+    data: {
+      bugId: bug.id,
+      userId: null,
+      actorType: "agent",
+      agentName: run.agentName,
+      action: "fix_completed",
+      isAI: true,
+      ...(args.result === "fixed"
+        ? { field: "state", oldValue: bug.state, newValue: "fixed" }
+        : {}),
+      metadata: toJsonValue({ result: args.result }),
+    },
+  });
+
+  // webhook（fix.completed）任务 23 真实投递（§3.8 body 形状：修复结果明细
+  // （result/summary/commitUrl 等）留在 run.report 与活动流，body 只含规范字段）
+  fireBugWebhook("fix.completed", {
+    projectId: ctx.auth.projectId,
+    bug: {
+      id: bug.id,
+      identifier: bug.identifier,
+      title: bug.title,
+      severity: bug.severity,
+      state: bugState,
+      url: bug.url,
+      stackSummary: bug.stackSummary,
+    },
+    fixRunId: run.id,
+  });
+
+  return ok({
+    bugId: bug.id,
+    runId: run.id,
+    result: args.result,
+    bugState,
+    ...(args.result === "cannot_reproduce"
+      ? { hint: "已记录 cannot_reproduce：可在 AllBlue 详情面板发起 AI 复现交叉验证" }
+      : {}),
+  });
+}
+
+async function listEventsHandler(
+  args: z.output<typeof listEventsSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const { bug, error } = await requireBug(args.bugId, ctx);
+  if (!bug) return error;
+
+  const events = await prisma.bugEvent.findMany({
+    where: { bugId: bug.id },
+    orderBy: { occurTime: "desc" },
+    take: args.limit ?? LIST_EVENTS_DEFAULT_LIMIT,
+  });
+
+  return ok({
+    bugId: bug.id,
+    total: events.length,
+    events,
+  });
+}
+
+// ── test 执行域共享助手（文件内私有，照 run-cases.ts 事务内重读再合并口径）──
+
+interface StepResultEntry {
+  order: number;
+  status?: string;
+  actual?: string;
+  evidenceBlobIds?: string[];
+}
+
+/** stepResults Json 读侧收敛：bare array（schema 注释形状），异常形状按空数组起步 */
+const readStepResultList = (value: unknown): StepResultEntry[] =>
+  Array.isArray(value) ? (value as StepResultEntry[]) : [];
+
+/** stepResults 增量合并（与人工报步同口径：同 order 覆写 status/actual，order 升序） */
+function mergeStepResult(
+  existing: StepResultEntry[],
+  incoming: { order: number; status: string; actual?: string },
+): StepResultEntry[] {
+  const merged = existing.map((item) => ({ ...item }));
+  const prev = merged.find((item) => item.order === incoming.order);
+  if (prev) {
+    prev.status = incoming.status;
+    if (incoming.actual !== undefined) prev.actual = incoming.actual;
+  } else {
+    merged.push({ ...incoming });
+  }
+  merged.sort((a, b) => a.order - b.order);
+  return merged;
+}
+
+/** 快照步骤定位（报步 order 白名单 + action 文案取自快照，快照锁定 §3.7） */
+function findSnapshotStep(
+  caseSnapshot: unknown,
+  order: number,
+): { order: number; action: string } | null {
+  const snapshot = caseSnapshot as { steps?: { steps?: { order: number; action: string }[] } | null };
+  return snapshot?.steps?.steps?.find((step) => step.order === order) ?? null;
+}
+
+/** 项目边界 + run 存在性收敛：越权与不存在同话术（照 findBugInProject 口径） */
+async function loadRunCaseInProject(runCaseId: string, ctx: McpRequestContext) {
+  const runCase = await prisma.testRunCase.findUnique({
+    where: { id: runCaseId },
+    select: {
+      id: true,
+      runId: true,
+      caseSnapshot: true,
+      status: true,
+      startedAt: true,
+      stepResults: true,
+      execRunId: true,
+    },
+  });
+  if (!runCase) return null;
+  const run = await prisma.testRun.findUnique({
+    where: { id: runCase.runId },
+    select: {
+      id: true,
+      projectId: true,
+      status: true,
+      name: true,
+      planId: true,
+      startedAt: true,
+      createdById: true, // AI 回报无登录用户，run 完成活动归属批次创建人（ProjectActivity.userId 非空）
+    },
+  });
+  if (!run || run.projectId !== ctx.auth.projectId) return null;
+  return { runCase, run };
+}
+
+/** run 双终态守卫（§11 TestRun 状态机，口径同人工回报 loadReportContext） */
+function runStatusGuard(status: string): string | null {
+  if (status === "completed") return "批次已完成，无法回报";
+  if (status === "aborted") return "批次已中止，无法回报";
+  return null;
+}
+
+/** ExecRun 活跃态守卫：非活跃（终态/timeout_reclaimed/缺失）→ -32002（审查重点 5） */
+function requireActiveExecRun(
+  execRun: { status: string } | null,
+  runCaseId: string,
+): void {
+  if (!execRun) {
+    throw new McpProtocolError(
+      CODE_EXEC_REPORT_REJECTED,
+      "该用例尚未认领执行（无活跃 ExecRun），请先调用 claim_exec",
+      { runCaseId },
+    );
+  }
+  if (!(ACTIVE_EXEC_RUN_STATUSES as readonly string[]).includes(execRun.status)) {
+    throw new McpProtocolError(
+      CODE_EXEC_REPORT_REJECTED,
+      `执行运行非活跃状态（${execRun.status}），上报被拒（可能已被超时回收或已完结）`,
+      { runCaseId, execRunStatus: execRun.status },
+    );
+  }
+}
+
+// ── test 执行域工具 handler（任务 24，规格 §8.2）──
+
+async function listPendingExecsHandler(
+  args: z.output<typeof listPendingExecsSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const limit = args.limit ?? LIST_PENDING_DEFAULT_LIMIT;
+  const runWhere: Prisma.TestRunWhereInput = {
+    projectId: ctx.auth.projectId,
+    status: "running",
+  };
+  if (args.runId) {
+    // 显式 runId：先做项目归属校验（越权与不存在同话术），再收窄查询
+    const run = await prisma.testRun.findFirst({
+      where: { id: args.runId, projectId: ctx.auth.projectId },
+      select: { id: true },
+    });
+    if (!run) return toolError(`执行批次不存在或无权访问：${args.runId}`);
+    runWhere.id = args.runId;
+  }
+
+  // 惰性回收（§8.3）：agent 拉池即回收窗口——先腾位再查池，被回收用例本轮即可见。
+  // fire-and-forget 节流（exec-pool 内 5min 窗），失败静默不反噬池查询。
+  scheduleExecReap();
+
+  // 池口径（§8.2/§8.3）：untested 且未被认领（execRunId null）才算待执行；
+  // id 升序 = 快照创建序（cuid 单调，runs.ts 列 RunCase 同款先例；TestRunCase 无 createdAt 列）
+  const rows = await prisma.testRunCase.findMany({
+    where: { status: "untested", execRunId: null, run: runWhere },
+    orderBy: { id: "asc" },
+    take: limit,
+    select: { id: true, runId: true, caseSnapshot: true, run: { select: { targetEnv: true } } },
+  });
+
+  return ok({
+    total: rows.length,
+    items: rows.map((row) => ({
+      runCaseId: row.id,
+      runId: row.runId,
+      caseSnapshot: row.caseSnapshot,
+      targetEnv: row.run.targetEnv,
+      claimed: false,
+    })),
+  });
+}
+
+async function claimExecHandler(
+  args: z.output<typeof claimExecSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const loaded = await loadRunCaseInProject(args.runCaseId, ctx);
+  if (!loaded) return toolError(`执行用例不存在或无权访问：${args.runCaseId}`);
+  const { runCase, run } = loaded;
+
+  const runError = runStatusGuard(run.status);
+  if (runError) return toolError(runError.replace("无法回报", "无法认领执行"), { runId: run.id });
+  if (runCase.status !== "untested") {
+    return toolError("该用例已有终态结果，无法认领执行", {
+      runCaseId: runCase.id,
+      status: runCase.status,
+    });
+  }
+
+  // 原子认领（审查重点 2）：事务逻辑收拢在 exec-pool.claimExec——execRunId
+  // 仍为 null 才生效，count=0 即已被并发认领 → JSON-RPC -32001（事务回滚撤销
+  // ExecRun 创建，无孤儿记录）。
+  const execRun = await claimExec({ runCaseId: runCase.id, agentName: args.agentName });
+
+  return ok({
+    runCaseId: runCase.id,
+    runId: run.id,
+    execRunId: execRun.id,
+    status: "claimed",
+    agentName: args.agentName,
+  });
+}
+
+async function reportStepHandler(
+  args: z.output<typeof reportStepSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const loaded = await loadRunCaseInProject(args.runCaseId, ctx);
+  if (!loaded) return toolError(`执行用例不存在或无权访问：${args.runCaseId}`);
+  const { runCase, run } = loaded;
+
+  const runError = runStatusGuard(run.status);
+  if (runError) return toolError(runError, { runId: run.id });
+  if (!runCase.execRunId) {
+    requireActiveExecRun(null, runCase.id); // 恒抛 -32002（从未认领）
+  }
+
+  // 快照锁定的 order 白名单 + action 文案取自快照（§3.7，与人工报步同守卫）
+  const step = findSnapshotStep(runCase.caseSnapshot, args.order);
+  if (!step) return toolError("步骤序号不存在", { runCaseId: runCase.id, order: args.order });
+
+  const now = new Date();
+  const perStepCount = await prisma.$transaction(async (tx) => {
+    const execRun = await tx.testExecRun.findUnique({
+      where: { id: runCase.execRunId as string },
+      select: { status: true, report: true },
+    });
+    requireActiveExecRun(execRun, runCase.id);
+
+    // report.perStep 追加（§3.8 形状：{order, action, observed, verdict, screenshotBlobId?}）
+    const base = (execRun!.report ?? {}) as { perStep?: unknown };
+    const perStep = Array.isArray(base.perStep) ? [...base.perStep] : [];
+    perStep.push(
+      toJsonValue({
+        order: step.order,
+        action: step.action,
+        observed: args.observed,
+        verdict: args.status,
+        ...(args.screenshotBlobId ? { screenshotBlobId: args.screenshotBlobId } : {}),
+      }),
+    );
+    // 活跃态条件更新即 -32002 闸门（读态守卫 + 条件更新双路，防守卫后竞态）；
+    // 首次报步 claimed→running（超时回收口径 §8.3：claimed 15min 无步 / running 30min 无终局）
+    const updated = await tx.testExecRun.updateMany({
+      where: { id: runCase.execRunId as string, status: { in: [...ACTIVE_EXEC_RUN_STATUSES] } },
+      data: { status: "running", report: toJsonValue({ ...base, perStep }) },
+    });
+    if (updated.count === 0) {
+      throw new McpProtocolError(
+        CODE_EXEC_REPORT_REJECTED,
+        "执行运行非活跃状态，上报被拒（可能已被超时回收）",
+        { runCaseId: runCase.id },
+      );
+    }
+
+    // RunCase.stepResults 增量合并：事务内重读再合并（两写方并发不整体覆盖丢更新）
+    const fresh = await tx.testRunCase.findUnique({
+      where: { id: runCase.id },
+      select: { stepResults: true, startedAt: true },
+    });
+    const stepResults = mergeStepResult(readStepResultList(fresh?.stepResults), {
+      order: args.order,
+      status: args.status, // AI 三值原值落盘（uncertain 为 AI 值域扩展，不映射人工四值）
+      actual: args.observed, // observed 映射 actual，与人工 RunCaseStepResult DTO 同形
+    });
+    await tx.testRunCase.update({
+      where: { id: runCase.id },
+      data: {
+        // Json 列写入 cast（runs.ts 快照同款惯例；Prisma 仅 type-only import）
+        stepResults: stepResults as unknown as Prisma.InputJsonValue,
+        // 未执行用例首次报步置 startedAt（以事务内重读为准，已置不重置）
+        ...(fresh?.startedAt === null && { startedAt: now }),
+      },
+    });
+    return perStep.length;
+  });
+
+  // SSE 接缝（任务 26）：事务提交后向 /api/test-runs/$runId/events 通道推送步骤
+  // 事件（runStepEventBus 进程内发布/订阅，多实例边界见 step-events.ts）。接入形态
+  // 与 webhook 同款：事务外 fire-and-forget，监听器抛错只落 console.warn 不反噬
+  // 回报主链路（EventEmitter.emit 同步派发，故 try/catch 包裹）。
+  try {
+    runStepEventBus.emit(run.id, {
+      runId: run.id,
+      runCaseId: runCase.id,
+      order: step.order,
+      action: step.action,
+      observed: args.observed,
+      verdict: args.status,
+      screenshotBlobId: args.screenshotBlobId ?? null,
+      at: now.toISOString(),
+    });
+  } catch (err) {
+    console.warn(
+      "[test-run-step] SSE emit failed:",
+      err instanceof Error ? err.message : "unknown",
+    );
+  }
+
+  return ok({
+    runCaseId: runCase.id,
+    execRunId: runCase.execRunId,
+    order: args.order,
+    status: args.status,
+    perStepCount,
+  });
+}
+
+async function reportExecResultHandler(
+  args: z.output<typeof reportExecResultSchema>,
+  ctx: McpRequestContext,
+): Promise<McpToolCallResult> {
+  const loaded = await loadRunCaseInProject(args.runCaseId, ctx);
+  if (!loaded) return toolError(`执行用例不存在或无权访问：${args.runCaseId}`);
+  const { runCase, run } = loaded;
+
+  const runError = runStatusGuard(run.status);
+  if (runError) return toolError(runError, { runId: run.id });
+  if (!runCase.execRunId) {
+    requireActiveExecRun(null, runCase.id); // 恒抛 -32002（从未认领）
+  }
+
+  const now = new Date();
+  // R16 教训：终态从结果参数恒置写入（pass→passed / fail→failed / uncertain→retest），
+  // 不读 run/runCase 现状决定成败；任务 32 flaky 判定例外地读 TestExecRun 历史
+  // finalVerdict（非 run/runCase 现状）——首例失败回池自动重试一次（规格 §10），
+  // 两态不一致 mark_flaky（retest+flaky=true，不转 bug 不计指纹），一致 failed triage
+  // （status 保持 failed 进归因队列，任务 33 扫描 failed 非 flaky）。
+  const runCaseStatus = VERDICT_TO_RUN_CASE_STATUS[args.finalVerdict];
+
+  const summary = await prisma.$transaction(async (tx) => {
+    const execRun = await tx.testExecRun.findUnique({
+      where: { id: runCase.execRunId as string },
+      select: { status: true, report: true },
+    });
+    requireActiveExecRun(execRun, runCase.id);
+
+    // report 合并终局面（§3.8 形状：{ perStep, consoleLog?, networkLog?, finalVerdict }）
+    const base = (execRun!.report ?? {}) as Record<string, unknown>;
+    const report = toJsonValue({
+      ...base,
+      ...(args.consoleLog ? { consoleLog: args.consoleLog } : {}),
+      ...(args.networkLog ? { networkLog: args.networkLog } : {}),
+      finalVerdict: args.finalVerdict,
+    });
+    // 恒置 ExecRun 终态 completed；活跃态条件更新 count=0 即并发完结/回收（-32002 双路之二）
+    const completed = await tx.testExecRun.updateMany({
+      where: { id: runCase.execRunId as string, status: { in: [...ACTIVE_EXEC_RUN_STATUSES] } },
+      data: { status: "completed", completedAt: now, report },
+    });
+    if (completed.count === 0) {
+      throw new McpProtocolError(
+        CODE_EXEC_REPORT_REJECTED,
+        "执行运行已完结或已被回收，重复上报被拒",
+        { runCaseId: runCase.id },
+      );
+    }
+
+    // 任务 32 flaky 判定：读执行历史终局（排除本次，automation 形状 report 无
+    // finalVerdict 天然跳过），结合本次裁决 retry/mark_flaky/triage/none
+    const history = await tx.testExecRun.findMany({
+      where: {
+        runCaseId: runCase.id,
+        status: "completed",
+        id: { not: runCase.execRunId as string },
+      },
+      select: { report: true },
+      orderBy: { createdAt: "asc" },
+    });
+    const flakyDecision = decideFlakyAction({
+      priorVerdicts: extractFinalVerdicts(history.map((row) => row.report)),
+      currentVerdict: args.finalVerdict,
+    });
+
+    // 恒置 RunCase 终态（retest 属终态可再执行覆盖，§11）；mark_flaky 例外：
+    // 两态不一致终局 retest + flaky=true（不转 bug 不计指纹，任务 33+ 归因链）
+    await tx.testRunCase.update({
+      where: { id: runCase.id },
+      data: {
+        status: flakyDecision === "mark_flaky" ? "retest" : runCaseStatus,
+        ...(flakyDecision === "mark_flaky" && { flaky: true }),
+        actualResult: args.summaryText,
+        finishedAt: now,
+        ...(runCase.startedAt
+          ? { durationMs: Math.max(0, now.getTime() - runCase.startedAt.getTime()) }
+          : {}),
+      },
+    });
+
+    // 复用任务 14/15 管道：与 RunCase 状态变更同事务、且在其后调用
+    //（finalizeRunIfComplete 自带 running 守卫与全终态判定，非 running/未全终态 null 零写入）
+    const finalizeSummary = await finalizeRunIfComplete(tx, runCase.runId, now);
+    if (finalizeSummary !== null) {
+      await tx.projectActivity.create({
+        data: {
+          projectId: run.projectId,
+          userId: run.createdById, // agent 无登录用户，活动归属批次创建人
+          action: "completed",
+          targetType: "testrun",
+          targetId: run.id,
+        },
+      });
+    }
+    return { finalizeSummary, flakyDecision };
+  });
+
+  // webhook（test.run.completed）事务提交后 fire-and-forget（照 run-cases.reportResultFn 口径）
+  if (summary.finalizeSummary !== null) {
+    fireTestRunWebhook({
+      projectId: run.projectId,
+      run: {
+        id: run.id,
+        name: run.name,
+        planId: run.planId,
+        startedAt: run.startedAt ? run.startedAt.toISOString() : null,
+        completedAt: now.toISOString(),
+      },
+      summary: summary.finalizeSummary,
+    });
+  }
+
+  // 任务 32：首例失败事务提交后回池自动重试一次（fire-and-forget，retryFailedExecOnce
+  // 自带 run running 守卫 + arbiter 条件更新——批次已完结/人工已改判则静默放弃）
+  if (summary.flakyDecision === "retry") {
+    scheduleFailedExecRetry({
+      runId: run.id,
+      runCaseId: runCase.id,
+      execRunId: runCase.execRunId as string,
+    });
+  }
+
+  return ok({
+    runCaseId: runCase.id,
+    runId: run.id,
+    finalVerdict: args.finalVerdict,
+    // mark_flaky 例外：终局 retest（非 verdict 映射的 passed）——payload 反映实际落库终态
+    runCaseStatus: summary.flakyDecision === "mark_flaky" ? "retest" : runCaseStatus,
+    flakyDecision: summary.flakyDecision,
+    runCompleted: summary.finalizeSummary !== null,
+    ...(summary.finalizeSummary ? { summary: summary.finalizeSummary } : {}),
+  });
+}
+
+// ── 注册表：{name, schema, handler} → McpToolDefinition（inputSchema 由 z.toJSONSchema 生成）──
+interface ToolRegistration<TSchema extends z.ZodType> {
+  name: string;
+  description: string;
+  schema: TSchema;
+  handler: (args: z.output<TSchema>, ctx: McpRequestContext) => Promise<McpToolCallResult>;
+}
+
+function defineTool<TSchema extends z.ZodType>(
+  registration: ToolRegistration<TSchema>,
+): McpToolDefinition {
+  return {
+    name: registration.name,
+    description: registration.description,
+    inputSchema: z.toJSONSchema(registration.schema) as Record<string, unknown>,
+    handler: async (rawArgs, ctx) => {
+      const parsed = registration.schema.safeParse(rawArgs);
+      if (!parsed.success) {
+        const detail = parsed.error.issues
+          .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+          .join("; ");
+        return toolError(`参数校验失败：${detail}`);
+      }
+      try {
+        return await registration.handler(parsed.data, ctx);
+      } catch (err) {
+        // 协议级错误直通（claim 冲突 -32001 / 非活跃 report -32002），
+        // 由 protocol.handleToolCall 转 JSON-RPC error 响应（规格 §8.2 钉死）
+        if (err instanceof McpProtocolError) throw err;
+        console.error(`[bug-mcp] tool ${registration.name} failed:`, err);
+        return toolError(`工具执行失败：${registration.name}（内部错误，请重试）`);
+      }
+    },
+  };
+}
+
+export const BUG_MCP_TOOLS: McpToolDefinition[] = [
+  defineTool({
+    name: TOOL_NAMES.listBugs,
+    description:
+      "列出项目的 BUG（含活跃 AI 修复任务状态）。无 status 时优先返回有待修复任务的 BUG，适合 AI 修复工作流拉取任务。",
+    schema: listBugsSchema,
+    handler: listBugsHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.getBug,
+    description:
+      "获取单个 BUG 全量上下文：描述/复现步骤/堆栈/环境/最近 5 条事件样本/关联 story/活跃修复任务，修复前必读。",
+    schema: getBugSchema,
+    handler: getBugHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.claimFix,
+    description:
+      "认领一个 pending 状态的 AI 修复任务（原子认领，先到先得；已被认领返回冲突与认领者）。认领成功后可 report_progress / report_result。",
+    schema: claimFixSchema,
+    handler: claimFixHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.reportProgress,
+    description:
+      "上报修复进度（落活动流；首次上报将任务从 claimed 推进到 in_progress）。phase: analyzing|fixing|verifying。",
+    schema: reportProgressSchema,
+    handler: reportProgressHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.reportResult,
+    description:
+      "上报修复结论并完结任务。result=fixed 时 BUG 置为 fixed；failed/cannot_reproduce 不改 BUG 状态（留人工裁决）。可附 commitUrl/prUrl/changedFiles。",
+    schema: reportResultSchema,
+    handler: reportResultHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.listEvents,
+    description: "列出 BUG 的原始事件样本（每次上报快照，按发生时间倒序，分页上限 50）。",
+    schema: listEventsSchema,
+    handler: listEventsHandler,
+  }),
+];
+
+/** test 执行域四工具（任务 24，规格 §8.2）：scope=test.exec token 专用（§8.1 分流） */
+export const TEST_MCP_TOOLS: McpToolDefinition[] = [
+  defineTool({
+    name: TOOL_NAMES.listPendingExecs,
+    description:
+      "列出待执行的测试用例（untested 且未被认领，仅运行中批次），返回 caseSnapshot 与目标环境，AI 执行工作流的取任务入口。",
+    schema: listPendingExecsSchema,
+    handler: listPendingExecsHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.claimExec,
+    description:
+      "认领一个待执行用例（原子认领先到先得，冲突返回 JSON-RPC -32001）。认领后按 caseSnapshot.steps 顺序执行并 report_step，终局 report_exec_result。",
+    schema: claimExecSchema,
+    handler: claimExecHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.reportStep,
+    description:
+      "逐步骤上报执行观察（追加 perStep 并同步 RunCase.stepResults，前端实时可见）。status: pass|fail|uncertain；order 须为快照内步骤序号。",
+    schema: reportStepSchema,
+    handler: reportStepHandler,
+  }),
+  defineTool({
+    name: TOOL_NAMES.reportExecResult,
+    description:
+      "上报终局并完结执行：finalVerdict pass→passed / fail→failed / uncertain→retest（恒置终态）；可附 consoleLog/networkLog 摘录与总结。批次内全部用例终态后自动完成批次。注意：首次 fail 上报后该用例会自动回池重试一次（判 flaky），请稍后经 list_pending_execs 重新拉取；两次均 fail 则进人工归因队列。",
+    schema: reportExecResultSchema,
+    handler: reportExecResultHandler,
+  }),
+];