@aipper/zentao-mcp-server 0.1.7 → 0.1.9

package/.env.example

@@ -11,6 +11,18 @@ ZENTAO_PASSWORD=your_password
 # 可选：默认产品 ID（当实例请求 bug 列表需要 product id 时使用）
 # ZENTAO_PRODUCT_ID=1
 
+# 可选：默认项目集 ID（当 bug 在项目集视角时使用）
+# ZENTAO_PROJECT_SET_ID=1001
+
+# 可选：我的 bug 列表路径（例如 /my/bug 或 /my/bugs）
+# ZENTAO_MY_BUGS_PATH=/my/bug
+
+# 可选：bug 列表回退路径（逗号分隔）
+# ZENTAO_BUGS_FALLBACK_PATHS=/my/bug,/my/bugs
+
+# 可选：项目集 bug 路径模板（逗号分隔，支持 {projectSetId} 占位）
+# ZENTAO_PROJECT_SET_BUGS_PATHS=/projectsets/{projectSetId}/bugs,/programs/{projectSetId}/bugs
+
 # 获取 Token 的路径（相对 ZENTAO_BASE_URL；通常为 /api.php/v1/tokens）
 ZENTAO_TOKEN_PATH=/api.php/v1/tokens
 

package/README.md

@@ -17,6 +17,10 @@
 - `ZENTAO_ACCOUNT`
 - `ZENTAO_PASSWORD`
 - （可选）`ZENTAO_PRODUCT_ID`：你的禅道实例若报 `Need product id` 时设置
+- （可选）`ZENTAO_PROJECT_SET_ID`：你的 bug 若在项目集视角，设置项目集 ID
+- （可选）`ZENTAO_MY_BUGS_PATH`：我的 bug 专用接口路径（如 `/my/bug`）
+- （可选）`ZENTAO_BUGS_FALLBACK_PATHS`：bug 列表回退路径（逗号分隔）
+- （可选）`ZENTAO_PROJECT_SET_BUGS_PATHS`：项目集 bug 路径模板（支持 `{projectSetId}`）
 
 > 注意：不同禅道版本/部署方式的 token 端点与返回结构可能不同；可通过 `ZENTAO_TOKEN_PATH`/`ZENTAO_API_PREFIX` 调整。
 >
@@ -88,6 +92,9 @@ npm run smoke
 `-32000` 通常是客户端侧“通用 MCP 调用失败”映射码，优先检查：
 - `env` 是否完整传入（尤其是 `ZENTAO_BASE_URL`/`ZENTAO_ACCOUNT`/`ZENTAO_PASSWORD`）。
 - 若报 `Need product id`，请设置 `ZENTAO_PRODUCT_ID`，或在 `get_my_bugs` 传 `productId`。
+- 若你的 bug 在“项目集/我的视角”而非产品，建议设置 `ZENTAO_PROJECT_SET_ID`，并配置 `ZENTAO_MY_BUGS_PATH=/my/bug`。
+- `get_my_bugs` 会按候选路径回退（包含项目集路径）；即使首个路径返回空列表也会继续尝试。
+- 排查时看工具返回里的 `raw.triedPaths`，可确认每条路径的返回码与命中数量。
 - `ZENTAO_API_PREFIX`/`ZENTAO_TOKEN_PATH` 是否和你的禅道实例一致。
 - MCP 客户端是否真的在执行 `npx -y @aipper/zentao-mcp-server`（而不是旧的本地命令）。
 - 客户端日志中是否有启动报错（如找不到命令、401、超时）。
@@ -96,19 +103,25 @@ npm run smoke
 - `get_token`：获取/刷新 token（默认不回显完整 token）
 - `call`：调用任意相对 API 路径（自动带 Token 头）
 - `list_my_projects`：示例：列出“我参与的项目”（字段匹配基于常见返回结构，可能需按你的实例微调）
-- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`/`productId`，默认路径 `/bugs`）
-- `get_bug_detail`：按 `id` 获取 bug 详情（默认路径模板 `/bugs/{id}`，返回详情与图片链接）
-- `resolve_bug`：按 `id` 处理单个 bug 状态（默认 `resolution=fixed`）
-- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`，支持 `productId`）
+- `get_my_bugs`：获取“指派给我”的 bug（支持 `status`/`keyword`/`limit`/`page`/`productId`/`projectSetId`，默认路径 `/bugs`）
+- `get_bug_detail`：按 `id` 获取 bug 详情（默认路径模板 `/bugs/{id}`，返回详情与图片链接；会提取富文本 `<img>`、Markdown 图片、附件图片并归一化为可访问 URL）
+- `resolve_bug`：按 `id` 处理单个 bug 状态（默认 `resolution=fixed`，支持 `solution` 解决说明）
+- `batch_resolve_my_bugs`：批量处理“我的 bug”（默认筛选 `status=active`，支持 `productId`/`projectSetId`）
 - `close_bug`：按 `id` 关闭 bug
 - `verify_bug`：验证结果处理（`pass`=关闭，`fail`=激活）
+- `comment_bug`：按 `id` 添加备注（默认路径 `/bugs/{id}/comment`）
 
 示例参数：
 - `resolve_bug`：`{"id":123,"resolution":"fixed","comment":"已修复并自测"}`
+- `resolve_bug`（建议）：`{"id":123,"resolution":"fixed","solution":"修复空指针并补充参数校验"}`
 - `batch_resolve_my_bugs`：`{"status":"active","maxItems":20,"comment":"批量修复"}`
+- `batch_resolve_my_bugs`（建议）：`{"status":"active","maxItems":20,"solution":"统一修复分页参数为空导致的报错"}`
 - `get_my_bugs`（按产品）：`{"status":"active","productId":1,"limit":50}`
+- `get_my_bugs`（项目集）：`{"status":"active","projectSetId":1001,"limit":50}`
+- `get_my_bugs`（我的）：`{"status":"active","path":"/my/bug","limit":50}`
 - `close_bug`：`{"id":123,"comment":"验证通过，关闭"}`
 - `verify_bug`：`{"id":123,"result":"pass","comment":"验证通过"}`
+- `comment_bug`：`{"id":123,"comment":"已复现，正在定位根因"}`
 
 ## 安全建议
 - 使用最小权限账号（仅需要的项目权限），避免使用管理员账号。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipper/zentao-mcp-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "private": false,
   "type": "module",
   "description": "A minimal MCP server for ZenTao (token + generic REST call + a few helper tools).",

package/src/index.js

