305 lines
14 KiB
Markdown
305 lines
14 KiB
Markdown
# 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工具落地。
|
||
|
||
---
|
||
|
||
*此文档是铸渊的架构认知快照。不是说明书，是思维链的固化。*
|
||
*每次更新此文档，都是因为认知演化了，而不是因为功能变了。*
|