@allbluecn/web-app 0.17.2 → 0.18.1

package/src/server/mcp/json-rpc.ts

@@ -0,0 +1,166 @@
+// 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/>.
+
+// 手写 JSON-RPC 2.0 通用层（任务 20，规格 §10.1）。零依赖、零 IO：
+// body 解析（batch 数组支持）+ 结构校验 + 错误码 + 响应构造。
+// 不引入 @modelcontextprotocol/sdk（其 peer zod ^3 与项目 zod 4 冲突），
+// 无状态子集自实现成本低于依赖治理成本。MCP 语义（initialize 协商、
+// 方法分发、HTTP 状态映射）在 ./protocol.ts。
+
+// ── JSON-RPC 2.0 错误码（规范保留段）──
+export const ERR_PARSE_ERROR = -32700;
+export const ERR_INVALID_REQUEST = -32600;
+export const ERR_METHOD_NOT_FOUND = -32601;
+export const ERR_INVALID_PARAMS = -32602;
+export const ERR_INTERNAL_ERROR = -32603;
+
+export const JSONRPC_VERSION = "2.0";
+
+export type JsonRpcId = string | number | null;
+
+/**
+ * 单条 JSON-RPC 消息。`id` 缺省即 notification（规范：无 id 成员 = 通知，
+ * 服务端不得回复）；`id: null` 是合法请求 id（虽然规范不建议）。
+ */
+export interface JsonRpcMessage {
+  id?: JsonRpcId;
+  method: string;
+  params?: Record<string, unknown> | unknown[];
+}
+
+export interface JsonRpcErrorObject {
+  code: number;
+  message: string;
+  data?: unknown;
+}
+
+export interface JsonRpcSuccessResponse {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  result: unknown;
+}
+
+export interface JsonRpcErrorResponse {
+  jsonrpc: "2.0";
+  id: JsonRpcId;
+  error: JsonRpcErrorObject;
+}
+
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+
+export function jsonRpcSuccess(id: JsonRpcId, result: unknown): JsonRpcSuccessResponse {
+  return { jsonrpc: JSONRPC_VERSION, id, result };
+}
+
+export function jsonRpcError(
+  id: JsonRpcId,
+  code: number,
+  message: string,
+  data?: unknown,
+): JsonRpcErrorResponse {
+  return {
+    jsonrpc: JSONRPC_VERSION,
+    id,
+    error: { code, message, ...(data !== undefined ? { data } : {}) },
+  };
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * 结构校验失败时错误响应可用的 id：能确定就用原 id（string/number/null），
+ * 不能确定一律 null（规范：invalid request 时 id 无法确定则为 null）。
+ */
+function extractId(raw: unknown): JsonRpcId {
+  if (!isPlainObject(raw) || !("id" in raw)) return null;
+  const id = raw.id;
+  if (typeof id === "string" || typeof id === "number" || id === null) return id;
+  return null;
+}
+
+/** 单条消息校验：非法 → { valid: false, id }；合法 → 归一化消息 */
+export type MessageEntry =
+  | { valid: true; message: JsonRpcMessage }
+  | { valid: false; id: JsonRpcId };
+
+const hasStructuredParams = (value: unknown): boolean =>
+  Array.isArray(value) || isPlainObject(value);
+
+export function validateJsonRpcMessage(raw: unknown): MessageEntry {
+  const id = extractId(raw);
+  if (!isPlainObject(raw)) return { valid: false, id };
+  if (raw.jsonrpc !== JSONRPC_VERSION) return { valid: false, id };
+  if (typeof raw.method !== "string") return { valid: false, id };
+  // params 存在时必须是结构化类型（by-name 对象 / by-position 数组）
+  if (raw.params !== undefined && raw.params !== null && !hasStructuredParams(raw.params)) {
+    return { valid: false, id };
+  }
+  const isNotification = raw.id === undefined;
+  return {
+    valid: true,
+    message: {
+      method: raw.method,
+      ...(isNotification ? {} : { id: id as JsonRpcId }),
+      ...(raw.params !== undefined ? { params: raw.params as Record<string, unknown> | unknown[] } : {}),
+    },
+  };
+}
+
+/** body 解析结果：顶层结构失败（-32700/-32600）或逐条目归一化 */
+export type JsonRpcPayloadParse =
+  | { ok: false; code: number; message: string }
+  | { ok: true; isBatch: false; entry: MessageEntry }
+  | { ok: true; isBatch: true; entries: MessageEntry[] };
+
+/**
+ * 解析原始 body 文本为 JSON-RPC 消息集（batch 数组支持，规范 2025-03-26 基础集）。
+ * - JSON 语法失败 → -32700
+ * - 顶层既非对象也非数组 / 空数组 batch → -32600
+ * - batch 元素逐条校验，非法元素保留位置以生成对应错误响应条目
+ */
+export function parseJsonRpcPayload(rawText: string): JsonRpcPayloadParse {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(rawText);
+  } catch {
+    return {
+      ok: false,
+      code: ERR_PARSE_ERROR,
+      message: "Parse error: request body is not valid JSON",
+    };
+  }
+  if (Array.isArray(raw)) {
+    if (raw.length === 0) {
+      return {
+        ok: false,
+        code: ERR_INVALID_REQUEST,
+        message: "Invalid Request: batch array must not be empty",
+      };
+    }
+    return { ok: true, isBatch: true, entries: raw.map(validateJsonRpcMessage) };
+  }
+  if (!isPlainObject(raw)) {
+    return {
+      ok: false,
+      code: ERR_INVALID_REQUEST,
+      message: "Invalid Request: body must be a JSON-RPC object or batch array",
+    };
+  }
+  return { ok: true, isBatch: false, entry: validateJsonRpcMessage(raw) };
+}

