171 lines
4.4 KiB
Markdown
171 lines
4.4 KiB
Markdown
# Grid-DB 架构设计文档
|
||
|
||
> 项目编号：PRJ-GDB-001
|
||
> 版权：国作登字-2026-A-00037559
|
||
> 版本：v0.1.0 · Phase 0
|
||
> 签发：AG-SY-01 霜砚 · 执行：AG-ZY-01 铸渊
|
||
|
||
---
|
||
|
||
## 1. 本体论锚定 [ONT-PATCH-006]
|
||
|
||
### Grid-DB · 纸 · 格子 · 笔迹
|
||
|
||
**Grid-DB = 纸**
|
||
|
||
笔需要纸来承载笔迹。Grid-DB 是纸。纸上有格子（格点），每个格子是最小寻址单元。
|
||
纸不属于笔，纸属于写字的人。
|
||
|
||
**格点 = 格子**
|
||
|
||
格子是纸上的最小单元。不同的格子存不同的数据。
|
||
同一个格子可以有多层（raw → cleaned → indexed → semantic）。
|
||
|
||
**事件 = 笔迹**
|
||
|
||
每写一笔，笔迹就留在了历史中，不可篡改。
|
||
天眼通过观察笔迹，发现异常行为。
|
||
|
||
### 与 EXE-Engine 的关系
|
||
|
||
| 层 | 组件 | 职责 | 本体论 |
|
||
|---|---|---|---|
|
||
| 执行层 | EXE-Engine | 模型调度、任务编排、算力路由 | 笔 |
|
||
| 存储层 | Grid-DB | 数据持久化、格点索引、事件流 | 纸 |
|
||
| 采集层 | DC v1.0 | 外部数据采集与清洗 | 墨水收集器 |
|
||
|
||
---
|
||
|
||
## 2. 核心组件
|
||
|
||
### 2.1 GridCell — 格点数据模型
|
||
|
||
文件：`src/core/grid-cell.js`
|
||
|
||
四元组寻址：`(namespace, grid_x, grid_y, layer)`
|
||
|
||
- **namespace** — 隔离不同 Agent / 项目的数据域
|
||
- **grid_x / grid_y** — 坐标轴
|
||
- **layer** — 数据层级：raw → cleaned → indexed → semantic
|
||
|
||
支持：
|
||
- JSON 序列化 / 反序列化
|
||
- 二进制 Buffer 编解码（用于页存储）
|
||
- 键生成（`toKey()` → `ns:x:y:layer`）
|
||
- 曼哈顿距离计算
|
||
|
||
### 2.2 WAL — Write-Ahead Log
|
||
|
||
文件：`src/storage/wal.js`
|
||
|
||
所有写操作先追加到 WAL 文件，崩溃后可从 WAL 恢复。
|
||
|
||
记录格式：
|
||
```
|
||
[length:4][seqNo:4][op:1][keyLen:2][key:N][dataLen:4][data:M][checksum:4]
|
||
```
|
||
|
||
操作码：
|
||
- `0x01` = PUT
|
||
- `0x02` = DELETE
|
||
|
||
特性：
|
||
- 追加写入 + fsync 保证持久化
|
||
- XOR 校验和验证完整性
|
||
- 支持截断（checkpoint 后清除已持久化记录）
|
||
- 崩溃恢复：重新打开时自动读取并恢复
|
||
|
||
### 2.3 PageManager — 页管理器
|
||
|
||
文件：`src/storage/page-manager.js`
|
||
|
||
以固定大小页（默认 4096 字节）为最小 I/O 单位。
|
||
|
||
文件结构：
|
||
```
|
||
[Header: 1 page] [Page 1] [Page 2] ... [Page N]
|
||
```
|
||
|
||
Header 页：`[magic:4][version:2][pageSize:4][pageCount:4][freeListHead:4]`
|
||
数据页：`[flags:1][nextFree:4][dataLen:4][data:N]`
|
||
|
||
特性：
|
||
- 空闲链表管理：释放的页自动回收复用
|
||
- 持久化：重新打开文件后数据完好
|
||
- 文件格式验证（magic number `0x47444230` = 'GDB0'）
|
||
|
||
### 2.4 EventLog — 事件溯源日志
|
||
|
||
文件：`src/events/event-log.js`
|
||
|
||
Phase 0：内存事件流（保留最近 1000 条）
|
||
Phase 1：持久化事件流 + 回放 + 订阅
|
||
|
||
每次写操作生成事件：
|
||
```json
|
||
{
|
||
"eventId": "evt-xxxx",
|
||
"seqNo": 1,
|
||
"timestamp": "2026-03-26T13:00:00Z",
|
||
"namespace": "exe-engine",
|
||
"operation": "put",
|
||
"gridCellKey": "exe-engine:1:2:raw",
|
||
"payload": { "dataSize": 256 }
|
||
}
|
||
```
|
||
|
||
支持订阅回调，可被天眼系统监听。
|
||
|
||
### 2.5 GridAPI — 统一接口
|
||
|
||
文件：`src/api/grid-api.js`
|
||
|
||
协调 WAL、PageManager、EventLog 协同工作。
|
||
|
||
```javascript
|
||
const { open } = require('./grid-db/src/index');
|
||
const db = open({ dataDir: './my-data' });
|
||
|
||
// put
|
||
db.put('my-ns', { gridX: 1, gridY: 2, layer: 'raw' }, { hello: 'world' });
|
||
|
||
// get
|
||
const data = db.get('my-ns', { gridX: 1, gridY: 2, layer: 'raw' });
|
||
|
||
// scan
|
||
const results = db.scan('my-ns', { xRange: [0, 10], yRange: [0, 10], layer: 'raw' });
|
||
|
||
// delete
|
||
db.delete('my-ns', { gridX: 1, gridY: 2, layer: 'raw' });
|
||
|
||
// subscribe
|
||
db.subscribe('auditor', (event) => console.log(event));
|
||
|
||
// checkpoint (truncate WAL)
|
||
db.checkpoint();
|
||
|
||
db.close();
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 技术栈
|
||
|
||
| 层 | 选型 | 理由 |
|
||
|---|---|---|
|
||
| 语言 | Node.js 20 | 与 EXE-Engine 同栈 |
|
||
| 持久化 | 自研 (.gdb/.wal) | 零外部依赖，嵌入式 |
|
||
| 序列化 | JSON + Binary Buffer | JSON 调试友好，Buffer 高性能 |
|
||
| 测试 | 自定义 assert runner | 与 EXE-Engine 测试框架统一 |
|
||
|
||
---
|
||
|
||
## 4. Phase 路线
|
||
|
||
| Phase | 目标 | 状态 |
|
||
|---|---|---|
|
||
| P0 基础骨架 | GridCell + WAL + PageManager + EventLog + GridAPI | 🟢 完成 |
|
||
| P1 索引与查询 | B+Tree + Namespace 隔离 + 范围扫描 + Event 持久化 | ⚪ 待开始 |
|
||
| P2 高级特性 | HNSW 向量索引 + EXE-Engine 对接 + DC 迁移 + 天眼审计 | ⚪ 待开始 |
|
||
| P3 生产就绪 | 性能基准 + 资源计量 + 全文索引 + 文档 | ⚪ 待开始 |
|