@xurenxiang1219/pingcode-mcp 0.3.1

package/dist/mcp/tools/relation.js

@@ -0,0 +1,592 @@
+import * as z from "zod/v4";
+import { PingCodeError } from "../../pingcode/errors.js";
+import { contentHashSchema } from "../../domain/content-hash.js";
+import { isSupportedRelationWritePair, relationPrincipalResourceId, relationTargetResourceId, traceableResourceTypes, } from "../../sources/relation-source.js";
+import { requestHash as calculateRequestHash } from "../../write/plan.js";
+import { executeTool, requestIdForLog } from "../tool-runtime.js";
+import { paginationGuidance } from "../pagination-guidance.js";
+import { approvalTokenSchema, commitWithApproval, formatPreviewToolResult, formatWriteConfirmationMessage, formatWriteToolResult, requestClientWriteConfirmation, resolveCommitVerification, } from "../write-approval.js";
+const identifier = z.string().trim().min(1).max(200);
+const optionalIdentifier = z.preprocess((value) => typeof value === "string" && value.trim().length === 0 ? undefined : value, identifier.optional());
+const contentHash = contentHashSchema;
+const approvalContextId = z.string().uuid();
+const agentSessionId = z.string().trim().min(8).max(200).optional();
+const relationTypeSchema = z.enum(traceableResourceTypes).describe("官方 Relation 资源类型；读取可见 ticket、test_plan、test_run，写入仍受 MCP 受控组合限制");
+const relationListPrincipalTypeSchema = z.enum(traceableResourceTypes).describe("官方 Relation 查询主体类型；必须与 principal_id、target_type 组合使用");
+const relationListTargetTypeSchema = z.enum(["ticket", "work_item", "test_case", "idea", "page"]).describe("官方 Relation 查询目标类型；必须与 principal_type、principal_id 组合使用");
+const writablePrincipalTypeSchema = z.enum(["idea", "work_item", "test_case"]);
+const sourceReferenceSchema = z.object({
+    type: z.enum(["wiki", "task", "test_case", "spec", "plan", "code", "project", "ship_idea"]),
+    id: identifier,
+    content_hash: contentHash.optional(),
+}).strict();
+const relationCreateFieldsSchema = z.object({
+    principal_type: writablePrincipalTypeSchema,
+    principal_id: optionalIdentifier.describe("主体 ID；与 principal_name 二选一"),
+    principal_name: optionalIdentifier.describe("主体名称或标识；与 principal_id 二选一"),
+    target_type: relationTypeSchema,
+    target_id: optionalIdentifier.describe("目标 ID；与 target_name 二选一"),
+    target_name: optionalIdentifier.describe("目标名称或标识；与 target_id 二选一"),
+}).strict().superRefine((value, context) => {
+    const requireExactlyOne = (left, right, path, message) => {
+        if ((left === undefined) === (right === undefined)) {
+            context.addIssue({ code: "custom", path: [path], message });
+        }
+    };
+    requireExactlyOne(value.principal_id, value.principal_name, "principal_id", "principal_id 与 principal_name 必须且只能提供一个");
+    requireExactlyOne(value.target_id, value.target_name, "target_id", "target_id 与 target_name 必须且只能提供一个");
+});
+// Keep delete inputs in one object. A union of eight mutually-exclusive objects
+// produces `not: {}` in the public JSON Schema, which some MCP clients reject
+// before the request reaches the server.
+const relationDeleteFieldsSchema = z.object({
+    relation_id: optionalIdentifier.describe("Relation 内部 ID；直接使用 pingcode_relation_get 或 pingcode_relation_list 返回的 id"),
+    relation_name: optionalIdentifier.describe("兼容别名；官方没有独立 Relation 名称时请传 Relation ID"),
+    // 官方 Relation 没有独立的可复用名称；省略端点期望值时由详情回读补齐，
+    // Preview／Commit 仍会绑定并核对端点快照。
+    expected_principal_type: writablePrincipalTypeSchema.optional(),
+    expected_principal_id: optionalIdentifier.describe("预期主体 ID；与 expected_principal_name 二选一"),
+    expected_principal_name: optionalIdentifier.describe("预期主体名称或标识；与 expected_principal_id 二选一"),
+    expected_target_type: relationTypeSchema.optional(),
+    expected_target_id: optionalIdentifier.describe("预期目标 ID；与 expected_target_name 二选一"),
+    expected_target_name: optionalIdentifier.describe("预期目标名称或标识；与 expected_target_id 二选一"),
+}).strict().superRefine((value, context) => {
+    const requireAtMostOne = (left, right, path, message) => {
+        if (left !== undefined && right !== undefined) {
+            context.addIssue({ code: "custom", path: [path], message });
+        }
+    };
+    if (value.relation_id === undefined && value.relation_name === undefined) {
+        context.addIssue({ code: "custom", path: ["relation_id"], message: "relation_id 必须提供；官方 Relation 没有独立名称" });
+    }
+    requireAtMostOne(value.relation_id, value.relation_name, "relation_id", "relation_id 与 relation_name 不得同时提供");
+    requireAtMostOne(value.expected_principal_id, value.expected_principal_name, "expected_principal_id", "expected_principal_id 与 expected_principal_name 不得同时提供");
+    requireAtMostOne(value.expected_target_id, value.expected_target_name, "expected_target_id", "expected_target_id 与 expected_target_name 不得同时提供");
+    if ((value.expected_principal_id !== undefined || value.expected_principal_name !== undefined) && value.expected_principal_type === undefined) {
+        context.addIssue({ code: "custom", path: ["expected_principal_type"], message: "提供预期主体引用时必须同时提供 expected_principal_type" });
+    }
+    if ((value.expected_target_id !== undefined || value.expected_target_name !== undefined) && value.expected_target_type === undefined) {
+        context.addIssue({ code: "custom", path: ["expected_target_type"], message: "提供预期目标引用时必须同时提供 expected_target_type" });
+    }
+});
+const createOperationSchema = z.object({
+    operation_id: identifier.describe("关联计划内唯一操作 ID"),
+    action: z.literal("create"),
+    fields: relationCreateFieldsSchema,
+    source_references: z.array(sourceReferenceSchema).min(1).max(20),
+}).strict();
+const deleteOperationSchema = z.object({
+    operation_id: identifier.describe("关联计划内唯一操作 ID"),
+    action: z.literal("delete"),
+    fields: relationDeleteFieldsSchema,
+    source_references: z.array(sourceReferenceSchema).min(1).max(20),
+}).strict();
+// Create and delete stay separate so the public JSON Schema has a clear action discriminator.
+const relationOperationSchema = z.union([createOperationSchema, deleteOperationSchema]);
+const relationPlanSchema = z.object({
+    plan_id: identifier.describe("关联同步计划 ID；Preview 与 Commit 必须完全相同"),
+    operations: z.array(relationOperationSchema).length(1).describe("一次计划只处理一个 Relation，避免非原子批量写入造成部分成功"),
+}).strict();
+const readAnnotations = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export function registerRelationTools(server, services, logger, runtime, writeApprovalMode) {
+    server.registerTool("pingcode_relation_list", {
+        title: "列出 PingCode 资源关联",
+        description: "按官方 Relation 的强关联参数读取关联。必须提供 principal_type 和 target_type，并在 principal_id 与 principal_name 中恰好选择一个；不要同时传入 ID 和名称。名称解析仅对当前已接入的 Idea、Work Item、Test Case 和 Wiki Page 提供；ticket、test_plan、test_run 只能使用已取得的资源 ID。分页参数可选；只返回可读摘要，不展示原始 JSON。",
+        inputSchema: {
+            principal_type: relationListPrincipalTypeSchema.optional().describe("Relation 主体资源类型；缺少时先明确主体类型，例如 work_item、test_case 或 idea"),
+            principal_id: identifier.optional().describe("Relation 主体资源 ID；来自主体资源列表/详情，名称入口使用 principal_name"),
+            principal_name: identifier.optional(),
+            target_type: relationListTargetTypeSchema.optional().describe("Relation 目标资源类型；缺少时先明确目标类型，例如 test_case、idea 或 page"),
+            page_index: z.number().int().min(0).optional(),
+            page_size: z.number().int().min(1).max(100).optional(),
+        },
+        annotations: readAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_relation_list", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { resourceId: input.principal_id ?? "", targetType: input.target_type ?? "" }, async () => {
+        if (input.principal_type === undefined || input.target_type === undefined) {
+            throw new PingCodeError("缺少 principal_type 或 target_type；请先明确 Relation 主体和目标资源类型，再调用本 Tool", "BAD_REQUEST");
+        }
+        if (input.principal_id === undefined && input.principal_name === undefined) {
+            throw new PingCodeError("principal_id 与 principal_name 必须提供一个；并且必须同时提供 target_type", "BAD_REQUEST");
+        }
+        if (input.principal_id !== undefined && input.principal_name !== undefined) {
+            throw new PingCodeError("principal_id 与 principal_name 不得同时提供", "BAD_REQUEST");
+        }
+        const principalId = input.principal_id ?? await resolveResourceReference(input.principal_type, undefined, input.principal_name, services);
+        const page = await services.getRelationSource().listRelations({
+            principalType: input.principal_type,
+            principalId,
+            targetType: input.target_type,
+            pageIndex: input.page_index,
+            pageSize: input.page_size,
+        });
+        return {
+            pageSize: page.page_size,
+            pageIndex: page.page_index,
+            total: page.total,
+            relations: page.values.map(mapRelation),
+        };
+    }, { formatResult: formatRelationList }));
+    server.registerTool("pingcode_relation_get", {
+        title: "读取 PingCode 资源关联",
+        description: "读取一个明确的 PingCode Relation，并返回官方响应中的主体、目标类型及资源 ID。此操作为只读。",
+        inputSchema: {
+            relation_id: optionalIdentifier.describe("必须来自 pingcode_relation_list 或 Relation Commit 返回的 Relation ID；缺少时先调用 pingcode_relation_list，Relation 没有独立名称入口"),
+        },
+        annotations: readAnnotations,
+    }, async (input, extra) => executeTool(logger, "pingcode_relation_get", requestIdForLog(extra.requestInfo?.headers["x-request-id"], extra.requestId), { resourceId: input.relation_id ?? "" }, async () => {
+        if (input.relation_id === undefined) {
+            throw new PingCodeError("缺少 relation_id；请先调用 pingcode_relation_list 获取关联候选，再传入用户选定的 Relation ID", "BAD_REQUEST");
+        }
+        return mapRelation(await services.getRelationSource().getRelation(input.relation_id));
+    }, { formatResult: formatRelation }));
+    server.registerTool("pingcode_relation_sync_preview", {
+        title: "预览同步 PingCode 资源关联",
+        description: "预览建立或移除当前 MCP 已批准组合中的 Idea、工作项、Test Case 与 Wiki 页面 Relation，不写入 PingCode。创建 Relation 的最小输入是 plan_id、operations[action=create]、fields.principal_type、fields.target_type、主体/目标各自的 id 或 name（二选一）以及 operation 内的 source_references。每个 operations 元素必须是 JSON 对象；fields 也必须是对象，例如 create 的 fields 为 {principal_type, principal_name, target_type, target_name}，不能把 fields 序列化成字符串。建立关系时 principal_id 与 principal_name 二选一，target_id 与 target_name 二选一，不能同时提供；名称应来自对应列表/详情候选，无法唯一匹配时返回候选并等待用户选择。删除时 MCP 以 pingcode_relation_get 返回的 principal -> target 为 canonical 方向；若客户端传入了相反端点，MCP 会先按 Relation 详情规范化后再校验。source_references 是 operations 元素内与 fields 同级的必填数组，不放在 fields 或计划顶层。官方还存在 ticket、test_plan、test_run 类型，但本 Tool 不未经验证开放这些类型写入；页面仅可作为新关联的目标。一次计划只允许一个操作。不得在正常用户回复中展示内部 hash、Approval Context、会话绑定、evidence 或幂等字段。",
+        inputSchema: {
+            ...relationPlanSchema.shape,
+            plan_id: relationPlanSchema.shape.plan_id.optional().describe("业务上必填；省略仅用于返回缺参引导"),
+            operations: relationPlanSchema.shape.operations.optional().describe("业务上必填且一次只处理一个 Relation；省略仅用于返回缺参引导"),
+            agent_session_id: agentSessionId,
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_relation_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；请补充 Relation 同步计划后重试 Preview", "BAD_REQUEST");
+        }
+        return previewRelationPlan({ plan_id: input.plan_id, operations: input.operations }, services, runtime, input.agent_session_id, extra.authInfo);
+    }, { formatResult: formatPreviewToolResult }));
+    server.registerTool("pingcode_relation_sync_commit", {
+        title: "提交同步 PingCode 资源关联",
+        description: "依已核准的 Preview 建立或移除一个 PingCode Relation。Commit 必须原样复用 Preview 请求中的计划和内部验证字段；删除前会再次核对 Relation 的主体与目标，写入后由 MCP 回读验证。",
+        inputSchema: {
+            ...relationPlanSchema.shape,
+            agent_session_id: agentSessionId,
+            preview_id: approvalContextId.optional().describe("可选。省略时 Server 依相同 plan_id 与 operations 自动匹配刚才的 Preview，并据此恢复 request hash、evidence hash、session binding 和幂等边界；仅当客户端确实读到 Preview 的 approvalContextId 时才需要传入"),
+            approval_context_id: approvalContextId.optional().describe("已弃用，等同 preview_id；新调用只传 preview_id"),
+            approval_token: approvalTokenSchema(writeApprovalMode),
+            idempotency_key: identifier.min(16).max(200).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (input, extra) => executeTool(logger, "pingcode_relation_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: calculateRequestHash({ plan_id: input.plan_id, operations: input.operations }),
+            agentSessionId: input.agent_session_id,
+            authInfo: extra.authInfo,
+        }, "relation");
+        const resolvedInput = {
+            ...input,
+            request_hash: verification.requestHash,
+            approval_context_id: verification.approvalContextId,
+            session_binding: verification.sessionBinding,
+            evidence_hash: verification.evidenceHash,
+            idempotency_key: verification.idempotencyKey,
+        };
+        const prepared = await prepareOperation(await resolveRelationOperation(resolvedInput.operations[0], services), services);
+        await requestClientWriteConfirmation(server, logger, writeApprovalMode, input.approval_token, formatRelationConfirmation(prepared), runtime.requiresConfirmation([prepared.operation.action]));
+        return commitRelationPlan(resolvedInput, prepared, services, runtime, writeApprovalMode, extra.authInfo);
+    }, { formatResult: formatWriteToolResult }));
+}
+async function previewRelationPlan(input, services, runtime, agentSessionIdValue, authInfo) {
+    const operation = input.operations[0];
+    if (!operation) {
+        throw new PingCodeError("Relation 计划不能为空", "BAD_REQUEST");
+    }
+    const prepared = await prepareOperation(await resolveRelationOperation(operation, services), services);
+    const displayOperation = relationDisplayOperation(prepared);
+    const plan = { plan_id: input.plan_id, operations: input.operations };
+    const requestHash = calculateRequestHash(plan);
+    const evidenceHash = calculateRequestHash({ planId: input.plan_id, requestHash, operations: [displayOperation] });
+    const context = await runtime.createApprovalContext({
+        resourceType: "relation",
+        requestHash,
+        evidenceHash,
+        ...(agentSessionIdValue === undefined ? {} : { agentSessionId: agentSessionIdValue }),
+        ...(authInfo === undefined ? {} : { authInfo }),
+    });
+    return {
+        planId: input.plan_id,
+        requestHash,
+        approvalContextId: context.approvalContextId,
+        sessionBinding: context.sessionBinding,
+        evidenceHash,
+        approvalExpiresAt: context.expiresAt,
+        counts: { creates: 0, updates: 0, relations: 1 },
+        warnings: prepared.target.type === "page"
+            ? ["Wiki 页面是关联目标；官方 Open API 不开放以页面为主体创建反向关联"]
+            : [],
+        operations: [displayOperation],
+    };
+}
+async function commitRelationPlan(input, prepared, services, runtime, writeApprovalMode, authInfo) {
+    const plan = { plan_id: input.plan_id, operations: input.operations };
+    if (calculateRequestHash(plan) !== input.request_hash) {
+        throw new PingCodeError("Commit 内容与 Relation Preview request hash 不一致", "CONFLICT");
+    }
+    const displayOperation = relationDisplayOperation(prepared);
+    const evidenceHash = calculateRequestHash({
+        planId: input.plan_id,
+        requestHash: input.request_hash,
+        operations: [displayOperation],
+    });
+    if (evidenceHash !== input.evidence_hash) {
+        throw new PingCodeError("Relation Preview 绑定的资源内容或端点已发生变化，当前 evidence hash 已过期；请重新执行 pingcode_relation_sync_preview 后再 Commit", "CONFLICT");
+    }
+    const committed = await commitWithApproval(runtime, writeApprovalMode, {
+        resourceType: "relation",
+        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: [input.operations[0]?.action ?? "create"],
+        action: async () => {
+            if (prepared.operation.action === "create") {
+                const fields = prepared.operation.fields;
+                if (!fields.principal_id || !fields.target_id)
+                    throw new PingCodeError("Relation 主体或目标尚未解析", "BAD_REQUEST");
+                const created = await services.getRelationSource().createRelation({
+                    principalType: fields.principal_type,
+                    principalId: fields.principal_id,
+                    targetType: fields.target_type,
+                    targetId: fields.target_id,
+                });
+                const verified = await services.getRelationSource().getRelation(created.id).catch((error) => {
+                    throw new PingCodeError(`Relation ${created.id} 已创建，但 MCP 回读失败；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: error });
+                });
+                try {
+                    assertRelationMatches(verified, fields.principal_type, fields.principal_id, fields.target_type, fields.target_id);
+                }
+                catch (error) {
+                    throw new PingCodeError(`Relation ${created.id} 已创建，但 MCP 回读结果与计划不一致；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: error });
+                }
+                return relationCommitResult(input.plan_id, prepared, created.id);
+            }
+            const relationId = prepared.operation.fields.relation_id;
+            if (!relationId)
+                throw new PingCodeError("Relation ID 尚未解析", "BAD_REQUEST");
+            await services.getRelationSource().deleteRelation(relationId);
+            try {
+                await services.getRelationSource().getRelation(relationId);
+            }
+            catch (error) {
+                // Some PingCode tenants return BAD_REQUEST rather than NOT_FOUND for
+                // a Relation that was just deleted. The DELETE already succeeded, so
+                // a 400 on the same resource is a confirmed absence, not uncertainty.
+                if (error instanceof PingCodeError &&
+                    (error.code === "NOT_FOUND" || (error.code === "BAD_REQUEST" && error.options.status === 400))) {
+                    return relationCommitResult(input.plan_id, prepared, relationId);
+                }
+                throw new PingCodeError(`Relation ${relationId} 的删除请求已发送，但 MCP 无法确认删除结果；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN", { cause: error });
+            }
+            throw new PingCodeError(`Relation ${relationId} 的删除请求已发送，但回读时仍存在；禁止更换幂等键重试`, "WRITE_OUTCOME_UNKNOWN");
+        },
+    });
+    return {
+        ...committed.result,
+        replayed: committed.replayed,
+        approvedBy: committed.approval.approvedBy,
+        auditId: committed.auditId,
+    };
+}
+async function prepareOperation(operation, services) {
+    if (operation.action === "create") {
+        const fields = operation.fields;
+        if (!fields.principal_id || !fields.target_id)
+            throw new PingCodeError("Relation 主体或目标尚未解析", "BAD_REQUEST");
+        assertSupportedPair(fields.principal_type, fields.target_type);
+        const [principal, target, existing] = await Promise.all([
+            services.getRelationSource().readResource(fields.principal_type, fields.principal_id),
+            services.getRelationSource().readResource(fields.target_type, fields.target_id),
+            services.getRelationSource().findExactRelation({
+                principalType: fields.principal_type,
+                principalId: fields.principal_id,
+                targetType: fields.target_type,
+                targetId: fields.target_id,
+            }),
+        ]);
+        if (existing) {
+            throw new PingCodeError(`Relation ${existing.id} 已存在，不会重复建立`, "CONFLICT");
+        }
+        assertSupportedWorkItemTypes(principal, target);
+        return { operation, existing: null, principal, target };
+    }
+    const fields = operation.fields;
+    if (!fields.relation_id || !fields.expected_principal_type || !fields.expected_principal_id || !fields.expected_target_type || !fields.expected_target_id)
+        throw new PingCodeError("Relation 删除引用尚未解析", "BAD_REQUEST");
+    assertSupportedPair(fields.expected_principal_type, fields.expected_target_type);
+    const existing = await services.getRelationSource().getRelation(fields.relation_id);
+    assertRelationMatches(existing, fields.expected_principal_type, fields.expected_principal_id, fields.expected_target_type, fields.expected_target_id);
+    const [principal, target] = await Promise.all([
+        services.getRelationSource().readResource(fields.expected_principal_type, fields.expected_principal_id),
+        services.getRelationSource().readResource(fields.expected_target_type, fields.expected_target_id),
+    ]);
+    assertSupportedWorkItemTypes(principal, target);
+    return { operation, existing, principal, target };
+}
+function assertSupportedWorkItemTypes(principal, target) {
+    for (const [role, resource] of [["主体", principal], ["目标", target]]) {
+        if (resource.type !== "work_item")
+            continue;
+        const workItemType = resource.workItemType?.trim().toLocaleLowerCase();
+        if (workItemType === "story" || workItemType === "bug")
+            continue;
+        throw new PingCodeError(`Relation ${role}工作项类型 ${resource.workItemType ?? "未知"} 不受支持；仅允许 story 或 bug`, "BAD_REQUEST");
+    }
+}
+async function resolveRelationOperation(operation, services) {
+    if (operation.action === "create") {
+        const fields = { ...operation.fields };
+        fields.principal_id = await resolveResourceReference(fields.principal_type, fields.principal_id, fields.principal_name, services);
+        fields.target_id = await resolveResourceReference(fields.target_type, fields.target_id, fields.target_name, services);
+        delete fields.principal_name;
+        delete fields.target_name;
+        return { ...operation, fields };
+    }
+    const fields = { ...operation.fields };
+    // A Relation has no separate name in the official response. Use its ID as
+    // the canonical selector and hydrate omitted endpoint expectations from the
+    // same server-side detail response.
+    fields.relation_id ??= fields.relation_name;
+    if (fields.relation_id === undefined) {
+        throw new PingCodeError("Relation 缺少 relation_id", "BAD_REQUEST");
+    }
+    const relation = await services.getRelationSource().getRelation(fields.relation_id);
+    normalizeRelationEndpointDirection(fields, relation);
+    fields.expected_principal_type ??= relation.principal_type;
+    fields.expected_target_type ??= relation.target_type;
+    fields.expected_principal_id ??= relationPrincipalResourceId(relation);
+    fields.expected_target_id ??= relationTargetResourceId(relation);
+    if (!fields.expected_principal_type || !fields.expected_target_type || !fields.expected_principal_id || !fields.expected_target_id) {
+        throw new PingCodeError("Relation 详情未返回完整主体或目标，不能安全删除", "INVALID_RESPONSE");
+    }
+    fields.expected_principal_id = await resolveResourceReference(fields.expected_principal_type, fields.expected_principal_id, fields.expected_principal_name, services);
+    fields.expected_target_id = await resolveResourceReference(fields.expected_target_type, fields.expected_target_id, fields.expected_target_name, services);
+    delete fields.relation_name;
+    delete fields.expected_principal_name;
+    delete fields.expected_target_name;
+    return { ...operation, fields };
+}
+function normalizeRelationEndpointDirection(fields, relation) {
+    const principalType = relation.principal_type;
+    const targetType = relation.target_type;
+    const principalId = relationPrincipalResourceId(relation);
+    const targetId = relationTargetResourceId(relation);
+    if (fields.expected_principal_type === targetType &&
+        fields.expected_target_type === principalType &&
+        fields.expected_principal_id === targetId &&
+        fields.expected_target_id === principalId) {
+        fields.expected_principal_type = principalType;
+        fields.expected_principal_id = principalId;
+        fields.expected_target_type = targetType;
+        fields.expected_target_id = targetId;
+    }
+}
+async function resolveResourceReference(type, value, name, services) {
+    if (value !== undefined) {
+        const resource = await services.getRelationSource().readResource(type, value);
+        return resource.id;
+    }
+    if (name === undefined)
+        throw new PingCodeError(`${type} 缺少名称或 ID`, "BAD_REQUEST");
+    const candidates = [];
+    if (type === "idea") {
+        for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+            const page = await services.getShipSource().listIdeas({ keywords: name, pageIndex, pageSize: 100 });
+            candidates.push(...page.values.map((item) => ({ id: item.id, name: item.title, identifier: item.identifier })));
+            if (candidates.length >= page.total || page.values.length === 0)
+                break;
+        }
+    }
+    else if (type === "work_item") {
+        for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+            const page = await services.getTaskSource().listWorkItems({ keywords: name, pageIndex, pageSize: 100 });
+            candidates.push(...page.values.map((item) => ({ id: item.id, name: item.title, identifier: item.identifier })));
+            if (candidates.length >= page.total || page.values.length === 0)
+                break;
+        }
+    }
+    else if (type === "test_case") {
+        for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+            const page = await services.getTestCaseSource().listTestCases({ keywords: name, pageIndex, pageSize: 100 });
+            candidates.push(...page.values.map((item) => ({ id: item.id, name: item.title, identifier: item.identifier })));
+            if (candidates.length >= page.total || page.values.length === 0)
+                break;
+        }
+    }
+    else if (type === "page") {
+        for (let pageIndex = 0; pageIndex < 100; pageIndex += 1) {
+            const page = await services.getWikiSource().listPages({ pageIndex, pageSize: 100 });
+            candidates.push(...page.values.map((item) => ({ id: item.id, name: item.name, identifier: item.short_id })));
+            if (candidates.length >= page.total || page.values.length === 0)
+                break;
+        }
+    }
+    else {
+        throw new PingCodeError(`${type} 尚未接入 MCP 资源目录，不能按名称解析；请提供前序 Relation Tool 返回的资源 ID`, "BAD_REQUEST");
+    }
+    return resolveReferenceName(type, name, candidates);
+}
+function resolveReferenceName(field, name, candidates) {
+    const normalized = name.trim().toLocaleLowerCase();
+    const matches = candidates.filter((candidate) => candidate.name.trim().toLocaleLowerCase() === normalized || candidate.identifier?.trim().toLocaleLowerCase() === normalized);
+    if (matches.length === 1)
+        return matches[0].id;
+    if (matches.length > 1)
+        throw new PingCodeError(`${field} 名称匹配多个候选，请选择一个`, "CONFLICT");
+    throw new PingCodeError(`${field} 名称没有匹配结果：${name}`, "NOT_FOUND");
+}
+function assertSupportedPair(principalType, targetType) {
+    if (!isSupportedRelationWritePair(principalType, targetType)) {
+        throw new PingCodeError(`官方 Open API 不支持或本 MCP 未批准建立 ${principalType} -> ${targetType} 关联；页面只能作为目标`, "BAD_REQUEST");
+    }
+}
+function assertRelationMatches(relation, principalType, principalId, targetType, targetId) {
+    if (relation.principal_type !== principalType ||
+        relationPrincipalResourceId(relation) !== principalId ||
+        relation.target_type !== targetType ||
+        relationTargetResourceId(relation) !== targetId) {
+        throw new PingCodeError(`Relation ${relation.id} 的主体或目标与 Preview 计划不一致，未执行写入`, "CONFLICT");
+    }
+}
+function relationDisplayOperation(prepared) {
+    const create = prepared.operation.action === "create";
+    return {
+        operationId: prepared.operation.operation_id,
+        action: prepared.operation.action,
+        targetId: prepared.existing?.id ?? null,
+        changes: {
+            relation: {
+                before: create ? null : `Relation ${prepared.existing?.id ?? ""}：${relationLabel(prepared.principal, prepared.target)}`,
+                after: create ? relationLabel(prepared.principal, prepared.target) : null,
+            },
+            principal: { before: resourceLabel(prepared.principal), after: resourceLabel(prepared.principal) },
+            target: { before: resourceLabel(prepared.target), after: resourceLabel(prepared.target) },
+        },
+        sourceReferences: prepared.operation.source_references,
+    };
+}
+function relationCommitResult(planId, prepared, relationId) {
+    return {
+        planId,
+        resources: [{
+                operationId: prepared.operation.operation_id,
+                action: prepared.operation.action,
+                id: relationId,
+                title: relationLabel(prepared.principal, prepared.target),
+                verified: true,
+            }],
+    };
+}
+function mapRelation(relation) {
+    const principalType = relationTypeSchema.parse(relation.principal_type);
+    const targetType = relationTypeSchema.parse(relation.target_type);
+    const principalId = relationPrincipalResourceId(relation);
+    const targetId = relationTargetResourceId(relation);
+    if (!principalId || !targetId) {
+        throw new PingCodeError(`Relation ${relation.id} 未返回完整主体或目标 ID`, "INVALID_RESPONSE");
+    }
+    return {
+        id: relation.id,
+        principalType,
+        principalId,
+        principal: relationResourceLabel(relation.principal),
+        targetType,
+        targetId,
+        target: relationResourceLabel(relation.target),
+    };
+}
+function relationResourceLabel(value) {
+    if (value === undefined)
+        return null;
+    return {
+        id: value.id,
+        name: typeof value.name === "string"
+            ? value.name
+            : typeof value.title === "string"
+                ? value.title
+                : null,
+        identifier: typeof value.identifier === "string"
+            ? value.identifier
+            : typeof value.short_id === "string"
+                ? value.short_id
+                : null,
+    };
+}
+function formatRelationList(result) {
+    const lines = [`PingCode 资源关联：${result.total} 个`];
+    for (const relation of result.relations) {
+        const principalLabel = relationDisplayLabel(relation.principal, relation.principalId);
+        const targetLabel = relationDisplayLabel(relation.target, relation.targetId);
+        lines.push(`- ${relation.id}：${typeLabel(relation.principalType)} ${principalLabel} -> ${typeLabel(relation.targetType)} ${targetLabel}`);
+    }
+    lines.push(...paginationGuidance({
+        pageIndex: result.pageIndex ?? 0,
+        pageSize: result.pageSize ?? Math.max(result.relations.length, 1),
+        total: result.total,
+        returned: result.relations.length,
+        searchable: false,
+    }));
+    return lines.join("\n");
+}
+function formatRelation(result) {
+    const principalLabel = relationDisplayLabel(result.principal, result.principalId);
+    const targetLabel = relationDisplayLabel(result.target, result.targetId);
+    return [
+        "已读取 PingCode 资源关联",
+        `- Relation ID：${result.id}`,
+        `- 主体：${typeLabel(result.principalType)} ${principalLabel}`,
+        `- 目标：${typeLabel(result.targetType)} ${targetLabel}`,
+    ].join("\n");
+}
+function relationDisplayLabel(resource, fallbackId) {
+    if (resource === null)
+        return fallbackId;
+    const displayName = resource.name ?? resource.identifier;
+    if (displayName === null)
+        return fallbackId;
+    const identifier = resource.name !== null && resource.identifier !== null
+        ? ` (${resource.identifier})`
+        : "";
+    return `${displayName}${identifier} [${resource.id}]`;
+}
+function formatRelationConfirmation(prepared) {
+    return formatWriteConfirmationMessage(prepared.operation.action === "create" ? "即将在 PingCode 建立资源关联" : "即将在 PingCode 移除资源关联", [
+        `操作：${prepared.operation.action === "create" ? "建立 Relation" : "移除已确认 Relation"}`,
+        `主体：${resourceLabel(prepared.principal)}`,
+        `目标：${resourceLabel(prepared.target)}`,
+    ]);
+}
+function relationLabel(principal, target) {
+    return `${resourceLabel(principal)} -> ${resourceLabel(target)}`;
+}
+function resourceLabel(resource) {
+    return `${typeLabel(resource.type)}「${resource.title}」${resource.identifier ? ` (${resource.identifier})` : ""}`;
+}
+function typeLabel(type) {
+    if (type === "idea")
+        return "产品需求";
+    if (type === "ticket")
+        return "工单";
+    if (type === "work_item")
+        return "工作项";
+    if (type === "test_plan")
+        return "测试计划";
+    if (type === "test_run")
+        return "测试执行";
+    if (type === "test_case")
+        return "测试用例";
+    return "Wiki 页面";
+}
+//# sourceMappingURL=relation.js.map