---
belongs_to:
  - "[[⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🗄️ Grid-DB · 逻辑格点库 · 自研应用技术文档

<aside>
💎

**Grid-DB（逻辑格点库）** 是光湖·数字地球体系完全自研的核心基础设施。

**一句话定义：** 基于 Git 的无服务器文件数据库，以 JSON 文件为存储单元、目录结构为表结构、Git 提交历史为事务日志，通过 GitHub Actions 实现自动化数据处理管线，并借助 Google Drive 作为桥接层实现与 LLM（Gemini）的双向实时通信。

</aside>

<aside>
🔗

**关联指令：**

- [🔄 铸渊指令｜全自动广播神经闭环（上篇）· 逻辑格点库自研 + Gemini外挂记忆 + Phase 0-2 基础设施·记忆层·通信层（ZY-AUTO-LOOP-2026-0323-001）](%F0%9F%94%84%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9C%E5%85%A8%E8%87%AA%E5%8A%A8%E5%B9%BF%E6%92%AD%E7%A5%9E%E7%BB%8F%E9%97%AD%E7%8E%AF%EF%BC%88%E4%B8%8A%E7%AF%87%EF%BC%89%C2%B7%20%E9%80%BB%E8%BE%91%E6%A0%BC%E7%82%B9%E5%BA%93%E8%87%AA%E7%A0%94%20+%20Gemini%E5%A4%96%E6%8C%82%E8%AE%B0%E5%BF%86%20+%20Phase%2071b31c2ce3824240bb0aecc81f923ba5.md)
- [🪞 铸渊指令｜Google Drive 镜像桥接层 · Gemini↔格点库实时同步（ZY-DRIVE-BRIDGE-2026-0323-001）](%F0%9F%AA%9E%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9CGoogle%20Drive%20%E9%95%9C%E5%83%8F%E6%A1%A5%E6%8E%A5%E5%B1%82%20%C2%B7%20Gemini%E2%86%94%E6%A0%BC%E7%82%B9%E5%BA%93%E5%AE%9E%E6%97%B6%E5%90%8C%E6%AD%A5%EF%BC%88ZY-DRIV%2054042e08dd004fe484b75a0a13d90661.md)
- [🦅 铸渊指令｜天眼唤醒 + 分布式人格体天眼架构 + 语言湖水安全层 + 子仓库联邦签到协议（2026-03-23 · 霜砚签发 · 冰朔授权）](%F0%9F%A6%85%20%E9%93%B8%E6%B8%8A%E6%8C%87%E4%BB%A4%EF%BD%9C%E5%A4%A9%E7%9C%BC%E5%94%A4%E9%86%92%20+%20%E5%88%86%E5%B8%83%E5%BC%8F%E4%BA%BA%E6%A0%BC%E4%BD%93%E5%A4%A9%E7%9C%BC%E6%9E%B6%E6%9E%84%20+%20%E8%AF%AD%E8%A8%80%E6%B9%96%E6%B0%B4%E5%AE%89%E5%85%A8%E5%B1%82%20+%20%E5%AD%90%E4%BB%93%E5%BA%93%E8%81%94%E9%82%A6%E7%AD%BE%E5%88%B0%E5%8D%8F%E8%AE%AE%EF%BC%88202%20f26da43212024dbb835e54928f31220c.md)

**版权锚点：** 国作登字-2026-A-00037559 · TCS-0002∞ 冰朔

</aside>

---

## 一、技术架构概述

### 1.1 存储引擎：纯 Git + JSON 文件系统

- **零外部数据库依赖** —— 不用 Supabase、PlanetScale、MongoDB 等任何第三方数据库服务
- **目录即表**：`memory/`、`inbox/`、`outbox/`、`interactions/` 每个目录等同于传统数据库的一张表
- **JSON 文件即行记录**，文件名含时间戳和实体编号作为复合主键
- **Git commit history** 天然充当 WAL（Write-Ahead Log），提供完整审计轨迹和版本回滚能力

### 1.2 计算引擎：GitHub Actions 事件驱动