package/src/server/mcp/protocol.ts

@@ -0,0 +1,317 @@
+// 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 Streamable HTTP 无状态模式协议层（任务 20，规格 §10.1；任务 24 扩 scope 分流）：
+// Bearer 鉴权（scope=bug.mcp | test.exec，§8.1 一个 token 只见自己 scope 的 tools）
+// → 限流（120 次/分）→ handleMcpRequest 纯函数（initialize 版本协商 / notifications
+// 202 / ping / tools:list+call 分发表）。不发放 Mcp-Session-Id（无状态）；GET SSE
+// 流由路由层 405 拒绝。路由层薄壳（routes/api/mcp/bugs.ts）只做 handler 委托。
+import { prisma } from "@allbluecn/database";
+import {
+  ERR_INTERNAL_ERROR,
+  ERR_INVALID_PARAMS,
+  ERR_INVALID_REQUEST,
+  ERR_METHOD_NOT_FOUND,
+  isPlainObject,
+  jsonRpcError,
+  jsonRpcSuccess,
+  parseJsonRpcPayload,
+  type JsonRpcId,
+  type JsonRpcMessage,
+  type JsonRpcResponse,
+  type MessageEntry,
+} from "./json-rpc";
+import { hashToken, isValidTokenFormat } from "@/server/bug-report/tokens";
+import { checkRateLimit } from "@/server/lib/rate-limit";
+import { McpProtocolError } from "./tool-errors";
+import { BUG_MCP_TOOLS, TEST_MCP_TOOLS } from "./tools";
+
+// ── 协议常量（§10.1 权威：支持集协商，默认回 2025-03-26）──
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+  "2024-11-05",
+  "2025-03-26",
+  "2025-06-18",
+] as const;
+export const DEFAULT_PROTOCOL_VERSION = "2025-03-26";
+export const MCP_SERVER_INFO = { name: "allblue-bugs", version: "1.0.0" } as const;
+export const MCP_RATE_LIMIT = { max: 120, windowMs: 60_000 } as const;
+
+// 服务端自定义错误码（JSON-RPC 规范保留段 -32000..-32099）
+export const CODE_UNAUTHORIZED = -32000;
+export const CODE_RATE_LIMITED = -32001;
+// 任务 24 test 域工具级协议错误（定义于 tool-errors.ts，re-export 供消费方单点导入）
+export { CODE_EXEC_CLAIM_CONFLICT, CODE_EXEC_REPORT_REJECTED } from "./tool-errors";
+
+/** token scope → 可见工具表（§8.1：一个 token 只见自己 scope 的 tools） */
+export const TOOLS_BY_SCOPE: Record<string, readonly McpToolDefinition[]> = {
+  "bug.mcp": BUG_MCP_TOOLS,
+  "test.exec": TEST_MCP_TOOLS,
+};
+
+// ── 请求上下文：鉴权结果 + 工具分发表由调用方注入（bug 域六工具 | test 域四工具按 scope）──
+export interface McpAuthContext {
+  /** token 绑定项目：工具内一切操作的数据边界（越权访问他项目 BUG 返回工具级错误） */
+  projectId: string;
+  tokenId: string;
+}
+
+/** 工具返回 MCP content（§10.2）；一般错误以 isError: true 表达，test 域两类契约错误（-32001/-32002）例外走 JSON-RPC error */
+export interface McpToolCallResult {
+  content: { type: "text"; text: string }[];
+  isError?: boolean;
+}
+
+export interface McpToolDefinition {
+  name: string;
+  description: string;
+  /** 任务 21 用 zod 4 z.toJSONSchema() 生成 */
+  inputSchema: Record<string, unknown>;
+  handler: (
+    args: Record<string, unknown>,
+    ctx: McpRequestContext,
+  ) => Promise<McpToolCallResult>;
+}
+
+export interface McpRequestContext {
+  auth: McpAuthContext;
+  tools: readonly McpToolDefinition[];
+}
+
+/** 工具分发表（任务 21 bug 域六工具；任务 24 test 域四工具见 TEST_MCP_TOOLS，按 §8.1 scope 分流） */
+export { BUG_MCP_TOOLS } from "./tools";
+
+/** 版本协商：请求版本 ∈ 支持集回显，否则回默认 2025-03-26 */
+export function negotiateProtocolVersion(requested: unknown): string {
+  const supported = SUPPORTED_PROTOCOL_VERSIONS as readonly string[];
+  return typeof requested === "string" && supported.includes(requested)
+    ? requested
+    : DEFAULT_PROTOCOL_VERSION;
+}
+
+// ── HTTP 响应助手 ──
+const jsonRpcHttpResponse = (status: number, body: unknown) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+
+const unauthorizedResponse = (message: string) =>
+  new Response(JSON.stringify(jsonRpcError(null, CODE_UNAUTHORIZED, message)), {
+    status: 401,
+    headers: {
+      "Content-Type": "application/json",
+      "WWW-Authenticate": 'Bearer realm="allblue-mcp", scope="bug.mcp test.exec"',
+    },
+  });
+
+/**
+ * GET 处理（§10.1 权威约束项）：无状态模式不提供 GET SSE 流，
+ * 按 MCP 规范 2025-03-26 以 405 拒绝并声明可用方法。
+ * 独立导出以便路由层委托与单测直接断言（路由薄壳零逻辑）。
+ */
+export function handleMcpGetRequest(): Response {
+  return new Response(null, {
+    status: 405,
+    headers: { Allow: "POST, OPTIONS" },
+  });
+}
+
+// ── 方法分发（协议核心，纯函数——副作用只可能来自任务 21 的工具 handler）──
+async function dispatchRequest(
+  message: JsonRpcMessage,
+  ctx: McpRequestContext,
+): Promise<JsonRpcResponse> {
+  const id = message.id as JsonRpcId;
+  try {
+    switch (message.method) {
+      case "initialize":
+        return handleInitialize(id, message.params);
+      case "ping":
+        return jsonRpcSuccess(id, {});
+      case "tools/list":
+        return jsonRpcSuccess(id, {
+          tools: ctx.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+          })),
+        });
+      case "tools/call":
+        return await handleToolCall(id, message.params, ctx);
+      default:
+        return jsonRpcError(id, ERR_METHOD_NOT_FOUND, `Method not found: ${message.method}`);
+    }
+  } catch (error) {
+    console.error("[bug-mcp] request dispatch failed:", error);
+    return jsonRpcError(id, ERR_INTERNAL_ERROR, "Internal error");
+  }
+}
+
+function handleInitialize(
+  id: JsonRpcId,
+  params: JsonRpcMessage["params"],
+): JsonRpcResponse {
+  if (!isPlainObject(params) || typeof params.protocolVersion !== "string") {
+    return jsonRpcError(
+      id,
+      ERR_INVALID_PARAMS,
+      "initialize requires params.protocolVersion (string)",
+    );
+  }
+  // 宽容解析：capabilities/clientInfo 规范要求必填，但服务端不消费，缺失不拒
+  return jsonRpcSuccess(id, {
+    protocolVersion: negotiateProtocolVersion(params.protocolVersion),
+    capabilities: { tools: { listChanged: false } },
+    serverInfo: { ...MCP_SERVER_INFO },
+  });
+}
+
+async function handleToolCall(
+  id: JsonRpcId,
+  params: JsonRpcMessage["params"],
+  ctx: McpRequestContext,
+): Promise<JsonRpcResponse> {
+  if (!isPlainObject(params) || typeof params.name !== "string") {
+    return jsonRpcError(id, ERR_INVALID_PARAMS, "tools/call requires params.name (string)");
+  }
+  const tool = ctx.tools.find((candidate) => candidate.name === params.name);
+  if (!tool) {
+    return jsonRpcError(id, ERR_INVALID_PARAMS, `Unknown tool: ${params.name}`);
+  }
+  const args = isPlainObject(params.arguments) ? params.arguments : {};
+  try {
+    const result = await tool.handler(args, ctx);
+    return jsonRpcSuccess(id, {
+      content: result.content,
+      ...(result.isError ? { isError: true } : {}),
+    });
+  } catch (error) {
+    // 工具级协议错误（任务 24：claim 冲突 -32001 / 非活跃 report -32002）：
+    // 以 JSON-RPC error 响应表达（规格 §8.2 钉死），非 isError 工具结果
+    if (error instanceof McpProtocolError) {
+      return jsonRpcError(id, error.code, error.message, error.data);
+    }
+    throw error; // 交由 dispatchRequest 兜底为 ERR_INTERNAL_ERROR
+  }
+}
+
+/**
+ * JSON-RPC 协议核心（纯函数，ctx 注入鉴权结果与工具表）：
+ * - 单请求 → 200 单响应；单 notification / 纯 notification batch → 202 空响应
+ * - batch 含请求 → 200 响应数组（notification 无条目，元素错误逐位保留）
+ * - 结构性失败（-32700/-32600）→ 400 单错误对象
+ */
+export async function handleMcpRequest(
+  rawBody: string,
+  ctx: McpRequestContext,
+): Promise<Response> {
+  const payload = parseJsonRpcPayload(rawBody);
+  if (!payload.ok) {
+    return jsonRpcHttpResponse(
+      400,
+      jsonRpcError(null, payload.code, payload.message),
+    );
+  }
+
+  const respondToEntry = async (entry: MessageEntry): Promise<Response> => {
+    if (!entry.valid) {
+      return jsonRpcHttpResponse(
+        400,
+        jsonRpcError(entry.id, ERR_INVALID_REQUEST, "Invalid Request"),
+      );
+    }
+    if (entry.message.id === undefined) {
+      // notification（含 notifications/initialized 等全部 notifications/*）：
+      // 规范要求服务端不得回复，Streamable HTTP 语义为 202 Accepted 空响应
+      return new Response(null, { status: 202 });
+    }
+    return jsonRpcHttpResponse(200, await dispatchRequest(entry.message, ctx));
+  };
+
+  if (!payload.isBatch) {
+    return respondToEntry(payload.entry);
+  }
+
+  const responses: JsonRpcResponse[] = [];
+  for (const entry of payload.entries) {
+    if (!entry.valid) {
+      responses.push(jsonRpcError(entry.id, ERR_INVALID_REQUEST, "Invalid Request"));
+      continue;
+    }
+    if (entry.message.id === undefined) continue; // notification 不产生响应条目
+    responses.push(await dispatchRequest(entry.message, ctx));
+  }
+  if (responses.length === 0) {
+    return new Response(null, { status: 202 }); // 纯 notification batch
+  }
+  return jsonRpcHttpResponse(200, responses);
+}
+
+/**
+ * POST 入口完整处理链：Bearer 鉴权（ProjectAccessToken，scope=bug.mcp|test.exec、
+ * 未吊销）→ 限流（按 tokenHash 120 次/60 秒）→ 协议层。鉴权/限流失败是 401/429
+ * JSON-RPC error 响应而非异常（MCP 客户端按协议消费错误体）。
+ * scope 分流（§8.1）：TOOLS_BY_SCOPE 决定该 token 可见的 tools 子集，
+ * 未登记 scope（如 bug.report/bug.collect）不授予 MCP 访问。
+ */
+export async function handleMcpPost(request: Request): Promise<Response> {
+  // ── 鉴权：Authorization: Bearer <token>（X-Bug-Key 的 Bearer 版口径）──
+  const authHeader = request.headers.get("authorization") ?? "";
+  const bearer = /^Bearer\s+(.+)$/i.exec(authHeader)?.[1]?.trim() ?? "";
+  if (!bearer || !isValidTokenFormat(bearer)) {
+    return unauthorizedResponse("Unauthorized: missing or malformed bearer token");
+  }
+  const token = await prisma.projectAccessToken.findUnique({
+    where: { tokenHash: hashToken(bearer) },
+  });
+  if (!token) return unauthorizedResponse("Unauthorized: invalid token");
+  if (token.revokedAt) return unauthorizedResponse("Unauthorized: token revoked");
+  const scopeTools = TOOLS_BY_SCOPE[token.scope];
+  if (!scopeTools) {
+    return unauthorizedResponse("Unauthorized: token scope does not grant MCP access");
+  }
+
+  // ── 限流：按 tokenHash 120 次/分钟（内存滑动窗口，照 report-handler 口径）──
+  const limit = checkRateLimit(`bug-mcp:${token.tokenHash}`, { ...MCP_RATE_LIMIT });
+  if (!limit.allowed) {
+    return new Response(
+      JSON.stringify(
+        jsonRpcError(null, CODE_RATE_LIMITED, "Rate limit exceeded", {
+          retryAfterMs: limit.retryAfterMs,
+        }),
+      ),
+      {
+        status: 429,
+        headers: {
+          "Content-Type": "application/json",
+          "Retry-After": String(Math.ceil(limit.retryAfterMs / 1000)),
+        },
+      },
+    );
+  }
+
+  // ── lastUsedAt：fire-and-forget，不阻塞响应（照 report-handler 口径）──
+  void prisma.projectAccessToken
+    .update({ where: { id: token.id }, data: { lastUsedAt: new Date() } })
+    .catch(() => {});
+
+  const rawBody = await request.text();
+  return handleMcpRequest(rawBody, {
+    auth: { projectId: token.projectId, tokenId: token.id },
+    tools: scopeTools,
+  });
+}

