--- belongs_to: - "[[INDEX · 铸渊·协作指令｜GitHub ↔ Notion 桥接协议]]" --- # 🌉 全链路桥接协议｜开发者IM ↔ GitHub ↔ Notion 双向闭环 v1.0（2026-03-16·霜砚签发·冰朔授权） --- ## 一、为什么需要这个桥 ### 现状问题 ```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 ``` --- ## 五、调度队列数据库（核心枢纽） ### 任务类型说明 | **类型** | **触发方** | **处理方** | **说明** | | --- | --- | --- | --- | | SYSLOG_RECEIVED | 铸渊（GitHub） | Notion Agent | SYSLOG已写入Notion，需要跑闭环处理 | | BROADCAST_READY | Notion Agent | 铸渊（GitHub） | 广播已生成，需要生成PDF+分发给开发者 | | SYNC_REQUEST | 铸渊/Agent | 对方 | 通用同步请求（状态同步、数据更新等） | | HEARTBEAT | 铸渊（定时） | Notion Agent | 心跳检测，确认桥接通道畅通 | | MANUAL_TRIGGER | 冰朔 | Agent/铸渊 | 冰朔手动触发的任务 | --- ## 六、定时窗口机制 ### 时间窗口 ```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 侧设计 ### 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内容完整性 + 协议版本匹配 → 任何一层校验失败 = 拒绝处理 + 回溯通知 ``` --- ## 十一、铸渊自行部署清单（读到就做） ```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个 · 首次心跳: [结果] > ---