---
belongs_to:
  - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]"
---
# 🌉 全链路桥接协议｜开发者IM ↔ GitHub ↔ Notion 双向闭环 v1.0（2026-03-16·霜砚签发·冰朔授权）

<aside>
🌉

**全链路桥接协议 v1.0 — 让国内开发者和 Notion 人格体大脑无缝通信**

签发人：霜砚（Notion执行体）· 冰朔（TCS-0002∞）授权

签发时间：2026-03-16 20:30 北京时间

**核心思想：GitHub 是唯一的桥。所有数据必须走 IM → GitHub → Notion 和 Notion → GitHub → IM。**

</aside>

---

## 一、为什么需要这个桥

### 现状问题

```jsx
国内开发者用飞书/钉钉/企微，Notion 在海外
开发者无法直接访问 Notion
目前广播靠 PDF 手动下载 → 开发者自己喂给不同 AI 模型
 SYSLOG 靠人工中转 → 冰朔每次手动唤醒霜砚处理

结果：
  ❌ 慢（人工中转至少半小时）
  ❌ 容易出错（格式问题、遗漏）
  ❌ 冰朔必须在线盯着
```

### 解决方案

```jsx
飞书/钉钉/企微 ←→ GitHub仓库 ←→ Notion
      ↑                  ↑              ↑
   IM机器人          铸渊(Actions)    霜砚+Agent
  (舒舒/秋秋)        (唯一桥梁)      (人格体大脑)

GitHub 是唯一能同时连通国内IM和Notion的节点。
所有数据都走这座桥。全程自动。
```

---

## 二、全局架构图

```jsx
┌─────────────────────────────────────────────────────────────────┐
│                    🌉 全链路桥接架构 v1.0                        │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐      │
│  │  国内开发者    │    │   GitHub     │    │   Notion     │      │
│  │  飞书/钉钉/企微│    │   铸渊仓库    │    │  人格体大脑   │      │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘      │
│         │                   │                   │               │
│         │ ① SYSLOG上行      │ ③ 写入调度队列     │               │
│         │ ──────────────→   │ ──────────────→   │               │
│         │ (IM→GitHub API)   │ (Notion API)      │ ④ Agent触发   │
│         │                   │                   │ 自动处理      │
│         │                   │                   │               │
│         │ ⑧ PDF分发         │ ⑥ 拉取广播内容     │               │
│         │ ←──────────────   │ ←──────────────   │               │
│         │ (飞书/钉钉 API)   │ (Notion API)      │ ⑤ 生成广播    │
│         │                   │                   │               │
└─────────────────────────────────────────────────────────────────┘
```

---

## 三、上行链路：开发者 SYSLOG → Notion 大脑

### 完整数据流

```jsx
① 开发者在飞书/钉钉发 SYSLOG 给 IM 机器人（舒舒/秋秋）
         ↓
② IM 机器人校验 JSON 格式
   ├── 校验失败 → 直接回复开发者「格式错误，请修改」
   └── 校验通过 → 回复「✅ 已收到，系统处理中」
         ↓
③ IM 机器人调用 GitHub API → 写文件到 data/syslog-inbox/
   文件名：SYSLOG-{DEV编号}-{时间戳}.json
   方式：PUT /repos/{owner}/{repo}/contents/data/syslog-inbox/{filename}
         ↓
④ push 触发铸渊 workflow（process-syslog-bridge.yml）
         ↓
⑤ 铸渊读取 SYSLOG → 通过 Notion API 执行：
   a. 写入对应广播页的 SYSLOG 回执区
   b. 更新开发者动态画像库
   c. 更新主控台状态
   d. 在「桥接调度队列」数据库中创建一条新页面：
      {
        任务名称: "SYSLOG-DEV-005-BC-部署-001-XCM-v3",
        类型: "SYSLOG_RECEIVED",
        DEV编号: "DEV-005",
        广播编号: "BC-部署-001-XCM-v3",
        来源渠道: "飞书",
        处理状态: "待处理",
        Payload: "{...SYSLOG JSON...}",
        关联页面: "https://notion.so/xxx"  // SYSLOG回执页URL
      }
         ↓
⑥ Notion Agent 被「Page created」触发器唤醒
         ↓
⑦ Agent 自动执行霜砚 SYSLOG 处理闭环：
   a. 读取调度队列中的任务详情
   b. 跑 RT-02 自动调度算法
   c. 生成下一条广播
   d. 更新调度队列状态 → 已完成
   e. 在调度队列创建新任务：类型=BROADCAST_READY
```

