@xurenxiang1219/pingcode-mcp 0.3.1

package/dist/mcp/tools/sync.js

@@ -0,0 +1,1110 @@
+import * as z from "zod/v4";
+import { PingCodeError } from "../../pingcode/errors.js";
+import { contentHashSchema, normalizeContentHash } from "../../domain/content-hash.js";
+import { requestHash as calculateRequestHash } from "../../write/plan.js";
+import { executeTool, requestIdForLog } from "../tool-runtime.js";
+import { resolveCandidate, resolveMetadataReference, resolveProjectStageReference, resolveUserReference, resolveWorkItemReference } from "../reference-resolution.js";
+import { approvalTokenSchema, commitWithApproval, formatPreviewToolResult, formatWriteConfirmationMessage, formatWriteToolResult, requestClientWriteConfirmation, resolveCommitVerification, } from "../write-approval.js";
+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 agentSessionId = z
+    .string()
+    .trim()
+    .min(8)
+    .max(200)
+    .optional()
+    .describe("当前 Agent/IDE 会话的稳定不透明 ID；能取得时由 Agent 在 Preview 与 Commit 间原样复用，不要要求用户手填。客户端无法提供时可省略。");
+const approvalContextId = z.string().uuid();
+const sourceReferenceSchema = z.object({
+    type: z
+        .enum(["wiki", "task", "test_case", "spec", "plan", "code"])
+        .describe("来源资源类型"),
+    id: identifier.describe("来源资源的稳定 ID 或仓库内规范 ID"),
+    url: z.url().optional().describe("来源可访问 URL；没有稳定 URL 时省略"),
+    content_hash: contentHash.optional().describe("读取来源时取得的 sha256 内容 Hash，用于追溯版本"),
+});
+const propertiesSchema = z
+    .record(z.string().trim().min(1).max(100), z.unknown())
+    .refine((value) => Object.keys(value).length <= 50, "properties 最多包含 50 个字段")
+    .refine((value) => Buffer.byteLength(JSON.stringify(value), "utf8") <= 32 * 1024, "properties 不得超过 32 KiB")
+    .describe("工作项属性键值。只能使用元数据 Tool 返回 writeField 为 properties.<id> 的字段，并按 valueShape/allowedValues 传值；不得猜字段 ID 或选项值。");
+// Test Case 仍保留旧客户端使用的 custom_properties 入口；工作项只使用官方
+// properties 字段，二者在各自的 endpoint 映射中保持明确边界。
+const customPropertiesSchema = propertiesSchema.describe("兼容旧客户端的自定义属性键值；Test Case 请求会映射为官方 properties。");
+const taskCommonFields = {
+    title: z.string().trim().min(1).max(500).optional().describe("工作项标题"),
+    description: z.string().max(50_000).optional().describe("工作项 Markdown 描述"),
+    start_at: z.number().int().min(0).optional().describe("开始时间，Unix 秒时间戳"),
+    end_at: z.number().int().min(0).optional().describe("结束时间，Unix 秒时间戳"),
+    priority_id: identifier.optional().describe("优先级 ID；从工作项元数据 priorities 获取"),
+    priority_name: identifier.optional().describe("优先级名称；Tool 会从工作项元数据解析 ID，名称不存在时返回候选"),
+    state_id: identifier.optional().describe("状态 ID；从指定项目和工作项类型的 states 获取"),
+    state_name: identifier.optional().describe("状态名称；Tool 会从工作项元数据解析 ID，名称不存在时返回候选"),
+    assignee_id: identifier.optional().describe("负责人用户 ID；通过 pingcode_user_search 查询"),
+    assignee_name: identifier.optional().describe("负责人姓名；Tool 会通过用户搜索解析 ID，搜索不到时返回用户候选"),
+    parent_id: identifier.optional().describe("父工作项内部 ID；不得填写显示编号"),
+    parent_name: identifier.optional().describe("父工作项名称或编号；Tool 会通过工作项列表解析 ID"),
+    participant_ids: z.array(identifier).max(50).optional().describe("关注人用户 ID 列表；每个 ID 均通过 pingcode_user_search 查询"),
+    participant_names: z.array(identifier).max(50).optional().describe("关注人姓名列表；Tool 会通过用户目录解析 ID"),
+    phase_id: identifier.optional().describe("发布阶段 ID；仅 waterfall/hybrid 项目有效，由发布阶段目录验证"),
+    phase_name: identifier.optional().describe("发布阶段名称；仅 waterfall/hybrid 项目有效，由发布阶段目录解析"),
+    version_ids: z
+        .array(identifier)
+        .optional()
+        .describe("官方版本 ID 列表；从工作项元数据 versions 获取"),
+    version_id: identifier
+        .optional()
+        .describe("兼容旧客户端的单个版本 ID；新调用必须使用官方字段 version_ids"),
+    board_id: identifier.optional().describe("看板 ID；从工作项元数据 boards 获取"),
+    board_name: identifier.optional().describe("看板名称；Tool 会从工作项元数据解析 ID"),
+    entry_id: identifier.optional().describe("看板栏 ID；提供 board_id 后从 entries 获取"),
+    entry_name: identifier.optional().describe("看板栏名称；Tool 会从工作项元数据解析 ID"),
+    swimlane_id: identifier.optional().describe("泳道 ID；提供 board_id 后从 swimlanes 获取"),
+    swimlane_name: identifier.optional().describe("泳道名称；Tool 会从工作项元数据解析 ID"),
+    properties: propertiesSchema.optional(),
+    story_points: z.number().min(0).max(100_000).refine((value) => Number.isInteger(value * 10), "story_points 必须是整数或最多包含一位小数").optional().describe("故事点数；必须是整数或最多一位小数"),
+    estimated_workload: z.number().min(0).max(1_000_000).optional().describe("预估工时"),
+    remaining_workload: z.number().min(0).max(1_000_000).optional().describe("剩余工时"),
+};
+const taskCreateFieldsSchema = z
+    .object({
+    project_id: identifier.optional().describe("可直接提供的项目内部 ID；必须来自 pingcode_project_list，Tool 会再次校验"),
+    project_name: identifier.optional().describe("项目名称或标识；正常流程先调用 pingcode_project_list 展示候选，Tool 会解析为 project_id"),
+    type_id: identifier.optional().describe("工作项类型内部 ID；必须来自 pingcode_work_item_metadata_get 的 types 目录"),
+    type_name: identifier.optional().describe("工作项类型名称或标识；Tool 会从项目 types 目录解析 ID"),
+    ...taskCommonFields,
+    title: z.string().trim().min(1).max(500).describe("工作项标题"),
+    sprint_id: identifier.optional().describe("迭代 ID；从工作项元数据 sprints 获取"),
+    sprint_name: identifier.optional().describe("迭代名称；Tool 会从工作项元数据解析 ID"),
+})
+    .strict()
+    .refine((value) => value.version_id === undefined || value.version_ids === undefined, {
+    message: "version_ids 与兼容字段 version_id 不得同时提供",
+})
+    .superRefine((value, context) => {
+    if (value.project_id === undefined && value.project_name === undefined)
+        context.addIssue({ code: "custom", path: ["project_id"], message: "project_id 或 project_name 至少提供一个" });
+    if (value.project_id !== undefined && value.project_name !== undefined)
+        context.addIssue({ code: "custom", path: ["project_name"], message: "project_id 与 project_name 不得同时提供" });
+    if (value.type_id !== undefined && value.type_name !== undefined)
+        context.addIssue({ code: "custom", path: ["type_name"], message: "type_id 与 type_name 不得同时提供" });
+    for (const [idKey, nameKey] of [["priority_id", "priority_name"], ["state_id", "state_name"], ["assignee_id", "assignee_name"], ["parent_id", "parent_name"], ["sprint_id", "sprint_name"], ["board_id", "board_name"], ["entry_id", "entry_name"], ["swimlane_id", "swimlane_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined) {
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+        }
+    }
+    if (value.phase_id !== undefined && value.phase_name !== undefined)
+        context.addIssue({ code: "custom", path: ["phase_name"], message: "phase_id 与 phase_name 不得同时提供" });
+    if (value.participant_ids !== undefined && value.participant_names !== undefined)
+        context.addIssue({ code: "custom", path: ["participant_names"], message: "participant_ids 与 participant_names 不得同时提供" });
+});
+const taskUpdateFieldsSchema = z
+    .object({
+    ...taskCommonFields,
+    sprint_id: identifier.optional().describe("迭代 ID；从工作项元数据 sprints 获取"),
+    sprint_name: identifier.optional().describe("迭代名称；Tool 会从工作项元数据解析 ID"),
+})
+    .strict()
+    .refine((value) => Object.values(value).some((item) => item !== undefined), "至少提供一個更新欄位")
+    .refine((value) => value.version_id === undefined || value.version_ids === undefined, {
+    message: "version_ids 与兼容字段 version_id 不得同时提供",
+})
+    .superRefine((value, context) => {
+    for (const [idKey, nameKey] of [["priority_id", "priority_name"], ["state_id", "state_name"], ["assignee_id", "assignee_name"], ["parent_id", "parent_name"], ["sprint_id", "sprint_name"], ["board_id", "board_name"], ["entry_id", "entry_name"], ["swimlane_id", "swimlane_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined) {
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+        }
+    }
+    if (value.phase_id !== undefined && value.phase_name !== undefined)
+        context.addIssue({ code: "custom", path: ["phase_name"], message: "phase_id 与 phase_name 不得同时提供" });
+    if (value.participant_ids !== undefined && value.participant_names !== undefined)
+        context.addIssue({ code: "custom", path: ["participant_names"], message: "participant_ids 与 participant_names 不得同时提供" });
+});
+const taskCreateOperationSchema = z
+    .object({
+    operation_id: identifier.describe("计划内唯一操作 ID，由 Agent 生成并在 Preview/Commit 间保持不变"),
+    action: z.literal("create").describe("创建工作项"),
+    fields: taskCreateFieldsSchema,
+    parent_operation_id: identifier
+        .optional()
+        .describe("引用本计划前面一个 create 操作的 operation_id，用其创建结果作为 parent_id"),
+    source_references: z
+        .array(sourceReferenceSchema)
+        .min(1)
+        .max(20)
+        .describe("支持本次创建的需求、规范或代码来源，至少一个"),
+})
+    .refine((value) => value.parent_operation_id === undefined
+    || (value.fields.parent_id === undefined && value.fields.parent_name === undefined), "parent_id/parent_name 與 parent_operation_id 不得同時提供");
+const taskUpdateOperationSchema = z.object({
+    operation_id: identifier.describe("计划内唯一操作 ID，由 Agent 生成并在 Preview/Commit 间保持不变"),
+    action: z.literal("update").describe("更新既有工作项"),
+    target_id: identifier.describe("由 pingcode_task_get 返回的工作项内部 ID"),
+    expected_content_hash: contentHash.describe("最近一次 pingcode_task_get 返回的 source.contentHash"),
+    fields: taskUpdateFieldsSchema,
+    source_references: z
+        .array(sourceReferenceSchema)
+        .min(1)
+        .max(20)
+        .describe("支持本次更新的需求、规范或代码来源，至少一个"),
+});
+const taskOperationSchema = z.discriminatedUnion("action", [
+    taskCreateOperationSchema,
+    taskUpdateOperationSchema,
+]);
+const taskPlanSchema = z.object({
+    plan_id: identifier.describe("同步计划稳定 ID；Preview 与 Commit 必须完全相同"),
+    operations: z
+        .array(taskOperationSchema)
+        .min(1)
+        .max(50)
+        .describe("输入计划操作数组；使用 snake_case 字段。Preview 返回的 operations 是 camelCase 展示差异，不能复制回 Commit"),
+});
+const testCaseStepSchema = z.object({
+    step_id: identifier.optional().describe("更新既有步骤时使用的步骤 ID；创建时省略"),
+    description: z.string().trim().min(1).max(5_000).describe("测试步骤"),
+    expected_value: z.string().max(5_000).optional().describe("预期结果"),
+    is_group: z.boolean().optional().describe("是否为步骤分组；普通步骤省略"),
+    group_id: identifier.optional().describe("所属步骤分组 ID；普通步骤省略"),
+}).strict();
+const testCaseCommonFields = {
+    title: z.string().trim().min(1).max(500).optional().describe("测试用例标题"),
+    suite_id: identifier.optional().describe("模块 ID；从 Test Case 元数据 suites 获取"),
+    suite_name: identifier.optional().describe("模块名称；Tool 会从 Test Case 元数据 suites 解析 ID"),
+    type_id: identifier.optional().describe("用例类型 ID；从 Test Case 元数据 types 获取"),
+    type_name: identifier.optional().describe("用例类型显示名称或目录标识；Tool 会从 Test Case 元数据 types 解析 ID"),
+    important_level_id: identifier
+        .optional()
+        .describe("官方重要程度 ID；从 Test Case 元数据 importantLevels 获取"),
+    important_level_name: identifier.optional().describe("重要程度名称；Tool 会从 Test Case 元数据 important_levels 解析 ID"),
+    important_level: z
+        .enum(["P0", "P1", "P2", "P3", "P4"])
+        .optional()
+        .describe("兼容旧客户端的名称值；新调用必须使用官方字段 important_level_id"),
+    maintenance_id: identifier.optional().describe("维护人用户 ID；通过 pingcode_user_search 查询"),
+    maintenance_name: identifier.optional().describe("维护人姓名；Tool 会通过用户搜索解析 ID"),
+    participant_ids: z.array(identifier).max(50).optional().describe("关注人用户 ID 列表；每个 ID 均通过 pingcode_user_search 查询"),
+    participant_names: z.array(identifier).max(50).optional().describe("关注人姓名列表；Tool 会通过用户目录解析 ID"),
+    custom_properties: customPropertiesSchema.optional(),
+    description: z.string().max(50_000).optional().describe("测试用例说明"),
+    precondition: z.string().max(50_000).optional().describe("测试前置条件"),
+    steps: z.array(testCaseStepSchema).max(100).optional().describe("测试步骤，最多 100 条"),
+};
+const testCaseCreateFieldsSchema = z
+    .object({
+    test_library_id: identifier.optional().describe("兼容字段；由 Tool 从测试库列表验证"),
+    test_library_name: identifier.optional().describe("测试库名称或标识；Tool 会从测试库列表解析 ID"),
+    ...testCaseCommonFields,
+    title: z.string().trim().min(1).max(500).describe("测试用例标题"),
+})
+    .strict()
+    .refine((value) => value.test_library_id !== undefined || value.test_library_name !== undefined, "test_library_id 或 test_library_name 至少提供一个")
+    .refine((value) => value.test_library_id === undefined || value.test_library_name === undefined, "test_library_id 与 test_library_name 不得同时提供")
+    .refine((value) => value.important_level_id === undefined || value.important_level === undefined, { message: "important_level_id 与兼容字段 important_level 不得同时提供" })
+    .superRefine((value, context) => {
+    for (const [idKey, nameKey] of [["suite_id", "suite_name"], ["type_id", "type_name"], ["important_level_id", "important_level_name"], ["maintenance_id", "maintenance_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined)
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+    }
+    if (value.participant_ids !== undefined && value.participant_names !== undefined)
+        context.addIssue({ code: "custom", path: ["participant_names"], message: "participant_ids 与 participant_names 不得同时提供" });
+});
+const testCaseUpdateFieldsSchema = z
+    .object({
+    ...testCaseCommonFields,
+    state_id: identifier.optional().describe("用例状态 ID；从 Test Case 元数据 states 获取"),
+    state_name: identifier.optional().describe("用例状态名称；Tool 会从 Test Case 元数据 states 解析 ID"),
+})
+    .strict()
+    .refine((value) => Object.values(value).some((item) => item !== undefined), "至少提供一個更新欄位")
+    .refine((value) => value.important_level_id === undefined || value.important_level === undefined, { message: "important_level_id 与兼容字段 important_level 不得同时提供" })
+    .superRefine((value, context) => {
+    for (const [idKey, nameKey] of [["suite_id", "suite_name"], ["type_id", "type_name"], ["important_level_id", "important_level_name"], ["maintenance_id", "maintenance_name"], ["state_id", "state_name"]]) {
+        if (value[idKey] !== undefined && value[nameKey] !== undefined)
+            context.addIssue({ code: "custom", path: [nameKey], message: `${idKey} 与 ${nameKey} 不得同时提供` });
+    }
+    if (value.participant_ids !== undefined && value.participant_names !== undefined)
+        context.addIssue({ code: "custom", path: ["participant_names"], message: "participant_ids 与 participant_names 不得同时提供" });
+});
+const testCaseCreateOperationSchema = z.object({
+    operation_id: identifier.describe("计划内唯一操作 ID，由 Agent 生成并在 Preview/Commit 间保持不变"),
+    action: z.literal("create").describe("创建 Test Case"),
+    fields: testCaseCreateFieldsSchema,
+    related_work_item_ids: z
+        .array(identifier)
+        .max(50)
+        .default([])
+        .describe("本次要新增关系的 story 或 bug 内部 ID；不要填写已经存在的关系，也不得填写 task ID"),
+    related_work_item_names: z.array(identifier).max(50).optional().describe("要关联的 story/bug 名称或编号；Tool 会通过工作项目录解析 ID"),
+    source_references: z
+        .array(sourceReferenceSchema)
+        .min(1)
+        .max(20)
+        .describe("支持本次创建的需求或测试规范来源，至少一个"),
+}).superRefine((value, context) => {
+    if (value.related_work_item_ids.length > 0 && value.related_work_item_names !== undefined)
+        context.addIssue({ code: "custom", path: ["related_work_item_names"], message: "related_work_item_ids 与 related_work_item_names 不得同时提供" });
+});
+const testCaseUpdateOperationSchema = z.object({
+    operation_id: identifier.describe("计划内唯一操作 ID，由 Agent 生成并在 Preview/Commit 间保持不变"),
+    action: z.literal("update").describe("更新既有 Test Case"),
+    target_id: identifier.describe("由 pingcode_test_case_get 返回的 Test Case 内部 ID"),
+    expected_content_hash: contentHash.describe("最近一次 pingcode_test_case_get 返回的 source.contentHash"),
+    fields: testCaseUpdateFieldsSchema,
+    related_work_item_ids: z
+        .array(identifier)
+        .max(50)
+        .default([])
+        .describe("要建立关系的 story 或 bug 内部 ID；不得填写 task ID"),
+    related_work_item_names: z.array(identifier).max(50).optional().describe("要关联的 story/bug 名称或编号；Tool 会通过工作项目录解析 ID"),
+    source_references: z
+        .array(sourceReferenceSchema)
+        .min(1)
+        .max(20)
+        .describe("支持本次更新的需求或测试规范来源，至少一个"),
+}).superRefine((value, context) => {
+    if (value.related_work_item_ids.length > 0 && value.related_work_item_names !== undefined)
+        context.addIssue({ code: "custom", path: ["related_work_item_names"], message: "related_work_item_ids 与 related_work_item_names 不得同时提供" });
+});
+const testCaseOperationSchema = z.discriminatedUnion("action", [
+    testCaseCreateOperationSchema,
+    testCaseUpdateOperationSchema,
+]);
+const testCasePlanSchema = z.object({
+    plan_id: identifier.describe("同步计划稳定 ID；Preview 与 Commit 必须完全相同"),
+    operations: z.array(testCaseOperationSchema).min(1).max(50).describe("按执行顺序排列的操作，最多 50 条"),
+});
+export function registerSyncTools(server, services, logger, writeRuntime, writeApprovalMode) {
+    server.registerTool("pingcode_task_sync_preview", {
+        title: "預覽 PingCode Task 同步",
+        description: "验证 Agent 生成的工作项创建/更新计划并显示差异；不写入 PingCode，但会建立短效 Approval Context。空参数或缺少字段时，按以下最小创建结构补齐：{plan_id, operations:[{operation_id, action:'create', fields:{project_name:'用户选择的项目', title:'工作项标题'}, source_references:[{type:'spec', id:'来源编号'}]}]}。create 的 fields 必须提供且只能提供一个 project_name 或 project_id：正常流程先调用 pingcode_project_list 展示项目名称、identifier 和 ID，等待用户选择后可传 project_name/identifier；也支持用户直接传 project_id，Server 会在项目目录中验证，不接受猜测 ID。类型可省略，MCP 会从该项目 types 目录选择系统 task 作为默认值；只有目录没有唯一默认 task 时，才展示 types 候选并要求选择 type_name。若传类型，type_name 与 type_id 也只能二选一，type_id 只允许使用目录返回的 ID。source_references 是 operation 内与 fields 同级的必填数组。其他负责人、状态、优先级、迭代、看板、属性等引用字段应优先使用名称或元数据目录候选，不能同时传 *_id 与 *_name。每个 operations 元素必须是完整 JSON 对象，fields 必须是 JSON 对象而不是字符串。Child Task 与 Story 同一 Preview 时使用 parent_operation_id；如果 Story 已在另一 Preview 中创建并已提交，则在新的 Preview 中使用 parent_name（或由目录返回的 parent_id）引用该 Story，不要把另一计划的 operation_id 当作当前计划的父操作。update 需要 operation_id、action=update、target_id、expected_content_hash、fields 和 source_references。不要把 Preview 返回的 camelCase 展示对象复制回 Commit。正常用户回复只展示操作、目标项目、字段差异、关系和警告；Commit 是否显示 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，不得先在聊天中重复询问。requestHash、approvalContextId、sessionBinding、evidenceHash、agent_session_id 和 idempotency_key 仅供 Agent 内部传递，不得在正常用户回复中展示或要求用户复制。调用前必须解析所有 ID，无法确定时才询问用户，禁止猜测。",
+        inputSchema: {
+            ...taskPlanSchema.shape,
+            plan_id: taskPlanSchema.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: z.array(taskOperationSchema).optional().describe("业务上必填且至少包含一个 operation；省略或传空数组仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: previewAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_task_sync_preview", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id ?? "", operationCount: input.operations?.length ?? 0 }, () => {
+        if (input.plan_id === undefined || input.operations === undefined || input.operations.length === 0) {
+            throw new PingCodeError("缺少 plan_id 或 operations；请补充工作项同步计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewTaskPlan({ plan_id: input.plan_id, operations: input.operations }, services, writeRuntime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_task_sync_commit", {
+        title: "提交 PingCode Task 同步",
+        description: "依已核准的 Preview 建立或更新 PingCode Task。Commit 必须原样复用 Preview 请求中的 plan_id 和 operations；不要复制 Preview 响应里的 camelCase operations 展示对象（operationId、targetId、changes、sourceReferences）。是否要求当前 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，并原样使用验证信息和唯一幂等键。",
+        inputSchema: {
+            ...taskPlanSchema.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 返回的短效 Approval Context ID；由 Agent 原样转交，不要要求用户手填"),
+            approval_token: approvalTokenSchema(writeApprovalMode),
+            idempotency_key: z
+                .string()
+                .trim()
+                .min(16)
+                .max(200)
+                .optional().describe("本次业务写入的唯一幂等键；未提供时由 Server 绑定到 Preview Context"),
+        },
+        annotations: commitAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_task_sync_commit", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id, operationCount: input.operations.length }, async () => {
+        writeRuntime.assertMcpWriteScope(extra.authInfo?.scopes);
+        const verification = await resolveCommitVerification(writeRuntime, {
+            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,
+        }, "task");
+        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, taskCommitConfirmationMessage(resolvedInput), writeRuntime.requiresConfirmation(input.operations.map((operation) => operation.action)));
+        return commitTaskPlan(resolvedInput, services, writeRuntime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+    server.registerTool("pingcode_test_case_sync_preview", {
+        title: "預覽 PingCode Test Case 同步",
+        description: "验证 Agent 根据 Acceptance Scenario 生成的 Test Case 创建/更新及工作项关联计划；创建的最小输入是 plan_id、operations[action=create]、fields.title、fields.test_library_id 或 test_library_name（二选一）以及 operation 内的 source_references。用户未主动指定测试库时，先调用 pingcode_project_context_get；如果已有已确认的 Test Library，只能把它作为候选展示并询问用户是否复用，用户同意后才传入 test_library_name 或 test_library_id；没有上下文或用户拒绝时调用 pingcode_test_library_list。每个 operations 元素必须是完整 JSON 对象，fields 必须是 JSON 对象而不是字符串，source_references 是 operation 内与 fields 同级的必填数组；suite_id/suite_name 只接受目标 Test Library 的 suites 目录，不接受 Ship Product 需求模块；若要关联 Product 需求模块，请使用 Relation Tool。不要复制 Preview 返回的 camelCase 展示对象回传。默认关联对应 story，不关联其子 task。此操作不写入 PingCode，但会建立短效 Approval Context。正常用户回复只展示操作、目标测试库、字段差异、关系和警告；Commit 是否显示 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，不得先在聊天中重复询问。requestHash、approvalContextId、sessionBinding、evidenceHash、agent_session_id 和 idempotency_key 仅供 Agent 内部传递，不得在正常用户回复中展示或要求用户复制。调用前必须用测试库和 Test Case 元数据 Tool 解析所有 ID/枚举；无法唯一确定时先询问用户。",
+        inputSchema: {
+            ...testCasePlanSchema.shape,
+            plan_id: testCasePlanSchema.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: z.array(testCaseOperationSchema).optional().describe("业务上必填且至少包含一个 operation；省略或传空数组仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: previewAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_test_case_sync_preview", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id ?? "", operationCount: input.operations?.length ?? 0 }, () => {
+        if (input.plan_id === undefined || input.operations === undefined || input.operations.length === 0) {
+            throw new PingCodeError("缺少 plan_id 或 operations；请补充 Test Case 同步计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewTestCasePlan({ plan_id: input.plan_id, operations: input.operations }, services, writeRuntime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_test_case_sync_commit", {
+        title: "提交 PingCode Test Case 同步",
+        description: "依已核准的 Preview 建立或更新 Test Case，并按计划关联工作项。Commit 必须原样复用 Preview 请求中的 plan_id 和 operations；不要复制 Preview 响应里的 camelCase operations 展示对象。是否要求当前 MCP Client 确认由 PINGCODE_WRITE_CONFIRMATION 决定，并原样使用验证信息和唯一幂等键。",
+        inputSchema: {
+            ...testCasePlanSchema.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 返回的短效 Approval Context ID；由 Agent 原样转交，不要要求用户手填"),
+            approval_token: approvalTokenSchema(writeApprovalMode),
+            idempotency_key: z
+                .string()
+                .trim()
+                .min(16)
+                .max(200)
+                .optional().describe("本次业务写入的唯一幂等键；未提供时由 Server 绑定到 Preview Context"),
+        },
+        annotations: commitAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_test_case_sync_commit", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { planId: input.plan_id, operationCount: input.operations.length }, async () => {
+        writeRuntime.assertMcpWriteScope(extra.authInfo?.scopes);
+        const verification = await resolveCommitVerification(writeRuntime, {
+            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,
+        }, "test_case");
+        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, await testCaseCommitConfirmationMessage(resolvedInput, services), writeRuntime.requiresConfirmation(input.operations.map((operation) => operation.action)));
+        return commitTestCasePlan(resolvedInput, services, writeRuntime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+}
+async function previewTaskPlan(plan, services, runtime, agentSessionIdValue, authInfo) {
+    validateOperations(plan.operations);
+    const resolvedPlan = await resolveTaskPlanReferences(plan, services);
+    const operations = [];
+    for (const operation of resolvedPlan.operations) {
+        if (operation.action === "create") {
+            operations.push({
+                operationId: operation.operation_id,
+                action: operation.action,
+                targetId: null,
+                changes: {
+                    ...changesFromCreate(operation.fields),
+                    ...(operation.parent_operation_id === undefined
+                        ? {}
+                        : { parent_operation_id: { before: null, after: operation.parent_operation_id } }),
+                },
+                sourceReferences: operation.source_references,
+            });
+            continue;
+        }
+        const current = await services.getTaskSource().getWorkItemContext(operation.target_id);
+        assertExpectedHash(operation.expected_content_hash, current.source.contentHash);
+        operations.push({
+            operationId: operation.operation_id,
+            action: operation.action,
+            targetId: current.source.id,
+            changes: taskChanges(current, operation.fields),
+            sourceReferences: operation.source_references,
+        });
+    }
+    return previewResult("task", plan, operations, runtime, 0, agentSessionIdValue, authInfo);
+}
+async function previewTestCasePlan(plan, services, runtime, agentSessionIdValue, authInfo) {
+    validateOperations(plan.operations);
+    const resolvedPlan = await resolveTestCasePlanReferences(plan, services);
+    await assertSupportedTestCaseRelationTargets(resolvedPlan, services);
+    const operations = [];
+    for (const operation of resolvedPlan.operations) {
+        if (operation.action === "create") {
+            operations.push({
+                operationId: operation.operation_id,
+                action: operation.action,
+                targetId: null,
+                changes: changesFromCreate(operation.fields),
+                sourceReferences: operation.source_references,
+                relatedWorkItemIds: operation.related_work_item_ids,
+            });
+            continue;
+        }
+        const current = await services.getTestCaseSource().getTestCaseContext(operation.target_id);
+        assertExpectedHash(operation.expected_content_hash, current.source.contentHash);
+        operations.push({
+            operationId: operation.operation_id,
+            action: operation.action,
+            targetId: current.source.id,
+            changes: testCaseChanges(current, operation.fields),
+            sourceReferences: operation.source_references,
+            relatedWorkItemIds: operation.related_work_item_ids,
+        });
+    }
+    const relations = plan.operations.reduce((total, operation) => total + operation.related_work_item_ids.length, 0);
+    return previewResult("test_case", plan, operations, runtime, relations, agentSessionIdValue, authInfo);
+}
+async function resolveTestCasePlanReferences(plan, services) {
+    let libraries;
+    const operations = [];
+    for (const operation of plan.operations) {
+        const current = operation.action === "update"
+            ? await services.getTestCaseSource().getTestCaseContext(operation.target_id)
+            : undefined;
+        const rawFields = { ...operation.fields };
+        if (rawFields.test_library_id !== undefined || rawFields.test_library_name !== undefined) {
+            libraries ??= [];
+            if (libraries.length === 0) {
+                for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+                    const page = await services.getMetadataSource().listTestLibraries({ pageIndex, pageSize: 100 });
+                    libraries.push(...page.values.map((library) => ({ id: library.id, name: library.name, identifier: library.identifier })));
+                    if (libraries.length >= page.total || page.values.length === 0)
+                        break;
+                }
+            }
+            rawFields.test_library_id = resolveCandidate("测试库", typeof rawFields.test_library_id === "string" ? rawFields.test_library_id : undefined, typeof rawFields.test_library_name === "string" ? rawFields.test_library_name : undefined, libraries);
+            const selectedLibrary = libraries.find((library) => library.id === rawFields.test_library_id);
+            if (selectedLibrary)
+                rawFields.test_library_name = `${selectedLibrary.name} (${selectedLibrary.identifier ?? selectedLibrary.id})`;
+        }
+        else if (current !== undefined) {
+            rawFields.test_library_id = current.source.libraryId;
+        }
+        const libraryId = typeof rawFields.test_library_id === "string" ? rawFields.test_library_id : undefined;
+        const metadata = libraryId === undefined ? null : await services.getMetadataSource().getTestCaseMetadata(libraryId);
+        const resolveCatalog = async (idKey, nameKey, catalog) => {
+            const value = rawFields[idKey];
+            const name = rawFields[nameKey];
+            if (typeof value !== "string" && typeof name !== "string")
+                return;
+            const result = metadata?.[catalog];
+            if (!result || !result.available)
+                throw new PingCodeError(`${nameKey} 无法解析：测试用例元数据未返回目录`, "NOT_CONFIGURED");
+            if (catalog === "suites" && typeof value === "string" && !result.values.some((candidate) => candidate.id === value)) {
+                throw new PingCodeError("Test Case 的 suite_id 必须来自目标 Test Library 的 suites 目录；Ship Product 需求模块 ID 不能作为 Test Case 模块，请改用 Test Library 模块或通过 Relation 关联 Product 需求模块", "NOT_FOUND");
+            }
+            rawFields[idKey] = await resolveMetadataReference(nameKey, typeof value === "string" ? value : undefined, typeof name === "string" ? name : undefined, result.values);
+            // 保留可读名称用于 Preview 展示；写入 Adapter 只消费解析后的 *_id。
+        };
+        await resolveCatalog("suite_id", "suite_name", "suites");
+        await resolveCatalog("type_id", "type_name", "types");
+        await resolveCatalog("state_id", "state_name", "states");
+        await resolveCatalog("important_level_id", "important_level_name", "importantLevels");
+        if (typeof rawFields.maintenance_id === "string" || typeof rawFields.maintenance_name === "string") {
+            rawFields.maintenance_id = await resolveUserReference("维护人", typeof rawFields.maintenance_id === "string" ? rawFields.maintenance_id : undefined, typeof rawFields.maintenance_name === "string" ? rawFields.maintenance_name : undefined, services);
+            delete rawFields.maintenance_name;
+        }
+        if (typeof rawFields.participant_names === "object" && Array.isArray(rawFields.participant_names)) {
+            rawFields.participant_ids = await Promise.all(rawFields.participant_names.map(async (name) => {
+                const id = await resolveUserReference("关注人", undefined, typeof name === "string" ? name : undefined, services);
+                if (id === undefined)
+                    throw new PingCodeError("关注人尚未解析为有效用户", "BAD_REQUEST");
+                return id;
+            }));
+            delete rawFields.participant_names;
+        }
+        else if (Array.isArray(rawFields.participant_ids)) {
+            rawFields.participant_ids = await Promise.all(rawFields.participant_ids.map(async (value) => {
+                const id = await resolveUserReference("关注人", typeof value === "string" ? value : undefined, undefined, services);
+                if (id === undefined)
+                    throw new PingCodeError("关注人尚未解析为有效用户", "BAD_REQUEST");
+                return id;
+            }));
+        }
+        const relatedWorkItemIds = operation.related_work_item_names === undefined
+            ? operation.related_work_item_ids
+            : await Promise.all(operation.related_work_item_names.map(async (name) => {
+                const id = await resolveWorkItemReference("关联工作项", undefined, name, services);
+                if (id === undefined)
+                    throw new PingCodeError("关联工作项尚未解析为有效资源", "BAD_REQUEST");
+                return id;
+            }));
+        operations.push({ ...operation, fields: rawFields, related_work_item_ids: relatedWorkItemIds, related_work_item_names: undefined });
+    }
+    return { ...plan, operations };
+}
+async function resolveTaskPlanReferences(plan, services) {
+    const operations = [];
+    const createOperationTypes = new Map();
+    for (const originalOperation of plan.operations) {
+        let operation = originalOperation;
+        if (operation.action === "create" && (operation.fields.project_id !== undefined || operation.fields.project_name !== undefined)) {
+            const projects = [];
+            for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+                const page = await services.getMetadataSource().listProjects({ pageIndex, pageSize: 100 });
+                projects.push(...page.values.map((project) => ({ id: project.id, name: project.name, identifier: project.identifier })));
+                if (projects.length >= page.total || page.values.length === 0)
+                    break;
+            }
+            const projectId = resolveCandidate("目标项目", operation.fields.project_id, operation.fields.project_name, projects);
+            if (projectId === undefined)
+                throw new PingCodeError("目标项目尚未解析为有效资源", "BAD_REQUEST");
+            const selectedProject = projects.find((project) => project.id === projectId);
+            operation = { ...operation, fields: { ...operation.fields, project_id: projectId, ...(selectedProject?.name === undefined ? {} : { project_name: selectedProject.name }) } };
+        }
+        const base = operation.action === "create"
+            ? { projectId: operation.fields.project_id, typeId: operation.fields.type_id, typeName: operation.fields.type_name }
+            : {};
+        const current = operation.action === "update"
+            ? await services.getTaskSource().getWorkItemContext(operation.target_id)
+            : undefined;
+        const projectId = base.projectId ?? current?.source.projectId;
+        let typeId = base.typeId;
+        let metadata = projectId === undefined
+            ? null
+            : await services.getMetadataSource().getWorkItemMetadata({
+                projectId,
+                ...(typeId === undefined ? {} : { workItemTypeId: typeId }),
+                include: typeId === undefined ? ["types", "priorities", "sprints", "boards"] : undefined,
+            });
+        if (typeId !== undefined || base.typeName !== undefined) {
+            if (!metadata?.types.available) {
+                throw new PingCodeError("工作项类型无法解析：工作项元数据未返回 types 目录", "NOT_CONFIGURED");
+            }
+            typeId = await resolveMetadataReference("工作项类型", typeId, base.typeName, metadata.types.values);
+            if (operation.action === "create") {
+                const selectedType = metadata.types.values.find((value) => String(value.id) === String(typeId));
+                operation = { ...operation, fields: { ...operation.fields, type_id: typeId, ...(typeof selectedType?.name === "string" ? { type_name: selectedType.name } : {}) } };
+            }
+        }
+        else if (operation.action === "create") {
+            if (!metadata?.types.available) {
+                throw new PingCodeError("工作项类型无法解析：工作项元数据未返回 types 目录", "NOT_CONFIGURED");
+            }
+            typeId = defaultWorkItemTypeId(metadata.types.values);
+            if (typeId === undefined) {
+                throw new PingCodeError("未指定工作项类型，且当前项目没有唯一默认类型；请从 types 候选中选择 type_name", "BAD_REQUEST");
+            }
+            const selectedType = metadata.types.values.find((value) => String(value.id) === String(typeId));
+            operation = { ...operation, fields: { ...operation.fields, type_id: typeId, ...(typeof selectedType?.name === "string" ? { type_name: selectedType.name } : {}) } };
+        }
+        if (operation.action === "create" && typeId !== undefined && !metadata?.states.available) {
+            metadata = await services.getMetadataSource().getWorkItemMetadata({ projectId: projectId, workItemTypeId: typeId });
+        }
+        const needsTypedMetadata = operation.action === "create"
+            || fieldsNeedWorkItemStateMetadata(operation.fields);
+        if (typeId === undefined && operation.action === "update" && needsTypedMetadata && current?.type !== undefined && metadata?.types.available) {
+            typeId = resolveCurrentWorkItemTypeId(current.type, metadata.types.values);
+            if (typeId !== undefined) {
+                metadata = projectId === undefined
+                    ? null
+                    : await services.getMetadataSource().getWorkItemMetadata({ projectId, workItemTypeId: typeId });
+            }
+        }
+        if (operation.action === "update" && fieldsNeedWorkItemStateMetadata(operation.fields) && typeId === undefined) {
+            throw new PingCodeError(`工作项更新需要按当前类型读取 states 目录，但回读类型 '${current?.type ?? "未知"}' 无法匹配项目类型目录`, "NOT_FOUND");
+        }
+        if (operation.action === "create" && typeId !== undefined) {
+            const typeEntry = metadata?.types.available
+                ? metadata.types.values.find((value) => String(value.id) === String(typeId))
+                : undefined;
+            createOperationTypes.set(operation.operation_id, classifyWorkItemType(typeEntry, typeId));
+        }
+        const fields = { ...operation.fields };
+        const resolveCatalog = async (idKey, nameKey, catalog, source = metadata) => {
+            const value = fields[idKey];
+            const name = fields[nameKey];
+            if (typeof value !== "string" && typeof name !== "string")
+                return;
+            const result = source?.[catalog];
+            if (!result || !result.available) {
+                throw new PingCodeError(`${nameKey} 无法解析：工作项元数据未返回 ${String(catalog)} 目录`, "NOT_CONFIGURED");
+            }
+            fields[idKey] = await resolveMetadataReference(nameKey, typeof value === "string" ? value : undefined, typeof name === "string" ? name : undefined, result.values);
+            // 保留可读名称用于 Preview 展示；写入 Adapter 只消费解析后的 *_id。
+        };
+        await resolveCatalog("priority_id", "priority_name", "priorities");
+        await resolveCatalog("state_id", "state_name", "states");
+        await resolveCatalog("sprint_id", "sprint_name", "sprints");
+        await resolveCatalog("board_id", "board_name", "boards");
+        if ((typeof fields.entry_id === "string" || typeof fields.entry_name === "string"
+            || typeof fields.swimlane_id === "string" || typeof fields.swimlane_name === "string")
+            && typeof fields.board_id === "string" && projectId !== undefined) {
+            metadata = await services.getMetadataSource().getWorkItemMetadata({
+                projectId,
+                ...(typeId === undefined ? {} : { workItemTypeId: typeId }),
+                boardId: fields.board_id,
+                include: ["entries", "swimlanes"],
+            });
+        }
+        await resolveCatalog("entry_id", "entry_name", "entries");
+        await resolveCatalog("swimlane_id", "swimlane_name", "swimlanes");
+        if (typeof fields.assignee_id === "string" || typeof fields.assignee_name === "string") {
+            fields.assignee_id = await resolveUserReference("负责人", typeof fields.assignee_id === "string" ? fields.assignee_id : undefined, typeof fields.assignee_name === "string" ? fields.assignee_name : undefined, services);
+            delete fields.assignee_name;
+        }
+        if (typeof fields.parent_id === "string" || typeof fields.parent_name === "string") {
+            fields.parent_id = await resolveWorkItemReference("父工作项", typeof fields.parent_id === "string" ? fields.parent_id : undefined, typeof fields.parent_name === "string" ? fields.parent_name : undefined, services, projectId);
+            delete fields.parent_name;
+            const parent = await services.getTaskSource().getWorkItemContext(String(fields.parent_id));
+            assertSupportedTaskParent(parent);
+        }
+        if (operation.action === "create" && operation.parent_operation_id !== undefined) {
+            const parentType = createOperationTypes.get(operation.parent_operation_id);
+            if (parentType === undefined) {
+                throw new PingCodeError(`parent_operation_id '${operation.parent_operation_id}' 的父工作项类型无法在 Preview 阶段解析`, "BAD_REQUEST");
+            }
+            if (parentType !== "story") {
+                throw new PingCodeError(`Child Task 的父工作项必须是 story；计划中的 '${operation.parent_operation_id}' 类型是 '${parentType}'`, "BAD_REQUEST");
+            }
+        }
+        if (typeof fields.phase_id === "string" || typeof fields.phase_name === "string") {
+            if (projectId === undefined)
+                throw new PingCodeError("发布阶段解析缺少项目", "BAD_REQUEST");
+            const project = await services.getMetadataSource().getProject(projectId);
+            if (project.type !== "waterfall" && project.type !== "hybrid") {
+                throw new PingCodeError(`项目类型 ${project.type} 不支持 phase_id；scrum/kanban 不会请求发布阶段目录`, "BAD_REQUEST");
+            }
+            fields.phase_id = await resolveProjectStageReference("发布阶段", typeof fields.phase_id === "string" ? fields.phase_id : undefined, typeof fields.phase_name === "string" ? fields.phase_name : undefined, services);
+            delete fields.phase_name;
+        }
+        if (Array.isArray(fields.participant_names)) {
+            fields.participant_ids = await Promise.all(fields.participant_names.map(async (name) => {
+                const id = await resolveUserReference("关注人", undefined, typeof name === "string" ? name : undefined, services);
+                if (id === undefined)
+                    throw new PingCodeError("关注人尚未解析为有效用户", "BAD_REQUEST");
+                return id;
+            }));
+            delete fields.participant_names;
+        }
+        else if (Array.isArray(fields.participant_ids)) {
+            fields.participant_ids = await Promise.all(fields.participant_ids.map(async (value) => {
+                const id = await resolveUserReference("关注人", typeof value === "string" ? value : undefined, undefined, services);
+                if (id === undefined)
+                    throw new PingCodeError("关注人尚未解析为有效用户", "BAD_REQUEST");
+                return id;
+            }));
+        }
+        operations.push({ ...operation, fields });
+    }
+    return { ...plan, operations };
+}
+function classifyWorkItemType(value, fallback) {
+    const candidates = [value?.type, value?.name, value?.id, fallback]
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim().toLowerCase());
+    if (candidates.some((item) => item === "story" || item.includes("story") || item.includes("用户故事"))) {
+        return "story";
+    }
+    if (candidates.some((item) => item === "bug" || item.includes("bug") || item.includes("缺陷"))) {
+        return "bug";
+    }
+    if (candidates.some((item) => item === "task" || item.includes("task") || item.includes("任务"))) {
+        return "task";
+    }
+    return candidates[0] ?? fallback;
+}
+export function defaultWorkItemTypeId(values) {
+    const exactTask = values.find((value) => value.id === "task");
+    if (exactTask && typeof exactTask.id === "string")
+        return exactTask.id;
+    const taskGroup = values.filter((value) => value.group === "task");
+    if (taskGroup.length === 1 && typeof taskGroup[0]?.id === "string")
+        return taskGroup[0].id;
+    if (values.length === 1 && typeof values[0]?.id === "string")
+        return values[0].id;
+    return undefined;
+}
+function fieldsNeedWorkItemStateMetadata(fields) {
+    return typeof fields.state_id === "string" || typeof fields.state_name === "string";
+}
+export function resolveCurrentWorkItemTypeId(type, values) {
+    const normalized = type.trim().toLocaleLowerCase();
+    const match = values.find((value) => [value.id, value.name, value.type, value.key, value.code]
+        .some((candidate) => typeof candidate === "string" && candidate.trim().toLocaleLowerCase() === normalized));
+    return typeof match?.id === "string" ? match.id : undefined;
+}
+function assertSupportedTaskParent(parent) {
+    if (parent.type === "story") {
+        return;
+    }
+    throw new PingCodeError(`Child Task 的父工作项必须是 story；'${parent.source.identifier}' 的类型是 '${parent.type}'`, "BAD_REQUEST");
+}
+async function commitTaskPlan(input, services, runtime, writeApprovalMode, authInfo) {
+    const rawPlan = { plan_id: input.plan_id, operations: input.operations };
+    assertRequestHash(rawPlan, input.request_hash);
+    const plan = await resolveTaskPlanReferences(rawPlan, services);
+    validateOperations(plan.operations);
+    const committed = await commitWithApproval(runtime, writeApprovalMode, {
+        resourceType: "task",
+        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: plan.operations.map((operation) => operation.action),
+        action: async () => {
+            const resources = [];
+            const createdIds = new Map();
+            for (const operation of plan.operations) {
+                if (operation.action === "create") {
+                    const fields = taskFields(operation.fields);
+                    if (operation.parent_operation_id) {
+                        fields.parentId = createdIds.get(operation.parent_operation_id);
+                    }
+                    const resource = await services.getWriteSource().createTask(fields);
+                    createdIds.set(operation.operation_id, resource.id);
+                    resources.push(resourceResult(operation, resource, []));
+                    continue;
+                }
+                const current = await services.getTaskSource().getWorkItemContext(operation.target_id);
+                assertExpectedHash(operation.expected_content_hash, current.source.contentHash);
+                const resource = await services
+                    .getWriteSource()
+                    .updateTask(current.source.id, taskFields(operation.fields));
+                resources.push(resourceResult(operation, resource, []));
+            }
+            return { planId: plan.plan_id, requestHash: input.request_hash, resources };
+        },
+    });
+    return {
+        planId: committed.result.planId,
+        resources: committed.result.resources,
+        replayed: committed.replayed,
+        approvedBy: committed.approval.approvedBy,
+        auditId: committed.auditId,
+    };
+}
+async function commitTestCasePlan(input, services, runtime, writeApprovalMode, authInfo) {
+    const rawPlan = { plan_id: input.plan_id, operations: input.operations };
+    assertRequestHash(rawPlan, input.request_hash);
+    const plan = await resolveTestCasePlanReferences(rawPlan, services);
+    validateOperations(plan.operations);
+    const committed = await commitWithApproval(runtime, writeApprovalMode, {
+        resourceType: "test_case",
+        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: plan.operations.map((operation) => operation.action),
+        action: async () => {
+            // Validate every target before the first mutation so an invalid relation cannot cause a partial plan.
+            await assertSupportedTestCaseRelationTargets(plan, services);
+            const resources = [];
+            for (const operation of plan.operations) {
+                let resource;
+                if (operation.action === "create") {
+                    resource = await services.getWriteSource().createTestCase(testCaseFields(operation.fields));
+                    const verifiedId = await verifyCreatedTestCase(resource.id, services);
+                    if (verifiedId !== undefined)
+                        resource = { ...resource, id: verifiedId };
+                }
+                else {
+                    const current = await services.getTestCaseSource().getTestCaseContext(operation.target_id);
+                    assertExpectedHash(operation.expected_content_hash, current.source.contentHash);
+                    resource = await services
+                        .getWriteSource()
+                        .updateTestCase(current.source.id, testCaseFields(operation.fields));
+                }
+                const relationIds = [];
+                for (const workItemId of operation.related_work_item_ids) {
+                    const relation = await services
+                        .getWriteSource()
+                        .relateTestCaseToWorkItem(resource.id, workItemId);
+                    relationIds.push(relation.id);
+                }
+                resources.push(resourceResult(operation, resource, relationIds));
+            }
+            return { planId: plan.plan_id, requestHash: input.request_hash, resources };
+        },
+    });
+    return {
+        planId: committed.result.planId,
+        resources: committed.result.resources,
+        replayed: committed.replayed,
+        approvedBy: committed.approval.approvedBy,
+        auditId: committed.auditId,
+    };
+}
+async function assertSupportedTestCaseRelationTargets(plan, services) {
+    for (const operation of plan.operations) {
+        if (operation.action !== "update" || operation.related_work_item_ids.length === 0) {
+            continue;
+        }
+        const current = await services.getTestCaseSource().getTestCaseContext(operation.target_id);
+        if (!current.relationsAvailable) {
+            throw new PingCodeError(`Test Case '${current.source.identifier}' 的现有关系无法读取（${current.relationErrorCode ?? "UNKNOWN"}）；无法安全判断新增关系是否重复，请省略 related_work_item_ids 或传空数组`, "BAD_REQUEST");
+        }
+        const existingTargetIds = new Set(current.relatedWorkItemIds);
+        const duplicateTargetIds = operation.related_work_item_ids.filter((id) => existingTargetIds.has(id));
+        if (duplicateTargetIds.length > 0) {
+            throw new PingCodeError(`Test Case '${current.source.identifier}' 已存在 ${duplicateTargetIds.length} 个计划中的工作项关系；related_work_item_ids 只用于新增关系，保留已有关系时请省略或传空数组`, "BAD_REQUEST");
+        }
+    }
+    const targetIds = [
+        ...new Set(plan.operations.flatMap((operation) => operation.related_work_item_ids)),
+    ];
+    for (const targetId of targetIds) {
+        const target = await services.getTaskSource().getWorkItemContext(targetId);
+        if (target.type !== "story" && target.type !== "bug") {
+            throw new PingCodeError(`測試用例只能關聯 story 或 bug；'${target.source.identifier}' 的類型是 '${target.type}'`, "BAD_REQUEST");
+        }
+    }
+}
+async function previewResult(resourceType, plan, operations, runtime, relations, agentSessionIdValue, authInfo) {
+    const requestHash = calculateRequestHash(plan);
+    const evidenceHash = calculateRequestHash({
+        planId: plan.plan_id,
+        requestHash,
+        operations,
+    });
+    const context = await runtime.createApprovalContext({
+        resourceType,
+        requestHash,
+        evidenceHash,
+        ...(agentSessionIdValue === undefined ? {} : { agentSessionId: agentSessionIdValue }),
+        ...(authInfo === undefined ? {} : { authInfo }),
+    });
+    return {
+        planId: plan.plan_id,
+        requestHash,
+        approvalContextId: context.approvalContextId,
+        sessionBinding: context.sessionBinding,
+        evidenceHash,
+        approvalExpiresAt: context.expiresAt,
+        counts: {
+            creates: plan.operations.filter((operation) => operation.action === "create").length,
+            updates: plan.operations.filter((operation) => operation.action === "update").length,
+            relations,
+        },
+        operations,
+    };
+}
+function validateOperations(operations) {
+    const seen = new Set();
+    const actions = new Map();
+    for (const operation of operations) {
+        if (seen.has(operation.operation_id)) {
+            throw new PingCodeError(`operation_id '${operation.operation_id}' 重複`, "BAD_REQUEST");
+        }
+        if (operation.parent_operation_id) {
+            if (!seen.has(operation.parent_operation_id) || actions.get(operation.parent_operation_id) !== "create") {
+                throw new PingCodeError(`parent_operation_id '${operation.parent_operation_id}' 必須指向前面已定義的建立操作`, "BAD_REQUEST");
+            }
+        }
+        seen.add(operation.operation_id);
+        if (operation.action) {
+            actions.set(operation.operation_id, operation.action);
+        }
+    }
+}
+function assertRequestHash(plan, expected) {
+    if (calculateRequestHash(plan) !== expected) {
+        throw new PingCodeError("Commit 內容與 Preview request hash 不一致", "CONFLICT");
+    }
+}
+function assertExpectedHash(expected, actual) {
+    if (normalizeContentHash(expected) !== normalizeContentHash(actual)) {
+        throw new PingCodeError("目標資源自 Preview 後已變更，請重新取得內容並產生 Preview", "CONFLICT");
+    }
+}
+function changesFromCreate(fields) {
+    return Object.fromEntries(Object.entries(fields)
+        .filter(([, value]) => value !== undefined)
+        .map(([field, value]) => [field, { before: null, after: value }]));
+}
+function taskChanges(current, fields) {
+    const before = {
+        title: current.title,
+        description: current.description,
+        start_at: current.startAt,
+        end_at: current.endAt,
+        priority_id: current.priority?.id ?? null,
+        state_id: current.state?.id ?? null,
+        assignee_id: current.assignee?.id ?? null,
+        parent_id: current.parent?.id ?? null,
+        properties: current.properties,
+    };
+    return selectedChanges(before, fields);
+}
+function testCaseChanges(current, fields) {
+    const before = {
+        title: current.title,
+        description: current.description,
+        precondition: current.precondition,
+        suite_id: current.suite?.id ?? null,
+        state_id: current.state?.id ?? null,
+        type_id: current.type?.id ?? null,
+        important_level_id: current.importantLevel?.id ?? null,
+        important_level: current.importantLevel?.name ?? null,
+        maintenance_id: current.maintenance?.id ?? null,
+        custom_properties: current.properties,
+        steps: current.steps,
+    };
+    return selectedChanges(before, fields);
+}
+function selectedChanges(before, fields) {
+    return Object.fromEntries(Object.entries(fields)
+        .filter(([, value]) => value !== undefined)
+        .map(([field, after]) => [field, { before: before[field] ?? null, after }]));
+}
+function taskFields(fields) {
+    return compact({
+        projectId: fields.project_id,
+        typeId: fields.type_id,
+        title: fields.title,
+        description: fields.description,
+        startAt: fields.start_at,
+        endAt: fields.end_at,
+        priorityId: fields.priority_id,
+        stateId: fields.state_id,
+        assigneeId: fields.assignee_id,
+        parentId: fields.parent_id,
+        sprintId: fields.sprint_id,
+        versionIds: fields.version_ids,
+        versionId: fields.version_id,
+        boardId: fields.board_id,
+        entryId: fields.entry_id,
+        swimlaneId: fields.swimlane_id,
+        phaseId: fields.phase_id,
+        storyPoints: fields.story_points,
+        estimatedWorkload: fields.estimated_workload,
+        remainingWorkload: fields.remaining_workload,
+        properties: fields.properties,
+        participantIds: fields.participant_ids,
+    });
+}
+function testCaseFields(fields) {
+    const steps = fields.steps;
+    return compact({
+        testLibraryId: fields.test_library_id,
+        title: fields.title,
+        suiteId: fields.suite_id,
+        stateId: fields.state_id,
+        typeId: fields.type_id,
+        importantLevel: fields.important_level,
+        importantLevelId: fields.important_level_id,
+        maintenanceId: fields.maintenance_id,
+        participantIds: fields.participant_ids,
+        properties: fields.custom_properties,
+        description: fields.description,
+        precondition: fields.precondition,
+        steps: steps?.map((step) => compact({
+            stepId: step.step_id,
+            description: step.description,
+            expectedValue: step.expected_value,
+            isGroup: step.is_group,
+            groupId: step.group_id,
+        })),
+    });
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, nested]) => nested !== undefined));
+}
+function taskCommitConfirmationMessage(input) {
+    const projectIds = [
+        ...new Set(input.operations.flatMap((operation) => operation.action === "create" ? [operation.fields.project_id] : [])),
+    ];
+    const targets = projectIds.map((id) => {
+        const namedOperation = input.operations.find((operation) => operation.action === "create" && operation.fields.project_id === id);
+        return namedOperation && "project_name" in namedOperation.fields && typeof namedOperation.fields.project_name === "string"
+            ? namedOperation.fields.project_name
+            : "已确认项目";
+    });
+    const projectNames = [
+        ...new Set(input.operations.flatMap((operation) => operation.action === "create" && operation.fields.project_id === undefined
+            ? [operation.fields.project_name]
+            : [])),
+    ];
+    const projectLabels = [...targets, ...projectNames.map((name) => `项目 ${name}`)];
+    const creates = input.operations.filter((operation) => operation.action === "create").length;
+    const updates = input.operations.length - creates;
+    const resources = input.operations.map((operation) => operation.fields.title ?? (operation.action === "update" ? "已确认工作项" : "已确认工作项"));
+    return formatWriteConfirmationMessage("即将写入 PingCode 工作项", [
+        `目标项目：${projectLabels.length > 0 ? projectLabels.join("、") : "由现有工作项决定"}`,
+        `操作：创建 ${creates} 个，更新 ${updates} 个`,
+        `资源：${summarizeLabels(resources)}`,
+    ]);
+}
+async function testCaseCommitConfirmationMessage(input, services) {
+    const libraryIds = [
+        ...new Set(input.operations.flatMap((operation) => operation.action === "create" && operation.fields.test_library_id !== undefined ? [operation.fields.test_library_id] : [])),
+    ];
+    const targets = await resolveTestLibraryLabels(input, libraryIds, services);
+    const creates = input.operations.filter((operation) => operation.action === "create").length;
+    const updates = input.operations.length - creates;
+    const relations = input.operations.reduce((total, operation) => total + operation.related_work_item_ids.length, 0);
+    const resources = input.operations.map((operation) => operation.fields.title ?? "已确认测试用例");
+    return formatWriteConfirmationMessage("即将写入 PingCode Test Case", [
+        `目标测试库：${targets.length > 0 ? targets.join("、") : "由现有 Test Case 决定"}`,
+        `操作：创建 ${creates} 个，更新 ${updates} 个，建立关系 ${relations} 个`,
+        `资源：${summarizeLabels(resources)}`,
+    ]);
+}
+async function resolveTestLibraryLabels(input, libraryIds, services) {
+    const labels = new Map();
+    await Promise.all(libraryIds.map(async (id) => {
+        try {
+            const library = await services.getMetadataSource().getTestLibrary(id);
+            labels.set(id, `${library.name} (${library.identifier})`);
+        }
+        catch {
+            labels.set(id, "已确认测试库");
+        }
+    }));
+    await Promise.all(input.operations.filter((operation) => operation.action === "update").map(async (operation) => {
+        try {
+            const context = await services.getTestCaseSource().getTestCaseContext(operation.target_id);
+            labels.set(context.source.libraryId, `${context.source.libraryName} (${context.source.libraryIdentifier})`);
+        }
+        catch {
+            // The update can still be confirmed using the Test Case target if enrichment is unavailable.
+        }
+    }));
+    const updateOnly = input.operations.some((operation) => operation.action === "update") && libraryIds.length === 0;
+    return updateOnly && labels.size === 0
+        ? ["由现有 Test Case 决定（库信息未能在确认前读取）"]
+        : [...labels.values()];
+}
+function summarizeLabels(values) {
+    const visible = values.slice(0, 5);
+    const remaining = values.length - visible.length;
+    return `${visible.join("、")}${remaining > 0 ? `，另有 ${remaining} 个` : ""}`;
+}
+function resourceResult(operation, resource, relationIds) {
+    return {
+        operationId: operation.operation_id,
+        action: operation.action,
+        id: resource.id,
+        identifier: resource.identifier,
+        title: resource.title,
+        url: resource.html_url ?? resource.url,
+        relationIds,
+        verified: true,
+    };
+}
+export async function verifyCreatedTestCase(caseId, services, sleep = waitForReadConsistency) {
+    let lastError;
+    for (let attempt = 0; attempt < 4; attempt += 1) {
+        try {
+            const context = await services.getTestCaseSource().getTestCaseContext(caseId);
+            return context.source.id === caseId ? undefined : context.source.id;
+        }
+        catch (error) {
+            lastError = error;
+            const retryableVisibilityError = isTestCaseReadConsistencyError(error);
+            if (!retryableVisibilityError || attempt === 3) {
+                break;
+            }
+            await sleep(250 * 2 ** attempt);
+        }
+    }
+    throw new PingCodeError(`Test Case ${caseId} 已创建，但写后读仍未可见；PingCode 可能存在索引或资源同步延迟。请使用 pingcode_test_case_get 按返回 ID 回读，确认成功前禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: lastError });
+}
+function isTestCaseReadConsistencyError(error) {
+    if (!(error instanceof PingCodeError))
+        return false;
+    return error.code === "NOT_FOUND" || /100601|尚未可见|尚未可見/i.test(error.message);
+}
+async function waitForReadConsistency(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+//# sourceMappingURL=sync.js.map