---
belongs_to:
  - "[[⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🛡️ 铸渊指令｜Grid-DB 架构升级 · 写缓冲层 + 定时批处理 + 人类零直写（ZY-GRIDDB-BUFFER-2026-0323-001）

<aside>
📌

**指令编号：** ZY-GRIDDB-BUFFER-2026-0323-001

**签发人：** 霜砚（PER-SY001）· 冰朔（TCS-0002∞）授权

**执行人：** 铸渊（ICE-GL-ZY001）

**优先级：** 🔴 高 · Grid-DB 核心架构升级

**前置指令：** [🔄 铸渊指令｜全自动广播神经闭环（上篇）· 逻辑格点库自研 + 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)

**关联文档：** [🗄️ Grid-DB · 逻辑格点库 · 自研应用技术文档](%F0%9F%97%84%EF%B8%8F%20Grid-DB%20%C2%B7%20%E9%80%BB%E8%BE%91%E6%A0%BC%E7%82%B9%E5%BA%93%20%C2%B7%20%E8%87%AA%E7%A0%94%E5%BA%94%E7%94%A8%E6%8A%80%E6%9C%AF%E6%96%87%E6%A1%A3%20a0ff51f90a474adca3eda7ea86c6bb01.md)

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

</aside>

---

## 一、升级背景与目标

### 1.1 现有架构的四个风险点

| **风险** | **根因** | **后果** |
| --- | --- | --- |
| Git 不适合高频写入 | 每次写入 = commit + push | 仓库膨胀、冲突频发 |
| GitHub Actions 配额有限 | 免费额度 2000 分钟/月 | 大量事件驱动可能超限 |
| Google Drive 桥接延迟 | Apps Script 轮询 + API 回写 | 延迟秒到分钟级，不适合实时交互 |
| 架构脆弱性 | 高度依赖 GitHub + Google API 可用性 | API 故障 = 全系统中断 |

### 1.2 升级目标

<aside>
🎯

**核心铁律：人类永远不直接写入 grid-db。系统在前面拦一层缓冲，系统自己内部跑完校验和合并后，再统一写入。**

</aside>

- ✅ 人类零直写 —— 所有人类输入先进**缓冲区**，不触发任何 Git 操作
- ✅ 定时批处理 —— 每天固定 3 次收集 + 1 次唤醒核心大脑统一处理
- ✅ 零高并发 —— 单次批量 commit 代替多次零散 commit
- ✅ 配额精算 —— 每天最多 3-4 次 workflow run，月消耗可精确预测
- ✅ 韧性增强 —— API 临时故障不丢数据，下次定时任务自动重试

---

## 二、升级后架构总览

```mermaid
graph TD
    subgraph 人类活动区
        H1["开发者通过 Gemini 对话"]
        H2["开发者在 Notion 提交需求"]
        H3["开发者在仓库提交代码"]
    end

    subgraph 缓冲层 Buffer Agent
        B1["📥 buffer-inbox/<br>接收所有人类输入"]
        B2["🔀 auto-router.js<br>自动分流 · 按 DEV 编号归档"]
        B3["📋 buffer-staging/<br>待处理队列（静态存储）"]
    end

    subgraph 定时调度器
        S1["⏰ cron: 09:00 / 14:00 / 21:00 CST<br>每天 3 次收集"]
        S2["🧠 唤醒铸渊核心大脑<br>repository_dispatch: grid-db-flush"]
    end

    subgraph 铸渊批处理区
        Z1["校验：签名 + dev_id + 格式"]
        Z2["合并：同一 DEV 的多条消息合并"]
        Z3["单次 commit + push 写入 grid-db/"]
        Z4["同步 Drive 镜像"]
    end

    H1 --> B1
    H2 --> B1
    H3 --> B1
    B1 --> B2
    B2 --> B3
    S1 -->|"抓取 buffer-staging/"| S2
    S2 --> Z1
    Z1 --> Z2
    Z2 --> Z3
    Z3 --> Z4
    Z4 -->|"Gemini 读取更新后的镜像"| H1
```

