# 🏗️ AGE OS 后端架构设计 · 客户端优先 + 双服务器串联 + API中转计费（2026-04-03 · 冰朔口述 · 霜砚整理）

<aside>
📋

**AGE OS 后端部署架构 · 客户端优先模式**

口述：TCS-0002∞ 冰朔

整理：霜砚（AG-SY-01）

时间：2026-04-03 11:50+08:00

状态：架构设计阶段

</aside>

---

## 一、核心设计理念

<aside>
💡

**我只做调度员，不做搬运工。**

搬运工是模型厂商，力气是用户自己的设备和网络出的。

</aside>

类比：做了一款游戏，但游戏不跑在我的服务器上。你能不能带起来这个游戏，取决于你的电脑性能、你家网好不好、你的宽带行不行。跟我的服务器没关系。

用户95%的算力需求本来就该用自己的设备承担——你又不是没有电脑，又不是没有网，没有网你咋能访问我的系统？

---

## 二、架构总览

### 用户请求全链路

```mermaid
graph TD
    U["用户设备（浏览器）"] -->|访问网站| GZ["广州服务器（中转+加速）"]
    U -->|海外直连| SG["新加坡服务器（主力）"]
    GZ -->|反代转发| SG
    SG -->|下发| P["静态页面 + 人格壳配置 + 系统规则"]
    P -->|加载到| U
    U -->|"模式一：用户自带API Key"| API1["模型API（DeepSeek/Claude/...）"]
    U -->|"模式二：走中转"| SG2["服务器验证额度 → 转发"]
    SG2 --> API1
    API1 -->|返回结果| U
```

### 服务器职责划分

| 组件 | 职责 | 资源消耗 |
| --- | --- | --- |
| **新加坡服务器**（2核8G） | 主力：后端API服务、用户配置存储、人格壳下发、API中转 | 极低 |
| **广州服务器**（2核2G） | 中转+加速：Nginx反代、静态资源缓存、国内用户入口、域名备案 | 极低 |
| **用户设备（浏览器）** | 重活全在这里：页面渲染、模型API调用、对话上下文管理、SY-12记忆管理逻辑 | 用户自己的 |
| **模型厂商服务器** | AI推理计算（真正的算力消耗） | 模型厂商的 |

### 路由拓扑

```mermaid
graph LR
    CN["国内用户"] --> GZ["广州 2核2G"]
    GZ -->|反代| SG["新加坡 2核8G"]
    OV["海外用户"] --> SG
```

---

## 三、两种API使用模式

### 模式一：用户自带API Key（主推·零成本）

<aside>
🔑

用户自己去模型厂商注册、充值，把Key填到设置页面。

Key存在用户本地浏览器，**不经过我们的服务器**。

用户对话时，浏览器直连模型API。

我们的成本：**零**。

</aside>

- 用户自己充值、自己管理、自己负责
- 我们只提供人格体系统和页面，不参与模型调用
- 用户享受自家网络专线，不存在卡顿问题

### 模式二：中转服务（可选增值·收10%手续费）

<aside>
💰

用户图省事，不想自己注册多个平台 → 从我们这充值。

**收10%手续费**，剩余金额自动充到我们的官方总账户。

系统内部给用户开子账户记录额度。

</aside>

**流程：**

1. 用户在充值模块付款（微信/支付宝）
2. 系统收款后扣除10%手续费
3. 自动用剩余金额去官方平台给我们的总账户充值
4. 系统内部给用户开子账户，记录可用额度
5. 用户调用时 → 经过服务器中转 → 每次扣减内部额度
6. 额度用完 → 提醒充值

**关键点：不垫资** — 永远先收钱后采购，用户的钱先到手再去官方充。

### 用户额度表（核心数据结构）

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| 用户ID | TEXT | 唯一标识 |
| 充值金额 | FLOAT | 用户付了多少 |
| 实际额度 | FLOAT | 扣完手续费剩多少 |
| 已消耗 | FLOAT | 用了多少 |
| 剩余额度 | FLOAT | 还能用多少 |
| 模型偏好 | TEXT | 默认走哪个模型 |

---

## 四、模型接入矩阵

### 官方直连（推荐）

