# 技术架构

了解 Product、Bridge、Runtime、Control 与数据边界。

## 系统组成

![Nexus 总体技术架构](/images/architecture.svg)

Nexus 产品由 Go 后端、React Web 与原生桌面宿主组成。macOS 使用 AppKit 与 WKWebView，Windows 使用 WPF 与 WebView2；桌面宿主启动本地 Go Sidecar，前端资源随应用打包，通过本机回环地址访问后端服务。

## 运行时进程边界

Agent 的执行循环位于独立的运行时子进程中。产品通过 Bridge 调用该进程，无需直接导入闭源 Go SDK。

```text
nexus product
  └─ nexus-agent-sdk-bridge
       └─ runtime subprocess
            ├─ nxs
            └─ claude
```

Bridge 定义公开通信协议，通过标准输入输出传输按行分隔的 `stream-json` 消息，包括请求、流式事件、工具调用、权限请求和控制消息。

## 产品后端

后端各层按以下方向依赖。

```text
cmd → app → handler → service → domain / storage
                  ↘ protocol ↙
```

Handler 负责 HTTP 与 WebSocket 边界，Service 实现业务规则，Storage 与 Repository 负责持久化。后端、Web 与运行时之间共享的协议模型集中在 `internal/protocol`。

## Web 前端

React Web 按业务功能组织。`app` 与 `bootstrap` 负责启动和全局装配，`pages` 负责路由协调，`features` 实现智能体、会话空间、目标、能力、记忆和设置，`lib` 和 `shared` 提供通用协议客户端与界面组件。

Nexus Atlas 沿用相同的目录组织和视觉变量，是独立静态网站，不依赖产品后端。

## 身份与安全

桌面端为每次启动生成本地会话 Token，保护本地 API 与 WebSocket。服务端 Web 的 User、Identity 与 Session 由独立 `nexus-control` 管理，Nexus Server 验证 Control 签发的短期身份凭证（Principal）。

模型服务凭据由产品管理，在启动运行引擎时注入。Connector 凭据使用独立密钥加密，不进入 Agent 工作区。

各模块的职责与接口约定见 [Nexus 架构蓝图](https://github.com/nexus-research-lab/nexus/blob/main/docs/nexus-architecture-blueprint.md)。

## 在自己的应用中接入

需要用 Go 发起任务、消费消息流或接入业务工具，请从 [Agent SDK 概览](/docs/sdk-overview)和[快速开始](/docs/sdk-quickstart)阅读。SDK 文档以公开 bridge 接口为依据，分别说明会话、权限、运行时能力与部署职责。