AI 时代的应用引擎

🚀 真正的多线程遇上上下文工程 —— 与 AI 协作者一起构建桌面级 UI。

⚡ 心智模型： Neo.mjs 是一个多线程应用运行时，其中 UI 组件是持久化对象——而非短暂的渲染结果。 这种架构转变实现了桌面级性能、多窗口编排以及传统框架无法实现的 AI 驱动运行时变更。

💻 Neo.mjs 不是一个框架；它是面向 Web 的应用引擎。正如 Unreal Engine 为游戏提供完整的运行时和工具链，Neo.mjs 为企业应用提供多线程运行时和 AI 原生工具链。

想象一下从不卡顿的 Web 应用，无论逻辑多么复杂、处理多少实时更新，或跨越多少个浏览器窗口。Neo.mjs 从头开始设计，旨在提供桌面般的流畅性和可扩展性。虽然它在单页应用（SPA）中表现出色，但 Neo.mjs 无疑是基于浏览器的多窗口应用的最佳选择，其运行方式与传统框架有着根本不同。

通过利用开创性的主线程外（OMT）架构，Neo.mjs 确保您的 UI 保持如黄油般顺滑。主线程仅保留一个用途：完美无瑕的用户交互和无缝的 DOM 更新。

🎯 Neo.mjs 适合您吗？

Neo.mjs 是一个应用引擎，而非网站构建器。 这是一个成熟的企业级平台，拥有超过 13 万行生产就绪代码。

✅ 适用于：

• 金融与交易平台： 每秒处理 1 万+数据更新而不冻结 UI。
• 多窗口工作区： 跨越多屏幕的 IDE、控制室和仪表板。
• AI 原生界面： UI 结构必须在运行时由 AI Agent 变更的应用。
• 企业级 SPA： 需要桌面应用稳定性的复杂逻辑。

❌ 不适用于：

• 静态内容网站或简单博客（请使用 Astro/Next.js）。
• 寻找“不同语法的 React”的团队。
• 不愿接受 Actor 模型（Workers）的开发者。

🚀 AI 原生开发平台

Neo.mjs v11 引入了一种革命性的软件开发方法：上下文工程。我们已超越简单的“AI 辅助”编码，创建了一个真正的 AI 原生平台，其中 AI Agent 是开发过程中深度集成的合作伙伴。这得益于一套专用的模型上下文协议（MCP）服务器，为 Agent 提供理解、构建和推理代码所需的上下文。

这不仅仅是生成代码；而是要创建一个自感知的开发环境，以加速开发速度、提高质量，并实现全新的人机协作水平。

1. 🧠 知识库服务器：为 Agent 提供对项目的深度语义理解。由 ChromaDB 和 Gemini 嵌入提供支持，它允许 Agent 在整个代码库、文档和历史工单中执行语义搜索。Agent 可以提问“VDOM 比对是如何工作的？”，并获得与当前检出版本相关的精确源文件和架构指南。

   • 📘 阅读指南

2. 💾 内存核心服务器：为 Agent 提供持久化、长期记忆。每一次交互——提示、思维过程和响应都被存储，使 Agent 能够从经验中学习、回忆过去的决策，并在多个会话之间保持上下文。这将 Agent 从一个无状态工具转变为与项目共同成长的真正协作者。

   • 📘 阅读指南

3. 🤖 GitHub 工作流服务器：通过让 Agent 直接参与项目生命周期来闭环。它提供用于自主 PR 审查、问题管理以及将 GitHub 问题双向同步到本地可查询的 Markdown 文件集的工具。这消除了代码审查和项目管理中的人为瓶颈。

   • 📘 阅读指南

4. ⚡️ Agent 运行时：让您的 Agent 作为自主开发者行动。Agent 无需被动地请求信息，而是可以使用 Neo.mjs AI SDK 编写并执行复杂脚本。这实现了自愈代码、自动重构和数据迁移等高级工作流——在本地以机器速度运行。

   • 📘 阅读指南

为什么引擎架构对 AI 至关重要