@@ -18,6 +18,7 @@ const KNOWN_TOOL_NAMES = new Set([
   "batch_resolve_my_bugs",
   "close_bug",
   "verify_bug",
+  "comment_bug",
 ]);
 
 function normalizeToolName(rawName) {
@@ -49,6 +50,16 @@ function getConfigFromEnv() {
   const timeoutMs = Number(process.env.ZENTAO_HTTP_TIMEOUT_MS || "30000");
   const exposeToken = String(process.env.ZENTAO_EXPOSE_TOKEN || "false").toLowerCase() === "true";
   const defaultProductId = Number(process.env.ZENTAO_PRODUCT_ID || "0") || null;
+  const defaultProjectSetId = Number(process.env.ZENTAO_PROJECT_SET_ID || "0") || null;
+  const myBugsPath = String(process.env.ZENTAO_MY_BUGS_PATH || "").trim();
+  const bugsFallbackPaths = String(process.env.ZENTAO_BUGS_FALLBACK_PATHS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
+  const projectSetBugsPaths = String(process.env.ZENTAO_PROJECT_SET_BUGS_PATHS || "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean);
 
   const account = requireEnv("ZENTAO_ACCOUNT");
   const password = requireEnv("ZENTAO_PASSWORD");
@@ -61,6 +72,10 @@ function getConfigFromEnv() {
     timeoutMs,
     exposeToken,
     defaultProductId,
+    defaultProjectSetId,
+    myBugsPath,
+    bugsFallbackPaths,
+    projectSetBugsPaths,
     auth: { account, password },
   };
 }
@@ -116,6 +131,7 @@ async function main() {
           limit: args.limit,
           page: args.page,
           productId: args.productId,
+          projectSetId: args.projectSetId,
           path: args.path || "/bugs",
           assignedTo: args.assignedTo || "",
         });
@@ -134,6 +150,7 @@ async function main() {
         const resp = await zentao.resolveBug({
           id: args.id,
           resolution: args.resolution || "fixed",
+          solution: args.solution || "",
           comment: args.comment || "",
           path: args.path || "/bugs/{id}/resolve",
         });
@@ -147,9 +164,11 @@ async function main() {
           limit: args.limit,
           page: args.page,
           productId: args.productId,
+          projectSetId: args.projectSetId,
           maxItems: args.maxItems,
           assignedTo: args.assignedTo || "",
           resolution: args.resolution || "fixed",
+          solution: args.solution || "",
           comment: args.comment || "",
           listPath: args.listPath || "/bugs",
           resolvePath: args.resolvePath || "/bugs/{id}/resolve",
@@ -178,6 +197,15 @@ async function main() {
         return toMcpTextResult(JSON.stringify(resp, null, 2));
       }
 
+      if (toolName === "comment_bug") {
+        const resp = await zentao.commentBug({
+          id: args.id,
+          comment: args.comment || "",
+          path: args.path || "/bugs/{id}/comment",
+        });
+        return toMcpTextResult(JSON.stringify(resp, null, 2));
+      }
+
       throw new Error(`Unknown tool: ${rawToolName}`);
     } catch (err) {
       const errorPayload = {
@@ -187,6 +215,7 @@ async function main() {
         status: err?.status ?? null,
         data: err?.data ?? null,
         hint: "If you see 'Need product id', set env ZENTAO_PRODUCT_ID or pass productId in get_my_bugs.",
+        hint2: "For project-set instances, set ZENTAO_PROJECT_SET_ID or ZENTAO_MY_BUGS_PATH.",
       };
       return toMcpTextResult(JSON.stringify(errorPayload, null, 2), { isError: true });
     }

package/src/tools.js

@@ -53,6 +53,7 @@ export const TOOLS = [
         limit: { type: "number", minimum: 1, maximum: 200, description: "Default 20, max 200" },
         page: { type: "number", minimum: 1, description: "Default 1" },
         productId: { type: "number", minimum: 1, description: "Optional product id (for instances requiring product scope)" },
+        projectSetId: { type: "number", minimum: 1, description: "Optional project-set id (for project-set scope)" },
         path: { type: "string", description: "Optional bugs endpoint override, default /bugs" },
         assignedTo: { type: "string", description: "Optional assignee override, default current account" },
       },
@@ -80,6 +81,7 @@ export const TOOLS = [
       properties: {
         id: { type: "number", minimum: 1, description: "Bug ID" },
         resolution: { type: "string", description: "Default fixed" },
+        solution: { type: "string", description: "Resolution description (preferred)" },
         comment: { type: "string", description: "Optional resolve comment" },
         path: { type: "string", description: "Optional resolve endpoint template, default /bugs/{id}/resolve" },
       },
@@ -98,9 +100,11 @@ export const TOOLS = [
         limit: { type: "number", minimum: 1, maximum: 200, description: "List page size, default 50" },
         page: { type: "number", minimum: 1, description: "Default 1" },
         productId: { type: "number", minimum: 1, description: "Optional product id (for instances requiring product scope)" },
+        projectSetId: { type: "number", minimum: 1, description: "Optional project-set id (for project-set scope)" },
         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" },
+        solution: { type: "string", description: "Resolution description (preferred)" },
         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" },
@@ -139,6 +143,20 @@ export const TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: "comment_bug",
+    description: "Add comment to one bug by ID.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "number", minimum: 1, description: "Bug ID" },
+        comment: { type: "string", description: "Comment content" },
+        path: { type: "string", description: "Optional comment endpoint template, default /bugs/{id}/comment" },
+      },
+      required: ["id", "comment"],
+      additionalProperties: false,
+    },
+  },
 ];
 
 export function assertToolArgs(name, args) {
@@ -160,6 +178,9 @@ export function assertToolArgs(name, args) {
     if (args.productId !== undefined && (!Number.isFinite(args.productId) || args.productId < 1)) {
       throw new Error("get_my_bugs.productId must be a number >= 1");
     }
+    if (args.projectSetId !== undefined && (!Number.isFinite(args.projectSetId) || args.projectSetId < 1)) {
+      throw new Error("get_my_bugs.projectSetId must be a number >= 1");
+    }
   }
   if (name === "get_bug_detail") {
     if (!Number.isFinite(args.id) || Number(args.id) < 1) {
@@ -176,6 +197,9 @@ export function assertToolArgs(name, args) {
     if (args.path !== undefined && typeof args.path !== "string") {
       throw new Error("resolve_bug.path must be a string");
     }
+    if (args.solution !== undefined && typeof args.solution !== "string") {
+      throw new Error("resolve_bug.solution must be a string");
+    }
   }
   if (name === "batch_resolve_my_bugs") {
     if (args.limit !== undefined && (!Number.isFinite(args.limit) || args.limit < 1 || args.limit > 200)) {
@@ -190,12 +214,18 @@ export function assertToolArgs(name, args) {
     if (args.productId !== undefined && (!Number.isFinite(args.productId) || args.productId < 1)) {
       throw new Error("batch_resolve_my_bugs.productId must be a number >= 1");
     }
+    if (args.projectSetId !== undefined && (!Number.isFinite(args.projectSetId) || args.projectSetId < 1)) {
+      throw new Error("batch_resolve_my_bugs.projectSetId must be a number >= 1");
+    }
     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 (args.solution !== undefined && typeof args.solution !== "string") {
+      throw new Error("batch_resolve_my_bugs.solution must be a string");
+    }
   }
   if (name === "close_bug") {
     if (!Number.isFinite(args.id) || Number(args.id) < 1) {
@@ -222,4 +252,15 @@ export function assertToolArgs(name, args) {
       throw new Error("verify_bug.activatePath must be a string");
     }
   }
+  if (name === "comment_bug") {
+    if (!Number.isFinite(args.id) || Number(args.id) < 1) {
+      throw new Error("comment_bug.id must be a number >= 1");
+    }
+    if (typeof args.comment !== "string" || !args.comment.trim()) {
+      throw new Error("comment_bug.comment must be a non-empty string");
+    }
+    if (args.path !== undefined && typeof args.path !== "string") {
+      throw new Error("comment_bug.path must be a string");
+    }
+  }
 }

package/src/zentao.js

@@ -31,7 +31,19 @@ function createAbortSignal(timeoutMs) {
 }
 
 export function createZenTaoClient(config) {
-  const { baseUrl, apiPrefix, tokenPath, tokenTtlMs, timeoutMs, defaultProductId, auth } = config;
+  const {
+    baseUrl,
+    apiPrefix,
+    tokenPath,
+    tokenTtlMs,
+    timeoutMs,
+    defaultProductId,
+    defaultProjectSetId,
+    myBugsPath,
+    bugsFallbackPaths,
+    projectSetBugsPaths,
+    auth,
+  } = config;
 
   let cachedToken = "";
   let cachedAt = 0;
@@ -193,11 +205,62 @@ export function createZenTaoClient(config) {
     return basePath;
   }
 
+  function buildMyBugsPath(pathTemplate) {
+    const template = String(pathTemplate || "").trim();
+    if (!template) return "";
+    return template.replaceAll("{account}", encodeURIComponent(auth.account || ""));
+  }
+
+  function buildProjectSetPath(pathTemplate, projectSetId) {
+    const template = String(pathTemplate || "").trim();
+    if (!template) return "";
+    const pid = normalizePositiveInt(projectSetId);
+    if (!pid) return "";
+    return template.replaceAll("{projectSetId}", String(pid));
+  }
+
+  function isMyBugsPath(path) {
+    const normalized = String(path || "").toLowerCase();
+    return normalized.includes("/my/bug");
+  }
+
+  function isProjectSetPath(path) {
+    const normalized = String(path || "").toLowerCase();
+    return (
+      normalized.includes("/projectset") ||
+      normalized.includes("/project-set") ||
+      normalized.includes("/projectsets") ||
+      normalized.includes("/programs/")
+    );
+  }
+
   function isNeedProductIdError(err) {
     const merged = `${String(err?.message || "")} ${JSON.stringify(err?.data || "")}`.toLowerCase();
     return merged.includes("need product id");
   }
 
+  function buildBugsQueryForPath({ path, limit, page, assignedTo, status, productId }) {
+    if (isMyBugsPath(path) || isProjectSetPath(path)) {
+      // "我的bug"和"项目集bug"类端点在部分实例不接受 assignedTo/status/product 参数，使用最小分页参数后本地过滤。
+      return { limit, page };
+    }
+    return {
+      limit,
+      page,
+      assignedTo: assignedTo || undefined,
+      status: status || undefined,
+      product: productId || undefined,
+    };
+  }
+
+  function buildResolutionComment({ solution, comment, resolution }) {
+    const normalizedSolution = String(solution || "").trim();
+    if (normalizedSolution) return `解决说明：${normalizedSolution}`;
+    const normalizedComment = String(comment || "").trim();
+    if (normalizedComment) return normalizedComment;
+    return `已处理，resolution=${String(resolution || "fixed")}`;
+  }
+
   function getBugAssignee(bug) {
     return (
       bug?.assignedTo ||
@@ -256,6 +319,16 @@ export function createZenTaoClient(config) {
     return buildBugTransitionPath({ id, path, action: "resolve" });
   }
 
+  function buildBugCommentPath({ id, path }) {
+    const normalizedId = Number(id);
+    const basePath = path || "/bugs/{id}/comment";
+    if (basePath.includes("{id}")) {
+      return basePath.replaceAll("{id}", String(normalizedId));
+    }
+    const trimmed = basePath.replace(/\/+$/, "");
+    return `${trimmed}/${normalizedId}/comment`;
+  }
+
   function buildBugTransitionPath({ id, path, action }) {
     const normalizedId = Number(id);
     const safeAction = String(action || "").trim();
@@ -279,23 +352,105 @@ export function createZenTaoClient(config) {
     return Number.isFinite(id) && id > 0 ? id : null;
   }
 
+  function normalizeResourceUrl(value) {
+    const raw = String(value || "").trim();
+    if (!raw) return "";
+    if (raw.startsWith("data:")) return "";
+    const cleaned = raw.replaceAll("&", "&");
+    if (/^https?:\/\//i.test(cleaned)) return cleaned;
+    if (cleaned.startsWith("//")) {
+      const protocol = new URL(baseUrl).protocol || "https:";
+      return `${protocol}${cleaned}`;
+    }
+    if (cleaned.startsWith("/")) {
+      return new URL(cleaned, `${baseUrl}/`).toString();
+    }
+    const normalized = cleaned.replace(/^\.?\//, "");
+    if (!normalized) return "";
+    return new URL(`/${normalized}`, `${baseUrl}/`).toString();
+  }
+
+  function isImageLikeText(value) {
+    const text = String(value || "").toLowerCase();
+    if (!text) return false;
+    if (text.includes("image/")) return true;
+    return /\.(png|jpe?g|gif|webp|bmp|svg|ico|avif)(?:$|[?#])/i.test(text);
+  }
+
+  function fileRecordLooksImage(record) {
+    if (!record || typeof record !== "object") return false;
+    if (record.isImage === true || record.isImage === 1 || record.image === true) return true;
+    const probes = [
+      record.mime,
+      record.contentType,
+      record.extension,
+      record.ext,
+      record.title,
+      record.name,
+      record.pathname,
+      record.path,
+      record.url,
+      record.webPath,
+      record.downloadUrl,
+      record.downloadurl,
+    ];
+    return probes.some((value) => isImageLikeText(value));
+  }
+
   function extractImageUrlsFromBug(bug) {
     const images = new Set();
+    const addImageUrl = (value) => {
+      const url = normalizeResourceUrl(value);
+      if (url) images.add(url);
+    };
     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]);
+        if (match[1]) addImageUrl(match[1]);
       }
-      const urlRegex = /https?:\/\/[^\s"'<>]+\.(png|jpe?g|gif|webp|bmp|svg)/gi;
+      const markdownImageRegex = /!\[[^\]]*]\(([^)\s]+)(?:\s+"[^"]*")?\)/gi;
+      for (const match of text.matchAll(markdownImageRegex)) {
+        if (match[1]) addImageUrl(match[1]);
+      }
+      const urlRegex = /https?:\/\/[^\s"'<>]+/gi;
       for (const match of text.matchAll(urlRegex)) {
-        if (match[0]) images.add(match[0]);
+        if (isImageLikeText(match[0])) addImageUrl(match[0]);
+      }
+    };
+
+    const addImagesFromFiles = (files) => {
+      if (!files) return;
+      const list = Array.isArray(files) ? files : Object.values(files);
+      for (const item of list) {
+        if (!item || typeof item !== "object") continue;
+        if (!fileRecordLooksImage(item)) continue;
+        const candidates = [
+          item.webPath,
+          item.url,
+          item.downloadUrl,
+          item.downloadurl,
+          item.path,
+          item.pathname,
+          item.viewUrl,
+          item.href,
+        ];
+        for (const candidate of candidates) {
+          if (candidate) addImageUrl(candidate);
+        }
       }
     };
+
     addMatches(bug?.steps);
     addMatches(bug?.stepsHtml);
+    addMatches(bug?.reproStep);
+    addMatches(bug?.comment);
+    addMatches(bug?.resolution);
     addMatches(bug?.openedBuild);
+    addImagesFromFiles(bug?.files);
+    addImagesFromFiles(bug?.attachments);
+    addImagesFromFiles(bug?.openedFiles);
     return Array.from(images);
   }
 
@@ -305,6 +460,7 @@ export function createZenTaoClient(config) {
     limit = 20,
     page = 1,
     productId,
+    projectSetId,
     path = "/bugs",
     assignedTo,
   } = {}) {
@@ -312,43 +468,110 @@ export function createZenTaoClient(config) {
     const safePage = Math.max(1, Number(page) || 1);
     const assignee = normalizeString(assignedTo) || normalizeString(auth.account);
     const effectiveProductId = normalizePositiveInt(productId) || normalizePositiveInt(defaultProductId);
+    const effectiveProjectSetId = normalizePositiveInt(projectSetId) || normalizePositiveInt(defaultProjectSetId);
     const primaryPath = buildProductScopedBugsPath({ productId: effectiveProductId, path });
-
-    const query = {
+    const preferProjectSetPath =
+      effectiveProjectSetId &&
+      (!path || String(path).trim() === "" || String(path).trim() === "/bugs");
+    const configuredMyBugsPath = buildMyBugsPath(myBugsPath);
+    const fallbackPathCandidates = (bugsFallbackPaths && bugsFallbackPaths.length > 0)
+      ? bugsFallbackPaths
+      : ["/my/bug", "/my/bugs"];
+    const fallbackPaths = fallbackPathCandidates.map((item) => buildMyBugsPath(item)).filter(Boolean);
+    const projectSetCandidates = (projectSetBugsPaths && projectSetBugsPaths.length > 0)
+      ? projectSetBugsPaths
+      : ["/projectsets/{projectSetId}/bugs", "/projectset/{projectSetId}/bugs", "/programs/{projectSetId}/bugs"];
+    const projectSetPaths = projectSetCandidates
+      .map((item) => buildProjectSetPath(item, effectiveProjectSetId))
+      .filter(Boolean);
+
+    const baseQuery = {
       limit: safeLimit,
       page: safePage,
-      assignedTo: assignee || undefined,
-      status: status || undefined,
-      product: effectiveProductId || undefined,
+      assignedTo: assignee,
+      status,
+      productId: effectiveProductId,
     };
-    let resp;
-    try {
-      resp = await call({ path: primaryPath, method: "GET", query });
-    } catch (err) {
-      const fallbackPath = effectiveProductId ? `/products/${effectiveProductId}/bugs` : null;
-      if (
-        fallbackPath &&
-        primaryPath !== fallbackPath &&
-        isNeedProductIdError(err)
-      ) {
-        resp = await call({ path: fallbackPath, method: "GET", query: { limit: safeLimit, page: safePage } });
-      } else {
-        throw err;
+    const candidatePaths = [];
+    if (preferProjectSetPath) {
+      for (const projectSetPath of projectSetPaths) {
+        if (!candidatePaths.includes(projectSetPath)) candidatePaths.push(projectSetPath);
       }
     }
+    candidatePaths.push(primaryPath);
+    if (effectiveProductId) {
+      const productPath = `/products/${effectiveProductId}/bugs`;
+      if (!candidatePaths.includes(productPath)) candidatePaths.push(productPath);
+    }
+    if (!preferProjectSetPath) {
+      for (const projectSetPath of projectSetPaths) {
+        if (!candidatePaths.includes(projectSetPath)) candidatePaths.push(projectSetPath);
+      }
+    }
+    if (configuredMyBugsPath && !candidatePaths.includes(configuredMyBugsPath)) {
+      candidatePaths.push(configuredMyBugsPath);
+    }
+    for (const fallback of fallbackPaths) {
+      if (!candidatePaths.includes(fallback)) candidatePaths.push(fallback);
+    }
 
-    const bugs = parseBugsFromResponse(resp?.data);
-    const filtered = bugs.filter((bug) => matchesBugFilters(bug, { status, keyword, assignee }));
+    let bestResult = null;
+    let lastErr = null;
+    const triedPaths = [];
+    for (const candidate of candidatePaths) {
+      try {
+        const query = buildBugsQueryForPath({ path: candidate, ...baseQuery });
+        const resp = await call({ path: candidate, method: "GET", query });
+        const bugs = parseBugsFromResponse(resp?.data);
+        const filtered = bugs.filter((bug) => matchesBugFilters(bug, { status, keyword, assignee }));
+
+        triedPaths.push({
+          path: candidate,
+          status: resp?.status ?? null,
+          total: bugs.length,
+          matched: filtered.length,
+        });
+
+        const currentResult = {
+          total: bugs.length,
+          matched: filtered.length,
+          page: safePage,
+          limit: safeLimit,
+          productId: effectiveProductId,
+          projectSetId: effectiveProjectSetId,
+          assignedTo: assignee,
+          bugs: filtered,
+          raw: { status: resp?.status, path: candidate },
+        };
+
+        if (
+          !bestResult ||
+          currentResult.matched > bestResult.matched ||
+          (currentResult.matched === bestResult.matched && currentResult.total > bestResult.total)
+        ) {
+          bestResult = currentResult;
+        }
+
+        if (currentResult.matched > 0) break;
+      } catch (err) {
+        lastErr = err;
+        triedPaths.push({
+          path: candidate,
+          status: err?.status ?? null,
+          error: String(err?.message || err),
+        });
+        if (!isNeedProductIdError(err)) continue;
+        if (candidate !== primaryPath) continue;
+      }
+    }
+    if (!bestResult) throw lastErr;
 
     return {
-      total: bugs.length,
-      matched: filtered.length,
-      page: safePage,
-      limit: safeLimit,
-      productId: effectiveProductId,
-      assignedTo: assignee,
-      bugs: filtered,
-      raw: { status: resp?.status, path: primaryPath },
+      ...bestResult,
+      raw: {
+        ...bestResult.raw,
+        triedPaths,
+      },
     };
   }
 
@@ -379,21 +602,33 @@ export function createZenTaoClient(config) {
     };
   }
 
-  async function resolveBug({ id, resolution = "fixed", comment = "", path = "/bugs/{id}/resolve" } = {}) {
+  async function resolveBug({
+    id,
+    resolution = "fixed",
+    solution = "",
+    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 resolvedValue = String(resolution || "fixed");
+    const resolvedComment = buildResolutionComment({ solution, comment, resolution: resolvedValue });
+    const body = {
+      resolution: resolvedValue,
+      comment: resolvedComment,
+    };
 
     const resp = await call({ path: resolvePath, method: "POST", body });
     return {
       id: bugId,
       resolved: true,
-      resolution: body.resolution,
+      resolution: resolvedValue,
+      solution: String(solution || "").trim(),
+      comment: resolvedComment,
       raw: { status: resp.status, data: resp.data },
     };
   }
@@ -467,15 +702,52 @@ export function createZenTaoClient(config) {
     };
   }
 
+  async function commentBug({ id, comment, path = "/bugs/{id}/comment" } = {}) {
+    const bugId = Number(id);
+    if (!Number.isFinite(bugId) || bugId < 1) {
+      throw new Error("commentBug requires a valid bug id");
+    }
+    const text = String(comment || "").trim();
+    if (!text) {
+      throw new Error("commentBug requires non-empty comment");
+    }
+
+    const primaryPath = buildBugCommentPath({ id: bugId, path });
+    const body = { comment: text };
+    try {
+      const resp = await call({ path: primaryPath, method: "POST", body });
+      return {
+        id: bugId,
+        commented: true,
+        comment: text,
+        raw: { status: resp.status, path: primaryPath, data: resp.data },
+      };
+    } catch (err) {
+      const fallbackPath = primaryPath.replace(/\/comment$/, "/comments");
+      if (fallbackPath !== primaryPath && Number(err?.status) === 404) {
+        const resp = await call({ path: fallbackPath, method: "POST", body });
+        return {
+          id: bugId,
+          commented: true,
+          comment: text,
+          raw: { status: resp.status, path: fallbackPath, data: resp.data },
+        };
+      }
+      throw err;
+    }
+  }
+
   async function batchResolveMyBugs({
     status = "active",
     keyword = "",
     limit = 50,
     page = 1,
     productId,
+    projectSetId,
     maxItems = 50,
     assignedTo = "",
     resolution = "fixed",
+    solution = "",
     comment = "",
     listPath = "/bugs",
     resolvePath = "/bugs/{id}/resolve",
@@ -488,6 +760,7 @@ export function createZenTaoClient(config) {
       limit,
       page,
       productId,
+      projectSetId,
       path: listPath,
       assignedTo,
     });
@@ -507,6 +780,7 @@ export function createZenTaoClient(config) {
         const result = await resolveBug({
           id: bugId,
           resolution,
+          solution,
           comment,
           path: resolvePath,
         });
@@ -552,6 +826,7 @@ export function createZenTaoClient(config) {
     resolveBug,
     closeBug,
     verifyBug,
+    commentBug,
     batchResolveMyBugs,
   };
 }