# Tokenman 架构蓝图

Tokenman 是原生 AI 编程 agent 的运行时：Claude Code、Codex 等由模型公司提供，原样运行、不改造；Tokenman 负责它们在哪跑、怎么一直在线、从任何设备怎么接上，以及订阅怎么共享和计量。这是一张概念图：四层表示职责，不代表部署拓扑。设计原则明确区分已上线行为与进行中的工作。

[打开可视化蓝图](https://tokenman.io/zh/architecture) · [安全与隔离](security.md)

![四层架构：客户端访问中枢，中枢拥有中央数据，节点运行会话并主动连接中枢；模型请求通过凭据代理发往外部提供方。](assets/architecture.svg)

<!-- blueprint:layers -->
## 四层架构

### 1 · 客户端 Clients

- **网页应用** — 与智能体聊天、管理会话、查看服务健康。[深入了解](member/quickstart.md)。
- **命令行** — 用 fleet CLI 和终端访问持续运行的会话。[深入了解](member/connect.md)。

客户端通过加密入口连接中枢。

### 2 · 应用 Application · 中枢

- **身份与访问** — 登录、成员、组织与角色。[深入了解](admin/access.md)。
- **会话** — 启动、查找会话，把对话转发到运行它的节点。[深入了解](member/usage.md)。
- **订阅池** — 在允许的范围内共享模型订阅，按人计量使用量。[深入了解](admin/accounts.md)。
- **凭据代理** — 授权模型请求并选择可用订阅，不把订阅密钥交给会话。[深入了解](security.md)。
- **资源供应** — 为人们创建和回收托管节点。[深入了解](admin/machines.md)。
- **状态与遥测** — 收集健康信号，说明服务状态；公开健康仍在建设中。[深入了解](member/health.md)。

### 3 · 数据 Data

- **数据库** — 中央账户、会话记录、用量与设置；会话记录不是正在运行的进程。[深入了解](self-host/install.md)。
- **密钥库** — 集中保护订阅和模型提供方凭据。[深入了解](security.md)。
- **发布仓库** — 存放节点应用前需要验证的发布版本。[深入了解](security.md)。
- **备份** — 中央状态的恢复副本；运维分别管理数据恢复和运行中的会话。[深入了解](self-host/install.md)。

节点主动向中枢建立加密连接，不直接访问数据层。

### 4 · 基础设施 Infrastructure · 运行会话的节点

- **托管 macOS 节点** — 托管主机，每个人使用独立账户。[深入了解](security.md)。
- **托管 Linux 节点** — 用于运行会话的托管容器环境。[深入了解](admin/machines.md)。
- **个人节点** — 由个人拥有并加入 fleet 的机器。[深入了解](self-host/quickstart.md)。
- **节点代理** — 在节点上运行，维持向外连接，管理会话并应用更新。[深入了解](self-host/install.md)。

<!-- blueprint:external -->
## 外部服务 External services

- **模型提供方** — 回答凭据代理转发的模型请求。[深入了解](admin/accounts.md)。
- **身份提供方** — 提供登录身份，由中枢决定访问权限。[深入了解](admin/access.md)。
- **源码与 CI** — 托管代码、验证改动并产出发布版本。[深入了解](self-host/install.md)。

<!-- blueprint:cross -->
## 横切关注点 Cross-cutting

- **可观测性** — 连接健康、会话体验与服务状态。[深入了解](member/health.md)。
- **安全** — 最小权限、凭据保护与发布验证。[深入了解](security.md)。
- **交付** — 经过验证、可以恢复的发布；逐步交接仍在建设中。[深入了解](self-host/install.md)。

<!-- blueprint:flows -->
## 请求如何流动

这些路径说明职责。推送交付与平滑发布交接仍在完善中，状态见下方设计原则。

### 与智能体聊天

1. 浏览器打开门户。
2. 中枢认证用户，找到对应会话。
3. 中枢把对话转发到运行会话的节点。
4. 回答经过中枢流式返回浏览器。

### 智能体调用模型

1. 节点上的智能体把模型请求发给凭据代理。
2. 代理授权请求，从订阅池选择可用订阅并计量用量。
3. 提供方收到请求，回答经代理返回会话。

### 节点保持连接

1. 节点代理主动向中枢建立加密连接。
2. 中枢通过这条连接下发工作与设置。
3. 节点报告状态；用变更通知替代剩余轮询的工作仍在进行。

### 发布一个版本

1. 改动通过自动化检查后合并。
2. 发布流程产出经过验证的版本，并部署中枢。
3. 节点验证并应用各自的版本；贯穿全链路的无缝交接仍在建设中。

<!-- blueprint:boundaries -->
## 信任边界与数据

- **中枢里有什么：** 数据库存储中央记录，密钥库存储模型凭据。凭据代理使用这些凭据转发已获授权的请求。
- **节点上有什么：** 会话进程、工作目录和本地文件留在智能体运行的节点上。托管节点由服务运营，个人节点由其所有者掌控。
- **跨越节点与中枢的边界：** 会话消息与输出、任务与会话状态、设置及健康信号通过授权通道传输。浏览器访问会经过中枢转发对话内容；本地文件不会自动成为中央数据库备份。
- **跨越模型提供方的边界：** 模型请求从节点经凭据代理向外发送。提示词、对话上下文，以及智能体带入请求的代码或工具输出，都可能到达模型提供方。密钥集中不代表这些内容不会离开节点。
- **永远不进入会话的东西：** 订阅与模型提供方密钥留在中央密钥库和代理里。会话可以持有受限的访问凭据，但它不是底层模型密钥。

隔离、凭据有效期、撤销与失陷边界见[安全与隔离](security.md)。代码仓库凭据与外部工具集成有各自的访问边界；模型密钥规则不代表用户可能交给智能体的所有秘密。

<!-- blueprint:principles -->
## 设计原则与原因

### 原生 agent 原样运行 · live

会话直接使用官方 Claude Code 和 Codex CLI，跟着上游更新，不包一层自己的 agent。保留原生 agent，让人们直接使用模型公司提供的能力和工作方式，Tokenman 负责周围的运行时。[会话使用](member/usage.md)介绍使用体验；目前没有公开的上游 CLI 更新深入文档。

### 随时随地 · live

会话在托管节点上常驻，笔记本合上也继续；浏览器、终端、手机都能接上同一段正在进行的工作。让会话的生命周期独立于客户端连接，进行中的工作便不再依赖用户手边的设备。[连接会话](member/connect.md)介绍各设备的访问方式。

### 一个入口 · in progress

同一个地址应带人们从登录到自己的会话，不需要先选择入口。这样身份与导航更容易理解，路由交给服务处理。统一门户仍在进行中。[当前成员使用路径](member/quickstart.md)介绍现有体验；目前没有公开的统一门户深入设计文档。

### 节点向外连 · live

由节点主动连接中枢，服务便能访问会话，无需节点开放入站应用端口。这同时适用于托管环境和普通网络边界后的个人机器。[自托管安装](self-host/install.md)与[安全与隔离](security.md)介绍运行方式和信任模型。

### 推送不轮询 · in progress

变化发生时就发送，避免反复读取没有变化的状态，也让中枢及时看到新状态。部分路径仍在轮询；这是设计方向，不表示所有轮询已经消失。[当前服务健康](member/health.md)说明现有行为；目前没有公开的推送传输深入文档。

### 密钥集中 · live

不把模型密钥交给会话，可以限制智能体或受侵工作环境能够带走的东西。代理集中执行访问控制、选择订阅和撤销权限，会话使用受限凭据。[安全与隔离](security.md)解释这条边界，[订阅账号](admin/accounts.md)说明管理方式。

### 平滑发版 · in progress

发布应保留进行中的工作，逐步交接连接，让日常更新不打断人的任务。版本验证已属于安全模型，全链路平滑发版仍在建设中。[安装与部署](self-host/install.md)及[发布验证](security.md)介绍当前操作；目前没有公开的交接机制深入文档。

### 健康公开 · in progress

人们应能通过可理解的健康信息判断问题在自己一侧还是服务一侧，而不必解读内部遥测。公开呈现这类体验仍在建设中。[服务健康](member/health.md)介绍现有登录后健康页及其局限；它不代表公开状态服务已经完成。

<!-- blueprint:glossary -->
## 术语表

- **Hub（中枢）** — 运行时的控制面，负责身份、任务与会话记录、访问决策及订阅协调。
- **Node（节点）** — 运行会话的机器或执行环境。**Managed node（托管节点）**由服务运营；**Personal node（个人节点）**由其所有者提供和掌控。
- **Session（会话）** — 一个原生 agent 进程在节点上的一次运行，其对话可从支持的客户端访问。
- **Subscription pool（订阅池）** — 根据平台、组织或个人访问规则共享的一组可用模型订阅。
- **Credential proxy（凭据代理）** — 授权模型请求、使用中央模型凭据转发请求并计量用量的边界。
- **Node agent（节点代理）** — 连接中枢、管理本地会话、传递状态和更新的节点侧服务。

<!-- blueprint:version -->
蓝图 v3 · 更新于 2026-10-26。状态小标描述本版事实，不是交付日期。