在传统编译型框架（React、Svelte）中，AI agents（AI 代理）是"盲目"的，因为它们编写的代码（JSX/模板）在构建步骤中被销毁——运行时的真实状态（DOM 节点）与源代码完全不同。

在 Neo.mjs 中，地图即领土。 因为组件是 App Worker 中的持久化对象（而非临时的 DOM 节点），AI 可以随时查询它们的状态、方法和继承链。这就像在 Unreal Engine 中检查一个正在运行的游戏角色，而不是解析屏幕上的像素。AI 看到的正是引擎所看到的，使其能够完美准确地推理状态、继承和拓扑结构。此外，Neural Link 允许代理查询运行时的 Ground Truth（真实状态），从而验证现实并解决静态分析无法处理的复杂运行时依赖问题。

这套强大的工具链是与 AI 代理共同创建的，使我们能够在短短 6 周内交付 388 项架构增强。这种数量级的速度提升证明了 Context Engineering（上下文工程）解决了复杂性瓶颈。要了解更多关于这一范式转变的信息，请阅读我们的博客文章：6 周完成 388 个任务：Context Engineering Done Right（正确的上下文工程实践）。

🔗 Neural Link：你的应用是一个活的图

大多数框架为 AI 提供代码的"只读"视图。Neo.mjs 提供对运行时的"读写"访问。

因为 Neo.mjs 组件是持久化对象（乐高机械组）而非临时的 DOM 节点（融化塑料），Neural Link 允许 AI 代理直接连接到引擎的内存。

• Introspection（内省）： 代理可以查询 Scene Graph（场景图）（get_component_tree）以了解 UI 的精确状态。
• Mutation（变更）： 代理可以 hot-patch（热补丁）类方法、修改状态或实时 re-parent（重新父级化）组件，无需重新加载。
• Verification（验证）： 代理可以模拟用户事件（点击、拖拽）来验证它们自己的修复。

📘 阅读 Neural Link 指南

🚀 快速开始：几分钟内创建你的第一个 Neo.mjs 应用

运行以下命令：

npx neo-app@latest

这一行命令会设置你开始使用 Neo.mjs 构建所需的一切，包括：

• 一个新的应用工作区。
• 一个预配置的应用外壳。
• 一个本地开发服务器。
• 在新浏览器窗口中启动你的应用——一步到位。

:book: 需要更多细节？请查看我们的入门指南

:student: 务必深入探索学习专区

下一步：

• :star: 在此体验精彩的演示和示例：Neo.mjs 示例门户
• 更多示例包含在仓库的 apps & examples 文件夹中。
• :blue_book: 所有博客文章列在这里：Neo.mjs 博客
• :robot: 开始使用 AI 知识库快速入门指南。

📦 对象模型：场景图

框架会编译消失。引擎保持存活。

在传统框架中，源代码是创建 DOM 时会被销毁的蓝图。在 Neo.mjs 中，源代码实例化一个 Scene Graph（场景图）——一个存在于 App Worker 中的持久化对象层级结构。

• Lego Technic（乐高机械组）vs. Duplo（得宝）： 大多数框架组件就像"融化塑料"——一旦渲染，就失去了身份。Neo.mjs 组件就像 Lego Technic（乐高机械组）：精密设计的部件，在运行时保留其状态、方法和关系。
• JSON 协议： 因为每个组件都遵循严格的 serialization protocol（序列化协议）（toJSON），整个应用程序表现为一个可变的图。
• Runtime Permutation（运行时置换）： 这允许 AI 代理（或你）即时检查、拆解和重新配置应用——更改布局、在窗口间移动仪表板或热切换主题，无需重新加载。

它不仅仅是一个视图库；它是构建自适应、活应用的 construction kit（构建工具包）。

💡 为什么选择 Neo.mjs？

你在用丰田零件制造 F1 赛车。

传统框架是可靠的通用工具（丰田），为大规模采用牺牲了原始性能。Neo.mjs 为极致性能而精密设计（F1），专为"足够好"不可接受的应用而设计。