package/src/server/mcp/tool-errors.ts

@@ -0,0 +1,44 @@
+// 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 工具级协议错误（任务 24，规格 §8.2）：部分工具契约以 JSON-RPC error 响应
+// 表达（非 isError 工具结果）——claim_exec 认领冲突 -32001、对非 claimed ExecRun
+// report 被拒 -32002。独立小模块的原因：tools.ts 与 protocol.ts 互相 import
+//（protocol 引工具表、tools 引协议类型），错误类若放任一侧即成运行时循环依赖；
+// 本模块零依赖，两侧各取所需。
+// 码值口径：-32001 与 protocol.ts 的 CODE_RATE_LIMITED 数值相同但分层不同
+//（限流是 HTTP 层 429 响应，认领冲突是 tools/call 响应体 error），JSON-RPC
+// 规范仅保留 -32000..-32099 段，服务器自定义码允许跨场景复用段内数值。
+
+/** claim_exec 认领冲突（已被并发认领，规格 §8.2 / 审查重点 2） */
+export const CODE_EXEC_CLAIM_CONFLICT = -32001;
+
+/** report_step / report_exec_result 对非 claimed（已完结/被回收/从未认领）ExecRun 上报被拒 */
+export const CODE_EXEC_REPORT_REJECTED = -32002;
+
+/** 工具 handler 抛出、protocol.handleToolCall 捕获并转 JSON-RPC error 响应 */
+export class McpProtocolError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "McpProtocolError";
+    this.code = code;
+    this.data = data;
+  }
+}