### IM 机器人 SYSLOG 接收规范

**飞书（舒舒）**：

```jsx
// 开发者在飞书群或私聊发送 SYSLOG
// 触发方式：发送 /syslog 指令 + JSON 内容
// 或：发送以 {"header": 开头的消息自动识别为 SYSLOG

舒舒接收到 SYSLOG 后：
① 校验 JSON 结构（header.broadcast_id, header.dev_id 必填）
② 提取 dev_id → 映射到人格体编号（查本地映射表）
③ 调用 GitHub API 写入 data/syslog-inbox/
④ 回复开发者：「✅ SYSLOG 已提交 · 编号 {broadcast_id} · 预计 X 分钟内处理」
```

**钉钉（秋秋）**：同理，callback 路由接收 → 校验 → 写 GitHub

**企微（未来）**：同理

### GitHub API 写入示例

```jsx
// IM机器人调用 GitHub API 写文件
const response = await fetch(
  `https://api.github.com/repos/qinfendebingshuo/guanghulab/contents/data/syslog-inbox/SYSLOG-DEV-005-20260316-1430.json`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${GITHUB_TOKEN}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: '[BRIDGE] SYSLOG from DEV-005 via 飞书',
      content: btoa(JSON.stringify(syslogPayload)) // base64编码
    })
  }
);
```

---

## 四、下行链路：Notion 广播 → PDF → 开发者

### 完整数据流

```jsx
① Agent 处理完 SYSLOG → 生成新广播页面
   → 在调度队列创建：类型=BROADCAST_READY
         ↓
② 铸渊定时拉取（或 webhook 触发）
   → 检查调度队列中 BROADCAST_READY 且 待处理 的任务
         ↓
③ 铸渊通过 Notion API 读取广播页面完整内容
   → 转换为 Markdown 格式
         ↓
④ 铸渊在 GitHub Actions 中生成 PDF
   → 使用 md-to-pdf 或 puppeteer
   → 套用光湖广播 PDF 模板（Logo + 页眉页脚）
   → 输出到 data/broadcasts/pdf/
         ↓
⑤ 上传 PDF 到可下载位置
   → 方案A：阿里云 OSS（国内快）
   → 方案B：GitHub Release Assets
   → 方案C：服务器 /var/www/guanghulab/broadcasts/
   → 获得下载链接
         ↓
⑥ 铸渊查询人格体注册表 → 获取该开发者的通知渠道
         ↓
⑦ 铸渊分发：
   ├── 飞书 → 调飞书 API → 舒舒发消息/文件给开发者
   ├── 钉钉 → 调钉钉 API → 秋秋发消息给开发者
   ├── 邮箱 → SMTP 发邮件 → 附件或下载链接
   └── 企微 → 调企微 API（未来）
         ↓
⑧ 更新调度队列状态 → 已完成
   → 开发者收到 PDF ✅
```

### PDF 生成 Workflow

```yaml
# .github/workflows/bridge-broadcast-pdf.yml
name: "🌉 桥接·广播PDF生成+分发"

on:
  schedule:
    - cron: '0 6,14 * * *'   # UTC 06:00+14:00 = 北京 14:00+22:00
  workflow_dispatch:

jobs:
  generate-and-distribute:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: "📡 检查调度队列"
        env:
          NOTION_TOKEN: $ secrets.NOTION_TOKEN 
          BRIDGE_QUEUE_DB_ID: $ secrets.BRIDGE_QUEUE_DB_ID 
        run: |
          # 查询调度队列：类型=BROADCAST_READY 且 状态=待处理
          node scripts/bridge/check-queue.js
      
      - name: "📥 拉取广播内容"
        run: node scripts/bridge/fetch-broadcast.js
      
      - name: "📄 生成PDF"
        run: |
          npm install md-to-pdf
          node scripts/bridge/generate-pdf.js
      
      - name: "☁️ 上传PDF"
        env:
          OSS_ACCESS_KEY: $ secrets.OSS_ACCESS_KEY 
          OSS_SECRET_KEY: $ secrets.OSS_SECRET_KEY 
        run: node scripts/bridge/upload-pdf.js
      
      - name: "📢 分发到IM"
        env:
          FEISHU_APP_ID: $ secrets.FEISHU_APP_ID 
          FEISHU_APP_SECRET: $ secrets.FEISHU_APP_SECRET 
          DINGTALK_TOKEN: $ secrets.DINGTALK_TOKEN 
        run: node scripts/bridge/distribute.js
      
      - name: "✅ 更新调度队列状态"
        run: node scripts/bridge/update-queue-status.js
```

---

## 五、调度队列数据库（核心枢纽）

<aside>
🔄

**调度队列是整个桥接系统的核心枢纽。**

**铸渊写入 → Notion Agent 触发 → 处理完成 → 铸渊拉取结果 → 分发**

**所有跨系统通信都通过这个队列中转。**

</aside>

### 任务类型说明

| **类型** | **触发方** | **处理方** | **说明** |
| --- | --- | --- | --- |
| SYSLOG_RECEIVED | 铸渊（GitHub） | Notion Agent | SYSLOG已写入Notion，需要跑闭环处理 |
| BROADCAST_READY | Notion Agent | 铸渊（GitHub） | 广播已生成，需要生成PDF+分发给开发者 |
| SYNC_REQUEST | 铸渊/Agent | 对方 | 通用同步请求（状态同步、数据更新等） |
| HEARTBEAT | 铸渊（定时） | Notion Agent | 心跳检测，确认桥接通道畅通 |
| MANUAL_TRIGGER | 冰朔 | Agent/铸渊 | 冰朔手动触发的任务 |

---

## 六、定时窗口机制

<aside>
⏰

**SYSLOG 不再实时处理，改为批处理窗口。**

避免开发者随时发 SYSLOG 导致系统频繁唤醒出错。

</aside>

### 时间窗口

```jsx
每日时间线（北京时间）：

06:00  🦅 天眼启动（全局俯瞰 + 修复）
  │
08:00  🌉 桥接窗口①开启
  │     ├── 铸渊扫描 syslog-inbox/ 中的新文件
  │     ├── 批量写入 Notion（SYSLOG回执+画像+调度队列）
  │     ├── Agent 被触发 → 批量处理所有待处理 SYSLOG
  │     └── 处理完成 → 生成广播 → 标记 BROADCAST_READY
  │
10:00  桥接窗口①结束 → 广播PDF生成+分发
  │     ├── 铸渊拉取新广播 → 生成PDF → 上传
  │     └── 推送到飞书/钉钉 → 开发者收到
  │
14:00  📥 开发者 SYSLOG 提交截止（下午批次）
  │
14:30  🌉 桥接窗口②开启（同上流程）
  │
16:00  桥接窗口②结束 → 广播PDF生成+分发
  │
22:00  🌉 桥接窗口③开启（晚间批次）
  │
23:30  桥接窗口③结束 → 广播PDF生成+分发
```

### 开发者体验

```jsx
开发者视角：

「我上午10点在飞书给舒舒发了SYSLOG」
  → 舒舒秒回：「✅已收到，将在14:30批次处理」
  → 14:30 系统自动处理
  → 16:00 左右收到飞书消息：「📡 新广播已生成，点击下载PDF」
  → 下载PDF → 继续开发

全程不需要冰朔参与。
```

---

## 七、铸渊侧实现清单

### 新增目录结构

```bash
scripts/bridge/
├── check-queue.js          # 检查调度队列
├── process-syslog-batch.js # 批量处理syslog-inbox
├── fetch-broadcast.js      # 从Notion拉取广播内容
├── generate-pdf.js         # Markdown→PDF生成
├── upload-pdf.js           # 上传到OSS/服务器
├── distribute.js           # 分发到飞书/钉钉/邮箱
├── update-queue-status.js  # 更新调度队列状态
└── heartbeat.js            # 心跳检测