---

## 三、缓冲层（Buffer Agent）详细设计

### 3.1 目录结构

在主仓库 `qinfendebingshuo/guanghulab` 根目录新建：

```jsx
buffer/
├── inbox/                          ← 📥 人类输入落地点
│   ├── DEV-001/                    ← 按开发者编号自动分流
│   │   └── [timestamp]-[type].json
│   ├── DEV-002/
│   ├── DEV-004/
│   ├── DEV-012/
│   └── system/                     ← 系统级消息（非开发者触发）
│
├── staging/                        ← 📋 已分流待处理（定时任务抓取源）
│   ├── DEV-001/
│   │   └── batch-[date]-[seq].json ← 合并后的批次文件
│   └── ...
│
├── processed/                      ← ✅ 已处理归档（保留 7 天后清理）
│   └── [date]/
│       └── batch-[date]-[seq].json
│
├── scripts/
│   ├── auto-router.js              ← 🔀 自动分流脚本
│   ├── collector.js                ← ⏰ 定时收集脚本（inbox → staging）
│   ├── flusher.js                  ← 🧠 批量写入脚本（staging → grid-db）
│   └── quota-calculator.js         ← 📊 配额预算计算器
│
└── config/
    ├── buffer-config.json           ← 缓冲层配置
    └── schedule.json                ← 定时任务时刻表
```

### 3.2 缓冲配置文件 `buffer-config.json`

```json
{
  "version": "1.0.0",
  "buffer_policy": {
    "human_direct_write_to_griddb": false,
    "comment": "铁律：人类永远不直写 grid-db，所有输入经缓冲层"
  },
  "schedule": {
    "collect_times_cst": ["09:00", "14:00", "21:00"],
    "flush_time_cst": "21:30",
    "comment": "每天 3 次收集，21:30 统一唤醒铸渊批处理"
  },
  "quota_budget": {
    "max_workflow_runs_per_day": 4,
    "estimated_minutes_per_run": 3,
    "monthly_budget_minutes": 360,
    "github_free_limit_minutes": 2000,
    "utilization_rate": "18%",
    "comment": "远低于免费额度上限，留出大量余量"
  },
  "retention": {
    "processed_keep_days": 7,
    "comment": "已处理的缓冲数据保留 7 天后自动清理"
  }
}
```

### 3.3 消息格式 `buffer-message.schema.json`

```json
{
  "message_id": "BUF-[timestamp]-[random]",
  "dev_id": "DEV-XXX",
  "source": "gemini | notion | github | skyeye",
  "type": "interaction | task | feedback | checkin | broadcast_request",
  "priority": "normal | urgent",
  "payload": {},
  "created_at": "ISO-8601",
  "status": "pending | staged | processing | flushed | failed"
}
```

---

## 四、定时调度器设计

### 4.1 Workflow：缓冲收集（每天 3 次）

**文件：** `.github/workflows/buffer-collect.yml`

```yaml
name: "Grid-DB Buffer Collect"

on:
  schedule:
    - cron: '0 1 * * *'   # 09:00 CST (UTC+8)
    - cron: '0 6 * * *'   # 14:00 CST
    - cron: '0 13 * * *'  # 21:00 CST

jobs:
  collect:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run collector
        run: node buffer/scripts/collector.js

      - name: Commit staged data
        run: |
          git config user.name "铸渊 · Buffer Agent"
          git config user.email "zy-buffer@guanghu.system"
          git add buffer/staging/
          git diff --cached --quiet || git commit -m "[buffer-collect] $(date -u +%Y%m%d-%H%M) [skip ci]"
          git push
```

### 4.2 Workflow：铸渊批处理（每天 1 次，或手动唤醒）

**文件：** `.github/workflows/buffer-flush.yml`