package/src/server/mcp/tool-schemas.ts

@@ -0,0 +1,124 @@
+// 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 六工具入参 zod schema（任务 21，规格 §10.2）——单一事实源：
+// tools.ts 用 z.toJSONSchema() 生成 tools/list 的 inputSchema（zod 4 原生，
+// 无需 @modelcontextprotocol/sdk），handler 用同一 schema safeParse 校验入参。
+// 纯 zod 定义，零 IO，client/server 两侧均安全（仅供 server/mcp 消费）。
+import { z } from "zod";
+
+/** BUG 状态联合（DB 为 String 列，与 shared/bug/constants.ts 的 BugState 对齐） */
+const bugState = z.enum(["open", "in_progress", "fixed", "closed", "wontfix"]);
+const bugSeverity = z.enum(["critical", "high", "medium", "low"]);
+const bugId = z.string().min(1).max(64).describe("BUG ID（list_bugs / get_bug 返回的 id）");
+/** 分页上限统一 50（规格 §10.2 limit?(≤50)），默认值在 handler 侧给（schema 不用 default，避免 toJSONSchema 产 required） */
+const limit = z.number().int().min(1).max(50).describe("返回条数上限（最大 50）");
+
+export const listBugsSchema = z.object({
+  status: bugState.optional().describe("按 BUG 状态过滤；缺省时优先返回有待修复任务的"),
+  severity: bugSeverity.optional().describe("按严重度过滤"),
+  limit: limit.optional().describe("默认 20"),
+});
+
+export const getBugSchema = z.object({ bugId });
+
+export const claimFixSchema = z.object({
+  bugId,
+  agentName: z.string().min(1).max(100).describe("认领 agent 标识（如 opencode / claude-code），冲突提示与活动流使用"),
+});
+
+export const reportProgressSchema = z.object({
+  bugId,
+  message: z.string().min(1).max(4000).describe("本次进度说明（落活动流）"),
+  phase: z.enum(["analyzing", "fixing", "verifying"]).optional().describe("当前修复阶段"),
+});
+
+export const reportResultSchema = z.object({
+  bugId,
+  result: z.enum(["fixed", "failed", "cannot_reproduce"]).describe("修复结论：fixed 才会置 BUG 为 fixed；failed/cannot_reproduce 不改 BUG 状态"),
+  summary: z.string().min(1).max(8000).describe("修复总结（落 run.summary 与活动流）"),
+  commitUrl: z.string().url().max(2000).optional().describe("修复 commit 链接"),
+  prUrl: z.string().url().max(2000).optional().describe("修复 PR 链接"),
+  changedFiles: z.array(z.string().min(1).max(500)).max(200).optional().describe("变更文件清单"),
+});
+
+export const listEventsSchema = z.object({
+  bugId,
+  limit: limit.optional().describe("默认 20"),
+});
+
+// ── test 执行域四工具（任务 24，规格 §8.2 钉死；scope=test.exec token 专用）──
+
+const runCaseId = z
+  .string()
+  .min(1)
+  .max(64)
+  .describe("执行用例 ID（list_pending_execs 返回的 runCaseId）");
+
+export const listPendingExecsSchema = z.object({
+  runId: z
+    .string()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe("限定批次；缺省时返回项目内全部运行中批次的待执行用例"),
+  limit: limit.optional().describe("默认 20"),
+});
+
+export const claimExecSchema = z.object({
+  runCaseId,
+  agentName: z
+    .string()
+    .min(1)
+    .max(100)
+    .describe("认领 agent 标识（如 opencode / claude-code），断线重连按同名回池重抢"),
+});
+
+/** AI 步骤判定三值（规格 §8.2：pass|fail|uncertain；uncertain 终局映射 retest） */
+const stepVerdict = z.enum(["pass", "fail", "uncertain"]);
+
+export const reportStepSchema = z.object({
+  runCaseId,
+  order: z.number().int().min(1).describe("步骤序号（caseSnapshot.steps 内的 order）"),
+  status: stepVerdict.describe("本步判定：pass|fail|uncertain"),
+  observed: z.string().min(1).max(5000).describe("实际观察到的现象"),
+  screenshotBlobId: z
+    .string()
+    .min(1)
+    .max(100)
+    .regex(/^[A-Za-z0-9_-]+$/, "screenshotBlobId 需为 Blob cuid 形态")
+    .optional()
+    .describe("本步截图（先经既有 Blob 上传链路取得 id）"),
+});
+
+export const reportExecResultSchema = z.object({
+  runCaseId,
+  finalVerdict: stepVerdict.describe(
+    "终局判定：pass→passed；fail→failed；uncertain→retest（恒置终态）",
+  ),
+  consoleLog: z
+    .array(z.string().min(1).max(4000))
+    .max(200)
+    .optional()
+    .describe("控制台日志摘录（逐条，落 ExecRun.report.consoleLog）"),
+  networkLog: z
+    .array(z.string().min(1).max(4000))
+    .max(200)
+    .optional()
+    .describe("网络日志摘录（逐条，落 ExecRun.report.networkLog）"),
+  summaryText: z.string().min(1).max(8000).describe("执行总结（落 RunCase.actualResult）"),
+});