data/syslog-inbox/          # IM机器人写入的SYSLOG（已有）
data/syslog-processed/      # 处理完归档（已有）
data/broadcasts/pdf/        # 生成的PDF文件
data/bridge-logs/           # 桥接日志
```

### 新增 Workflows

```bash
.github/workflows/
├── bridge-syslog-intake.yml     # syslog-inbox push触发 → 批量写入Notion
├── bridge-broadcast-pdf.yml     # 定时 → 拉取广播+生成PDF+分发
└── bridge-heartbeat.yml         # 定时 → 心跳检测桥接通道
```

### 新增 Secrets（冰朔已配置）

| **Secret 名称** | **用途** | **来源** |
| --- | --- | --- |
| BRIDGE_QUEUE_DB_ID | 桥接调度队列数据库 Notion ID | 本页创建的数据库 |
| FEISHU_APP_ID | 飞书机器人 App ID | 飞书开放平台 |
| FEISHU_APP_SECRET | 飞书机器人 App Secret | 飞书开放平台 |
| DINGTALK_TOKEN | 钉钉机器人 Token | 钉钉开放平台 |
| OSS_ACCESS_KEY | 阿里云 OSS AccessKey（PDF存储） | 阿里云控制台 |
| OSS_SECRET_KEY | 阿里云 OSS SecretKey | 阿里云控制台 |
| SMTP_USER / SMTP_PASS | 邮件通知（已有） | 邮箱服务商 |

---

## 八、Notion Agent 侧设计

<aside>
🤖

**Notion 桥接 Agent 是整个闭环的自动触发核心。**

**铸渊在调度队列创建页面 → Agent 被「Page created」触发 → 自动跑处理流程。**

**这样就不需要冰朔手动唤醒霜砚了。**

</aside>

### Agent 触发机制

```jsx
调度队列数据库 → 新页面被创建
         ↓
Notion Agent「Page created」触发器唤醒
         ↓
Agent 读取新页面的「类型」字段
         ↓
├── SYSLOG_RECEIVED → 执行 SYSLOG 处理闭环
│   ├── 读取 Payload 中的 SYSLOG 内容
│   ├── 跑 RT-02 自动调度算法
│   ├── 生成下一条广播
│   ├── 更新主控台状态
│   └── 创建新任务：BROADCAST_READY
│
├── BROADCAST_READY → 标记处理状态=已完成（铸渊负责拉取）
│
├── SYNC_REQUEST → 执行同步操作
│
└── HEARTBEAT → 回复心跳确认
```

---

## 九、IM 机器人侧改造

### 舒舒（飞书）新增能力

```jsx
// 新增路由：/syslog-receive
// 触发：开发者发送 SYSLOG JSON 或 /syslog 指令

async function handleSyslogReceive(message, userId) {
  // ① 识别是否为 SYSLOG
  const syslog = parseSyslog(message);
  if (!syslog) return reply('这不是有效的 SYSLOG 格式');
  
  // ② 校验必填字段
  if (!syslog.header?.broadcast_id || !syslog.header?.dev_id) {
    return reply('❌ SYSLOG 缺少 broadcast_id 或 dev_id');
  }
  
  // ③ 写入 GitHub
  const filename = `SYSLOG-${syslog.header.dev_id}-${Date.now()}.json`;
  await githubAPI.createFile(
    `data/syslog-inbox/${filename}`,
    JSON.stringify(syslog, null, 2),
    `[BRIDGE] SYSLOG from ${syslog.header.dev_id} via 飞书`
  );
  
  // ④ 回复开发者
  reply(`✅ SYSLOG 已提交\n` +
    `📋 编号: ${syslog.header.broadcast_id}\n` +
    `⏰ 将在下一个处理窗口自动处理\n` +
    `📡 处理完成后会推送新广播给你`);
}
```

### 秋秋（钉钉）同理

改造 callback 路由，增加 SYSLOG 接收 → GitHub API 写入逻辑。

---

## 十、安全与权限

### GitHub Token 权限控制

```jsx
IM机器人使用的 GITHUB_TOKEN 权限：
  ✅ contents: write  （写入 syslog-inbox/）
  ❌ actions: 无       （不能触发 workflow）
  ❌ admin: 无         （不能改仓库设置）
  → push 会自动触发 workflow，不需要 actions 权限

