feat(browser): 完成 Phase 10B replay 能力

新增最小 replay 闭环，支持消费 10A 结构化 steps 并顺序回放常见动作。
同时补充输入校验、失败定位与 replay 边界覆盖。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lib/mcp/ccs-browser-server.cjs

@@ -66,6 +66,9 @@ const TOOL_START_RECORDING = 'browser_start_recording';
 const TOOL_STOP_RECORDING = 'browser_stop_recording';
 const TOOL_GET_RECORDING = 'browser_get_recording';
 const TOOL_CLEAR_RECORDING = 'browser_clear_recording';
+const TOOL_START_REPLAY = 'browser_start_replay';
+const TOOL_GET_REPLAY = 'browser_get_replay';
+const TOOL_CANCEL_REPLAY = 'browser_cancel_replay';
 const TOOL_TAKE_SCREENSHOT = 'browser_take_screenshot';
 const TOOL_WAIT_FOR = 'browser_wait_for';
 const TOOL_EVAL = 'browser_eval';
@@ -101,6 +104,9 @@ const TOOL_NAMES = [
   TOOL_STOP_RECORDING,
   TOOL_GET_RECORDING,
   TOOL_CLEAR_RECORDING,
+  TOOL_START_REPLAY,
+  TOOL_GET_REPLAY,
+  TOOL_CANCEL_REPLAY,
   TOOL_TAKE_SCREENSHOT,
   TOOL_WAIT_FOR,
   TOOL_EVAL,
@@ -139,6 +145,9 @@ let nextDownloadCounter = 1;
 let nextRecordingCounter = 1;
 let activeRecordingSession = null;
 let latestRecordingSession = null;
+let nextReplayCounter = 1;
+let activeReplaySession = null;
+let latestReplaySession = null;
 const interceptRules = [];
 const recentRequests = [];
 const recentDownloads = [];
@@ -759,6 +768,38 @@ function getTools() {
         additionalProperties: false,
       },
     },
