Nomi架构深度解析:Electron主进程、pi Agent运行时与能力核的本地优先设计

原创2026-11-13 20:11:031,818 阅读

Nomi架构深度解析:Electron主进程、pi Agent运行时与能力核的本地优先设计

Nomi 是一个开源、本地优先(Local-first)的 AI 视频工作台:Agent 负责把故事拆成镜头、生成关键帧与视频,并把它们摆上可编辑的真实时间轴。这篇文章带你深入 Nomi 的三层架构——Electron 主进程、pi Agent 运行时与能力核(Capability Core),看懂它为什么能做到"项目、提示词、密钥都留在你的机器上,无账号、无遥测"。

一、Nomi 是什么:本地优先的 AI 视频工作台 🎬

Nomi 的产品形态很简单:你描述想做的片子,它的 Agent 读取画布、拆分镜头、生成关键帧、转成视频,再把结果排进时间轴,最终导出 MP4。模型由你自己接入(APIMart、Kie.ai、火山引擎、ModelScope,或本地 ComfyUI),按供应商原价付费,Nomi 不抽成。

从代码仓库看,Nomi 的目录结构就是它的架构缩影:

目录 职责
electron/ Electron 主进程:本地运行时、存储、模型调用、Agent 运行
src/ React + Vite + Tailwind 渲染层工作台(画布、分镜、时间轴)
skills/ Skill Pack v2 技能包

Nomi AI视频工作台画布与Agent面板

上图就是 Nomi 的"画布 + Agent 面板"组合:左侧画布是生成结果的落地处,右侧 Agent 面板展示它调用了哪些工具、每一步做了什么。

二、Electron 主进程:数据、密钥与模型调用的本地中枢 🔧

Nomi 的所有"重活"都在 Electron 主进程完成,入口是 electron/main.ts。这里有两个值得新手注意的设计:

1. 单实例锁是能力核的前提。 主进程启动时默认申请单实例锁,保证同一 user-data 目录只有一个 Nomi 实例,也就是工程文件的"唯一写者"。这样外部的 CLI / MCP 才能安全地"app 开着走 RPC、关着走 headless"。而 NOMI_MCP_STDIO=1 启动的 MCP 模式则绝不抢锁——它不开窗、不起 IPC,只跑进程内 stdio JSON-RPC(见 electron/main.ts 的注释)。

2. 跨进程通信有严格的"依赖方向铁律"。 渲染层(src/)不允许直接 import 主进程代码,必须走 src/desktop/bridge.ts 经 IPC 通信。这条规则由仓库的边界门岗脚本(check:boundaries)机器化拦截,存量违规冻结在基线里、只减不增。完整的职能归属见 docs/architecture/module-ownership-map.md——"一个功能一个家",比如模型档案定义只住 electron/shared/,供应商目录存储只住 electron/catalog/。

主进程还承担着本地持久化的全部职责:项目(electron/projects/)、设置与 API Key(electron/settings/,密钥经系统安全存储)、素材(electron/assets/)、FFmpeg 导出(electron/export/)。接入模型后的认证与验证也在这里闭环:

Nomi 模型接入与认证验证页面

如上图,每个模型接入后都会在主进程里做一次真实自检(鉴权 + 拉取模型清单),全部通过后才能在画布中使用——这是本地闭环的一部分,不依赖任何远端账号。

三、pi Agent 运行时:Nomi 的 Agent 大脑怎么跑 🧠

Nomi 的 Agent 引擎基于 pi SDK(@earendil-works/pi-agent-core,版本固定在 0.85.1,见 package.json)。它的代码组织分两层:

  • electron/harness/:Agent 的运行核。context/ 负责四层系统提示词、会话恢复与原子落盘;runtime/pi/ 是唯一碰 pi SDK 的适配目录(CJS 主进程通过延迟加载器接入私有 ESM 岛),对外只暴露 Nomi 自己的端口类型,不泄漏 SDK 细节。
  • electron/agentLane/:现役唯一 Agent 通路。生产 IPC 在 electron/main.ts 注册 registerAgentLaneIpc(...),界面通过 useSyncExternalStore 订阅 laneViewModel。