1. 通过真正的多线程消除 UI 冻结：

   "浏览器的主线程应该像神经外科医生一样对待：只执行精确、有计划的操作，零干扰。"
   
   — Neo.mjs 核心哲学

   Neo.mjs 的 OMT 架构从根本上防止 UI 冻结。通过优化的渲染管线，即使在密集数据处理期间，您的 UI 也能保持持续响应。在优化环境中，它实现了惊人的**每秒超过 40,000 次 delta updates（增量更新）**速率，潜力仅受用户交互限制，而非平台限制。

2. AI 原生工作流带来前所未有的速度： 集成的 MCP 服务器提供了一个"上下文丰富"的环境，AI 代理可以与人类开发者并肩工作。这使得自主代码审查、深度代码库分析以及对项目历史的共同理解成为可能，极大地加速了开发，并解决了复杂项目的 bus factor（巴士因子） 问题。

3. 构建桌面级、多窗口应用： Neo.mjs 是构建复杂多窗口 Web 应用的首选解决方案，如交易平台、基于浏览器的 IDE、Outlook 风格的邮件客户端和多屏 LLM 界面。其共享 worker 架构允许单个应用实例在多个浏览器窗口中运行，具有实时状态同步和无缝跨窗口移动组件的能力。

4. 无与伦比的开发者体验：无需转译的 ESM： 告别复杂的构建步骤。Neo.mjs 应用以 ES 模块（ES Modules）形式直接在浏览器中原生运行。这意味着开发模式下零构建或转译，提供即时重载和前所未有的调试体验，所见即所调。

5. 设计固有的安全性： 通过优先使用直接 DOM API 操作而非基于字符串的方法（如 innerHTML），Neo.mjs 从根本上减少了跨站脚本攻击（Cross-Site Scripting, XSS）等漏洞的攻击面，从一开始就构建更健壮、更安全的应用。

📊 实战胜利：彻底消除 UI 延迟（UI Lag）

想象一下，一位开发者正在构建一个股票交易应用，其实时数据流每毫秒都在更新。传统框架往往会不堪重负，在数据洪流下冻结 UI。而使用 Neo.mjs，繁重的处理工作在 worker 线程（工作线程）中完成，让主线程（main thread）保持空闲。交易者可以获得零延迟的实时更新，应用体验如同原生桌面工具。现在，想象一下将这一能力扩展到多个同步的浏览器窗口，每个窗口显示不同的实时视图，全部保持如黄油般顺滑。这就是 Neo.mjs 的实战能力——解决其他框架无法触及的问题。

🌟 引擎子系统（Engine Subsystems）及其如何为您的应用注入超强动力

• 线程子系统（Threading Subsystem）：一个专用的协调器，将应用逻辑（App Worker）与渲染逻辑（Main Thread）以及数据处理（Data Worker）隔离开来。这确保了主线程始终可以响应用户输入，从而在架构层面消除 UI 卡顿（UI jank）。

• 渲染管线（Rendering Pipeline）：正如游戏引擎向 GPU（图形处理器）发送绘制调用（draw calls），Neo.mjs 的 App Worker 向主线程发送压缩的 JSON 增量。这种**非对称 VDOM（Asymmetric VDOM）**方法比主线程 diff 操作更快、更安全，也更适合 AI。

• 场景图（对象持久性，Object Permanence）：作为持久化应用引擎，Neo.mjs 组件在 App Worker 中是活跃实体（live entities），如同场景图（Scene Graph）中的节点。即使从 DOM 中分离，它们也能保留自身状态和身份。这实现了运行时变换（Runtime Permutation）：能够在运行时拖动活跃仪表板跨窗口，或重新挂载复杂工具而不丢失上下文。

