# 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)。
- **定时任务** — 中枢保存个人定义、限额与最终结果；既有节点 daemon 按时启动会话。[使用方法](member/usage.md#定时任务)。
- **会话** — 启动、查找会话，把对话转发到运行它的节点。[深入了解](member/usage.md)。
- **订阅池** — 在允许的范围内共享模型订阅，按人计量使用量。[深入了解](admin/accounts.md)。
- **凭据代理** — 授权模型请求并选择可用订阅，不把订阅密钥交给会话。[深入了解](security.md)。
- **资源供应** — 为人们创建和回收托管节点。[深入了解](admin/machines.md)。
- **状态与遥测** — 收集健康信号，说明服务状态；[公开健康页](/status)无需登录即可访问。[深入了解](member/health.md)。

按需的一站式企业增长运营 Agent 复用同一原生会话和家登录转发：Agent 通过已有 MCP 读取和改动，先保存待发版本，按具体版本确认后才发布。中枢不增加发布凭据；入口默认关闭，按 principal 限定。

预览续期为按需能力，不依赖模型回合：原生 Agent 经 LivePage MCP 授予有期限、限定版本的只读续期权，家登录将它换成短时嵌入票，浏览器投影不包含续期凭据。LivePage 每次续期检查成员、来源与原始授权。发布凭据与确认后的写入仍由原生 Agent 使用。

### 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)介绍各设备的访问方式。

### 一个入口 · live

浏览器访问统一到 tokenman.io，由服务按地区自动路由，中国大陆访问经过区域加速入口。这样从登录到会话始终有一个熟悉的入口，用户无需自行选择访问路径。既有微信内访问和原生客户端连接方式继续可用。[成员快速开始](member/quickstart.md)介绍会话使用路径。

### 节点向外连 · live

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

### 推送不轮询 · live

节点在状态变化时主动推送，避免反复读取没有变化的状态，也让中枢及时看到新状态。旧版节点更新后自动切换。这样既减少不必要的请求，也能及时呈现变化。[节点更新](self-host/install.md)介绍更新操作，[服务健康](member/health.md)说明读者可以查看的健康信息。

### 密钥集中 · live

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

### 平滑发版 · live

发版时分批交接连接，浏览器流自动续上。这样能保持进行中工作的连续性，减少日常更新对任务的打断。[安装与部署](self-host/install.md)介绍运维操作，[发布验证](security.md)解释发布版本的信任机制。

### 健康公开 · live

[公开健康页](/status)无需登录，即可查看服务状态和事件。可理解的健康信息帮助人们判断问题在本地连接还是服务一侧。[服务健康](member/health.md)介绍各项指标、适用范围，以及登录后可见的额外信息。

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

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

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