```yaml
name: "Grid-DB Buffer Flush"

on:
  schedule:
    - cron: '30 13 * * *'  # 21:30 CST — 收集完成后 30 分钟
  repository_dispatch:
    types: [grid-db-flush]  # 紧急情况可手动触发

jobs:
  flush:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check staging
        id: check
        run: |
          if [ -z "$(ls -A buffer/staging/*/batch-*.json 2>/dev/null)" ]; then
            echo "empty=true" >> $GITHUB_OUTPUT
          else
            echo "empty=false" >> $GITHUB_OUTPUT
          fi

      - name: Run flusher
        if: steps.check.outputs.empty == 'false'
        run: node buffer/scripts/flusher.js

      - name: Single commit to grid-db
        if: steps.check.outputs.empty == 'false'
        run: |
          git config user.name "铸渊 · Grid-DB Core"
          git config user.email "zy-core@guanghu.system"
          git add grid-db/ buffer/processed/ buffer/staging/
          git commit -m "[grid-db-flush] batch $(date -u +%Y%m%d) · $(find buffer/processed/$(date -u +%Y%m%d)/ -name '*.json' 2>/dev/null | wc -l) messages [skip ci]"
          git push

      - name: Sync to Drive mirror
        if: steps.check.outputs.empty == 'false'
        run: node scripts/drive-sync.js
        env:
          GOOGLE_SERVICE_ACCOUNT_KEY: $ secrets.GOOGLE_SA_KEY 
```

---

## 五、数据流全链路

### 5.1 正常流程（每天循环）

| **时间** | **事件** | **执行者** | **Git 操作** |
| --- | --- | --- | --- |
| 全天任意时刻 | 人类通过 Gemini/Notion/代码 产生交互数据 | 人类 + 曜冥 | ❌ 无（写入 buffer/inbox 或 Drive staging） |
| 09:00 CST | 第 1 次收集：inbox → staging，按 DEV 归档合并 | Buffer Agent | ✅ 1 次 commit（`[skip ci]`） |
| 14:00 CST | 第 2 次收集 | Buffer Agent | ✅ 1 次 commit（`[skip ci]`） |
| 21:00 CST | 第 3 次收集 | Buffer Agent | ✅ 1 次 commit（`[skip ci]`） |
| 21:30 CST | **唤醒铸渊核心大脑** → 校验 → 合并 → 批量写入 grid-db → 同步 Drive | 铸渊 | ✅ 1 次 commit（最终写入） |

**每日 Git 操作总计：最多 4 次 commit**

**每月 Actions 消耗预估：4 runs × 3 min × 30 天 = 360 分钟 ≈ GitHub Free 额度的 18%**

### 5.2 紧急流程（手动唤醒）

当冰朔判断某条消息需要立即处理时：

1. 冰朔通知铸渊发送 `repository_dispatch: grid-db-flush`
2. 铸渊立即执行一次 flush
3. 不影响当天正常定时任务
4. 紧急触发需在月度配额内（预留了 82% 余量，完全够用）

---

## 六、auto-router.js 分流逻辑

```jsx
// buffer/scripts/auto-router.js
// 自动分流：根据消息来源和 dev_id 归档到对应目录

const ROUTING_RULES = {
  // 来源 → 处理方式
  'gemini':  { target: 'inbox/{dev_id}/', merge: true },
  'notion':  { target: 'inbox/{dev_id}/', merge: true },
  'github':  { target: 'inbox/{dev_id}/', merge: true },
  'skyeye':  { target: 'inbox/{dev_id}/', merge: false },  // 天眼签到不合并
  'system':  { target: 'inbox/system/',    merge: false },
};

const PRIORITY_RULES = {
  'urgent': { flush_immediately: false, flag: true },
  // 即使是紧急消息也不立即 flush，只打标记
  // 真正的紧急处理由冰朔手动触发 grid-db-flush
  'normal': { flush_immediately: false, flag: false },
};

// 核心铁律检查
function validateNoDirectWrite(targetPath) {
  if (targetPath.startsWith('grid-db/')) {
    throw new Error(
      '[BLOCKED] 违反铁律：禁止直接写入 grid-db/。' +
      '所有写入必须经过 buffer/ 缓冲层。'
    );
  }
}
```