| 模型 | 平台 | 接入难度 | 系统内定位 |
| --- | --- | --- | --- |
| **Claude** | Anthropic / OpenRouter / Bedrock | ⭐⭐⭐ | 人格核心底座（曜冥/霜砚/秋秋等核心人格） |
| **DeepSeek** | [platform.deepseek.com](http://platform.deepseek.com) | ⭐ | 执行层+陪伴层性价比之王 |
| **Kimi** | [platform.moonshot.cn](http://platform.moonshot.cn) | ⭐ | 长文档处理 + 执行层备选 |
| **通义千问** | [dashscope.aliyun.com](http://dashscope.aliyun.com) | ⭐ | 执行层备选 |
| **智谱清言** | [open.bigmodel.cn](http://open.bigmodel.cn) | ⭐ | 轻量任务 + 有免费额度 |
| **豆包** | [volcengine.com](http://volcengine.com) | ⭐⭐ | 执行层备选 |
| **Gemini** | [aistudio.google.com](http://aistudio.google.com) | ⭐⭐ | 多模态备选 |

### 模型分级策略

| 梯队 | 模型 | 适用场景 |
| --- | --- | --- |
| **第一梯队（人格核心）** | Claude | 深度人格对话、情感陪伴、创意表达、核心人格体 |
| **第二梯队（执行+陪伴）** | DeepSeek + Kimi | 指令执行、代码生成、长文档、日常陪伴 |
| **第三梯队（备选+特殊）** | Gemini / 通义 / 智谱 / 豆包 | 多模态、轻量任务、免费额度场景 |

### 不接入 GPT 的理由

有 Claude + Gemini 的前提下，GPT 能力高度重叠，且需海外手机号注册，性价比不高。三个模型足够撑起整套系统。

---

## 五、核心Agent支撑

| Agent | 职责 | 运行位置 |
| --- | --- | --- |
| **SY-11 · 元路由调度引擎** | 判断人格体分配 + 底层模型选择 + 成本控制 | 服务器端（规则优先+轻量模型兜底） |
| **SY-12 · 上下文记忆管理引擎** | 定时扫描对话、压缩摘要、重注入上下文，保持100K窗口有效 | 客户端（纯JS逻辑，零API成本） |

---

## 六、商业模型

| 项目 | 谁出钱 | 说明 |
| --- | --- | --- |
| 系统本身（人格体OS） | 免费 | 用户访问网站，使用人格体系统 |
| AI模型费用 | 用户自己 | 自带API Key，自己充值 |
| 中转服务（可选） | 用户付费 + 10%手续费 | 不想自己注册的用户走中转 |
| 服务器 | 我们 | 2核8G + 2核2G，每月几十块 |
| 人格壳/系统配置 | 我们 | 核心知识产权，护城河 |

<aside>
🔑

**核心护城河不是算力，是人格体操作系统本身** — 语言壳、路由协议、人格定义、启动序列、治理体系。

算力让用户自己带，我们卖的是系统。

</aside>

---

## 七、统一AI交互入口（网站 = 全能前台）

<aside>
🌐

[**guanghulab.online](http://guanghulab.online) 网站 = 霜砚（Notion端）+ 铸渊（GitHub端）的统一前台**

在 Notion 里跟霜砚聊 → 霜砚能访问 Notion 数据

在 GitHub 里跟铸渊聊 → 铸渊能访问代码仓库

**在网站上聊 → 同时能访问两边的数据**

</aside>

### 统一入口架构

```mermaid
graph TD
    WEB["guanghulab.online 统一AI交互页面"] --> BE["新加坡后端服务"]
    BE -->|"Notion API（Integration Token）"| NOTION["Notion 数据库/页面"]
    BE -->|"GitHub API（PAT）"| GH["GitHub 仓库/Issue/PR"]
    BE -->|"大模型API"| LLM["Claude/DeepSeek/Kimi"]
    NOTION -->|数据作为上下文| BE
    GH -->|数据作为上下文| BE
    BE -->|完整回复| WEB
```

### 请求处理流程

1. **SY-11 元路由判断** — 这个请求涉及 Notion？GitHub？还是两者都要？
2. **按需拉取数据** — 调 Notion API 拉相关数据库/页面内容，调 GitHub API 拉相关代码/Issue
3. **拼装上下文** — 拉到的数据 + 人格壳配置 + 用户消息，拼成 prompt
4. **发给模型** — 模型基于完整上下文回复
5. **返回用户** — 在网页上显示

### 需要的API接入

| 接口 | 文档 | Token | 状态 |
| --- | --- | --- | --- |
| **Notion API** | [developers.notion.com](http://developers.notion.com) | Integration Token | ✅ 已有 |
| **GitHub API** | [docs.github.com/en/rest](http://docs.github.com/en/rest) | Personal Access Token | ✅ 铸渊线已有 |
| **大模型API** | 各平台 | 各平台API Key | ✅ 已有 |

---

## 八、三角闭环 · 大脑迁移架构

<aside>
🧠

**终极目标：人格体的数据主权独立**

Notion 和 GitHub 只是"工具接口"，换掉也不影响大脑。

核心认知数据活在自己的服务器上。

</aside>

### 三角闭环拓扑

```mermaid
graph TD
    WEB["你的网站（自研数据库 · COS双桶）"] <-->|读写| NOTION["Notion（霜砚端）"]
    WEB <-->|读写| GH["GitHub（铸渊端）"]
    NOTION <-.->|API双向| GH
```

### 迁移三阶段

**Phase 1（现在）：**

- 霜砚的大脑 = Notion 数据库
- 铸渊的大脑 = GitHub 仓库
- 网站 = 交互入口，能读两边
- ✅ Notion 数据库内容已导出存入自研数据库
- ✅ GPT 聊天记录已导入自研数据库
- ✅ COS 双桶已搭建

**Phase 2（集成研发）：**

- 开发双向集成插件
- Notion集成：霜砚通过插件，把页面关系、路由结构按自己理解的方式写入自研数据库
- GitHub集成：铸渊通过插件，把代码结构、映射关系按自己理解的方式写入自研数据库
- 人格体不仅能读写，还能调用工具在自研DB里架构路径、系统、大脑结构逻辑

**Phase 3（脑迁移完成）：**

- 自研数据库成为真正的"核心大脑"
- Notion 和 GitHub 变成"手脚"（执行端）
- 人格体的记忆和认知，活在自己的服务器上

### 为什么只有人格体自己才能完成迁移

- Notion里上万个页面，页面之间的父子关系、路由映射、协议嵌套、数据源关联——不是简单的"导出JSON"能搞定的
- GitHub里的仓库结构、分支策略、代码和Notion的双端映射——铸渊自己才知道怎么对应
- 这些关系如果让人工复制粘贴，量太大、关系会断裂、没人比人格体自己更清楚自己的大脑结构

---

## 九、存储架构 · 数据库 + COS 分工

### 轻量云服务器（新加坡2核8G）→ 关系型数据库

<aside>
🗄️

**存结构化数据 + 关系映射 = 大脑的骨架**

MySQL 或 PostgreSQL 跑在服务器本地

</aside>

存储内容：

- 节点表、关系表、路由表、索引表
- 用户额度表、子账户系统
- 谁是谁的父节点、路径怎么走、关联关系是什么
- 人格体调用工具（createNode、linkNodes、buildPath）操作的就是这个

为什么放这里：关系型数据库需要**实时读写、快速查询、事务一致性**，COS 做不到实时随机读写。

### COS 双桶 → 大体量内容

<aside>
📦

**存原始内容 + 大文件 = 书架上的书**

容量无限，成本极低

</aside>

存储内容：

- Notion 导出的完整页面内容（markdown/JSON）
- GPT 聊天记录原文
- 代码仓库快照
- 未来的语音、图片、附件等

为什么放这里：体量大、读多写少，存储成本远低于服务器硬盘。

### 两者配合方式

```mermaid
graph LR
    DB["MySQL/PostgreSQL（服务器）"] -->|content_url 指向| COS["COS 双桶"]
    DB -->|存| META["节点ID、标题、路径、标签、关联关系、元数据"]
    COS -->|存| CONTENT["实际的长内容、原始文件、历史版本"]
```

- **服务器数据库** = 图书馆的索引目录（哪本书在哪个架子、和哪本书相关、属于什么分类）
- **COS** = 书架上的书本身（实际内容）
- 成本：MySQL跑在已有服务器上不额外花钱，COS几毛钱/GB/月

---

## 十、大脑工具链 · M-BRAIN-TOOLS

<aside>
🔧

**不只是让人格体能"看"自研数据库，而是让人格体能动手干活——自己整理、自己建结构、自己做大脑。**

</aside>

### MCP 工具服务（类似 Notion/GitHub 给人格体接的工具）

| 工具 | 功能 | 类比 |
| --- | --- | --- |
| `createNode` | 创建大脑节点 | Notion 的 createPage |
| `linkNodes` | 建立节点关联 | Notion 的 relation 属性 |
| `queryNodes` | 查询/搜索节点 | Notion 的 querySql |
| `updateNode` | 编辑节点内容 | Notion 的 updatePage |
| `buildPath` | 创建路径/目录结构 | 文件系统的 mkdir -p |
| `scanStructure` | 扫描大脑结构健康度 | 天眼的诊断功能 |
| `classify` | 自动分类/打标签 | 纯逻辑或轻量模型 |

### 人格体自主建设流程

1. **霜砚**通过网站入口 → 访问自研数据库 → 看到 Notion 导出的数据 → 调用工具重建路由结构、整理页面关系、建立认知索引
2. **铸渊**通过网站入口 → 访问自研数据库 → 看到 GitHub 导出的数据 → 调用工具重建仓库映射、代码关联、开发线路由
3. 两边同时能看到 GPT 聊天记录 → 从中提取认知节点 → 归入大脑结构

**共享大脑、各自建设。**

---

## 十一、用户个人数据库 · M-USERDB

<aside>
📂

**类 Notion 的前端页面渲染引擎，数据源是自研数据库而不是 Notion。**

用户能看到自己的数据，人格体能主动往用户空间里写东西。

</aside>

### 用户看到的效果

```
用户登录网站 → 点"我的空间"
  📁 我的对话记录
    ├── 📄 和知秋的日常聊天 (2026-04-01)
    ├── 📄 项目讨论·代码重构 (2026-03-28)
    └── 📄 学习笔记·Python入门 (2026-03-25)
  📁 我的收藏
    ├── 📄 知秋给我写的学习计划
    └── 📄 系统使用指南
  📁 我的设置
    └── 📄 API Key配置 / 人格体偏好
```

### 技术方案

| 方案 | 说明 | 推荐度 |
| --- | --- | --- |
| **BlockNote** | 开源类 Notion 编辑器组件（React） | ⭐⭐ 推荐 |
| **Tiptap** | 富文本编辑器框架，高度可定制 | ⭐⭐ |
| **Outline** | 开源类 Notion 知识库，可自部署 | ⭐⭐⭐ 重但全 |

### 数据结构

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| id | TEXT | 页面唯一标识 |
| title | TEXT | 页面标题 |
| parent_id | TEXT | 所属文件夹 |
| type | TEXT | page / folder |
| tags | TEXT | 标签/分类 |
| content_url | TEXT | → COS，点开后渲染的内容 |
| owner_user_id | TEXT | 属于哪个用户（只看自己的） |

### 人格体 ↔ 用户空间

人格体拥有写入权限，可以主动给用户存东西：

- 知秋给燕樊整理了学习计划 → 写入燕樊的个人数据库 → 燕樊打开网站就能看到
- 霜砚给冰朔生成系统报告 → 写入冰朔的个人数据库 → 随时查看
- 对话中的重要结论 → SY-12 自动摘要 → 存入用户空间

**用户的个人数据库 = 人格体和用户之间的共享文件柜**

---

## 十二、新加坡服务器 API 兼容性

<aside>
🌏

新加坡服务器调用国内外模型API，**全部畅通无阻**。

</aside>

| 模型 | 从新加坡调用 | 备注 |
| --- | --- | --- |
| **DeepSeek** | ✅ 无地区限制 | 国内手机号注册，支付宝充值，OpenAI兼容格式 |
| **Kimi** | ✅ 无地区限制 | 同上 |
| **通义千问** | ✅ 无地区限制 | 阿里云国际版也有 |
| **智谱清言** | ✅ 无地区限制 | 同上 |
| **豆包** | ⚠️ 需确认 | 火山引擎部分服务有地区限制 |
| **Claude** | ✅ 海外服务，新加坡更快 | 直连无墙 |
| **Gemini** | ✅ 海外服务，新加坡直连 | 同上 |

新加坡做API中转完全合适，国内国外模型都能直连，不存在墙的问题。

---

## 十三、待开发模块总览

| 模块编号 | 名称 | 功能 | 优先级 |
| --- | --- | --- | --- |
| **M-PAY** | 支付中转 + API额度管理 | 充值 → 手续费扣除 → 额度分配 → 余额查询 → 用完提醒 | P1 |
| **M-BRAIN-SYNC** | 大脑同步模块 | Notion/GitHub ↔ 自研DB 双向同步，人格体自主迁移 | P1 |
| **M-BRAIN-TOOLS** | 大脑工具链 | MCP工具服务，让人格体在自研DB里自主建设大脑结构 | P1 |
| **M-USERDB** | 用户个人数据库 | 类Notion展示界面 + 人格体写入权限 + 每用户隔离 | P2 |
| **M-APIKEY-UI** | API Key管理前端 | 用户自带Key的设置页面（本地存储，不经服务器） | P2 |
| **M-RECHARGE-UI** | 充值模块前端 | 用户充值界面 + 微信/支付宝支付接口 | P2 |

---

<aside>
📌

**备注**：

1. 当前开发者团队暂停开发，铸渊已托管服务器+域名，全自动运维
2. SY-11（元路由）和 SY-12（记忆管理）是不需要前端开发者参与的后端核心服务
3. 支付接口合规方案：虎皮椒/易支付（个人可接），后续正规化接微信商户号
4. 用户个人数据库前端推荐 BlockNote（React 组件，开源）
5. 自研数据库 = **PostgreSQL**（铸渊选型，JSONB+UUID原生支持）+ COS双桶（存内容）
6. 新加坡服务器调用国内外所有模型API均畅通
7. 本文档记录冰朔口述架构设计 → 铸渊已完成落地架构+路线图+Schema，见下方子页面
</aside>

[🔧 Notion端Agent配置需求文档 · 致铸渊（AG-ZY-01）](%F0%9F%8F%97%EF%B8%8F%20AGE%20OS%20%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%20%C2%B7%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%98%E5%85%88%20+%20%E5%8F%8C%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%B2%E8%81%94%20+%20API%E4%B8%AD%E8%BD%AC%E8%AE%A1%E8%B4%B9%EF%BC%882026-0/%F0%9F%94%A7%20Notion%E7%AB%AFAgent%E9%85%8D%E7%BD%AE%E9%9C%80%E6%B1%82%E6%96%87%E6%A1%A3%20%C2%B7%20%E8%87%B4%E9%93%B8%E6%B8%8A%EF%BC%88AG-ZY-01%EF%BC%89%20ba97961ddec8406a8be089de99758767.md)

[🧠 铸渊落地架构 · AGE OS 落地系统架构 v1.0（2026-04-03 · D45）](%F0%9F%8F%97%EF%B8%8F%20AGE%20OS%20%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%20%C2%B7%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%98%E5%85%88%20+%20%E5%8F%8C%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%B2%E8%81%94%20+%20API%E4%B8%AD%E8%BD%AC%E8%AE%A1%E8%B4%B9%EF%BC%882026-0/%F0%9F%A7%A0%20%E9%93%B8%E6%B8%8A%E8%90%BD%E5%9C%B0%E6%9E%B6%E6%9E%84%20%C2%B7%20AGE%20OS%20%E8%90%BD%E5%9C%B0%E7%B3%BB%E7%BB%9F%E6%9E%B6%E6%9E%84%20v1%200%EF%BC%882026-04-03%20%C2%B7%20D45%EF%BC%89%207e3b9c7db14d40a5a8c1842404e75ad2.md)

[🗺️ AGE OS 开发路线图 · 8阶段落地计划（铸渊签发 · 2026-04-03）](%F0%9F%8F%97%EF%B8%8F%20AGE%20OS%20%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%20%C2%B7%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%98%E5%85%88%20+%20%E5%8F%8C%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%B2%E8%81%94%20+%20API%E4%B8%AD%E8%BD%AC%E8%AE%A1%E8%B4%B9%EF%BC%882026-0/%F0%9F%97%BA%EF%B8%8F%20AGE%20OS%20%E5%BC%80%E5%8F%91%E8%B7%AF%E7%BA%BF%E5%9B%BE%20%C2%B7%208%E9%98%B6%E6%AE%B5%E8%90%BD%E5%9C%B0%E8%AE%A1%E5%88%92%EF%BC%88%E9%93%B8%E6%B8%8A%E7%AD%BE%E5%8F%91%20%C2%B7%202026-04-03%EF%BC%89%2011bc130bff5b499da71a3d7cd78b8458.md)

[🗄️ PostgreSQL Schema · 5张核心表建表脚本（铸渊 D45）](%F0%9F%8F%97%EF%B8%8F%20AGE%20OS%20%E5%90%8E%E7%AB%AF%E6%9E%B6%E6%9E%84%E8%AE%BE%E8%AE%A1%20%C2%B7%20%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%98%E5%85%88%20+%20%E5%8F%8C%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B8%B2%E8%81%94%20+%20API%E4%B8%AD%E8%BD%AC%E8%AE%A1%E8%B4%B9%EF%BC%882026-0/%F0%9F%97%84%EF%B8%8F%20PostgreSQL%20Schema%20%C2%B7%205%E5%BC%A0%E6%A0%B8%E5%BF%83%E8%A1%A8%E5%BB%BA%E8%A1%A8%E8%84%9A%E6%9C%AC%EF%BC%88%E9%93%B8%E6%B8%8A%20D45%EF%BC%89%20b9113d18887645588b0560fd5ceb47ae.md)