taskmeld 0.1.1

package/dist/src/pipeline/structured-output/prompt.js

@@ -0,0 +1,290 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildExternalPipelineArtifactInput = exports.createNodeCorrectionPrompt = exports.createNodeExecutionPrompt = exports.buildDependencyArtifactInputs = void 0;
+const promises_1 = require("node:fs/promises");
+const node_crypto_1 = require("node:crypto");
+const node_path_1 = require("node:path");
+const parser_1 = require("./parser");
+const guards_1 = require("../../utils/guards");
+const MAINLINE_ROUTE_VALUE = "yes";
+const buildDependencyArtifactInputs = async (run, node, itemKey, dependencyIds) => {
+    const inputs = [];
+    const effectiveDependencyIds = dependencyIds?.length ? dependencyIds : node.dependsOn;
+    for (const depId of effectiveDependencyIds) {
+        const depNode = run.nodes.find((n) => n.id === depId);
+        const depGroup = run.groups?.find((g) => g.id === depId);
+        const depItem = itemKey ? run.itemRuns?.find((item) => item.nodeId === depId && item.itemKey === itemKey) : null;
+        const depGroupItem = itemKey ? run.groupItemRuns?.find((item) => item.groupId === depId && item.itemKey === itemKey) : null;
+        const depSource = depNode
+            ? {
+                id: depNode.id,
+                title: depNode.title,
+                agentId: depNode.executor.agentId,
+                artifacts: depItem?.artifacts?.length ? depItem.artifacts : depNode.artifacts,
+                route: depItem?.route ?? null,
+            }
+            : depGroup
+                ? {
+                    id: depGroup.id,
+                    title: depGroup.title,
+                    agentId: depGroup.id,
+                    artifacts: depGroupItem?.artifacts?.length ? depGroupItem.artifacts : depGroup.artifacts,
+                    route: null,
+                }
+                : null;
+        if (!depSource || depSource.artifacts.length === 0)
+            continue;
+        const loaded = await Promise.all(depSource.artifacts.map(async (manifest) => {
+            try {
+                const raw = await (0, promises_1.readFile)(manifest.path, "utf8");
+                const parsed = JSON.parse(raw);
+                const obj = (0, guards_1.isRecord)(parsed) ? parsed : null;
+                const artifact = obj && (0, guards_1.isRecord)(obj.artifact) ? obj.artifact : null;
+                const rawContent = artifact ? artifact.content : raw;
+                const content = depSource.route &&
+                    Array.isArray(rawContent) &&
+                    rawContent.some((entry) => (0, guards_1.isRecord)(entry) && typeof entry.route === "string")
+                    ? rawContent.filter((entry) => (0, guards_1.isRecord)(entry) && typeof entry.route === "string" && entry.route.trim() === depSource.route)
+                    : rawContent;
+                const meta = (0, guards_1.isRecord)(artifact?.meta) ? artifact.meta : undefined;
+                return {
+                    sourceNodeId: depSource.id,
+                    sourceNodeTitle: depSource.title,
+                    sourceAgentId: depSource.agentId,
+                    type: manifest.type,
+                    schemaVersion: manifest.schemaVersion,
+                    name: manifest.name,
+                    path: manifest.path,
+                    hash: manifest.hash,
+                    createdAt: manifest.createdAt,
+                    content: (0, parser_1.toPromptContentText)(content),
+                    meta,
+                };
+            }
+            catch {
+                return {
+                    sourceNodeId: depSource.id,
+                    sourceNodeTitle: depSource.title,
+                    sourceAgentId: depSource.agentId,
+                    type: manifest.type,
+                    schemaVersion: manifest.schemaVersion,
+                    name: manifest.name,
+                    path: manifest.path,
+                    hash: manifest.hash,
+                    createdAt: manifest.createdAt,
+                    content: "[artifact_read_failed]",
+                };
+            }
+        }));
+        for (const item of loaded) {
+            if (item)
+                inputs.push(item);
+        }
+    }
+    return inputs;
+};
+exports.buildDependencyArtifactInputs = buildDependencyArtifactInputs;
+const createNodeExecutionPrompt = (ctx) => {
+    const spec = ctx.outputSpec;
+    const isRouteNode = ctx.allowedRoutes.length > 0;
+    const groupedDependencies = (() => {
+        const grouped = new Map();
+        for (const artifact of ctx.dependencyArtifacts) {
+            const key = `${artifact.sourceNodeId}|${artifact.sourceAgentId}`;
+            const current = grouped.get(key);
+            if (current) {
+                current.contents.push(artifact.content);
+                continue;
+            }
+            grouped.set(key, {
+                sourceNodeId: artifact.sourceNodeId,
+                sourceNodeTitle: artifact.sourceNodeTitle,
+                sourceAgentId: artifact.sourceAgentId,
+                contents: [artifact.content],
+            });
+        }
+        return Array.from(grouped.values());
+    })();
+    const lines = [
+        "# 流水线节点执行指令",
+        "",
+        "## 输出要求",
+        "- 只能返回一个合法 JSON 对象（ResultEnvelope）。",
+        "- 不要输出任何额外解释、前后缀、Markdown 之外的文本。",
+        "- `status=success` 时，`artifacts` 必须至少 1 条。",
+        "- `artifacts[].content` 支持任意 JSON 值（例如：`\"text\"`、`{\"k\":\"v\"}`、`[{\"k\":\"v1\"},{\"k\":\"v2\"}]`）。",
+        ...(isRouteNode ? ["- 分流节点的 `artifacts[0].content` 必须是数组，数组内每个对象都要包含 `route` 字段。"] : []),
+        "",
+        "## ResultEnvelope 固定字段",
+        `- version: \`2.0\``,
+        `- runId: \`${ctx.runId}\``,
+        `- nodeId: \`${ctx.nodeId}\``,
+        `- requestId: \`${ctx.requestId}\``,
+        `- sessionId: \`${ctx.sessionId}\``,
+        "- status: `success | failed`",
+        "- artifacts: `array`",
+        "",
+        "## 节点上下文",
+        `- 当前节点: \`${ctx.nodeId}\`（${ctx.nodeTitle}）`,
+        `- 依赖节点: ${ctx.dependencies.length > 0 ? ctx.dependencies.map((id) => `\`${id}\``).join(", ") : "`none`"}`,
+    ];
+    lines.push("", "## 产物规格", `- type: \`${spec.type}\``, `- schemaVersion: \`${spec.schemaVersion}\``);
+    // 仅在节点明确开启分流时，才注入分流相关说明，避免无配置时污染提示词。
+    if (ctx.allowedRoutes.length > 0) {
+        lines.push("", "## 分流规则", `- 允许的 route 仅能是: ${ctx.allowedRoutes.map((route) => `\`${route}\``).join(", ")}`, `- \`${MAINLINE_ROUTE_VALUE}\` 表示继续主线，不需要配置分流目标。`, "- `artifacts[0].content` 必须输出为数组。", "- 数组中的每个对象都必须包含 `route` 字段。", "- 每个对象的 `route` 必须命中上述取值。", "- 系统会按 `content[*].route` 自动分组、汇总并推送到对应分支。");
+        if (ctx.routeTargets.length > 0) {
+            lines.push("- 当前配置的 route 目标如下:");
+            for (const target of ctx.routeTargets) {
+                lines.push(`  - \`${target.route}\` -> \`${target.targetNodeId}\` (${target.targetNodeTitle}, agent:${target.targetAgentId}, lane:${target.lane})`);
+            }
+        }
+    }
+    // 仅在节点明确开启打回且存在上游依赖时，才注入打回相关说明，避免无配置时污染提示词。
+    if (ctx.allowReject && ctx.dependencies.length > 0) {
+        lines.push("", "## 打回配置", `- allowReject: \`${ctx.allowReject ? "true" : "false"}\``, `- maxRejectCount: \`${ctx.maxRejectCount}\``, "", "### 打回规则", "- 仅当上游内容不符合你的校验规范时，才允许打回。", "- 打回时必须返回 `status=failed`，且 `error.code=upstream_reject`。", "- 如需指定目标上游，可提供 `error.targets=[\"nodeId\"]`。", "- 不提供 `targets` 时，系统默认打回上一个直接上游节点。", "", "```json", "{\"code\":\"upstream_reject\",\"message\":\"打回原因\"}", "```");
+    }
+    if (isRouteNode) {
+        lines.push("", "## 分流节点 JSON 示例", "```json", JSON.stringify({
+            version: "2.0",
+            runId: "__RUN_ID__",
+            nodeId: "__NODE_ID__",
+            requestId: "__REQUEST_ID__",
+            sessionId: "__SESSION_ID__",
+            status: "success",
+            artifacts: [
+                {
+                    type: "__TYPE__",
+                    schemaVersion: 1,
+                    name: "primary",
+                    content: [
+                        { label: "A", route: "yes", value: "..." },
+                        { label: "B", route: "holo", value: "..." },
+                        { label: "C", route: "no", value: "..." },
+                    ],
+                    meta: {},
+                },
+            ],
+            control: {
+                sleepUntil: null,
+                retryFromNodeId: null,
+            },
+            logs: [],
+            error: null,
+        }, null, 2), "```");
+    }
+    else {
+        lines.push("", "## JSON 输出示例", "```json", JSON.stringify({
+            version: "2.0",
+            runId: "__RUN_ID__",
+            nodeId: "__NODE_ID__",
+            requestId: "__REQUEST_ID__",
+            sessionId: "__SESSION_ID__",
+            status: "success",
+            artifacts: [
+                {
+                    type: "__TYPE__",
+                    schemaVersion: 1,
+                    name: "primary",
+                    content: "artifact content",
+                    meta: {},
+                },
+            ],
+            control: {
+                sleepUntil: null,
+                retryFromNodeId: null,
+            },
+            logs: [],
+            error: null,
+        }, null, 2), "```");
+    }
+    lines.push("");
+    // External pipeline upstream artifact — injected before internal dependency artifacts
+    if (ctx.externalPipelineArtifact) {
+        const artifact = ctx.externalPipelineArtifact;
+        const fence = (0, parser_1.detectFenceLanguage)(artifact.content);
+        lines.push("## 外部流水线上游产物", "", `来源: 流水线 ${artifact.sourcePipelineId} 的最终输出`, "", "内容:", `\`\`\`${fence}`, artifact.content, "```");
+    }
+    if (groupedDependencies.length > 0) {
+        lines.push("## 上游输输出结构：");
+        for (const dep of groupedDependencies) {
+            const merged = dep.contents.join("\n");
+            const fence = (0, parser_1.detectFenceLanguage)(merged);
+            lines.push(`### 节点 \`${dep.sourceNodeId}\`（${dep.sourceNodeTitle}）- agent \`${dep.sourceAgentId}\``, `\`\`\`${fence}`, merged, "```");
+        }
+        lines.push("");
+    }
+    // 节点目标是执行 prompt 的核心约束，不能因为存在打回反馈或分流说明而被覆盖掉。
+    // 这里固定保留“节点目标”段，再额外追加反馈，避免分流节点提示词缺少主任务目标。
+    lines.push("## 节点目标", ctx.instruction || "请按节点职责完成任务");
+    if (ctx.rejectFeedbacks.length > 0) {
+        lines.push("", "## 下游打回反馈（请优先修正）");
+        for (const item of ctx.rejectFeedbacks) {
+            lines.push(`- ${item}`);
+        }
+    }
+    return lines.join("\n");
+};
+exports.createNodeExecutionPrompt = createNodeExecutionPrompt;
+const createNodeCorrectionPrompt = (ctx, lastViolation) => [
+    `结构校验未通过，错误码: ${lastViolation}`,
+    "请严格基于本次请求的固定字段重发完整 ResultEnvelope，不要沿用旧请求的顶层字段。",
+    `固定字段必须为: version="2.0", runId="${ctx.runId}", nodeId="${ctx.nodeId}", requestId="${ctx.requestId}", sessionId="${ctx.sessionId}"`,
+    `产物规格必须为: type="${ctx.outputSpec.type}", schemaVersion=${ctx.outputSpec.schemaVersion}`,
+    ctx.allowedRoutes && ctx.allowedRoutes.length > 0
+        ? `这是分流节点。允许的 route 只有: ${ctx.allowedRoutes.map((route) => `"${route}"`).join(", ")}。请把 route 写进 artifacts[0].content 的每个对象里。`
+        : ctx.externalPipelineArtifact
+            ? `本次请求包含来自流水线 ${ctx.externalPipelineArtifact.sourcePipelineId} 的外部上游产物。请继续基于该上游产物修正。`
+            : "请按当前结构输出结果。",
+    "请先把完整 ResultEnvelope 保存为当前工作目录下的 result.json，然后自行运行下面的校验命令，确认 JSON valid 后再继续：",
+    "```bash",
+    "cat result.json | python3 -m json.tool > /dev/null && echo \"JSON valid\" || echo \"JSON invalid\"",
+    "```",
+    "如果校验结果不是 JSON valid，请继续修正 result.json，直到通过为止。",
+    "必须输出完整 JSON 对象，不要只输出 artifacts 片段。",
+    "只输出修正后的合法 JSON ResultEnvelope，不要输出任何解释。",
+].join("\n");
+exports.createNodeCorrectionPrompt = createNodeCorrectionPrompt;
+const buildExternalPipelineArtifactInput = async (output) => {
+    try {
+        const { absolutePath } = output.artifactRef;
+        // Verify path is within artifact directory (basic path traversal check)
+        const normalizedPath = (0, node_path_1.resolve)(absolutePath);
+        if (!normalizedPath)
+            return null;
+        const raw = await (0, promises_1.readFile)(normalizedPath, "utf8");
+        const parsed = JSON.parse(raw);
+        const obj = (0, guards_1.isRecord)(parsed) ? parsed : null;
+        if (!obj)
+            return null;
+        const artifact = (0, guards_1.isRecord)(obj.artifact) ? obj.artifact : null;
+        if (!artifact)
+            return null;
+        // Verify hash
+        const fileHash = `sha256:${(0, node_crypto_1.createHash)("sha256").update(raw).digest("hex")}`;
+        if (fileHash !== output.artifactRef.hash)
+            return null;
+        const content = (0, parser_1.toPromptContentText)(artifact.content);
+        const meta = (0, guards_1.isRecord)(artifact.meta) ? artifact.meta : undefined;
+        return {
+            sourceKind: "pipeline_output",
+            sourcePipelineId: output.pipelineId,
+            sourceRunId: output.runId,
+            sourceBatchRunId: output.batchRunId,
+            sourceOutputId: output.outputId,
+            sourceOutputNodeId: output.outputNodeId,
+            sourceArtifactId: output.artifactId,
+            sourceArtifactHash: output.artifactRef.hash,
+            type: output.artifactRef.type,
+            schemaVersion: output.artifactRef.schemaVersion,
+            name: output.artifactRef.name,
+            path: normalizedPath,
+            createdAt: output.producedAt,
+            content,
+            meta,
+        };
+    }
+    catch {
+        return null;
+    }
+};
+exports.buildExternalPipelineArtifactInput = buildExternalPipelineArtifactInput;

