@aipper/zentao-mcp-server 0.1.4 → 0.1.6

package/.env.example

@@ -5,8 +5,8 @@ ZENTAO_BASE_URL=http://zentao.example.com
 ZENTAO_ACCOUNT=your_account
 ZENTAO_PASSWORD=your_password
 
-# API 前缀（多数禅道为 /api.php/v1）
-ZENTAO_API_PREFIX=/api.php/v1
+# 可选：API 前缀（默认 /api.php/v1）
+# ZENTAO_API_PREFIX=/api.php/v1
 
 # 获取 Token 的路径（相对 ZENTAO_BASE_URL；通常为 /api.php/v1/tokens）
 ZENTAO_TOKEN_PATH=/api.php/v1/tokens

package/README.md

@@ -18,6 +18,8 @@
 - `ZENTAO_PASSWORD`
 
 > 注意：不同禅道版本/部署方式的 token 端点与返回结构可能不同；可通过 `ZENTAO_TOKEN_PATH`/`ZENTAO_API_PREFIX` 调整。
+>
+> 默认情况下不需要配置 `ZENTAO_API_PREFIX`（默认值是 `/api.php/v1`）。
 
 ## 安装与运行
 ```bash
@@ -26,6 +28,12 @@ cp .env.example .env
 npm start
 ```
 
