Nomi 架构拆解:Electron 主进程、Agent 运行时与生产流程引擎如何协作
Nomi 架构拆解:Electron 主进程、Agent 运行时与生产流程引擎如何协作
Nomi 是一个开源、本地优先的 AI 视频创作工作台:用 Agent 完成分镜、关键帧与视频生成,再经画布编排、时间轴剪辑导出 MP4,支持自选模型、API 与本地 ComfyUI,并提供 MCP 接口。这篇文章拆解它最核心的三层架构——Electron 主进程、Agent 运行时(pi lane)与生产流程引擎(productionRun),看看一条指令从输入到出片是怎么流转的。
三层分工:谁负责什么
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/agentLane/:用户唯一能走到的 Agent 通路(会话、审批闸、工具目录、花费确认)
- electron/productionRun/:生产流程引擎,180+ 文件,含预算账本、幂等提交、崩溃恢复
- electron/export/:导出作业管理、FFmpeg 命令构建与执行
- electron/harness/:Agent 运行核导览,见 electron/harness/README.md
一个值得学习的细节:electron/productionRun/productionPlaybooks.ts 把流水线阶段收进注册表——未登记的 playbook 名字在写盘前就抛人话错误,而不是静默降级成一个推不动的坏 Run。
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
三个容易看漏的设计:
- 工具面只有一个 owner:模型看得见哪些工具,全部由 electron/shared/agentCapabilities/verbDeclarations.ts 声明式派生,内部 Agent(lane)与对外 MCP 共享同一份注册表(
modelFacingToolRegistry.ts),不存在"两套工具定义漂移"。 - 审批闸按契约判:工具能不能调用不看名字,看声明的
effect/effectClass;付费边界(花费确认)是独立闸门,Skill 只是做事方法,不是扩大权限的许可证。 - 会话与界面解耦:任务绑定
{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 |
事件流,界面进度展示不轮询、全订阅 |
分镜到时间轴这段同样值得看:planStoryboardTimeline 只负责按 shotIndex 选片,落轴归采纳桥 adoptStoryboardBatch(整批一次写定、一层撤销、带幂等键),字幕与转场正是在采纳桥里落进 textClips[] 与 transitions[]。
导出管线:时间轴如何变成 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/:
- exportJobManager.ts:作业状态机、取消、清理
- exportManifest.ts:manifest 校验与快照读写
- ffmpegFiltergraph.ts:视觉链 / 音频链 / 文字链的 FFmpeg 图;片段音量、淡入淡出与预览共用同一帧语义
- ffmpegRunner.ts:子进程执行、进度解析、原子输出
因为每次导出都基于不可变快照,你在导出进行中继续编辑时间轴,也不会影响已经开始的 job——这是"本地优先"工作台和"网页按钮"最大的区别。
一条指令的完整路径
把三层串起来,一次典型的"生成分镜并出图"指令路径是:
- 界面经 lane IPC 提交指令(固定请求 ID + 任务归属)
- 主进程
agentLane恢复会话,pi AgentSession 启动模型/工具循环 - 模型调用
propose_storyboard_plan等领域工具,高危动作弹审批闸 - 工具结果回喂模型;镜头落进画布与时间轴(采纳桥一次写定)
productionRun推进阶段机:generate 阶段经预算账本 + 幂等提交派发给供应商- 成片经 manifest 快照 → FFmpeg job → 原子写入导出 MP4
- 全程事件流实时驱动界面进度,崩溃后可凭回执与意图日志恢复
延伸阅读
想继续深入,建议按这个顺序读:
- docs/ARCHITECTURE-NOW.md —— 现状权威表,附"常见误解"一栏
- electron/harness/README.md —— Agent 运行核导览与最短阅读顺序
- docs/architecture/nomi-production-video-export-architecture-2026-05-24.md —— 导出架构全文,含对 Kdenlive、Remotion 等开源方案的参考对照
- electron/agentLane/ 与 electron/productionRun/ 的源码文件头注释——团队把"为什么这么设计"写在代码旁边,是很少见的好习惯



