MagicEdit 领域骨架与全链路架构设计演进 (Architecture Spec)
日期: 2026-09-16 目标: 梳理「用户意图 -> 骨架路由 -> 技能探测 -> 需求分析闭环 -> 交互发卡 -> 沉淀 Brief -> 确定性编排执行 -> 中途中断重规划」终态架构。
一、同行竞品与业界标杆策略对照 (Competitive Analysis & Insights)
在多模态生成、AI 创意工作流领域，当前主流竞品（如 Midjourney v6/Niji、Runway Gen-3 / Aleph、Pika 2.0、Sora API 包装工作流，以及 LangGraph / AutoGen / Devin 等复杂 Agent 系统）主要呈现以下策略模式：
| 产品 / 架构模式 | 需求澄清策略 (Intake/Clarification) | 编排与执行策略 (Orchestration/Execution) | 优缺点分析 |
|---|---|---|---|
| Midjourney / Pika (单触发式黑盒) | 零交互/隐式补全：依靠庞大的 Prompt Expander（重写器）填补空白，不问用户。 | 单阶段端到端：单请求直接进生成模型队列。 | 优点：摩擦力极低；缺点：不可控，长视频或多镜头必翻车。 |
| Runway Aleph / Storyboard 类 (分镜向导) | 分阶段向导 (Wizard-Driven)：强制按步骤填写剧本 -> 分镜 -> 人设 -> 生成。 | 管道固定流水线 (Static Pipeline)：DAG 固定，只填节点参数。 | 优点：确定性强；缺点：呆板，无法处理灵活自由的自然语言复合需求。 |
| Devin / AutoGen / Claude Code (工程级 Agent) | 前置规格澄清 (Spec Clarification)：先提问确认需求边界（Spec/PRD），生成 Checklist 让用户确认。 | 动态 DAG + 自反思循环：根据 Settled Spec 分解计划，每步带验证与重试。 | 优点：高鲁棒性、适合高价值复杂任务；缺点：设计不好容易出现连续问询疲劳。 |
| MagicEdit (目标形态) | 骨架引导的多轮收敛 (Skeleton-guided Settling)：按领域骨架自动映射，只问高价值歧义点/开放要素，默认值透明化。 | 确定性 DAG 编排 + 中断重路由 (Interrupt & Replan)：需求沉淀后纯粹调度，支持执行态即时截断与增补。 | 结合了两者的优势：既有 Agent 的柔性自适应，又有工厂流水线的确定性交付。 |
二、架构总览图谱 (Architectural Topology)
===================================================================================================
MagicEdit L2 Agent Architecture
===================================================================================================
[ USER TIER ]
│
│ 1. 自然语言诉求 (Prompt + 附件: 图/视/音/文)
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 1. 意图识别与骨架路由层 (Intent Recognition & Skeleton Router) │
│ - 快速意图分流: [图: Image] | [视: Video/Recut] | [音: Music/Audio] | [文: Story/Novel] │
│ - 绑定领域骨架契约 (Domain Skeleton Contract) │
│ - 圈定初始候选技能树 (Candidate Skills Set: Atoms / Molecules) │
└───────────────────────────────────────────────┬─────────────────────────────────────────────────┘
│
│ { intent, skeleton, candidate_skills, raw_input }
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 2. 需求收敛循环闭环 (Phase: INTAKE_SETTLING) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ [需求分析 Agent - Intake Analyst] │ │
│ │ - 对照 Skeleton 必须要素契约进行要素匹配: │ │
│ │ * Given (用户已明确给出的要素) │ │
│ │ * Defaulted (可安全依规则兜底的要素，附带说明) │ │
│ │ * Open/Ambiguous (缺失或歧义的核心要素，阻碍进入 Plan) │ │
│ │ - 终止条件判定: │ │
│ │ * If (有 Open 且 轮次 < 3) -> 产出 Clarification Questions Package │ │
│ │ * If (无 Open 或 达到上限) -> 产出 Settled Immutable Brief │ │
│ └───────────────────────────┬─────────────────────────────────────▲───────────────────────┘ │
│ │ 有 Open 要素 │ 用户回答/选项回填 │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────┐ │ │
│ │ [交互呈现 Agent - Interact Presenter] │ │ │
│ │ - 转换为专业交互卡片 (Decision Protocol / Choice / Confirm) │ │ │
│ │ - 挂载代价/建议 (Recommended First, Cost Labels) │ │ │
│ │ - 统一由 deliverContract 发给前端展示给用户 │ │ │
│ └───────────────────────────┬───────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ [ 用户点击选项 / 补充文本 ] ──────────────────────┘ │
│ │
└───────────────────────────────────────────────┬─────────────────────────────────────────────────┘
│
│ 达成共识: Settled Brief (完整需求单)
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 3. 编排与执行引擎层 (Phase: PLAN_EXECUTING) │
│ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ [编排主脑 - Orchestrator (loop.js)] │ │
│ │ - 纯粹编排职责：禁止在此时反向问询基础业务需求 │ │
│ │ - 结合 Settled Brief + 选定 Skills 构建确定性 DAG 执行计划 (PlanRecord) │ │
│ │ - 门控校验 (Read Gates / DAG Gate / Type Matching) │ │
│ └───────────────────────────┬─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ 逐步下发 step (Task Dispatch) │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
│ │ [专业构建 Agent 集群 - Canvas / Builders] │ │
│ │ - Canvas Agent: 画布拓扑连接 (Node Insertion, Edge Wiring, Param Binding) │ │
│ │ - Tool Execution: 调用实际算力节点 (V2V, I2V, Txt2Img, Seedance, ClipExtract, Join) │ │
│ │ - Step Trace & Result Verification (验证生成制品是否符合预期) │ │
│ └─────────────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└───────────────────────────────────────────────┬─────────────────────────────────────────────────┘
│
│ 异步事件驱动 / 用户交互输入
▼
┌─────────────────────────────────────────────────────────────────────────────────────────────────┐
│ 4. 中断与动态重规划监控器 (Replanning & Interrupt Monitor) │
│ - 运行态持续监听 User New Turn / Cancel / Patch 指令 │
│ - 影响面评估 (Blast Radius Evaluator): │
│ * 局部微调 (Local Patch): 仅重跑受影响下游节点，不重置 Brief │
│ * 方向变更 (Goal Pivot): 挂起当前 Plan 执行流 -> 回退至 Phase 1 需求收敛循环 │
└─────────────────────────────────────────────────────────────────────────────────────────────────┘
三、四大领域骨架契约 (Domain Skeletons) 与详细要素字段
┌──────────────────────────────┐
│ 领域骨架契约 (Skeletons) │
└──────────────┬───────────────┘
│
┌───────────────────┬─────────┴─────────┬───────────────────┐
▼ ▼ ▼ ▼
【图】IMAGE 【视】VIDEO 【音】AUDIO 【文】STORY
1. 【图】IMAGE 领域骨架
- 必填 Hard 字段（不可随意默认）：
subject: 核心主体（角色/主体物体/场景核心）。reference_mode: 参考图模式（无参考 / 角色人设参考 / 姿态控制参考 / 风格参考）。
- 软默认 Soft 字段（可提供透明默认值 Transparent Default）：
style: 艺术风格（默认: "cinematic realism", 电影质感写实）。aspect_ratio: 画面比例（默认: "16:9"）。lighting_color: 光影与色调（默认: "natural daylight / balanced warm", 自然光暖调）。render_quality: 采样步数与画质（默认: "high"）。
- 候选关联技能：
molecules/image-build（文生图基础流水线）molecules/reference-sheet-build（参考图多视角提取）molecules/image-edit-build（局部重绘与外扩）
2. 【视】VIDEO 领域骨架
- 必填 Hard 字段：
narrative_intent: 叙事意图（从零原创 / 现有原片重拍剪辑 Recut）。shots_plan: 镜头规划（单镜头 / 多镜头连贯分镜）。recut_route（若为 Recut）: 路线 A（全重拍）/ B（深度与控制重拍）/ C（局部切片替换）/ D（纯节奏重剪）。character_anchor: 是否需要保人脸/主体一致性（若多镜头必须提供或指定锚点）。
- 软默认 Soft 字段：
fps_duration: 帧率与单镜头时长（默认: 24fps, 3~5秒）。continuity_level: 连贯性等级（默认: high，首尾关键帧继承）。camera_motion: 运镜控制（默认: "smooth dolly-in / pan", 平稳推拉）。audio_pairing: 是否配音/配乐（默认: 暂仅生成画面，预留音频轨道）。
- 候选关联技能：
molecules/video-build（通用视频构建）molecules/recut-methodology（重拍四路线方法论）molecules/recast-language-control（语言与动作控制流）
3. 【音】AUDIO / MUSIC 领域骨架
- 必填 Hard 字段：
audio_type: 音频类型（纯背景音乐 BGM / 歌曲带人声 / 影视音效 SFX / 旁白配音 Voiceover）。genre_mood: 曲风与情感（如 "Epic Cinematic", "Lo-Fi chill", "Dark ambient"）。
- 软默认 Soft 字段：
bpm: 节拍速率（根据 mood 自动推断，如 Epic 默认 120bpm，Chill 默认 80bpm）。vocal_timbre: 人声音色（如 "Warm female narrative", "Deep authoritative male"）。duration: 目标时长（默认: 匹配视频分镜总时长，或 30秒短音）。structure: 结构（默认: Intro -> Verse -> Climax -> Outro）。
- 候选关联技能：
molecules/audio-designmolecules/voice-craftmolecules/voiceover-build
4. 【文】STORY / NOVEL 领域骨架
- 必填 Hard 字段：
premise: 核心设定与故事前提（一句话梗概）。format: 交付形态（小说章节 / 短剧剧本 / 广告短视频脚本）。
- 软默认 Soft 字段：
tone_pov: 视角与基调（默认: 第三人称限制视角，严肃叙事）。target_length: 目标篇幅（短剧 60s / 小说 2000字）。character_count: 主要出场人物数（默认: 2~3人）。
- 候选关联技能：
molecules/script-writingmolecules/story-shapesubjects/formats/short-drama
四、多轮澄清协议与防疲劳规范 (Clarification & Anti-Fatigue Protocol)
为彻底解决传统 Agent 容易出现的“查户口式连续追问”，必须确立以下强约束协议：
-
单轮提问数量约束 (Question Density)：
- 每轮发给交互 Agent 的问题包 严格限制在 1 ~ 3 个核心问题，严禁一次性抛出长问卷。
- 优先问决定骨架走向的“分水岭要素”（Forking Question），例如：
- “先决定是整段重拍还是局部替换”，而不是在未确定路线前同时问“要用什么运镜和光影”。
-
选项呈现规范 (Options UX)：
- 必须包含：推荐选项（Recommended First）、其他输入（Free-text Other）。
- 代价透明标注 (Cost Transparency)：
- 选项必须携带实现成本或潜在风险。例如：“路线 A：快速但无法保证角色脸部一致；路线 B：需先生成人物参考图节点，成本稍高但保持人设连贯”。
-
透明默认原则 (Transparent Defaulting)：
- 所有 Soft 要素均有合规默认值，需求 Agent 自动填充并在最终确认卡片中列出：
“画幅已默认设为 16:9，风格为写实电影感（如有变更可随时说明）”。
- 用户如未明确修改，直接视为确认，不阻碍流程推进。
- 所有 Soft 要素均有合规默认值，需求 Agent 自动填充并在最终确认卡片中列出：
-
硬性收敛轮次门槛 (Hard Turn Ceiling)：
- 需求澄清循环上限为 3 轮（Turn 1 -> Turn 2 -> Turn 3）。
- 若达到第 3 轮仍有部分软性歧义未消除，Intake Agent 强制进入 Best-effort Defaulting（采用系统安全默认值），生成
Settled Brief并下发编排器。
五、状态载体与持久化模型 (State Persistence Model)
在多轮澄清与长耗时任务中，状态必须能够在多 Agent 间无损传递并持久化：
{
"sessionId": "session-20260916-01",
"domain": "video",
"phase": "INTAKE_SETTLING", // "INTAKE_SETTLING" | "PLAN_EXECUTING" | "REPLAN_EVALUATING"
"clarificationTurns": 1,
"briefStatus": "drafting", // "drafting" | "settled"
"skeletonContract": {
"domain": "video",
"hardRequirements": ["narrative_intent", "recut_route", "character_anchor"],
"softRequirements": ["aspect_ratio", "continuity_level", "fps_duration"]
},
"settledBrief": {
"intent": "video_recut",
"recut_route": "Route B (depth & character anchor)",
"character_anchor": "ref_image_node_01",
"aspect_ratio": "16:9",
"shots": [
{ "shot_id": 1, "action": "walking in rain", "duration": 3 },
{ "shot_id": 2, "action": "close-up looking back", "duration": 2 }
]
},
"planRecord": {
"status": "pending", // "pending" | "executing" | "completed" | "interrupted"
"steps": []
}
}
- 存储层：持久化于会话存储或本地状态
intakeState，每次 Agent 轮换时通过快照无缝恢复。 - 不可变性：一旦
briefStatus标记为settled，该 Brief 对编排器与 Canvas Agent 即为只读；任何修改必须经过 Phase 3 中断控制器解锁。
六、运行态中断与爆炸半径决策树 (Blast Radius Decision Tree)
在 Phase 2（执行阶段），用户发送补充文本或指令时，系统不会直接推翻重来，而是运行以下决策逻辑：
[ 用户在执行态注入新消息 ]
│
▼
[ 提取意图与变更参数 ]
│
┌───────────────┴───────────────┐
▼ ▼
【参数级微调 / 局部增补】 【核心设定推翻 / 领域切换】
(Local Patch Candidate) (Goal Pivot Candidate)
│ │
例如: "背景光影暗一点" / 例如: "不要做视频了，改成写小说" /
"换成女声旁白" "把整个二次元画风推翻，要真人实拍"
│ │
▼ ▼
[ 评估下游受影响节点 ] [ 挂起当前 Plan 执行流 ]
│ │
▼ ▼
[ 仅重跑脏节点 (Dirty Nodes) ] [ 将上下文送回 Phase 1 Intake ]
• 保留上游已完成产物 • 提取已有有效参数，重置冲突字段
• 打补丁更新执行队列 • 发起微型澄清确认卡 (Delta Confirm)
决策判断矩阵：
- Local Patch（局部安全微调）：
- 触发条件：变更仅涉及已生成节点的下游渲染参数（如 Prompt 词缀微调、音频音量调节、字幕字体修改）。
- 动作：保持
briefStatus = settled，由 Mini-Intake 毫秒级生成差量 Payload，直接对【平面 C 固定执行层】打补丁。
- Goal Overhaul / Pivot（核心推翻 ➔ 强制新开画布 Force New Canvas）：
- 触发条件：推翻核心人设、更换视频骨架、从原片剪辑切换为全新文生视频、要求全盘推翻重新生成。
- 铁律动作：严禁在旧画布原地清洗/摧毁已有历史节点，强制用户开辟全新画布！ ① 将当前旧画布整体标记为【归档/只读存档 (Archived)】，保护沉没产物； ② 自动创建全新的 Canvas ID 与 Session，干净隔离； ③ 重新由 Phase 1 (平面 A) 进入全新需求收敛闭环； ④ UI 支持一键将旧画布中满意的优质素材勾选迁移至新画布。
七、异常处理与边界用例保障 (Edge Cases & Resilience)
- 矛盾输入处理 (Contradictory Inputs)：
- 示例：用户输入“生成极其写实的真人自拍赛博朋克像素画”。
- 处理：Intake Agent 识别出风格冲突（
photorealisticvspixel art），不直接报错，而是归入 Open 状态，交由 Interact Agent 提示：“您提到了写实自拍与像素画两种不同风格，推荐为您采用【高清像素艺术风格】或【写实赛博朋克摄影】，您更倾向哪一种？”
- 多模态混淆 (Multi-domain Confusion)：
- 示例：用户同时发了一段音频和一段剧本：“帮我配上画面和做成音乐MV”。
- 处理：Skeleton Router 识别为复合任务（Compound Flow），绑定
Video作为顶层主骨架，将Audio作为内置子资产节点联动，防止分流器震荡。
- 超域请求 (Out-of-Domain Requests)：
- 示例：用户在输入框要求“帮我写一段 Python 爬虫”或纯知识问答。
- 处理：Router 直接命中非多媒体创意域，绕过骨架生成，回退至交互 Agent 进行合规友好的能力边界引导。
八、系统状态机迁移表 (State Machine Transitions)
| 当前状态 (Current State) | 触发事件 (Trigger Event) | 守卫条件 (Guard Condition) | 目标状态 (Next State) | 执行动作 (Action) |
|---|---|---|---|---|
IDLE |
收到用户首条需求输入 | 包含生成诉求 | INTAKE_ROUTING |
提取领域骨架与关联技能列表 |
INTAKE_ROUTING |
骨架映射完成 | 存在匹配骨架 | INTAKE_SETTLING |
启动 Intake Agent 对比要素契约 |
INTAKE_SETTLING |
要素分析完毕 | 存在 Open 且轮次 < 3 | AWAITING_USER_INPUT |
触发 Interact Agent 渲染发卡 |
AWAITING_USER_INPUT |
用户点击选项/回答 | - | INTAKE_SETTLING |
回填要素，重新核对完整性 |
INTAKE_SETTLING |
要素齐备 / 用户确认 | 无阻塞 Open 要素 | PLAN_EXECUTING |
封板 Settled Brief，唤醒编排器 |
PLAN_EXECUTING |
计划生成并校验通过 | DAG 门控通过 | STEP_DISPATCHING |
依次调用 Canvas 节点构建与运行 |
STEP_DISPATCHING |
所有步骤完成 | 产物检验合格 | COMPLETED |
交付最终结果与播放卡片 |
STEP_DISPATCHING |
命中 HIL 门控节点 | node.require_human === true |
HUNG_FOR_USER |
释放 Worker 算力，Checkpointer 存盘，向前端推送待确认产物 |
HUNG_FOR_USER |
用户完成确认/修改 | Webhook/Socket 唤醒 | STEP_DISPATCHING |
恢复快照，拉起新 Worker 继续拓扑推进 (LangGraph Resume 语义) |
ANY_EXECUTING_STATE |
收到用户新指令 | 指令为修订/推翻 | REPLAN_EVALUATING |
挂起当前任务，评估影响面 |
REPLAN_EVALUATING |
判定为方向大改 (Pivot) | 影响上游定义 | INTAKE_SETTLING |
将新改动送入需求循环，重新确认 |
九、Copilot 与画布结合：DAG 执行层深度设计 (Phase 2 & Phase 3 Deep Dive)
针对 Copilot 与 Canvas 画布深度结合的复杂创作场景，DAG 执行层从单纯的“步骤列表”升级为具备严格状态机语义的有向无环图。核心实现聚焦于以下四个工程维度：
1. 核心数据结构：PlanRecord (有向无环图状态机)
编排主脑生成的 PlanRecord 抛弃原先的一维 steps 列表，采用工业级 Supervisor 模式的图状态机结构：
- 节点定义 (Node Schema)：
每个节点代表一个原子任务（如
generate_character_anchor、clip_extract_window_01、seedance_remake_01）。interface PlanNode { id: string; // 唯一节点标识 (如 "node_anchor_01") type: string; // 算力节点类型 (如 "Txt2ImageGptNode", "R2VSeedanceNode", "HIL_GateNode") inDegree: number; // 动态入度计数 (当为 0 时进入可执行就绪队列) dependencies: string[]; // 前置依赖节点 ID 集合 (入度边) dependents: string[]; // 下游后继节点 ID 集合 (出度边) status: 'Pending' | 'Running' | 'Yield' | 'HUNG_FOR_USER' | 'Success' | 'Failed' | 'Dirty'; require_human?: boolean; // 是否需要人类审批/交互 (HIL 一等公民) branchId?: string; // 所属分支版本 (如 "v1", "v2") costWeight?: number; // 算力/重要度权重 (用于 LAZY 模式排序决策) retryCount: number; // 当前重试次数 maxRetries: number; // 重试阈值 (默认 2) inputContract: Record<string, any>; // 局部入参规格契约 outputArtifact?: { // 执行产物元数据 assetId: string; url: string; meta: Record<string, any>; }; } - 边定义与 Read Gates (数据契约阻塞检查点)：
边不仅代表拓扑时序，更强制承载“输出-输入类型与语义契约”。系统中的
Read Gates充当阻塞门禁：- 契约校验：当下游节点需要
character_reference_image时，边门禁强制检查上游node_anchor_01输出的图片是否合法可用，禁止将未就绪或格式不符的产物透传下游。 - 无环性校验 (Cycle Detection)：在计划生成及每次 Local Patch 局部改线时，通过拓扑染色算法做实时环路检测，严禁闭环死锁。
- 契约校验：当下游节点需要
- 上下文快照 (Checkpointer)：
节点状态由
Pending -> Running -> Success/Failed发生迁移时，触发 Checkpointer：- 将当前图拓扑、节点状态矩阵及全局
intakeState原子化保存至持久化缓存（快照）。 - 断点续传能力：若由于后端重启、用户离线或单点 GPU 报错发生中断，重连后可精准从失败节点的上游状态恢复，无需从头重算。
- 将当前图拓扑、节点状态矩阵及全局
2. 编排主脑 (loop.js) 的调度生命周期
loop.js 坚守纯粹调度主脑定位，绝不越权向用户发卡，其调度循环严格按照拓扑排序推进：
┌──────────────────────────────┐
│ Settled Immutable Brief │
└──────────────┬───────────────┘
│
▼
┌──────────────────────────────┐
│ 构建初始 DAG (PlanRecord) │
└──────────────┬───────────────┘
│
┌─────────▼─────────┐
┌───────────────────▶│ Kahn 拓扑排序扫描 │◀─────────────────────────┐
│ └─────────┬─────────┘ │
│ │ │
│ ▼ │
│ [ 查找所有 inDegree === 0 节点 ] │
│ │ │
│ ┌──────────┴──────────┐ │
│ ▼ ▼ │
│ 【无依赖独立任务】 【依赖上游已完成】 │
│ (如: BGM生成 / (如: 分镜2重绘依 │
│ 角色锚点人设生成) 赖切片2+人物锚点) │
│ │ │ │
│ └──────────┬──────────┘ │
│ │ │
│ ▼ │
│ [ Read Gates 门控检查 ] │
│ • 人物锚点完整性检查 │
│ • 上游制品格式与分辨率校验 │
│ │ │
│ ┌─────────┴─────────┐ │
│ 通过 │ │ 失败/不全 │
│ ▼ ▼ │
│ [ 并发下发执行队列 ] [ 阻塞等待 / 触发修复 ] │
│ (Promise.allSettled) │
│ │ │
│ ▼ │
│ [ 节点标记 Success ] │
│ [ 递减下游后继入度 ] ───────────────────────────────────┘
│ │
│ ▼
└─────────── [ 检查全图是否已全胜 ]
- 拓扑排序与并发分配： 采用 Kahn 算法动态维护就绪队列。对于拓扑层级并列、无入度依赖的节点（如“背景音乐生成”与“主人物设定生成”），编排器向构建集群发起并发执行调度，大幅缩短首帧交付耗时。
- 门控阻塞与放行 (Gating)：
当下游渲染节点（如
R2VSeedanceNode）就绪时，编排主脑触发unanchoredRemakeGap及相关门控。只有当该镜头切片（clip）与角色参考锚点（anchor）双重到位且质检合格，才真正下发算力调用，从调度源头根绝“人脸漂移”与“空跑吞币”。
3. Canvas Agent 集群的执行边界
Canvas Agent 从传统的“全能决策黑盒”降维为“精确的物理拓扑执行器与算力桥接器”：
- 单回合单任务隔离 (Single-Turn Single-Task)：
- 编排器每次仅向单个 Canvas Agent 实例派发单个特定的
PlanNode执行任务，严格限定 Agent 的上下文视界与写权限。 - 杜绝多步吞并：彻底消除了过去大模型单回合内自行合并“切片+重绘+合成”、跳过必要中间检查点的认知幻觉。
- 编排器每次仅向单个 Canvas Agent 实例派发单个特定的
- 参数注入与环境一致性 (Param Fusion)：
每个 Agent 接收的环境上下文由两部分严密缝合而成：
- 全局不可变需求注入：从
Settled Brief中锁定的画幅比例（如16:9）、全剧画风 Prompt 词缀、以及统一的角色 reference 图路径； - 局部节点参数注入：当前节点专属的时间切片区间（
start,end）、分镜专属动作 Prompt。
- Canvas Agent 将两者组装成底层标准 Payload 传递给渲染内核，并在画布上完成微观节点的物理连线（Wire Placement）。
- 全局不可变需求注入：从
4. 脏节点污染与 Local Patch (局部微调) 机制
当系统在 Phase 3 捕获到用户的局部修改（如“把第2个分镜的背景从雨天改成雪天”），DAG 触发高效的子图失效与重算机制：
【原完整 DAG 执行流水线】
[Node 1: 角色锚点] ──▶ [Node 2: 切片抽取] ──▶ [Node 3: 分镜2重制] ──▶ [Node 4: 最终拼接]
│ │ │ │
已完成 已完成 用户提出修改 等待输入
│ │ │ │
▼ ▼ ▼ ▼
[锁定并复用] [锁定并复用] [标记为 DIRTY] [级联标记 DIRTY]
│ │ │ │
└──────────────────────┼─────────────────────┘ │
│ │
▼ │
[ 仅针对脏子图打补丁 ] │
• 注入新参数: "背景改成雪天" │
• 仅调度 Node 3' 重跑 ────────────────────────────────┘
• 算力复用率: > 70%
- 子图级联失效与隔离 (Taint Propagation)：
- 定位到用户修改对应的靶向节点（如
node_shot_02），将其置为Dirty。 - 顺着该节点的
dependents（出度边）进行有向图前向遍历（Forward Traversal），将所有受影响的下游后继节点（如最终的video_join节点）级联置为Dirty/Invalidated。
- 定位到用户修改对应的靶向节点（如
- 最大化算力复用 (Asset Reuse)：
- 所有入度上游未被污染的节点（如已经消耗 GPU 算力生成的高清角色锚点、未修改镜头 1/3 的视频片段）保持
Success状态并完全锁定。 - 调度器仅为脏子图生成 Delta DAG Patch，Canvas Agent 仅对脏节点重新注参并请求生成，节约大量昂贵算力与时间成本。
- 所有入度上游未被污染的节点（如已经消耗 GPU 算力生成的高清角色锚点、未修改镜头 1/3 的视频片段）保持
十、人机协同 (HIL) 深度演进：确定性系统与主观审美的平滑调和 (Human-in-the-Loop & State Branching)
生成式任务的最大特征是高度依赖人类主观审美。如果为了单纯追求工程确定性，将整个 Phase 2 变为只读的黑盒流水线、将所有人工介入延后到 Phase 3 运行态打断，必然导致两个极端体验痛点：
- “盲等” (Blind Waiting)：用户干等 3~5 分钟模型渲染出整条视频，最后发现第 1 个分镜的角色脸就已经崩了，导致全片报废；
- “算力空转” (Resource Spinning)：传统的同步等待会让 GPU Worker 线程一直挂起等待用户点击确认，造成显存锁死与资源浪费。
为了在不破坏 DAG 纯粹调度的前提下实现丝滑的 HIL，系统引入以下三大机制：
1. HIL 门控节点作为一等公民 (HIL_GateNode / Approval Node)
与其依赖不可预知的运行态强行打断，不如在 DAG 静态规划时，就在高风险审美卡点主动预埋 Approval Node（例如：character_anchor_approval、script_storyboard_approval）：
[上游: 角色锚点生成] ──▶ [HIL_GateNode: 人设质检门禁] ──▶ [下游: 30s 视频生成]
│ (require_human: true)
▼
【状态挂起: HUNG_FOR_USER】
│
┌─────────┴─────────┐
▼ ▼
[释放底层 Worker 算力] [Checkpointer 全量存盘]
• 无状态化 (Stateless) • 快照落盘至 Redis/DB
• 显存/线程立即释放 • 向前端推送待审批资产
│ │
└─────────┬─────────┘
│ 用户在前端查看预览并点击「通过/调整」
▼
【Webhook / WebSocket 异步唤醒 (Resume)】
• 重新申请算力拉起新 Worker
• 反序列化图快照 (对齐 LangGraph 中断恢复语义)
• 激活下游节点继续 Running
- 状态机挂起 (HUNG_FOR_USER)：
当执行流到达门控节点时，节点状态置为
HUNG_FOR_USER。 - 无状态释放 (Zero Compute Spinning)：
利用
Checkpointer将当前的完整图状态（拓扑结构、入度、各节点 outputArtifact、上下文）原子化落盘，直接销毁当前 Worker 线程与连接，彻底释放 GPU 算力，系统进入完全无状态休眠。 - 异步唤醒 (Resume via Webhook)：
前端通过 WebSocket 展示待审资产卡片。用户在 Canvas 上满意确认后，通过 API/Webhook 重新拉起一个新的无状态 Worker，反序列化图状态，顺畅恢复下游
Running。
2. 乐观执行与渐进式透出 (Optimistic Execution & Progressive Delivery)
并非所有的节点都需要阻塞。系统采用分级透出策略消除用户的等待焦虑：
- 低成本节点（乐观执行直通）： 如“文本 Prompt 润色扩展”、“分镜脚本规划”、“轻量 BGM 伴奏生成”。这类节点后台秒级并行跑完，结果以瀑布流的形式即时透出到 Canvas 画布上。
- 高成本节点（强前置 HIL 守卫）：
如“耗时 60 秒的 Seedance 视频重拍”、“4K 超分辨率渲染”。此类高昂算力节点前，强制安插
HIL_GateNode。 - 体感效果： 用户的“运行态打断”不再是对着黑盒进度条的盲目等待，而是在画布上实时看着中间资产（Prompt、设定图、草稿）像拼图一样逐步展开时，顺手进行的自然点击确认。
3. 基于分支的画布版本控制 (State Branching / "Git for Canvas")
在运行态调整（Phase 3 局部微调）时，若直接在原图覆盖写入（Overwrite），一旦用户调整后发现“还不如上一版”，将产生严重的不可逆挫败感。 系统实现 Git for Canvas 分支机制：
【主分支: Branch main (v1)】
[Anchor 设定] ──▶ [Shot 1: 晴天] ──▶ [Shot 2: 晴天] ──▶ [Join 拼接]
│ │
│ (不变资产指针复用)│ (不变资产指针复用)
▼ ▼
[Anchor 设定] ──▶ [Shot 1: 晴天] ──▶ [Shot 2: 改雪天] ──▶ [Join' 拼接]
【新分支: Branch v2 (Fork)】
- 零拷贝指针复用 (Immutable Pointer Sharing)：
当用户对某节点提出修改时，系统不修改
DAG_v1，而是基于当前快照Fork出DAG_v2。 上游所有已处于Success状态的产物节点（如已生成的角色脸部锚点、Shot 1 视频），通过不可变对象引用（Pointer Reference）直接挂载到v2，无需重复占用存储与 GPU 算力。 - 脏节点挂载与多版本对比：
仅针对被修改的节点及其下游脏子图在
v2分支上打补丁生成。前端 Canvas 提供多分支对比（如Version 1 (晴天)vsVersion 2 (雪天)），用户可随时自由切换或一键回退（Checkout）。
十一、生产级防坑设计：应对极易忽视的三大“暗坑” (Production Hardening & Edge Pitfalls)
在真实工业级上线场景下，上述机制若缺乏下述三个兜底闭环，极易造成存储账单失控、数据库挂死与运行态死循环。
1. 分支爆炸与孤儿资产垃圾回收 (Branch Explosion & Garbage Collection / TTL)
- 痛点：
在 HIL 试错阶段，用户可能对同一个分镜连续调整 5~8 次，派生出
v1, v2, ..., v8多个版本。虽然拓扑数据是轻量 JSON，但每个版本生成的高清视频、图片等底层 OSS 对象存储资产是极其昂贵的。 - 解法（主分支合并与分级 TTL 回收）：
- 主线合并 (Merge to Master)：当用户最终点击“导出视频”或“发布完成”时，被选中的分支标记为主干
main/winner。 - 分级垃圾回收策略 (Tiered GC)：
- 状态层 (Metadata)：所有分支的 JSON 结构与操作历史永久保留（体积极小，供溯源与审计）。
- 资产层 (Heavy Assets)：所有未被选中的孤儿分支 (Orphan Branches) 自动打上生命周期标签（如
ttl: 86400，即 24 小时）。 - 后台清理守护进程 (Sweep Cronjob)：24 小时后，后台定时巡检并将非 winner 分支独占的冷存储产物从 OSS 物理删除，仅保留引用指针与低清预览缩略图，存储降本率可达 80% 以上。
- 主线合并 (Merge to Master)：当用户最终点击“导出视频”或“发布完成”时，被选中的分支标记为主干
2. HUNG_FOR_USER 的看门狗超时机制 (Watchdog Timeout & Draft Fallback)
- 痛点：
节点到达
HIL_GateNode时，底层 Worker 线程虽然已销毁释放，但图状态被存盘为HUNG_FOR_USER。若用户中途直接关闭浏览器下班离开，甚至多天不再登录，该会话将长期滞留在活跃任务池与内存索引中，造成队列脏读与统计失真。 - 解法（两级看门狗策略 Watchdog）：
[到达门控: HUNG_FOR_USER] │ ▼ (超时计时开始) [2 小时无操作/心跳中断] ──▶ 【自动降级为 Draft (草稿休眠态)】 • 移出实时调度器活跃活跃队列 • 释放 WebSocket 长连接 • 发送轻量通知（邮件/App 推送：“您的资产已暂存”） │ ▼ (用户随时再次打开工程) 【懒加载重激活 (Lazy Resume)】 • 点击打开时才从冷存储反序列化快照 • 重新呈现待确认卡片，点击即激活- 活跃保护：设置 2 小时无响应看门狗阈值。
- 自动休眠降级：超时后将
sessionStatus从HUNG_FOR_USER降级为DRAFT_HIBERNATED，系统不再维持实时监听。 - 零损冷启动唤醒：用户未来数周甚至数月后重新打开工程时，触发懒加载机制（Lazy Load），从数据库拉出快照恢复现场，既杜绝任务池堆积，又保证了用户工程的永远可用。
3. Local Patch 的“意图翻译”微型解析器 (Mini-Intake / Fast-Path Parameter Resolver)
- 痛点：
在 Phase 3 中，运行态监听器虽然截获了用户的局部修改诉求（如“把背景改成雪天”），并将对应节点标记为了
Dirty，但大模型算力节点无法直接消费这句自然语言口语，底层 Seedance/Img2Img 依赖的是精准的 Prompt 词缀、负向词、LoRA 权重或 ControlNet 掩码。 如果为此让用户重新走一遍 Phase 1 的全量需求澄清，又违背了“微调不打扰”的初衷。 - 解法（轻量级 Mini-Intake 局部解析器）：
[用户插话: "把背景改成雪天"] │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 【Mini-Intake 局部意图解析器 (Zero-Loop Fast Path)】 │ │ • 纯无状态微型 LLM 调用 (耗时 < 1s) │ │ • 专供局部打补丁，绝不向用户反向发卡 │ │ • 输入: 用户增量 Prompt + 原节点的 inputContract 规格 │ │ • 逻辑: 仅执行 Delta Patch (提取雪天视觉词缀，覆写 prompt) │ │ • 输出: 组装好的标准底层 Payload │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ [直接注入 Canvas Agent 脏节点] [无需重新发卡，直接调度算力重跑]- 极窄职责与单向流：Mini-Intake 仅做文本/参数层面的差量补丁合并（Delta Merge），严禁向用户二次反问。
- 透明生效：将原节点的 Prompt 与增量诉求做微型差量合成（如
prompt = prompt.replace("sunny", "heavy snow, blizzard atmosphere")），直接组装成合规 Payload 送给 Canvas Agent 执行，做到用户一句话、系统秒级就绪重跑。
十三、专业独立 Agent 矩阵及其在全景架构中的精准分层 (Layered Agent Topology)
在新架构的清晰划分下，并非所有 Agent 都属于“DAG 执行层”。如果把认知决策、需求收敛和创意规划统统塞进 DAG 执行期，就会重蹈“执行中途动态反问、图拓扑结构不可预知、边跑算力边做宏观决策”的覆辙。
必须将 8 大专业 Agent 严格划分为 三大正交平面（Three Orthogonal Planes）：
=========================================================================================================
Phase 与平面的精准映射分层架构拓扑
=========================================================================================================
【平面 A：需求与认知交互平面】──▶ 归属于 Phase 1 (需求收敛闭环阶段)
• 核心使命：消除一切业务歧义与审美盲区，将用户口语诉求收敛为唯一的【Settled Immutable Brief】。
• 驻留 Agent：
1. Search Agent : [前置勘探] 搜索外网风格、影视术语，受未读验证门控防脏数据穿透。
2. Intake Agent : [要素判官] 对照骨架核验 Given/Defaulted/Open，未全部解决前绝对禁止进入规划。
3. Interact Agent: [人机网关] 专精卡片排版、推荐项与代价展示。严禁篡改业务要素，纯专注交互。
│
▼ (交付物: Settled Immutable Brief 需求封板)
│
【平面 B：创意方案与指令预编译平面】──▶ 归属于 Phase 2 (编排主脑决策与图编译阶段)
• 核心使命：编排主脑 (loop.js) 拿到 Brief 后，在真正调用底层算力前，通过各领域专家**自顶向下预编译出确定性 DAG**。
• 驻留 Agent：
4. Director Agent: [视听导演] 将 Brief 转化为场记板 (Slate Board / Treatment: 景别/运镜/节奏/拍点时长)。
★ 绝对不碰画布节点！只出创意蓝图，告诉主脑切几个镜头、每个镜头怎么拍。
5. Craft Agent : [指令工匠] 接收 Director 的 Treatment，按底层模型（如 Seedance）偏好翻译为高分 Prompt。
★ 四壁铁律约束：无会话、无画布、无场记板，专精 Prompt 预编译，Fail-open 兜底。
6. Asset Agent : [资产管家] 在编译期锁定主人物垫图、参考音轨等不可变 Handle ID，注满节点参数。
│
▼ (交付物: 编译完成且注满 Payload 的确定性 PlanRecord DAG)
│
【平面 C：物理拓扑与算力固定执行层】──▶ 处于 Phase 2 编译 与 Phase 3 运行态中断 之间的【绝对固定执行层】
• 核心使命：作为系统唯一的**物理执行终端与算力中枢**。对上承接 Phase 2 编译好的完整 DAG，按拓扑/LAZY 策略
一步步执行；对下支撑 Phase 3 的运行态局部微调（Local Patch），接收打补丁指令。
• 驻留 Agent：
7. Canvas Agent : [物理拓扑建造者] ★★★ 整个系统的固定执行层中有且仅有 Canvas Agent 驻留！★★★
★ 极窄执行边界：单回合单任务隔离，每次只接收一个节点的完整 Payload。
★ 只负责画布真实节点的插入（Insertion）、连线（Wiring）和调用工具（Seedance/Clip/Join）。
★ 严禁自主业务决策！严禁做需求发卡！严禁跳步吞并！
─────────────────────────────────────────────────────────────────────────────────────────────────────────
【旁路与跨周期平面：持续演进与运行态中断 (Cross-cutting & Phase 3)】
8. Mini-Intake : [Phase 3 运行态增量解析器] 用户中途打断插话时，微型解析局部差量，直接向平面 C 固定层打补丁。
9. Distill Agent : [离线经验蒸馏官] 离线分析全流程执行轨迹，沉淀微技能，完全不挤占在线算力。
三大平面的职责划分对照表
| 平面归属 | 对应阶段 (Phase) | Agent 角色 | 触发时机 | 核心输入 | 交付产物 | 为什么不能混杂在其它层？ |
|---|---|---|---|---|---|---|
| 平面 A (认知交互) |
Phase 1 (需求收敛闭环) |
Search Agent | Phase 0/1 | 用户模糊词/风格参考 | 勘探知识库 | 检索外部网络具有不确定性，必须前置验证，严防污染执行流。 |
| 平面 A (认知交互) |
Phase 1 (需求收敛闭环) |
Intake Agent | Phase 1 | 骨架契约 + 对话历史 | Settled Brief | 若放到执行层，编排器会边跑算力边问用户，引发发卡死锁与幽灵计划。 |
| 平面 A (认知交互) |
Phase 1 (需求收敛闭环) |
Interact Agent | Phase 1 & HIL | Intake 结构化问题包 | 前端展示卡片 | 只懂人机交互与 UI 渲染，根本不具备图调度与算力理解能力。 |
| 平面 B (创意预编译) |
Phase 2 编译期 (图结构与参数决策) |
Director Agent | Pre-DAG (构图前) |
Settled Brief | Slate Treatment (场记板/镜头语言) |
属于宏观视听构思，必须在生成 DAG 节点之前定好分镜数与景别，才能知道要建几个节点！ |
| 平面 B (创意预编译) |
Phase 2 编译期 (图结构与参数决策) |
Craft Agent | Pre-DAG (注参前) |
Director Treatment | 模型级高分 Prompt | 属于参数编译器。如果在 Canvas 执行时才临时写 Prompt，极易受局部上下文干扰导致风格漂移。 |
| 平面 B (创意预编译) |
Phase 2 编译期 (图结构与参数决策) |
Asset Agent | Pre-DAG (注参前) |
素材池引用 | 不可变 Handle 列表 | 确保全局参考垫图与音轨在连线前就已经 ID 固化，防止边执行边找资产。 |
| 平面 C (固定执行层) |
P2 / P3 固定层 (物理执行中枢) |
Canvas Agent | P2调度 / P3补丁 | 已注满参数的单节点 | 真实画布节点连线与算力结果 | 系统唯一的物理执行终端！ 既作为 Phase 2 的执行落地，又作为 Phase 3 补丁的受体，机械化执行，零创意决策。 |
| 旁路平面 | Phase 3 (运行态中断) |
Mini-Intake | Phase 3 (打断) | 用户增量修改自然语言 | Delta Patch Payload | 仅在运行态打断时唤起，毫秒级合并参数，直接对接平面 C 打补丁。 |
| 旁路平面 | 离线/跨生命周期 | Distill Agent | 任务结束后 | 会话与轨迹快照 | 结构化经验微技能 | 离线反思，不能拖慢用户交互与渲染流水线。 |
十四、调度求值策略演进：贪婪并发 (EAGER) 与 惰性步进 (LAZY)
在生成式工作流中，“并行跑满”与“成本最小化”是一对天然矛盾。为了实现“一步一步最小化创建”，彻底解决多任务无节制并发导致的算力报废问题，系统在 loop.js 编排层正式引入求值策略维度 (Evaluation Strategy)。
1. 全局执行模式定义 (Execution Modes)
在 PlanRecord 根对象增加 executionStrategy 字段，默认以成本优先：
| 模式 | 定位与倾向 | 触发条件 | 调度行为 |
|---|---|---|---|
LAZY (默认/向导模式) |
成本优先 (Cost-First) 控制爆炸半径与试错成本 |
• 用户自然语言意图包含：“先给我看看人设”、“一步步来” • 前端 UI Toggle 处于“向导/步进模式” • 默认兜底策略 |
最短 HIL 路径优先：即使有多个 inDegree === 0 节点就绪，只挑一条主干路径执行。产生第一个可见实体产物后立即挂起进入 HUNG_FOR_USER，等待用户确认才解锁下游。非主干就绪节点置为 Yield (惰性暂缓)。 |
EAGER (贪婪/并发模式) |
时间优先 (Latency-First) 追求极限交付速度 |
• 用户明确表达：“一键全量生成”、“直接出全套成片带BGM” • 前端 UI Toggle 选择“极速批量模式” |
拓扑并发打满：所有 inDegree === 0 的就绪任务（人物设定、背景音乐、分镜文案、原片切片）由 Promise.allSettled 全力并行下发执行。 |
2. loop.js 改造：从“就绪即执行”到“最短 HIL 路径优先 (Yield 机制)”
在 LAZY 模式下，拓扑排序不再是盲目贪婪下发：
[LAZY 模式拓扑就绪节点扫描]
│
├─▶ [Anchor 人设生成] (inDegree: 0, costWeight: 10, 主视觉主干) ──▶ 【立即下发调度 (Running)】
│ │
│ ▼ 产物就绪
│ 【隐式微门控: HUNG_FOR_USER】
│ • 界面弹出人设预览与「下一步」
│ • 算力暂缓，等待用户确认
│
└─▶ [BGM 音轨生成] (inDegree: 0, costWeight: 50, 非主干任务) ──▶ 【强行挂起: 置为 Yield】
• 虽无前置依赖，但为防人设
推翻连带浪费算力，暂不启动！
- 非主干并发节点主动 Yield：
在视频生成链路中，BGM 和人设虽然从图结构上看互不依赖（入度均为 0），但从业务价值链上看，视觉人设是决定全片走向的核心骨架。若人设被用户推翻，先生成的 BGM 往往一同报废。因此 LAZY 模式下系统依据
costWeight与主干规则，先跑 Anchor，将 BGM 置为Yield暂缓。 - 隐式微步门控 (Implicit Micro-Gating)：
在
LAZY模式下，即便节点原本未显式声明require_human: true，只要它产生了第一个实体资产（一张设定图、一段关键分镜描述），系统会自动将图状态切为HUNG_FOR_USER，并在前端点亮“眼见为实”的确认卡片。
3. 前端交互与 Phase 1 联动的完整工程闭环 (Release Signal)
- Phase 1 意图捕获：
Intake Agent 识别用户意图：
- 用户说：“帮我做个赛博朋克短片，你先给我看下主角长啥样” ➔
executionStrategy = "LAZY"； - 用户说：“赶紧帮我直接生成赛博朋克女孩成片，加上配乐” ➔
executionStrategy = "EAGER"。
- 用户说：“帮我做个赛博朋克短片，你先给我看下主角长啥样” ➔
- 向导式 “Next Step” 解锁信号 (Release Node API)：
在
LAZY模式下，用户查看人设满意后，点击前端的“下一步：生成场景与音乐”。前端向loop.js发送轻量指令：POST /api/workflow/release { sessionId: "...", releaseNodeId: "anchor_01" }主脑收到该信号后，原子性地将等待中的后继节点以及处于Yield状态的bgm_01唤醒进入Running，实现“指哪打哪”的步进式掌控感。
4. 核心权衡与架构铁律 (Core Trade-off)
- 成本与耗时的 Trade-off：
LAZY模式将原本可并行的任务碎片化、串行化，牺牲了绝对端到端时间（Latency），但将算力浪费风险降到了绝对最低。 - 架构底线原则：
系统默认一律采用
LAZY模式步进阻断并发，控制爆炸半径；仅在接收到显式批处理契约时才切为EAGER模式全量并发。
十四、统一上下文协议 (Unified Media MCP Payload Schema)
为了让 Director（分镜蓝图）、Craft（提示词工匠）、Asset（资产管家）与 Canvas Agent（物理建造者）之间的数据交互完全解耦并具备对图、视、音、文的极强泛化能力，系统定义标准化 Unified Media MCP Payload Schema：
interface UnifiedMediaNodePayload {
// 1. 元数据层 (Metadata Header)
meta: {
nodeId: string; // 节点唯一ID (如 "shot_02_remake")
domain: image | video | audio | story;
targetAiNodeType: string; // 物理算力类型 (如 "R2VSeedanceNode", "Txt2ImageGptNode")
costWeight: number; // 权重 (LAZY 调度使用)
branchId: string; // 归属分支版本 (如 "v1", "v2")
};
// 2. 依赖契约层 (Dependency Contract - Read Gates)
inputs: {
handles: Array<{
inputKey: string; // 物理算力入参槽位 (如 "reference_image", "source_clip")
sourceNodeId: string; // 依赖的上游节点 ID
handleId: string; // 不可变资产句柄引用 (严禁传实体 Buffer!)
required: boolean;
validationGate: ANCHOR_MATCH | FORMAT_READY | NONE;
}>;
};
// 3. 通用多模态指令层 (Polymorphic Directives - 由 Craft 与 Director 编译)
directives: {
// 提示词与概念控制 (图像/视频/音频通用)
prompt: {
positive: string; // 经过 Craft 编译的高分标签块
negative?: string;
tags?: string[]; // 核心特征标签 (如 ["cyberpunk", "cinematic", "blizzard"])
};
// 空间与视觉参数 (图/视特化)
spatial?: {
aspectRatio: 16:9 | 9:16 | 1:1;
cameraMotion?: static | pan_left | push_in | orbit;
scaleFactor?: number; // 放大倍率
};
// 时间与动态参数 (视/音特化)
temporal?: {
startTimeSec?: number; // 切片起始时间
durationSec: number; // 持续时长
fps?: number;
bpm?: number; // 音频节拍
audioRole?: bgm | voiceover | sfx;
};
};
// 4. 执行约束与 HIL 策略 (Execution Policy)
policy: {
requireHuman: boolean; // 是否挂载 HIL 门控 (HUNG_FOR_USER)
timeoutSec: number;
maxRetries: number;
};
}
十五、状态全链路可观测性 (DAG Observability & Debugging)
针对 Kahn 拓扑动态排序与 Git for Canvas 多分支并存的高并发场景，必须提供无死角的实时可观测性：
1. 结构化状态变迁事件流 (State Transition Event Stream)
节点状态（Pending -> Running -> Yield -> HUNG_FOR_USER -> Success/Dirty）在流转瞬间，通过 WebSocket 广播统一格式的打点日志：
{
"timestamp": "2026-09-16T12:00:00.123Z",
"sessionId": "20260916-01",
"branchId": "v2",
"event": "NODE_STATE_TRANSITION",
"nodeId": "bgm_01",
"from": "Pending",
"to": "Yield",
"reason": "LAZY_EVALUATION_PATH_YIELD",
"activeInDegree": 0,
"costWeight": 50
}
2. 调试器可视化拓扑投影 (DebugPanel Graph Visualizer)
- 本地 Dev 模式控制台：在开发态激活
DebugPanel，通过轻量 Web 页面或终端 ASCII 流，实时高亮展示：- 🟢 绿色：Success 节点（可悬浮查看 outputArtifact 句柄）
- 🟡 闪烁黄色：Yield 暂缓节点
- 🟣 紫色框：HUNG_FOR_USER 挂起门控
- 🔴 红色：Dirty 脏子图
- 🌿 分支标签：支持在调试器侧边栏直接点击切换
main (v1)与v2 (Fork)，对比入度出度差异。
- 快照回溯与时间旅行 (Time-Travel Debugging)：
每个 Checkpoint 记录对应时间切片的完整图拓扑，开发者可通过 CLI
bb replay --checkpoint-id <id>单步重放 Kahn 拓扑排序的决策过程，秒级定位悬空边与发卡死锁。