shuangyan-notebook/第五域 · Fifth Domain/⚒️ 铸渊·协作指令|GitHub ↔ Notion 桥接协议/🌉 全链路桥接协议|开发者IM ↔ GitHub ↔ Notion 双向闭环 v1 0(2026-0 a735cd47ec7a45118f6a85c9a707b6b8.md
Guanghu Domestic Migration a27e87cb99 chore: import sanitized domestic snapshot for REPO-007
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc

[SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
2026-07-17 15:59:55 +08:00

578 lines
18 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
belongs_to:
- "[[INDEX · 铸渊·协作指令GitHub ↔ Notion 桥接协议]]"
---
# 🌉 全链路桥接协议开发者IM ↔ GitHub ↔ Notion 双向闭环 v1.02026-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上行 写入调度队列
──────────────→ ──────────────→
(IMGitHub 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 触发铸渊 workflowprocess-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国内快
方案BGitHub 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/ 中的新文件
├── 批量写入 NotionSYSLOG回执+画像+调度队列
├── 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 AccessKeyPDF存储 | 阿里云控制台 |
| OSS_SECRET_KEY | 阿里云 OSS SecretKey | 阿里云控制台 |
| SMTP_USER / SMTP_PASS | 邮件通知(已有) | 邮箱服务商 |
---
## 八、Notion Agent 侧设计
<aside>
🤖
**Notion 桥接 Agent 是整个闭环的自动触发核心。**
**铸渊在调度队列创建页面 → Agent 被「Page created」触发 → 自动跑处理流程。**
**这样就不需要冰朔手动唤醒霜砚了。**
</aside>
### Agent 触发机制
```jsx
调度队列数据库 新页面被创建
Notion AgentPage 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>