+## npm 安装后的运行
+发布到 npm 后，推荐用 `npx` 启动（适合 MCP 客户端配置）：
+```bash
+npx -y @aipper/zentao-mcp-server
+```
+
 ## 验证（不依赖 MCP 客户端）
 ```bash
 npm i
@@ -38,7 +46,24 @@ npm run smoke
 - 输出 `GET /projects status: 200`（或你的禅道实际返回码）
 
 ## Claude Desktop / Cursor 示例（stdio）
-把启动命令指向 `node src/index.js`（或 `npm start`）。
+优先使用 `npx`（npm 发布版）：
+```json
+{
+  "mcpServers": {
+    "zentao": {
+      "command": "npx",
+      "args": ["-y", "@aipper/zentao-mcp-server"],
+      "env": {
+        "ZENTAO_BASE_URL": "https://zentao.example.com",
+        "ZENTAO_ACCOUNT": "your_account",
+        "ZENTAO_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+本地源码调试可继续用 `node src/index.js`：
 
 示例（Claude Desktop 的 `mcpServers` 风格，按你的客户端实际字段为准）：
 ```json
@@ -50,7 +75,6 @@ npm run smoke
       "cwd": "/ABS/PATH/TO/zentao",
       "env": {
         "ZENTAO_BASE_URL": "https://zentao.example.com",
-        "ZENTAO_API_PREFIX": "/api.php/v1",
         "ZENTAO_ACCOUNT": "your_account",
         "ZENTAO_PASSWORD": "your_password"
       }
@@ -59,10 +83,29 @@ npm run smoke
 }
 ```
 
+## 常见错误（`-32000`）
+`-32000` 通常是客户端侧“通用 MCP 调用失败”映射码，优先检查：
+- `env` 是否完整传入（尤其是 `ZENTAO_BASE_URL`/`ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD`）。
+- `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致。
+- MCP 客户端是否真的在执行 `npx -y @aipper/zentao-mcp-server`（而不是旧的本地命令）。
+- 客户端日志中是否有启动报错（如找不到命令、401、超时）。
+
 ## 已实现工具
 - `get_token`：获取/刷新 token（默认不回显完整 token）
 - `call`：调用任意相对 API 路径（自动带 Token 头）
 - `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调）
+- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`，默认路径 `/bugs`）
+- `get_bug_detail`：按 `id` 获取 bug 详情（默认路径模板 `/bugs/{id}`，返回详情与图片链接）
+- `resolve_bug`：按 `id` 处理单个 bug 状态（默认 `resolution=fixed`）
+- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`）
+- `close_bug`：按 `id` 关闭 bug
+- `verify_bug`：验证结果处理（`pass`=关闭，`fail`=激活）
+
+示例参数：
+- `resolve_bug`：`{"id":123,"resolution":"fixed","comment":"已修复并自测"}`
+- `batch_resolve_my_bugs`：`{"status":"active","maxItems":20,"comment":"批量修复"}`
+- `close_bug`：`{"id":123,"comment":"验证通过，关闭"}`
+- `verify_bug`：`{"id":123,"result":"pass","comment":"验证通过"}`
 
 ## 安全建议
 - 使用最小权限账号（仅需要的项目权限），避免使用管理员账号。

package/bin/zentao-mcp-server.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "../src/index.js";
+

package/package.json

@@ -1,14 +1,17 @@
 {
   "name": "@aipper/zentao-mcp-server",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "private": false,
   "type": "module",
   "description": "A minimal MCP server for ZenTao (token + generic REST call + a few helper tools).",
   "license": "UNLICENSED",
   "main": "src/index.js",
+  "bin": {
+    "zentao-mcp-server": "bin/zentao-mcp-server.js"
+  },
   "scripts": {
     "start": "node src/index.js",
-    "lint": "node -c src/index.js && node -c src/zentao.js && node -c src/tools.js && node -c scripts/smoke.mjs",
+    "lint": "node -c src/index.js && node -c src/zentao.js && node -c src/tools.js && node -c scripts/smoke.mjs && node -c bin/zentao-mcp-server.js",
     "smoke": "node scripts/smoke.mjs",
     "release:npm": "bash scripts/release-npm.sh"
   },

package/src/index.js

@@ -8,6 +8,33 @@ import {
 import { createZenTaoClient } from "./zentao.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 
+const KNOWN_TOOL_NAMES = new Set([
+  "get_token",
+  "call",
+  "list_my_projects",
+  "get_my_bugs",
+  "get_bug_detail",
+  "resolve_bug",
+  "batch_resolve_my_bugs",
+  "close_bug",
+  "verify_bug",
+]);
+
+function normalizeToolName(rawName) {
+  if (!rawName || typeof rawName !== "string") return rawName;
+  if (KNOWN_TOOL_NAMES.has(rawName)) return rawName;
+
+  if (rawName.includes("_")) {
+    const withoutPrefix = rawName.replace(/^[^_]+_/, "");
+    if (KNOWN_TOOL_NAMES.has(withoutPrefix)) return withoutPrefix;
+  }
+
+  for (const name of KNOWN_TOOL_NAMES) {
+    if (rawName.endsWith(name)) return name;
+  }
+  return rawName;
+}
+
 function requireEnv(name) {
   const value = process.env[name];
   if (!value) throw new Error(`Missing required env: ${name}`);
@@ -50,7 +77,8 @@ async function main() {
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
-    const toolName = req.params?.name;
+    const rawToolName = req.params?.name;
+    const toolName = normalizeToolName(rawToolName);
     const args = req.params?.arguments || {};
     assertToolArgs(toolName, args);
 
@@ -77,7 +105,74 @@ async function main() {
       return toMcpTextResult(JSON.stringify(resp, null, 2));
     }
 
-    throw new Error(`Unknown tool: ${toolName}`);
+    if (toolName === "get_my_bugs") {
+      const resp = await zentao.getMyBugs({
+        status: args.status || "",
+        keyword: args.keyword || "",
+        limit: args.limit,
+        page: args.page,
+        path: args.path || "/bugs",
+        assignedTo: args.assignedTo || "",
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    if (toolName === "get_bug_detail") {
+      const resp = await zentao.getBugDetail({
+        id: args.id,
+        path: args.path || "/bugs/{id}",
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    if (toolName === "resolve_bug") {
+      const resp = await zentao.resolveBug({
+        id: args.id,
+        resolution: args.resolution || "fixed",
+        comment: args.comment || "",
+        path: args.path || "/bugs/{id}/resolve",
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    if (toolName === "batch_resolve_my_bugs") {
+      const resp = await zentao.batchResolveMyBugs({
+        status: args.status || "active",
+        keyword: args.keyword || "",
+        limit: args.limit,
+        page: args.page,
+        maxItems: args.maxItems,
+        assignedTo: args.assignedTo || "",
+        resolution: args.resolution || "fixed",
+        comment: args.comment || "",
+        listPath: args.listPath || "/bugs",
+        resolvePath: args.resolvePath || "/bugs/{id}/resolve",
+        stopOnError: Boolean(args.stopOnError),
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    if (toolName === "close_bug") {
+      const resp = await zentao.closeBug({
+        id: args.id,
+        comment: args.comment || "",
+        path: args.path || "/bugs/{id}/close",
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    if (toolName === "verify_bug") {
+      const resp = await zentao.verifyBug({
+        id: args.id,
+        result: args.result || "pass",
+        comment: args.comment || "",
+        closePath: args.closePath || "/bugs/{id}/close",
+        activatePath: args.activatePath || "/bugs/{id}/activate",
+      });
+      return toMcpTextResult(JSON.stringify(resp, null, 2));
+    }
+
+    throw new Error(`Unknown tool: ${rawToolName}`);
   });
 
   const transport = new StdioServerTransport();

package/src/tools.js

@@ -1,5 +1,8 @@
 export function toMcpTextResult(text) {
-  return { content: [{ type: "text", text }] };
+  return {
+    content: [{ type: "text", text }],
+    structuredContent: { output: text },
+  };
 }
 
 export const TOOLS = [
@@ -36,6 +39,101 @@ export const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "get_my_bugs",
+    description: "List bugs assigned to me (supports status/keyword/limit/page filter).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", description: "Optional status filter, e.g. active/resolved/closed" },
+        keyword: { type: "string", description: "Optional keyword in title/steps/severity/pri" },
+        limit: { type: "number", minimum: 1, maximum: 200, description: "Default 20, max 200" },
+        page: { type: "number", minimum: 1, description: "Default 1" },
+        path: { type: "string", description: "Optional bugs endpoint override, default /bugs" },
+        assignedTo: { type: "string", description: "Optional assignee override, default current account" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_bug_detail",
+    description: "Get bug detail by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", minimum: 1, description: "Bug ID" },
+        path: { type: "string", description: "Optional detail endpoint template, default /bugs/{id}" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "resolve_bug",
+    description: "Resolve one bug by ID (default resolution=fixed).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", minimum: 1, description: "Bug ID" },
+        resolution: { type: "string", description: "Default fixed" },
+        comment: { type: "string", description: "Optional resolve comment" },
+        path: { type: "string", description: "Optional resolve endpoint template, default /bugs/{id}/resolve" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "batch_resolve_my_bugs",
+    description: "Batch resolve my bugs (default status=active, resolution=fixed).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", description: "Default active" },
+        keyword: { type: "string", description: "Optional keyword filter before resolve" },
+        limit: { type: "number", minimum: 1, maximum: 200, description: "List page size, default 50" },
+        page: { type: "number", minimum: 1, description: "Default 1" },
+        maxItems: { type: "number", minimum: 1, maximum: 500, description: "Max resolve count, default 50" },
+        assignedTo: { type: "string", description: "Optional assignee override" },
+        resolution: { type: "string", description: "Default fixed" },
+        comment: { type: "string", description: "Optional resolve comment" },
+        listPath: { type: "string", description: "Optional list endpoint, default /bugs" },
+        resolvePath: { type: "string", description: "Optional resolve path template, default /bugs/{id}/resolve" },
+        stopOnError: { type: "boolean", description: "Default false; stop on first resolve failure" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "close_bug",
+    description: "Close one bug by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", minimum: 1, description: "Bug ID" },
+        comment: { type: "string", description: "Optional close comment" },
+        path: { type: "string", description: "Optional close endpoint template, default /bugs/{id}/close" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "verify_bug",
+    description: "Verify bug result: pass -> close, fail -> activate.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", minimum: 1, description: "Bug ID" },
+        result: { type: "string", description: "pass or fail, default pass" },
+        comment: { type: "string", description: "Optional verification comment" },
+        closePath: { type: "string", description: "Optional close endpoint template, default /bugs/{id}/close" },
+        activatePath: { type: "string", description: "Optional activate endpoint template, default /bugs/{id}/activate" },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
 ];
 
 export function assertToolArgs(name, args) {
@@ -44,4 +142,73 @@ export function assertToolArgs(name, args) {
   if (name === "call" && typeof args.path !== "string") {
     throw new Error("call.path must be a string");
   }
+  if (name === "get_my_bugs") {
+    if (args.limit !== undefined && (!Number.isFinite(args.limit) || args.limit < 1 || args.limit > 200)) {
+      throw new Error("get_my_bugs.limit must be a number between 1 and 200");
+    }
+    if (args.page !== undefined && (!Number.isFinite(args.page) || args.page < 1)) {
+      throw new Error("get_my_bugs.page must be a number >= 1");
+    }
+    if (args.path !== undefined && typeof args.path !== "string") {
+      throw new Error("get_my_bugs.path must be a string");
+    }
+  }
+  if (name === "get_bug_detail") {
+    if (!Number.isFinite(args.id) || Number(args.id) < 1) {
+      throw new Error("get_bug_detail.id must be a number >= 1");
+    }
+    if (args.path !== undefined && typeof args.path !== "string") {
+      throw new Error("get_bug_detail.path must be a string");
+    }
+  }
+  if (name === "resolve_bug") {
+    if (!Number.isFinite(args.id) || Number(args.id) < 1) {
+      throw new Error("resolve_bug.id must be a number >= 1");
+    }
+    if (args.path !== undefined && typeof args.path !== "string") {
+      throw new Error("resolve_bug.path must be a string");
+    }
+  }
+  if (name === "batch_resolve_my_bugs") {
+    if (args.limit !== undefined && (!Number.isFinite(args.limit) || args.limit < 1 || args.limit > 200)) {
+      throw new Error("batch_resolve_my_bugs.limit must be a number between 1 and 200");
+    }
+    if (args.page !== undefined && (!Number.isFinite(args.page) || args.page < 1)) {
+      throw new Error("batch_resolve_my_bugs.page must be a number >= 1");
+    }
+    if (args.maxItems !== undefined && (!Number.isFinite(args.maxItems) || args.maxItems < 1 || args.maxItems > 500)) {
+      throw new Error("batch_resolve_my_bugs.maxItems must be a number between 1 and 500");
+    }
+    if (args.listPath !== undefined && typeof args.listPath !== "string") {
+      throw new Error("batch_resolve_my_bugs.listPath must be a string");
+    }
+    if (args.resolvePath !== undefined && typeof args.resolvePath !== "string") {
+      throw new Error("batch_resolve_my_bugs.resolvePath must be a string");
+    }
+  }
+  if (name === "close_bug") {
+    if (!Number.isFinite(args.id) || Number(args.id) < 1) {
+      throw new Error("close_bug.id must be a number >= 1");
+    }
+    if (args.path !== undefined && typeof args.path !== "string") {
+      throw new Error("close_bug.path must be a string");
+    }
+  }
+  if (name === "verify_bug") {
+    if (!Number.isFinite(args.id) || Number(args.id) < 1) {
+      throw new Error("verify_bug.id must be a number >= 1");
+    }
+    if (args.result !== undefined) {
+      const result = String(args.result).toLowerCase();
+      if (result !== "pass" && result !== "fail") {
+        throw new Error("verify_bug.result must be pass or fail");
+      }
+    }
+    if (args.closePath !== undefined && typeof args.closePath !== "string") {
+      throw new Error("verify_bug.closePath must be a string");
+    }
+    if (args.activatePath !== undefined && typeof args.activatePath !== "string") {
+      throw new Error("verify_bug.activatePath must be a string");
+    }
+  }
 }

package/src/zentao.js

@@ -154,6 +154,326 @@ export function createZenTaoClient(config) {
     return { total: list.length, matched: filtered.length, projects: filtered };
   }
 
+  function parseBugsFromResponse(data) {
+    if (Array.isArray(data?.bugs)) return data.bugs;
+    if (Array.isArray(data?.data?.bugs)) return data.data.bugs;
+    if (Array.isArray(data?.data)) return data.data;
+    if (Array.isArray(data)) return data;
+    return [];
+  }
+
+  function parseBugDetailFromResponse(data) {
+    if (data?.bug && typeof data.bug === "object") return data.bug;
+    if (data?.data?.bug && typeof data.data.bug === "object") return data.data.bug;
+    if (data?.data && typeof data.data === "object" && !Array.isArray(data.data)) return data.data;
+    if (data && typeof data === "object" && !Array.isArray(data)) return data;
+    return null;
+  }
+
+  function normalizeString(value) {
+    return String(value || "").trim().toLowerCase();
+  }
+
+  function getBugAssignee(bug) {
+    return (
+      bug?.assignedTo ||
+      bug?.assignedto ||
+      bug?.assigned_to ||
+      bug?.assignedUser ||
+      bug?.owner ||
+      ""
+    );
+  }
+
+  function matchesBugFilters(bug, { status, keyword, assignee }) {
+    const normalizedStatus = normalizeString(status);
+    const normalizedKeyword = normalizeString(keyword);
+    const normalizedAssignee = normalizeString(assignee);
+
+    if (normalizedStatus) {
+      const bugStatus = normalizeString(bug?.status);
+      if (bugStatus !== normalizedStatus) return false;
+    }
+
+    if (normalizedAssignee) {
+      const bugAssignee = normalizeString(getBugAssignee(bug));
+      if (bugAssignee !== normalizedAssignee) return false;
+    }
+
+    if (normalizedKeyword) {
+      const searchableText = [
+        bug?.title,
+        bug?.severity,
+        bug?.pri,
+        bug?.steps,
+        bug?.status,
+        getBugAssignee(bug),
+      ]
+        .filter(Boolean)
+        .map((value) => String(value).toLowerCase())
+        .join(" ");
+      if (!searchableText.includes(normalizedKeyword)) return false;
+    }
+
+    return true;
+  }
+
+  function buildBugDetailPath({ id, path }) {
+    const normalizedId = Number(id);
+    const basePath = path || "/bugs/{id}";
+    if (basePath.includes("{id}")) {
+      return basePath.replaceAll("{id}", String(normalizedId));
+    }
+    const trimmed = basePath.replace(/\/+$/, "");
+    return `${trimmed}/${normalizedId}`;
+  }
+
+  function buildBugResolvePath({ id, path }) {
+    return buildBugTransitionPath({ id, path, action: "resolve" });
+  }
+
+  function buildBugTransitionPath({ id, path, action }) {
+    const normalizedId = Number(id);
+    const safeAction = String(action || "").trim();
+    if (!safeAction) throw new Error("buildBugTransitionPath requires action");
+    const basePath = path || `/bugs/{id}/${safeAction}`;
+    if (basePath.includes("{id}")) {
+      return basePath.replaceAll("{id}", String(normalizedId));
+    }
+    const trimmed = basePath.replace(/\/+$/, "");
+    return `${trimmed}/${normalizedId}/${safeAction}`;
+  }
+
+  function getBugId(bug) {
+    const id = Number(
+      bug?.id ??
+      bug?.bugId ??
+      bug?.bugID ??
+      bug?.bug_id ??
+      bug?.bug?.id
+    );
+    return Number.isFinite(id) && id > 0 ? id : null;
+  }
+
+  function extractImageUrlsFromBug(bug) {
+    const images = new Set();
+    const addMatches = (value) => {
+      if (!value) return;
+      const text = String(value);
+      const srcRegex = /<img[^>]+src=["']([^"']+)["']/gi;
+      for (const match of text.matchAll(srcRegex)) {
+        if (match[1]) images.add(match[1]);
+      }
+      const urlRegex = /https?:\/\/[^\s"'<>]+\.(png|jpe?g|gif|webp|bmp|svg)/gi;
+      for (const match of text.matchAll(urlRegex)) {
+        if (match[0]) images.add(match[0]);
+      }
+    };
+    addMatches(bug?.steps);
+    addMatches(bug?.stepsHtml);
+    addMatches(bug?.openedBuild);
+    return Array.from(images);
+  }
+
+  async function getMyBugs({ status, keyword, limit = 20, page = 1, path = "/bugs", assignedTo } = {}) {
+    const safeLimit = Math.max(1, Math.min(Number(limit) || 20, 200));
+    const safePage = Math.max(1, Number(page) || 1);
+    const assignee = normalizeString(assignedTo) || normalizeString(auth.account);
+
+    const query = {
+      limit: safeLimit,
+      page: safePage,
+      assignedTo: assignee || undefined,
+      status: status || undefined,
+    };
+    const resp = await call({ path, method: "GET", query });
+    const bugs = parseBugsFromResponse(resp.data);
+    const filtered = bugs.filter((bug) => matchesBugFilters(bug, { status, keyword, assignee }));
+
+    return {
+      total: bugs.length,
+      matched: filtered.length,
+      page: safePage,
+      limit: safeLimit,
+      assignedTo: assignee,
+      bugs: filtered,
+      raw: { status: resp.status },
+    };
+  }
+
+  async function getBugDetail({ id, path = "/bugs/{id}" } = {}) {
+    const bugId = Number(id);
+    if (!Number.isFinite(bugId) || bugId < 1) {
+      throw new Error("getBugDetail requires a valid bug id");
+    }
+
+    const detailPath = buildBugDetailPath({ id: bugId, path });
+    const resp = await call({ path: detailPath, method: "GET" });
+    const bug = parseBugDetailFromResponse(resp.data);
+    if (!bug) {
+      return {
+        id: bugId,
+        found: false,
+        images: [],
+        raw: { status: resp.status, data: resp.data },
+      };
+    }
+
+    return {
+      id: bugId,
+      found: true,
+      bug,
+      images: extractImageUrlsFromBug(bug),
+      raw: { status: resp.status },
+    };
+  }
+
+  async function resolveBug({ id, resolution = "fixed", comment = "", path = "/bugs/{id}/resolve" } = {}) {
+    const bugId = Number(id);
+    if (!Number.isFinite(bugId) || bugId < 1) {
+      throw new Error("resolveBug requires a valid bug id");
+    }
+
+    const resolvePath = buildBugResolvePath({ id: bugId, path });
+    const body = { resolution: String(resolution || "fixed") };
+    if (comment) body.comment = String(comment);
+
+    const resp = await call({ path: resolvePath, method: "POST", body });
+    return {
+      id: bugId,
+      resolved: true,
+      resolution: body.resolution,
+      raw: { status: resp.status, data: resp.data },
+    };
+  }
+
+  async function closeBug({ id, comment = "", path = "/bugs/{id}/close" } = {}) {
+    const bugId = Number(id);
+    if (!Number.isFinite(bugId) || bugId < 1) {
+      throw new Error("closeBug requires a valid bug id");
+    }
+
+    const closePath = buildBugTransitionPath({ id: bugId, path, action: "close" });
+    const body = {};
+    if (comment) body.comment = String(comment);
+
+    const resp = await call({ path: closePath, method: "POST", body });
+    return {
+      id: bugId,
+      closed: true,
+      raw: { status: resp.status, data: resp.data },
+    };
+  }
+
+  async function activateBug({ id, comment = "", path = "/bugs/{id}/activate" } = {}) {
+    const bugId = Number(id);
+    if (!Number.isFinite(bugId) || bugId < 1) {
+      throw new Error("activateBug requires a valid bug id");
+    }
+
+    const activatePath = buildBugTransitionPath({ id: bugId, path, action: "activate" });
+    const body = {};
+    if (comment) body.comment = String(comment);
+
+    const resp = await call({ path: activatePath, method: "POST", body });
+    return {
+      id: bugId,
+      activated: true,
+      raw: { status: resp.status, data: resp.data },
+    };
+  }
+
+  async function verifyBug({
+    id,
+    result = "pass",
+    comment = "",
+    closePath = "/bugs/{id}/close",
+    activatePath = "/bugs/{id}/activate",
+  } = {}) {
+    const normalizedResult = normalizeString(result || "pass");
+    if (normalizedResult !== "pass" && normalizedResult !== "fail") {
+      throw new Error("verifyBug.result must be pass or fail");
+    }
+
+    if (normalizedResult === "pass") {
+      const closeResult = await closeBug({ id, comment, path: closePath });
+      return {
+        id: Number(id),
+        verified: true,
+        result: "pass",
+        action: "close",
+        raw: closeResult.raw,
+      };
+    }
+
+    const activateResult = await activateBug({ id, comment, path: activatePath });
+    return {
+      id: Number(id),
+      verified: true,
+      result: "fail",
+      action: "activate",
+      raw: activateResult.raw,
+    };
+  }
+
+  async function batchResolveMyBugs({
+    status = "active",
+    keyword = "",
+    limit = 50,
+    page = 1,
+    maxItems = 50,
+    assignedTo = "",
+    resolution = "fixed",
+    comment = "",
+    listPath = "/bugs",
+    resolvePath = "/bugs/{id}/resolve",
+    stopOnError = false,
+  } = {}) {
+    const safeMaxItems = Math.max(1, Math.min(Number(maxItems) || 50, 500));
+    const listResult = await getMyBugs({
+      status,
+      keyword,
+      limit,
+      page,
+      path: listPath,
+      assignedTo,
+    });
+
+    const candidates = (listResult.bugs || []).slice(0, safeMaxItems);
+    const success = [];
+    const failed = [];
+
+    for (const bug of candidates) {
+      const bugId = getBugId(bug);
+      if (!bugId) {
+        failed.push({ id: null, error: "Missing bug id in list item" });
+        if (stopOnError) break;
+        continue;
+      }
+      try {
+        const result = await resolveBug({
+          id: bugId,
+          resolution,
+          comment,
+          path: resolvePath,
+        });
+        success.push({ id: bugId, status: result.raw.status });
+      } catch (err) {
+        failed.push({ id: bugId, error: String(err?.message || err) });
+        if (stopOnError) break;
+      }
+    }
+
+    return {
+      requested: listResult.matched,
+      attempted: candidates.length,
+      resolved: success.length,
+      failed: failed.length,
+      success,
+      errors: failed,
+    };
+  }
+
   // 轻量重试：禅道偶发 502/网关问题时可用；默认不用，保留扩展点
   async function callWithRetry(args, { retries = 0, backoffMs = 200 } = {}) {
     let lastErr;
@@ -169,5 +489,16 @@ export function createZenTaoClient(config) {
     throw lastErr;
   }
 
-  return { getToken, call, callWithRetry, listMyProjects };
+  return {
+    getToken,
+    call,
+    callWithRetry,
+    listMyProjects,
+    getMyBugs,
+    getBugDetail,
+    resolveBug,
+    closeBug,
+    verifyBug,
+    batchResolveMyBugs,
+  };
 }