• 组件系统（Component System）：Neo.mjs 提供两种强大的组件模型。**函数式组件（Functional Components）**是近期引入的，提供了更简单的上手体验和现代的、基于 hook 的开发风格（defineComponent、useConfig、useEvent），与其他流行框架类似，非常适合更简单、更具声明性的 UI。对于需要精细控制 VDOM 变更以及与引擎生命周期深度集成的高级用例，**类组件（Class-Based Components）**提供了更强大的功能和灵活性，尽管代码开销稍大。两种模型可以无缝互操作，让您为应用的每个部分选择合适的工具，同时享受我们多线程架构带来的无与伦比的性能。最重要的是，我们的函数式组件免受了传统 UI 库困扰的"记忆化开销（memoization tax）"（useMemo、useCallback）之苦。

• 状态子系统（State Subsystem）：借助 Neo.state.Provider，Neo.mjs 提供了原生集成的分层状态管理。组件通过简洁的 bind 配置声明其数据需求。这些 bind 函数充当强大的内联公式，允许组件自动响应变更，并在组件层级内组合来自多个状态提供者的数据。这确保了动态、高效的更新——从简单的属性变更到复杂的计算值——全部在主线程之外处理。

  // Example: A component binding its text to state
  static config = {
      bind: {
          // 'data' here represents the combined state from all parent providers
          myComputedText: data => `User: ${data.userName || 'Guest'} | Status: ${data.userStatus || 'Offline'}`
      }
  }
  

• 逻辑子系统（Logic Subsystem）：视图控制器（View controllers）确保清晰的关注点分离，将业务逻辑与 UI 组件隔离，便于维护、测试和团队协作。

• 多窗口与单页应用（SPAs）：除了传统的 SPA，Neo.mjs 在复杂的多窗口应用方面表现出色。其独特的架构通过无缝的跨 worker 通信和可扩展的主线程插件（Main Thread addons），实现了真正类似原生、跨浏览器窗口的持久化体验。

• 模块系统（Module System）：Neo.mjs 应用以零运行时依赖运行，仅包含少量用于工具链的开发依赖。这意味着更小的包体积、更少的冲突和更简单的依赖关系图。

• 无与伦比的调试体验：受益于 Neo.mjs 内置的调试能力。可以轻松检查跨 worker 的完整组件树，直接在浏览器控制台中实时修改组件配置，并观察实时 UI 更新，所有这些都无需复杂的工具链设置。

• 非对称 VDOM 与 JSON 蓝图：应用逻辑处理的是简单的、可序列化的 JSON 对象，而非复杂的、基于类的 VNode 树。这些蓝图被发送到专用的 VDOM worker 进行高性能 diff 操作，确保主线程永远不会被渲染计算阻塞。这种架构不仅更快，而且本质上更安全，也更易于 AI 工具生成和操作。

• 异步感知组件生命周期：通过 initAsync() 生命周期方法，组件可以在被视为"就绪"之前处理异步初始化（如获取数据或懒加载模块）。这消除了整类竞态条件（race conditions）和 UI 闪烁（UI flicker），让您能够自信地构建复杂的数据依赖组件。

图示：Neo.mjs 多线程架构的高层次概览（主线程 Main Thread、App Worker、VDom Worker、Canvas Worker、Data Worker、Service Worker、后端）。可选 worker 在 neomjs.com 上悬停时淡入。

🔍 引擎架构：运行时（Runtime）与工具链（Toolchain）

正如游戏引擎（Game Engine）由运行时（Runtime）（玩家使用的部分）和编辑器（Editor）（开发者使用的部分）组成，Neo.mjs 也分为两个互补的层。

1. 运行时（Neo.mjs 核心）

在浏览器中运行。生产就绪（Production-Ready）。零膨胀（Zero-Bloat）。

这是驱动您应用的高性能引擎。它基于**多线程架构（multi-threaded architecture）**运行，隔离主线程以确保即使在重负载下也能保持 60fps 的流畅度。

• App Worker： 运行您的整个应用逻辑、状态和虚拟 DOM diff。
• 多窗口编排（Multi-Window Orchestration）： 单个引擎实例可以通过 SharedWorkers（共享 worker）驱动多个浏览器窗口。组件可以无缝地在窗口之间拖放和移动——这对于复杂的"控制室（Control Room）"界面至关重要。
• 主线程（Main Thread）： 被视为"哑渲染器"，仅应用高效的 DOM 补丁。
• 对象持久性（Object Permanence）： 组件是持久化实体，可以被移动、分离和重新挂载而不会丢失状态。