package/dist/src/pipeline/structured-output/waiter.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractViolationCode = exports.waitForStructuredEnvelope = exports.evaluateObservedEnvelopeWindow = exports.evaluateEnvelopeCandidates = exports.rememberObservedEnvelopes = exports.shouldFailFastForCompletedSession = void 0;
+const execution_timeout_1 = require("../execution-timeout");
+const parser_1 = require("./parser");
+const contract_1 = require("./contract");
+const STRUCTURED_RESULT_TIMEOUT_MS = (0, execution_timeout_1.getStructuredResultTimeoutMs)();
+const STRUCTURED_RESULT_POLL_MS = (0, execution_timeout_1.getStructuredResultPollMs)();
+const MAX_OBSERVED_ENVELOPES = 400;
+const SESSION_COMPLETION_GRACE_MS = 1_200;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const shouldFailFastForCompletedSession = (sessionCompletedAt, now = Date.now()) => sessionCompletedAt !== null && now >= sessionCompletedAt + SESSION_COMPLETION_GRACE_MS;
+exports.shouldFailFastForCompletedSession = shouldFailFastForCompletedSession;
+const rememberObservedEnvelopes = (observed, payload, source) => {
+    const envelopes = (0, parser_1.collectEnvelopeCandidates)(payload);
+    const now = Date.now();
+    for (const envelope of envelopes) {
+        observed.push({
+            envelope,
+            observedAt: now,
+            source,
+        });
+    }
+    if (observed.length > MAX_OBSERVED_ENVELOPES) {
+        observed.splice(0, observed.length - MAX_OBSERVED_ENVELOPES);
+    }
+    return envelopes;
+};
+exports.rememberObservedEnvelopes = rememberObservedEnvelopes;
+const evaluateEnvelopeCandidates = (envelopes, ctx) => {
+    const forRequestId = envelopes.filter((envelope) => envelope.requestId === ctx.requestId);
+    if (forRequestId.length > 0) {
+        let firstFailure = null;
+        for (const envelope of forRequestId) {
+            const checked = (0, contract_1.validateEnvelope)(envelope, ctx);
+            if (checked.ok)
+                return { envelope, seenCandidate: true };
+            if (!firstFailure)
+                firstFailure = checked.code;
+        }
+        return { violation: firstFailure ?? "result_envelope_missing", seenCandidate: true };
+    }
+    const related = envelopes.filter((envelope) => envelope.runId === ctx.runId &&
+        envelope.nodeId === ctx.nodeId &&
+        envelope.sessionId === ctx.sessionId);
+    if (related.length > 0) {
+        return { violation: "request_id_mismatch", seenCandidate: true };
+    }
+    return { seenCandidate: false };
+};
+exports.evaluateEnvelopeCandidates = evaluateEnvelopeCandidates;
+const evaluateObservedEnvelopeWindow = (observed, ctx, options) => {
+    const confirmFinal = options?.confirmFinal === true;
+    const forRequestId = observed.filter((entry) => entry.envelope.requestId === ctx.requestId);
+    if (forRequestId.length > 0) {
+        if (!confirmFinal) {
+            // agent 会话未结束前，只记录“已见到候选”，不能提前认定成功/失败。
+            // 否则中途调试 JSON、半成品 envelope 都可能被过早消费。
+            return { seenCandidate: true };
+        }
+        let latestFailure = null;
+        for (let i = forRequestId.length - 1; i >= 0; i -= 1) {
+            const checked = (0, contract_1.validateEnvelope)(forRequestId[i].envelope, ctx);
+            if (checked.ok)
+                return { envelope: forRequestId[i].envelope, seenCandidate: true };
+            if (!latestFailure)
+                latestFailure = checked.code;
+        }
+        return { violation: latestFailure ?? "result_envelope_missing", seenCandidate: true };
+    }
+    const related = observed.filter((entry) => entry.envelope.runId === ctx.runId &&
+        entry.envelope.nodeId === ctx.nodeId &&
+        entry.envelope.sessionId === ctx.sessionId);
+    if (related.length > 0) {
+        if (!confirmFinal)
+            return { seenCandidate: true };
+        return { violation: "request_id_mismatch", seenCandidate: true };
+    }
+    return { seenCandidate: false };
+};
+exports.evaluateObservedEnvelopeWindow = evaluateObservedEnvelopeWindow;
+/**
+ * 等待结构化回执。
+ *
+ * 当传入 AbortSignal 且被触发时，提前退出本地轮询循环。
+ * 远端 agent 的停止由上游 executionService 通过 "/stop" 命令处理。
+ *
+ * @param signal 可选的中止信号，用于流水线 stop/retry 时提前退出轮询。
+ */
+const waitForStructuredEnvelope = async (emitter, ctx, initialViolation, hasSessionCompleted, signal) => {
+    const deadline = Date.now() + STRUCTURED_RESULT_TIMEOUT_MS;
+    let lastViolation = initialViolation;
+    const latest = [];
+    const MAX_LOCAL_ENVELOPES = 400;
+    const onCandidate = (entry) => {
+        latest.push(entry);
+        if (latest.length > MAX_LOCAL_ENVELOPES) {
+            latest.splice(0, latest.length - MAX_LOCAL_ENVELOPES);
+        }
+    };
+    emitter.on("candidate", onCandidate);
+    try {
+        while (Date.now() <= deadline) {
+            const currentWindow = [...latest];
+            const sessionCompletedAt = hasSessionCompleted?.() ?? null;
+            const canConfirm = (0, exports.shouldFailFastForCompletedSession)(sessionCompletedAt);
+            const checked = (0, exports.evaluateObservedEnvelopeWindow)(currentWindow, ctx, { confirmFinal: canConfirm });
+            if (checked.envelope) {
+                return checked.envelope;
+            }
+            if (canConfirm && checked.violation) {
+                lastViolation = checked.violation;
+                throw new Error(`contract_violation:${checked.violation}`);
+            }
+            if (canConfirm) {
+                throw new Error(`contract_violation:${lastViolation ?? "result_envelope_missing"}`);
+            }
+            await sleep(STRUCTURED_RESULT_POLL_MS);
+            if (signal?.aborted) {
+                throw new Error("aborted");
+            }
+        }
+        throw new Error(`contract_violation:${lastViolation ?? "result_envelope_missing"}`);
+    }
+    finally {
+        emitter.off("candidate", onCandidate);
+    }
+};
+exports.waitForStructuredEnvelope = waitForStructuredEnvelope;
+const extractViolationCode = (error) => {
+    const raw = String(error ?? "");
+    const marker = "contract_violation:";
+    const idx = raw.indexOf(marker);
+    if (idx < 0)
+        return null;
+    const code = raw.slice(idx + marker.length).trim();
+    return code || null;
+};
+exports.extractViolationCode = extractViolationCode;

