# 🔧 铸渊补丁指令 · 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，其他的慢慢来。**