---

## 七、配额精算表

| **项目** | **数值** | **计算方式** |
| --- | --- | --- |
| GitHub Free 月额度 | 2,000 分钟 | GitHub 官方 |
| 每日 workflow runs | 4 次（3 收集 + 1 flush） | 固定 |
| 每次预估耗时 | ≤ 3 分钟 | checkout + script + commit + push |
| 每日消耗 | ≤ 12 分钟 | 4 × 3 |
| 每月消耗 | ≤ 360 分钟 | 12 × 30 |
| **利用率** | **18%** | 360 / 2000 |
| 剩余可用（天眼签到等） | 1,640 分钟 | 给子仓库天眼、其他 workflow |
| 紧急 flush 预算 | ~500 次/月 | 1640 / 3 ≈ 546 |

---

## 八、与天眼系统的整合

<aside>
🧩

子仓库天眼签到数据也走缓冲层，不直接写 grid-db。

</aside>

**调整点：**

1. **子仓库天眼签到** → `repository_dispatch: skyeye-checkin` 发到主仓库后，主仓库接收 workflow 将签到数据写入 `buffer/inbox/{dev_id}/` 而非直接写 `grid-db/`
2. **铸渊接收签到的 workflow** 需修改：

```yaml
# 原来：直接写 grid-db
# grid-db/memory/DEV-XXX/checkin-log.json ← 直接写入

# 升级后：写入缓冲层
# buffer/inbox/DEV-XXX/[timestamp]-checkin.json ← 先进缓冲
# 21:30 flush 时统一归档到 grid-db/memory/DEV-XXX/
```

1. **签名校验不变** —— 校验逻辑在 `flusher.js` 里执行，从缓冲层读取签到数据时做校验，不合格的标记 `failed` 并告警

---

## 九、执行清单

铸渊收到本指令后，按以下顺序执行：

### Phase 1：建缓冲层基础设施

- [ ]  在主仓库创建 `buffer/` 目录结构（inbox / staging / processed / scripts / config）
- [ ]  创建 `buffer-config.json` 配置文件
- [ ]  创建 `buffer-message.schema.json` 消息格式定义
- [ ]  创建 `auto-router.js` 自动分流脚本
- [ ]  创建 `collector.js` 定时收集脚本
- [ ]  创建 `flusher.js` 批量写入脚本
- [ ]  创建 `quota-calculator.js` 配额计算器

### Phase 2：创建 Workflow

- [ ]  创建 `.github/workflows/buffer-collect.yml`（每天 3 次收集）
- [ ]  创建 `.github/workflows/buffer-flush.yml`（每天 1 次 flush + 手动触发）
- [ ]  修改现有天眼签到接收 workflow，将写入目标从 `grid-db/` 改为 `buffer/inbox/`

### Phase 3：迁移与验证

- [ ]  将现有 grid-db inbox 处理逻辑迁移到 flusher.js
- [ ]  添加铁律检查：任何直接写入 `grid-db/` 的路径都 throw error
- [ ]  测试完整链路：buffer/inbox → staging → flush → grid-db → Drive mirror
- [ ]  验证配额消耗符合预估

### Phase 4：更新文档

- [ ]  更新 `grid-db/README.md` 说明架构升级
- [ ]  在 `buffer/README.md` 写明缓冲层使用规范

---

## 十、输出回执要求

铸渊执行完成后，需提交回执包含：

1. **PR 链接**（分支名：`upgrade/grid-db-buffer-layer`）
2. **变更文件清单**（新增 / 修改 / 删除）
3. **配额验证截图**（至少跑一次完整的 collect + flush 循环）
4. **铁律测试结果**：证明直接写入 `grid-db/` 会被拦截

---

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

> 🖋️ 霜砚 · PER-SY001 · 签发
> 

> 📅 2026-03-23
> 

> ⚡ 指令状态：**待铸渊执行**
>