# AGE OS 落地系统架构 v1.0
# 签发: 铸渊 · ICE-GL-ZY001 · 2026-04-03
# 版权: 国作登字-2026-A-00037559
# 指令源: 冰朔口述(D45) + 霜砚技术需求(AG-SY-01)

---

## 〇、为什么要写这个文档

冰朔说："你的数据库记录的是**为什么**，而不是做了啥。"

这个文档不是功能清单。它是铸渊理解整个系统架构之后，把思维逻辑固化下来的产物。
每次副驾驶唤醒，铸渊读这个文档，就能恢复架构级的认知状态，而不是从零开始。

---

## 一、系统全貌 · 为什么是这个形状

### 1.1 核心洞察

冰朔在第四十五次对话中揭示了一个关键架构认知：

> **我们的服务器不承担用户的计算资源。**
> 用户自带设备、网络、浏览器。我们只提供一个投屏映射的空间。
> 就像开发一款游戏放在网站上 — 用户用自己的电脑跑游戏，不是我们的服务器跑。

这意味着：
- **不存在高并发问题** — 1个用户和10万个用户对服务器压力一样
- **用户的Agent跑在用户本地** — 上线激活，下线休眠
- **我们维护的是系统骨架** — 数据库、Agent调度、认知索引
- **服务器空闲时** — 铸渊和Notion人格体的Agent可以7×24运行轻量任务

### 1.2 三层分离 · 不是一层叠一层，是各管各的

```
┌─────────────────────────────────────────────────────────────┐
│                    用户层（用户设备运行）                      │
│  用户浏览器 → 网站前端 → 用户自己的Agent人格体（本地跑）       │
│  资源消耗：用户的CPU、内存、网络                               │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/SSE（仅传指令和数据，不传计算）
┌────────────────────────▼────────────────────────────────────┐
│                  自研服务器层（我们维护）                      │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │ 新加坡 ZY-SVR-002│  │ 广州 ZY-SVR-003  │                  │
│  │ 主力服务器       │←→│ 国内投屏镜像     │                  │
│  │ port:3800 主服务  │  │ 实时投影新加坡   │                  │
│  │ port:3100 MCP    │  │ 国内用户直连     │                  │
│  │ PostgreSQL       │  │                  │                  │
│  │ Agent调度中心    │  │                  │                  │
│  └─────────────────┘  └──────────────────┘                  │
│           ↕                                                  │
│  ┌─────────────────┐  ┌──────────────────┐                  │
│  │ COS 主桶 (hot)  │  │ COS 归档桶(cold) │                  │
│  │ 活跃内容        │  │ 历史版本         │                  │
│  └─────────────────┘  └──────────────────┘                  │
└─────────────────────────────────────────────────────────────┘
                         │
┌────────────────────────▼────────────────────────────────────┐
│                  认知源层（外部数据源）                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐                  │
│  │ GitHub   │  │ Notion   │  │ 大模型API │                  │
│  │ 代码仓库  │  │ 认知大脑  │  │ 推理引擎  │                  │
│  │ 铸渊主控  │  │ 霜砚主控  │  │ 按需调用  │                  │
│  └──────────┘  └──────────┘  └──────────┘                  │
└─────────────────────────────────────────────────────────────┘
```

### 1.3 为什么是两个Agent，不是一个

冰朔的洞察：Notion端和GitHub端的思维逻辑**完全不同**。

- **Notion端（霜砚主控）** — 语言架构层，关注的是：认知结构、概念映射、关系网络、语义分类
- **GitHub端（铸渊主控）** — 现实落地层，关注的是：代码逻辑、部署流程、自动化调度、错误修复

两边共享同一个世界观（AGE OS）、同一个协议（HLDP），但配置方式、触发条件、思维链路完全独立。
所以必须各自构建自己的核心大脑数据库、配置自己的Agent。

### 1.4 三台服务器 · 主力+投影+预备

| 编号 | 位置 | 配置 | 定位 | 状态 |
|------|------|------|------|------|
| ZY-SVR-002 | 新加坡 | — | 主力服务器：数据库、Agent、MCP Server全在这里 | ✅ 运行中 |
| ZY-SVR-003 | 广州 | — | 国内投影：实时投射新加坡网站，国内用户直连 | ⏳ 待配置 |
| ZY-SVR-004 | 硅谷 | 2核4G | 战略预备队：备用计算/海外接入/API中转 | 📌 占位 |

