@xurenxiang1219/pingcode-mcp 0.3.1

package/dist/mcp/tools/ship-suite.js

@@ -0,0 +1,636 @@
+import * as z from "zod/v4";
+import { PingCodeError } from "../../pingcode/errors.js";
+import { contentHashSchema } from "../../domain/content-hash.js";
+import { requestHash as calculateRequestHash } from "../../write/plan.js";
+import { executeTool, requestIdForLog } from "../tool-runtime.js";
+import { paginationGuidance } from "../pagination-guidance.js";
+import { resolveCandidate } from "../reference-resolution.js";
+import { approvalTokenSchema, commitWithApproval, formatPreviewToolResult, formatWriteConfirmationMessage, formatWriteToolResult, requestClientWriteConfirmation, resolveCommitVerification, } from "../write-approval.js";
+const identifier = z.string().trim().min(1).max(200);
+const contentHash = contentHashSchema;
+const approvalContextId = z.string().uuid();
+const agentSessionId = z.string().trim().min(8).max(200).optional();
+const sourceReferenceSchema = z.object({
+    type: z.enum(["wiki", "task", "test_case", "spec", "plan", "code", "project", "ship_idea"]),
+    id: identifier,
+    url: z.url().optional().describe("来源可访问 URL；没有稳定 URL 时省略"),
+    content_hash: contentHash.optional(),
+}).strict();
+const suiteCreateFieldsSchema = z.union([
+    z.object({
+        product_id: identifier.describe("产品 ID；来自 pingcode_ship_product_list 或 Product Commit 返回结果"),
+        product_name: z.never().optional(),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: identifier.describe("父需求模块 ID；来自当前产品的 pingcode_ship_product_suite_list，名称入口使用 parent_name"),
+        parent_name: z.never().optional(),
+    }).strict(),
+    z.object({
+        product_id: identifier.describe("产品 ID；来自 pingcode_ship_product_list 或 Product Commit 返回结果"),
+        product_name: z.never().optional(),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: z.never().optional(),
+        parent_name: identifier.describe("可选父需求模块名称；Tool 会从当前产品模块列表解析唯一 ID"),
+    }).strict(),
+    z.object({
+        product_id: identifier.describe("产品 ID；来自 pingcode_ship_product_list 或 Product Commit 返回结果"),
+        product_name: z.never().optional(),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: z.never().optional(),
+        parent_name: z.never().optional(),
+    }).strict(),
+    z.object({
+        product_id: z.never().optional(),
+        product_name: identifier.describe("产品名称或标识；Tool 会从产品目录解析 product_id"),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: identifier.describe("父需求模块 ID；来自当前产品的 pingcode_ship_product_suite_list，名称入口使用 parent_name"),
+        parent_name: z.never().optional(),
+    }).strict(),
+    z.object({
+        product_id: z.never().optional(),
+        product_name: identifier.describe("产品名称或标识；Tool 会从产品目录解析 product_id"),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: z.never().optional(),
+        parent_name: identifier.describe("可选父需求模块名称；Tool 会从当前产品模块列表解析唯一 ID"),
+    }).strict(),
+    z.object({
+        product_id: z.never().optional(),
+        product_name: identifier.describe("产品名称或标识；Tool 会从产品目录解析 product_id"),
+        name: z.string().trim().min(1).max(200),
+        type: z.enum(["product", "module"]),
+        parent_id: z.never().optional(),
+        parent_name: z.never().optional(),
+    }).strict(),
+]);
+const suiteCreatePlanSchema = z.object({
+    plan_id: identifier.describe("需求模块创建计划 ID；Preview 与 Commit 必须完全相同"),
+    operations: z.array(z.object({
+        operation_id: identifier,
+        action: z.literal("create"),
+        fields: suiteCreateFieldsSchema,
+        source_references: z.array(sourceReferenceSchema).min(1).max(20).optional().describe("可选来源引用；省略时由 MCP 根据 plan_id 自动生成内部计划引用"),
+    }).strict()).length(1),
+}).strict();
+const suiteRemovePlanSchema = z.object({
+    plan_id: identifier.describe("需求模块移除计划 ID；Preview 与 Commit 必须完全相同"),
+    operations: z.array(z.object({
+        operation_id: identifier,
+        action: z.literal("delete"),
+        fields: z.union([
+            z.object({
+                product_id: identifier.describe("产品 ID；来自 pingcode_ship_product_list 或 Product Commit 返回结果"),
+                product_name: z.never().optional(),
+                suite_id: identifier.describe("需求模块 ID；来自当前产品的 pingcode_ship_product_suite_list"),
+                suite_name: z.never().optional(),
+            }).strict(),
+            z.object({
+                product_id: identifier.describe("产品 ID；来自 pingcode_ship_product_list 或 Product Commit 返回结果"),
+                product_name: z.never().optional(),
+                suite_id: z.never().optional(),
+                suite_name: identifier.describe("需求模块名称或标识；由当前产品模块目录解析"),
+            }).strict(),
+            z.object({
+                product_id: z.never().optional(),
+                product_name: identifier.describe("产品名称或标识；Tool 会从产品目录解析 product_id"),
+                suite_id: identifier.describe("需求模块 ID；来自当前产品的 pingcode_ship_product_suite_list"),
+                suite_name: z.never().optional(),
+            }).strict(),
+            z.object({
+                product_id: z.never().optional(),
+                product_name: identifier.describe("产品名称或标识；Tool 会从产品目录解析 product_id"),
+                suite_id: z.never().optional(),
+                suite_name: identifier.describe("需求模块名称或标识；由当前产品模块目录解析"),
+            }).strict(),
+        ]),
+        source_references: z.array(sourceReferenceSchema).min(1).max(20).optional().describe("可选来源引用；省略时由 MCP 根据 plan_id 自动生成内部计划引用"),
+    }).strict()).length(1),
+}).strict();
+function normalizeSuiteCreatePlan(input) {
+    return {
+        plan_id: input.plan_id,
+        operations: input.operations.map((operation) => ({
+            ...operation,
+            source_references: operation.source_references ?? [{ type: "plan", id: input.plan_id }],
+        })),
+    };
+}
+function normalizeSuiteRemovePlan(input) {
+    return {
+        plan_id: input.plan_id,
+        operations: input.operations.map((operation) => ({
+            ...operation,
+            source_references: operation.source_references ?? [{ type: "plan", id: input.plan_id }],
+        })),
+    };
+}
+const readAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export function registerShipSuiteTools(server, services, logger, runtime, writeApprovalMode) {
+    server.registerTool("pingcode_ship_product_suite_list", {
+        title: "列出 PingCode 产品需求模块",
+        description: "读取指定产品中的需求模块和子产品结构。此 Tool 只读，不展示原始 JSON。",
+        inputSchema: {
+            product_id: identifier.optional().describe("产品 ID；必须来自 pingcode_ship_product_list 或 Product Commit 返回结果；缺少时先调用 pingcode_ship_product_list"),
+            page_index: z.number().int().min(0).optional(),
+            page_size: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_list", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { resourceId: input.product_id ?? "" }, async () => {
+        if (input.product_id === undefined) {
+            throw new PingCodeError("缺少 product_id；请先调用 pingcode_ship_product_list 获取产品候选并等待用户选择", "BAD_REQUEST");
+        }
+        const page = await services.getShipSource().listSuites(input.product_id, {
+            pageIndex: input.page_index,
+            pageSize: input.page_size,
+        });
+        return {
+            pageSize: page.page_size,
+            pageIndex: page.page_index,
+            total: page.total,
+            suites: page.values.map(mapSuite),
+        };
+    }, { formatResult: formatSuiteList }));
+    server.registerTool("pingcode_ship_product_suite_get", {
+        title: "读取 PingCode 产品需求模块",
+        description: "读取指定产品中的一个需求模块，返回产品、父模块和模块类型。此操作为只读。",
+        inputSchema: {
+            product_id: identifier.optional().describe("产品 ID；必须来自 pingcode_ship_product_list 或 Product Commit 返回结果；缺少时先调用 pingcode_ship_product_list"),
+            suite_id: identifier.optional().describe("需求模块 ID；必须来自 pingcode_ship_product_suite_list 或 Suite Commit 返回结果；缺少时先调用 pingcode_ship_product_suite_list"),
+        },
+        annotations: readAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_get", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { resourceId: input.suite_id ?? "", productId: input.product_id ?? "" }, async () => {
+        if (input.product_id === undefined) {
+            throw new PingCodeError("缺少 product_id；请先调用 pingcode_ship_product_list 获取产品候选并等待用户选择", "BAD_REQUEST");
+        }
+        if (input.suite_id === undefined) {
+            throw new PingCodeError("缺少 suite_id；请先调用 pingcode_ship_product_suite_list 获取需求模块候选并等待用户选择", "BAD_REQUEST");
+        }
+        return mapSuite(await services.getShipSource().getSuite(input.product_id, input.suite_id));
+    }, { formatResult: formatSuite }));
+    server.registerTool("pingcode_ship_product_suite_create_preview", {
+        title: "预览创建 PingCode 产品需求模块",
+        description: "预览在指定产品中创建一个需求模块，不写入 PingCode。name 和 type 必填；product_id 与 product_name 必须二选一，正常用户流程优先传 product_name。用户未主动指定产品时，先调用 pingcode_project_context_get；上下文中的 Ship 产品只能作为候选展示并询问是否复用，用户同意后才使用，否则调用 pingcode_ship_product_list。可选父模块使用 parent_name，省略表示产品根层；Tool 会从当前产品模块列表解析并验证 ID，找不到时返回候选，用户无需输入 ID。source_references 可省略，省略时由 MCP 根据 plan_id 自动生成内部计划引用。会检查产品、父模块归属和同层名称冲突。不得在正常用户回复中展示内部 hash、Approval Context、会话绑定、evidence 或幂等字段。",
+        inputSchema: {
+            ...suiteCreatePlanSchema.shape,
+            plan_id: suiteCreatePlanSchema.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: suiteCreatePlanSchema.shape.operations.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_create_preview", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id ?? "" }, () => {
+        if (input.plan_id === undefined || input.operations === undefined) {
+            throw new PingCodeError("缺少 plan_id 或 operations；请补充需求模块创建计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewSuiteCreation({ plan_id: input.plan_id, operations: input.operations }, services, runtime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_ship_product_suite_create_commit", {
+        title: "提交创建 PingCode 产品需求模块",
+        description: "依已核准的 Preview 在产品中创建需求模块。Commit 必须原样复用 Preview 计划；创建后 MCP 会使用模块详情接口回读确认。",
+        inputSchema: {
+            ...suiteCreatePlanSchema.shape,
+            agent_session_id: agentSessionId,
+            preview_id: approvalContextId.optional().describe("可选。省略时 Server 依相同 plan_id 与 operations 自动匹配刚才的 Preview"),
+            approval_context_id: approvalContextId.optional().describe("已弃用，等同 preview_id；新调用只传 preview_id"),
+            approval_token: approvalTokenSchema(writeApprovalMode),
+            idempotency_key: identifier.min(16).max(200).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_create_commit", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id }, async () => {
+        runtime.assertMcpWriteScope(extra.authInfo?.scopes);
+        const verification = await resolveCommitVerification(runtime, {
+            previewId: input.preview_id,
+            approvalContextId: input.approval_context_id,
+            idempotencyKey: input.idempotency_key,
+            requestHash: calculateRequestHash({ plan_id: input.plan_id, operations: input.operations }),
+            agentSessionId: input.agent_session_id,
+            authInfo: extra.authInfo,
+        }, "ship_suite");
+        const resolvedInput = {
+            ...input,
+            request_hash: verification.requestHash,
+            approval_context_id: verification.approvalContextId,
+            session_binding: verification.sessionBinding,
+            evidence_hash: verification.evidenceHash,
+            idempotency_key: verification.idempotencyKey,
+        };
+        const prepared = await prepareSuiteCreation(normalizeSuiteCreatePlan(resolvedInput).operations[0], services);
+        await requestClientWriteConfirmation(server, logger, writeApprovalMode, input.approval_token, formatSuiteCreationConfirmation(prepared), runtime.requiresConfirmation(["create"]));
+        return commitSuiteCreation(resolvedInput, prepared, services, runtime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+    server.registerTool("pingcode_ship_product_suite_remove_preview", {
+        title: "预览移除 PingCode 产品需求模块",
+        description: "预览从产品中移除一个需求模块，不写入 PingCode。每个 operations 元素必须是 JSON 对象；fields 必须是 {product_id, suite_id} 或对应的名称引用对象，不能把 fields 序列化成字符串。source_references 是 operation 内与 fields 同级的必填数组，不放在 fields 或计划顶层。官方接口会同时删除该模块的所有子模块；MCP 不会调用任何需求 Idea 删除接口。不得在正常用户回复中展示内部 hash、Approval Context、会话绑定、evidence 或幂等字段。",
+        inputSchema: {
+            ...suiteRemovePlanSchema.shape,
+            plan_id: suiteRemovePlanSchema.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: suiteRemovePlanSchema.shape.operations.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_remove_preview", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id ?? "" }, () => {
+        if (input.plan_id === undefined || input.operations === undefined) {
+            throw new PingCodeError("缺少 plan_id 或 operations；请补充需求模块移除计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewSuiteRemoval({ plan_id: input.plan_id, operations: input.operations }, services, runtime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_ship_product_suite_remove_commit", {
+        title: "提交移除 PingCode 产品需求模块",
+        description: "依已核准的 Preview 从产品中移除需求模块及其所有子模块。Commit 必须原样复用 Preview 计划；删除后 MCP 会逐一回读确认目标模块及已发现的子模块不再存在。",
+        inputSchema: {
+            ...suiteRemovePlanSchema.shape,
+            agent_session_id: agentSessionId,
+            preview_id: approvalContextId.optional().describe("可选。省略时 Server 依相同 plan_id 与 operations 自动匹配刚才的 Preview，并据此恢复 request hash、evidence hash、session binding 和幂等边界；仅当客户端确实读到 Preview 的 approvalContextId 时才需要传入"),
+            approval_context_id: approvalContextId.optional().describe("已弃用，等同 preview_id；新调用只传 preview_id"),
+            approval_token: approvalTokenSchema(writeApprovalMode),
+            idempotency_key: identifier.min(16).max(200).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_suite_remove_commit", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id }, async () => {
+        runtime.assertMcpWriteScope(extra.authInfo?.scopes);
+        const verification = await resolveCommitVerification(runtime, {
+            previewId: input.preview_id,
+            approvalContextId: input.approval_context_id,
+            idempotencyKey: input.idempotency_key,
+            requestHash: calculateRequestHash({ plan_id: input.plan_id, operations: input.operations }),
+            agentSessionId: input.agent_session_id,
+            authInfo: extra.authInfo,
+        }, "ship_suite");
+        const resolvedInput = {
+            ...input,
+            request_hash: verification.requestHash,
+            approval_context_id: verification.approvalContextId,
+            session_binding: verification.sessionBinding,
+            evidence_hash: verification.evidenceHash,
+            idempotency_key: verification.idempotencyKey,
+        };
+        const prepared = await prepareSuiteRemoval(normalizeSuiteRemovePlan(resolvedInput).operations[0], services);
+        await requestClientWriteConfirmation(server, logger, writeApprovalMode, input.approval_token, formatSuiteRemovalConfirmation(prepared), runtime.requiresConfirmation(["delete"]));
+        return commitSuiteRemoval(resolvedInput, prepared, services, runtime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+}
+async function previewSuiteCreation(input, services, runtime, agentSessionIdValue, authInfo) {
+    const normalizedInput = normalizeSuiteCreatePlan(input);
+    const operation = normalizedInput.operations[0];
+    if (!operation) {
+        throw new PingCodeError("需求模块创建计划不能为空", "BAD_REQUEST");
+    }
+    const prepared = await prepareSuiteCreation(operation, services);
+    const displayOperation = suiteCreationDisplayOperation(prepared);
+    const plan = normalizedInput;
+    const requestHash = calculateRequestHash(plan);
+    const evidenceHash = calculateRequestHash({ planId: input.plan_id, requestHash, operations: [displayOperation] });
+    const context = await runtime.createApprovalContext({
+        resourceType: "ship_suite",
+        requestHash,
+        evidenceHash,
+        ...(agentSessionIdValue === undefined ? {} : { agentSessionId: agentSessionIdValue }),
+        ...(authInfo === undefined ? {} : { authInfo }),
+    });
+    return {
+        planId: input.plan_id,
+        requestHash,
+        approvalContextId: context.approvalContextId,
+        sessionBinding: context.sessionBinding,
+        evidenceHash,
+        approvalExpiresAt: context.expiresAt,
+        counts: { creates: 1, updates: 0, relations: 0 },
+        operations: [displayOperation],
+    };
+}
+async function commitSuiteCreation(input, prepared, services, runtime, writeApprovalMode, authInfo) {
+    const plan = normalizeSuiteCreatePlan(input);
+    if (calculateRequestHash(plan) !== input.request_hash) {
+        throw new PingCodeError("Commit 内容与需求模块创建 Preview request hash 不一致", "CONFLICT");
+    }
+    const displayOperation = suiteCreationDisplayOperation(prepared);
+    const evidenceHash = calculateRequestHash({
+        planId: input.plan_id,
+        requestHash: input.request_hash,
+        operations: [displayOperation],
+    });
+    if (evidenceHash !== input.evidence_hash) {
+        throw new PingCodeError("Commit 内容与需求模块创建 Preview evidence hash 不一致", "CONFLICT");
+    }
+    const committed = await commitWithApproval(runtime, writeApprovalMode, {
+        resourceType: "ship_suite",
+        requestHash: input.request_hash,
+        evidenceHash: input.evidence_hash,
+        approvalContextId: input.approval_context_id,
+        sessionBinding: input.session_binding,
+        ...(input.agent_session_id === undefined ? {} : { agentSessionId: input.agent_session_id }),
+        approvalToken: input.approval_token,
+        idempotencyKey: input.idempotency_key,
+        ...(authInfo === undefined ? {} : { authInfo }),
+        actions: ["create"],
+        action: async () => {
+            const created = await services.getShipSource().createSuite(prepared.product.id, toSuiteWriteFields(prepared.operation.fields, prepared.parentId));
+            const verified = await services.getShipSource().getSuite(prepared.product.id, created.id);
+            return {
+                planId: input.plan_id,
+                resources: [{
+                        operationId: prepared.operation.operation_id,
+                        action: "create",
+                        id: verified.id,
+                        title: `${verified.product.name} / ${verified.name}`,
+                        verified: true,
+                    }],
+            };
+        },
+    });
+    return {
+        ...committed.result,
+        replayed: committed.replayed,
+        approvedBy: committed.approval.approvedBy,
+        auditId: committed.auditId,
+    };
+}
+async function prepareSuiteCreation(operation, services) {
+    const productId = await resolveProductId(operation.fields.product_id, operation.fields.product_name, services);
+    const product = await services.getShipSource().getProduct(productId);
+    const allSuites = await listAllSuites(productId, services);
+    const parentId = resolveCandidate("父需求模块", operation.fields.parent_id, operation.fields.parent_name, allSuites.map((suite) => ({ id: suite.id, name: suite.name })));
+    const parent = parentId === undefined
+        ? null
+        : allSuites.find((suite) => suite.id === parentId) ?? await services.getShipSource().getSuite(productId, parentId);
+    if (parent !== null && parent.product.id !== product.id) {
+        throw new PingCodeError("需求模块父模块不属于指定产品，未执行写入", "CONFLICT");
+    }
+    if (allSuites.some((suite) => suite.name === operation.fields.name && (suite.parent?.id ?? null) === (parent?.id ?? null))) {
+        throw new PingCodeError("同一产品层级下已存在同名需求模块", "CONFLICT");
+    }
+    return { product, parent, parentId, operation: { ...operation, fields: { ...operation.fields, product_id: productId, product_name: undefined } } };
+}
+function toSuiteWriteFields(fields, parentId) {
+    return {
+        name: fields.name,
+        type: fields.type,
+        ...(parentId === undefined ? {} : { parentId }),
+    };
+}
+function suiteCreationDisplayOperation(prepared) {
+    return {
+        operationId: prepared.operation.operation_id,
+        action: "create",
+        targetId: null,
+        changes: {
+            product: { before: null, after: productLabel(prepared.product) },
+            name: { before: null, after: prepared.operation.fields.name },
+            type: { before: null, after: prepared.operation.fields.type },
+            parent: { before: null, after: prepared.parent ? suiteLabel(prepared.parent) : "产品根层" },
+        },
+        sourceReferences: prepared.operation.source_references,
+    };
+}
+function formatSuiteCreationConfirmation(prepared) {
+    return formatWriteConfirmationMessage("即将在 PingCode 产品中创建需求模块", [
+        `产品：${productLabel(prepared.product)}`,
+        `模块：${prepared.operation.fields.name} (${prepared.operation.fields.type})`,
+        `父模块：${prepared.parent ? suiteLabel(prepared.parent) : "产品根层"}`,
+    ]);
+}
+async function previewSuiteRemoval(input, services, runtime, agentSessionIdValue, authInfo) {
+    const normalizedInput = normalizeSuiteRemovePlan(input);
+    const operation = normalizedInput.operations[0];
+    if (!operation) {
+        throw new PingCodeError("需求模块移除计划不能为空", "BAD_REQUEST");
+    }
+    const prepared = await prepareSuiteRemoval(operation, services);
+    const displayOperation = suiteRemovalDisplayOperation(prepared);
+    const plan = normalizedInput;
+    const requestHash = calculateRequestHash(plan);
+    const evidenceHash = calculateRequestHash({ planId: input.plan_id, requestHash, operations: [displayOperation] });
+    const context = await runtime.createApprovalContext({
+        resourceType: "ship_suite",
+        requestHash,
+        evidenceHash,
+        ...(agentSessionIdValue === undefined ? {} : { agentSessionId: agentSessionIdValue }),
+        ...(authInfo === undefined ? {} : { authInfo }),
+    });
+    return {
+        planId: input.plan_id,
+        requestHash,
+        approvalContextId: context.approvalContextId,
+        sessionBinding: context.sessionBinding,
+        evidenceHash,
+        approvalExpiresAt: context.expiresAt,
+        counts: { creates: 0, updates: 0, relations: 0 },
+        warnings: [
+            `官方接口会同时删除 ${prepared.descendants.length} 个已发现的子模块`,
+            "此 Tool 不会删除需求 Idea；需求在模块移除后的归属由 PingCode 产品规则处理",
+        ],
+        operations: [displayOperation],
+    };
+}
+async function commitSuiteRemoval(input, prepared, services, runtime, writeApprovalMode, authInfo) {
+    const plan = normalizeSuiteRemovePlan(input);
+    if (calculateRequestHash(plan) !== input.request_hash) {
+        throw new PingCodeError("Commit 内容与需求模块移除 Preview request hash 不一致", "CONFLICT");
+    }
+    const displayOperation = suiteRemovalDisplayOperation(prepared);
+    const evidenceHash = calculateRequestHash({
+        planId: input.plan_id,
+        requestHash: input.request_hash,
+        operations: [displayOperation],
+    });
+    if (evidenceHash !== input.evidence_hash) {
+        throw new PingCodeError("Commit 内容与需求模块移除 Preview evidence hash 不一致", "CONFLICT");
+    }
+    const committed = await commitWithApproval(runtime, writeApprovalMode, {
+        resourceType: "ship_suite",
+        requestHash: input.request_hash,
+        evidenceHash: input.evidence_hash,
+        approvalContextId: input.approval_context_id,
+        sessionBinding: input.session_binding,
+        ...(input.agent_session_id === undefined ? {} : { agentSessionId: input.agent_session_id }),
+        approvalToken: input.approval_token,
+        idempotencyKey: input.idempotency_key,
+        ...(authInfo === undefined ? {} : { authInfo }),
+        actions: ["delete"],
+        action: async () => {
+            await services.getShipSource().removeSuite(prepared.product.id, prepared.suite.id);
+            await verifySuitesRemoved(prepared, services);
+            return {
+                planId: input.plan_id,
+                resources: [{
+                        operationId: prepared.operation.operation_id,
+                        action: "delete",
+                        id: prepared.suite.id,
+                        title: `${prepared.product.name} / ${prepared.suite.name}`,
+                        verified: true,
+                    }],
+            };
+        },
+    });
+    return {
+        ...committed.result,
+        replayed: committed.replayed,
+        approvedBy: committed.approval.approvedBy,
+        auditId: committed.auditId,
+    };
+}
+async function prepareSuiteRemoval(operation, services) {
+    const productId = await resolveProductId(operation.fields.product_id, operation.fields.product_name, services);
+    const suiteId = operation.fields.suite_id ?? (await resolveCandidate("需求模块", undefined, operation.fields.suite_name, await listAllSuites(productId, services).then((values) => values.map((suite) => ({ id: suite.id, name: suite.name })))));
+    if (suiteId === undefined)
+        throw new PingCodeError("需求模块尚未解析", "BAD_REQUEST");
+    const [product, suite, allSuites] = await Promise.all([
+        services.getShipSource().getProduct(productId),
+        services.getShipSource().getSuite(productId, suiteId),
+        listAllSuites(productId, services),
+    ]);
+    if (suite.product.id !== product.id) {
+        throw new PingCodeError("需求模块不属于 Preview 指定的产品，未执行写入", "CONFLICT");
+    }
+    return { product, suite, descendants: collectDescendants(suite.id, allSuites), operation: { ...operation, fields: { ...operation.fields, product_id: productId, product_name: undefined, suite_id: suiteId, suite_name: undefined } } };
+}
+async function resolveProductId(value, name, services) {
+    if (value !== undefined)
+        return (await services.getShipSource().getProduct(value)).id;
+    if (name === undefined)
+        throw new PingCodeError("产品缺少名称或 ID", "BAD_REQUEST");
+    const values = [];
+    for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+        const page = await services.getShipSource().listProducts({ pageIndex, pageSize: 100 });
+        values.push(...page.values.map((product) => ({ id: product.id, name: product.name, identifier: product.identifier })));
+        if (values.length >= page.total || page.values.length === 0)
+            break;
+    }
+    const id = resolveCandidate("产品", undefined, name, values);
+    if (id === undefined)
+        throw new PingCodeError("产品尚未解析", "BAD_REQUEST");
+    return id;
+}
+async function listAllSuites(productId, services) {
+    const values = [];
+    let pageIndex = 0;
+    for (let pageCount = 0; pageCount < 100; pageCount += 1) {
+        const page = await services.getShipSource().listSuites(productId, { pageIndex, pageSize: 100 });
+        values.push(...page.values);
+        if (values.length >= page.total || page.values.length === 0) {
+            return values;
+        }
+        pageIndex = page.page_index + 1;
+    }
+    throw new PingCodeError("需求模块数量超过安全扫描上限，无法完整确认级联删除范围", "RESPONSE_TOO_LARGE");
+}
+function collectDescendants(parentId, suites) {
+    const descendants = [];
+    const pending = [parentId];
+    const visited = new Set();
+    while (pending.length > 0) {
+        const current = pending.shift();
+        if (visited.has(current)) {
+            continue;
+        }
+        visited.add(current);
+        for (const suite of suites) {
+            if (suite.parent?.id === current && suite.id !== parentId) {
+                descendants.push(suite);
+                pending.push(suite.id);
+            }
+        }
+    }
+    return descendants;
+}
+async function verifySuitesRemoved(prepared, services) {
+    for (const suite of [prepared.suite, ...prepared.descendants]) {
+        try {
+            await services.getShipSource().getSuite(prepared.product.id, suite.id);
+        }
+        catch (error) {
+            if (error instanceof PingCodeError && error.code === "NOT_FOUND") {
+                continue;
+            }
+            // 部分 PingCode 租户对已删除需求模块的详情请求返回 BAD_REQUEST。
+            // 通过只读列表核对目标及子模块是否仍存在，不重试 DELETE。
+            if (error instanceof PingCodeError && error.code === "BAD_REQUEST") {
+                try {
+                    const suites = await listAllSuites(prepared.product.id, services);
+                    if (!suites.some((candidate) => candidate.id === suite.id)) {
+                        continue;
+                    }
+                    throw new PingCodeError(`需求模块 ${suite.name} 的删除请求已发送，但列表回读时仍存在；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN");
+                }
+                catch (listError) {
+                    if (listError instanceof PingCodeError && listError.code === "WRITE_OUTCOME_UNKNOWN") {
+                        throw listError;
+                    }
+                    throw new PingCodeError(`需求模块 ${suite.name} 的删除请求已发送，但 MCP 无法通过列表确认结果；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: listError });
+                }
+            }
+            throw new PingCodeError(`需求模块 ${suite.name} 的删除请求已发送，但 MCP 无法确认结果；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: error });
+        }
+        throw new PingCodeError(`需求模块 ${suite.name} 的删除请求已发送，但回读时仍存在；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN");
+    }
+}
+function suiteRemovalDisplayOperation(prepared) {
+    return {
+        operationId: prepared.operation.operation_id,
+        action: "delete",
+        targetId: prepared.suite.id,
+        changes: {
+            product: { before: productLabel(prepared.product), after: productLabel(prepared.product) },
+            suite: { before: suiteLabel(prepared.suite), after: null },
+            child_modules: { before: prepared.descendants.map(suiteLabel), after: [] },
+        },
+        sourceReferences: prepared.operation.source_references,
+    };
+}
+function mapSuite(suite) {
+    return {
+        id: suite.id,
+        productId: suite.product.id,
+        productIdentifier: suite.product.identifier,
+        productName: suite.product.name,
+        name: suite.name,
+        type: suite.type,
+        parentId: suite.parent?.id ?? null,
+        parentName: suite.parent?.name ?? null,
+    };
+}
+function formatSuiteList(result) {
+    const lines = [`PingCode 产品需求模块：${result.total} 个`];
+    for (const suite of result.suites) {
+        lines.push(`- ${suite.name} (${suite.type}) [${suite.id}]${suite.parentName ? `；父模块：${suite.parentName}` : ""}`);
+    }
+    lines.push(...paginationGuidance({
+        pageIndex: result.pageIndex ?? 0,
+        pageSize: result.pageSize ?? Math.max(result.suites.length, 1),
+        total: result.total,
+        returned: result.suites.length,
+        searchable: false,
+    }));
+    return lines.join("\n");
+}
+function formatSuite(suite) {
+    return [
+        "已读取 PingCode 产品需求模块",
+        `- 产品：${suite.productName} (${suite.productIdentifier})`,
+        `- 模块：${suite.name} (${suite.type})`,
+        `- 模块 ID：${suite.id}`,
+        `- 父模块：${suite.parentName ?? "无"}${suite.parentId ? ` [${suite.parentId}]` : ""}`,
+    ].join("\n");
+}
+function formatSuiteRemovalConfirmation(prepared) {
+    return formatWriteConfirmationMessage("即将在 PingCode 产品中移除需求模块", [
+        `产品：${productLabel(prepared.product)}`,
+        `需求模块：${suiteLabel(prepared.suite)}`,
+        `同时移除的子模块：${prepared.descendants.length} 个${prepared.descendants.length > 0 ? `（${prepared.descendants.map((suite) => suite.name).join("、")}）` : ""}`,
+        "需求 Idea：此 Tool 不执行删除",
+    ], "确认后将立即移除该模块及其子模块，请核对以上范围和 Preview 差异。");
+}
+function productLabel(product) {
+    return `${product.name} (${product.identifier})`;
+}
+function suiteLabel(suite) {
+    return `${suite.name} (${suite.type})`;
+}
+//# sourceMappingURL=ship-suite.js.map