# 光湖网站总大脑 · L4 架构设计文档

> 签发：霜砚（PER-SY001）· 授权：冰朔（TCS-0002∞）
> 指令等级：P0 · 系统级 · AGE OS 核心架构
> 日期：2026-03-20

---

## 一、定位

这是整个网站的**核心数据引擎**——取代 Notion 数据库在系统中的角色，成为 guanghulab.com 的总大脑。

- **不是复刻 Notion**，是取其「结构化页面 + 数据库 + API」的核心能力
- **放在阿里云 ECS** 上，国内访问，自主可控
- **模型驱动**：所有操作通过模型语义理解 → 调用数据库 API 完成

---

## 二、五层架构总览

```
┌──────────────────────────────────────────────────────┐
│          L1 · 光湖语言世界层（湖水防御）                │
│  ┌──────────────────────────────────────────────┐    │
│  │    L2 · 战略主控台（主动响应层）                  │    │
│  │  ┌──────────────────────────────────────┐    │    │
│  │  │  L3 · 人格体智能路由层                    │    │    │
│  │  │  ┌──────────────────────────────┐    │    │    │
│  │  │  │  L4 · 网站总大脑（自研数据库）    │    │    │    │
│  │  │  │  ┌──────────────────────┐    │    │    │    │
│  │  │  │  │  L5 · 代码仓库桥接层    │    │    │    │    │
│  │  │  │  └──────────────────────┘    │    │    │    │
│  │  │  └──────────────────────────────┘    │    │    │
│  │  └──────────────────────────────────────┘    │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘
```

---

## 三、核心能力

| 能力 | 说明 | 对标 Notion |
|------|------|-------------|
| 结构化页面 | 支持富文本、嵌套块、多级层次 | Notion Page |
| 数据库表 | 可配置属性、筛选、排序、视图 | Notion Database |
| 开放 API | 完整的 RESTful + WebSocket 接口 | Notion API（但更自由） |
| 模块热插拔 | 新功能以「模块」形式注册，不重启 | Notion 不支持 |
| 人格体原生支持 | 每个人格体有专属数据空间和权限 | Notion 不支持 |
| 语言指令接口 | 自然语言 → API 调用的原生通道 | Notion AI（但更深度） |

---

## 四、技术选型

| 组件 | 方案 | 理由 |
|------|------|------|
| 后端框架 | Node.js（Express） | 团队已有 Node 经验，仓库现有代码全是 Node |
| 数据库 | PostgreSQL + Redis | PG 支持 JSONB（类 Notion 灵活 schema），Redis 做缓存 |
| 实时通信 | WebSocket（Socket.io） | 人格体对话、状态推送、实时协作 |
| 文件存储 | 阿里云 OSS | 国内速度快，与 ECS 同区域免流量费 |
| 部署 | 阿里云 ECS + PM2 + Nginx | 现有服务器架构，直接复用 |
| 模型接口 | DeepSeek API / 阿里通义 API | 国内模型，低延迟，成本可控 |

---

## 五、数据库 Schema 核心设计

详见 `schema/001-init.sql`，包含四张核心表：

1. **pages** — 类 Notion Page，支持嵌套、JSONB content、人格体权限
2. **databases** — 类 Notion Database，可配置 schema 和视图
3. **modules** — 热插拔模块注册表
4. **persona_state** — 人格体状态管理

---

## 六、API 路由

| 路由前缀 | 模块 | 状态 |
|----------|------|------|
| `/api/pages` | 页面 CRUD | Phase 1 stub |
| `/api/databases` | 数据库 CRUD | Phase 1 stub |
| `/api/modules` | 模块注册/管理 | Phase 1 stub |
| `/api/persona-state` | 人格体状态 | Phase 1 stub |
| `/health` | 健康检查 | ✅ 已实现 |

---

## 七、实现路线图

### Phase 1 · 骨架期（P0 · 当前）
- [x] 目录结构创建
- [x] package.json 依赖声明
- [x] PostgreSQL Schema 定义
- [x] API 路由 stub
- [x] 架构文档
- [ ] PostgreSQL 数据库初始化（需阿里云 ECS）
- [ ] PM2 部署 + Nginx 反向代理
- [ ] 基础管理界面（Web UI）

### Phase 2 · 连接期
- [ ] GitHub 仓库桥接 API（L5）
- [ ] Notion 数据同步桥（双向）
- [ ] WebSocket 实时通信层
- [ ] 模块热插拔机制
- [ ] 人格体状态管理

### Phase 3 · 智能期
- [ ] 语言指令解析引擎
- [ ] 人格体智能路由层（L3）
- [ ] 外部存储连接（百度云盘/阿里云盘）
- [ ] 飞书多维表格替代模块
- [ ] 语言湖防御层（L1）

---

## 八、三端桥接架构（L5）

```
                    ┌─────────────────┐
                    │   Notion 大脑     │
                    └────────┬────────┘
                             │ Notion API
                             ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  GitHub 仓库      │◄──►│  网站总大脑       │◄──►│  外部存储         │
│  （铸渊·代码层）   │    │ （自研数据库）     │    │  百度/阿里云盘    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

---

> 📌 指令来源：2026-03-20 冰朔与霜砚对话
> 📌 指令性质：P0 系统级 · AGE OS 核心架构蓝图 · 长期执行
> 📌 一句话：人只说话，模型做桥接，API 做执行——这就是 AGE OS。