2. 工具链（Agent OS）

运行于 Node.js。仅开发时使用。AI 原生。

这是 AI 时代的"编辑器"。它将你的开发环境与运行中的引擎连接起来，让 AI 代理成为一等协作者（first-class collaborators）。

• Neural Link（神经链接）： 一个双向桥梁，允许代理"查看"和"修改"实时运行时图谱。
• MCP Servers（MCP 服务器）： 为代理提供深度上下文（Knowledge Base/知识库）和记忆（Memory Core/记忆核心）。
• Context Engineering（上下文工程）： 一种结构化工作流，代理通过理解引擎架构来帮助你构建引擎。

结果： 你不仅仅是编写代码；你是在与一位完全理解引擎工作原理的 AI 伙伴共同培育一个活的系统。

规模化平台：不仅仅是库

要理解 Neo.mjs 的广度，重要的是了解它的规模。这不是一个微型库；而是一个全面的、企业级平台（enterprise-ready platform），代表了超过十年的架构投入。Neo.mjs 是一个创新工厂（innovation factory）。

以下统计数据来自 2026 年 1 月，展示了生态系统的概况。如需深入了解，你可以探索完整的 代码库概览。

• 约 45,000 行 核心平台源代码
• 约 36,000 行 数百个实用示例和旗舰应用代码
• 约 12,000 行 生产级主题系统（production-grade theming）
• 约 14,000 行 专用 AI 原生基础设施（AI-native infrastructure）
• 约 53,000 行 详细的 JSDoc 文档

总计：超过 170,000 行精心策划的代码和文档。

这不是一个小型库——它是一个完整的生态系统，源代码行数超过许多成熟框架，专为最苛刻的使用场景而设计。

📚 基础架构：核心原则

v10 版本标志着 Neo.mjs 核心的重大演进，引入了全新的函数式组件模型（functional component model）和革命性的双层响应式系统（two-tier reactivity system）。这些原则构成了框架今天的基石。我们发布了一个五篇博客系列，深入探讨这一架构：

1. 前端爱情故事：为何今天的策略无法构建明天的应用
   • 介绍现代前端开发中的核心问题以及 Neo.mjs 的架构愿景。
2. 深度解析：命名状态 vs 匿名状态——组件响应性的新时代
   • 探索强大的双层响应式系统，让"记忆化开销（memoization tax）"成为过去。
3. 超越 Hooks：面向多线程世界的新型函数式组件
   • 了解多线程世界中的函数式组件如何消除传统 hooks 的权衡。
4. 深度解析：VDOM 革命——JSON 蓝图与非对称渲染
   • 学习我们的离线程 VDOM 引擎如何使用简单的 JSON 蓝图（JSON Blueprints）实现最大性能和安全性。
5. 深度解析：状态提供者革命
   • 深入了解强大、可轻松扩展的分层状态管理（hierarchical state management）系统。

⚙️ 声明式类配置：更快构建，更易维护

Neo.mjs 的类配置系统（class config system）允许你以声明式且可复用的方式定义和管理类。这简化了类创建，减少了样板代码（boilerplate code），并提高了可维护性。

import Component from '../../src/component/Base.mjs';

/**
 * Lives within the App Worker
 * @class MyComponent
 * @extends Neo.component.Base
 */
class MyComponent extends Component {
    static config = {
        className   : 'MyComponent',
        myConfig_   : 'defaultValue', // Reactive property
        domListeners: {               // Direct DOM event binding
            click: 'onClick'
        }
    }

    // Triggered automatically by the config setter when myConfig changes
    afterSetMyConfig(value, oldValue) {
       console.log('myConfig changed:', value, oldValue);
    }

    // Executed in the App Worker. The Main Thread (UI) never sees this logic.
    onClick(data) {
        console.log('Clicked!', data);
    }
}