+    {
+      name: TOOL_START_REPLAY,
+      description: 'Start replaying a sequence of structured Browser MCP steps on the selected page.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          steps: { type: 'array', items: { type: 'object' } },
+          pageIndex: { type: 'integer', minimum: 0 },
+          pageId: { type: 'string' },
+        },
+        required: ['steps'],
+        additionalProperties: false,
+      },
+    },
+    {
+      name: TOOL_GET_REPLAY,
+      description: 'Read the current replay status and result summary from session-local state.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    },
+    {
+      name: TOOL_CANCEL_REPLAY,
+      description: 'Cancel the active replay session and keep the summary in session-local state.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      },
+    },
     {
       name: TOOL_TAKE_SCREENSHOT,
       description:
@@ -2286,6 +2327,12 @@ function createRecordingId() {
   return recordingId;
 }
 
+function createReplayId() {
+  const replayId = `rep_${String(nextReplayCounter).padStart(4, '0')}`;
+  nextReplayCounter += 1;
+  return replayId;
+}
+
 function requireLatestRecording() {
   if (!latestRecordingSession) {
     throw new Error('no recording available');
@@ -2304,6 +2351,27 @@ function formatRecordingSummary(session) {
   ].join('\n');
 }
 
+function requireLatestReplay() {
+  if (!latestReplaySession) {
+    throw new Error('no replay available');
+  }
+  return latestReplaySession;
+}
+
+function formatReplaySummary(session) {
+  return [
+    `replayId: ${session.replayId}`,
+    `pageId: ${session.pageId}`,
+    `pageIndex: ${session.pageIndex}`,
+    `stepCount: ${session.stepCount}`,
+    `completedSteps: ${session.completedSteps}`,
+    `currentStepIndex: ${session.currentStepIndex}`,
+    `failedStepIndex: ${session.failedStepIndex === null ? 'none' : session.failedStepIndex}`,
+    `error: ${session.error || 'none'}`,
+    `status: ${session.status}`,
+  ].join('\n');
+}
+
 function formatRecordingDetail(session) {
   const lines = [formatRecordingSummary(session), 'steps:'];
   if (session.steps.length === 0) {
@@ -2344,6 +2412,35 @@ function formatRecordingDetail(session) {
   return lines.join('\n');
 }
 
+const SUPPORTED_REPLAY_STEP_TYPES = new Set([
+  'click',
+  'type',
+  'press_key',
+  'scroll',
+  'drag_element',
+  'pointer_action',
+]);
+
+function requireReplaySteps(toolArgs) {
+  const steps = Array.isArray(toolArgs.steps) ? toolArgs.steps : null;
+  if (!steps || steps.length === 0) {
+    throw new Error('steps must be a non-empty array');
+  }
+  return steps;
+}
+
+function validateReplayStep(step, replayPageId) {
+  if (!step || typeof step !== 'object') {
+    throw new Error('invalid replay step payload');
+  }
+  if (!SUPPORTED_REPLAY_STEP_TYPES.has(step.type)) {
+    throw new Error('unsupported replay step type');
+  }
+  if (step.pageId && step.pageId !== replayPageId) {
+    throw new Error('replay step pageId mismatch');
+  }
+}
+
 function normalizeRecordedEvent(pageId, event) {
   if (!event || typeof event !== 'object') {
     return null;
@@ -4560,6 +4657,192 @@ async function handleClearRecording() {
   return 'status: cleared';
 }
 
+function buildReplayToolArgs(step, replayPage) {
+  const baseArgs = {
+    pageId: replayPage.pageId,
+  };
+
+  if (step.type === 'click') {
+    return {
+      toolName: TOOL_CLICK,
+      toolArgs: {
+        ...baseArgs,
+        selector: requireNonEmptyString(step.selector, 'selector'),
+        nth: step.nth,
+        frameSelector: step.frameSelector,
+        pierceShadow: step.pierceShadow,
+        button: step.args?.button,
+        clickCount: step.args?.clickCount,
+        offsetX: step.args?.offsetX,
+        offsetY: step.args?.offsetY,
+      },
+    };
+  }
+
+  if (step.type === 'type') {
+    return {
+      toolName: TOOL_TYPE,
+      toolArgs: {
+        ...baseArgs,
+        selector: requireNonEmptyString(step.selector, 'selector'),
+        nth: step.nth,
+        frameSelector: step.frameSelector,
+        pierceShadow: step.pierceShadow,
+        text: requireString(step.args?.text, 'text'),
+        clearFirst: true,
+      },
+    };
+  }
+
+  if (step.type === 'press_key') {
+    return {
+      toolName: TOOL_PRESS_KEY,
+      toolArgs: {
+        ...baseArgs,
+        key: requireNonEmptyString(step.args?.key, 'key'),
+        modifiers: Array.isArray(step.args?.modifiers) ? step.args.modifiers : [],
+      },
+    };
+  }
+
+  if (step.type === 'scroll') {
+    return {
+      toolName: TOOL_SCROLL,
+      toolArgs: {
+        ...baseArgs,
+        selector: step.selector,
+        frameSelector: step.frameSelector,
+        pierceShadow: step.pierceShadow,
+        behavior: 'by-offset',
+        deltaX: step.args?.deltaX ?? 0,
+        deltaY: step.args?.deltaY ?? 0,
+      },
+    };
+  }
+
+  if (step.type === 'drag_element') {
+    return {
+      toolName: TOOL_DRAG_ELEMENT,
+      toolArgs: {
+        ...baseArgs,
+        selector: requireNonEmptyString(step.selector, 'selector'),
+        nth: step.nth,
+        frameSelector: step.frameSelector,
+        pierceShadow: step.pierceShadow,
+        ...(step.args?.targetSelector !== undefined ? { targetSelector: step.args.targetSelector } : {}),
+        ...(step.args?.targetNth !== undefined ? { targetNth: step.args.targetNth } : {}),
+        ...(step.args?.targetX !== undefined ? { targetX: step.args.targetX } : {}),
+        ...(step.args?.targetY !== undefined ? { targetY: step.args.targetY } : {}),
+      },
+    };
+  }
+
+  if (step.type === 'pointer_action') {
+    return {
+      toolName: TOOL_POINTER_ACTION,
+      toolArgs: {
+        ...baseArgs,
+        actions: Array.isArray(step.args?.actions) ? step.args.actions : [],
+      },
+    };
+  }
+
+  return null;
+}
+
+async function executeReplaySteps(session) {
+  for (let index = 0; index < session.steps.length; index += 1) {
+    const step = session.steps[index];
+    session.currentStepIndex = index;
+    validateReplayStep(step, session.pageId);
+
+    const mapped = buildReplayToolArgs(step, session);
+    if (!mapped) {
+      throw new Error('unsupported replay step type');
+    }
+
+    if (mapped.toolName === TOOL_CLICK) {
+      await handleClick(mapped.toolArgs);
+    } else if (mapped.toolName === TOOL_TYPE) {
+      await handleType(mapped.toolArgs);
+    } else if (mapped.toolName === TOOL_PRESS_KEY) {
+      await handlePressKey(mapped.toolArgs);
+    } else if (mapped.toolName === TOOL_SCROLL) {
+      await handleScroll(mapped.toolArgs);
+    } else if (mapped.toolName === TOOL_DRAG_ELEMENT) {
+      await handleDragElement(mapped.toolArgs);
+    } else if (mapped.toolName === TOOL_POINTER_ACTION) {
+      await handlePointerAction(mapped.toolArgs);
+    } else {
+      throw new Error('unsupported replay step type');
+    }
+
+    session.completedSteps = index + 1;
+  }
+}
+
+async function handleStartReplay(toolArgs) {
+  if (activeReplaySession) {
+    throw new Error('replay already active');
+  }
+
+  const pages = await listPageTargets();
+  if (pages.length === 0) {
+    throw new Error('Browser MCP did not find any page targets in the current Chrome session.');
+  }
+
+  const { page, pageIndex } = resolveTargetPage(pages, toolArgs, selectedPageId);
+  if (!page.webSocketDebuggerUrl) {
+    throw new Error(`Browser MCP page ${pageIndex} does not expose a websocket debugger URL.`);
+  }
+
+  const steps = requireReplaySteps(toolArgs);
+  const session = {
+    replayId: createReplayId(),
+    pageId: page.id,
+    pageIndex,
+    status: 'running',
+    stepCount: steps.length,
+    completedSteps: 0,
+    currentStepIndex: 0,
+    failedStepIndex: null,
+    error: null,
+    steps,
+  };
+
+  latestReplaySession = session;
+  activeReplaySession = session;
+
+  try {
+    await executeReplaySteps(session);
+    session.status = 'completed';
+  } catch (error) {
+    session.status = 'failed';
+    session.failedStepIndex = session.currentStepIndex;
+    session.error = error instanceof Error ? error.message : String(error);
+  }
+
+  activeReplaySession = null;
+  latestReplaySession = session;
+  return formatReplaySummary(session);
+}
+
+async function handleGetReplay() {
+  const session = requireLatestReplay();
+  return formatReplaySummary(session);
+}
+
+async function handleCancelReplay() {
+  if (!activeReplaySession) {
+    throw new Error('no active replay');
+  }
+  activeReplaySession.status = 'canceled';
+  const canceled = activeReplaySession;
+  activeReplaySession = null;
+  latestReplaySession = canceled;
+  return formatReplaySummary(canceled);
+}
+
 async function handleToolCall(message) {
   const id = message.id;
   const params = message.params || {};
@@ -4780,6 +5063,30 @@ async function handleToolCall(message) {
       return;
     }
 
+    if (toolName === TOOL_START_REPLAY) {
+      const text = await handleStartReplay(toolArgs);
+      writeResponse(id, {
+        content: [{ type: 'text', text }],
+      });
+      return;
+    }
+
+    if (toolName === TOOL_GET_REPLAY) {
+      const text = await handleGetReplay(toolArgs);
+      writeResponse(id, {
+        content: [{ type: 'text', text }],
+      });
+      return;
+    }
+
+    if (toolName === TOOL_CANCEL_REPLAY) {
+      const text = await handleCancelReplay(toolArgs);
+      writeResponse(id, {
+        content: [{ type: 'text', text }],
+      });
+      return;
+    }
+
     if (toolName === TOOL_TAKE_SCREENSHOT) {
       const text = await handleScreenshot(toolArgs);
       writeResponse(id, {