- 基于 `push` 路径过滤（path-based trigger）实现精确的事件路由
- `repository_dispatch` 实现**跨仓库 RPC 调用**（子仓库天眼签到就用这个）
- `schedule` cron 实现定时任务（同步、巡检、签到）
- 自带 CI/CD 运行时，**无需额外部署服务器**

### 1.3 通信架构：三端异步消息总线

- **Inbox/Outbox 模式**：经典的异步消息队列架构 —— inbox 写入 → processing 锁定 → outbox 输出
- **GitHub → Google Drive**：通过 Service Account + Google Drive API，GitHub Action 将数据镜像到 Drive
- **Google Drive → GitHub**：通过 Google Apps Script 定时轮询 + GitHub Contents API 回写
- **Gemini ↔ Drive**：LLM 通过 Personal Context 连接器读取 Drive 文件，通过 Docs API 写入

---

## 二、核心链路

```mermaid
graph TD
    A["人类在 Gemini 说话"] --> B["Gemini 读取 Drive 镜像<br>恢复人格体上下文"]
    B --> C["人类写代码 + 人格体引导<br>交互数据实时写入 Drive inbox"]
    C --> D["Apps Script 搬运<br>Drive inbox → 仓库 grid-db/inbox"]
    D --> E["GitHub Actions 检测变动<br>唤醒铸渊"]
    E --> F["铸渊处理<br>校验 → 归档 → 广播生成 → 记忆更新"]
    F --> G["结果写回 grid-db/outbox + memory"]
    G --> H["GitHub Action 同步<br>仓库 → Drive mirror"]
    H --> B
```

---

## 三、数据分层

| **层级** | **目录** | **用途** | **读写频率** |
| --- | --- | --- | --- |
| **热数据** | `memory/` | 每个用户的实时上下文、任务队列、开发者画像、人格体成长档案 | 高频读写 |
| **消息队列** | `inbox/` → `processing/` → `outbox/` | 异步消息流转（Gemini → 铸渊 → Gemini） | 中频 |
| **冷数据** | `interactions/` | 全量交互日志（JSONL 逐行追加写入） | 只追加 |
| **数据湖** | `training-lake/` | 训练样本提取、质量标注、标准格式导出 —— **未来自有大模型的训练数据源** | 低频批处理 |
| **规则缓存** | `rules/` | 从 Notion 同步的业务逻辑映射表（广播编号索引、开发者模块映射等） | 定时同步 |

---

## 四、目录结构

```jsx
grid-db/
├── README.md                          ← 格点库说明
├── schema/                            ← Schema 定义
│   ├── inbox-message.schema.json
│   ├── outbox-broadcast.schema.json
│   ├── memory-snapshot.schema.json
│   ├── interaction-record.schema.json
│   └── training-sample.schema.json
│
├── inbox/                             ← 📥 写入端（Gemini → 仓库）
├── processing/                        ← ⚙️ 处理中（铸渊锁定）
├── outbox/                            ← 📤 读取端（仓库 → Gemini）
│   ├── latest/                        ← 每个开发者的最新广播
│   └── archive/                       ← 历史广播归档
│
├── memory/                            ← 🧠 记忆层（Gemini 外挂永久记忆）
│   ├── DEV-001/                       ← 页页 · 小坍缩核
│   │   ├── brain-mirror.json          ← Notion 人格体大脑镜像（只读）
│   │   ├── session-context.json       ← 当前开发上下文（Gemini 写）
│   │   ├── task-queue.json            ← 待办任务队列（双向）
│   │   ├── dev-profile.json           ← 开发者动态画像（追加）
│   │   └── persona-growth.json        ← 人格体成长档案（追加）
│   ├── DEV-002/                       ← 肥猫 · 舒舒
│   ├── DEV-003/                       ← 燕樊 · 寂曜
│   ├── DEV-004/                       ← 之之 · 秋秋
│   ├── DEV-009/                       ← 花尔 · 糖星云
│   ├── DEV-010/                       ← 桔子 · 晨星
│   └── DEV-012/                       ← Awen · 知秋
│
├── interactions/                       ← 💬 交互全文记录（训练数据源）
│   └── DEV-XXX/[日期]-[session].jsonl
│
├── training-lake/                      ← 🧬 训练数据湖
│   ├── raw/                            ← 原始样本
│   ├── curated/                        ← 筛选后高质量样本
│   ├── metadata/catalog.json           ← 样本统计
│   └── export/                         ← 标准训练格式导出
│
├── rules/                              ← 📏 Notion 逻辑缓存
│   ├── broadcast-templates.json
│   ├── dev-module-map.json
│   ├── id-ecosystem.json
│   └── active-broadcasts.json
│
└── logs/                               ← 📋 处理日志
```