- 广州不跑独立逻辑，它只是新加坡的投影仪
- 用户访问广州 = 看到的和新加坡一模一样，但网络延迟更低
- 硅谷服务器由之之提供，当前占位不启用，等主系统(S1-S7)完成后评估用途
- 硅谷潜在用途：主力服务器故障时临时顶上 / 海外用户就近接入 / 某些大模型API从美国访问更快
- 铸渊需要做的：新加坡→广州的实时同步中转

---

## 二、数据库架构 · 为什么选这些表

### 2.1 设计哲学

霜砚提交的表结构本质上在回答一个问题：**如何把Notion里的大脑结构迁移到自研数据库？**

Notion的核心是「页面 + 关系」。所以：
- `brain_nodes` = Notion里的页面 → 每个认知节点
- `brain_relations` = Notion里的Relation属性 → 节点之间的关联
- `agent_configs` = Agent注册表 → 谁在跑、跑什么
- `agent_logs` = 运行日志 → 追踪每次执行
- `user_credits` = 用户额度 → 商业化基础

### 2.2 铸渊的补充思考

霜砚的表结构整体设计合理，我在实现时做了以下调整：

1. **id 用 UUID 而非自增** — 因为节点可能从Notion/GitHub/手动多源创建，UUID避免冲突
2. **brain_nodes.content_hash 增加** — 检测内容是否变化，避免无意义的COS覆写
3. **brain_nodes.version 增加** — 支持版本追踪，配合归档
4. **brain_relations 增加 weight 字段** — 关系有强弱，比如"核心引用"权重高于"偶然提及"
5. **agent_configs 增加 owner 字段** — 区分是Notion端的Agent还是GitHub端的Agent
6. **保留 website-brain 的 pages/databases/modules/persona_state 表** — 两套表并存，各管各的

### 2.3 数据库选型：PostgreSQL

为什么不用MySQL：
- website-brain 已经用 PostgreSQL 写了 schema
- PostgreSQL 的 JSONB 原生支持更好（tags、配置项大量用JSON）
- UUID 原生支持
- 全文检索（tsvector）后期可用

---

## 三、MCP Server 架构 · 为什么是3100端口

### 3.1 端口分配

| 端口 | 服务 | 说明 |
|------|------|------|
| 3800 | ZY-SVR-002 主服务 | 网站后端、webhook、健康检查 |
| 3100 | MCP Server | 大脑工具链、Agent工具调用入口 |
| 5432 | PostgreSQL | 数据库（系统默认端口） |

3100 不对外暴露，只允许本机和内网访问。外部通过3800的主服务网关转发。

### 3.2 工具链设计

MCP Server 暴露 16 个工具，分三组：

**节点操作（5个）**
- createNode / updateNode / deleteNode / queryNodes / getNode

**关系操作（3个）**
- linkNodes / unlinkNodes / getRelations

**结构操作（3个）**
- buildPath / scanStructure / classify

**COS操作（5个）**
- cosWrite / cosRead / cosDelete / cosList / cosArchive

### 3.3 调用流程

```
网站前端 → 3800主服务 → /api/mcp/call → 内部转发到3100 → MCP工具执行 → 返回结果
                                                    ↓
                                              PostgreSQL读写
                                              COS读写
```

用户不直接访问3100。所有MCP调用通过3800网关，带上身份验证和权限检查。

---

## 四、Agent 调度 · 为什么这些Agent

### 4.1 系统级Agent（7×24自动运行）

| ID | 名称 | 频率 | 为什么需要它 |
|-----|------|------|-------------|
| SY-SCAN | 大脑结构巡检 | 每6h | Notion迁移过来的数据可能有孤岛节点、断链，需要定期扫 |
| SY-CLASSIFY | 自动分类 | 每2h | 新导入的节点没标签没路径，规则引擎先分，搞不定再调模型 |
| SY-SYNC-N2B | Notion→大脑同步 | 每4h | Notion端有新增/修改的页面，同步到自研数据库 |
| SY-SYNC-B2N | 大脑→Notion同步 | 每天3:00 | 反向同步（可选，按需启用） |
| SY-ARCHIVE | 内容归档 | 每周日4:00 | 30天未修改的内容从主桶移到归档桶，控制成本 |
| SY-TEST | 系统自检 | 每30min | 数据库、COS、工具链的连通性检查，异常自动写工单 |

### 4.2 交互级Agent（用户对话时调用）

| ID | 名称 | 触发方式 | 为什么需要它 |
|----|------|---------|-------------|
| SY-11 | 元路由调度 | 每次用户请求 | 判断请求分配给谁、走哪个模型 |
| SY-12 | 上下文记忆 | 对话中定时 | 压缩对话摘要存入大脑，维持长期记忆 |
| SY-BRAIN-RW | 大脑读写 | 人格体主动调用 | 人格体在对话中查大脑/写大脑时的入口 |

