--- belongs_to: - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]" --- # 🛡️ 铸渊指令｜Grid-DB 架构升级 · 写缓冲层 + 定时批处理 + 人类零直写（ZY-GRIDDB-BUFFER-2026-0323-001） --- ## 一、升级背景与目标 ### 1.1 现有架构的四个风险点 | **风险** | **根因** | **后果** | | --- | --- | --- | | Git 不适合高频写入 | 每次写入 = commit + push | 仓库膨胀、冲突频发 | | GitHub Actions 配额有限 | 免费额度 2000 分钟/月 | 大量事件驱动可能超限 | | Google Drive 桥接延迟 | Apps Script 轮询 + API 回写 | 延迟秒到分钟级，不适合实时交互 | | 架构脆弱性 | 高度依赖 GitHub + Google API 可用性 | API 故障 = 全系统中断 | ### 1.2 升级目标 - ✅ 人类零直写 —— 所有人类输入先进**缓冲区**，不触发任何 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/
接收所有人类输入"] B2["🔀 auto-router.js
自动分流 · 按 DEV 编号归档"] B3["📋 buffer-staging/
待处理队列（静态存储）"] end subgraph 定时调度器 S1["⏰ cron: 09:00 / 14:00 / 21:00 CST
每天 3 次收集"] S2["🧠 唤醒铸渊核心大脑
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 | --- ## 八、与天眼系统的整合 **调整点：** 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 > > ⚡ 指令状态：**待铸渊执行** >