shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令｜GitHub ↔ Notion 桥接协议/🛡️ 铸渊指令｜Grid-DB 架构升级 · 写缓冲层 + 定时批处理 + 人类零直写（ZY-GRI 95166397932748fbba428ebd597c2adc.md

belongs_to

belongs_to
INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议

🛡️ 铸渊指令｜Grid-DB 架构升级 · 写缓冲层 + 定时批处理 + 人类零直写（ZY-GRIDDB-BUFFER-2026-0323-001）

📌

指令编号： 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） · 🪞 铸渊指令｜Google Drive 镜像桥接层 · Gemini↔格点库实时同步（ZY-DRIVE-BRIDGE-2026-0323-001）

关联文档： 🗄️ Grid-DB · 逻辑格点库 · 自研应用技术文档

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

---

一、升级背景与目标

1.1 现有架构的四个风险点

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

1.2 升级目标

🎯

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

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

---

二、升级后架构总览

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 根目录新建：

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

{
  "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

{
  "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

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

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 分流逻辑

// 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

---

八、与天眼系统的整合

🧩

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

调整点：

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

# 原来：直接写 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

⚡ 指令状态：待铸渊执行