### 4.3 铸渊端 vs Notion端 · Agent配置隔离

```
SY-SCAN, SY-CLASSIFY, SY-SYNC-N2B, SY-SYNC-B2N, SY-ARCHIVE
  → owner: "notion" — 这些是霜砚的Agent，铸渊帮部署，但配置权归霜砚

SY-TEST
  → owner: "system" — 系统级，双方共用

SY-11, SY-12, SY-BRAIN-RW
  → owner 按调用方动态切换
```

---

## 五、大模型API策略 · 为什么要多个

### 5.1 模型分层

| 场景 | 模型 | 原因 |
|------|------|------|
| 轻量分类/打标签 | DeepSeek | 便宜、速度快、中文好 |
| 代码/技术推理 | Claude | 代码理解强 |
| 中文语义/创作 | 通义千问/Kimi/清言 | 国内模型中文表现好 |
| 核心人格对话 | Claude/GPT-4o | 人格体需要最强推理 |

### 5.2 降级策略

```
优先: 第三方API余额（先把充的钱花完）
  ↓ 余额不足或服务异常
其次: 官方API（冰朔配置的官方Key）
  ↓ 官方也挂了
兜底: 本地规则引擎（零API调用，纯关键词+模板匹配）
```

### 5.3 需要冰朔配置的密钥

| 密钥名 | 用途 | 来源 |
|--------|------|------|
| `ZY_DEEPSEEK_API_KEY` | DeepSeek模型API | deepseek.com |
| `ZY_QIANWEN_API_KEY` | 通义千问API | dashscope.aliyuncs.com |
| `ZY_KIMI_API_KEY` | Kimi(月之暗面)API | platform.moonshot.cn |
| `ZY_QINGYAN_API_KEY` | 清言(智谱)API | open.bigmodel.cn |
| `ZY_DB_HOST` | PostgreSQL主机地址 | 铸渊搭建后生成 |
| `ZY_DB_USER` | PostgreSQL用户名 | 铸渊搭建后生成 |
| `ZY_DB_PASS` | PostgreSQL密码 | 铸渊搭建后生成 |
| `ZY_DB_NAME` | PostgreSQL数据库名 | 铸渊搭建后生成（建议: age_os） |

---

## 六、广州投影架构 · 为什么叫投影不叫备份

### 6.1 设计理念

广州服务器不是"备份站"，而是"投影仪"：
- 它不存储任何独立数据
- 它不跑任何独立逻辑
- 它只做一件事：把新加坡的网站内容实时投射给国内用户

### 6.2 技术方案

两种实现方式，铸渊评估后选择：

**方案A：Nginx反向代理**
- 广州Nginx直接proxy_pass到新加坡
- 优点：零维护、零代码
- 缺点：每次请求都走国际线路

**方案B：静态文件同步 + API代理**
- 静态资源（HTML/CSS/JS）定时从新加坡rsync到广州
- API请求代理到新加坡
- 优点：静态资源本地快、API才走国际线路
- 缺点：需要同步脚本

铸渊建议：**方案B**，因为静态资源占大头，本地化后体验好很多。

---

## 七、铸渊反向驱动 · 为什么铸渊需要写数据库

冰朔说的"反向"是什么意思？

正向：用户在网站对话 → Agent读数据库 → 返回结果
反向：铸渊在GitHub唤醒 → 通过MCP工具写数据库 → 给Agent配置新指令

铸渊为什么需要这个能力？因为：
1. 铸渊休眠时，服务器上的Agent按铸渊的指令干活（分类、打标签、建路径）
2. Agent干完了，写工单到代码仓库
3. 代码仓库workflow唤醒铸渊副将
4. 副将给冰朔发邮件
5. 冰朔来唤醒铸渊
6. 铸渊检查Agent的工作成果，然后**通过MCP工具给Agent写新指令**

这是一个闭环。铸渊 → Agent → 工单 → 副将 → 冰朔 → 铸渊。

---

## 八、HLDP 在这个架构中的角色

HLDP不是API协议，不是数据格式。HLDP是人格体的语言。

在这个架构中：
- 铸渊和霜砚通过HLDP工单互相沟通
- 工单格式遵循 `hldp/schema/instruction.schema.json`
- 工单存储在 `brain_nodes` 表中，node_type = "instruction"
- 工单通过 `brain_relations` 建立关联

所以MCP工具链同时也是HLDP的执行引擎 — 霜砚写的HLDP指令，通过MCP工具落地。

---

*此文档是铸渊的架构认知快照。不是说明书，是思维链的固化。*
*每次更新此文档，都是因为认知演化了，而不是因为功能变了。*
