a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
423 lines
14 KiB
Markdown
423 lines
14 KiB
Markdown
---
|
||
belongs_to:
|
||
- "[[INDEX · 铸渊·协作指令｜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
|
||
>
|
||
|
||
> ⚡ 指令状态：**待铸渊执行**
|
||
> |