@chenyingxian/zentao-mcp 0.1.0

package/src/zentao-client.js

@@ -0,0 +1,1123 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const DEFAULT_TIMEOUT_MS = 15000;
+const MAX_REC_PER_PAGE = 1000;
+
+export class ZentaoApiError extends Error {
+  /**
+   * Create a normalized ZenTao API error.
+   * @param {string} message Error message.
+   * @param {{statusCode?: number, response?: unknown}} options Error options.
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "ZentaoApiError";
+    this.statusCode = options.statusCode;
+    this.response = options.response;
+  }
+}
+
+export class ZentaoClient {
+  /**
+   * Create a ZenTao RESTful API v1 client.
+   * @param {{baseUrl: string, account?: string, password?: string, token?: string, timeoutMs?: number, fetchImpl?: typeof fetch}} options Client options.
+   */
+  constructor(options) {
+    if (!options?.baseUrl) throw new Error("ZENTAO_BASE_URL is required.");
+    this.baseUrl = normalizeBaseUrl(options.baseUrl);
+    this.account = options.account;
+    this.currentAccount = "";
+    this.password = options.password;
+    this.token = options.token || "";
+    this.timeoutMs = Number(options.timeoutMs || DEFAULT_TIMEOUT_MS);
+    this.fetchImpl = options.fetchImpl || globalThis.fetch;
+    if (typeof this.fetchImpl !== "function") throw new Error("fetch is unavailable. Please run with Node.js 18 or newer.");
+  }
+  /**
+   * Fetch pending tasks assigned to the authenticated ZenTao user from "My Work".
+   * @param {{recPerPage?: number, pageId?: number}} params Query parameters.
+   * @returns {Promise<{account: string, title: string, todoCount: unknown, tasks: unknown[], raw: unknown}>} Normalized task result.
+   */
+  async getMyTasks(params = {}) {
+    const recPerPage = clampRecPerPage(params?.recPerPage);
+    const pageId = assertPositiveId(params?.pageId ?? 1, "pageId");
+    const account = await this.getCurrentAccount();
+    const orderBy = sanitizeRouteSegment(params?.orderBy || "id_desc", "orderBy");
+    const route = `/my-work-task-assignedTo-${orderBy}-0-${pageId}-${recPerPage}.json`;
+    const response = await this.requestLegacyJson(route);
+    const tasks = Array.isArray(response?.tasks) ? response.tasks.filter((task) => sameAccount(getAssignedAccount(task), account)) : [];
+    return { account, title: String(response?.title || ""), todoCount: response?.todoCount, tasks, raw: response };
+  }
+  /**
+   * Fetch tasks finished by the authenticated ZenTao user.
+   * @param {{orderBy?: string, recPerPage?: number, pageId?: number}} params Query parameters.
+   * @returns {Promise<{account: string, title: string, count: number, tasks: unknown[], raw: unknown}>} Finished tasks.
+   */
+  async getFinishedTasks(params = {}) {
+    const recPerPage = clampRecPerPage(params?.recPerPage);
+    const pageId = assertPositiveId(params?.pageId ?? 1, "pageId");
+    const account = await this.getCurrentAccount();
+    const response = await this.requestLegacyJson("/my-contribute-task-finishedBy.json");
+    const tasks = Array.isArray(response?.tasks) ? response.tasks.filter((task) => sameAccount(getFinishedAccount(task), account)) : [];
+    const sortedTasks = tasks.sort((left, right) => Number(right?.id || 0) - Number(left?.id || 0));
+    const offset = (pageId - 1) * recPerPage;
+    return { account, title: String(response?.title || ""), count: sortedTasks.length, tasks: sortedTasks.slice(offset, offset + recPerPage), raw: response };
+  }
+  /**
+   * Fetch one ZenTao task by ID.
+   * @param {number|string} taskId Task ID.
+   * @returns {Promise<unknown>} Task detail.
+   */
+  async getTask(taskId) {
+    const id = assertPositiveId(taskId, "taskId");
+    const task = await this.request("GET", `/tasks/${id}`);
+    if (task && typeof task === "object" && typeof task.desc === "string") {
+      return { ...task, descText: htmlToText(task.desc) };
+    }
+    return task;
+  }
+  /**
+   * Read base data needed before submitting a task to test.
+   * @param {number|string} taskId Task ID.
+   * @returns {Promise<{taskId: number, storyId: number, projectId: number, productId: number, branch: number, task: unknown, story: unknown, product: unknown}>} Submit-test base data.
+   */
+  async getSubmitTestBaseData(taskId) {
+    const id = assertPositiveId(taskId, "taskId");
+    const task = await this.getTask(id);
+    const storyId = Number(task?.storyID || task?.story || 0);
+    const projectId = Number(task?.project || 0);
+    if (!Number.isInteger(storyId) || storyId <= 0) throw new ZentaoApiError("Task does not contain a valid story ID.", { response: task });
+    if (!Number.isInteger(projectId) || projectId <= 0) throw new ZentaoApiError("Task does not contain a valid project ID.", { response: task });
+    const story = await this.request("GET", `/stories/${storyId}`);
+    const productId = Number(story?.product || task?.product || 0);
+    const branch = Number(story?.branch || 0);
+    if (!Number.isInteger(productId) || productId <= 0) throw new ZentaoApiError("Task story does not contain a valid product ID.", { response: story });
+    const product = await this.request("GET", `/products/${productId}`);
+    return { taskId: id, storyId, projectId, productId, branch, task, story, product };
+  }
+  /**
+   * Find test tasks corresponding to one development task.
+   * @param {number|string} taskId Development task ID.
+   * @returns {Promise<{taskId: number, storyId: number, projectId: number, productId: number, productName: string, branch: number, executionId: number, expectedTestTaskName: string, testTasks: unknown[], testUsers: unknown[], task: unknown}>} Matching test tasks.
+   */
+  async findSubmitTestTasks(taskId) {
+    const baseData = await this.getSubmitTestBaseData(taskId);
+    const executionId = Number(baseData.task?.execution || 0);
+    if (!Number.isInteger(executionId) || executionId <= 0) throw new ZentaoApiError("Task does not contain a valid execution ID.", { response: baseData.task });
+    const expectedTestTaskName = buildExpectedTestTaskName(String(baseData.task?.name || ""));
+    const response = await this.request("GET", `/executions/${executionId}/tasks?limit=1000&page=1`);
+    const tasks = Array.isArray(response?.tasks) ? response.tasks : [];
+    const testTasks = tasks.filter((task) => Number(task?.story || task?.storyID || 0) === baseData.storyId && isMatchingTestTaskName(String(task?.name || ""), expectedTestTaskName));
+    return { taskId: baseData.taskId, storyId: baseData.storyId, projectId: baseData.projectId, productId: baseData.productId, productName: String(baseData.product?.name || ""), branch: baseData.branch, executionId, expectedTestTaskName, testTasks, testUsers: getAssignedUsers(testTasks), task: baseData.task };
+  }
+  /**
+   * Find builds created by current user for one development task.
+   * @param {number|string} taskId Development task ID.
+   * @returns {Promise<{taskId: number, storyId: number, projectId: number, executionId: number, expectedBuildName: string, builds: unknown[], task: unknown}>} Matching builds.
+   */
+  async findSubmitTestBuilds(taskId) {
+    const baseData = await this.getSubmitTestBaseData(taskId);
+    const account = await this.getCurrentAccount();
+    const executionId = Number(baseData.task?.execution || 0);
+    if (!Number.isInteger(executionId) || executionId <= 0) throw new ZentaoApiError("Task does not contain a valid execution ID.", { response: baseData.task });
+    const expectedBuildName = buildExpectedBuildName(String(baseData.task?.name || ""));
+    const response = await this.request("GET", `/projects/${baseData.projectId}/builds?limit=100&page=1`);
+    const builds = Array.isArray(response?.builds) ? response.builds : [];
+    const matchedBuilds = builds.filter((build) => Number(build?.execution || 0) === executionId && sameAccount(String(build?.createdBy || build?.builder || ""), account) && isMatchingBuildName(String(build?.name || ""), expectedBuildName));
+    return { taskId: baseData.taskId, storyId: baseData.storyId, projectId: baseData.projectId, executionId, expectedBuildName, builds: matchedBuilds, task: baseData.task };
+  }
+  /**
+   * Prepare build creation payload without creating it.
+   * @param {number|string} taskId Development task ID.
+   * @returns {Promise<{taskId: number, storyId: number, projectId: number, executionId: number, payload: unknown, referenceBuild: unknown}>} Build creation data.
+   */
+  async prepareSubmitTestBuildPayload(taskId) {
+    const baseData = await this.getSubmitTestBaseData(taskId);
+    const account = await this.getCurrentAccount();
+    const executionId = Number(baseData.task?.execution || 0);
+    if (!Number.isInteger(executionId) || executionId <= 0) throw new ZentaoApiError("Task does not contain a valid execution ID.", { response: baseData.task });
+    const response = await this.request("GET", `/executions/${executionId}/builds?limit=20&page=1`);
+    const builds = Array.isArray(response?.builds) ? response.builds : [];
+    const referenceBuild = findBestReferenceBuild(builds, account) || builds[0] || {};
+    const today = formatDate(new Date());
+    const payload = {
+      executionID: executionId,
+      product: baseData.productId,
+      productName: String(baseData.product?.name || ""),
+      branch: baseData.branch,
+      name: buildExpectedBuildName(String(baseData.task?.name || "")),
+      system: Number(referenceBuild.system || 0),
+      builder: account,
+      date: today,
+      scmPath: "",
+      filePath: "",
+      desc: "无",
+      stories: [baseData.storyId],
+      bugs: []
+    };
+    return { taskId: baseData.taskId, storyId: baseData.storyId, projectId: baseData.projectId, productId: baseData.productId, productName: String(baseData.product?.name || ""), branch: baseData.branch, executionId, payload, referenceBuild };
+  }
+  /**
+   * Create a ZenTao build for a development task and link the task story after creation.
+   * @param {number|string} taskId Development task ID.
+   * @param {{dryRun?: boolean}} params Creation options.
+   * @returns {Promise<{dryRun: boolean, taskId: number, storyId: number, projectId: number, productId: number, productName: string, branch: number, executionId: number, payload: unknown, createResult?: unknown, linkResult?: unknown, build?: unknown, buildId?: number, storyViewUrl?: string}>} Build creation result.
+   */
+  async createBuildForTask(taskId, params = {}) {
+    const prepared = await this.prepareSubmitTestBuildPayload(taskId);
+    const testTaskInfo = await this.findSubmitTestTasks(taskId);
+    const dryRun = params.dryRun !== false;
+    if (dryRun) return { dryRun: true, taskId: prepared.taskId, storyId: prepared.storyId, projectId: prepared.projectId, productId: prepared.productId, productName: prepared.productName, branch: prepared.branch, executionId: prepared.executionId, expectedTestTaskName: testTaskInfo.expectedTestTaskName, testTasks: testTaskInfo.testTasks, testUsers: testTaskInfo.testUsers, payload: prepared.payload };
+    const createResult = await this.createBuildFromPayload(prepared.projectId, prepared.executionId, prepared.payload);
+    const buildId = getBuildIdFromCreateResult(createResult);
+    if (!buildId) throw new ZentaoApiError("ZenTao build creation succeeded but build ID was not found.", { response: createResult });
+    const linked = await this.linkBuildStory(buildId, prepared.storyId);
+    return { dryRun: false, taskId: prepared.taskId, storyId: prepared.storyId, projectId: prepared.projectId, productId: prepared.productId, productName: prepared.productName, branch: prepared.branch, executionId: prepared.executionId, expectedTestTaskName: testTaskInfo.expectedTestTaskName, testTasks: testTaskInfo.testTasks, testUsers: testTaskInfo.testUsers, payload: prepared.payload, createResult, linkResult: linked.result, build: linked.build, buildId, storyViewUrl: buildLegacyUrl(this.baseUrl, `/build-view-${buildId}-story-true.html`) };
+  }
+  /**
+   * Create a ZenTao test task for a development task and build.
+   * @param {number|string} taskId Development task ID.
+   * @param {number|string} buildId Build ID.
+   * @param {{dryRun?: boolean, owner?: string, begin?: string, end?: string, attachmentPaths?: string[]}} params Creation options.
+   * @returns {Promise<{dryRun: boolean, taskId: number, buildId: number, storyId: number, projectId: number, productId: number, productName: string, branch: number, executionId: number, owner: string, testUsers: unknown[], payload: unknown, createResult?: unknown, testtaskId?: number, testtaskViewUrl?: string}>} Test task creation result.
+   */
+  async createTestTaskForTask(taskId, buildId, params = {}) {
+    const id = assertPositiveId(buildId, "buildId");
+    const baseData = await this.getSubmitTestBaseData(taskId);
+    const executionId = Number(baseData.task?.execution || 0);
+    if (!Number.isInteger(executionId) || executionId <= 0) throw new ZentaoApiError("Task does not contain a valid execution ID.", { response: baseData.task });
+    const build = await this.request("GET", `/builds/${id}`);
+    const testTaskInfo = await this.findSubmitTestTasks(taskId);
+    const owner = String(params.owner || testTaskInfo.testUsers[0]?.account || "");
+    if (!owner) throw new ZentaoApiError("No test owner found. Please pass owner explicitly.", { response: testTaskInfo });
+    const range = resolveTestTaskDateRange(params.begin, params.end);
+    const attachmentPaths = Array.isArray(params.attachmentPaths) ? params.attachmentPaths.filter(Boolean).map(String) : [];
+    const payload = {
+      product: baseData.productId,
+      execution: executionId,
+      build: id,
+      name: buildTestTaskName(String(build?.name || baseData.task?.name || "")),
+      owner,
+      members: [owner],
+      pri: Number(baseData.task?.pri || 3),
+      type: "system",
+      begin: range.begin,
+      end: range.end,
+      desc: buildTestTaskDesc(baseData),
+      attachmentPaths
+    };
+    const dryRun = params.dryRun !== false;
+    if (dryRun) return { dryRun: true, taskId: baseData.taskId, buildId: id, storyId: baseData.storyId, projectId: baseData.projectId, productId: baseData.productId, productName: String(baseData.product?.name || ""), branch: baseData.branch, executionId, owner, testUsers: testTaskInfo.testUsers, payload };
+    const createPayload = omitInternalPayloadFields(payload);
+    const createResult = attachmentPaths.length ? await this.requestMultipart("POST", `/projects/${baseData.projectId}/testtasks`, createPayload, attachmentPaths) : await this.request("POST", `/projects/${baseData.projectId}/testtasks`, createPayload);
+    const testtaskId = getTestTaskIdFromCreateResult(createResult);
+    if (!testtaskId) throw new ZentaoApiError("ZenTao test task creation succeeded but test task ID was not found.", { response: createResult });
+    return { dryRun: false, taskId: baseData.taskId, buildId: id, storyId: baseData.storyId, projectId: baseData.projectId, productId: baseData.productId, productName: String(baseData.product?.name || ""), branch: baseData.branch, executionId, owner, testUsers: testTaskInfo.testUsers, payload, createResult, testtaskId, testtaskViewUrl: buildLegacyUrl(this.baseUrl, `/testtask-cases-${testtaskId}.html`) };
+  }
+  /**
+   * Prepare a publish task from development task IDs without creating it by default.
+   * @param {{taskIds: Array<number|string>, system: string, storyId?: number|string, releaseScope?: string, grayTag?: string, branch?: string, database?: string, env?: string, cron?: string, dependencies?: string, other?: string, risk?: string, releaseContent?: string[], dryRun?: boolean}} params Release task options.
+   * @returns {Promise<{dryRun: boolean, taskIds: number[], storyIds: number[], primaryStoryId: number, projectId: number, executionId: number, name: string, assignedTo: string, payload: unknown, warnings: string[]}>} Prepared release task data.
+   */
+  async createReleaseTask(params) {
+    const taskIds = assertPositiveIdList(params?.taskIds, "taskIds");
+    const system = String(params?.system || "").trim();
+    if (!system) throw new Error("system is required.");
+    const releaseScope = String(params?.releaseScope || "生产环境").trim();
+    const currentAccount = await this.getCurrentAccount();
+    const baseItems = [];
+    for (const taskId of taskIds) baseItems.push(await this.getSubmitTestBaseData(taskId));
+    const mainItems = await this.getMainTaskBaseItems(baseItems);
+    const releaseUsers = await this.getReleaseTaskUsers(baseItems);
+    const primary = baseItems[0];
+    const branch = String(params?.branch || findFirstBranch(mainItems) || findFirstBranch(baseItems) || "").trim();
+    const warnings = [];
+    if (!branch) warnings.push("未从开发任务描述中解析到 git分支，请确认后补充 branch。");
+    if (isProductionScope(releaseScope) && !params?.grayTag) warnings.push("生产发布任务建议填写 grayTag，用于描述中记录灰度 tag。");
+    const storyIds = uniqueNumbers(baseItems.map((item) => item.storyId));
+    const primaryStoryId = params?.storyId ? assertPositiveId(params.storyId, "storyId") : storyIds[0];
+    const releaseContent = normalizeReleaseContent(params?.releaseContent, mainItems);
+    const releasePeople = formatReleasePeople(releaseUsers);
+    const payload = {
+      project: primary.projectId,
+      execution: Number(primary.task?.execution || 0),
+      story: primaryStoryId,
+      name: `发布-${system} xxxxxx ${releaseScope}`,
+      type: "publish",
+      assignedTo: currentAccount,
+      pri: 1,
+      estimate: 1,
+      estStarted: formatDate(new Date()),
+      deadline: formatDate(new Date()),
+      desc: buildReleaseTaskDesc({ system, releaseScope, branch, grayTag: params?.grayTag, releasePeople, releaseContent, database: params?.database, env: params?.env, cron: params?.cron, dependencies: params?.dependencies, other: params?.other, risk: params?.risk })
+    };
+    const dryRun = params?.dryRun !== false;
+    if (!dryRun) throw new ZentaoApiError("Release task creation is not enabled yet. Please confirm dry-run output first.", { response: payload });
+    return { dryRun: true, taskIds, mainTaskIds: uniqueNumbers(mainItems.map((item) => item.taskId)), storyIds, primaryStoryId, projectId: primary.projectId, executionId: Number(primary.task?.execution || 0), name: payload.name, assignedTo: currentAccount, releaseUsers: sortReleaseUsers(releaseUsers), payload, warnings };
+  }
+  /**
+   * Resolve parent development tasks for child tasks.
+   * @param {unknown[]} baseItems Task base data items.
+   * @returns {Promise<unknown[]>} Main task base data items.
+   */
+  async getMainTaskBaseItems(baseItems) {
+    const result = [];
+    const seen = new Set();
+    for (const item of baseItems) {
+      const parentId = Number(item?.task?.parent || 0);
+      const mainId = parentId > 0 ? parentId : item.taskId;
+      if (seen.has(mainId)) continue;
+      seen.add(mainId);
+      result.push(mainId === item.taskId ? item : await this.getSubmitTestBaseData(mainId));
+    }
+    return result;
+  }
+  /**
+   * Find development and test assignees from main tasks and child tasks.
+   * @param {unknown[]} baseItems Task base data items.
+   * @returns {Promise<Array<{account: string, realname?: string, roles: string[]}>>} Release task users.
+   */
+  async getReleaseTaskUsers(baseItems) {
+    const users = new Map();
+    for (const item of baseItems) {
+      const executionId = Number(item?.task?.execution || 0);
+      if (!executionId) continue;
+      const response = await this.request("GET", `/executions/${executionId}/tasks?limit=1000&page=1`);
+      const storyTasks = Array.isArray(response?.tasks) ? response.tasks.filter((task) => Number(task?.story || task?.storyID || 0) === item.storyId) : [];
+      addRoleUsers(users, findTaskTree(storyTasks, "devel"), "devel");
+      addRoleUsers(users, findTaskTree(storyTasks, "test"), "test");
+    }
+    return [...users.values()];
+  }
+  /**
+   * Create a build using ZenTao's legacy form endpoint.
+   * @param {number} projectId Project ID.
+   * @param {number} executionId Execution ID.
+   * @param {unknown} payload Prepared build payload.
+   * @returns {Promise<unknown>} Creation response.
+   */
+  async createBuildFromPayload(projectId, executionId, payload) {
+    const product = Number(payload?.product || 0);
+    if (!Number.isInteger(product) || product <= 0) throw new ZentaoApiError("Build payload does not contain a valid product ID.", { response: payload });
+    const body = new URLSearchParams();
+    body.append("execution", String(executionId));
+    body.append("product", String(product));
+    body.append("branch[]", String(Number(payload?.branch || 0)));
+    body.append("system", String(Number(payload?.system || 0)));
+    body.append("newSystem", "");
+    body.append("systemName", "");
+    body.append("name", String(payload?.name || ""));
+    body.append("builder", String(payload?.builder || ""));
+    body.append("date", String(payload?.date || formatDate(new Date())));
+    body.append("scmPath", String(payload?.scmPath || ""));
+    body.append("filePath", String(payload?.filePath || ""));
+    body.append("desc", String(payload?.desc || "无"));
+    body.append("project", String(projectId));
+    return this.requestLegacyForm(`/build-create-${executionId}.html?t=json`, body);
+  }
+  /**
+   * Link one story to an existing build through ZenTao's legacy form endpoint.
+   * @param {number|string} buildId Build ID.
+   * @param {number|string} storyId Story ID.
+   * @returns {Promise<{buildId: number, storyId: number, result: unknown, build: unknown}>} Link result and refreshed build detail.
+   */
+  async linkBuildStory(buildId, storyId) {
+    const id = assertPositiveId(buildId, "buildId");
+    const story = assertPositiveId(storyId, "storyId");
+    const body = new URLSearchParams();
+    body.append("stories[]", String(story));
+    const result = await this.requestLegacyForm(`/build-linkStory-${id}--0.html?t=json`, body);
+    const build = await this.request("GET", `/builds/${id}`);
+    return { buildId: id, storyId: story, result, build };
+  }
+  /**
+   * Fetch effort logs from ZenTao "My Effort" and calendar overview.
+   * @param {{type?: string, orderBy?: string, recPerPage?: number, pageId?: number}} params Query parameters.
+   * @returns {Promise<{calendar: unknown, title: string, count: number, efforts: unknown[], raw: unknown}>} Effort logs.
+   */
+  async getEffortLogs(params = {}) {
+    const type = sanitizeRouteSegment(params?.type || "all", "type");
+    const orderBy = sanitizeRouteSegment(params?.orderBy || "date_desc", "orderBy");
+    const recPerPage = clampRecPerPage(params?.recPerPage);
+    const pageId = assertPositiveId(params?.pageId ?? 1, "pageId");
+    const calendar = await this.requestLegacyJson("/effort-calendar.json");
+    const response = await this.requestLegacyJson(`/my-effort-${type}-${orderBy}-0-${recPerPage}-${pageId}.json`);
+    const efforts = Array.isArray(response?.efforts) ? response.efforts : [];
+    return { calendar: getCalendarSummary(calendar), title: String(response?.title || ""), count: efforts.length, efforts, raw: response };
+  }
+  /**
+   * Generate a weekly summary from effort logs.
+   * @param {{startDate?: string, endDate?: string, maxPages?: number, recPerPage?: number}} params Query parameters.
+   * @returns {Promise<{range: {startDate: string, endDate: string}, count: number, totalConsumed: number, summary: string, efforts: unknown[]}>} Weekly summary.
+   */
+  async generateWeeklySummary(params = {}) {
+    const range = resolveWeekRange(params.startDate, params.endDate);
+    const recPerPage = clampRecPerPage(params.recPerPage || 100);
+    const maxPages = assertPositiveId(params.maxPages || 10, "maxPages");
+    const efforts = [];
+    for (let pageId = 1; pageId <= maxPages; pageId += 1) {
+      const page = await this.getEffortLogs({ recPerPage, pageId });
+      const pageEfforts = page.efforts || [];
+      efforts.push(...pageEfforts.filter((effort) => effort.date >= range.startDate && effort.date <= range.endDate && !isWeeklySummaryEffort(effort)));
+      if (pageEfforts.length === 0 || pageEfforts.some((effort) => effort.date < range.startDate)) break;
+    }
+    const sortedEfforts = efforts.sort((left, right) => right.date.localeCompare(left.date) || Number(right.id || 0) - Number(left.id || 0));
+    const totalConsumed = normalizeHour(sortedEfforts.reduce((sum, effort) => sum + Number(effort.consumed || 0), 0));
+    const summary = buildWeeklySummaryText(sortedEfforts, totalConsumed);
+    return { range, count: sortedEfforts.length, totalConsumed, summary, efforts: sortedEfforts };
+  }
+  /**
+   * Get the authenticated account name.
+   * @returns {Promise<string>} Current account.
+   */
+  async getCurrentAccount() {
+    const response = await this.request("GET", "/user");
+    const account = response?.profile?.account || this.account;
+    if (!account) throw new ZentaoApiError("ZenTao current user profile does not contain account.", { response });
+    this.currentAccount = String(account);
+    return this.currentAccount;
+  }
+  /**
+   * Ensure an API token is available.
+   * @returns {Promise<string>} API token.
+   */
+  async ensureToken() {
+    if (this.token) return this.token;
+    if (!this.account || !this.password) throw new Error("ZENTAO_TOKEN or both ZENTAO_ACCOUNT and ZENTAO_PASSWORD are required.");
+    const response = await this.request("POST", "/tokens", { account: this.account, password: this.password }, false);
+    const token = getTokenFromResponse(response);
+    if (!token) throw new ZentaoApiError("ZenTao login failed or token is empty.", { response });
+    this.token = token;
+    return this.token;
+  }
+  /**
+   * Execute one ZenTao API request.
+   * @param {"GET"|"POST"|"PUT"|"DELETE"} method HTTP method.
+   * @param {string} path API path beginning with slash.
+   * @param {unknown} body JSON body.
+   * @param {boolean} authenticated Whether token auth is required.
+   * @returns {Promise<unknown>} JSON response.
+   */
+  async request(method, path, body = undefined, authenticated = true) {
+    const headers = { Accept: "application/json" };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (authenticated) headers.Token = await this.ensureToken();
+    const response = await fetchWithTimeout(this.fetchImpl, buildApiUrl(this.baseUrl, path), { method, headers, body: body === undefined ? undefined : JSON.stringify(body) }, this.timeoutMs);
+    const payload = await readJsonResponse(response);
+    if (!response.ok) throw new ZentaoApiError(`ZenTao API request failed with HTTP ${response.status}.`, { statusCode: response.status, response: payload });
+    if (payload?.status === "fail") throw new ZentaoApiError("ZenTao API returned fail status.", { statusCode: response.status, response: payload });
+    return payload;
+  }
+  /**
+   * Execute one ZenTao API multipart request.
+   * @param {"POST"|"PUT"} method HTTP method.
+   * @param {string} path API path beginning with slash.
+   * @param {Record<string, unknown>} fields Form fields.
+   * @param {string[]} filePaths Local file paths to upload as files[].
+   * @returns {Promise<unknown>} JSON response.
+   */
+  async requestMultipart(method, path, fields, filePaths) {
+    const form = new FormData();
+    appendFormFields(form, fields);
+    await appendFiles(form, filePaths);
+    const headers = { Accept: "application/json", Token: await this.ensureToken() };
+    const response = await fetchWithTimeout(this.fetchImpl, buildApiUrl(this.baseUrl, path), { method, headers, body: form }, this.timeoutMs);
+    const payload = await readJsonResponse(response);
+    if (!response.ok) throw new ZentaoApiError(`ZenTao API multipart request failed with HTTP ${response.status}.`, { statusCode: response.status, response: payload });
+    if (payload?.status === "fail") throw new ZentaoApiError("ZenTao API returned fail status.", { statusCode: response.status, response: payload });
+    return payload;
+  }
+  /**
+   * Execute one ZenTao legacy JSON route request.
+   * @param {string} route Route path beginning with slash.
+   * @returns {Promise<unknown>} Parsed legacy JSON data payload.
+   */
+  async requestLegacyJson(route) {
+    const headers = { Accept: "application/json", Token: await this.ensureToken() };
+    const response = await fetchWithTimeout(this.fetchImpl, buildLegacyUrl(this.baseUrl, route), { method: "GET", headers }, this.timeoutMs);
+    const payload = await readJsonResponse(response);
+    if (!response.ok) throw new ZentaoApiError(`ZenTao legacy request failed with HTTP ${response.status}.`, { statusCode: response.status, response: payload });
+    if (payload?.status !== "success") throw new ZentaoApiError("ZenTao legacy API returned non-success status.", { statusCode: response.status, response: payload });
+    if (typeof payload.data !== "string") return payload;
+    try {
+      return JSON.parse(payload.data);
+    } catch (error) {
+      throw new ZentaoApiError("ZenTao legacy API returned malformed data JSON.", { statusCode: response.status, response: payload });
+    }
+  }
+  /**
+   * Submit one ZenTao legacy form route and parse its JSON response.
+   * @param {string} route Legacy route.
+   * @param {URLSearchParams} body Form body.
+   * @returns {Promise<unknown>} Parsed submit response.
+   */
+  async requestLegacyForm(route, body) {
+    const headers = { Accept: "application/json, text/javascript, */*; q=0.01", "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8", "X-Requested-With": "XMLHttpRequest", Token: await this.ensureToken() };
+    const response = await fetchWithTimeout(this.fetchImpl, buildLegacyUrl(this.baseUrl, route), { method: "POST", headers, body }, this.timeoutMs);
+    const payload = await readJsonResponse(response);
+    if (!response.ok) throw new ZentaoApiError(`ZenTao legacy form request failed with HTTP ${response.status}.`, { statusCode: response.status, response: payload });
+    if (payload?.result && payload.result !== "success") throw new ZentaoApiError("ZenTao legacy form returned non-success result.", { statusCode: response.status, response: payload });
+    return payload;
+  }
+}
+
+/**
+ * Build a client from process environment variables.
+ * @param {NodeJS.ProcessEnv} env Process environment.
+ * @returns {ZentaoClient} ZenTao client.
+ */
+export function createClientFromEnv(env = process.env) {
+  return new ZentaoClient({ baseUrl: env.ZENTAO_BASE_URL, account: env.ZENTAO_ACCOUNT, password: env.ZENTAO_PASSWORD, token: env.ZENTAO_TOKEN, timeoutMs: env.ZENTAO_TIMEOUT_MS });
+}
+
+/**
+ * Normalize a ZenTao site URL.
+ * @param {string} value Raw URL.
+ * @returns {string} URL without trailing slash.
+ */
+function normalizeBaseUrl(value) {
+  return String(value).trim().replace(/\/+$/, "");
+}
+
+/**
+ * Build a RESTful API v1 URL from a site root or api.php URL.
+ * @param {string} baseUrl Base URL.
+ * @param {string} path API path.
+ * @returns {string} Full request URL.
+ */
+function buildApiUrl(baseUrl, path) {
+  const apiRoot = "/api.php/v1";
+  if (baseUrl.endsWith(apiRoot)) return `${baseUrl}${path}`;
+  if (baseUrl.endsWith("/api.php")) return `${baseUrl}/v1${path}`;
+  if (baseUrl.endsWith("/api.php/v2")) return `${baseUrl.replace(/\/api\.php\/v2$/, apiRoot)}${path}`;
+  return `${baseUrl}${apiRoot}${path}`;
+}
+
+/**
+ * Build a legacy ZenTao JSON route URL from a site root.
+ * @param {string} baseUrl Base URL.
+ * @param {string} route Legacy route.
+ * @returns {string} Full request URL.
+ */
+function buildLegacyUrl(baseUrl, route) {
+  const siteRoot = baseUrl.replace(/\/api\.php(\/v[12])?$/, "");
+  return `${siteRoot}${route}`;
+}
+
+/**
+ * Restrict dynamic legacy route segments to simple safe characters.
+ * @param {string} value Raw route segment.
+ * @param {string} name Field name.
+ * @returns {string} Safe route segment.
+ */
+function sanitizeRouteSegment(value, name) {
+  const segment = String(value);
+  if (!/^[A-Za-z0-9_]+$/.test(segment)) throw new Error(`${name} contains unsupported characters.`);
+  return segment;
+}
+
+/**
+ * Extract a token from known ZenTao login response shapes.
+ * @param {unknown} response Login response.
+ * @returns {string} API token.
+ */
+function getTokenFromResponse(response) {
+  const token = response?.token || response?.data?.token || response?.data?.user?.token;
+  return token ? String(token) : "";
+}
+
+/**
+ * Extract a build ID from ZenTao create responses.
+ * @param {unknown} response Build creation response.
+ * @returns {number} Build ID, or 0 when unavailable.
+ */
+function getBuildIdFromCreateResult(response) {
+  const directId = Number(response?.id || response?.buildID || response?.data?.id || response?.data?.buildID || 0);
+  if (Number.isInteger(directId) && directId > 0) return directId;
+  const load = String(response?.load || response?.locate || "");
+  const match = load.match(/build-view-(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+/**
+ * Extract a test task ID from ZenTao create responses.
+ * @param {unknown} response Test task creation response.
+ * @returns {number} Test task ID, or 0 when unavailable.
+ */
+function getTestTaskIdFromCreateResult(response) {
+  const directId = Number(response?.id || response?.testtaskID || response?.taskID || response?.data?.id || response?.data?.testtaskID || 0);
+  if (Number.isInteger(directId) && directId > 0) return directId;
+  const load = String(response?.load || response?.locate || "");
+  const match = load.match(/testtask-(?:cases|view)-(\d+)/);
+  return match ? Number(match[1]) : 0;
+}
+
+/**
+ * Remove local-only fields before submitting to ZenTao.
+ * @param {Record<string, unknown>} payload Tool payload.
+ * @returns {Record<string, unknown>} ZenTao payload.
+ */
+function omitInternalPayloadFields(payload) {
+  const { attachmentPaths, ...fields } = payload;
+  return fields;
+}
+
+/**
+ * Append scalar and array fields to a multipart form.
+ * @param {FormData} form Multipart form.
+ * @param {Record<string, unknown>} fields Form fields.
+ * @returns {void}
+ */
+function appendFormFields(form, fields) {
+  for (const [name, value] of Object.entries(fields)) {
+    if (value === undefined || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) form.append(`${name}[]`, String(item));
+      continue;
+    }
+    form.append(name, String(value));
+  }
+}
+
+/**
+ * Append local files to a multipart form as ZenTao files[] uploads.
+ * @param {FormData} form Multipart form.
+ * @param {string[]} filePaths Local file paths.
+ * @returns {Promise<void>} Resolves after files are read.
+ */
+async function appendFiles(form, filePaths) {
+  for (const filePath of filePaths) {
+    const buffer = await readFile(filePath);
+    form.append("files[]", new Blob([buffer]), basename(filePath));
+  }
+}
+
+/**
+ * Read the assigned account from V1 task payloads.
+ * @param {unknown} task ZenTao task.
+ * @returns {string} Assigned account.
+ */
+function getAssignedAccount(task) {
+  const assignedTo = task?.assignedTo;
+  if (typeof assignedTo === "string") return assignedTo;
+  if (assignedTo?.account) return String(assignedTo.account);
+  return "";
+}
+
+/**
+ * Read unique assignees from matched test tasks.
+ * @param {unknown[]} tasks Test tasks.
+ * @returns {Array<{account: string, realname?: string}>} Assigned users.
+ */
+function getAssignedUsers(tasks) {
+  const users = new Map();
+  for (const task of tasks) {
+    const assignedTo = task?.assignedTo;
+    const account = typeof assignedTo === "string" ? assignedTo : String(assignedTo?.account || "");
+    if (!account || users.has(account)) continue;
+    const user = { account };
+    if (typeof assignedTo === "object" && assignedTo?.realname) user.realname = String(assignedTo.realname);
+    users.set(account, user);
+  }
+  return [...users.values()];
+}
+
+/**
+ * Find main tasks and child tasks for a role under one story.
+ * @param {unknown[]} tasks Same-story tasks.
+ * @param {string} type Task type.
+ * @returns {unknown[]} Related tasks.
+ */
+function findTaskTree(tasks, type) {
+  const mainIds = tasks.filter((task) => task?.type === type && Number(task?.parent || 0) === 0).map((task) => Number(task.id));
+  return tasks.filter((task) => task?.type === type && (mainIds.includes(Number(task.id)) || mainIds.includes(Number(task.parent || 0))));
+}
+
+/**
+ * Add assigned users from task list to a role-aware map.
+ * @param {Map<string, {account: string, realname?: string, roles: string[]}>} users User map.
+ * @param {unknown[]} tasks Tasks.
+ * @param {string} role User role.
+ * @returns {void}
+ */
+function addRoleUsers(users, tasks, role) {
+  for (const task of tasks) {
+    const taskUser = getTaskContributor(task);
+    const account = taskUser.account;
+    if (!account) continue;
+    const openedAccount = getUserObject(task?.openedBy)?.account || "";
+    if (openedAccount && sameAccount(account, openedAccount)) continue;
+    const current = users.get(account) || { account, roles: [] };
+    if (taskUser.realname) current.realname = taskUser.realname;
+    if (!current.roles.includes(role)) current.roles.push(role);
+    users.set(account, current);
+  }
+}
+
+/**
+ * Pick the real contributor for a task.
+ * @param {unknown} task ZenTao task.
+ * @returns {{account: string, realname?: string}} Contributor.
+ */
+function getTaskContributor(task) {
+  return getUserObject(task?.finishedBy) || getUserObject(task?.assignedTo) || { account: "" };
+}
+
+/**
+ * Normalize a ZenTao user field.
+ * @param {unknown} value User field.
+ * @returns {{account: string, realname?: string}|null} User object.
+ */
+function getUserObject(value) {
+  if (!value) return null;
+  if (typeof value === "string") return value ? { account: value } : null;
+  const account = String(value?.account || "");
+  if (!account) return null;
+  const user = { account };
+  if (value?.realname) user.realname = String(value.realname);
+  return user;
+}
+
+/**
+ * Format release participants with real names when available.
+ * @param {Array<{account: string, realname?: string}>} users Release users.
+ * @returns {string} Participant text.
+ */
+function formatReleasePeople(users) {
+  const sortedUsers = sortReleaseUsers(users);
+  return sortedUsers.map((user) => user.realname || user.account).filter(Boolean).join("、");
+}
+
+/**
+ * Sort release users by developer list first, then tester list, each lexically.
+ * @param {Array<{account: string, realname?: string, roles: string[]}>} users Release users.
+ * @returns {Array<{account: string, realname?: string, roles: string[]}>} Sorted users.
+ */
+function sortReleaseUsers(users) {
+  const emitted = new Set();
+  const result = [];
+  for (const role of ["devel", "test"]) {
+    const roleUsers = users.filter((user) => user.roles.includes(role) && !emitted.has(user.account)).sort(compareReleaseUser);
+    for (const user of roleUsers) {
+      emitted.add(user.account);
+      result.push(user);
+    }
+  }
+  return result;
+}
+
+/**
+ * Compare release users by display name.
+ * @param {{account: string, realname?: string}} left Left user.
+ * @param {{account: string, realname?: string}} right Right user.
+ * @returns {number} Sort comparison.
+ */
+function compareReleaseUser(left, right) {
+  return (left.realname || left.account).localeCompare(right.realname || right.account, "zh-Hans-CN");
+}
+
+/**
+ * Read the finished account from task payloads.
+ * @param {unknown} task ZenTao task.
+ * @returns {string} Finished account.
+ */
+function getFinishedAccount(task) {
+  const finishedBy = task?.finishedBy;
+  if (typeof finishedBy === "string") return finishedBy;
+  if (finishedBy?.account) return String(finishedBy.account);
+  return "";
+}
+
+/**
+ * Compare two date strings in descending order.
+ * @param {string|undefined} left First date.
+ * @param {string|undefined} right Second date.
+ * @returns {number} Sort comparison.
+ */
+function compareDateDesc(left, right) {
+  return String(right || "").localeCompare(String(left || ""));
+}
+
+/**
+ * Compare ZenTao accounts without being tripped by letter case.
+ * @param {string} left First account.
+ * @param {string} right Second account.
+ * @returns {boolean} Whether both accounts match.
+ */
+function sameAccount(left, right) {
+  return left.toLowerCase() === right.toLowerCase();
+}
+
+/**
+ * Convert ZenTao HTML content into readable plain text.
+ * @param {string} html HTML content.
+ * @returns {string} Plain text content.
+ */
+function htmlToText(html) {
+  return html
+    .replace(/<br\s*\/?>(?=.)/gi, "\n")
+    .replace(/<\/p>/gi, "\n")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&quot;/g, "\"")
+    .replace(/&#39;/g, "'")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/**
+ * Build a safe calendar summary without leaking user internals.
+ * @param {unknown} calendar Raw calendar data.
+ * @returns {unknown} Calendar summary.
+ */
+function getCalendarSummary(calendar) {
+  return {
+    title: calendar?.title || "",
+    date: calendar?.date || "",
+    effortCount: calendar?.effortCount,
+    todoCount: calendar?.todoCount,
+    user: calendar?.user ? { account: calendar.user.account, realname: calendar.user.realname } : null
+  };
+}
+
+/**
+ * Resolve a week date range.
+ * @param {string|undefined} startDate Start date.
+ * @param {string|undefined} endDate End date.
+ * @returns {{startDate: string, endDate: string}} Date range.
+ */
+function resolveWeekRange(startDate, endDate) {
+  if (startDate && endDate) return { startDate, endDate };
+  const now = new Date();
+  const day = now.getDay() || 7;
+  const start = new Date(now);
+  start.setDate(now.getDate() - day + 1);
+  const end = new Date(start);
+  end.setDate(start.getDate() + 6);
+  return { startDate: formatDate(start), endDate: formatDate(end) };
+}
+
+/**
+ * Format a Date as yyyy-mm-dd.
+ * @param {Date} date Date value.
+ * @returns {string} Formatted date.
+ */
+function formatDate(date) {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Resolve the default test task date range.
+ * @param {string|undefined} begin Begin date.
+ * @param {string|undefined} end End date.
+ * @returns {{begin: string, end: string}} Date range.
+ */
+function resolveTestTaskDateRange(begin, end) {
+  if (begin && end) return { begin, end };
+  const start = new Date();
+  const finish = new Date(start);
+  finish.setDate(start.getDate() + 4);
+  return { begin: begin || formatDate(start), end: end || formatDate(finish) };
+}
+
+/**
+ * Detect the existing weekly-summary effort entry.
+ * @param {unknown} effort Effort record.
+ * @returns {boolean} Whether this effort is a weekly summary.
+ */
+function isWeeklySummaryEffort(effort) {
+  const work = String(effort?.work || "");
+  return Number(effort?.objectID || 0) === 0 || /^1、/.test(work) && /共计[\d.]+小时/.test(work);
+}
+
+/**
+ * Build weekly summary text in the established numbered format.
+ * @param {unknown[]} efforts Effort records.
+ * @param {number} totalConsumed Total consumed hours.
+ * @returns {string} Weekly summary text.
+ */
+function buildWeeklySummaryText(efforts, totalConsumed) {
+  const items = efforts.map((effort) => cleanWorkText(String(effort?.work || ""))).filter(Boolean);
+  const uniqueItems = [...new Set(items)];
+  const body = uniqueItems.map((item, index) => `${index + 1}、${item}。`).join("");
+  return `${body}共计${formatHour(totalConsumed)}小时。`;
+}
+
+/**
+ * Clean one effort work item for weekly summary.
+ * @param {string} value Raw work text.
+ * @returns {string} Clean work text.
+ */
+function cleanWorkText(value) {
+  return value
+    .replace(/^【AI】/, "")
+    .replace(/[。.\s]+$/g, "")
+    .trim();
+}
+
+/**
+ * Normalize hour precision.
+ * @param {number} value Raw hours.
+ * @returns {number} Normalized hours.
+ */
+function normalizeHour(value) {
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * Format hour without unnecessary trailing decimal zero.
+ * @param {number} value Hours.
+ * @returns {string} Formatted hours.
+ */
+function formatHour(value) {
+  return Number.isInteger(value) ? String(value) : String(value);
+}
+
+/**
+ * Build the expected test task name from a development task name.
+ * @param {string} taskName Development task name.
+ * @returns {string} Expected test task name.
+ */
+function buildExpectedTestTaskName(taskName) {
+  if (taskName.startsWith("开发-")) return `测试-${taskName.slice("开发-".length)}`;
+  return taskName.replace(/^开发/, "测试");
+}
+
+/**
+ * Check whether a candidate task name matches the expected test task.
+ * @param {string} candidate Candidate task name.
+ * @param {string} expected Expected task name.
+ * @returns {boolean} Whether names match.
+ */
+function isMatchingTestTaskName(candidate, expected) {
+  return candidate === expected || stripTrailingNumber(candidate) === stripTrailingNumber(expected);
+}
+
+/**
+ * Strip a trailing ASCII number suffix.
+ * @param {string} value Raw task name.
+ * @returns {string} Task name without trailing number.
+ */
+function stripTrailingNumber(value) {
+  return value.replace(/\d+$/, "");
+}
+
+/**
+ * Build the expected build name from a development task name.
+ * @param {string} taskName Development task name.
+ * @returns {string} Expected build name.
+ */
+function buildExpectedBuildName(taskName) {
+  return stripTrailingNumber(taskName.replace(/^开发-/, "").replace(/^开发/, "")).trim();
+}
+
+/**
+ * Build the test task name from a build name.
+ * @param {string} buildName Build name.
+ * @returns {string} Test task name.
+ */
+function buildTestTaskName(buildName) {
+  const cleanName = stripTrailingNumber(buildName.replace(/^开发-/, "").replace(/^开发/, "").replace(/^测试-/, "")).trim();
+  return `测试-${cleanName}`;
+}
+
+/**
+ * Build the test task description from related task and story data.
+ * @param {unknown} baseData Submit-test base data.
+ * @returns {string} HTML description.
+ */
+function buildTestTaskDesc(baseData) {
+  const title = String(baseData?.story?.title || baseData?.task?.storyTitle || "");
+  return title ? `<p>关联需求：${escapeHtml(title)}</p>` : "<p>无</p>";
+}
+
+/**
+ * Escape a short text value for HTML.
+ * @param {string} value Raw text.
+ * @returns {string} Escaped HTML text.
+ */
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+/**
+ * Find the first git branch written in related development task descriptions.
+ * @param {unknown[]} baseItems Task base data items.
+ * @returns {string} Parsed branch.
+ */
+function findFirstBranch(baseItems) {
+  for (const item of baseItems) {
+    const text = htmlToText(String(item?.task?.desc || ""));
+    const match = text.match(/git\s*分支\s*[:：]\s*([^\s\n\r]+)/i);
+    if (match?.[1]) return match[1].trim();
+  }
+  return "";
+}
+
+/**
+ * Whether the release scope is production-like.
+ * @param {string} scope Release scope.
+ * @returns {boolean} Whether production.
+ */
+function isProductionScope(scope) {
+  return /生产/.test(scope) && !/灰度/.test(scope);
+}
+
+/**
+ * Normalize release content lines.
+ * @param {string[]|undefined} releaseContent Explicit release content.
+ * @param {unknown[]} baseItems Task base data items.
+ * @returns {string[]} Release content lines.
+ */
+function normalizeReleaseContent(releaseContent, baseItems) {
+  if (Array.isArray(releaseContent) && releaseContent.some(Boolean)) return releaseContent.map(String).map((item) => item.trim()).filter(Boolean);
+  return baseItems.map((item) => String(item?.story?.title || item?.task?.storyTitle || item?.task?.name || "")).map((item) => item.replace(/^开发-/, "").replace(/^测试-/, "").trim()).filter(Boolean);
+}
+
+/**
+ * Build the release task description in the established nine-section format.
+ * @param {{system: string, releaseScope: string, branch: string, grayTag?: string, releasePeople: string, releaseContent: string[], database?: string, env?: string, cron?: string, dependencies?: string, other?: string, risk?: string}} params Release content.
+ * @returns {string} HTML description.
+ */
+function buildReleaseTaskDesc(params) {
+  const codeLines = [params.system, params.branch ? `git分支: ${params.branch}` : "git分支: ", "tag: xxxxxx"];
+  if (isProductionScope(params.releaseScope) && params.grayTag) codeLines.push(`灰度tag: ${params.grayTag}`);
+  const releaseLines = [];
+  if (params.releasePeople) releaseLines.push(params.releasePeople);
+  releaseLines.push(...(params.releaseContent.length ? params.releaseContent.map((item, index) => `${index + 1}.${item}`) : ["1."]));
+  return [
+    section("一.更新范围", params.releaseScope),
+    section("二.代码", codeLines.join("\n")),
+    section("三.数据库", defaultNone(params.database)),
+    section("四.环境变量", defaultNone(params.env)),
+    section("五.计划任务", defaultNone(params.cron)),
+    section("六.依赖包", defaultNone(params.dependencies)),
+    section("七.其它", defaultNone(params.other)),
+    section("八.对外说明发布的内容", releaseLines.join("\n")),
+    section("九.风险", defaultNone(params.risk))
+  ].join("");
+}
+
+/**
+ * Build one HTML section.
+ * @param {string} title Section title.
+ * @param {string} body Section body.
+ * @returns {string} HTML section.
+ */
+function section(title, body) {
+  const lines = String(body || "").split(/\r?\n/).map((line) => `<p>${escapeHtml(line)}</p>`).join("");
+  return `<p>${escapeHtml(title)}</p>${lines}${"<p></p>".repeat(6)}`;
+}
+
+/**
+ * Default empty section text to "无".
+ * @param {string|undefined} value Raw value.
+ * @returns {string} Section text.
+ */
+function defaultNone(value) {
+  const text = String(value || "").trim();
+  return text || "无";
+}
+
+/**
+ * Check whether a candidate build name matches the expected build name.
+ * @param {string} candidate Candidate build name.
+ * @param {string} expected Expected build name.
+ * @returns {boolean} Whether names match.
+ */
+function isMatchingBuildName(candidate, expected) {
+  return stripTrailingNumber(candidate).includes(expected) || expected.includes(stripTrailingNumber(candidate));
+}
+
+/**
+ * Find the best reference build for default creation values.
+ * @param {unknown[]} builds Existing builds.
+ * @param {string} account Current account.
+ * @returns {unknown|undefined} Reference build.
+ */
+function findBestReferenceBuild(builds, account) {
+  return builds.find((build) => sameAccount(String(build?.createdBy || build?.builder?.account || build?.builder || ""), account)) || builds[0];
+}
+
+/**
+ * Validate a positive integer-like ID.
+ * @param {number|string} value Raw ID.
+ * @param {string} name Field name.
+ * @returns {number} Positive integer.
+ */
+function assertPositiveId(value, name) {
+  const id = Number(value);
+  if (!Number.isInteger(id) || id <= 0) throw new Error(`${name} must be a positive integer.`);
+  return id;
+}
+
+/**
+ * Validate a list of positive integer-like IDs.
+ * @param {Array<number|string>|undefined} values Raw IDs.
+ * @param {string} name Field name.
+ * @returns {number[]} Positive integers.
+ */
+function assertPositiveIdList(values, name) {
+  if (!Array.isArray(values) || values.length === 0) throw new Error(`${name} must contain at least one ID.`);
+  return values.map((value) => assertPositiveId(value, name));
+}
+
+/**
+ * Return unique positive numbers in input order.
+ * @param {number[]} values Raw numbers.
+ * @returns {number[]} Unique numbers.
+ */
+function uniqueNumbers(values) {
+  return [...new Set(values.filter((value) => Number.isInteger(value) && value > 0))];
+}
+
+/**
+ * Clamp page size to ZenTao's documented upper bound.
+ * @param {number|undefined} value Raw page size.
+ * @returns {number} Page size.
+ */
+function clampRecPerPage(value) {
+  const recPerPage = Number(value ?? 100);
+  if (!Number.isInteger(recPerPage) || recPerPage <= 0) throw new Error("recPerPage must be a positive integer.");
+  return Math.min(recPerPage, MAX_REC_PER_PAGE);
+}
+
+/**
+ * Fetch with a timeout so MCP calls do not hang indefinitely.
+ * @param {typeof fetch} fetchImpl Fetch implementation.
+ * @param {string} url Request URL.
+ * @param {RequestInit} options Fetch options.
+ * @param {number} timeoutMs Timeout in milliseconds.
+ * @returns {Promise<Response>} Fetch response.
+ */
+async function fetchWithTimeout(fetchImpl, url, options, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetchImpl(url, { ...options, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Read a JSON response and report malformed payloads clearly.
+ * @param {Response} response Fetch response.
+ * @returns {Promise<unknown>} Parsed JSON.
+ */
+async function readJsonResponse(response) {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new ZentaoApiError("ZenTao API returned non-JSON response.", { statusCode: response.status, response: text.slice(0, 1000) });
+  }
+}