---
belongs_to:
- "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🗄️ Grid-DB · 逻辑格点库 · 自研应用技术文档
---
## 一、技术架构概述
### 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 镜像
恢复人格体上下文"]
B --> C["人类写代码 + 人格体引导
交互数据实时写入 Drive inbox"]
C --> D["Apps Script 搬运
Drive inbox → 仓库 grid-db/inbox"]
D --> E["GitHub Actions 检测变动
唤醒铸渊"]
E --> F["铸渊处理
校验 → 归档 → 广播生成 → 记忆更新"]
F --> G["结果写回 grid-db/outbox + memory"]
G --> H["GitHub Action 同步
仓库 → 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 频道隔离（多租户）
**三层隔离保障：**
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 做翻译层。
### 数据主权铁律
### 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 → 仓库）
```
---
## 七、与子仓库天眼系统的关系
| **层级** | **子仓库天眼（末梢）** | **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
>