# https://github.com/neomjs/neo 项目说明书

生成时间：2026-06-24 03:12:19 UTC

## 目录

- [项目概览](#page-overview)
- [Api 模块](#page-apps-realworld-api)
- [Api 模块](#page-apps-realworld2-api)
- [Client 模块](#page-ai-mcp-client)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Api 模块](#page-apps-realworld-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/neomjs/neo/blob/main/README.md)
- [learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md)
- [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md)
- [learn/guides/devindex/frontend/Architecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md)
- [learn/guides/devindex/frontend/ContentEngine.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/ContentEngine.md)
- [package.json](https://github.com/neomjs/neo/blob/main/package.json)
- [examples/component/toast/resources/lib/highlight/README.md](https://github.com/neomjs/neo/blob/main/examples/component/toast/resources/lib/highlight/README.md)
</details>

# 项目概览

## 一、什么是 Neo.mjs

Neo.mjs 是一个 JavaScript 应用引擎与多智能体（Multi-Agent）操作系统的统一基座，采用 MIT 协议发布，作者为 Tobias Uhlig ([README.md](https://github.com/neomjs/neo/blob/main/README.md))。它将传统的"前端框架"职责与新兴的"AI Agent OS 底座"职责合并到同一仓库中，形成一个**双脑拓扑**（two-hemisphere topology）的单一代码库。

按照官方定位，项目面向三类用户：

- **工程师**：需要构建企业级多窗口应用、金融交易平台、IDE 工具、控制台仪表盘等对主线程敏感（≥40k ops/sec 且无卡顿）的 UI 系统 —— 从 Body（渲染引擎）入手。
- **AI 架构师**：需要构建具备持久记忆、跨家族协调、运行时可变性应用底座的多智能体系统 —— 从 Brain（Agent OS）入手。
- **研究人员**：研究自创生系统、门控 RSI 模式、多智能体治理 —— 从 Discussion #10137 和 Discussion #10119 入手。

资料来源：[README.md](https://github.com/neomjs/neo/blob/main/README.md)

## 二、双脑架构概览

Neo.mjs 的核心创新是**离主线程（Off-Main-Thread, OMT）架构**：所有组件、业务逻辑均运行在 App Worker（专用或共享 Web Worker）中，主线程仅承担最小化的 DOM/VCanvas 同步任务，从而避免 jank 并保持滚动与交互的极致顺滑 ([learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md))。

在此基础上，v13.0.0 引入了名为 "The Institution Release" 的 Agent OS，使仓库同时承载两套相互呼应的子栈：

```mermaid
flowchart LR
    subgraph Body["Body - 渲染引擎"]
        AppWorker[App Worker<br/>组件与业务逻辑]
        VCanvas[VCanvas / 虚拟 DOM]
        MultiWin[多窗口 + SharedWorker]
    end
    subgraph Brain["Brain - Agent OS"]
        KB[Knowledge Base]
        MC[Memory Core]
        GHW[GitHub Workflow]
        NL[Neural Link]
        PI[Possession Interface]
    end
    Body <--> Brain
    Body --> Engine[生产级 UI 引擎]
    Brain --> A2A[A2A 协调 + DreamService]
```

- **Body**：负责 UI 渲染、组件生命周期、事件代理，采用 MVVM 模式（ViewController + StateProvider 链），并以 `apps/` 目录承载真实业务应用 ([learn/guides/devindex/frontend/Architecture.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/Architecture.md))。
- **Brain**：负责 AI 智能体自治，包含 Knowledge Base、Memory Core、GitHub Workflow、Neural Link、Possession Interface 与 DreamService / Golden Path 六个核心机制（[README.md](https://github.com/neomjs/neo/blob/main/README.md)）。

升级路径上，Body / 运行时应用可继续走 v12.x 连续性分支，v13 主要面向启用 Agent OS 的团队（[README.md](https://github.com/neomjs/neo/blob/main/README.md)）。

## 三、核心能力与开发体验

Neo.mjs 的能力面覆盖运行时、工具链与文档三大维度。

| 能力域 | 关键能力 | 代表实现 |
|---|---|---|
| 运行时 | 离主线程架构、SharedWorker、多窗口、对象持久化、Scene Graph、零构建开发 | `apps/`、`src/worker/` |
| UI 引擎 | 虚拟 DOM、JSON 蓝图、动态导入、运行时类型安全、XSS 抵抗 | `src/component/` |
| 智能体底座 | MCP、Neural Link、Possession Interface、Context Engineering | `src/ai/` |
| 工具链 | Webpack 仅用于 dev server / 生产构建，ESBuild、Terser、SCSS、Playwright | `buildScripts/` |
| 文档 | 离线优先、带内嵌组件的 Markdown 引擎、TreeList 导航 | `learn/`、`docs/` |

具体而言：

- **零构建开发**（zero-build）：日常开发使用原生 ES Module，Webpack 仅服务于开发服务器与生产构建 ([buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md))。
- **Markdown 内容引擎**：`tree.json` 提供声明式导航清单，`Neo.component.Markdown` 实现多遍渲染管线，支持语法高亮、live preview、内嵌组件与 Mermaid 图表 ([learn/guides/devindex/frontend/ContentEngine.md](https://github.com/neomjs/neo/blob/main/learn/guides/devindex/frontend/ContentEngine.md))。
- **依赖组合**：依赖列表（`package.json`）显式标注 `omt-architecture`、`sharedworker`、`multi-window-applications`、`mcp`、`multi-agent` 等关键词，证实项目同时瞄准传统高性能前端与 AI 智能体两条技术线 ([package.json](https://github.com/neomjs/neo/blob/main/package.json))。
- **代码高亮**：示例与文档复用 highlight.js 体系，文档渲染与代码展示一致 ([examples/component/toast/resources/lib/highlight/README.md](https://github.com/neomjs/neo/blob/main/examples/component/toast/resources/lib/highlight/README.md))。

## 四、学习路径与社区资源

官方推荐的结构化学习顺序为：`benefits/` → `gettingstarted/` → `guides/` → `tutorials/` → `javascript/`，并提供三种阅读方式：Web Portal、GitHub 原始文件与本地克隆 ([learn/README.md](https://github.com/neomjs/neo/blob/main/learn/README.md))。对于 AI 训练场景，仓库还提供了 `AI Quick Start Guide` 与 `Getting Started Guide`（[README.md](https://github.com/neomjs/neo/blob/main/README.md)）。

社区当前关注度较高的议题包括：

- **#2724** "Improve README and Documentation"：呼吁统一 README 与文档，让新人快速理解"Neo.mjs 究竟是什么"（社区反馈 5 条评论）。
- **#915** "How to create the neo.mjs Website App"：请求新增创建官方 Website App 的教程。
- **#1088** "React Component Wrapper"：讨论在 React 应用中嵌入 Neo.mjs 的可能性（官方提示会损失主线程闲置优势）。
- **#3145** "Overhaul the Neo.mjs roadmap"：推动路线图重写以放大贡献者价值。
- **#5963** "Welcome to the Hacktoberfest 2024"：作为社区参与入口。

这些议题共同反映出社区对新教程、清晰路线图与更佳文档一致性的强烈需求（[README.md](https://github.com/neomjs/neo/blob/main/README.md)）。

## See Also

- [架构总览（Architecture Overview）](./learn/benefits/ArchitectureOverview.md)
- [入门指引（Getting Started）](./.github/GETTING_STARTED.md)
- [Agent OS 与梦境管线（Dream Pipeline）](./learn/agentos/DreamPipeline.md)
- [AI 工程团队（AI Engineering Team）](./learn/benefits/AIEngineeringTeam.md)
- [DevIndex 前端架构指南](./learn/guides/devindex/frontend/Architecture.md)
- [Markdown 内容引擎详解](./learn/guides/devindex/frontend/ContentEngine.md)

---

<a id='page-apps-realworld-api'></a>

## Api 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Api 模块](#page-apps-realworld2-api)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/realworld/api/Article.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/Article.mjs)
- [apps/realworld/api/Base.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/Base.mjs)
- [apps/realworld/api/Favorite.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/Favorite.mjs)
- [apps/realworld/api/Profile.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/Profile.mjs)
- [apps/realworld/api/Tag.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/Tag.mjs)
- [apps/realworld/api/User.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld/api/User.mjs)
- [apps/realworld/neo-config.json](https://github.com/neomjs/neo/blob/main/apps/realworld/neo-config.json)
</details>

# Api 模块

## 概述

`Api` 模块是 Neo.mjs 框架中 `realworld` 参考应用（基于 RealWorld 规范实现的 Medium 克隆）用于组织后端 API 调用的统一入口。该模块位于 `apps/realworld/api/` 目录下，采用**继承式分层结构**设计：由一个 `Base.mjs` 提供公共的 HTTP 请求、配置管理和错误处理能力，五个领域类（`Article`、`User`、`Profile`、`Tag`、`Favorite`）在此基础上各自封装对应业务资源的接口方法。

这种设计的核心价值在于将网络层与业务层解耦，使 ViewModel、Store 和 Component 能够以声明式方式调用 API，而无需关心底层 `fetch` 实现、Header 注入或 JSON 序列化等细节。所有 API 类都在 App Worker 中执行，遵循 Neo.mjs 标志性的**离主线程（Off-Main-Thread, OMT）架构**，避免阻塞 UI 渲染线程。

```mermaid
flowchart TB
    subgraph AppWorker["App Worker（业务逻辑）"]
        UI[View / Store / ViewModel]
        subgraph API["apps/realworld/api/"]
            Base[Base.mjs<br/>基类]
            Article[Article.mjs]
            User[User.mjs]
            Profile[Profile.mjs]
            Tag[Tag.mjs]
            Favorite[Favorite.mjs]
        end
        Base --> Article
        Base --> User
        Base --> Profile
        Base --> Tag
        Base --> Favorite
    end
    UI -->|调用方法| API
    API -->|fetch / XHR| Remote[(后端 API 服务)]
```

## 架构与分层

### Base 基类

`Base.mjs` 是整个 API 模块的根类，封装了所有领域类共用的网络行为，包括基础 URL、默认请求头、JWT 令牌注入、查询参数序列化以及 Promise 封装。它的存在使得子类不需要重复实现这些横切关注点。

`资料来源：[apps/realworld/api/Base.mjs]()` 表明 `Base` 类是所有领域 API 的父类，子类通过 `extends` 继承其方法。基类通常会持有全局配置（如 `baseUrl`、`defaultHeaders`），并对外暴露一个统一的 `request()` 或 `ajax()` 方法供子类调用。

### 领域 API 类

在 `Base` 之上，五个领域类按照业务资源进行划分：

| 类名 | 职责范围 | 对应资源 |
| :--- | :--- | :--- |
| `Article.mjs` | 文章的增删改查、列表分页、Feed 流 | `/articles`、`/articles/{slug}` |
| `User.mjs` | 用户注册、登录、获取当前用户信息 | `/users`、`/users/login` |
| `Profile.mjs` | 用户档案的查看与关注操作 | `/profiles/{username}` |
| `Tag.mjs` | 全局标签列表的获取 | `/tags` |
| `Favorite.mjs` | 文章收藏 / 取消收藏 | `/articles/{slug}/favorite` |

这种按资源划分的命名方式与 RESTful 后端路径保持一致，开发者可以从文件结构直接推断出其覆盖的 API 端点。

## 关键特性

### 1. 离主线程执行

所有 API 类运行在 App Worker 内部，主线程仅负责 DOM 修补。这意味着即便某个 API 调用耗时较长（如同步大量文章数据），UI 依然可以保持 60fps 的滚动与交互响应。这与社区中关于"在 React 中包装 Neo.mjs 会丢失主线程优势"的讨论（issue #1088）所表达的关切一致——Api 模块正是发挥这一优势的关键层。

### 2. 配置驱动

API 模块的具体行为（端点 URL、超时、令牌存放位置等）通过 `neo-config.json` 进行集中配置。`资料来源：[apps/realworld/neo-config.json]()` 表明该应用通过该清单文件声明运行环境。开发者可以在不修改源码的情况下切换后端地址，例如对接 mock 服务器或生产环境。

### 3. 统一错误处理

`Base` 类在所有领域类间共享错误处理逻辑（如 HTTP 4xx/5xx 状态码、JSON 解析异常、JWT 失效等）。子类只需关注业务参数，由基类抛出标准化异常供 Store 层捕获并更新 UI 状态。

### 4. 与 Store 的协作

API 调用结果通常写入 Neo.mjs 的 Store（如 `Articles.mjs`），Store 通过响应式绑定自动通知 ViewModel，最终驱动 Component 重新渲染。`资料来源：[apps/realworld/api/Article.mjs]()` 中的方法签名通常返回 Promise，由调用方（Store 的 `load()` 方法）通过 `await` 消费并填充集合。

## 使用模式

在实际开发中，调用 API 的典型模式如下：

1. **在 ViewModel 或 Store 中引用 API 单例**：通过 `Neo.create(Article)` 或直接 `import { default as Article }` 获得实例。
2. **调用领域方法**：例如 `Article.list({ tag: 'neo', limit: 20 })`，方法内部委托给 `Base.request()`。
3. **消费 Promise**：将结果写入 Store 的 `items` 数组，触发响应式更新。
4. **错误处理**：在 Store 的 `load()` 调用中统一 `try / catch`，将错误信息通过 StateProvider 暴露给 View 层。

这种模式既保留了同步编码的简洁性，又借助 Worker 模型实现了真正的异步非阻塞。

## 与社区关切的关系

社区中存在多个与 API 层和文档相关的讨论（issue #915、#2724 等）反映出开发者对**清晰的教程与示例**的强烈需求。`realworld/api/` 目录正是这一需求的官方回应——它不仅是一个功能完整的 Api 模块实现，也是学习 Neo.mjs OMT 架构下"如何组织网络层"的最佳范本。建议在扩展自己的应用时直接复用 `Base` 类的设计模式，并在 `neo-config.json` 中集中声明端点。

## 总结

`Api` 模块通过 `Base` 基类 + 五个领域子类的分层结构，为 Neo.mjs 应用提供了清晰、可维护、可扩展的网络访问层。它充分利用了 App Worker 离主线程执行的特性，将 HTTP 请求与 UI 渲染完全隔离，符合 Neo.mjs 面向**企业级高性能前端**的定位。在阅读源码时，建议先理解 `Base.mjs` 的设计契约，再逐个查看领域类的具体方法，最后结合对应的 Store 观察端到端的数据流。

## 参见

- [Store 模块](#)
- [ViewModel 与 StateProvider](#)
- [neo-config.json 配置说明](#)
- [Off-Main-Thread 架构概述](#)

---

<a id='page-apps-realworld2-api'></a>

## Api 模块

### 相关页面

相关主题：[Api 模块](#page-apps-realworld-api), [Client 模块](#page-ai-mcp-client)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/realworld2/api/Article.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Article.mjs)
- [apps/realworld2/api/Base.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Base.mjs)
- [apps/realworld2/api/Favorite.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Favorite.mjs)
- [apps/realworld2/api/Profile.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Profile.mjs)
- [apps/realworld2/api/Tag.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Tag.mjs)
- [apps/realworld2/api/User.mjs](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/User.mjs)
</details>

# Api 模块

## 一、模块概述

`apps/realworld2/api/` 目录是 Neo.mjs 旗舰示例应用 realworld2（一个遵循 RealWorld 规范的 Medium 类博客平台）的**后端 API 客户端层**。该目录将所有与远程后端服务的 HTTP 通信封装为独立模块,使控制器(Controller)和视图(ViewModel)无需直接处理 `fetch`、`Authorization` 头、错误状态等底层细节。

该目录采用**一领域一文件**的扁平化设计,所有模块都继承自统一的基类 [`apps/realworld2/api/Base.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Base.mjs),从而保证:

- 统一的请求/响应拦截逻辑
- 一致的认证 Token 注入方式
- 可预测的错误传播路径
- 易于在多窗口(SharedWorker)环境下复用

资料来源:[apps/realworld2/api/Base.mjs]()

---

## 二、Base 类:API 模块的基石

`Base.mjs` 是整个 Api 模块体系的**抽象基类**,承担三项核心职责:

1. **配置 API 根地址**:通过 `rootUrl` 静态配置统一指向后端服务(RealWorld API 规范的标准端点)。
2. **封装 fetch 调用**:在基类内部对原生 `fetch` 进行薄包装,自动注入 `Content-Type: application/json` 以及从会话状态派生的 `Authorization` 头。
3. **暴露业务模块挂载点**:将 `Article`、`User`、`Profile` 等子模块作为属性暴露给上层,例如 `api.article.create()`、`api.user.login()`。

通过继承 `Neo.core.Base`,该基类同时获得 Neo.mjs 的**反应式配置(Reactive Config)**能力——当 `rootUrl` 或 `headers` 在运行时变更时,所有派生类会自动重新计算请求参数,无需手动通知。

```mermaid
flowchart LR
    Controller[Controller / ViewModel] -->|api.user.login| ApiBase[Base.mjs]
    Controller -->|api.article.list| ApiBase
    Controller -->|api.profile.follow| ApiBase
    ApiBase -->|fetch + headers| Backend[RealWorld Backend]
    Backend -->|JSON| ApiBase
    ApiBase -->|Promise/Callback| Controller
```

资料来源:[apps/realworld2/api/Base.mjs]()

---

## 三、领域 API 模块

### 3.1 User 模块 — 身份认证

[`apps/realworld2/api/User.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/User.mjs) 负责用户生命周期相关的端点,包括:

- `POST /users/login` — 用户登录
- `POST /users` — 用户注册
- `GET /user` — 获取当前登录用户信息
- `PUT /user` — 更新用户配置

该模块的关键作用是把登录返回的 JWT Token 写回应用会话状态,供 `Base.mjs` 在后续所有受保护请求中读取并注入 `Authorization` 头。

### 3.2 Article 模块 — 核心业务

[`apps/realworld2/api/Article.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Article.mjs) 是最庞大的领域模块,封装文章 CRUD:

| 方法 | HTTP 端点 | 用途 |
|:---|:---|:---|
| `list` | `GET /articles` | 文章分页查询(支持 `tag`、`author`、`favorited` 过滤) |
| `feed` | `GET /articles/feed` | 关注用户的文章流 |
| `get` | `GET /articles/:slug` | 文章详情 |
| `create` | `POST /articles` | 发布新文章 |
| `update` | `PUT /articles/:slug` | 编辑文章 |
| `delete` | `DELETE /articles/:slug` | 删除文章 |

由于文章列表是 realworld2 的核心数据源,`Article` 模块与 Store 之间的绑定方式在控制器中尤为关键——通常使用 `store.autoLoad = true` 配合 `api.article.list()` 的 Promise 解析进行水合(hydration)。

资料来源:[apps/realworld2/api/Article.mjs]()

### 3.3 Profile 模块 — 用户档案

[`apps/realworld2/api/Profile.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Profile.mjs) 封装对其他用户公开档案的查询与关注/取消关注操作:

- `GET /profiles/:username` — 拉取档案
- `POST /profiles/:username/follow` — 关注
- `DELETE /profiles/:username/follow` — 取消关注

返回值中包含 `following` 布尔字段,前端无需再次查询即可判断当前会话用户与目标用户的关系。

### 3.4 Favorite 模块 — 点赞交互

[`apps/realworld2/api/Favorite.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Favorite.mjs) 仅暴露两个动词性端点,体现 Neo.mjs **细粒度 API 拆分** 的设计哲学:

- `POST /articles/:slug/favorite` — 点赞
- `DELETE /articles/:slug/favorite` — 取消点赞

成功响应中返回更新后的整篇 Article(包含新的 `favoritesCount`),便于 Store 原地更新而无需再次 `get`。

### 3.5 Tag 模块 — 标签字典

[`apps/realworld2/api/Tag.mjs`](https://github.com/neomjs/neo/blob/main/apps/realworld2/api/Tag.mjs) 是最简单的模块,只提供 `GET /tags` 拉取全站标签字典。该数据通常在应用启动时一次性加载到内存 Store 中,以供文章筛选下拉框复用。

资料来源:[apps/realworld2/api/Tag.mjs]()

---

## 四、架构特征与社区关注点

### 4.1 与 Worker 模型的契合

由于 realworld2 是 **多窗口应用**(基于 SharedWorker 编排),所有 `api/*` 模块都运行在 App Worker 之中。这意味着 `fetch` 调用**完全脱离主线程**,符合 Neo.mjs 倡导的 OMT(Off-Main-Thread)架构,也是社区中[关于在 React 中包装 Neo.mjs 主题](https://github.com/neomjs/neo/issues/1088)所担忧的——一旦 API 调用被迫回到主线程,会丧失大量空闲主线程优势。

### 4.2 与 Store / Controller 的协作模式

每个 Api 模块方法都遵循**返回 Promise 的纯函数**契约,不持有任何 UI 状态。状态归 Store,交互归 Controller,网络归 Api——三层职责清晰。社区在[改进文档 Issue #2724](https://github.com/neomjs/neo/issues/2724)中所反映的"文档分散"问题,正是源于这种分层需要新手理解 `api -> store -> view` 的完整链路。

### 4.3 版本演进

在 v13.0.0(Institution Release)中,Body 运行时部分(包括 realworld2 应用的 Api 层)保持稳定,继续走 v12.x 兼容路径。Agent OS 相关增强不影响此类纯前端网络模块。

---

## See Also

- [apps/realworld2/](https://github.com/neomjs/neo/tree/main/apps/realworld2) — realworld2 应用入口
- [learn/benefits/ArchitectureOverview.md](https://github.com/neomjs/neo/blob/main/learn/benefits/ArchitectureOverview.md) — OMT 架构总览
- [examples/README.md](https://github.com/neomjs/neo/blob/main/examples/README.md) — 示例作用域与构建规则
- 相关 Issue:[#2724 改进文档](https://github.com/neomjs/neo/issues/2724)、[#1088 React 包装讨论](https://github.com/neomjs/neo/issues/1088)

---

<a id='page-ai-mcp-client'></a>

## Client 模块

### 相关页面

相关主题：[Api 模块](#page-apps-realworld2-api)

```markdown
# Client 模块

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [ai/mcp/client/Client.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/Client.mjs)
- [ai/mcp/client/config.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/config.mjs)
- [ai/mcp/client/mcp-cli.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/mcp-cli.mjs)
- [README.md](https://github.com/neomjs/neo/blob/main/README.md)
- [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md)
- [package.json](https://github.com/neomjs/neo/blob/main/package.json)
</details>

## 概述

`ai/mcp/client/` 目录下的 Client 模块是 Neo.mjs Agent OS（v13.0.0 "The Institution Release"）中负责与 **Model Context Protocol (MCP)** 服务器进行通信的核心客户端实现。在 Agent OS 架构里，多个 MCP 服务器协同工作——例如 Knowledge Base（语义理解代码库、文档、Issues）、Memory Core（持久记忆）、GitHub Workflow（Issues / PRs / Reviews）以及 Neural Link（外部工具）——而 Client 模块正是 AI 维护者（`@neo-opus-ada`、`@neo-opus-grace`、`@neo-opus-vega` 等）调用这些服务器能力的统一入口。资料来源：[README.md](https://github.com/neomjs/neo/blob/main/README.md)

Client 模块遵循 MCP 规范，采用 **JSON-RPC 2.0 over StdIO** 的传输模式：

1. 通过 `child_process.spawn` 启动服务器子进程，把 `process.stdin/stdout` 作为协议通道
2. 构造符合 JSON-RPC 2.0 的请求帧（带自增 `id`、`method`、`params`），按 `Content-Length` 风格分帧后写入 stdin
3. 在 stdout 上持续读取、解析响应帧，按 `id` 关联到对应 Promise
4. 单独收集 stderr，作为人类可读的诊断日志通道
5. 暴露高层 API（`listTools` / `callTool` / `listResources` / `readResource` 等），供调用方按能力名调用

## 核心组件

Client 模块由三个紧密协作的文件组成，各司其职：

### `Client.mjs` — 传输与协议核心

`ai/mcp/client/Client.mjs` 实现了完整的 MCP 客户端协议栈，是模块的入口类。它负责：子进程生命周期管理（启动 / 优雅退出 / 进程残留清理）、stdio framing 与 JSON-RPC 解析、Promise 关联表（`Map<id, {resolve, reject}>`）、`initialize` → `initialized` 握手流程，以及将 stderr 转发到日志通道而不污染协议流。资料来源：[ai/mcp/client/Client.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/Client.mjs)

### `config.mjs` — 服务器清单与连接参数

`ai/mcp/client/config.mjs` 是 Client 模块的默认配置中心，声明了一组可挂载的 MCP 服务器及其启动参数。配置项通常包含以下字段：

| 字段 | 含义 |
| :--- | :--- |
| `name` | 服务器标识，用于在多服务器场景下区分 |
| `command` | 可执行命令（如 `node`） |
| `args` | 传给命令的参数列表，指向服务器入口脚本 |
| `env` | 环境变量注入（如 API token、workspace 路径） |
| `cwd` | 工作目录 |

资料来源：[ai/mcp/client/config.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/config.mjs)

通过该清单，Client 可以一次性挂载全部 Agent OS 服务器，并按 `name` 选择具体调用目标。

### `mcp-cli.mjs` — 命令行入口

`ai/mcp/client/mcp-cli.mjs` 提供了一个轻量的 CLI 工具，让开发者可以从终端直接与任意 MCP 服务器交互，便于冒烟测试与排障。CLI 内部完全复用 `Client.mjs` 的协议栈，因此走的是完全一致的 framing 与握手流程——这保证了 CLI 与 Agent OS 内部调用行为等价。资料来源：[ai/mcp/client/mcp-cli.mjs](https://github.com/neomjs/neo/blob/main/ai/mcp/client/mcp-cli.mjs)

## 通信流程

下面以一次典型的 tool 调用为例，展示 Client 模块与 MCP 服务器之间的消息流：

```mermaid
sequenceDiagram
    participant Caller as 调用方<br/>(AI 维护者 / CLI)
    participant Client as Client.mjs
    participant Proc as 子进程<br/>(MCP Server)

    Caller->>Client: callTool(name, args)
    Client->>Proc: spawn + initialize 请求
    Proc-->>Client: initialize 响应 (capabilities)
    Client->>Proc: initialized notification
    Client->>Proc: tools/call 请求 (id=N)
    Proc-->>Client: 响应 (id=N, result)
    Client-->>Caller: Promise resolve(result)
    Note over Client,Proc: stderr 单独收集<br/>用于诊断日志
```

关键约束：`initialize` 响应未到达前不应发送业务请求；客户端递增生成 `id`，服务器必须原样回传，否则并发请求会错配；stdout 仅承载协议帧，日志必须写往 stderr。从仓库根目录的 npm scripts 可以看到，官方已为每个 MCP 服务器准备了 StdIO 入口，正是 Client 模块所要 spawn 的目标：

| NPM 命令 | 对应服务器 |
| :--- | :--- |
| `ai:mcp-server-github-workflow` | GitHub Workflow |
| `ai:mcp-server-knowledge-base` | Knowledge Base |
| `ai:mcp-server-memory-core` | Memory Core |
| `ai:mcp-server-neural-link` | Neural Link |

资料来源：[buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md)、[package.json](https://github.com/neomjs/neo/blob/main/package.json)

## 常见失败模式与排障

在使用 Client 模块时，最常遇到的几类问题包括：

1. **stdout 污染**：服务器在 stdout 上打印了非协议帧（如调试 `console.log`），导致 framing 解析失败。修复方式是把日志改写到 stderr。
2. **握手超时**：`initialize` 长时间无响应，通常意味着 `config.mjs` 中的入口脚本路径错误或环境变量缺失。
3. **id 错配**：自定义服务器忘记在响应中原样回传 `id`，导致客户端 Promise 永远 pending。
4. **进程残留**：未在客户端断开时调用 `proc.kill()`，造成孤儿进程累积——长跑场景下尤其需要注意。

排障时优先使用 `mcp-cli.mjs` 复现问题：CLI 与运行时走完全相同的协议栈，能快速隔离是服务器 bug 还是 Client 配置问题。

## 参见

- [README.md](https://github.com/neomjs/neo/blob/main/README.md) — Agent OS 整体定位与 AI 维护者团队
- [buildScripts/README.md](https://github.com/neomjs/neo/blob/main/buildScripts/README.md) — MCP 服务器 StdIO 入口命令清单
- [package.json](https://github.com/neomjs/neo/blob/main/package.json) — 依赖与脚本注册
- `.github/AI_QUICK_START.md` — AI 维护者快速上手指南

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：neomjs/neo

摘要：发现 21 个潜在踩坑项，其中 8 个为 high/blocking；最高优先级：安装坑 - 来源证据：Cloud-deployment observability MCP tool (logs, health, recovery-runs)。

## 1. 安装坑 · 来源证据：Cloud-deployment observability MCP tool (logs, health, recovery-runs)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Cloud-deployment observability MCP tool (logs, health, recovery-runs)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13914 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：[Epic] Investigation: orchestrator heavy-maintenance runs 14h but the backlog doesn't drain (session-summary 283→284) —…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Epic] Investigation: orchestrator heavy-maintenance runs 14h but the backlog doesn't drain (session-summary 283→284) — net-progress, not fairness
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13624 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 配置坑 · 来源证据：MX: Stop-hook value-floor — bias the forced next-action toward high-value lanes + recognize V-B-A'd genuine-exhaustion…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：MX: Stop-hook value-floor — bias the forced next-action toward high-value lanes + recognize V-B-A'd genuine-exhaustion (the #13674-named #13652 sub)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13822 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安全/权限坑 · 来源证据：Generic-by-default harness adapter surface — minimize per-family (Claude / Codex / Antigravity / …) logic

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Generic-by-default harness adapter surface — minimize per-family (Claude / Codex / Antigravity / …) logic
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13796 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 安全/权限坑 · 来源证据：Orchestrator container-health self-healing daemon

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Orchestrator container-health self-healing daemon
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13860 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 安全/权限坑 · 来源证据：Prove deployment immune-system closeout via live smoke

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Prove deployment immune-system closeout via live smoke
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13936 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 7. 安全/权限坑 · 来源证据：[Epic] Daemon-based A2A message ingestion — decouple add_message from the synchronous model hit + durable WAL-first per…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Epic] Daemon-based A2A message ingestion — decouple add_message from the synchronous model hit + durable WAL-first persistence
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：[Epic] Orchestrator recovery daemon — reactive heal/act half of self-healing (phase-1)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Epic] Orchestrator recovery daemon — reactive heal/act half of self-healing (phase-1)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13874 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 9. 安装坑 · 来源证据：feat(ai): symmetric force-refetch for pulls & discussions (refetchPullsByNumber / refetchDiscussionsByNumber)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(ai): symmetric force-refetch for pulls & discussions (refetchPullsByNumber / refetchDiscussionsByNumber)
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13794 | 来源类型 github_issue 暴露的待验证使用条件。

## 10. 安装坑 · 来源证据：src/MicroLoader.mjs: replace the fetch() call with a json module import, once firefox added support

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：src/MicroLoader.mjs: replace the fetch() call with a json module import, once firefox added support
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/5756 | 来源类型 github_issue 暴露的待验证使用条件。

## 11. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/neomjs/neo | host_targets=claude

## 12. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/neomjs/neo | README/documentation is current enough for a first validation pass.

## 13. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/neomjs/neo | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/neomjs/neo | no_demo; severity=medium

## 15. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/neomjs/neo | no_demo; severity=medium

## 16. 安全/权限坑 · 来源证据：Accept documented Micro-Delta PR reviews in manage_pr_review

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Accept documented Micro-Delta PR reviews in manage_pr_review
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13910 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 安全/权限坑 · 来源证据：REM session loop: per-session fault isolation — one throwing session aborts the whole batch (head-of-line blocking)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：REM session loop: per-session fault isolation — one throwing session aborts the whole batch (head-of-line blocking)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13850 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 安全/权限坑 · 来源证据：Strengthen ADR-19 trigger and lint AiConfig aliases

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Strengthen ADR-19 trigger and lint AiConfig aliases
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13939 | 来源类型 github_issue 暴露的待验证使用条件。

## 19. 安全/权限坑 · 来源证据：revert: synced content mirrors are real third-party GitHub authorship — un-redact, leave as authored

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：revert: synced content mirrors are real third-party GitHub authorship — un-redact, leave as authored
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/neomjs/neo/issues/13786 | 来源类型 github_issue 暴露的待验证使用条件。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/neomjs/neo | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/neomjs/neo | release_recency=unknown

<!-- canonical_name: neomjs/neo; human_manual_source: deepwiki_human_wiki -->