export default Neo.setupClass(MyComponent);

// -------------------------------------------------------
// The Engine allows Runtime Mutation:
// An AI agent (or you) can inspect and modify this instance LIVE without a reload.
// -------------------------------------------------------

// Agent Command (via Neural Link):
Neo.get('my-component-id').set({
    myConfig: 'newValue',
    style   : { color: 'red' } // Instant update via OMT Rendering Pipeline. No build step. No reload.
});

对于每个以下划线（_）结尾的配置属性，Neo.mjs 会自动在类原型上生成 getter 和 setter。这些 setter 确保变更会触发相应的生命周期钩子（lifecycle hooks），提供强大的内置响应式系统：

• beforeGetMyConfig(value)
  （可选）在通过 getter 返回配置值之前调用，允许进行最后一刻的转换。
• beforeSetMyConfig(value, oldValue)
  （可选）在设置配置值之前调用，允许你拦截、验证或修改新值。返回 undefined 将取消更新。
• afterSetMyConfig(value, oldValue)
  （可选）在配置值已成功设置并检测到变更后调用，允许执行副作用或响应新值。

更多详情，请查看 类配置系统文档。

🤝 社区与支持

有问题或想与社区交流？我们有两个渠道可以帮助你。

• 💬 Discord（推荐用于提问和历史记录）： 我们的主要社区中心。所有对话都会永久存档且可搜索，是提问和查找过往答案的最佳场所。
• ⚡️ Slack（用于实时聊天）： 适合快速、实时的对话。请注意，免费版的历史记录是临时的（消息会在 90 天后删除）。

🧭 愿景与路线图

要了解项目的长期目标和未来方向，请查看我们的战略文档：

• ✨ 愿景： 了解核心哲学以及我们架构背后的"为什么"。
• 🗺️ 路线图： 查看我们正在开发的内容以及未来的计划。

:handshake: 如何贡献

:hammer_and_wrench: 想要参与贡献吗？请查看我们的贡献指南。

版权所有 (c) 2015 - 至今，Tobias Uhlig

Neo.mjs 快速上手指南

环境准备

系统要求

• 操作系统：Windows 10/11、macOS 10.15+ 或 Linux
• Node.js：v18.0.0 或更高版本（推荐 v20+）
• npm：v9.0.0 或更高版本（随 Node.js 一起安装）
• 浏览器：Chrome 90+、Firefox 88+、Safari 14+ 或 Edge 90+

前置依赖

确保已安装 Node.js 和 npm：

node --version
npm --version

如果未安装，请访问 Node.js 官网 下载并安装 LTS 版本。

安装步骤

使用以下命令一键创建并启动你的第一个 Neo.mjs 应用：

npx neo-app@latest

该命令将自动完成：

• 创建新的应用工作区
• 生成预配置的应用外壳
• 安装所有依赖包
• 启动本地开发服务器
• 在浏览器中打开应用

注意：首次运行可能需要几分钟时间下载依赖，请耐心等待。

基本使用

启动开发服务器

命令执行成功后，开发服务器会自动启动并打开浏览器窗口。默认访问地址为：

• 本地地址：http://localhost:8080

项目结构

创建完成后，你的项目将包含以下核心目录：

my-neo-app/
├── apps/                 # 应用主代码
├── resources/            # 静态资源
├── src/                  # 源码
└── neo-config.json       # 配置文件

开发流程

1. 修改代码：编辑 apps/ 目录下的组件文件
2. 实时预览：保存后浏览器自动刷新（热更新）
3. 构建生产版本：运行 npm run build 生成优化后的生产包

下一步学习

• 体验官方示例：Neo.mjs 示例门户
• 查看完整教程：入门指南
• AI 开发指南：AI 知识库快速入门
• 在线学习资源：Neo.mjs 学习中心

---

提示：Neo.mjs 采用多线程架构，所有业务逻辑在 Web Worker 中运行，主线程仅负责 DOM 更新，确保 UI 始终保持流畅。