Nomi 架构拆解:Electron 主进程、Agent 运行时与生产流程引擎如何协作

原创2026-11-07 16:49:162,306 阅读
文章标签:人工智能AI 应用AI Agent媒体生成视频桌面应用

Nomi 架构拆解:Electron 主进程、Agent 运行时与生产流程引擎如何协作

Nomi 是一个开源、本地优先的 AI 视频创作工作台:用 Agent 完成分镜、关键帧与视频生成,再经画布编排、时间轴剪辑导出 MP4,支持自选模型、API 与本地 ComfyUI,并提供 MCP 接口。这篇文章拆解它最核心的三层架构——Electron 主进程、Agent 运行时(pi lane)与生产流程引擎(productionRun),看看一条指令从输入到出片是怎么流转的。

Nomi 工作台总览:创作、生成与预览三大工作区

三层分工:谁负责什么

Nomi 是一个 Electron 应用,界面(Renderer)只负责展示与交互,所有"有权威"的事都发生在主进程:

React 界面(画布 / 时间轴 / 文稿 / Agent 面板)
  │  IPC(固定请求 ID + 订阅制)
  ▼
Electron 主进程(electron/main.ts 统一装配)
  ├─ agentLane    → Agent 运行通路(pi SDK 会话 + 工具执行)
  ├─ productionRun → 生产流程引擎(阶段机 / 门 / 预算 / 审批)
  ├─ export       → 导出作业(manifest → FFmpeg → MP4)
  └─ capabilityCore → 对外 MCP 协议
  ▼
模型供应商 API / 本地 ComfyUI / 本地资产

入口在 electron/main.ts:主进程在此注册 desktopLaneIpc = registerAgentLaneIpc(...),把 Agent 面板、生成页和制作流程接到同一个 IPC 权威上。想核对"当前 main 上真实跑的是什么",docs/ARCHITECTURE-NOW.md 是最权威的一张表——每条都带 file:line 锚点,方便你当场证伪。

Electron 主进程:唯一的权威中枢

主进程的设计纪律很明确:Renderer 执行过的工具结果只回喂模型,主进程不会二次执行;花钱、写盘、调供应商这类不可逆操作,全部由主进程模块持有唯一写口。

几个关键目录:

一个值得学习的细节:electron/productionRun/productionPlaybooks.ts 把流水线阶段收进注册表——未登记的 playbook 名字在写盘前就抛人话错误,而不是静默降级成一个推不动的坏 Run。

Nomi Agent 运行时面板:右侧对话框与文稿编辑联动

Agent 运行时:pi SDK 与 agentLane

现役 Agent 运行时基于固定版本的 pi SDK(0.85.1,@earendil-works/pi-agent-core),主进程经私有 ESM 接缝调用,适配层集中在 electron/harness/runtime/pi/:

界面指令 → lane IPC(固定请求 ID、窗口归属)
  → contextService(恢复/排队/保存会话)
  → runtimePort → pi AgentSession(模型/工具循环与压缩)
  → Nomi 工具宿主(审批 + 领域工具执行)
  → 结果回喂 → 稳定收尾 → 落盘 → result/done

三个容易看漏的设计:

  1. 工具面只有一个 owner:模型看得见哪些工具,全部由 electron/shared/agentCapabilities/verbDeclarations.ts 声明式派生,内部 Agent(lane)与对外 MCP 共享同一份注册表(modelFacingToolRegistry.ts),不存在"两套工具定义漂移"。
  2. 审批闸按契约判:工具能不能调用不看名字,看声明的 effect/effectClass;付费边界(花费确认)是独立闸门,Skill 只是做事方法,不是扩大权限的许可证。
  3. 会话与界面解耦:任务绑定 {sessionKey, threadId},显示在哪个视图不改变任务归属;临时任务(如 single-shot,1 步零工具)与持久会话互不污染。

生产流程引擎:productionRun 阶段机

把"从一句话到一部成片"拆成可恢复的流水线,是 electron/productionRun/ 的核心工作。playbook brand.promo 的阶段为:

brief → direction → script → storyboard → build → generate → qa → assemble → export

每个阶段之间设"门"(人工审批点),配套一整套工程化机制,散落在 electron/productionRun/ 各文件中:

机制 作用
budgetLedger.ts 预算账本,花费先记账再放行
productionRunApprovalReceipt.ts 审批回执,谁批的、批了什么可追溯
submissionOutbox.ts + submissionIntent.ts 幂等提交,崩溃重启不会重复扣费
productionRunLifecycle.ts 生命周期唯一 owner:"为什么停"必须写明原因(见 productionRunLifecycle.ts 的文件头注释,是极好的代码自文档示范)
productionRunEventTap.ts 事件流,界面进度展示不轮询、全订阅

Nomi 画布编排:镜头卡、生成方式与提示词控制

分镜到时间轴这段同样值得看:planStoryboardTimeline 只负责按 shotIndex 选片,落轴归采纳桥 adoptStoryboardBatch(整批一次写定、一层撤销、带幂等键),字幕与转场正是在采纳桥里落进 textClips[] 与 transitions[]。

Nomi 分镜方案表格:Agent 拆解镜头并请求确认

导出管线:时间轴如何变成 MP4

导出是整条链路的终点,方案沉淀在 docs/architecture/nomi-production-video-export-architecture-2026-05-24.md。核心原则一句话:UI 不直接承担导出引擎,导出是 job 而不是 button promise。

时间轴 UI
  → NomiRenderManifest v1(不可变快照:轨道/片段/变换/编码参数)
  → 导出作业队列(job id / 状态机 / 取消 / 日志)
  → exportPlanner 选择 direct-ffmpeg / frame-render / hybrid
  → FFmpeg filtergraph 执行(scale + overlay + 时间窗 / 音频混音 / 文字叠层)
  → 临时文件 + 原子 rename → 最终 MP4

对应实现全部在 electron/export/:

因为每次导出都基于不可变快照,你在导出进行中继续编辑时间轴,也不会影响已经开始的 job——这是"本地优先"工作台和"网页按钮"最大的区别。

一条指令的完整路径

把三层串起来,一次典型的"生成分镜并出图"指令路径是:

  1. 界面经 lane IPC 提交指令(固定请求 ID + 任务归属)
  2. 主进程 agentLane 恢复会话,pi AgentSession 启动模型/工具循环
  3. 模型调用 propose_storyboard_plan 等领域工具,高危动作弹审批闸
  4. 工具结果回喂模型;镜头落进画布与时间轴(采纳桥一次写定)
  5. productionRun 推进阶段机:generate 阶段经预算账本 + 幂等提交派发给供应商
  6. 成片经 manifest 快照 → FFmpeg job → 原子写入导出 MP4
  7. 全程事件流实时驱动界面进度,崩溃后可凭回执与意图日志恢复

延伸阅读

想继续深入,建议按这个顺序读:

登录后查看全文
Nomi