@xurenxiang1219/pingcode-mcp 0.3.1

package/dist/mcp/tools/ship.js

@@ -0,0 +1,617 @@
+import * as z from "zod/v4";
+import { PingCodeError } from "../../pingcode/errors.js";
+import { contentHashSchema } from "../../domain/content-hash.js";
+import { requestHash } from "../../write/plan.js";
+import { executeTool, requestIdForLog } from "../tool-runtime.js";
+import { loadWithKeywordFallback, paginationGuidance } from "../pagination-guidance.js";
+import { resolveCandidate, resolveTeamReference, resolveUserReference } from "../reference-resolution.js";
+import { approvalTokenSchema, commitWithApproval, formatPreviewToolResult, formatWriteConfirmationMessage, formatWriteToolResult, requestClientWriteConfirmation, resolveCommitVerification, } from "../write-approval.js";
+const readOnlyAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const previewAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const commitAnnotations = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+const identifier = z.string().trim().min(1).max(200);
+const contentHash = contentHashSchema;
+const sourceReference = z.object({
+    type: z.enum(["wiki", "task", "test_case", "spec", "plan", "code", "ship_idea"]),
+    id: identifier,
+    url: z.url().optional(),
+    content_hash: contentHash.optional(),
+});
+const agentSessionId = z.string().trim().min(8).max(200).optional();
+const approvalContextId = z.string().uuid();
+const listInput = {
+    keywords: z.string().trim().min(1).max(200).optional(),
+    page_index: z.number().int().min(0).max(100000).optional(),
+    page_size: z.number().int().min(1).max(100).optional(),
+};
+const ideaListInput = {
+    ...listInput,
+    product_id: identifier.optional().describe("按产品 ID 筛选需求"),
+};
+const productMemberSchema = z
+    .object({
+    id: identifier.optional().describe("成员用户/团队 ID；来自 pingcode_user_list/search 或团队目录，名称入口使用 name"),
+    name: identifier.optional().describe("成员名称；Tool 会按 type 从用户或团队目录解析"),
+    type: z.enum(["user", "user_group"]),
+})
+    .strict()
+    .refine((value) => value.id !== undefined || value.name !== undefined, "成员必须提供 id 或 name")
+    .refine((value) => value.id === undefined || value.name === undefined, "成员 id 与 name 不得同时提供");
+const productCreateFields = z
+    .object({
+    scope_type: z.enum(["organization", "user_group"]).optional(),
+    scope_id: identifier.optional().describe("产品所属团队 ID；仅在 scope_type=user_group 时有效，并由 Tool 从团队目录验证"),
+    scope_name: identifier.optional().describe("产品所属团队名称；仅在 scope_type=user_group 时有效，Tool 会解析为 scope_id"),
+    name: z.string().trim().min(1).max(32),
+    visibility: z.enum(["public", "private"]).optional(),
+    identifier: z
+        .string()
+        .trim()
+        .min(1)
+        .max(15)
+        .regex(/^[A-Z0-9_-]+$/),
+    description: z.string().optional(),
+    members: z.array(productMemberSchema).optional(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    if (value.scope_type === "user_group" && value.scope_id === undefined && value.scope_name === undefined) {
+        context.addIssue({ code: "custom", path: ["scope_id"], message: "scope_type=user_group 时必须提供 scope_id 或 scope_name" });
+    }
+    if (value.scope_type !== "user_group" && (value.scope_id !== undefined || value.scope_name !== undefined)) {
+        context.addIssue({ code: "custom", path: [value.scope_name !== undefined ? "scope_name" : "scope_id"], message: "scope_id/scope_name 仅在 scope_type=user_group 时有效" });
+    }
+    if (value.scope_id !== undefined && value.scope_name !== undefined) {
+        context.addIssue({ code: "custom", path: ["scope_name"], message: "scope_id 与 scope_name 不得同时提供" });
+    }
+});
+const productUpdateFields = z
+    .object({
+    name: z.string().trim().min(1).max(32).optional(),
+    identifier: z.string().trim().min(1).max(15).regex(/^[A-Z0-9_-]+$/).optional(),
+    description: z.string().optional(),
+})
+    .strict()
+    .refine((value) => Object.values(value).some((item) => item !== undefined), "至少提供一個更新欄位");
+const ideaCreateFields = z
+    .object({
+    product_id: identifier.optional().describe("兼容字段；由 Tool 从产品目录验证"),
+    product_name: identifier.optional().describe("产品名称或标识；Tool 会从 Ship 产品目录解析 product_id"),
+    title: z.string().trim().min(1).max(255),
+    assignee_id: identifier.optional().describe("需求负责人用户 ID；来自 pingcode_user_list/search，名称入口使用 assignee_name"),
+    assignee_name: identifier.optional().describe("负责人姓名；Tool 会通过用户目录解析 assignee_id"),
+    description: z.string().optional(),
+    suite_id: identifier.optional().describe("需求模块 ID；来自指定产品的 pingcode_ship_product_suite_list，名称入口使用 suite_name"),
+    suite_name: identifier.optional().describe("需求模块名称；Tool 会从指定产品的模块目录解析 suite_id"),
+    priority_id: identifier.optional().describe("产品级需求优先级 ID；来自指定产品优先级目录，名称入口使用 priority_name"),
+    priority_name: identifier.optional().describe("产品级需求优先级名称；Tool 只从指定产品的需求优先级目录解析（通常为 P0-P4），不得使用工作项的优先级名称"),
+    properties: z.record(z.string().trim().min(1).max(100), z.unknown()).optional(),
+})
+    .strict()
+    .refine((value) => value.product_id !== undefined || value.product_name !== undefined, "product_id 或 product_name 至少提供一个")
+    .refine((value) => value.product_id === undefined || value.product_name === undefined, "product_id 与 product_name 不得同时提供")
+    .superRefine((value, context) => {
+    for (const [idKey, nameKey] of [["assignee_id", "assignee_name"], ["suite_id", "suite_name"], ["priority_id", "priority_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined)
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+    }
+});
+const ideaUpdateFields = z
+    .object({
+    title: z.string().trim().min(1).max(255).optional(),
+    assignee_id: identifier.optional().describe("需求负责人用户 ID；来自 pingcode_user_list/search，名称入口使用 assignee_name"),
+    assignee_name: identifier.optional(),
+    description: z.string().optional(),
+    suite_id: identifier.optional().describe("需求模块 ID；来自指定产品的 pingcode_ship_product_suite_list，名称入口使用 suite_name"),
+    suite_name: identifier.optional(),
+    priority_id: identifier.optional().describe("产品级需求优先级 ID；来自指定产品优先级目录，名称入口使用 priority_name"),
+    priority_name: identifier.optional().describe("产品级需求优先级名称；更新时只接受指定产品目录返回的名称，通常为 P0-P4"),
+    properties: z.record(z.string().trim().min(1).max(100), z.unknown()).optional(),
+})
+    .strict()
+    .refine((value) => Object.values(value).some((item) => item !== undefined), "至少提供一個更新欄位")
+    .superRefine((value, context) => {
+    for (const [idKey, nameKey] of [["assignee_id", "assignee_name"], ["suite_id", "suite_name"], ["priority_id", "priority_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined)
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+    }
+});
+const productOperation = z.discriminatedUnion("action", [
+    z.object({
+        operation_id: identifier,
+        action: z.literal("create"),
+        fields: productCreateFields,
+        source_references: z.array(sourceReference).min(1).max(20).describe("本操作的来源引用；必须放在 operations 的每个元素内，不能放在计划顶层"),
+    }),
+    z.object({
+        operation_id: identifier,
+        action: z.literal("update"),
+        target_id: identifier.describe("待更新 Product/Idea 的内部 ID；来自对应列表或详情 Tool"),
+        expected_content_hash: contentHash,
+        fields: productUpdateFields,
+        source_references: z.array(sourceReference).min(1).max(20).describe("本操作的来源引用；必须放在 operations 的每个元素内，不能放在计划顶层"),
+    }),
+]);
+const ideaOperation = z.discriminatedUnion("action", [
+    z.object({
+        operation_id: identifier,
+        action: z.literal("create"),
+        fields: ideaCreateFields,
+        source_references: z.array(sourceReference).min(1).max(20).describe("本操作的来源引用；必须放在 operations 的每个元素内，不能放在计划顶层"),
+    }),
+    z.object({
+        operation_id: identifier,
+        action: z.literal("update"),
+        target_id: identifier.describe("待更新 Product/Idea 的内部 ID；来自对应列表或详情 Tool"),
+        expected_content_hash: contentHash,
+        fields: ideaUpdateFields,
+        source_references: z.array(sourceReference).min(1).max(20).describe("本操作的来源引用；必须放在 operations 的每个元素内，不能放在计划顶层"),
+    }),
+]);
+const productPlan = z.object({ plan_id: identifier.describe("Ship Product 同步计划 ID；由 Agent 生成，Preview 与 Commit 必须完全相同"), operations: z.array(productOperation).min(1).max(50).describe("产品操作数组；每个操作必须包含自己的 source_references") });
+const ideaPlan = z.object({ plan_id: identifier.describe("Ship Idea 同步计划 ID；由 Agent 生成，Preview 与 Commit 必须完全相同"), operations: z.array(ideaOperation).min(1).max(50).describe("需求操作数组；每个操作必须包含自己的 source_references") });
+export function registerShipTools(server, services, logger, writeRuntime, writeApprovalMode) {
+    server.registerTool("pingcode_ship_product_list", {
+        title: "列出 PingCode Ship 产品",
+        description: "读取当前凭据可访问的 Ship 产品列表。",
+        inputSchema: listInput,
+        annotations: readOnlyAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_list", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), {}, async () => {
+        const loaded = await loadWithKeywordFallback(input.keywords, (keywords, resetPage) => services.getShipSource().listProducts({ keywords, pageIndex: resetPage ? 0 : input.page_index, pageSize: input.page_size }));
+        const result = loaded.page;
+        return { pageSize: result.page_size, pageIndex: result.page_index, total: result.total, products: result.values, keywords: loaded.keywords, fallbackFromKeywords: loaded.fallbackFromKeywords };
+    }, { formatResult: (result) => formatShipListResult("Ship 产品", result.products, result.total, result.pageIndex, result.pageSize, result.keywords, result.fallbackFromKeywords) }));
+    server.registerTool("pingcode_ship_product_get", {
+        title: "读取 PingCode Ship 产品",
+        description: "读取一个 Ship 产品及其官方返回字段。",
+        inputSchema: { product_id: identifier.optional().describe("Ship Product 内部 ID；必须来自 pingcode_ship_product_list 或 Product Commit 返回结果；缺少时先调用 pingcode_ship_product_list") },
+        annotations: readOnlyAnnotations,
+    }, async ({ product_id }, extra) => executeTool(logger, "pingcode_ship_product_get", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { productId: product_id ?? "" }, async () => {
+        if (product_id === undefined) {
+            throw new PingCodeError("缺少 product_id；请先调用 pingcode_ship_product_list 获取产品候选并等待用户选择", "BAD_REQUEST");
+        }
+        const product = await services.getShipSource().getProduct(product_id);
+        return { product, source: sourceMeta(product) };
+    }, { formatResult: (result) => formatShipResourceResult("Ship 产品", result.product, result.source) }));
+    server.registerTool("pingcode_ship_idea_list", {
+        title: "列出 PingCode Ship 需求",
+        description: "读取当前凭据可访问的 Ship 需求（Idea）列表。",
+        inputSchema: ideaListInput,
+        annotations: readOnlyAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_idea_list", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), {}, async () => {
+        const loaded = await loadWithKeywordFallback(input.keywords, (keywords, resetPage) => services.getShipSource().listIdeas({ keywords, productId: input.product_id, pageIndex: resetPage ? 0 : input.page_index, pageSize: input.page_size }));
+        const result = loaded.page;
+        return { pageSize: result.page_size, pageIndex: result.page_index, total: result.total, ideas: result.values, keywords: loaded.keywords, fallbackFromKeywords: loaded.fallbackFromKeywords };
+    }, { formatResult: (result) => formatShipListResult("Ship 需求", result.ideas, result.total, result.pageIndex, result.pageSize, result.keywords, result.fallbackFromKeywords) }));
+    server.registerTool("pingcode_ship_product_idea_list", {
+        title: "列出 PingCode 产品需求",
+        description: "读取指定 Ship 产品下的需求（Idea）列表。此 Tool 只读，不创建、删除或修改需求。",
+        inputSchema: {
+            product_id: identifier.optional().describe("产品 ID；必须来自 pingcode_ship_product_list 或 Product Commit 返回结果；缺少时先调用 pingcode_ship_product_list"),
+            keywords: z.string().trim().min(1).max(200).optional(),
+            page_index: z.number().int().min(0).max(100000).optional(),
+            page_size: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readOnlyAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_idea_list", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { productId: input.product_id ?? "" }, async () => {
+        if (input.product_id === undefined) {
+            throw new PingCodeError("缺少 product_id；请先调用 pingcode_ship_product_list 获取产品候选并等待用户选择", "BAD_REQUEST");
+        }
+        const loaded = await loadWithKeywordFallback(input.keywords, (keywords, resetPage) => services.getShipSource().listIdeas({ productId: input.product_id, keywords, pageIndex: resetPage ? 0 : input.page_index, pageSize: input.page_size }));
+        const result = loaded.page;
+        return { pageSize: result.page_size, pageIndex: result.page_index, total: result.total, ideas: result.values, keywords: loaded.keywords, fallbackFromKeywords: loaded.fallbackFromKeywords };
+    }, { formatResult: (result) => formatShipListResult("产品需求", result.ideas, result.total, result.pageIndex, result.pageSize, result.keywords, result.fallbackFromKeywords) }));
+    server.registerTool("pingcode_ship_idea_get", {
+        title: "读取 PingCode Ship 需求",
+        description: "读取一个 Ship 需求（Idea）及其官方返回字段。",
+        inputSchema: { idea_id: identifier.optional().describe("Ship Idea 内部 ID；必须来自 pingcode_ship_idea_list、pingcode_ship_product_idea_list 或 Idea Commit 返回结果；缺少时先调用对应列表 Tool") },
+        annotations: readOnlyAnnotations,
+    }, async ({ idea_id }, extra) => executeTool(logger, "pingcode_ship_idea_get", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { ideaId: idea_id ?? "" }, async () => {
+        if (idea_id === undefined) {
+            throw new PingCodeError("缺少 idea_id；请先调用 pingcode_ship_idea_list 或 pingcode_ship_product_idea_list 获取需求候选并等待用户选择", "BAD_REQUEST");
+        }
+        const idea = await services.getShipSource().getIdea(idea_id);
+        return { idea, source: sourceMeta(idea) };
+    }, { formatResult: (result) => formatShipResourceResult("Ship 需求", result.idea, result.source) }));
+    registerProductSyncTools(server, services, logger, writeRuntime, writeApprovalMode);
+    registerIdeaSyncTools(server, services, logger, writeRuntime, writeApprovalMode);
+}
+function registerProductSyncTools(server, services, logger, runtime, writeApprovalMode) {
+    server.registerTool("pingcode_ship_product_sync_preview", {
+        title: "预览 PingCode Ship 产品同步",
+        description: "验证 Ship 产品创建／更新计划并返回差异，不写入 PingCode。创建的最小输入是 plan_id、operations[action=create]、fields.name、fields.identifier、fields.scope_type（可选）以及 operation 内的 source_references；scope_type=user_group 时还必须提供 scope_name 或 scope_id，正常流程使用 scope_name 由团队目录解析。每个 operations 元素必须是 JSON 对象；fields 必须是 JSON 对象而不是字符串，source_references 是 operation 内与 fields 同级的必填数组。正常用户回复只展示目标产品、操作、字段差异和警告；Commit 是否显示 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，不得先在聊天中重复询问。requestHash、approvalContextId、sessionBinding、evidenceHash、agent_session_id 和 idempotency_key 仅供 Agent 内部传递，不得在正常用户回复中展示或要求用户复制。Product 创建支持官方 endpoint 的 scope_type、scope_id、name、visibility、identifier、description 和 members；name 和 identifier 必填，scope_type=user_group 时必须提供并解析真实团队。",
+        inputSchema: {
+            ...productPlan.shape,
+            plan_id: productPlan.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: productPlan.shape.operations.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: previewAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_sync_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；请补充 Ship Product 同步计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewShipPlan("ship_product", { plan_id: input.plan_id, operations: input.operations }, services, runtime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_ship_product_sync_commit", {
+        title: "提交 PingCode Ship 产品同步",
+        description: "依已核准的 Preview 建立或更新 Ship 产品。Commit 必须原样复用 Preview 请求中的 plan_id 和 operations；不要复制 Preview 响应里的 camelCase operations 展示对象。产品创建成功并回读确认后，Agent 应询问用户是否将产品的 id、identifier、name 保存到当前工作区；只有用户明确同意才调用 pingcode_project_context_save。是否要求当前 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，并原样使用验证信息和唯一幂等键。",
+        inputSchema: commitInput(productPlan, writeApprovalMode),
+        annotations: commitAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_product_sync_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: requestHash({ plan_id: input.plan_id, operations: input.operations }), agentSessionId: input.agent_session_id, authInfo: extra.authInfo }, "ship_product");
+        const resolvedInput = { ...input, request_hash: verification.requestHash, approval_context_id: verification.approvalContextId, session_binding: verification.sessionBinding, evidence_hash: verification.evidenceHash, idempotency_key: verification.idempotencyKey };
+        await requestClientWriteConfirmation(server, logger, writeApprovalMode, input.approval_token, shipCommitConfirmationMessage("ship_product", resolvedInput), runtime.requiresConfirmation(input.operations.map((operation) => operation.action)));
+        return commitShipPlan("ship_product", resolvedInput, services, runtime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+}
+function registerIdeaSyncTools(server, services, logger, runtime, writeApprovalMode) {
+    server.registerTool("pingcode_ship_idea_sync_preview", {
+        title: "预览 PingCode Ship 需求同步",
+        description: "验证 Ship 需求（Idea）创建／更新计划并返回差异，不写入 PingCode。创建的最小输入是 plan_id、operations[action=create]、fields.title、fields.product_id 或 product_name（二选一）以及 operation 内的 source_references。用户未主动指定产品时，先调用 pingcode_project_context_get；上下文中的 Ship 产品只能作为候选展示并询问是否复用，用户同意后才传入 product_name 或 product_id；没有上下文或用户拒绝时调用 pingcode_ship_product_list。正常用户回复只展示目标产品、操作、字段差异和警告；Commit 是否显示 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，不得先在聊天中重复询问。requestHash、approvalContextId、sessionBinding、evidenceHash、agent_session_id 和 idempotency_key 仅供 Agent 内部传递，不得在正常用户回复中展示或要求用户复制。建立时 product_id/product_name 和 title 必填且不能同时提供。",
+        inputSchema: {
+            ...ideaPlan.shape,
+            plan_id: ideaPlan.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: ideaPlan.shape.operations.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: previewAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_idea_sync_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；请补充 Ship Idea 同步计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewShipPlan("ship_idea", { plan_id: input.plan_id, operations: input.operations }, services, runtime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_ship_idea_sync_commit", {
+        title: "提交 PingCode Ship 需求同步",
+        description: "依已核准的 Preview 建立或更新 Ship 需求（Idea）。Commit 必须原样复用 Preview 请求中的 plan_id 和 operations；不要复制 Preview 响应里的 camelCase operations 展示对象。是否要求当前 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，并原样使用验证信息和唯一幂等键。",
+        inputSchema: commitInput(ideaPlan, writeApprovalMode),
+        annotations: commitAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_ship_idea_sync_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: requestHash({ plan_id: input.plan_id, operations: input.operations }), agentSessionId: input.agent_session_id, authInfo: extra.authInfo }, "ship_idea");
+        const resolvedInput = { ...input, request_hash: verification.requestHash, approval_context_id: verification.approvalContextId, session_binding: verification.sessionBinding, evidence_hash: verification.evidenceHash, idempotency_key: verification.idempotencyKey };
+        await requestClientWriteConfirmation(server, logger, writeApprovalMode, input.approval_token, shipCommitConfirmationMessage("ship_idea", resolvedInput), runtime.requiresConfirmation(input.operations.map((operation) => operation.action)));
+        return commitShipPlan("ship_idea", resolvedInput, services, runtime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+}
+function commitInput(plan, writeApprovalMode) {
+    return {
+        ...plan.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: z.string().trim().min(16).max(200).optional(),
+    };
+}
+async function previewShipPlan(resourceType, input, services, runtime, agentSession, authInfo) {
+    const resolvedInput = await resolveShipPlanReferences(resourceType, input, services);
+    if (resourceType === "ship_product") {
+        await assertNoShipProductCreateConflict(resolvedInput, services);
+    }
+    const operations = [];
+    for (const operation of resolvedInput.operations) {
+        if (operation.action === "create") {
+            operations.push({ operationId: operation.operation_id, action: "create", targetId: null, changes: changesFromCreate(operation.fields), sourceReferences: operation.source_references });
+            continue;
+        }
+        const targetId = operation.target_id;
+        const expectedHash = operation.expected_content_hash;
+        if (!targetId || !expectedHash) {
+            throw new PingCodeError("Ship 更新操作缺少 target_id 或 expected_content_hash", "BAD_REQUEST");
+        }
+        const current = resourceType === "ship_product"
+            ? await services.getShipSource().getProduct(targetId)
+            : await services.getShipSource().getIdea(targetId);
+        assertContentHash(expectedHash, current);
+        operations.push({ operationId: operation.operation_id, action: "update", targetId, changes: selectedChanges(current, operation.fields), sourceReferences: operation.source_references });
+    }
+    const request = { plan_id: input.plan_id, operations: input.operations };
+    const evidence = requestHash(operations);
+    const approval = await runtime.createApprovalContext({ resourceType, requestHash: requestHash(request), evidenceHash: evidence, agentSessionId: agentSession, authInfo });
+    return { planId: input.plan_id, requestHash: requestHash(request), approvalContextId: approval.approvalContextId, sessionBinding: approval.sessionBinding, evidenceHash: evidence, approvalExpiresAt: approval.expiresAt, counts: { creates: input.operations.filter((item) => item.action === "create").length, updates: input.operations.filter((item) => item.action === "update").length, relations: 0 }, operations };
+}
+async function commitShipPlan(resourceType, input, services, runtime, writeApprovalMode, authInfo) {
+    const request = { plan_id: input.plan_id, operations: input.operations };
+    if (input.request_hash !== requestHash(request)) {
+        throw new PingCodeError("Ship Commit 的计划 Hash 与 Preview 不一致", "CONFLICT");
+    }
+    const resolvedInput = await resolveShipPlanReferences(resourceType, input, services);
+    const committed = await commitWithApproval(runtime, writeApprovalMode, { resourceType, requestHash: input.request_hash, evidenceHash: input.evidence_hash, approvalContextId: input.approval_context_id, sessionBinding: input.session_binding, agentSessionId: input.agent_session_id, approvalToken: input.approval_token, idempotencyKey: input.idempotency_key, authInfo, actions: input.operations.map((operation) => operation.action), action: async () => {
+            if (resourceType === "ship_product") {
+                await assertNoShipProductCreateConflict(resolvedInput, services);
+            }
+            const resources = [];
+            for (const operation of resolvedInput.operations) {
+                if (operation.action === "update" && !operation.target_id) {
+                    throw new PingCodeError("Ship 更新操作缺少 target_id", "BAD_REQUEST");
+                }
+                const value = resourceType === "ship_product"
+                    ? operation.action === "create"
+                        ? await services.getShipSource().createProduct(toShipProductWriteFields(parseResolvedProductCreateFields(operation.fields)))
+                        : await services.getShipSource().updateProduct(operation.target_id, toShipProductWriteFields(productUpdateFields.parse(operation.fields)))
+                    : operation.action === "create"
+                        ? await services.getShipSource().createIdea(toShipIdeaWriteFields(parseResolvedIdeaCreateFields(operation.fields)))
+                        : await services.getShipSource().updateIdea(operation.target_id, toShipIdeaWriteFields(parseResolvedIdeaUpdateFields(operation.fields)));
+                const title = "name" in value ? String(value.name) : String(value.title);
+                resources.push({ operationId: operation.operation_id, action: operation.action, id: value.id, identifier: value.identifier, title, url: value.url, relationIds: [] });
+            }
+            return resources;
+        } });
+    return { planId: input.plan_id, replayed: committed.replayed, approvedBy: committed.approval.approvedBy, auditId: committed.auditId, resources: committed.result };
+}
+async function assertNoShipProductCreateConflict(input, services) {
+    const creates = input.operations.filter((operation) => operation.action === "create");
+    if (creates.length === 0)
+        return;
+    const products = await listAllProducts(services);
+    const seenIdentifiers = new Set();
+    const seenNames = new Set();
+    for (const operation of creates) {
+        const fields = operation.fields;
+        const identifier = asString(fields.identifier);
+        const name = asString(fields.name);
+        if (identifier !== undefined) {
+            const normalized = identifier.toLocaleLowerCase();
+            if (seenIdentifiers.has(normalized)) {
+                throw new PingCodeError(`同一 Preview 中重复创建 Ship 产品 identifier：${identifier}`, "CONFLICT");
+            }
+            seenIdentifiers.add(normalized);
+        }
+        if (name !== undefined) {
+            const normalized = name.toLocaleLowerCase();
+            if (seenNames.has(normalized)) {
+                throw new PingCodeError(`同一 Preview 中重复创建 Ship 产品名称：${name}`, "CONFLICT");
+            }
+            seenNames.add(normalized);
+        }
+        const matching = products.find((product) => (identifier !== undefined && product.identifier?.toLocaleLowerCase() === identifier.toLocaleLowerCase())
+            || (name !== undefined && product.name.toLocaleLowerCase() === name.toLocaleLowerCase()));
+        if (matching) {
+            throw new PingCodeError(`Ship 产品名称或 identifier 已存在：${matching.name} (${matching.identifier})；请换用新的名称和 identifier`, "CONFLICT");
+        }
+    }
+}
+async function resolveShipPlanReferences(resourceType, input, services) {
+    const products = input.operations.some((operation) => resourceType === "ship_idea" && operation.action === "create" && (typeof operation.fields.product_id === "string" || typeof operation.fields.product_name === "string"))
+        ? await listAllProducts(services)
+        : [];
+    const operations = [];
+    for (const operation of input.operations) {
+        const fields = { ...operation.fields };
+        if (resourceType === "ship_product" && operation.action === "create") {
+            if (fields.scope_type === "user_group") {
+                fields.scope_id = await resolveTeamReference("产品归属团队", asString(fields.scope_id), asString(fields.scope_name), services);
+            }
+            if (Array.isArray(fields.members)) {
+                fields.members = await Promise.all(fields.members.map(async (member) => {
+                    const value = asRecord(member);
+                    const type = value.type === "user_group" ? "user_group" : "user";
+                    const id = type === "user_group"
+                        ? await resolveTeamReference("产品团队成员", asString(value.id), asString(value.name), services)
+                        : await resolveUserReference("产品成员", asString(value.id), asString(value.name), services);
+                    if (id === undefined)
+                        throw new PingCodeError("产品成员尚未解析为有效目录资源", "BAD_REQUEST");
+                    return { id, type };
+                }));
+            }
+        }
+        if (resourceType === "ship_idea") {
+            let productId = asString(fields.product_id);
+            if (operation.action === "create") {
+                productId = resolveCandidate("产品", productId, asString(fields.product_name), products);
+                fields.product_id = productId;
+            }
+            else if (productId === undefined && operation.target_id !== undefined) {
+                const current = await services.getShipSource().getIdea(operation.target_id);
+                productId = extractResourceId(current.product);
+            }
+            if (typeof fields.assignee_id === "string" || typeof fields.assignee_name === "string") {
+                fields.assignee_id = await resolveUserReference("需求负责人", asString(fields.assignee_id), asString(fields.assignee_name), services);
+            }
+            if (typeof fields.suite_id === "string" || typeof fields.suite_name === "string") {
+                if (!productId)
+                    throw new PingCodeError("需求模块解析需要先确定产品", "BAD_REQUEST");
+                const suites = await listAllShipSuites(productId, services);
+                fields.suite_id = resolveCandidate("需求模块", asString(fields.suite_id), asString(fields.suite_name), suites);
+            }
+            if (typeof fields.priority_id === "string" || typeof fields.priority_name === "string") {
+                if (!productId)
+                    throw new PingCodeError("需求优先级解析需要先确定产品", "BAD_REQUEST");
+                const priorities = await listAllShipIdeaPriorities(productId, services);
+                fields.priority_id = resolveCandidate("需求优先级", asString(fields.priority_id), asString(fields.priority_name), priorities);
+            }
+        }
+        operations.push({ ...operation, fields });
+    }
+    return { ...input, operations };
+}
+async function listAllProducts(services) {
+    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;
+    }
+    return values;
+}
+async function listAllShipSuites(productId, services) {
+    const values = [];
+    for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+        const page = await services.getShipSource().listSuites(productId, { pageIndex, pageSize: 100 });
+        values.push(...page.values.map((suite) => ({ id: suite.id, name: suite.name })));
+        if (values.length >= page.total || page.values.length === 0)
+            break;
+    }
+    return values;
+}
+async function listAllShipIdeaPriorities(productId, services) {
+    const values = [];
+    for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+        const page = await services.getMetadataSource().listShipIdeaPriorities(productId, { pageIndex, pageSize: 100 });
+        values.push(...page.values.map((priority) => ({ id: priority.id, name: priority.name })));
+        if (values.length >= page.total || page.values.length === 0)
+            break;
+    }
+    return values;
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function extractResourceId(value) {
+    const record = asRecord(value);
+    return asString(record.id);
+}
+function toShipProductWriteFields(fields) {
+    return {
+        ...("scope_type" in fields && fields.scope_type !== undefined ? { scopeType: fields.scope_type } : {}),
+        ...("scope_id" in fields && fields.scope_id !== undefined ? { scopeId: fields.scope_id } : {}),
+        ...(typeof fields.name === "string" ? { name: fields.name } : {}),
+        ...("visibility" in fields && fields.visibility !== undefined ? { visibility: fields.visibility } : {}),
+        ...(typeof fields.identifier === "string" ? { identifier: fields.identifier } : {}),
+        ...(typeof fields.description === "string" ? { description: fields.description } : {}),
+        ...("members" in fields && fields.members !== undefined ? { members: resolvedShipMembers(fields.members) } : {}),
+    };
+}
+function parseResolvedProductCreateFields(fields) {
+    const normalized = { ...fields };
+    // Name references remain in the Preview for readability. Once resolved, the
+    // write schema must receive only the corresponding server-side ID.
+    if (normalized.scope_id !== undefined)
+        delete normalized.scope_name;
+    return productCreateFields.parse(normalized);
+}
+function parseResolvedIdeaCreateFields(fields) {
+    const normalized = { ...fields };
+    stripResolvedIdeaReferenceNames(normalized);
+    return ideaCreateFields.parse(normalized);
+}
+function parseResolvedIdeaUpdateFields(fields) {
+    const normalized = { ...fields };
+    stripResolvedIdeaReferenceNames(normalized);
+    return ideaUpdateFields.parse(normalized);
+}
+function stripResolvedIdeaReferenceNames(fields) {
+    if (fields.product_id !== undefined)
+        delete fields.product_name;
+    if (fields.assignee_id !== undefined)
+        delete fields.assignee_name;
+    if (fields.suite_id !== undefined)
+        delete fields.suite_name;
+    if (fields.priority_id !== undefined)
+        delete fields.priority_name;
+}
+function resolvedShipMembers(members) {
+    return members.map((member) => {
+        if (member.id === undefined)
+            throw new PingCodeError("产品成员尚未解析为有效目录资源", "BAD_REQUEST");
+        return { id: member.id, type: member.type };
+    });
+}
+function toShipIdeaWriteFields(fields) {
+    return {
+        ...("product_id" in fields && fields.product_id !== undefined ? { productId: fields.product_id } : {}),
+        ...(typeof fields.title === "string" ? { title: fields.title } : {}),
+        ...("assignee_id" in fields && fields.assignee_id !== undefined ? { assigneeId: fields.assignee_id } : {}),
+        ...(typeof fields.description === "string" ? { description: fields.description } : {}),
+        ...("suite_id" in fields && fields.suite_id !== undefined ? { suiteId: fields.suite_id } : {}),
+        ...("priority_id" in fields && fields.priority_id !== undefined ? { priorityId: fields.priority_id } : {}),
+        ...(fields.properties !== undefined ? { properties: fields.properties } : {}),
+    };
+}
+function shipCommitConfirmationMessage(resourceType, input) {
+    const creates = input.operations.filter((operation) => operation.action === "create").length;
+    const updates = input.operations.length - creates;
+    const resources = input.operations.map((operation) => String(operation.fields.name ?? operation.fields.title ?? "已确认资源"));
+    const productIds = resourceType === "ship_idea"
+        ? [...new Set(input.operations.flatMap((operation) => {
+                const productId = operation.fields.product_id;
+                return typeof productId === "string" ? [productId] : [];
+            }))]
+        : [];
+    return formatWriteConfirmationMessage(resourceType === "ship_product" ? "即将写入 PingCode Ship 产品" : "即将写入 PingCode Ship 需求", [
+        ...(productIds.length > 0 ? [`目标产品：${input.operations.map((operation) => operation.fields.product_name ?? "已确认产品").filter((value, index, values) => values.indexOf(value) === index).join("、")}`] : []),
+        `操作：创建 ${creates} 个，更新 ${updates} 个`,
+        `资源：${resources.slice(0, 5).join("、")}${resources.length > 5 ? `，另有 ${resources.length - 5} 个` : ""}`,
+    ]);
+}
+function formatShipListResult(label, resources, total, pageIndex = 0, pageSize = Math.max(resources.length, 1), keywords, fallbackFromKeywords) {
+    const lines = [`${label}列表：共 ${total} 个`];
+    for (const resource of resources.slice(0, 20)) {
+        const item = asVisibleResource(resource);
+        lines.push(`- ${item.name}${item.identifier ? ` (${item.identifier})` : ""}${item.id ? `，ID：${item.id}` : ""}`);
+    }
+    if (total > resources.length) {
+        lines.push(`- 其余 ${total - resources.length} 个资源请使用分页继续读取`);
+    }
+    lines.push(...paginationGuidance({
+        pageIndex,
+        pageSize,
+        total,
+        returned: resources.length,
+        ...(keywords === undefined ? {} : { keywords }),
+        searchable: true,
+        ...(fallbackFromKeywords === undefined ? {} : { fallbackFromKeywords }),
+    }));
+    return lines.join("\n");
+}
+function formatShipResourceResult(label, resource, source) {
+    const item = asVisibleResource(resource);
+    return [
+        `${label}已读取`,
+        `名称：${item.name}`,
+        item.identifier ? `标识：${item.identifier}` : null,
+        item.id ? `资源 ID：${item.id}` : null,
+        source.contentHash ? `contentHash：${source.contentHash}` : null,
+    ].filter((line) => line !== null).join("\n");
+}
+function asVisibleResource(resource) {
+    if (typeof resource !== "object" || resource === null) {
+        return { id: null, identifier: null, name: "未命名资源" };
+    }
+    const value = resource;
+    return {
+        id: typeof value.id === "string" ? value.id : null,
+        identifier: typeof value.identifier === "string" ? value.identifier : null,
+        name: typeof value.name === "string"
+            ? value.name
+            : typeof value.title === "string" ? value.title : "未命名资源",
+    };
+}
+function changesFromCreate(fields) {
+    return Object.fromEntries(Object.entries(fields).map(([field, after]) => [field, { before: null, after }]));
+}
+function selectedChanges(current, fields) {
+    return Object.fromEntries(Object.entries(fields).map(([field, after]) => [field, { before: current[field] ?? null, after }]));
+}
+function assertContentHash(expected, current) {
+    const actual = requestHash(current);
+    if (expected !== actual) {
+        throw new PingCodeError(`Ship 资源内容已变化，无法安全覆盖（expected=${expected}, actual=${actual}）`, "CONFLICT");
+    }
+}
+function sourceMeta(value) {
+    return { contentHash: requestHash(value), retrievedAt: new Date().toISOString() };
+}
+//# sourceMappingURL=ship.js.map