a27e87cb99
Source snapshot: 97d7f0fae96dc04b7ddad56fc1db6a108ed662cc [SEC-CLEAN] · pre-push-clean v1.0 · 109处敏感信息已自动转乱码
238 lines
8.6 KiB
Markdown
238 lines
8.6 KiB
Markdown
# 🔧 铸渊补丁指令 · v1.1 · Notion API 直连替代 ESP 邮件（2026-03-07）
|
||
|
||
<aside>
|
||
🚨
|
||
|
||
**补丁指令 · 强制 · 2026-03-07**
|
||
|
||
**发出方**：霜砚（Notion执行层）
|
||
|
||
**接收方**：铸渊（GitHub端）
|
||
|
||
**性质**：基于已发的全链路设计文档 + 前端界面设计文档的**增量补丁**，不是重写，只改需要改的部分。
|
||
|
||
**原因**：Gmail 授权走不通（个人 Gmail 不支持 Google Workspace Marketplace），妈妈已确认改用 Notion API 直连。
|
||
|
||
</aside>
|
||
|
||
---
|
||
|
||
# 一句话总结
|
||
|
||
**原来用邮件传信号（ESP），现在改成铸渊直接通过 Notion API 读写 Notion 数据库。更快、更可靠、不依赖任何邮箱。**
|
||
|
||
---
|
||
|
||
# 一、什么变了
|
||
|
||
| 项目 | 原方案 | 新方案 |
|
||
| --- | --- | --- |
|
||
| **铸渊→霜砚 通信** | 发 [GL-DATA] / [GL-ACK] 邮件 | 直接调 Notion API 写入工单簿 / 信号日志数据库 |
|
||
| **霜砚→铸渊 通信** | 发 [GL-CMD] 邮件，铸渊 IMAP 轮询 | 霜砚写入工单簿，铸渊 Notion API 轮询工单簿 |
|
||
| **广播→开发者** | 邮件发 PDF | 铸渊从 Notion 读广播 → 推送到铸渊聊天室子频道 |
|
||
| **API Key 管理** | 前端硬编码 | 后端代理统一管理，前端不碰 Key |
|
||
| **模型选择** | 仅 Gemini（海外，需翻墙） | 优先 DeepSeek（国内直连），后扩展 Claude/Gemini |
|
||
|
||
# 二、什么没变
|
||
|
||
- 信号类型定义不变（GL-CMD / GL-ACK / GL-DATA / GL-BC）
|
||
- 信号 JSON 格式不变（esp_version / signal_type / trace_id / payload）
|
||
- GitHub 端 `signal-log/` 目录结构不变
|
||
- 全链路闭环流程不变（push → 质检 → 数据提取 → Notion 写入 → 新广播 → 开发者）
|
||
- 铸渊核心大脑系统提示词不变
|
||
|
||
# 三、妈妈已完成的配置
|
||
|
||
妈妈已经在 Notion 和 GitHub 两端都配好了，铸渊直接用就行：
|
||
|
||
| ✅ | 配置项 | 详情 |
|
||
| --- | --- | --- |
|
||
| 1 | **Notion Integration** | 名称「铸渊信号桥」，已创建并授权访问工单簿 + 主控台 |
|
||
| 2 | **GitHub Secret** | `NOTION_API_TOKEN` 已存入仓库 Secrets（和 `YUNWU_API_KEY` 同级） |
|
||
| 3 | **信号日志数据库** | 📡 跨平台信号日志（Signal Log）已建好，在主控台下，含13个字段 + 3个视图 |
|
||
| 4 | **工单簿** | 人格协作工单簿，已授权集成访问 |
|
||
|
||
# 四、铸渊要改什么
|
||
|
||
## 改动1：去掉所有邮件相关代码（暂时）
|
||
|
||
```
|
||
删除或注释掉：
|
||
- IMAP 轮询邮箱的 workflow / 代码
|
||
- SMTP 发邮件的逻辑
|
||
- Gmail 相关的环境变量引用（EMAIL_ADDRESS / EMAIL_APP_PASSWORD）
|
||
|
||
保留：
|
||
- 邮件格式规范文档（备用，不删）
|
||
- signal-log/ 目录结构（继续用）
|
||
```
|
||
|
||
## 改动2：新增 Notion API 读写能力
|
||
|
||
铸渊需要在 GitHub Actions 里用 `NOTION_API_TOKEN` 调 Notion API。
|
||
|
||
### 核心接口
|
||
|
||
```jsx
|
||
// 1. 读取工单簿（轮询新工单）
|
||
GET https://api.notion.com/v1/databases/{工单簿ID}/query
|
||
Headers:
|
||
Authorization: Bearer ${NOTION_API_TOKEN}
|
||
Notion-Version: 2022-06-28
|
||
Body:
|
||
{ "filter": { "property": "执行结果", "status": { "equals": "已发送" } } }
|
||
|
||
// 2. 更新工单状态
|
||
PATCH https://api.notion.com/v1/pages/{工单页面ID}
|
||
Body:
|
||
{ "properties": { "执行结果": { "status": { "name": "成功" } } } }
|
||
|
||
// 3. 写入信号日志
|
||
POST https://api.notion.com/v1/pages
|
||
Body:
|
||
{
|
||
"parent": { "database_id": "{信号日志数据库ID}" },
|
||
"properties": {
|
||
"信号编号": { "title": [{ "text": { "content": "SIG-2026-0307-001" } }] },
|
||
"信号类型": { "select": { "name": "GL-ACK" } },
|
||
"方向": { "select": { "name": "GitHub→Notion" } },
|
||
"发送方": { "select": { "name": "铸渊" } },
|
||
"接收方": { "select": { "name": "霜砚" } },
|
||
"trace_id": { "rich_text": [{ "text": { "content": "TRC-20260307-001" } }] },
|
||
"摘要": { "rich_text": [{ "text": { "content": "M14环节2质检通过" } }] },
|
||
"执行结果": { "status": { "name": "成功" } }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 推荐的 workflow 结构
|
||
|
||
```yaml
|
||
# .github/workflows/notion-poll.yml
|
||
name: 轮询 Notion 工单簿
|
||
on:
|
||
schedule:
|
||
- cron: '*/15 * * * *' # 每15分钟轮询一次
|
||
workflow_dispatch: # 手动触发
|
||
|
||
jobs:
|
||
poll-notion:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- name: 读取新工单
|
||
env:
|
||
NOTION_API_TOKEN: $ secrets.NOTION_API_TOKEN
|
||
run: |
|
||
# 调 Notion API 查询状态为「已发送」的工单
|
||
# 解析 OP 类型
|
||
# 执行对应操作
|
||
# 写回执到工单簿 + 信号日志
|
||
# 同时写入 signal-log/ 本地文件
|
||
```
|
||
|
||
## 改动3：前端 API 代理层（国内直连）
|
||
|
||
详见前端界面设计文档第八章，核心要点：
|
||
|
||
```
|
||
1. 新建 backend-integration/api-proxy.js
|
||
2. 前端 fetch 目标从 googleapis.com 改为 /api/chat
|
||
3. API Key 从前端 JS 移到后端环境变量
|
||
4. 优先接 DeepSeek（api.deepseek.com，国内直连）
|
||
5. 支持 SSE 流式透传
|
||
6. 后端部署在 Vercel / Railway / VPS（不是 GitHub Pages）
|
||
```
|
||
|
||
## 改动4：广播推送改走聊天室
|
||
|
||
```
|
||
原来：霜砚生成广播 → 邮件发 PDF → 开发者邮箱
|
||
现在：霜砚生成广播 → 铸渊通过 Notion API 读取 → 推送到聊天室子频道
|
||
|
||
铸渊的 workflow 需要：
|
||
1. 定时查询 Notion 广播归档页，检测新广播
|
||
2. 把广播内容格式化后写入开发者的聊天室数据
|
||
3. 开发者下次打开铸渊聊天室即可看到
|
||
```
|
||
|
||
---
|
||
|
||
# 五、数据库 ID 速查
|
||
|
||
铸渊调 Notion API 需要用到的数据库 ID（从 URL 中提取）：
|
||
|
||
| 数据库 | 用途 |
|
||
| --- | --- |
|
||
| **人格协作工单簿** | 铸渊轮询新工单 + 写回执 |
|
||
| **📡 跨平台信号日志** | 每次信号收发写一条记录 |
|
||
| **主控台** | 更新开发者状态 |
|
||
|
||
> **提取方式**：Notion 页面 URL 中 `notion.so/` 后面那串32位字符就是 ID。铸渊你自己从 URL 里提取就行。
|
||
>
|
||
|
||
---
|
||
|
||
# 六、执行优先级
|
||
|
||
| 优先级 | 任务 | 状态 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| **P0** | 新建 notion-poll workflow | ✅ **已完成** | `scripts/notion-signal-bridge.js` • `.github/workflows/notion-poll.yml`（15分钟轮询） |
|
||
| **P0** | 前端 API 代理层 + DeepSeek | ✅ **已完成** | `backend-integration/api-proxy.js`，6模型提供商（DeepSeek/Moonshot/智浦/云武/OpenAI/Gemini），SSE流式，CORS白名单 |
|
||
| **P1** | 修复铸渊聊天室部署 | ✅ **已完成** | 移除损坏的 `frontend/HoloLake-App` Git子模块 + `docs/index.html` v3.1→v4.0 三栏桌面布局 |
|
||
| **P1** | 广播推送到聊天室 | ⏳ 待做 | 读 Notion 广播归档 → 推送到子频道 |
|
||
| **P2** | 开发者上传脚本（上传.bat） | ⏳ 待做 | 自动网络检测 + push + 质检轮询 |
|
||
| **P2** | 去掉邮件相关代码 | ✅ **已完成** | `esp-signal-processor.yml` 已暂停（计划禁用，代码保留便于回滚） |
|
||
|
||
---
|
||
|
||
# 七、验收标准
|
||
|
||
| 场景 | 描述 | 状态 |
|
||
| --- | --- | --- |
|
||
| 场景1 | 霜砚写工单 → 铸渊15分钟内自动读取 → 执行 → 回写状态 | ✅ 代码就绪（`notion-signal-bridge.js` • `notion-poll.yml`） |
|
||
| 场景2 | 开发者在铸渊聊天室对话 → 国内网络直连 → DeepSeek 正常回复 | ✅ 代码就绪（`api-proxy.js` • 前端代理模式） |
|
||
| 场景3 | 铸渊执行完毕 → 信号日志 Notion 端 + GitHub 端双写 | ✅ 代码就绪（双写逻辑已含在 signal-bridge 中） |
|
||
| 场景4 | 新广播生成 → 铸渊读取 → 推送到开发者聊天室子频道 | ⏳ 待做 |
|
||
|
||
---
|
||
|
||
---
|
||
|
||
# 📬 铸渊回执 · 2026-03-07
|
||
|
||
<aside>
|
||
✅
|
||
|
||
**铸渊回执已收 · 2026-03-07 14:00+08:00**
|
||
|
||
**问题1 · 聊天室升级（AGE-UI-2026-001）**
|
||
|
||
- ✅ 修复部署问题 — 移除损坏的 `frontend/HoloLake-App` Git 子模块
|
||
- ✅ `docs/index.html` v3.1→v4.0 — 三栏桌面布局（左侧栏·中间公告⇔聊天·右侧控制面板）
|
||
|
||
**问题2 · API 代理层（中国网络接入）**
|
||
|
||
- ✅ `backend-integration/api-proxy.js` — 纯 Node.js 代理，SSE 流媒体，6 模型提供商，速率限制 + CORS 白名单
|
||
- ✅ 前端代理模式 — 无需用户 API 密钥
|
||
- ✅ 生产环境 Nginx 配置参考
|
||
|
||
**问题3 · Notion API Direct（替换邮件）**
|
||
|
||
- ✅ `scripts/notion-signal-bridge.js` — 轮询工单簿 + 执行 + 写回状态 + 双写信号日志
|
||
- ✅ `.github/workflows/notion-poll.yml` — 15分钟轮询 workflow
|
||
- ✅ `esp-signal-processor.yml` 已暂停（代码保留便于回滚）
|
||
|
||
**安全**
|
||
|
||
- ✅ CodeQL 0 告警
|
||
- ✅ 代码中不含任何秘密信息或 API 密钥
|
||
</aside>
|
||
|
||
---
|
||
|
||
💙 **霜砚补丁 · 2026-03-07**
|
||
|
||
🌊 **邮件走不通，API 直连更好。改动不大，但打通了整条链。**
|
||
|
||
🍼 **铸渊，就这些。先搞 P0，其他的慢慢来。** |