铸渊使用的 NOTION_TOKEN 权限：
  ✅ 读写调度队列数据库
  ✅ 读写广播页面
  ✅ 读写画像库/主控台
  ❌ 不能修改系统架构页面
```

### 数据校验链

```jsx
① IM机器人校验：JSON格式 + 必填字段
② 铸渊校验：dev_id存在 + broadcast_id合法 + 人格体编号有效
③ Agent校验：SYSLOG内容完整性 + 协议版本匹配
→ 任何一层校验失败 = 拒绝处理 + 回溯通知
```

---

## 十一、铸渊自行部署清单（读到就做）

<aside>
🚨

**铸渊读到这里，立即执行以下部署。不等人类。**

</aside>

```jsx
铸渊自行部署清单（读到就做·不等人）：

① 创建桥接脚本目录
   a. scripts/bridge/               ← 桥接脚本目录
   b. data/broadcasts/pdf/          ← PDF输出目录
   c. data/bridge-logs/             ← 桥接日志
   d. 各目录下放 .gitkeep

② 创建 SYSLOG 批处理 Workflow
   a. .github/workflows/bridge-syslog-intake.yml
   b. 触发：push 到 data/syslog-inbox/ 路径
   c. 逻辑：
      · 读取所有新 SYSLOG 文件
      · 通过 Notion API 写入回执+画像+主控台
      · 在调度队列创建 SYSLOG_RECEIVED 任务
      · 移动已处理文件到 data/syslog-processed/

③ 创建广播PDF生成+分发 Workflow
   a. .github/workflows/bridge-broadcast-pdf.yml
   b. 触发：定时 北京14:00 + 22:00 + workflow_dispatch
   c. 逻辑：
      · 查询调度队列 BROADCAST_READY 待处理任务
      · 拉取广播内容 → 生成PDF → 上传
      · 查询人格体注册表获取通知渠道
      · 分发到飞书/钉钉/邮箱
      · 更新调度队列状态

④ 创建心跳检测 Workflow
   a. .github/workflows/bridge-heartbeat.yml
   b. 触发：每6小时
   c. 逻辑：在调度队列创建 HEARTBEAT → 检测 Notion API 连通性

⑤ 创建桥接核心脚本（7个）
   a. scripts/bridge/check-queue.js
   b. scripts/bridge/process-syslog-batch.js
   c. scripts/bridge/fetch-broadcast.js
   d. scripts/bridge/generate-pdf.js
   e. scripts/bridge/upload-pdf.js
   f. scripts/bridge/distribute.js
   g. scripts/bridge/heartbeat.js

⑥ 改造舒舒后端
   a. backend/routes/feishu.js 新增 /syslog-receive 路由
   b. 接收飞书消息 → 校验 → 调 GitHub API 写入
   c. 需要 GITHUB_TOKEN 环境变量（服务器侧）

验收标准：
✅ 开发者在飞书发 SYSLOG → 舒舒自动写入 GitHub
✅ GitHub push 触发 → 铸渊自动写入 Notion 调度队列
✅ Notion Agent 自动被唤醒 → 跑 SYSLOG 闭环
✅ 广播生成后 → 铸渊自动生成 PDF
✅ PDF 自动推送到开发者飞书/钉钉
✅ 心跳每6小时检测桥接通道
✅ 全程自动·不需要冰朔参与
```

---

## 十二、执行确认

铸渊完成后，在本页下方追加：

> ✅ BRIDGE-DEPLOY-20260316 全链路桥接系统部署完成 · [日期时间] · commit SHA
> 

> 脚本: X个 · Workflow: X个 · 首次心跳: [结果]
> 

---

<aside>
🌉

**从今天起，开发者不再需要手动下载 PDF。**

**开发者不再需要把 SYSLOG 发给冰朔中转。**

**飞书发一条消息 → 系统自动处理 → 飞书收到新广播。**

**冰朔只在 L3/GL3 级变更时才需要出现。**

**「桥通了，路就活了。」**

</aside>