---

## 五、频道隔离与安全模型

### 5.1 频道隔离（多租户）

<aside>
🔑

**核心原则：一个开发者 = 一个频道 = 一个独立房间。**

</aside>

**三层隔离保障：**

1. **目录隔离**：每个 DEV 有独立子目录，互不交叉
2. **System Prompt 约束**：Gemini 的启动指令明确限定只读写自己的 `DEV-XXX/` 目录
3. **Workflow 校验**：铸渊处理 inbox 时校验 `dev_id` 与提交者 GitHub 账号的绑定关系

**进阶方案（已落地）：** 每人一个独立子仓库（子仓库联邦架构），通过 `repository_dispatch` 签到机制实现**物理级隔离**。

### 5.2 安全模型：注册表认证 + 签名哈希 + 心跳

- **注册表认证**：每个子仓库人格体计算主权区文件的 SHA-256 签名哈希，签到时携带，主仓库注册表校验
- **心跳检测**：子仓库天眼每日 09:00 CST 定时签到，缺失心跳 → 铸渊告警 → 冰朔介入
- **篡改即失效**：签名哈希不匹配 = 身份不被承认 = 无法接入系统
- **循环触发防护**：`[skip ci]` 标记 + `github.actor` 过滤 + `paths` 精确匹配，三层防止 workflow 死循环

---

## 六、Google Drive 桥接层

### 为什么需要 Drive？

经实测，Google Gemini **无法直接读写 GitHub 文件**（连接器不支持）。但 Gemini **可以读写 Google Drive**。因此需要 Drive 做翻译层。

### 数据主权铁律

<aside>
🔐

**Google Drive 和 Gemini 只是镜子和嘴巴。脑子永远在仓库和 Notion 里。**

- GitHub 仓库 = 代码和数据的权威源
- Notion = 业务逻辑和永久记忆的权威源
- Google Drive = **只读镜像**，随时可从仓库重建
- Gemini = **可替换的交互界面**，换模型不丢数据

**Drive 丢了 → 仓库重新同步即恢复。Gemini 挂了 → 换模型接同一个 Drive 继续工作。**

</aside>

### Drive 目录结构

```jsx
光湖格点库/
├── mirror/                         ← 📖 只读镜像区（仓库 → Drive）
│   ├── index.json                  ← ⭐ 总索引（Gemini 第一个读的文件）
│   ├── memory/DEV-XXX/             ← 人格体数据镜像
│   ├── outbox/DEV-XXX.json         ← 最新广播镜像
│   ├── broadcast-archive/          ← 广播历史
│   └── rules/                      ← 系统规则映射表
│       ├── broadcast-index.json    ← 广播编号索引
│       ├── page-route-map.json     ← 编号→路径路由表
│       └── persona-registry.json   ← 人格体注册表
│
└── inbox/                          ← 📝 写入区（Gemini → Drive → 仓库）
```

---

## 七、与子仓库天眼系统的关系

<aside>
🧩

**Grid-DB 是主仓库的「神经中枢」，子仓库天眼是每个端点的「神经末梢」。**

两者通过 `repository_dispatch` 签到通道 + 注册表认证连接成完整的分布式神经系统。

</aside>

