@world-engines/dag-flow 0.1.3-alpha.0

package/dist/document.js

@@ -0,0 +1,704 @@
+/** 浏览器和 Node 共用的作者 Agent DAG 文档。 */
+/** 当前持久化版本。读取器仍接受 v1，并通过 upgradeDagDocument 显式规范化。 */
+export const DAG_FLOW_SCHEMA_VERSION = 2;
+export const DAG_FLOW_LEGACY_SCHEMA_VERSION = 1;
+export const DAG_FLOW_SOURCE_SECTION_KEY = "view.agent_dag";
+export const DAG_FLOW_VIEW_PERMISSION = "view";
+export const SYSTEM_USER_INPUT_NODE_ID = "user_input";
+export const SYSTEM_DIRECTOR_NODE_ID = "director";
+export const SYSTEM_TEXT_OUTPUT_NODE_ID = "text_output";
+/** 作者 Agent 只能插入这三个由系统调度的阶段，不能改写系统主线。 */
+export const DAG_INSERTION_SLOTS = ["before_director", "after_scribe", "after_writer"];
+export const DAG_STAGE_BOUNDARIES = [
+    { slot: "before_director", start_id: "stage.before_director.start", handoff_id: "stage.before_director.handoff" },
+    { slot: "after_scribe", start_id: "stage.after_scribe.start", handoff_id: "stage.after_scribe.handoff" },
+    { slot: "after_writer", start_id: "stage.after_writer.start", handoff_id: "stage.after_writer.handoff" },
+];
+/** 仅供界面展示的真实系统角色；它们不是可编辑 DAG 节点。 */
+export const SYSTEM_AGENT_ROLE_CATALOG = [
+    { id: "director", label: "Director" },
+    { id: "screenwriter", label: "Screenwriter" },
+    { id: "scribe", label: "Scribe" },
+    { id: "writer", label: "Writer" },
+    { id: "scene", label: "Scene" },
+    { id: "photographer", label: "Photographer" },
+    { id: "voice", label: "Voice" },
+];
+/** 编剧召回是 WASM 检索工具而非冻结 LLM Agent，不能承载可执行提示词覆盖。 */
+export const EDITABLE_SYSTEM_AGENT_ROLES = ["director", "scribe", "writer", "scene", "photographer", "voice"];
+export function defaultSystemAgentPromptBlocks(role) {
+    const task = {
+        director: "根据玩家输入、历史与场景上下文决定后续剧情，并输出可校验的结构化手稿。",
+        screenwriter: "根据手稿和场景上下文检索、整理与剧情相关的数据库证据。",
+        scribe: "依据手稿、场景和触发器规则准备状态刷新，并报告可提交或需要打回的原因。",
+        writer: "严格遵循手稿润色为面向玩家的正文，不新增手稿以外的剧情、动作或台词。每回合只依据回合开始时冻结的 Scene snapshot 与 authority 工作；若最终手稿产生了新的短期事实、在场对象或位置，提出仅包含 scene.context.*、scene.present.*、scene.location.set 的 scene_patch，并附逐字手稿证据、scene id、revision、冻结投影摘要与操作字节摘要。不得通过 scene_patch 修改 worldTime、Scene note、数据库属性或任意 graph。scene_patch 必须与正文在同一 Writer 存档事务中提交并取得 receipt；stale revision、对象或地点身份无效、authority 不匹配或无变化时接受拒绝，不得伪造 revision 或盲重试，下一回合从重新读取的冻结 snapshot 重新判断。",
+        scene: "维护当前 Scene cache，并把 contextItems、presentEntityNodeIds 与 location 作为相互独立的字段处理。每回合以冻结 snapshot、scene id、revision 与 authority 为唯一输入；只根据最终手稿提出 scene.context.*、scene.present.*、scene.location.set 的 scene_patch，临时信息必须为字符串，位置必须保持 GPS 或预绘制 location 的完整身份。worldTime 只消费已封印的时间增量，禁止由 Writer 或 scene_patch 修改。patch 与正文必须在同一 Writer 存档事务中原子提交并绑定 receipt；stale revision、缺失对象、错误地点身份、authority 不匹配或无变化时拒绝，随后重新读取 snapshot，不得沿用旧 patch、伪造 revision 或绕过冻结。",
+        photographer: "依据已确认手稿准备演出图像指令，不扩展剧情。",
+        voice: "依据手稿中的逐字台词准备语音演出指令，不改写台词。",
+    };
+    return [
+        { id: "system-task", name: "Agent 任务", role: "system", content: task[role] },
+        { id: "system-primer", name: "System Primer", role: "system", content: "" },
+        { id: "primer", name: "Primer", role: "user", content: "" },
+        { id: "anchor", name: "Anchor", role: "assistant", content: "" },
+    ];
+}
+const FIXED_EDGES = [
+    { id: "system.user_input.director", from: { node_id: SYSTEM_USER_INPUT_NODE_ID, port: "output" }, to: { node_id: SYSTEM_DIRECTOR_NODE_ID, port: "input" } },
+    { id: "system.director.text_output", from: { node_id: SYSTEM_DIRECTOR_NODE_ID, port: "output" }, to: { node_id: SYSTEM_TEXT_OUTPUT_NODE_ID, port: "input" } },
+];
+const SYSTEM_NODES = [
+    [SYSTEM_USER_INPUT_NODE_ID, "user_input"],
+    [SYSTEM_DIRECTOR_NODE_ID, "director"],
+    [SYSTEM_TEXT_OUTPUT_NODE_ID, "text_output"],
+];
+export function createEmptyDagDocument() {
+    return {
+        schema_version: DAG_FLOW_SCHEMA_VERSION,
+        section_key: DAG_FLOW_SOURCE_SECTION_KEY,
+        permission: DAG_FLOW_VIEW_PERMISSION,
+        nodes: [
+            { id: SYSTEM_USER_INPUT_NODE_ID, kind: "user_input", system: true },
+            { id: SYSTEM_DIRECTOR_NODE_ID, kind: "director", system: true },
+            { id: SYSTEM_TEXT_OUTPUT_NODE_ID, kind: "text_output", system: true, name: "Text Output" },
+        ],
+        edges: FIXED_EDGES.map(copyEdge),
+        stage_boundaries: DAG_STAGE_BOUNDARIES.map((boundary) => ({ ...boundary })),
+    };
+}
+/** 创建可序列化、可执行的三阶段控制流图。默认 start → handoff 可由作者删除后重新接线。 */
+export function createStageDagDocument() {
+    const base = createEmptyDagDocument();
+    const boundaries = DAG_STAGE_BOUNDARIES.map((boundary) => ({ ...boundary }));
+    const nodes = [
+        ...base.nodes,
+        ...boundaries.flatMap((boundary) => [
+            { id: boundary.start_id, kind: "stage_start", slot: boundary.slot, system: true },
+            { id: boundary.handoff_id, kind: "stage_handoff", slot: boundary.slot, system: true },
+        ]),
+    ];
+    const stageEdges = boundaries.map((boundary) => ({
+        id: `system.stage.${boundary.slot}.direct`,
+        from: { node_id: boundary.start_id, port: "output" },
+        to: { node_id: boundary.handoff_id, port: "input" },
+    }));
+    return { ...base, nodes, edges: [...base.edges, ...stageEdges], stage_boundaries: boundaries, stage_flow: { enabled: true }, execution: { terminal_on_text_output: true } };
+}
+/**
+ * 将 v1 文档升级为 v2。升级只补齐明确的阶段边界，不猜测节点之间的作者连线；
+ * 形状不明确或版本过新时拒绝，避免把旧数据静默解释成另一条执行路径。
+ */
+export function upgradeDagDocument(value) {
+    if (!isRecord(value))
+        throw new TypeError("dag_document_shape");
+    if (value.schema_version === DAG_FLOW_SCHEMA_VERSION) {
+        const result = validateDagDocument(value, { mode: "draft" });
+        if (!result.ok)
+            throw new DagDocumentValidationErrorLike(result.issues);
+        return { document: value, migrated: false };
+    }
+    if (value.schema_version !== DAG_FLOW_LEGACY_SCHEMA_VERSION)
+        throw new TypeError("dag_schema_version_unsupported");
+    const result = validateDagDocument(value, { mode: "draft" });
+    if (!result.ok)
+        throw new DagDocumentValidationErrorLike(result.issues);
+    const legacy = value;
+    const authorNodes = legacy.nodes.filter((node) => !isSystemNode(node));
+    if (legacy.insertion_slots !== undefined) {
+        if (authorNodes.some((node) => DAG_STAGE_BOUNDARIES.some((boundary) => node.id === boundary.start_id || node.id === boundary.handoff_id)))
+            throw new TypeError("dag_legacy_stage_id_conflict");
+        const staged = createStageDagDocument();
+        const edges = [...FIXED_EDGES.map(copyEdge)];
+        for (const boundary of DAG_STAGE_BOUNDARIES) {
+            const members = legacy.insertion_slots[boundary.slot] ?? [];
+            const chain = [boundary.start_id, ...members, boundary.handoff_id];
+            for (let index = 0; index < chain.length - 1; index += 1)
+                edges.push({
+                    id: `stage.${boundary.slot}.${index}`,
+                    from: { node_id: chain[index], port: index === 0 ? "output" : "success" },
+                    to: { node_id: chain[index + 1], port: "input" },
+                });
+        }
+        return {
+            migrated: true,
+            document: {
+                ...staged,
+                nodes: [...staged.nodes.filter((node) => isSystemNode(node)), ...authorNodes],
+                edges,
+                ...(legacy.system_agent_prompts === undefined ? {} : { system_agent_prompts: legacy.system_agent_prompts }),
+                ...(legacy.positions === undefined ? {} : { positions: legacy.positions }),
+            },
+        };
+    }
+    if (authorNodes.length > 0)
+        throw new TypeError("dag_legacy_graph_ambiguous");
+    return {
+        migrated: true,
+        document: { ...legacy, schema_version: DAG_FLOW_SCHEMA_VERSION, stage_boundaries: DAG_STAGE_BOUNDARIES.map((boundary) => ({ ...boundary })) },
+    };
+}
+/** 供 document.ts 使用的轻量错误，避免依赖 executor.ts 形成循环导入。 */
+class DagDocumentValidationErrorLike extends Error {
+    issues;
+    constructor(issues) { super("dag_document_invalid"); this.issues = issues; }
+}
+/** 对不可信 JSON 文档只返回问题清单，永不因形状错误抛出。 */
+export function validateDagDocument(document, options = {}) {
+    const mode = options.mode ?? "draft";
+    const issues = [];
+    if (!isRecord(document)) {
+        issue(issues, "document_shape", "DAG 文档必须是对象");
+        return { ok: false, issues };
+    }
+    if (document.schema_version !== DAG_FLOW_SCHEMA_VERSION && document.schema_version !== DAG_FLOW_LEGACY_SCHEMA_VERSION)
+        issue(issues, "schema_version", "只支持 schema_version 1 或 2");
+    if (document.section_key !== DAG_FLOW_SOURCE_SECTION_KEY)
+        issue(issues, "section_key", "DAG 必须属于 view.agent_dag section");
+    if (document.permission !== DAG_FLOW_VIEW_PERMISSION)
+        issue(issues, "permission", "DAG 只允许 view 权限");
+    const nodes = new Map();
+    if (!Array.isArray(document.nodes))
+        issue(issues, "nodes_shape", "nodes 必须是数组");
+    else
+        for (const candidate of document.nodes) {
+            if (!isRecord(candidate)) {
+                issue(issues, "node_shape", "节点必须是对象");
+                continue;
+            }
+            const id = candidate.id;
+            if (!validId(id)) {
+                issue(issues, "node_id", "节点 id 必须是非空稳定字符串");
+                continue;
+            }
+            if (nodes.has(id))
+                issue(issues, "duplicate_node", "节点 id 必须唯一", id);
+            if (!isNodeKind(candidate.kind)) {
+                issue(issues, "node_kind", "节点 kind 不受支持", id);
+                continue;
+            }
+            const node = candidate;
+            nodes.set(id, node);
+            validateNode(node, issues);
+        }
+    validateFixedNodes(nodes, document.stage_flow, issues);
+    const slottedNodes = validateInsertionSlots(document.insertion_slots, nodes, issues);
+    validateSystemAgentPrompts(document.system_agent_prompts, issues);
+    validateStageBoundaries(document.stage_boundaries, document.schema_version, issues);
+    if (document.execution !== undefined && (!isRecord(document.execution) || (document.execution.terminal_on_text_output !== undefined && typeof document.execution.terminal_on_text_output !== "boolean")))
+        issue(issues, "execution_shape", "execution.terminal_on_text_output 必须是布尔值");
+    const edges = new Map();
+    const incoming = new Map();
+    const outgoing = new Map();
+    if (!Array.isArray(document.edges))
+        issue(issues, "edges_shape", "edges 必须是数组");
+    else
+        for (const candidate of document.edges) {
+            if (!isEdge(candidate)) {
+                issue(issues, "edge_shape", "边必须包含 id、from 与 to");
+                continue;
+            }
+            const edge = candidate;
+            if (edges.has(edge.id))
+                issue(issues, "duplicate_edge", "边 id 必须唯一", undefined, edge.id);
+            edges.set(edge.id, edge);
+            const from = nodes.get(edge.from.node_id);
+            const to = nodes.get(edge.to.node_id);
+            if (!from)
+                issue(issues, "edge_from_missing", "边起点节点不存在", undefined, edge.id);
+            if (!to)
+                issue(issues, "edge_to_missing", "边终点节点不存在", undefined, edge.id);
+            if (!from || !to)
+                continue;
+            const validFromPort = isOutputPort(from, edge.from.port);
+            const validToPort = isInputPort(to, edge.to.port);
+            if (!validFromPort)
+                issue(issues, "edge_from_port", "边起点端口无效", from.id, edge.id);
+            if (!validToPort)
+                issue(issues, "edge_to_port", "边终点端口无效", to.id, edge.id);
+            if (!validFromPort || !validToPort)
+                continue;
+            const targetKey = key(edge.to.node_id, edge.to.port);
+            const inbound = incoming.get(targetKey) ?? [];
+            if (inbound.length > 0)
+                issue(issues, "input_fanin", "每个输入端口只能有一条入边，保证路径唯一", to.id, edge.id);
+            inbound.push(edge);
+            incoming.set(targetKey, inbound);
+            const sourceKey = key(edge.from.node_id, edge.from.port);
+            const list = outgoing.get(sourceKey) ?? [];
+            list.push(edge);
+            outgoing.set(sourceKey, list);
+        }
+    validateFixedEdges(edges, issues);
+    if (document.stage_flow !== undefined)
+        validateStageFlow(document.stage_flow, nodes, edges, incoming, outgoing, issues);
+    if (document.insertion_slots !== undefined)
+        validateControlledSlotMode(nodes, edges, slottedNodes, issues);
+    if (hasCycle(nodes, outgoing))
+        issue(issues, "cycle", "Agent DAG 不允许环；循环应由系统运行时处理");
+    if (mode !== "draft") {
+        if (document.stage_flow !== undefined)
+            validateStageRunnable(nodes, incoming, outgoing, issues);
+        else
+            validateRunnable(nodes, incoming, outgoing, issues, slottedNodes);
+    }
+    return { ok: issues.length === 0, issues };
+}
+function validateStageBoundaries(value, version, issues) {
+    if (value === undefined) {
+        if (version === DAG_FLOW_SCHEMA_VERSION)
+            issue(issues, "stage_boundaries_missing", "schema_version 2 必须保存三个阶段的控制流边界");
+        return;
+    }
+    if (!Array.isArray(value) || value.length !== DAG_STAGE_BOUNDARIES.length) {
+        issue(issues, "stage_boundaries_shape", "stage_boundaries 必须包含三个阶段边界");
+        return;
+    }
+    for (const expected of DAG_STAGE_BOUNDARIES) {
+        const actual = value.find((item) => isRecord(item) && item.slot === expected.slot);
+        if (!actual || actual.start_id !== expected.start_id || actual.handoff_id !== expected.handoff_id)
+            issue(issues, "stage_boundary_invalid", `阶段 ${expected.slot} 的边界不可修改`);
+    }
+}
+/** 判断值能否完整且无损地作为 DAG 内部的 JSON 值传递。 */
+export function isDagJson(value) {
+    try {
+        return isDagJsonValue(value, new Set());
+    }
+    catch {
+        return false;
+    }
+}
+export function dagMixedToString(value) { return typeof value === "string" ? value : JSON.stringify(value); }
+function validateNode(node, issues) {
+    if (node.kind === "user_input" || node.kind === "director" || node.kind === "stage_start" || node.kind === "stage_handoff") {
+        if (!hasSystem(node))
+            issue(issues, "system_node_mutated", `系统节点 ${node.id} 不可修改`, node.id);
+        if ((node.kind === "stage_start" || node.kind === "stage_handoff") && !DAG_INSERTION_SLOTS.includes(node.slot))
+            issue(issues, "stage_node_slot", "阶段边界必须属于已知阶段", node.id);
+        return;
+    }
+    if (node.kind === "agent") {
+        if (Object.hasOwn(node, "system"))
+            issue(issues, "system_node_extra", "作者节点不得标记为系统节点", node.id);
+        if (!isRecord(node.config)) {
+            issue(issues, "agent_config", "Agent 必须提供 config", node.id);
+            return;
+        }
+        if (typeof node.config.system_prompt !== "string" || !node.config.system_prompt.trim())
+            issue(issues, "agent_system_prompt", "Agent 必须提供 system_prompt", node.id);
+        if (typeof node.config.model_id !== "string" || !node.config.model_id.trim())
+            issue(issues, "agent_model_id", "Agent 必须提供 model_id", node.id);
+        if (typeof node.config.require_json !== "boolean")
+            issue(issues, "agent_require_json", "require_json 必须是布尔值", node.id);
+        if (node.config.prompt_injection !== "enabled" && node.config.prompt_injection !== "disabled")
+            issue(issues, "agent_prompt_injection", "prompt_injection 只能是 enabled 或 disabled", node.id);
+        if (!isRecord(node.config.templates) || !isMessageTemplates(node.config.templates))
+            issue(issues, "agent_template", "Agent 模板必须恰好为 system/primer/anchor 三段消息", node.id);
+        if (node.config.prompt_blocks !== undefined && !validPromptBlocks(node.config.prompt_blocks))
+            issue(issues, "agent_prompt_blocks", "提示词对象必须具有唯一 id、名称、合法角色和文本", node.id);
+        return;
+    }
+    if (node.kind === "script") {
+        if (Object.hasOwn(node, "system"))
+            issue(issues, "system_node_extra", "作者节点不得标记为系统节点", node.id);
+        if (!isRecord(node.config)) {
+            issue(issues, "script_config", "脚本节点必须提供 config", node.id);
+            return;
+        }
+        if (typeof node.config.source !== "string" || !node.config.source.trim())
+            issue(issues, "script_source", "脚本节点必须提供 source", node.id);
+        if (node.config.entrypoint !== undefined && node.config.entrypoint !== "main")
+            issue(issues, "script_entrypoint", "脚本 entrypoint 只能是 main", node.id);
+        if (node.config.paths !== undefined && !Array.isArray(node.config.paths))
+            issue(issues, "script_paths", "脚本 paths 必须是数组", node.id);
+        const paths = scriptOutputPorts(node);
+        if (new Set(paths).size !== paths.length || paths.some((path) => !validId(path)))
+            issue(issues, "script_paths", "脚本 path 必须是唯一的非空字符串", node.id);
+        return;
+    }
+    if (node.id === SYSTEM_TEXT_OUTPUT_NODE_ID) {
+        if (!hasSystem(node))
+            issue(issues, "system_node_mutated", `系统节点 ${node.id} 不可修改`, node.id);
+    }
+    else if (Object.hasOwn(node, "system") || typeof node.name !== "string" || !node.name.trim()) {
+        issue(issues, "text_output_name", "作者 Text Output 必须提供名称且不可标记为系统节点", node.id);
+    }
+}
+function validPromptBlocks(value) {
+    const ids = new Set();
+    return Array.isArray(value) && value.length > 0 && !value.some((block) => {
+        if (!isRecord(block) || typeof block.id !== "string" || !block.id.trim() || ids.has(block.id)
+            || typeof block.name !== "string" || !block.name.trim()
+            || !["system", "assistant", "user"].includes(block.role)
+            || typeof block.content !== "string")
+            return true;
+        ids.add(block.id);
+        return false;
+    });
+}
+function validateSystemAgentPrompts(value, issues) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value)) {
+        issue(issues, "system_agent_prompts_shape", "system_agent_prompts 必须是系统角色到提示词对象数组的映射");
+        return;
+    }
+    const roles = new Set(SYSTEM_AGENT_ROLE_CATALOG.map((role) => role.id));
+    for (const [role, blocks] of Object.entries(value)) {
+        if (!roles.has(role)) {
+            issue(issues, "system_agent_prompt_role", `未知系统 Agent ${role}`);
+            continue;
+        }
+        if (role === "screenwriter") {
+            issue(issues, "system_agent_prompt_unsupported", "编剧召回是检索工具，不支持提示词覆盖");
+            continue;
+        }
+        if (!validPromptBlocks(blocks))
+            issue(issues, "system_agent_prompt_blocks", `${role} 提示词对象必须具有唯一 id、名称、合法角色和文本`);
+    }
+}
+function validateFixedNodes(nodes, stageFlow, issues) {
+    for (const [id, kind] of SYSTEM_NODES) {
+        const node = nodes.get(id);
+        if (!node)
+            issue(issues, "missing_system_node", `缺少固定系统节点 ${id}`, id);
+        else if (node.kind !== kind || !hasSystem(node))
+            issue(issues, "system_node_mutated", `系统节点 ${id} 不可修改`, id);
+    }
+    const stageSystemCount = stageFlow === undefined ? 0 : DAG_STAGE_BOUNDARIES.length * 2;
+    const systemNodes = [...nodes.values()].filter(hasSystem);
+    if (systemNodes.length !== SYSTEM_NODES.length + stageSystemCount)
+        issue(issues, "system_node_count", `DAG 必须恰好包含 ${SYSTEM_NODES.length + stageSystemCount} 个固定系统节点`);
+    for (const node of nodes.values()) {
+        if (node.kind === "user_input" && String(node.id) !== SYSTEM_USER_INPUT_NODE_ID)
+            issue(issues, "system_node_extra", "不得新增 user_input 系统节点", String(node.id));
+        if (node.kind === "director" && String(node.id) !== SYSTEM_DIRECTOR_NODE_ID)
+            issue(issues, "system_node_extra", "不得新增 director 系统节点", String(node.id));
+        const stageMatch = stageFlow !== undefined && DAG_STAGE_BOUNDARIES.some((boundary) => (node.id === boundary.start_id && node.kind === "stage_start" && node.slot === boundary.slot)
+            || (node.id === boundary.handoff_id && node.kind === "stage_handoff" && node.slot === boundary.slot));
+        if (hasSystem(node) && !SYSTEM_NODES.some(([id, kind]) => node.id === id && node.kind === kind) && !stageMatch)
+            issue(issues, "system_node_extra", "不得新增或伪造系统节点", node.id);
+    }
+    if (stageFlow !== undefined)
+        for (const boundary of DAG_STAGE_BOUNDARIES) {
+            if (!nodes.has(boundary.start_id))
+                issue(issues, "stage_start_missing", `缺少阶段 ${boundary.slot} 的控制流启动`, boundary.start_id);
+            if (!nodes.has(boundary.handoff_id))
+                issue(issues, "stage_handoff_missing", `缺少阶段 ${boundary.slot} 的控制流交接`, boundary.handoff_id);
+        }
+}
+function validateFixedEdges(edges, issues) {
+    for (const expected of FIXED_EDGES) {
+        const edge = edges.get(expected.id);
+        if (!edge || !samePort(edge.from, expected.from) || !samePort(edge.to, expected.to))
+            issue(issues, "missing_system_edge", `固定系统边 ${expected.id} 不可删除或修改`, undefined, expected.id);
+    }
+}
+function validateRunnable(nodes, incoming, outgoing, issues, slottedNodes) {
+    const reachable = reachableFromRoots(nodes, outgoing);
+    const authorNodes = [...nodes.values()].filter((node) => !isSystemNode(node) && !slottedNodes.has(node.id));
+    for (const node of authorNodes) {
+        if (!reachable.has(node.id))
+            issue(issues, "orphan_node", "运行/发布时作者节点必须从 user_input 或 director 可达", node.id);
+        if (!(incoming.get(key(node.id, "input"))?.length))
+            issue(issues, "missing_input", "运行/发布时作者节点必须连接唯一输入", node.id);
+        for (const port of outputPorts(node))
+            if (!(outgoing.get(key(node.id, port))?.length))
+                issue(issues, "dangling_output", `运行/发布时 ${port} 输出必须连接到 text_output 或后续节点`, node.id);
+    }
+    for (const node of nodes.values())
+        if (node.kind !== "text_output" && !slottedNodes.has(node.id))
+            for (const port of outputPorts(node))
+                if (!outgoing.get(key(node.id, port))?.length)
+                    issue(issues, "dangling_output", "运行/发布时所有正常路径必须终到 text_output", node.id);
+    const canReachText = nodesThatReachText(nodes, incoming);
+    for (const node of nodes.values())
+        if (node.kind !== "text_output" && !slottedNodes.has(node.id) && reachable.has(node.id) && !canReachText.has(node.id))
+            issue(issues, "path_not_terminal", "运行/发布时每条正常路径必须终到 text_output", node.id);
+}
+function validateInsertionSlots(value, nodes, issues) {
+    const members = new Set();
+    if (value === undefined)
+        return members;
+    if (!isRecord(value)) {
+        issue(issues, "insertion_slots_shape", "insertion_slots 必须是三个受控槽的对象");
+        return members;
+    }
+    for (const key of Object.keys(value))
+        if (!DAG_INSERTION_SLOTS.includes(key)) {
+            issue(issues, "insertion_slot_unknown", `未知插入槽 ${key}`);
+        }
+    for (const slot of DAG_INSERTION_SLOTS) {
+        const list = value[slot];
+        if (list === undefined)
+            continue;
+        if (!Array.isArray(list)) {
+            issue(issues, "insertion_slot_members", `${slot} 必须是 Agent id 数组`);
+            continue;
+        }
+        for (const id of list) {
+            if (!validId(id)) {
+                issue(issues, "insertion_slot_member", `${slot} 包含非法 Agent id`);
+                continue;
+            }
+            if (members.has(id)) {
+                issue(issues, "insertion_slot_duplicate", `Agent ${id} 只能属于一个插入槽`, id);
+                continue;
+            }
+            members.add(id);
+            const node = nodes.get(id);
+            if (!node)
+                issue(issues, "insertion_slot_missing", `插入槽引用的 Agent ${id} 不存在`, id);
+            else if (node.kind !== "agent" || isSystemNode(node))
+                issue(issues, "insertion_slot_kind", "插入槽只允许作者 Agent", id);
+        }
+    }
+    return members;
+}
+function validateControlledSlotMode(nodes, edges, slottedNodes, issues) {
+    for (const node of nodes.values())
+        if (!isSystemNode(node) && !slottedNodes.has(node.id)) {
+            issue(issues, "insertion_slot_unassigned", "受控插槽模式下，每个作者节点都必须是已分配插槽的 Agent", node.id);
+        }
+    for (const edge of edges.values()) {
+        if (!FIXED_EDGES.some((fixed) => fixed.id === edge.id && samePort(fixed.from, edge.from) && samePort(fixed.to, edge.to))) {
+            issue(issues, "insertion_slot_edge", "受控插槽模式只允许固定系统主线边；槽内顺序由 insertion_slots 决定", undefined, edge.id);
+        }
+    }
+}
+function validateStageFlow(value, nodes, edges, incoming, outgoing, issues) {
+    if (!isRecord(value) || value.enabled !== true || Object.keys(value).length !== 1) {
+        issue(issues, "stage_flow_shape", "stage_flow 必须为 { enabled: true }");
+        return;
+    }
+    for (const edge of edges.values()) {
+        const source = nodes.get(edge.from.node_id);
+        const target = nodes.get(edge.to.node_id);
+        if (!source || !target)
+            continue;
+        const sourceSlot = stageSlot(source);
+        const targetSlot = stageSlot(target);
+        const authorEdge = !isCoreSystemNode(source) && !isCoreSystemNode(target);
+        if (authorEdge && sourceSlot !== undefined && targetSlot !== undefined && sourceSlot !== targetSlot)
+            issue(issues, "stage_cross_edge", "阶段控制流不能跨阶段连线", undefined, edge.id);
+        if (source.kind === "stage_handoff")
+            issue(issues, "stage_handoff_output", "控制流交接没有输出端口", source.id, edge.id);
+        if (target.kind === "stage_start")
+            issue(issues, "stage_start_input", "控制流启动没有输入端口", target.id, edge.id);
+    }
+    for (const boundary of DAG_STAGE_BOUNDARIES) {
+        const start = nodes.get(boundary.start_id);
+        const handoff = nodes.get(boundary.handoff_id);
+        if (!start || !handoff)
+            continue;
+        const startOutgoing = outgoing.get(key(start.id, "output")) ?? [];
+        if (startOutgoing.length > 1)
+            issue(issues, "stage_output_fanout", "阶段控制流每个输出只能连接一条线", start.id);
+        for (const node of nodes.values()) {
+            if (isCoreSystemNode(node) || node.kind === "stage_start" || node.kind === "stage_handoff")
+                continue;
+            const inStage = reachableFromBoundary(start.id, nodes, outgoing).has(node.id);
+            if (inStage) {
+                for (const port of outputPorts(node))
+                    if ((outgoing.get(key(node.id, port))?.length ?? 0) > 1)
+                        issue(issues, "stage_output_fanout", "阶段控制流每个输出只能连接一条线", node.id);
+            }
+        }
+        if ((incoming.get(key(handoff.id, "input"))?.length ?? 0) > 1)
+            issue(issues, "input_fanin", "控制流交接只能接收一条入边", handoff.id);
+        const reached = reachableFromBoundary(boundary.start_id, nodes, outgoing);
+        for (const id of reached) {
+            const node = nodes.get(id);
+            if (node?.kind === "stage_handoff" && node.slot !== boundary.slot)
+                issue(issues, "stage_cross_edge", "阶段控制流不能交接到另一阶段", node.id);
+            if (node?.kind === "stage_start" && node.id !== boundary.start_id)
+                issue(issues, "stage_cross_edge", "阶段控制流不能进入另一阶段启动器", node.id);
+        }
+    }
+    const ownership = new Map();
+    for (const boundary of DAG_STAGE_BOUNDARIES)
+        for (const id of reachableFromBoundary(boundary.start_id, nodes, outgoing)) {
+            const node = nodes.get(id);
+            if (!node || isSystemNode(node))
+                continue;
+            const prior = ownership.get(id);
+            if (prior !== undefined && prior !== boundary.slot)
+                issue(issues, "stage_node_reused", "作者节点只能属于一个阶段控制流", id);
+            else
+                ownership.set(id, boundary.slot);
+        }
+}
+function validateStageRunnable(nodes, incoming, outgoing, issues) {
+    for (const boundary of DAG_STAGE_BOUNDARIES) {
+        const start = nodes.get(boundary.start_id);
+        if (!start)
+            continue;
+        const reachable = reachableFromBoundary(start.id, nodes, outgoing);
+        const terminals = [...reachable].map((id) => nodes.get(id)).filter((node) => node !== undefined && (node.kind === "stage_handoff" || (node.kind === "text_output" && !hasSystem(node))));
+        if (terminals.length === 0)
+            issue(issues, "stage_not_connected", `阶段 ${boundary.slot} 的控制流未连接到交接或文本出口`, start.id);
+        for (const id of reachable) {
+            const node = nodes.get(id);
+            if (!node || node.kind === "stage_handoff" || (node.kind === "text_output" && !hasSystem(node)))
+                continue;
+            // Agent 的 error 是失败终态：旧受控插槽在 provider 错误时直接失败，
+            // 因而 v1 升级无需伪造一条会把错误当正常数据交接的边。
+            for (const port of outputPorts(node))
+                if (!(node.kind === "agent" && port === "error") && (outgoing.get(key(node.id, port))?.length ?? 0) === 0)
+                    issue(issues, "stage_dangling_output", `阶段 ${boundary.slot} 的 ${port} 输出未连接`, node.id);
+        }
+    }
+    for (const boundary of DAG_STAGE_BOUNDARIES) {
+        const handoff = nodes.get(boundary.handoff_id);
+        const start = nodes.get(boundary.start_id);
+        const reachable = start ? reachableFromBoundary(start.id, nodes, outgoing) : new Set();
+        const hasTerminalOutput = [...reachable].some((id) => {
+            const node = nodes.get(id);
+            return node?.kind === "text_output" && !hasSystem(node);
+        });
+        if (handoff && !hasTerminalOutput && (incoming.get(key(handoff.id, "input"))?.length ?? 0) !== 1)
+            issue(issues, "stage_handoff_input", `阶段 ${boundary.slot} 的控制流交接必须恰有一个输入`, handoff.id);
+    }
+}
+function reachableFromBoundary(root, nodes, outgoing) {
+    const found = new Set([root]);
+    const queue = [root];
+    while (queue.length) {
+        const id = queue.shift();
+        const node = nodes.get(id);
+        if (!node)
+            continue;
+        for (const port of outputPorts(node))
+            for (const edge of outgoing.get(key(id, port)) ?? [])
+                if (!found.has(edge.to.node_id)) {
+                    found.add(edge.to.node_id);
+                    queue.push(edge.to.node_id);
+                }
+    }
+    return found;
+}
+function stageSlot(node) {
+    if (node.kind === "stage_start" || node.kind === "stage_handoff")
+        return node.slot;
+    return undefined;
+}
+function isCoreSystemNode(node) { return node.kind === "user_input" || node.kind === "director" || (node.kind === "text_output" && hasSystem(node)); }
+function reachableFromRoots(nodes, outgoing) {
+    const found = new Set([SYSTEM_USER_INPUT_NODE_ID, SYSTEM_DIRECTOR_NODE_ID]);
+    const queue = [...found];
+    while (queue.length) {
+        const id = queue.shift();
+        const node = nodes.get(id);
+        if (!node)
+            continue;
+        for (const port of outputPorts(node))
+            for (const edge of outgoing.get(key(id, port)) ?? [])
+                if (!found.has(edge.to.node_id)) {
+                    found.add(edge.to.node_id);
+                    queue.push(edge.to.node_id);
+                }
+    }
+    return found;
+}
+function nodesThatReachText(nodes, incoming) {
+    const queue = [...nodes.values()].filter((node) => node.kind === "text_output").map((node) => node.id);
+    const found = new Set(queue);
+    while (queue.length) {
+        const id = queue.shift();
+        const node = nodes.get(id);
+        if (!node)
+            continue;
+        for (const port of inputPorts(node))
+            for (const edge of incoming.get(key(id, port)) ?? [])
+                if (!found.has(edge.from.node_id)) {
+                    found.add(edge.from.node_id);
+                    queue.push(edge.from.node_id);
+                }
+    }
+    return found;
+}
+function hasCycle(nodes, outgoing) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (id) => {
+        if (visiting.has(id))
+            return true;
+        if (visited.has(id))
+            return false;
+        visiting.add(id);
+        const node = nodes.get(id);
+        if (node)
+            for (const port of outputPorts(node))
+                for (const edge of outgoing.get(key(id, port)) ?? [])
+                    if (visit(edge.to.node_id))
+                        return true;
+        visiting.delete(id);
+        visited.add(id);
+        return false;
+    };
+    return [...nodes.keys()].some(visit);
+}
+function isDagJsonValue(value, ancestors) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || ancestors.has(value))
+        return false;
+    if (Array.isArray(value)) {
+        ancestors.add(value);
+        try {
+            const ownNames = Object.getOwnPropertyNames(value);
+            if (ownNames.length !== value.length + 1 || !ownNames.includes("length") || Object.getOwnPropertySymbols(value).length > 0)
+                return false;
+            for (let index = 0; index < value.length; index += 1) {
+                const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+                if (!descriptor || !descriptor.enumerable || !("value" in descriptor) || !isDagJsonValue(descriptor.value, ancestors))
+                    return false;
+            }
+            return true;
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if ((prototype !== Object.prototype && prototype !== null) || Object.getOwnPropertySymbols(value).length > 0)
+        return false;
+    ancestors.add(value);
+    try {
+        for (const property of Object.getOwnPropertyNames(value)) {
+            const descriptor = Object.getOwnPropertyDescriptor(value, property);
+            if (!descriptor || !descriptor.enumerable || !("value" in descriptor) || !isDagJsonValue(descriptor.value, ancestors))
+                return false;
+        }
+        return true;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function isRecord(value) { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function isNodeKind(value) { return value === "agent" || value === "script" || value === "text_output" || value === "user_input" || value === "director" || value === "stage_start" || value === "stage_handoff"; }
+function isEdge(value) { return isRecord(value) && validId(value.id) && isPortRef(value.from) && isPortRef(value.to); }
+function isPortRef(value) { return isRecord(value) && validId(value.node_id) && validId(value.port); }
+function isMessageTemplates(value) {
+    const parts = ["system", "primer", "anchor"];
+    return Object.keys(value).length === parts.length && parts.every((part) => typeof value[part] === "string");
+}
+function hasSystem(node) { return isRecord(node) && node.system === true; }
+function isSystemNode(node) { return node.kind === "user_input" || node.kind === "director" || node.kind === "stage_start" || node.kind === "stage_handoff" || (node.kind === "text_output" && hasSystem(node)); }
+function inputPorts(node) { return node.kind === "user_input" || node.kind === "stage_start" ? [] : ["input"]; }
+function outputPorts(node) { return node.kind === "agent" ? ["success", "error"] : node.kind === "script" ? scriptOutputPorts(node) : node.kind === "text_output" || node.kind === "stage_handoff" ? [] : ["output"]; }
+function scriptOutputPorts(node) {
+    const paths = isRecord(node.config) ? node.config.paths : undefined;
+    return Array.isArray(paths) && paths.length ? paths.filter((path) => typeof path === "string") : ["output"];
+}
+function isInputPort(node, port) { return inputPorts(node).includes(port); }
+function isOutputPort(node, port) { return outputPorts(node).includes(port); }
+function validId(value) { return typeof value === "string" && value.length > 0; }
+function samePort(a, b) { return a.node_id === b.node_id && a.port === b.port; }
+function copyEdge(edge) { return { id: edge.id, from: { ...edge.from }, to: { ...edge.to } }; }
+/** ID 与 port 可包含冒号，故使用无歧义 JSON 元组作为索引键。 */
+function key(nodeId, port) { return JSON.stringify([nodeId, port]); }
+function issue(issues, code, message, node_id, edge_id) { issues.push({ code, message, ...(node_id ? { node_id } : {}), ...(edge_id ? { edge_id } : {}) }); }