package/dist/src/pipeline/template.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOutputId = exports.isValidLinkId = exports.buildJobId = exports.readWorkflowDefinitionFromRawDetailed = exports.readWorkflowDefinitionFromRaw = exports.validateWorkflowOutputConfig = exports.validateWorkflowDefinition = exports.savePipelineTemplateWithStorage = exports.savePipelineTemplate = exports.loadPipelineTemplateWithStorage = exports.loadPipelineTemplate = exports.saveWorkflowDefinitionWithStorage = exports.saveWorkflowDefinition = exports.loadWorkflowDefinitionWithStorage = exports.loadWorkflowDefinition = exports.migrateWorkflowDefinitionV2RawToV3 = exports.readTemplateNodesFromRaw = exports.normalizeWorkflowFallbacksWithStorage = exports.normalizeWorkflowFallbacks = exports.workflowToTemplateNodes = exports.mergeTemplateNodesIntoWorkflow = exports.defaultWorkflowDefinition = exports.defaultTemplateNodes = void 0;
+const guards_1 = require("../utils/guards");
+const normalize_1 = require("./workflow/normalize");
+const io_1 = require("./workflow/io");
+const validate_1 = require("./workflow/validate");
+// ====== Re-exports from extracted modules ======
+// Defaults
+var defaults_1 = require("./workflow/defaults");
+Object.defineProperty(exports, "defaultTemplateNodes", { enumerable: true, get: function () { return defaults_1.defaultTemplateNodes; } });
+Object.defineProperty(exports, "defaultWorkflowDefinition", { enumerable: true, get: function () { return defaults_1.defaultWorkflowDefinition; } });
+// Template mapper
+var template_mapper_1 = require("./workflow/template-mapper");
+Object.defineProperty(exports, "mergeTemplateNodesIntoWorkflow", { enumerable: true, get: function () { return template_mapper_1.mergeTemplateNodesIntoWorkflow; } });
+Object.defineProperty(exports, "workflowToTemplateNodes", { enumerable: true, get: function () { return template_mapper_1.workflowToTemplateNodes; } });
+// ====== Normalize fallbacks ======
+const normalizeWorkflowFallbacks = (workflow) => {
+    return (0, exports.normalizeWorkflowFallbacksWithStorage)(workflow, {});
+};
+exports.normalizeWorkflowFallbacks = normalizeWorkflowFallbacks;
+const normalizeWorkflowFallbacksWithStorage = (workflow, options) => {
+    const currentNodeById = new Map((0, io_1.loadWorkflowDefinitionWithStorage)(options).nodes.map((node) => [node.id, node]));
+    const normalizedNodes = workflow.nodes.map((node) => {
+        const prev = currentNodeById.get(node.id);
+        if (!prev)
+            return node;
+        const prevAgent = prev.executor.agentId.trim();
+        const nextAgent = node.executor.agentId.trim();
+        if (prevAgent === nextAgent)
+            return node;
+        return {
+            ...node,
+            executor: {
+                ...node.executor,
+                fallbackAgentId: null,
+            },
+        };
+    });
+    return {
+        ...workflow,
+        nodes: normalizedNodes,
+    };
+};
+exports.normalizeWorkflowFallbacksWithStorage = normalizeWorkflowFallbacksWithStorage;
+// ====== Read template nodes from raw ======
+const readTemplateNodesFromRaw = (value) => {
+    if (!Array.isArray(value))
+        return null;
+    const nodes = [];
+    for (const item of value) {
+        const normalized = (0, normalize_1.normalizeTemplateNode)(item);
+        if (!normalized)
+            return null;
+        nodes.push(normalized);
+    }
+    const ids = new Set(nodes.map((n) => n.id));
+    if (ids.size !== nodes.length)
+        return null;
+    for (const node of nodes) {
+        for (const dep of node.dependsOn) {
+            if (!ids.has(dep))
+                return null;
+        }
+    }
+    return nodes;
+};
+exports.readTemplateNodesFromRaw = readTemplateNodesFromRaw;
+// ====== Migration ======
+const migrateWorkflowDefinitionV2RawToV3 = (value) => {
+    if (!(0, guards_1.isRecord)(value) || value.version !== "2.0") {
+        return { ok: false, error: "invalid_workflow_definition", detail: "仅支持从 workflow v2.0 迁移" };
+    }
+    if (!Array.isArray(value.nodes) || !Array.isArray(value.edges) || !Array.isArray(value.groups)) {
+        return { ok: false, error: "invalid_workflow_definition", detail: "workflow.nodes/edges/groups 必须为数组" };
+    }
+    const nodes = [];
+    for (const item of value.nodes) {
+        const normalized = (0, normalize_1.normalizeWorkflowNode)(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.nodes 存在非法节点结构" };
+        nodes.push(normalized);
+    }
+    const edges = [];
+    for (const item of value.edges) {
+        const normalized = (0, normalize_1.normalizeWorkflowEdge)(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.edges 存在非法边结构" };
+        edges.push(normalized);
+    }
+    const groups = [];
+    for (const item of value.groups) {
+        const normalized = (0, normalize_1.normalizeWorkflowGroup)(item);
+        if (!normalized)
+            return { ok: false, error: "invalid_workflow_definition", detail: "workflow.groups 存在非法并行组结构" };
+        groups.push(normalized);
+    }
+    const workflow = {
+        version: "3.0",
+        scheduler: (0, normalize_1.normalizeWorkflowScheduler)(value.scheduler),
+        plugins: (0, normalize_1.normalizeWorkflowPlugins)(value.plugins),
+        output: { mode: "mainline_last", nodeId: null },
+        nodes,
+        edges,
+        groups,
+    };
+    const validation = (0, validate_1.validateWorkflowGraph)(workflow);
+    if (!validation.ok)
+        return { ok: false, error: validation.error, detail: validation.detail };
+    return { ok: true, workflow };
+};
+exports.migrateWorkflowDefinitionV2RawToV3 = migrateWorkflowDefinitionV2RawToV3;
+// I/O functions re-exported from ./workflow/io
+var io_2 = require("./workflow/io");
+Object.defineProperty(exports, "loadWorkflowDefinition", { enumerable: true, get: function () { return io_2.loadWorkflowDefinition; } });
+Object.defineProperty(exports, "loadWorkflowDefinitionWithStorage", { enumerable: true, get: function () { return io_2.loadWorkflowDefinitionWithStorage; } });
+Object.defineProperty(exports, "saveWorkflowDefinition", { enumerable: true, get: function () { return io_2.saveWorkflowDefinition; } });
+Object.defineProperty(exports, "saveWorkflowDefinitionWithStorage", { enumerable: true, get: function () { return io_2.saveWorkflowDefinitionWithStorage; } });
+Object.defineProperty(exports, "loadPipelineTemplate", { enumerable: true, get: function () { return io_2.loadPipelineTemplate; } });
+Object.defineProperty(exports, "loadPipelineTemplateWithStorage", { enumerable: true, get: function () { return io_2.loadPipelineTemplateWithStorage; } });
+Object.defineProperty(exports, "savePipelineTemplate", { enumerable: true, get: function () { return io_2.savePipelineTemplate; } });
+Object.defineProperty(exports, "savePipelineTemplateWithStorage", { enumerable: true, get: function () { return io_2.savePipelineTemplateWithStorage; } });
+// Validation re-exported from ./workflow/validate
+var validate_2 = require("./workflow/validate");
+Object.defineProperty(exports, "validateWorkflowDefinition", { enumerable: true, get: function () { return validate_2.validateWorkflowDefinition; } });
+Object.defineProperty(exports, "validateWorkflowOutputConfig", { enumerable: true, get: function () { return validate_2.validateWorkflowOutputConfig; } });
+// Normalize/parse re-exported from ./workflow/normalize
+var normalize_2 = require("./workflow/normalize");
+Object.defineProperty(exports, "readWorkflowDefinitionFromRaw", { enumerable: true, get: function () { return normalize_2.readWorkflowDefinitionFromRaw; } });
+Object.defineProperty(exports, "readWorkflowDefinitionFromRawDetailed", { enumerable: true, get: function () { return normalize_2.readWorkflowDefinitionFromRawDetailed; } });
+var pipeline_link_1 = require("./types/pipeline-link");
+Object.defineProperty(exports, "buildJobId", { enumerable: true, get: function () { return pipeline_link_1.buildJobId; } });
+Object.defineProperty(exports, "isValidLinkId", { enumerable: true, get: function () { return pipeline_link_1.isValidLinkId; } });
+var pipeline_output_1 = require("./types/pipeline-output");
+Object.defineProperty(exports, "buildOutputId", { enumerable: true, get: function () { return pipeline_output_1.buildOutputId; } });

package/dist/src/pipeline/timeline-log-store.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTimelineLogStore = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const LOG_FILE_NAME = "timeline.log";
+const stringifyTimelineEntry = (entry) => {
+    const seen = new WeakSet();
+    return JSON.stringify(entry, (_key, value) => {
+        // 允许完整保留 detail 内容，但循环引用对象本身无法直接 JSON 化，
+        // 这里仅做兜底，避免日志持久化因为异常对象而中断主流程。
+        if (typeof value !== "object" || value === null)
+            return value;
+        if (seen.has(value))
+            return "[Circular]";
+        seen.add(value);
+        return value;
+    });
+};
+const createTimelineLogStore = (options) => {
+    let writeChain = Promise.resolve();
+    const getRunLogFile = (runId) => (0, node_path_1.join)(options.rootDir, runId, LOG_FILE_NAME);
+    const appendTimeline = (runId, item) => {
+        const logFile = getRunLogFile(runId);
+        let line = `${stringifyTimelineEntry({
+            id: item.id,
+            ts: item.createdAt,
+            level: item.level,
+            runId,
+            text: item.text,
+            ...(item.detail === undefined ? {} : { detail: item.detail }),
+        })}\n`;
+        // 单行大小兜底，防止超大 detail 撑爆日志文件
+        const MAX_LOG_LINE_BYTES = 512 * 1024;
+        if (Buffer.byteLength(line, "utf8") > MAX_LOG_LINE_BYTES) {
+            const truncated = line.slice(0, MAX_LOG_LINE_BYTES);
+            const suffix = "[TRUNCATED_LOG_LINE]\n";
+            const suffixBytes = Buffer.byteLength(suffix, "utf8");
+            line = truncated.slice(0, MAX_LOG_LINE_BYTES - suffixBytes) + suffix;
+        }
+        writeChain = writeChain
+            .catch(() => {
+            // 前一次写盘失败后继续后续写入，避免整个队列永久卡死。
+        })
+            .then(async () => {
+            await (0, promises_1.mkdir)((0, node_path_1.dirname)(logFile), { recursive: true });
+            await (0, promises_1.appendFile)(logFile, line, "utf8");
+        });
+        return writeChain.catch(() => {
+            // 日志持久化失败不能影响流水线运行，这里吞掉异常交给调用方按需记录。
+        });
+    };
+    return {
+        appendTimeline,
+    };
+};
+exports.createTimelineLogStore = createTimelineLogStore;