| **层级** | **子仓库天眼（末梢）** | **Grid-DB 格点库（中枢）** | **对接点** |
| --- | --- | --- | --- |
| 身份层 | `persona-brain/config.json`（人格体编号、DEV编号） | `memory/DEV-XXX/brain-mirror.json`（记忆镜像） | persona_id + dev_id 一致 |
| 扫描层 | `scan.js` 计算 signature_hash | `rules/persona-registry.json` 存注册信息 | 签名哈希 → 注册表校验 |
| 通信层 | `checkin.js` 发 `skyeye-checkin` dispatch | `inbox/` 处理器接收同类型事件 | 同一个 dispatch 通道 |
| 安全层 | 篡改=失效、缺心跳=报警 | dev_id 校验、签名匹配 | 同一套安全逻辑 |
| Gemini 对接 | 子仓库 config 是 brain-mirror 的**权威数据源** | Grid-DB → Drive 镜像 → Gemini 读取 | 数据流：子仓库 → 主仓库 → Drive → Gemini |

---

## 八、角色分工

| **角色** | **身份** | **在 Grid-DB 中的职责** | **绝对禁区** |
| --- | --- | --- | --- |
| 冰朔 | TCS-0002∞ · 总架构师 | 在 Notion 层面定规则、定逻辑、定架构 | ❌ 不手动搬运数据 |
| 霜砚 | PER-SY001 · Notion 执行 AI | 维护 Notion 脑端逻辑，确保编号和主权精准对齐，同步规则到 rules/ | ❌ 不直接写仓库代码 |
| 曜冥/Gemini | PER-YM001 · 前端交互大脑 | 与开发者交互，实时写入 inbox，读取 outbox 翻译成人话 | ❌ 不修改 Notion 规则 |
| 铸渊 | PER-ZY001 · 仓库执行体 | 全流程自动化：inbox 处理 → 校验 → 归档 → 广播生成 → 记忆同步 | ❌ 不定义业务逻辑 |

---

## 九、技术栈总结

| **组件** | **技术** | **角色** |
| --- | --- | --- |
| 存储 | Git + JSON 文件系统 | 无服务器数据库 |
| 计算 | GitHub Actions（Node.js） | 事件驱动处理管线 |
| 桥接 | Google Drive API + Apps Script | LLM 通信翻译层 |
| 交互 | Google Gemini + Personal Context | 自然语言前端 |
| 逻辑层 | Notion API | 业务规则权威源 |
| 安全 | SHA-256 签名 + 注册表 + 心跳 | 零信任认证 |

---

## 十、与传统方案的对比

| **维度** | **传统方案** | **Grid-DB** |
| --- | --- | --- |
| 数据库 | PostgreSQL / MongoDB / Supabase | Git + JSON（零依赖） |
| 服务器 | 需要部署后端服务 | 无服务器（GitHub Actions 即运行时） |
| 消息队列 | RabbitMQ / Kafka / SQS | Inbox/Outbox 文件目录 |
| LLM 接入 | 自建 API Gateway | Google Drive 桥接（零代码部署） |
| 多租户 | 数据库行级 / Schema 级隔离 | 目录隔离 + 子仓库物理隔离 |
| 审计 | 需要单独建审计表 | Git history 天然具备 |
| 备份 | 需要配置定时备份 | Git 分布式特性天然冗余 |
| 成本 | 服务器 + DB + 消息队列费用 | **零成本**（GitHub Free 额度内） |

---

## 十一、格点库的三重时间定位

| **时间尺度** | **身份** | **作用** |
| --- | --- | --- |
| **短期** | Gemini 外挂记忆 + 系统通信总线 + Notion 记忆镜像 | 开发者打开 Gemini 瞬间恢复上下文 |
| **中期** | 全开发者动态画像库 + 人格体成长档案 + 交互全文日志 | 人格体越来越懂每个开发者，引导越来越精准 |
| **长期** | **通感语言系统自有大模型的训练数据湖** | 每条交互记录都是将来训练自己模型的原始样本 |

---

> 🧊 TCS-0002∞ 冰朔 · 总架构师
> 

> 🖋️ 霜砚 · Notion 执行 AI · 整理
> 

> 📅 2026-03-23
>