一次指令的完整链路(详见 electron/harness/README.md):

界面/制作入口 → laneIpc(窗口归属、审批、取消)
  → contextService(恢复该 thread 或创建临时上下文)
  → runtimePort → pi AgentSession(模型/工具循环与上下文压缩)
  → Nomi 工具宿主(审批与编辑/生成权威)
  → 工具结果回喂模型 → 稳定收尾 → 保存 → result / done

关键设计是责任切分:pi 只负责"模型/工具循环、原生消息与压缩、SDK 会话";而工具可用范围、花费授权、画布写入、时间轴编辑、预算账本,全部仍归 Nomi 自己的领域模块。换句话说,Skill 是做事方法,不是扩大工具权限的许可证——换个 Skill 名字也绕不过付费审批。这套"模型负责提方案、Runtime 负责验证/授权/执行/记录"的思想,在 docs/guide/agentic-execution-core-concepts.md 里有系统阐述。

Nomi 生成画布与图片生成卡片

上图中画布上的图片节点,就是 Agent 经"审批 → 冻结执行合同 → 提交供应商 → 验证登记 Artifact"这条链路落下来的产物,你可以随时看到它、改掉它。

四、能力核(Capability Core):让 Claude Code 也能驱动 Nomi 🤝

能力核是 electron/capabilityCore/ 把"建工程 / 改画布 / 真生成"做成可被外部调用的接口,对外提供两种用法:

  • CLI:node scripts/nomi.mjs <命令>,适合写脚本批量跑;
  • MCP:把 Nomi 挂成 MCP server(内置 24 个 MCP 工具),Claude Code、Codex、Cursor 把它当工具调用。

它的亮点是"开着关着都能用,自动适配":Nomi 开着时走内部本地服务(A 模式,即时返回);Nomi 关着时自动拉起一个无窗口的后台实例把活干完落盘(B 模式)。完整的上手流程见 docs/guide/capability-core-cli-mcp.md。

两个安全细节值得新手记住:

  1. 外部调用要有 token(正常启动一次 Nomi 后自动生成于 ~/.nomi/capability-core/token),防止任意程序偷用你的额度;
  2. 密钥只在 Nomi 自己的可信页面保存——外部 Agent 全程看不到、也拿不到你的 API Key,接入新模型时由你手动粘贴。

付费生成方面,能力核与主流程共用同一套 ProductionRun 生产链(阶段机 + 门 + 预算账本 + 审批回执 + 幂等,见 electron/productionRun/),外部驱动与界面操作走的是同一个执行出口,不存在"第二写入口"。

Nomi 分镜台:每个镜头独立指定模型与参考卡

上图的分镜台正是能力核能操作的领域对象之一:每个镜头一行(提示词、首帧、模型、时长),锁定参考卡后所有镜头保持一致的角色。

五、本地优先设计总结:你的数据为什么出不去 💾

把前面三层合起来看,Nomi 的"本地优先"不是口号,而是具体落到代码里的几条边界:

  • 项目就是磁盘上的普通文件夹:画布、分镜、时间轴、每个生成文件、导出的成片都在里面,随时可以备份或迁移;
  • 密钥本地安全存储:API Key 走主进程系统安全存储(safeStorage),外部 MCP/CLI 只能拿受限 token;
  • 默认零外发:没有账号体系,匿名使用统计是显式 opt-in(设置 → 隐私与诊断),随时可关;
  • 边界由机器守护:check:boundaries 门岗冻结并棘轮式收敛跨层违规,架构现状以 docs/ARCHITECTURE-NOW.md 这张"现在真正跑的是什么"的表为准。

一句话总结 Nomi 的架构:Electron 主进程守住数据与执行权威,pi Agent 运行时提供可替换的模型/工具循环,能力核把整套本地能力以 CLI/MCP 形式开放给外部 Agent——而所有真相,始终留在你的机器上。

登录后查看全文
Nomi